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 随后允许精确的静默 tokenNO_REPLY(不区分大小写)。有关全局设置和优先级,请参阅 静默回复。激活默认值来自配置(channels.whatsapp.groupsrequireMention),并可通过/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,以查看当前激活模式。
如何使用¶
- 将你的 WhatsApp 账户(运行 OpenClaw 的那个)添加到群组。
- 说
@openclaw ...(或包含号码)。除非你设置groupPolicy: "open",否则只有允许列表中的发送者可以触发它。 - 代理 prompt 包含待处理群组上下文以及带发送者标签的行,以便它可以称呼正确的人。
- 会话指令(
/verbose on、/trace on、/think high、/new或/reset、/compact)仅适用于该群组的会话;请作为独立消息发送它们,以便它们生效。你的个人私信会话保持独立。
测试 / 验证¶
- 手动冒烟测试:
- 在群组中发送一个
@openclawping,并确认回复引用了发送者名称。 - 发送第二个 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