Installation

Detailed installation instructions for OpenClaw on macOS, Linux, and Windows

Installation

OpenClaw can be installed globally via npm, built from source, or run with Docker. This guide covers all installation methods and platform-specific notes.

System Requirements

Runtime

Node.js ≥ 22.12.0 (LTS recommended)

Package Manager

npm, pnpm, or bun

Operating System

macOS, Linux, or Windows (WSL2)

AI Provider

Anthropic or OpenAI subscription

Windows users must use WSL2 (Windows Subsystem for Linux). Native Windows support is not available.

Global Installation (Recommended)

Install OpenClaw globally for easy access from anywhere:

npm

npm install -g openclaw@latest

pnpm add -g openclaw@latest

bun add -g openclaw@latest

Verify Installation

# Check version
oclaw --version

# Run diagnostics
oclaw doctor

Platform-Specific Setup

macOS

On macOS, OpenClaw can run as a menu bar app or as a daemon service.

1. Install OpenClaw

   npm install -g openclaw@latest
   
2. Install the daemon

   openclaw onboard --install-daemon
   

   This creates a launchd service that starts automatically on login.

3. Optional: Install macOS app

   Download the macOS app from the releases page for menu bar control, Voice Wake, and Canvas support.

The macOS app requires signed builds for TCC permissions (camera, microphone, screen recording) to persist across updates.

Linux

Linux installation uses systemd for the daemon service.

1. Install Node.js 22+

   Using nvm:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 22
   nvm use 22
   

   Or using your package manager:

   # Ubuntu/Debian
   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt-get install -y nodejs
   
   # Fedora
   sudo dnf install nodejs
   
   # Arch
   sudo pacman -S nodejs npm
   
2. Install OpenClaw

   npm install -g openclaw@latest
   
3. Install systemd service

   openclaw onboard --install-daemon
   

   This creates a systemd user service at ~/.config/systemd/user/openclaw-gateway.service.

4. Manage the service

   # Start
   systemctl --user start openclaw-gateway
   
   # Stop
   systemctl --user stop openclaw-gateway
   
   # Status
   systemctl --user status openclaw-gateway
   
   # Enable auto-start
   systemctl --user enable openclaw-gateway
   

Windows (WSL2)

Windows users must use WSL2. Native Windows is not supported.

1. Install WSL2

   Open PowerShell as Administrator and run:

   wsl --install -d Ubuntu
   

   Restart your computer when prompted.

2. Open Ubuntu terminal

   Launch Ubuntu from the Start menu.

3. Install Node.js 22+

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   source ~/.bashrc
   nvm install 22
   nvm use 22
   
4. Install OpenClaw

   npm install -g openclaw@latest
   openclaw onboard --install-daemon
   

WSL2 networking allows you to access the Gateway from Windows browsers at http://127.0.0.1:18789.

Installation from Source

For development or customization, build OpenClaw from source.

1. Clone the repository

   git clone https://github.com/openclaw/openclaw.git
   cd openclaw
   
2. Install dependencies

   pnpm install
   

   Source builds require pnpm. Bun can also be used for running TypeScript directly.

3. Build the UI and core

   pnpm ui:build
   pnpm build
   
4. Run the onboarding wizard

   pnpm openclaw onboard --install-daemon
   
5. Development mode

   For auto-reload on code changes:

   pnpm gateway:watch
   

Build Commands

# Type-check and build
pnpm build

# Type-check only
pnpm tsgo

# Lint and format
pnpm check

# Run tests
pnpm test

# Run with coverage
pnpm test:coverage

Docker Installation

Run OpenClaw in a Docker container for isolated deployment.

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-secure-token-here
      - OPENCLAW_GATEWAY_PASSWORD=your-password-here
    command: ["node", "openclaw.mjs", "gateway", "--allow-unconfigured", "--bind", "lan"]

Start the container:

docker-compose up -d

Building from Dockerfile

The Dockerfile in the repository supports custom builds:

# Build with browser support (adds ~300MB but pre-installs Chromium)
docker build --build-arg OPENCLAW_INSTALL_BROWSER=1 -t openclaw:custom .

# Build with additional packages
docker build --build-arg OPENCLAW_DOCKER_APT_PACKAGES="git curl" -t openclaw:custom .

Docker containers bind to localhost by default. Use --bind lan to allow external connections, but ensure you set authentication tokens.

Docker Configuration

Mount your configuration file:

docker run -d \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENCLAW_GATEWAY_TOKEN=your-token \
  ghcr.io/openclaw/openclaw:latest

See the Docker guide for detailed configuration options.

Configuration

After installation, configure OpenClaw:

Using the Wizard

oclaw onboard

The wizard will guide you through:

1. AI model selection (Anthropic or OpenAI)
2. Gateway configuration
3. Channel setup (WhatsApp, Telegram, etc.)
4. Security settings

Manual Configuration

Edit ~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    }
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN"
    }
  }
}

See the configuration guide for all options.

Updating OpenClaw

Global Installation

# Update to latest stable
npm update -g openclaw

# Update to specific version
npm install -g openclaw@2026.2.19

# Switch to beta channel
npm install -g openclaw@beta

Source Installation

cd openclaw
git pull --rebase origin main
pnpm install
pnpm build

After Updating

Run diagnostics and migrations:

oclaw doctor

See the updating guide for detailed upgrade instructions.

Troubleshooting

Command not found: openclaw

The OpenClaw binary is not in your PATH.

For npm global installs, ensure npm prefix -g is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm prefix -g)/bin:$PATH"

For pnpm, add the pnpm global bin directory:

# macOS
export PATH="$HOME/Library/pnpm:$PATH"

# Linux
export PATH="$HOME/.local/share/pnpm:$PATH"

Permission denied errors

Don’t use sudo with global npm install. Fix permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Then reinstall OpenClaw:

npm install -g openclaw

Node version too old

OpenClaw requires Node.js ≥ 22.12.0. Install via nvm:

nvm install 22
nvm use 22
nvm alias default 22

pnpm build fails

Clear caches and reinstall:

pnpm store prune
rm -rf node_modules
pnpm install
pnpm build

Next Steps

Configure OpenClaw

Set up your AI model, channels, and security settings

Connect Channels

Add WhatsApp, Telegram, Discord, and more

Deploy to Production

Run OpenClaw on a VPS or cloud instance

Platform Apps

Install the macOS app or mobile nodes