节点配对

节点配对包含两个层面，二者都存储在 Gateway 的 SQLite 状态数据库中的已配对设备记录上：

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

旧的独立节点配对存储（nodes/paired.json，包含每个节点的令牌，已于 2026 年 1 月从 connect 路径中退役）已移除：openclaw doctor --fix 会将剩余行合并到设备记录中，并以 .migrated 后缀归档旧文件。旧版 TCP 桥接支持已移除。

能力批准如何工作¶

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

待处理的节点能力请求不会仅因时间流逝而过期。它们会保留在节点断开连接和 Gateway 重启之后，并持续保持待处理状态，直到被批准、被拒绝、被变更后的表面取代，或被节点生命周期清除，例如移除节点角色，或一次不再需要该批准的重新连接成功。

待处理的能力请求不会授予访问权限。批准仍然需要所请求命令的操作员作用域。在更新活动连接之前，Gateway 会将其配对身份和代际与持久化的批准进行核对，并将访问限制为该连接所声明的能力和命令。

初始未批准的表面没有任何有效命令。在后续扩展等待期间，先前已批准的命令只有在节点仍然声明它们且 Gateway 命令策略允许时，才保持有效。

5 分钟过期仍然适用于设备配对请求，而不适用于已配对设备上的能力批准。

升级与旧版本写入方¶

请同时升级 Gateway 以及任何直接写入同一状态数据库的 CLI。仅通过 RPC 调用 Gateway 的旧版应用或 CLI 不是直接数据库写入方；Gateway 会处理这些请求。

能力请求的存储格式未改变。旧版 Gateway 或直接 CLI 写入方仍会应用先前的 5 分钟过期规则，并可能持久化删除过期请求，包括在不相关的配对更新期间。因此，降级可能会恢复旧的过期行为；当旧版本写入数据库时，生命周期保留不保证。

升级时，如果某个过期请求仍然被存储，而旧版本只是将其从输出中隐藏，它可能会重新可见。它仍然需要显式批准。升级无法恢复已被删除的请求：节点必须提交一个新的能力请求供操作员审核。现有设备配对和先前已批准的能力与该待处理请求是分开的。

一键粘贴节点配对¶

在 Control UI 的 Devices 页面中，打开配对对话框，选择 Node 主机，并将生成的命令复制到设备：

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

设置链接包含 Gateway 端点、一个短期一次性 bootstrap 令牌，以及当 Gateway 直接提供可固定的叶子证书时的 TLS 证书固定。bootstrap 令牌在 10 分钟后过期。显式的 --host、--port、--context-path、--tls/--no-tls 和 --tls-fingerprint 标志会覆盖来自 --pair 的值。

bootstrap 令牌和由此产生的设备凭据是分开的，类似于短期 Tailscale 授权密钥及其所允许进入的持久设备身份。撤销或使设置链接过期不会撤销已配对设备；需要时请单独移除该设备。管理员签发的 bootstrap 注册会批准该设备及其首次声明的命令表面，包括在声明时批准 system.run，类似于 SSH 验证设备自动批准。后续的命令、能力或权限扩展仍需要批准。Gateway 命令策略和节点本地 exec 批准仍然是独立的关卡。本地 exec 批准默认为 full，且 ask: "off"；如果该访问范围过宽，请在使用链接之前配置它们。

CLI 工作流（无头友好）¶

对于手动设备准入，请先在 Gateway 上运行：

openclaw devices list
openclaw devices approve <deviceRequestId>

无头节点主机在设备批准待处理期间会持续重新连接，采用指数退避，上限为 30 秒。批准后，下一次重新连接会创建独立的命令表面请求：

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

如果旧版客户端已经报告重新连接已暂停，请使用 openclaw node restart 重启已安装的节点，或停止并重新运行一次其前台命令。

设备请求 ID 和节点请求 ID 是不同的。若要拒绝表面请求，或改为管理现有节点：

openclaw nodes reject <nodeRequestId>
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status 显示已配对/已连接节点及其能力。

API 接口（Gateway 协议）¶

事件：

node.pair.requested - 当创建新的待处理请求时发出。
node.pair.resolved - 当请求被批准、拒绝或被节点生命周期清除时发出。

方法：

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

Removed in 2026.7: node.pair.request and node.pair.verify. Pending requests are created by the Gateway itself during node connects, and the standalone per-node token they served no longer exists; node auth is the device pairing token.

说明：

表面未变化的重连会复用待处理请求；重复请求会刷新已存储的节点元数据以及最新的允许列表声明命令快照，供操作员查看。
操作员作用域级别和审批时检查总结在操作员作用域中。
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

这里，fs.listDir 是通过 node.invoke 中继的节点命令。顶层 Gateway fs.listDir RPC 在浏览工作区内的主机时需要 operator.write，当存在 nodeId 时需要 operator.admin。

Warning

节点表面审批记录持久的命令/能力上限。它不会授予节点后来添加或不再声明的命令。

