Run OpenClaw with Docker: Complete Guide

Why Use Docker?

Docker simplifies OpenClaw deployment with:

Consistent environments - Same setup everywhere
Easy updates - Pull new images, restart
Isolation - Bot runs in its own container
Portability - Move between servers easily
Resource control - Limit CPU/memory usage

Prerequisites

VPS with at least 2GB RAM
Docker installed
Docker Compose (recommended)
Basic terminal knowledge

Step 1: Install Docker

Ubuntu/Debian

# Update packages
sudo apt update

# Install dependencies
sudo apt install -y ca-certificates curl gnupg

# Add Docker repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Verify Installation

docker --version
docker compose version

Step 2: Create Project Directory

mkdir -p /opt/openclaw-docker
cd /opt/openclaw-docker

Step 3: Create Docker Compose File

nano docker-compose.yml

version: '3.8'

services:
  openclaw:
    image: node:20-alpine
    container_name: openclaw
    restart: unless-stopped
    working_dir: /app
    volumes:
      - ./app:/app
      - ./data:/app/data
    env_file:
      - .env
    command: sh -c "npm install && npm start"
    mem_limit: 1g
    cpus: 1.5

  # Optional: PostgreSQL database
  postgres:
    image: postgres:15-alpine
    container_name: openclaw-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: openclaw
      POSTGRES_USER: openclaw
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  # Optional: Redis for caching/session storage
  redis:
    image: redis:7-alpine
    container_name: openclaw-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Step 4: Clone OpenClaw

git clone https://github.com/nicepkg/openclaw.git app

Step 5: Configure Environment

nano .env

# AI Configuration
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-api-key-here

# Discord Configuration
DISCORD_ENABLED=true
DISCORD_TOKEN=your-discord-token
DISCORD_PREFIX=!

# Telegram Configuration (optional)
TELEGRAM_ENABLED=false
TELEGRAM_TOKEN=

# Database (if using PostgreSQL)
DATABASE_URL=postgresql://openclaw:${DB_PASSWORD}@postgres:5432/openclaw
DB_PASSWORD=secure-password-here

# Bot Settings
BOT_NAME=OpenClaw
AI_TEMPERATURE=0.7
MAX_TOKENS=1000

# Redis (if using)
REDIS_URL=redis://redis:6379

Step 6: Start the Container

docker compose up -d

Check Status

docker compose ps
docker compose logs -f openclaw

Managing Your Container

View Logs

# All logs
docker compose logs openclaw

# Follow logs
docker compose logs -f openclaw

# Last 100 lines
docker compose logs --tail 100 openclaw

Restart

docker compose restart openclaw

Stop

docker compose down

Update

# Pull latest code
cd app
git pull

# Rebuild and restart
cd ..
docker compose down
docker compose up -d --build

Dockerfile (Alternative)

For custom builds, create a Dockerfile:

FROM node:20-alpine AS builder

WORKDIR /app
COPY app/package*.json ./
RUN npm ci

FROM node:20-alpine

WORKDIR /app

# Copy dependencies
COPY --from=builder /app/node_modules ./node_modules
COPY app/ .

# Create non-root user
RUN addgroup -S openclaw && adduser -S openclaw -G openclaw
RUN chown -R openclaw:openclaw /app
USER openclaw

ENV NODE_ENV=production

CMD ["npm", "start"]

Build and run:

docker build -t openclaw .
docker run -d --name openclaw --env-file .env openclaw

Resource Limits

Memory Limits

services:
  openclaw:
    mem_limit: 1g        # Hard limit
    mem_reservation: 512m # Soft limit

CPU Limits

services:
  openclaw:
    cpus: 1.5            # Limit to 1.5 CPUs
    cpu_shares: 1024     # Relative weight

Health Checks

Add health monitoring:

services:
  openclaw:
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Logging Configuration

services:
  openclaw:
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "5"

Auto-Restart on Boot

Docker Compose with restart: unless-stopped handles this. Alternatively:

# Enable Docker to start on boot
sudo systemctl enable docker

# Your containers will auto-start

Networking

Expose Ports (if needed)

services:
  openclaw:
    ports:
      - "3001:3001"  # Health check endpoint

Multiple Services

services:
  openclaw:
    networks:
      - bot-network

  redis:
    networks:
      - bot-network

networks:
  bot-network:
    driver: bridge

Backup and Restore

Backup Data

# Stop container
docker compose stop openclaw

# Backup data directory
tar -czf backup-$(date +%Y%m%d).tar.gz data/

# Backup PostgreSQL
docker compose exec -T postgres pg_dump -U openclaw openclaw > backup-db-$(date +%Y%m%d).sql

# Restart
docker compose start openclaw

Restore

docker compose stop openclaw
tar -xzf backup-20260129.tar.gz
docker compose start openclaw

Troubleshooting

Container won't start

# Check logs
docker compose logs openclaw

# Run interactively
docker compose run --rm openclaw sh

Permission issues

# Fix ownership
sudo chown -R 1000:1000 app/ data/

Memory issues

Increase limit in docker-compose.yml:

mem_limit: 2g

Network issues

# Check network
docker network ls
docker network inspect openclaw-docker_default

Production Tips

Use specific image tags - Not latest
Enable resource limits - Prevent runaway usage
Configure logging - Prevent disk fill
Use secrets - Not plain text env files
Regular backups - Automate with cron

Related Guides

Need Help?

Our setup service includes Docker configuration with best practices.