Gateway(网关) 网关拥有的配对

Gateway(网关) 网关拥有型配对（选项 B）

在 Gateway(网关) 网关拥有型配对中，Gateway(网关) 网关是决定允许哪些节点加入的唯一事实来源。UI（macOS 应用、未来的客户端）只是用于批准或拒绝待处理请求的前端。

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

概念

待处理请求：请求加入的节点；需要批准。
已配对节点：已获批准且拥有已颁发身份验证令牌的节点。
传输：Gateway(网关) 网关 WebSocket 端点转发请求但不决定成员资格。（传统 TCP 桥接支持已被弃用/移除。）

配对如何工作

节点连接到 Gateway(网关) 网关 WebSocket 并请求配对。
Gateway(网关) 存储一个 pending request 并发出 node.pair.requested。
您批准或拒绝该请求（CLI 或 UI）。
批准后，Gateway(网关) 会颁发一个新令牌（令牌在重新配对时会轮换）。
节点使用该令牌重新连接，此时已“配对”。

待处理请求会在 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 — 批准待处理请求（颁发令牌）。
node.pair.reject — 拒绝待处理请求。
node.pair.verify — 验证 { nodeId, token }。

注意事项：

node.pair.request 针对每个节点是幂等的：重复调用返回相同的待处理请求。
对同一待处理节点的重复请求也会刷新存储的节点元数据，以及最新的已列入允许列表的声明命令快照，以便操作员查看。
批准始终会生成一个新的令牌；永远不会从 node.pair.request 返回任何令牌。
请求可以包含 silent: true 作为自动批准流程的提示。

重要提示：

节点配对是一个信任/身份流程加上令牌颁发。
它不锁定每个节点的实时节点命令表面。
实时节点命令来自节点在连接时声明的内容，并在应用网关的全局节点命令策略 (gateway.nodes.allowCommands / denyCommands) 之后。
每个节点的 system.run 允许/询问策略位于节点的 exec.approvals.node.* 中，而不在配对记录中。

节点命令门控 (2026.3.31+)

当节点首次连接时，会自动请求配对。在配对请求获得批准之前，来自该节点的所有待处理节点命令都将被过滤，并且不会执行。一旦通过配对批准建立了信任，节点的声明命令将变为可用，但需遵循正常的命令策略。

这意味着：

以前仅依赖设备配对来暴露命令的节点现在必须完成节点配对。
在配对批准之前排队的命令将被丢弃，而不是延迟。

节点事件信任边界 (2026.3.31+)

节点发起的摘要和相关会话事件被限制在预期的可信表面上。以前依赖更广泛的主机或会话工具访问的通知驱动或节点触发的流程可能需要进行调整。这种强化确保节点事件无法升级到超出节点信任边界允许的主机级工具访问。

自动批准 (macOS 应用)

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

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

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

存储（本地，私有）

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

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

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

安全说明：

令牌是秘密；请将 paired.json 视为敏感信息。
轮换令牌需要重新批准（或删除节点条目）。

传输行为

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