WhatsApp

ZeroClaw 在同一 channels.whatsapp 配置族下支持两种 WhatsApp 后端：

除非你有意让 Cloud API 模式胜出以实现向后兼容，否则请勿在同一通道中同时配置两个选择器。

谁可以与代理通信

入站发送方会根据为绑定代理解析出的对等集合进行限制，该集合来自代理所属的 peer_groups 配置。匹配时会去除开头的 @，并对通道的原生发送方标识符执行不区分大小写的比对。空集合会拒绝所有人；包含 "*" 的集合会接受所有人；否则仅接受列出的外部对等方（以及对等代理）。这与网关配对（gateway.require_pairing）不同，后者验证的是 HTTP/WebSocket 客户端，而非聊天通道的发送方。

whatsapp 的对等组将 channel 设置为 whatsapp，在 external_peers 中列出允许的发送者（对于 whatsapp，即电话标识符（Cloud API）或 JID 用户部分（Web 模式）；["*"] 接受任何人），可选地在 agents 中命名对等代理以实现跨代理分派、ignore 屏蔽列表，以及 output_modality（mirror、voice 或 text）。字段参考请参见 Peer Groups。

在何处设置：

云端 API 模式

Cloud API 模式是 Meta Business Platform 集成。它需要 Meta Business 账户、WhatsApp Business 应用、电话号码 ID、验证令牌、访问令牌和应用密钥。对于通过 Meta webhook 接收消息的业务部署，这是正确的模式。

入站 webhook 会根据 app_secret 进行签名验证，且验证是强制性的。未配置应用密钥时，网关无法验证请求，因此会返回 401，不会处理任何内容。在将 Meta 指向回调 URL 之前，请先设置 app_secret。

网关必须能够被 Meta 访问以接收入站 webhook。请在顶层 [tunnel] 部分下配置隧道（tunnel_provider 及相关的 provider 配置块，参见配置参考），或者在本地开发时使用你自己的反向代理来代理网关。

将 Meta 的回调 URL 指向应接收该回调的 [channels.whatsapp.<alias>] 实例的别名：GET/POST https://<your-public-url>/whatsapp/<alias>（例如 [channels.whatsapp.work] → /whatsapp/work）。这种按别名路由的方式（#6312）允许多个 WhatsApp 号码并行运行。裸 /whatsapp 路径仍然可用，但已弃用：它会解析为按字典序排在首位的别名（重启后保持确定性），并设置 X-Zeroclaw-Deprecation 响应头。未知别名将返回 404。单实例部署无需更改。

网页模式

WhatsApp Web 模式通过可选的 Web 后端关联普通 WhatsApp 账户。它不需要 Meta Business 账户，但需要启用了 whatsapp-web 特性的 ZeroClaw 构建版本以及一个持久化的会话数据库路径。

首次启动时，Web 后端会使用二维码或配对码链接来配对账户（设置 pair_phone 可启用配对码链接；不设置则使用二维码）。请将 session_path 保存在持久化存储中；删除它会强制重新进行设备链接。通过相应智能体的 channels 列表，将该通道绑定到该智能体。

push_name 用于设置收件人看到的显示名称；不设置时，账户会保留手机注册时使用的名称。它会在连接时应用，但仅当该名称与已关联设备已有的名称不同时才会应用；应用失败会记录日志，但不会停止通道。Cloud API 模式会忽略此设置；在该模式下，显示名称来自 Meta Business 个人资料。

共享的 interrupt_on_new_message 选项同时适用于 Cloud API 模式和 Web 模式。启用后，来自同一发送者/聊天的较新 WhatsApp 消息会取消正在处理中的响应。

个人和企业行为

对于 Web 模式，dm_policy 和 group_policy 在两种模式下都适用。self_chat_mode 仅适用于个人：

self_chat_mode 仍仅限个人使用，因为自聊入口按设计限定在个人分支中。mode 选择的是 ZeroClaw 的策略模式，而不是 WhatsApp 账户类型：两种模式使用同一个已关联设备会话。

fromMe 防护同样保留在个人分支中，但这并不是因为业务模式缺少等价机制。业务模式仍然是 WhatsApp Web 的关联设备会话，而在两种模式下，WhatsApp 都会将操作员自己发出的消息以 fromMe 标记同步到关联设备。关联账户会作为已授权对端持久化保存，因此在业务模式下，这种同步消息可能满足允许列表并进入分发流程，这正是 #6353 针对个人模式修复的问题类型。该行为早于此次更改，并非由此引入；这里将其明确指出，而不是武断地否认其存在，修复工作另行跟踪。

mode = "business" 兼容性说明

