跳转到主要内容

​
Presence

OpenClaw “presence” 是一个轻量级、尽力而为的视图:
  • Gateway 本身,以及
  • 连接到 Gateway 的客户端(mac app、WebChat、CLI 等)
Presence 主要用于渲染 macOS app 的 Instances 选项卡并提供快速操作员可见性。

​
Presence 字段(显示什么)

Presence 条目是具有以下字段的结构化对象:
  • 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: 上次更新时间戳(自 epoch 以来的 ms)

​
生产者(presence 来自何处)

Presence 条目由多个来源生成并 合并。

​
1) Gateway self 条目

Gateway 始终在启动时播种”self”条目,以便 UIs 即使在任何客户端连接之前也显示 gateway 主机。

​
2) WebSocket connect

每个 WS 客户端都以 connect 请求开始。成功握手后,Gateway 为该连接 upserts presence 条目。

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

CLI 通常为短暂的一次性命令连接。为了避免垃圾 Instances 列表,client.mode === "cli" 不 转换为 presence 条目。

​
3) system-event beacons

客户端可以通过 system-event 方法发送更丰富的定期 beacons。mac app 使用它来报告主机名、IP 和 lastInputSeconds。

​
4) Node connects (role: node)

当 node 通过 Gateway WebSocket 以 role: node 连接时,Gateway 为该 node upserts presence 条目(与其他 WS 客户端相同的流程)。

​
合并 + 去重规则(为什么 instanceId 很重要)

Presence 条目存储在单个内存映射中:
  • 条目由 presence key 键控。
  • 最好的键是稳定的 instanceId(来自 connect.client.instanceId),它在重启后仍然存在。
  • 键不区分大小写。
如果客户端在没有稳定 instanceId 的情况下重新连接,它可能会显示为 重复 行。

​
TTL 和有界大小

Presence 有意是短暂的:
  • TTL: 超过 5 分钟的条目被修剪
  • 最大条目数: 200(最旧的首先删除)
这使列表保持新鲜并避免无界内存增长。

​
远程/隧道警告(loopback IPs)

当客户端通过 SSH 隧道 / 本地端口转发连接时,Gateway 可能会将远程地址视为 127.0.0.1。为了避免覆盖良好的客户端报告的 IP,忽略 loopback 远程地址。

​
消费者

​
macOS Instances 选项卡

macOS app 渲染 system-presence 的输出,并根据上次更新的年龄应用小状态指示器(Active/Idle/Stale)。

​
调试提示

  • 要查看原始列表,对 Gateway 调用 system-presence。
  • 如果你看到重复:
    • 确认客户端在握手中发送稳定的 client.instanceId
    • 确认定期 beacons 使用相同的 instanceId
    • 检查连接派生的条目是否缺少 instanceId(预期重复)