跳转到主要内容

​
Presence

OpenClaw”在线状态”是以下内容的轻量级、尽力而为的视图：
  • Gateway 网关本身，以及
  • 连接到 Gateway 网关的客户端（mac 应用、WebChat、CLI 等）
在线状态主要用于渲染 macOS 应用的实例标签页，并为运维人员提供快速可见性。

​
Presence fields (what shows up)

在线状态条目是具有以下字段的结构化对象：
  • instanceId（可选但强烈推荐）：稳定的客户端身份（通常是 connect.client.instanceId）
  • host：人类友好的主机名
  • ip：尽力而为的 IP 地址
  • version：客户端版本字符串
  • deviceFamily / modelIdentifier：硬件提示
  • mode：ui、webchat、cli、backend、probe、test、node，…
  • lastInputSeconds：“自上次用户输入以来的秒数”（如果已知）
  • reason：self、connect、node-connected、periodic，…
  • ts：最后更新时间戳（自纪元以来的毫秒数）

​
生产者（在线状态来源）

在线状态条目由多个来源生成并合并。

​
1）Gateway 网关自身条目

Gateway 网关始终在启动时植入一个”self”条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway 网关主机。

​
2）WebSocket 连接

每个 WS 客户端都以 connect 请求开始。在成功握手后，Gateway 网关为该连接更新插入一个在线状态条目。 On successful handshake the Gateway upserts a presence entry for that connection.

​
为什么一次性 CLI 命令不会显示

  1. CLI 通常用于短暂的一次性命令连接。 3. 为了避免刷屏 Instances 列表，client.mode === "cli" 不会 被转换为 presence 条目。

​
3）system-event 信标

  1. 客户端可以通过 system-event 方法发送更丰富的周期性信标。 6. mac 应用使用它来上报主机名、IP 以及 lastInputSeconds。

​
4）节点连接（role: node）

当节点通过 Gateway 网关 WebSocket 以 role: node 连接时，Gateway 网关为该节点更新插入一个在线状态条目（与其他 WS 客户端流程相同）。

​
合并 + 去重规则（为什么 instanceId 很重要）

在线状态条目存储在单个内存映射中：
  • 条目以在线状态键为索引。
  • 最佳键是稳定的 instanceId（来自 connect.client.instanceId），它在重启后仍然有效。
  • 键不区分大小写。
如果客户端在没有稳定 instanceId 的情况下重新连接，它可能会显示为重复行。

​
TTL 和有界大小

  1. Presence 被刻意设计为短暂存在：
  • TTL： 超过 5 分钟的条目会被修剪
  • 最大条目数： 200（最旧的优先删除）
这使列表保持新鲜并避免无限制的内存增长。

​
远程/隧道注意事项（回环 IP）

当客户端通过 SSH 隧道/本地端口转发连接时，Gateway 网关可能会看到远程地址为 127.0.0.1。为避免覆盖客户端报告的有效 IP，回环远程地址会被忽略。 22. 为了避免覆盖客户端自行上报的有效 IP，会忽略回环的远端地址。

​
消费者

​
macOS 实例标签页

macOS 应用渲染 system-presence 的输出，并根据最后更新的时间应用一个小的状态指示器（活跃/空闲/过期）。

​
26. 调试提示

  • 要查看原始列表，对 Gateway 网关调用 system-presence。
  • 如果你看到重复项：
    • 确认客户端在握手中发送稳定的 client.instanceId
    • 确认周期性信标使用相同的 instanceId
    • 检查连接派生的条目是否缺少 instanceId（这种情况下重复是预期的）