业务模式此前接受 dm_policy 和 group_policy，但之后从未参考这两个键中的任何一个，因此，策略显示为限制性的频道会回复其收到的每条消息。现在，这两个键在业务模式下都会得到强制执行。

dm_policy 默认为 allowlist，因此依赖之前宽松行为的业务模式部署必须选择以下之一：

• 继续回复所有人 - 显式设置 dm_policy = "all" 和 group_policy = "all"。
• 保留限制 - 保持默认设置，并确保你打算服务的发送方可通过通道的对等组访问，使用 [peer_groups.<name>].external_peers。

不要等 config validate 来告诉你这一点。在 mode = "business" 下，它会将 self_chat_mode 报告为不生效，并且不会提及 dm_policy 或 group_policy，恰恰是因为这两个现在已经生效而非不生效。因此，真正对你而言行为发生变化的键，正是验证器不会提及的那些。升级前请阅读本节；这是业务模式部署获得的唯一通知。

passive_group_context = true 为可选启用，仅适用于 WhatsApp Web 群聊。允许的未直接点名群消息会存储在房间作用域的会话历史中，不会触发智能体回合、发送反应、下载媒体或调用模型。之后在同一群组中被点名的消息可以使用该被动上下文。

限制哪些组 (allowed_groups)

allowed_groups（Web 模式）根据 JID 将机器人限定在一组指定的群聊中。它独立于 mode——无论是业务模式还是个人模式都适用，并且在聊天类型策略之前运行。空列表不表示授权：其含义由 group_policy 决定。在 allowlist（默认值）或 ignore 下，空列表不允许任何群组；在 all 下，空列表允许所有群组。允许所有群组的列表无法与未配置任何列表区分，因此必须明确请求开放群组访问。非空列表会丢弃聊天 JID 与任何条目都不匹配的所有群消息，并且在包括 all 在内的所有策略下都如此，因此 all 是放宽空列表的默认行为，而不是覆盖显式列表。直接消息始终绕过此过滤器。

每个条目都匹配完整的 group JID (123456789012345@g.us) 或 JID 用户部分——即 @ 之前的片段 (123456789012345)——并且是精确比较，而不是字符串前缀比较（因此 123 允许 123@g.us，但绝不会允许 123999@g.us）。这用于控制群组_身份_，而 group_policy（聊天类型）和发送者允许列表（sender）并不控制这一点。

[channels.whatsapp.myaccount]
enabled = true
session_path = "/var/lib/zeroclaw/wa.db"
# 仅在这两个群组中操作；所有其他群组都将被忽略。
allowed_groups = ["120363012345678901@g.us", "120363098765432109"]

通过聊天进行工具审批 (approval_timeout_secs)

当工具需要批准（位于 always_ask 中，或风险配置文件不会自动批准它）时，代理会将请求发送到消息来源的聊天中，并等待回复。使用提示中的令牌回答：

a1b2c3 yes
a1b2c3 no
a1b2c3 always

approval_timeout_secs 限制该等待时间。默认值为 300 秒，而 0 会立即拒绝，而不是禁用审批，因此设为零意味着拒绝每个需要审批的工具调用，而不是无限期等待。超时后，请求会被拒绝且令牌会被丢弃，因此延迟到达的回复无法批准任何已经没有人等待的调用。

谁可以回答。 该令牌是关联标识符，而不是密码：它会以明文发送到聊天中，因此在群组中每位成员都能读取它。

这两种模式有所不同，而这种差异是安全边界，而非实现细节。

在 Web 模式下，只有当回复来自发布提示的同一聊天，并且来自此别名获授权接受其指令的对端时，才会被采纳。未通过任一检查的回复都会被记录并忽略，请求仍会保持打开状态，以便操作员仍可回答。在群聊中，提示会说明这一点，因为否则无法判断旁观者的回复为何没有产生作用。

已授权的对等方是规范解析器为此别名返回的对等方，也就是其 channel 指向该别名的对等方组：

[peer_groups.whatsapp_default]
channel = "whatsapp.personal"   # this alias only; bare "whatsapp" covers every alias
external_peers = ["+15550100"]

没有可设置的 allowed_numbers 字段。那是 v2 中的写法，迁移会将其合并到类似上面的对等组中，因此 v2 配置仍可继续使用，而 v3 配置没有地方放置旧键。

请参阅对等组，了解完整的字段列表，以及每个通道用于匹配的标识符格式。

