跳转至

在线状态与事件

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 返回结构化结果:

{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}

较旧的 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