openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 02:43:25 +00:00
parent e3f2ffe4c3
commit 6bbe94b1e9
1 changed files with 143 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
docs/zh-CN/channels/whatsapp.md
View File

@ -1,43 +1,45 @@
---
read_when:
- 处理 WhatsApp/网页渠道行为或收件箱路由
summary: WhatsApp 渠道支持、访问控制、交付行为和运维
- 处理 WhatsApp/web 渠道行为或收件箱路由
summary: WhatsApp 渠道支持、访问控制、投递行为和运维
title: WhatsApp
x-i18n:
generated_at: "2026-04-29T23:07:42Z"
generated_at: "2026-04-30T02:42:12Z"
model: gpt-5.5
provider: openai
source_hash: bf363ec2cc7100635ee6b0a7b0e7bb956521d0203b445fd38b5a75a13e8918a6
source_hash: 5d0268e068de0001a11a6ed87fe70df8e685d1dcc87c8142ee5b3c77d7a727f3
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 channel + git checkout：默认使用本地插件路径。
- Stable/Beta：当当前包已发布时，使用 npm 包 `@openclaw/whatsapp`。
- 当插件尚不存在时，`openclaw channels login --channel whatsapp` 也会提供安装流程。
- 开发渠道 + git checkout：默认使用本地插件路径。
- Stable/Beta：当当前软件包已发布时，使用 npm 包 `@openclaw/whatsapp`。
仍可手动安装：
手动安装仍然可用：
```bash
openclaw plugins install @openclaw/whatsapp
```
如果 npm 报告 OpenClaw 拥有的包已弃用或缺失，请使用当前打包的 OpenClaw 构建或本地 checkout，直到 npm 包发布节奏跟上。
如果 npm 报告 OpenClaw 拥有的软件包已弃用或缺失，请使用
当前已打包的 OpenClaw 构建版本或本地 checkout，直到 npm package train
跟上。
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
对未知发送者的默认私信策略是配对。
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断和修复手册。
</Card>
<Card title="Gateway configuration" icon="settings" href="/zh-CN/gateway/configuration">
<Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
完整的渠道配置模式和示例。
</Card>
</CardGroup>
@ -45,7 +47,7 @@ openclaw plugins install @openclaw/whatsapp
## 快速设置
<Steps>
<Step title="Configure WhatsApp access policy">
<Step title="配置 WhatsApp 访问策略">
```json5
{
@ -62,19 +64,19 @@ openclaw plugins install @openclaw/whatsapp
</Step>
<Step title="Link WhatsApp (QR)">
<Step title="关联 WhatsApp（二维码）">
```bash
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
@ -83,7 +85,7 @@ openclaw channels login --channel whatsapp --account work
</Step>
<Step title="Start the gateway">
<Step title="启动 Gateway 网关">
```bash
openclaw gateway
@ -91,31 +93,31 @@ openclaw gateway
</Step>
<Step title="Approve first pairing request (if using pairing mode)">
<Step title="批准首次配对请求（如果使用配对模式）">
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
配对请求会在 1 小时后过期。待处理请求每个渠道最多 3 个。
配对请求会在 1 小时后过期。每个渠道最多有 3 个待处理请求。
</Step>
</Steps>
<Note>
OpenClaw 建议在可行时使用单独号码运行 WhatsApp。（渠道元数据和设置流程已针对该设置优化，但也支持个人号码设置。）
OpenClaw 建议尽可能在单独号码上运行 WhatsApp。（渠道元数据和设置流程已针对这种设置优化，但也支持个人号码设置。）
</Note>
## 部署模式
<AccordionGroup>
<Accordion title="Dedicated number (recommended)">
这是最清晰的运维模式：
<Accordion title="专用号码（推荐）">
这是最干净的运维模式：
- 为 OpenClaw 使用单独的 WhatsApp 身份
- 更清晰的私信 allowlist 和路由边界
- 降低自聊混淆的可能性
- 更清晰的私信允许列表和路由边界
- 更低的自聊混淆概率
最小策略模式：
@ -132,8 +134,8 @@ OpenClaw 建议在可行时使用单独号码运行 WhatsApp。（渠道元数
</Accordion>
<Accordion title="Personal-number fallback">
新手引导支持个人号码模式，并写入适合自聊的基线：
<Accordion title="个人号码回退">
新手引导支持个人号码模式，并会写入适合自聊的基线：
- `dmPolicy: "allowlist"`
- `allowFrom` 包含你的个人号码
@ -143,7 +145,7 @@ OpenClaw 建议在可行时使用单独号码运行 WhatsApp。（渠道元数
</Accordion>
<Accordion title="WhatsApp Web-only channel scope">
<Accordion title="仅限 WhatsApp Web 的渠道范围">
在当前 OpenClaw 渠道架构中，消息平台渠道基于 WhatsApp Web（`Baileys`）。
内置聊天渠道注册表中没有单独的 Twilio WhatsApp 消息渠道。
@ -154,22 +156,21 @@ OpenClaw 建议在可行时使用单独号码运行 WhatsApp。（渠道元数
## 运行时模型
- Gateway 网关拥有 WhatsApp socket 和重连循环。
- 重连 watchdog 使用 WhatsApp Web 传输活动，而不只是入站应用消息量，因此安静的已关联设备会话不会仅因为最近没人发消息而重启。如果传输帧持续到达但 watchdog 窗口内没有处理任何应用消息，更长的应用静默上限仍会强制重连；对于最近活跃会话的瞬时重连之后，该应用静默检查会在第一个恢复窗口使用正常消息超时。
- 重连 watchdog 使用 WhatsApp Web 传输活动，而不仅仅是入站应用消息量，因此安静的已关联设备会话不会仅因为最近没有人发送消息而被重启。如果传输帧持续到达但在 watchdog 窗口内没有处理任何应用消息，较长的应用静默上限仍会强制重连；对于最近活跃会话的瞬时重连之后，该应用静默检查会在第一个恢复窗口使用正常消息超时。
- Baileys socket 时序在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制打开握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。
- 出站发送需要目标账号存在活跃的 WhatsApp listener。
- 出站发送要求目标账号有活跃的 WhatsApp listener。
- Status 和广播聊天会被忽略（`@status`、`@broadcast`）。
- 重连 watchdog 跟随 WhatsApp Web 传输活动，而不只是入站应用消息量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在后续远端断开路径之前很早就触发重连。
- 重连 watchdog 跟随 WhatsApp Web 传输活动，而不仅仅是入站应用消息量：安静的已关联设备会话会在传输帧持续时保持在线，但传输停滞会在后续远端断开路径之前强制重连。
- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。
- 群组会话相互隔离（`agent:<agentId>:whatsapp:group:<jid>`）。
- WhatsApp Web 传输会遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道专用的 WhatsApp 代理设置。
- 启用 `messages.removeAckAfterReply` 后，OpenClaw 会在可见回复送达后清除 WhatsApp ack 反应。
- WhatsApp Web 传输会遵守 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道特定的 WhatsApp 代理设置。
- 启用 `messages.removeAckAfterReply` 后，OpenClaw 会在可见回复送达后清除 WhatsApp ack reaction。
## 插件钩子和隐私
WhatsApp 入站消息可能包含个人消息内容、电话号码、
群组标识符、发送者姓名和会话关联字段。因此，
除非你显式选择启用，否则 WhatsApp 不会向插件广播入站
`message_received` 钩子载荷：
除非你显式选择启用，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子 payload：
```json5
{
@ -183,7 +184,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
}
```
你可以将选择启用限定到一个账号：
你可以将选择启用范围限定到一个账号：
```json5
{
@ -201,12 +202,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
}
```
仅在你信任插件可以接收入站 WhatsApp 消息内容和标识符时才启用此项。
仅为你信任可接收入站 WhatsApp 消息内容和标识符的插件启用此项。
## 访问控制和激活
<Tabs>
<Tab title="DM policy">
<Tab title="私信策略">
`channels.whatsapp.dmPolicy` 控制直接聊天访问：
- `pairing`（默认）
@ -214,53 +215,53 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
- `open`（要求 `allowFrom` 包含 `"*"`）
- `disabled`
`allowFrom` 接受 E.164 风格号码（内部会归一化）。
`allowFrom` 接受 E.164 风格号码（内部会规范化）。
多账号覆盖：`channels.whatsapp.accounts.<id>.dmPolicy`（以及 `allowFrom`）优先于该账号的渠道级默认值。
运行时行为细节：
- 配对会持久化到渠道 allow-store，并与配置的 `allowFrom` 合并
- 如果未配置 allowlist，默认允许已关联的自身号码
- OpenClaw 永远不会自动配对出站 `fromMe` 私信（你从已关联设备发给自己的消息）
- 配对会持久化到渠道 allow-store，并与已配置的 `allowFrom` 合并
- 如果未配置允许列表，默认允许已关联的自身号码
- OpenClaw 永远不会自动配对出站 `fromMe` 私信（你从已关联设备发送给自己的消息）
</Tab>
<Tab title="Group policy + allowlists">
<Tab title="群组策略 + 允许列表">
群组访问有两层：
1. **群组成员 allowlist**（`channels.whatsapp.groups`）
1. **群组成员允许列表**（`channels.whatsapp.groups`）
- 如果省略 `groups`，所有群组都符合条件
- 如果存在 `groups`，它会作为群组 allowlist（允许 `"*"`）
- 如果存在 `groups`，它会作为群组允许列表（允许 `"*"`）
2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）
- `open`：绕过发送者 allowlist
- `open`：绕过发送者允许列表
- `allowlist`：发送者必须匹配 `groupAllowFrom`（或 `*`）
- `disabled`：阻止所有群组入站
发送者 allowlist 回退：
发送者允许列表回退：
- 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom`
- 发送者 allowlist 会在提及/回复激活之前评估
- 发送者允许列表会在提及/回复激活之前评估
注意：如果完全不存在 `channels.whatsapp` 块，即使设置了 `channels.defaults.groupPolicy`，运行时群组策略回退也是 `allowlist`（并记录警告日志）。
注意：如果完全不存在 `channels.whatsapp` 块，运行时群组策略回退为 `allowlist`（带警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。
</Tab>
<Tab title="Mentions + /activation">
群组回复默认需要提及。
<Tab title="提及 + /activation">
群组回复默认要求提及。
提及检测包括：
- 对 bot 身份的显式 WhatsApp 提及
- 配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 已授权群组消息的入站语音备注转录
- 隐式回复 bot 检测（回复发送者匹配 bot 身份）
- 对机器人身份的显式 WhatsApp 提及
- 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
- 授权群组消息的入站语音备注转录
- 隐式回复机器人检测（回复发送者匹配机器人身份）
安全注意事项：
- 引用/回复只满足提及门控；它**不会**授予发送者授权
- 使用 `groupPolicy: "allowlist"` 时，未在 allowlist 中的发送者即使回复了 allowlist 用户的消息，仍会被阻止
- 使用 `groupPolicy: "allowlist"` 时，即使非允许列表发送者回复了允许列表用户的消息，仍会被阻止
会话级激活命令：
@ -274,19 +275,19 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
## 个人号码和自聊行为
当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活：
当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊防护会激活：
- 跳过自聊轮次的已读回执
- 忽略提及 JID 自动触发行为，否则它会 ping 你自己
- 忽略原本会 ping 你自己的提及 JID 自动触发行为
- 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]`
## 消息归一化和上下文
## 消息规范化和上下文
<AccordionGroup>
<Accordion title="Inbound envelope + reply context">
传入的 WhatsApp 消息会包装在共享入站信封中。
<Accordion title="入站信封 + 回复上下文">
传入的 WhatsApp 消息会被包装在共享入站信封中。
如果存在引用回复，上下文会以这种形式追加：
如果存在引用回复，上下文会按以下形式追加：
```text
[Replying to <sender> id:<stanzaId>]
@ -298,8 +299,8 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
</Accordion>
<Accordion title="Media placeholders and location/contact extraction">
仅媒体的入站消息会用如下占位符归一化：
<Accordion title="媒体占位符和位置/联系人提取">
仅媒体的入站消息会使用如下占位符规范化：
- `<media:image>`
- `<media:video>`
@ -307,15 +308,16 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
- `<media:document>`
- `<media:sticker>`
当正文只有 `<media:audio>` 时，已授权群组语音备注会在提及门控前转录，因此在语音备注中说出 bot 提及可以触发回复。如果转录仍未提及 bot，
转录会保留在待处理群组历史中，而不是原始占位符。
当正文只有 `<media:audio>` 时，授权群组语音备注会在提及门控之前转录，因此在语音备注中说出机器人提及可以
触发回复。如果转录仍未提及机器人，
则转录会保留在待处理群组历史中，而不是原始占位符。
位置正文使用简短坐标文本。位置标签/评论以及联系人/vCard 详情会呈现为围栏包裹的不受信任元数据，而不是内联提示文本。
位置正文使用简短的坐标文本。位置标签/评论和联系人/vCard 详情会渲染为带围栏的不受信任元数据，而不是内联 prompt 文本。
</Accordion>
<Accordion title="Pending group history injection">
对于群组，未处理消息可以缓冲，并在 bot 最终被触发时作为上下文注入。
<Accordion title="待处理群组历史注入">
对于群组，未处理消息可以缓冲，并在机器人最终被触发时作为上下文注入。
- 默认限制：`50`
- 配置：`channels.whatsapp.historyLimit`
@ -329,8 +331,8 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
</Accordion>
<Accordion title="Read receipts">
对已接受的入站 WhatsApp 消息，默认启用已读回执。
<Accordion title="已读回执">
已接受的入站 WhatsApp 消息默认启用已读回执。
全局禁用：
@ -344,7 +346,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
}
```
单账号覆盖：
按账号覆盖：
```json5
{
@ -365,10 +367,10 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
</Accordion>
</AccordionGroup>
## 送达、分块和媒体
## 投递、分块和媒体
<AccordionGroup>
<Accordion title="Text chunking">
<Accordion title="文本分块">
- 默认分块限制：`channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- `newline` 模式优先使用段落边界（空行），然后回退到长度安全的分块
@ -376,14 +378,14 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
</Accordion>
<Accordion title="出站媒体行为">
- 支持图片、视频、音频（PTT 语音消息）和文档载荷
- 音频媒体通过 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
- 通过视频发送中的 `gifPlayback: true` 支持动画 GIF 播放
- 发送多媒体回复载荷时，说明文字会应用到第一个媒体项，但 PTT 语音消息会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端无法一致地渲染语音消息说明文字
- 支持图片、视频、音频（PTT 语音便笺）和文档载荷
- 音频媒体通过 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
- 通过在视频发送中设置 `gifPlayback: true` 支持动画 GIF 播放
- 发送多媒体回复载荷时，标题会应用到第一个媒体项；但 PTT 语音便笺会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端无法一致地渲染语音便笺标题
- 媒体来源可以是 HTTP(S)、`file://` 或本地路径
</Accordion>
@ -392,7 +394,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、
- 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
- 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
- 按账号覆盖使用 `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- 图片会自动优化（调整大小/质量扫描）以适配限制
- 图片会自动优化（调整大小/质量扫描）以符合限制
- 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应
</Accordion>
@ -404,10 +406,10 @@ WhatsApp 支持原生回复引用，即出站回复会明显引用入站消息
| 值 | 行为 |
| ----------- | --------------------------------------------------------------------- |
| `"off"` | 永不引用；作为普通消息发送 |
| `"off"` | 从不引用；作为普通消息发送 |
| `"first"` | 只引用第一个出站回复分块 |
| `"all"` | 引用每个出站回复分块 |
| `"batched"` | 引用排队的批量回复，同时让即时回复不带引用 |
| `"batched"` | 引用已排队的批量回复，同时让即时回复不带引用 |
默认值为 `"off"`。按账号覆盖使用 `channels.whatsapp.accounts.<id>.replyToMode`。
@ -425,12 +427,12 @@ WhatsApp 支持原生回复引用，即出站回复会明显引用入站消息
`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情反应的范围：
| 级别 | 确认反应 | 智能体发起的反应 | 描述 |
| ------------- | -------- | ---------------- | -------------------------------- |
| `"off"` | 否 | 否 | 完全不使用反应 |
| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） |
| `"minimal"` | 是 | 是（保守） | 确认 + 智能体反应，采用保守引导 |
| `"extensive"` | 是 | 是（鼓励） | 确认 + 智能体反应，采用鼓励引导 |
| 级别 | 确认反应 | 智能体发起的反应 | 描述 |
| ------------- | -------- | ---------------------- | ------------------------------ |
| `"off"` | 否 | 否 | 完全不使用反应 |
| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） |
| `"minimal"` | 是 | 是（保守） | 确认 + 带保守指引的智能体反应 |
| `"extensive"` | 是 | 是（鼓励） | 确认 + 带鼓励指引的智能体反应 |
默认值：`"minimal"`。
@ -449,7 +451,7 @@ WhatsApp 支持原生回复引用，即出站回复会明显引用入站消息
## 确认反应
WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。
确认反应受 `reactionLevel` 控制，当 `reactionLevel` 为 `"off"` 时会被抑制。
确认反应受 `reactionLevel` 控制：当 `reactionLevel` 为 `"off"` 时会被抑制。
```json5
{
@ -468,8 +470,8 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
行为说明：
- 入站消息被接受后立即发送（回复前）
- 失败会记录日志，但不会阻塞正常回复投递
- 群组模式 `mentions` 会在提及触发的轮次中反应；群组激活 `always` 会绕过此检查
- 失败会被记录，但不会阻塞正常回复投递
- 群组模式 `mentions` 会在由提及触发的回合中做出反应；群组激活 `always` 会绕过此检查
- WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`）
## 多账号和凭据
@ -477,20 +479,20 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
<AccordionGroup>
<Accordion title="账号选择和默认值">
- 账号 ID 来自 `channels.whatsapp.accounts`
- 默认账号选择：如果存在 `default` 则使用它，否则使用第一个已配置的账号 ID（排序后）
- 账号 ID 会在内部规范化以便查找
- 默认账号选择：如果存在则使用 `default`，否则使用第一个已配置账号 ID（排序后）
- 账号 ID 会在内部标准化以便查找
</Accordion>
<Accordion title="凭据路径和旧版兼容性">
- 当前认证路径：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- 备份文件：`creds.json.bak`
- `~/.openclaw/credentials/` 中的旧版默认认证仍会在默认账号流程中被识别/迁移
- `~/.openclaw/credentials/` 中的旧版默认认证仍会被默认账号流程识别/迁移
</Accordion>
<Accordion title="注销行为">
`openclaw channels logout --channel whatsapp [--account <id>]` 会清除此账号的 WhatsApp 认证状态。
<Accordion title="退出登录行为">
`openclaw channels logout --channel whatsapp [--account <id>]` 会清除该账号的 WhatsApp 认证状态。
在旧版认证目录中，`oauth.json` 会被保留，而 Baileys 认证文件会被移除。
@ -503,13 +505,13 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
- 操作门控：
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
- 渠道发起的配置写入默认启用（通过 `channels.whatsapp.configWrites=false` 禁用）。
- 渠道发起的配置写入默认启用（可通过 `channels.whatsapp.configWrites=false` 禁用）。
## 故障排除
<AccordionGroup>
<Accordion title="未关联（需要 QR）">
症状：渠道 Status 报告未关联。
症状：渠道 Status 报告为未关联。
修复：
@ -520,12 +522,12 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
</Accordion>
<Accordion title="已关联但断开连接/重连循环">
症状：已关联账号反复断开连接或尝试重连。
<Accordion title="已关联但断开连接 / 重新连接循环">
症状：已关联账号反复断开连接或反复尝试重新连接。
安静账号可以在正常消息超时后继续保持连接；当 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
{
@ -550,28 +552,37 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
</Accordion>
<Accordion title="代理后方的 QR 登录超时">
<Accordion title="代理后面的 QR 登录超时">
症状：`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`。
</Accordion>
<Accordion title="发送时没有活动监听器">
当目标账号没有活动 Gateway 网关监听器时，出站发送会快速失败。
当目标账号不存在活动 Gateway 网关监听器时，出站发送会快速失败。
确保 Gateway 网关正在运行，并且账号已关联。
请确认 Gateway 网关正在运行，并且账号已关联。
</Accordion>
<Accordion title="群组消息意外被忽略">
<Accordion title="回复出现在转录中，但未出现在 WhatsApp 中">
转录行记录的是智能体生成的内容。WhatsApp 投递会单独检查：OpenClaw 只有在 Baileys 为至少一次可见文本或媒体发送返回出站消息 ID 后，才会将自动回复视为已发送。
确认反应是独立的回复前回执。反应成功并不能证明后续的文本或媒体回复已被 WhatsApp 接受。
检查 Gateway 网关日志中是否有 `auto-reply delivery failed` 或 `auto-reply was not accepted by WhatsApp provider`。
</Accordion>
<Accordion title="群组消息被意外忽略">
按以下顺序检查：
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- `groups` 允许列表条目
- 提及门控（`requireMention` + 提及模式）
- `openclaw.json`（JSON5）中的重复键：后面的条目会覆盖前面的条目，因此每个作用域只保留一个 `groupPolicy`
- `openclaw.json`（JSON5）中的重复键：较后的条目会覆盖较早的条目，因此每个作用域只保留一个 `groupPolicy`
</Accordion>
@ -582,34 +593,34 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
## 系统提示词
WhatsApp 通过 `groups` 和 `direct` 映射支持用于群组和直接聊天的 Telegram 风格系统提示词。
WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和直接聊天系统提示词。
群组消息的解析层级：
首先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后在生成的单个映射上执行提示词查找：
会先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不做深度合并）。然后提示词查找会在生成的单个映射上运行：
1. **群组专属系统提示词**（`groups["<groupId>"].systemPrompt`）：当映射中存在特定群组条目**并且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用系统提示词。
2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在特定群组条目，或存在该条目但未定义 `systemPrompt` 键时使用。
1. **群组特定系统提示词**（`groups["<groupId>"].systemPrompt`）：当映射中存在特定群组条目**且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，且不应用任何系统提示词。
2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在特定群组条目，或条目存在但未定义 `systemPrompt` 键时使用。
私信消息的解析层级：
直接消息的解析层级：
首先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后在生成的单个映射上执行提示词查找：
会先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不做深度合并）。然后提示词查找会在生成的单个映射上运行：
1. **私信专属系统提示词**（`direct["<peerId>"].systemPrompt`）：当映射中存在特定对等方条目**并且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用系统提示词。
2. **私信通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在特定对等方条目，或存在该条目但未定义 `systemPrompt` 键时使用。
1. **直接聊天特定系统提示词**（`direct["<peerId>"].systemPrompt`）：当映射中存在特定对端条目**且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，且不应用任何系统提示词。
2. **直接聊天通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在特定对端条目，或条目存在但未定义 `systemPrompt` 键时使用。
<Note>
`dms` 仍然是轻量的按私信历史覆盖桶（`dms.<id>.historyLimit`）。提示词覆盖位于 `direct` 下。
`dms` 仍然是轻量级的按私信历史覆盖桶（`dms.<id>.historyLimit`）。提示词覆盖位于 `direct` 下。
</Note>
**与 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` 或配对存储规则被准入后，提供默认的直接聊天配置。
- `channels.whatsapp.groups` 既是按群组的配置映射，也是聊天级群组允许列表。在根作用域或账号作用域中，`groups["*"]` 表示该作用域“允许所有群组进入”。
- 只有在你已经希望该作用域允许所有群组进入时，才添加通配符群组 `systemPrompt`。如果你仍然只希望固定的一组群组 ID 符合条件，请不要使用 `groups["*"]` 来设置默认提示。改为在每个显式加入允许列表的群组条目上重复该提示。
- 群组准入和发送者授权是两项独立检查。`groups["*"]` 会扩大可进入群组处理流程的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 分别控制。
- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已通过 `dmPolicy` 加 `allowFrom` 或配对存储规则准入后，提供默认的直接聊天配置。
示例：
@ -657,14 +668,14 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持用于群组和直接聊天的
- [配置参考 - WhatsApp](/zh-CN/gateway/config-channels#whatsapp)
高价值 WhatsApp 字段：
高信号 WhatsApp 字段：
- 访问控制：`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
- 发送：`textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`
- 多账号：`accounts.<id>.enabled`, `accounts.<id>.authDir`, 账号级覆盖项
- 操作：`configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*`
- 会话行为：`session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
- 提示词：`groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
- 访问：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel`
- 多账号：`accounts.<id>.enabled`、`accounts.<id>.authDir`、账号级覆盖
- 运维：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`、`web.whatsapp.*`
- 会话行为：`session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms.<id>.historyLimit`
- 提示：`groups.<id>.systemPrompt`、`groups["*"].systemPrompt`、`direct.<id>.systemPrompt`、`direct["*"].systemPrompt`
## 相关内容