OpenClaw 白皮书

Gateway 网关拥有的配对（选项 B）

在 Gateway 网关拥有的配对中，Gateway 网关是允许哪些节点加入的唯一信息源。UI（macOS 应用、未来的客户端）只是审批或拒绝待处理请求的前端。
重要：WS 节点在 connect 期间使用设备配对（角色 node）。node.pair.* 是一个独立的配对存储，不会限制 WS 握手。只有显式调用 node.pair.* 的客户端使用此流程。

概念

  • ✦待处理请求：一个节点请求加入；需要审批。
  • ✦已配对节点：已批准的节点，带有已颁发的认证令牌。
  • ✦传输层：Gateway 网关 WS 端点转发请求但不决定成员资格。（旧版 TCP 桥接支持已弃用/移除。）

配对工作原理

  1. ✦节点连接到 Gateway 网关 WS 并请求配对。
  2. ✦Gateway 网关存储一个待处理请求并发出 node.pair.requested。
  3. ✦你审批或拒绝该请求（CLI 或 UI）。
  4. ✦审批后，Gateway 网关颁发一个新令牌（重新配对时令牌会轮换）。
  5. ✦节点使用该令牌重新连接，现在是"已配对"状态。
待处理请求在 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 — 批准待处理请求（颁发令牌）。
  • ✦node.pair.reject — 拒绝待处理请求。
  • ✦node.pair.verify — 验证 { nodeId, token }。
注意事项：
  • ✦node.pair.request 对每个节点是幂等的：重复调用返回相同的待处理请求。
  • ✦审批总是生成新的令牌；node.pair.request 永远不会返回令牌。
  • ✦请求可以包含 silent: true 作为自动审批流程的提示。

自动审批（macOS 应用）

当满足以下条件时，macOS 应用可以选择尝试静默审批：
  • ✦请求标记为 silent，且
  • ✦应用可以使用相同用户验证到 Gateway 网关主机的 SSH 连接。
如果静默审批失败，则回退到正常的"批准/拒绝"提示。

存储（本地，私有）

配对状态存储在 Gateway 网关状态目录下（默认 ~/.openclaw）：
  • ✦~/.openclaw/nodes/paired.json
  • ✦~/.openclaw/nodes/pending.json
如果你覆盖了 OPENCLAW_STATE_DIR，nodes/ 文件夹会随之移动。
安全注意事项：
  • ✦令牌是机密信息；将 paired.json 视为敏感文件。
  • ✦轮换令牌需要重新审批（或删除节点条目）。

传输层行为

  • ✦传输层是无状态的；它不存储成员资格。
  • ✦如果 Gateway 网关离线或配对被禁用，节点无法配对。
  • ✦如果 Gateway 网关处于远程模式，配对仍然针对远程 Gateway 网关的存储进行。