OpenClaw 怎么接入 WhatsApp？本文提供完整配置操作。通过 WhatsApp Web（Baileys 库）集成，支持独立号码或个人号码部署。快速步骤：配置访问策略 → QR 扫码登录 → 启动网关 → 批准配对请求。关键配置包括 dmPolicy、groupPolicy、媒体大小限制、确认反应和系统提示。故障排查覆盖断连重连、群组消息忽略、代理超时等场景。

WhatsApp（Web 渠道）

状态：通过 WhatsApp Web（Baileys）实现，已生产就绪。Gateway 独占管理已关联的会话。

安装

• 首次通过 openclaw onboard 或 openclaw channels add --channel whatsapp 选择该渠道时，会提示安装 WhatsApp 插件。
• openclaw channels login --channel whatsapp 在插件未安装时也会提供安装流程。
• 开发渠道 + git checkout：默认使用本地插件路径。
• Stable/Beta：先从 ClawHub 安装官方 @openclaw/whatsapp 插件，npm 作为回退。
• WhatsApp 运行时依赖与 OpenClaw 核心 npm 包分离，确保外部插件携带完整依赖。

手动安装：

openclaw plugins install clawhub:@openclaw/whatsapp

仅当需要注册表回退时使用 @openclaw/whatsapp 裸包。需要可复现安装时锁定精确版本。

配对机制

未知发送者的默认私信策略是配对模式。

渠道故障排查

跨渠道诊断与修复手册。

网关配置

全渠道配置模式与示例。

快速配置

配置 WhatsApp 访问策略

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

扫码关联 WhatsApp

openclaw channels login --channel whatsapp

指定账号：

openclaw channels login --channel whatsapp --account work

登录前附加已有的 WhatsApp Web 认证目录：

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

启动 Gateway

openclaw gateway

批准首个配对请求（如使用 pairing 模式）

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

配对请求有效期 1 小时，每个渠道最多同时存在 3 个待处理请求。

INFO

OpenClaw 建议在可能时使用独立号码运行 WhatsApp。（渠道元数据和配置流程针对该模式优化，但个人号码也支持。）

部署模式

独立号码（推荐）

最简洁的运营模式：

- OpenClaw 有独立的 WhatsApp 身份
- 私信白名单和路由边界更清晰
- 降低自我聊天混淆风险

最小化策略配置：

```json5
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
```

个人号码回退

引导配置支持个人号码模式，生成友好的基础配置：

- `dmPolicy: "allowlist"`
- `allowFrom` 包含你的个人号码
- `selfChatMode: true`

运行时自我聊天保护基于已关联的自身号码和 `allowFrom`。

仅 WhatsApp Web 渠道范围

当前 OpenClaw 渠道架构中，消息平台渠道基于 WhatsApp Web（Baileys）。内置渠道注册表中没有独立的 Twilio WhatsApp 消息渠道。

运行时模型

• Gateway 独占 WhatsApp socket 和重连循环。
• 重连看门狗基于 WhatsApp Web 传输活动，不仅监控入站消息量：安静的已关联设备会话不会仅因为最近无人发送消息而重启。即使传输帧持续到达，若应用消息在更长安全窗口内未处理，也会触发重连；对于最近活跃的会话，应用静默检查在首次恢复窗口使用正常消息超时。
• Baileys socket 超时在 web.whatsapp.* 下显式配置：keepAliveIntervalMs 控制 WhatsApp Web 应用心跳，connectTimeoutMs 控制握手超时，defaultQueryTimeoutMs 控制 Baileys 查询超时。
• 出站发送需要目标账号有活跃的 WhatsApp 监听器。
• 群组发送时，文本和媒体说明中的 @+<digits> 和 @<digits> 标记若匹配当前 WhatsApp 参与者元数据（包括 LID 支持的群组），会自动附加原生提及元数据。
• 状态和广播聊天被忽略（@status、@broadcast）。
• 私信使用私信会话规则（session.dmScope；默认 main 将私信折叠到 Agent 主会话）。
• 群组会话独立隔离（agent:<agentId>:whatsapp:group:&lt;jid&gt;）。
• WhatsApp Channels/Newsletters 可以显式出站目标，使用原生 @newsletter JID。出站 newsletter 发送使用渠道会话元数据（agent:<agentId>:whatsapp:channel:&lt;jid&gt;），而非私信会话语义。
• WhatsApp Web 传输支持网关主机上的标准代理环境变量（HTTPS_PROXY、HTTP_PROXY、NO_PROXY / 小写变体）。优先使用主机级代理配置，而非渠道特定的 WhatsApp 代理设置。
• 当 messages.removeAckAfterReply 启用时，OpenClaw 在可见回复投递后清除 WhatsApp ack 反应。

