OpenClaw Docker Setup: The Complete Guide to Containerized AI Agents (2026)

Why Run OpenClaw in Docker?

OpenClaw is designed as an agent runtime with real access to files, shell commands, APIs, browser automation, and messaging integrations. That level of capability makes containerization not just nice-to-have — it's the responsible way to run it.

Here's what Docker gives you that bare-metal doesn't: Filesystem isolation — without Docker the agent accesses everything, with Docker the agent sees only mounted volumes. Dependency management — Node.js, Chromium, ffmpeg are all packaged in the image instead of installed on your host. Rollback capability — just docker pull and restart instead of manual reinstall. Multi-instance support — isolated containers per instance instead of port conflicts and shared state. Reproducibility — identical everywhere instead of "works on my machine." Security boundary — container namespace isolation instead of root-level access risk.

Simon Willison, the creator of Datasette, wrote about his experience running OpenClaw in Docker specifically because he wasn't "brave enough" to run it directly on his Mac. That's a healthy instinct — and Docker makes it easy to act on.

• **Use Docker when:** You want isolation between the agent and your host OS
• You're deploying to a VPS or server (not your daily-driver laptop)
• You want reproducible, version-pinned deployments
• You're running multiple OpenClaw instances
• You want sandbox isolation for agent-spawned sub-processes
• **Skip Docker when:** You want the fastest possible development loop on your own machine
• You're on a Raspberry Pi with limited RAM (< 2 GB available)
• You just want to test OpenClaw for 10 minutes

Prerequisites and System Requirements

Before you start, make sure you have the following hardware and software.

Hardware requirements: Minimum 2 GB free RAM (recommended 4 GB+), minimum 5 GB disk (recommended 10 GB+), minimum 1 CPU core (recommended 2+), and outbound HTTPS network access.

The 2 GB RAM minimum is real — pnpm install during image builds will OOM-kill (exit code 137) on 1 GB hosts. If you're on a budget VPS, check our cheap VPS hosting guide for providers that actually work.

# Docker Engine (or Docker Desktop) + Compose v2
docker --version      # 20.10+ required
docker compose version  # v2.0+ required

# Git (to clone the repository)
git --version

# Install Docker Engine on Ubuntu/Debian
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (logout/login after)
sudo usermod -aG docker $USER
newgrp docker

Step-by-Step: OpenClaw Docker Setup

This section walks through the complete setup process from cloning the repository to accessing the web dashboard.

Step 1: Clone the Repository

This repository contains the Dockerfile, docker-compose.yml, and the docker-setup.sh script that orchestrates everything.

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

Step 2: Run the Setup Script

The fastest path to a running OpenClaw Docker instance:

This single command builds the Docker image locally (or pulls a remote image if OPENCLAW_IMAGE is set), runs the onboarding wizard for model provider, messaging channels, and bind mode, prints provider setup hints for API keys, starts the gateway via Docker Compose, and generates a gateway token and writes it to .env.

The onboarding wizard will ask you several questions. Here are the recommended answers for most users:

./docker-setup.sh

Onboarding mode: manual
Gateway type: Local gateway (this machine)
Model provider: [your choice — see model section below]
Messaging: Telegram (easiest to set up)
Tailscale: No (unless you specifically need it)

Step 3: Choose Your Model Provider

This decision shapes your cost, privacy, and performance. Here's a quick comparison: Anthropic (Claude) costs ~$15-30/mo typical with excellent quality and easy setup via API key. OpenAI (GPT-4o) costs ~$10-25/mo typical with very good quality and easy setup. Google Gemini has a free tier available with good quality and easy setup. Ollama (local) is $0/mo with fully private operation and medium setup difficulty. OpenRouter is pay-per-use with access to multiple models and easy setup.

For a deep dive, see our best AI model for OpenClaw guide.

If you want to run models locally alongside Docker, check our OpenClaw + Ollama guide.

Step 4: Verify the Deployment

After the script completes, check that your containers are running.

You should see output confirming the gateway is running, your model provider is configured, and messaging channels are connected.

# Check running containers
docker ps

# You should see two containers:
# openclaw-openclaw-gateway-1  (the agent runtime)
# openclaw-openclaw-cli-1      (management interface, stops after commands)

