This guide walks through installing OpenClaw, an open-source personal AI agent that runs on your own machine and communicates through chat apps like WhatsApp, Telegram, Discord, Slack, and iMessage.
Official Resources:
For Node.js installation, see Node.js.
OpenClaw offers multiple installation methods:
| Method | Best For | Complexity |
|---|---|---|
| Installer Script | Quick setup on macOS/Linux/WSL | Lowest |
| npm/pnpm | Most users, direct installation | Low |
| Docker | Isolated environments, production | Medium |
| From Source | Developers, custom builds | High |
macOS/Linux/WSL2:
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell):
iwr -useb https://openclaw.ai/install.ps1 | iex
Skip onboarding:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
The installer will:
Ensure Node.js version 24 or higher is installed (Node.js 22 LTS 22.16+ also supported):
node -v # Should show v24.x.x or higher (or v22.16+)
If not installed, see Node.js for installation instructions.
Install OpenClaw globally via npm:
npm install -g openclaw@latest
Alternatively, using pnpm:
pnpm add -g openclaw@latest
pnpm approve-builds -g
Start the interactive onboarding wizard:
openclaw onboard --install-daemon
The wizard will guide you through:
Start the OpenClaw gateway service:
openclaw gateway --port 18789
Open your browser and navigate to:
http://127.0.0.1:18789/?token=<your-token>
To retrieve your access token:
# On Linux/macOS
cat ~/.openclaw/openclaw.json | grep token
# Or use the dashboard command
openclaw dashboard --no-open
OpenClaw provides Dockerfiles in the repository for building images locally. The GitHub repository shows no official pre-built images published at ghcr.io, so you’ll need to build from source.
Note: Community-maintained Docker images may exist, but for production deployments, building from source using the provided Dockerfiles is recommended.
mkdir -p /opt/openclaw
cd /opt/openclaw
mkdir -p config workspace
Create a secure random token for gateway authentication:
openssl rand -hex 32
Save this token for later use.
Create a .env file:
cat > .env << EOF
# Gateway access token (use the value generated above)
OPENCLAW_GATEWAY_TOKEN=your-random-token-here
# Gateway port (default: 18789)
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
# Bind address: "lan" for all interfaces, "loopback" for localhost only
OPENCLAW_GATEWAY_BIND=lan
# Volume paths
OPENCLAW_CONFIG_DIR=/opt/openclaw/config
OPENCLAW_WORKSPACE_DIR=/opt/openclaw/workspace
# Docker image (build locally from repository)
# OPENCLAW_IMAGE=openclaw:local
EOF
version: '3.8'
services:
openclaw-gateway:
image: ${OPENCLAW_IMAGE:-openclaw:local}
container_name: openclaw-gateway
build:
context: .
dockerfile: Dockerfile
restart: unless-stopped
ports:
- "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
- "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
environment:
- HOME=/home/node
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
command: ["node", "dist/index.js", "gateway", "--bind", "${OPENCLAW_GATEWAY_BIND:-lan}", "--port", "18789"]
openclaw-cli:
image: ${OPENCLAW_IMAGE:-openclaw:local}
container_name: openclaw-cli
build:
context: .
dockerfile: Dockerfile
restart: unless-stopped
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
environment:
- HOME=/home/node
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
- BROWSER=echo
entrypoint: ["node", "dist/index.js"]
stdin_open: true
tty: true
docker compose up -d
Alternatively, clone the repository and use the included Docker setup script:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh
This script builds a local Docker image and starts the gateway service.
OpenClaw stores configuration in:
~/.openclaw/openclaw.json
| Setting | Description |
|---|---|
gateway.mode |
"local" for local access, "lan" for network access |
gateway.port |
Gateway port (default: 18789) |
gateway.auth.mode |
Authentication mode ("token") |
gateway.auth.token |
Access token for Web UI |
models.providers |
Configured AI model providers |
channels |
Connected messaging platforms |
| Command | Description |
|---|---|
openclaw -v |
Check version |
openclaw --help |
Show help |
openclaw gateway start |
Start gateway |
openclaw gateway restart |
Restart gateway |
openclaw gateway status |
Check gateway status |
openclaw gateway stop |
Stop gateway |
openclaw configure |
Reconfigure settings |
openclaw channels add |
Add communication channels |
openclaw dashboard |
Open Web UI |
openclaw doctor |
Health checks and security audit - surfaces risky/misconfigured DM policies, network exposure |
openclaw logs |
View gateway logs |
openclaw message send --to <number> --message "<text>" |
Send a message |
openclaw agent --message "<prompt>" |
Chat with the agent |
openclaw devices list |
List pending device pairings |
openclaw devices approve <REQUEST_ID> |
Approve a device pairing |
openclaw pairing approve <channel> <code> |
Approve DM pairing from unknown sender |
OpenClaw supports 22 messaging platform integrations:
| Platform | Setup Method |
|---|---|
| Telegram | Bot token from @BotFather |
| QR code pairing (WhatsApp Web protocol) | |
| Discord | Bot token from Discord Developer Portal |
| Slack | App token + bot token |
| iMessage | macOS only, requires additional setup |
| Signal | Via signal-cli |
| Mattermost | Plugin installation |
| Provider | Models | Setup |
|---|---|---|
| Anthropic | Claude 3.5, Claude 3, Claude Sonnet 4 | API key |
| OpenAI | GPT-4, GPT-4o, GPT-5 | API key |
| Ollama | llama3.1, mistral, phi3 | Local installation |
| MiniMax | MiniMax models | API key |
| Mistral | Mistral models | API key |
| OpenRouter | Multiple providers | API key |
OpenClaw supports 28+ model providers. See official docs for the complete list.
# Check Node.js version
node -v # Must be v22+
# Reinstall OpenClaw
npm install -g openclaw@latest
# Check logs
openclaw logs
Approve the device pairing:
# List pending devices
openclaw devices list
# Approve device
openclaw devices approve <REQUEST_ID>
Change the gateway port:
openclaw gateway --port 19001
# Stop gateway
openclaw gateway stop
# Backup and reset
mv ~/.openclaw ~/.openclaw.backup
openclaw onboard --install-daemon
~/.openclaw/openclaw.jsondmPolicy="pairing") - unknown senders require approvalopenclaw security audit to check for misconfigurationsFor detailed security guidance, see OpenClaw Security.
| Language | Percentage | Usage |
|---|---|---|
| TypeScript | 88.4% | Gateway daemon, CLI, web components |
| Swift | 7.3% | macOS/iOS clients, menu bar app |
| Kotlin | 1.6% | Android node |
| Other | 2.7% | Shell, JavaScript, CSS |
| Library | Purpose |
|---|---|
| Baileys | WhatsApp WebSocket integration |
| grammY | Telegram bot framework |
| TypeBox | JSON Schema validation |
Choose your deployment method:
openclaw plugins listSetting up Openclaw can be complex. We offer consulting services for:
Contact us at office@linux-server-admin.com or visit our contact page.