How to Run OpenClaw in Docker: Step-by-Step Setup

Running OpenClaw in Docker gives you isolation, reproducibility, and easy team sharing. Your agent runs in a container with its own filesystem, can't accidentally mess up your host machine, and every team member gets the exact same environment.

This guide covers everything from a basic single-container setup to a production-ready docker-compose configuration.

Why Docker for OpenClaw?

Three reasons to containerize your OpenClaw setup:

1. Isolation — OpenClaw can run shell commands and modify files. Docker contains the blast radius. If an agent goes rogue, it only affects the container.

2. Reproducibility — "Works on my machine" is eliminated. Your Dockerfile IS the setup documentation.

3. Team consistency — Everyone runs the same OpenClaw version, same tools, same skills. No more debugging environment differences.

Quick Start: Single Container

The fastest way to get OpenClaw running in Docker:

docker run -it \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/anthropic/openclaw:latest

This mounts your current directory into the container at /workspace, passes your API key, and drops you into an interactive OpenClaw session.

Building a Custom Dockerfile

For real projects, you'll want a custom image with your tools pre-installed:

FROM ghcr.io/anthropic/openclaw:latest

# Install additional tools your agent might need
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    postgresql-client \
    jq \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js tools
RUN npm install -g prettier eslint typescript

# Copy your skills into the container
COPY .openclaw/skills/ /root/.openclaw/skills/

# Copy MCP server configs
COPY .openclaw/mcp-servers.json /root/.openclaw/mcp-servers.json

# Set working directory
WORKDIR /workspace

# Default command
CMD ["openclaw"]

Build and run it:

docker build -t my-openclaw .
docker run -it \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  -v $(pwd):/workspace \
  my-openclaw

Docker Compose for Production

A docker-compose.yml that handles everything — volumes, environment variables, networking, and optional services:

version: '3.8'

services:
  openclaw:
    build:
      context: .
      dockerfile: Dockerfile.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENCLAW_MODEL=claude-sonnet-4-20250514
      - OPENCLAW_MAX_TOKENS=8192
    volumes:
      # Mount your project
      - ./project:/workspace
      # Persist OpenClaw session history
      - openclaw-history:/root/.openclaw/history
      # Mount skills (live reload)
      - ./skills:/root/.openclaw/skills
    working_dir: /workspace
    stdin_open: true
    tty: true
    networks:
      - openclaw-net
    # Optional: limit resources
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2.0'

  # Optional: local Postgres for agent tasks
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: agentdb
      POSTGRES_USER: agent
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-agentpass}
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - openclaw-net

volumes:
  openclaw-history:
  pgdata:

networks:
  openclaw-net:
    driver: bridge

Usage:

# Create .env file with your keys
echo "ANTHROPIC_API_KEY=sk-ant-your-key" > .env

# Start everything
docker compose up -d

# Attach to OpenClaw
docker compose exec openclaw openclaw

# Run a one-off command
docker compose exec openclaw openclaw "analyze the database schema and suggest indexes"

Environment Variables

Key environment variables for containerized OpenClaw:

| Variable | Required | Description | | ---------- | ---------- | ------------- | | ANTHROPIC_API_KEY | Yes | Your Anthropic API key | | OPENCLAW_MODEL | No | Model to use (default: claude-sonnet-4-20250514) | | OPENCLAW_MAX_TOKENS | No | Max tokens per response | | OPENCLAW_SKILLS_DIR | No | Custom skills directory path | | OPENCLAW_MCP_CONFIG | No | Path to MCP server configuration | | OPENAI_API_KEY | No | For using OpenAI models instead |

Never hardcode API keys in your Dockerfile. Always pass them via environment variables or Docker secrets.

Volume Mounts: What to Persist

Getting volumes right is critical. Here's what to mount and why:

# Your project files (read/write)
-v $(pwd)/project:/workspace

# Session history (persist across container restarts)
-v openclaw-history:/root/.openclaw/history

# Skills (mount from host for live editing)
-v $(pwd)/skills:/root/.openclaw/skills

# SSH keys (for git operations — read-only)
-v ~/.ssh:/root/.ssh:ro

