Gateway 托管的 Pairing（方案 B）

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

重要提示： WS 节点在 connect 时使用的是 device pairing（角色为 node）。node.pair.* 是一个独立的 pairing 存储，不会控制 WS 握手过程。只有显式调用 node.pair.* 的客户端才会使用这个流程。

核心概念

  • 待处理请求（Pending request）：节点请求加入，需要审批。
  • 已配对节点（Paired node）：已批准的节点，拥有颁发的认证 token。
  • 传输层（Transport）：Gateway WS 端点转发请求，但不决定成员资格。（旧版 TCP 桥接支持已弃用/移除。）

Pairing 工作流程

  1. 节点连接到 Gateway WS 并请求配对。
  2. Gateway 存储一个待处理请求并触发 node.pair.requested 事件。
  3. 你通过 CLI 或 UI 批准或拒绝请求。
  4. 批准后，Gateway 会颁发一个新 token（重新配对时 token 会轮换）。
  5. 节点使用 token 重新连接，现在就是”已配对”状态了。

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

CLI 工作流程（支持无界面环境）

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 作为自动批准流程的提示。

自动批准（macOS 应用）

macOS 应用可以在以下情况下尝试静默批准：

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

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

存储（本地、私有）

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

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

如果你覆盖了 OPENCLAW_STATE_DIR，nodes/ 文件夹会跟着移动。

安全提示：

  • Token 是机密信息；要把 paired.json 当作敏感文件对待。
  • 轮换 token 需要重新批准（或删除节点条目）。

传输层行为

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