Run OpenClaw in Docker
— Safe, Isolated, Reproducible

💡 What Is Docker? What Is Sandboxing?

New to Docker? No problem. Here's what you need to know in plain English.

🛡️ Why Run OpenClaw in Docker?

Docker isn't just for developers. Here are real benefits for any OpenClaw user.

⬇️ Step 1 — Install Docker

Choose your operating system below for installation instructions.

📁 Step 2 — Set Up Your Project Folder

Before writing any Docker files, create a clean folder structure for your OpenClaw project.

my-openclaw/
├── openclaw.json       # your OpenClaw config
├── Dockerfile          # tells Docker how to build the image
├── docker-compose.yml  # easier way to manage the container
├── .env                # your API keys (never commit this!)
├── .gitignore          # make sure .env and agent.db aren't committed
└── data/               # persistent storage (memory db, logs)

🔨 Step 3 — Write the Dockerfile

A Dockerfile is a recipe that tells Docker how to build a container image for OpenClaw. Each line is a simple instruction — here's a beginner-friendly version with every line explained.

# Start from the official Node.js 20 image (slim = smaller file size)
FROM node:20-slim

# Set the working directory inside the container
WORKDIR /app

# Install OpenClaw globally
RUN npm install -g openclaw

# Copy your config file into the container
COPY openclaw.json .

# Create a directory for persistent data (memory, logs)
RUN mkdir -p /app/data

# Expose the gateway port so your browser/apps can connect
EXPOSE 8080

# The command that runs when the container starts
CMD ["openclaw", "start"]

🎻 Step 4 — Docker Compose (Recommended)

Instead of typing long docker run commands every time, Docker Compose lets you define everything in one simple file and start your whole setup with one command.

version: '3.9'

services:
  openclaw:
    # Build the image from the Dockerfile in this folder
    build: .

    # Give the container a friendly name
    container_name: openclaw-agent

    # Restart automatically if it crashes or the server reboots
    restart: unless-stopped

    # Map host port 8080 to container port 8080
    # Format: "host_port:container_port"
    ports:
      - "8080:8080"

    # Load environment variables (API keys) from .env file
    env_file:
      - .env

    # Mount the data folder so memory persists between restarts
    # Format: "host_path:container_path"
    volumes:
      - ./data:/app/data

    # Health check: ping the gateway every 30 seconds
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

🔑 Step 5 — Environment Variables (.env)

Store all your API keys and secrets in a .env file. Docker Compose reads this file automatically — your keys never get baked into the image.

# AI provider API keys
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-openai-key

# Messaging integrations
TELEGRAM_BOT_TOKEN=1234567890:your-bot-token
DISCORD_BOT_TOKEN=your-discord-token

# Search tool
BRAVE_API_KEY=your-brave-key

Then reference them in your openclaw.json using the $VARIABLE_NAME syntax — OpenClaw substitutes them automatically at runtime:

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "apiKey": "$ANTHROPIC_API_KEY"  // reads from .env
  },
  "memory": {
    "type": "sqlite",
    "path": "/app/data/agent.db"   // inside the mounted volume
  },
  "gateway": {
    "host": "0.0.0.0",             // must be 0.0.0.0 inside Docker
    "port": 8080
  }
}

🚀 Step 6 — Build and Run

With your files in place, starting OpenClaw in Docker is a single command.

1. Navigate to your project folder

   $ cd my-openclaw

2. Build the Docker image and start the container

   $ docker compose up --build
   # You'll see the build output, then OpenClaw starting up.
   # Press Ctrl+C to stop.

   The first run takes a minute to download the base image and install OpenClaw. Subsequent starts are instant.

3. Run in the background (detached mode)

   Add -d to run the container in the background so it doesn't occupy your terminal:

   $ docker compose up -d
   ✓ Container openclaw-agent  Started

4. Verify it's running

   $ docker compose ps
   NAME               STATUS          PORTS
   openclaw-agent     running (healthy)   0.0.0.0:8080->8080/tcp

   Your OpenClaw gateway is now reachable at http://localhost:8080.

🔌 How Volumes & Networking Work

Understanding the relationship between your computer and the container makes troubleshooting much easier.

⌨️ Essential Docker Commands

A quick reference for everything you'll need day to day.

🔄 Updating OpenClaw in Docker

Keeping OpenClaw up to date is clean and simple with Docker.

1. Stop the running container

   $ docker compose down

2. Rebuild the image with the latest OpenClaw version

   $ docker compose build --no-cache

   The --no-cache flag forces a fresh install rather than using a cached layer — this ensures you get the latest version of OpenClaw from npm.

3. Start back up

   $ docker compose up -d

   Your data is preserved because it lives in the ./data volume on your machine, not inside the container.

🦙 Using a Local LLM with Docker

Running Ollama alongside OpenClaw? Here's how to wire them together.

When both OpenClaw and Ollama run in Docker, they're on the same internal network. Use the service name ollama as the hostname instead of localhost:

version: '3.9'

services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    restart: unless-stopped
    volumes:
      - ollama_data:/root/.ollama   # persists downloaded models
    # Uncomment below for NVIDIA GPU support:
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]

  openclaw:
    build: .
    container_name: openclaw-agent
    restart: unless-stopped
    ports:
      - "8080:8080"
    env_file: .env
    volumes:
      - ./data:/app/data
    depends_on:
      - ollama               # wait for Ollama to start first

volumes:
  ollama_data:

Then in your openclaw.json, point to Ollama using the service name:

"llm": {
  "provider": "ollama",
  "model": "llama3.1:8b",
  "baseUrl": "http://ollama:11434"  // "ollama" = the service name above
}

After starting with docker compose up -d, pull a model into the running Ollama container:

$ docker compose exec ollama ollama pull llama3.1:8b

🔧 Common Docker Problems & Fixes