Docker Deployment

+15 Mana ✨
OpenClaw Docker Deployment(DOCUMENTATION)

Introduction

Docker is the most common way to deploy OpenClaw to production. A containerized deployment provides consistent environments, easy updates, and volume-based persistence for agent data. This lesson covers the Dockerfile, volume configuration, and orchestration patterns.

Key Concepts

  • Docker Image: The official openclaw/gateway image contains the gateway binary and all dependencies.
  • Volume Mounts: Persistent storage for configuration, agent workspaces, sessions, and credentials at ~/.openclaw.
  • Port Mapping: The gateway listens on port 18789 by default, which must be exposed to receive webhook callbacks.
  • Container Orchestration: Using Docker Compose or Kubernetes to manage gateway lifecycle, restarts, and health checks.

Real World Context

A SaaS company deploys OpenClaw in a Docker container on their existing infrastructure. The container runs alongside their application services, sharing the same Docker network. Agent data persists in a named volume, surviving container updates. Docker Compose handles automatic restarts and log management.

Deep Dive

The simplest Docker deployment uses a single command:

bash
docker run -d \
  --name openclaw-gateway \
  --restart unless-stopped \
  -p 18789:18789 \
  -v openclaw-data:/root/.openclaw \
  -e ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} \
  -e TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN} \
  openclaw/gateway:latest

This starts the gateway in detached mode with automatic restart, maps port 18789, mounts a named volume for persistent data, and passes environment variables for API keys. The named volume openclaw-data ensures agent workspaces and sessions survive container restarts and updates.

For more complex setups, use Docker Compose:

yaml
version: '3.8'
services:
  gateway:
    image: openclaw/gateway:latest
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/root/.openclaw
      - ./config/openclaw.json:/root/.openclaw/openclaw.json:ro
    environment:
      - ANTHROPIC_API_KEY
      - TELEGRAM_BOT_TOKEN
      - DISCORD_BOT_TOKEN
    healthcheck:
      test: ["CMD", "openclaw", "status"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  openclaw-data:

This Compose file adds a health check that verifies the gateway is responsive every 30 seconds. The configuration file is mounted read-only from the host, allowing version-controlled config.

Common Pitfalls

  1. Forgetting the volume mount — Without a persistent volume, all agent data (sessions, memory, credentials) is lost when the container restarts.
  2. Using latest tag in production — The latest tag can change unexpectedly. Pin to a specific version like openclaw/gateway:2026.2.19.

Best Practices

  1. Pin image versions — Use explicit version tags for reproducible deployments.
  2. Use Docker secrets for credentials — Avoid passing API keys as plain environment variables. Use Docker secrets or a secrets manager.

Summary

  • Docker is the standard deployment method for OpenClaw gateways
  • Named volumes persist agent data across container restarts and updates
  • Docker Compose adds health checks, service management, and configuration mounting
  • Always pin image versions and use secrets management for credentials
  • The health check uses openclaw status to verify gateway responsiveness
✓ Completed