WhatsApp

状态：已通过 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 包之外发布，因此其运行时依赖项随外部插件一起提供。手动安装：

openclaw plugins install clawhub:@openclaw/whatsapp

仅将纯 npm 包（@openclaw/whatsapp）用于注册表回退；只有在需要可复现安装时才固定到确切版本。

快速设置

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

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

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

部署模式

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

运行时模型

• Gateway 网关拥有 WhatsApp 套接字和重连循环。
• 看门狗独立跟踪两种信号：原始 WhatsApp Web 传输活动和应用消息活动。会话即使处于静默状态，只要仍保持连接，就不会仅因近期没有收到消息而重启；只有在传输帧持续一个固定的内部时间窗口未到达（用户不可配置），或应用消息的静默时间超过正常消息超时的 4 倍时，才会强制重连。对于最近处于活跃状态的会话，刚刚完成重连后的第一个时间窗口使用较短的正常消息超时，而不是 4 倍时间窗口。对于 Baileys 在该重连早期送达的离线消息，OpenClaw 可以自动回复，范围受入站消息 ID 去重生命周期限制；初始启动仍保留较短的陈旧历史记录防护。
• 出站发送要求目标账户具有活跃的 WhatsApp 监听器；否则发送会立即失败。
• 在群组发送中，当 @+<digits> 和 @<digits> 令牌（位于文本和媒体说明中）与当前参与者元数据匹配时，会附加原生提及元数据，包括由 LID 支持的群组。
• 状态和广播聊天（@status、@broadcast）会被忽略。
• 直接聊天使用私信会话规则（session.dmScope；默认的 main 会将私信合并到智能体主会话中）。群组会话按 JID 隔离（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Channels/Newsletters 可以通过其原生 @newsletter JID 明确指定为出站目标，并使用渠道会话元数据（agent:<agentId>:whatsapp:channel:<jid>），而不是私信语义。
• WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（HTTPS_PROXY、HTTP_PROXY、NO_PROXY 及其小写变体）。优先使用主机级代理配置，而不是每渠道设置。

使用 MeowCaller 呼叫当前请求者（实验性）

该插件可以在源自 WhatsApp 的智能体轮次中公开 whatsapp_call。它使用 MeowCaller 向当前已获授权的请求者发起 WhatsApp 语音通话，并在对方接听后播放 OpenClaw TTS 消息。该工具没有目标号码参数，因此提示词无法将通话重定向到其他号码。默认禁用。

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

限制：仅支持一对一出站音频通话、不支持任意目标号码、不与聊天连接共享身份验证、不支持在个人号码/与自己聊天模式下呼叫自身、合成音频最长为 60 秒、除 MeowCaller 完成接听/播放/挂断外不提供手机端可听性回执，并且 OpenClaw 会在有界的 115-175 秒时间窗口后停止伴随进程（涵盖 MeowCaller 的连接、接听、播放和关闭阶段）。

审批提示

WhatsApp 可以将 Exec 和插件审批提示呈现为 👍/👎 表情回应，由顶层审批转发配置控制：

{  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 发送者授权路径，然后才解析审批。

问题表情回应

对于包含一个非敏感单选问题和一至四个选项的 ask_user 提示，WhatsApp 会在选项标签旁显示从 1️⃣ 到 4️⃣。使用匹配的数字对已送达的提示作出表情回应即可回答。OpenClaw 通过 Gateway 网关将数字映射到规范选项；过期或重复的点击会被忽略。多问题、多选和自由文本提示仍只能通过文本回复。正常的 WhatsApp 私信/群组准入规则会对作出表情回应的发送者进行授权。

插件钩子和隐私

入站 WhatsApp 消息可能包含个人内容、电话号码、群组标识符、发送者姓名和会话关联字段。除非你选择启用，否则 WhatsApp 不会向插件广播入站 message_received 钩子载荷：

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

请在 channels.whatsapp.accounts.<id>.pluginHooks.messageReceived 下将选择启用的范围限定为一个账户。仅对你信任其可访问入站 WhatsApp 内容和标识符的插件启用此功能。

访问控制和激活

已配置的 ACP 绑定

WhatsApp 通过顶层 bindings[] 支持持久化 ACP 绑定：

{  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 自动触发行为；并且当渠道/账户的 responsePrefix 未设置时，默认将回复发送到 [{identity.name}]（或 [openclaw]）。

消息规范化和上下文

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

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

发送、分块和媒体

回复引用

channels.whatsapp.replyToMode 控制原生回复引用（出站回复会明显引用入站消息）：

每账户覆盖：channels.whatsapp.accounts.<id>.replyToMode。

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

表情回应级别

channels.whatsapp.reactionLevel 控制智能体使用表情符号回应的范围：

每账户覆盖：channels.whatsapp.accounts.<id>.reactionLevel。

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

确认回应

channels.whatsapp.ackReaction 会在收到入站消息后立即发送回应，该行为受 reactionLevel 限制（当 "off" 时会被抑制）：

{  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 会在轮次期间替换确认回应，而不是一直保留静态的已接收表情符号，并依次显示已排队、思考中、工具活动、压缩、完成和错误等状态：

{  messages: {    statusReactions: {      enabled: true,    },  },}

注意：channels.whatsapp.ackReaction 仍控制私信和群组的适用条件；已排队状态使用与普通确认回应相同的有效表情符号；对于每条消息，WhatsApp 只有一个 Bot 回应槽位，因此生命周期更新会就地替换当前回应，并在最终的完成/错误状态后恢复确认回应。

多账户和凭据

工具、操作和配置写入

• Agent 工具支持包括 WhatsApp 表情回应操作（react）。
• 操作开关：channels.whatsapp.actions.reactions、channels.whatsapp.actions.polls（现有操作默认为 true）、channels.whatsapp.actions.calls（默认值为 false，参见上文的 MeowCaller）。
• 默认启用由渠道发起的配置写入；可通过 channels.whatsapp.configWrites: false 禁用。

故障排查

openclaw channels login --channel whatsappopenclaw channels status

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

系统提示词

WhatsApp 通过 groups 和 direct 映射，为群组和私聊支持 Telegram 风格的系统提示词。

群组消息的解析方式：首先确定有效的 groups 映射——只要账户定义了自己的 groups 键，它就会完全替换根级 groups 映射（不会深度合并）。随后，提示词查找仅在这个最终映射上进行：

1. 群组专属提示词（groups["<groupId>"].systemPrompt）：当群组条目存在，并且其 systemPrompt 键已定义时使用。空字符串（""）会阻止使用通配符且不应用任何提示词。
2. 群组通配符提示词（groups["*"].systemPrompt）：当特定群组条目不存在，或存在但没有 systemPrompt 键时使用。

私信的解析方式与此完全相同，但使用的是 direct 映射和 direct["*"]。

**与 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 或配对存储规则获准后，提供默认配置。

示例：

{  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

相关内容

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