插件钩子与隐私

WhatsApp 入站消息包含个人消息内容、电话号码、群组标识、发送者名称和会话关联字段。因此，除非显式同意，WhatsApp 不会向插件广播入站 message_received 钩子负载：

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

可限定到某个账号：

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

仅对可信任接收 WhatsApp 入站消息内容和标识的插件启用此选项。

访问控制与激活

私信策略

`channels.whatsapp.dmPolicy` 控制私信访问：

- `pairing`（默认）
- `allowlist`
- `open`（`allowFrom` 需包含 `"*"`）
- `disabled`

`allowFrom` 接受 E.164 格式号码（内部标准化处理）。

`allowFrom` 是私信发送者访问控制列表，不影响对 WhatsApp 群组 JID 或 `@newsletter` 频道 JID 的显式出站发送。

多账号覆盖：`channels.whatsapp.accounts.<id>.dmPolicy`（和 `allowFrom`）优先于该账号的渠道级默认值。

运行时行为细节：

- 配对记录在渠道允许存储中持久化，并与配置的 `allowFrom` 合并
- 定时自动化和心跳接收方回退使用显式投递目标或配置的 `allowFrom`；私信配对批准不隐式成为 cron 或心跳接收方
- 如未配置白名单，已关联的自身号码默认被允许
- OpenClaw 永远不会自动配对出站 `fromMe` 私信（从已关联设备发送给自己的消息）

群组策略与白名单

群组访问有两个层次：

1. **群组成员白名单**（`channels.whatsapp.groups`）
   - 省略 `groups` 时所有群组均可使用
   - 存在 `groups` 时作为群组白名单（允许 `"*"`）

2. **群组发送方策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）
   - `open`：绕过发送方白名单
   - `allowlist`：发送方须匹配 `groupAllowFrom`（或 `*`）
   - `disabled`：屏蔽所有群组入站

发送方白名单回退：

- 未设置 `groupAllowFrom` 时回退到 `allowFrom`（如可用）
- 发送方白名单在提及/回复激活之前评估

注意：如果完全没有 `channels.whatsapp` 块，运行时群组策略回退为 `allowlist`（并记录警告），即使设置了 `channels.defaults.groupPolicy`。

提及与激活命令

群组回复默认需要提及。提及检测包括：

- 显式 WhatsApp 提及机器人身份
- 配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退 `messages.groupChat.mentionPatterns`）
- 入站语音转录（对授权群组消息）
- 隐式回复机器人检测（回复发送方与机器人身份匹配）

安全说明：

- 引用/回复仅满足提及门控，**不**授予发送方授权
- 在 `groupPolicy: "allowlist"` 下，非白名单发送方即使回复白名单用户消息也会被拦截

会话级激活命令：

- `/activation mention`
- `/activation always`

`activation` 只更新会话状态（不是全局配置），且受 Owner 门控。

个人号码与自我聊天行为

当已关联的自身号码也出现在 allowFrom 中时，WhatsApp 自我聊天保护激活：

• 跳过自我聊天轮次的已读回执
• 忽略可能触发自我提及的提及 JID 自动触发行为
• 如果 messages.responsePrefix 未设置，自我聊天回复默认使用 [{identity.name}] 或 [openclaw]

