文档
群组消息（WhatsApp web 通道）

群组消息（WhatsApp web 通道）

适用范围

在以下情况使用此页面：

  • 更改群组消息规则或提及

目标：让 Clawdb 坐在 WhatsApp 群组中，仅在 ping 时唤醒，并将该线程与个人 DM 会话分开。

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

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

  • 激活模式：mention（默认）或 always。mention 需要 ping（通过 mentionedJids 的真实 WhatsApp @-提及、正则表达式模式或文本中任何位置的机器人 E.164）。always 在每条消息上唤醒代理，但它应该只在可以添加有意义的值时回复；否则它返回静默令牌 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 之类的命令（作为独立消息发送）的作用域限于该组；个人 DM 状态保持不变。群组线程跳过心跳。
  • 上下文注入：仅待处理的群组消息（默认 50 条）未 触发运行的消息以 [Chat messages since your last reply - for context] 为前缀，触发行位于 [Current message - respond to this] 下。会话中已有的消息不会被重新注入。
  • 发件人显示：每个组批次现在以 [from: Sender Name (+E164)] 结尾，以便 Pi 知道谁在说话。
  • 临时/查看一次：我们在提取文本/提及之前解包这些消息，因此其中的 ping 仍然会触发。
  • 群组系统提示：在群组会话的第一轮（以及每当 /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）

将 groupChat 块添加到 ~/.moltbot/moltbot.json，以便即使 WhatsApp 在文本正文中剥离视觉 @，显示名称 ping 仍然有效：

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

注意：

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

激活命令（仅所有者）

使用群组聊天命令：

  • /activation mention
  • /activation always

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

如何使用

  1. 将您的 WhatsApp 帐户（运行 Moltbot 的帐户）添加到群组。
  2. 说 @moltbot …（或包括号码）。除非您设置 groupPolicy: "open"，否则只有允许的发件人可以触发它。
  3. 代理提示将包括最近的群组上下文加上尾随的 [from: …] 标记，以便它可以称呼正确的人。
  4. 会话级指令（/verbose on、/think high、/new 或 /reset、/compact）仅应用于该群组的会话；将它们作为独立消息发送，以便它们注册。您的个人 DM 会话保持独立。

测试/验证

  • 手动冒烟：
    • 在群组中发送 @clawd ping 并确认引用发件人姓名的回复。
    • 发送第二次 ping 并验证历史记录块在下一轮被包括然后被清除。
  • 检查网关日志（使用 --verbose 运行）以查看 inbound web message 条目，显示 from: <groupJid> 和 [from: …] 后缀。

已知注意事项

  • 群组有意跳过心跳以避免嘈杂的广播。
  • 回显抑制使用组合的批次字符串；如果您在没有提及的情况下发送两次相同的文本，只有第一次会得到响应。
  • 会话存储条目将在会话存储中显示为 agent:<agentId>:whatsapp:group:<jid>（默认 ~/.moltbot/agents/<agentId>/sessions/sessions.json）；缺少条目仅意味着该群组尚未触发运行。
  • 群组中的打字指示符遵循 agents.defaults.typingMode（默认：在未提及时为 message）。
群组上下文