# Check gateway health
docker compose run --rm openclaw-cli status

Step 5: Access the Web Dashboard

OpenClaw's web UI runs on port 18789:

This prints a URL like http://127.0.0.1:18789/?token=abc123... — open it in your browser. The dashboard gives you a chat interface, session logs, skill management, resource monitoring, and device management.

If you see "disconnected (1008): pairing required", approve the browser device:

# Get the dashboard URL with auth token
docker compose run --rm openclaw-cli dashboard --no-open

# List pending device requests
docker compose run --rm openclaw-cli devices list

# Approve the pending request
docker compose run --rm openclaw-cli devices approve <requestId>

Connecting Telegram (Remote Control from Your Phone)

Telegram is the most popular way to interact with OpenClaw because it works from any device and has excellent bot support. Here's how to set it up.

Telegram Step 1: Create a Bot

Open Telegram and search for @BotFather. Send /newbot, follow the prompts to name your bot, and copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).

Telegram Step 2: Configure

When the setup wizard asks about messaging channels, select Telegram and paste your bot token. If you've already completed setup, you can add Telegram later:

docker compose run --rm openclaw-cli config set channels.telegram.token "YOUR_BOT_TOKEN"
docker compose restart openclaw-gateway

Telegram Step 3: Pair Your Account

Send any message to your bot on Telegram. OpenClaw will send you a pairing code. Approve it:

Now you can message your AI agent from your phone, tablet, or desktop Telegram client. For the full walkthrough, see our OpenClaw Telegram setup guide.

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

Understanding the Docker Compose Architecture

Let's break down what's actually running. Here's the key structure from docker-compose.yml:

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e",
        "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

  openclaw-cli:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    network_mode: "service:openclaw-gateway"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    depends_on:
      - openclaw-gateway

Key Design Decisions

**Two-container architecture:** The gateway runs the agent runtime continuously, while the CLI container is ephemeral — it starts, runs a command, and exits. They share the same network namespace via network_mode: "service:openclaw-gateway".

**Security hardening on CLI:** The CLI container drops NET_RAW and NET_ADMIN capabilities and enables no-new-privileges. This minimizes the attack surface if the CLI process is compromised.

**Health checks:** The gateway has a built-in health check hitting /healthz every 30 seconds with 5 retries. Docker will automatically restart the container if it becomes unhealthy.

**Persistent volumes:** Two host directories are mounted: ~/.openclaw/ for configuration, memory, API keys, and agent settings; and ~/openclaw/workspace/ for the agent's working directory (files it creates appear here).

Enabling Sandbox Isolation (Docker-in-Docker)

OpenClaw's sandbox feature runs agent-spawned tools in isolated containers — essentially Docker-in-Docker. This adds another security layer: even if an agent skill tries to do something dangerous, it's confined to a throwaway sandbox container.

This mounts docker.sock into the gateway container, builds the sandbox image (openclaw-sandbox:bookworm-slim), and configures agents.defaults.sandbox.mode in your gateway config.

If you're running rootless Docker, specify a custom Docker socket path.

# Enable sandbox during setup
export OPENCLAW_SANDBOX=1
./docker-setup.sh

# Custom Docker socket (rootless Docker)
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

How Sandbox Isolation Works

Each agent session can spawn sandbox containers for file operations and shell commands. The architecture is nested: the host machine contains the OpenClaw Gateway Container, which contains agent sessions, which spawn throwaway sandbox containers for exec and file operations. When the session ends, the sandbox container is destroyed. Nothing persists unless explicitly written to mounted volumes.

Using Pre-Built Images (Skip the Build)

Building from source takes 3-5 minutes depending on your hardware. If you want to skip that:

The script detects the non-default image name and runs docker pull instead of docker build.

Available image tags: "latest" is the latest stable release for production use. "main" is the latest build from the main branch for bleeding edge. "2026.2.26" format is for specific release versions for pinned deployments.

Images are published at GitHub Container Registry. The base image is node:22-bookworm.

Always use ghcr.io/openclaw/openclaw — not similarly named Docker Hub images, which may be unofficial.

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

Advanced Configuration

The setup script supports a wide range of environment variables for customization.

