配对与状态
配对 + 状态¶
节点采用设备配对。节点在连接时出示经过签名的设备身份;Gateway 会为 role: node 创建设备配对请求。设备审批通过后允许连接;所声明的命令面还需要单独审批。直接 Apple Watch 设置使用管理员签发的、短期有效的仅节点设置代码来批准其固定的低风险命令面;后续能力扩展仍需要常规审批。
如需手动审批,请在 Gateway 上运行以下命令:
无头节点主机在设备审批挂起期间会持续重连,指数退避上限为 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。
挂起的命令面请求不会仅因时间而过期;它们遵循能力审批生命周期。
- 当节点的设备配对角色包含
node时,nodes status将其标记为已配对。 - 已连接的原生 Mac 无需额外权限即可报告与 OpenClaw 交互产生的合并活动。可选的设置 -> 权限 -> 系统级存在检测还会包括其他应用中的物理输入,并且需要辅助功能权限。Gateway 将最近活跃的符合条件的 Mac 标记为
active,为代理提供稳定的节点 ID 提示,并在延迟回退前将节点连接警报路由到该 Mac。设置、隐私、时机和故障排查请参阅活动电脑存在检测。 - 设备配对记录是持久的已批准角色契约。Token 轮换保持在该契约之内;它不能将已配对节点升级为配对审批从未授予的角色。
node.pair.*(CLI:openclaw nodes pending/approve/reject/remove/rename)在节点的规范配对设备记录上管理其已批准的命令/能力面。设备配对同时负责传输认证和持久的节点命令面;不存在独立的节点配对存储。openclaw nodes remove --node <id|name|ip>会撤销设备在配对设备存储中的node角色,并断开该设备的 node 角色会话:混合角色设备保留其行,仅失去node角色;而仅节点设备则删除整行。operator.pairing可以删除其他设备上的非 operator 节点行;设备 Token 调用者在混合角色设备上撤销自己的 node 角色时,还需要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 数量、平均负载、内存和 home 卷磁盘容量。Gateway 将最新快照以 hostStats 形式暴露在 node.list 和 node.describe 中。Gateway 收到后,会将快照保存到配对节点记录上,因此离线节点会继续显示上次已知的统计信息,连同原始的 updatedAtMs。已连接节点使用实时会话统计。openclaw nodes status 和 openclaw nodes describe 显示紧凑的统计摘要,并为离线节点标明最后已知数据的时效。Windows 省略平均负载,无法获取的磁盘容量也会被省略。线协议细节请参阅节点主机统计。
版本偏差与升级顺序¶
Gateway WebSocket 接受 N-1 协议窗口内的已认证节点客户端。因此,当连接同时声明 role: "node" 和 client.mode: "node" 时,当前 v4 Gateway 接受 v3 节点。Operator 和 UI 会话仍必须使用当前协议。
对于分阶段的节点群升级,请先升级 Gateway,然后再升级每个节点。N-1 节点在升级期间保持可见且可管理;Gateway 会记录 legacy node protocol accepted 并附上升级建议。配对、设备认证、命令允许列表和 exec 审批仍然适用。插件拥有的能力和命令保持隐藏,直到节点升级到当前协议。早于 N-1 的节点需要先进行带外升级才能重新连接。
watchOS 直接 HTTPS 传输需要当前协议版本;在启用直接模式之前, 请使用 Gateway 更新 watch 应用。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw