群组消息(WhatsApp web 渠道)

目标:让 Clawd 加入 WhatsApp 群组,仅在被 ping 时唤醒,并将该对话线程与个人私聊会话分开。

注意: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(作为独立消息发送)的作用范围限定在该群组;个人私聊状态不受影响。群组线程会跳过心跳。
上下文注入:仅待处理的群组消息(默认 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)

在 ~/.openclaw/openclaw.json 中添加 groupChat 块,以便显示名称 ping 即使在 WhatsApp 从文本正文中剥离可视 @ 时也能工作:

json5

{
  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 以查看当前激活模式。

如何使用

将您的 WhatsApp 账户(运行 OpenClaw 的账户)添加到群组。
说 @openclaw …(或包含号码)。除非您设置 groupPolicy: "open",否则只有允许列表中的发送者可以触发它。
代理提示将包含最近的群组上下文以及尾随的 [from: …] 标记,以便它可以向正确的人发言。
会话级指令(/verbose on、/think high、/new 或 /reset、/compact)仅适用于该群组的会话;将它们作为独立消息发送以便注册。您的个人私聊会话保持独立。

测试/验证

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

已知注意事项

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

群组消息(WhatsApp web 渠道) ​

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

配置示例(WhatsApp) ​

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

如何使用 ​

测试/验证 ​