From 2cf82c357e7e293ea56d39e0b8d814f12573c904 Mon Sep 17 00:00:00 2001 From: Shadow Date: Tue, 17 Feb 2026 14:27:52 -0600 Subject: [PATCH] Docs: expand multi-agent routing --- docs/channels/discord.md | 1 + docs/channels/telegram.md | 1 + docs/channels/whatsapp.md | 1 + docs/concepts/multi-agent.md | 151 ++++++++++++++++++++++++++++++++++- 4 files changed, 152 insertions(+), 2 deletions(-) diff --git a/docs/channels/discord.md b/docs/channels/discord.md index 05b8003e953..336157e0472 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -708,5 +708,6 @@ High-signal Discord fields: - [Pairing](/channels/pairing) - [Channel routing](/channels/channel-routing) +- [Multi-agent routing](/concepts/multi-agent) - [Troubleshooting](/channels/troubleshooting) - [Slash commands](/tools/slash-commands) diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index 28a9c227f9d..7e1d95d2feb 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -757,4 +757,5 @@ Telegram-specific high-signal fields: - [Pairing](/channels/pairing) - [Channel routing](/channels/channel-routing) +- [Multi-agent routing](/concepts/multi-agent) - [Troubleshooting](/channels/troubleshooting) diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md index d14e38eb5d9..88251bd8454 100644 --- a/docs/channels/whatsapp.md +++ b/docs/channels/whatsapp.md @@ -433,4 +433,5 @@ High-signal WhatsApp fields: - [Pairing](/channels/pairing) - [Channel routing](/channels/channel-routing) +- [Multi-agent routing](/concepts/multi-agent) - [Troubleshooting](/channels/troubleshooting) diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md index 8f4c05a7cc8..069fcfb6367 100644 --- a/docs/concepts/multi-agent.md +++ b/docs/concepts/multi-agent.md @@ -19,7 +19,7 @@ An **agent** is a fully scoped brain with its own: Auth profiles are **per-agent**. Each agent reads from its own: -``` +```text ~/.openclaw/agents//agent/auth-profiles.json ``` @@ -70,6 +70,55 @@ Verify with: openclaw agents list --bindings ``` +## Quick start + + + + +Use the wizard or create workspaces manually: + +```bash +openclaw agents add coding +openclaw agents add social +``` + +Each agent gets its own workspace with `SOUL.md`, `AGENTS.md`, and optional `USER.md`, plus a dedicated `agentDir` and session store under `~/.openclaw/agents/`. + + + + + +Create one account per agent on your preferred channels: + +- Discord: one bot per agent, enable Message Content Intent, copy each token. +- Telegram: one bot per agent via BotFather, copy each token. +- WhatsApp: link each phone number per account. + +```bash +openclaw channels login --channel whatsapp --account work +``` + +See channel guides: [Discord](/channels/discord), [Telegram](/channels/telegram), [WhatsApp](/channels/whatsapp). + + + + + +Add agents under `agents.list`, channel accounts under `channels..accounts`, and connect them with `bindings` (examples below). + + + + + +```bash +openclaw gateway restart +openclaw agents list --bindings +openclaw channels status --probe +``` + + + + ## Multiple agents = multiple people, multiple personalities With **multiple agents**, each `agentId` becomes a **fully isolated persona**: @@ -133,6 +182,7 @@ Bindings are **deterministic** and **most-specific wins**: 7. channel-level match (`accountId: "*"`) 8. fallback to default agent (`agents.list[].default`, else first list entry, default: `main`) +If multiple bindings match in the same tier, the first one in config order wins. If a binding sets multiple match fields (for example `peer` + `guildId`), all specified fields are required (`AND` semantics). ## Multiple accounts / phone numbers @@ -148,7 +198,104 @@ multiple phone numbers without mixing sessions. - `binding`: routes inbound messages to an `agentId` by `(channel, accountId, peer)` and optionally guild/team ids. - Direct chats collapse to `agent::` (per-agent “main”; `session.mainKey`). -## Example: two WhatsApps → two agents +## Platform examples + +### Discord bots per agent + +Each Discord bot account maps to a unique `accountId`. Bind each account to an agent and keep allowlists per bot. + +```json5 +{ + agents: { + list: [ + { id: "main", workspace: "~/.openclaw/workspace-main" }, + { id: "coding", workspace: "~/.openclaw/workspace-coding" }, + ], + }, + bindings: [ + { agentId: "main", match: { channel: "discord", accountId: "default" } }, + { agentId: "coding", match: { channel: "discord", accountId: "coding" } }, + ], + channels: { + discord: { + groupPolicy: "allowlist", + accounts: { + default: { + token: "DISCORD_BOT_TOKEN_MAIN", + guilds: { + "123456789012345678": { + channels: { + "222222222222222222": { allow: true, requireMention: false }, + }, + }, + }, + }, + coding: { + token: "DISCORD_BOT_TOKEN_CODING", + guilds: { + "123456789012345678": { + channels: { + "333333333333333333": { allow: true, requireMention: false }, + }, + }, + }, + }, + }, + }, + }, +} +``` + +Notes: + +- Invite each bot to the guild and enable Message Content Intent. +- Tokens live in `channels.discord.accounts..token` (default account can use `DISCORD_BOT_TOKEN`). + +### Telegram bots per agent + +```json5 +{ + agents: { + list: [ + { id: "main", workspace: "~/.openclaw/workspace-main" }, + { id: "alerts", workspace: "~/.openclaw/workspace-alerts" }, + ], + }, + bindings: [ + { agentId: "main", match: { channel: "telegram", accountId: "default" } }, + { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } }, + ], + channels: { + telegram: { + accounts: { + default: { + botToken: "123456:ABC...", + dmPolicy: "pairing", + }, + alerts: { + botToken: "987654:XYZ...", + dmPolicy: "allowlist", + allowFrom: ["tg:123456789"], + }, + }, + }, + }, +} +``` + +Notes: + +- Create one bot per agent with BotFather and copy each token. +- Tokens live in `channels.telegram.accounts..botToken` (default account can use `TELEGRAM_BOT_TOKEN`). + +### WhatsApp numbers per agent + +Link each account before starting the gateway: + +```bash +openclaw channels login --channel whatsapp --account personal +openclaw channels login --channel whatsapp --account biz +``` `~/.openclaw/openclaw.json` (JSON5):