skip to content

When you run OpenClaw from its official container image with Docker Compose, what has to live outside the container, and how do image upgrades work?

level: middleimportance: should knowfreq 7%

answer

  1. the container is disposable, the state is not
  2. ghcr.io first, Docker Hub mirror
  3. gateway service and cli service
  4. the entrypoint repairs before it starts

basics

~20 s

The state directory mounted at /home/node/.openclaw (config, SQLite auth and session stores, .env) and the workspace must live on the host. Upgrades pull a new ghcr.io/openclaw/openclaw tag; the entrypoint runs openclaw doctor --fix before the Gateway starts.

solid answer

~40 s

The official image is `ghcr.io/openclaw/openclaw` (mirrored as `openclaw/openclaw` on Docker Hub); `./scripts/docker/setup.sh` uses it when `OPENCLAW_IMAGE` names it, otherwise it builds `openclaw:local`. Compose runs two services, `openclaw-gateway` and `openclaw-cli`, and bind-mounts the host config directory to `/home/node/.openclaw` and the workspace to `/home/node/.openclaw/workspace`. That mount holds `openclaw.json`, the SQLite stores with auth profiles and sessions, and the `.env` with the generated Gateway token, so it is what survives a container replacement and what you back up. To upgrade, pull a new tag and recreate the Gateway: the entrypoint runs `openclaw doctor --fix --non-interactive` against the mounted state, migrating databases and keeping `.bak` copies, so rolling back means the old image **and** the matching state.

code

bash · 7 lines
bash
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.9.3"
./scripts/docker/setup.sh

# later: move to a newer pinned tag and recreate the Gateway
docker compose pull openclaw-gateway openclaw-cli
docker compose up -d openclaw-gateway
docker compose run --rm openclaw-cli doctor --json

go deeper

for a junior

Recall that the official image is ghcr.io/openclaw/openclaw and that config and workspace live on host mounts, not in the container.

for a middle

Explain the two Compose services, the three mounts and what each holds, and how the entrypoint runs Doctor on upgrade.

for a senior

Plan pinned tags, backups taken before upgrades, and recovery from a refused migration without deleting state.

for a principal

Decide when the container route earns its keep over a native install, given who maintains the host and how upgrades are rolled back.

## When the container route fits Docker is optional for OpenClaw. The docs recommend it for an isolated, throwaway Gateway environment or a host where you do not want a local Node install, such as a VPS or a home server that already runs containers. On your own development machine the normal install is simpler. Two things are easy to confuse: - Running the **Gateway** in a container is a hosting choice. - **Sandboxing** agent tools in Docker containers is a separate feature, off by default, and does not require the Gateway itself to be containerised. ## The image and the setup script - **Image:** `ghcr.io/openclaw/openclaw` is the primary registry; the same release is mirrored as `openclaw/openclaw` on Docker Hub. Avoid unofficial mirrors. - **Tags:** release tags such as `2026.9.3`, moving tags such as `latest` and `main`, and variants such as `slim` and `-browser` (Chromium baked in for the Gateway-controlled browser). Pin a release tag for a deployment you want to reproduce. - **Setup:** from the repository root, `./scripts/docker/setup.sh` builds `openclaw:local` (a local source build needs about 6 GB of RAM) unless `OPENCLAW_IMAGE` names a pre-built image. It then runs onboarding, prompting for provider API keys, generating a Gateway token into `.env`, and starting the stack with Docker Compose. - **Services:** `openclaw-gateway` is the long-running Gateway; `openclaw-cli` shares its network namespace, so `docker compose run --rm openclaw-cli ...` runs CLI commands against it. The setup script defaults `OPENCLAW_GATEWAY_BIND` to `lan` so the published port `18789` is reachable from the host's browser and CLI, and the Control UI asks for the token from `.env`. Whether that port should be reachable beyond the host is a hardening question for the Gateway's exposure settings, not something the image decides for you. ## What must live outside the container Compose bind-mounts three host paths: | Host variable | Container path | Holds | | --- | --- | --- | | `OPENCLAW_CONFIG_DIR` | `/home/node/.openclaw` | `openclaw.json`, SQLite state and agent auth stores, sessions, `.env` | | `OPENCLAW_WORKSPACE_DIR` | `/home/node/.openclaw/workspace` | The agent workspace files | | `OPENCLAW_AUTH_PROFILE_SECRET_DIR` | `/home/node/.config/openclaw` | The key for legacy encrypted OAuth sidecars | Everything else in the container is replaceable. Treat the config directory as credentials: current OAuth access and refresh tokens sit in plaintext SQLite rows there, and the separate key mount does not encrypt them. ## How an upgrade runs 1. Change or pull the image tag, then recreate the Gateway with the same Compose files and overlays. 2. On start, the image entrypoint runs `openclaw doctor --fix --non-interactive` under exclusive ownership of the mounted state, before the Gateway starts. Routine upgrades need no separate Doctor pass. 3. Doctor applies schema migrations and first saves verified SQLite copies named `<database>.pre-startup-migration-<id>.bak` beside the originals. 4. If state cannot be migrated safely, startup exits with code `78` and keeps the source files, claim and backups for recovery. Do not delete state or lock files to get past it. A rollback therefore means the old image together with the state that matches it. A newer schema left in place under an old image is not a rollback. ## Health checks for an unattended host The Gateway serves unauthenticated probe endpoints on its port: `/healthz` for liveness, `/startupz` for startup and traffic admission, and `/readyz` for deeper, channel-aware readiness. The image's built-in `HEALTHCHECK` pings `/healthz`, so repeated failures mark the container unhealthy and let an orchestrator restart it. Use `/startupz` as a readiness probe when one failed channel account should not take the whole Gateway and Control UI out of service, and `/readyz` only for monitoring that should treat hard channel failures as not ready. After any upgrade, `docker compose run --rm openclaw-cli doctor --json` gives a read-only preflight against the same mounted state. ## Mistakes worth naming - Keeping state in the container's writable layer, then losing auth profiles and channel logins at the first `docker compose up` with a new image. - Re-running `setup.sh` from an empty shell to change one setting: it rewrites `.env` from the current shell and defaults. - Replacing the entrypoint and skipping Doctor, so the Gateway starts on unmigrated state. - Assuming the Gateway container is the tool sandbox. It isolates the Gateway's install, not what the agent's tools may do.

  • The upgraded Gateway container keeps restarting after a state migration failure. What do you do?
    Keep the mounted state volume. Run the same image once with `openclaw doctor --fix` as the container command against the same mounts, for example `docker run --rm -v <state>:/home/node/.openclaw <image> openclaw doctor --fix`, then restart the Gateway with its default command. Never delete state or lock files to silence the exit code 78.
  • How do you reach a model server such as Ollama running on the Docker host?
    Inside the container, `127.0.0.1` is the container itself. Use `host.docker.internal` (for Ollama, `http://host.docker.internal:11434`), which the bundled `docker-compose.yml` maps to the host on Linux Docker Engine, and make the host service listen on an address Docker can reach.

  • The container keeps its own state, so no host mount is needed.
  • Running the Gateway in Docker sandboxes the agent's tools.
  • After an image upgrade you must rerun onboarding inside the container.
  • Rolling back is just starting the previous image on the migrated state.
  • Re-running setup.sh is a safe way to change one setting in .env.