Run the OpenClaw Gateway in Docker with the maintained setup script
Some teams describe their automation helper as clawdbot, while the current official Docker documentation names the maintained gateway product OpenClaw. For a Docker install task, start from the OpenClaw repository, choose the documented image name, and decide the persistent host directories before the first setup run.
The OpenClaw Docker guide says Docker is optional and is mainly useful for an isolated Gateway environment. It lists Docker Engine or Docker Desktop plus Docker Compose v2 as prerequisites, and publishes prebuilt images at ghcr.io/openclaw/openclaw with a Docker Hub mirror at openclaw/openclaw.
Fresh install: set persistent paths before setup
On a new VM or workstation, define the state paths and image before running ./scripts/docker/setup.sh. Do not run setup once with defaults and only then decide where the state should live.
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker --version
docker compose version
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
export OPENCLAW_WORKSPACE_DIR="$HOME/.openclaw/workspace"
export OPENCLAW_AUTH_PROFILE_SECRET_DIR="$HOME/.openclaw-auth-profile-secrets"
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.shThe OpenClaw Docker VM runtime guide uses those host-side directories for long-lived state. Keep them in backups. The config directory contains Gateway state and SQLite data; the workspace directory contains agent work; the auth-profile secret directory is separate legacy recovery material. If your registry policy prefers Docker Hub, set OPENCLAW_IMAGE="openclaw/openclaw:latest" before the first setup run instead.
What setup creates
The setup flow builds or pulls the Gateway image, synchronizes .env, runs onboarding, records the Gateway token, and starts the service through Docker Compose. Keep provider keys, Gateway tokens, channel tokens, OAuth material, state directories, published ports, and extra mounts out of ad-hoc examples; they belong in the real deployment environment or secret store, not in a Dockerfile.
Open the UI and check logs
After setup, verify the container and collect the dashboard URL or health status with ordinary Compose commands:
docker compose ps
docker compose logs --tail=100 openclaw-gateway
curl -fsS http://127.0.0.1:18789/healthz
docker compose run --rm openclaw-cli dashboard --no-openThe documented local Control UI is on http://127.0.0.1:18789/ unless you changed OPENCLAW_GATEWAY_PORT. If the UI asks for a token, use the token written during setup rather than exposing the Gateway port directly to the public Internet.
Adding the browser image to an existing install
For a brand-new installation that needs Chromium inside the Gateway container, set OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest-browser" before the first setup run. For an existing Compose installation, do not rerun setup from an empty shell just to switch images; the Docker guide warns that setup rewrites .env from the current shell and defaults.
Instead, edit the existing deployment’s .env while preserving its current state paths, mounts, ports, token, provider settings, and overlays. Change only the image line to the browser variant, then recreate the Gateway with the same Compose files you already use:
# keep the same docker-compose.yml / override / extra files used by this install
docker compose pull openclaw-gateway openclaw-cli
docker compose up -d openclaw-gatewayIf your deployment normally uses overlays such as docker-compose.override.yml or docker-compose.extra.yml, include the same -f chain for pull and up. After startup, open the Browser panel and confirm that navigation and snapshots work from the Gateway-controlled browser.
Upgrade without losing state
Before a source update or image change, back up the current state directories and keep a copy of the existing .env. Verify that the next command still uses the same OPENCLAW_CONFIG_DIR, workspace directory, auth-profile secret directory, ports, mounts, Gateway token, and channel/provider settings. The VM runtime example is useful, but it is not permission to rerun setup from a blank shell with defaults.
git pull --ff-only
# run from the same configured environment as the existing install
OPENCLAW_SKIP_ONBOARDING=1 ./scripts/docker/setup.sh
docker compose run --rm openclaw-cli doctor --jsonRoutine image upgrades run startup-safe checks against the mounted state. If logs show an ownership, migration, or schema problem that requires repair, stop the Gateway first and run openclaw doctor --fix only against the same mounted state/config. Do not run a fixing doctor concurrently against a live Gateway database, and do not delete state, database, or lock files to force a start.