OpenClaw Docker Complete Guide: Containerize Your AI Agent in 2026

Why Run OpenClaw in Docker?

The OpenClaw documentation makes Docker optional, but for most users, it's actually the smartest choice. Here's why:

**Isolation** means OpenClaw's dependencies don't clash with your system. Node.js versions, Python packages, system libraries—everything stays contained. Upgrade your host OS without breaking OpenClaw.

**Reproducibility** is built in. The same image runs everywhere Docker does. What works on your development machine works on your server.

**Security** improves significantly. Docker lets you run OpenClaw with restricted permissions, isolated networking, and temporary filesystem layers for sensitive operations.

**Portability** matters. Move your OpenClaw instance from a Raspberry Pi to a cloud VPS by copying a few files.

The trade-off is slightly higher resource usage (Docker's overhead) and one extra layer of abstraction to debug. For most self-hosters in 2026, these trade-offs are worth it.

Prerequisites

Before you begin, ensure your system meets these requirements:

RAM: 2 GB minimum / 4+ GB recommended. Disk: 5 GB free minimum / 20+ GB recommended. Docker: Docker Engine minimum / Docker Desktop recommended. Docker Compose: v2 minimum / Latest recommended. OS: Ubuntu 22.04+, Debian 12+, macOS 12+ minimum / Latest stable recommended.

Verify Docker is installed:

If either command fails, install Docker from docker.com or use your system's package manager.

docker --version
docker compose version

Quick Start: Five Minutes to Running

The fastest way to get OpenClaw running in Docker uses the official setup script:

The script performs these steps automatically:

When it completes, access the Control UI at `http://127.0.0.1:18789`. Paste your token to authenticate.

**Finding Your Token Later:** Misplaced the token? Retrieve it:

This prints a fresh dashboard URL with an embedded token.

• Builds the OpenClaw image (or pulls a pre-built one)
• Launches the onboarding wizard
• Starts the gateway via Docker Compose
• Generates a gateway token
• Writes configuration to `.env`

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Run the Docker setup script
./docker-setup.sh

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

Using Pre-Built Images (Skip the Build)

Building from source takes 5-15 minutes depending on your hardware. Use a pre-built image instead:

Available image tags: `latest` — Most recent stable release. `main` — Latest build from main branch. `2026.2.26` — Specific release version.

The script detects `OPENCLAW_IMAGE` and runs `docker pull` instead of `docker build`. Everything else works identically.

**Pulling Images Manually:**

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

docker pull ghcr.io/openclaw/openclaw:latest
docker images ghcr.io/openclaw/openclaw

Docker Compose Configuration Deep Dive

Understanding the compose configuration helps you customize your deployment.

**Default docker-compose.yml Structure:**

Key points:

**Customizing with Environment Variables:** The setup script generates a `.env` file. Common customizations:

Rerun `./docker-setup.sh` after changing these variables.

• **Ports**: The gateway exposes port 18789. Change the left number to remap (e.g., `8080:18789` for `http://localhost:8080`).
• **Volumes**: Config and workspace persist on your host. These survive container restarts.
• **Network mode**: CLI uses the gateway's network namespace, allowing CLI commands to reach the gateway over `127.0.0.1`.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - ./config:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace
    environment:
      - OPENCLAW_GATEWAY_BIND=lan
    restart: unless-stopped

  openclaw-cli:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    container_name: openclaw-cli
    network_mode: service:openclaw-gateway
    volumes:
      - ./config:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace
    profiles:
      - cli

# Use a specific image version
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.2.26

# Change the gateway bind address
OPENCLAW_GATEWAY_BIND=loopback

# Persist the entire home directory
OPENCLAW_HOME_VOLUME=openclaw_home

# Add extra host mounts
OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro"

# Install system packages in the image
OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"

Volume Management and Persistence

Understanding what persists and what doesn't prevents data loss.

**What's Persisted:**

**What's Ephemeral:**

**Backing Up Your Data:**

**Restoring from Backup:**

• **Configuration**: `~/.openclaw/` contains your config, sessions, and agent data
• **Workspace**: `~/.openclaw/workspace/` holds files your agents work with
• **Named volumes**: If you set `OPENCLAW_HOME_VOLUME`, the entire `/home/node` persists
• **Container filesystem**: Any changes inside the container that aren't mounted
• **Sandbox tmpfs**: When sandboxing is enabled, `/tmp`, `/var/tmp`, and `/run` use temporary storage
• **Logs inside container**: Application logs in `/tmp/openclaw/` disappear on restart

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

# Or use the named volume
docker run --rm -v openclaw_home:/data -v $(pwd):/backup alpine \
  tar czf /backup/openclaw-volume-backup.tar.gz -C /data .

# Stop the container
docker compose down

# Extract to the right locations
tar -xzf openclaw-backup-20260308.tar.gz

# Restart
docker compose up -d

Security Hardening for Docker Deployments

Running OpenClaw in Docker doesn't automatically make it secure. Apply these hardening measures:

**1. Don't Expose Port 18789 Publicly:**

**2. Run as Non-Root User:** The official image runs as the `node` user (UID 1000). Ensure your host directories match:

**3. Enable Agent Sandboxing:** Isolate agent tool execution:

This enables Docker-based agent isolation where non-main sessions run tools inside ephemeral containers.

**4. Restrict Network Access:** The default sandbox configuration blocks all network access:

**5. Set Resource Limits:** Prevent runaway agents from consuming all resources:

# Wrong - exposes to all interfaces
ports:
  - "18789:18789"

# Better - only localhost
ports:
  - "127.0.0.1:18789:18789"

# Fix ownership on Linux
sudo chown -R 1000:1000 /path/to/config /path/to/workspace

export OPENCLAW_SANDBOX=1
./docker-setup.sh

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "network": "none"
        }
      }
    }
  }
}

