Agent-Status in der Menu Bar verstehen

Du kennst das Problem: Ein Hintergrund-Agent läuft, aber du hast keine Ahnung, ob er gerade wirklich arbeitet oder im Leerlauf feststeckt. Ohne klares visuelles Feedback suchst du oft vergeblich in Logs nach Antworten. Ein gutes Menu Bar Icon sollte dir sofort sagen, was Sache ist, ohne dich abzulenken.

Hier erfährst du, wie die Status-Logik für den Agent aufgebaut ist und wie die verschiedenen Sessions priorisiert werden.

Voraussetzungen

Zugriff auf den Control-Channel für agent Events
Swift-Umgebung für die Arbeit mit dem IconState Enum

Schnellstart

In nur 5 Minuten verstehst du, wie der Agent seinen Status kommuniziert:

Icon-Check: Das Icon in der Menu Bar zeigt den aktuellen Work State. Ein animierter Critter bedeutet, dass die Main-Session aktiv ist.
Status-Zeile: Die erste Zeile im Menü zeigt Details im Format <Session role> · <activity label>.
Geräte-Liste: Unter “Nodes” findest du ausschließlich gepairte Devices aus node.list, keine Presence-Einträge.
Debug-Modus: Über Settings ▸ Debug ▸ Icon override kannst du Icons manuell testen, was den IconState.overridden triggert.

State Modell und Priorität

Das System verarbeitet Events über eine runId und einen sessionKey. Dabei gilt eine klare Hierarchie, damit das Icon nicht nervös hin- und herspringt.

Main Session: Der Key main gewinnt immer. Ist die Main-Session aktiv, wird ihr Status sofort angezeigt.
Fallback: Wenn main idle ist, zeigt das System die zuletzt aktive Non-Main-Session an.
Stabilität: Wir wechseln die Anzeige nie während einer laufenden Aktivität. Ein Wechsel erfolgt nur, wenn die aktuelle Session fertig ist oder die Main-Session aktiv wird.

IconState Enum (Swift)

Die visuelle Darstellung basiert auf diesem Enum:

enum IconState {
    case idle
    case workingMain(ActivityKind)
    case workingOther(ActivityKind)
    case overridden(ActivityKind)
}

Aktivitäten und Glyphen

Je nach ActivityKind ändert sich das Glyph im Badge:

exec → 💻
read → 📄
write → ✍️
edit → 📝
attach → 📎
Default → 🛠️

Event Ingestion

Die Daten stammen aus ControlChannel.handleAgentEvent. Das System parst zwei primäre Streams:

stream: "job": Nutzt data.state (started, streaming, done, error) für den Start-Stopp-Status.
stream: "tool": Nutzt data.phase sowie Namen und Metadaten für die Beschriftung.

Für die Labels werden Pfade gekürzt und bei exec wird die erste Zeile des args.command verwendet.

Fehlerbehebung

Hier sind Lösungen für bekannte Verhaltensweisen aus der Dokumentation:

Das Badge flackert bei schnellen Tool-Aufrufen: Das System nutzt eine TTL-Grace-Period auf Tool-Results, um visuelle Unruhe zu vermeiden.
Der Health-Status ist verschwunden: Das ist beabsichtigt. Der Health-Status wird ausgeblendet, sobald eine Session aktiv ist, und kehrt erst zurück, wenn alle Sessions idle sind.

AI Setup Assistant

Nächste Schritte

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.