For OpenClaw v2026.2 | This article assumes you have Node.js >= 22 and an AI API Key (Anthropic Claude recommended).

TL;DR: Complete OpenClaw installation in 5 minutes. Supports npm/pnpm/bun/Docker. Recommended: npm install -g openclaw@latest && openclaw onboard. Config file at ~/.openclaw/openclaw.json. Start with openclaw gateway. Covers Docker deployment, config structure, and troubleshooting.

Prerequisites

Required Environment

Recommended Environment

AI API Key

OpenClaw requires an AI model connection to work. Recommended providers:

💡 Recommendation: Anthropic Claude Opus 4.6 offers the best long-context handling and prompt injection protection.

Environment Verification

# Check Node.js version
node --version
# Example output: v22.12.0

# Check npm version
npm --version
# Example output: 10.9.0

# Check system info
uname -a  # Linux/macOS
# or
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"  # Windows

Installation Methods Comparison

flowchart TB
    A[Choose installation method] --> B{Use case?}
    B -->|Quick trial| C[npm global install]
    B -->|Daily use| D[pnpm/bun install]
    B -->|Production deployment| E[Docker deployment]
    B -->|Development contribution| F[Source build]
    
    C --> G[5 minutes to complete]
    D --> H[Faster dependency management]
    E --> I[Environment isolation, reproducible]
    F --> J[Customizable, participate in development]

Method Comparison Table

Method 1: npm Global Install (Recommended for Beginners)

Installation Steps

# 1. Install latest stable version
npm install -g openclaw@latest

# 2. Verify installation
openclaw --version
# Example output: 2026.2.26

# 3. View help
openclaw --help

Directory Structure After Install

/usr/local/lib/node_modules/openclaw/  # Global install directory
├── bin/
│   └── openclaw                        # Executable
├── lib/
│   └── ...                             # Core library files
└── package.json

~/.openclaw/                            # User data directory (created on first run)
├── openclaw.json                       # Main config file
├── credentials/                       # Channel credentials storage
├── workspace/                          # Agent workspace
│   ├── AGENTS.md                      # Agent behavior guide
│   ├── SOUL.md                        # Agent personality
│   └── skills/                        # Custom skills
└── logs/                              # Log directory

Run the Onboarding Wizard

# Start interactive configuration wizard
openclaw onboard --install-daemon

The wizard will guide you through:

sequenceDiagram
    participant U as User
    participant W as Wizard
    participant S as System
    
    U->>W: Start onboard
    W->>U: Select model provider
    U->>W: Select Anthropic
    W->>U: Enter API Key
    U->>W: Paste Key
    W->>U: Select Gateway port
    U->>W: 18789 (default)
    W->>U: Install daemon?
    U->>W: Yes
    W->>S: Create systemd/launchd service
    S-->>W: Install success
    W-->>U: Configuration complete!

Method 2: pnpm Install (Recommended for Daily Use)

Install pnpm

# Install pnpm via npm
npm install -g pnpm

# Or use standalone script
curl -fsSL https://get.pnpm.io/install.sh | sh -

Install OpenClaw

# Install with pnpm
pnpm add -g openclaw@latest

# Verify
openclaw --version

pnpm Advantages

Method 3: bun Install (Maximum Speed)

Install bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Or via npm
npm install -g bun

Install OpenClaw

# Install with bun
bun add -g openclaw@latest

# Verify
openclaw --version

bun Advantages

Method 4: Docker Deployment (Recommended for Production)

Pull Image

# Pull latest image
docker pull openclaw/openclaw:latest

# Or specify version
docker pull openclaw/openclaw:2026.2

Basic Run

# Minimal run
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=your_key_here \
  openclaw/openclaw:latest

# View logs
docker logs -f openclaw

Docker Compose Configuration

Create docker-compose.yml:

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # Or use config file
      # - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Start the service:

# Create .env file
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# Start
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Docker Network Configuration

# docker-compose.yml extended config
services:
  openclaw:
    # ... other config
    networks:
      - openclaw-net

  # Optional: reverse proxy
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

Method 5: Source Build (Developers)

Clone Repository

# Clone main repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies (pnpm recommended)
pnpm install

# Build
pnpm build

# Run
pnpm openclaw onboard

Development Mode

# Development mode (auto-reload)
pnpm gateway:watch

# Run tests
pnpm test

# Lint
pnpm lint

Configuration File Reference

Configuration Priority

CLI args > Environment variables > Config file > Defaults

Directory Structure

