状态
How OpenClaw presence entries are produced, merged, and displayed
OpenClaw "presence" is a lightweight, best-effort view of:
- 网关自体、以及
- clients connected to the Gateway (mac app, WebChat, CLI, etc.)
Presence 主要用于渲染 macOS 应用的实例标签页，并提供快速的操作员可见性。
Presence 字段（显示内容）
Presence 条目是具有以下字段的结构化对象：
- ''instanceId'' (optional but strongly recommended): stable client identity (usually ''connect.client.instanceId'')
- ''host'': human-friendly host name
- ''ip'': best-effort IP address
- ''version''：客户端版本字符串
- ''deviceFamily'' / ''modelIdentifier''：硬件的提示
- ''mode''：''ui''、''webchat''、''cli''、''backend''、''probe''、''test''、''node''、...
- ''lastInputSeconds'': "seconds since last user input" (if known)
- ''reason''：''self''、''connect''、''node-connected''、''periodic''、...
生产者（presence 来源）
Presence 条目由多个来源产生并合并。
1) 网关的自己条目
The Gateway always seeds a "self" entry at startup so UIs show the gateway host
客户端但连接执行前在也。
2) WebSocket 接続
Every WS client begins with a ''connect'' request. On successful handshake the
网关是那个连接的状态条目挿入执行。
Why one-off CLI commands don't show up
The CLI often connects for short, one-off commands. To avoid spamming the
实示例列表、''client.mode === "cli"'' 是状态条目在''转换不会被''。
3) `system-event` 信标
客户端可以通过 ''system-event'' 方法发送更丰富的定期信标。mac
app uses this to report host name, IP, and ''lastInputSeconds''.
4) 节点连接（角色：节点）
当节点通过 Gateway WebSocket 以 ''role: node'' 连接时，Gateway
那个节点的状态条目更新挿入执行（他的 WS 客户端和同自流程）。
合并 + 去重规则（为什么 `instanceId` 很重要）
Presence 条目存储在单个内存映射中：
- 条目是状态密钥由密钥付可被。
- The best key is a stable ''instanceId'' (from ''connect.client.instanceId'') that survives restarts.
- 密钥是大文字和小文字区別不会执行。
如果客户端在没有稳定 ''instanceId'' 的情况下重新连接，它可能会显示为''重复''行。
TTL and bounded size
Presence 是有意设计为短暂的：
- TTL: entries older than 5 minutes are pruned
- 最大条目数： 200（最也旧的从）
这可以保持列表新鲜并避免内存无限增长。
Remote/tunnel caveat (loopback IPs)
客户端但 SSH 隧道/本地端口转发通过在连接当执行、网关是
see the remote address as ''127.0.0.1''. To avoid overwriting a good client-reported
IP, loopback remote addresses are ignored.
消费者
macOS 实示例制表符
The macOS app renders the output of ''system-presence'' and applies a small status
indicator (Active/Idle/Stale) based on the age of the last update.
调试的提示
- To see the raw list, call ''system-presence'' against the Gateway.
- If you see duplicates:
- confirm clients send a stable ''client.instanceId'' in the handshake
- confirm periodic beacons use the same ''instanceId''
- check whether the connection-derived entry is missing ''instanceId'' (duplicates are expected)