openclaw-docker-setup

# openclaw-docker-setup Install a fully isolated, production-ready OpenClaw instance inside Docker on macOS. One session, zero to running. All common pitfalls are handled inline. **Supports multiple instances on the same machine.** Each instance gets a unique name and port. **What you end up with:** - A named container running and auto-restarting - Persistent data via named Docker volumes (survives container recreation) - Dashboard accessible at http://127.0.0.1:YOUR_PORT/ - Discord channel configured and responding - (Optional) Gmail working via Himalaya (supports attachments); Google Drive via gog --- ## Step 0: Pick Your Instance Name and Port Run this auto-detect script. It scans existing OpenClaw containers, finds the next free port, and suggests a name. Confirm or override. ```bash # Auto-detect existing instances and suggest next available name+port python3 - << 'AUTODETECT' import subprocess, re # Find all running openclaw containers result = subprocess.run( ["docker", "ps", "-a", "--format", "{{.Names}} {{.Ports}}"], capture_output=True, text=True ) existing = {} for line in result.stdout.strip().splitlines(): parts = line.split(' ') name = parts[0] ports = parts[1] if len(parts) > 1 else "" if 'openclaw' in name.lower() or '18789' in ports: m = re.search(r'0\.0\.0\.0:(\d+)->18789', ports) port = int(m.group(1)) if m else None existing[name] = port # Find next free port starting from 19002 used_ports = set(p for p in existing.values() if p) port = 19002 while port in used_ports: port += 1 # Suggest name count = len(existing) + 1 names = ["openclaw-main", "openclaw-work", "openclaw-demo", "openclaw-test", "openclaw-lab"] suggested_name = names[min(count - 1, len(names) - 1)] print("\n=== Existing OpenClaw instances ===") if existing: for n, p in existing.items(): print(f" {n} → port {p}") else: print(" (none found)") print(f"\n=== Suggested for new instance ===") print(f" INSTANCE={suggested_name}") print(f" HOST_PORT={port}") print(f"\nTo accept, run:") print(f" export INSTANCE={suggested_name}") print(f" export HOST_PORT={port}") print(f"\nTo override, replace the values and run the export commands with your chosen values.") AUTODETECT ``` Review the output, then set your variables: ```bash # Accept suggestion (paste the export lines from the output above) export INSTANCE=openclaw-main export HOST_PORT=19002 # Or override with your own values: export INSTANCE=openclaw-demo export HOST_PORT=19003 ``` **All subsequent commands in this guide use `$INSTANCE` and `$HOST_PORT`.** Keep this terminal session open, or re-export the variables if you open a new one. **Multiple instances example:** | Instance | Host port | Purpose | |----------|-----------|---------| | `openclaw-main` | 19002 | Primary personal assistant | | `openclaw-demo` | 19003 | Public demo / lecture | | `openclaw-work` | 19004 | Work projects | Each instance has its own volumes (`$INSTANCE-data`, `$INSTANCE-home`) — data is fully isolated. --- ## Prerequisites - macOS (Darwin) — Intel or Apple Silicon - Docker Desktop installed and running (or Docker Engine + CLI) - Claude Code CLI installed on the host if using a Claude Max/Pro subscription (`claude` command available). Skip if using a raw API key. Verify Docker is running: ```bash docker --version docker ps ``` Both commands must succeed before continuing. --- ## Step 1: Pull the Image The official image is on GitHub Container Registry (GHCR), **not Docker Hub**. ```bash docker pull ghcr.io/openclaw/openclaw:latest ``` > **Pitfall:** `openclaw/openclaw` on Docker Hub does not exist. Always use `ghcr.io/openclaw/openclaw:latest`. **Success:** Pull completes without error and `docker images | grep openclaw` shows the image. --- ## Step 2: Generate a Claude Setup Token **Skip this step if you have a raw Anthropic API key** — you will pass it via `-e ANTHROPIC_API_KEY=sk-ant-api03-...` in Step 3 instead. If you have a Claude Max or Pro subscription, generate a setup token on the host: ```bash claude setup-token ``` Copy the token (format: `sk-ant-oat01-...`). You will paste it into the container in Step 5. > **Pitfall:** This is a **setup token**, not an API key. The two are different. A setup token lets the container authenticate using your subscription. An API key charges per token. --- ## Step 3: Launch the Container Use the `$INSTANCE` and `$HOST_PORT` variables you set in Step 0. Do not reduce the memory — 512 MB and 1024 MB are insufficient and cause crash loops. ```bash docker run -d \ --name $INSTANCE \ --restart unless-stopped \ -p $HOST_PORT:18789 \ -m 2048m \ --cpus=2 \ --cap-drop=ALL \ --cap-add=NET_BIND_SERVICE \ --security-opt no-new-privileges \ -v ${INSTANCE}-data:/app/data \ -v ${INSTANCE}-home:/home/node \ -e NODE_OPTIONS="--max-old-space-size=1024" \ ghcr.io/openclaw/openclaw:latest ``` If using a raw API key instead of a setup token, add `-e ANTHROPIC_API_KEY=sk-ant-api03-...` before the image name. Wait 10 seconds, then verify: ```bash docker ps --filter name=$INSTANCE ``` **Success:** Status shows `Up X seconds` and the container is not restarting. > **Pitfall — OOM crash loop:** If the container keeps restarting, check logs: > `docker logs --tail 20 $INSTANCE` > If you see `JavaScript heap out of memory`, the container needs `-m 2048m` AND `-e NODE_OPTIONS="--max-old-space-size=1024"`. Recreate with the full command above. > **Pitfall — port conflict:** If the port is in use, you chose the wrong `HOST_PORT` in Step 0. Re-run the conflict check: `lsof -i :$HOST_PORT`. Pick a free port and relaunch. --- ## Step 4: Configure the Gateway The gateway binds to `127.0.0.1` (loopback) inside the container by default. Docker port-forwarding sends traffic to the container's network interface, not its loopback. You must switch to LAN mode. ### 4a. Set bind to LAN ```bash docker exec $INSTANCE node /app/openclaw.mjs config set gateway.bind lan ``` ### 4b. Set allowed origins Non-loopback bind requires explicitly allowed origins or the gateway refuses to start: ```bash docker exec $INSTANCE node /app/openclaw.mjs config set \ gateway.controlUi.allowedOrigins '["http://127.0.0.1:$HOST_PORT"]' --json ``` ### 4c. Restart to apply ```bash docker restart $INSTANCE ``` Wait 10 seconds, then verify: ```bash curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:$HOST_PORT/ ``` **Success:** Returns `200`. > **Pitfall — crash after setting LAN bind:** If you set `gateway.bind lan` but forget the `allowedOrigins` step, the container crash-loops with `non-loopback Control UI requires gateway.controlUi.allowedOrigins`. Run step 4b, then restart. --- ## Step 5: Register Authentication > **Important:** Do NOT paste your token directly in the command line — it would be stored in shell history. The command below prompts interactively. ```bash docker exec -it $INSTANCE node /app/openclaw.mjs models auth paste-token --provider anthropic ``` When prompted, paste the setup token from Step 2 (or your API key if using one). **Success:** ``` Updated ~/.openclaw/openclaw.json Auth profile: anthropic:manual (anthropic/token) ``` > **Pitfall — `openclaw` command not found:** The CLI binary is NOT installed as a global command in this image. Always use `node /app/openclaw.mjs` inside the container: > ```bash > docker exec $INSTANCE node /app/openclaw.mjs <command> > ``` > For interactive commands (pasting tokens, TTY prompts), add `-it`: > ```bash > docker exec -it $INSTANCE node /app/openclaw.mjs <command> > ``` --- ## Step 6: Verify Authentication and Gateway ```bash # Check model auth docker exec $INSTANCE node /app/openclaw.mjs models status ``` **Success:** Output includes `Providers w/ OAuth/tokens (1): anthropic (1)` ```bash # Check gateway docker exec $INSTANCE node /app/openclaw.mjs gateway status ``` **Success:** Output includes `RPC probe: ok` --- ## Step 7: Access the Dashboard and Pair Your Browser ### Get the gateway auth token The CLI redacts secrets in output. Read the raw config file instead: ```bash docker exec $INSTANCE cat /home/node/.openclaw/openclaw.json ``` Find `gateway.auth.token` in the output. Copy it. ### Open the dashboard Open http://127.0.0.1:$HOST_PORT/ in your browser. Enter the gateway token to log in. The browser will show "Pairing required." This is expected on first access. ### Approve the pairing request ```bash docker exec $INSTANCE node /app/openclaw.mjs devices list ``` Find the pending request ID, then approve it: ```bash docker exec $INSTANCE node /app/openclaw.mjs devices approve <REQUEST_ID> ``` Refresh the browser. **Success:** Dashboard loads and shows the OpenClaw interface. --- ## Step 8: Configure Discord ### Create a Discord bot 1. Go to https://discord.com/developers/applications 2. Click **New Application** — name it (e.g. "OpenClaw Isolated") 3. Go to **Bot** → set a username → click **Reset Token** → copy the token 4. Under **Privileged Gateway Intents**, enable: - **Message Content Intent** (required) - **Server Members Intent** (recommended) 5. Go to **OAuth2 > URL Generator**: - Scopes: `bot` AND `applications.commands` (both required) - Bot Permissions: View Channels, Send Messages, Read Message History, Embed Links, Attach Files 6. Copy the generated URL, open it in a browser, and add the bot to your server > **Pitfall — slash commands say "not authorized":** If you invite the bot without `applications.commands`, slash commands will not work. Re-authorize using this URL (replace `BOT_CLIENT_ID`): > ``` > https://discord.com/oauth2/authorize?client_id=BOT_CLIENT_ID&scope=bot+applications.commands&permissions=274877991936 > ``` ### Collect Discord IDs Enable **Developer Mode**: Discord → User Settings → Advanced → Developer Mode. - Right-click your server icon → **Copy Server ID** - Right-click your own avatar → **Copy User ID** ### Configure Discord in the container Replace `YOUR_DISCORD_BOT_TOKEN`, `YOUR_SERVER_ID`, and user IDs with real values. ```bash # Enable Discord docker exec $INSTANCE node /app/openclaw.mjs config set \ channels.discord.enabled true --json # Set bot token docker exec $INSTANCE node /app/openclaw.mjs config set \ channels.discord.token '"YOUR_DISCORD_BOT_TOKEN"' --json # Set access policy to allowlist docker exec $INSTANCE node /app/openclaw.mjs config set \ channels.discord.groupPolicy '"allowlist"' --json # Configure the guild with authorized users docker exec $INSTANCE node /app/openclaw.mjs config set \ channels.discord.guilds \ '{"YOUR_SERVER_ID":{"requireMention":false,"users":["USER_ID_1","USER_ID_2"]}}' \ --json # Restart to apply docker restart $INSTANCE ``` ### Verify Discord is connected ```bash docker exec $INSTANCE node /app/openclaw.mjs channels status --probe ``` **Success:** Output includes `Discord default: enabled, configured, running, ... works` Confirm users resolved: ```bash docker logs --tail 10 $INSTANCE ``` Look for: `[discord] channel users resolved: USER_ID_1→USER_ID_1` > **Pitfall — guilds config fails with "expected record, received array":** Always set the full `guilds` object at once. Setting individual guild keys fails: > ```bash > # WRONG > docker exec $INSTANCE node /app/openclaw.mjs config set \ > 'channels.discord.guilds.SERVER_ID' '{"requireMention":false}' --json > > # CORRECT > docker exec $INSTANCE node /app/openclaw.mjs config set \ > channels.discord.guilds '{"SERVER_ID":{"requireMention":false,"users":["UID"]}}' --json > ``` > **Pitfall — adding users later:** `config set guilds` replaces the entire object. Always include ALL existing user IDs when adding new ones. --- ## Optional: Gmail Integration **Skip this section if you do not need Gmail.** The rest of the setup works without it. See `references/gmail-setup.md` for the complete guide (uses Himalaya — the only reliable option for attachment download). The key insight: OAuth browser auth does NOT work inside Docker because the callback URL points to localhost inside the container, which the host browser cannot reach. The solution is to authenticate on the host Mac first, then copy tokens into the container. --- ## Optional: Google Drive Integration **Skip this section if you do not need Google Drive.** Google Drive uses gog (gogcli) — independent of the Gmail/Himalaya setup. You can set up Drive without setting up Gmail. See `references/google-drive-setup.md` for the complete guide. --- ## Maintenance Reference ### Daily operations ```bash # Stop the container docker stop $INSTANCE # Start the container docker start $INSTANCE # View logs docker logs --tail 50 $INSTANCE # Monitor resource usage docker stats --no-stream $INSTANCE ``` ### Update OpenClaw to a new version ```bash docker pull ghcr.io/openclaw/openclaw:latest docker stop $INSTANCE docker rm $INSTANCE # Re-run the same launch command from Step 3 # Named volumes retain all config, auth, and workspace data docker run -d \ --name $INSTANCE \ --restart unless-stopped \ -p $HOST_PORT:18789 \ -m 2048m \ --cpus=2 \ --cap-drop=ALL \ --cap-add=NET_BIND_SERVICE \ --security-opt no-new-privileges \ -v ${INSTANCE}-data:/app/data \ -v ${INSTANCE}-home:/home/node \ -e NODE_OPTIONS="--max-old-space-size=1024" \ ghcr.io/openclaw/openclaw:latest ``` ### Transfer files ```bash # Host to container docker cp /path/to/local/file.txt $INSTANCE:/home/node/.openclaw/workspace/ # Container to host docker cp $INSTANCE:/home/node/.openclaw/workspace/file.txt ~/Desktop/ # Backup entire .openclaw directory docker exec $INSTANCE tar -czf - -C /home/node .openclaw \ > ~/Desktop/${INSTANCE}-backup.tar.gz # Restore from backup cat ~/Desktop/${INSTANCE}-backup.tar.gz | \ docker exec -i $INSTANCE tar -xzf - -C /home/node ``` ### Completely remove everything ```bash docker rm -f $INSTANCE docker volume rm ${INSTANCE}-data ${INSTANCE}-home ``` **Warning:** This permanently deletes all config, auth, and workspace data. Backup first. --- ## Troubleshooting | Symptom | Cause | Fix | |---------|-------|-----| | `pull access denied for openclaw/openclaw` | Wrong image registry | Use `ghcr.io/openclaw/openclaw:latest` | | Container keeps restarting | OOM crash | Use `-m 2048m` + `-e NODE_OPTIONS="--max-old-space-size=1024"` | | `curl 127.0.0.1:$HOST_PORT` returns 000 or connection refused | Gateway on loopback | Set `gateway.bind lan` + `allowedOrigins`, restart | | Container crash-loops after setting LAN bind | Missing `allowedOrigins` | Set `gateway.controlUi.allowedOrigins`, restart | | `exec: "openclaw": executable file not found` | No global CLI binary | Use `node /app/openclaw.mjs` | | Dashboard shows "Pairing required" | Browser not approved | `devices list` then `devices approve <ID>` | | `config get gateway.auth.token` returns `__OPENCLAW_REDACTED__` | CLI redacts secrets | `cat /home/node/.openclaw/openclaw.json` | | Discord slash commands say "not authorized" | Missing `applications.commands` scope or user not in allowlist | Re-authorize bot; check `guilds` config | | Data gone after container recreation | Data on ephemeral overlay | Mount `/home/node` as named volume (the launch command above already does this) | For full pitfall details, see `references/pitfalls.md`. --- ## Container Reference | Setting | Value | |---------|-------| | Container name | `$INSTANCE` | | Image | `ghcr.io/openclaw/openclaw:latest` | | Host port | `19002` | | Container port | `18789` | | Dashboard URL | http://127.0.0.1:$HOST_PORT/ | | Memory limit | 2048 MB | | CPU limit | 1 core | | Node.js heap | 1024 MB | | Restart policy | `unless-stopped` | | CLI prefix inside container | `node /app/openclaw.mjs` | | Volume | Mounted at | Contains | |--------|-----------|----------| | `${INSTANCE}-home` | `/home/node` | Config, auth, workspace | | `${INSTANCE}-data` | `/app/data` | App-level data | --- ## Do You Need to Be at Your Mac? **Short answer: Yes for initial setup. No for ongoing use.** ### Why initial setup requires your Mac Three steps require direct Mac access (physical or SSH with port forwarding): | Step | Why Mac access is needed | |------|--------------------------| | **Step 2: Claude setup token** | `claude setup-token` opens a browser auth flow on `localhost`. Cannot be done remotely without a browser on the Mac. Skip if using a raw API key — that can be set from anywhere. | | **Step 4: Browser pairing** | The OpenClaw dashboard runs at `http://127.0.0.1:$HOST_PORT/` — only reachable from the Mac. You must open a browser there to pair. | | **Optional Gmail/Drive OAuth** | Google OAuth callback points to `localhost` on the Mac. Must authenticate from a browser running on the Mac. | ### Remote setup is possible via SSH port forwarding If you SSH into your Mac from another machine, you can forward the container port to your local browser: ```bash # From your remote machine — forward Mac's port 19002 to your local 19002 ssh -L 19002:localhost:19002 your-mac.local # Then open http://127.0.0.1:19002/ in your local browser ``` This lets you complete the browser pairing step remotely. ### After setup is complete Once the container is running and paired, you do **not** need to be at your Mac. OpenClaw runs as a background service (`--restart unless-stopped`). You interact with it entirely through your configured channel (Discord, Telegram, etc.) — from your phone, any browser, anywhere. --- ## Configuration No persistent configuration required. All settings are chosen interactively in Step 0 and set as shell variables (`$INSTANCE`, `$HOST_PORT`). **Optional integrations require additional setup:** | Integration | Guide | Requires | |-------------|-------|---------| | Gmail (email + attachments) | `references/gmail-setup.md` | Gmail App Password | | Google Drive / Docs / Sheets / Calendar | `references/google-drive-setup.md` | Google Cloud OAuth credentials | **System dependencies:** | Dependency | Purpose | Check | |------------|---------|-------| | Docker Desktop | Container runtime | `docker --version` | | Python 3 | Auto-detect script in Step 0 | `python3 --version` | | Claude Code CLI (`claude`) | Generate setup token (Claude Max/Pro only) | `claude --version` |