~/.openclaw/
├── openclaw.json           # Main config file
├── openclaw.json.backup    # Auto backup
├── credentials/            # Sensitive credentials (auto-encrypted)
│   ├── telegram.json
│   ├── whatsapp.json
│   └── discord.json
├── workspace/              # Agent workspace
│   ├── AGENTS.md          # Global behavior guide
│   ├── SOUL.md            # Agent personality
│   ├── TOOLS.md           # Custom tools reference
│   ├── USER.md            # User info
│   └── skills/            # Skills directory
│       ├── gmail/
│       │   └── SKILL.md
│       └── calendar/
│           └── SKILL.md
├── sessions/              # Session data
├── logs/                  # Log files
│   ├── gateway.log
│   └── agent.log
└── cache/                 # Cache data

Minimal Configuration

~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

Full Configuration Example

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verboseLevel": "normal"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "guilds": {}
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      }
    ]
  },
  "webhooks": [],
  "cron": []
}

Configuration Reference

Environment Variables

OpenClaw supports config overrides via environment variables:

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Channel config
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export DISCORD_BOT_TOKEN="..."

# Gateway config
export OPENCLAW_PORT=18789
export OPENCLAW_BIND="loopback"

Start and Verify

Start Gateway

# Foreground (debug mode)
openclaw gateway --verbose

# Background (daemon)
openclaw gateway --daemon

# Specify port
openclaw gateway --port 18790

Verify Running Status

# Check health
openclaw doctor

# Example output:
# ✓ Node.js version: v22.12.0
# ✓ OpenClaw version: 2026.2.26
# ✓ Gateway running on port 18789
# ✓ API key configured
# ✓ Workspace directory exists

Access Web Console

After starting the Gateway, open your browser at:

http://127.0.0.1:18789

You will see the Web Control UI:

Test Conversation

# CLI test
openclaw agent --message "Hello, please introduce yourself"

# Example output:
# Hello! I'm your OpenClaw assistant. I can help you...

Troubleshooting

Issue 1: Port Already in Use

Symptom:

Error: EADDRINUSE: address already in use 127.0.0.1:18789

Solution:

# Find process using the port
lsof -i :18789
# or
netstat -tlnp | grep 18789

# Kill process
kill -9 <PID>

# Or use another port
openclaw gateway --port 18790

Issue 2: Invalid API Key

Symptom:

Error: Invalid API key

Solution:

# Verify config
openclaw config get agent.model

# Check environment variable
echo $ANTHROPIC_API_KEY

# Reconfigure
openclaw onboard

Issue 3: Node Version Too Low

Symptom:

Error: OpenClaw requires Node.js >= 22.0.0

Solution:

# Switch version with nvm
nvm install 22
nvm use 22
nvm alias default 22

# Verify
node --version

Issue 4: Permission Denied

Symptom:

Error: EACCES: permission denied

Solution:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# Or use nvm to manage Node.js (recommended)

Issue 5: Docker Network Problem

Symptom:

Error: Cannot connect to Gateway from container

Solution:

# Check network
docker network ls
docker network inspect bridge

# Use host network
docker run --network host ...

# Or map port correctly
docker run -p 127.0.0.1:18789:18789 ...

Issue 6: Credentials Missing

Symptom:

Warning: Telegram credentials not found

Solution:

# Re-login to channel
openclaw channels login telegram

# Check credentials files
ls ~/.openclaw/credentials/

# Backup credentials
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

Issue 7: Out of Memory

Symptom:

Error: JavaScript heap out of memory

Solution:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"
openclaw gateway

# Or in Docker
docker run -e NODE_OPTIONS="--max-old-space-size=8192" ...

Updates and Maintenance

Update OpenClaw

# npm update
npm update -g openclaw@latest

# pnpm update
pnpm update -g openclaw@latest

# Docker update
docker pull openclaw/openclaw:latest
docker-compose up -d

# Check version
openclaw --version

Switch Release Channel

# Stable (recommended)
openclaw update --channel stable

# Beta
openclaw update --channel beta

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

Backup and Restore

# Backup config
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# Restore config
tar -xzvf openclaw-backup-20260226.tar.gz -C ~/

# Backup key files only
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

Next Steps

Congratulations! You have successfully set up OpenClaw. Next:

1. Configure your first channel → Next: Channel Setup
2. Install your first Skill → Search and install in Web UI
3. Customize Agent personality → Edit ~/.openclaw/workspace/SOUL.md

Summary:

• Learned 5 installation methods and their use cases
• Understood config structure and priority
• Learned startup verification and troubleshooting
• Covered basic update and maintenance

Changelog:

• 2026-02-26: Initial release, based on OpenClaw v2026.2

Series Navigation:

• ← Previous: OpenClaw Introduction
• → Next: Channel Setup: Starting with Telegram