Deploy OpenClaw with Docker in 15 Minutes

Set up a secure, containerized AI agent with Docker isolation. Learn proper sandbox configuration, security hardening, and production deployment.
·
7 min read
·
Mark
·
AI Agent

Problem: AI Agents Need Secure Isolation

You want to run an AI agent that can execute commands and manage files, but giving an AI direct access to your system is risky. One hallucinated command could damage your environment.

You'll learn:

  • How to deploy OpenClaw in Docker for isolation
  • Configure secure sandbox environments
  • Set up production-grade agent deployment
  • Manage permissions and security boundaries

Time: 15 min | Level: Intermediate

Why Docker Matters for OpenClaw

OpenClaw solves security concerns by running all execution inside a Docker container. When the agent creates files or runs scripts, everything happens in isolation—protecting your host system even if the AI makes mistakes.

Common deployment challenges:

  • AI agents need system access to be useful
  • Direct host access creates security risks
  • Managing dependencies across environments
  • Isolating multi-agent workflows

Docker provides:

  • Container isolation for tool execution
  • Controlled workspace access
  • Network restrictions by default
  • Resource limits and monitoring

Solution

Step 1: Install Prerequisites

# Check Docker and Compose versions
docker --version  # Need Docker 20.10+
docker compose version  # Need Compose v2

# Verify Node.js (for custom skills development)
node --version  # Need Node 22+

Expected: Docker 20.10+, Compose v2.x, Node 22.x

If missing:

Step 2: Clone and Run Setup

# Clone official repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Run automated Docker setup
./docker-setup.sh

What this does:

  • Builds the gateway image
  • Runs onboarding wizard
  • Configures authentication
  • Starts containers via Compose
  • Generates gateway token

During setup, choose:

  1. Model Provider: Anthropic (Claude 4.5 recommended for best reasoning)
  2. Gateway Mode: Local (for personal use)
  3. Channels: Skip initially, add later

Step 3: Verify Gateway is Running

# Check container status
docker compose ps

# View logs
docker compose logs openclaw-gateway -f

Expected output:

openclaw-gateway-1  running  0.0.0.0:18789->18789/tcp

Access Control UI:

# Open browser interface
docker compose run --rm openclaw-cli dashboard --no-open

Copy the tokenized URL and open it in your browser.

If connection fails:

  • Error: "unauthorized": Get fresh token with command above
  • Port conflict: Change port in docker-compose.yml (line ~15)

Step 4: Configure Agent Sandbox (Critical)

The gateway runs in Docker, but you need a second layer of isolation for tool execution:

# Build sandbox image
./scripts/sandbox-setup.sh

Edit config file:

# Open config in container
docker compose exec openclaw-gateway vi ~/.openclaw/config/gateway.json

Add sandbox configuration:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent",
        "workspaceAccess": "none",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "network": "none",
          "user": "1000:1000",
          "readOnlyRoot": true,
          "memory": "1g",
          "cpus": 1,
          "pidsLimit": 256
        },
        "prune": {
          "idleHours": 24,
          "maxAgeDays": 7
        }
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["exec", "read", "write", "edit"],
        "deny": ["browser", "gateway", "nodes"]
      }
    }
  }
}

Why these settings:

  • network: "none" — No internet access from sandbox (blocks data exfiltration)
  • readOnlyRoot: true — Prevents filesystem tampering
  • memory: "1g" — Caps resource usage
  • pidsLimit: 256 — Prevents fork bombs

Restart gateway:

docker compose restart openclaw-gateway

Step 5: Add Communication Channel (Optional)

For remote access via Telegram:

# Login to messaging platform
docker compose run --rm openclaw-cli channels login

# For Telegram bot (get token from @BotFather)
docker compose run --rm openclaw-cli channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Approve pairing:

# List pending devices
docker compose run --rm openclaw-cli devices list

# Approve your device
docker compose run --rm openclaw-cli devices approve <requestId>

Verification

Test basic functionality:

# Send test message via CLI
docker compose run --rm openclaw-cli message send \
  --target "control-ui" \
  --message "List files in workspace"

Expected: Agent responds with workspace contents, execution happens inside sandbox container.

Check sandbox isolation:

# This should show separate container running
docker ps | grep openclaw-sandbox

# Inspect sandbox workspace
docker compose exec openclaw-gateway ls -la ~/.openclaw/sandboxes/

Production Hardening

Resource Limits

Update docker-compose.yml:

services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

Persistent Storage

Mount workspace on host:

# Set before running setup
export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/openclaw-data:/home/node/data:rw"

./docker-setup.sh

Install Build Tools

For agents that need development tools:

# Set packages before build
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq build-essential python3"

./docker-setup.sh

Common packages:

  • Media processing: ffmpeg imagemagick
  • Development: build-essential python3 golang
  • Networking: curl wget netcat-openbsd

Advanced: Multi-Agent Configuration

For running multiple agents with different permission levels:

