Openclaw Install

OpenClaw Installation & Configuration

OpenClaw is an open-source AI agent platform (github.com/openclaw/openclaw, 373k+ GitHub stars). It is NOT the same as Hermes WebUI (nesquena/hermes-webui) — they are completely different products. OpenClaw uses Docker, Node.js/TypeScript, and its own skill system (ClawHub).

⚠️ Critical Distinction: OpenClaw ≠ Hermes WebUI

Both can coexist on the same server but serve different purposes. Do NOT confuse them.

Quick Deploy (Docker)

1. Pull the Docker image

docker pull ghcr.io/openclaw/openclaw:latest

2. Create config directory structure

mkdir -p /root/.openclaw/workspace /root/.openclaw-auth-profile-secrets
chmod -R 777 /root/.openclaw /root/.openclaw-auth-profile-secrets
Container runs as UID 1000 (node user) — needs write access

3. Run initial setup (generates default config)

docker run --rm \
  -v /root/.openclaw:/home/node/.openclaw \
  -v /root/.openclaw/workspace:/home/node/.openclaw/workspace \
  ghcr.io/openclaw/openclaw:latest \
  node dist/index.js setup --non-interactive --accept-risk

This creates /root/.openclaw/openclaw.json with default configuration.

4. Configure providers (API keys)

Edit /root/.openclaw/openclaw.json — add env block with API keys:

{
  "defaultProvider": "chutes",
  "defaultModel": "zai-org/GLM-5-Turbo",
  "env": {
    "OPENCLAW_API_KEY_CHUTES": "sk-your-chutes-key",
    "OPENCLAW_API_KEY_GROQ": "gsk_your-groq-key",
    "OPENCLAW_API_KEY_OPENROUTER": "sk-or-your-key"
  },
  "gateway": {
    "controlUi": {
      "allowedOrigins": ["https://your-domain.example.com"]
    }
  }
}

Provider name mapping — OpenClaw uses lowercase provider names as env var suffixes:

Important: Use a working free provider (e.g., Chutes) as the default. Avoid providers that require special env vars (like opencode-go which needs a separate API key env var) unless that env var is also set.

5. Create Docker Compose

# /opt/openclaw/docker-compose.yml
version: "3.8"
services:
  gateway:
    image: ghcr.io/openclaw/openclaw:latest
    ports:
      - "18789:8080"
    volumes:
      - /root/.openclaw:/home/node/.openclaw
      - /root/.openclaw/workspace:/home/node/.openclaw/workspace
      - /root/.openclaw-auth-profile-secrets:/home/node/.openclaw-auth-profile-secrets
      - /etc/localtime:/etc/localtime:ro
    environment:
      - OPENCLAW_AUTH_PASSWORD=munaf
    restart: unless-stopped

6. Start the gateway

cd /opt/openclaw && docker compose up -d

7. Verify

curl -s http://localhost:18789/healthz
{"ok":true,"status":"live"}
docker logs openclaw-openclaw-gateway-1 --tail 10
Should show: [gateway] ready, [browser/server] Browser control listening

8. Install skills from ClawHub

# List available skills
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills list
Search for skills
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills search "browser"
Install skills
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install bsession
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install github
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install research-agent
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install web-search
... etc

Skills install to /home/node/.openclaw/workspace/skills/ (mapped to /root/.openclaw/workspace/skills/ on host).

9. Restart after config changes

cd /opt/openclaw && docker compose restart

Nginx + SSL (External Access)

# /etc/nginx/sites-available/openclaw
server {
    server_name oc.example.com;
location / {
        proxy_pass http://127.0.0.1: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;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
        proxy_buffering off;
    }
}

ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d oc.example.com

Do NOT add nginx auth_basic — OpenClaw has built-in password auth (OPENCLAW_AUTH_PASSWORD env var). Adding nginx auth creates a double-login.

Browser Plugin (CamoFox)

OpenClaw auto-detects a running CamoFox browser server. If CamoFox is on localhost:9377, the gateway log will show:

[browser/server] Browser control listening on http://127.0.0.1:18791/ (auth=password)

And the browser plugin appears in the gateway startup line.

To point OpenClaw at a remote CamoFox fleet, add browser config to openclaw.json:

{
  "browser": {
    "endpoints": [
      {"url": "http://localhost:9377", "label": "US"},
      {"url": "http://103.171.122.216:9377", "label": "PK"},
      {"url": "http://103.171.122.217:9377", "label": "PK-2"}
    ]
  }
}

Password Auth

Set OPENCLAW_AUTH_PASSWORD in the Docker Compose environment:

environment:
  - OPENCLAW_AUTH_PASSWORD=munaf

Copying Config from Another Hermes Setup

When migrating API keys from a Hermes Agent config:

Important: Hermes .env values like OPENCODE_GO_API_KEY=* are MASKED — the real keys are in config.yaml under each provider's api_key: field. Always copy from config.yaml, not .env.

Also important: PyYAML's dump() mangles config files. Never round-trip a YAML config through yaml.safe_load() → yaml.dump(). Use scp for raw file transfer, then sed or Python string replacement for targeted edits.

Config Directory Layout

/root/.openclaw/
├── openclaw.json          # Main config (providers, model, system prompt)
├── workspace/
│   └── skills/            # Installed ClawHub skills
│       ├── bsession/
│       ├── github/
│       ├── research-agent/
│       └── ...
└── auth-profile-secrets/
/opt/openclaw/
├── docker-compose.yml
└── .env                   # OPENCLAW_API_KEY_* vars (alternative to openclaw.json env)

Pitfalls

Files

Advanced Techniques (2025-2026)

Docker healthcheck with restart policies

Add a healthcheck to your Compose service so Docker can detect gateway hangs and auto-restart:

services:
  gateway:
    # ... existing config ...
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    restart: unless-stopped

Without a healthcheck, Docker only restarts on process exit — not on deadlocks or silent hangs. The /healthz endpoint returns {"ok":true} when the gateway is live.

Compose Watch zero-downtime config reload (v2.22+)

Use Docker Compose Watch to hot-reload openclaw.json changes without restarting the container:

services:
  gateway:
    # ... existing config ...
    develop:
      watch:
        - path: /root/.openclaw/openclaw.json
          action: sync
          target: /home/node/.openclaw/openclaw.json

This is especially useful for iterative provider/model tuning — changes propagate in seconds instead of requiring docker compose restart.

Fix UID mismatch with chown instead of chmod 777

The container runs as UID 1000 (node). chmod 777 works but is sloppy. Prefer targeted ownership:

# Instead of: chmod -R 777 /root/.openclaw
chown -R 1000:1000 /root/.openclaw /root/.openclaw-auth-profile-secrets

This grants the node user write access without making directories world-writable.

jq for JSON config editing

Since openclaw.json is JSON (not YAML), jq is the right tool for scripted edits:

# Change default provider
jq '.defaultProvider = "chutes"' /root/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json /root/.openclaw/openclaw.json
Add an API key
jq '.env.OPENCLAW_API_KEY_CHUTES = "sk-xxx"' /root/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json /root/.openclaw/openclaw.json
Set gateway bind to lan
jq '.gateway.bind = "lan"' /root/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json /root/.openclaw/openclaw.json

Edge Cases / Pitfalls

OpenClaw 2025 Updates

Skill Marketplace Growth (ClawHub 200+)

ClawHub has expanded from ~52 built-in skills to 200+ community and official skills. New categories include data-pipeline, devops-automate, ai-redteam, and browser-agent clusters. Search and install:

# Browse by category
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills search "category:data-pipeline"
Install popular new skills
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install browser-agent
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install ai-redteam
docker exec openclaw-openclaw-gateway-1 node dist/index.js skills install devops-automate

The marketplace now supports skill dependencies — installing a skill auto-installs its prerequisites. Check for skill updates with skills update .

Browser Plugin Improvements (CamoFox v2+)

CamoFox integration improvements in 2025:

{
  "browser": {
    "endpoints": [
      {"url": "http://localhost:9377", "label": "local", "fingerprintRotation": true}
    ],
    "sessionPersistence": true
  }
}

Docker Compose v2 Healthcheck + Watch

The develop.watch section and healthchecks documented earlier are now the recommended deployment pattern. One addition: use depends_on with health conditions for startup ordering:

services:
  gateway:
    # ... existing config ...
    depends_on:
      redis:
        condition: service_healthy
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 5

This ensures the gateway doesn't start accepting connections until Redis is ready.

References

Templates

Scripts