本页内容
本页内容
主流消息传递
状态:通过 WhatsApp Web(Baileys)达到生产可用。网关拥有已关联的会话;不存在单独的 Twilio WhatsApp 频道。
设置
安装
openclaw onboard和openclaw channels add --channel whatsapp首次选择时提示安装插件;如果插件丢失,openclaw channels login --channel whatsapp 提供相同的安装流程。开发检查使用本地插件路径; stable/beta 首先从 npm 安装 @openclaw/whatsapp,然后仅当 npm 目标不可用时才回退到其声明的 ClawHub 包。 WhatsApp 运行时在核心 OpenClaw npm 包之外提供,因此其运行时依赖项仍保留在外部插件中。手动安装:
使用 npm:@openclaw/whatsapp 或 clawhub:@openclaw/whatsapp 强制源;仅针对可重复安装固定精确版本。
快速设置
配置访问策略
链接 WhatsApp (QR)
登录名为 QR-only。在远程或无头主机上,在开始登录之前有可靠的路径将实时 QR 传送到电话;终端呈现的 QR、屏幕截图或聊天附件可能会在传输过程中过期。
对于特定账号:
要在登录前附加 existing/custom 身份验证目录:
启动网关
批准第一个DM访问请求(配对模式)
打开设置→通道→DM访问请求,找到WhatsApp账户,并批准发件人。如果您更喜欢 CLI:
DM 访问请求1小时后过期;每个帐户的待处理请求上限为 3 个。此批准与用于链接帐户本身的 WhatsApp 登录名 QR 是分开的。
部署模式
专用号码(推荐)
- OpenClaw 的单独 WhatsApp 身份
- clearer DM 许可名单和路由边界
- 降低自聊混淆的可能性
个人号码回退
Onboarding 支持个人号码模式,并写入适合自聊的基线:dmPolicy: "allowlist"、allowFrom,包括您自己的号码 selfChatMode: true。准入及保障规则参见个人号码及自聊行为。
运行时模型
- 网关拥有 WhatsApp socket 和重连循环。
- A 看门狗独立跟踪两个信号:原始 WhatsApp Web 传输活动和应用程序消息活动。安静但已连接的会话不会仅仅因为最近没有消息到达而重新启动;仅当传输帧停止到达固定内部窗口(用户不可配置)或应用程序消息保持静默超过正常消息超时的 4 倍时,它才会强制重新连接。在重新连接最近活动的会话后,第一个窗口将使用较短的正常消息超时而不是 4x 窗口。 OpenClaw 可以自动回复 Baileys 在重新连接早期传递的离线消息,受入站消息 ID 重复数据删除生命周期的限制;初始启动保留了短暂的陈旧历史保护。
- 发送出站消息需要目标账号存在活跃的 WhatsApp 监听器;否则发送会快速失败。
- 当令牌与当前参与者元数据(包括 LID- 支持的组)匹配时,Group 会发送
@+<digits>和@<digits>令牌的附加本机提及元数据(在文本和媒体标题中)。 - 状态和广播聊天(
@status、@broadcast)会被忽略。 - Direct 聊天使用 DM 会话规则(
session.dmScope;默认main将 DM 折叠到座席主会话中)。使用默认值session.groupScope: "per-group",组会话按照 JID (agent:<agentId>:whatsapp:group:<jid>) 进行隔离。 - WhatsApp Channels/Newsletters 可以通过其原生
@newsletterJID 作为显式出站目标,使用频道会话元数据(agent:<agentId>:whatsapp:channel:<jid>)而不是 DM 语义。 - WhatsApp Web 传输遵守网关主机上的标准代理环境变量(
HTTPS_PROXY、HTTP_PROXY、NO_PROXY及其小写变体)。优先使用主机级代理配置,而不是按频道配置。 - 在 Node 和 Bun 上,媒体上传使用相同的代理环境和托管 HTTPS- 代理信任,并针对每个实际上传和重定向主机评估
NO_PROXY,而与 WebSocket 目标无关。 - Media 代理 URL 必须使用 HTTP 或 HTTPS。无效的媒体代理设置会导致上传失败,但不会阻止登录或短信。
使用 MeowCaller 呼叫当前请求者(实验性)
该插件可以在 WhatsApp- 发起的代理回合中公开 whatsapp_call。它使用 MeowCaller 向当前授权请求者发出 WhatsApp 语音呼叫,并在他们应答后播放 OpenClaw TTS 消息。该工具没有目标号码参数,因此提示无法重定向呼叫。默认禁用。
启用实验调用
将 actions.calls: true 添加到 WhatsApp 通道配置中。更改遵循 hot reload:
当该项缺失或为 false 时,OpenClaw 不会公开 whatsapp_call 工具。
安装经过审查的 MeowCaller CLI
该适配器需要在网关主机的 PATH 上执行 meowcaller。直到 MeowCaller PR #7 合并,构建审核分支:
将$HOME/.local/bin添加到网关服务的PATH中;如果更改了网关的服务环境,请重新启动网关。此版本具有显式 pair 和仅发送 notify 命令; notify 不打开麦克风、扬声器、视频设备或诊断捕获。不要替换上游示例 CLI 的 play 命令。
配对 MeowCaller 链接设备
让 WhatsApp 代理检查通话设置(whatsapp_call 状态动作会报告账户特定的状态目录和配对命令)。对于默认账户:
以交互方式运行此命令,从 WhatsApp > 链接设备 扫描 QR,然后等待 MeowCaller linked device ready。将 wa-voip.db 设为私有 — 这是 MeowCaller 会话。非默认帐户从状态操作中获取自己的存储路径;在Windows上,运行其PowerShell命令。
配置TTS并从WhatsApp调用
配置支持电话功能的 TTS 提供程序,然后发送诸如 Call me and say the build finished. 之类的请求。该工具从受信任的入站上下文中解析发件人,合成临时私有 WAV 文件,为有界呼叫窗口运行 MeowCaller,然后删除音频文件。 OpenClaw 显式传递帐户的存储,在 answer/playback/hangup 之后等待零退出状态,并将超时或非零退出视为失败的工具调用。
限制:仅限一对一出站音频呼叫、无任意目标号码、无与聊天连接共享身份验证、无来自个人 number/self-chat 模式的自呼叫、合成音频上限为 60 秒、超出 MeowCaller 的 answer/playback/hangup 完成范围后没有手机端可听接收,并且 OpenClaw 在有界后停止同伴进程115-175第二个窗口(涵盖MeowCaller的连接、接听、播放和关机阶段)。
审批提示
WhatsApp 可以将 exec 和 plugin 的审批提示渲染为 👍/👎 反应,由顶层的审批转发配置控制:
approvals.exec 和 approvals.plugin 相互独立;仅将 WhatsApp 启用为一个通道,只会连接传输层,并不会发送任何内容,除非对应的审批家族已启用并路由到那里。session 模式仅对源自 WhatsApp 的审批传递原生 emoji 审批。target 模式使用共享的转发管道处理显式目标,不会创建单独的 approver-DM 扇出。
WhatsApp 审批反应要求在 allowFrom 中显式指定审批人(或使用 "*")。defaultTo 设置的是普通默认消息目标,而不是审批人列表。在审批解析之前,手动 /approve 命令仍会先经过正常的 WhatsApp 发送者授权路径。
问题反应
对于包含一个非秘密单选问题和一到四个选项的 ask_user 提示,WhatsApp 在选项标签旁边显示 1️⃣ 到 4️⃣。使用匹配的号码对发送的提示作出反应以回答它。 OpenClaw 通过网关将号码映射到存储的选项;过时或重复的点击将被忽略。多问题、多选择和自由文本提示仍然仅限文本回复。正常 WhatsApp DM/group 准入规则授权做出反应的发送者。
插件钩子与隐私
传入的 WhatsApp 消息可能包含个人内容、电话号码、群组标识符、发送者名称以及会话关联字段。除非你主动启用,否则 WhatsApp 不会将传入的 message_received 钩子载荷广播给插件:
将该启用范围限定到 channels.whatsapp.accounts.<id>.pluginHooks.messageReceived 下的某一个账号。仅对你信任能够处理传入 WhatsApp 内容和标识符的插件启用此功能。
访问控制
访问控制和激活
DM 政策
channels.whatsapp.dmPolicy:
| 值 | 行为 |
|---|---|
pairing(默认) |
未知发送者请求配对;所有者批准 |
allowlist |
仅允许 allowFrom 中的发送者 |
open |
需要 allowFrom 包含 "*" |
disabled |
阻止所有私信 |
allowFrom 接受 E.164-style 数字(内部标准化)。它只是一个 DM 发送方访问控制列表 - 它不会将显式出站发送门控到组 JID 或 @newsletter 通道 JID。
多账号覆盖:channels.whatsapp.accounts.<id>.dmPolicy(以及 .allowFrom)会优先于该账号的频道级默认值。
运行时说明:
- 配对会保留在频道 allow-store 中,并与已配置的
allowFrom合并 - 计划的自动化和心跳接收者回退使用显式传送目标或配置的
allowFrom; DM 配对批准不是隐式 cron/heartbeat 收件人 - 允许同号自DM,除非
selfChatMode: false或dmPolicy: "disabled";参见自聊天行为 - OpenClaw 永远不会自动配对外发的
fromMe私信(你从已绑定设备自行发送的消息)
组策略和许可名单
群组访问有两层:
- 群组成员 allowlist(
channels.whatsapp.groups):如果省略groups,则所有群组都符合条件;如果存在,则它充当群组 allowlist("*"允许全部)。 - 群组发送者策略(
channels.whatsapp.groupPolicy+groupAllowFrom):open会绕过发送者 allowlist,allowlist需要匹配groupAllowFrom(或*),disabled会阻止所有群组入站。
如果 groupAllowFrom 未设置,则发送方检查在有条目时回退到 allowFrom。在 mention/reply 激活之前评估发件人白名单。
如果完全不存在 channels.whatsapp 块,运行时会回退到 groupPolicy: "allowlist"(并记录警告日志),即使 channels.defaults.groupPolicy 设置了其他值也是如此。
提及和/激活
群组回复默认需要提及。提及检测包括:
- 对机器人身份的显式 WhatsApp 提及
- 提及正则表达式模式(
agents.entries.*.groupChat.mentionPatterns,后备messages.groupChat.mentionPatterns);如果两者均未设置,则模式源自路由代理的identity.name和identity.emoji - 已授权群组消息的入站语音便笺转写
- 隐式的回复机器人检测(回复发送者与机器人身份匹配)
所选代理或全局级别的显式 mentionPatterns: [] 会抑制源自身份的文本模式。本机提及和回复机器人检测仍然是分开的。
要处理组中所有允许的消息,请在已提供帐户组策略的映射中设置 groups["<group-id>"].requireMention: false:channels.whatsapp.groups 或有效的 channels.whatsapp.accounts.<id>.groups 映射,包括继承的 accounts.default.groups。保留每个现有的通配符和每组设置。如果您有意创建特定于帐户的映射而不是编辑继承的映射,请先复制完整的继承映射,然后仅更改目标组的 requireMention。如果之前没有应用地图,请包含 "*": {} 以允许其他聊天;否则保留现有限制。已保存的会话激活模式优先于此配置默认值;该会话使用 /activation always。
安全:quote/reply只满足提及门控——确实如此不是授予发件人授权。和groupPolicy: "allowlist",即使回复列入白名单的用户的邮件,非白名单发件人仍会被阻止。
会话级激活命令:/activation mention 或 /activation always。这会更新会话状态(不是全局配置),并且受所有者保护。
指定帐户仅使用其自己的帐户范围内的激活。他们不再继承较旧的无范围群体的偏好。如果这是您唯一保存的首选项,则配置的提及策略将一直适用,直到您在目标帐户组中再次运行 /activation 为止。现有的作用域和默认帐户首选项、会话历史记录和存储的行保持不变;没有自动迁移会复制旧的设置。
配置的 ACP 绑定
WhatsApp 通过顶层的 bindings[] 支持持久化 ACP 绑定:
直接聊天匹配E.164号码;组与 WhatsApp 组 JID 匹配。如果需要,在 OpenClaw 创建绑定的 ACP 会话之前运行组白名单、发件人策略和 mention/activation 门控。匹配的绑定拥有该路由 — 广播组不会将结果转为普通 WhatsApp 会话。
个人号码及自聊天行为
channels.whatsapp.selfChatMode 控制相同号码 DM 准入和自助聊天安全措施。将其设置在通道级别或使用 channels.whatsapp.accounts.<id>.selfChatMode 按帐户覆盖它。
true或 unset: 来自链接号码的 DM 被允许作为座席输入,即使allowFrom中不存在该号码。dmPolicy: "disabled"仍然阻止所有 DM。false: 自发的 DM 会被忽略,即使您的号码位于allowFrom中。其他入站 DM 和群组消息仍遵循其访问策略;此设置不会使帐户仅限出站。
隐式自我编号限额仅适用于 DM,不适用于群组白名单。
自助聊天保护措施由 true 启用,由 false 禁用。取消设置时,如果链接的自身编号出现在配置的 allowFrom 中,则 OpenClaw 启用它们。这些保护措施会跳过已读回执,抑制本机自提及触发器,并在未配置响应前缀时提供身份回复前缀。
因此,发送到您自己的号码的活动检查可以成为未设置 selfChatMode 或 true 的代理输入。如果要排除那些自发的 DM,请设置 selfChatMode: false。
消息传递和传递
消息规范化和上下文
入站信封和回复上下文
传入消息会被包装在共享的传入封套中。引用回复会按以下形式附加上下文:
回复元数据(ReplyToId、ReplyToBody、ReplyToSender、sender JID/E.164)会在可用时被填充。如果被引用的目标是可下载媒体,OpenClaw 会通过常规传入媒体存储保存它,并暴露 MediaPath/MediaType,以便代理可以直接检查它,而不是只看到 <media:image>。
媒体占位符和 location/contact 提取
仅媒体消息会规范化为占位符:<media:image>、<media:video>、<media:audio>、<media:document>、<media:sticker>。
仅当正文只有 <media:audio> 时,授权群组语音会在提及门控之前先转写,因此在语音中说出机器人提及可以触发回复。如果转写内容仍未提及机器人,它会保留在待处理群历史中,而不是原始占位符。
位置主体呈现为简洁的坐标文本。位置 labels/comments 和 contact/vCard 详细信息呈现为受保护的不受信任元数据,而不是内联提示文本。
待定组历史注射
未处理的群消息会缓冲,并在机器人最终被触发时作为上下文注入。
- 默认限制:
50 - 配置:
channels.whatsapp.historyLimit,回退到messages.groupChat.historyLimit 0禁用
注入标记:[Chat messages since your last reply - for context] 和 [Current message - respond to this]。
阅读收据
对已接受的传入消息默认启用。全局禁用:
每个帐户覆盖:channels.whatsapp.accounts.<id>.sendReadReceipts。即使全局启用,自助聊天保护措施也会跳过已读回执(请参阅 自助聊天行为)。
传送、分块和媒体
文本分块
- 默认分块限制:
channels.whatsapp.textChunkLimit = 4000 - Markdown 在发送块之前进行转换,跨消息边界保留样式并将 WhatsApp 格式化标记计入限制
channels.whatsapp.streaming.chunkMode = "length" | "newline";newline优先按段落边界(空行)分割,然后回退到按长度安全分块
出站媒体行为
- 支持图像、视频、音频(PTT 语音消息)和文档负载
- 音频会作为 Baileys 的
audio负载发送,并设置ptt: true,从而呈现为按住说话语音消息;audioAsVoice会保留在回复负载中,因此无论提供方的源格式如何,TTS 语音消息输出都会保持走这一路径 - native Ogg/Opus 音频发送为
audio/ogg; codecs=opus;其他任何内容(包括 Microsoft Edge TTS MP3/WebM 输出)在 PTT 交付之前均使用ffmpeg转码为 48 kHz 单声道 Ogg/Opus /tts latest会将最新的助手回复作为一条语音消息发送,并抑制对同一回复的重复发送;/tts chat on|off|default控制当前聊天的自动 TTS- 发送视频时设置
gifPlayback: true会启用动画 GIF 播放 forceDocument/asDocument通过 Baileys 文档负载路由出站图像、GIF 和视频,以避免 WhatsApp 的媒体压缩,保留解析的文件名和 MIME 类型- 标题会应用到多媒体回复中的第一项媒体,但 PTT 语音消息除外:音频先发送且不带标题,然后标题作为单独的文本消息发送(WhatsApp 客户端对语音消息标题的渲染并不一致)
- 当稍后带标题的回复重复待处理附件时,只有 WhatsApp 接受的附件会替换其待处理副本;不匹配的附件仍在排队等待传送
- 媒体源可以是 HTTP(S)、
file://或本地路径
媒体大小限制和后备行为
- 传入保存上限和出站发送上限:
channels.whatsapp.mediaMaxMb(默认50) - 按账户覆盖:
channels.whatsapp.accounts.<id>.mediaMaxMb - 图像自动优化(resize/quality 扫描)以适应限制,除非
forceDocument/asDocument请求文档传送 - 媒体发送失败时,第一项的回退会发送文本警告,而不是静默丢弃回复
回复引用
channels.whatsapp.replyToMode 控制原生回复引用(出站回复会明显引用传入消息):
| 值 | 行为 |
|---|---|
"off"(默认) |
从不引用;以普通消息发送 |
"first" |
仅引用第一个出站回复分块 |
"all" |
引用每个出站回复分块 |
"batched" |
引用排队的批量回复;即时回复不引用 |
如果不再缓存原始消息文本和媒体详细信息,OpenClaw 将回复作为纯消息发送。回复正文被保留,但其与原始消息的视觉链接丢失。
按账户覆盖:channels.whatsapp.accounts.<id>.replyToMode。
反应和打字
反应水平
channels.whatsapp.reactionLevel 控制代理使用表情回应的广泛程度:
| 等级 | 确认回应 | 代理发起的回应 |
|---|---|---|
"off" |
No | No |
"ack" |
是 | No |
"minimal" (默认) |
是 | 是,保守引导 |
"extensive" |
是 | 是,鼓励性引导 |
按账户覆盖:channels.whatsapp.accounts.<id>.reactionLevel。
致谢反应
messages.ackReaction 会在收到入站消息后立即发送反应,其受活跃 WhatsApp 账户的 reactionLevel 控制(当设置为 "off" 时会被抑制)。messages.ackReactionScope 用于选择私信、群组或两者:
注:接受入站后立即发送反应(预回复);省略 messages.ackReaction 或将其设置为 "" 则不进行确认。失败会被记录,但不会阻止回复传递。默认范围为"group-mentions";使用 "all" 进行直接消息和所有符合条件的群组。在激活为 always 的组中,"group-mentions" 确认每条消息,而不仅仅是提及触发的回合,因为激活代表提及检查。
生命周期状态反应
设置 messages.statusReactions.enabled: true,让 WhatsApp 在一次轮次中用状态反应替换 ack 反应,而不是保留静态的回执表情,状态会在 queued、thinking、tool activity、compaction、done 和 error 之间切换:
注意:messages.ackReactionScope 仍控制私聊和群组的适用性;queued 状态使用与普通确认反应相同的有效表情。WhatsApp 每条消息只有一个机器人反应槽,因此生命周期更新会原地替换当前反应,并在最终的 done/error 状态后恢复确认反应。
在活动运行后面排队的消息会保留其确认,直到其后续运行提供可见的回复。仅仅成功的执行并不会产生成功的反应。如果运输保留未确认的交付,则反应被清除,而不声明成功或失败;稍后的持久重试不会更新已清除的反应。没有可见回复的固定转弯(包括无声转弯或 NO_REPLY 转弯)会像直接调度一样显示错误反应。执行失败、终端准入跳过、停止取消以及队列上限策略拒绝或删除的消息会立即显示错误反应。收集和总结的后续活动保留了每条消息的传递相关性。
主动轮打字
对于允许输入状态的已接纳自动回合,代理执行开始时,WhatsApp 会发送一条 composing 状态更新,并在回合保持活跃期间刷新该状态。运行完成时(包括终止失败或取消),刷新会停止。当回复分发器报告空闲时,控制器会封存并清理;如果未收到该信号,则会在一段较短的安全超时后执行。现有输入状态和抑制策略禁用输入状态的回合不会启动此活动。
输入状态是短暂的、尽力而为的活动反馈。它不是持久化消息、送达回执,也不保证每个 WhatsApp 客户端都会显示持续的活动状态;重新连接和客户端行为可能会使该指示器消失。生命周期状态反应仍然是上文所述的、具有持久外观的自愿选择状态界面。
多账户和凭据
帐户选择和默认值
帐户 ID 来自 channels.whatsapp.accounts。默认帐户选择为 default(如果存在),否则为第一个配置的帐户 ID(按字母顺序排序)。帐户 ID 在内部进行标准化以供查找。
命名帐户按以下顺序解析共享设置:帐户、accounts.default,然后是通道根。这包括 dmPolicy 和 groupPolicy:省略继承,而显式值获胜。在未配置策略的情况下,DM 使用 pairing,组使用 allowlist。默认账户的 authDir、enabled、name 和 selfChatMode 不与指定账户共享。
凭证路径和旧版兼容性
- 当前认证路径:
~/.openclaw/credentials/whatsapp/<accountId>/creds.json(备份:creds.json.bak) - 在保留精确的私有
.migrated备份后,Doctor 将隐式旧版默认身份验证从~/.openclaw/credentials/移动到帐户目录中。运行时帐户选择使用帐户目录;直接替换旧安装后运行openclaw doctor --fix。 - 显式
authDir设置保持权威,包括故意使用共享凭据根的帐户。医生将这些目录保留在原处。不同的当前和旧凭证保持不变,并提供可操作的冲突警告; Doctor 绝不会混合两个凭证集。 - Doctor 在写入帐户目录之前记录凭证迁移收据。如果中断导入的完整目标后来丢失或更改,Doctor 会保留剩余的源和备份并要求显式恢复。它不会重新创建注销的帐户。
- 帐户目录凭据在 OpenClaw 上仍然有效 2026.9.7. 共享根修复需要具有脱机 Doctor 迁移权限和源备份的主机。如果Doctor要求您升级主机,请先更新OpenClaw核心再重试;该插件保持原始凭证不变。
注销行为
openclaw channels logout --channel whatsapp [--account <id>] 会清除该账户的 WhatsApp 认证状态。当网关可达时,注销会先停止该账户的实时监听,因此在下次重启前,已绑定的会话将不再接收消息。openclaw channels remove --channel whatsapp 也会在禁用或删除账户配置之前停止实时监听。
注销会将显式配置的凭据目录保留在托管帐户树之外。它永远不会从共享根中删除不相关的 OAuth 凭据。
工具、动作与配置写入
- Agent 工具支持包括 WhatsApp 反应动作(
react)。 - 动作开关:
channels.whatsapp.actions.reactions、channels.whatsapp.actions.polls(现有动作默认值为true)、channels.whatsapp.actions.calls(默认false,见上面的 MeowCaller)。 - 频道发起的配置写入默认启用;可通过
channels.whatsapp.configWrites: false禁用。
故障排查
未链接(需要 QR)
症状:通道状态报告未绑定。
已链接但已断开/重新连接循环
症状:已绑定账号反复断开或尝试重连。
静默账号可以在正常消息超时之后继续保持连接;看门狗仅在 WhatsApp Web 传输活动停止、socket 关闭,或应用层活动在更长的安全窗口内持续无响应时才会重启(参见上面的运行时模型)。
使固定:
如果在主机连接性和时序都修复后循环仍然存在,请备份账号认证目录并重新关联:
如果 ~/.openclaw/logs/whatsapp-health.log 显示 Gateway inactive,但 openclaw gateway status 和 openclaw channels status --probe 都显示正常,请运行 openclaw doctor。在 Linux 上,doctor 会警告那些调用已弃用的 ~/.openclaw/bin/ensure-whatsapp.sh 脚本的旧 crontab 条目;请使用 crontab -e 删除这些条目——cron 可能缺少 systemd 用户总线环境,从而让旧脚本误报网关健康状态。
QR 在代理后面登录超时
症状:openclaw channels login --channel whatsapp 在显示可用 QR 之前就失败,报 status=408 Request Time-out 或 TLS socket 断开。
WhatsApp Web 登录使用网关主机的标准代理环境变量(HTTPS_PROXY、HTTP_PROXY、小写变体、NO_PROXY)。请确认网关进程继承了代理环境变量,并且 NO_PROXY 不会匹配 mmg.whatsapp.net。
发送时没有活动侦听器
当目标账号不存在活动的网关监听器时,出站发送会快速失败。确认网关正在运行且该账号已关联。
群组消息意外被忽略
请按以下顺序检查:groupPolicy、groupAllowFrom/allowFrom、groups 白名单条目、提及门控(requireMention + 提及模式),以及 openclaw.json 中的重复键(JSON5 中后面的条目会覆盖前面的条目——每个作用域只保留一个 groupPolicy)。
如果 channels.whatsapp.groups 存在,WhatsApp 仍然可以观察来自其他组的消息,但 OpenClaw 在会话路由之前丢弃它们。将组 JID 添加到 channels.whatsapp.groups,或添加 groups["*"] 以接纳所有组,同时将发件人授权保留在 groupPolicy/groupAllowFrom. 下
Bun 运行时警告
Node 仍然是主要且推荐的网关运行时。支持使用 WAL- 重置安全 node:sqlite 的 Bun 1.4.3+ 构建作为显式选择加入; doctor 仅将不支持的 Bun 服务迁移到 Node。
系统提示词
WhatsApp 支持 Telegram- 风格的系统提示,可通过 groups 和 direct 地图进行群组和直接聊天。
群组消息的解析方式:先确定最终有效的 groups 映射——如果某个账号定义了自己的 groups 键,那么它会完全替换根级 groups 映射(不会进行深度合并)。随后提示词查找只在这个单一结果映射上进行:
- 组特定提示(
groups["<groupId>"].systemPrompt):当组条目存在和时使用,其systemPrompt键被定义。空字符串 ("") 会抑制通配符并且不应用提示。 - 群组通配符提示词(
groups["*"].systemPrompt):当特定群组条目不存在,或者存在但未定义systemPrompt键时使用。
私聊消息的解析遵循同样的模式,作用于 direct 映射和 direct["*"]。
与 Telegram 的区别: Telegram 在多账户配置中对 groups 使用相同的全地图账户覆盖,但单个账户的空 groups: {} 会回退到根组作为迁移安全网。 Telegram 的 direct 映射也具有单独的 DM- 主题语义。在 WhatsApp 中(或对于多个 Telegram 帐户中的一个帐户),当该帐户不应继承根组默认值时,请使用显式空 groups: {}。
重要行为:
channels.whatsapp.groups既是每个群组的配置映射,也是聊天级别的群组白名单。在根级或账号级,groups["*"]都表示“该作用域接纳所有群组”。- 仅当您已经希望该范围允许所有组时才添加通配符
systemPrompt。要仅保留一组固定的组 ID 符合条件,请对每个明确列入许可名单的条目重复提示,而不是使用groups["*"]。 - 组准入和发件人授权是单独检查的。
groups["*"]拓宽了哪些组达到组处理;它不会授权这些组中的每个发件人 - 仍由groupPolicy/groupAllowFrom. 控制 channels.whatsapp.direct对 DM 没有同等副作用:direct["*"]仅在 DM 已被dmPolicy加上allowFrom或配对存储规则接纳后提供默认配置。
示例:
配置参考指针
主要参考: 配置参考 - WhatsApp
| 区域 | 字段 |
|---|---|
| 使用权 | dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups |
| 送货 | textChunkLimit, streaming.chunkMode, mediaMaxMb, sendReadReceipts, reactionLevel |
| 多账户 | accounts.<id>.enabled, accounts.<id>.authDir,以及其他按账户配置的覆盖项 |
| 操作 | configWrites, enabled |
| 入站批处理 | messages.inbound.debounceMs, messages.inbound.byChannel.whatsapp |
| 确认 | messages.ackReaction, messages.ackReactionScope |
| 会话行为 | session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit |
| 提示词 | groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt |