古法编程

Appearance

OpenClaw Gateway 自管配对模式下，Gateway 拥有节点加入的最终决定权，macOS 或未来客户端只是审批界面。CLI 命令 openclaw nodes pending、openclaw nodes approve <requestId>、openclaw nodes status 适用于无头环境。自 2026.3.31 起，节点命令在配对审批通过前会被过滤，不执行。待处理请求 5 分钟过期，令牌在审批时重新生成。配对状态存储在 ~/.openclaw/nodes/paired.json 和 pending.json。自动审批支持静默模式（SSH 验证）和信任 CIDR 配置，但受严格安全边界限制。

OpenClaw Gateway 自管节点配对配置与 CLI 操作 ​

在 Gateway 自管配对模式下，Gateway 是决定哪些节点可以加入的权威来源。macOS 应用、未来的客户端等 UI 只是审批或拒绝待处理请求的前端界面。

重要说明： WebSocket 节点在 connect 时使用的是设备配对（角色为 node）。node.pair.* 是独立的配对存储，不控制 WS 握手。只有显式调用 node.pair.* 的客户端才会走这套流程。

核心概念 ​

  • 待处理请求：节点发起了加入请求，等待审批。
  • 已配对节点：已审批的节点，拥有颁发的 auth token。
  • 传输层：Gateway WS 端点转发请求，但不决定成员资格。（旧版 TCP 桥接支持已废弃/移除。）

配对流程 ​

  1. 节点连接到 Gateway WS 并发起配对请求。
  2. Gateway 存储待处理请求并触发 node.pair.requested 事件。
  3. 你通过 CLI 或 UI 审批或拒绝该请求。
  4. 审批后，Gateway 颁发新 token（重新配对时 token 会轮换）。
  5. 节点使用该 token 重新连接，此时已完成配对。

待处理请求会在 5 分钟后自动过期。

CLI 操作流程（无头友好） ​

bash
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

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

API 接口（Gateway 协议） ​

事件：

  • node.pair.requested — 新待处理请求创建时触发。
  • node.pair.resolved — 请求被审批/拒绝/过期时触发。

方法：

  • node.pair.request — 创建或复用待处理请求。
  • node.pair.list — 列出待处理和已配对的节点。
  • node.pair.approve — 审批待处理请求（颁发 token）。
  • node.pair.reject — 拒绝待处理请求。
  • node.pair.verify — 验证 { nodeId, token }。

注意事项：

  • node.pair.request 对同一节点是幂等的：重复调用返回同一个待处理请求。重复请求会刷新节点元数据和最新允许声明的命令快照。
  • 审批始终生成新 token；node.pair.request 不会返回任何 token。
  • 请求可携带 silent: true 作为自动审批流的提示。
  • node.pair.approve 会根据待处理请求声明的命令实施额外的审批作用域：
    • 无命令请求：需要 operator.pairing
    • 非 exec 命令请求：需要 operator.pairing + operator.write
    • system.run / system.run.prepare / system.which 请求：需要 operator.pairing + operator.admin

WARNING

节点配对是信任与身份流加令牌颁发。它不固定每个节点的实时命令表面。

  • 实时节点命令来自节点连接后，经过 Gateway 全局节点命令策略（gateway.nodes.allowCommands 和 denyCommands）过滤后声明的命令。
  • 每个节点的 system.run 允许/询问策略存储在节点自身的 exec.approvals.node.* 中，不在配对记录中。

节点命令门控（2026.3.31+） ​

WARNING

重大变更： 从 2026.3.31 开始，节点命令在节点配对审批通过之前被禁用。仅设备配对不再足以暴露声明的节点命令。

当节点首次连接时，会自动请求配对。在配对请求被批准之前，来自该节点的所有待处理节点命令都会被过滤，不会执行。一旦通过配对审批建立信任，节点的声明命令才可用，并受正常命令策略约束。

这意味着：

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

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

WARNING

重大变更： 节点发起的运行现在停留在更小的受信任表面上。

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

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

自动审批（macOS 应用） ​

满足以下条件时，macOS 应用可以尝试静默审批：

  • 请求标记了 silent，且
  • 应用可以使用相同用户验证到 Gateway 宿主机的 SSH 连接。

若静默审批失败，则回退到正常的"审批/拒绝"提示界面。

信任 CIDR 设备自动审批 ​

默认情况下，role: node 的 WS 设备配对是手动的。对于 Gateway 已信任网络路径的私有节点网络，你可以选择显式指定 CIDR 或精确 IP 启用自动审批：

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

安全边界：

  • 当 gateway.nodes.pairing.autoApproveCidrs 未设置时禁用。
  • 没有通用的局域网或私有网络自动审批模式。
  • 仅对新的 role: node 设备配对且未请求任何作用域时才适用。
  • Operator、浏览器、Control UI 和 WebChat 客户端仍保持手动。
  • 角色、作用域、元数据和公钥升级仍保持手动。
  • 本地回环的受信任代理头路径不符合条件，因为该路径可能被本地调用者伪造。

元数据升级自动审批 ​

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

QR 配对助手 ​

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

删除设备时，也会清理该设备 ID 的任何过期待处理配对请求，因此 nodes pending 在撤销后不会显示孤儿条目。

本地性和转发头 ​

当原始套接字和所有上游代理证据都一致时，Gateway 配对才将连接视为回环。如果请求到达回环但带有 Forwarded、任何 X-Forwarded-* 或 X-Real-IP 头部证据，则转发头部证据会使回环本地性声明无效。配对路径随后需要显式审批，而不是静默地将其视为同台主机连接。参见 Trusted Proxy Auth 了解 operator 认证的等效规则。

存储（本地私有） ​

配对状态存储在 Gateway 状态目录（默认 ~/.openclaw）下：

  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json

若你覆盖了 OPENCLAW_STATE_DIR，nodes/ 文件夹会随之迁移。

安全注意事项：

  • Token 是机密信息，请将 paired.json 视为敏感文件妥善保管。
  • 轮换 token 需要重新审批（或删除对应节点条目）。

传输层行为 ​

  • 传输层是无状态的，不存储成员资格信息。
  • 若 Gateway 离线或配对功能已禁用，节点无法完成配对。
  • 若 Gateway 运行在 remote 模式，配对仍在远端 Gateway 的存储中进行。

常见问题 ​

节点配对请求的过期时间是多少？ ​

待处理请求在 5 分钟后自动过期。过期后，节点需要重新发起配对请求。

如何查看当前有哪些待审批的节点？ ​

在 Gateway 主机上运行 openclaw nodes pending 即可列出所有待处理的配对请求，每个请求有唯一的 requestId。

升级到 2026.3.31 后节点命令不执行怎么办？ ​

确认节点已经完成节点配对（不只是设备配对）。运行 openclaw nodes status 检查节点是否显示为“已配对”。如果节点未配对，使用 openclaw nodes approve <requestId> 批准请求。注意：在批准前排队的所有命令都会被丢弃，不会延迟执行。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策