# Image configuration
OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"  # Use pre-built image
OPENCLAW_DOCKER_APT_PACKAGES="ripgrep fd-find"      # Extra apt packages

# Networking
OPENCLAW_GATEWAY_BIND="lan"          # lan, loopback, or 0.0.0.0
OPENCLAW_GATEWAY_PORT="18789"        # Gateway port
OPENCLAW_BRIDGE_PORT="18790"         # Bridge port

# Sandbox
OPENCLAW_SANDBOX="1"                 # Enable sandbox isolation
OPENCLAW_DOCKER_SOCKET="/var/run/docker.sock"  # Docker socket path

# Volumes
OPENCLAW_EXTRA_MOUNTS="$HOME/.ssh:/home/node/.ssh:ro"  # Additional mounts
OPENCLAW_HOME_VOLUME="openclaw-home"  # Named volume for /home/node

# Extensions
OPENCLAW_EXTENSIONS="diagnostics-otel matrix"  # Pre-install extensions

# Browser
OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS="0"  # Keep WebGL enabled
OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT="4"  # Limit Chromium processes

Extra Host Mounts

Need to give the agent access to additional directories?

This generates docker-compose.extra.yml automatically. When running Compose manually afterward, include it:

export OPENCLAW_EXTRA_MOUNTS="$HOME/projects:/home/node/projects:rw,$HOME/.codex:/home/node/.codex:ro"
./docker-setup.sh

docker compose -f docker-compose.yml -f docker-compose.extra.yml up -d

Persisting the Container Home

By default, /home/node inside the container is ephemeral (except for mounted volumes). To persist everything:

This creates a Docker named volume that survives container recreation — useful for agent-installed packages and tools.

export OPENCLAW_HOME_VOLUME="openclaw-home"
./docker-setup.sh

Installing Extra Packages

The agent runs as a non-root user (which is good for security). If you need system packages, you can install them at runtime or bake them into the image at build time:

# Get a root shell inside the running container
docker compose exec -u root openclaw-gateway bash

# Install what you need
apt-get update && apt-get install -y ripgrep fd-find jq

# Exit back to normal
exit

# Or bake them into the image at build time
export OPENCLAW_DOCKER_APT_PACKAGES="ripgrep fd-find jq"
./docker-setup.sh

Production Hardening Checklist

Running OpenClaw Docker on a public VPS? Here's your security checklist.

1. Bind to Loopback (Not LAN)

This prevents the gateway from being accessible on your public IP. Use a reverse proxy or Tailscale for remote access.

# In your .env or during setup
OPENCLAW_GATEWAY_BIND=loopback

2. Firewall the Docker Ports

Docker bypasses ufw by default via the DOCKER-USER iptables chain. You must explicitly block ports:

This is critical. See our security hardening guide for the full checklist.

# Block external access to OpenClaw ports
sudo iptables -I DOCKER-USER -p tcp --dport 18789 -j DROP
sudo iptables -I DOCKER-USER -p tcp --dport 18790 -j DROP

# Allow only loopback
sudo iptables -I DOCKER-USER -p tcp --dport 18789 -s 127.0.0.1 -j ACCEPT
sudo iptables -I DOCKER-USER -p tcp --dport 18790 -s 127.0.0.1 -j ACCEPT

3. Use Tailscale for Remote Access

Instead of exposing ports, use Tailscale for zero-trust access:

Then access OpenClaw at http://<tailscale-ip>:18789. See our Tailscale setup guide for details.

# Install Tailscale on your VPS
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

4. Rotate API Keys and Tokens

Regularly rotate your gateway token and update your .env file with the new token.

# Regenerate the gateway token
docker compose run --rm openclaw-cli gateway token --rotate

# Update your .env file with the new token

5. Resource Limits

Add resource constraints to your docker-compose.override.yml:

services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '0.5'
          memory: 1G

Daily Management Commands

Here's your cheat sheet for managing a running OpenClaw Docker instance:

# Start/stop/restart
docker compose up -d
docker compose down
docker compose restart openclaw-gateway

# View logs (follow mode)
docker compose logs -f openclaw-gateway

# Check status
docker compose run --rm openclaw-cli status

# Update to latest
docker compose pull
docker compose up -d

