ClawDock <!-- omit in toc -->

Stop typing docker-compose commands. Just type clawdock-start.

Inspired by Simon Willison's Running OpenClaw in Docker.

• Quickstart
• Available Commands
  • Basic Operations
  • Container Access
  • Web UI & Devices
  • Setup & Configuration
  • Maintenance
  • Utilities
• Configuration & Secrets
  • Docker Files
  • Config Files
  • Initial Setup
  • How It Works in Docker
  • Env Precedence
• Common Workflows
  • Check Status and Logs
  • Set Up WhatsApp Bot
  • Troubleshooting Device Pairing
  • Fix Token Mismatch Issues
  • Permission Denied
• Requirements
• Development

Quickstart

Install:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Canonical docs page: https://docs.openclaw.ai/install/clawdock

If you previously installed ClawDock from scripts/shell-helpers/clawdock-helpers.sh, rerun the install command above. The old raw GitHub path has been removed.

See what you get:

clawdock-help

On first command, ClawDock auto-detects your OpenClaw directory:

• Checks common paths (~/openclaw, ~/workspace/openclaw, etc.)
• If found, asks you to confirm
• Saves to ~/.clawdock/config

First time setup:

clawdock-start

clawdock-fix-token

clawdock-dashboard

If you see "pairing required":

clawdock-devices

And approve the request for the specific device:

clawdock-approve <request-id>

Available Commands

Basic Operations

Container Access

Web UI & Devices

Setup & Configuration

Maintenance

Utilities

Configuration & Secrets

The Docker setup uses three config files on the host. The container never stores secrets — everything is bind-mounted from local files.

Docker Files

Config Files

Do NOT put API keys or bot tokens in openclaw.json. Use ~/.openclaw/.env for all secrets.

Initial Setup

./scripts/docker/setup.sh handles first-time Docker configuration:

• Builds the openclaw:local image from Dockerfile
• Creates <project>/.env from .env.example with a generated gateway token
• Sets up ~/.openclaw directories if they don't exist

./scripts/docker/setup.sh

After setup, add your API keys:

vim ~/.openclaw/.env

See .env.example for all supported keys.

The Dockerfile supports two optional build args:

• OPENCLAW_DOCKER_APT_PACKAGES — extra apt packages to install (e.g. ffmpeg)
• OPENCLAW_INSTALL_BROWSER=1 — pre-install Chromium for browser automation (adds ~300MB, but skips the 60-90s Playwright install on each container start)

How It Works in Docker

docker-compose.yml bind-mounts both config and workspace from the host:

volumes:
  - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
  - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace

This means:

• ~/.openclaw/.env is available inside the container at /home/node/.openclaw/.env — OpenClaw loads it automatically as the global env fallback
• ~/.openclaw/openclaw.json is available at /home/node/.openclaw/openclaw.json — the gateway watches it and hot-reloads most changes
• Downloadable plugin packages and install records live under the mounted OpenClaw home
• No need to add API keys to docker-compose.yml or configure anything inside the container
• Keys survive clawdock-update, clawdock-rebuild, and clawdock-clean because they live on the host

The project .env feeds Docker Compose directly (gateway token, image name, ports). The ~/.openclaw/.env feeds the OpenClaw process inside the container.

Example ~/.openclaw/.env

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABCDEF...

Example <project>/.env

OPENCLAW_CONFIG_DIR=/Users/you/.openclaw
OPENCLAW_WORKSPACE_DIR=/Users/you/.openclaw/workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=<generated-by-docker-setup>
OPENCLAW_IMAGE=openclaw:local

Env Precedence

OpenClaw loads env vars in this order (highest wins, never overrides existing):

1. Process environment — docker-compose.yml environment: block (gateway token, session keys)
2. .env in CWD — project root .env (Docker infra vars)
3. ~/.openclaw/.env — global secrets (API keys, bot tokens)
4. openclaw.json env block — inline vars, applied only if still missing
5. Shell env import — optional login-shell scrape (OPENCLAW_LOAD_SHELL_ENV=1)

Common Workflows

Update OpenClaw

Important: openclaw update does not work inside Docker. The container runs as a non-root user with a source-built image, so npm i -g fails with EACCES. Use clawdock-update instead — it pulls, rebuilds, and restarts from the host.

clawdock-update

This runs git pull → docker compose build → docker compose down/up in one step.

If you only want to rebuild without pulling:

clawdock-rebuild && clawdock-stop && clawdock-start

Check Status and Logs

Restart the gateway:

clawdock-restart

Check container status:

clawdock-status

View live logs:

clawdock-logs

Set Up WhatsApp Bot

Shell into the container:

clawdock-shell

Inside the container, login to WhatsApp:

openclaw channels login --channel whatsapp --verbose

Scan the QR code with WhatsApp on your phone.

Verify connection:

openclaw status

Troubleshooting Device Pairing

Check for pending pairing requests:

clawdock-devices

Copy the Request ID from the "Pending" table, then approve:

clawdock-approve <request-id>

Then refresh your browser.

Fix Token Mismatch Issues

If you see "gateway token mismatch" errors:

clawdock-fix-token

This will:

1. Read the token from your .env file
2. Configure it in the OpenClaw config
3. Restart the gateway
4. Verify the configuration

Permission Denied

Ensure Docker is running and you have permission:

docker ps

Requirements

• Docker and Docker Compose installed
• Bash or Zsh shell
• OpenClaw project (run scripts/docker/setup.sh)

Development

Test with fresh config (mimics first-time install):

unset CLAWDOCK_DIR && rm -f ~/.clawdock/config && source scripts/clawdock/clawdock-helpers.sh

Then run any command to trigger auto-detect:

clawdock-start