{
  "agents": {
    "defaults": {
      "sandbox": { "mode": "non-main" }
    },
    "list": [
      {
        "id": "personal",
        "sandbox": {
          "workspaceAccess": "rw"
        },
        "tools": {
          "sandbox": {
            "tools": {
              "allow": ["exec", "read", "write", "browser"]
            }
          }
        }
      },
      {
        "id": "readonly-analyst",
        "sandbox": {
          "workspaceAccess": "ro"
        },
        "tools": {
          "sandbox": {
            "tools": {
              "allow": ["read"],
              "deny": ["exec", "write", "browser"]
            }
          }
        }
      }
    ]
  }
}

Use cases:

  • Personal agent: Full access for your work
  • Team agent: Read-only for shared analysis
  • Public agent: Severely restricted for demos

Common Issues and Fixes

Permission Errors (EACCES)

Symptom: Error: EACCES: permission denied

Fix:

# Container runs as uid 1000, match host permissions
sudo chown -R 1000:1000 ~/.openclaw

Network Access in Sandbox

Symptom: Package installs fail in sandbox

Fix: Add network access to sandbox config:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "network": "bridge",  // Changed from "none"
          "dns": ["1.1.1.1", "8.8.8.8"]
        }
      }
    }
  }
}

Security note: Only enable network access when necessary, as it reduces isolation.

OAuth Redirect Issues

Symptom: OAuth callback fails in headless setup

Fix: Copy the full redirect URL from the error and paste it back into the wizard:

# URL will look like:
# http://127.0.0.1:1455/auth/callback?code=...

Container Auto-Recreation

Symptom: Warning about container recreation

Fix: This is normal when config changes. To force recreation:

# Recreate specific sandbox
docker compose run --rm openclaw-cli \
  openclaw sandbox recreate --agent-id <agentId>

What You Learned

  • Docker provides two-layer isolation: gateway container + sandbox containers
  • Network isolation (network: "none") is critical for security
  • Workspace access levels control what the agent can modify
  • Tool policies let you restrict dangerous operations
  • Multi-agent routing enables different permission levels

Security limitations:

  • Prompt injection remains a risk (malicious web content can trick the AI)
  • Sandbox escapes are theoretically possible (though rare with proper configuration)
  • Always treat AI agents like untrusted users

Not covered:

  • Running OpenClaw as a systemd service (see Gateway & Ops docs)
  • Custom skill development
  • Production monitoring and logging

Next steps:

Security Best Practices

What This Deployment Protects Against

✅ Filesystem damage: Sandbox runs in isolated container
✅ Resource exhaustion: CPU/memory limits enforced
✅ Network attacks: Default network isolation
✅ Privilege escalation: Non-root container user

What You Still Need to Manage

⚠️ API key leakage: Don't share gateway tokens
⚠️ Prompt injection: Validate agent actions before execution
⚠️ Model costs: Monitor API usage
⚠️ Data privacy: Don't send sensitive data to cloud models

Production Checklist

  • Gateway token stored securely (not in git)
  • Sandbox network set to "none" unless required
  • Resource limits configured (memory, cpus)
  • Tool allowlist configured (deny dangerous tools)
  • Workspace mounted with appropriate permissions
  • Log rotation enabled
  • Backup strategy for ~/.openclaw/ directory
  • Monitoring alerts for container failures

Architecture Diagram

┌────────────────────────────────────────────┐
│             Host Machine                   │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │   Docker: OpenClaw Gateway           │  │
│  │   (Node.js, port 18789)              │  │
│  │                                      │  │
│  │   Manages:                           │  │
│  │   • Authentication                   │  │
│  │   • Session routing                  │  │
│  │   • Channel connections              │  │
│  └───────────┬──────────────────────────┘  │
│              │                             │
│              │ Spawns on demand            │
│              ▼                             │
│  ┌──────────────────────────────────────┐  │
│  │   Docker: Agent Sandbox              │  │
│  │   (isolated per agent/session)       │  │
│  │                                      │  │
│  │   Executes:                          │  │
│  │   • Shell commands                   │  │
│  │   • File operations                  │  │
│  │   • Python/Node scripts              │  │
│  │                                      │  │
│  │   Restrictions:                      │  │
│  │   • No network (network: none)       │  │
│  │   • Read-only root filesystem        │  │
│  │   • 1GB memory limit                 │  │
│  │   • Non-root user (1000:1000)        │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  Volumes:                                  │
│  ~/.openclaw/        → Config & sessions   │
│  ~/.openclaw/workspace → Agent workspace   │
│  ~/.openclaw/sandboxes → Sandbox storage   │
└────────────────────────────────────────────┘

Quick Reference Commands

# Start/stop
docker compose up -d openclaw-gateway
docker compose down

# View logs
docker compose logs openclaw-gateway -f

# Access shell
docker compose exec openclaw-gateway bash

# Get dashboard URL
docker compose run --rm openclaw-cli dashboard --no-open

# List active sandboxes
docker ps | grep openclaw-sandbox

# Rebuild after config changes
docker compose restart openclaw-gateway

# Update OpenClaw
cd openclaw && git pull
./docker-setup.sh  # Rebuilds image

# Clean up old containers
docker compose run --rm openclaw-cli sandbox prune

# Health check
docker compose exec openclaw-gateway \
  node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"