WhatsApp 群组

For the cross-channel groups model (Discord, iMessage,Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo), see Groups. This page covers the WhatsApp-specific behavior on top of that model: activation, group allowlists, per-group session keys, and pending-message context injection.

Goal: let OpenClaw sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.

行为¶

• 激活模式：mention（默认）或 always。mention 需要一次呼叫：真实的 WhatsApp @提及（mentionedJids）、已配置的正则表达式模式、文本任意位置出现机器人的 E.164 数字，或引用回复机器人的一条消息（共享号码自聊设置除外）。always 会在每个被接受的消息上唤醒智能体，并默认要求回复。若要允许对未直接提及的消息选择性保持沉默，请显式设置 surfaces.whatsapp.silentReply.group: "allow"；自动回复提示随后允许精确的静默令牌 NO_REPLY（不区分大小写）。有关全局设置和优先级，请参阅 静默回复。激活默认值来自配置（channels.whatsapp.groups 的 requireMention），并可通过 /activation 按群组覆盖。
• 群组允许列表：当设置 channels.whatsapp.groups 时，仅接受列出的群组 JID（包含 "*" 可允许全部）；来自未列出群组的消息会被丢弃并记录日志提示。
• 群组策略：channels.whatsapp.groupPolicy 控制是否接受群组消息（open|disabled|allowlist）。allowlist 使用 channels.whatsapp.groupAllowFrom（回退：显式 channels.whatsapp.allowFrom）。默认值为 allowlist（在添加发送者之前会被阻止）。
• 按群组会话：会话键形如 agent:<agentId>:whatsapp:group:<jid>（非默认账户会追加 :thread:whatsapp-account-<accountId>），因此诸如 /verbose on、/trace on 或 /think high（作为独立消息发送）等指令仅作用于该群组；个人 DM 状态不受影响。
• 上下文注入：仅待处理的群组消息（默认 50 条）中_未_触发运行的消息会置于 [Chat messages since your last reply - for context] 之下，触发行置于 [Current message - respond to this] 之下。运行之后会清除待处理窗口；已在会话中的消息不会被重新注入。
• 发送者归属：每条群组消息行都在消息信封内携带发送者标签，例如 [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text，发送者身份以及群组主题/成员会随不可信的会话元数据块一起传递。
• 临时/阅后即焚：在提取文本/提及之前会先解包，因此其中的呼叫仍会触发。
• 群组系统提示：群组会话的第一轮（以及 /activation 更改模式后的任何一轮）会向系统提示注入激活指引（Activation: trigger-only ... 或 Activation: always-on ...，外加“针对特定发送者”）。持久的群聊投递指引（“You are in a WhatsApp group chat...”）始终包含。

配置示例（WhatsApp）¶

即使 WhatsApp 从文本正文中移除视觉上的 @，也能让显示名称呼叫生效：

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
      historyLimit: 50, // pending group context window (default 50)
    },
  },
  agents: {
    entries: {
      main: {
        default: true,
        groupChat: {
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    },
  },
}

说明：

• 这些正则表达式不区分大小写，并使用与其他配置正则表达式位置相同的安全正则表达式防护；无效模式和存在风险的嵌套重复会被忽略。
• 当有人点击联系人时，WhatsApp 仍会通过 mentionedJids 发送规范提及，因此号码回退很少需要，但可作为有用的安全网。
• 待处理上下文窗口按 channels.whatsapp.accounts.<id>.historyLimit → channels.whatsapp.historyLimit → messages.groupChat.historyLimit → 50 解析。

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

使用群聊命令：

• /activation mention
• /activation always

只有所有者号码（来自 channels.whatsapp.allowFrom，未设置时为机器人自身的 E.164）可以更改此项；其他人发送的 /activation 会被忽略，仅作为上下文存储。在群组中作为独立消息发送 /status 可查看当前激活模式。

使用方法¶

1. 将你的 WhatsApp 账户（运行 OpenClaw 的那个）添加到群组。
2. 发送 @openclaw ...（或包含号码）。除非设置 groupPolicy: "open"，否则仅允许列表中的发送者可以触发。
3. 智能体提示包含待处理群组上下文以及带发送者标签的行，以便其能够称呼正确的人。
4. 会话指令（/verbose on、/trace on、/think high、/new 或 /reset、/compact）仅适用于该群组的会话；请作为独立消息发送，以便它们生效。你的个人 DM 会话保持独立。

测试 / 验证¶

• 手动冒烟测试：
• 在群组中发送 @openclaw 呼叫，并确认回复中引用了发送者名称。
• 发送第二次呼叫，验证历史块被包含，然后在下一轮清除。
• 检查网关日志（使用 --verbose 运行），查找显示 from: <groupJid> 和带发送者标签正文的 inbound web message 条目。

已知注意事项¶

• 心跳在智能体的主会话中运行；群组会话永远不会获得心跳运行。
• 回声抑制按会话记住组合提示（历史 + 当前消息），因此机器人自己已发送的消息不会再次触发它；完全相同的重复批次可作为回声跳过。
• 会话存储条目在按智能体的 SQLite 会话存储中显示为 agent:<agentId>:whatsapp:group:<jid>；缺少条目仅表示该群组尚未触发运行。
• 正在输入指示器遵循 agents.entries.*.typingMode / agents.defaults.typingMode。当可见回复选择仅消息工具模式时，默认立即开始输入，以便群组成员可以看到智能体正在工作，即使没有发布自动最终回复。显式的输入模式配置仍然优先。

相关¶

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