群组消息（Group messages）（WhatsApp web channel）

目标：让 Clawd 待在 WhatsApp 群组中，只在被提及时唤醒，并将该会话线程与个人私聊会话（DM session）分开。

注意：agents.list[].groupChat.mentionPatterns 现在也被 Telegram/Discord/Slack/iMessage 使用；本文档聚焦于 WhatsApp 特定的行为。对于多代理（multi-agent）设置，为每个代理设置 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作为全局后备）。

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

  • 激活模式（Activation modes）：mention（默认）或 always。mention 需要一个 ping（通过 mentionedJids 的真实 WhatsApp @提及、正则模式或消息文本中任何位置的机器人 E.164 号码）。always 在每条消息时唤醒代理，但它应该仅在能添加有意义价值时回复；否则返回静默令牌（silent token）NO_REPLY。默认值可在配置中设置（channels.whatsapp.groups），并可通过 /activation 针对每个群组覆盖。当设置了 channels.whatsapp.groups 时，它也充当群组白名单（allowlist）（包含 "*" 以允许所有群组）。
  • 群组策略（Group policy）：channels.whatsapp.groupPolicy 控制是否接受群组消息（open|disabled|allowlist）。allowlist 使用 channels.whatsapp.groupAllowFrom（后备：显式的 channels.whatsapp.allowFrom）。默认值为 allowlist（在您添加发送者之前会被阻止）。
  • 每个群组的会话（Per-group sessions）：会话密钥（session keys）看起来像 agent:<agentId>:whatsapp:group:<jid>，因此诸如 /verbose on 或 /think high 之类的命令（作为独立消息发送）的作用域限定在该群组；个人私聊状态不受影响。群组会话线程会跳过心跳（Heartbeats）。
  • 上下文注入（Context injection）：仅待处理的群组消息（默认 50 条）未触发运行的消息会在 [Chat messages since your last reply - for context] 下作为前缀，触发的那行在 [Current message - respond to this] 下。已在会话中的消息不会重新注入。
  • 发送者显示（Sender surfacing）：现在每个群组批次都以 [from: Sender Name (+E164)] 结尾，以便 Pi 知道是谁在说话。
  • 临时/一次性查看（Ephemeral/view-once）：我们在提取文本/提及之前解包这些消息，因此其中的 pings 仍会触发。
  • 群组系统提示（Group system prompt）：在群组会话的第一轮（以及每当 /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）

在 ~/.openclaw/openclaw.json 中添加一个 groupChat 块，以便即使 WhatsApp 在消息正文中去掉视觉上的 @，显示名称 ping 也能工作：

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

注意：

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

激活命令（仅所有者）

使用群聊命令：

  • /activation mention
  • /activation always

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

如何使用

  1. 将您的 WhatsApp 账户（运行 OpenClaw 的账户）添加到群组。
  2. 说 @openclaw …（或包含号码）。只有白名单发送者可以触发它，除非您设置 groupPolicy: "open"。
  3. 代理提示将包括最近的群组上下文加上尾随的 [from: …] 标记，以便它可以针对正确的人进行回复。
  4. 会话级指令（/verbose on、/think high、/new 或 /reset、/compact）仅适用于该群组的会话；将它们作为独立消息发送以便注册。您的个人私聊会话保持独立。

测试/验证

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

已知注意事项

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