广播组（Broadcast Groups）

状态： 实验性功能 版本： 2026.1.9 新增

概述

广播组允许多个 Agent 同时处理并回复同一条消息。你可以在一个 WhatsApp 群组或私信中组建专业分工的 Agent 团队——只需一个电话号码。

当前范围：仅支持 WhatsApp（web 渠道）。

广播组在渠道白名单和群组激活规则之后进行评估。在 WhatsApp 群组中，这意味着广播发生在 OpenClaw 正常回复的情况下（例如：被提及时，取决于你的群组设置）。

使用场景

1. 专业 Agent 团队

部署多个各司其职的 Agent：

群组："开发团队"
Agents:
  - CodeReviewer（代码审查）
  - DocumentationBot（生成文档）
  - SecurityAuditor（安全检查）
  - TestGenerator（生成测试用例）

每个 Agent 处理同一条消息，提供自己专业领域的见解。

2. 多语言支持

群组："国际支持"
Agents:
  - Agent_EN（英文回复）
  - Agent_DE（德文回复）
  - Agent_ES（西班牙文回复）

3. 质量保障工作流

群组："客户支持"
Agents:
  - SupportAgent（提供答案）
  - QAAgent（质量审核，只在发现问题时才回复）

4. 任务自动化

群组："项目管理"
Agents:
  - TaskTracker（更新任务数据库）
  - TimeLogger（记录耗时）
  - ReportGenerator（生成摘要）

配置

基础设置

在顶层添加 broadcast 段落（与 bindings 并列），键为 WhatsApp peer id：

群聊：群组 JID（如 120363403215116621@g.us）
私信：E.164 电话号码（如 +15551234567）

json

{
  "broadcast": {
    "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
  }
}

效果： 当 OpenClaw 在该聊天中回复时，会同时运行三个 Agent。

处理策略

控制 Agent 处理消息的方式：

并行（默认）

所有 Agent 同时处理：

json

{
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"]
  }
}

串行

Agent 按顺序处理（前一个完成后下一个才开始）：

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 群组收到消息
广播检查：系统检查 peer ID 是否在 broadcast 中
若在广播列表：
- 所有列出的 Agent 处理该消息
- 每个 Agent 有独立的会话密钥和隔离上下文
- Agent 并行处理（默认）或串行处理
若不在广播列表：
- 使用普通路由（第一个匹配的 binding）

注意：广播组不会绕过渠道白名单或群组激活规则（提及/命令等）。它们只改变消息符合处理条件时运行哪些 Agent。

会话隔离

广播组中每个 Agent 保持完全独立的：

会话密钥（agent:alfred:whatsapp:group:120363... vs agent:baerbel:whatsapp:group:120363...）
对话历史（Agent 看不到其他 Agent 的消息）
工作目录（若已配置，各自独立的沙箱）
工具访问（不同的允许/拒绝列表）
记忆/上下文（独立的 IDENTITY.md、SOUL.md 等）
群组上下文缓冲区（用于上下文的最近群组消息）按 peer 共享，所有广播 Agent 触发时看到相同上下文

这意味着每个 Agent 可以有：

不同的人格
不同的工具访问（如只读 vs 读写）
不同的模型（如 opus vs sonnet）
不同的已安装技能

示例：隔离会话

群组 120363403215116621@g.us 中有 Agent ["alfred", "baerbel"]：

Alfred 的上下文：

Session: agent:alfred:whatsapp:group:120363403215116621@g.us
History: [用户消息, alfred 的历史回复]
Workspace: /Users/pascal/openclaw-alfred/
Tools: read, write, exec

Bärbel 的上下文：

Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
History: [用户消息, baerbel 的历史回复]
Workspace: /Users/pascal/openclaw-baerbel/
Tools: 只读

最佳实践

1. 保持 Agent 专注

为每个 Agent 设计单一明确的职责：

json

{
  "broadcast": {
    "DEV_GROUP": ["formatter", "linter", "tester"]
  }
}

✅ 好：每个 Agent 只做一件事 ❌ 坏：一个万能的 "dev-helper" Agent

2. 使用描述性名称

让名称清楚表达每个 Agent 的用途：

json

{
  "agents": {
    "security-scanner": { "name": "Security Scanner" },
    "code-formatter": { "name": "Code Formatter" },
    "test-generator": { "name": "Test Generator" }
  }
}

3. 按需分配工具权限

只给 Agent 所需的工具：

json

{
  "agents": {
    "reviewer": {
      "tools": { "allow": ["read", "exec"] }
    },
    "fixer": {
      "tools": { "allow": ["read", "write", "edit", "exec"] }
    }
  }
}

