概述

Presence 是 OpenClaw 对 Gateway 自身及已连接客户端(macOS app、WebChat、CLI 等)的轻量级、尽力而为的可见性视图,主要用于渲染 macOS app 的 Instances 标签页。

核心要点

Presence 条目字段:

  • instanceId:稳定的客户端标识(强烈建议设置,用于去重)
  • host/ip:主机名和 IP(SSH 隧道下可能显示 127.0.0.1)
  • version:客户端版本
  • mode:ui、webchat、cli、backend、probe 等
  • lastInputSeconds:距上次用户输入的秒数
  • ts:最后更新时间戳

Presence 来源(多源合并):

  1. Gateway 自身条目:启动时自动创建,确保 UI 在客户端连接前就能看到 Gateway
  2. WebSocket connect:每个 WS 客户端握手成功后 upsert 一条记录(CLI 短命令不创建条目)
  3. system-event beacons:客户端定期发送的丰富信标(macOS app 用此上报主机名、IP、lastInputSeconds)
  4. Node 连接:role=node 的节点连接时 upsert

TTL 与大小限制:

  • TTL:5 分钟(超时自动清除)
  • 最大条目数:200(超出时删除最旧的)

去重规则:以 instanceId 为 key(大小写不敏感),客户端重连时若无稳定 instanceId 会出现重复行。

相关页面

  • streaming - 出站流式传输与 channel 格式化
  • agent - Agent 运行时与 Gateway 架构
  • session - 会话管理