# 广播群组
> 向多个智能体广播 WhatsApp 消息
- 网址：https://funcoding.ai/agents/openclaw/channels/broadcast-groups/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/channels/broadcast-groups
---
**状态：** 实验性功能。于 2026.1.9 中添加。仅支持 WhatsApp（Web 渠道）。
## 概览
广播群组会针对同一条入站消息运行**多个智能体**。每个智能体都在各自隔离的会话中处理消息并发布自己的回复，因此，一个 WhatsApp 号码可以在单个群聊或私信中承载一组专业化智能体。
广播群组会在渠道允许列表和群组激活规则之后进行评估。在 WhatsApp 群组中，当 OpenClaw 通常会回复时（例如：被提及时，具体取决于你的群组设置），广播就会发生。它们只会改变**运行哪些智能体**，绝不会改变消息是否符合处理条件。
实时 WhatsApp QA 通道包含 `whatsapp-broadcast-group-fanout`，用于验证一条提及智能体的群组消息可以让两个已配置的智能体分别生成不同的可见回复。
## 配置
### 基本设置
添加一个顶层 `broadcast` 部分（与 `bindings` 同级）。键是 WhatsApp 对端 ID，值是智能体 ID 数组：
- 群聊：群组 JID（例如 `120363403215116621@g.us`）
- 私信：发送者的 E.164 电话号码（例如 `+15551234567`）
```json
{
"broadcast": {
"120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
}
}
```
**结果：** 当 OpenClaw 要在此聊天中回复时，它会运行全部三个智能体。
列出的每个智能体 ID 都必须存在于 `agents.entries` 中：配置验证会报告未知 ID，运行时则会跳过它们并发出 `Broadcast agent not found in agents.entries; skipping` 警告。
### 处理策略
`broadcast.strategy` 设置智能体处理消息的方式：
| 策略 | 行为 |
| -------------------- | --------------------------------------------------------------------- |
| `parallel`（默认） | 所有智能体同时处理；回复可以按任意顺序到达。 |
| `sequential` | 智能体按数组顺序处理；每个智能体都会等待前一个处理完成。 |
```json
{
"broadcast": {
"strategy": "sequential",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
### 完整示例
```json
{
"agents": {
"list": [
{
"id": "code-reviewer",
"name": "Code Reviewer",
"workspace": "/path/to/code-reviewer",
"sandbox": { "mode": "all" }
},
{
"id": "security-auditor",
"name": "Security Auditor",
"workspace": "/path/to/security-auditor",
"sandbox": { "mode": "all" }
},
{
"id": "docs-generator",
"name": "Documentation Generator",
"workspace": "/path/to/docs-generator",
"sandbox": { "mode": "all" }
}
]
},
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
"120363424282127706@g.us": ["support-en", "support-de"],
"+15555550123": ["assistant", "logger"]
}
}
```
## 工作原理
### 消息流
**收到入站消息**
收到一条 WhatsApp 群组或私信消息。
**路由和准入**
OpenClaw 应用渠道允许列表、群组激活规则以及已配置的 ACP 绑定所有权。
**广播检查**
如果没有已配置的 ACP 绑定拥有该路由，OpenClaw 会检查对端 ID 是否位于 `broadcast` 中。
**如果应用广播**
- 所有列出的智能体都会处理该消息。
- 每个智能体都有自己的会话键和隔离上下文。
- 智能体以并行（默认）或顺序方式处理。
- 音频附件会在扇出前仅转录一次，因此智能体会共享同一份转录文本，而不是分别发起 STT 调用。
**如果不应用广播**
OpenClaw 会分派普通路由，或分派在路由期间选定的已配置 ACP 会话路由。
广播群组不会绕过渠道允许列表或群组激活规则（提及、命令等）。它们只会在消息符合处理条件时改变_运行哪些智能体_。
### 会话隔离
广播群组中的每个智能体都分别维护完全独立的：
- **会话键**（`agent:alfred:whatsapp:group:120363...` 与 `agent:baerbel:whatsapp:group:120363...`）
- **对话历史记录**（智能体看不到其他智能体的回复）
- **工作区**（如果已配置，则使用单独的沙箱）
- **工具访问权限**（不同的允许/拒绝列表）
- **记忆/上下文**（单独的 `IDENTITY.md`、`SOUL.md` 等）
有一个特意共享的例外：**群组上下文缓冲区**（用于提供上下文的近期群组消息）按对端共享，因此所有广播智能体在触发时都会看到相同的上下文。扇出完成后，该缓冲区会统一清除一次。
这样一来，每个智能体都可以拥有不同的个性、模型、Skills 和工具访问权限（例如只读与读写）。
### 示例：隔离的会话
在包含智能体 `["alfred", "baerbel"]` 的群组 `120363403215116621@g.us` 中：
**Alfred 的上下文**
```text
会话：agent:alfred:whatsapp:group:120363403215116621@g.us
历史记录：[用户消息，alfred 之前的回复]
工作区：~/openclaw-alfred/
工具：读取、写入、执行
```
**Baerbel 的上下文**
```text
会话：agent:baerbel:whatsapp:group:120363403215116621@g.us
历史记录：[用户消息，baerbel 之前的回复]
工作区：~/openclaw-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`），而不是使用一个通用的“开发助手”智能体。
2. 使用描述性 ID 和名称
```json
{
"agents": {
"list": [
{ "id": "security-scanner", "name": "Security Scanner" },
{ "id": "code-formatter", "name": "Code Formatter" },
{ "id": "test-generator", "name": "Test Generator" }
]
}
}
```
3. 配置不同的工具访问权限
```json
{
"agents": {
"list": [
{ "id": "reviewer", "tools": { "allow": ["read", "exec"] } },
{ "id": "fixer", "tools": { "allow": ["read", "write", "edit", "exec"] } }
]
}
}
```
`reviewer` 是只读的。`fixer` 可以读取和写入。
4. 监控性能
使用多个智能体时，优先选择 `"strategy": "parallel"`（默认），将广播群组限制在少量智能体，并为较简单的智能体使用速度更快的模型。
5. 故障保持隔离
智能体之间的故障相互独立。一个智能体的错误会被记录（`Broadcast agent failed: ...`），且不会阻塞其他智能体。
## 兼容性
### 提供商
广播群组目前仅针对 WhatsApp（Web 渠道）实现。其他渠道会忽略 `broadcast` 配置。
### 路由
广播群组可以与现有路由配合使用：
```json
{
"bindings": [
{
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
"agentId": "alfred"
}
],
"broadcast": {
"GROUP_B": ["agent1", "agent2"]
}
}
```
- `GROUP_A`：仅 alfred 回复（普通路由）。
- `GROUP_B`：agent1 和 agent2 都会回复（广播）。
**优先级：** `broadcast` 的优先级高于普通路由绑定。已配置的 ACP 绑定（`bindings[].type="acp"`）具有排他性：当其中一个匹配时，OpenClaw 会分派到已配置的 ACP 会话，而不是进行扇出广播。
## 故障排查
智能体未响应
**检查：**
1. 智能体 ID 存在于 `agents.entries` 中（配置验证会拒绝未知 ID）。
2. 对端 ID 格式正确（群组 JID，例如 `120363403215116621@g.us`；私信使用 E.164，例如 `+15551234567`）。
3. 消息通过了普通准入检查（提及/激活规则仍然适用）。
**调试：**
```bash
openclaw logs --follow | grep -i broadcast
```
成功的扇出会记录 `Broadcasting message to agents ()`。
只有一个智能体响应
**原因：** 对端 ID 可能位于普通路由绑定中，但不在 `broadcast` 中；或者，它可能匹配了一个排他的已配置 ACP 绑定。
**修复：** 将绑定了普通路由的对端添加到广播配置；如果需要扇出广播，则移除或更改已配置的 ACP 绑定。
性能问题
如果智能体较多时速度缓慢：减少每个群组中的智能体数量、使用更轻量的模型，并检查沙箱启动时间。
## 示例
示例 1：代码审查团队
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": [
"code-formatter",
"security-scanner",
"test-coverage",
"docs-checker"
]
},
"agents": {
"list": [
{
"id": "code-formatter",
"workspace": "~/agents/formatter",
"tools": { "allow": ["read", "write"] }
},
{
"id": "security-scanner",
"workspace": "~/agents/security",
"tools": { "allow": ["read", "exec"] }
},
{
"id": "test-coverage",
"workspace": "~/agents/testing",
"tools": { "allow": ["read", "exec"] }
},
{ "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
]
}
}
```
群组中的一段代码会产生四条回复：格式修复、安全发现、覆盖率缺口和文档小问题。
示例 2：多语言流水线
```json
{
"broadcast": {
"strategy": "sequential",
"+15555550123": ["detect-language", "translator-en", "translator-de"]
},
"agents": {
"list": [
{ "id": "detect-language", "workspace": "~/agents/lang-detect" },
{ "id": "translator-en", "workspace": "~/agents/translate-en" },
{ "id": "translator-de", "workspace": "~/agents/translate-de" }
]
}
}
```
## API 参考
### 配置架构
```typescript
interface OpenClawConfig {
broadcast?: {
strategy?: "parallel" | "sequential";
[peerId: string]: string[];
};
}
```
### 字段
智能体的处理方式。`parallel` 会同时运行所有智能体；`sequential` 会按数组顺序运行它们。
WhatsApp 群组 JID 或 E.164 电话号码。值为智能体 ID 数组，其中所有智能体都应处理来自该对端的消息。
## 限制
1. **最大智能体数：**没有硬性限制，但智能体数量较多（10 个以上）时速度可能会变慢。
2. **共享上下文：**智能体无法看到彼此的响应（这是有意设计的）。
3. **消息顺序：**并行响应可能以任意顺序到达。
4. **速率限制：**所有回复都来自同一个 WhatsApp 账号，因此每个智能体的回复都会计入同一 WhatsApp 速率限制。
## 相关内容
- [频道路由](https://funcoding.ai/agents/openclaw/channels/channel-routing/)
- [群组](https://funcoding.ai/agents/openclaw/channels/groups/)
- [多 Agent 沙盒工具](https://funcoding.ai/agents/openclaw/tools/multi-agent-sandbox-tools/)
- [配对](https://funcoding.ai/agents/openclaw/channels/pairing/)
- [会话管理](https://funcoding.ai/agents/openclaw/concepts/session/)