Setup Guide April 16, 2026

OpenClaw Docker Setup Guide 2026: The Practical Version

Running OpenClaw in Docker sounds appealing — clean, portable, easy to update, easy to roll back. The reality is a bit more nuanced. This guide covers which image to use, how to handle the instability that comes with OpenClaw's fast release cadence, how to keep your config and memory persistent, and when Docker actually makes more sense than a native install.

Which Image to Use

The official image is at ghcr.io/openclaw/openclaw (GitHub Container Registry). The most widely used community mirror is alpine/openclaw on Docker Hub, which auto-mirrors from the official source.

Note: Despite the name, alpine/openclaw is currently built on Debian (not Alpine Linux) due to musl compatibility issues. The maintainer is working on a true Alpine build. Functionally it works the same — just don't be surprised by the base image.

Quick Start

git clone https://github.com/ozbillwang/openclaw-in-docker.git
cd openclaw-in-docker
export OPENCLAW_IMAGE="alpine/openclaw:latest"
docker pull alpine/openclaw:latest
./docker-setup.sh

Full official Docker docs: docs.openclaw.ai/install/docker

The Version Pinning Problem

OpenClaw releases fast — multiple versions per week sometimes. Not all of them are stable. The community has documented several versions that broke badly:

2026.4.14 — GPT-5.4 / openai-codex Cloudflare 403 bug, ACP lane congestion
2026.3.2 — Known broken in Docker
2026.2.26 — Known broken in Docker
2026.4.5 — CPU saturation plugin regression

Don't run :latest in production. Pin to a known-good version:

# Pin to a specific version tag
export OPENCLAW_IMAGE="alpine/openclaw:2026.4.12"
docker pull alpine/openclaw:2026.4.12

Currently stable recommendation: 2026.4.12 (pre-4.14 regression cluster). Wait for 4.15 stable before upgrading if you're running anything critical.

Persistent Config and Memory

The most common Docker mistake with OpenClaw: losing your workspace and config on container restart. Always mount volumes for the paths that matter:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v ~/.openclaw/workspace:/root/.openclaw/workspace \
  -v ~/.openclaw/openclaw.json:/root/.openclaw/openclaw.json \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  alpine/openclaw:2026.4.12

Key volumes to mount:

~/.openclaw/workspace — your memory, SOUL.md, AGENTS.md, everything
~/.openclaw/openclaw.json — API keys, provider config, channel config
~/.openclaw/logs — optional, useful for debugging

WSL2 Notes

If you're running Docker on Windows via WSL2 (the most common setup), a few things to know:

Port forwarding: Docker Desktop handles this automatically, but if you're using Docker Engine directly in WSL2, you may need to manually forward port 18789 for the gateway to be reachable from Windows.
Volume paths: Use WSL2 paths (/home/user/) not Windows paths (C:\Users\) when mounting volumes from within WSL2.
Systemd in WSL2: Docker itself doesn't need systemd, but if you're running OpenClaw both in Docker and natively (testing), make sure the native gateway isn't competing on port 18789.

Running OpenClaw With a Local LLM (Zero API Cost)

One of the best Docker use cases: running OpenClaw alongside Ollama in the same Docker network, with zero API costs. The pattern:

# docker-compose.yml
version: '3'
services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

  openclaw:
    image: alpine/openclaw:2026.4.12
    ports:
      - "18789:18789"
    volumes:
      - ./workspace:/root/.openclaw/workspace
      - ./openclaw.json:/root/.openclaw/openclaw.json
    environment:
      - OLLAMA_HOST=http://ollama:11434
    depends_on:
      - ollama

volumes:
  ollama_data:

In your openclaw.json, point the Ollama provider at http://ollama:11434 (the Docker service name) rather than localhost.

When Docker Makes Sense vs Native Install

Use Docker when	Use native install when
Running on a server/VPS (no desktop)	Running on your personal laptop/NUC
You want easy rollbacks between versions	You want simpler setup (npm install is 1 command)
Running multiple OpenClaw instances	You need full system access (exec tool, file access)
Part of a larger Docker Compose stack	First-time setup — native is easier to debug
CI/CD or ephemeral environments	Raspberry Pi / ARM (native has better support)

Updating Safely

# Test the new version before switching
docker pull alpine/openclaw:2026.4.15
docker run --rm -it alpine/openclaw:2026.4.15 openclaw --version

# If it looks good, swap your running container
docker stop openclaw
docker rm openclaw
# re-run with new version tag

Always check the release notes before pulling a new version. The OpenClaw GitHub releases page and this blog are the two fastest places to learn about breaking changes before they hit your setup.

Want a Docker-based OpenClaw setup that actually works?

ClawReady can set up a properly configured Docker deployment — pinned versions, persistent volumes, Ollama integration if you want it, and channel config so your agent talks to you on Telegram or Discord from day one.

Book a Free Call →