services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2.0'

Channel Configuration in Docker

Set up messaging channels from inside the container:

**Telegram:**

**Discord:**

**WhatsApp:**

This displays a QR code for scanning with WhatsApp.

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

docker compose run --rm openclaw-cli channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"

docker compose run --rm openclaw-cli channels login

Health Checks and Monitoring

**Built-in Health Endpoints:**

The Docker image includes a `HEALTHCHECK` instruction. Docker automatically monitors `/healthz` and marks containers unhealthy if they fail repeatedly.

**Authenticated Health Snapshot:**

This returns detailed status including channel connections, agent states, and system metrics.

**Viewing Logs:**

# Basic liveness probe
curl -fsS http://127.0.0.1:18789/healthz

# Readiness probe (checks channel connections)
curl -fsS http://127.0.0.1:18789/readyz

docker compose exec openclaw-gateway node dist/index.js health \
  --token "$OPENCLAW_GATEWAY_TOKEN"

# Gateway logs
docker compose logs -f openclaw-gateway

# CLI logs
docker compose logs -f openclaw-cli

# Last 100 lines
docker compose logs --tail=100 openclaw-gateway

Troubleshooting Common Issues

Even with a well-designed Docker setup, you'll occasionally hit problems. This section covers the most common issues and their solutions.

**"port is already allocated":** Another process uses port 18789. This typically happens if you have another OpenClaw instance running, or another application has claimed that port.

**"permission denied" errors:** The container user (UID 1000) can't write to mounted directories. This occurs when host directories are owned by root or a different user.

**"unauthorized" or "pairing required":** Your authentication token expired or was never properly saved. This commonly happens after container recreation or when the `.env` file is lost. The dashboard shows "disconnected" or "pairing required" despite the container running.

**Container exits immediately:** The gateway container starts then immediately exits. This usually indicates a startup failure. Common exit codes: Exit 1 — Missing config (run onboard). Exit 2 — Invalid config syntax (validate config). Exit 125 — Docker daemon issue (check systemctl). Exit 137 — OOM killed (increase memory). Exit 139 — Segmentation fault (prune and rebuild).

**"Docker socket not found":** The sandbox feature can't access the Docker daemon. This happens with rootless Docker installations or custom socket paths.

**Image pull failures:** Sometimes the pre-built image fails to download, especially in regions with restricted network access.

**Volume persistence issues:** Data doesn't persist after container restart. This usually means incorrect volume mounts.

**Network connectivity problems:** The gateway can't reach external services (API providers, channels).

**Performance Issues:** OpenClaw runs slowly inside Docker. This can stem from several factors. Slow responses — allocate more CPU. High memory usage — increase to 4GB+. Disk I/O delays — move config to SSD. Intermittent timeouts — reduce concurrent processes.

**Data disk full:** The Docker volumes or data directories consume all disk space.

# Find the conflicting process
sudo lsof -i :18789

# Or using ss
sudo ss -tulpn | grep 18789

# Fix ownership on Linux
sudo chown -R 1000:1000 ./config ./workspace

# On macOS with Docker Desktop, ensure the directory is shared
# in Docker Desktop > Settings > Resources > File Sharing

# Get a fresh token
docker compose run --rm openclaw-cli dashboard --no-open

# This outputs a URL like:
# http://127.0.0.1:18789/?token=eyJhbGciOiJIUzI1...

# Approve devices if needed
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

# If that doesn't work, re-run onboarding
docker compose run --rm openclaw-cli onboard

# Check the exit code
docker ps -a

