节点配对

• 设备配对（角色 node）限制 connect 握手。参见 受信任 CIDR 设备自动批准 下文以及 通道配对。
• 节点能力审批（node.pair.*）限制已连接节点可以暴露哪些已声明的 能力/命令。Gateway 是事实来源；UI（macOS 应用、Control UI）是用于批准或 拒绝待处理请求的前端。

​

能力审批如何工作

1. 节点连接到 Gateway WS（设备配对会对这一步进行门控）。
2. Gateway 将声明的能力/命令表面与已批准的表面进行比较；新的或扩展后的表面会在设备记录上存储一个待处理请求，并发出 node.pair.requested。
3. 你批准或拒绝该请求（CLI 或 UI）。
4. 在批准之前，节点命令会保持过滤状态；批准后会暴露声明的表面，但仍受正常命令策略约束。

​

一键粘贴节点配对

openclaw node run --pair "oc-pair://<setup-code>"

​

CLI 工作流（适合无界面环境）

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "客厅 iPad"

​

API 表面（gateway 协议）

• node.pair.requested - 在创建新的待处理请求时发出。
• node.pair.resolved - 在请求被批准、拒绝或 过期时发出。

• node.pair.list - 列出待处理和已配对的节点（operator.pairing）。
• node.pair.approve - 批准待处理请求。
• node.pair.reject - 拒绝待处理请求。
• node.pair.remove - 移除已配对的节点。这会撤销该设备在已配对设备存储中的 node 角色，连同它一起移除已批准的节点表面，并使该设备的 node 角色会话失效/断开。混合角色 设备（例如同时拥有 operator 的设备）会保留其记录，只失去 node 角色；仅具有 node 的设备记录将被删除。授权： operator.pairing 可以移除非 operator 的 node 记录；而设备令牌调用方在混合角色设备上撤销其自己的 node 角色时，还需要 operator.admin。
• node.rename - 重命名已配对节点面向 operator 显示的名称。

• 表面未发生变化的重新连接会复用待处理请求；重复请求会刷新存储的节点元数据以及最新的、列入允许列表的声明命令快照，供 operator 查看。
• operator 作用域级别和批准时检查的摘要，请参阅 Operator 作用域。
• node.pair.approve 使用待处理请求声明的命令来强制执行额外的批准作用域：
  • 不含命令的请求：operator.pairing
  • 普通命令请求：operator.pairing + operator.write
  • 包含 system.run、system.run.prepare、 system.which、browser.proxy、browser.proxy.upload.v1、fs.listDir、 或 system.execApprovals.get/set 的管理员敏感请求：operator.pairing + operator.admin

​

节点命令门控（2026.3.31+）

• 之前仅依赖设备配对即可暴露命令的节点，现在还必须完成节点配对。
• 在配对批准之前排队的命令会被丢弃，而不是延后执行。

​

节点事件信任边界（2026.3.31+）

​

静默本地配对

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveLocal: false,
      },
    },
  },
}

​

SSH 验证的设备自动批准（默认）

• 网关进程用户（或 sshVerify.user）可以通过 SSH 非交互式连接到节点主机（密钥/agent；Tailscale SSH 也可），且该主机密钥已被信任。
• openclaw 在远程的 sh -lc 非交互环境下可从 PATH 中解析到。
• 连接 IP 是直接的（非代理、非回环）私有地址、ULA、链路本地地址或 CGNAT 地址，或者在设置了 sshVerify.cidrs 时与其匹配。
• 与受信任 CIDR 批准相同的准入门槛：仅限新的、无作用域的节点配对；升级、浏览器、Control UI 和 WebChat 始终会提示。

{
  gateway: {
    nodes: {
      pairing: {
        // 完全禁用：
        sshVerify: false,
        // ...或者限定/调整探测：
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

​

自动批准（macOS 应用）

• 请求被标记为 silent（当设备配对以非交互方式获批时，网关会将第一个能力界面标记为静默），并且
• 应用能够使用相同用户验证到网关主机的 SSH 连接。

​

基于受信任 CIDR 的设备自动批准

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

• 当 gateway.nodes.pairing.autoApproveCidrs 未设置时，将禁用。
• 不存在一刀切的 LAN 或私有网络自动批准模式；上文所述的基于 SSH 验证的 自动批准要求设备密钥的加密学匹配，绝不只是依赖网络位置。
• 只有没有请求任何作用域的全新 role: node 设备配对请求才具备资格。
• 运维人员、浏览器、Control UI 和 WebChat 客户端仍然需要手动处理。
• 角色、作用域、元数据和公钥升级仍然需要手动处理。
• 同主机回环的受信任代理头路径不具备资格，因为该路径可能被本地调用者伪造。

​

静默配对替代清理

• 只有最新批准为同主机本地（silent）的记录才有资格，既作为触发条件，也作为目标。受信任 CIDR 和 SSH 验证配对跨越主机，而显示元数据并不是机器身份，因此它们绝不会被自动移除——请对这些使用 Control UI 清理或 openclaw nodes remove。
• 由所有者批准以及 QR/设置码（bootstrap）配对绝不会被自动移除。即使后来同一设备 ID 又被静默重新批准，之前在尚未记录来源时批准的记录也会继续受到保护。
• 当前已连接的设备会被跳过，因此使用独立状态目录的并发本地会话在在线期间会保留各自的令牌。最近一分钟内批准的记录也会被跳过，因此同时进行的配对握手不会在连接注册之前互相清理。
• 受影响的客户端从结构上就是本地客户端，因此它们会在下次连接时静默重新配对。

​

元数据升级自动批准

​

QR 配对辅助

​

本地性与转发头

​

存储（本地，私有）

• ~/.openclaw/state/openclaw.sqlite（包含带设备认证的已配对设备、已批准的节点表面、待处理的表面请求、待处理的设备配对请求以及引导令牌）

• 设备令牌是机密信息；请将状态数据库视为敏感数据。
• 轮换设备令牌时使用 openclaw devices rotate / device.token.rotate。

​

传输行为

• 该传输是无状态的；它不存储成员关系。
• 如果 Gateway 离线或已禁用配对，则节点无法进行配对。
• 在远程模式下，配对会针对远程 Gateway 的存储进行。

​

相关内容

• 通道配对
• 节点 CLI
• 设备 CLI