广播组
Note
状态: 实验性。旧版 WhatsApp 广播数组仍受支持。
概述¶
代理组线程使用顶层 broadcast 配置,在同一条入站消息上运行多个代理。每个代理都在自己的会话中运行。频道限定条目可以通过提及选择参与者,并允许有限数量的后续轮次,以便代理可以基于同级回复构建。
频道允许列表和群组激活规则仍然适用。对于 Discord、Slack 和 Telegram 上的限定条目,显式提及任何已配置参与者都可以满足房间的提及门控,即使该参与者不是常规路由代理。旧版 WhatsApp 条目保留其现有准入行为。
实时 WhatsApp QA 通道包含 whatsapp-broadcast-group-fanout,它验证一条被提及的群组消息可以由两个已配置代理产生不同的可见回复。
配置¶
代理组线程¶
使用形如 "<channel>:<peerId>" 的键,例如
"discord:123456789"、"slack:C0123"、"telegram:-100123" 或
"whatsapp:1203@g.us"。值可以是代理 ID 数组或严格对象:
{
agents: {
ownership: "explicit",
entries: {
reviewer: {
name: "Reviewer",
groupChat: { mentionPatterns: ["@reviewer\\b"] },
},
writer: {
name: "Writer",
groupChat: { mentionPatterns: ["@writer\\b"] },
},
},
},
bindings: [{ agentId: "reviewer", match: { channel: "telegram" } }],
broadcast: {
"telegram:-100123": {
agents: ["reviewer", "writer"],
mentionGating: true,
maxRounds: 2,
maxTurns: 4,
},
},
}
常规频道路由仍然需要一个代理;上述绑定在群组分发前选择
Reviewer 进行准入。在房间被其频道配置允许后,发送 @reviewer @writer Review
this draft。两个参与者都可以回复初始消息,并在预算内通过一轮后续轮次添加新内容。发送 @writer 可仅为初始轮次选择
Writer。
| 对象字段 | 默认值 | 约定 |
|---|---|---|
agents |
必需 | 已配置的代理 ID;最多 16 个参与者。 |
mentionGating |
true |
选择被显式提及的参与者;如果没有匹配项,则选择全部。 |
maxRounds |
1 |
1 到 4 的整数,包括初始轮次。 |
maxTurns |
agents.length |
1 到 32 的整数;针对一条入站消息启动的参与者轮次总数。 |
未知对象字段会被拒绝。限定数组使用相同默认值:
"slack:C0123": ["reviewer", "writer"] 运行一轮初始轮次,并使用提及
选择。对于同一对等方,限定 WhatsApp 键优先于非限定键。
不支持非限定对象条目。
maxTurns 统计由协调器启动的代理运行,包括
通过或失败的运行。槽位在并行启动前同步预留,因此
并行参与者不会超支预算。如果预算小于
符合条件的参与者数量,则配置顺序决定哪些轮次
启动。一个轮次可以通过分块、预览
或消息工具发送产生多条平台消息。这些投递由代理运行和
频道传输控制;maxTurns 不统计、不缓冲、也不限制物理消息。
Telegram、Discord 和 Slack 会为限定群组线程禁用其共享预览和进度草稿,以免并发参与者相互覆盖草稿。最终回复、块回复和消息工具发送仍然 可用。
默认轮次预算覆盖每个已配置代理一个轮次。若要每个
代理运行两次,请设置 maxRounds: 2,并将 maxTurns 设为参与者数量的两倍。
提及选择¶
选择仅使用当前入站文本中显式的 @ 样式匹配,
并为参与者集合计算一次。正文中的名称或单独的表情符号不会
选择参与者。提及模式依次从代理的
groupChat.mentionPatterns、messages.groupChat.mentionPatterns,再到其
身份派生模式解析。如果需要单独称呼参与者,请为参与者提供不同的模式。
当 mentionGating: true 时,匹配项仅为第 1 轮选择匹配的参与者;没有匹配项则选择全部。当 mentionGating: false 时,选择所有参与者。此选项不会关闭频道的 requireMention
策略、发送者允许列表或命令授权。
有界后续轮次¶
在完成一轮后,只有同时处于 maxRounds
和 maxTurns 范围内,才能运行另一轮。符合条件的参与者是上一轮产生了最终回复,或在同级参与者的最终回复中被点名提及的参与者。
摘要中每个参与者的最终文本限制为 4,000 个字符;
同级文本合计限制为 16,000 个字符。
每个参与者都会收到该轮同级最终回复的带来源、大小受限摘要,并附有指示:仅在添加新内容时回复,否则返回 NO_REPLY。通过不会产生可见的最终回复。
所有参与者通过都会结束线程。达到任一限制或取消也会停止后续轮次。每个延续都有自己内部身份;它不是对物理入站消息的重放。顺序策略会改变一轮内的启动顺序;它不会将该轮变成流水线,使每个参与者看到同一轮中较早的回复。
预算状态保存在内存中,作用域为频道、账户、会话、线程和根入站消息。它不支持重启恢复:Gateway 重启会丢失活动轮次和预算状态。常规入站去重仍然是独立的保护机制。
参与者标签¶
当限定条目配置了多个参与者时,Discord、Slack 和 Telegram 的回复会以加粗的参与者名称开头。配置的数量控制标签,即使提及选择、轮次预算或静默只留下一个响应者。WhatsApp 展示保持不变。
基础设置¶
旧版单次处理设置使用未限定的 WhatsApp 对端 ID 作为键,并使用智能体 ID 数组作为值:
- 群聊:群组 JID(例如
120363403215116621@g.us) - 私信:发送者 E.164 电话号码(例如
+15551234567)
结果: 当 OpenClaw 将在此聊天中回复时,它会运行全部三个智能体。
列出的每个智能体 ID 都必须存在于已配置的名单中:配置验证会拒绝数组和对象中的未知 ID。删除智能体会将其从两种形式中移除。
运行时成员资格使用规范的 agents.entries 名单。启动前运行 openclaw doctor --fix 以迁移旧版 agents.list 名单。
处理策略¶
broadcast.strategy 设置智能体如何处理消息:
| 策略 | 行为 |
|---|---|
parallel(默认) |
所有智能体同时处理;回复到达顺序任意。 |
sequential |
智能体按数组顺序处理;每个等待前一个完成。 |
完整示例¶
{
"agents": {
"ownership": "explicit",
"defaults": {
"authInheritance": { "agentId": "code-reviewer" },
"heartbeat": { "agentId": "code-reviewer" },
"systemAgent": { "agentId": "code-reviewer" }
},
"entries": {
"code-reviewer": {
"name": "Code Reviewer",
"workspace": "/path/to/code-reviewer",
"sandbox": { "mode": "all" }
},
"security-auditor": {
"name": "Security Auditor",
"workspace": "/path/to/security-auditor",
"sandbox": { "mode": "all" }
},
"docs-generator": {
"name": "Documentation Generator",
"workspace": "/path/to/docs-generator",
"sandbox": { "mode": "all" }
}
}
},
"bindings": [
{ "agentId": "code-reviewer", "match": { "channel": "whatsapp", "accountId": "*" } }
],
"talk": { "agentId": "code-reviewer" },
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"]
}
}
工作原理¶
消息流程¶
1. 传入消息到达
一个频道消息到达。
2. 路由和准入
OpenClaw 应用频道允许列表、群组激活规则和已配置的 ACP 绑定所有权。
3. 广播检查
如果没有已配置的 ACP 绑定拥有该路由,OpenClaw 会检查限定的频道/对端键,然后检查 WhatsApp 的旧版对端键。
4. 如果广播适用
- 选定的参与者在轮次和回合限制内处理消息。
- 每个智能体都有自己的会话键和隔离上下文。
- 智能体并行(默认)或顺序处理。
- WhatsApp 音频附件在扇出之前只转录一次,因此智能体共享一份转录文本,而不是分别进行 STT 调用。
5. 如果广播不适用
OpenClaw 分派普通路由或路由期间选定的已配置 ACP 会话路由。
Note
群组线程不会绕过频道允许列表、命令授权或独占 ACP 绑定。参与者提及准入扩展了如上所述的房间提及门控。
会话隔离¶
广播组中的每个智能体都保持完全独立的:
- 会话键(
agent:alfred:whatsapp:group:120363...与agent:baerbel:whatsapp:group:120363...) - 对话历史(同级回复仅通过有界的后续摘要共享)
- 工作区(如果配置了独立沙箱)
- 工具访问(不同的允许/拒绝列表)
- 内存/上下文(独立的
IDENTITY.md、SOUL.md等)
在 Discord、Slack 和 Telegram 上,回复投递和完成钩子使用响应参与者的会话,本地媒体使用该参与者的媒体根目录解析。这也适用于只有一个参与者的限定条目,其回复没有参与者名称标签。
在 WhatsApp 上,一个输入是有意共享的:群组上下文缓冲区(用于上下文的最近群组消息)按对端共享,因此所有广播智能体被触发时看到相同的上下文。扇出完成后会清除一次。
这允许每个智能体拥有不同的个性、模型、技能和工具访问权限(例如只读与读写)。
示例:隔离会话¶
在群组 120363403215116621@g.us 中,智能体为 ["alfred", "baerbel"]:
用例¶
- 专业智能体团队:一个开发群组,其中
code-reviewer、security-auditor、test-generator和docs-checker各自从自己的角度回答同一条消息。 - 多语言支持:一个支持聊天,
support-en、support-de、support-es用各自的语言回复。 - 质量保证:
support-agent回答,而qa-agent审查,并且只在发现问题时回复。 - 任务自动化:
task-tracker、time-logger和report-generator都消费同一条状态更新。
最佳实践¶
1. 保持智能体专注
为每个代理分配单一、明确的职责(formatter、linter、tester),而不是一个通用的 "dev-helper" 代理。
2. 使用描述性的 id 和名称
{
"agents": {
"ownership": "explicit",
"defaults": {
"authInheritance": { "agentId": "security-scanner" },
"heartbeat": { "agentId": "security-scanner" },
"systemAgent": { "agentId": "security-scanner" }
},
"entries": {
"security-scanner": {
"name": "Security Scanner",
"workspace": "~/.openclaw/workspace"
},
"code-formatter": { "name": "Code Formatter" },
"test-generator": { "name": "Test Generator" }
}
},
"talk": { "agentId": "security-scanner" }
}
3. 配置不同的工具访问权限
{
"agents": {
"ownership": "explicit",
"defaults": {
"authInheritance": { "agentId": "reviewer" },
"heartbeat": { "agentId": "reviewer" },
"systemAgent": { "agentId": "reviewer" }
},
"entries": {
"reviewer": {
"workspace": "~/.openclaw/workspace",
"tools": { "allow": ["read", "exec"] }
},
"fixer": { "tools": { "allow": ["read", "write", "edit", "exec"] } }
}
},
"talk": { "agentId": "reviewer" }
}
reviewer 为只读。fixer 可以读取和写入。
4. 监控性能
当代理数量较多时,建议使用 "strategy": "parallel"(默认值),将广播组限制在少数几个代理,并为较简单的代理使用更快的模型。
5. 故障保持隔离
代理会独立失败。某个代理的错误会被记录(Broadcast agent <id> failed: ...),并且不会阻塞其他代理。
兼容性¶
提供商¶
带渠道限定的条目使用跨渠道插件的共享核心分发路径。Discord、Slack 和 Telegram 额外支持参与者提及准入和名称标签。旧版无限定条目仅适用于 WhatsApp(Web 渠道)。
路由¶
广播组可与现有路由协同工作:
{
"bindings": [
{
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
"agentId": "alfred"
}
],
"broadcast": {
"GROUP_B": ["agent1", "agent2"]
}
}
GROUP_A:只有 alfred 响应(正常路由)。GROUP_B:agent1 和 agent2 都响应(广播)。
Note
优先级: broadcast 优先于普通路由绑定。已配置的 ACP 绑定(bindings[].type="acp")是独占的:当其中一个匹配时,OpenClaw 会分发到已配置的 ACP 会话,而不是扇出广播。
故障排除¶
代理未响应
检查:
- 代理 ID 存在于
agents.entries中(配置验证会拒绝未知 id)。 - 带限定的渠道/对等方键与房间匹配。旧版 WhatsApp 键使用类似
120363403215116621@g.us的群组 JID,或用于 DM 的类似+15551234567的 E.164。 - 消息通过了正常门控(提及/激活规则仍然适用)。
调试:
成功的扇出会记录 Broadcasting message to <n> agents (<strategy>)。
只有一个代理响应
检查: 显式提及可能只选择一个参与者,maxTurns 可能只允许一次运行,或者其他代理可能通过(未响应)。还需检查该对等方是否仅在普通路由绑定中,或是否匹配独占的已配置 ACP 绑定。
修复: 将普通路由绑定的对等方添加到广播配置中,或者如果希望扇出广播,则移除/更改已配置的 ACP 绑定。
性能问题
如果代理较多时较慢:减少每组中的代理数量,使用更轻量的模型,并检查沙箱启动时间。
示例¶
示例 1:代码审查团队
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": [
"code-formatter",
"security-scanner",
"test-coverage",
"docs-checker"
]
},
"agents": {
"ownership": "explicit",
"defaults": {
"authInheritance": { "agentId": "code-formatter" },
"heartbeat": { "agentId": "code-formatter" },
"systemAgent": { "agentId": "code-formatter" }
},
"entries": {
"code-formatter": {
"workspace": "~/agents/formatter",
"tools": { "allow": ["read", "write"] }
},
"security-scanner": {
"workspace": "~/agents/security",
"tools": { "allow": ["read", "exec"] }
},
"test-coverage": {
"workspace": "~/agents/testing",
"tools": { "allow": ["read", "exec"] }
},
"docs-checker": { "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
}
},
"bindings": [
{ "agentId": "code-formatter", "match": { "channel": "whatsapp", "accountId": "*" } }
],
"talk": { "agentId": "code-formatter" }
}
群组中的一段代码可以产生四个视角:格式修复、安全发现、覆盖缺口和文档小问题。
示例 2:多语言流水线
{
"broadcast": {
"strategy": "sequential",
"+15555550123": ["detect-language", "translator-en", "translator-de"]
},
"agents": {
"ownership": "explicit",
"defaults": {
"authInheritance": { "agentId": "detect-language" },
"heartbeat": { "agentId": "detect-language" },
"systemAgent": { "agentId": "detect-language" }
},
"entries": {
"detect-language": { "workspace": "~/agents/lang-detect" },
"translator-en": { "workspace": "~/agents/translate-en" },
"translator-de": { "workspace": "~/agents/translate-de" }
}
},
"bindings": [
{ "agentId": "detect-language", "match": { "channel": "whatsapp", "accountId": "*" } }
],
"talk": { "agentId": "detect-language" }
}
API 参考¶
配置模式¶
type BroadcastGroupConfig = {
agents: string[];
mentionGating?: boolean;
maxRounds?: number;
maxTurns?: number;
};
type BroadcastConfig = {
strategy?: "parallel" | "sequential";
[key: string]: string[] | BroadcastGroupConfig | "parallel" | "sequential" | undefined;
};
字段¶
strategy"parallel" | "sequential" (路径) 默认:"parallel"- 如何处理每轮中符合条件的代理。
parallel同时启动保留回合;sequential按配置顺序运行它们。 [channel:peerId]string[] | BroadcastGroupConfig (路径)- 带频道限定的对等 ID。数组使用群组线程默认值;对象用于配置提及选择、轮次和参与者回合预算。最多 16 个代理。
[peerId]string[] (路径)- 旧版 WhatsApp 群组 JID 或 E.164 电话号码。每个列出的代理处理一个回合,没有内部后续轮次或参与者选择。
限制¶
- 共享上下文: 后续摘要包含有界同级最终消息,而不是完整的同级会话或工具历史。
- 消息顺序: 并行响应可能以任意顺序到达。
- 速率限制: 参与者共享频道账户的传输限制;一个回合可能生成多条平台消息。
- 恢复: 轮次和回合预算状态保存在内存中,Gateway 重启后无法恢复。
- 控制 UI: 专用的团队线程会话尚不可用。每个参与者保留自己的会话。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw