How to Install OpenClaw in 2026: Docker, npm, and Script Setup Guide

If you want to install OpenClaw in 2026, the easiest rule is: use the one-click script for a fast trial, use npm for the most flexible daily setup, and use Docker when you care most about isolation and server deployment. On Windows, native Windows and WSL2 are both supported by the official install docs—WSL2 is often the smoother path if you want a Linux-like environment for copy-pasting tutorials.

This guide walks through each installation path, the system requirements that matter, and the fixes for the setup problems most people hit first: Node.js version mismatches, npm permissions, missing API keys, and Docker restarts.

It was 2 AM, and I was staring at the 17th error message on my screen.

“Cannot find module ‘@anthropic-ai/sdk’” — I’d been looking at this red text for three days. As someone who’s tinkered with countless open-source projects, I thought I’d seen every installation failure scenario out there.

This guide won’t make empty promises or regurgitate the same official documentation you’ve read ten times already. I’m going to tell you exactly which pitfalls I fell into, which approaches I tried, and what finally worked. Whether you’re a Windows user, Mac enthusiast, or a seasoned sysadmin looking to deploy on a server, you’ll find a solution that fits. The official install docs cover native Windows and WSL2; if you mostly want to reuse the Linux-style commands in this article, WSL2 is often the smoother path.

Pre-Installation: Don’t Rush Into It

Many people see “one-click installation script” and immediately copy-paste with excitement — hold on, wait a second.

OpenClaw has strict system requirements, and skipping these checks leads to endless headaches. Based on official docs and community feedback, here’s what you need to verify:

Node.js version (match the official install docs)

Per docs.openclaw.ai/install: recommended Node.js v24, minimum Node.js v22.14+ (the one-click script will also warn if you’re below baseline). I tried Node 20 and hit dependency pain; moving to 24.x cleared it up.

node --version

If you’re below v22.14, upgrade to at least v22.14 or, preferably, install v24.x (recommended on Windows too).

Operating System Compatibility

• macOS: 12.0 (Monterey) and above, both Intel and Apple Silicon supported
• Windows: Native Windows and WSL2 are both supported; for a Linux-like workflow and tutorial parity, WSL2 is often the smoother choice
• Linux: Tested on Ubuntu 20.04+, Debian 11+, CentOS 8+

API Key Preparation

OpenClaw itself is just a “gateway” — you need to connect actual AI services to use it. Currently supports Claude (Anthropic), OpenAI, Google Gemini, etc. I recommend at least getting a Claude API Key for the best experience.

Special Notes for Users in China

The official npm registry is painfully slow in China — switch to a mirror beforehand:

npm config set registry https://registry.npmmirror.com

Also, API calls require international network access — both Anthropic and OpenAI APIs need outbound connectivity. If you don’t have stable international routing, consider compliant proxy services.

Method 1: One-Click Script Installation (Fastest, 5 Minutes)

If you meet these conditions, just go with this method:

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

• Running macOS, Linux, or WSL2
• Just want a quick taste, don’t want to tinker
• Comfortable with system modifications

Installation Command

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

This script automatically:

1. Checks Node.js version (prompts to upgrade if insufficient)
2. Installs the openclaw npm package globally
3. Creates necessary config directories (~/.openclaw/)
4. Sets up system services (optional)

Post-Installation Setup

openclaw onboard --install-daemon

This step asks for your API Key and configures default messaging channels. Just follow the prompts — nothing special to watch out for.

Verify Installation

openclaw --version

Seeing the version number means success. If everything goes smoothly, it really does take just 5 minutes.

But I’ll be honest — this “one-click” script failed twice on my Ubuntu server, both times due to permission issues. If you hit similar problems, don’t panic; check out the manual npm installation below.

Method 2: npm Global Installation (Most Flexible, Recommended for Advanced Users)

This is my go-to method and my top recommendation. It takes a few more steps, but troubleshooting is easier and it’s less invasive to your system.

Step 1: Verify Node.js Environment

# Check version
node --version

# If version insufficient, use nvm to manage
# macOS/Linux install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Then install Node 24
nvm install 24
nvm use 24

Step 2: Install OpenClaw

npm install -g openclaw@latest

The @latest ensures you get the newest version. OpenClaw updates frequently — as of February 2026, it’s at v2026.2.24.

If you encounter EACCES permission errors during installation (common on macOS), your npm global directory permissions aren’t set up correctly. Here’s the fix:

# Create dedicated directory
mkdir ~/.npm-global

# Configure npm to use new directory
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install -g openclaw@latest

Step 3: Initialize Configuration

openclaw onboard --install-daemon

This interactively guides you through:

1. Selecting AI providers (Claude, OpenAI, Gemini, etc.)
2. Entering corresponding API Keys
3. Configuring messaging channels (Telegram Bot, Discord, etc.)
4. Setting up system services (optional but recommended)

Step 4: Start and verify the Gateway

If you already ran openclaw onboard --install-daemon, the local Gateway service is usually registered. Check it first:

openclaw gateway status

For foreground debugging (terminal stays open, easier to read logs):

openclaw gateway

To start or stop the installed system service explicitly:

openclaw gateway start
openclaw gateway stop

Method 3: Docker Installation (Most Secure, Recommended for Server Deployment)

If you’re running OpenClaw on a VPS, NAS, or any environment requiring long-term stability, Docker is the smartest choice. Container isolation effectively prevents AI agent mishaps from affecting your host system — and yes, someone’s OpenClaw instance actually did delete files by mistake.

