廣播群組

狀態： 實驗性。新增於 2026.1.9。僅支援 WhatsApp（網頁頻道）。

​

概覽

廣播群組會針對同一則傳入訊息執行多個代理程式。每個代理程式都會在自己隔離的工作階段中處理訊息，並各自發布回覆，因此一個 WhatsApp 號碼可在單一群組聊天或私訊中容納一組專業化代理程式團隊。

廣播群組會在頻道允許清單和群組啟用規則之後進行評估。在 WhatsApp 群組中，當 OpenClaw 通常會回覆時（例如：有人提及時，取決於你的群組設定）就會進行廣播。它們只會改變要執行哪些代理程式，絕不會改變訊息是否符合處理資格。

即時 WhatsApp QA 流程包含 whatsapp-broadcast-group-fanout，用來驗證一則有提及對象的群組訊息，能否從兩個已設定的代理程式產生不同且可見的回覆。

​

設定

​

基本設定

新增頂層 broadcast 區段（與 bindings 同層）。鍵是 WhatsApp 對等端 ID，值是代理程式 ID 陣列：

• 群組聊天：群組 JID（例如 [e-mail]）
• 私訊：傳送者的 E.164 電話號碼（例如 [phone]）

{
  "broadcast": {
    "[e-mail]": ["alfred", "baerbel", "assistant3"]
  }
}

結果： 當 OpenClaw 會在此聊天中回覆時，它會執行全部三個代理程式。

列出的每個代理程式 ID 都必須存在於 agents.entries：設定驗證會回報未知的 ID，而執行階段會略過它們並發出 Broadcast agent <id> not found in agents.entries; skipping 警告。

​

處理策略

broadcast.strategy 設定代理程式處理訊息的方式：

策略	行為
parallel（預設）	所有代理程式同時處理；回覆可按任意順序送達。
sequential	代理程式依陣列順序處理；每個代理程式都會等待前一個完成。

