群组消息（WhatsApp web 频道）

目标：让 Clawd 待在 WhatsApp 群组里，只有被提及时才唤醒回复，同时保持该群的对话线程与个人私信会话隔离。

说明：agents.list[].groupChat.mentionPatterns 现在也被 Telegram/Discord/Slack/iMessage 使用；本文聚焦 WhatsApp 特有的行为。对于多代理场景，请为每个代理设置 agents.list[].groupChat.mentionPatterns（或使用 messages.groupChat.mentionPatterns 作为全局回退）。

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

  • 激活模式：mention（默认）或 always。mention 模式需要被提及（通过 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 知道谁在说话。
  • 阅后即焚/单次查看：这些消息在提取文本/提及之前会被展开，因此其中的提及仍能触发响应。
  • 群组系统提示：在群组会话的首轮（以及 /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 去除文本正文中的可视 @ 时也能生效：

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

说明：

  • 正则表达式不区分大小写；覆盖了 @openclaw 这样的显示名提及和带或不带 +/空格的原始号码。
  • 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 提及，确认回复中引用了发送者姓名。
    • 再发送一次提及，确认历史记录块被包含，然后在下一轮清除。
  • 检查 Gateway 日志（以 --verbose 运行），查看 inbound web message 条目中显示的 from: <groupJid> 和 [from: …] 后缀。

已知注意事项

  • 群组有意跳过心跳以避免噪音广播。
  • 回声抑制使用组合批次字符串；如果你在没有提及的情况下连续发送相同文本，只有第一条会得到响应。
  • 会话存储条目将在会话存储中显示为 agent:<agentId>:whatsapp:group:<jid>（默认路径 ~/.openclaw/agents/<agentId>/sessions/sessions.json）；缺少条目只是意味着该群组尚未触发过运行。
  • 群组中的输入指示器遵循 agents.defaults.typingMode（默认：未提及时为 message）。
arrow_back
上一页
Pairing
下一页
Groups
arrow_forward