OpenClaw stable
running with Docker
Docker Compose for the OpenClaw Gateway: health checks on /healthz, restart policies, reverse proxy + WebSocket, and lossless updates. No Docker basics — but production incidents that we see on VPS and SMB stacks.
direct answer
Is Docker the best way
to run OpenClaw?
Short answer: Docker is the best choice if you want reproducible deploys, container isolation, and a multi-service stack (Gateway + Ollama sidecar + proxy) — not automatically on every small VPS.
Nuance: bare metal with systemd is often easier to debug (journalctl) and lighter on RAM. Docker wins in SME automation, where the same compose runs in staging and production.
Docker Compose
OpenClaw Compose structure in production
Gateway container, volumes, environment variables, and networking — compact fragments, no 200-line dump.
Gateway container
One primary Gateway container per stack — not two Gateways on the same host without explicit port separation.
services: openclaw-gateway: image: your-registry/openclaw-gateway:pin-tag restart: unless-stopped env_file: .env
- Keep service name stable for logs and monitoring
- Pin image tag;
latestonly in dev - Gateway node must
readybecome before health check is green
Volumes & config
Persistent state resides in volumes — container rebuild without volume = “lose everything” feeling.
volumes: - ./data/openclaw:/home/openclaw/.openclaw - ./.env:/run/secrets/.env:ro
openclaw.json+ channel state in named volume or bind mount- Backup volume before image upgrade
- Read-only mount for secrets where possible
Environment variables
API keys via .env + env_file — not plaintext in compose in git.
environment: - GATEWAY_MODE=local - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- Same keys as bare-metal systemd service-user
- Ollama:
OLLAMA_HOSTto sidecar or host gateway - after
.env-change:docker compose up -d(recreate)
Restart policies & networking
Publish Gateway only on localhost; reverse proxy on 443 handles TLS + WebSocket.
restart: unless-stopped ports: - "127.0.0.1:18789:18789" networks: - openclaw_internal
unless stoppedfor production;on-failurewith max retries in dev- Separate internal network for sidecars (Ollama, Redis)
network_mode: hostonly if you understand port conflicts
Health & monitoring
Health checks and container logs
Short answer: unhealthy means that /healthz fails before the Gateway stable ready is — logs tell why.
docker compose ps
Expected: STATUS running, no unhealthy
If incorrect: unhealthy or Restarting → health check fails before Gateway ready
Next: docker compose logs -f --tail=100 openclaw-gateway
curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/healthz
Expected: HTTP 200
If incorrect: 000 or timeout → port mapping or Gateway bind
Next: openclaw gateway status (exec in container or host CLI)
docker inspect --format="{{.State.Health.Status}}" openclaw-gateway
Expected: healthy
If incorrect: unhealthy → check healthcheck CMD and start_period
Next: Adjust health check interval/timeout after cold start with plugins
docker compose logs -f --tail=80
Expected: ready in logs after start
If incorrect: stops at runtime.early → config/auth/plugin
Next: see problems
On hosts with systemd alongside Docker: correlate container timestamps with journalctl -u openclaw-gateway if your CLI also runs on the host. Cron/heartbeat in logs must remain visible after deploy.
Networking
Reverse proxy, SSL and WebSocket
Gateway on localhost; Nginx or Traefik on 443 with WebSocket upgrade to the OpenClaw Gateway.
Nginx
- →Upstream to
127.0.0.1:18789— hardcode non-container IP without network alias - →WebSocket:
proxy_http_version 1.1,Upgrade,Connection "upgrade" - →Health route optional to
/healthzfor external monitoring
Traefik
- →Labels on Gateway Service; TLS via ACME at entry point
- →WebSocket middleware/router on the same host as HTTP
- →Internal network: Traefik + Gateway on shared composite network
Exposure & firewall
- →Gateway not on
0.0.0.0without auth — firewall only 22/443 - →SSL termination on proxy; no self-signed to the public without monitoring
- →Increase WebSocket timeouts on long agent runs (do not overly aggressive proxy read timeout)
Hardening
OpenClaw Docker
safety
Short answer: Container isolation is a single layer — API keys, approvals, and browser automation risks remain.
- ✓ Container isolation: dedicated user in image, no privileged mode unless GPU passthrough is required
- ✓ Rootless Docker where possible — mapped UID must match volume ownership
-
✓
.envchmod 600; secrets not in image layers - ✓ Read-only mounts for config that agents are not allowed to overwrite
- ✓ Approvals + limited tools — Docker does not resolve prompt injection (safety)
- ✓ Browser automation in a separate sidecar or profile volume — not in the Gateway container cache
- Gateway publish:
127.0.0.1:gateonly .envnot in image; chmod 600 on host- Non-root user in Dockerfile
- Firewall + SSH keys; no Docker API on the web
- Full hardening: safety guide
Stability
Performance, RAM and updates
RAM & Ollama
Problem: Gateway + Ollama in a single small VPS (<4 GB) results in OOM (<code>Exit 137</code>) and restart loops.
Approach: Ollama as a sidecar with memory limit; or external API (Anthropic/OpenAI-compatible); monitor Docker stats.
GPU passthrough
Problem: Only needed for local inference — requires NVIDIA runtime / device mappings.
Approach: Compose deploy.resources.reservations.devices of documented runtime; without GPU: no CUDA image.
Updates
Problem: Image pull + recreate without volume backup = risk of state mismatch.
Approach: Pin tag → backup volume → docker compose pull → up -d → healthz + channel probe.
Zombie / double containers
Problem: Manual <code>docker run</code> next to compose = two Gateways, port conflict.
Approach: docker compose down before experiments; one compose project per host/production environment.
Incidents
Common Docker mistakes with OpenClaw
Volume cleared during “clean” deploy
Channel-state and ~/.openclaw gone — looks like a corrupted installation.
Cause: <code>docker compose down -v</code> in production without backup.
Fix: Backing up named volumes; down without -v unless intentionally reset.
Incorrect .env in container
Gateway unhealthy while host CLI is working — split-brain between mount and env_file.
Cause: Wrong path; old env in container cache after modification without recreate.
Fix: docker compose up -d --force-recreate after .env-fix.
Gateway unhealthy/healthz timeout
Healthcheck fails because Gateway never ready is or wrong gate in check-in.
Cause: Port in compose ≠ <code>gateway.port</code>; plugin bootstrap hang.
Fix: Logs first; curl healthz from host; only then start_period On.
WebSocket does not work behind a proxy
Channels disconnected; HTTP seems OK, realtime is not.
Cause: Nginx/Traefik without upgrade headers or incorrect path strip.
Fix: WebSocket route 1:1 to Gateway; test with openclaw channels status --probe.
Approvals are stalled
Container “healthy” but officer does nothing.
Cause: Pending approvals queue — not a Docker issue.
Fix: Clear/approve queue before restart; see runtime in problems.
Consideration
When Docker is not convenient
Short answer: with very limited RAM, purely local debugging, or if compose adds more overhead than a single systemd Gateway service.
- → Small VPS (<2 GB RAM) with Ollama + Gateway — bare metal or external API only
-
→
Local debugging: systemd +
openclaw logs --followfaster than compose rebuild - → Homelab iteration: nvm + user Gateway before pinning compose production
-
→
Incident forensics:
journalctlOn host sometimes clearer than just container logs
Short answer: No — OpenClaw also runs on bare metal via npm/systemd; Docker is a deployment choice for isolation and reproducible environments.
Cause of confusion: Many guides show compose-first; production can do both.
Advice: Docker in teams with compose CI/CD; systemd on a single VPS and simple management.
Short answer: Usually failed health check, OOM (Exit 137), or Gateway crash before ready.
Cause: too little RAM, wrong .env, port conflict, duplicate gateway.
Fix: docker compose logs -f → fix config → compose up -d; do not delete volumes immediately.
Short answer: Docker offers container isolation, no automatic security — permissions, .env, proxy authentication, and approvals remain required.
Cause: shared volumes and open gates ignore isolation.
Advice: safety + localhost bind + firewall.
Short answer: Yes — npm install -g openclaw + systemd user/service is common on Linux VPS.
Cause: same Gateway, different process model; config path ~/.openclaw/ directly.
Advice: Install for PATH/Node; Docker for multi-service stacks.
Short answer: Backup volume → pin new image tag → docker compose pull → up -d → verify /healthz.
Cause: Pull without recreate makes old container rotate.
Fix: rolling one node; monitor logs 5 min after deploy.
Short answer: Proxy misses HTTP/1.1 upgrade headers or routes to the wrong upstream port.
Cause: SSL termination without WS-config; timeout too short.
Fix: Nginx/Traefik WS-template; Gateway on fixed internal port; test channel probe.
Short answer: Health check to /healthz fails — Gateway not ready, wrong port, or start_period too short.
Cause: config/auth/API key; plugin hang; UNCLE kill.
Fix: logs → open claw doctor → .env + recreate; see Docker section on problems.
Deployment
OpenClaw Docker deployment
have it furnished?
Compose stack, health monitoring, reverse proxy + WebSocket, secure updates, and hardening audit — for SMB automation and VPS production. Send your current compose (without secrets) and health check output.