实时命令必须既已声明又已批准，然后通过 Gateway 的命令策略（gateway.nodes.commands.allow 和 gateway.nodes.commands.deny）。
system.run 的 Shell 允许列表和询问策略位于节点的执行审批中，而不是配对记录中。

节点命令门控 (2026.3.31+)¶

Warning

破坏性变更： 从 2026.3.31 开始，在节点配对获批之前，节点命令将被禁用。仅设备配对已不足以暴露声明的节点命令。

当节点首次连接时，会自动请求配对。在该请求获批之前，来自该节点的所有待处理节点命令都会被过滤且不会执行。一旦配对获批，节点声明的命令即可用，但仍受正常命令策略约束。

这意味着：

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

节点事件信任边界 (2026.3.31+)¶

Warning

破坏性变更： 节点发起的运行现在保持在缩减后的受信任表面上。

节点发起的摘要和相关会话事件被限制在预期的受信任表面内。之前依赖更广泛主机或会话工具访问的通知驱动或节点触发流程可能需要调整。此加固可防止节点事件升级为超出节点信任边界允许范围的主机级工具访问。

持久的节点在线状态更新遵循相同的身份边界：node.presence.alive 事件仅从已认证的节点设备会话接受，并且仅当设备/节点身份已配对时更新配对元数据。自行声明的 client.id 值不足以写入最后见到状态。

静默本地配对¶

Gateway 将环回源地址视为本地。这包括客户端通过 SSH 端口转发访问仅监听环回的远程 Gateway：SSH 服务器在 Gateway 主机上终止连接，因此 Gateway 将转发连接视为环回。这是有意为之，因为普通 SSH 访问已经隐含本地信任，包括读取共享 Gateway token 的能力。

默认情况下，受信任的本地连接会静默批准首次设备配对以及角色和作用域升级。这使得常规的同主机和 SSH 隧道重连保持便捷。使用无 shell、仅端口转发的 SSH 密钥或多用户 Mac 的操作员可以要求对每个设备进行显式审批：

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

在此设置下，即使连接是本地，新的配对请求、角色升级和作用域升级也会使用正常审批流程。仅元数据的重连刷新仍保持自动，因此常规客户端或操作系统元数据变化不会造成审批频繁变动。

SSH 验证设备自动批准 (默认)¶

来自私有/CGNAT 地址的首次 role: node 设备配对，在 Gateway 能够通过 SSH 证明机器所有权时会自动批准：它会回连到配对主机（BatchMode、StrictHostKeyChecking=yes），在那里运行 openclaw node identity --json，并且仅当远程设备 id 和公钥与待处理请求完全匹配时才批准。密钥匹配正是使其安全的原因：仅可达性永远不会批准，因此 NAT 共租户、共享主机上的其他用户以及局域网欺骗都会落入正常提示。

默认启用。触发条件：

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

在设备审批待处理期间，节点客户端会被告知继续重试（wait_then_retry），包括在 SSH 探测运行期间。如果探测失败，请求仍可供手动批准，并且节点会继续重试。失败的 SSH 目标会进入短暂冷却（密钥不匹配后 5 分钟）。

配对设置可热应用，无需重启 Gateway。自动批准在授予访问权限前会立即重新检查当前策略，即使策略更改时已有 SSH 探测或存储锁处于待处理状态。SSH 验证设置的更改会使用新的探测，并且不会继承之前策略的冷却时间。已配对的设备保持已配对状态。

已批准的设备会记录 approvedVia: "ssh-verified"，并且其首个声明的能力面会在同一步骤中获批——密钥匹配已经证明该节点运行在操作员所拥有机器上的操作员账户下，这与手动能力批准所声明的内容相同。后续能力面升级仍会触发提示。

加固或禁用：

