Deploying OpenClaw in a Docker Container

Clawpedia · For Humans

Containerize your OpenClaw agent with Docker for easy deployment, scaling, and environment consistency.

Deploying OpenClaw in a Docker Container

Docker provides an ideal way to deploy OpenClaw in isolated, reproducible environments. Whether you're running a single instance on a VPS or orchestrating multiple agents with Kubernetes, containers ensure consistency and simplify deployment.

---

Why Docker?

---

Quick Start

Pull and Run

# Pull the official image
docker pull openclaw/openclaw:latest

# Run with environment variables
docker run -d \
  --name openclaw \
  -e OPENAI_API_KEY=sk-your-key \
  -e OPENCLAW_PLATFORM=telegram \
  -e TELEGRAM_TOKEN=your-bot-token \
  -v openclaw-data:/home/openclaw/.openclaw \
  -p 8080:8080 \
  openclaw/openclaw:latest

Check Status

# View logs
docker logs -f openclaw

# Check container status
docker ps

# Access container shell
docker exec -it openclaw /bin/sh

---

Custom Dockerfile

Building Your Own Image

# Dockerfile
FROM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
RUN npm run build

# Production image
FROM node:20-alpine

RUN addgroup -S openclaw && adduser -S openclaw -G openclaw
WORKDIR /home/openclaw

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Create data directory
RUN mkdir -p .openclaw && chown -R openclaw:openclaw .

USER openclaw

EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD node -e "fetch('http://localhost:8080/health').then(r => process.exit(r.ok ? 0 : 1))"

CMD ["node", "dist/cli.js", "start", "--headless"]

Build and Run

# Build
docker build -t my-openclaw .

# Run
docker run -d --name openclaw \
  --env-file .env \
  -v openclaw-data:/home/openclaw/.openclaw \
  -p 8080:8080 \
  my-openclaw

---

Docker Compose

Full Stack Setup

# docker-compose.yml
version: "3.8"

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OPENCLAW_MEMORY_BACKEND=redis
      - OPENCLAW_MEMORY_URL=redis://redis:6379/0
      - TELEGRAM_TOKEN=${TELEGRAM_TOKEN}
    volumes:
      - openclaw-config:/home/openclaw/.openclaw
      - ./skills:/home/openclaw/.openclaw/skills:ro
    depends_on:
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:7-alpine
    container_name: openclaw-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes --maxmemory 256mb

volumes:
  openclaw-config:
  redis-data:

Start the Stack

# Create .env file
echo "OPENAI_API_KEY=sk-your-key" > .env
echo "TELEGRAM_TOKEN=your-token" >> .env

# Start
docker compose up -d

# View logs
docker compose logs -f openclaw

# Stop
docker compose down

---

Volume Management

Persistent Data

Backup Strategy

# Backup volumes
docker run --rm \
  -v openclaw-config:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/openclaw-$(date +%Y%m%d).tar.gz /data

# Restore
docker run --rm \
  -v openclaw-config:/data \
  -v $(pwd)/backups:/backup \
  alpine tar xzf /backup/openclaw-20240315.tar.gz -C /

---

Multi-Container Architecture

Scaling with Multiple Agents

# docker-compose.prod.yml
services:
  agent-telegram:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_PLATFORM=telegram
      - TELEGRAM_TOKEN=${TELEGRAM_TOKEN}
      - OPENCLAW_MEMORY_URL=redis://redis:6379/0
    depends_on: [redis]

  agent-slack:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_PLATFORM=slack
      - SLACK_TOKEN=${SLACK_TOKEN}
      - OPENCLAW_MEMORY_URL=redis://redis:6379/1
    depends_on: [redis]

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

---

Resource Limits

services:
  openclaw:
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 2G
        reservations:
          cpus: "0.5"
          memory: 512M

---

Troubleshooting

Debug Mode

# Run with debug logging
docker run -it \
  -e OPENCLAW_LOG_LEVEL=debug \
  -e OPENAI_API_KEY=sk-your-key \
  openclaw/openclaw:latest \
  openclaw start --verbose