在线状态与事件
How the Gateway reports which nodes are connected, and which server-pushed events reach a given session.
在线状态¶
system-presence返回以设备身份为键的条目,包括deviceId、roles和scopes,因此 UI 即使设备同时以操作员和节点身份连接,也可以为每个设备显示一行。node.list包含可选的lastSeenAtMs和lastSeenReason。已连接 节点会以原因connect报告当前连接时间;已配对节点还可以 通过可信节点事件报告持久的后台在线状态。
原生 macOS 节点还可以发送经过身份验证的 node.presence.activity 事件,
其中包含有界输入空闲时间和可选的 source:app 表示与 OpenClaw 的交互,
system 表示系统范围的物理活动。应用本地报告不需要 Accessibility;系统范围报告需要。
省略 source 时保留旧的系统范围权限要求。Gateway 使用自己的时钟推导活动时间戳,
通过 node.list 和 node.describe 暴露最新连接的 Mac,并向具有读取作用域的客户端广播
node.presence 更新。
当系统范围检测被禁用时,应用会发送 { "action": "clear" },
然后报告任何观察到的应用本地活动。当 Accessibility 权限丢失时,它会
回退到应用本地活动,或者如果未观察到任何活动则清除样本。
Gateway 只针对该确切的已认证节点连接清除时间戳。
早于该已确认动作的 Gateway 会将其返回为未处理,因此 Mac 节点会重新连接一次,
并让断开连接清理移除旧的连接状态。
有关选择、隐私、模型上下文和通知路由行为,请参阅 活动计算机在线状态。
节点主机统计¶
已连接的 CLI 节点主机和 macOS 应用的共享节点主机工作进程会在连接后立即发送资源快照,
然后每 60 秒发送一次。它们调用 node.event,其中 event: "node.host.stats" 和一个对象 payload
(或其在 payloadJSON 中的 JSON 编码):
{
"event": "node.host.stats",
"payload": {
"cpuCount": 8,
"loadAverage": [1.25, 1.1, 0.9],
"memoryTotalBytes": 17179869184,
"memoryFreeBytes": 4294967296,
"diskTotalBytes": 1000000000000,
"diskAvailableBytes": 250000000000
}
}
cpuCount 是 1 到 4096 之间的整数。可选的 loadAverage 包含 1 分钟、5 分钟和 15 分钟平均值,
每个值有限且在 0 到 100000 之间。Windows 没有负载平均值;当三个读数均为零时,主机省略该字段。
内存和磁盘值是非负整数字节,且空闲或可用字节不大于总字节数。在 macOS 上,memoryFreeBytes 包括
可回收的主机内存,因此空闲文件缓存不会被报告为已使用;其他平台保留主机范围的空闲内存读数。
磁盘字段仅当主机能够读取包含其主目录的卷的容量时一起出现,且与工作进程的当前目录无关。
Gateway 只接受来自当前节点连接的更新,并使用自己的接收时间戳记 updatedAtMs;节点从不发送时间戳。
成功的更新会作为 hostStats 出现在 node.list 和 node.describe 中,并使用 dropIfSlow: true
向具有读取作用域的操作员广播 { nodeId, hostStats } 的 node.hostStats。统计信息面向操作员,
不会更新模型可见的节点上下文。收到后,Gateway 会将快照作为 lastHostStats 持久化到已配对节点记录上。
断开连接或重新连接但没有新快照时,会保留之前的值。
node.list 和 node.describe 在连接时使用实时会话统计信息,并在离线时将保存的快照投影为 hostStats,
同时保留其原始 updatedAtMs,以便客户端显示最后已知的时长。
结构化的 node.event 结果使用 reason: "updated"、"stale_connection" 或 "invalid_payload"。
较旧的 Gateway 可能返回 handled: false;节点会继续以正常频率运行,而不会立即重试。
节点后台存活事件¶
节点调用 node.event,其中 event: "node.presence.alive",以记录已配对节点在后台唤醒期间处于存活状态,
而不将其标记为已连接:
{
"event": "node.presence.alive",
"payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}
trigger 是封闭枚举:background、silent_push、bg_app_refresh、significant_location、
manual、connect。未知值会规范化为 background(src/shared/node-presence.ts)。
该事件仅对已认证的节点设备会话持久化;无设备或未配对会话返回 handled: false。
成功的 Gateway 返回结构化结果:
较旧的 Gateway 可能仅对 node.event 返回 { "ok": true };应将其视为已确认的 RPC,
而不是持久的在线状态持久化。
广播事件作用域¶
服务器推送的广播事件会进行作用域门控,因此配对作用域或仅限节点的会话不会被动接收会话内容
(src/gateway/server-broadcast.ts):
- 聊天、agent 和工具结果帧(流式
agent事件、工具结果事件)至少需要operator.read。 没有该权限的会话会完全跳过这些帧。 - 插件定义的
plugin.*广播默认门控到operator.write或operator.admin; 诸如plugin.approval.requested/plugin.approval.resolved的显式条目则使用operator.approvals。 - 在线状态事件需要操作员读取访问权限(
operator.read,也可由operator.write或operator.admin满足)。监视的会话引用会为每个接收者过滤,包括在 hello 快照和system-presence回复中。 - 诸如
heartbeat和tick的传输事件对所有已认证会话保持可用。 - 未知广播事件族默认进行作用域门控(失败关闭),除非已注册的处理程序明确放宽它们。
每个客户端连接都维护自己的每客户端序列号,因此即使不同客户端看到事件流中不同的经过作用域过滤的子集,广播在该套接字上仍保持单调有序。
hello-ok.features.capabilities 通告增量式线路契约。原生客户端仅在存在 session-scoped-chat-metadata 时,才会在 chat.metadata 中发送 sessionKey;否则,它们保留由稳定版 v2026.7.1-2 支持的仅代理请求。该旧响应描述的是代理全局可用性,而非某个会话所选的配置。仅当最低受支持的 Gateway 契约保证会话级元数据时,才应退役此协商。仅方法或事件的存在并不足够。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw