In This Article
Introduction
Docker is the recommended way to run OpenClaw in production. It provides isolation, consistent environments, and easy updates. Here's what we're covering: Docker deployment from basic setup to production hardening: step-by-step commands, persistence configuration, Docker Compose for multi-container setups, and the operational practices that keep agents running reliably.
Whether you're running to a single VPS or orchestrating multiple agents, you'll find actionable steps. We'll cover the exact docker run commands, volume mounts, resource limits, health checks, and backup strategies that production deployments use.
Why Docker
Docker ensures OpenClaw runs the same way on your laptop, a VPS, or a Raspberry Pi. Dependencies are bundled. Updates are pull-and-restart. Shell execution Skills run in sandboxed containers by default in recent versions — Docker-on-Docker for extra isolation. No "works on my machine" — it works everywhere Docker runs.
Benefits. Reproducibility: same image, same behavior. Isolation: agent can't affect host. Portability: move between cloud providers easily. Updates: docker pull, docker restart. Resource limits: prevent runaway consumption.
Docker Setup: Step-by-Step
Pull the official OpenClaw image or build from the Dockerfile. Mount your config directory. Set environment variables for API keys (or use a secrets manager). Expose the necessary ports for your messaging integrations. The documentation provides a minimal docker run command to get started.
Step 1: Install Docker. docker.io or Docker Engine. On Ubuntu: apt install docker.io. On Mac: Docker Desktop. Verify: docker --version.
Step 2: Pull image. docker pull openclaw/openclaw:latest (or your registry). Or build: docker build -t openclaw . from repo.
Step 3: Create config directory. mkdir -p ./openclaw-config. Add config.yaml, memory files, .env for secrets. Structure: config/, memory/, .env.
Step 4: Run container. docker run -d --name openclaw -v $(pwd)/openclaw-config:/app/config -e OPENAI_API_KEY=sk-... openclaw/openclaw:latest. Adjust ports if needed (-p 3000:3000 for web UI).
Step 5: Verify. docker logs openclaw. Check for startup errors. Test your integration (Telegram, Slack, etc.).
Minimal run command. docker run -d --restart unless-stopped --name openclaw -v ./config:/app/config -e OPENAI_API_KEY=$OPENAI_API_KEY -p 3000:3000 openclaw/openclaw:latest
Data Persistence
OpenClaw's memory and state live in mounted volumes. Ensure your Docker setup persists the memory directory across container restarts. Back up this directory regularly — it contains your agent's context and history.
Volume mount. -v /host/path/config:/app/config. Config includes memory. Never use anonymous volumes for config — you'll lose data on container remove.
Backup strategy. Daily backup of config directory. tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ./config. Store off-host. Test restore. Memory is critical — losing it means losing agent context.
What to back up. config/, memory/, any custom Skills. .env has secrets — back up encrypted or exclude and document separately.
Docker Compose
Docker Compose simplifies multi-container setups. Run OpenClaw with Ollama in a separate container for local models. Add Redis for caching if needed. Compose makes it easy to bring the whole stack up with one command.
Basic compose. services: openclaw: image: openclaw/openclaw, volumes: [./config:/app/config], environment: [OPENAI_API_KEY=${OPENAI_API_KEY}], restart: unless-stopped. Add Ollama: image: ollama/ollama, volumes: [ollama:/root/.ollama], deploy: resources: limits: memory: 8G.
With Ollama. openclaw depends_on: ollama. openclaw env: OPENCLAW_LLM_PROVIDER=ollama, OPENCLAW_OLLAMA_HOST=http://ollama:11434. One command: docker compose up -d. Full local stack.
Networking. Containers on same network can communicate. ollama:11434 from openclaw. No port exposure needed for internal services.
Production Hardening
Use restart policies so the container recovers from crashes. Set resource limits to prevent runaway consumption. Run behind a reverse proxy (nginx, Caddy) for TLS. Consider health checks. OpenClaw Consult advises on production architecture.
Restart policy. --restart unless-stopped. Container restarts on crash. Survives host reboot.
Resource limits. deploy: resources: limits: cpus: '2', memory: 2G. Prevents one agent from consuming all host resources. Tune based on workload.
Reverse proxy. nginx or Caddy in front. TLS termination. Rate limiting. Don't expose OpenClaw directly to internet without auth.
Health checks. HEALTHCHECK in Dockerfile or compose. curl http://localhost:3000/health. Orchestrators (K8s, ECS) use this for restart decisions.
Secrets. Don't put API keys in compose file. Use Docker secrets, env files (not committed), or external secrets manager (Vault, AWS Secrets Manager).
Logging. docker logs or json-file driver. Consider centralized logging (Loki, CloudWatch) for production. Logs help debug "why did the agent do X?"
Implementation Checklist
- □ Install Docker. Verify version
- □ Create config directory structure. Add config.yaml, memory
- □ Set up .env for secrets. Never commit
- □ Run with volume mount. Verify persistence
- □ Configure restart policy
- □ Add resource limits
- □ Set up backup for config directory
- □ If using web UI: add reverse proxy, TLS
- □ Document run command for team
Common Pitfalls to Avoid
Pitfall 1: Losing data on restart. Must use volume mount for config. Anonymous volumes get removed with container. Always -v /host/path:/app/config.
Pitfall 2: No resource limits. Runaway Heartbeat or heavy Skill can consume all CPU/RAM. Set limits. Monitor.
Pitfall 3: Exposing without auth. If OpenClaw has web UI, don't expose to internet without authentication. Use reverse proxy with auth or VPN.
Frequently Asked Questions
Can I run OpenClaw and Ollama in the same container? Possible but not recommended. Separate containers: cleaner, easier to update independently, better resource isolation. Use Compose to run both.
What about Docker on Raspberry Pi? Yes. Use arm64 image if available. Ollama + OpenClaw on Pi 4 (4GB+) works for light workloads. Expect slower inference with local models.
How do I update OpenClaw? docker pull openclaw/openclaw:latest. docker stop openclaw. docker rm openclaw. docker run ... (same command). Or: docker compose pull && docker compose up -d. Backup config first.
What about Docker Swarm or Kubernetes? OpenClaw runs in K8s as a Deployment. Use ConfigMaps for config, Secrets for API keys. See our AWS/GCP/Azure guides for K8s getting it running.
Can I use Docker secrets? Yes. docker secret create openai_key .env.openai. Mount in container. Read from file in config. Keeps keys out of env.
How much disk for persistence? Config + memory: typically 50MB–500MB. Grows with conversation history. Plan for 1GB to be safe. Monitor.
Wrapping Up
Docker is the standard for OpenClaw production getting it running. Follow this guide for reliable, reproducible setups. OpenClaw Consult helps design and deploy Docker-based architectures — we've deployed for single-agent and multi-agent production environments.