在线状态
OpenClaw 的 “presence”(在线状态)是一种轻量级、尽力而为的视图,用于展示:
- Gateway 本身,以及
- 连接到 Gateway 的用户可见客户端(mac 应用、WebChat、节点等)。
在线状态会在 Control UI 的 Devices 页面(位于 Settings → Devices 下)以及 macOS 应用的 Instances 标签页中渲染实时连接元数据。
本页介绍 Gateway 客户端列表。若要检测最近使用的 Mac 并将节点告警路由到该设备,请参阅 活动计算机在线状态。
询问代理关于在线状态¶
核心 presence 工具读取当前的人员、其已连接客户端和设备,以及已观察到的活动快照。它在个人和共享 Gateway 上均可使用,无需 shell 访问权限。相同的读取模型也可通过 Gateway RPC 以 presence.query 形式提供。
| 参数 | 含义 |
|---|---|
action |
list(默认值)、person 或 device。 |
person |
使用 person 时必填:me、返回的人员/配置文件 ID,或无歧义的显示名称。 |
deviceId |
使用 device 时必填:由 presence 返回的设备 ID。 |
include |
可选数组,包含 devices、network 和 location。网络和位置详情也会包含设备行。 |
limit |
列表中最多包含的人员数,范围为 1 到 100;默认值为 50。截断结果会被标识。 |
示例:
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 访问权限。受信任的本地操作员轮次、已配置的频道所有者以及操作员拥有的计划任务,在其源权限保持有效时也可以查询在线状态。其他频道调用者以及没有读取权限的请求者拥有的计划任务无法查询列表。该工具不会公开 watched-session 引用,也不会授予设备控制权限。兼容的远程 worker 会将读取转发到其准入的 Gateway;连接到没有在线状态功能的 Gateway 的 worker 会省略该工具。
要从 CLI 查询相同快照:
openclaw gateway call presence.query --params '{"action":"person","person":"me","include":["devices"]}' --json
在线状态字段(显示内容)¶
在线状态条目是结构化对象,包含如下字段:
instanceId(可选但强烈建议提供):稳定的客户端身份(通常为connect.client.instanceId)host:人类可读的主机名clientId:来自已接受连接的客户端类型,与其显示名称分开;人员卡片使用它来区分 Terminal 和原生 Appip:尽力而为的 IP 地址。地理位置插件 会在可用时将其解析为粗略城市version:客户端版本字符串deviceFamily/modelIdentifier:硬件提示timeZone:自报告的 IANA 时区,例如Europe/Vienna。浏览器会在连接期间报告它。当连接 IP 为 loopback、隧道或 CGNAT 时,它仍然有用mode:ui、webchat、cli、backend、node、probe、testlastInputSeconds:自上次用户输入以来的秒数(如果已知)reason:自由格式的客户端提供字符串。Gateway 本身只发出self、connect和disconnectdeviceId、roles、scopes:来自连接握手的设备身份以及角色/范围提示ts:上次在线状态更新时间戳(自 epoch 以来的毫秒数),包括心跳更新。这不是用户活动时间戳onlineSince:已认证人员当前连续在线时段的开始时间,跨重叠连接共享lastActivityAt:该在线时段内最新观察到的已接受交互。在观察到活动之前不存在connectionLastActivityAt:在此确切客户端连接上最新已接受的交互,早于人员级聚合connectionId:Gateway 为当前连接分配的身份watchedSessions:客户端明确声明其正在查看的会话键,针对接收者进行过滤
谁可以查看在线状态¶
在线状态列表会与具有 operator.read 访问权限的操作员共享。operator.write 和 operator.admin 也会授予读取访问权限。读取者可以看到其他人的在线和活动计时以及报告的 timeZone,包括未正在查看会话的人员。节点连接、仅配对的操作员以及其他没有读取权限的连接,会在连接快照中收到空的在线状态列表,并且不会收到 presence 事件。system-presence RPC 需要相同的操作员读取访问权限。
Watched-session references are filtered separately for each recipient using the
same visibility rules as sessions.list. Hidden or missing sessions are omitted
entirely, without counts or placeholders. This filtering applies to connect
snapshots, system-presence responses, and presence events. The person being
viewed does not grant the recipient access to their sessions.
Drafts, incognito sessions, and operator role restrictions follow those list
rules. Missing or deleted references are omitted even for admins. Keys retain
their agent scope, including agent-qualified global and unknown references.
Non-admin readers awaiting authenticated profile verification receive person
metadata but no watched references. Established admin grants retain admin list
visibility. When no references are visible, watchedSessions is omitted.
Message subscriptions alone do not declare viewer presence.
This policy does not change which IP addresses are shared between readers and does not isolate all Gateway metadata. Use separate Gateway trust boundaries when readers must not see each other's presence or other shared metadata.
生产者(在线状态的来源)¶
在线状态条目由多个来源生成并合并。
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 连接。临时控制平面客户端完全被排除在跟踪之外。
Control UI 在显示人员时,按记录的标识命名空间对连接行进行分组。具有相同限定资料标识的连接共享同一个人。具有相同原始 ID 的非限定连接形成一个单独的组。与资料 ID 匹配的原始 ID 永远不会合并它们的已观看会话、连接事实或查看者计数。Gateway 对在线/活动计时和协作输入计数使用相同的命名空间边界。重叠的标签页仅在其命名空间内共享计时事实。如果原始标签页获得资料限定,后续活动仍保持独立。在线名册包括您自己的已连接标识。会话查看者指示器根据已认证用户记录的限定状态排除您,仅当该用户不可用时才使用当前连接。只有具有精确限定资料标识的显示所有者才会从会话的实时查看者中去重。人员卡片 将在线时长和观察到的活动与每个条目的心跳新鲜度分开。
已接受交互(包括输入)会更新该人员每个实时连接上的精确活动时间戳。仅活动在线状态事件按每个标识最多每 30 秒合并一次。首次观察到的活动以及该窗口之后的活动会安排一次发布;连接、断开连接、资料和已观看会话变更共享一个锚定在首个待处理变更上的 200 ms 发布窗口。后续变更不会推迟它。Hello 快照和 system-presence 回复会立即读取当前状态。因此,人员卡片的活动时间可能比最新交互滞后不到 30 秒。新的快照和 system-presence 读取包含最新存储的时间戳。
在线与最近活动¶
已连接的人员为在线。活动是一个独立的最近交互提示:
- 活跃: 已观察到已接受交互发生在不到两分钟前。
- 空闲: 已观察到交互,但它至少已有两分钟。
- 在线但没有活动标签:没有可用的交互时间戳。 人员卡片显示活动不可用,而不是猜测活跃或空闲。
侧边栏会将活跃人员变为空闲,而无需等待另一次 Gateway 更新。卡片将连续在线时长与最近交互分开。UI 活动标签使用某人员所有实时、标识限定的连接中最新的 OpenClaw 交互。心跳和原生输入新鲜度不会决定此标签。agent 的在线状态查询还会公开带有来源的原生设备活动,因此它可以识别最近使用的已连接机器,而不会将原生输入视为与 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 的输出,并根据最后一次更新的时长应用一个小型状态指示器(活跃/空闲/过期)。
调试技巧¶
- 要查看针对你的连接投影的列表,请对 Gateway 调用
system-presence。 - 如果你看到重复项:
- 确认客户端在握手中发送稳定的
client.instanceId - 确认周期性信标使用相同的
instanceId - 检查是否存在多个标签页或重连。不同的用户连接拥有不同的行,旧行会在 TTL 后过期
相关¶
物理 Mac 输入如何选择活动节点并路由连接提醒。
何时发送输入指示器以及如何调整它们。
出站流式传输、分块以及按渠道格式化。
Gateway 组件以及驱动在线状态更新的 WebSocket 协议。
connect、system-event 和 system-presence 的线路协议。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw