OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

网关

节点配对

节点配对分为两层，二者都存储在 Gateway 网关 SQLite 状态数据库的已配对设备记录中：

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

以前独立的节点配对存储（nodes/paired.json，其中包含每个节点的 令牌，已于 2026 年 1 月从连接路径中停用）现已移除：Gateway 网关会在启动时一次性将 所有剩余记录合并到设备记录中，并使用 .migrated 后缀归档 旧文件。旧版 TCP 桥接支持也已移除。

能力批准的工作原理

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

待处理请求会在节点上次重试后的 5 分钟自动过期——持续主动重新连接的节点会使其唯一的待处理请求保持有效， 而不会在每次尝试时都生成新请求（以及批准提示）。

CLI 工作流（适用于无头环境）

bash
openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw 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 - 重命名已配对节点面向操作员显示的名称。

已于 2026.7 移除：node.pair.request 和 node.pair.verify。待处理 请求现在由 Gateway 网关在节点连接期间自行创建，而它们过去所服务的 独立单节点令牌已不存在；节点身份验证使用 设备配对令牌。

注意：

  • 使用未变化表面进行重新连接时会复用待处理请求；重复 请求会刷新已存储的节点元数据，以及最新的已列入允许列表的 声明命令快照，供操作员查看。
  • 操作员权限范围级别和批准时检查的摘要请参阅 操作员权限范围。
  • node.pair.approve 使用待处理请求中声明的命令来强制执行 额外的批准权限范围：
    • 无命令请求：operator.pairing
    • 非 Exec 命令请求：operator.pairing + operator.write
    • system.run / system.run.prepare / system.which 请求： operator.pairing + operator.admin

节点命令门控（2026.3.31+）

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

这意味着：

  • 以前仅依靠设备配对来公开命令的节点，现在 还必须完成节点配对。
  • 在配对批准前排队的命令会被丢弃，而不会延后执行。

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

源自节点的摘要和相关会话事件仅限于 预期的受信任表面。以前依赖更广泛主机或会话工具访问权限的通知驱动或节点触发流程 可能需要调整。 此项加固可防止节点事件突破节点信任边界所允许的范围， 升级为主机级工具访问权限。

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

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

当来自私有/CGNAT 地址的 role: node 设备首次请求配对时， 如果 Gateway 网关能够通过 SSH 证明机器所有权，则会自动批准：它会 反向连接到配对主机（BatchMode、StrictHostKeyChecking=yes）， 在该主机上运行 openclaw node identity --json，并且仅当远程 设备 ID 和公钥与待处理请求完全匹配时才批准。密钥匹配 使这一流程具备安全性：仅可访问绝不会触发批准，因此 NAT 共同租户、 共享主机上的其他用户以及局域网欺骗都会转入常规 提示流程。

默认启用。触发要求：

  • Gateway 网关进程用户（或 sshVerify.user）能够以非交互方式通过 SSH 连接节点主机 （使用密钥/智能体；Tailscale SSH 也可用），并且主机密钥 已受信任。
  • 在非交互式 sh -lc 中，远程 PATH 可以解析到 openclaw。
  • 连接 IP 是直接连接（未经过代理、非环回）的私有、ULA、 链路本地或 CGNAT 地址，或者在设置 sshVerify.cidrs 后与其匹配。
  • 适用资格下限与受信任 CIDR 批准相同：仅限全新且未请求权限范围的节点 配对；升级、浏览器、Control UI 和 WebChat 始终需要提示。

探测运行期间，节点客户端会被告知继续重试 （wait_then_retry），而不是暂停并等待手动批准；如果探测 失败，下一次尝试将回退到常规提示流程。失败目标 会进入短暂冷却期（密钥不匹配后 5 分钟）。

获批准的设备会记录 approvedVia: "ssh-verified"，并在同一步骤中批准其首次声明的 能力表面——密钥匹配已经证明 节点以操作员账户在其拥有的机器上运行，这与 手动能力批准所确认的主张相同。之后的表面升级仍需 提示。

加固或禁用：

