在线状态

OpenClaw “presence”（在线状态）是一种轻量级、尽力而为的视图，涵盖：

• Gateway 本身，以及
• 连接到 Gateway 的用户可见客户端（mac 应用、WebChat、节点等）

在线状态会在 Control UI 的 Devices 页面（位于 Settings → Devices 下）以及 macOS 应用的 Instances 选项卡中渲染实时连接元数据。

本页介绍 Gateway 客户端名册。要检测你最近使用的 Mac 并将节点警报路由到该 Mac，请参阅 活动计算机在线状态。

向代理询问在线状态¶

核心 presence 工具读取人员、其已连接客户端和设备以及观察到的活动的当前快照。它在个人和共享 Gateway 上均可使用，且无需 shell 访问权限。相同的读取模型可通过 Gateway RPC 以 presence.query 形式使用。

示例：

{ "action": "list" }

{ "action": "person", "person": "me", "include": ["devices"] }

{ "action": "person", "person": "Alex", "include": ["network", "location"] }

list 包含请求者，并为每个已连接身份返回一行，而不是为每个浏览器标签页返回一行。me 使用发起该轮次的已认证人员，包括在远程 worker 上。歧义名称会返回候选项；未识别的轮次对 me 返回 identity-unavailable。

设备活动会保留其来源：openclaw-interaction、app-input 或 system-input。人员活动摘要会标识与其最新观察到的活动相关联的设备。没有已认证人员关联的设备会保持独立；使用带有 devices 的 list 来检查共享或未识别的机器。浏览器客户端不一定能标识一台物理计算机，且匹配的名称或 IP 地址永远不会建立这种关联。

结果包含 observedAt；缺失的活动为 null，而不是某人处于非活动状态的证据。在线表示已连接，包括空闲标签页。这是实时在线状态，而非保留的活动历史：已断开的设备和之前的 Gateway 进程不会建立历史最后使用的机器。

network 在可用时包含观察到的连接 IP。location 会延迟使用现有的地理位置插件，返回带有来源归属的粗略 IP 地理位置。缺失结果与不可用的提供方是不同的。时区仍由客户端报告；IP 地理位置可能描述的是 VPN 或网络出口。在线状态从不请求 GPS 或更改设备权限。

已认证调用者需要与在线状态名册相同的 operator.read 访问权限。受信任的本地操作员轮次、已配置的频道所有者以及操作员拥有的计划任务，在其源权限保持有效时也可以查询在线状态。其他频道调用者以及没有读取权限的请求者拥有的计划任务无法查询名册。该工具不会公开受监视会话引用，也不会授予设备控制权限。兼容的远程 worker 会将读取转发到其准入 Gateway；连接到不具备 presence 功能的 Gateway 的 worker 会省略该工具。

要从 CLI 查询同一快照：

openclaw gateway call presence.query --params '{"action":"person","person":"me","include":["devices"]}' --json

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

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

• instanceId（可选但强烈建议）：稳定的客户端身份（通常为 connect.client.instanceId）
• host：人类可读的主机名
• clientId：来自已接受连接的客户端类型，与其显示名称分开；人员卡片使用它来区分 Terminal 和原生 App
• ip：尽力而为的 IP 地址。地理位置插件 在可用时会将其解析为粗略城市
• version：客户端版本字符串
• deviceFamily / modelIdentifier：硬件提示
• timeZone：自报告的 IANA 时区，例如 Europe/Vienna。浏览器在连接期间报告它。当连接 IP 为回环、隧道或 CGNAT 时，它仍然有用
• mode：ui、webchat、cli、backend、node、probe、test
• lastInputSeconds：距上次用户输入的秒数（如果已知）
• reason：客户端提供的自由格式字符串。Gateway 本身只发出 self、connect 和 disconnect
• deviceId、roles、scopes：来自连接握手的设备身份以及角色/范围提示
• ts：上次在线状态更新时间戳（自 epoch 起的毫秒数），包括心跳更新。这不是用户活动时间戳
• onlineSince：已认证人员当前连续在线时段的开始时间，在重叠连接之间共享
• lastActivityAt：该在线时段内观察到的最新已接受交互。在观察到活动之前不存在
• connectionLastActivityAt：在此确切客户端连接上观察到的最新已接受交互，早于人员级聚合
• connectionId：Gateway 为当前连接分配的身份
• watchedSessions：客户端明确声明其正在查看的会话键，已针对接收者过滤

