npm package: @linkclaw/clawpool
Description: CLI tool to manage OpenClaw container instances with Web Dashboard
Latest version: 0.2.3

# 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

```bash
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

```bash
# 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

```bash
# 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`:

```jsonc
{
  "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:

```bash
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:

```bash
# 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`) |