From 7360abad8ed5bbdf2e1c9fdb7be98dc2932a2df3 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 22:44:07 +0100 Subject: [PATCH] docs: update multi-agent guide --- README.md | 2 +- docs/multi-agent.md | 46 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 848666e45..23d1827b9 100644 --- a/README.md +++ b/README.md @@ -453,5 +453,5 @@ Thanks to all clawtributors: azade-c andranik-sahakyan adamgall jalehman jarvis-medmatic mneves75 regenrek tobiasbischoff MSch obviyus dbhurley Asleep123 Iamadig imfing kitze nachoiacovino VACInc cash-echo-bot claude kiranjd pcty-nextgen-service-account minghinmatthewlam - ngutman onutc oswalpalash snopoke ManuelHettich loukotal hugobarauna AbhisekBasu1 + ngutman onutc oswalpalash snopoke ManuelHettich loukotal hugobarauna AbhisekBasu1 emanuelst

diff --git a/docs/multi-agent.md b/docs/multi-agent.md index c0253346c..004fd1bf4 100644 --- a/docs/multi-agent.md +++ b/docs/multi-agent.md @@ -9,6 +9,52 @@ status: active Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple provider accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings. +## What is “one agent”? + +An **agent** is a fully scoped brain with its own: + +- **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules). +- **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config. +- **Session store** (chat history + routing state) under `~/.clawdbot/agents//sessions`. + +The Gateway can host **one agent** (default) or **many agents** side-by-side. + +### Single-agent mode (default) + +If you do nothing, Clawdbot runs a single agent: + +- `agentId` defaults to **`main`**. +- Sessions are keyed as `agent:main:`. +- Workspace defaults to `~/clawd` (or `~/clawd-` when `CLAWDBOT_PROFILE` is set). +- State defaults to `~/.clawdbot/agents/main/agent`. + +## Multiple agents = multiple people, multiple personalities + +With **multiple agents**, each `agentId` becomes a **fully isolated persona**: + +- **Different phone numbers/accounts** (per provider `accountId`). +- **Different personalities** (per-agent workspace files like `AGENTS.md` and `SOUL.md`). +- **Separate auth + sessions** (no cross-talk unless explicitly enabled). + +This lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated. + +## Routing rules (how messages pick an agent) + +Bindings are **deterministic** and **most-specific wins**: + +1. `peer` match (exact DM/group/channel id) +2. `guildId` (Discord) +3. `teamId` (Slack) +4. `accountId` match for a provider +5. provider-level match (`accountId: "*"`) +6. fallback to `routing.defaultAgentId` (default: `main`) + +## Multiple accounts / phone numbers + +Providers that support **multiple accounts** (e.g. WhatsApp) use `accountId` to identify +each login. Each `accountId` can be routed to a different agent, so one server can host +multiple phone numbers without mixing sessions. + ## Concepts - `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).