OpenClaw Docker Setup: Copy-Paste docker-compose.yml + Common Error Fixes (2026) | OpenClaw DC

TL;DR: the one command

docker compose up -d

That starts the OpenClaw gateway on http://localhost:18789, with restart: unless-stopped, a non-root node user (uid 1000), a /healthz health check every 30 seconds, and two persistent bind mounts for config and workspace. The full Compose file is below — copy it verbatim, add an ANTHROPIC_API_KEY to your .env, run the command, done.

If the container keeps restarting, jump straight to Common Docker errors and fixes. The top cause is a bad gateway.bind value.

Prerequisites

You need Docker Engine 24+ and Docker Compose v2 installed on your host. If you have not installed OpenClaw at all yet, the installation guide covers the non-Docker paths and prerequisites in detail.

Confirm your Docker version:

docker --version
docker compose version

You also need at least 2 GB of RAM available. The image build and initial startup can OOM-kill on 1 GB hosts (exit code 137).

The complete docker-compose.yml

Create a project directory and save this file as docker-compose.yml:

# OpenClaw production Compose file
# Docs: https://docs.openclaw.ai/install/docker

services:
  openclaw-gateway:
    image: alpine/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped

    # Non-root: runs as node (uid 1000) inside the container
    user: "1000:1000"

    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"

    environment:
      - NODE_ENV=production
      - TZ=${TZ:-UTC}
      - OPENCLAW_SKIP_SERVICE_CHECK=true
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND:-lan}
      - OPENCLAW_GATEWAY_PORT=18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

    volumes:
      # Config, memory, and API key storage
      - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw
      # Agent workspace (files the agent reads and writes)
      - ${OPENCLAW_WORKSPACE_DIR:-~/openclaw/workspace}:/home/node/.openclaw/workspace

    healthcheck:
      test: >
        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

    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

Environment variables explained

Create a .env file in the same directory as your Compose file. Docker Compose reads it automatically.

# Required: your Anthropic API key
ANTHROPIC_API_KEY=sk-ant-your-key-here

# Required: gateway auth token (generate one below)
OPENCLAW_GATEWAY_TOKEN=

# Optional: override default port (18789)
OPENCLAW_GATEWAY_PORT=18789

# Optional: bind mode (lan | loopback | auto | tailnet)
OPENCLAW_GATEWAY_BIND=lan

# Optional: timezone (IANA format)
TZ=America/New_York

# Optional: custom paths for config and workspace
OPENCLAW_CONFIG_DIR=~/.openclaw
OPENCLAW_WORKSPACE_DIR=~/openclaw/workspace

Generate a strong gateway token before your first start:

echo "OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)" >> .env

ANTHROPIC_API_KEY is the only provider key you must set. If you use other providers, add their keys to the same .env file. Provider keys are always read from environment variables, never from JSON config files.

OPENCLAW_GATEWAY_BIND controls how the gateway listens. Use lan for local network access (default), loopback to restrict to 127.0.0.1 only, or auto to let OpenClaw decide. Do not pass raw IP addresses like 0.0.0.0. That triggers a schema validation error and a restart loop.

Volumes: what to persist

Two bind mounts keep your data safe across container replacements.

Config directory (~/.openclaw mapped to /home/node/.openclaw). This holds config.yaml, your .env secrets, memory storage, agent definitions, and installed skills. Losing this directory means re-running onboarding from scratch.

Workspace directory (~/openclaw/workspace mapped to /home/node/.openclaw/workspace). This is where the agent reads and writes files during task execution. Any documents, code, or output your agents produce live here.

Before the first start, make sure the host directories exist and are owned by uid 1000:

mkdir -p ~/.openclaw ~/openclaw/workspace
sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace

Start, onboard, and verify

docker compose up -d
docker compose logs -f openclaw-gateway

On first run, the setup script launches an interactive onboarding wizard inside the container. It configures your AI provider credentials and optional messaging channels (WhatsApp, Telegram, Discord).

Once the logs show the gateway is listening, verify the health endpoint:

curl http://127.0.0.1:18789/healthz

Check readiness with /readyz and container status with:

docker compose ps

You should see openclaw-gateway with a status of Up (healthy).

Health checks and restart policies

The Compose file uses restart: unless-stopped, which means the container automatically recovers from crashes and host reboots but stays down if you explicitly stop it with docker compose stop.

The healthcheck pings /healthz every 30 seconds. After 5 consecutive failures, Docker marks the container as unhealthy. Pair this with a monitoring tool or a simple cron-based alert:

# Add to crontab: alert if gateway is unhealthy
*/5 * * * * docker inspect --format='{{.State.Health.Status}}' openclaw-gateway | grep -q healthy || echo "OpenClaw unhealthy" | mail -s "Alert" you@example.com

Common Docker errors and fixes

“Missing config. Run clawdbot setup or set gateway.mode.” This appears when the config directory is empty or not mounted correctly. Fix: run docker compose exec openclaw-gateway openclaw onboard to re-trigger setup, or verify your volume paths point to a valid ~/.openclaw directory.

Container restart loop (gateway.bind invalid input). OpenClaw rejects raw addresses like 0.0.0.0 or 127.0.0.1 in gateway.bind. Use the keyword values instead: lan, loopback, auto, or tailnet. Check your .env file and remove any raw IP.

# Wrong
OPENCLAW_GATEWAY_BIND=0.0.0.0

# Correct
OPENCLAW_GATEWAY_BIND=lan

Timezone mismatch in logs. If agent logs show UTC timestamps but you expected local time, set the TZ variable in your .env to your IANA timezone string, for example TZ=America/New_York or TZ=Europe/Berlin.

Permission denied on /home/node/.openclaw. The container runs as uid 1000. If your host directories are owned by root or another user, the gateway cannot write config or memory files. Fix with sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace.

Port 18789 already in use. Another process or a leftover OpenClaw service is occupying the port. Stop it first, or change OPENCLAW_GATEWAY_PORT in your .env to a free port.

Security: non-root user and network isolation

The official image runs as the node user (uid 1000) by default. The user: "1000:1000" directive in the Compose file enforces this even if the image changes its default. Running as non-root limits the blast radius if a skill or agent is compromised.

The dedicated openclaw-net bridge network isolates OpenClaw traffic from other containers on the host. If you add services like a reverse proxy later, attach only the proxy to openclaw-net and keep everything else on separate networks.

For a full hardening walkthrough, including gateway token rotation, TLS termination, and firewall rules, follow the OpenClaw security checklist. If you are deploying to a remote server, the VPS and cloud deployment guide covers provider selection, Nginx reverse proxy setup, and Let’s Encrypt certificates.

Updating the container

Pull the latest image and recreate the container without losing data:

docker compose pull
docker compose up -d

Your config and workspace volumes persist through the update. Check the release notes before upgrading, as some versions (notably 2026.3.2 and 2026.2.26) introduced regressions. Version 2026.3.7 and later are stable.

Next steps

• Install OpenClaw if you want to compare the non-Docker path
• Security checklist for production hardening
• VPS and cloud deployment for remote hosting with Nginx and TLS