群组消息（WhatsApp web 渠道）

目标：让你的龙虾待在 WhatsApp 群组里，只在被@时才醒来，并将群组会话与个人私信会话完全隔离。

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

当前实现

激活模式：mention（默认）或 always。mention 需要被@（通过 mentionedJids 的真实 WhatsApp @提及、安全正则模式，或文本中任意位置的 Bot E.164 号码）。always 对每条消息都唤醒 Agent，但 Agent 应只在能提供有意义内容时才回复，否则返回静默 token 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: 发送者名称 (+E164)]，让 Agent 知道谁在说话
阅后即焚/仅查看一次：在提取文本/提及之前解包，其中的@提及仍可触发
群组系统提示：在群组会话的第一轮（以及 /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）

在 ~/.openclaw/openclaw.json 中添加 groupChat 块，使显示名称@提及即使 WhatsApp 在文本正文中去掉视觉 @ 也能正常工作：

json5

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

注意：

正则表达式不区分大小写，使用与其他配置正则接口相同的安全正则防护；无效模式和不安全的嵌套重复会被忽略
WhatsApp 在有人点击联系人时仍通过 mentionedJids 发送规范@提及，因此号码回退很少需要，但是一个有用的安全网

激活命令（仅限所有者）

在群聊中使用以下命令：

/activation mention
/activation always

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

使用方法

将你的 WhatsApp 账号（运行 OpenClaw 的那个）添加到群组
说 @openclaw …（或包含号码）。只有白名单中的发送者才能触发，除非设置 groupPolicy: "open"
Agent 提示中包含最近的群组上下文和末尾的 [from: …] 标记，方便它向正确的人回复
会话级指令（/verbose on、/think high、/new 或 /reset、/compact）只作用于该群组的会话；作为独立消息发送以便注册。你的个人私信会话保持独立

测试 / 验证

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

已知注意事项

心跳检测对群组有意跳过，避免广播噪声
回声抑制使用合并的批量字符串；若你发送相同文本两次而不带@提及，只有第一条会得到回复
会话存储条目显示为 agent:<agentId>:whatsapp:group:<jid>（在会话存储 ~/.openclaw/agents/<agentId>/sessions/sessions.json 中）；缺少条目只意味着该群组还没有触发过运行
群组中的打字提示遵循 agents.defaults.typingMode（未被提及时默认为 message）

群组消息（WhatsApp web 渠道） ​

当前实现 ​

配置示例（WhatsApp） ​

激活命令（仅限所有者） ​

使用方法 ​

测试 / 验证 ​