WhatsApp 群组消息

对于跨渠道群组模型（Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo），请参阅群组。本页介绍该模型之上的 WhatsApp 专属行为：激活、群组允许列表、按群组划分的会话键，以及待处理消息上下文注入。

目标：让 OpenClaw 驻留在 WhatsApp 群组中，只在被 ping 时唤醒，并将该线程与个人私信会话分开。

# 行为

• 激活模式：mention（默认）或 always。mention 需要 ping（通过 mentionedJids 传递的真实 WhatsApp @ 提及、安全的正则模式，或文本中任意位置的机器人 E.164 号码）。always 会在每条消息上唤醒智能体，但它只应在能提供有意义价值时回复；否则返回精确的静默令牌 NO_REPLY / 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、/trace on 或 /think high（作为独立消息发送）等命令仅作用于该群组；个人私信状态不受影响。群组线程会跳过 Heartbeat。
• 上下文注入：仅待处理的群组消息（默认 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 块，这样即使 WhatsApp 从正文中剥离可见的 @，显示名称 ping 也能工作：

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

说明：

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

# 激活命令（仅所有者）

使用群聊命令：

• /activation mention
• /activation always

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

# 使用方法

1. 将你的 WhatsApp 账号（运行 OpenClaw 的那个账号）添加到群组。
2. 发送 @openclaw …（或包含号码）。除非你设置 groupPolicy: "open"，否则只有允许列表中的发送者可以触发它。
3. 智能体提示会包含最近的群组上下文以及末尾的 [from: …] 标记，以便它能称呼正确的人。
4. 会话级指令（/verbose on、/trace on、/think high、/new 或 /reset、/compact）仅适用于该群组的会话；请将它们作为独立消息发送，以便它们被注册。你的个人私信会话保持独立。

# 测试 / 验证

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

# 已知注意事项

• 群组会有意跳过 Heartbeat，以避免产生嘈杂的广播。
• 回声抑制使用组合后的批次字符串；如果你发送两次不带提及的相同文本，只有第一次会获得响应。
• 会话存储条目会在会话存储中显示为 agent:<agentId>:whatsapp:group:<jid>（默认位于 ~/.openclaw/agents/<agentId>/sessions/sessions.json）；缺失条目只表示该群组尚未触发运行。
• 群组中的输入指示器遵循 agents.defaults.typingMode。当可见回复使用默认的仅消息工具模式时，输入默认会立即开始，因此即使没有发布自动最终回复，群组成员也能看到智能体正在工作。显式的输入模式配置仍然优先。

# 相关

• 群组
• 渠道路由
• 广播群组