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.

✓ Compose & Gateway
✓ healthz & logs
✓ Nginx / Traefik WS
✓ Production updates

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.

Install · problems · safety

healthz
Monitoring
unless stopped
restart
127.0.0.1
bind
pin tag
Updates

Docker Compose

OpenClaw Compose structure in production

Gateway container, volumes, environment variables, and networking — compact fragments, no 200-line dump.

Compose

Gateway container

One primary Gateway container per stack — not two Gateways on the same host without explicit port separation.

compose.yaml fragment
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; latest only in dev
  • Gateway node must ready become before health check is green
Compose

Volumes & config

Persistent state resides in volumes — container rebuild without volume = “lose everything” feeling.

compose.yaml fragment
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
Compose

Environment variables

API keys via .env + env_file — not plaintext in compose in git.

compose.yaml fragment
environment: - GATEWAY_MODE=local - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  • Same keys as bare-metal systemd service-user
  • Ollama: OLLAMA_HOST to sidecar or host gateway
  • after .env-change: docker compose up -d (recreate)
Compose

Restart policies & networking

Publish Gateway only on localhost; reverse proxy on 443 handles TLS + WebSocket.

compose.yaml fragment
restart: unless-stopped ports: - "127.0.0.1:18789:18789" networks: - openclaw_internal
  • unless stopped for production; on-failure with max retries in dev
  • Separate internal network for sidecars (Ollama, Redis)
  • network_mode: host only 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.

terminal
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

terminal
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)

terminal
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

terminal
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 /healthz for 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.0 without 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
  • ✓ .env chmod 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
🔒 Production minimum
  • Gateway publish: 127.0.0.1:gate only
  • .env not 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

Volumes

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.

Config

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.

Health

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.

Proxy

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.

Runtime

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 --follow faster than compose rebuild
  • → Homelab iteration: nvm + user Gateway before pinning compose production
  • → Incident forensics: journalctl On host sometimes clearer than just container logs

FAQ

Docker &
OpenClaw FAQ

Short answer, cause, and fix — for AI overviews and production debugging.

Troubleshooting →

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.

✓ Gateway + healthz
✓ Nginx / Traefik WS
✓ Bespoke