群組訊息（WhatsApp web 頻道）

目標：讓 Clawd 待在 WhatsApp 群組裡，只在被提及時回覆，並將該討論串與個人私訊工作階段分開。

備註：agents.list[].groupChat.mentionPatterns 現在也被 Telegram/Discord/Slack/iMessage 使用；本文件著重於 WhatsApp 特定行為。多代理設定中，請為每個代理設定 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作為全域備援）。

已實作功能（2025-12-03）

  • 啟動模式：mention（預設）或 always。mention 需要被提及（真正的 WhatsApp @ 提及透過 mentionedJids、正則表達式，或機器人的 E.164 出現在文字中）。always 在每則訊息時喚醒代理，但它應只在能提供有意義的價值時回覆；否則返回靜默 token NO_REPLY。預設值可在設定中設定（channels.whatsapp.groups），並可透過 /activation 按群組覆寫。當 channels.whatsapp.groups 被設定時，它也作為群組許可清單（包含 "*" 以允許所有群組）。
  • 群組政策：channels.whatsapp.groupPolicy 控制是否接受群組訊息（open|disabled|allowlist）。allowlist 使用 channels.whatsapp.groupAllowFrom（備援：明確的 channels.whatsapp.allowFrom）。預設為 allowlist（在你加入發送者之前被封鎖）。
  • 按群組工作階段：工作階段鍵格式為 agent:<agentId>:whatsapp:group:<jid>，因此像 /verbose on 或 /think high 這樣的指令（作為獨立訊息發送）只在該群組中生效；個人私訊狀態不受影響。群組討論串會跳過心跳。
  • 上下文注入：僅待處理的 群組訊息（預設 50 則）會以 [Chat messages since your last reply - for context] 為前綴注入，觸發行以 [Current message - respond to this] 標示。已在工作階段中的訊息不會重複注入。
  • 發送者呈現：每個群組批次現在以 [from: Sender Name (+E164)] 結尾，讓 Pi 知道誰在說話。
  • 限時/一次性訊息：我們在提取文字/提及之前會先展開這些訊息，因此其中的提及仍會觸發。
  • 群組系統提示：在群組工作階段的第一輪（以及 /activation 變更模式時），我們注入一段簡短描述到系統提示中，例如 You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context. 如果中繼資料不可用，我們仍會告訴代理這是群組聊天。

設定範例（WhatsApp）

在 ~/.openclaw/openclaw.json 中加入 groupChat 區塊，這樣即使 WhatsApp 在文字本體中去除了視覺上的 @，顯示名稱提及也能正常運作：

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

備註：

  • 正則表達式不區分大小寫；涵蓋像 @openclaw 這樣的顯示名稱提及和帶或不帶 +/空格的原始號碼。
  • WhatsApp 在有人點擊聯絡人時仍透過 mentionedJids 發送標準提及，所以號碼備援很少需要，但作為安全網很有用。

啟動指令（僅限擁有者）

在群組聊天中使用指令：

  • /activation mention
  • /activation always

只有擁有者號碼（來自 channels.whatsapp.allowFrom，或未設定時的機器人自身 E.164）可以變更。在群組中發送 /status 作為獨立訊息可查看目前的啟動模式。

使用方式

  1. 將你的 WhatsApp 帳號（執行 OpenClaw 的那個）加入群組。
  2. 說 @openclaw ...（或包含號碼）。除非你設定 groupPolicy: "open"，否則只有許可清單中的發送者可以觸發。
  3. 代理提示會包含最近的群組上下文加上結尾的 [from: ...] 標記，讓它能對正確的人回覆。
  4. 工作階段層級指令（/verbose on、/think high、/new 或 /reset、/compact）只適用於該群組的工作階段；將它們作為獨立訊息發送以便註冊。你的個人私訊工作階段保持獨立。

測試/驗證

  • 手動測試：
    • 在群組中發送 @openclaw 提及，確認收到引用發送者名稱的回覆。
    • 發送第二次提及，確認歷史記錄區塊被包含然後在下一輪清除。
  • 檢查 Gateway 日誌（以 --verbose 執行）可看到 inbound web message 項目顯示 from: <groupJid> 和 [from: ...] 後綴。

已知注意事項

  • 群組刻意跳過心跳以避免嘈雜的廣播。
  • 回聲抑制使用組合的批次字串；如果你在沒有提及的情況下發送兩次相同文字，只有第一次會得到回覆。
  • 工作階段存儲項目會以 agent:<agentId>:whatsapp:group:<jid> 出現在工作階段存儲中（預設 ~/.openclaw/agents/<agentId>/sessions/sessions.json）；缺少項目只表示該群組尚未觸發過執行。
  • 群組中的輸入指示器遵循 agents.defaults.typingMode（預設：未被提及時為 message）。
arrow_back
上一頁
Pairing
下一頁
Groups
arrow_forward