{
  gateway: {
    nodes: {
      pairing: {
        // Disable entirely:
        sshVerify: false,
        // ...or scope/tune the probe:
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

手动批准（macOS 应用）¶

macOS 应用会在一个 OpenClaw 批准面板中显示节点和设备请求。每个请求都会保持名称、平台、源地址和所有请求的访问权限可见。系统命令执行和设备管理员访问会被高亮显示。被 Gateway 分类为需要管理员批准的节点请求也会在整个请求上显示警告。展开详情可查看完整身份、应用/核心版本和请求元数据。

批准节点会批准节点声明的能力；它不会轮换设备的访问 Token。命令返回仅批准单个已显示的请求。仅返回不会批准。稍后或 Escape 会隐藏面板，而不解决请求。设备配对请求保留其正常过期时间；节点能力请求保持待处理状态，直到其生命周期将其解决。

对于多个请求，全部批准和全部拒绝仅适用于已显示的请求。在该视图显示后到达的请求不包含在决定中。

自动批准（macOS 应用）¶

macOS 应用可以在以下情况下尝试对节点能力请求进行静默批准：

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

如果静默批准失败，则回退到正常的批准/拒绝提示。

可信 CIDR 设备自动批准¶

WS 设备配对对于 role: node 默认保持手动。对于 Gateway 已经信任网络路径的私有节点网络，操作员可以通过显式 CIDR 或精确 IP 选择加入：

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

安全边界：

当 gateway.nodes.pairing.autoApproveCidrs 未设置时禁用。
不存在笼统的 LAN 或私有网络自动批准模式；SSH 验证的自动批准（如上）要求加密设备密钥匹配，绝不单独依赖网络位置。
只有新的、未请求任何范围的 role: node 设备配对请求符合条件。
这仅批准设备。其首个命令面仍需要 openclaw nodes pending 和 openclaw nodes approve <nodeRequestId>。
Operator、浏览器、Control UI 和 WebChat 客户端保持手动。
角色、范围、元数据和公钥升级保持手动。
同主机回环可信代理头路径不符合条件，因为该路径可被本地调用方伪造。

静默配对取代清理¶

非交互批准会在配对设备行上记录其来源：同主机本地策略批准记录为 silent，可信 CIDR 节点批准记录为 trusted-cidr，SSH 验证的节点批准记录为 ssh-verified。状态目录为临时（临时主目录、容器、按运行沙箱）的客户端会在每次运行时生成新的设备密钥对，并且每次运行都会作为全新设备静默重新配对——如果没有清理，配对列表每次运行都会多出一行过期记录。

当 Gateway 静默批准一个本地设备配对时，它会退役属于同一客户端集群（匹配 clientId、clientMode 和显示名称）且当前未连接的较旧的 silent 批准记录。本地客户端运行在网关主机本身，因此集群密钥不会匹配到另一台机器。被退役的行会立即失去其 Token；任何匹配的旧版节点配对条目都会被清除，并广播一个 node.pair.resolved 移除事件。

边界：

只有最新批准为同主机本地（silent）的记录才符合条件，无论是作为触发者还是目标。可信 CIDR 和 SSH 验证的配对会跨主机，在这些情况下显示元数据不是机器标识，因此它们永远不会被自动移除——请使用 Control UI 清理或 openclaw nodes remove 处理这些记录。
所有者批准以及 QR/设置码（引导）配对永远不会被自动移除。在来源记录功能存在之前批准的记录仍受保护，即使之后对同一设备 id 进行了静默重新批准。
当前已连接的设备会被跳过，因此具有不同状态目录的并发本地会话在存活期间会保留其 Token。最近一分钟内批准的记录也会被跳过，因此同时进行的配对握手不会在连接注册之前相互退役。
受影响的客户端按设计是本地客户端，因此它们会在下次连接时静默重新配对。

元数据升级自动批准¶

当已配对设备重新连接且仅包含非敏感元数据变更（例如显示名称或客户端平台提示）时，OpenClaw 会将其视为 metadata-upgrade。静默自动批准范围很窄：它仅适用于已经证明拥有本地或共享凭据的可信非浏览器本地重连，包括操作系统版本元数据变更后同主机原生应用的重连。浏览器/Control UI 客户端和远程客户端仍使用显式重新批准流程。范围升级（从读取到写入/管理员）和公钥变更不符合元数据升级自动批准条件；它们仍保持为显式重新批准请求。

QR 配对辅助工具¶

/pair qr 将配对负载渲染为结构化媒体，以便移动和浏览器客户端可以直接扫描。

删除设备还会清理该设备 id 的任何过期待处理配对请求，因此在撤销后 nodes pending 不会显示孤立行。

本地性与转发头¶

网关配对仅当原始套接字和任何上游代理证据都一致时，才将连接视为回环。如果请求通过回环到达，但携带 Forwarded、任何 X-Forwarded-* 或 X-Real-IP 头证据，则该转发头证据会使回环本地性声明失效，配对路径会要求显式批准，而不是静默地将请求视为同主机连接。有关操作员身份验证中的等效规则，请参阅可信代理身份验证。

存储（本地、私有）¶

配对状态保存在网关状态目录（默认 ~/.openclaw）下共享 SQLite 状态数据库中的已配对设备记录里：

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

如果你覆盖 OPENCLAW_STATE_DIR，数据库会随之移动。停止网关并运行 openclaw doctor --fix 以导入旧版本中的存储。Doctor 会留下 devices/*.json.migrated 和 nodes/*.json.migrated 归档。它会先导入设备批准，再合并节点能力；现有 SQLite 批准优先。正常网关启动会报告待处理的旧版存储，但不会更改它们。

安全说明：

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

传输行为¶

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

频道配对
网关协议身份验证 — 设备身份、配对签名和设备令牌的线路契约
节点 CLI
设备 CLI

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

节点配对

能力批准如何工作¶

升级与旧版本写入方¶

一键粘贴节点配对¶

CLI 工作流（无头友好）¶

API 接口（Gateway 协议）¶

节点命令门控 (2026.3.31+)¶

节点事件信任边界 (2026.3.31+)¶

静默本地配对¶

SSH 验证设备自动批准 (默认)¶

手动批准（macOS 应用）¶

自动批准（macOS 应用）¶

可信 CIDR 设备自动批准¶

静默配对取代清理¶

元数据升级自动批准¶

QR 配对辅助工具¶

本地性与转发头¶

存储（本地、私有）¶

传输行为¶

相关¶