Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
112 lines
12 KiB
JSON
Executable File
112 lines
12 KiB
JSON
Executable File
{
|
||
"title": "Multi-Agent Routing",
|
||
"content": "Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.\n\n## What is “one agent”?\n\nAn **agent** is a fully scoped brain with its own:\n\n* **Workspace** (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules).\n* **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.\n* **Session store** (chat history + routing state) under `~/.openclaw/agents/<agentId>/sessions`.\n\nAuth profiles are **per-agent**. Each agent reads from its own:\n\nMain agent credentials are **not** shared automatically. Never reuse `agentDir`\nacross agents (it causes auth/session collisions). If you want to share creds,\ncopy `auth-profiles.json` into the other agent's `agentDir`.\n\nSkills are per-agent via each workspace’s `skills/` folder, with shared skills\navailable from `~/.openclaw/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).\n\nThe Gateway can host **one agent** (default) or **many agents** side-by-side.\n\n**Workspace note:** each agent’s workspace is the **default cwd**, not a hard\nsandbox. Relative paths resolve inside the workspace, but absolute paths can\nreach other host locations unless sandboxing is enabled. See\n[Sandboxing](/gateway/sandboxing).\n\n* Config: `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`)\n* State dir: `~/.openclaw` (or `OPENCLAW_STATE_DIR`)\n* Workspace: `~/.openclaw/workspace` (or `~/.openclaw/workspace-<agentId>`)\n* Agent dir: `~/.openclaw/agents/<agentId>/agent` (or `agents.list[].agentDir`)\n* Sessions: `~/.openclaw/agents/<agentId>/sessions`\n\n### Single-agent mode (default)\n\nIf you do nothing, OpenClaw runs a single agent:\n\n* `agentId` defaults to **`main`**.\n* Sessions are keyed as `agent:main:<mainKey>`.\n* Workspace defaults to `~/.openclaw/workspace` (or `~/.openclaw/workspace-<profile>` when `OPENCLAW_PROFILE` is set).\n* State defaults to `~/.openclaw/agents/main/agent`.\n\nUse the agent wizard to add a new isolated agent:\n\nThen add `bindings` (or let the wizard do it) to route inbound messages.\n\n## Multiple agents = multiple people, multiple personalities\n\nWith **multiple agents**, each `agentId` becomes a **fully isolated persona**:\n\n* **Different phone numbers/accounts** (per channel `accountId`).\n* **Different personalities** (per-agent workspace files like `AGENTS.md` and `SOUL.md`).\n* **Separate auth + sessions** (no cross-talk unless explicitly enabled).\n\nThis lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.\n\n## One WhatsApp number, multiple people (DM split)\n\nYou can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: \"dm\"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).\n\nImportant detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.\n\n* DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.\n* For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).\n\n## Routing rules (how messages pick an agent)\n\nBindings are **deterministic** and **most-specific wins**:\n\n1. `peer` match (exact DM/group/channel id)\n2. `guildId` (Discord)\n3. `teamId` (Slack)\n4. `accountId` match for a channel\n5. channel-level match (`accountId: \"*\"`)\n6. fallback to default agent (`agents.list[].default`, else first list entry, default: `main`)\n\n## Multiple accounts / phone numbers\n\nChannels that support **multiple accounts** (e.g. WhatsApp) use `accountId` to identify\neach login. Each `accountId` can be routed to a different agent, so one server can host\nmultiple phone numbers without mixing sessions.\n\n* `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).\n* `accountId`: one channel account instance (e.g. WhatsApp account `\"personal\"` vs `\"biz\"`).\n* `binding`: routes inbound messages to an `agentId` by `(channel, accountId, peer)` and optionally guild/team ids.\n* Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent “main”; `session.mainKey`).\n\n## Example: two WhatsApps → two agents\n\n`~/.openclaw/openclaw.json` (JSON5):\n\n## Example: WhatsApp daily chat + Telegram deep work\n\nSplit by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.\n\n* If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: \"whatsapp\", accountId: \"personal\" }`).\n* To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over channel-wide rules.\n\n## Example: same channel, one peer to Opus\n\nKeep WhatsApp on the fast agent, but route one DM to Opus:\n\nPeer bindings always win, so keep them above the channel-wide rule.\n\n## Family agent bound to a WhatsApp group\n\nBind a dedicated family agent to a single WhatsApp group, with mention gating\nand a tighter tool policy:\n\n* Tool allow/deny lists are **tools**, not skills. If a skill needs to run a\n binary, ensure `exec` is allowed and the binary exists in the sandbox.\n* For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep\n group allowlists enabled for the channel.\n\n## Per-Agent Sandbox and Tool Configuration\n\nStarting with v2026.1.6, each agent can have its own sandbox and tool restrictions:\n\nNote: `setupCommand` lives under `sandbox.docker` and runs once on container creation.\nPer-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `\"shared\"`.\n\n* **Security isolation**: Restrict tools for untrusted agents\n* **Resource control**: Sandbox specific agents while keeping others on host\n* **Flexible policies**: Different permissions per agent\n\nNote: `tools.elevated` is **global** and sender-based; it is not configurable per agent.\nIf you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.\nFor group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.\n\nSee [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.",
|
||
"code_samples": [
|
||
{
|
||
"code": "~/.openclaw/agents/<agentId>/agent/auth-profiles.json",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Then add `bindings` (or let the wizard do it) to route inbound messages.\n\nVerify with:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "## Multiple agents = multiple people, multiple personalities\n\nWith **multiple agents**, each `agentId` becomes a **fully isolated persona**:\n\n* **Different phone numbers/accounts** (per channel `accountId`).\n* **Different personalities** (per-agent workspace files like `AGENTS.md` and `SOUL.md`).\n* **Separate auth + sessions** (no cross-talk unless explicitly enabled).\n\nThis lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.\n\n## One WhatsApp number, multiple people (DM split)\n\nYou can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: \"dm\"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).\n\nImportant detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.\n\nExample:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Notes:\n\n* DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.\n* For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).\n\n## Routing rules (how messages pick an agent)\n\nBindings are **deterministic** and **most-specific wins**:\n\n1. `peer` match (exact DM/group/channel id)\n2. `guildId` (Discord)\n3. `teamId` (Slack)\n4. `accountId` match for a channel\n5. channel-level match (`accountId: \"*\"`)\n6. fallback to default agent (`agents.list[].default`, else first list entry, default: `main`)\n\n## Multiple accounts / phone numbers\n\nChannels that support **multiple accounts** (e.g. WhatsApp) use `accountId` to identify\neach login. Each `accountId` can be routed to a different agent, so one server can host\nmultiple phone numbers without mixing sessions.\n\n## Concepts\n\n* `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).\n* `accountId`: one channel account instance (e.g. WhatsApp account `\"personal\"` vs `\"biz\"`).\n* `binding`: routes inbound messages to an `agentId` by `(channel, accountId, peer)` and optionally guild/team ids.\n* Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent “main”; `session.mainKey`).\n\n## Example: two WhatsApps → two agents\n\n`~/.openclaw/openclaw.json` (JSON5):",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "## Example: WhatsApp daily chat + Telegram deep work\n\nSplit by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Notes:\n\n* If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: \"whatsapp\", accountId: \"personal\" }`).\n* To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over channel-wide rules.\n\n## Example: same channel, one peer to Opus\n\nKeep WhatsApp on the fast agent, but route one DM to Opus:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Peer bindings always win, so keep them above the channel-wide rule.\n\n## Family agent bound to a WhatsApp group\n\nBind a dedicated family agent to a single WhatsApp group, with mention gating\nand a tighter tool policy:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Notes:\n\n* Tool allow/deny lists are **tools**, not skills. If a skill needs to run a\n binary, ensure `exec` is allowed and the binary exists in the sandbox.\n* For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep\n group allowlists enabled for the channel.\n\n## Per-Agent Sandbox and Tool Configuration\n\nStarting with v2026.1.6, each agent can have its own sandbox and tool restrictions:",
|
||
"language": "unknown"
|
||
}
|
||
],
|
||
"headings": [
|
||
{
|
||
"level": "h2",
|
||
"text": "What is “one agent”?",
|
||
"id": "what-is-“one-agent”?"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Paths (quick map)",
|
||
"id": "paths-(quick-map)"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Single-agent mode (default)",
|
||
"id": "single-agent-mode-(default)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Agent helper",
|
||
"id": "agent-helper"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Multiple agents = multiple people, multiple personalities",
|
||
"id": "multiple-agents-=-multiple-people,-multiple-personalities"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "One WhatsApp number, multiple people (DM split)",
|
||
"id": "one-whatsapp-number,-multiple-people-(dm-split)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Routing rules (how messages pick an agent)",
|
||
"id": "routing-rules-(how-messages-pick-an-agent)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Multiple accounts / phone numbers",
|
||
"id": "multiple-accounts-/-phone-numbers"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Concepts",
|
||
"id": "concepts"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Example: two WhatsApps → two agents",
|
||
"id": "example:-two-whatsapps-→-two-agents"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Example: WhatsApp daily chat + Telegram deep work",
|
||
"id": "example:-whatsapp-daily-chat-+-telegram-deep-work"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Example: same channel, one peer to Opus",
|
||
"id": "example:-same-channel,-one-peer-to-opus"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Family agent bound to a WhatsApp group",
|
||
"id": "family-agent-bound-to-a-whatsapp-group"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Per-Agent Sandbox and Tool Configuration",
|
||
"id": "per-agent-sandbox-and-tool-configuration"
|
||
}
|
||
],
|
||
"url": "llms-txt#multi-agent-routing",
|
||
"links": []
|
||
} |