OpenClaw Docker: Complete Setup & Compose Guide

Docker is the recommended way to install OpenClaw — it isolates the agent in a container, simplifies updates to a single docker pull command, and lets you run multiple instances on one server without conflicts. The entire setup takes under 10 minutes if Docker is already installed.

Why Docker Is the Best Way to Run OpenClaw

If you have ever installed a complex AI tool directly on a server and later struggled to update it, roll it back, or run two versions at once — Docker is the answer you have been looking for. OpenClaw is a multi-process application: it runs one or more agent processes, manages API credentials, writes logs, and optionally exposes a web UI. All of that is much cleaner inside a container.

Three reasons Docker makes OpenClaw easier:

---

Prerequisites

Before starting, make sure the following are installed on your server or workstation:

• Docker Engine 24+ (or Docker Desktop on macOS/Windows)
• Docker Compose v2 (included with Docker Desktop; on Linux install the docker-compose-plugin package)
• An Anthropic API key (or another supported provider key)
• Basic familiarity with the terminal

docker --version      # Docker version 24.x or higher
docker compose version # Docker Compose version v2.x

---

Step-by-Step: docker-compose.yml

Create a working directory and add the following files:

mkdir openclaw && cd openclaw

1. docker-compose.yml

version: "3.9"
services:   openclaw:     image: openclaw/agent:latest     container_name: openclaw_main     restart: unless-stopped     env_file:       - .env     ports:       - "3000:3000"   # Web UI     volumes:       - ./data:/app/data        # Persistent agent data       - ./logs:/app/logs        # Log files       - ./config:/app/config    # Custom config overrides     healthcheck:       test: ["CMD", "curl", "-f", "http://localhost:3000/health"]       interval: 30s       timeout: 10s       retries: 3       start_period: 20s     deploy:       resources:         limits:           cpus: "1.0"           memory: 512M

2. .env file

Create a .env file in the same directory. Never commit this file to git.

# API credentials
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
Agent settings
OCL_MODEL=claude-sonnet-4-6
OCL_MAX_TOKENS=4096
OCL_LOG_LEVEL=info
Web UI
OCL_UI_PORT=3000
OCL_UI_SECRET=change-this-to-a-random-string
Telegram notifications (optional)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

3. Create volume directories

mkdir -p data logs config

Now start the container:

docker compose up -d

Check that it is running:

docker compose ps
docker compose logs -f openclaw

---

Configuration: Ports, Variables, and Secrets

chmod 600 .env

If you are on a shared server, consider using Docker Secrets syntax in the compose file and storing the actual values in /run/secrets/.

---

Running Multiple Agents with Different Models

One of Docker Compose's biggest advantages is running several agent instances side-by-side. Here is how to set up a "fast" agent (Haiku for cheap tasks) and a "deep" agent (Sonnet for complex research):

version: "3.9"
services:   agent-fast:     image: openclaw/agent:latest     container_name: openclaw_fast     restart: unless-stopped     env_file: .env.fast     ports:       - "3001:3000"     volumes:       - ./data/fast:/app/data       - ./logs/fast:/app/logs
agent-deep:     image: openclaw/agent:latest     container_name: openclaw_deep     restart: unless-stopped     env_file: .env.deep     ports:       - "3002:3000"     volumes:       - ./data/deep:/app/data       - ./logs/deep:/app/logs

Create .env.fast with OCL_MODEL=claude-haiku-4-5 and .env.deep with OCL_MODEL=claude-sonnet-4-6. Each agent runs on its own port, with its own data directory.

---

Updating OpenClaw

Updating is a two-step process:

# Pull the latest image
docker compose pull
Recreate the container with the new image
docker compose up -d --force-recreate

Your data persists because it lives in the ./data volume on the host, not inside the container. The old image is cached locally until you clean it up:

docker image prune -f

image: openclaw/agent:1.4.2

This way updates only happen when you explicitly change the tag.

---

Monitoring: Portainer and Docker Logs

# Follow live logs
docker compose logs -f openclaw
Last 100 lines
docker compose logs --tail=100 openclaw
Logs from a specific time
docker compose logs --since 1h openclaw

portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9000:9000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
volumes:   portainer_data:

Access Portainer at http://your-server:9000. You can view logs, restart containers, inspect environment variables, and check resource usage — all from a browser.

---

Troubleshooting Common Docker Issues

chown -R 1000:1000 ./data ./logs

docker compose exec openclaw env | grep ANTHROPIC

---

Docker vs Bare-Metal: When to Use Which

---

Production Tips

# Simple tar backup
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ./data
Or rsync to another server
rsync -az ./data user@backup-server:/backups/openclaw/

server {
    listen 443 ssl;
    server_name agent.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/agent.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agent.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

With these practices in place, your OpenClaw Docker setup is ready for long-term production use.

Is Docker the Best Way to Install OpenClaw?

For most users — yes. Docker provides isolated environments, one-command updates (docker pull), easy rollbacks, and the ability to run multiple instances. The only cases where a native installation is preferable: if you need maximum performance on limited hardware (Raspberry Pi) or if your hosting provider doesn't support Docker.