Praesenz

Die OpenClaw-”Praesenz” ist eine leichtgewichtige Best-Effort-Ansicht von:

• dem Gateway selbst und
• den mit dem Gateway verbundenen Clients (Mac-App, WebChat, CLI usw.)

Die Praesenz dient hauptsaechlich dazu, den Instances-Tab der macOS-App zu rendern und Betreibern schnelle Sichtbarkeit zu bieten.

Praesenz-Felder (was angezeigt wird)

Praesenz-Eintraege sind strukturierte Objekte mit Feldern wie:

• instanceId (optional, aber dringend empfohlen): stabile Client-Identitaet (ueblicherweise connect.client.instanceId)
• host: menschenlesbarer Hostname
• ip: Best-Effort-IP-Adresse
• version: Client-Versionsstring
• deviceFamily / modelIdentifier: Hardware-Hinweise
• mode: ui, webchat, cli, backend, probe, test, node, …
• lastInputSeconds: “Sekunden seit letzter Nutzereingabe” (falls bekannt)
• reason: self, connect, node-connected, periodic, …
• ts: Zeitstempel der letzten Aktualisierung (ms seit Epoch)

Quellen (woher Praesenz kommt)

Praesenz-Eintraege werden von mehreren Quellen erzeugt und zusammengefuehrt.

1) Gateway-Selbsteintrag

Das Gateway erstellt beim Start immer einen “self”-Eintrag, damit UIs den Gateway-Host anzeigen, noch bevor Clients verbunden sind.

2) WebSocket-Verbindung

Jeder WS-Client beginnt mit einem connect-Request. Nach erfolgreichem Handshake legt das Gateway einen Praesenz-Eintrag fuer diese Verbindung an (Upsert).

Warum einmalige CLI-Befehle nicht auftauchen

Die CLI verbindet sich oft fuer kurze Einmalbefehle. Um die Instances-Liste nicht zuzuspammen, wird client.mode === "cli" nicht in einen Praesenz-Eintrag umgewandelt.

3) system-event-Beacons

Clients koennen reichhaltigere periodische Beacons per 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 ueber den Gateway-WebSocket mit role: node verbindet, legt das Gateway einen Praesenz-Eintrag fuer diesen Node an (gleicher Ablauf wie bei anderen WS-Clients).

Merge- und Deduplizierungsregeln (warum instanceId wichtig ist)

Praesenz-Eintraege werden in einer einzigen In-Memory-Map gespeichert:

• Eintraege sind per Praesenz-Key geschluesselt.
• Der beste Key ist eine stabile instanceId (aus connect.client.instanceId), die Neustarts ueberlebt.
• Keys sind case-insensitive.

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

TTL und Groessenbegrenzung

Praesenz ist bewusst kurzlebig:

• TTL: Eintraege, die aelter als 5 Minuten sind, werden bereinigt
• Maximale Eintraege: 200 (aelteste werden zuerst entfernt)

So bleibt die Liste aktuell und unkontrolliertes Speicherwachstum wird vermieden.

Remote-/Tunnel-Hinweis (Loopback-IPs)

Wenn sich ein Client ueber einen SSH-Tunnel oder lokalen Port-Forward verbindet, sieht das Gateway die Remote-Adresse moeglicherweise als 127.0.0.1. Um eine vom Client korrekt gemeldete IP nicht zu ueberschreiben, werden Loopback-Remote-Adressen ignoriert.

Konsumenten

macOS Instances-Tab

Die macOS-App rendert die Ausgabe von system-presence und zeigt einen kleinen Status-Indikator (Aktiv/Inaktiv/Veraltet) basierend auf dem Alter der letzten Aktualisierung.

Debugging-Tipps

• Um die Rohliste zu sehen, rufe system-presence gegen das Gateway auf.
• Bei Duplikaten:
  • pruefe, ob Clients eine stabile client.instanceId im Handshake senden
  • pruefe, ob periodische Beacons dieselbe instanceId verwenden
  • pruefe, ob der verbindungsbasierte Eintrag keine instanceId hat (Duplikate sind dann zu erwarten)