节点配对
节点配对包含两个层级,二者都存储在网关 SQLite 状态数据库中的已配对设备记录上:
- 设备配对(
node角色)对connect握手进行门控。参见下文可信 CIDR 设备自动审批以及通道配对。 - 节点能力审批(
node.pair.*)对已连接节点可暴露的已声明能力/命令进行门控。网关是事实来源;UI(macOS 应用、Control UI)是批准或拒绝待处理请求的前端。
此前独立的节点配对存储(nodes/paired.json,内含每节点 token,于 2026 年 1 月从 connect 路径中退役)已经移除:openclaw doctor --fix 会将剩余行并入设备记录,并用 .migrated 后缀归档旧文件。旧式 TCP 桥接支持已删除。
能力审批如何运作¶
- 节点连接到网关 WS(设备配对对此步骤进行门控)。
- 网关将声明的能力/命令面与已批准的面进行比较;新增或扩展的能力/命令面会在设备记录上存储待处理请求,并发出
node.pair.requested。 - 你批准或拒绝该请求(通过 CLI 或 UI)。
- 在批准之前,节点命令保持被过滤状态;批准后会暴露所声明的能力/命令面,并受常规命令策略约束。
待处理的节点能力请求不会仅仅因为时间流逝而过期。它们会在节点断开连接和网关重启后仍然存在,并保持待处理状态,直到被批准、拒绝、被变更后的能力/命令面取代,或被节点生命周期清除(例如移除 node 角色,或某次成功重连不再需要该审批)。
待处理的能力请求不会授予访问权限。批准仍然要求操作者具备所请求命令对应的 operator 作用域。在更新活动连接之前,网关会根据持久化的审批检查其配对身份和代次,并将访问限制在该连接所声明的能力和命令范围内。
初始未批准的能力/命令面没有任何有效命令。当后续扩展处于等待状态时,先前已批准的命令仅在节点仍然声明它们且网关命令策略允许时保持有效。
5 分钟过期仍然适用于设备配对请求,而不适用于已配对设备上的能力审批。
升级与旧版写入方¶
请一起升级网关以及任何直接写入同一状态数据库的 CLI。仅通过 RPC 调用网关的旧版应用或 CLI 不是直接数据库写入方;这些请求由网关处理。
能力请求的存储格式没有变化。旧版网关或直接 CLI 写入方仍会应用先前 5 分钟过期机制,并可能持久化删除过期请求,包括在无关的配对更新期间。因此,降级可能会恢复旧的过期行为;在旧版本写入数据库期间,生命周期保留不被保证。
升级后,旧版本仅从输出中隐藏的过期请求,如果仍被存储,可能会再次可见。它仍然需要明确批准。升级无法恢复已删除的请求:节点必须提交新的能力请求供操作者审查。现有的设备配对和先前已批准的能力与该待处理请求是分开的。
一键节点配对¶
在 Control UI 的 Devices 页面中,打开配对对话框,选择 Node host,然后将生成的命令复制到设备:
设置链接包含网关端点、一个短时有效的单次使用引导 token,以及当网关直接提供可固定的叶子证书时的 TLS 证书固定信息。引导 token 在 10 分钟后过期。显式的 --host、--port、--context-path、--tls/--no-tls 和 --tls-fingerprint 标志会覆盖 --pair 中的值。
引导 token 与最终生成的设备凭据是分开的,类似于短期的 Tailscale 认证密钥与其接纳的持久设备身份。撤销或使设置链接过期并不会撤销已配对的设备;需要时请单独移除设备。管理员签发的引导注册会批准设备及其首次声明的命令面,包括在声明了 system.run 时对该命令的批准,如同 SSH 验证设备自动审批。后续的命令、能力或权限扩展仍需审批。网关命令策略与节点本地执行审批仍然是独立的门控。本地执行审批默认采用 ask: "off" 的 full;如果该访问权限过于宽泛,请在使用链接之前进行配置。
CLI 工作流(适合无头环境)¶
对于手动设备准入,首先在网关上运行:
无头节点主机会在设备审批待处理期间持续重连,指数退避上限为 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 接口(网关协议)¶
事件:
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 的节点行;设备 token 调用者若要在混合角色设备上撤销自身的node角色,还需要operator.admin。node.rename- 重命名已配对节点的面向操作者显示名称。
已在 2026.7 中移除 node.pair.request 和 node.pair.verify。待处理请求现在由 Gateway 自身在节点连接期间创建,这两个 RPC 所服务的独立每节点令牌已不复存在;节点认证使用设备配对令牌。
注意:
- 能力面未改变的重新连接会复用待处理请求;重复请求会刷新已存储的节点元数据,以及供操作员查看的最新允许列表声明命令快照。
- 操作员范围级别和审批时检查摘要见 操作员范围。
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 令牌。
默认情况下,受信任的本地连接会静默批准首次设备配对以及角色和范围升级。这使常规同主机和 SSH 隧道重连保持便捷。已作为操作员完成配对的原生应用,可以用同一设备身份添加其第一个节点角色,而无需设备批准提示,包括重试标记为修复的待处理请求。这会保留其操作员令牌。Gateway 还会为静默配对的非浏览器本地设备直接批准初始节点能力面,包括使用远程模式连接同机 Gateway 的原生应用。无需应用侧 SSH 检查或批准面板。
这里使用的是同机器、同用户的信任边界。Gateway 的命令拒绝、节点本机操作系统权限及执行审批仍然生效。之后的能力面升级和被显式吊销的节点令牌仍需要批准。远程、受信任 CIDR、浏览器和代理连接不会因设备先前有过静默配对而获得本地批准。
使用无 shell、仅端口转发 SSH 密钥或多用户 Mac 的操作员可以要求对每台设备进行显式批准:
使用此设置后,即使连接是本地连接,新的配对请求、角色升级、范围升级和初始节点能力请求也会使用正常审批流程。重新启用本地自动批准时,未获批准的初始能力面可在重连时获得批准,包括之前被拒绝的。仅元数据的重连刷新仍会自动进行,因此常规客户端或操作系统元数据变更不会造成审批反复。
SSH 验证的设备自动批准(默认)¶
当网关能够通过 SSH 证明机器所有权时,来自私有/CGNAT 地址的首次 role: node 设备配对会被自动批准:网关会回连配对主机(BatchMode、StrictHostKeyChecking=yes),在其中运行 openclaw node identity --json,并且仅当远程设备 ID 和公钥与待处理请求完全匹配时才批准。密钥匹配正是安全性的来源:仅可达性永远不会获得批准,因此 NAT 同租户、共享主机上的其他用户以及 LAN 欺骗都会回退到正常提示。
默认启用。其触发条件如下:
- 网关进程用户(或
sshVerify.user)能够非交互式地 SSH 到节点主机(密钥/agent;Tailscale SSH 也可用),并且主机密钥已被信任。 - 在非交互式
sh -lc中,openclaw可在远程PATH中解析。 - 连接 IP 是直连(非代理、非回环)的私有、ULA、链路本地或 CGNAT 地址,或者在设置
sshVerify.cidrs时与其匹配。 - 与可信 CIDR 批准具有相同的资格下限:仅限全新的无 scope 节点配对;升级、浏览器、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 check:
// sshVerify: { user: "me", identity: "~/.ssh/check", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
},
},
},
}
手动批准(macOS 应用)¶
macOS 应用会在一个 OpenClaw 批准面板中显示节点和设备请求。每个请求都会保持名称、平台、源地址以及所有请求的访问权限可见。系统命令执行和设备管理员访问会被高亮显示。Gateway 归类为需要管理员批准的节点请求也会在整个请求上显示警告。展开 详情 可查看完整身份、应用/核心版本和请求元数据。
批准节点 用于批准节点声明的能力;它不会轮换设备访问令牌。命令返回 仅批准单个显示请求。仅按 Return 不会批准。暂不 或 Escape 会隐藏面板,而不处理请求。设备配对请求保留其正常过期时间;节点能力请求保持待定,直到其生命周期将其解决。
对于多个请求,全部批准 和 全部拒绝 仅适用于显示的请求。在该视图显示后到达的请求不会包含在决定中。
自动批准(macOS 应用)¶
macOS 应用可以在以下情况下尝试对节点能力请求进行 静默批准:
- 请求被标记为
silent(当设备配对被非交互式批准时,Gateway 会将首个能力面标记为静默),并且 - 应用能够使用同一用户验证到 Gateway 主机的 SSH 连接。
如果静默批准失败,它会回退到正常的批准/拒绝提示。
可信 CIDR 设备自动批准¶
对于 role: node 的 WS 设备配对默认保持手动。对于 Gateway 已信任网络路径的私有节点网络,操作员可以使用显式 CIDR 或精确 IP 选择加入:
安全边界:
- 当
gateway.nodes.pairing.autoApproveCidrs未设置时禁用。 - 不存在笼统的 LAN 或私有网络自动批准模式;SSH 验证自动批准(如上)要求加密设备密钥匹配,绝不单独依赖网络位置。
- 只有全新的、未请求任何 scope 的
role: node设备配对请求才符合条件。 - 这仅批准设备。其首个命令面仍需要
openclaw nodes pending和openclaw nodes approve <nodeRequestId>。 - Operator、浏览器、Control UI 和 WebChat 客户端保持手动。
- 角色、scope、元数据和公钥升级保持手动。
- 同主机回环可信代理头路径不符合条件,因为该路径可被本地调用方伪造。
静默配对覆盖清理¶
非交互式批准会在配对设备行上记录其来源:同主机本地策略批准记录为 silent,可信 CIDR 节点批准记录为 trusted-cidr,SSH 验证节点批准记录为 ssh-verified。状态目录为临时(临时主目录、容器、按运行沙箱)的客户端会在每次运行时生成新的设备密钥对,并且每次运行都会作为全新设备静默重新配对——如果没有清理,配对列表每次运行都会多出一条过期记录。
当 Gateway 静默批准一个 本地 设备配对时,它会退役属于同一客户端集群(匹配 clientId、clientMode 和显示名称)且当前未连接的较旧 silent 批准记录。本地客户端运行在 Gateway 主机本身,因此集群密钥不会匹配到另一台机器。退役的行会立即失去其令牌;任何匹配的旧版节点配对条目都会被清除,并广播一个 node.pair.resolved 移除事件。
边界:
- 只有最新批准为同主机本地(
silent)的记录才符合条件,无论是作为触发者还是目标。可信 CIDR 和 SSH 验证配对会跨主机,而显示元数据不是机器身份,因此它们永远不会被自动移除——请使用 Control UI 清理或openclaw nodes remove处理这些记录。 - 所有者批准和 QR/设置码(bootstrap)配对永远不会被自动移除。在来源字段存在之前批准的记录仍受保护,即使之后对同一设备 id 进行了静默重新批准。
- 当前已连接的设备会被跳过,因此具有不同状态目录的并发本地会话在存活期间会保留其令牌。最近一分钟内批准的记录也会被跳过,因此同时进行的配对握手不会在连接注册之前相互退役。
- 受影响的客户端按构造是本地的,因此它们会在下次连接时静默重新配对。
元数据升级自动批准¶
当已配对设备仅以非敏感元数据变更重新连接(例如显示名称或客户端平台提示)时,OpenClaw 会将其视为 metadata-upgrade。静默自动批准的适用范围很窄:它仅适用于已证明持有本地或共享凭据的可信非浏览器本地重连,包括操作系统版本元数据变更后同主机原生应用的重连。浏览器/控制 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。
传输行为¶
- 传输是无状态的;它不存储成员关系。
- 如果网关离线或配对已禁用,节点无法配对。
- 在远程模式下,配对针对远程网关的存储进行。
相关¶
- 通道配对
- 网关协议身份验证 — 设备身份、配对签名和设备令牌的线路契约
- Nodes CLI
- Devices CLI
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw