本篇从“选哪个号码”开始，直到手机端收到第一条实际回复。首次练习关闭群入口，只验证一个明确身份。旧号码选择页已合并到本页。
**验证范围：**下文依据当前官方文档整理，本站未关联真实 WhatsApp 账号。两份下载配置是文档示例，不是产品实测证据；实际安装版本、插件 schema 和消息行为需按步骤验收。
第一步：选择号码模式
| 模式 | 你需要准备 | 本文采用的规则 |
|---|---|---|
| 专用号码 | 给 OpenClaw 关联的独立 WhatsApp 账号，以及向它发任务的操作员账号 | 操作员号码放入 allowFrom，关闭同号自聊，群入口关闭 |
| 个人号码自聊 | 你日常使用且准备关联的 WhatsApp 账号 | 明确开启 selfChatMode，将自己的号码写入名单，群入口关闭 |
官网建议条件允许时使用专用号码，也支持个人号码自聊。这里的选择取决于你是否希望把个人聊天与助手身份分开。群聊是后续的接入范围，不是第三种号码模式。
先在自己的记录中填清：哪个号码被扫码关联、哪个号码发送任务、谁负责维护关联设备。专用号路线尤其不要把机器人账号本身的号码误填成唯一操作员。
第二步：准备环境和最小配置
确认 OpenClaw 已安装、模型能完成基本回复，并有一个可持续运行 Gateway 的环境。新建测试实例时按其安装文档选择配置路径，不要覆盖正在使用的完整配置。
WhatsApp 运行组件是独立插件。当前官方文档说明，首次选择该渠道时引导可提示安装；手工安装入口为：
openclaw plugins install @openclaw/whatsapp安装完成后记录 OpenClaw 和插件版本。此命令会安装插件，本文没有代你执行它。不要把缺插件、模型未配置与消息权限问题混为同一类失败。
以下内容只包含 channels.whatsapp，应合入对应实例的配置；保留现有模型、Gateway 和其他渠道设置。
专用号码配置
下载专用号码模板。把示例号码换成发送任务的操作员号码，使用带国家代码的 E.164 格式。
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": [
"+15551234567"
],
"selfChatMode": false,
"groupPolicy": "disabled"
}
}
}本模板明确关闭同号自聊。它只限制入站任务范围，不代表 Agent 获得的其他工具不能向外发送消息；工具权限仍需要单独设计。
个人号码自聊配置
下载个人自聊模板。把示例号码换成你将关联的个人账号号码。
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": [
"+15551234567"
],
"selfChatMode": true,
"groupPolicy": "disabled"
}
}
}selfChatMode 并非普通 allowlist 的别名。当前文档说明，同号自聊有特殊准入：为 true 或未设置时可以进入，dmPolicy: "disabled" 仍会阻止；显式 false 则忽略同号 DM。这里主动写出设置，避免依赖隐式行为。
在扫码之前检查
openclaw config validate --json核对实际校验路径、valid 和警告。此时如果报告渠道或插件无法识别，先检查插件安装与版本，不要删除配置字段来掩盖问题。JSON 能解析并不证明插件接受配置，也不证明 WhatsApp 连接可用。
第三步：关联 WhatsApp 账号
在正确的实例中运行：
openclaw channels login --channel whatsapp用准备关联的 WhatsApp 账号在手机的关联设备入口扫描本次实时二维码。二维码会失效，远程主机上要先准备能及时查看终端的方式，不反复使用旧截图。
扫码关联建立的是账号会话。它不会自动批准所有发送者，也不代表模型已经能回复。
若采用多账号，登录时需明确 --account，并核对认证目录。首次练习建议只完成一个账号；不要将已有私人认证目录复制到公开项目或下载模板里。
第四步：启动 Gateway 并发送最小任务
若该实例已有 Gateway 服务，先查看状态；不要再启动第二个进程。仅在需要前台运行的测试实例中使用：
openclaw gateway另一个终端检查：
openclaw channels status专用号路线：从名单中的操作员账号私信关联号码。个人号路线：在自己的自聊对话发送。使用一个不涉及文件操作的任务：
这是 AC-WA-017 接入测试。请只回复：AC-WA-017 已收到。
不要调用其他工具，不要给其他联系人发送消息。这是演练提示，不替代实际工具权限。检查三层结果：渠道收到输入、模型完成处理、手机端收到回复。只看到“输入中”或 Gateway 日志里的模型文本，都不足以证明送达。
什么时候才使用 pairing approve
本文两份模板都采用 allowlist，不要求名单用户再走配对审批。旧教程把 allowlist 配置与无条件 pairing approve 连在一起，现已更正。
如果你有意将私聊策略改成 pairing，才处理未知发送者的待批准请求：
openclaw pairing list whatsapp
openclaw pairing approve whatsapp "实际配对码"先确认请求属于你正在测试的人和账号，再批准。配对码与登录二维码不是同一件事；没有待处理请求时，不要编造配对码或通过开放所有人来绕过。
第五步：验证拒绝、重启和实际送达
下载 WhatsApp 接入验收表。预期结果不是本站实测结果，逐项填写实际观察。
| 场景 | 要验证的结果 |
|---|---|
| 已授权身份发送测试消息 | 手机端实际收到对应标记回复 |
| 经同意使用的非授权测试账号发消息 | 不执行其任务；日志能区分准入拒绝与离线 |
| 专用号对自己发 DM | 本模板 selfChatMode false，应被忽略 |
| 个人号自聊 | 本模板 selfChatMode true，按测试请求处理 |
| 测试群内发送消息 | groupPolicy disabled，不执行群任务 |
| 正常重启同一 Gateway 实例 | 检查会话是否恢复，并重新完成一次私聊 |
先完成授权正例，才有条件判断负例是否因准入规则被拒绝。机器人全部无响应时，不能把负例记为成功。
会话是否持久化取决于实际认证目录和运行环境。重启后需要扫码时，先核对账号、目录持久化和日志，不直接删除所有凭据重来。
群聊放到私聊之后
群入口开放前分别记录群 JID、允许的发送者、提及方式。WhatsApp 的群标识与 Telegram 负数群 ID 不同，不要互相复制。
当前官方文档区分群范围与群内发送者策略，提及还要单独判断。首次指定群时使用真实核实的群 JID，并保留发送者限制；不要把 groups: { "*": ... } 当成“只开放测试群”。
这一步需要新的正例和负例验收。私聊 pairing 已批准或某个人能使用私聊，都不能直接证明群权限正确。多账号时还要确认最终生效的是哪份群配置。
按现象排错
| 现象 | 先检查 | 暂时不要做 |
|---|---|---|
| 登录命令没有正常进入 QR 流程 | 插件安装、版本、渠道识别及终端错误 | 重写全部渠道配置 |
| 扫码后仍未关联 | QR 是否有效、手机账号、实例与账户选择 | 重用旧二维码 |
| 已关联但断开 | Gateway 进程、网络、代理和认证目录 | 一次性修改所有超时参数 |
| 私聊输入被忽略 | 实际发送者、dmPolicy、allowFrom、自聊模式 | 改成 open 放行所有人 |
| 模型有输出但手机没有 | 渠道投递错误与目标账号 | 把模型成功当成送达成功 |
| 重启后丢失会话 | 持久卷、认证目录和运行身份 | 清空其他账号凭据 |
停用与保留记录
结束临时测试时，记录结果并清理测试消息中的无关信息。如果决定不再使用该关联，按当前 CLI 帮助确认账号后注销：
openclaw channels logout --channel whatsapp多账号必须指定正确账号；注销会清除对应认证状态，不能当作普通排错的第一步。停用后核对手机关联设备与渠道状态。保留不含凭据的配置、版本和验收记录，后续增加群聊或自动化时才有可比较的基线。