Running OpenClaw in Docker: A Step-by-Step Deployment Guide

Why Docker?

Running OpenClaw in Docker provides three key advantages over a bare-metal installation:

1. 1.Security isolation: The agent runs inside a container with limited access to your host system. If a malicious skill or prompt injection attempts to access your files, the container boundary limits the blast radius.
2. 2.Reproducibility: The same Docker image runs identically on any machine — your laptop, a VPS, or a Raspberry Pi.
3. 3.Easy cleanup: Want to start fresh? Remove the container and spin up a new one. No leftover files, no broken Node.js installations.

Prerequisites

• •Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• •Docker Compose v2 (included with Docker Desktop)
• •At least 2 GB RAM available for the container
• •An AI API key (Anthropic, OpenAI, or other supported provider)

Quick Start

Option A: Official Docker Compose (Recommended)

Clone the OpenClaw repository and use the built-in Docker setup:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Run the setup script, which creates the necessary directories and configuration:

bash docker-setup.sh

• •~/.openclaw/ — configuration, SOUL.md, API keys
• •~/openclaw/workspace/ — files accessible to the agent

Run the onboarding wizard inside the container:

docker compose run --rm openclaw-cli onboard

Follow the prompts to set up your API key and connect a chat platform. Then start the gateway:

docker compose up -d openclaw-gateway

Your agent is now running in the background.

Option B: Pre-built Image

If you do not want to clone the repository, use the official pre-built image:

docker run -d   --name openclaw   --restart unless-stopped   -v ~/.openclaw:/root/.openclaw   -v ~/openclaw/workspace:/root/workspace   -p 3000:3000   ghcr.io/openclaw/openclaw:latest

Docker Compose Reference

Here is a annotated docker-compose.yml for production use:

version: "3.8"
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"        # Web UI
    volumes:
      - ~/.openclaw:/root/.openclaw          # Config and data
      - ~/openclaw/workspace:/root/workspace  # Agent workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TZ=Asia/Shanghai     # Set your timezone
    mem_limit: 2g            # Prevent runaway memory usage
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Create a .env file in the same directory with your API keys:

ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

Environment Variables

*At least one AI provider key is required.

Managing Your Container

# View logs
docker logs -f openclaw

# Stop the agent
docker compose stop

# Start the agent
docker compose up -d

# Restart after config changes
docker compose restart

# Update to latest version
docker compose pull
docker compose up -d

# Enter the container shell
docker exec -it openclaw bash

# Run CLI commands inside container
docker exec openclaw openclaw skill list
docker exec openclaw openclaw status

Security Hardening

Limit filesystem access

Only mount the directories your agent actually needs. Avoid mounting your entire home directory:

volumes:
  - ~/.openclaw:/root/.openclaw:rw     # Config (read-write)
  - ~/documents:/root/docs:ro           # Documents (read-only)

Network isolation

If your agent does not need to access local network services, restrict its network:

networks:
  openclaw-net:
    driver: bridge
    internal: false    # Set to true to block all external access

Read-only root filesystem

For maximum security, make the root filesystem read-only and only allow writes to specific paths:

read_only: true
tmpfs:
  - /tmp
  - /run

Updating

OpenClaw releases frequently. To update your Docker deployment:

docker compose pull           # Pull latest image
docker compose up -d          # Recreate container with new image
docker image prune -f         # Clean up old images

Your configuration and data persist in the mounted volumes, so updates are non-destructive.

Troubleshooting

Container crashes immediately: Check logs with docker logs openclaw. Common causes: missing API keys, insufficient memory, or port conflicts.

WhatsApp QR code not showing: Run the onboarding in interactive mode: docker compose run --rm openclaw-cli onboard. The QR code needs a terminal that supports rendering.

Permission errors on mounted volumes: Ensure the host directories exist and are owned by your user: mkdir -p ~/.openclaw ~/openclaw/workspace.

High memory usage: Set mem_limit: 2g in docker-compose.yml to prevent the container from consuming excessive RAM.

For more details, see the official Docker documentation and the docker-compose.yml in the repository.