# Backup config
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# Shell access (as agent user)
docker compose exec openclaw-gateway bash

# Shell access (as root)
docker compose exec -u root openclaw-gateway bash

# Run CLI commands in CI/automation (no TTY)
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

ClawDock Shell Helpers

For even easier management, install the official shell helpers:

Then use clawdock-start, clawdock-stop, clawdock-dashboard, etc. Run clawdock-help for all available commands.

mkdir -p ~/.clawdock && curl -sL \
  https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh \
  -o ~/.clawdock/clawdock-helpers.sh

# Add to your shell
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc
source ~/.zshrc

Troubleshooting Common Issues

Here are the most common problems and their solutions.

Issue 1: Build Fails with Exit Code 137 (OOM)

Symptom: docker build exits with code 137 during pnpm install.

Cause: Not enough RAM. The build needs at least 2 GB free.

# Option A: Use a pre-built image (no build needed)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# Option B: Add swap space
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Then retry the build

Issue 2: "disconnected (1008): pairing required"

Symptom: Web dashboard shows pairing error.

# List device requests
docker compose exec openclaw-gateway \
  node dist/index.js devices list

# Approve the pending request
docker compose exec openclaw-gateway \
  node dist/index.js devices approve <requestId>

Issue 3: Permission Errors in Sandbox

Symptom: Agent can't read/write files in mounted volumes.

Cause: UID/GID mismatch between host and container.

# Check the container user's UID
docker compose exec openclaw-gateway id
# Typically: uid=1000(node) gid=1000(node)

# Fix ownership on host
sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace

Issue 4: Container Keeps Restarting

Symptom: Gateway container restarts in a loop.

Cause: Usually a config error or port conflict. Common causes include port 18789 already in use (change OPENCLAW_GATEWAY_PORT), invalid API key (reconfigure provider), or corrupted config (delete ~/.openclaw/config.yaml and re-onboard).

# Check the logs for the actual error
docker compose logs openclaw-gateway | tail -50

Issue 5: Can't Connect to Telegram/WhatsApp from Container

Symptom: Messaging channels don't connect.

# Verify outbound connectivity
docker compose exec openclaw-gateway curl -s https://api.telegram.org

# If DNS fails, add DNS to docker-compose.override.yml:
# services:
#   openclaw-gateway:
#     dns:
#       - 8.8.8.8
#       - 1.1.1.1

Issue 6: Custom Tools Not Found

Symptom: Agent can't find installed CLI tools.

Cause: OpenClaw runs commands with sh -lc (login shell), which sources /etc/profile and may reset PATH.

# Install tools system-wide (not in user-local paths)
docker compose exec -u root openclaw-gateway bash -c \
  "apt-get update && apt-get install -y <package>"

# Or add to PATH explicitly in the agent's shell profile
docker compose exec openclaw-gateway bash -c \
  "echo 'export PATH=/custom/path:\$PATH' >> ~/.profile"

Docker vs Native Install: Decision Matrix

Here is a comparison to help you decide between Docker and native installation. Setup speed: Docker takes 5-10 min, native takes 3-5 min. Isolation: Docker provides full container isolation, native provides none. Update process: Docker uses docker pull + restart, native uses npm update -g openclaw. Disk usage: Docker uses ~1.5 GB for the image, native uses ~500 MB. RAM overhead: Docker adds ~100 MB for container runtime, native adds none. Sandbox support: Docker uses Docker-in-Docker, native uses a Docker sidecar. Multi-instance: Docker makes it easy with different compose files, native is tricky with port management. Docker is best for VPS, servers, and homelabs. Native is best for developer workstations.

For a broader comparison of deployment options, see our complete deployment guide.

Conclusion

You've got OpenClaw running in Docker — now make it useful. Connect WhatsApp for messaging from your phone. Set up cron jobs and heartbeats for proactive automation. Install skills from ClawHub to extend capabilities. Reduce your API costs with smart model routing. Harden security for production deployments. Docker gives you the isolation to experiment boldly while keeping your host machine safe. The combination of containerized execution, sandbox isolation, and persistent workspace storage makes OpenClaw Docker the gold standard for anyone running AI agents on shared infrastructure.

Frequently asked questions