json5
{  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 应用可以尝试静默批准节点能力请求：

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

如果静默批准失败，则回退到常规 Approve/Reject 提示。

受信任 CIDR 设备自动批准

role: node 的 WS 设备配对默认仍需手动完成。对于 Gateway 网关已信任网络路径的私有节点 网络，操作员可以通过显式 CIDR 或精确 IP 选择启用：

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

安全边界：

  • 未设置 gateway.nodes.pairing.autoApproveCidrs 时禁用。
  • 不存在覆盖整个局域网或私有网络的自动批准模式；上文的 SSH 验证 自动批准要求设备密钥通过加密匹配，绝不会 仅凭网络位置批准。
  • 只有全新的 role: node 设备配对请求且未请求任何权限范围时 才符合条件。
  • 操作员、浏览器、Control UI 和 WebChat 客户端仍需手动批准。
  • 角色、权限范围、元数据和公钥升级仍需手动批准。
  • 同主机环回受信任代理标头路径不符合条件，因为该 路径可能被本地调用方伪造。

静默配对取代清理

非交互式批准会在已配对设备记录中记录其来源： 同主机本地策略批准记录为 silent，受信任 CIDR 节点批准记录为 trusted-cidr，SSH 验证节点批准记录为 ssh-verified。状态目录是临时性的客户端（临时主目录、 容器、每次运行独立的沙箱）会在每次运行时生成全新的设备密钥对，并且每次 运行都会作为全新设备静默重新配对——如果不清理，已配对列表 每次运行都会增加一条过时记录。

当 Gateway 网关静默批准一个本地设备配对时，它会停用 属于同一客户端集群（clientId、clientMode 和显示名称均匹配）且当前 未连接的旧 silent 批准记录。本地客户端运行在 Gateway 网关主机本身， 因此该集群键不可能与其他机器匹配。已停用记录的令牌会立即失效； 所有匹配的旧版节点配对条目都会被清除，并广播一个 node.pair.resolved 移除事件。

边界：

  • 只有最近一次批准来自同主机本地（silent）的记录 才能作为触发记录和目标记录。受信任 CIDR 和 SSH 验证配对 跨越不同主机，而显示元数据并非机器身份，因此它们 绝不会被自动移除——请使用 Control UI 清理功能或 openclaw nodes remove 移除这些记录。
  • 所有者批准以及二维码/设置代码（引导）配对绝不会被 自动移除。在来源记录机制出现之前获批准的记录仍受保护， 即使同一设备 ID 后来再次通过静默方式获批准也是如此。
  • 当前已连接的设备会被跳过，因此使用不同状态目录的并发本地会话 在存活期间会保留其令牌。最近一分钟内获批准的记录 也会被跳过，以免同时进行的配对握手 在连接注册前相互停用对方。
  • 受影响的客户端按设计均为本地客户端，因此会在 下次连接时静默重新配对。

元数据升级自动批准

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

二维码配对辅助工具

/pair qr 会将配对载荷呈现为结构化媒体，以便移动端和浏览器客户端直接扫描。

删除设备时，还会清除该设备 ID 对应的所有过期待处理配对请求，因此撤销设备后，nodes pending 不会显示孤立记录。

本地性与转发请求头

仅当原始套接字和所有上游代理证据均表明连接来自回环地址时，Gateway 网关配对才会将其视为回环连接。如果请求通过回环地址到达，但携带 Forwarded、任何 X-Forwarded-* 或 X-Real-IP 请求头证据，则这些转发请求头证据会使回环本地性声明失效，配对流程将要求明确批准，而不会静默地将该请求视为同一主机上的连接。有关操作员身份验证的等效规则，请参阅受信任代理身份验证。

存储（本地、私有）

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

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

如果覆盖 OPENCLAW_STATE_DIR，数据库也会随之迁移。从使用 JSON 存储的版本升级而来的 Gateway 网关会在启动时导入这些数据，并保留 devices/*.json.migrated 和 nodes/*.json.migrated 归档。

安全说明：

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

传输行为

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

相关内容

Was this useful?
On this page

On this page