OpenClaw AI Deployment Guide

Choosing a Deployment Model

OpenClaw supports a spectrum of deployment targets — from a single Docker container on a $5 VPS to multi-region Kubernetes clusters with autoscaling. The right choice depends on your traffic profile, budget, team size, and compliance requirements.

Production Readiness Checklist

Before going live, work through this checklist to avoid common production pitfalls:

• ✅ Store all secrets (API keys, DB passwords) in a secrets manager — never in environment files or container images
• ✅ Set OPENCLAW_LOG_LEVEL=INFO and enable JSON log format for structured log ingestion
• ✅ Configure a Prometheus scrape endpoint and set up error-rate and latency alerts
• ✅ Enable distributed tracing (tracing.enabled: true) with a sampler configured for your volume
• ✅ Use a read-only filesystem for the container; mount only the required volumes
• ✅ Pin the agent image to a specific digest or semantic version tag — never :latest in production
• ✅ Run a load test at ≥1.5× peak expected concurrency before launch

Sections

Quick Deploy with Docker

docker run -d \
  --name openclaw \
  -e OPENAI_API_KEY=sk-... \
  -e OPENCLAW_PROVIDER=openai \
  -v ~/.openclaw:/root/.openclaw \
  -p 8080:8080 \
  ghcr.io/openclaw-ai/openclaw:latest

Critical Environment Variables

The following environment variables control all runtime behaviour. Set them in your container definition, Helm values.yaml, or cloud provider secrets manager — never in source code or committed files.

Production Docker Compose

For a single-server production deployment, use this hardened Docker Compose file. It adds resource limits, a health check, a non-root user, and a read-only filesystem:

version: "3.9"
services:
  openclaw:
    image: ghcr.io/openclaw-ai/openclaw:2.4.1   # pin to exact version
    container_name: openclaw
    restart: unless-stopped
    read_only: true
    tmpfs: [/tmp]
    user: "1000:1000"
    ports:
      - "127.0.0.1:8080:8080"    # bind to localhost only; Nginx handles TLS
      - "127.0.0.1:9090:9090"    # Prometheus metrics
    environment:
      OPENCLAW_PROVIDER: openai
      OPENCLAW_LOG_FORMAT: json
      OPENCLAW_LOG_LEVEL: INFO
    secrets:
      - openclaw_openai_key
    volumes:
      - openclaw_data:/root/.openclaw
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 2G

secrets:
  openclaw_openai_key:
    environment: OPENAI_API_KEY

volumes:
  openclaw_data:

Health & Readiness Endpoints

OpenClaw exposes two HTTP endpoints for container orchestrators and load balancers:

Networking & Reverse Proxy

Always place OpenClaw behind a TLS-terminating reverse proxy in production. Below is a minimal Nginx configuration with rate-limiting:

upstream openclaw {
    server 127.0.0.1:8080;
    keepalive 16;
}

server {
    listen 443 ssl http2;
    server_name agents.example.com;

    ssl_certificate     /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    limit_req_zone $binary_remote_addr zone=api:10m rate=30r/m;
    limit_req zone=api burst=10 nodelay;

    location / {
        proxy_pass         http://openclaw;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_read_timeout 300s;   # long-running agents need extended timeout
    }
}

Horizontal Scaling Strategies

OpenClaw agents are stateless by design — all persistent state is stored externally (Redis for short-term memory, PostgreSQL or Pinecone for long-term memory). This makes horizontal scaling straightforward:

• Docker Swarm / ECS: Scale the service replica count; use an Application Load Balancer to distribute incoming task requests.
• Kubernetes HPA: Autoscale on openclaw_agent_active (custom metric via Prometheus Adapter) or CPU/memory. A target of 70% concurrent agent capacity works well as an initial threshold.
• Queue-based scaling: Decouple task submission (HTTP) from execution (workers) using RabbitMQ or AWS SQS. Scale workers independently from the API layer.
• Read replicas: If using PostgreSQL for memory, add read replicas for memory retrieval queries to reduce load on the primary.

Secrets Management

Never store API keys in environment files, container images, or source code. Use these provider-native secrets managers:

Zero-Downtime Upgrades

To upgrade OpenClaw without dropping in-flight agent tasks:

1. Put new version in maintenance tag (e.g., :2.5.0-rc1) alongside current :2.4.1.
2. Use a blue/green deployment: route 5% of traffic to new version, monitor error rates in Grafana for 15 minutes.
3. Enable drain_timeout: 300 in openclaw.yaml — running agents complete before the pod terminates.
4. Shift traffic to 100% once error rate is stable; decommission old pods.
5. Run openclaw db migrate after all pods are on new version if a schema migration is pending.