为什么这篇值得先看
pairing 是很多人第一次接 OpenClaw 渠道时最困惑的环节，但它恰恰是让助手不乱接入的关键安全机制。你可以把它理解成“第一次让谁进门”的审批动作：陌生私信发送者、移动端设备、远程节点，都不应该默认拥有访问权。
真正容易出错的地方不在命令，而在把不同 pairing 混成一类：聊天渠道 pairing 解决“谁能给机器人私信”；Gateway / device pairing 解决“哪个设备或节点能加入 Gateway”。如果你把两者混起来，就会出现“私信已经批了，为什么群里还是不响应”“设备已经扫了二维码，为什么 Control UI 还没权限”这类误判。
先抓住这 3 个关键点
- pairing 的目标不是增加麻烦，而是把首次接入做成可审计、可批准的动作。
- pairing code 和 pending request 都有生命周期，审批拖太久会自然过期，这是设计而不是 bug。
- pairing 和 allowlist、dmPolicy、groupPolicy 一起决定了“谁能成为你的助手入口”。
先分清两类 pairing
| 类型 | 解决的问题 | 常见入口 | 你要检查什么 |
|---|---|---|---|
| 私信发送者 pairing | 某个人能不能通过 Telegram / WhatsApp 等渠道私信助手 | /start、首次私聊、机器人返回 code | openclaw pairing list <channel>、code 是否过期、approve 后是否进入 allowlist |
| 设备 / 节点 pairing | 某个移动端、浏览器、Control UI、无头节点能不能加入 Gateway | QR、setup code、device request | openclaw devices list、requestId、角色、作用域、是否请求更高权限 |
一个非常实用的判断标准：如果问题发生在“某个人发消息给 bot”，优先看 channels pairing；如果问题发生在“某个设备连接 Gateway”，优先看 Gateway / devices pairing。
实操步骤
- 先在 channel 侧触发 pairing，再用终端或 Control UI 查看是否出现待审批项目。
- 运行
openclaw pairing list <channel>，确认 code 是否已经生成、channel 是否正确、状态是否仍有效。 - 用
openclaw pairing approve <channel> <CODE>完成审批，不要让 code 超过有效期。 - 审批完成后，立刻回到 channel 测一次消息路径，确认不是“批了但没真正通”。
- 如果是设备或节点接入，不要套用 channel 命令，改用
openclaw devices list和openclaw devices approve <requestId>。
配置或命令示例
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>如果你不希望陌生私信默认触发 pairing，可以把策略改得更严格。下面只是结构示例，真实 ID 要以官方渠道文档和你的账号格式为准。
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "allowlist",
allowFrom: ["tg:123456789"],
groups: { "*": { requireMention: true } }
}
}
}一条标准私信审批链
- 用户在 Telegram 或 WhatsApp 私信机器人。
- 机器人根据
dmPolicy决定是否返回 pairing code。 - 管理员运行
openclaw pairing list telegram，确认 code、发送者和状态。 - 管理员运行 approve 命令。
- OpenClaw 把允许信息写入对应 channel 的 allowlist 存储。
- 用户再次发消息，管理员确认消息真正进入对话路径。
官方 channels pairing 页面特别强调：DM 配对允许列表用于私信访问，群组授权是独立的。也就是说，批准了某个人的 DM pairing，不代表他可以在群里控制机器人。群组仍然要看 groupAllowFrom、groups 或渠道自己的群组规则。
一条标准设备审批链
- 移动端、浏览器、Control UI 或无头节点尝试连接 Gateway。
- Gateway 创建设备 pairing request，通常带有 requestId、role、scope 等信息。
- 管理员运行
openclaw devices list查看请求。 - 管理员比较“当前已批准访问权限”和“新请求的访问权限”。
- 权限合理时 approve；不认识的设备、异常 scope、异常公钥变更一律 reject 或暂停调查。
设备 pairing 的风险比普通私信 pairing 更接近运行边界。尤其是 role、scope、公钥、token 轮换这类变化，不应该为了省事静默批准。
过期和重试怎么处理
- 不要复用旧 code：过期就是过期，重新触发比排查旧状态更快。
- 不要同时开多个入口乱试：Telegram、WhatsApp、Control UI、mobile app 同时试，会让你分不清哪条 pending request 对应哪个动作。
- 先 reject 再重来：无法确认来源的 pending request，不要因为“可能是我刚才点的”而批准。
- 记录谁批准了什么：团队环境里至少把 channel、code/requestId、批准人、时间和验证结果记下来。
风险边界
- pairing code、setup code 和 bootstrap token 都应当临时当作密码处理。
allowFrom、paired devices、pending requests 都控制访问权，不要把这些文件当普通缓存随意删改。dmPolicy: "open"只适合非常明确的临时测试或公开机器人场景，生产环境应有额外隔离。- 已配对设备如果请求更多 scope 或角色变化，需要重新审批，不能简单当成“同一台设备所以没问题”。
常见坑
- 看到配对码生成就以为完成了，忘记审批这一步。
- 配对码过期后继续反复点旧链接，浪费时间在无效状态上。
- pairing 批了，但后续 dmPolicy / allowlist 仍然挡住消息。
- 批准了 DM pairing，却以为群组权限也同步放开。
- 把设备 pairing request 当成普通聊天 pairing code 处理，导致审批命令和排错方向都错了。
完成检查
- 你知道如何查看、审批和验证一次 pairing。
- 你理解 pairing 和后续访问控制的关系，而不是把它当成一次性登录。
- 新的 channel 接入时，你已经有标准操作顺序。
- 你能向团队解释 DM pairing、group access、device pairing 分别控制什么。
为什么建议把这篇收藏起来
- 以后每接一个新入口都要回到 pairing，这是一篇高复访率内容。
- 把它搞懂，后续所有渠道接入都会顺很多。
- 一旦进入团队环境，它还能作为审批 SOP 的基础版本。