How to Run OpenClaw in Docker: Complete Setup Guide (2026)

Why Should You Run OpenClaw in Docker?

Running OpenClaw in Docker gives you dependency isolation, consistent environments across operating systems, persistent storage, security boundaries with non-root execution, easy updates, and production-ready health checks and logging.

• Dependency isolation — all 70+ dependencies managed automatically
• Consistent environment — same setup on Ubuntu, macOS, or Windows
• Persistent storage — configuration and workspace survive container restarts
• Security boundaries — the agent runs as a non-root user with limited host access
• Easy updates — pull new images without reinstalling anything
• Production-ready — health checks, logging, and monitoring built in

What Do You Need Before Starting?

You need Docker Desktop or Engine (latest stable), Docker Compose v2+, at least 2 GB RAM (4 GB recommended), 10 GB disk space, Git, Bash v4+, and at least one AI provider API key.

Verify your setup:

docker --version
docker compose version
git --version

VPS Sizing by Use Case

How Do You Clone the OpenClaw Repository?

Clone the official OpenClaw GitHub repository and navigate into the project directory — this gives you the Docker Compose configuration, setup scripts, and all required files.

git clone https://github.com/openclaw/openclaw.git
cd openclaw

How Do You Run the OpenClaw Docker Setup Script?

The setup script builds the Docker image, runs an interactive onboarding wizard, prompts for your API key, generates authentication tokens, creates configuration directories, and starts the gateway via Docker Compose.

chmod +x docker-setup.sh
./docker-setup.sh

Using a Pre-Built Image (Faster)

Skip the local build by specifying a remote image:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

Pre-built images are available from GitHub Container Registry with tags: latest (most recent stable release), main (latest from main branch), and version-specific (e.g., 2026.2.26).

How Do You Verify OpenClaw Docker Is Running?

Run docker compose ps to confirm the gateway container is running, then check health endpoints at localhost:18789 for liveness and readiness without authentication.

docker compose ps

You should see openclaw-openclaw-gateway-1 running. Check the logs:

docker compose logs -f openclaw-gateway

Health Checks

# Liveness check
curl -fsS http://127.0.0.1:18789/healthz

# Readiness check
curl -fsS http://127.0.0.1:18789/readyz

How Do You Access the OpenClaw Web Dashboard?

Navigate to http://127.0.0.1:18789 in your browser to access OpenClaw's web-based control panel for chatting with your agent, configuring channels, and managing skills.

If you see a pairing or authentication prompt, retrieve your dashboard link:

docker compose run --rm openclaw-cli dashboard --no-open

If device approval is needed:

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

How Do You Connect WhatsApp, Telegram, Discord, and Slack?

Each messaging channel connects through CLI commands after the gateway is running — WhatsApp via QR code scan, Telegram via BotFather token, and Discord and Slack via bot tokens with pairing approval.

WhatsApp (QR Code)

docker compose run --rm openclaw-cli channels login

Scan the QR code with your WhatsApp app to connect.

Telegram

1. Create a bot with @BotFather on Telegram
2. Copy the bot token
3. Add the channel:

docker compose run --rm openclaw-cli channels add \
  --channel telegram \
  --token <YOUR_BOT_TOKEN>

4. Send a message to your bot, then approve the pairing:

docker compose run --rm openclaw-cli pairing approve telegram <CODE>

Discord

docker compose run --rm openclaw-cli channels add \
  --channel discord \
  --token <DISCORD_BOT_TOKEN>

Slack

docker compose run --rm openclaw-cli channels add \
  --channel slack \
  --token <SLACK_BOT_TOKEN>

What Environment Variables Does OpenClaw Docker Support?

OpenClaw Docker supports environment variables for image selection, API keys (Anthropic, OpenAI, Google, Groq), gateway tokens, extra apt packages, bind mounts, sandbox mode, and network binding configuration.

How Does OpenClaw Docker Handle Storage and Persistence?

Docker Compose bind-mounts two critical directories — ~/.openclaw/ for configuration and agent state, and ~/.openclaw/workspace/ for agent-accessible files — both persisting across container restarts and rebuilds.

How Do You Update OpenClaw Docker?

Update by pulling the latest code and images, then restarting — your configuration and workspace persist in the mounted volumes.

cd ~/openclaw
git pull
docker compose pull
docker compose up -d

How Do You Troubleshoot Common OpenClaw Docker Issues?

The most common Docker issues are out-of-memory crashes (exit code 137), permission errors from UID mismatch, gateway binding misconfigurations, and stale pairing tokens — each with straightforward fixes.

Container Won't Start (Exit Code 137)

Cause: Out of memory. The image build requires at least 2 GB RAM.

Fix: Increase Docker memory allocation in Docker Desktop > Settings > Resources > Memory.

Permission Errors

Cause: OpenClaw runs as node user (UID 1000), not root. Host-mounted directories may have wrong ownership.

sudo chown -R 1000:1000 ~/.openclaw

Gateway Not Accessible

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose up -d

Dashboard Pairing Errors

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices approve <requestId>

Missing Sandbox Image

./scripts/sandbox-setup.sh

Frequently Asked Questions

Can I run OpenClaw Docker on a Raspberry Pi?

OpenClaw requires at least 2 GB RAM and the Docker image is built for amd64 and arm64. A Raspberry Pi 4 with 4 GB RAM can run it, though performance will be limited.

Do I need Docker Desktop or can I use Docker Engine?

Either works. Docker Desktop provides a GUI and is easier on macOS/Windows. Docker Engine (CLI-only) is sufficient for Linux servers.

Can I use multiple AI providers simultaneously?

Yes. Set multiple API key environment variables and configure which model each agent uses in your openclaw.json.

How do I back up my OpenClaw data?

Back up the ~/.openclaw/ directory. This contains all configuration, API keys, agent state, session history, and workspace files.

Is the Docker image updated automatically?

No. You need to manually pull updates with docker compose pull && docker compose up -d. Consider setting up a cron job or Watchtower for automatic updates.

Can I run multiple OpenClaw instances on one server?

Yes, but each instance needs unique port mappings and separate configuration directories. Adjust the docker-compose.yml ports and volume mounts accordingly.