# View the logs
docker compose logs openclaw-gateway

services:
  openclaw-gateway:
    mem_limit: 4g
    mem_reservation: 2g

ls -la /var/run/docker.sock
ls -la /run/user/1000/docker.sock

# For rootless Docker
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

# Or edit docker-compose.yml directly
services:
  openclaw-gateway:
    environment:
      - OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
    volumes:
      - /run/user/1000/docker.sock:/run/user/1000/docker.sock

# Try a different registry mirror
export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest

# Or build from source instead
unset OPENCLAW_IMAGE
./docker-setup.sh

# For Chinese users, try a mirror
export OPENCLAW_IMAGE=ghcr.dockerproxy.com/openclaw/openclaw:latest

# Ensure your docker-compose.yml has correct volume mounts
volumes:
  - ./config:/home/node/.openclaw
  - ./workspace:/home/node/.openclaw/workspace

# Verify the directories exist
ls -la ./config ./workspace

# Test from inside the container
docker compose exec openclaw-gateway curl -s https://api.openai.com

# Check DNS resolution
docker compose exec openclaw-gateway nslookup api.openai.com

# Add custom DNS in docker-compose.yml
services:
  openclaw-gateway:
    dns:
      - "8.8.8.8"
      - "1.1.1.1"

# Or use host network for debugging
# (not recommended for production)
network_mode: "host"

# Recommended resource limits
services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 2G
          cpus: '1.0'

docker system df
du -sh ./config ./workspace

# Clean up Docker resources
docker system prune -a
docker volume prune

# Archive and remove old session data
tar -czf sessions-backup-$(date +%Y%m%d).tar.gz ./config/agents/*/sessions/
rm -rf ./config/agents/*/sessions/sessions.json

# Or limit log sizes
# Add to docker-compose.yml:
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Shell Helpers: ClawDock

For easier day-to-day management, install the optional shell helpers:

Add to your shell config:

Available commands: `clawdock-start` — Start OpenClaw containers. `clawdock-stop` — Stop containers. `clawdock-restart` — Restart containers. `clawdock-logs` — Follow logs. `clawdock-dashboard` — Open dashboard URL. `clawdock-help` — Show all commands.

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

# For zsh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc
source ~/.zshrc

Updating Your Docker Deployment

**Method 1: Pull New Image:**

**Method 2: Rebuild from Source:**

**Method 3: Use the Update Command:**

This updates the CLI inside the container.

# Pull the latest image
docker pull ghcr.io/openclaw/openclaw:latest

# Restart containers
docker compose down
docker compose up -d

# Remove old image
docker rmi openclaw:local

# Rebuild
./docker-setup.sh

docker compose run --rm openclaw-cli self-update

Production Recommendations

For production deployments, consider these additions:

**1. Use a Reverse Proxy:**

**2. Enable Automatic Restarts:**

**3. Set Up Log Rotation:**

**4. Use a Dedicated Docker Network:**

# Traefik example
services:
  openclaw-gateway:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.openclaw.rule=Host(`openclaw.yourdomain.com`)"
      - "traefik.http.routers.openclaw.tls=true"

services:
  openclaw-gateway:
    restart: unless-stopped

services:
  openclaw-gateway:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  openclaw-net:
    driver: bridge

services:
  openclaw-gateway:
    networks:
      - openclaw-net

Can I run OpenClaw Docker on Raspberry Pi?

Yes, but with caveats. Raspberry Pi devices run the `linux/arm64` variant of the OpenClaw image. Most Raspberry Pi 4 and 5 models with 64-bit operating systems work fine with OpenClaw, though you'll notice slower performance compared to x86_64 hardware.

**Hardware requirements for Raspberry Pi:**

**Performance expectations:**

**Installation on Raspberry Pi:**

**Storage considerations:** The Pi's microSD card has limited write endurance. Consider using a USB SSD for Docker data or moving Docker's data directory to external storage.

**Cooling and power:** The Pi throttles under sustained load. Ensure active cooling (fan or heatsink), adequate power supply, and good ventilation.

• Raspberry Pi 4 (4GB or 8GB recommended) or Raspberry Pi 5
• Raspberry Pi OS 64-bit (Debian bookworm)
• High-quality power supply (3A for Pi 4, 5A for Pi 5)
• SSD or fast microSD card for storage
• Build time: 15-30 minutes (vs 5-10 on x86_64)
• Response latency: Noticeably slower for complex tasks
• Concurrent agents: Limit to 1-2 active agents
• Memory: Use swap if only 4GB available

# Install Docker
curl -sSL get.docker.com | sh
sudo usermod -aG docker $USER

# Reboot or run:
newgrp docker

