OpenClaw Deployment & Usage Guide

1. Prerequisites

Runtime & Tools

Node.js ≥22 (required for built-in node:sqlite and modern features)
Package manager: npm, pnpm, or bun (pnpm strongly preferred for development)
Git
OS: macOS, Linux, or Windows (via WSL2—strongly recommended for Windows)

External Accounts

AI Provider: Anthropic account (Claude Pro/Max recommended) or OpenAI account
Messaging Channels (optional): Accounts for WhatsApp, Telegram, Slack, Discord, Signal, or other supported platforms you want to connect

2. Installation

Option A: Global NPM Install (Recommended for Users)

npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

Option B: Build from Source (Recommended for Development)

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

pnpm install
pnpm ui:build    # Auto-installs UI dependencies on first run
pnpm build       # Produces dist/ for Node.js binary execution

Development Tools:

TypeScript runs directly via tsx when using pnpm openclaw ...
Built artifacts output to dist/ for production Node execution

3. Configuration

Initial Setup Wizard

Run the interactive onboarding wizard to configure the gateway, workspace, channels, and skills:

# Install with system daemon (launchd on macOS, systemd on Linux)
openclaw onboard --install-daemon

# Or configure without daemon first
openclaw onboard

AI Provider Authentication

Configure model access via OAuth or API keys:

# The wizard will prompt for provider credentials
# Recommended: Anthropic Pro/Max (100/200) with Opus 4.6 for long-context strength

Manual Auth Management:

Auth profiles support rotation and fallbacks
Config location: Managed via openclaw CLI (use openclaw doctor to verify)

Security Configuration (Critical)

OpenClaw treats inbound DMs as untrusted by default.

Default DM Policy (Pairing Mode): Unknown senders receive a pairing code and messages are blocked until approved.

# Approve a device/sender
openclaw pairing approve <channel> <code>

# Configure channel-specific policies in generated config:
# dmPolicy="pairing"  (default - requires approval)
# dmPolicy="open"     (allow all - not recommended)

Channel Setup

Enable messaging channels via the wizard or manual configuration:

WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage
BlueBubbles, Matrix, Zalo, WebChat

4. Build & Run

Development Mode (Hot Reload)

# From source directory
pnpm gateway:watch    # Auto-reloads on TypeScript changes

Production Mode

# Run gateway manually
openclaw gateway --port 18789 --verbose

# Run with specific configuration
openclaw gateway --port 18789 --config /path/to/config

CLI Commands

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

# Direct agent interaction
openclaw agent --message "Ship checklist" --thinking high

Daemon Management

If installed with --install-daemon:

macOS: Managed via launchd (user service)
Linux: Managed via systemd user service

# Check status
openclaw doctor

# Update to new version
openclaw update --channel stable   # or beta, dev

5. Deployment

Docker Deployment

# See official Docker documentation at https://docs.openclaw.ai/install/docker
docker run -p 18789:18789 -v openclaw-data:/data openclaw/openclaw:latest

Self-Hosted VPS/Server

Prerequisites: Install Node ≥22 and pnpm
Build: Follow "Build from Source" steps
Process Manager: Use systemd (Linux) or launchd (macOS) via openclaw onboard --install-daemon
Reverse Proxy: Configure Nginx/Caddy for WebSocket support on port 18789

Nginx WebSocket Configuration Example:

location / {
    proxy_pass http://localhost:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Cloud Platforms

Nix: Use nix-openclaw flake for reproducible deployments
Railway/Render: Deploy Docker container with persistent volume for SQLite database
Fly.io: Suitable for WebSocket gateway deployment

Data Persistence: Ensure these directories are backed up:

Agent workspaces (session data)
SQLite databases (memory/QMD storage)
Configuration files

6. Troubleshooting

Diagnostic Tools

# Run system health check
openclaw doctor

# Verify configuration
openclaw config validate

Common Issues

Node Version Errors

Ensure Node ≥22: node --version
OpenClaw requires native node:sqlite module introduced in Node 22

UI Build Failures

# Rebuild UI assets
pnpm ui:build
pnpm build

Port Conflicts

Default port 18789 may be occupied
Specify alternative: openclaw gateway --port 8080

Authentication Failures

Check auth profile status: Profiles enter cooldown after failures
Verify API keys are valid and have billing enabled
For OAuth: Ensure subscription is active (Anthropic Pro/Max)

Database/Locking Issues

SQLite is used for memory and session storage
Ensure single process access to state directory
Check permissions on ~/.openclaw/state/ (or platform equivalent)

Gateway Connection Refused

Verify daemon is running: openclaw doctor
Check firewall rules for port 18789
For remote access: Ensure dmPolicy is configured (security default blocks unknown DMs)

Memory/Context Window Errors

Model context limits reached: Switch to higher-capacity model (Opus 4.6 recommended)
Enable automatic compaction in configuration

Getting Help

Documentation: https://docs.openclaw.ai
Discord: https://discord.gg/clawd
Wizard: Run openclaw onboard to reconfigure any component

How to Deploy & Use openclaw