Installation & Troubleshooting

Get OpenClaw running on macOS, Linux, Windows, Raspberry Pi, or in Docker.

📦 Install Methods

Recommended: One-Line Installer

Detects your OS, installs Node if needed, and runs onboarding.

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex

npm / pnpm

If you already have Node 22.14+ or Node 24:

# npm (global)
npm install -g openclaw

# pnpm
pnpm add -g openclaw

Docker

Run OpenClaw in a container with persistent state:

docker run -d \
  --name openclaw \
  -v openclaw-data:/root/.openclaw \
  -p 18789:18789 \
  ghcr.io/openclaw/openclaw:latest

From Source

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
node dist/cli.js setup

💻 OS-Specific Notes

macOS

Install via the one-liner. If you use Homebrew for Node, make sure it's Node 22.14+ or 24.

Linux (Ubuntu/Debian)

curl -fsSL https://openclaw.ai/install.sh | bash
# If running on a server, enable the systemd service:
openclaw gateway start

Raspberry Pi

Works great on Pi 4/5 (ARM64). The installer handles everything.

Windows

WSL2 is recommended over native Windows for stability.

# Option A: WSL2 (recommended)
wsl --install
# Then inside WSL:
curl -fsSL https://openclaw.ai/install.sh | bash

# Option B: Native PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

🔍 Post-Install Checklist

# Check everything is working:
openclaw status

# Run diagnostics:
openclaw doctor

# Check model connectivity:
openclaw models list

🛠️ Troubleshooting

"Gateway not running"

# Start the gateway:
openclaw gateway start

# Check logs:
openclaw logs

"No model configured"

# Run setup again:
openclaw configure

# Or set directly:
openclaw models set anthropic/claude-sonnet-4-20250514

"WhatsApp QR code not showing"

# Make sure gateway is running first:
openclaw gateway status

# Then login to WhatsApp:
openclaw channels login whatsapp

"Permission denied" on Linux

# Don't use sudo for install — instead:
npm install -g openclaw --unsafe-perm

# Or fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

"Port 18789 already in use"

# Change the gateway port:
openclaw config set gateway.bind.port 18790

# Or find what's using it:
lsof -i :18789

Still stuck?

← Back to Guide