# Git config (for commits)
-v ~/.gitconfig:/root/.gitconfig:ro

The :ro flag makes mounts read-only — use it for sensitive files like SSH keys.

Networking

If your OpenClaw agent needs to access services running on your host machine (like a local dev server), use the special Docker host networking:

# Linux
docker run --network host ...

# macOS/Windows (Docker Desktop)
# Use host.docker.internal instead of localhost
docker run -e DATABASE_URL=postgresql://user:pass@host.docker.internal:5432/mydb ...

For accessing other containers, use Docker Compose networking (as shown in the compose file above). Services can reach each other by name — the OpenClaw container can connect to postgres:5432 directly.

Running Non-Interactive Tasks

Docker is perfect for fire-and-forget agent tasks:

# Run a task and exit
docker run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/workspace \
  my-openclaw \
  openclaw "run all tests and fix any failures" --auto-approve

# Schedule with cron
0 9 * * 1 docker run --rm -e ANTHROPIC_API_KEY=$KEY -v /path/to/project:/workspace my-openclaw openclaw "generate the weekly analytics report"

For teams running many automated agent tasks, RunAgents handles scheduling, monitoring, and task management through a visual dashboard — so you don't have to manage cron jobs and Docker commands manually.

Troubleshooting

Permission denied on mounted volumes

The most common Docker + OpenClaw issue. Files created inside the container are owned by root, which causes permission errors on the host.

Fix: run the container with your host user's UID:

docker run -it --user $(id -u):$(id -g) \
  -e ANTHROPIC_API_KEY=$KEY \
  -v $(pwd):/workspace \
  my-openclaw

API key not found

If OpenClaw says it can't find your API key, check that you're passing it correctly:

# Verify the variable is set inside the container
docker run --rm -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY my-openclaw env | grep ANTHROPIC

# Common mistake: using .env file without --env-file flag
docker run --env-file .env ...

Container runs out of memory

OpenClaw itself is lightweight, but if your agent tasks involve processing large files or running memory-intensive commands, you may need to increase the memory limit:

docker run -m 4g ...  # 4 GB memory limit

Volume mount shows empty directory

Double-check your mount paths. Docker requires absolute paths on the host side:

# This won't work
-v ./project:/workspace

# This works
-v $(pwd)/project:/workspace

# Or use absolute path
-v /home/user/project:/workspace

Frequently Asked Questions

Should I use Docker or install OpenClaw natively?

For personal development, native install is simpler and faster. Use Docker when you need isolation (running untrusted agent tasks), team consistency (everyone gets the same environment), or automated/scheduled tasks (fire-and-forget containers).

How much disk space does the OpenClaw Docker image use?

The base image is around 800MB. A custom image with additional tools typically lands between 1-2GB. Session history and agent output are extra, but usually negligible unless your agent generates large files.

Does OpenClaw in Docker support GPU?

OpenClaw doesn't need a GPU — the AI models run in the cloud via API. The GPU question only matters if you're running local models. In that case, use nvidia-docker or the --gpus all flag, but that's a separate setup from OpenClaw itself.

How do I update OpenClaw in Docker?

Pull the latest image and rebuild: docker pull ghcr.io/anthropic/openclaw:latest && docker compose build. Pin to specific versions in production (e.g., openclaw:2026.3) to avoid surprise breaking changes.

Can I run multiple OpenClaw agents in separate containers?

Yes, and this is one of Docker's biggest advantages. Each container gets its own filesystem and environment. Run 10 agents in parallel, each working on different tasks, without them interfering with each other.

How do I access my host's localhost services from the container?

On macOS and Windows with Docker Desktop, use host.docker.internal instead of localhost. On Linux, use --network host flag or add --add-host=host.docker.internal:host-gateway to your docker run command.

Want Docker-level isolation without managing containers? RunAgents gives you managed OpenClaw hosting with task management, team collaboration, and agent debugging built in. Get started free

Related Guides

• How to Install OpenClaw -- All installation methods

• Deploy OpenClaw on Linux VPS -- Full VPS deployment guide

• Secure Your ClawdBot Deployment -- Security hardening