Running OpenClaw AI Agent in an Isolated Docker Environment

Project: OpenClaw Docker

Tech Stack: Docker, Docker Compose, bash scripting

Category: DevOps, AI Agent Infrastructure

Background

OpenClaw is an AI agent framework. The goal was to run it in an isolated Docker environment with the current working directory bound as a volume — so agent-generated outputs would persist on the host filesystem.

Challenge 1: Docker Compose v1 vs v2 Incompatibility

Problem: After setting up the entire Docker Compose configuration and a run.sh helper script, the first run failed:

./run.sh onboard
unknown flag: --rm
See 'docker --help'.

Root cause: The run.sh script used docker compose (v2 plugin syntax), but the machine only had docker-compose (v1 standalone binary). The v1 binary doesn't support some v2 flags.

Solution: Claude updated run.sh to auto-detect which compose command is available:

if docker compose version &>/dev/null 2>&1; then
    COMPOSE="docker compose"
elif command -v docker-compose &>/dev/null; then
    COMPOSE="docker-compose"
else
    echo "Error: neither 'docker compose' nor 'docker-compose' found"
    exit 1
fi

Also removed --no-deps from the onboard command — unnecessary and caused issues with v1.

Challenge 2: Volume Architecture Design

Problem: The agent needed access to workspace files (user's project) AND needed its own persistent config directory — these are different concerns.

Solution: Two separate mount points:

This keeps user files accessible to the agent while agent config persists between runs.

Challenge 3: Security Hardening

Problem: Running an AI agent in Docker with broad filesystem access is a security concern.

Solution:

• Capability drops: --cap-drop=ALL with only CHOWN, SETUID added back
• Token stored in .env (gitignored), not hardcoded
• .gitignore excludes .openclaw/ directory to prevent accidental credential commits
• Read-only bind for sensitive config paths

The Final Setup

./run.sh onboard   # First-time setup wizard
./run.sh start     # Start the gateway service
./run.sh cli       # Open interactive CLI session
./run.sh stop      # Stop all services

Key Learnings

• Always handle Docker Compose v1/v2 compatibility in scripts targeting mixed environments
• Separate volume mounts for workspace vs. config is a cleaner pattern than a single mount
• Auto-detection of available tools (which docker compose vs docker-compose) makes scripts more portable

Session Date: Early 2026 | Tool: OpenClaw AI Agent Framework