私信配对和节点配对是 OpenClaw 的两道独立审批关卡。你要配置 dmPolicy: pairing 让未知发送者收到8位短码，1小时内凭码审批；节点设备需通过 /pair 命令或 CLI 生成配置码后再 approve。私信配对不会自动赋予群组权限，节点配对默认手动，可选 autoApproveCidrs 指定可信 IP 范围实现自动放行。

OpenClaw 配对配置：私信审批与节点设备接入

"配对"是 OpenClaw 的显式访问审批步骤，用于两个场景：私信配对（谁可以和 Bot 对话）和节点配对（哪些设备/节点可以加入 Gateway 网络）。

安全上下文详见：安全

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

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

各渠道默认 DM 策略详见：安全

dmPolicy: "open" 仅在 DM 允许列表包含 "*" 时才真正公开。如果当前状态是 open 但 allowFrom 有具体项，运行时仍只允许那些发送者，配对存储的审批不会扩大 open 的访问范围。

配对码规则

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

审批一个发送者

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

如果没有配置命令所有者（commands.ownerAllowFrom），第一次审批配对码时会自动将审批的发送者设为命令所有者（格式如 telegram:123456789）。后续审批只授予私信访问权限，不再添加更多所有者。

支持渠道

discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser。

可重用的发送者组

使用顶层 accessGroups 定义信任发送者集，然后在多个渠道的 allowlist 中引用。

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}

详细文档：Access groups

状态存储位置

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

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

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

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

INFO

配对白名单只控制私信访问。群组授权是独立的：审批一个私信配对码不会自动允许该发送者在群组中运行命令或控制 Bot。首次所有者引导是独立的 commands.ownerAllowFrom 状态，群组消息传递仍然遵循渠道的群组 allowlist（例如 groupAllowFrom、groups 或按群组/话题的覆盖设置）。

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

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

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

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

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

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

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

该引导 Token 携带内置的配对引导策略：

• 内置配置只允许基础操作：node 加上一个受限的 operator 交接
• 交接后的 node Token 保持 scopes: []
• 交接后的 operator Token 仅限于 operator.approvals、operator.read 和 operator.write
• operator.admin 和 operator.pairing 不会通过二维码/配置码引导授予，需要单独的已批准操作员配对或 Token 流程
• 后续 Token 轮换/吊销仍受设备已批准角色合同和调用会话操作员作用域的双重约束

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

网络限制：对于 Tailscale、公网或其他远程移动配对，请使用 Tailscale Serve/Funnel 或其它 wss:// Gateway URL。纯文本 ws:// 的配置码只接受环回地址、私有局域网地址、.local Bonjour 主机和 Android 模拟器主机。Tailnet CGNAT 地址、.ts.net 名称和公网主机在二维码/配置码签发前就会拒绝。

审批一个节点设备

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

当显式审批因审批方配对设备会话只有配对作用域而被拒绝时，CLI 会以 operator.admin 重新尝试同一个审批请求。这样已有管理员能力的配对设备可以在不手动编辑 devices/paired.json 的情况下恢复新的 Control UI/浏览器配对。Gateway 仍会验证重试连接；无法用 operator.admin 认证的 Token 继续被阻止。

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

INFO

已配对的设备不会静默获得更广泛访问权限。如果它重新连接时要求更多作用域或更宽泛的角色，OpenClaw 保持现有批准不变，并创建一个新的待处理升级请求。审批前用 openclaw devices list 对比当前已批准访问与新请求的访问。

可选的 trusted-CIDR 节点自动审批

节点设备配对默认手动。对于严格控制的节点网络，可以选择通过显式 CIDR 或精确 IP 实现首次节点自动批准：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

这仅适用于没有请求作用域的新 role: node 配对请求。操作员、浏览器、Control UI 和 WebChat 客户端仍需手动审批。角色、作用域、元数据和公钥变更也仍需手动审批。

节点配对状态存储

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

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

注意事项

• 旧版 node.pair.* API（CLI：openclaw nodes pending|approve|reject|remove|rename）是独立的 Gateway 配对存储。WebSocket 节点仍需要设备配对。
• 配对记录是已批准角色的持久化唯一权威来源。活动设备 Token 始终受限于该批准角色集；不在批准角色内的 Token 条目不会产生新访问权限。

常见问题

如何审批一个 Telegram 私信发送者的配对请求？

收到配对码后，运行 openclaw pairing list telegram 查看待处理请求和代码，然后 openclaw pairing approve telegram <CODE> 完成审批。注意审批前要先确认命令所有者已设置（第一次审批时会自动设置）。

通过 Telegram 配对 iOS 节点时，配置码无法连接怎么办？

检查 Gateway URL 是否使用 wss://（公网或 Tailscale 必须用 wss://，ws:// 仅限局域网）。确认配置码在有效期内，并确保 device-pair 插件已启用。如果网络受限，尝试 Tailscale Serve/Funnel 暴露 Gateway。

节点设备配对如何设置自动批准？

在 config.yaml 的 gateway.nodes.pairing.autoApproveCidrs 中填写可信 CIDR 列表（如 ["192.168.1.0/24"]）。这仅对新 role: node 且无作用域请求生效，不影响操作员/浏览器配对。

相关文档

• 安全模型 + 提示注入：安全
• 安全更新（运行 doctor）：更新
• 各渠道配置：
  • Telegram：Telegram
  • WhatsApp：WhatsApp
  • Signal：Signal
  • iMessage：iMessage
  • Discord：Discord
  • Slack：Slack