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 去重生存期限制；初始启动仍保留较短的陈旧历史记录保护。
• Baileys 套接字计时在 web.whatsapp.* 下明确定义：keepAliveIntervalMs（应用 ping 间隔）、connectTimeoutMs（打开握手超时）、defaultQueryTimeoutMs（Baileys 查询等待时间，以及 OpenClaw 的出站发送/在线状态和入站已读回执超时）。
• 出站发送要求目标账户具有活动的 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 及其小写变体）。相较于每渠道设置，优先使用主机级代理配置。
• 启用 messages.removeAckAfterReply 后，OpenClaw 会在可见回复送达后清除确认表情回应。

使用 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 发送者授权路径。

插件钩子和隐私

入站 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 自动触发行为，并在未设置 messages.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,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

注意：channels.whatsapp.ackReaction 仍控制私信和群组的适用条件；排队状态使用与普通确认表情回应相同的有效表情符号；WhatsApp 对每条消息只有一个 Bot 表情回应槽位，因此生命周期更新会原位替换当前表情回应；messages.removeAckAfterReply: true 会在配置的完成/错误保留时间结束后清除最终状态表情回应；工具表情符号类别包括 tool、coding、web、deploy、build 和 concierge。

多账户和凭据

工具、操作和配置写入

• 智能体工具支持包括 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

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

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

相关内容

• 配对
• 群组
• 安全性
• 渠道路由
• 多智能体路由
• 故障排查