Step 1: Verify Docker Environment

docker --version
docker-compose --version

No strict version requirements, but Docker 20.10+ recommended.

Step 2: Create Configuration Directories

mkdir -p ~/openclaw-data/config
mkdir -p ~/openclaw-data/data

Step 3: Prepare Docker Compose File

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ~/openclaw-data/config:/app/config
      - ~/openclaw-data/data:/app/data
    environment:
      - NODE_ENV=production
      - ANTHROPIC_API_KEY=${{ANTHROPIC_API_KEY}}
      - OPENAI_API_KEY=${{OPENAI_API_KEY}}

Step 4: Configure Environment Variables

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

# Create .env file
cat > ~/openclaw-data/.env << EOF
ANTHROPIC_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
EOF

Step 5: Start the Container

cd ~/openclaw-data
docker-compose up -d

Step 6: Check Logs to Confirm Status

docker logs -f openclaw

Seeing “OpenClaw Gateway started on port 3000” means success.

By the way, a bonus of the Docker approach: you can deploy on Mac Mini, Raspberry Pi, or any Docker-capable device, then access it from your phone via Telegram or WhatsApp. This is actually how many people primarily use OpenClaw.

Windows: WSL2 setup (optional but common)

If you choose WSL2, most Linux-style commands in this article apply one-to-one. Native Windows installs are supported, but teams often standardize on WSL2 for stability and fewer PATH surprises. Common pitfalls:

Pitfall 1: Wrong WSL Version

# Check WSL version
wsl --list --verbose

If it shows Version 1, you need to upgrade:

# Run in PowerShell (Administrator)
wsl --set-version Ubuntu 2

Pitfall 2: Insufficient WSL2 Memory

OpenClaw consumes some memory when running, and WSL2’s default configuration might not be enough. I recommend creating .wslconfig in your Windows user directory:

[wsl2]
memory=4GB
processors=2

Then restart WSL:

wsl --shutdown

Pitfall 3: Windows Firewall Blocking

If you want to access the OpenClaw web interface running in WSL2 from your Windows browser, you may need to allow the corresponding port through Windows Firewall.

How to Run OpenClaw on Mac Mini

Running OpenClaw on a Mac Mini is a pretty solid choice — low power consumption, silent operation, and sufficient performance. My M1 Mac Mini has been running stably for three months.

M-Series Chip Considerations

Docker images need to support ARM64 architecture. The latest OpenClaw official images natively support Apple Silicon — no Rosetta translation needed.

# Specify platform in docker-compose.yml (usually not needed, but try if pull fails)
services:
  openclaw:
    platform: linux/arm64
    image: openclaw/openclaw:latest

Running as Background Service

macOS recommends using launchd for service management. The --install-daemon flag during installation automatically creates the plist file, but if you installed manually, you might need to configure it yourself:

# Check service status
launchctl list | grep openclaw

# Manual load
launchctl load ~/Library/LaunchAgents/ai.openclaw.daemon.plist

OpenClaw Common Error Troubleshooting

Even following the steps, you might encounter various issues. Here are the most frequent errors and solutions:

Error 1: “Cannot find module” Series

Cause: Incomplete npm installation or version incompatibility

Solution:

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

Error 2: “EACCES: permission denied”

Cause: npm global directory permission issues

Solution: Refer to the permission fix steps in the npm installation section above

Error 3: API Calls Return 401/403

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

Cause: Invalid API Key or quota exhausted

Troubleshoot:

# Check configuration
openclaw config get

# Reset
openclaw config set anthropic.apiKey=your_new_key

Error 4: Docker Container Keeps Restarting

Cause: Environment variable configuration error or port conflict

Troubleshoot:

# View detailed logs
docker logs openclaw

# Check port usage
lsof -i :3000

Error 5: Messaging Channel Not Receiving Replies

Cause: Webhook configuration error or network issues

Troubleshoot:

• Telegram: Verify Bot Token is correct, Webhook URL is accessible
• Discord: Verify Bot permissions are set correctly, Intents enabled
• Domestic servers: Check if Telegram/Discord servers are accessible

Post-Installation Configuration Tips

Once OpenClaw is installed, these configurations can enhance your experience:

1. Configure Multiple AI Providers

I recommend configuring both Claude and GPT-4 so you can auto-switch when one service is unstable.

2. Set Up System-Wide Shortcuts

macOS can use Alfred + Workflow, Windows can use PowerToys Run for global quick access.

3. Regular Configuration Backups

# Config files are all in ~/.openclaw/
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)

4. Monitor Running Status

Docker deployments should add health checks:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Summary

Having said all that, if you’re still debating which installation method to choose, my recommendations:

• Want the fastest experience → One-click script
• Daily primary use → npm global installation
• Long-term server deployment → Docker

Actually, OpenClaw installation isn’t as difficult as it seems — many “pitfalls” are just due to unfriendly documentation and unclear error messages. Hopefully this guide helps you avoid some detours.

A final thought: deploying OpenClaw itself is about more than just installing software — it represents an attitude toward AI usage: data privacy, self-control, not being locked into any single platform. As AI capabilities grow stronger, this “sovereignty consciousness” might be more important than you think.

Alright, go give it a try. If you run into issues not covered in this guide, feel free to share in the comments — I’ve probably fallen into more pits than you’d imagine.

9 min read · Published on: Feb 26, 2026 · Modified on: Apr 20, 2026

Easton

AI & Intelligence