Phase 1 / Ep 03: Docker Containerized Installation —— Best Practices for Secure Isolation

🎯 Learning Objective: Use Docker Compose to run OpenClaw, and understand the importance of containerized isolation for Agent security.

1. Why is Docker Recommended?

The OpenClaw Agent possesses powerful tool capabilities—it can execute Shell commands, read and write files, and access the network. This also means that if misconfigured, the Agent might perform unintended operations on your system.

Docker provides process-level isolation: The Agent can only access directories you explicitly mount to it. Even if an error occurs, it will not affect the host system.

graph TD
    subgraph Host["🖥️ macOS Host"]
        DockerEngine["Docker Engine"]
        Volume["~/.openclaw-data\nData Volume"]
        Env[".env File\nAPI Keys"]
    end

    subgraph Container["📦 OpenClaw Container"]
        Gateway["Gateway Process"]
        Agent["Agent Runtime"]
        Node["Node.js v22"]
    end

    DockerEngine --> Container
    Volume -.->|"Mount /data"| Container
    Env -.->|"Inject"| Container
    Gateway -->|"HTTPS"| LLM["Anthropic API"]
    Gateway -->|"HTTPS"| TG["Telegram API"]

2. Minimal docker-compose.yml

Create a dedicated directory and write the configuration file:

mkdir ~/openclaw-docker && cd ~/openclaw-docker

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw-agent
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./data:/root/.openclaw     # Data persistence
      - ./workspace:/workspace     # Agent workspace
    ports:
      - "3377:3377"                # Dashboard (optional)
    healthcheck:
      test: ["CMD", "openclaw", "status"]
      interval: 60s
      timeout: 10s
      retries: 3

3. Environment Variable Management

Create a .env file to store sensitive configurations:

# .env (Never commit this to Git!)
ANTHROPIC_API_KEY=sk-ant-api03-xxxx
OPENCLAW_LLM_PROVIDER=anthropic
OPENCLAW_LLM_MODEL=claude-sonnet-4-20250514

⚠️ Security Reminder: Add .env to .gitignore. Never hardcode API Keys into configuration files.

4. Startup and Verification

# Start (run in background)
docker compose up -d

# View logs
docker compose logs -f openclaw

# Enter container interactively
docker compose exec openclaw openclaw status
docker compose exec openclaw openclaw doctor

5. Volume Mount Strategy

6. Container vs. Native Installation Decision

Next Episode Preview: In Ep 04, we will install the Linux version of OpenClaw in a UTM virtual machine to achieve kernel-level isolation—this is the highest security level solution, suitable for running Agents with full permissions.