How to Install OpenClaw: Complete Step-by-Step Guide (2026)

OpenClaw is a powerful, self-hosted AI assistant that connects to your favorite messaging platforms like WhatsApp, Telegram, Discord, iMessage, and more. Unlike cloud-based AI assistants, OpenClaw runs entirely on your own hardware, giving you complete control over your data and privacy.

In this comprehensive guide, we’ll walk you through the complete OpenClaw installation process on Windows, macOS, and Linux. Whether you’re a developer looking for a local AI agent or a privacy-conscious user wanting a personal assistant, this tutorial will help you get OpenClaw up and running in no time.

OpenClaw is a local-first, self-hosted AI gateway that bridges your messaging applications with AI coding agents. Think of it as your personal AI infrastructure that lives on your machine rather than in the cloud.

Before installing OpenClaw, ensure your system meets these requirements:

Checking Your Node.js Version

Open your terminal or command prompt and run:

node --version

If you see a version lower than 22 or get a “command not found” error, you’ll need to download Node.js from the official website or use a version manager like nvm.

Openclaw Installation Methods

OpenClaw offers several installation methods. The recommended approach uses the onboarding wizard, but you can also install directly via npm/pnpm/bun or build from source.

The fastest way to get started is by installing OpenClaw globally via your preferred package manager:

npm install -g openclaw@latest

pnpm add -g openclaw@latest

bun add -g openclaw@latest

After installation, the onboarding wizard guides you through the entire setup process. This is the recommended method as it handles

openclaw onboard --install-daemon

The wizard supports:

For developers who want to contribute to OpenClaw or modify the source code:

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
pnpm install

# Build the UI
pnpm ui:build

# Build the project
pnpm build

# Run the onboarding wizard
pnpm openclaw onboard --install-daemon

# Development mode with auto-reload
pnpm gateway:watch

Note: For development, pnpm openclaw runs TypeScript directly via tsx, while pnpm build produces compiled JavaScript in the dist/ directory for production use.

If you haven’t already installed Node.js 22 or higher:

Choose your preferred method:

# Using pnpm (recommended)
pnpm add -g openclaw@latest

The wizard is the easiest way to set up OpenClaw:

openclaw onboard --install-daemon

The wizard will guide you through:

OpenClaw works with various AI models. The recommended setup uses Anthropic’s Claude models:

1. Get your API key from Anthropic Console
2. During onboarding, enter your API key
3. Recommended model: Claude Opus 4.6 for best long-context performance

1. Get your API key from OpenAI Platform
2. Configure in the wizard or manually in ~/.openclaw/openclaw.json

Minimal Configuration File

Your ~/.openclaw/openclaw.json should look something like:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    },
    "discord": {
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

After configuration, start the OpenClaw gateway:

openclaw gateway --port 18789 --verbose

The gateway will:

• Start running on ws://127.0.0.1:18789
• Launch the Control UI dashboard
• Connect to your configured channels

Access the dashboard at: http://127.0.0.1:18789/

Test your installation with these commands:

# Check system health
openclaw doctor

# Send a test message
openclaw message send --to +1234567890 --message "Hello from OpenClaw!"

# Talk to the agent
openclaw agent --message "What can you do?" --thinking high

One of OpenClaw’s most powerful features is its ability to connect to multiple messaging platforms. Here’s how to set up the most popular channels:

# Login and link your WhatsApp device
pnpm openclaw channels login

This stores credentials in ~/.openclaw/credentials. Configure allowlist in your config:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15551234567", "+15559876543"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

1. Create a bot via @BotFather
2. Copy your bot token
3. Configure in OpenClaw:

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF123456"
    }
  }
}

1. Create an application at Discord Developer Portal
2. Add a bot and copy the token
3. Configure in OpenClaw:

{
  "channels": {
    "discord": {
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

macOS offers the smoothest OpenClaw experience with additional features:

# Install via pnpm
pnpm add -g openclaw@latest

# Run onboarding with macOS-specific setup
pnpm openclaw onboard --install-daemon

Permissions: macOS may prompt for:

OpenClaw works best on Windows through WSL2 (Windows Subsystem for Linux):

# Enable WSL2 feature
wsl --install

# Restart your computer
# Install Ubuntu from Microsoft Store

# Inside WSL2 terminal
pnpm add -g openclaw@latest
pnpm openclaw onboard --install-daemon

Why WSL2? WSL2 provides:

OpenClaw runs natively on Linux, making it ideal for headless servers or Raspberry Pi:

# Install pnpm
npm install -g pnpm

# Install OpenClaw
pnpm add -g openclaw@latest

# Run onboarding
pnpm openclaw onboard --install-daemon

The onboarding wizard automatically sets up a systemd user service for you.

# Create systemd service file
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/openclaw.service << EOF
[Unit]
Description=OpenClaw Gateway

[Service]
Type=simple
ExecStart=/usr/bin/pnpm openclaw gateway --port 18789
Restart=always

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user enable openclaw
systemctl --user start openclaw

OpenClaw’s configuration lives at ~/.openclaw/openclaw.json. Here’s a comprehensive example:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verbose": true
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_TOKEN",
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_TOKEN",
      "dm": { "policy": "pairing" }
    }
  },
  "browser": {
    "enabled": true,
    "color": "#FF4500"
  },
  "security": {
    "sandbox": {
      "mode": "non-main"
    }
  }
}

OpenClaw supports multiple AI models:

Setting model fallback:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "modelFallback": [
    "openai/gpt-4o",
    "openai/gpt-4o-mini"
  ]
}