# Clone and setup
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Use pre-built image (building is very slow)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# Edit /etc/docker/daemon.json
{
  "data-root": "/mnt/ssd/docker"
}

How much RAM does OpenClaw Docker use?

Memory usage varies based on activity level: Idle — Gateway 200-300 MB / Sandbox 0 MB. Light use — Gateway 300-500 MB / Sandbox 200-400 MB. Heavy use — Gateway 500 MB-1 GB / Sandbox 400-800 MB. Peak — Gateway up to 1.5 GB / Sandbox up to 1 GB.

**Total recommended allocation:** Minimum: 2 GB host RAM. Comfortable: 4 GB host RAM. Production: 8+ GB host RAM.

**Monitoring memory:**

**Memory optimization tips:** Disable unused channels (each active channel uses memory). Limit concurrent sessions (set in config). Use swap as buffer on systems with limited RAM. Enable sandbox pruning to auto-cleanup idle sandboxes.

# Inside container
docker stats openclaw-gateway

# Or via API
curl -s http://127.0.0.1:18789/healthz | jq

{
  "agents": {
    "defaults": {
      "sandbox": {
        "prune": {
          "idleHours": 1,
          "maxAgeDays": 3
        }
      }
    }
  }
}

Can I use Docker Swarm or Kubernetes?

The current `docker-compose.yml` is designed for standalone Docker Compose. While you can adapt it for orchestration platforms, it's not officially supported.

**Docker Swarm:** Some users successfully run OpenClaw in Docker Swarm mode:

**Known limitations in Swarm:** Health checks work but may need tuning. Volume management differs from Compose. Some CLI commands require service adaptation.

**Kubernetes:** Running OpenClaw on Kubernetes requires custom manifests. You'll need to create a Deployment with proper resource limits, set up PersistentVolumeClaims for config and workspace, configure Service (ClusterIP or LoadBalancer), and handle init containers for first-run setup. This is advanced and not covered in this guide. Community examples may exist in the OpenClaw GitHub repository.

# docker-compose.swarm.yml
version: '3.8'

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    ports:
      - "18789:18789"
    volumes:
      - openclaw-config:/home/node/.openclaw
      - openclaw-workspace:/home/node/.openclaw/workspace
    deploy:
      replicas: 1
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

volumes:
  openclaw-config:
  openclaw-workspace:

docker stack deploy -c docker-compose.swarm.yml openclaw

What's the difference between "lan" and "loopback" bind modes?

Understanding bind modes controls who can access your OpenClaw instance: `lan` — Binds to all local network interfaces (default, access from other devices). `loopback` — Only binds to 127.0.0.1 (maximum security, container-only access). `custom` — Custom IP address (advanced, specific interface binding). `tailnet` — Tailscale network binding (remote access via Tailscale). `auto` — Automatic selection (let OpenClaw decide).

**When to use loopback:** Running on a VPS with additional firewall, only accessing from the same machine, or maximum security for sensitive deployments.

**When to use lan:** Home network access from multiple devices, development and testing, or when using a reverse proxy.

# Set via environment variable
export OPENCLAW_GATEWAY_BIND=loopback
./docker-setup.sh

# Or edit config directly
# In config.yaml:
gateway:
  bind: loopback

Can I run multiple OpenClaw instances on one host?

Yes, but you'll need to change the port mapping for each instance, use different container names, and use different config/workspace directories.

**Example for running two instances:**

# First instance (default)
./docker-setup.sh  # Uses port 18789

# Second instance
mkdir -p openclaw-instance-2
cd openclaw-instance-2
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
export OPENCLAW_CONFIG_DIR="./config"
export OPENCLAW_WORKSPACE_DIR="./workspace"
# Edit docker-compose.yml to change:
# - ports: "18791:18789"
# - container_name: openclaw-gateway-2
./docker-setup.sh

Additional Docker Tips

**How do I access the container shell for debugging?**

docker compose exec openclaw-gateway /bin/sh

docker compose exec --user root openclaw-gateway /bin/sh

Conclusion

Docker transforms OpenClaw deployment from a manual process into something repeatable and manageable. The key points to remember: Start with the quick script — `./docker-setup.sh` handles most setup automatically. Use pre-built images for faster deployment. Understand volume persistence — config and workspace survive restarts; the container filesystem doesn't. Apply security hardening — don't expose ports publicly, enable sandboxing, set resource limits. Monitor health — use `/healthz` and `/readyz` endpoints. Back up data — tar your config and workspace directories regularly. The OpenClaw Docker setup is mature and well-documented. Most users can be running in under ten minutes. The trade-off is slightly higher resource usage than a native install—but the isolation, portability, and security benefits make it worth it for most self-hosters.

Frequently asked questions