diff --git a/docs/zh-CN/channels/whatsapp.md b/docs/zh-CN/channels/whatsapp.md index ef10f393d..473144e9d 100644 --- a/docs/zh-CN/channels/whatsapp.md +++ b/docs/zh-CN/channels/whatsapp.md @@ -1,26 +1,26 @@ --- read_when: - 处理 WhatsApp/网页渠道行为或收件箱路由 -summary: WhatsApp 渠道支持、访问控制、投递行为和运维 +summary: WhatsApp 渠道支持、访问控制、交付行为和运维 title: WhatsApp x-i18n: - generated_at: "2026-04-29T10:59:36Z" + generated_at: "2026-04-29T23:07:42Z" model: gpt-5.5 provider: openai - source_hash: f5acfebb37e16c4a3602ead7c9a4f2e16315d07612dc1e929f30fb7b1bc37761 + source_hash: bf363ec2cc7100635ee6b0a7b0e7bb956521d0203b445fd38b5a75a13e8918a6 source_path: channels/whatsapp.md workflow: 16 --- -Status: 可通过 WhatsApp Web（Baileys）投入生产使用。Gateway 网关拥有已关联的会话。 +Status：已可用于生产，通过 WhatsApp Web（Baileys）。Gateway 网关拥有已关联的会话。 ## 安装（按需） - 新手引导（`openclaw onboard`）和 `openclaw channels add --channel whatsapp` 会在你首次选择 WhatsApp 插件时提示安装。 - 当插件尚未存在时，`openclaw channels login --channel whatsapp` 也会提供安装流程。 -- Dev 渠道 + git checkout：默认使用本地插件路径。 -- Stable/Beta：当当前软件包已发布时，使用 npm 包 `@openclaw/whatsapp`。 +- Dev channel + git checkout：默认使用本地插件路径。 +- Stable/Beta：当当前包已发布时，使用 npm 包 `@openclaw/whatsapp`。 仍可手动安装： @@ -28,11 +28,11 @@ Status: 可通过 WhatsApp Web（Baileys）投入生产使用。Gateway 网关 openclaw plugins install @openclaw/whatsapp ``` -如果 npm 报告 OpenClaw 拥有的软件包已弃用或缺失，请使用当前打包的 OpenClaw 构建，或使用本地 checkout，直到 npm 包发布节奏跟上。 +如果 npm 报告 OpenClaw 拥有的包已弃用或缺失，请使用当前打包的 OpenClaw 构建或本地 checkout，直到 npm 包发布节奏跟上。 - 未知发送者的默认私信策略是配对。 + 对未知发送者的默认私信策略是配对。 跨渠道诊断和修复手册。 @@ -68,13 +68,13 @@ openclaw plugins install @openclaw/whatsapp openclaw channels login --channel whatsapp ``` - 对于特定账户： + 对于特定账号： ```bash openclaw channels login --channel whatsapp --account work ``` - 如需在登录前附加现有/自定义 WhatsApp Web 凭证目录： + 如需在登录前附加现有/自定义 WhatsApp Web 认证目录： ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth @@ -98,13 +98,13 @@ openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - 配对请求会在 1 小时后过期。每个渠道最多保留 3 个待处理请求。 + 配对请求会在 1 小时后过期。待处理请求每个渠道最多 3 个。 -OpenClaw 建议尽可能在单独号码上运行 WhatsApp。（渠道元数据和设置流程针对这种设置进行了优化，但也支持个人号码设置。） +OpenClaw 建议在可行时使用单独号码运行 WhatsApp。（渠道元数据和设置流程已针对该设置优化，但也支持个人号码设置。） ## 部署模式 @@ -153,22 +153,23 @@ OpenClaw 建议尽可能在单独号码上运行 WhatsApp。（渠道元数据 ## 运行时模型 -- Gateway 网关拥有 WhatsApp 套接字和重连循环。 -- 重连看门狗使用 WhatsApp Web 传输活动，而不仅是入站应用消息数量，因此安静的已关联设备会话不会仅仅因为最近没人发送消息而被重启。如果传输帧持续到达但在看门狗窗口内没有处理任何应用消息，较长的应用静默上限仍会强制重连；对于最近活跃会话的临时重连之后，该应用静默检查会在首个恢复窗口使用常规消息超时。 -- Baileys 套接字时序在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制开启握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。 -- 出站发送要求目标账户有活跃的 WhatsApp 监听器。 +- Gateway 网关拥有 WhatsApp socket 和重连循环。 +- 重连 watchdog 使用 WhatsApp Web 传输活动，而不只是入站应用消息量，因此安静的已关联设备会话不会仅因为最近没人发消息而重启。如果传输帧持续到达但 watchdog 窗口内没有处理任何应用消息，更长的应用静默上限仍会强制重连；对于最近活跃会话的瞬时重连之后，该应用静默检查会在第一个恢复窗口使用正常消息超时。 +- Baileys socket 时序在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制打开握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。 +- 出站发送需要目标账号存在活跃的 WhatsApp listener。 - Status 和广播聊天会被忽略（`@status`、`@broadcast`）。 -- 重连看门狗跟随 WhatsApp Web 传输活动，而不仅是入站应用消息数量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在较晚的远端断开路径之前强制重连。 +- 重连 watchdog 跟随 WhatsApp Web 传输活动，而不只是入站应用消息量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在后续远端断开路径之前很早就触发重连。 - 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。 -- 群组会话是隔离的（`agent::whatsapp:group:`）。 -- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道特定的 WhatsApp 代理设置。 -- 启用 `messages.removeAckAfterReply` 后，OpenClaw 会在可见回复送达后清除 WhatsApp 确认反应。 +- 群组会话相互隔离（`agent::whatsapp:group:`）。 +- WhatsApp Web 传输会遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道专用的 WhatsApp 代理设置。 +- 启用 `messages.removeAckAfterReply` 后，OpenClaw 会在可见回复送达后清除 WhatsApp ack 反应。 ## 插件钩子和隐私 WhatsApp 入站消息可能包含个人消息内容、电话号码、 群组标识符、发送者姓名和会话关联字段。因此， -除非你显式选择加入，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子载荷： +除非你显式选择启用，否则 WhatsApp 不会向插件广播入站 +`message_received` 钩子载荷： ```json5 { @@ -182,7 +183,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 } ``` -你可以将选择加入限定到一个账户： +你可以将选择启用限定到一个账号： ```json5 { @@ -200,7 +201,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 } ``` -仅为你信任可接收入站 WhatsApp 消息内容和标识符的插件启用此选项。 +仅在你信任插件可以接收入站 WhatsApp 消息内容和标识符时才启用此项。 ## 访问控制和激活 @@ -213,15 +214,15 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `allowFrom` 接受 E.164 风格的号码（内部会规范化）。 + `allowFrom` 接受 E.164 风格号码（内部会归一化）。 - 多账户覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）优先于该账户的渠道级默认值。 + 多账号覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）优先于该账号的渠道级默认值。 - 运行时行为详情： + 运行时行为细节： - - 配对会持久化到渠道允许存储中，并与配置的 `allowFrom` 合并 - - 如果未配置 allowlist，则默认允许已关联的自身号码 - - OpenClaw 从不自动配对出站 `fromMe` 私信（你从已关联设备发给自己的消息） + - 配对会持久化到渠道 allow-store，并与配置的 `allowFrom` 合并 + - 如果未配置 allowlist，默认允许已关联的自身号码 + - OpenClaw 永远不会自动配对出站 `fromMe` 私信（你从已关联设备发给自己的消息） @@ -235,31 +236,31 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`） - `open`：绕过发送者 allowlist - `allowlist`：发送者必须匹配 `groupAllowFrom`（或 `*`） - - `disabled`：阻止所有群组入站消息 + - `disabled`：阻止所有群组入站 发送者 allowlist 回退： - 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom` - - 发送者 allowlist 会在提及/回复激活前求值 + - 发送者 allowlist 会在提及/回复激活之前评估 - 注意：如果完全没有 `channels.whatsapp` 块，即使设置了 `channels.defaults.groupPolicy`，运行时群组策略回退也是 `allowlist`（并记录警告日志）。 + 注意：如果完全不存在 `channels.whatsapp` 块，即使设置了 `channels.defaults.groupPolicy`，运行时群组策略回退也是 `allowlist`（并记录警告日志）。 - 默认情况下，群组回复需要提及。 + 群组回复默认需要提及。 提及检测包括： - - 对机器人身份的显式 WhatsApp 提及 + - 对 bot 身份的显式 WhatsApp 提及 - 配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 授权群组消息的入站语音备注转录 - - 隐式回复机器人检测（回复发送者匹配机器人身份） + - 已授权群组消息的入站语音备注转录 + - 隐式回复 bot 检测（回复发送者匹配 bot 身份） - 安全说明： + 安全注意事项： - 引用/回复只满足提及门控；它**不会**授予发送者授权 - - 使用 `groupPolicy: "allowlist"` 时，即使非 allowlist 发送者回复 allowlist 用户的消息，仍会被阻止 + - 使用 `groupPolicy: "allowlist"` 时，未在 allowlist 中的发送者即使回复了 allowlist 用户的消息，仍会被阻止 会话级激活命令： @@ -276,14 +277,14 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活： - 跳过自聊轮次的已读回执 -- 忽略否则会 ping 你自己的 mention-JID 自动触发行为 +- 忽略提及 JID 自动触发行为，否则它会 ping 你自己 - 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]` -## 消息规范化和上下文 +## 消息归一化和上下文 - 传入 WhatsApp 消息会封装在共享入站信封中。 + 传入的 WhatsApp 消息会包装在共享入站信封中。 如果存在引用回复，上下文会以这种形式追加： @@ -293,12 +294,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 [/Replying] ``` - 可用时，也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 + 可用时也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 - 仅媒体的入站消息会使用如下占位符规范化： + 仅媒体的入站消息会用如下占位符归一化： - `` - `` @@ -306,15 +307,15 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - `` - `` - 授权群组语音备注会在提及门控前转录，前提是正文只有 ``，因此在语音备注中说出机器人提及可以触发回复。如果转录仍未提及机器人， + 当正文只有 `` 时，已授权群组语音备注会在提及门控前转录，因此在语音备注中说出 bot 提及可以触发回复。如果转录仍未提及 bot， 转录会保留在待处理群组历史中，而不是原始占位符。 - 位置正文使用简短坐标文本。位置标签/评论和联系人/vCard 详情会呈现为围栏式不可信元数据，而不是内联提示文本。 + 位置正文使用简短坐标文本。位置标签/评论以及联系人/vCard 详情会呈现为围栏包裹的不受信任元数据，而不是内联提示文本。 - 对于群组，未处理的消息可以被缓冲，并在机器人最终被触发时作为上下文注入。 + 对于群组，未处理消息可以缓冲，并在 bot 最终被触发时作为上下文注入。 - 默认限制：`50` - 配置：`channels.whatsapp.historyLimit` @@ -329,7 +330,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - 对于已接受的入站 WhatsApp 消息，默认启用已读回执。 + 对已接受的入站 WhatsApp 消息，默认启用已读回执。 全局禁用： @@ -343,7 +344,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 } ``` - 按账户覆盖： + 单账号覆盖： ```json5 { @@ -376,13 +377,13 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - 支持图片、视频、音频（PTT 语音消息）和文档载荷 - - 音频媒体会通过 Baileys `audio` 载荷并带 `ptt: true` 发送，因此 WhatsApp 客户端会将其渲染为按键说话语音消息 - - 回复载荷会保留 `audioAsVoice`；WhatsApp 的 TTS 语音消息输出会继续使用这条 PTT 路径，即使提供商返回 MP3 或 WebM + - 音频媒体通过 Baileys `audio` 载荷发送，并带有 `ptt: true`，因此 WhatsApp 客户端会将其渲染为按住说话语音消息 + - 回复载荷会保留 `audioAsVoice`；即使提供商返回 MP3 或 WebM，WhatsApp 的 TTS 语音消息输出也会继续走此 PTT 路径 - 原生 Ogg/Opus 音频会以 `audio/ogg; codecs=opus` 发送，以兼容语音消息 - - 非 Ogg 音频（包括 Microsoft Edge TTS 的 MP3/WebM 输出）会先用 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus，再通过 PTT 发送 - - `/tts latest` 会把最新的助手回复作为一条语音消息发送，并阻止同一条回复重复发送；`/tts chat on|off|default` 控制当前 WhatsApp 聊天的自动 TTS + - 非 Ogg 音频，包括 Microsoft Edge TTS MP3/WebM 输出，会先用 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus，再通过 PTT 发送 + - `/tts latest` 会将最新的助手回复作为一条语音消息发送，并抑制同一回复的重复发送；`/tts chat on|off|default` 控制当前 WhatsApp 聊天的自动 TTS - 通过视频发送中的 `gifPlayback: true` 支持动画 GIF 播放 - - 发送多媒体回复载荷时，说明文字会应用到第一个媒体项；但 PTT 语音消息会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端不会一致地渲染语音消息说明文字 + - 发送多媒体回复载荷时，说明文字会应用到第一个媒体项，但 PTT 语音消息会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端无法一致地渲染语音消息说明文字 - 媒体来源可以是 HTTP(S)、`file://` 或本地路径 @@ -391,38 +392,22 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、 - 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 按账号覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` - - 图片会自动优化（调整尺寸/质量扫描）以符合限制 + - 图片会自动优化（调整大小/质量扫描）以适配限制 - 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应 -## 错误可见性 - -`channels.whatsapp.exposeErrorText` 控制是否将智能体/提供商错误文本送回 WhatsApp。默认值为 `true`。将其设为 `false` 可以让 WhatsApp 上的失败保持静默，同时保留其他渠道行为。 - -```json5 -{ - channels: { - whatsapp: { - exposeErrorText: false, - }, - }, -} -``` - -按账号覆盖使用 `channels.whatsapp.accounts..exposeErrorText`。 - ## 回复引用 -WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。使用 `channels.whatsapp.replyToMode` 控制。 +WhatsApp 支持原生回复引用，即出站回复会明显引用入站消息。使用 `channels.whatsapp.replyToMode` 控制它。 -| 值 | 行为 | -| ----------- | ---------------------------------------------------------------- | -| `"off"` | 永不引用；作为普通消息发送 | -| `"first"` | 仅引用第一个出站回复片段 | -| `"all"` | 引用每个出站回复片段 | -| `"batched"` | 引用已排队的批量回复，同时让即时回复不带引用 | +| 值 | 行为 | +| ----------- | --------------------------------------------------------------------- | +| `"off"` | 永不引用；作为普通消息发送 | +| `"first"` | 只引用第一个出站回复分块 | +| `"all"` | 引用每个出站回复分块 | +| `"batched"` | 引用排队的批量回复，同时让即时回复不带引用 | 默认值为 `"off"`。按账号覆盖使用 `channels.whatsapp.accounts..replyToMode`。 @@ -440,12 +425,12 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 `channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情反应的范围： -| 级别 | 确认反应 | 智能体发起的反应 | 描述 | -| ------------- | -------- | ---------------- | ---------------------------------- | -| `"off"` | 否 | 否 | 完全不使用反应 | -| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） | -| `"minimal"` | 是 | 是（保守） | 确认 + 带保守指引的智能体反应 | -| `"extensive"` | 是 | 是（鼓励） | 确认 + 带鼓励指引的智能体反应 | +| 级别 | 确认反应 | 智能体发起的反应 | 描述 | +| ------------- | -------- | ---------------- | -------------------------------- | +| `"off"` | 否 | 否 | 完全不使用反应 | +| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） | +| `"minimal"` | 是 | 是（保守） | 确认 + 智能体反应，采用保守引导 | +| `"extensive"` | 是 | 是（鼓励） | 确认 + 智能体反应，采用鼓励引导 | 默认值：`"minimal"`。 @@ -464,7 +449,7 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 ## 确认反应 WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。 -确认反应受 `reactionLevel` 限制，当 `reactionLevel` 为 `"off"` 时会被抑制。 +确认反应受 `reactionLevel` 控制，当 `reactionLevel` 为 `"off"` 时会被抑制。 ```json5 { @@ -482,9 +467,9 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 行为说明： -- 在入站消息被接受后立即发送（回复前） -- 失败会被记录，但不会阻止正常回复送达 -- 群组模式 `mentions` 会在由提及触发的轮次中作出反应；群组激活 `always` 会作为此检查的绕过条件 +- 入站消息被接受后立即发送（回复前） +- 失败会记录日志，但不会阻塞正常回复投递 +- 群组模式 `mentions` 会在提及触发的轮次中反应；群组激活 `always` 会绕过此检查 - WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`） ## 多账号和凭据 @@ -492,7 +477,7 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - 账号 ID 来自 `channels.whatsapp.accounts` - - 默认账号选择：如果存在 `default`，则使用它；否则使用第一个已配置账号 ID（排序后） + - 默认账号选择：如果存在 `default` 则使用它，否则使用第一个已配置的账号 ID（排序后） - 账号 ID 会在内部规范化以便查找 @@ -500,14 +485,14 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - 当前认证路径：`~/.openclaw/credentials/whatsapp//creds.json` - 备份文件：`creds.json.bak` - - 仍会识别/迁移 `~/.openclaw/credentials/` 中的旧版默认认证，用于默认账号流程 + - `~/.openclaw/credentials/` 中的旧版默认认证仍会在默认账号流程中被识别/迁移 - - `openclaw channels logout --channel whatsapp [--account ]` 会清除该账号的 WhatsApp 认证状态。 + + `openclaw channels logout --channel whatsapp [--account ]` 会清除此账号的 WhatsApp 认证状态。 - 在旧版认证目录中，`oauth.json` 会被保留，而 Baileys 认证文件会被删除。 + 在旧版认证目录中，`oauth.json` 会被保留，而 Baileys 认证文件会被移除。 @@ -515,16 +500,16 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 ## 工具、操作和配置写入 - 智能体工具支持包括 WhatsApp 反应操作（`react`）。 -- 操作开关： +- 操作门控： - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- 渠道发起的配置写入默认启用（可通过 `channels.whatsapp.configWrites=false` 禁用）。 +- 渠道发起的配置写入默认启用（通过 `channels.whatsapp.configWrites=false` 禁用）。 ## 故障排除 - - 症状：渠道状态报告未链接。 + + 症状：渠道 Status 报告未关联。 修复： @@ -535,12 +520,12 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - - 症状：已链接账号反复断开连接或尝试重连。 + + 症状：已关联账号反复断开连接或尝试重连。 - 安静账号可以在正常消息超时后仍保持连接；当 WhatsApp Web 传输活动停止、套接字关闭，或应用级活动在更长的安全窗口之外持续静默时，看门狗会重启。 + 安静账号可以在正常消息超时后继续保持连接；当 WhatsApp Web 传输活动停止、套接字关闭，或应用级活动在更长的安全窗口之外仍保持静默时，看门狗会重启。 - 如果日志显示重复的 `status=408 Request Time-out Connection was lost`，请调整 `web.whatsapp` 下的 Baileys 套接字时序。先将 `keepAliveIntervalMs` 缩短到低于你的网络空闲超时时间，并在缓慢或丢包链路上增大 `connectTimeoutMs`： + 如果日志显示重复的 `status=408 Request Time-out Connection was lost`，请调整 `web.whatsapp` 下的 Baileys 套接字计时。先将 `keepAliveIntervalMs` 缩短到低于你的网络空闲超时时间，并在慢速或高丢包链路上增加 `connectTimeoutMs`： ```json5 { @@ -561,26 +546,26 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 openclaw logs --follow ``` - 如有需要，使用 `channels login` 重新链接。 + 如有需要，使用 `channels login` 重新关联。 - - 症状：`openclaw channels login --channel whatsapp` 在显示可用 QR 码之前失败，并出现 `status=408 Request Time-out` 或 TLS 套接字断开。 + + 症状：`openclaw channels login --channel whatsapp` 在显示可用 QR 码之前失败，并出现 `status=408 Request Time-out` 或 TLS 套接字断开连接。 - WhatsApp Web 登录使用 Gateway 网关主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、小写变体和 `NO_PROXY`）。确认 Gateway 网关进程继承了代理环境变量，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。 + WhatsApp Web 登录使用 Gateway 网关主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、小写变体和 `NO_PROXY`）。确认 Gateway 网关进程继承了代理环境，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。 - 当目标账号没有活动的 Gateway 网关监听器时，出站发送会快速失败。 + 当目标账号没有活动 Gateway 网关监听器时，出站发送会快速失败。 - 确保 Gateway 网关正在运行且账号已链接。 + 确保 Gateway 网关正在运行，并且账号已关联。 - - 按此顺序检查： + + 按以下顺序检查： - `groupPolicy` - `groupAllowFrom` / `allowFrom` @@ -591,40 +576,40 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp/Telegram Gateway 网关操作。 + WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp/Telegram Gateway 网关运行。 ## 系统提示词 -WhatsApp 支持通过 `groups` 和 `direct` 映射为群组和直接聊天设置 Telegram 风格的系统提示词。 +WhatsApp 通过 `groups` 和 `direct` 映射支持用于群组和直接聊天的 Telegram 风格系统提示词。 群组消息的解析层级： -首先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后在得到的单一映射上执行提示词查找： +首先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后在生成的单个映射上执行提示词查找： -1. **群组专属系统提示词**（`groups[""].systemPrompt`）：当映射中存在特定群组条目**且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），通配符会被抑制，并且不会应用任何系统提示词。 -2. **群组通配系统提示词**（`groups["*"].systemPrompt`）：当映射中完全没有特定群组条目，或存在该条目但未定义 `systemPrompt` 键时使用。 +1. **群组专属系统提示词**（`groups[""].systemPrompt`）：当映射中存在特定群组条目**并且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用系统提示词。 +2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在特定群组条目，或存在该条目但未定义 `systemPrompt` 键时使用。 -直接消息的解析层级： +私信消息的解析层级： -首先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后在得到的单一映射上执行提示词查找： +首先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后在生成的单个映射上执行提示词查找： -1. **直接聊天专属系统提示词**（`direct[""].systemPrompt`）：当映射中存在特定对端条目**且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），通配符会被抑制，并且不会应用任何系统提示词。 -2. **直接聊天通配系统提示词**（`direct["*"].systemPrompt`）：当映射中完全没有特定对端条目，或存在该条目但未定义 `systemPrompt` 键时使用。 +1. **私信专属系统提示词**（`direct[""].systemPrompt`）：当映射中存在特定对等方条目**并且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用系统提示词。 +2. **私信通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在特定对等方条目，或存在该条目但未定义 `systemPrompt` 键时使用。 -`dms` 仍然是轻量级的按私信历史覆盖存储桶（`dms..historyLimit`）。提示词覆盖位于 `direct` 下。 +`dms` 仍然是轻量的按私信历史覆盖桶（`dms..historyLimit`）。提示词覆盖位于 `direct` 下。 -**与 Telegram 多账号行为的差异：** 在 Telegram 中，根级 `groups` 会被有意对多账号设置中的所有账号抑制，即使某些账号没有定义自己的 `groups`，也是如此，以防止机器人接收它不属于的群组的群组消息。WhatsApp 不应用此保护：根级 `groups` 和根级 `direct` 始终会被没有定义账号级覆盖的账号继承，无论配置了多少个账号。在多账号 WhatsApp 设置中，如果你想要按账号设置群组或直接聊天提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。 +**与 Telegram 多账号行为的区别：** 在 Telegram 中，对于多账号设置中的所有账号，根级 `groups` 都会被有意抑制，即使账号没有定义自己的 `groups` 也是如此，以防止机器人接收不属于它的群组的群组消息。WhatsApp 不应用此保护：未定义账号级覆盖的账号始终会继承根级 `groups` 和根级 `direct`，无论配置了多少个账号。在多账号 WhatsApp 设置中，如果你想使用按账号的群组或私信提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。 重要行为： - `channels.whatsapp.groups` 既是按群组配置映射，也是聊天级群组允许列表。在根级或账号作用域中，`groups["*"]` 表示该作用域“允许所有群组”。 -- 仅当你已经希望该作用域允许所有群组时，才添加通配群组 `systemPrompt`。如果你仍只希望固定的一组群组 ID 符合条件，请不要使用 `groups["*"]` 作为提示词默认值。请改为在每个显式允许列出的群组条目上重复该提示词。 -- 群组准入和发送者授权是两个独立检查。`groups["*"]` 会扩大可以进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 -- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已经通过 `dmPolicy` 加 `allowFrom` 或配对存储规则准入后，提供默认的直接聊天配置。 +- 只有当你已经希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍然只想让固定的一组群组 ID 有资格进入，请不要使用 `groups["*"]` 作为提示词默认值。请改为在每个显式允许的群组条目上重复该提示词。 +- 群组准入和发送者授权是相互独立的检查。`groups["*"]` 会扩大可进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 +- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已通过 `dmPolicy` 加 `allowFrom` 或配对存储规则被准入后，提供默认的直接聊天配置。 示例： @@ -666,7 +651,7 @@ WhatsApp 支持通过 `groups` 和 `direct` 映射为群组和直接聊天设置 } ``` -## 配置参考指针 +## 配置参考指引 主要参考： @@ -674,12 +659,12 @@ WhatsApp 支持通过 `groups` 和 `direct` 映射为群组和直接聊天设置 高价值 WhatsApp 字段： -- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` -- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel`、`exposeErrorText` -- 多账号：`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` +- 访问控制：`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups` +- 发送：`textChunkLimit`, `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` ## 相关内容