群组消息（WhatsApp web channel）

目标：让 Clawd 可以待在 WhatsApp 群组里，只在被提及时才响应，并且把群组对话和个人 DM 的 Session 分开。

注意：agents.list[].groupChat.mentionPatterns 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档主要关注 WhatsApp 特有的行为。对于多 Agent 设置，可以为每个 Agent 单独设置 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作为全局默认值）。

已实现的功能（2025-12-03）

  • 激活模式：mention（默认）或 always。mention 模式需要被提及才会响应（通过 WhatsApp 真实的 @提及、mentionedJids、正则表达式匹配，或消息文本中任何位置出现机器人的 E.164 号码）。always 模式会在每条消息时唤醒 Agent，但它只应在能提供有意义价值时才回复；否则返回静默 token NO_REPLY。默认值可以在配置中设置（channels.whatsapp.groups），并可通过 /activation 命令为每个群组单独覆盖。当设置了 channels.whatsapp.groups 时，它也会作为群组白名单（包含 "*" 表示允许所有群组）。
  • 群组策略：channels.whatsapp.groupPolicy 控制是否接受群组消息（open|disabled|allowlist）。allowlist 使用 channels.whatsapp.groupAllowFrom（回退到显式的 channels.whatsapp.allowFrom）。默认是 allowlist（在你添加发送者之前会被阻止）。
  • 独立群组 Session：Session 键的格式是 agent:<agentId>:whatsapp:group:<jid>，所以像 /verbose on 或 /think high 这样的命令（作为独立消息发送）只作用于该群组；个人 DM 的状态不受影响。群组对话会跳过 Heartbeat。
  • Context 注入：仅待处理的群组消息（默认 50 条）_没有_触发运行的消息会被添加到 [Chat messages since your last reply - for context] 前缀下，触发消息则在 [Current message - respond to this] 下。已经在 Session 中的消息不会重复注入。
  • 发送者标识：每个群组消息批次现在都会以 [from: Sender Name (+E164)] 结尾，这样 Pi 就知道是谁在说话。
  • 阅后即焚/仅查看一次：我们会在提取文本/提及之前解包这些消息，所以里面的提及仍然会触发。
  • 群组系统 Prompt：在群组 Session 的第一轮（以及每次 /activation 改变模式时），我们会在系统 Prompt 中注入一段简短说明，比如 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. 如果元数据不可用，我们仍会告诉 Agent 这是群组聊天。

配置示例（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. Agent Prompt 会包含最近的群组 Context 以及尾部的 [from: …] 标记，这样它就能回复正确的人。
  4. Session 级别的指令（/verbose on、/think high、/new 或 /reset、/compact）只应用于该群组的 Session；将它们作为独立消息发送以便注册。你的个人 DM Session 保持独立。

测试/验证

  • 手动冒烟测试：
    • 在群组中发送 @openclaw 提及，确认回复中引用了发送者名称。
    • 发送第二次提及，验证历史记录块被包含，然后在下一轮被清除。
  • 检查 Gateway 日志（使用 --verbose 运行）以查看 inbound web message 条目，显示 from: <groupJid> 和 [from: …] 后缀。

已知注意事项

  • Heartbeat 会故意跳过群组，以避免嘈杂的广播。
  • 回声抑制使用组合的批次字符串；如果你发送两次相同的文本而没有提及，只有第一次会得到响应。
  • Session 存储条目会显示为 agent:<agentId>:whatsapp:group:<jid>，存储在 Session 存储中（默认为 ~/.openclaw/agents/<agentId>/sessions/sessions.json）；缺少条目只是意味着该群组还没有触发过运行。
  • 群组中的输入指示器遵循 agents.defaults.typingMode（默认：未被提及时为 message）。