WhatsApp（Web 渠道）

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

安装

首次通过 openclaw onboard 或 openclaw channels add --channel whatsapp 选择该渠道时，会提示安装 WhatsApp 插件。
openclaw channels login --channel whatsapp 在插件未安装时也会提供安装流程。
开发渠道 + git checkout：默认使用本地插件路径。
Stable/Beta：默认使用 npm 包 @openclaw/whatsapp。

手动安装也同样支持：

bash

openclaw plugins install @openclaw/whatsapp

快速配置

第一步：配置 WhatsApp 访问策略

json5

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

第二步：扫码关联 WhatsApp

bash

openclaw channels login --channel whatsapp

指定账号：

bash

openclaw channels login --channel whatsapp --account work

第三步：启动 Gateway

bash

openclaw gateway

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

bash

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

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

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

部署模式

独立号码（推荐）： 这是最简洁的运营模式——OpenClaw 有独立的 WhatsApp 身份，私信白名单和路由边界更清晰，减少自发消息混淆。

json5

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

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

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

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

运行时模型

Gateway 独占 WhatsApp socket 和重连循环。
出站发送需要目标账号有活跃的 WhatsApp 监听器。
状态和广播聊天被忽略（@status、@broadcast）。
私信使用私信会话规则（session.dmScope；默认 main 将私信折叠到 Agent 主会话）。
群组会话独立隔离（agent:<agentId>:whatsapp:group:<jid>）。

访问控制与激活

私信策略

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

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

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

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

运行时行为细节：

配对记录在渠道允许存储中持久化，并与配置的 allowFrom 合并
如未配置白名单，已关联的自身号码默认被允许
fromMe 出站私信不会自动配对

群组策略与白名单

群组访问有两个层次：

群组成员白名单（channels.whatsapp.groups）
- 省略 groups 时所有群组均可使用
- 存在 groups 时作为群组白名单（允许 "*"）
群组发送方策略（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]

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

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

位置和联系人负载在路由前规范化为文本上下文。

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

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

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

禁用：

json5

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

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

投递、分块与媒体

文本分块：

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

出站媒体：

支持图片、视频、音频（PTT 语音消息）和文档负载
audio/ogg 重写为 audio/ogg; codecs=opus 以兼容语音消息
通过 gifPlayback: true 支持 GIF 动画播放
发送多媒体回复负载时，字幕应用于第一个媒体项
媒体来源可以是 HTTP(S)、file:// 或本地路径

媒体大小限制与回退：

入站媒体保存上限：channels.whatsapp.mediaMaxMb（默认 50）
图片自动优化（调整大小/质量）以符合限制
媒体发送失败时，第一项回退为文本警告而非静默丢弃回复

确认反应（Ack Reaction）

WhatsApp 支持在接收入站消息时立即通过 channels.whatsapp.ackReaction 发送确认反应。

json5

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

行为说明：

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

多账号与凭证

账号 ID 来自 channels.whatsapp.accounts
默认账号选择：存在 default 时优先使用，否则取第一个已配置的账号 ID（排序后）
当前认证路径：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
openclaw channels logout --channel whatsapp [--account <id>] 清除该账号的 WhatsApp 认证状态

工具、动作与配置写入

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

故障排查

未关联（需要扫码）：

bash

openclaw channels login --channel whatsapp
openclaw channels status

已关联但断连/重连循环：

bash

openclaw doctor
openclaw logs --follow

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

发送时无活跃监听器： 确保 Gateway 正在运行且账号已关联。

群组消息意外被忽略： 按以下顺序检查：

groupPolicy
groupAllowFrom / allowFrom
groups 白名单条目
提及门控（requireMention + 提及模式）
openclaw.json 中的重复键（JSON5）：后面的条目覆盖前面的，每个作用域只保留一个 groupPolicy

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

WhatsApp（Web 渠道） ​

安装 ​

快速配置 ​

部署模式 ​

运行时模型 ​

访问控制与激活 ​

私信策略 ​

群组策略与白名单 ​

提及与激活命令 ​

个人号码与自我聊天行为 ​

消息规范化与上下文 ​

投递、分块与媒体 ​

确认反应（Ack Reaction） ​

多账号与凭证 ​

工具、动作与配置写入 ​

故障排查 ​

相关链接 ​

WhatsApp（Web 渠道）

安装

快速配置

部署模式

运行时模型

访问控制与激活

私信策略

群组策略与白名单

提及与激活命令

个人号码与自我聊天行为

消息规范化与上下文

投递、分块与媒体

确认反应（Ack Reaction）

多账号与凭证

工具、动作与配置写入

故障排查

相关链接