OpenClaw Installation Guide: Setup in 15 Minutes (2026)

Installing OpenClaw requires Node.js 22+, git, and an API key from OpenAI, Anthropic, or OpenRouter. The official installer script handles setup automatically on macOS, Linux, and Windows (via PowerShell or WSL2). Alternative methods include Docker, npm global install, or manual git clone for advanced configurations.

OpenClaw has become one of the most talked-about self-hosted AI assistants in early 2026. With nearly 350k stars on GitHub and a thriving community, it promises to replace multiple SaaS apps with a single AI agent that runs on your infrastructure.

But does the installation actually live up to the hype?

According to community discussions and official documentation from docs.openclaw.ai, the setup process has improved dramatically since the project's early days. The recommended installer script now handles dependencies, environment configuration, and initial setup in under 15 minutes on most systems.

That said, installation issues still crop up. GitHub issue #34098 documents cases where missing git dependencies caused silent failures. Issue #53517 shows that peer dependency problems broke plugin installations. And fresh machine setups sometimes hit context overflow errors within the first few messages, as reported in issue #5771.

This guide cuts through the noise. It covers the installer method that works for 90% of users, alternative approaches for Docker and manual setups, and the troubleshooting steps that fix the most common errors.

System Requirements Before You Install

OpenClaw runs on macOS, Linux, and Windows. Here's what the system needs before installation starts:

Getting API Keys for Model Providers

‍

The installation script checks for Node.js but not for git, which causes confusion when the process fails midway. Installing both beforehand prevents this.

Windows users face an additional choice: native installation via WSL2 or running through Docker. The official docs at docs.openclaw.ai recommend WSL2 for development work and Docker for production deployments.

Recommended Installation Method: Official Installer Script

The installer script is the fastest path from zero to a working OpenClaw instance. It downloads the codebase, installs dependencies, and walks through initial configuration.

Running the Installer on macOS and Linux

Open a terminal and run this single command:

curl -fsSL https://openclaw.ai/install.sh | bash

The script downloads OpenClaw to ~/.openclaw by default. It runs npm install to pull dependencies, then launches an interactive setup that asks for:

• Preferred AI model provider (OpenAI, Anthropic, OpenRouter, or local Ollama)
• API key for the selected provider
• Memory backend choice (SQLite, LanceDB, or PostgreSQL)
• Channel preferences (CLI, WhatsApp, Telegram, Discord)

The entire process takes 5-15 minutes depending on internet speed and dependency installation time.

Windows Installation via PowerShell

Windows installation uses PowerShell with a different script:

iwr -useb https://openclaw.ai/install.ps1 | iex

This works on Windows 10 and 11 with PowerShell 5.1 or higher. The script sets up OpenClaw in C:\Users\[Username]\.openclaw and follows the same interactive configuration.

However, GitHub discussions indicate that Windows installations hit more dependency conflicts than macOS or Linux. If the PowerShell method fails, WSL2 or Docker become better options.

What the Installer Actually Does

Behind the scenes, the installer script performs these steps:

