群组消息 (WhatsApp Web 渠道)

目标：让 Clawd 能够参与 WhatsApp 群组，仅在被提及（ping）时唤醒，并将该线程与个人私聊（DM）会话分开。

注意：agents.list[].groupChat.mentionPatterns 现在也由 Telegram/Discord/Slack/iMessage 使用；本文件侧重于 WhatsApp 特有的行为。对于多 Agent 设置，请为每个 Agent 设置 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作为全局回退）。

已实现的功能 (2025-12-03)

激活模式：mention（默认）或 always。mention 模式需要提及（通过 mentionedJids 进行真正的 WhatsApp @提及、正则表达式模式，或在文本任何位置出现机器人的 E.164 号码）。always 模式会在每条消息时唤醒 Agent，但它只有在能提供有意义的价值时才应回复；否则它会返回静默令牌 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（作为独立消息发送）的作用域仅限于该群组；个人私聊状态不受影响。群组线程会跳过心跳。
上下文注入：仅限待定 (pending-only) 的群组消息（默认 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. 如果元数据不可用，我们仍会告诉 Agent 这是一个群聊。

配置示例 (WhatsApp)

在 ~/.clawdbot/clawdbot.json 中添加 groupChat 块，这样即使 WhatsApp 在正文中去掉了视觉上的 @，显示名称的提及（ping）仍然有效：

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

注意：

正则表达式不区分大小写；它们涵盖了显示名称提及（如 @clawdbot）以及带或不带 +/空格的原始号码。
当有人点击联系人时，WhatsApp 仍会通过 mentionedJids 发送规范的提及，因此号码回退很少需要，但它是一个有用的安全网。

激活命令 (仅限所有者)

使用群聊命令：

/activation mention
/activation always

只有所有者号码（来自 channels.whatsapp.allowFrom，如果未设置，则为机器人自身的 E.164）可以更改此设置。在群组中发送 /status 作为独立消息，以查看当前的激活模式。

如何使用

将您的 WhatsApp 帐户（运行 Clawdbot 的帐户）添加到群组中。
说 @clawdbot …（或包含号码）。除非您将 groupPolicy 设置为 "open"，否则只有白名单中的发送者才能触发它。
Agent 提示词将包含最近的群组上下文以及结尾的 [from: …] 标记，以便它可以称呼正确的人。
会话级指令（/verbose on, /think high, /new 或 /reset, /compact）仅适用于该群组的会话；将它们作为独立消息发送以便注册。您的个人私聊会话保持独立。

测试 / 验证

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

已知考量

群组会有意跳过心跳，以避免嘈杂的广播。
回显抑制使用组合后的批处理字符串；如果您发送了两次不带提及的相同文本，则只有第一条会得到响应。
会话存储条目将以 agent:<agentId>:whatsapp:group:<jid> 的形式出现在会话存储中（默认在 ~/.clawdbot/agents/<agentId>/sessions/sessions.json）；条目缺失仅表示该群组尚未触发过运行。
群组中的输入指示器（Typing indicators）遵循 agents.defaults.typingMode（默认：未提及消息时为 message）。

群组消息 (WhatsApp Web 渠道)

已实现的功能 (2025-12-03)​

配置示例 (WhatsApp)​

激活命令 (仅限所有者)​

如何使用​

测试 / 验证​

已知考量​