为什么需要 presence
OpenClaw 跑在一台常驻的网关(Gateway)上,你、你的家人、同事可能从不同设备(浏览器 Control UI、Discord、微信、飞书、iOS/Android 节点)连进来。出问题时常问三件事:
- 现在到底谁在线?
- 对方是用什么设备、什么频道连进来的?
- 这个人最近几分钟在干嘛、有没有卡住?
过去要 who、w、last、ss -tnp 一顿敲,还看不出「这是 OpenClaw 的哪个会话」。presence 把这些聚合到一处,直接回一份结构化快照。
presence 是什么
presence 是 OpenClaw 的「在场状态」读取工具。它不推送、不修改,只读。默认动作是 list:
list(默认):列出当前在线的人,每人一条记录,包含其连接设备、活跃频道、最近活动时间。
person:深入看某一个体——传me、某个 profile ID、或一个无歧义的名字/标识,返回该人的设备明细与近期活动轨迹。
它读的是网关本地维护的在线状态,不是去外部平台轮询,所以很快、零依赖。
实战一:一眼看谁在线
不需要参数,直接读 list 即可。概念上等价于下面这条真实命令在本机看到的在线会话:
# 本机真实可见的「谁在线」底层信号
who # 当前登录的用户与会话
w # 谁在线 + 在跑什么命令 + 空闲多久
last -n 20 # 最近的登录/登出记录
ss -tnp | grep -E ':443|:22' # 谁还挂着长连(nginx/ssh)presence 的价值是把这些零散信号归一化成「人」维度:你能直接看到「Z 用 macOS 节点连着、3 分钟前活跃、当前挂在主会话」,而不是自己从 ss 的一堆 IP 里反推。
实战踩坑提醒:w 显示的 IDLE 是从上次按键算的,AI 长任务跑着但人不敲键盘,IDLE 会很大,别误判成「人已离开」。presence 的「最近活动」更贴近真实交互,优先看它。
实战二:看某个人的设备与轨迹
当你怀疑「某人的推送没收到」或「节点掉线了」,用 person 定点看:
presence person: me
→ 返回当前操作者自身的连接列表、各设备的最后心跳、所属会话真实排障里这一步常配合节点状态一起看。比如飞书 WebSocket 掉线,presence 里那个人对应的设备会显示「心跳过期」,而 nodes 里同节点标 pending/掉线——两相对照,基本能定位是「人走了」还是「节点断了」,而不是盲目重启。
实战踩坑提醒:person 传名字时必须无歧义。网关里有两个「Z」(比如 nick 和 profile 不同)会报错或返回错的那个。稳妥做法是先 list 拿到准确的 profile ID,再把这个 ID 喂给 person。
实战三:把它接进巡检脚本
presence 是只读工具,很适合放进定时自检。思路:每日巡检时顺手拉一份在线快照存盘,哪天出了「某关键节点的人突然全掉」的异常,翻历史快照就能对比。
# 伪代码思路(真实执行用 OpenClaw 的 presence 工具,不是 shell)
# 每天 03:00 巡检:
# 1) presence list -> 写入 memory/presence-<date>.json
# 2) 若「预期在线的人」不在列表 -> 触发告警注意:presence 读的是网关内存态,重启后会清零,所以别拿它当审计日志。要留痕就定时落盘,像上面那样另存一份。
presence vs 手动 who/w
| 维度 | presence | who/w/ss |
|------|----------|----------|
| 视角 | 以「人/会话」聚合 | 以「系统会话/IP」展开 |
| 速度 | 网关本地,瞬时 | 需多命令拼凑 |
| 能看出 OpenClaw 会话 | 能 | 不能 |
| 适合排障 | 定位「谁/哪台设备」 | 定位「哪条连接/端口」 |
二者不是替代关系:presence 先把「人」锁定,who/w/ss 再下钻到连接层做根因确认。
小结
presence是只读的「在场地图」:list看全局在线,person看单人设备与轨迹。
- 排障先
list拿 profile ID,再person定点,避免名字歧义。
- IDLE/心跳别误读;presence 重启即丢,要留痕就定时落盘。
- 它和
who/w/ss互补:一个锁定「谁」,一个锁定「哪条连接」。
扫码关注公众号，获取更多 OpenClaw 实操技巧：
