英文 Multi-agent
- 原始链接：https://docs.openclaw.ai/concepts/multi-agent
- 来源章节：4. 官方文档：核心概念、模型与安全
- 来源小节：无
- 抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/concepts/multi-agent
- 抓取时间：2026-04-05 13:47:10
- 状态：ok
中文内容
多代理路由 - OpenClaw
[OpenClaw主页！图片1：深色徽标！图片2：深色徽标](http://docs.openclaw.ai/)
英语
搜索...
⌘K
搜索...
导航
多代理
多代理路由
基础知识
会话和内存
多代理
消息和传递
在此页面上
- 多代理路由
- 什么是“单一代理”？
- 路径（快速地图）
- 单代理模式（默认）
- 代理助手
- 快速入门
- 多个代理 = 多人，多重人格
- 跨agent QMD内存搜索
- 一个 WhatsApp 号码，多人（DM 分割）
- 路由规则（消息如何选择代理）
- [多个账户/电话号码](http://docs.openclaw.ai/concepts/multi-agent#multip
le-账户-%2F-电话号码）
- 概念
- 平台示例
- 每个代理的 Discord 机器人
- 每个代理的 Telegram 机器人
- 每个代理的 WhatsApp 号码
- 示例：WhatsApp 日常聊天 + Telegram 深度工作
- 示例：同一通道，一个对等 Opus
- 家庭代理绑定到 WhatsApp 群组
- 每代理沙箱和工具配置
- 相关
多代理
多代理路由
多代理路由
目标：多个_隔离_代理（单独的工作区 + agentDir + 会话），以及一个正在运行的网关中的多个渠道帐户（例如两个 WhatsApp）。入站通过绑定路由至代理。
什么是“单一代理人”？
代理是一个具有完整范围的大脑，拥有自己的：
- 工作区（文件、AGENTS.md/SOUL.md/USER.md、本地注释、角色规则）。
- 状态目录 (
agentDir) 用于身份验证配置文件、模型注册表和每个代理配置。 - 会话存储（聊天历史记录+路由状态）位于
~/.openclaw/agents/<agentId>/sessions下。
身份验证配置文件是每个代理。每个代理读取自己的内容：
〜/.openclaw/agents/<agentId>/agent/auth-profiles.jsonsessions_history 在这里也是更安全的跨会话调用路径：它返回一个有界的、经过清理的视图，而不是原始转录转储。助手召回剥离了思考标签、<relevant-memories> 脚手架、纯文本工具调用 XML 负载（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 和截断的工具调用块）、降级的工具调用脚手架、泄露ASCII/全角模型控制令牌，以及编辑/截断之前格式错误的 MiniMax 工具调用 XML。主代理凭据不自动共享。切勿跨代理重复使用“agentDir”（它会导致身份验证/会话冲突）。如果您想共享信用，请将“auth-profiles.json”复制到其他代理的“agentDir”中。技能从每个代理工作区以及共享根（例如“~/.openclaw/skills”）加载，然后在配置时按有效代理技能白名单进行过滤。使用“agents.defaults.skills”作为共享基线，使用“agents.list[].skills”来替换每个代理。请参阅技能：每个代理与共享 和 [技能：代理技能白名单](http://do
cs.openclaw.ai/tools/skills#agent-skill-allowlists）。网关可以并排托管一个代理（默认）或多个代理。工作空间注意：每个代理的工作空间是默认的cwd，而不是硬沙箱。相对路径在工作区内部解析，但除非启用沙箱，否则绝对路径可以到达其他主机位置。请参阅沙盒。
路径（快速地图）
- 配置：
~/.openclaw/openclaw.json（或OPENCLAW_CONFIG_PATH） - 状态目录：
~/.openclaw（或OPENCLAW_STATE_DIR） - 工作空间：
~/.openclaw/workspace（或~/.openclaw/workspace-<agentId>） - 代理目录：
~/.openclaw/agents/<agentId>/agent（或agents.list[].agentDir） - 会话：
~/.openclaw/agents/<agentId>/sessions
单代理模式（默认）
如果您什么都不做，OpenClaw 会运行一个代理：
agentId默认为main。- 会话的密钥为“agent:main:”。
- 工作空间默认为
~/.openclaw/workspace（或设置OPENCLAW_PROFILE时为~/.openclaw/workspace-<profile>）。 - 状态默认为
~/.openclaw/agents/main/agent。
代理帮手
使用代理向导添加新的隔离代理：
openclaw 特工添加工作然后添加“绑定”（或让向导执行此操作）以路由入站消息。验证方式：
openclaw 代理列表--绑定
快速启动
1
创建每个代理工作区
使用向导或手动创建工作区：
openclaw 特工添加编码
OpenClaw 特工添加社交功能每个代理都有自己的工作区，其中包含“SOUL.md”、“AGENTS.md”和可选的“USER.md”，以及“~/.openclaw/agents/”下的专用“agentDir”和会话存储。
2
创建频道帐户
在您的首选渠道上为每个代理创建一个帐户：
- Discord：每个代理一个机器人，启用消息内容意图，复制每个令牌。
- Telegram：每个代理一个机器人，通过 BotFather 复制每个令牌。
- WhatsApp：链接每个帐户的每个电话号码。
openclaw 频道登录 --channel Whatsapp --account work请参阅频道指南：Discord、Telegram、WhatsApp。
3
添加代理、帐户和绑定
在“agents.list”下添加代理，在“channels..accounts”下添加通道帐户，并将它们与“绑定”连接（示例如下）。
4
重启并验证
openclaw网关重启
openclaw 代理列表--绑定
openclaw 通道状态--probe
多个代理=多个人，多个性格
对于 多个代理，每个 agentId 都成为一个 完全隔离的角色：
- 不同的电话号码/帐户（每个通道“accountId”）。
- 不同的个性（每个代理工作区文件，如“AGENTS.md”和“SOUL.md”）。
- 单独的身份验证+会话（除非明确启用，否则不会发生串扰）。
这使得多人可以共享一台网关服务器，同时保持他们的人工智能“大脑”和数据隔离。
跨代理 QMD 内存搜索
如果一个代理应搜索另一代理的 QMD 会话记录，请在“agents.list[].memorySearch.qmd.extraCollections”下添加额外的集合。仅当每个代理都应继承相同的共享脚本集合时，才使用“agents.defaults.memorySearch.qmd.extraCollections”。
{
代理商：{
默认值：{
工作区：“〜/工作区/主”，
内存搜索：{
qmd：{
extraCollections: [{ 路径: "~/agents/family/sessions", 名称: "family-sessions" }],
},
},
},
列表：[
{
id：“主要”，
工作区：“〜/工作区/主”，
内存搜索：{
qmd：{
extraCollections: [{ path: "notes" }], // 解析工作区 -> 名为“notes-main”的集合
},
},
},
{ id: "family", 工作空间: "~/workspaces/family" },
],
},
内存：{
后端：“qmd”，
qmd: { includeDefaultMemory: false },
},
}额外的集合路径可以在代理之间共享，但当路径位于代理工作区之外时，集合名称保持明确。工作区内的路径保持代理范围，因此每个代理保留自己的转录搜索集。
一个 WhatsApp 号码，多人（DM 分割）
您可以将不同的 WhatsApp DM 路由至不同的客服人员，同时保留在一个 WhatsApp 帐户。将发件人 E.164（如“+15551234567”）与“peer.kind: "direct"”进行匹配。回复仍然来自相同的 WhatsApp 号码（没有每个客服人员的发件人身份）。重要细节：直接聊天会崩溃到客服人员的主会话密钥，因此真正的隔离需要每人一个客服人员。示例：
{
代理商：{
列表：[
{ id: "alex", 工作空间: "~/.openclaw/workspace-alex" },
{ id: "mia", 工作空间: "~/.openclaw/workspace-mia" },
],
},
绑定：[
{
代理 ID：“亚历克斯”，
匹配：{ 频道：“whatsapp”，对等：{ kind：“直接”，id：“+15551230001” } }，
},
{
代理 ID：“mia”，
匹配：{ 频道：“whatsapp”，对等：{ kind：“直接”，id：“+15551230002” } }，
},
],
频道：{
微信：{
dmPolicy: "白名单",
允许来自: ["+15551230001", "+15551230002"],
},
},
}注意事项：
- DM 访问控制是针对每个 WhatsApp 帐户（配对/白名单），而不是针对每个客服人员。
- 对于共享组，将组绑定到一个代理或使用广播组。
路由规则（消息如何选择代理）
绑定是确定性和最具体的胜利：
peer匹配（精确的 DM/组/频道 ID） 2.parentPeer匹配（线程继承） 3.guildId + Roles（Discord角色路由）guildId(Discord) 5.teamId(Slack)- 频道的
accountId匹配 - 渠道级匹配(
accountId: "*") - 回退到默认代理（
agents.list[].default，否则第一个列表条目，默认：main）
如果同一层中有多个绑定匹配，则配置顺序中的第一个绑定获胜。如果绑定设置多个匹配字段（例如“peer”+“guildId”），则所有指定字段都是必需的（“AND”语义）。重要的帐户范围详细信息：
- 省略
accountId的绑定仅匹配默认帐户。 - 使用
accountId: "*"在所有帐户之间进行通道范围的回退。 - 如果您稍后为具有显式帐户 ID 的同一代理添加相同的绑定，OpenClaw 会将现有的仅限通道绑定升级为帐户范围的绑定，而不是重复它。
多个帐户/电话号码
支持多个帐户的渠道（例如 WhatsApp）使用“accountId”来识别每次登录。每个“accountId”都可以路由到不同的代理，因此一台服务器可以托管多个电话号码，而无需混合会话。如果在省略“accountId”时希望使用通道范围的默认帐户，请设置“channels..defaultAccount”（可选）。未设置时，OpenClaw 如果存在则回退到“默认”，否则使用第一个配置的帐户 ID（已排序）。支持此模式的常见渠道包括：
whatsapp、telegram、discord、slack、signal、imessageirc、line、googlechat、mattermost、matrix、nextcloud-talkbluebubbles、zalo、zalouser、nostr、feishu
概念
agentId：一个“大脑”（工作区、每个代理身份验证、每个代理会话存储）。accountId：一个渠道帐户实例（例如 WhatsApp 帐户“个人”与“商业”）。 *“绑定”：通过“(channel, accountId,peer)”和可选的公会/团队 ID 将入站消息路由到“agentId”。- 直接聊天折叠为“agent::”（每个代理“main”；“session.mainKey”）。
平台示例
每个代理的 Discord 机器人数
每个 Discord 机器人帐户都会映射到一个唯一的“accountId”。将每个帐户绑定到代理并保留每个机器人的许可名单。
{
代理商：{
列表：[
{ id: "main", 工作空间: "~/.openclaw/workspace-main" },
{ id: "编码", 工作区: "~/.openclaw/workspace-coding" },
],
},
绑定：[
{ agentId: "main", match: { 频道: "discord", accountId: "default" } },
{ agentId: "coding", match: { 频道: "discord", accountId: "coding" } },
],
频道：{
不和谐：{
组策略：“允许名单”，
帐户：{
默认值：{
令牌：“DISCORD_BOT_TOKEN_MAIN”，
行会：{
“123456789012345678”：{
频道：{
"222222222222222222": { 允许: true, requireMention: false },
},
},
},
},
编码：{
令牌：“DISCORD_BOT_TOKEN_CODING”，
行会：{
“123456789012345678”：{
频道：{
"333333333333333333": { 允许: true, requireMention: false },
},
},
},
},
},
},
},
}注意事项：
- 邀请每个机器人加入公会并启用消息内容意图。
- 令牌位于
channels.discord.accounts.<id>.token中（默认帐户可以使用DISCORD_BOT_TOKEN）。
每个代理的 Telegram 机器人
{
代理商：{
列表：[
{ id: "main", 工作空间: "~/.openclaw/workspace-main" },
{ id: "alerts", 工作区: "~/.openclaw/workspace-alerts" },
],
},
绑定：[
{ agentId: "main", match: { channel: "telegram", accountId: "default" } },
{ agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
],
频道：{
电报：{
帐户：{
默认值：{
botToken: "123456:ABC...",
dmPolicy：“配对”，
},
警报：{
botToken: "987654:XYZ...",
dmPolicy: "白名单",
允许来自：[“tg：123456789”]，
},
},
},
},
}注意事项：
- 使用 BotFather 为每个代理创建一个机器人并复制每个令牌。
- 令牌位于
channels.telegram.accounts.<id>.botToken中（默认帐户可以使用TELEGRAM_BOT_TOKEN）。
每个客服人员的 WhatsApp 号码
在启动网关之前链接每个帐户：
openclaw频道登录--频道whatsapp--个人帐户
openclaw 频道登录 --channel Whatsapp --account biz~/.openclaw/openclaw.json (JSON5):
{
代理商：{
列表：[
{
id：“家”，
默认值：真，
名称：“家”，
工作空间：“~/.openclaw/workspace-home”，
agentDir: "~/.openclaw/agents/home/agent",
},
{
id：“工作”，
名称：“工作”，
工作区：“~/.openclaw/workspace-work”，
agentDir: "~/.openclaw/agents/work/agent",
},
],
},
// 确定性路由：第一个匹配获胜（最具体的第一个）。
绑定：[
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
{ agentId: "工作", match: { 频道: "whatsapp", accountId: "biz" } },
// 可选的每个对等覆盖（例如：将特定组发送到工作代理）。
{
代理 ID：“工作”，
匹配：{
频道：“whatsapp”，
accountId: "个人",
同伴: { kind: "group", id: "1203630...@g.us" },
},
},
],
// 默认情况下关闭：必须显式启用代理间消息传递+列入白名单。
工具：{
代理到代理：{
启用：假，
允许：[“家”，“工作”]，
},
},
频道：{
微信：{
帐户：{
个人：{
// 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/personal
// authDir: "~/.openclaw/credentials/whatsapp/personal",
},
业务：{
// 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/biz
// authDir: "~/.openclaw/credentials/whatsapp/biz",
},
},
},
},
}
示例：WhatsApp 日常聊天 + Telegram 深度工作
按渠道拆分：将 WhatsApp 路由至快速日常代理，将 Telegram 路由至 Opus 代理。
{
代理商：{
列表：[
{
id：“聊天”，
名称：《每一天》，
工作区：“~/.openclaw/workspace-chat”，
型号：“anthropic/claude-sonnet-4-6”，
},
{
id：“作品”，
名称：《深度工作》，
工作区：“~/.openclaw/workspace-opus”，
型号：“anthropic/claude-opus-4-6”，
},
],
},
绑定：[
{ agentId: "聊天", 匹配: { 频道: "whatsapp" } },
{ agentId: "opus", match: { 频道: "telegram" } },
],
}注意事项：
- 如果您的频道有多个帐户，请将
accountId添加到绑定（例如{ channel: "whatsapp", accountId: "personal" }）。 - 要将单个 DM/组路由到 Opus，同时保持其余的聊天，请为该对等点添加“match.peer”绑定；同行比赛总是胜过频道范围内的规则。
示例：同一通道，Opus 的一个对等点
将 WhatsApp 保留在快速代理上，但将一条 DM 路由至 Opus：
{
代理商：{
列表：[
{
id：“聊天”，
名称：《每一天》，
工作区：“~/.openclaw/workspace-chat”，
型号：“anthropic/claude-sonnet-4-6”，
},
{
id：“作品”，
名称：《深度工作》，
工作区：“~/.openclaw/workspace-opus”，
型号：“anthropic/claude-opus-4-6”，
},
],
},
绑定：[
{
代理 ID：“作品”，
匹配：{ 频道：“whatsapp”，对等：{ kind：“直接”，id：“+15551234567” } }，
},
{ agentId: "聊天", 匹配: { 频道: "whatsapp" } },
],
}对等绑定总是获胜，因此请将它们置于通道范围规则之上。
家庭代理人绑定 WhatsApp 群组
将专门的家庭代理绑定到单个 WhatsApp 群组，并提供提及门控和更严格的工具策略：
{
代理商：{
列表：[
{
id：“家人”，
名称：“家人”，
工作空间：“~/.openclaw/workspace-family”，
身份：{名称：“家庭机器人”}，
群聊：{
提及模式：[“@family”，“@familybot”，“@Family Bot”]，
},
沙箱：{
模式：“全部”，
范围：“代理”，
},
工具：{
允许：[
“执行”，
“读”，
“会话列表”，
“会话历史记录”，
“会话_发送”，
“sessions_spawn”，
“会话状态”，
],
拒绝：[“写入”，“编辑”，“apply_patch”，“浏览器”，“画布”，“节点”，“cron”]，
},
},
],
},
绑定：[
{
代理ID：“家人”，
匹配：{
频道：“whatsapp”，
同伴: { kind: "group", id: "120363999999999999@g.us" },
},
},
],
}注意事项：
- 工具允许/拒绝列表是工具，而不是技能。如果技能需要运行二进制文件，请确保允许“exec”并且二进制文件存在于沙箱中。
- 为了更严格的控制，请设置
agents.list[].groupChat.mentionPatterns并保持为频道启用组白名单。
每个代理的沙箱和工具配置
每个代理可以有自己的沙箱和工具限制：
{
代理商：{
列表：[
{
id：“个人”，
工作空间：“~/.openclaw/workspace-personal”，
沙箱：{
mode: "off", // 个人代理没有沙箱
},
// 无工具限制 - 所有工具均可用
},
{
id：“家人”，
工作空间：“~/.openclaw/workspace-family”，
沙箱：{
mode: "all", // 始终沙箱化
range: "agent", // 每个代理一个容器
泊坞窗：{
// 容器创建后可选的一次性设置
setupCommand: "apt-get update && apt-get install -y git curl",
},
},
工具：{
allowed: ["read"], // 只读取工具
deny: ["exec", "write", "edit", "apply_patch"], // 拒绝其他
},
},
],
},
}注意：“setupCommand”位于“sandbox.docker”下，并在容器创建时运行一次。当解析范围为“共享”时，每个代理的“sandbox.docker.*”覆盖将被忽略。好处：
- 安全隔离：限制不受信任代理使用的工具
- 资源控制：沙箱特定代理，同时将其他代理保留在主机上
- 灵活的政策：每个代理有不同的权限
注意：“tools.elevated”是全局并且基于发送者；它不可针对每个代理进行配置。如果您需要每个代理边界，请使用“agents.list[].tools”来拒绝“exec”。对于组定位，请使用“agents.list[].groupChat.mentionPatterns”，以便@mentions清晰地映射到预期的代理。有关详细示例，请参阅多代理沙箱和工具。
相关
- Channel Routing — 消息如何路由到代理
- 子代理 — 生成后台代理运行
- ACP Agents — 运行外部编码工具
- Presence — 代理的存在和可用性
- Session — 会话隔离和路由
⌘我