Gateway 自管配对（Option B）

在 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 操作流程（无头友好）

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 连接。

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

存储（本地私有）

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

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

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

安全注意事项：

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

传输层行为

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