配对与状态

配对与状态¶

节点使用设备配对。节点在连接期间出示已签名的设备身份；Gateway 会为 role: node 创建设备配对请求。设备批准允许连接；声明的命令面需要单独批准。Apple Watch 直接设置使用由管理员签发的、短时效的仅限节点设置代码，以批准其固定的低风险命令面；后续能力扩展仍需要正常批准。

如需手动批准，请在 Gateway 上运行以下命令：

openclaw devices list
openclaw devices approve <deviceRequestId>

无头节点主机在设备批准待处理期间会持续重连，采用指数退避，上限为 30 秒。批准后，下一次重连会创建一个独立的命令面请求。回到 Gateway：

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

如果较旧的客户端已经报告重连已暂停，请使用 openclaw node restart 重启已安装的节点，或停止并重新运行一次其前台 openclaw node run 命令。对于因手动配对而暂停的应用节点，请重启节点模式或应用。

这两个请求 ID 是不同的。使用 openclaw devices reject <deviceRequestId> 拒绝设备准入，而不是批准它。初始未批准的命令面没有有效命令。在扩展期间，先前已批准的命令仅在节点仍声明它们且 Gateway 策略允许时保持有效。

SSH 验证以及管理员签发的引导注册可以自动批准第一个命令面。仅受信任网络的设备批准不能做到这一点；请检查 nodes pending 并单独批准命令面。后续的命令、能力或权限扩展仍需要批准。命令面批准不会绕过 Gateway 命令策略 或 本地 exec 批准。

待处理的设备配对请求会在设备最后一次重试后 5 分钟过期——持续重连的设备会保持其一个待处理请求（以及 requestId）有效，而不是每隔几分钟生成一个新的配对提示；完整的请求/批准生命周期参见 节点配对。如果节点使用更改后的身份验证详情（role/scopes/公钥）重试，则先前待处理的请求会被取代，并创建新的 requestId——客户端会收到被取代请求的 device.pair.resolved 事件，并且你应在批准前重新运行 openclaw devices list。

待处理的命令面请求不会仅随时间过期；它们遵循 能力批准生命周期。

• nodes status 在节点的设备配对角色包含 node 时，将该节点标记为已配对。
• 已连接的原生 Mac 会在与 OpenClaw 交互时报告合并后的活动，无需额外权限。可选的 设置 -> 权限 -> 系统范围存在检测 还会包括其他应用中的物理输入，并且需要辅助功能。Gateway 会将最新符合条件的 Mac 标记为 active，向代理提供稳定的 node-id 提示，并在延迟回退之前将节点连接警报路由到该 Mac。设置、隐私、时序和故障排除参见 活动计算机存在。
• 设备配对记录是持久的已批准角色契约。Token 轮换保持在该契约之内；它不能将已配对节点升级为配对批准从未授予的角色。
• node.pair.*（CLI：openclaw nodes pending/approve/reject/remove/rename）管理节点在其规范配对设备记录上已批准的命令/能力面。设备配对同时负责传输身份验证和持久的节点面；没有单独的节点配对存储。
• openclaw nodes remove --node <id|name|ip> 会撤销设备在配对设备存储中的 node 角色，并断开该设备的节点角色会话：混合角色设备会保留其行，仅失去 node 角色，而仅限节点的设备行会被删除。operator.pairing 可以移除其他设备上的非 operator 节点行；设备 Token 调用方在混合角色设备上撤销自己的节点角色时，还需要 operator.admin。
• 批准范围遵循待处理请求声明的命令：
• 无命令请求：operator.pairing
• 非 exec 节点命令：operator.pairing + operator.write
• system.run / system.run.prepare / system.which：operator.pairing + operator.admin

无头节点主机在 macOS 和 Linux 上报告硬件型号。

已连接的 CLI 节点主机和 macOS 应用会从连接开始，每 60 秒报告 CPU 数量、负载平均值、内存和主卷磁盘容量。Gateway 会在 node.list 和 node.describe 中将最新快照暴露为 hostStats。收到后，它会将快照保存在配对节点记录上，因此离线节点会继续显示最后已知的统计信息，并保留原始 updatedAtMs。已连接节点使用实时会话统计信息。openclaw nodes status 和 openclaw nodes describe 会显示紧凑的统计信息摘要，并为离线节点显示最后已知时长。Windows 会省略负载平均值，不可用的磁盘容量也会被省略。线上契约参见 节点主机统计。

版本偏差与升级顺序¶

Gateway WebSocket 接受跨越 N-1 协议窗口的已认证节点客户端。因此，当前 v4 Gateway 会在连接同时声明 role: "node" 和 client.mode: "node" 时接受 v3 节点。Operator 和 UI 会话仍必须使用当前协议。

对于分阶段集群升级，请先升级 Gateway，然后升级每个节点。N-1 节点在升级期间仍保持可见且可管理；Gateway 会记录 legacy node protocol accepted 并附带升级建议。配对、设备身份验证、命令允许列表和 exec 批准仍然适用。插件拥有的能力和命令在节点升级到当前协议之前保持隐藏。早于 N-1 的节点需要在重连前进行带外升级。

直接 watchOS HTTPS 传输需要当前协议版本；在启用直接模式之前， 请使用 Gateway 更新手表应用。