Group messages（WhatsApp web channel）

目标：让 Clawd 待在 WhatsApp 群里，只在被 @ 时醒来，并把该线程与个人 DM session 分离。

注意：agents.list[].groupChat.mentionPatterns 现在也用于 Telegram/Discord/Slack/iMessage；本文聚焦 WhatsApp 专属行为。对 multi-agent 场景，请按 agent 设置 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作为全局 fallback）。

已实现内容（2025-12-03）

激活模式：mention（默认）或 always。
- mention 需要被 ping：真实 WhatsApp @mentions（通过 mentionedJids）、regex patterns，或文本中任意位置出现 bot 的 E.164。
- always 会在每条消息唤醒 agent，但它只应在能提供有意义价值时回复；否则返回静默 token NO_REPLY。
- 默认值可在配置中设置（channels.whatsapp.groups），并可通过 /activation 按群覆盖。
- 当设置了 channels.whatsapp.groups 时，它也会作为群 allowlist（加入 "*" 表示允许所有群）。
群策略：channels.whatsapp.groupPolicy 控制是否接收群消息（open|disabled|allowlist）。
- allowlist 使用 channels.whatsapp.groupAllowFrom（fallback：显式 channels.whatsapp.allowFrom）。
- 默认是 allowlist（在添加允许的发送者之前会被阻止）。
按群分 session：session keys 形如 agent:<agentId>:whatsapp:group:<jid>，因此 /verbose on、/think high 等命令（作为独立消息发送）只作用于该群；个人 DM 状态不受影响。群线程会跳过 heartbeats。
上下文注入：pending-only 的群消息（默认 50 条）若未触发 run，会被放在 [Chat messages since your last reply - for context] 之下；触发 run 的那一行放在 [Current message - respond to this] 之下。已在 session 中的消息不会被重复注入。
Sender 展示：每个群 batch 末尾都会追加 [from: Sender Name (+E164)]，便于 Pi 知道谁在说话。
Ephemeral/view-once：在提取文本/mentions 之前会先解包，因此其中的 ping 仍可触发。
群 system prompt：在群 session 的第一回合（以及每次 /activation 改变模式时），我们会向 system 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/moltbot.json 添加一个 groupChat 区块，使得当 WhatsApp 在 body 文本中去掉可见的 @ 时，display-name pings 仍能匹配：

json5

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

备注：

这些正则是大小写不敏感的；既覆盖 @moltbot 这类 display-name ping，也覆盖带或不带 +/空格的原始号码。
WhatsApp 在用户点选联系人时仍会通过 mentionedJids 发送规范化 mentions，因此“号码兜底”通常不需要，但作为安全网很有用。

Activation 命令（仅 owner）

使用群聊命令：

/activation mention
/activation always

只有 owner 号码（来自 channels.whatsapp.allowFrom，未设置时使用 bot 自身 E.164）可以修改。把 /status 作为独立消息发到群里，可查看当前 activation 模式。

如何使用

把运行 Moltbot 的 WhatsApp 账号加入群。
发送 @moltbot …（或包含号码）。除非你把 groupPolicy: "open"，否则只有 allowlisted senders 能触发。
agent prompt 会包含近期群上下文 + 末尾的 [from: …] 标记，从而能对正确的人回应。
session 级 directives（/verbose on、/think high、/new//reset、/compact）只作用于该群 session；请作为独立消息发送以便生效。个人 DM session 保持独立。

测试 / 验证

手工 smoke：
- 在群里发送 @clawd ping，并确认回复能引用发送者名字。
- 再发一次 ping，确认历史区块被包含，并在下一回合清空。
查看 gateway logs（用 --verbose 运行），寻找 inbound web message 条目，其中包含 from: <groupJid> 与 [from: …] 后缀。

已知注意事项

群聊会刻意跳过 heartbeats，以避免噪音广播。
Echo suppression 使用合并后的 batch 字符串；如果你连续两次发送完全相同的文本且没有 mentions，则只有第一次会得到响应。
session store 条目会在 session store（默认 ~/.openclaw/agents/<agentId>/sessions/sessions.json）中显示为 agent:<agentId>:whatsapp:group:<jid>；缺少条目只是表示该群尚未触发过 run。
群里的 typing indicators 遵循 agents.defaults.typingMode（默认：在未 mention 时为 message）。

Group messages（WhatsApp web channel） ​

已实现内容（2025-12-03） ​

配置示例（WhatsApp） ​

Activation 命令（仅 owner） ​

如何使用 ​

测试 / 验证 ​