消息规范化与上下文

入站信封与引用上下文

入站 WhatsApp 消息包裹在共享入站信封中。如果存在引用回复，上下文以以下格式附加：

```text
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
```

回复元数据字段也会在可用时填充（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。当引用目标为可下载媒体时，OpenClaw 通过常规入站媒体存储保存并通过 `MediaPath`/`MediaType` 暴露，使 Agent 能检查引用的图片而非仅看到 `<media:image>`。

媒体占位符与位置/联系人提取

仅媒体的入站消息使用以下占位符：

- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`

授权群组语音笔记在提及门控前进行转录（当正文仅 `<media:audio>` 时），因此语音笔记中说出的机器人提及可以触发回复。如果转录仍不包含机器人提及，则保留在待处理群组历史中而非原始占位符。

位置正文使用简洁坐标文本。位置标签/评论和联系人/vCard 详情渲染为围栏不可信元数据，而非内联提示文本。

群组待处理历史注入

对于群组，未处理的消息可以缓冲并在机器人被触发时作为上下文注入：

- 默认限制：`50`
- 配置：`channels.whatsapp.historyLimit`
- 回退：`messages.groupChat.historyLimit`
- `0` 禁用

注入标记：

- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`

已读回执

对已接受的入站 WhatsApp 消息默认启用已读回执。

全局禁用：

```json5
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
```

按账号覆盖：

```json5
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
```

自我聊天轮次即使全局启用也会跳过已读回执。

投递、分块与媒体

文本分块

- 默认分块限制：`channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- `newline` 模式优先按段落边界（空行）分割，长段落再按长度分割

出站媒体行为

- 支持图片、视频、音频（PTT 语音消息）和文档负载
- 音频媒体通过 Baileys `audio` 负载发送，`ptt: true`，使 WhatsApp 客户端渲染为 push-to-talk 语音消息
- 回复负载保留 `audioAsVoice`；TTS 语音输出对 WhatsApp 保持此 PTT 路径，即使提供方返回 MP3 或 WebM
- 原生 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 动画播放
- `forceDocument` / `asDocument` 将出站图片、GIF 和视频通过 Baileys 文档负载发送，绕过 WhatsApp 媒体压缩，同时保留文件名和 MIME 类型
- 发送多媒体回复负载时，说明应用于第一个媒体项，但 PTT 语音消息先发送音频再单独发送可见文本，因为 WhatsApp 客户端对语音消息说明渲染不一致
- 媒体来源可以是 HTTP(S)、`file://` 或本地路径

媒体大小限制与回退行为