4. 监控性能

Agent 较多时注意：

使用 "strategy": "parallel"（默认）提升速度
每组广播 Agent 限制在 5-10 个
简单 Agent 使用更快的模型

5. 优雅处理失败

Agent 独立失败，一个 Agent 报错不影响其他：

消息 → [Agent A ✓, Agent B ✗ 报错, Agent C ✓]
结果：A 和 C 回复，B 记录错误

兼容性

提供商支持

广播组目前支持：

✅ WhatsApp（已实现）
🚧 Telegram（计划中）
🚧 Discord（计划中）
🚧 Slack（计划中）

与路由的关系

广播组与现有路由并存：

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 优先于 bindings。

故障排除

Agent 不回复

检查：

Agent ID 是否存在于 agents.list
Peer ID 格式是否正确（如 120363403215116621@g.us）
Agent 是否在拒绝列表中

调试：

bash

tail -f ~/.openclaw/logs/gateway.log | grep broadcast

只有一个 Agent 回复

原因： Peer ID 可能在 bindings 中但不在 broadcast 中。

解决： 添加到广播配置，或从 bindings 中移除。

性能问题

Agent 过多时较慢：

减少每组 Agent 数量
使用更轻量的模型（sonnet 而非 opus）
检查沙箱启动时间

示例

示例 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"] } }
    ]
  }
}

用户发送： 代码片段 各 Agent 回复：

code-formatter："已修正缩进并添加类型提示"
security-scanner："⚠️ 第 12 行存在 SQL 注入漏洞"
test-coverage："覆盖率 45%，缺少错误用例的测试"
docs-checker："函数 process_data 缺少 docstring"

示例 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 参考

配置 Schema

typescript

interface OpenClawConfig {
  broadcast?: {
    strategy?: "parallel" | "sequential";
    [peerId: string]: string[];
  };
}

字段说明

strategy（可选）：Agent 处理方式
- "parallel"（默认）：所有 Agent 同时处理
- "sequential"：Agent 按数组顺序处理
[peerId]：WhatsApp 群组 JID、E.164 号码或其他 peer ID
- 值：应处理消息的 Agent ID 数组

限制

最大 Agent 数： 无硬性上限，但 10+ Agent 可能较慢
共享上下文： Agent 看不到彼此的回复（设计如此）
消息顺序： 并行回复可能以任意顺序到达
速率限制： 所有 Agent 都计入 WhatsApp 速率限制

未来规划

计划中的特性：

[ ] 共享上下文模式（Agent 可以看到彼此的回复）
[ ] Agent 协调机制（Agent 间可以互发信号）
[ ] 动态 Agent 选择（根据消息内容选择 Agent）
[ ] Agent 优先级（某些 Agent 先回复）

广播组（Broadcast Groups） ​

概述 ​

使用场景 ​

1. 专业 Agent 团队 ​

2. 多语言支持 ​

3. 质量保障工作流 ​

4. 任务自动化 ​

配置 ​

基础设置 ​

处理策略 ​

并行（默认） ​

串行 ​

完整示例 ​

工作原理 ​

消息流程 ​

会话隔离 ​

示例：隔离会话 ​

最佳实践 ​

1. 保持 Agent 专注 ​

2. 使用描述性名称 ​

3. 按需分配工具权限 ​

4. 监控性能 ​

5. 优雅处理失败 ​

兼容性 ​

提供商支持 ​

与路由的关系 ​

故障排除 ​

Agent 不回复 ​

只有一个 Agent 回复 ​

性能问题 ​

示例 ​

示例 1：代码审查团队 ​

示例 2：多语言支持 ​

API 参考 ​

配置 Schema ​

字段说明 ​

限制 ​

未来规划 ​

参见 ​

广播组（Broadcast Groups）

概述

使用场景

1. 专业 Agent 团队

2. 多语言支持

3. 质量保障工作流

4. 任务自动化

配置

基础设置

处理策略

并行（默认）

串行

完整示例

工作原理

消息流程

会话隔离

示例：隔离会话

最佳实践

1. 保持 Agent 专注

2. 使用描述性名称

3. 按需分配工具权限

4. 监控性能

5. 优雅处理失败

兼容性

提供商支持

与路由的关系

故障排除

Agent 不回复

只有一个 Agent 回复

性能问题

示例

示例 1：代码审查团队

示例 2：多语言支持

API 参考

配置 Schema

字段说明

限制

未来规划

参见