openclaw/scripts/clawdock

ClawDock

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

Command	Description
clawdock-start	Start the gateway
clawdock-stop	Stop the gateway
clawdock-restart	Restart the gateway
clawdock-status	Check container status
clawdock-logs	View live logs (follows output)

Container Access

Command	Description
clawdock-shell	Interactive shell inside the gateway container
clawdock-cli <command>	Run OpenClaw CLI commands
clawdock-exec <command>	Execute arbitrary commands in the container

Web UI & Devices

Command	Description
clawdock-dashboard	Open web UI in browser with authentication
clawdock-devices	List device pairing requests
clawdock-approve <id>	Approve a device pairing request

Setup & Configuration

Command	Description
clawdock-fix-token	Configure gateway authentication token (run once)

Maintenance

Command	Description
clawdock-update	Pull latest, rebuild image, and restart (one command)
clawdock-rebuild	Rebuild the Docker image only
clawdock-clean	Remove all containers and volumes (destructive!)

Utilities

Command	Description
clawdock-health	Run gateway health check
clawdock-token	Display the gateway authentication token
clawdock-cd	Jump to the OpenClaw project directory
clawdock-config	Open the OpenClaw config directory
clawdock-show-config	Print config files with redacted values
clawdock-workspace	Open the workspace directory
clawdock-help	Show all available commands with examples

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

File	Purpose
Dockerfile	Builds the openclaw:local image (Node 22, pnpm, non-root node user)
docker-compose.yml	Defines openclaw-gateway and openclaw-cli services, bind-mounts, ports
docker-setup.sh	First-time setup — builds image, creates .env from .env.example
.env.example	Template for <project>/.env with all supported vars and docs
docker-compose.extra.yml	Optional overrides — auto-loaded by ClawDock helpers if present

Config Files

File	Purpose	Examples
<project>/.env	Docker infra — image, ports, gateway token	OPENCLAW_GATEWAY_TOKEN, OPENCLAW_IMAGE, OPENCLAW_GATEWAY_PORT
~/.openclaw/.env	Secrets — API keys and bot tokens	OPENAI_API_KEY, ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN
~/.openclaw/openclaw.json	Behavior config — models, channels, policies	Model selection, WhatsApp allowlists, agent settings

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

Initial Setup

./docker-setup.sh (in the project root) 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

./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
• 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