Gateway-owned pairing（Option B）

在 Gateway-owned pairing 中，Gateway 是“哪些 nodes 允许加入”的事实来源（source of truth）。UI（macOS app、未来客户端）只是用于批准或拒绝 pending requests 的前端。

重要： WS nodes 在 connect 时使用 device pairing（role node）。 node.pair.* 是一套独立的配对存储，并 不会 约束 WS 握手。 只有显式调用 node.pair.* 的客户端才会走本流程。

概念

• Pending request：某个 node 请求加入；需要审批。
• Paired node：已批准且已签发 auth token 的 node。
• Transport：Gateway WS 端点负责转发请求，但不决定成员资格。（旧版 TCP bridge 支持已 deprecated/removed。）

配对如何工作

1. node 连接到 Gateway WS 并请求配对。
2. Gateway 存储一个 pending request，并发出 node.pair.requested。
3. 你批准或拒绝该请求（CLI 或 UI）。
4. 批准后，Gateway 会签发一个 新 token（重新配对会轮换 token）。
5. node 使用 token 重新连接，此时它就“已配对”。

Pending requests 会在 5 分钟 后自动过期。

CLI 工作流（适合 headless）

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 会显示已配对/已连接的 nodes 及其 capabilities。

API 面（gateway protocol）

Events：

• node.pair.requested — 创建新的 pending request 时触发。
• node.pair.resolved — 当请求被批准/拒绝/过期时触发。

Methods：

• node.pair.request — 创建或复用一个 pending request。
• node.pair.list — 列出 pending + paired nodes。
• node.pair.approve — 批准 pending request（签发 token）。
• node.pair.reject — 拒绝 pending request。
• node.pair.verify — 校验 { nodeId, token }。

备注：

• node.pair.request 对每个 node 是幂等的：重复调用会返回同一个 pending request。
• 批准操作 总是 生成一个新 token；node.pair.request 不会 返回 token。
• 请求可以带 silent: true 作为自动批准流程的提示。

自动批准（macOS app）

当满足以下条件时，macOS app 可以选择尝试一次 静默批准（silent approval）：

• 请求被标记为 silent，并且
• app 能以同一用户验证到 gateway host 的 SSH 连接。

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

存储（本地、私有）

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

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

如果你覆盖了 OPENCLAW_STATE_DIR，nodes/ 文件夹也会随之移动。

安全备注：

• Tokens 属于敏感信息；请把 paired.json 当作敏感文件处理。
• 轮换 token 需要重新审批（或删除该 node 条目）。

传输行为

• 传输层是 无状态的；它不存储成员资格。
• 如果 Gateway 离线或配对被禁用，nodes 将无法配对。
• 如果 Gateway 处于 remote mode，配对仍会针对远端 Gateway 的存储进行。