Presence

“Presence” trong OpenClaw là một cái nhìn nhẹ nhàng, best-effort về:

  • chính Gateway, và
  • các client kết nối tới Gateway (mac app, WebChat, CLI, v.v.)

Presence được dùng chủ yếu để render tab Instances trong macOS app và cung cấp khả năng quan sát nhanh cho người vận hành.

Các trường Presence (những gì hiển thị)

Các entry Presence là các object có cấu trúc với các trường như:

  • instanceId (tùy chọn nhưng mình khuyên nên có): định danh client ổn định (thường là connect.client.instanceId)
  • host: tên host thân thiện với người dùng
  • ip: địa chỉ IP (best-effort)
  • version: chuỗi phiên bản client
  • deviceFamily / modelIdentifier: thông tin phần cứng
  • mode: ui, webchat, cli, backend, probe, test, node, …
  • lastInputSeconds: “số giây kể từ lần nhập liệu cuối của user” (nếu biết)
  • reason: self, connect, node-connected, periodic, …
  • ts: timestamp cập nhật cuối (ms kể từ epoch)

Producers (nguồn tạo ra presence)

Các entry Presence được tạo ra từ nhiều nguồn và được gộp lại.

1) Gateway self entry

Gateway luôn tạo một entry “self” khi khởi động để các UI hiển thị gateway host ngay cả khi chưa có client nào kết nối.

2) WebSocket connect

Mỗi WS client bắt đầu với một request connect. Khi handshake thành công, Gateway sẽ upsert một entry presence cho connection đó.

Tại sao các lệnh CLI một lần không hiển thị

CLI thường kết nối cho các lệnh ngắn, chỉ một lần. Để tránh làm spam danh sách Instances, client.mode === "cli" sẽ không được chuyển thành entry presence.

3) system-event beacons

Các client có thể gửi các beacon định kỳ phong phú hơn qua method system-event. Mac app dùng cái này để báo cáo tên host, IP và lastInputSeconds.

4) Node connects (role: node)

Khi một node kết nối qua Gateway WebSocket với role: node, Gateway sẽ upsert một entry presence cho node đó (cùng flow với các WS client khác).

Quy tắc merge + dedupe (tại sao instanceId quan trọng)

Các entry Presence được lưu trong một map in-memory duy nhất:

  • Các entry được đánh key bằng một presence key.
  • Key tốt nhất là một instanceId ổn định (từ connect.client.instanceId) tồn tại qua các lần restart.
  • Các key không phân biệt chữ hoa chữ thường.

Nếu một client reconnect mà không có instanceId ổn định, nó có thể hiển thị dưới dạng một hàng trùng lặp.

TTL và giới hạn kích thước

Presence được thiết kế tạm thời:

  • TTL: các entry cũ hơn 5 phút sẽ bị xóa
  • Max entries: 200 (các entry cũ nhất bị xóa trước)

Điều này giữ cho danh sách luôn mới và tránh tăng trưởng bộ nhớ không giới hạn.

Lưu ý về Remote/tunnel (loopback IPs)

Khi một client kết nối qua SSH tunnel / local port forward, Gateway có thể thấy địa chỉ remote là 127.0.0.1. Để tránh ghi đè một IP do client báo cáo tốt, các địa chỉ remote loopback sẽ bị bỏ qua.

Consumers

macOS Instances tab

MacOS app render output của system-presence và áp dụng một chỉ báo trạng thái nhỏ (Active/Idle/Stale) dựa trên độ tuổi của lần cập nhật cuối.

Mẹo debug

  • Để xem danh sách thô, gọi system-presence với Gateway.
  • Nếu các bạn thấy trùng lặp:
    • xác nhận các client gửi một client.instanceId ổn định trong handshake
    • xác nhận các beacon định kỳ dùng cùng instanceId
    • kiểm tra xem entry từ connection có thiếu instanceId không (trùng lặp là điều bình thường)