# multi-clawd — agent setup guide

> **You are an AI agent** (an OpenClaw assistant, Claude Code, or similar)
> and your human has asked you to install multi-clawd on this machine.
> Follow this guide exactly. Where it says **ASK YOUR HUMAN**, stop and ask —
> one step genuinely needs them.

## Ground rules (non-negotiable)

1. **Back up before touching config:** `cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-multiclawd-$(date +%Y%m%d)`
   (the wizard also makes its own backup, but yours costs nothing).
2. **Merge, never overwrite** — if you ever edit `openclaw.json` by hand, use a
   JSON read-modify-write (jq/python), not a rewrite from memory. Prefer
   letting the wizard do the merging.
3. **Never print, log, or echo token values.** Not even partially.
4. **Do not change the model failover chain (primary/fallbacks) unless your
   human explicitly asks.** Registration and routing are separate decisions.
5. Report everything you changed (files + config keys) when you finish.

## 1. Preflight

```bash
openclaw --version    # need >= 2026.8.1
which claude          # Claude Code CLI must be on PATH
node --version
```

If OpenClaw is older than 2026.8.1, stop and tell your human to upgrade first.
If `claude` is missing: `npm install -g @anthropic-ai/claude-code`.

## 2. Install + configure — one wizard does it

Since v1.2 the package ships its own CLI; it replaces every manual step that
used to live in this guide (plugin install flags, config merging, watchdog
scheduling, doctor runs):

```bash
npx @drakon-systems/multi-clawd update   # installs (or updates) the OpenClaw plugin —
                                         # right flags, offers the gateway restart, doctor after
npx @drakon-systems/multi-clawd setup    # guided wizard: accounts, token storage, pool, watchdog
```

For a raw plugin install, run `openclaw plugins install clawhub:@drakon-systems/multi-clawd`.
ClawHub is the source OpenClaw trusts; npm installs show a source caution.
For existing installs, prefer the guarded `multi-clawd update` command rather than a raw source retry.

**Raw-install fallback boundary:** use npm only after positively identifying a
ClawHub availability failure (for example, package/version not found or registry
unreachable), or an older OpenClaw CLI explicitly rejecting the `clawhub:` spec
as unsupported. An old CLI version alone is not evidence of that incompatibility.
**Stop; do not retry through npm** for moderation, security, integrity, trust,
signature or policy failures, unknown errors, cancellation or interruption.
These stops take precedence even if availability diagnostics appeared first.
If the cause is unclear, stop and investigate; do not switch sources or restart
the gateway after a failed or interrupted install.

Only after the availability/unsupported-spec check above, an unversioned fresh
install may use `openclaw plugins install @drakon-systems/multi-clawd --pin`.
For a versioned install, retain the same selected exact target: if ClawHub was
`clawhub:@drakon-systems/multi-clawd@X.Y.Z`, the permitted npm retry is
`openclaw plugins install @drakon-systems/multi-clawd@X.Y.Z --pin`.
Replace `X.Y.Z` with that same exact version; never drop it, re-resolve latest,
or substitute a different version during fallback.

**If this machine has used multi-clawd before, install the CLI globally once,
first:**

```bash
npm i -g @drakon-systems/multi-clawd@latest
```

The package is two halves: the **plugin** (serves turns, updated by `update`)
and the **CLI** (`doctor`, `chain`, `setup` — updated only by the global
install). `update` does not upgrade the command running it. Since v1.6.0 the
command warns when it lags, but that warning ships *in the command*, so an
older one stays silent — we found three machines running current plugins
behind stale commands. A stale CLI reports stale diagnostics about a current
plugin, so do this before you trust anything `doctor` tells you. Check with
`multi-clawd version`: both halves should match.

Run the wizard WITH your human present — it pauses on decisions that are
theirs (which accounts, pool or not, where tokens live). The wizard merges
`openclaw.json` non-destructively with a backup, **never overwrites an
account that already works** (v1.2.3), and challenges suspicious-looking
secret refs instead of silently accepting them.

**From source** (contributors, or ahead of a published release):

```bash
git clone https://github.com/Drakon-Systems-Ltd/multi-clawd.git /tmp/multi-clawd
cd /tmp/multi-clawd && npm install && npm run build
openclaw plugins install "$(pwd)"
```

(Plain `npm install`, NOT `--omit=dev` — the build needs `tsc` from
devDependencies. Registry installs ship prebuilt `dist/`.)

## 3. Second-account login — **ASK YOUR HUMAN**

