How to Install OpenClaw: The Complete Setup Guide (npm, Docker, Source)

Three Ways to Install OpenClaw

OpenClaw gives you three installation paths: npm (recommended for most developers), Docker (recommended for production deployments), and building from source (for contributors and advanced customization). This guide covers all three, in order of complexity.

Before you pick a path, run through the prerequisites. A bad install is almost always a prerequisites problem.

Prerequisites

Every install method requires these:

Node.js 24 OpenClaw is built against Node.js 24. Node 22.16+ works but may show deprecation warnings on certain CLI operations. Check your version:

node --version

If you don't have Node 24, use nvm:

nvm install 24
nvm use 24
nvm alias default 24

The last command sets 24 as your default so new terminal sessions don't revert.

An AI provider API key OpenClaw routes requests to an AI backend. You need at least one key from:

Anthropic (Claude) — recommended for reasoning-heavy agent tasks
OpenAI (GPT-4o)
Google (Gemini)

Get a key before you start the install. The onboarding wizard asks for it on step 3 and there's no clean way to add it mid-flow.

Git (source install only) If you're building from source, confirm git is installed: git --version.

Method 1: npm Install (Fastest Path)

This is the standard install for developers running OpenClaw locally.

npm install -g @openclaw/cli

The -g flag installs the CLI globally. You'll use the openclaw command throughout setup. Once the install completes:

openclaw --version

If this returns a version number, the install succeeded. If it returns a "command not found" error, your npm global bin directory is not in your PATH. Fix:

npm config get prefix

Add {prefix}/bin to your PATH in ~/.zshrc or ~/.bashrc, then restart your terminal.

Run the onboarding wizard:

openclaw init

The wizard walks you through:

Creating your Gateway configuration
Entering your AI provider API key
Setting up authentication tokens
Configuring your first channel (email, Slack, calendar, etc.)

The wizard is well-designed. Don't skip steps. The auth configuration on step 3 is where misconfigured installs originate — take 60 extra seconds to confirm the key is correct before continuing.

Start the Gateway:

openclaw start

Your Gateway starts on localhost:3000 by default. Open a chat session to test:

openclaw chat

If you get a response to a plain text prompt, the install is working. Total time for a clean npm install with one channel: 20–30 minutes.

Method 2: Docker Install (Production-Ready)

Docker is the right path if you're deploying OpenClaw on a VPS or server, want process isolation, or plan to run multiple instances. See the full Docker Compose guide for persistent storage and Telegram/Discord setup →

Pull the official image:

docker pull openclaw/gateway:latest

Run the container:

docker run -d \
  --name openclaw \
  -p 3000:3000 \
  -e AI_PROVIDER=anthropic \
  -e AI_API_KEY=your_anthropic_key_here \
  -e OPENCLAW_AUTH_TOKEN=your_secure_token \
  openclaw/gateway:latest

Replace the environment variables with your values. The OPENCLAW_AUTH_TOKEN is the bearer token used to authenticate requests to your Gateway — generate a random string (32+ characters) and store it somewhere safe.

Confirm the container is running:

docker ps
docker logs openclaw

The logs should show Gateway started on port 3000. If you see an error about API key validation, the key format is wrong — check for trailing whitespace or line breaks in your environment variable.

Test the Gateway:

curl -H "Authorization: Bearer your_secure_token" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Hello"}' \
     http://localhost:3000/v1/chat

A valid JSON response means the Gateway is running correctly.

Method 3: Build From Source

Building from source is for contributors, or for teams that need to patch OpenClaw before an official release. It is not the right path if you just want a working install.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link

The npm link command makes the openclaw CLI available globally from your local build. After linking, run openclaw --version to confirm. The output should include a dev build identifier.

Running from source means you're responsible for pulling updates manually (git pull && npm run build) and handling any breaking changes in main. Most teams on source builds pin to a specific commit hash rather than tracking main directly.

Common Installation Errors

"Cannot find module '@openclaw/core'" The package didn't install cleanly. Run npm install -g @openclaw/cli --force to reinstall. If the error persists, clear your npm cache: npm cache clean --force.

"Gateway failed to start: EADDRINUSE" Port 3000 is already in use. Either stop the process using that port or start OpenClaw on a different port: openclaw start --port 3001.

"Invalid API key" during onboarding Your key is either wrong or not active. Verify directly against your AI provider's API dashboard. A common issue: copying keys from a web interface that includes invisible characters — paste into a plain text editor first, then copy again.

"node: command not found" after nvm install You're in a shell session that loaded before nvm. Close the terminal, open a new one, and run node --version again.

Docker: "permission denied while trying to connect to Docker daemon" Add your user to the docker group: sudo usermod -aG docker $USER, then log out and back in.

Docker: container starts but Gateway is unreachable Check if port 3000 is exposed on your host firewall. For VPS deployments: ufw allow 3000 (or your firewall equivalent). Never expose port 3000 publicly without putting a reverse proxy and TLS in front of it.

After Install: What to Configure First

A working Gateway is not a working agent setup. These configuration steps determine whether OpenClaw is actually useful:

1. Set API key permissions to read-only where possible. OpenClaw agents with write access to email or GitHub represent a significant attack surface. Grant write access to specific tools only after you understand exactly what each agent will do with it.

2. Connect one channel before connecting all of them. The most common early-stage failure is connecting six channels at once, having one auth token expire, and not knowing which one broke. Start with email or calendar. Confirm it works. Add the next one.

3. Create your first agent with a narrow scope. Define one role, two or three tools, and explicit behavior rules. A research-only agent that cannot send email is a good first agent. Expand scope after the base configuration is stable.

4. Test in a session before going live. Run the agent against test inputs. Confirm it's using the right tools. Confirm it's not doing anything you didn't expect. What a well-configured OpenClaw agent does on day one →

The Self-Hosting Decision

Before you put more hours into this setup, run one honest check.

OpenClaw installation is fast. What's slow is the ongoing overhead: Gateway updates, dependency patches, API deprecation notices, debugging broken channel integrations. That work doesn't show up in the install guide.

For a developer who finds infrastructure configuration interesting, that tradeoff is fine. For a CEO or operator whose goal is to get 2 hours back per day without becoming an ops person, it's often the wrong trade.

	Self-Hosted OpenClaw	Managed (MrDelegate)
Install time	20–35 min	8 min
Ongoing maintenance	Monthly, by you	None
Security burden	On you	Handled
Channel setup	Manual + auth flows	Guided onboarding
When it breaks	Your problem	Not your problem
Cost	VPS + your time	$47/month

Neither option is wrong. They serve different operators. If you want to run your own infrastructure, this guide has everything you need to get started. If you want the outcome without the infrastructure, the faster path is starting a managed setup →.

Ready to skip the install entirely? Start your free trial →