Präsenz

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw „Presence“ ist eine schlanke Best-Effort-Ansicht von:

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

Presence wird hauptsächlich verwendet, um den Tab Instanzen der macOS-App zu rendern und schnelle operative Sichtbarkeit bereitzustellen.

​

Presence-Felder (was angezeigt wird)

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

• instanceId (optional, aber dringend empfohlen): stabile Client-Identität (normalerweise connect.client.instanceId)
• host: menschenlesbarer Hostname
• ip: Best-Effort-IP-Adresse
• version: Client-Versionszeichenfolge
• deviceFamily / modelIdentifier: Hardware-Hinweise
• mode: ui, webchat, cli, backend, probe, test, node, …
• lastInputSeconds: „Sekunden seit der letzten Benutzereingabe“ (falls bekannt)
• reason: self, connect, node-connected, periodic, …
• ts: Zeitstempel der letzten Aktualisierung (ms seit der Epoche)

​

Produzenten (woher Presence stammt)

Presence-Einträge werden von mehreren Quellen erzeugt und zusammengeführt.

​

1) Self-Eintrag des Gateway

Das Gateway legt beim Start immer einen „Self“-Eintrag an, damit UIs den Gateway-Host anzeigen, noch bevor sich Clients verbinden.

​

2) WebSocket-Verbindung

Jeder WS-Client beginnt mit einer connect-Anfrage. Nach erfolgreichem Handshake legt das Gateway einen Presence-Eintrag für diese Verbindung an oder aktualisiert ihn.

​

Warum einmalige CLI-Befehle nicht angezeigt werden

Die CLI verbindet sich oft für kurze, einmalige Befehle. Um die Instanzenliste nicht zu überfluten, wird client.mode === "cli" nicht in einen Presence-Eintrag umgewandelt.

​

3) system-event-Beacons

Clients können über die Methode system-event umfangreichere periodische Beacons senden. Die Mac-App verwendet dies, um Hostname, IP und lastInputSeconds zu melden.

​

4) Node-Verbindungen (Rolle: node)

Wenn sich ein Node über das Gateway-WebSocket mit role: node verbindet, legt das Gateway einen Presence-Eintrag für diesen Node an oder aktualisiert ihn (derselbe Ablauf wie bei anderen WS-Clients).

​

Regeln zum Zusammenführen und Deduplizieren (warum instanceId wichtig ist)

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

• Einträge werden über einen Presence-Schlüssel indiziert.
• Der beste Schlüssel ist eine stabile instanceId (aus connect.client.instanceId), die Neustarts überdauert.
• Schlüssel sind nicht groß-/kleinschreibungssensitiv.

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

​

TTL und begrenzte Größe

Presence ist absichtlich flüchtig:

• TTL: Einträge, die älter als 5 Minuten sind, werden entfernt
• Maximale Einträge: 200 (älteste werden zuerst verworfen)

Dadurch bleibt die Liste aktuell und unbegrenztes Speicherwachstum wird vermieden.

​

Hinweis zu Remote/Tunnel (Loopback-IPs)

Wenn sich ein Client über einen SSH-Tunnel / eine lokale Portweiterleitung verbindet, sieht das Gateway die Remote-Adresse möglicherweise als 127.0.0.1. Um zu vermeiden, dass eine gute vom Client gemeldete IP überschrieben wird, werden Loopback-Remote-Adressen ignoriert.

​

Konsumenten

​

macOS-Tab „Instanzen“

Die macOS-App rendert die Ausgabe von system-presence und wendet eine kleine Statusanzeige (Aktiv/Inaktiv/Veraltet) basierend auf dem Alter der letzten Aktualisierung an.

​

Debugging-Tipps

• Um die Rohdatenliste zu sehen, rufen Sie system-presence gegen das Gateway auf.
• Wenn Sie Duplikate sehen:
  • bestätigen Sie, dass Clients beim Handshake eine stabile client.instanceId senden
  • bestätigen Sie, dass periodische Beacons dieselbe instanceId verwenden
  • prüfen Sie, ob dem aus der Verbindung abgeleiteten Eintrag instanceId fehlt (Duplikate sind dann erwartet)

​

Verwandte Themen