The sign-in itself is the one step you can never do: it opens a browser and
needs your human's credentials. What you CAN do is launch the right flow:

```bash
npx @drakon-systems/multi-clawd login claw2
```

`login` knows what each configured account IS (native → default dir/keychain;
isolated dir → same flow inside that dir, created 0700 if missing;
token-file/secret-ref → `claude setup-token` with the right target) and
verifies afterwards **which email** is signed in — no more wrong-account
mix-ups. It never captures, stores, or prints token values, and neither do
you. `login` with no argument lists the accounts in plain English.

Token hygiene (preferred over a plaintext token file): store the token in a
secret manager and reference it as
`"oauthTokenRef": { "source": "exec", "provider": "<your-secret-provider>", "id": "op://Vault/Item/field" }`
— resolved through the gateway's configured secret providers, so no token
sits on disk. Sources are mutually exclusive per account. (A vault copy that
diffs from a file by one trailing newline is fine — resolution trims it.)

## 4. Verify

```bash
npx @drakon-systems/multi-clawd doctor --probe   # health check + one live end-to-end turn
npx @drakon-systems/multi-clawd explain          # the whole setup in plain English
```

Fix every ❌ the doctor reports before telling your human you're done. If you
want to see the raw registration evidence, the gateway journal shows:

```
[multi-clawd] register() pass — config source: ..., accounts: N
[multi-clawd] registered N backend(s)+provider(s): ...
```

For a manual probe, keep it contained (file-redirected — never into a live
chat):

```bash
openclaw agent --agent main --session-key agent:main:mc-setup-probe \
  --model claw2/claude-fable-5 --json \
  --message "Reply with exactly this line and nothing else: MC_SETUP_OK. Do not use any tools." \
  > /tmp/mc-setup-probe.out 2>&1
grep -o "MC_SETUP_OK" /tmp/mc-setup-probe.out | head -1
```

## 5. The pool (proactive rotation) — **ASK YOUR HUMAN**

The wizard offers this; here's what you're offering so you can explain it.
One backend id (`clawd`) fronts all their Claude accounts; each launch runs
on the first account that is not nearly maxed out (live `rate_limit_event`
health; hand over BEFORE the limit error, return home when the window
resets, sticky selection so mid-conversation flapping doesn't happen).

The config the wizard writes, for reference — only touch it by hand if the
wizard genuinely can't run:

- Accounts: `plugins.entries["multi-clawd"].config.accounts` =
  `[ { "id": "claw1", "label": "Main Claude", "native": true }, { "id": "claw2", "configDir": "~/.claw2", ... } ]`
  (native = default config dir / OS keychain; a native account gets NO
  configDir and NO token — on macOS the keychain is only consulted when
  `CLAUDE_CONFIG_DIR` is unset).
- Pool: `plugins.entries["multi-clawd"].config.pool` = `{ "id": "clawd", "accounts": ["claw1", "claw2"] }`
- Models: `agents.defaults.models["clawd/claude-fable-5"]` = `{}` (plus any
  other pooled models your human wants agents to use).

## 6. Routing — **ASK YOUR HUMAN**

Ask whether they want `clawd/claude-fable-5` (pool) or `claw2/claude-fable-5`
(single account) in the failover chain — typical: pool as primary with
non-Anthropic providers as fallbacks, or first fallback after their current
primary — or left unrouted for manual/per-agent use. Apply only what they
choose, same merge discipline, and confirm the final chain back to them.

## 7. Known issue you should warn about

On OpenClaw ≤ 2026.7.1, an **idle** plugin CLI backend can be silently
evicted by core's scoped harness activation
([openclaw#107408](https://github.com/openclaw/openclaw/issues/107408),
fixed in [openclaw#108110](https://github.com/openclaw/openclaw/pull/108110)
and included in OpenClaw 2026.8.1). Symptom: `Unknown CLI backend: claw2`
while the model catalog still lists it. A gateway restart always heals it.

Since v1.1 the **setup wizard schedules the bundled eviction watchdog
itself** (systemd/launchd, every ~5 min, restart → probe → confirm) and the
doctor verifies the watchdog's target script exists — so if you used the
wizard, this is already handled. Only mention it if your human declined the
watchdog while a backend will sit idle in a fallback chain.

## 8. Report

Tell your human: what was installed and where, the exact config keys
added, the backup file path, the doctor/probe result, and the routing
decision applied. `multi-clawd explain` output makes a good closing
summary. You're done. 🦞