WhatsApp 群组消息

WhatsApp 特有的群组消息处理行为，包括激活模式、白名单、会话键和上下文注入。跨平台通用群组模型见 channel-groups。

激活模式

mention（默认）：需要 @mention 触发（通过 mentionedJids、安全正则或 E.164 号码）
always：每条消息都唤醒 agent，但无实质价值时返回 NO_REPLY

通过 /activation mention 或 /activation always 命令切换（仅 owner 可操作）。

配置示例

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

群组策略

channels.whatsapp.groupPolicy：open | disabled | allowlist

allowlist 使用 groupAllowFrom（回退到 allowFrom）
默认 allowlist（未添加发送者则阻止）

会话键

每个群组独立会话：agent:<agentId>:whatsapp:group:<jid>

群组命令（/verbose on、/trace on、/think high）仅作用于该群组会话
个人 DM 会话不受影响
群组会话不发送心跳

上下文注入

未触发运行的待处理群组消息（默认 50 条）以 [Chat messages since your last reply - for context] 前缀注入
触发消息以 [Current message - respond to this] 标注
每条消息末尾附加 [from: Sender Name (+E164)]

特殊处理

Ephemeral/view-once 消息：解包后提取文本/mention，其中的 @mention 仍可触发
群组系统提示：首次会话注入群组信息（名称、成员列表、激活模式）

使用流程

将 WhatsApp 账号加入群组
发送 @openclaw …（或包含号码）
Agent 提示包含近期群组上下文和 [from: …] 标记
会话级指令（/verbose on、/new 等）作为独立消息发送

Wiki AI

目录