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 install -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.

Install OpenClaw

npm install -g openclaw@latest

Install the daemon

openclaw onboard --install-daemon

This creates a launchd service that starts automatically on login.

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.

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

Install OpenClaw

npm install -g openclaw@latest

Install systemd service

openclaw onboard --install-daemon

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

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.

Install WSL2

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu

Restart your computer when prompted.

Open Ubuntu terminal

Launch Ubuntu from the Start menu.

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

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.

Clone the repository

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Install dependencies

pnpm install

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

Build the UI and core

pnpm ui:build
pnpm build

Run the onboarding wizard

pnpm openclaw onboard --install-daemon

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:

AI model selection (Anthropic or OpenAI)
Gateway configuration
Channel setup (WhatsApp, Telegram, etc.)
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

Getting Started

Core Concepts

Channels

Platform Apps

Guides

Installation

Installation

System Requirements

Runtime

Package Manager

Operating System

AI Provider

Global Installation (Recommended)

Verify Installation

Platform-Specific Setup

macOS

Linux

Windows (WSL2)

Installation from Source

Build Commands

Docker Installation

Using Docker Compose

Building from Dockerfile

Docker Configuration

Configuration

Using the Wizard

Manual Configuration

Updating OpenClaw

Global Installation

Source Installation

After Updating

Troubleshooting

Next Steps

Configure OpenClaw

Connect Channels

Deploy to Production

Platform Apps

Getting Started

Core Concepts

Channels

Platform Apps

Guides

​Installation

​System Requirements

Runtime

Package Manager

Operating System

AI Provider

​Global Installation (Recommended)

​Verify Installation

​Platform-Specific Setup

​macOS

​Linux

​Windows (WSL2)

​Installation from Source

​Build Commands

​Docker Installation

​Using Docker Compose

​Building from Dockerfile

​Docker Configuration

​Configuration

​Using the Wizard

​Manual Configuration

​Updating OpenClaw

​Global Installation

​Source Installation

​After Updating

​Troubleshooting

​Next Steps

Configure OpenClaw

Connect Channels

Deploy to Production

Platform Apps

Installation

System Requirements

Global Installation (Recommended)

Verify Installation

Platform-Specific Setup

macOS

Linux

Windows (WSL2)

Installation from Source

Build Commands

Docker Installation

Using Docker Compose

Building from Dockerfile

Docker Configuration

Configuration

Using the Wizard

Manual Configuration

Updating OpenClaw

Global Installation

Source Installation

After Updating

Troubleshooting

Next Steps