网关侧配对（方案 B）

设备与用户配对。谁可以和 agent 对话——以网关为权威来源。在网关侧配对中，网关决定哪些节点可以加入。UI（macOS 应用、未来客户端）只是审批或拒绝待处理请求的前端。

重要：WS 节点在 connect 时使用设备配对（角色 node）。node.pair.* 是独立的配对存储，不会控制 WS 握手。只有显式调用 node.pair.* 的客户端才走这套流程。

概念

• 待处理请求：节点请求加入，需审批。
• 已配对节点：已审批并下发认证 token 的节点。
• 传输层：网关 WS 端点转发请求，但不决定成员资格。（旧版 TCP 桥接已弃用/移除。）

配对流程

1. 节点连接网关 WS 并请求配对。
2. 网关保存待处理请求并发出 node.pair.requested。
3. 你在 CLI 或 UI 中批准或拒绝请求。
4. 批准后，网关下发新 token（重新配对会轮换 token）。
5. 节点用该 token 重连，即视为「已配对」。

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

CLI 流程（无头友好）

moltbot nodes pending
moltbot nodes approve <requestId>
moltbot nodes reject <requestId>
moltbot nodes status
moltbot 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 验证到网关主机。

若静默批准失败，会回退到正常的「批准/拒绝」弹窗。

存储（本地、私有）

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

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

若覆盖 CLAWDBOT_STATE_DIR，nodes/ 目录会随之移动。

安全说明：

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

传输行为

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