谁可以查看在线状态¶

在线状态名册会与具有 operator.read 访问权限的操作员共享。operator.write 和 operator.admin 也授予读取访问权限。读取者可以看到其他人的在线和活动计时以及报告的 timeZone，包括未监视会话的人员。节点连接、仅配对操作员以及其他没有读取权限的连接，在连接快照中会收到空的在线状态名册，并且不会收到 presence 事件。system-presence RPC 需要相同操作员读取访问权限。

被监视会话引用会针对每个接收方单独过滤，使用与 sessions.list 相同的可见性规则。隐藏或缺失的会话会被完全省略，不提供计数或占位符。此过滤适用于 connect 快照、system-presence 响应和在线状态事件。被查看的人不会授予接收方访问其会话的权限。

草稿、隐身会话和运营角色限制遵循这些列表规则。缺失或已删除的引用即使对管理员也会省略。键保留其代理作用域，包括带代理限定的 global 和 unknown 引用。等待已认证资料验证的非管理员读取者会收到人员元数据，但不会收到被监视引用。已建立的管理员授权保留管理员列表可见性。当没有可见引用时，省略 watchedSessions。仅消息订阅不会声明查看者在线状态。

此策略不会改变读取者之间共享哪些 IP 地址，也不会隔离所有 Gateway 元数据。当读取者必须无法看到彼此的在线状态或其他共享元数据时，请使用独立的 Gateway 信任边界。

生产者（在线状态的来源）¶

在线状态条目由多个来源生成并合并。

1) Gateway 自身条目¶

Gateway 始终在启动时播种一个“self”条目，以便 UI 在任何客户端连接之前都能显示 Gateway 主机。

2) WebSocket 连接¶

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

为什么临时控制平面连接不会显示¶

CLI 命令、后端 RPC 客户端和探针通常会短暂连接。为避免将这种频繁变化保留完整的在线状态 TTL，处于 cli、backend 或 probe 模式的客户端不会被转换为在线状态条目。测试模式客户端仍会被跟踪，因为测试套件将它们用作真实客户端的替代。

3) system-event 信标¶

客户端可以通过 system-event 方法发送更丰富的周期性信标。mac 应用使用它来报告主机名、IP、版本和存活元数据。电脑输入活动不属于此通用信标的一部分。活动电脑在线状态 中描述的特定用途原生节点事件负责它。Mac 会为这些信标打上 system-presence-clear-last-input 标签。当前 Gateway 使用该向后兼容标记来移除从旧版应用保留的任何输入新鲜度。该信标还携带一个固定的 30 天值，以便忽略该标签的旧 Gateway 覆盖精确新鲜度，而不是保留它。不会为此兼容值采样新的活动。

4) 节点连接（role: node）¶

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

连接行与信标去重¶

在线状态条目存储在一个使用不区分大小写键的单个内存映射中。用户 WebSocket 客户端每个连接有一行，因此监视不同会话的两个标签页不会相互覆盖。节点连接使用其设备 id，然后是 connect.client.instanceId，然后是连接 id。

system-event 信标在提供时按设备 id 或实例 id 合并，否则按解析出的主机或其他信标元数据合并。稳定的 instanceId 有助于消费者将行关联到同一客户端。它不会合并不同的用户 WebSocket 连接。临时控制平面客户端完全被排除在跟踪之外。

控制 UI 在显示人员时按记录的标识命名空间对连接行进行分组。具有相同带限定资料标识的连接共享同一个人。具有相同原始 ID 的未限定连接形成一个单独的组。与资料 ID 匹配的原始 ID 永远不会合并它们的被监视会话、连接事实或查看者计数。Gateway 对在线/活动计时和协作输入计数使用相同的命名空间边界。重叠标签页仅在其命名空间内共享计时事实。如果原始标签页获得资料限定，后续活动仍保持独立。在线名册包含您自己的已连接标识。会话查看者指示器根据已认证用户记录的限定排除您，仅当该用户不可用时才使用当前连接。只有具有精确带限定资料标识的显示所有者会从会话的实时查看者中去重。人员卡片 将在线时长和观察到的活动与每个条目的心跳新鲜度分开。

已接受的交互（包括输入）会更新该人员每个实时连接上的精确活动时间戳。仅活动在线状态事件按每个标识合并为每 30 秒最多一次。首次观察到的活动以及该窗口之后的活动会安排一次发布；连接、断开连接、资料和被监视会话变更共享一个锚定在首个待处理变更上的 200 毫秒发布窗口。后续变更不会推迟它。Hello 快照和 system-presence 响应会立即读取当前状态。因此，人员卡片的活动年龄可能比最新交互滞后不到 30 秒。新的快照和 system-presence 读取包含最新存储的时间戳。

在线与最近活动¶

已连接的人员为在线。活动是一个独立的最近交互提示：

• 活跃： 观察到已接受的交互发生在不到两分钟前。
• 空闲： 观察到交互，但它至少已有两分钟。
• 在线 但没有活动标签：没有可用的交互时间戳。 人员卡片显示活动不可用，而不是猜测活跃或空闲。

侧边栏会将活跃人员变为空闲，而无需等待另一次 Gateway 更新。卡片将连续在线时长与最近交互分开。UI 活动标签使用某人员实时、带标识限定的连接中最新的 OpenClaw 交互。心跳和原生输入新鲜度不会决定此标签。代理的在线状态查询还会公开带有来源的原生设备活动，因此它可以识别最近使用的已连接机器，而不会将原生输入视为与 OpenClaw 的交互。

Control UI 会上报其初始前台访问以及经过节流的键盘、指针和滚动交互。自动重连、后台标签页、传入消息和后台请求不计为新的交互。不上报交互的客户端仍可能在线。这描述的是 OpenClaw 的最近使用情况，而不是物理在场或注意力：有人阅读但不交互可能会变为空闲。独立的原生活动计算机信号不会识别某个人。

TTL 与有界大小¶

存在状态被有意设计为短暂存在：

• TTL： 超过 5 分钟的条目会被清除
• 最大条目数： 200（最旧的条目先被丢弃）

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

远程/隧道注意事项（回环 IP）¶

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

消费者¶

Control UI 设备页面¶

设备 页面将 system-presence 与持久配对和节点记录关联。它首先固定 Gateway 自身信标，并使用匹配的设备或实例 ID 来获取实时的平台、版本、型号和输入最近性元数据。

macOS 实例选项卡¶

macOS 应用会渲染 system-presence 的输出，并根据上次更新的时长应用一个小状态指示器（Active/Idle/Stale）。

调试技巧¶

• 要查看针对你的连接投影的列表，请对 Gateway 调用 system-presence。
• 如果你看到重复项：
• 确认客户端在握手中发送稳定的 client.instanceId
• 确认周期性信标使用相同的 instanceId
• 检查是否存在多个标签页或重连。不同的用户连接具有不同的行，旧行会在 TTL 后过期

相关¶

活动计算机存在

物理 Mac 输入如何选择活动节点并路由连接警报。

输入指示器

何时发送输入指示器以及如何调整它们。

流式传输与分块

出站流式传输、分块以及按渠道的格式化。

Gateway 架构

Gateway 组件以及驱动存在状态更新的 WebSocket 协议。

Gateway 协议

connect、system-event 和 system-presence 的线路协议。