Presence（在线状态）

OpenClaw 的"presence"是对以下内容的轻量级、尽力而为的视图：

• Gateway 自身，以及
• 连接到 Gateway 的客户端（macOS 应用、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 Beacon

客户端可通过 system-event 方法发送更丰富的周期性 beacon。macOS 应用用此报告主机名、IP 和 lastInputSeconds。

4）Node 连接（role: node）

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

合并 + 去重规则（为何 instanceId 很重要）

Presence 条目存储在一个内存 map 中：

• 条目以presence key为键。
• 最佳 key 是在重启后仍稳定的 instanceId（来自 connect.client.instanceId）。
• Key 不区分大小写。

若客户端在重连时没有稳定的 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
  • 确认周期性 beacon 使用了相同的 instanceId
  • 检查连接派生的条目是否缺少 instanceId（缺少时重复是预期行为）