跳转至

WhatsApp 群组

对于跨渠道群组模型(Discord、iMessage、Matrix、Microsoft Teams、QQBot、Signal、Slack、Telegram、WhatsApp、Zalo),请参阅 群组。本页介绍在该模型之上的 WhatsApp 特定行为:激活、群组允许列表、按群组的会话键,以及待处理消息上下文注入。

目标:让 OpenClaw 驻留在 WhatsApp 群组中,仅在被 ping 时唤醒,并将该线程与个人私信会话保持隔离。

Note

agents.entries.*.groupChat.mentionPatterns 与其他渠道的提及门控共享。对于多代理设置,请为每个代理单独设置,或使用 messages.groupChat.mentionPatterns 作为全局回退。如果两者都未设置,模式将从代理身份名称/表情符号派生。

行为

  • 激活模式:mention(默认)或 always。mention 需要一次 ping:真实的 WhatsApp @-提及(mentionedJids)、已配置的正则表达式模式、文本中任意位置的 bot 的 E.164 数字,或对 bot 消息之一的引用回复(共享号码自聊设置除外)。always 会为每条被接受的消息唤醒代理,并且默认要求回复。若要允许对未直接提及的消息选择性沉默,请显式设置 surfaces.whatsapp.silentReply.group: "allow";自动回复 prompt 随后允许精确的静默 token 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(作为独立消息发送)等指令仅作用于该群组;个人私信状态不受影响。
  • 上下文注入:仅待处理的群组消息(默认 50 条)中,_未_触发运行的消息会在 [Chat messages since your last reply - for context] 前缀下注入,触发行位于 [Current message - respond to this] 下。运行结束后,待处理窗口会被清除;已在会话中的消息不会被重新注入。
  • 发送者归属:每条群组消息行都在消息信封内携带发送者标签,例如 [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text,并且发送者身份以及群组主题/成员会随不可信的会话元数据块一起携带。
  • 临时/仅一次查看:在提取文本/提及之前会解包包装器,因此其中的 ping 仍会触发。
  • 群组系统 prompt:群组会话的第一轮(以及 /activation 更改模式后的任何一轮)都会向系统 prompt 注入激活指导(Activation: trigger-only ... 或 Activation: always-on ...,外加“address the specific sender”)。持久的群组聊天投递指导(“You are in a WhatsApp group chat...”)始终包含在内。

配置示例(WhatsApp)

即使 WhatsApp 从文本正文中移除视觉 @,也让显示名称 ping 生效:

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
      historyLimit: 50, // pending group context window (default 50)
    },
  },
  agents: {
    entries: {
      main: {
        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,未设置时为 bot 自身的 E.164)可以更改此项;来自其他人的 /activation 会被忽略,仅作为上下文存储。在群组中作为独立消息发送 /status,以查看当前激活模式。

如何使用

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

测试 / 验证

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

已知注意事项

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw