Complete Guide to Deploying OpenClaw with Docker

Why Deploy with Docker

For anyone who needs OpenClaw running reliably over the long term, Docker is a better choice than a bare npm install. The advantages are clear: environment isolation prevents dependency conflicts, one-command start/stop simplifies operations, container restarts automatically recover the service, and upgrading is as simple as pulling a new image tag.

This tutorial walks you through a complete Docker Compose deployment, suitable for personal servers, home NAS devices, or cloud instances.

Prerequisites

Make sure the following tools are installed on your machine:

• Docker Engine 24+
• Docker Compose v2+ (bundled with modern Docker CLI releases)

Verify the installation:

docker --version
docker compose version

If you haven't installed Docker yet, follow the official Docker documentation to get set up.

Write the docker-compose.yml

Create a project directory and write the Compose configuration file:

mkdir -p ~/openclaw-docker && cd ~/openclaw-docker

Create a docker-compose.yml file with the following content:

version: "3.8"

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.config/openclaw
      - ./data:/root/.openclaw
    environment:
      - NODE_ENV=production
      - TZ=Asia/Shanghai
    env_file:
      - .env

Here's what this configuration does:

• Uses the official image openclaw/openclaw:latest
• Maps the Gateway port 18789 to the host
• Mounts the config and data directories for persistence
• Sets the timezone to Shanghai (change this to match your location)
• Reads sensitive environment variables from a .env file

Set Up Environment Variables

Create a .env file to store API keys and other sensitive information:

# .env
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

Only fill in the keys for the providers you actually use. Keep in mind that the .env file contains sensitive data — make sure it's excluded from version control.

Create the Configuration File

Create the core OpenClaw configuration file inside the config directory:

mkdir -p config

Create config/openclaw.json5:

{
  // AI model provider settings
  providers: {
    anthropic: {
      enabled: true,
      defaultModel: "claude-sonnet-4-20250514"
    }
  },

  // Gateway settings
  gateway: {
    port: 18789,
    host: "0.0.0.0"  // Must listen on all interfaces inside the container
  },

  // Channel settings (enable as needed)
  channels: {}
}

Note that host must be set to 0.0.0.0; otherwise the Gateway won't be reachable from outside the container.

Start the Container

With everything in place, bring up the service:

docker compose up -d

Check the container status:

docker compose ps

You should see the openclaw container in a running state.

View Logs

Watching the logs in real time is invaluable when troubleshooting:

docker compose logs -f openclaw

To view only the last 100 lines:

docker compose logs --tail 100 openclaw

If you see API connection errors during startup, the most likely cause is an incorrect key in the .env file.

Day-to-Day Operations

Stop the service:

docker compose down

Restart the service:

docker compose restart

Upgrade to the latest version:

docker compose pull
docker compose up -d

This pulls the latest image and recreates the container. Your configuration and data are safe because they're stored in mounted volumes.

Open a shell inside the container:

docker exec -it openclaw sh

From inside the container you can run openclaw doctor to diagnose issues.

Backing Up Your Data

Since both configuration and data are mounted on the host under ./config and ./data, backups are straightforward:

tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz config data .env

Make a habit of backing up regularly, especially before upgrades.

Reverse Proxy Setup (Optional)

If you want to access OpenClaw through a domain name, place an Nginx reverse proxy in front of it. You can either add an Nginx service to your docker-compose.yml or configure Nginx on the host:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The WebSocket Upgrade headers are important — OpenClaw's real-time communication depends on them.

Wrapping Up

Docker deployment makes running OpenClaw practically effortless. Once configured, your day-to-day responsibilities are limited to monitoring logs and pulling updates. If you run into issues, check the OpenClaw official documentation or file an issue on the OpenClaw GitHub repository. For more feature details, visit OpenClaw.