配对（Pairing）

"配对"是 OpenClaw 的主人审批步骤。用于两个场景：

私信配对（谁可以和 Bot 对话）
节点配对（哪些设备/节点可以加入 Gateway 网络）

安全说明详见：安全

1）私信配对（入站聊天访问控制）

当某个渠道配置了 dmPolicy: pairing 时，未知发送者会收到一个短码，其消息在你审批前不会被处理。

各渠道的默认私信策略详见：安全

配对码规则：

8 位字符，全大写，不含易混淆字符（0O1I）。
1 小时后过期。Bot 只在创建新请求时发送配对消息（每个发送者大约每小时一次）。
待处理的私信配对请求默认每渠道上限 3 个；超出部分会被忽略，直到有请求过期或被审批。

审批发送者

bash

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

支持的渠道：bluebubbles、discord、feishu、googlechat、imessage、irc、line、matrix、mattermost、msteams、nextcloud-talk、nostr、openclaw-weixin、signal、slack、synology-chat、telegram、twitch、whatsapp、zalo、zalouser。

状态存储位置

存储在 ~/.openclaw/credentials/ 下：

待处理请求：<channel>-pairing.json
已审批的白名单存储：
- 默认账号：<channel>-allowFrom.json
- 非默认账号：<channel>-<accountId>-allowFrom.json

账号作用域说明：

非默认账号只读写其作用域的白名单文件。
默认账号使用不含账号作用域的白名单文件。

这些文件控制谁可以访问你的智能体，请妥善保管。

2）节点设备配对（iOS/Android/macOS/无头节点）

节点以 role: node 的设备身份连接到 Gateway。Gateway 会创建一个设备配对请求，必须经过你的审批。

通过 Telegram 配对（iOS 推荐方式）

如果你使用了 device-pair 插件，可以完全通过 Telegram 完成首次设备配对：

在 Telegram 中，给你的 Bot 发送消息：/pair
Bot 回复两条消息：一条说明消息和一条单独的配置码消息（在 Telegram 中便于复制粘贴）。
在手机上，打开 OpenClaw iOS 应用 → 设置 → Gateway。
粘贴配置码并连接。
回到 Telegram：/pair pending（查看请求 ID、角色和权限范围），然后审批。

配置码是 Base64 编码的 JSON 载荷，包含：

url：Gateway WebSocket URL（ws://... 或 wss://...）
bootstrapToken：用于初始配对握手的短效单设备引导 Token

在有效期内，请像对待密码一样保护好配置码。

审批节点设备

bash

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

如果同一设备用不同的认证信息重试（例如不同的角色/权限范围/公钥），之前的待处理请求会被替换，并生成新的 requestId。

节点配对状态存储

存储在 ~/.openclaw/devices/ 下：

pending.json（短效；待处理请求会过期）
paired.json（已配对设备 + Token）

注意事项

旧版 node.pair.* API（CLI：openclaw nodes pending/approve）是独立的 Gateway 配对存储。WebSocket 节点仍需要设备配对。

配对（Pairing） ​

1）私信配对（入站聊天访问控制） ​

审批发送者 ​

状态存储位置 ​

2）节点设备配对（iOS/Android/macOS/无头节点） ​

通过 Telegram 配对（iOS 推荐方式） ​

审批节点设备 ​

节点配对状态存储 ​

注意事项 ​

相关文档 ​