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?
answer
- the container is disposable, the state is not
- ghcr.io first, Docker Hub mirror
- gateway service and cli service
- the entrypoint repairs before it starts
basics
~20 sThe 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 sThe 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 linesexport 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 --jsongo deeper
Recall that the official image is ghcr.io/openclaw/openclaw and that config and workspace live on host mounts, not in the container.
Explain the two Compose services, the three mounts and what each holds, and how the entrypoint runs Doctor on upgrade.
Plan pinned tags, backups taken before upgrades, and recovery from a refused migration without deleting state.
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.