- 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
- 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
- 按账号覆盖使用 `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- 图片自动优化（调整大小/质量扫描）以符合限制，除非 `forceDocument` / `asDocument` 请求文档投递
- 媒体发送失败时，第一项回退为文本警告而非静默丢弃回复

回复引用

WhatsApp 支持原生回复引用，出站回复能可见地引用入站消息。通过 channels.whatsapp.replyToMode 控制。

值	行为
"off"	从不引用，作为纯文本发送
"first"	仅引用第一个出站回复块
"all"	引用所有出站回复块
"batched"	引用排队的批量回复，但立即回复不引用

默认值："off"。按账号覆盖使用 channels.whatsapp.accounts.<id>.replyToMode。

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

反应级别

channels.whatsapp.reactionLevel 控制 Agent 在 WhatsApp 上使用表情反应的广度：

级别	确认反应	Agent 自发反应	描述
"off"	否	否	无反应
"ack"	是	否	仅确认反应（回复前的回执）
"minimal"	是	是（保守）	确认 + Agent 反应，保守指导
"extensive"	是	是（鼓励）	确认 + Agent 反应，鼓励指导

默认值："minimal"。

按账号覆盖使用 channels.whatsapp.accounts.<id>.reactionLevel。

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

确认反应

WhatsApp 支持在接收入站消息时立即通过 channels.whatsapp.ackReaction 发送确认反应。确认反应受 reactionLevel 控制——reactionLevel 为 "off" 时抑制。

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

行为说明：

• 在接受入站消息后立即发送（回复前）
• 失败会记录日志但不阻断正常回复投递
• 群组模式 mentions 在提及触发的轮次中反应；群组激活 always 会绕过此检查
• WhatsApp 使用 channels.whatsapp.ackReaction（旧版 messages.ackReaction 在此不适用）

生命周期状态反应

设置 messages.statusReactions.enabled: true 让 WhatsApp 在轮次中用状态反应替换确认反应，而不是保留静态回执表情。启用后，OpenClaw 使用同一入站消息反应槽位来表示排队、思考、工具活动、压缩、完成和错误等生命周期状态。

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

行为说明：

• channels.whatsapp.ackReaction 仍然控制状态反应是否适用于私信和群组。
• WhatsApp 每条消息只有一个机器人反应槽位，因此生命周期更新会替换当前反应。
• messages.removeAckAfterReply: true 在配置的完成/错误保持后清除最终状态反应。
• 工具表情类别包括 tool、coding、web、deploy、build 和 concierge。

多账号与凭证

账号选择与默认值

- 账号 ID 来自 `channels.whatsapp.accounts`
- 默认账号选择：存在 `default` 时优先使用，否则取第一个已配置的账号 ID（排序后）
- 账号 ID 内部标准化用于查找

凭证路径与旧版兼容

- 当前认证路径：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- 备份文件：`creds.json.bak`
- 旧版默认认证在 `~/.openclaw/credentials/` 中仍然识别并迁移到默认账号流程

登出行为

`openclaw channels logout --channel whatsapp [--account <id>]` 清除该账号的 WhatsApp 认证状态。

当 Gateway 可达时，登出会先停止所选账号的活跃 WhatsApp 监听器，以避免已关联的会话持续接收消息直到下次重启。`openclaw channels remove --channel whatsapp` 也会在禁用或删除账号配置前停止活跃监听器。

在旧版认证目录中，`oauth.json` 保留，Baileys 认证文件被删除。

工具、动作与配置写入

• Agent 工具支持包括 WhatsApp 反应动作（react）。
• 动作开关：
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 渠道发起的配置写入默认启用（通过 channels.whatsapp.configWrites=false 禁用）。

故障排查

未关联（需要扫码）

症状：渠道状态报告未关联。

修复：

```bash
openclaw channels login --channel whatsapp
openclaw channels status
```

已关联但断连/重连循环

症状：已关联的账号反复断连或重连尝试。

安静账号可以在正常消息超时后仍保持连接；看门狗在 WhatsApp Web 传输活动停止、socket 关闭或应用消息静默超过较长安全窗口时重启。

如果日志显示重复的 `status=408 Request Time-out Connection was lost`，调整 `web.whatsapp` 下的 Baileys socket 超时。首先缩短 `keepAliveIntervalMs` 低于网络空闲超时，增加 `connectTimeoutMs`（慢速或有损链路）：

```json5
{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}
```

修复：

```bash
openclaw doctor
openclaw logs --follow
```

如果 `~/.openclaw/logs/whatsapp-health.log` 显示 `Gateway inactive` 但 `openclaw gateway status` 和 `openclaw channels status --probe` 显示网关和 WhatsApp 健康，运行 `openclaw doctor`。在 Linux 上，doctor 会警告旧版 crontab 条目仍调用 `~/.openclaw/bin/ensure-whatsapp.sh`；通过 `crontab -e` 删除这些条目，因为 cron 可能缺少 systemd user-bus 环境导致该脚本错误报告网关健康。

如果需要，使用 `channels login` 重新关联。

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`。

发送时无活跃监听器

出站发送在目标账号无活跃网关监听器时快速失败。

确保网关正在运行且账号已关联。

回复出现在日志但不在 WhatsApp 中

