OpenClaw Presence im Griff

Es ist frustrierend, wenn man ein verteiltes System betreibt und nicht genau weiß, welche Clients gerade wirklich aktiv sind. Man starrt auf Logs und hofft, dass die Verbindung zum Gateway steht, aber eine echte Echtzeit-Übersicht fehlt oft.

Ohne eine zentrale Sicht auf die Instanzen wird das Debugging zur Raterei. Du weißt nicht, ob ein Client gerade nur im Idle-Modus ist oder ob die Verbindung komplett abgebrochen ist. OpenClaw Presence löst dieses Problem durch eine schlanke Übersicht aller aktiven Komponenten.

Voraussetzungen

• Ein laufendes OpenClaw Gateway
• Verbundene Clients (wie die macOS App oder ein WebChat)

Schnellstart

Presence-Daten sind flüchtig und zeigen dir den aktuellen Status deines Systems. Um die Liste der aktiven Instanzen zu sehen, kannst du die Methode system-presence gegen das Gateway aufrufen. In der macOS App findest du diese Daten direkt im Instances Tab.

Ein Presence-Eintrag besteht aus strukturierten Feldern. Hier sind einige der wichtigsten Werte:

• instanceId: Die stabile Identität deines Clients
• host: Der Name des Rechners
• ip: Die aktuell erkannte IP-Adresse
• version: Die Version der Client-Software

Die Daten werden aus verschiedenen Quellen gesammelt. Das Gateway erstellt beim Start einen eigenen “self”-Eintrag. Sobald sich ein Client per WebSocket verbindet, wird ein Eintrag erstellt oder aktualisiert. Clients können zusätzlich über system-event Beacons senden, um Details wie die letzte Nutzerinteraktion (lastInputSeconds) zu melden.

Damit die Liste sauber bleibt, nutzt OpenClaw eine instanceId, um doppelte Einträge zu vermeiden. Die Liste ist im Speicher begrenzt: Einträge, die älter als 5 Minuten sind, werden gelöscht, und es werden maximal 200 Instanzen gleichzeitig verwaltet.

Fehlerbehebung

CLI-Befehle tauchen nicht in der Liste auf Das ist beabsichtigt. Da CLI-Kommandos oft nur kurz ausgeführt werden, würde client.mode === "cli" die Liste unnötig füllen. Diese Modus-Typen werden daher nicht in Presence-Einträge umgewandelt.

Doppelte Einträge in der Instanz-Liste Wenn ein Client keine stabile instanceId beim Handshake mitsendet, kann das Gateway Reconnects nicht korrekt zuordnen. Stelle sicher, dass connect.client.instanceId bei jeder Verbindung und jedem Beacon identisch ist.

IP-Adresse wird nur als 127.0.0.1 angezeigt Wenn du einen SSH-Tunnel oder ein lokales Port-Forwarding nutzt, erkennt das Gateway die Loopback-Adresse. Um zu verhindern, dass korrekte Client-Daten überschrieben werden, ignoriert das Gateway IP-Meldungen von Loopback-Adressen.

Raw-Daten zur Fehlersuche abrufen Wenn du die unformatierten Daten sehen willst, um Probleme mit der Identität von Instanzen zu finden, kannst du die Liste direkt abfragen:

# Rufe die rohe Presence-Liste vom Gateway ab
system-presence

Bei weiteren Fragen zur Einrichtung hilft dir der AI Setup Assistant gerne weiter.

Nächste Schritte

• Gateway API Dokumentation
• macOS App Übersicht