clawpool

CLI tool to manage OpenClaw container instances on a local Docker host (Mac Mini + Colima).

Each instance gets its own Web Dashboard with an auto-generated auth token — no Telegram or external accounts required.

Prerequisites

brew install colima docker bun

# Start Colima (first time)
colima start --cpu 8 --memory 12 --disk 100 --vm-type vz

# Auto-start on boot
brew services start colima

Install

# Via bunx (no install needed)
bunx @linkclaw/clawpool list

# Or install globally
npm i -g @linkclaw/clawpool
clawpool list

Usage

clawpool create <name> [--telegram-token <token>] [-p <port>] [-e KEY=VAL ...]
clawpool list [--json]
clawpool start <name>
clawpool stop <name>
clawpool restart <name>
clawpool delete <name> [--purge]
clawpool rename <old_name> <new_name>
clawpool config <name> [--telegram-token <token>] [-e KEY=VAL ...]
clawpool logs <name> [-f]
clawpool status <name>
clawpool shell <name>
clawpool image [set <image> | show]

Quick Start

# 1. Create an instance — dashboard URL is printed automatically
clawpool create alpha

# 2. Add another with extra env vars
clawpool create beta -e "OPENAI_API_KEY=sk-..."

# 3. Optionally attach Telegram
clawpool create gamma --telegram-token "123456:AAH..."

# 4. List all instances with dashboard URLs
clawpool list

# 5. View logs
clawpool logs alpha -f

# 6. Clean up
clawpool delete beta --purge

How It Works

• Dashboard: Each instance exposes OpenClaw's built-in Web UI. Auth token is auto-generated and shown in clawpool list.
• Config: ~/.clawpool/config.json stores instance metadata.
• Containers: Each instance runs as claw-<name> with --restart unless-stopped.
• Volumes: Data persisted in Docker named volumes (claw-<name>-data mounted at /home/claw).
• Ports: Auto-assigned starting from 18789 with 20-port spacing (OpenClaw requirement), or manually specified with -p.
• Telegram: Optional — pass --telegram-token to enable Telegram bot integration via long-polling.

Config File

Stored at ~/.clawpool/config.json:

{
  "image": "openclaw:latest",
  "next_port": 18829,
  "instances": {
    "alpha": {
      "name": "alpha",
      "port": 18789,
      "gateway_token": "abc123...",
      "status": "running",
      "container_id": "a1b2c3...",
      "volume": "claw-alpha-data",
      "env": { "OPENAI_API_KEY": "sk-..." },
      "created_at": "2026-03-19T10:00:00Z"
    }
  }
}

Host Config Inheritance

When creating or restarting an instance, clawpool automatically merges settings from the host machine's OpenClaw installation (if present) into each container:

• ~/.openclaw/openclaw.json — model providers, default model, env vars, and other settings are inherited. Gateway-specific settings (gateway, meta) are excluded and managed by clawpool per-instance.
• ~/.openclaw/agents/main/agent/auth-profiles.json — OAuth auth profiles (e.g. openai-codex) are copied into each container, enabling provider access without per-instance login.

If OpenClaw is not installed on the host, instances start with a minimal config (gateway auth only). You can then configure providers via environment variables:

clawpool create alpha -e "ANTHROPIC_API_KEY=sk-ant-..." -e "OPENAI_API_KEY=sk-..."

Reusing auth profiles from another machine

If you want to copy auth profiles from a remote OpenClaw installation:

# On the machine where OpenClaw is logged in:
cat ~/.openclaw/agents/main/agent/auth-profiles.json

# Copy the output to the clawpool host:
mkdir -p ~/.openclaw/agents/main/agent
# paste into ~/.openclaw/agents/main/agent/auth-profiles.json

clawpool will pick up the file on the next create or restart.

Environment

| Variable | Purpose | |---|---| | CLAWPOOL_DIR | Override config directory (default: ~/.clawpool) |