日志记录 Agent 生成的内容。WhatsApp 投递需单独检查：OpenClaw 仅在 Baileys 返回至少一个可见文本或媒体发送的出站消息 ID 后才视为自动回复已发送。

确认反应是独立的回复前回执。成功的反应不证明后续文本或媒体回复已被 WhatsApp 接受。

检查网关日志中的 `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` 下的发送者授权。

Bun 运行时警告

WhatsApp 网关运行时应使用 Node。Bun 被标记为不兼容，不适用于稳定的 WhatsApp/Telegram 网关运营。

系统提示

WhatsApp 支持通过 groups 和 direct 映射为群组和私信设置系统提示，类似 Telegram。

群组消息的分辨层次：

先确定生效的 groups 映射：如果账号定义了自身的 groups，则完全替换根 groups 映射（不深度合并）。然后在结果映射上执行提示查找：

1. 群组特定系统提示（groups["<groupId>"].systemPrompt）：当该群组条目存在于映射中且其 systemPrompt 键已定义时使用。如果 systemPrompt 为空字符串（""），则抑制通配符，不应用系统提示。
2. 群组通配符系统提示（groups["*"].systemPrompt）：当映射中完全不存在该群组条目时使用，或条目存在但未定义 systemPrompt 键。

私信的分辨层次：

先确定生效的 direct 映射：如果账号定义了自身的 direct，则完全替换根 direct 映射（不深度合并）。然后在结果映射上执行提示查找：

1. 私信特定系统提示（direct["<peerId>"].systemPrompt）：当该对等条目存在于映射中且其 systemPrompt 键已定义时使用。如果 systemPrompt 为空字符串（""），则抑制通配符，不应用系统提示。
2. 私信通配符系统提示（direct["*"].systemPrompt）：当映射中完全不存在该对等条目时使用，或条目存在但未定义 systemPrompt 键。

INFO

dms 仍然是轻量级的按私信历史覆写桶（dms.<id>.historyLimit）。提示覆写位于 direct 下。

与 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: "所有群组的默认提示。" },
      },
      direct: {
        // 适用于所有未定义自身 direct 映射的账号。
        "*": { systemPrompt: "所有私信的默认提示。" },
      },
      accounts: {
        work: {
          groups: {
            // 该账号定义了自身的 groups，因此根 groups 被完全替换。
            // 若要保留通配符，在此显式定义 "*"。
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "专注于项目管理。",
            },
            // 仅当该账号应准入所有群组时使用。
            "*": { systemPrompt: "工作群组的默认提示。" },
          },
          direct: {
            // 该账号定义了自身的 direct，因此根 direct 条目被完全替换。
            // 若要保留通配符，在此显式定义 "*"。
            "+15551234567": { systemPrompt: "特定工作私信的提示。" },
            "*": { systemPrompt: "工作私信的默认提示。" },
          },
        },
      },
    },
  },
}

配置参考指针

主要参考：

• 配置参考 - 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

相关链接

• 配对机制
• 群组
• 安全
• 频道路由
• 多 Agent 路由
• 故障排查

常见问题

为什么 WhatsApp 关联后总是断连重连？

检查日志中是否有 status=408 Request Time-out。尝试调优 web.whatsapp.keepAliveIntervalMs 和 connectTimeoutMs。运行 openclaw doctor 诊断网关健康，并验证连接无代理冲突。在 Linux 上确保清理旧版 crontab 条目。

群组消息收不到怎么办？

按顺序检查：groupPolicy 是否为 disabled，groupAllowFrom 或 allowFrom 是否包含发送者，groups 白名单是否包含该群组 JID，提及门控是否配置正确。注意 JSON5 中重复键会覆盖先前值。若 channels.whatsapp 块缺失，群组策略默认回退为 allowlist（并有警告日志）。

QR 扫码登录超时或失败？

确认网关运行的终端继承了 HTTPS_PROXY / HTTP_PROXY 环境变量，且 NO_PROXY 未排除 mmg.whatsapp.net。使用较长的 connectTimeoutMs（如 60000）处理慢速或代理链路。