在 Gateway 拥有的配对中，Gateway 是允许哪些节点加入的真理来源。UI (macOS 应用程序，未来的客户端) 只是批准或拒绝待处理请求的前端。

重要： WS 节点在 connect 期间使用 设备配对 (角色 node)。 node.pair.* 是一个独立的配对存储，不 限制 WS 握手。 只有显式调用 node.pair.* 的客户端使用此流程。

• 待处理请求: 节点请求加入；需要批准。
• 已配对节点: 具有已颁发认证令牌的已批准节点。
• 传输: Gateway WS 端点转发请求，但不决定成员资格。(已弃用/移除对遗留 TCP 桥接的支持。)

1. 节点连接到 Gateway WS 并请求配对。
2. Gateway 存储 待处理请求 并发出 node.pair.requested。
3. 你批准或拒绝请求 (CLI 或 UI)。
4. 批准后，Gateway 颁发 新令牌 (令牌在重新配对时轮换)。
5. 节点使用令牌重新连接，现在已“配对”。

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

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 显示已配对/连接的节点及其功能。

事件：

• node.pair.requested — 当创建新的待处理请求时发出。
• node.pair.resolved — 当请求被批准/拒绝/过期时发出。

方法：

• node.pair.request — 创建或重用待处理请求。
• node.pair.list — 列出待处理 + 已配对的节点。
• node.pair.approve — 批准待处理请求 (颁发令牌)。
• node.pair.reject — 拒绝待处理请求。
• node.pair.verify — 验证 { nodeId, token }。

注意：

• node.pair.request 对每个节点是幂等的：重复调用返回相同的待处理请求。
• 批准 总是 生成一个新的令牌；node.pair.request 永远不会返回令牌。
• 请求可以包含 silent: true 作为自动批准流程的提示。

macOS 应用程序可以选择尝试 静默批准，当：

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

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

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

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

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

安全说明：

• 令牌是机密的；将 paired.json 视为敏感信息。
• 轮换令牌需要重新批准 (或删除节点条目)。

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