OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Configuration

WhatsApp 群組訊息

關於跨頻道群組模型（Discord、iMessage、Matrix、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp、Zalo），請參閱群組。本頁說明在該模型之上的 WhatsApp 特定行為：啟用方式、群組允許清單、各群組工作階段金鑰，以及待處理訊息的情境注入。

目標：讓 OpenClaw 能待在 WhatsApp 群組中，只有被點名時才喚醒，並讓該對話串與個人私訊工作階段分開。

行為

  • 啟用模式：mention（預設）或 always。mention 需要點名：真正的 WhatsApp @提及（mentionedJids）、已設定的規則運算式模式、文字中任何位置出現機器人的 E.164 號碼，或引用回覆機器人的其中一則訊息（共用號碼的自我聊天設定除外）。always 會在每則訊息出現時喚醒代理程式，但注入的群組提示會要求它只在能提供價值時回覆，否則傳回完全一致的靜默權杖 NO_REPLY（不區分大小寫）。預設值來自設定（channels.whatsapp.groups 的 requireMention），並可透過 /activation 為各群組覆寫。
  • 群組允許清單：設定 channels.whatsapp.groups 後，只接受列出的群組 JID（加入 "*" 可允許全部）；未列出群組的訊息會遭捨棄，並留下記錄提示。
  • 群組政策：channels.whatsapp.groupPolicy 控制是否接受群組訊息（open|disabled|allowlist）。allowlist 使用 channels.whatsapp.groupAllowFrom（備援：明確設定的 channels.whatsapp.allowFrom）。預設為 allowlist（在加入傳送者前都會封鎖）。
  • 各群組工作階段：工作階段金鑰的格式類似 agent:<agentId>:whatsapp:group:<jid>（非預設帳號會附加 :thread:whatsapp-account-<accountId>），因此 /verbose on、/trace on 或 /think high 等指令（以獨立訊息傳送）只適用於該群組；個人私訊狀態不受影響。
  • 情境注入：僅待處理且_未_觸發執行的群組訊息（預設 50 則）會加上 [Chat messages since your last reply - for context] 前綴，而觸發訊息所在行則位於 [Current message - respond to this] 之下。執行後會清除待處理視窗；已存在於工作階段中的訊息不會再次注入。
  • 傳送者歸屬：每個群組訊息行都會在訊息封裝中包含傳送者標籤，例如 [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text；傳送者身分以及群組主旨／成員也會一併放入不受信任的對話中繼資料區塊。
  • 暫時性／僅限檢視一次：在擷取文字／提及前會先解除包裝，因此其中的點名仍會觸發。
  • 群組系統提示：群組工作階段的第一輪（以及 /activation 變更模式後的任何一輪）會將啟用指引注入系統提示（Activation: trigger-only ... 或 Activation: always-on ...，以及「針對特定傳送者回覆」）。持續性的群組聊天傳送指引（「你正在 WhatsApp 群組聊天中……」）則一律包含在內。

設定範例（WhatsApp）

即使 WhatsApp 從文字本文中移除可見的 @，也能讓顯示名稱點名正常運作：

json5
{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },      historyLimit: 50, // 待處理群組情境視窗（預設 50）    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    ],  },}

注意事項：

  • 規則運算式不區分大小寫，並採用與其他設定規則運算式介面相同的安全規則運算式防護；無效模式及不安全的巢狀重複會被忽略。
  • 當有人點選聯絡人時，WhatsApp 仍會透過 mentionedJids 傳送標準提及，因此很少需要號碼備援，但它是實用的安全網。
  • 待處理情境視窗的解析順序為 channels.whatsapp.accounts.<id>.historyLimit → channels.whatsapp.historyLimit → messages.groupChat.historyLimit → 50。

啟用命令（僅限擁有者）

使用群組聊天命令：

  • /activation mention
  • /activation always

只有擁有者號碼（來自 channels.whatsapp.allowFrom；若未設定，則為機器人自己的 E.164 號碼）能變更此項；其他人的 /activation 會被忽略，並僅儲存為情境。在群組中以獨立訊息傳送 /status，即可查看目前的啟用模式。

使用方式

  1. 將你的 WhatsApp 帳號（執行 OpenClaw 的帳號）加入群組。
  2. 傳送 @openclaw ...（或包含該號碼）。除非你設定 groupPolicy: "open"，否則只有允許清單中的傳送者能觸發它。
  3. 代理程式提示包含待處理的群組情境及標有傳送者的訊息行，因此能針對正確的人回覆。
  4. 工作階段指令（/verbose on、/trace on、/think high、/new 或 /reset、/compact）只套用至該群組的工作階段；請將它們以獨立訊息傳送，才能正確登記。你的個人私訊工作階段會保持獨立。

測試／驗證

  • 手動冒煙測試：
    • 在群組中傳送 @openclaw 點名，並確認回覆中提及傳送者名稱。
    • 傳送第二次點名，確認其中包含歷史記錄區塊，然後驗證該區塊在下一輪已清除。
  • 檢查閘道記錄（使用 --verbose 執行），確認 inbound web message 項目顯示 from: <groupJid> 以及標有傳送者的本文。

已知注意事項

  • 心跳偵測在代理程式的主要工作階段中執行；群組工作階段永遠不會執行心跳偵測。
  • 回音抑制功能會依工作階段記住合併後的提示（歷史記錄 + 目前訊息），避免機器人自己已傳送的訊息再次觸發；完全相同的重複批次可能會被判定為回音而略過。
  • 工作階段儲存區中的項目會以 agent:<agentId>:whatsapp:group:<jid> 顯示於各代理程式的 SQLite 工作階段儲存區；缺少項目只表示該群組尚未觸發執行。
  • 輸入指示器遵循 session.typingMode／agents.defaults.typingMode。當可見回覆選擇僅限訊息工具模式時，輸入指示預設會立即開始，讓群組成員即使在未發布自動最終回覆時，也能看到代理程式正在處理。明確的輸入模式設定仍具有優先權。

相關內容

Was this useful?
On this page

On this page