广播群组

概览

广播群组会针对同一条入站消息运行多个智能体。每个智能体都在各自隔离的会话中处理消息并发布自己的回复，因此，一个 WhatsApp 号码可以在单个群聊或私信中承载一组专业化智能体。

广播群组会在渠道允许列表和群组激活规则之后进行评估。在 WhatsApp 群组中，当 OpenClaw 通常会回复时（例如：被提及时，具体取决于你的群组设置），广播就会发生。它们只会改变运行哪些智能体，绝不会改变消息是否符合处理条件。

实时 WhatsApp QA 通道包含 whatsapp-broadcast-group-fanout，用于验证一条提及智能体的群组消息可以让两个已配置的智能体分别生成不同的可见回复。

配置

基本设置

添加一个顶层 broadcast 部分（与 bindings 同级）。键是 WhatsApp 对端 ID，值是智能体 ID 数组：

• 群聊：群组 JID（例如 [email protected]）
• 私信：发送者的 E.164 电话号码（例如 +15551234567）

{
  "broadcast": {
    "[email protected]": ["alfred", "baerbel", "assistant3"]
  }
}

结果： 当 OpenClaw 要在此聊天中回复时，它会运行全部三个智能体。

列出的每个智能体 ID 都必须存在于 agents.entries 中：配置验证会报告未知 ID，运行时则会跳过它们并发出 Broadcast agent <id> not found in agents.entries; skipping 警告。

处理策略

broadcast.strategy 设置智能体处理消息的方式：

{
  "broadcast": {
    "strategy": "sequential",
    "[email protected]": ["alfred", "baerbel"]
  }
}

完整示例

{
  "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",
    "[email protected]": ["code-reviewer", "security-auditor", "docs-generator"],
    "[email protected]": ["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"] 的群组 [email protected] 中：

Alfred 的上下文

会话：agent:alfred:whatsapp:group:[email protected]
历史记录：[用户消息，alfred 之前的回复]
工作区：~/openclaw-alfred/
工具：读取、写入、执行

Baerbel 的上下文

会话：agent:baerbel:whatsapp:group:[email protected]
历史记录：[用户消息，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 都会处理同一条状态更新。

最佳实践

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

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

兼容性

提供商

广播群组目前仅针对 WhatsApp（Web 渠道）实现。其他渠道会忽略 broadcast 配置。

路由

广播群组可以与现有路由配合使用：

{
  "bindings": [
    {
      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
      "agentId": "alfred"
    }
  ],
  "broadcast": {
    "GROUP_B": ["agent1", "agent2"]
  }
}

• GROUP_A：仅 alfred 回复（普通路由）。
• GROUP_B：agent1 和 agent2 都会回复（广播）。

故障排查

openclaw logs --follow | grep -i broadcast

示例

{
  "broadcast": {
    "strategy": "parallel",
    "[email protected]": [
      "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"] } }
    ]
  }
}

{
  "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 参考

配置架构

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

字段

智能体的处理方式。parallel 会同时运行所有智能体；sequential 会按数组顺序运行它们。

WhatsApp 群组 JID 或 E.164 电话号码。值为智能体 ID 数组，其中所有智能体都应处理来自该对端的消息。

限制

1. **最大智能体数：**没有硬性限制，但智能体数量较多（10 个以上）时速度可能会变慢。
2. **共享上下文：**智能体无法看到彼此的响应（这是有意设计的）。
3. **消息顺序：**并行响应可能以任意顺序到达。
4. **速率限制：**所有回复都来自同一个 WhatsApp 账号，因此每个智能体的回复都会计入同一 WhatsApp 速率限制。

相关内容

• 频道路由
• 群组
• 多 Agent 沙盒工具
• 配对
• 会话管理