OpenClaw 🦞

Presence

Presence

OpenClaw "presence" 是一个轻量级、尽力的视图：

  • Gateway 本身，和
  • 连接到 Gateway 的客户端（mac 应用、WebChat、CLI 等）

Presence 主要用于渲染 macOS 应用的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：上次更新时间戳（毫秒，自纪元）

生产者（presence 来自哪里）

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

1) Gateway 自条目

Gateway 始终在启动时播种"self"条目，因此 UI 在任何客户端连接之前显示 gateway 主机。

2) WebSocket 连接

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

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

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

3) system-event 信标

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

4) Node 连接（role: node）

当节点通过 Gateway WebSocket 连接，带有 role: node 时，Gateway 为该节点 upsert 一个 presence 条目（与其他 WS 客户端相同的流程）。

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

Presence 条目存储在单个内存映射中：

  • 条目按presence 键键控。
  • 最佳键是稳定的 instanceId（来自 connect.client.instanceId），在重启中存活。
  • 键不区分大小写。

如果客户端重新连接而没有稳定的 instanceId，它可能显示为重复行。

TTL 和有界大小

Presence 故意是短暂的：

  • TTL： 超过 5 分钟的条目被修剪
  • 最大条目： 200（最旧优先丢弃）

这保持列表新鲜并避免无界内存增长。

远程/隧道警告（环回 IP）

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

消费者

macOS Instances 标签

macOS 应用渲染 system-presence 的输出，并应用小状态指示器（Active/Idle/Stale），基于上次更新的年龄。

调试技巧

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