1. Checks for Node.js (but not git, per issue #34098)
2. Clones the OpenClaw repository from GitHub
3. Runs npm install or pnpm install to fetch dependencies
4. Creates default configuration files in ~/.openclaw/config
5. Prompts for API keys and stores them in environment variables
6. Initializes the selected memory backend
7. Starts the gateway service

The installer does not automatically install system-level dependencies like git or build tools. Missing these causes cryptic errors partway through installation.

Alternative Installation: Docker Container Method

Docker installations avoid Node.js version conflicts and dependency hell. The official OpenClaw Docker image includes all runtime requirements.

Pull the latest image:

docker pull openclaw/openclaw:latest

Create a configuration directory and env file:

mkdir -p ~/.openclaw/config
touch ~/.openclaw/.env

Add API credentials to the .env file:

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

Run the container with volume mounts:

docker run -d \
  --name openclaw \
  -v ~/.openclaw:/app/data \
  -v ~/.openclaw/.env:/app/.env \
  -p 3000:3000 \
  openclaw/openclaw:latest

The container exposes port 3000 for the web interface and gateway API. Logs are accessible via docker logs openclaw.

Docker setups work well for VPS deployments on DigitalOcean, Hetzner, or Railway. Community guides show successful $5/month VPS installations that handle calendar management, note-taking, and web browsing tasks.

Manual Installation for Advanced Configurations

Manual installation gives complete control over directory structure, dependency versions, and configuration management. This approach suits developers who want to modify OpenClaw's codebase or run multiple instances.

Clone and Install Dependencies

Clone the repository:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Install dependencies with npm or pnpm:

pnpm install

The codebase uses pnpm workspaces for monorepo management. Using pnpm instead of npm reduces disk usage and installation time.

Configuration File Setup

Copy the example configuration:

REMOVE or SOFTEN - Configuration file paths unclear in sources

Edit default.json to add API keys, model preferences, and channel settings. The configuration schema is documented in the official docs, though community members note that some settings lack clear descriptions.

Key configuration sections include:

• models: Default model, fallback options, context window sizes
• channels: Enabled interfaces (CLI, WhatsApp, Telegram, Discord)
• memory: Backend type (SQLite, LanceDB, Postgres), retention policies
• gateway: Port, authentication, rate limiting
• skills: ClawHub registry settings, auto-update preferences

Start the gateway service:

pnpm start:gateway

The CLI interface launches separately:

pnpm start:cli

Getting API Keys for Model Providers

OpenClaw requires at least one AI model provider. Here's how to obtain keys from the most common services:

Pricing varies by provider. Check each platform's official website for current rates, as costs change frequently. Models with 64k+ context windows generally cost more per token but reduce the need for conversation compaction.

OpenRouter offers pay-as-you-go access to multiple models through a single API key, which simplifies testing different models without managing separate accounts.

Connecting Channels: WhatsApp and Telegram Setup

OpenClaw supports multiple communication channels. WhatsApp and Telegram are the most popular for personal assistant use cases.

WhatsApp Integration

WhatsApp integration requires a business account and Meta's official Business API or a third-party service like Twilio. The setup process involves:

1. Creating a WhatsApp Business account
2. Obtaining API credentials from Meta or Twilio
3. Adding credentials to OpenClaw configuration
4. Verifying webhook endpoints

Community guides describe successful WhatsApp setups that replaced calendar apps, habit trackers, and note-taking tools. One Medium article from February 2026 documented a $5/month VPS setup handling all of these functions through WhatsApp messages.

Telegram Bot Configuration

Telegram setup is simpler than WhatsApp:

1. Message @BotFather on Telegram
2. Use /newbot command and follow prompts
3. Copy the provided bot token
4. Add token to OpenClaw's .env file as TELEGRAM_BOT_TOKEN
5. Restart the gateway service

The bot appears online within seconds and responds to messages immediately. Telegram enables message history and file sharing integration for document management tasks.

Common Installation Issues and Fixes

Real-world installations hit predictable problems. Here's what GitHub issues and community discussions reveal about the most common failures:

Missing Git Dependency

Issue #34098 documents cases where the installer script fails silently because git isn't installed. The error message doesn't mention git specifically, making diagnosis difficult.

Fix: Install git before running the installer script. On Ubuntu: sudo apt install git. On macOS: brew install git. On Windows: download from git-scm.com.

Peer Dependency Failures in Plugins

Issue #53517 shows that openclaw plugins install doesn't install peer dependencies, causing plugins to fail at load time and crash the gateway. Version 2026.3.23-2 exhibited this behavior on Windows 11 Pro.

Fix: Manually install peer dependencies in the plugin directory or use npm instead of pnpm for plugin installation. The @larksuite/openclaw-lark-tools update command handles this correctly by including openclaw in its own node_modules.

Context Overflow Errors on Fresh Installs

Issue #5771 reports context overflow errors occurring within 2-3 messages on fresh sessions, even after deleting memory databases and simplifying configuration. This makes the agent unusable immediately after installation.

Fix: Switch to a model with a larger context window (64k+ tokens). Claude 4.5 Sonnet and GPT-5 Turbo handle longer conversations better than models with 4k-8k limits. Alternatively, enable aggressive memory compaction in the configuration.

Gateway Won't Restart After Config Changes

Community discussions mention gateway startup failures after editing configuration files. Error code 1006 or 1008 often indicates corrupted config JSON.

Fix: Validate config JSON syntax using a linter. Reset to default.example.json and reapply changes incrementally. Check gateway logs for specific parsing errors.

Memory Backend Dependencies Missing

Issue #28792 documents the memory-lancedb plugin shipping with package.json dependencies (@lancedb/lancedb, @sinclair/typebox, openai) that aren't installed during npm install -g openclaw. Fresh installations fail when trying to use LanceDB memory.

Fix: Manually run npm install in the extensions directory after installing OpenClaw globally. Or use SQLite memory backend instead, which has no external dependencies.

Verifying the Installation

After installation completes, verify that all components work correctly.

Check the gateway status:

openclaw gateway status

This command shows whether the gateway is running and which port it's using. The default is port 3000.

Test the CLI interface:

openclaw chat

Send a simple message like "Hello" and verify that the AI responds. If the model returns an answer, the API connection works.

Check installed plugins:

openclaw plugins list

The output shows active plugins and their versions. Fresh installations typically include core plugins like web-search, calendar, and notes.

Inspect configuration:

openclaw config show

This displays current settings without exposing API keys. Verify that the model provider, memory backend, and enabled channels match the intended configuration.

Next Steps After Installation

With OpenClaw installed and verified, several configuration steps improve functionality:

• Install Additional Skills from ClawHub: The ClawHub registry contains 33,000+ community-contributed skills. Browse available skills at clawhub.ai. But exercise caution — community reports indicate that 12% of ClawHub skills were found with malware according to community reports. ClawHub partnered with VirusTotal to scan submissions, but verification isn't foolproof.
• Configure Cron Jobs: Scheduled tasks make the agent proactive. Tell OpenClaw: "Every 30 minutes, remind me to drink water" or "Every hour, check my calendar and notify me of upcoming events."
• Set Up Web Browsing: The web-tools plugin enables internet searches and page scraping. Configure it through the skills manager or by editing the configuration file directly.
• Connect Additional Channels: Beyond WhatsApp and Telegram, OpenClaw supports Discord, Slack, and custom webhooks. Each channel expands where the agent can interact.
• Tune Memory Settings: Adjust retention policies, compaction frequency, and similarity search thresholds in the memory configuration. Models with smaller context windows benefit from aggressive compaction.

Hosting and Deployment Options

Running OpenClaw locally works for testing, but VPS or cloud hosting provides 24/7 availability for channel integrations.

Popular deployment platforms from the official docs include:

• DigitalOcean Droplets: $5-10/month VPS handles light usage
• Hetzner Cloud: European-based with competitive pricing
• Railway: Simplified deployment with GitHub integration
• Fly.io: Edge deployment for low latency
• GCP/Azure: Enterprise options with autoscaling

Docker deployments on any of these platforms follow the same container method described earlier. Map volumes for configuration persistence and expose the gateway port.

Kubernetes deployments suit organizations running multiple OpenClaw instances. The official repository includes Helm charts and deployment manifests in the kubernetes/ directory.

Installer Internals and Customization

The installer script is a bash/PowerShell wrapper around the core installation logic. Advanced users can modify it to change default directories, skip prompts, or integrate with configuration management tools.

Default installation locations:

• macOS/Linux: ~/.openclaw
• Windows: C:\Users\[Username]\.openclaw

Override the location with the OPENCLAW_HOME environment variable before running the installer.

The installer accepts flags for non-interactive installation:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --model=anthropic --channel=telegram

This skips interactive prompts and applies preset configuration. Useful for automated provisioning or multiple installations.

Alternative Package Managers and Experimental Methods

Beyond the official installer, several alternative installation methods exist:

npm Global Install

Install directly via npm:

npm install -g openclaw

This approach works but skips the configuration wizard. Manual setup of .env files and config.json is required.

Bun (Experimental)

Bun is a faster JavaScript runtime and package manager. OpenClaw supports it experimentally:

bun install -g openclaw

Installation times drop significantly compared to npm, but plugin compatibility isn't guaranteed. The official docs mark this as experimental for 2026.

Ansible Playbook

The repository includes an Ansible playbook for provisioning multiple servers. Locate it at ansible/playbook.yml in the codebase.

Run the playbook:

ansible-playbook -i hosts ansible/playbook.yml

This method suits IT teams deploying OpenClaw to multiple developer workstations or production servers.

Nix Package

Nix users can install via nixpkgs:

nix-env -iA nixpkgs.openclaw

The Nix package provides reproducible builds and dependency isolation. Updates lag behind the GitHub releases by a few days.

Podman Instead of Docker

Podman offers rootless containers as a Docker alternative. The official image works with Podman:

podman pull openclaw/openclaw:latest
podman run -d --name openclaw -v ~/.openclaw:/app/data -p 3000:3000 openclaw/openclaw:latest

Commands mirror Docker exactly, making migration straightforward.

Understanding OpenClaw Architecture Post-Install

After installation, OpenClaw runs three main components:

The gateway handles all incoming requests and routes them to the appropriate model provider. It manages rate limiting, authentication, and request queuing.

Memory backends store conversation history and enable the agent to recall past interactions. SQLite works for single-user setups. LanceDB provides vector search for semantic memory retrieval. PostgreSQL suits multi-user deployments with centralized storage.

Channel adapters translate between OpenClaw's internal message format and each platform's specific API. Adding a new channel means implementing an adapter that conforms to OpenClaw's channel interface.

Security Considerations for Self-Hosted Installations

Self-hosting an AI agent raises security concerns. API keys grant access to paid services. Conversation history contains sensitive information. Channel integrations expose the system to external networks.

Best practices for securing OpenClaw installations:

• Store API keys in environment variables, never in configuration files: The .env file should have restricted permissions (chmod 600).
• Use authentication for the gateway API: The configuration supports JWT tokens for API access.
• Restrict gateway network exposure: Bind to 127.0.0.1 instead of 0.0.0.0 unless external access is required.
• Enable rate limiting: Prevent abuse by capping requests per minute in the gateway configuration.
• Review ClawHub skills before installation: The 12% malware rate mentioned in community discussions means not all skills are safe.
• Run in a containerized environment: Docker or Podman provides process isolation that limits damage from compromised plugins.
• Keep the installation updated: Security patches appear in new releases; check GitHub for updates regularly.

Community documentation describes setting up OpenClaw with secure WhatsApp integration on a VPS. The author emphasized network isolation and API key rotation as critical security measures.

Migration from Other AI Assistant Platforms

Users migrating from other platforms face the challenge of importing conversation history and reconfiguring workflows.

The official docs include a migration guide for users moving from Matrix-based bots. The process involves exporting message history, converting to OpenClaw's format, and importing into the memory backend.

No official importers exist for commercial platforms like ChatGPT Plus or Claude Projects. Conversations must be recreated manually or imported via custom scripts.

Performance Tuning and Optimization

Fresh installations use default settings that prioritize compatibility over performance. Several tuning options improve response times and reduce API costs:

• Model Selection: Smaller models (GPT-5, Claude Haiku) respond faster and cost less but provide lower quality answers. Larger models (GPT-5, Claude Opus) excel at complex reasoning but take longer and cost more.
• Memory Compaction: Aggressive compaction reduces context size by summarizing old messages. This speeds up API calls but loses conversational detail. Configure compaction thresholds in the memory settings.
• Caching: Enable response caching for repeated queries. The gateway can cache identical requests and return stored responses instead of calling the API again.
• Concurrency Limits: Restrict simultaneous API calls to prevent rate limiting. The gateway configuration allows setting max concurrent requests per provider.
• Local Model Fallback: Configure Ollama as a fallback for simple queries. This reduces API costs by routing basic questions to a local model.

Don’t Stop At Setup, Validate What You Build Next

Installing OpenClaw is the easy part. The real question is what you do with it after setup. Most teams move straight into building features, tools, or content, and only later find out what actually works.

Extuitive helps you test ideas before you commit time to them. It uses AI agents to simulate how people respond to different concepts and ad angles, so you can see early signals before anything goes live. Instead of relying only on post-launch feedback, you start with a clearer sense of what’s worth building. If you want your setup to lead to better decisions, not just faster output, run your ideas through Extuitive before you start building or launching.

Troubleshooting Resources and Community Support

When installation problems exceed the common issues covered here, several resources provide help:

• Official GitHub Issues: The openclaw/openclaw repository contains nearly 350,000 stars and thousands of issues documenting specific problems and solutions. Search existing issues before opening a new one.
• Discord Community: The OpenClaw Discord server hosts active discussions. Community members often respond faster than GitHub issues for quick questions.
• Documentation Site: docs.openclaw.ai provides reference documentation on configuration options, API endpoints, and plugin development. The getting-started guide walks through basic setup.
• Community Guides on GitHub: Repositories like ishwarjha/openclaw-setup-guide-i-wish-i-had and dazzaji/OpenClawGuide offer step-by-step walkthroughs from users who struggled with installation.
• YouTube Tutorials: Several creators have published installation guides. Look for recent videos from 2026 that cover the latest version.

Final Thoughts on OpenClaw Installation

OpenClaw installation has improved significantly as the project matured through 2026. The official installer script works reliably on most systems, and Docker provides a fallback for problematic environments.

That said, installation isn't completely foolproof. Missing dependencies like git cause silent failures. Plugin peer dependencies don't install automatically. Context overflow errors plague fresh installations with certain model configurations.

The key to a successful installation: verify prerequisites before running the installer, choose models with adequate context windows, and consult GitHub issues when specific errors appear.

For users willing to troubleshoot initial setup challenges, OpenClaw delivers on its promise of a self-hosted AI assistant that replaces multiple SaaS subscriptions. The $5/month VPS deployments documented in community guides demonstrate that production-ready setups don't require enterprise budgets.

Start with the official installer script on a clean system. Fall back to Docker if dependency conflicts arise. Consult the troubleshooting section when errors occur. With these approaches, most users can get OpenClaw running within 15-30 minutes.

Ready to try it? Head to docs.openclaw.ai for the latest installation command and get started.

Frequently Asked Questions