在 Cloud API 模式下，这两项检查都不会应用。其待处理条目只是一个以令牌为键的裸响应者，其中没有同时记录聊天会话或身份信息，因此 webhook 将持有令牌视为授权。在群组中，这意味着任何能读到提示的成员都可以回答，包括从不同的聊天会话中回答。在该路径得到加固之前，Cloud 模式下的批准只能证明有人持有过令牌，除此之外别无他物。它既不会验证聊天会话，也不会验证响应者的身份，因此只要聊天会话或响应者身份有任何一项重要，就应优先使用 Web 模式。

配置界面

zeroclaw config set channels.whatsapp.<alias>.access_token    # 掩码输入，加密存储

export ZEROCLAW_channels__whatsapp__<alias>__access_token=

zeroclaw config set channels.whatsapp.<alias>.allowed_groups <value>

export ZEROCLAW_channels__whatsapp__<alias>__allowed_groups=

zeroclaw config set channels.whatsapp.<alias>.app_secret    # 掩码输入，加密存储

export ZEROCLAW_channels__whatsapp__<alias>__app_secret=

zeroclaw config set channels.whatsapp.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__whatsapp__<alias>__approval_timeout_secs=

zeroclaw config set channels.whatsapp.<alias>.dm_mention_patterns <value>

export ZEROCLAW_channels__whatsapp__<alias>__dm_mention_patterns=

zeroclaw config set channels.whatsapp.<alias>.dm_policy <value>

export ZEROCLAW_channels__whatsapp__<alias>__dm_policy=

zeroclaw config set channels.whatsapp.<alias>.excluded_tools <value>

export ZEROCLAW_channels__whatsapp__<alias>__excluded_tools=

zeroclaw config set channels.whatsapp.<alias>.group_mention_patterns <value>

export ZEROCLAW_channels__whatsapp__<alias>__group_mention_patterns=

zeroclaw config set channels.whatsapp.<alias>.group_policy <value>

export ZEROCLAW_channels__whatsapp__<alias>__group_policy=

zeroclaw config set channels.whatsapp.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__whatsapp__<alias>__interrupt_on_new_message=

zeroclaw config set channels.whatsapp.<alias>.mention_only <value>

export ZEROCLAW_channels__whatsapp__<alias>__mention_only=

zeroclaw config set channels.whatsapp.<alias>.mode <value>

export ZEROCLAW_channels__whatsapp__<alias>__mode=

zeroclaw config set channels.whatsapp.<alias>.pair_code <value>

export ZEROCLAW_channels__whatsapp__<alias>__pair_code=

zeroclaw config set channels.whatsapp.<alias>.pair_phone <value>

export ZEROCLAW_channels__whatsapp__<alias>__pair_phone=

zeroclaw config set channels.whatsapp.<alias>.passive_group_context <value>

export ZEROCLAW_channels__whatsapp__<alias>__passive_group_context=

zeroclaw config set channels.whatsapp.<alias>.phone_number_id <value>

export ZEROCLAW_channels__whatsapp__<alias>__phone_number_id=

zeroclaw config set channels.whatsapp.<alias>.proxy_url <value>

export ZEROCLAW_channels__whatsapp__<alias>__proxy_url=

zeroclaw config set channels.whatsapp.<alias>.push_name <value>

export ZEROCLAW_channels__whatsapp__<alias>__push_name=

zeroclaw config set channels.whatsapp.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__whatsapp__<alias>__reply_min_interval_secs=

zeroclaw config set channels.whatsapp.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__whatsapp__<alias>__reply_queue_depth_max=

zeroclaw config set channels.whatsapp.<alias>.self_chat_mode <value>

export ZEROCLAW_channels__whatsapp__<alias>__self_chat_mode=

zeroclaw config set channels.whatsapp.<alias>.session_path <value>

export ZEROCLAW_channels__whatsapp__<alias>__session_path=

zeroclaw config set channels.whatsapp.<alias>.verify_token    # 掩码输入，加密存储

export ZEROCLAW_channels__whatsapp__<alias>__verify_token=

zeroclaw config set channels.whatsapp.<alias>.ws_url <value>

export ZEROCLAW_channels__whatsapp__<alias>__ws_url=

channels.whatsapp.<alias>.access_token 是机密信息。 以加密方式存储，绝不以明文形式保存在 config.toml 中。请通过以下方式之一进行设置，这些方式会在写入时加密：

zeroclaw config set channels.whatsapp.<alias>.access_token    # 提示输入掩码内容，以加密形式存储

这同样适用于 verify_token 和 app_secret（Cloud API）。

启动并检查

配置好一种模式后，启动通道运行器：

zeroclaw channel start

使用 zeroclaw channel doctor 进行初步检查。对于 Web 模式，还需确认二进制文件是使用 whatsapp-web 构建的；对于 Cloud API 模式，请确认 webhook 隧道与 Meta 验证令牌一致。