Peter Steinberger
6.4 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| Shared Docker VM runtime steps for long-lived OpenClaw Gateway hosts |
|
Docker VM runtime |
Shared runtime steps for VM-based Docker installs such as GCP, Hetzner, and similar VPS providers.
Bake required binaries into the image
Installing binaries inside a running container is a trap: anything installed at runtime is lost on restart. Bake every external binary a skill needs into the image at build time.
The examples below cover three binaries only, alphabetically:
gog(fromgogcli) for Gmail accessgoplacesfor Google Placeswaclifor WhatsApp
These are examples, not a complete list. Docker Compose builds the repo-root
Dockerfile, so extend that file rather than creating a standalone example or
replacing its contents. The repository Dockerfile has required
workspace-deps, build, runtime-assets, and final runtime stages. Its manifest
extraction covers the packages/* and selected extensions/* workspaces before
pnpm install --frozen-lockfile.
For Debian packages, prefer the existing build argument:
export OPENCLAW_IMAGE_APT_PACKAGES="socat"
For downloaded release binaries such as gog, goplaces, or wacli, add the
download and install commands to the repo-root Dockerfile final runtime stage,
after its package-install blocks and before USER node. Preserve the existing
non-root uid 1000 setup, tini entrypoint, health check, and openclaw symlink.
Then rebuild and restart the containers.
Build and launch
docker compose build
docker compose up -d openclaw-gateway
If the build fails with Killed or exit code 137 during pnpm install --frozen-lockfile, the VM is out of memory. Use a larger machine class before retrying.
Verify binaries:
docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli
Expected output:
/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli
Verify the gateway is up:
docker compose logs -f openclaw-gateway
curl -fsS http://127.0.0.1:18789/healthz
/healthz returning a 200 response confirms the gateway process is listening and healthy; the built-in image HEALTHCHECK polls the same endpoint.
What persists where
OpenClaw runs in Docker, but Docker is not the source of truth. All long-lived state must survive restarts, rebuilds, and reboots.
| Component | Location | Persistence mechanism | Notes |
|---|---|---|---|
| Gateway config | /home/node/.openclaw/ |
Host volume mount | Includes openclaw.json |
| Channel/provider creds | /home/node/.openclaw/credentials/ |
Host volume mount | Channel and provider credential material |
| Model auth profiles | /home/node/.openclaw/agents/ |
Host volume mount | agents/<agentId>/agent/auth-profiles.json (OAuth, API keys) |
| Legacy OAuth key file | /home/node/.config/openclaw/ |
Host volume mount | Read-only compat for pre-migration OAuth sidecars; openclaw doctor --fix migrates these into auth-profiles.json |
| Skill configs | /home/node/.openclaw/skills/ |
Host volume mount | Skill-level state |
| Agent workspace | /home/node/.openclaw/workspace/ |
Host volume mount | Code and agent artifacts |
| WhatsApp session | /home/node/.openclaw/ |
Host volume mount | Preserves QR login |
| Gmail keyring | /home/node/.openclaw/ |
Host volume + password | Requires GOG_KEYRING_PASSWORD |
| Plugin packages | /home/node/.openclaw/npm, /home/node/.openclaw/git |
Host volume mount | Downloadable plugin package roots |
| External binaries | /usr/local/bin/ |
Docker image | Must be baked at build time |
| Node runtime | Container filesystem | Docker image | Rebuilt every image build |
| OS packages | Container filesystem | Docker image | Do not install at runtime |
| Docker container | Ephemeral | Restartable | Safe to destroy |
Updates
To update OpenClaw on the VM:
git pull
docker compose build
docker compose up -d