存在性

OpenClaw "存在性"是一个轻量级、尽力而为的视图,用于查看:

• 网关本身,以及
• 连接到网关的客户端(mac 应用、WebChat、CLI 等)

存在性主要用于渲染 macOS 应用的实例标签页,并为操作员提供快速可见性。

存在性字段(显示内容)

存在性条目是结构化对象,包含以下字段:

• 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) 网关自身条目

网关在启动时始终会播种一个"自身"条目,这样即使在任何客户端连接之前,UI 也会显示网关主机。

2) WebSocket 连接

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

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

CLI 通常为短暂的一次性命令而连接。为避免刷屏实例列表,client.mode === "cli" 不会转换为存在性条目。

3) system-event 信标

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

4) 节点连接(role: node)

当节点通过网关 WebSocket 以 role: node 连接时,网关会为该节点更新插入一个存在性条目(与其他 WS 客户端流程相同)。

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

存在性条目存储在单个内存映射中:

• 条目按存在性键作为键值。
• 最佳键是一个稳定的 instanceId(来自 connect.client.instanceId),能够在重启后保持不变。
• 键不区分大小写。

如果客户端在没有稳定 instanceId 的情况下重新连接,可能会显示为重复行。

TTL 和有界大小

存在性有意设计为临时性的:

• **TTL:**超过 5 分钟的条目将被清除
• **最大条目数:**200(最旧的优先删除)

这使列表保持新鲜并避免无限制的内存增长。

远程/隧道注意事项(回环 IP)

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

消费者

macOS 实例标签页

macOS 应用渲染 system-presence 的输出,并根据最后更新的时间应用小型状态指示器(活动/空闲/过期)。

调试提示

• 要查看原始列表,请对网关调用 system-presence。
• 如果看到重复项:
  • 确认客户端在握手时发送稳定的 client.instanceId
  • 确认周期性信标使用相同的 instanceId
  • 检查连接派生的条目是否缺少 instanceId(预期会有重复)