--- read_when: - 处理 WhatsApp/Web 渠道行为或收件箱路由 summary: WhatsApp 渠道支持、访问控制、消息投递行为和运维 title: WhatsApp x-i18n: generated_at: "2026-07-14T13:28:42Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 25 provider: openai source_hash: d9d6af1b32a428e0a35794fa4b5a8a861cb404a5b6848a265bf5d43f4cdad168 source_path: channels/whatsapp.md workflow: 16 --- 状态：已通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关拥有已关联的会话；不存在单独的 Twilio WhatsApp 渠道。 ## 安装 `openclaw onboard` 和 `openclaw channels add --channel whatsapp` 会在你首次选择插件时提示安装；如果插件缺失，`openclaw channels login --channel whatsapp` 会提供相同的安装流程。开发检出使用本地插件路径；稳定版/测试版安装会先从 ClawHub 安装 `@openclaw/whatsapp`，失败时回退到 npm。WhatsApp 运行时在 OpenClaw 核心 npm 软件包之外发布，因此其运行时依赖项保留在外部插件中。手动安装： ```bash openclaw plugins install clawhub:@openclaw/whatsapp ``` 仅将裸 npm 软件包（`@openclaw/whatsapp`）用于注册表回退；只有需要可复现安装时才固定精确版本。 对未知发送者，默认私信策略为配对。 跨渠道诊断和修复操作手册。 完整的渠道配置模式和示例。 ## 快速设置 ```json5 { channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["+15551234567"], groupPolicy: "allowlist", groupAllowFrom: ["+15551234567"], }, }, } ``` ```bash openclaw channels login --channel whatsapp ``` 登录仅支持二维码。在远程或无头主机上，开始登录前请确保有可靠途径将实时二维码传送到手机；终端渲染的二维码、屏幕截图或聊天附件可能会在传送途中失效。 对于特定账户： ```bash openclaw channels login --channel whatsapp --account work ``` 要在登录前附加现有/自定义身份验证目录： ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth openclaw channels login --channel whatsapp --account work ``` ```bash openclaw gateway ``` ```bash openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` 配对请求会在 1 小时后过期；每个账户最多可有 3 个待处理请求。 建议使用单独的 WhatsApp 号码（设置和元数据已针对此方式进行优化），但也完全支持个人号码/自聊设置。 ## 部署模式 - 为 OpenClaw 使用独立的 WhatsApp 身份 - 更清晰的私信允许列表和路由边界 - 降低自聊混淆的可能性 ```json5 { channels: { whatsapp: { dmPolicy: "allowlist", allowFrom: ["+15551234567"], }, }, } ``` 新手引导支持个人号码模式，并写入适合自聊的基线配置：`dmPolicy: "allowlist"`、包含你自己号码的 `allowFrom`、`selfChatMode: true`。运行时自聊保护以已关联的自身号码和 `allowFrom` 为依据。 ## 运行时模型 - Gateway 网关拥有 WhatsApp 套接字和重连循环。 - 看门狗独立跟踪两个信号：原始 WhatsApp Web 传输活动和应用消息活动。会话保持安静但仍处于连接状态时，不会仅因最近没有消息到达而重启；只有传输帧在固定的内部时间窗口内停止到达（用户不可配置），或应用消息静默时间超过正常消息超时的 4 倍时，才会强制重连。对于最近处于活动状态的会话，在刚完成重连后，第一个时间窗口使用较短的正常消息超时，而不是 4 倍时间窗口。Baileys 在该重连期间提前传送的离线消息可以由 OpenClaw 自动回复，范围受入站消息 ID 去重生存期限制；初始启动仍保留较短的陈旧历史记录保护。 - Baileys 套接字计时在 `web.whatsapp.*` 下明确定义：`keepAliveIntervalMs`（应用 ping 间隔）、`connectTimeoutMs`（打开握手超时）、`defaultQueryTimeoutMs`（Baileys 查询等待时间，以及 OpenClaw 的出站发送/在线状态和入站已读回执超时）。 - 出站发送要求目标账户具有活动的 WhatsApp 侦听器；否则发送会立即失败。 - 群组发送会为 `@+` 和 `@` 标记（位于文本和媒体说明中）附加原生提及元数据，前提是该标记与当前参与者元数据匹配；这也包括由 LID 支持的群组。 - 状态和广播聊天（`@status`、`@broadcast`）会被忽略。 - 直接聊天使用私信会话规则（`session.dmScope`；默认的 `main` 会将私信合并到智能体主会话中）。群组会话按 JID 隔离（`agent::whatsapp:group:`）。 - WhatsApp Channels/Newsletters 可以通过其原生 `@newsletter` JID 作为明确的出站目标，使用渠道会话元数据（`agent::whatsapp:channel:`），而不是私信语义。 - WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。相较于每渠道设置，优先使用主机级代理配置。 - 启用 `messages.removeAckAfterReply` 后，OpenClaw 会在可见回复送达后清除确认表情回应。 ## 使用 MeowCaller 呼叫当前请求者（实验性） 该插件可以在源自 WhatsApp 的智能体轮次中公开 `whatsapp_call`。它使用 [MeowCaller](https://github.com/purpshell/meowcaller) 向当前已获授权的请求者发起 WhatsApp 语音通话，并在对方接听后播放 OpenClaw TTS 消息。该工具没有目标号码参数，因此提示词无法将通话重定向到其他号码。默认禁用。 MeowCaller 处于实验阶段，没有带标签的版本，并使用单独配对的 whatsmeow 关联设备会话——它无法复用插件的 Baileys 凭据。配对会向同一 WhatsApp 账户添加另一个关联设备；请使用 OpenClaw 所使用的身份进行扫描。个人号码/自聊模式无法呼叫自身；请使用专用 OpenClaw 号码呼叫你的个人号码。 将 `actions.calls: true` 添加到 WhatsApp 渠道配置，然后重启 Gateway 网关： ```json { "channels": { "whatsapp": { "actions": { "calls": true } } } } ``` 当该项缺失或为 `false` 时，OpenClaw 不会公开 `whatsapp_call` 工具。 适配器要求 Gateway 网关主机的 `PATH` 中存在一个 `meowcaller` 可执行文件。在 [MeowCaller PR #7](https://github.com/purpshell/meowcaller/pull/7) 合并之前，请构建已审核的分支： ```bash git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git cd meowcaller git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f mkdir -p "$HOME/.local/bin" go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller ``` 确保 `$HOME/.local/bin` 位于 Gateway 网关服务的 `PATH` 中。此修订版具有明确的 `pair` 和仅发送的 `notify` 命令；`notify` 不会打开麦克风、扬声器、视频设备或诊断捕获。请勿替换为上游示例 CLI 的 `play` 命令。 要求 WhatsApp 智能体检查通话设置（`whatsapp_call` 状态操作会报告账户特定的状态目录和配对命令）。对于默认账户： ```bash state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default" mkdir -p "$state_dir" chmod 700 "$state_dir" meowcaller pair --store "$state_dir/wa-voip.db" ``` 以交互方式运行此命令，从 **WhatsApp > Linked devices** 扫描二维码，然后等待 `MeowCaller linked device ready`。请将 `wa-voip.db` 保密——它是 MeowCaller 会话。非默认账户会从状态操作获得各自的存储路径；在 Windows 上，请运行其 PowerShell 命令。 配置支持电话功能的 [TTS 提供商](/zh-CN/tools/tts)，重启 Gateway 网关，然后发送类似 `Call me and say the build finished.` 的请求。该工具从可信的入站上下文中解析发送者，合成临时私有 WAV 文件，在有界的通话时间窗口内运行 MeowCaller，并在之后删除音频文件。OpenClaw 会明确传递账户的存储，在接听/播放/挂断后等待零退出状态，并将超时或非零退出视为工具调用失败。 限制：仅支持一对一出站音频通话，不支持任意目标号码，不与聊天连接共享身份验证，个人号码/自聊模式不能呼叫自身，合成音频最长为 60 秒，除 MeowCaller 的接听/播放/挂断完成状态外不提供手机端可听性回执，并且 OpenClaw 会在有界的 115-175 秒时间窗口后停止伴随进程（涵盖 MeowCaller 的连接、接听、播放和关闭阶段）。 ## 审批提示 WhatsApp 可以将 Exec 和插件审批提示呈现为 `👍`/`👎` 表情回应，由顶层审批转发配置控制： ```json5 { approvals: { exec: { enabled: true, mode: "session", }, plugin: { enabled: true, mode: "targets", targets: [{ channel: "whatsapp", to: "+15551234567" }], }, }, } ``` `approvals.exec` 和 `approvals.plugin` 相互独立；启用 WhatsApp 渠道只会关联传输，不会发送任何内容，除非匹配的审批类别已启用并路由至此。会话模式仅针对源自 WhatsApp 的审批传送原生表情符号审批。目标模式对明确目标使用共享转发管道，不会创建单独的审批者私信扇出。 WhatsApp 审批表情回应要求在 `allowFrom`（或 `"*"`）中明确指定审批者。`defaultTo` 设置的是普通默认消息目标，而不是审批者列表。手动 `/approve` 命令在解析审批之前仍会经过常规 WhatsApp 发送者授权路径。 ## 插件钩子和隐私 入站 WhatsApp 消息可能包含个人内容、电话号码、群组标识符、发送者姓名和会话关联字段。除非你选择启用，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子负载： ```json5 { channels: { whatsapp: { pluginHooks: { messageReceived: true, }, }, }, } ``` 请在 `channels.whatsapp.accounts..pluginHooks.messageReceived` 下将此选择性启用限制为一个账户。仅对你信任其处理入站 WhatsApp 内容和标识符的插件启用此功能。 ## 访问控制和激活 `channels.whatsapp.dmPolicy`： | 值 | 行为 | | --- | --- | | `pairing`（默认） | 未知发送者请求配对；所有者批准 | | `allowlist` | 仅允许 `allowFrom` 中的发送者 | | `open` | 要求 `allowFrom` 包含 `"*"` | | `disabled` | 阻止所有私信 | `allowFrom` 接受 E.164 格式的号码（内部会进行规范化）。它仅是私信发送者访问控制列表——不会限制明确发送到群组 JID 或 `@newsletter` 渠道 JID 的出站消息。 多账户覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `.allowFrom`）优先于该账户的渠道级默认值。 运行时说明： - 配对信息会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并 - 定时自动化和 Heartbeat 接收方回退使用明确的投递目标或已配置的 `allowFrom`；私信配对审批不会隐式成为 cron/Heartbeat 接收方 - 如果未配置允许列表，默认允许已关联的本机号码 - OpenClaw 绝不会自动配对出站 `fromMe` 私信（即你从已关联设备发送给自己的消息） 群组访问分为两层： 1. **群组成员资格允许列表**（`channels.whatsapp.groups`）：如果省略 `groups`，则所有群组均符合条件；如果存在，则作为群组允许列表（`"*"` 允许所有群组）。 2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）：`open` 绕过发送者允许列表，`allowlist` 要求匹配 `groupAllowFrom`（或 `*`），`disabled` 阻止所有群组入站消息。 如果未设置 `groupAllowFrom`，当 `allowFrom` 中有条目时，发送者检查会回退到该配置。发送者允许列表的判定先于提及/回复激活。 如果根本不存在 `channels.whatsapp` 块，运行时会回退到 `groupPolicy: "allowlist"`（并记录警告日志），即使 `channels.defaults.groupPolicy` 被设置为其他值也是如此。 群组成员资格解析有一项单账号安全保障：如果仅配置了一个 WhatsApp 账号，且其 `accounts..groups` 是显式空对象（`{}`），则会将其视为“未设置”，并回退到根级 `channels.whatsapp.groups` 映射，而不是静默阻止所有群组。配置 2 个或更多账号时，显式空账号映射将保持为空且不会回退——这允许某个账号有意禁用所有群组，而不影响其他账号。 默认情况下，群组回复需要提及。提及检测包括： - 在 WhatsApp 中明确提及 Bot 身份 - 已配置的提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - 已获授权的群组消息中的入站语音留言转录文本 - 隐式回复 Bot 检测（回复发送者与 Bot 身份匹配） 安全性：引用/回复仅满足提及门控——它**不会**授予发送者授权。使用 `groupPolicy: "allowlist"` 时，不在允许列表中的发送者仍会被阻止，即使其回复的是允许列表中用户的消息。 会话级激活命令：`/activation mention` 或 `/activation always`。这会更新会话状态（而非全局配置），并且仅限所有者操作。 ## 已配置的 ACP 绑定 WhatsApp 通过顶级 `bindings[]` 支持持久化 ACP 绑定： ```json5 { bindings: [ { type: "acp", agentId: "codex", match: { channel: "whatsapp", accountId: "work", peer: { kind: "direct", id: "+15555550123" }, }, }, { type: "acp", agentId: "codex", match: { channel: "whatsapp", accountId: "work", peer: { kind: "group", id: "120363424282127706@g.us" }, }, }, ], } ``` 直接聊天匹配 E.164 号码；群组匹配 WhatsApp 群组 JID。在 OpenClaw 确保绑定的 ACP 会话存在之前，会先执行群组允许列表、发送者策略和提及/激活门控。匹配的绑定拥有该路由——广播群组不会将该轮次分发到普通 WhatsApp 会话。 ## 个人号码和自聊行为 当已关联的本机号码也存在于 `allowFrom` 中时，自聊安全保障会激活：跳过自聊轮次的已读回执，忽略可能会提醒你自己的提及 JID 自动触发行为，并在未设置 `messages.responsePrefix` 时，默认回复至 `[{identity.name}]`（或 `[openclaw]`）。 ## 消息规范化和上下文 入站消息会封装在共享入站信封中。引用回复会以如下形式追加上下文： ```text [Replying to id:] [/Replying] ``` 回复元数据（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）会在可用时填充。如果引用目标是可下载媒体，OpenClaw 会通过常规入站媒体存储保存该媒体，并公开 `MediaPath`/`MediaType`，以便智能体直接检查，而不是只能看到 ``。 仅含媒体的消息会规范化为占位符：``、``、``、``、``。 当正文仅为 `` 时，已获授权的群组语音留言会在提及门控前进行转录，因此在语音留言中说出 Bot 提及内容即可触发回复。如果转录文本仍未提及 Bot，它会保留在待处理群组历史记录中，而不是保留原始占位符。 位置消息正文会呈现为简洁的坐标文本。位置标签/评论以及联系人/vCard 详细信息会呈现为围栏式不可信元数据，而非内联提示词文本。 未处理的群组消息会先缓冲，并在 Bot 最终被触发时作为上下文注入。 - 默认限制：`50` - 配置：`channels.whatsapp.historyLimit`，回退为 `messages.groupChat.historyLimit` - `0` 会禁用此功能 注入标记：`[Chat messages since your last reply - for context]` 和 `[Current message - respond to this]`。 对已接受的入站消息默认启用。全局禁用： ```json5 { channels: { whatsapp: { sendReadReceipts: false } } } ``` 每账户覆盖：`channels.whatsapp.accounts..sendReadReceipts`。即使已全局启用，自聊轮次也会跳过已读回执。 ## 发送、分块和媒体 - 默认分块限制：`channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.streaming.chunkMode = "length" | "newline"`；`newline` 优先按段落边界（空行）分块，然后回退到长度安全的分块方式 - 支持图像、视频、音频（PTT 语音消息）和文档载荷 - 音频作为带有 `ptt: true` 的 Baileys `audio` 载荷发送，并呈现为按住说话语音消息；回复载荷中会保留 `audioAsVoice`，因此无论提供商的源格式如何，TTS 语音消息输出都会继续使用此路径 - 原生 Ogg/Opus 音频作为 `audio/ogg; codecs=opus` 发送；其他任何格式（包括 Microsoft Edge TTS 的 MP3/WebM 输出）都会先通过 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus，再以 PTT 方式发送 - `/tts latest` 将最新的智能体回复作为一条语音消息发送，并抑制对同一回复的重复发送；`/tts chat on|off|default` 控制当前聊天的自动 TTS - 在视频发送中启用 `gifPlayback: true` 可实现 GIF 动画播放 - `forceDocument`/`asDocument` 通过 Baileys 文档载荷路由出站图像、GIF 和视频，以避免 WhatsApp 的媒体压缩，同时保留解析后的文件名和 MIME 类型 - 在包含多个媒体项的回复中，说明文字应用于第一个媒体项，但 PTT 语音消息除外：音频先发送且不附带说明文字，随后说明文字作为单独的文本消息发送（WhatsApp 客户端无法一致地呈现语音消息说明文字） - 媒体来源可以是 HTTP(S)、`file://` 或本地路径 - 入站保存上限和出站发送上限：`channels.whatsapp.mediaMaxMb`（默认值为 `50`） - 每账户覆盖：`channels.whatsapp.accounts..mediaMaxMb` - 图像会自动优化（调整尺寸并逐级尝试质量）以符合限制，除非 `forceDocument`/`asDocument` 请求以文档方式发送 - 媒体发送失败时，第一个媒体项的回退机制会发送文本警告，而不是静默丢弃响应 ## 回复引用 `channels.whatsapp.replyToMode` 控制原生回复引用（出站回复会直观地引用入站消息）： | 值 | 行为 | | ----------------- | -------------------------------------------------------------- | | `"off"`（默认） | 从不引用；作为普通消息发送 | | `"first"` | 仅引用第一个出站回复分块 | | `"all"` | 引用每个出站回复分块 | | `"batched"` | 引用排队的批量回复；即时回复不引用 | 每账户覆盖：`channels.whatsapp.accounts..replyToMode`。 ```json5 { channels: { whatsapp: { replyToMode: "first" } } } ``` ## 表情回应级别 `channels.whatsapp.reactionLevel` 控制智能体使用表情回应的范围： | 级别 | 确认表情回应 | 智能体主动发起的表情回应 | | --------------------- | ------------- | -------------------------- | | `"off"` | 否 | 否 | | `"ack"` | 是 | 否 | | `"minimal"`（默认） | 是 | 是，采用保守指引 | | `"extensive"` | 是 | 是，采用鼓励性指引 | 每账户覆盖：`channels.whatsapp.accounts..reactionLevel`。 ```json5 { channels: { whatsapp: { reactionLevel: "ack" } } } ``` ## 确认表情回应 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送表情回应，该行为受 `reactionLevel` 限制（当 `"off"` 时抑制）： ```json5 { channels: { whatsapp: { ackReaction: { emoji: "👀", direct: true, group: "mentions", // always | mentions | never }, }, }, } ``` 注意：在入站消息被接受后立即发送（回复前）；如果存在 `ackReaction` 但不存在 `emoji`，WhatsApp 会使用路由到的智能体的身份表情符号，并回退到“👀”（省略 `ackReaction` 或设置 `emoji: ""` 可禁用确认表情回应）；失败会被记录到日志，但不会阻止回复发送；群组模式 `mentions` 仅在由提及触发的轮次中作出表情回应，而群组激活 `always` 会绕过此检查；WhatsApp 仅使用 `channels.whatsapp.ackReaction`（旧版 `messages.ackReaction` 在此不适用）。 ## 生命周期状态表情回应 设置 `messages.statusReactions.enabled: true`，让 WhatsApp 在轮次期间替换确认表情回应，而不是保留静态的回执表情符号，并在排队、思考、工具活动、压缩、完成和错误等状态之间切换： ```json5 { messages: { statusReactions: { enabled: true, emojis: { deploy: "🛫", build: "🏗️", concierge: "💁", }, }, }, } ``` 注意：`channels.whatsapp.ackReaction` 仍控制私信和群组的适用条件；排队状态使用与普通确认表情回应相同的有效表情符号；WhatsApp 对每条消息只有一个 Bot 表情回应槽位，因此生命周期更新会原位替换当前表情回应；`messages.removeAckAfterReply: true` 会在配置的完成/错误保留时间结束后清除最终状态表情回应；工具表情符号类别包括 `tool`、`coding`、`web`、`deploy`、`build` 和 `concierge`。 ## 多账户和凭据 账户 ID 来自 `channels.whatsapp.accounts`。如果存在 `default`，则选择它作为默认账户；否则选择按字母顺序排序后的第一个已配置账户 ID。账户 ID 会在内部进行规范化以供查找。 - 当前身份验证路径：`~/.openclaw/credentials/whatsapp//creds.json`（备份：`creds.json.bak`） - `~/.openclaw/credentials/` 中旧版默认身份验证仍会在默认账户流程中被识别并迁移 `openclaw channels logout --channel whatsapp [--account ]` 会清除该账户的 WhatsApp 身份验证状态。当 Gateway 网关可访问时，退出登录会先停止该账户的实时监听器，使已关联的会话在下次重启前就停止接收消息。`openclaw channels remove --channel whatsapp` 也会在禁用或删除账户配置之前停止实时监听器。 在旧版身份验证目录中，删除 Baileys 身份验证文件时会保留 `oauth.json`。 ## 工具、操作和配置写入 - 智能体工具支持包括 WhatsApp 表情回应操作（`react`）。 - 操作门控：`channels.whatsapp.actions.reactions`、`channels.whatsapp.actions.polls`（现有操作默认为 `true`）、`channels.whatsapp.actions.calls`（默认值为 `false`，请参阅上文的 MeowCaller）。 - 默认启用由渠道发起的配置写入；可通过 `channels.whatsapp.configWrites: false` 禁用。 ## 故障排查 症状：渠道状态报告未关联。 ```bash openclaw channels login --channel whatsapp openclaw channels status ``` 症状：已关联的账户反复断开连接或尝试重新连接。 不活跃的账户可在超过正常消息超时时间后仍保持连接；只有当 WhatsApp Web 传输活动停止、套接字关闭，或应用层活动的静默时间超过较长的安全窗口时，看门狗才会重启（请参阅上文的运行时模型）。 如果日志反复显示 `status=408 Request Time-out Connection was lost`，请在 `web.whatsapp` 下调整 Baileys 套接字时序。首先将 `keepAliveIntervalMs` 缩短到低于网络的空闲超时时间，并在速度较慢或丢包的链路上增大 `connectTimeoutMs`： ```json5 { web: { whatsapp: { keepAliveIntervalMs: 15000, connectTimeoutMs: 60000, defaultQueryTimeoutMs: 60000, }, }, } ``` 修复方法： ```bash openclaw channels status --probe openclaw doctor openclaw logs --follow openclaw gateway status ``` 如果修复主机连接和时序后循环仍然存在，请备份账户身份验证目录并重新关联： ```bash cp -a ~/.openclaw/credentials/whatsapp/ \ ~/.openclaw/credentials/whatsapp/.bak openclaw channels logout --channel whatsapp --account openclaw channels login --channel whatsapp --account ``` 如果 `~/.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 用户总线环境，导致该旧脚本错误报告 Gateway 健康状态。 症状：`openclaw channels login --channel whatsapp` 在显示可用二维码之前失败，并出现 `status=408 Request Time-out` 或 TLS 套接字断开连接。 WhatsApp Web 登录使用 Gateway 网关主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、对应的小写变体以及 `NO_PROXY`）。请确认 Gateway 网关进程继承了代理环境，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。 如果目标账户没有活动的 Gateway 网关监听器，出站发送会快速失败。请确认 Gateway 网关正在运行且账户已关联。 会话记录行保存智能体生成的内容；WhatsApp 投递会单独检查。只有当 Baileys 为至少一次用户可见的文本或媒体发送返回出站消息 ID 后，OpenClaw 才会将自动回复视为已发送。 确认表情回应是回复前独立发送的回执——表情回应成功并不能证明后续文本或媒体回复已被接受。请检查 Gateway 网关日志中是否存在 `auto-reply delivery failed` 或 `auto-reply was not accepted by WhatsApp provider`。 请按以下顺序检查：`groupPolicy`、`groupAllowFrom`/`allowFrom`、`groups` 允许列表条目、提及门控（`requireMention` + 提及模式），以及 `openclaw.json` 中的重复键（JSON5 中后面的条目会覆盖前面的条目——每个作用域只保留一个 `groupPolicy`）。 如果存在 `channels.whatsapp.groups`，WhatsApp 仍可观察到其他群组的消息，但 OpenClaw 会在会话路由前丢弃它们。请将群组 JID 添加到 `channels.whatsapp.groups`，或添加 `groups["*"]` 以允许所有群组，同时继续由 `groupPolicy`/`groupAllowFrom` 控制发送者授权。 OpenClaw Gateway 网关需要使用 Node。Bun 不提供规范状态存储所使用的 `node:sqlite` API，Doctor 会将旧版 Bun 服务迁移到 Node。 ## 系统提示词 WhatsApp 通过 `groups` 和 `direct` 映射，为群组和私聊支持 Telegram 风格的系统提示词。 群组消息的解析方式：首先确定有效的 `groups` 映射——只要账户定义了自己的 `groups` 键，它就会完全替换根级 `groups` 映射（不会进行深度合并）。随后仅在最终得到的这个映射中查找提示词： 1. **群组专属提示词**（`groups[""].systemPrompt`）：当群组条目存在，**并且**其 `systemPrompt` 键已定义时使用。空字符串（`""`）会抑制通配符且不应用任何提示词。 2. **群组通配符提示词**（`groups["*"].systemPrompt`）：当特定群组条目不存在，或条目存在但没有 `systemPrompt` 键时使用。 私信的解析方式完全相同，但针对 `direct` 映射和 `direct["*"]`。 `dms` 仍是轻量级的每私信历史记录覆盖存储区（`dms..historyLimit`）。提示词覆盖位于 `direct` 下。 用于提示词解析的这种“账户替换根级配置”行为是一种简单的浅层覆盖：任何账户级 `groups`/`direct` 键（包括显式空对象）都会替换根级映射。这与上文所述的群组成员资格允许列表检查不同；后者针对意外为空的 `groups: {}` 提供单账户安全保障。 **与 Telegram 的区别：**在多账户设置中，Telegram 会对每个账户抑制根级 `groups`（即使账户没有自己的 `groups`），以防止 Bot 接收其未加入的群组消息。WhatsApp 不应用此保护措施——无论账户数量多少，任何没有自身覆盖配置的账户都会继承根级 `groups`/`direct`。在多账户 WhatsApp 设置中，如果需要按账户设置提示词，请在每个账户下显式定义完整映射。 重要行为： - `channels.whatsapp.groups` 既是每群组配置映射，也是聊天级群组允许列表。在根级或账户级作用域中，`groups["*"]` 表示该作用域“允许所有群组”。 - 只有当你本来就希望该作用域允许所有群组时，才添加通配符 `systemPrompt`。如果只需允许一组固定的群组 ID，请在每个显式列入允许列表的条目上重复设置提示词，而不要使用 `groups["*"]`。 - 群组准入和发送者授权是两项独立检查。`groups["*"]` 会扩大可进入群组处理流程的群组范围；它不会授权这些群组中的所有发送者——发送者授权仍由 `groupPolicy`/`groupAllowFrom` 控制。 - `channels.whatsapp.direct` 对私信没有相同的附带影响：`direct["*"]` 仅在私信已通过 `dmPolicy` 加 `allowFrom` 或配对存储规则获得准入后，提供默认配置。 示例： ```json5 { channels: { whatsapp: { groups: { // 仅在根级作用域应允许所有群组时使用。 // 应用于所有未定义自身 groups 映射的账户。 "*": { systemPrompt: "所有群组的默认提示词。" }, }, direct: { // 应用于所有未定义自身 direct 映射的账户。 "*": { systemPrompt: "所有私聊的默认提示词。" }, }, accounts: { work: { groups: { // 此账户定义了自己的 groups，因此根级 groups 会被完全 // 替换。若要保留通配符，也需在此处显式定义 "*"。 "120363406415684625@g.us": { requireMention: false, systemPrompt: "专注于项目管理。", }, // 仅在此账户应允许所有群组时使用。 "*": { systemPrompt: "工作群组的默认提示词。" }, }, direct: { // 此账户定义了自己的 direct 映射，因此根级 direct 条目会被 // 完全替换。若要保留通配符，也需在此处显式定义 "*"。 "+15551234567": { systemPrompt: "特定工作私聊的提示词。" }, "*": { systemPrompt: "工作私聊的默认提示词。" }, }, }, }, }, }, } ``` ## 配置参考指引 主要参考：[Configuration reference - WhatsApp](/zh-CN/gateway/config-channels#whatsapp) | 范围 | 字段 | | ---------------- | -------------------------------------------------------------------------------------------------------------- | | 访问控制 | `dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` | | 投递 | `textChunkLimit`、`streaming.chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel` | | 多账户 | `accounts..enabled`、`accounts..authDir` 和其他每账户覆盖配置 | | 操作 | `configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`、`web.whatsapp.*` | | 会话行为 | `session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms..historyLimit` | | 提示词 | `groups..systemPrompt`、`groups["*"].systemPrompt`、`direct..systemPrompt`、`direct["*"].systemPrompt` | ## 相关内容 - [配对](/zh-CN/channels/pairing) - [群组](/zh-CN/channels/groups) - [安全性](/zh-CN/gateway/security) - [渠道路由](/zh-CN/channels/channel-routing) - [多智能体路由](/zh-CN/concepts/multi-agent) - [故障排查](/zh-CN/channels/troubleshooting)