Presence

OpenClaw „Presence” ist eine einfache Übersicht über:

  • das Gateway selbst, und
  • Clients, die mit dem Gateway verbunden sind (Mac App, WebChat, CLI, usw.)

Presence wird hauptsächlich für den Instances-Tab in der macOS App verwendet und gibt dir einen schnellen Überblick über verbundene Geräte.

Presence-Felder (was angezeigt wird)

Presence-Einträge sind strukturierte Objekte mit folgenden Feldern:

  • instanceId (optional, aber empfohlen): stabile Client-Identität (normalerweise connect.client.instanceId)
  • host: lesbarer Hostname
  • ip: IP-Adresse (best-effort)
  • version: Client-Version
  • deviceFamily / modelIdentifier: Hardware-Infos
  • mode: ui, webchat, cli, backend, probe, test, node, …
  • lastInputSeconds: „Sekunden seit letzter Benutzereingabe” (falls bekannt)
  • reason: self, connect, node-connected, periodic, …
  • ts: letzter Update-Zeitstempel (ms seit Epoch)

Quellen (woher Presence kommt)

Presence-Einträge kommen aus mehreren Quellen und werden zusammengeführt.

1) Gateway Self-Eintrag

Das Gateway erstellt beim Start immer einen „self”-Eintrag, damit UIs den Gateway-Host anzeigen — auch wenn noch keine Clients verbunden sind.

2) WebSocket-Verbindung

Jeder WS-Client beginnt mit einer connect-Anfrage. Nach erfolgreichem Handshake erstellt das Gateway einen Presence-Eintrag für diese Verbindung.

Warum einmalige CLI-Befehle nicht auftauchen

Die CLI verbindet sich oft nur kurz für einzelne Befehle. Um die Instances-Liste nicht zu überfüllen, werden Verbindungen mit client.mode === "cli" nicht als Presence-Eintrag gespeichert.

3) system-event Beacons

Clients können regelmäßig detailliertere Beacons über die system-event-Methode senden. Die Mac App nutzt das, um Hostname, IP und lastInputSeconds zu melden.

4) Node-Verbindungen (role: node)

Wenn sich ein Node über den Gateway WebSocket mit role: node verbindet, erstellt das Gateway einen Presence-Eintrag für diesen Node (gleicher Ablauf wie bei anderen WS-Clients).

Merge- und Dedupe-Regeln (warum instanceId wichtig ist)

Presence-Einträge werden in einer In-Memory-Map gespeichert:

  • Einträge werden über einen Presence Key identifiziert.
  • Der beste Key ist eine stabile instanceId (aus connect.client.instanceId), die Neustarts überlebt.
  • Keys sind case-insensitive.

Wenn sich ein Client ohne stabile instanceId neu verbindet, kann er als Duplikat erscheinen.

TTL und Größenbegrenzung

Presence ist absichtlich kurzlebig:

  • TTL: Einträge älter als 5 Minuten werden entfernt
  • Max. Einträge: 200 (älteste werden zuerst gelöscht)

Das hält die Liste aktuell und verhindert unbegrenztes Speicherwachstum.

Remote/Tunnel-Hinweis (Loopback-IPs)

Wenn sich ein Client über einen SSH-Tunnel oder lokalen Port-Forward verbindet, sieht das Gateway möglicherweise 127.0.0.1 als Remote-Adresse. Um eine gute, vom Client gemeldete IP nicht zu überschreiben, werden Loopback-Adressen ignoriert.

Verbraucher

macOS Instances-Tab

Die macOS App zeigt die Ausgabe von system-presence an und verwendet einen kleinen Status-Indikator (Active/Idle/Stale) basierend auf dem Alter des letzten Updates.

Debugging-Tipps

  • Um die Rohliste zu sehen, rufe system-presence gegen das Gateway auf.
  • Bei Duplikaten:
    • Prüfe, ob Clients eine stabile client.instanceId im Handshake senden
    • Prüfe, ob periodische Beacons dieselbe instanceId verwenden
    • Prüfe, ob dem verbindungsbasierten Eintrag die instanceId fehlt (Duplikate sind dann zu erwarten)