Originally published on Remote OpenClaw.
OpenClaw's standard installation works great — run a one-liner, go through onboarding, and you are up in five minutes. But if you want isolation, reproducibility, and tighter security, Docker is the way to go.
Running OpenClaw in a container means your agent's runtime is completely separated from your host system. You get predictable deployments, easy rollbacks, and the peace of mind that comes with knowing your agent cannot accidentally touch files it should not. After the Claw Hub security incident earlier this year, containerized deployment went from "nice to have" to "strongly recommended" for anyone running third-party skills.
Marketplace
Free skills and AI personas for OpenClaw — browse the marketplace.
Join the Community
Join 1k+ OpenClaw operators sharing deployment guides, security configs, and workflow automations.
Why Should You Run OpenClaw in Docker?
There are four main reasons to containerize your OpenClaw deployment:
- Isolation — Your agent runs in its own filesystem, network, and process space. A misbehaving skill cannot corrupt your host system.
- Security — Containers limit what the agent can access. You explicitly define which directories, ports, and environment variables the container sees.
- Portability — A Docker image runs identically on your MacBook, a Linux VPS, or a Windows machine with WSL2.
- Reproducibility — Pin a specific image tag and your deployment is frozen in time.
How Does Docker Compare to Bare Metal Installation?
Factor
Bare Metal
Docker
Setup complexity
Lower — one curl command
Moderate — requires Docker knowledge
Isolation
None — full host access
Strong — sandboxed filesystem and network
Security
Depends on host config
Built-in — explicit resource exposure
Portability
OS-dependent
Runs anywhere Docker runs
Multi-agent
Manual OPENCLAW_HOME config
One container per agent
Bottom line: Use bare metal for quick local experimentation. Use Docker for anything production-facing, multi-agent, or security-sensitive.
What Are the Prerequisites?
You need Docker installed on your machine. Mac users install Docker Desktop for Mac. Windows users install Docker Desktop with WSL2 backend. Linux users install Docker Engine and the Docker Compose plugin.
docker --version
docker compose version
How Do You Quick Start With Docker Pull and Run?
The fastest way to get OpenClaw running in Docker:
docker pull openclaw/openclaw:latest
docker run -d \
--name openclaw \
-p 18789:18789 \
-v openclaw-config:/root/.openclaw \
-e ANTHROPIC_API_KEY=your-api-key-here \
openclaw/openclaw:latest
This runs the container in detached mode, maps port 18789, creates a named Docker volume for persistent configuration, and passes your API key. Open http://localhost:18789 to access the dashboard.
Important: Replace your-api-key-here with your actual API key. Never commit Docker run commands containing real API keys to version control.
How Do You Set Up Docker Compose?
For anything beyond quick testing, use Docker Compose:
version: "3.8"
services:
openclaw:
image: openclaw/openclaw:latest
container_name: openclaw-agent
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ./config:/root/.openclaw
- ./memory:/root/.openclaw/memory
- ./skills:/root/.openclaw/skills
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- OPENCLAW_HOME=/root/.openclaw
healthcheck:
test: ["CMD", "openclaw", "gateway", "status"]
interval: 30s
timeout: 10s
retries: 3
Create a .env file to store your API key, then start: docker compose up -d
How Do Volume Mounts Work for Persistent Data?
OpenClaw stores three categories of data you want to persist across container restarts:
Volume Mount
Container Path
Purpose
./config
/root/.openclaw
Main configuration — API keys, provider settings, Gateway config
./memory
/root/.openclaw/memory
Agent memory — soul.md and memory.md files
./skills
/root/.openclaw/skills
Managed skills — community or custom skills
Splitting these into separate host directories gives you granular control for backups, sharing skills across containers, and version-controlling config.
How Do You Configure Environment Variables?
OpenClaw supports all major providers. Pass your keys as environment variables:
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- GOOGLE_API_KEY=${GOOGLE_API_KEY}
- OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
Best practice: Store all secrets in a .env file and reference them with ${VARIABLE} syntax. Never hardcode API keys in docker-compose.yml.
Marketplace
Free skills and AI personas for OpenClaw — browse the marketplace.
How Do You Run Multiple Agents in Docker?
Running multiple OpenClaw agents is one of Docker's biggest strengths. Each agent gets its own container, configuration, memory, and optionally its own model provider.
Key points for multi-agent Docker setups:
- Each agent maps to a different host port (18789, 18790, etc.)
- Each agent has its own config and memory directories
- Both agents can share a read-only skills directory
- Agents can use different model providers (one uses Claude, the other uses GPT)
A modest VPS can comfortably run 5-10 agents since the heavy computation happens on the model provider's servers, not locally.
How Do You Troubleshoot Common Docker Issues?
Container exits immediately after starting
Check the logs with docker compose logs openclaw. Common causes: missing or invalid API key, port conflict, or invalid volume path with incorrect permissions.
Gateway status shows "not running"
The Gateway may need a few seconds to initialize. Wait 10-15 seconds after container start, then check again. Verify that the OPENCLAW_HOME environment variable matches the volume mount paths.
Permission denied errors on mounted volumes
On Linux, set appropriate permissions or use user: "1000:1000" in your Compose file to match the host UID/GID.
Memory or soul.md changes not persisting
Ensure your memory directory is mounted as a volume, not copied into the image. Changes inside the container should appear in your host directory immediately.
Frequently Asked Questions
Can I run the OpenClaw onboarding wizard inside Docker?
Yes. Run it interactively with docker exec -it openclaw-agent openclaw onboard --install-daemon. However, for Docker deployments it is often simpler to pass configuration through environment variables and volume-mount a pre-configured config.yaml.
Does OpenClaw's Docker image include Node.js?
Yes. The official image ships with Node.js 22.16+ pre-installed. You do not need to install Node.js separately.
Is the OpenClaw Docker image available for ARM (Apple Silicon, Raspberry Pi)?
Yes. The official image is published as a multi-architecture manifest supporting both amd64 and arm64. Docker automatically pulls the correct architecture.
What happens to my data if I delete the container?
If you used volume mounts (as shown in this guide), your data is safe on the host filesystem. Deleting the container only removes the running instance. Recreate it with docker compose up -d and it picks up right where it left off.
How do I view OpenClaw logs in Docker?
Use Docker's built-in logging: docker compose logs -f openclaw. For persistent logging, configure Docker's logging driver in your Compose file.
*Last updated: March 2026. Published by the Remote OpenClaw team at remoteopenclaw.com.*
Top comments (0)