OpenClaw Docker Setup: The Complete Container Deployment Guide

Why Docker for OpenClaw?

Docker gives you a reproducible, isolated environment that works identically on any machine. No "it works on my machine" problems, easy upgrades by rebuilding the image, and built-in security isolation between OpenClaw and your host system.

Prerequisites

• Docker Desktop (Mac/Windows) or Docker Engine + Docker Compose v2 (Linux)
• At least 2GB RAM available for the container
• Git (to clone the repository)

Quick Start: One Script Does Everything

Clone the repo and run the setup script:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

This single script handles the entire process:

1. Builds the Docker image (openclaw:local) from the Dockerfile
2. Generates a secure gateway token via openssl rand -hex 32
3. Writes environment variables to .env
4. Runs the onboarding wizard interactively in a temporary container
5. Starts the gateway in detached mode via docker compose up -d

What Gets Created

After running docker-setup.sh, your project has:

• .env — Environment variables including your generated gateway token
• ~/.openclaw/ — Configuration directory (bind-mounted into the container)
• ~/.openclaw/workspace/ — Workspace for skills and data
• Two Docker Compose services: openclaw-gateway (always-on) and openclaw-cli (interactive)

Docker Compose Architecture

The docker-compose.yml defines two services:

• openclaw-gateway — The always-running gateway server, bound to LAN (0.0.0.0) on ports 18789 and 18790. Restarts automatically on failure.
• openclaw-cli — An interactive container for running commands like onboard, channels login, and channels add. Exits after each use.

Environment Variables

These environment variables customize your Docker deployment:

# Core settings (set automatically by docker-setup.sh)
OPENCLAW_GATEWAY_TOKEN=your-generated-token
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_CONFIG_DIR=~/.openclaw
OPENCLAW_WORKSPACE_DIR=~/.openclaw/workspace

# Optional: Extra apt packages in the Docker image
OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"

# Optional: Additional host directories to mount
OPENCLAW_EXTRA_MOUNTS="$HOME/documents:/home/node/documents:ro"

# Optional: Named volume for persistent home directory
OPENCLAW_HOME_VOLUME="openclaw_home"

Connecting Messaging Channels via Docker

Use the CLI container to set up channels:

# WhatsApp (shows QR code to scan)
docker compose run --rm openclaw-cli channels login

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

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

# Slack
docker compose run --rm openclaw-cli channels add --channel slack --bot-token "xoxb-..." --app-token "xapp-..."

Health Checks

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

# View gateway logs
docker compose logs -f openclaw-gateway

# Check container status
docker compose ps

Agent Sandbox: Isolating AI Tool Execution

OpenClaw can run AI tool executions (code, shell commands) inside isolated sandbox containers. This is crucial for group chat sessions where untrusted users might interact with the AI.

Build the sandbox images:

# Basic sandbox (Debian slim)
scripts/sandbox-setup.sh

# Extended sandbox (Node, Go, Rust pre-installed)
scripts/sandbox-common-setup.sh

# Browser sandbox (Chromium + CDP)
scripts/sandbox-browser-setup.sh

Enable in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "network": "none",
          "memory": "1g",
          "cpus": 1
        }
      }
    }
  }
}

Upgrading

# Pull latest code
git pull

# Rebuild the image
docker compose build

# Restart with new image
docker compose up -d openclaw-gateway

Common Issues

• Permission errors (EACCES on /home/node/.openclaw): The container runs as user node (uid 1000). Ensure host bind mounts are owned by uid 1000: sudo chown -R 1000:1000 ~/.openclaw
• Container can't reach webhook providers: Ensure your firewall allows outbound HTTPS (port 443) from Docker containers
• WhatsApp QR code not showing: Use docker compose run --rm openclaw-cli channels login — the CLI container has TTY support for interactive QR display
• Gateway lock file stuck after crash: If the gateway won't start after an unclean shutdown: docker compose exec openclaw-gateway rm -f /home/node/.openclaw/gateway.*.lock