在线状态（Presence）

OpenClaw"在线状态（presence）"是一个轻量级、尽力而为的视图，包括：

  • **网关（Gateway）**本身，以及
  • 连接到网关的客户端（Mac 应用、WebChat、CLI 等）

在线状态主要用于渲染 macOS 应用的**实例（Instances）**选项卡，并提供快速的操作员可见性。

在线状态字段（显示的内容）

在线状态条目是结构化对象，包含以下字段：

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

网关在启动时始终生成一个"self"条目，以便 UI 即使在没有客户端连接之前也显示网关主机。

2）WebSocket 连接

每个 WebSocket 客户端都以 connect 请求开始。握手成功后，网关为该连接插入或更新在线状态条目。

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

CLI 通常连接进行短暂的一次性命令。为了避免垃圾邮件实例列表，client.mode === "cli" 不会转换为在线状态条目。

3）system-event 信标

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

4）节点连接（role: node）

当节点通过网关 WebSocket 以 role: node 连接时，网关为该节点插入或更新在线状态条目（与其他 WebSocket 客户端流程相同）。

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

在线状态条目存储在单个内存映射中：

  • 条目由**在线状态键（presence key）**键控。
  • 最佳键是来自 connect.client.instanceId 的稳定 instanceId，可以在重启后保持不变。
  • 键不区分大小写。

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

TTL 和有界大小

在线状态是有意短暂的：

  • **TTL：**超过 5 分钟的条目会被清除
  • **最大条目：**200（最旧的首先删除）

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

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

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

消费者

macOS 实例（Instances）选项卡

macOS 应用渲染 system-presence 的输出，并根据最后更新的年龄应用一个小的状态指示器（活跃/空闲/过时）。

调试提示

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