{
  "broadcast": {
    "strategy": "sequential",
    "[e-mail]": ["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",
    "[e-mail]": ["code-reviewer", "security-auditor", "docs-generator"],
    "[e-mail]": ["support-en", "support-de"],
    "[phone]": ["assistant", "logger"]
  }
}

​

運作方式

​

訊息流程

1. 傳入訊息到達

   WhatsApp 群組或私訊訊息到達。

2. 路由與准入

   OpenClaw 會套用頻道允許清單、群組啟用規則，以及已設定的 ACP 繫結擁有權。

3. 廣播檢查

   如果沒有已設定的 ACP 繫結擁有該路由，OpenClaw 會檢查對等端 ID 是否位於 broadcast。

4. 如果套用廣播

   • 所有列出的代理程式都會處理訊息。
   • 每個代理程式都有自己的工作階段金鑰和隔離的上下文。
   • 代理程式會平行（預設）或循序處理。
   • 音訊附件會在分派前轉錄一次，因此代理程式共用同一份轉錄內容，而不是分別進行 STT 呼叫。
5. 如果不套用廣播

   OpenClaw 會分派一般路由，或在路由期間選取的已設定 ACP 工作階段路由。

廣播群組不會略過頻道允許清單或群組啟用規則（提及／命令等）。它們只會在訊息符合處理資格時，改變_要執行哪些代理程式_。

​

工作階段隔離

廣播群組中的每個代理程式都會維持完全分離的：

• 工作階段金鑰（agent:alfred:whatsapp:group:120363... 與 agent:baerbel:whatsapp:group:120363...）
• 對話記錄（代理程式不會看到其他代理程式的回覆）
• 工作區（若有設定，則使用不同的沙箱）
• 工具存取權（不同的允許／拒絕清單）
• 記憶／上下文（分離的 IDENTITY.md、SOUL.md 等）

有一項刻意共用的例外：群組上下文緩衝區（用作上下文的近期群組訊息）會由每個對等端共用，因此觸發時，所有廣播代理程式都會看到相同的上下文。分派完成後，它會統一清除一次。

如此一來，每個代理程式都能擁有不同的個性、模型、技能和工具存取權（例如唯讀與讀寫）。

​

範例：隔離的工作階段

在具有代理程式 ["alfred", "baerbel"] 的群組 [e-mail] 中：

Alfred 的上下文

工作階段：agent:alfred:whatsapp:group:[e-mail]
記錄：[使用者訊息、alfred 先前的回覆]
工作區：~/openclaw-alfred/
工具：讀取、寫入、執行

Baerbel 的上下文

工作階段：agent:baerbel:whatsapp:group:[e-mail]
記錄：[使用者訊息、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），而不是使用一個通用的「dev-helper」代理程式。

2. 使用具描述性的 ID 和名稱

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

3. 設定不同的工具存取權

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

reviewer 是唯讀的。fixer 可以讀取和寫入。

4. 監控效能

使用許多代理程式時，請優先使用 "strategy": "parallel"（預設），將廣播群組限制在少數幾個代理程式，並為較簡單的代理程式使用速度較快的模型。

5. 故障維持隔離

代理程式各自獨立失敗。單一代理程式的錯誤會被記錄（Broadcast agent <id> failed: ...），且不會封鎖其他代理程式。

​

相容性

​

提供者

廣播群組目前僅針對 WhatsApp（網頁頻道）實作。其他頻道會忽略 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 都會回覆（廣播）。

優先順序： broadcast 的優先順序高於一般路由繫結。已設定的 ACP 繫結（bindings[].type="acp"）具有排他性：當其中一項相符時，OpenClaw 會分派至已設定的 ACP 工作階段，而不會進行分派廣播。

​

疑難排解

代理程式沒有回應

檢查：

1. 代理程式 ID 存在於 agents.entries（設定驗證會拒絕未知的 ID）。
2. 對等端 ID 格式正確（群組 JID 如 [e-mail]，或私訊使用的 E.164 格式如 [phone]）。
3. 訊息通過一般閘控（提及／啟用規則仍然適用）。

偵錯：

openclaw logs --follow | grep -i broadcast

成功的分派會記錄 Broadcasting message to <n> agents (<strategy>)。

只有一個代理程式回應

原因： 對等端 ID 可能位於一般路由繫結中，但不在 broadcast 中，或可能符合排他的已設定 ACP 繫結。

修正： 將一般路由繫結的對等端新增至廣播設定；若需要分派廣播，則移除或變更已設定的 ACP 繫結。

效能問題

如果代理程式數量較多時速度緩慢：減少每個群組的代理程式數量、使用較輕量的模型，並檢查沙箱啟動時間。

​

範例

範例 1：程式碼審查團隊

{
  "broadcast": {
    "strategy": "parallel",
    "[e-mail]": [
      "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：多語言流水線

{
  "broadcast": {
    "strategy": "sequential",
    "[phone]": ["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[];
  };
}

​

欄位

strategy · "parallel" | "sequential" · 預設值: "\"parallel\""

代理程式的處理方式。parallel 會同時執行所有代理程式；sequential 會依陣列順序執行。

[peerId] · string[]

WhatsApp 群組 JID 或 E.164 電話號碼。值是代理程式 ID 陣列，這些代理程式都應處理來自該對等端的訊息。

​

限制

1. **代理程式上限：**沒有硬性限制，但代理程式數量過多（10 個以上）時可能變慢。
2. **共用情境：**代理程式彼此看不到對方的回應（這是刻意的設計）。
3. **訊息順序：**平行回應可能以任何順序抵達。
4. **速率限制：**所有回覆都來自同一個 WhatsApp 帳號，因此每個代理程式的回覆都會計入相同的 WhatsApp 速率限制。

​

相關內容

• 頻道路由
• 群組
• 多代理程式沙箱工具
• 配對
• 工作階段管理