OpenClaw takes security seriously. By default:

For stricter security:

{
  "channels": {
    "telegram": {
      "allowFrom": ["+1234567890"],
      "groups": {
        "YOUR_GROUP_ID": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

Error message:

Error: Node.js 22+ required. Found: v18.x.x

Solution:

1. Install Node.js 22+ from nodejs.org
2. Or use nvm (Node Version Manager):

# Install nvm (Linux/macOS/WSL2)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 22
nvm install 22
nvm use 22

# Verify
node --version

Error message:

Error: Port 18789 already in use

Solution:

# Find and kill the process using port 18789
# Linux/macOS:
lsof -i :18789
kill -9 <PID>

# Windows (WSL2):
netstat -ano | findstr :18789
taskkill /PID <PID> /F

Symptom: Messages aren’t being sent or received

Solutions:

1. Run the diagnostic tool:openclaw doctor
2. Check your credentials:# For WhatsApp cat ~/.openclaw/credentials/whatsapp.json # For Telegram echo $TELEGRAM_BOT_TOKEN
3. Verify network connectivity:# Test API connectivity curl -I https://api.anthropic.com

Symptom: Screen recording or microphone not working

Solution:

1. Open System Settings → Privacy & Security
2. Enable permissions for:
   • Microphone
   • Screen Recording
   • Notifications
3. Restart the OpenClaw app

Error message:

Error: Docker not found or not running

Solution:

1. Install Docker from docker.com
2. Start Docker daemon:# Linux/macOS sudo systemctl start docker # or dockerd &
3. Add user to docker group:sudo usermod -aG docker $USER

Run OpenClaw on a Linux server and access it remotely:

{
  "gateway": {
    "bind": "loopback",
    "tailscale": {
      "mode": "serve"
    }
  }
}

With Tailscale Serve enabled, you can access your gateway from any device on your Tailscale network.

For public access (requires password authentication):

{
  "gateway": {
    "auth": {
      "mode": "password"
    },
    "tailscale": {
      "mode": "funnel"
    }
  }
}

Route different channels to different agent workspaces:

{
  "agents": {
    "workspaces": {
      "personal": "~/.openclaw/workspace/personal",
      "work": "~/.openclaw/workspace/work"
    },
    "routes": [
      {
        "channel": "telegram",
        "from": "+1234567890",
        "agent": "personal"
      },
      {
        "channel": "discord",
        "guild": "123456789",
        "agent": "work"
      }
    ]
  }
}

Enable browser automation:

{
  "browser": {
    "enabled": true,
    "color": "#FF4500",
    "profiles": {
      "chrome": {
        "path": "/usr/bin/google-chrome"
      }
    }
  }
}

Enable hands-free activation:

openclaw nodes voicewake --enable

Configure wake words and sensitivity:

{
  "nodes": {
    "voicewake": {
      "enabled": true,
      "wakeWords": ["hey openclaw", "hey claw"],
      "sensitivity": 0.7
    }
  }
}

Enable continuous conversation:

openclaw nodes talk --enable

For high-quality text-to-speech:

1. Get an ElevenLabs API key from elevenlabs.io
2. Configure in OpenClaw:

{
  "audio": {
    "elevenlabs": {
      "apiKey": "YOUR_API_KEY",
      "voiceId": "21m00Tcm4TlvDq8ikWAM"
    }
  }
}

Keep your installation up to date:

# npm
npm update -g openclaw@latest

# pnpm
pnpm update -g openclaw@latest

# bun
bun update -g openclaw@latest

# Stable (recommended for production)
openclaw update --channel stable

# Beta (testing)
openclaw update --channel beta

# Development (latest features, may be unstable)
openclaw update --channel dev

Run the health check:

openclaw doctor

This will:

Security Best Practices

1. Protect Your API Keys

Never commit your openclaw.json to version control:

# Add to .gitignore
echo "**/openclaw.json" >> ~/.gitignore_global
git config --global core.excludesFile ~/.gitignore_global

2. Configure DM Pairing

Unknown senders should require pairing:

{
  "channels": {
    "discord": {
      "dm": { "policy": "pairing" }
    },
    "slack": {
      "dm": { "policy": "pairing" }
    }
  }
}

3. Use Allowlists

Restrict who can access your assistant:

{
  "channels": {
    "telegram": {
      "allowFrom": ["123456789", "987654321"]
    },
    "whatsapp": {
      "allowFrom": ["+1234567890"]
    }
  }
}

4. Enable Sandboxing for Groups

Run group conversations in isolated Docker containers:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

Getting Started with Your AI Assistant

Now that OpenClaw is installed, here’s what you can do:

Basic Commands

Example Conversations

Coding assistance:

You: Write a Python script to download files from a URL

OpenClaw: Here's a Python script using the requests library...

Research:

You: What's the latest news about AI agents?

OpenClaw: Let me search for recent developments in AI agents...

Automation:

You: Set a reminder to call mom at 5 PM

OpenClaw: Done! I've scheduled a reminder for 5:00 PM today.

Useful Resources

Frequently Asked Questions

Conclusion

OpenClaw represents the future of personal AI assistants—powerful, private, and completely under your control. By following this guide, you’ve successfully installed and configured a self-hosted AI assistant that works with all your favorite messaging platforms.

The journey doesn’t end here. Explore the official documentation to discover advanced features like:

• Multi-agent workflows
• Browser automation
• Voice wake and talk mode
• Canvas visualizations
• Custom skills development

Happy automating with OpenClaw!