网关管理的配对（Option B）

在这种模式下，网关是节点准入的唯一权威。UI（macOS 应用、未来的客户端）只是前端，负责批准或拒绝待处理的请求。

注意： WS 节点在 connect 时使用的是设备配对（角色 node）。node.pair.* 是一套独立的配对存储，不会限制 WS 握手。只有主动调用 node.pair.* 的客户端才走这个流程。

概念

待处理请求：节点请求加入，需要批准。
已配对节点：已批准的节点，持有签发的 auth token。
传输层：网关 WS 端点转发请求，但不做成员管理决策。（旧的 TCP 桥接已废弃/移除。）

配对流程

节点连接到网关 WS 并请求配对。
网关存储待处理请求并发出 node.pair.requested 事件。
你通过 CLI 或 UI 批准或拒绝请求。
批准后，网关签发新 token（重新配对时 token 会轮换）。
节点使用新 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 接口（网关协议）

事件：

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，且
应用能通过同一用户的 SSH 连接验证到网关主机。

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

存储（本地私有）

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

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

如果你覆盖了 OPENCLAW_STATE_DIR，nodes/ 目录也随之移动。

安全说明：

Token 是敏感信息，paired.json 应视为机密文件。
轮换 token 需要重新批准（或删除节点条目）。

传输层行为

传输层是无状态的，不存储成员关系。
网关离线或配对功能被禁用时，节点无法配对。
网关处于远程模式时，配对仍然针对远程网关的存储进行。