在线状态

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、node、probe、test
• lastInputSeconds：自上次用户输入以来经过的秒数（如果已知）
• reason：客户端提供的自由格式字符串；Gateway 网关 本身只会发出 self、connect 和 disconnect
• deviceId、roles、scopes：来自连接握手的设备身份以及角色/权限范围提示
• ts：上次更新时间戳（自纪元以来的毫秒数）

​

生产者（Presence 来源）

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

​

1) Gateway 网关自身条目

Gateway 网关始终会在启动时播种一个 “self” 条目，因此即使还没有任何客户端连接，UI 也会显示网关主机。

​

2) WebSocket 连接

每个 WS 客户端都会以 connect 请求开始。握手成功后，Gateway 网关会为该连接更新或插入一个 Presence 条目。

​

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

CLI 经常为了短暂的一次性命令而连接。为了避免刷屏 Instances 列表，client.mode === "cli" 不会转换为 Presence 条目。

​

3) system-event 信标

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

​

4) 节点连接（角色：node）

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

​

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

Presence 条目存储在单个内存映射中，键不区分大小写，并按顺序使用第一个可用值：已配对设备 ID、connect.client.instanceId，或作为最后手段的每连接 ID。 CLI 客户端会被完全排除在跟踪之外（见上文），因此它们的连接 ID 永远不会成为键。对于其他所有客户端，连接 ID 回退意味着如果客户端在没有稳定 instanceId 的情况下重新连接，会显示为重复行。

​

TTL 和有界大小

Presence 有意设计为临时数据：

• TTL： 超过 5 分钟的条目会被剪除
• 最大条目数： 200（最旧的优先删除）

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

​

远程/隧道注意事项（loopback IP）

当客户端通过 SSH 隧道 / 本地端口转发连接时，Gateway 网关看到的远程地址可能是 127.0.0.1。为避免把该隧道地址记录为客户端的 IP，连接处理会对检测为本地（loopback）的客户端完全省略 ip，而不是把 loopback 地址写入条目。

​

消费者

​

macOS Instances 标签页

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

​

调试提示

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

​

相关