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）用于注册表回退；只有在需要可复现安装时才固定到确切版本。

• 配对：对于未知发送者，默认私信策略为配对。
• 渠道故障排除：跨渠道诊断和修复操作手册。
• Gateway 配置：完整的渠道配置模式和示例。

快速设置

配置访问策略

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

关联 WhatsApp（二维码）

openclaw channels login --channel whatsapp

登录仅支持二维码。在远程或无头主机上，开始登录前应确保有可靠的方式将实时二维码传送到手机；终端渲染的二维码、屏幕截图或聊天附件可能在传输过程中失效。

对于特定账户：

openclaw channels login --channel whatsapp --account work

要在登录前关联现有/自定义身份验证目录：

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

启动 Gateway 网关

openclaw gateway

批准第一个私信访问请求（配对模式）

打开 **Settings → Channels → DM access requests**，找到 WhatsApp 账户，
然后批准发送者。如果更喜欢使用 CLI：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

私信访问请求会在 1 小时后过期；每个账户最多可有 3 个待处理请求。
此批准与用于关联账户本身的 WhatsApp 登录二维码相互独立。

部署模式

{
  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 消息。该工具没有目标号码参数，因此提示词无法将通话重定向到其他号码。默认禁用。

启用实验性通话

将 `actions.calls: true` 添加到 WhatsApp 渠道配置中，然后重启 Gateway 网关：

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

如果缺少该项或其值为 `false`，OpenClaw 不会公开 `whatsapp_call` 工具。

安装经过审查的 MeowCaller CLI

适配器要求 Gateway 网关主机的 `PATH` 中存在 `meowcaller` 可执行文件。在 [MeowCaller PR #7](https://github.com/purpshell/meowcaller/pull/7) 合并之前，请构建经过审查的分支：

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

确保 `$HOME/.local/bin` 位于 Gateway 网关服务的 `PATH` 中。此修订版提供明确的 `pair` 和仅发送的 `notify` 命令；`notify` 不会打开麦克风、扬声器、视频设备或诊断捕获。请勿改用上游示例 CLI 的 `play` 命令。

配对 MeowCaller 已关联设备

要求 WhatsApp 智能体检查通话设置（`whatsapp_call` 状态操作会报告账户专属状态目录和配对命令）。对于默认账户：

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

以交互方式运行此命令，通过 **WhatsApp > Linked devices** 扫描二维码，并等待 `MeowCaller linked device ready`。请将 `wa-voip.db` 保密——它是 MeowCaller 会话。非默认账户会通过状态操作获得各自的存储路径；在 Windows 上，请运行其 PowerShell 命令。

配置 TTS 并从 WhatsApp 发起通话

配置支持电话通话的 TTS 提供商，重启 Gateway 网关，然后发送类似 Call me and say the build finished. 的请求。该工具从可信的入站上下文解析发送者，合成临时私有 WAV 文件，在有界的通话时间窗口内运行 MeowCaller，并在之后删除音频文件。OpenClaw 会明确传入账户的存储位置，在接听、播放和挂断后等待零退出状态，并将超时或非零退出视为工具调用失败。

限制：仅支持一对一出站音频通话、不支持任意目标号码、不与聊天连接共享身份验证、不支持在个人号码/与自己聊天模式下呼叫自身、合成音频最长为 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 内容和标识符的插件启用此功能。

访问控制和激活

私信策略

channels.whatsapp.dmPolicy：

allowFrom 接受 E.164 格式的号码（内部会进行规范化）。它仅是私信发送者访问控制列表，不会限制向群组 JID 或 @newsletter 渠道 JID 的显式出站发送。

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

运行时说明：

• 配对会持久化到渠道允许存储中，并与配置的 allowFrom 合并
• 定时自动化和 Heartbeat 收件人回退使用显式投递目标或配置的 allowFrom；私信配对批准不会隐式成为定时任务/Heartbeat 收件人
• 如果未配置允许列表，默认允许已关联的本机号码
• OpenClaw 绝不会自动配对出站 fromMe 私信（即你从已关联设备发送给自己的消息）

群组策略和允许列表

群组访问分为两层：

1. 群组成员资格允许列表（channels.whatsapp.groups）：如果省略 groups，则所有群组均符合条件；如果存在，它将充当群组允许列表（"*" 允许所有群组）。
2. 群组发送者策略（channels.whatsapp.groupPolicy + groupAllowFrom）：open 会绕过发送者允许列表，allowlist 要求匹配 groupAllowFrom（或 *），disabled 会阻止所有群组入站消息。

如果未设置 groupAllowFrom，当 allowFrom 包含条目时，发送者检查会回退到该配置。发送者允许列表的评估先于提及/回复激活。

如果完全不存在 channels.whatsapp 块，运行时会回退到 groupPolicy: "allowlist"（并记录警告日志），即使 channels.defaults.groupPolicy 设置为其他值也是如此。

提及和 /activation

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

• 在 WhatsApp 中显式提及 Bot 身份
• 配置的提及正则表达式模式（agents.entries.*.groupChat.mentionPatterns，回退到 messages.groupChat.mentionPatterns）
• 已获授权的群组消息中的入站语音留言转录文本
• 隐式的回复 Bot 检测（回复发送者与 Bot 身份匹配）

安全性：引用/回复仅满足提及门控要求，不会授予发送者权限。使用 groupPolicy: "allowlist" 时，不在允许列表中的发送者即使回复允许列表中用户的消息，也仍会被阻止。

会话级激活命令：/activation mention 或 /activation always。此命令更新会话状态（而非全局配置），且仅限所有者使用。

已配置的 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: "[email protected]" },
      },
    },
  ],
}

私聊匹配 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 whatsapp
openclaw channels status

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw 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 会被完全
            // 替换。若要保留通配符，也需要在此显式定义 "*"。
            "[email protected]": {
              requireMention: false,
              systemPrompt: "专注于项目管理。",
            },
            // 仅当此账户应允许所有群组时使用。
            "*": { systemPrompt: "工作群组的默认提示词。" },
          },
          direct: {
            // 此账户定义了自己的 direct 映射，因此根级 direct 条目会被
            // 完全替换。若要保留通配符，也需要在此显式定义 "*"。
            "+15551234567": { systemPrompt: "特定工作私聊的提示词。" },
            "*": { systemPrompt: "工作私聊的默认提示词。" },
          },
        },
      },
    },
  },
}

配置参考入口

主要参考：Configuration reference - WhatsApp

相关内容

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