Gateway-Gesundheit und Doktor-Befehle

Die meisten OpenClaw-Ausfälle werden durch denselben Reflex schlimmer: erst an der Config drehen, dann nachdenken.

Ein besseres Bild ist die Triage im Krankenhaus. Niemand startet direkt mit einer Operation, nur weil jemand schlecht aussieht. Erst kommen Vitalzeichen, dann die Einordnung des Problems und erst danach die Entscheidung, ob Beobachtung, Eingriff oder Reparatur nötig ist.

Genau darin liegt die Aufgabentrennung zwischen openclaw status, openclaw health und openclaw doctor. Das eine gibt dir den schnellen Überblick, das andere fragt das laufende Gateway nach seinem Health-Snapshot und das dritte kümmert sich um Findings, Migrationen und unterstützte Reparaturschritte.

Wenn du diese Flächen sauber trennst, wird Fehlersuche schnell ruhiger. Wenn du sie vermischst, sieht jedes Problem plötzlich wie ein Anlass aus, mit dem Schraubenschlüssel auf die Maschine loszugehen.

Was du zuerst prüfen solltest, wenn etwas kaputt wirkt

Starte mit der schnellsten read-only Sicht, die das Problem schon eingrenzen kann.

1. openclaw status ausführen: schnelle Übersicht zu Gateway-Erreichbarkeit, Modus, Channel-Auth-Alter, Sessions und letzter Aktivität
2. Zu openclaw status --deep eskalieren: ergänzt Live-Probes, wenn die Schnellansicht verdächtig, aber nicht eindeutig ist
3. openclaw health oder openclaw health --verbose nutzen: das laufende Gateway nach seinem Health-Snapshot fragen, wobei verbose einen Live-Probe erzwingt
4. openclaw doctor --lint verwenden: read-only Findings für Config-Drift, stale state oder bekannte Health-Probleme
5. openclaw doctor --fix nur verwenden, wenn du Änderungen willst: das ist die unterstützte Reparatur-Spur, nicht der erste Reflex

Diese Reihenfolge ist wichtig, weil die erste Frage nicht lautet: "Wie repariere ich das?" Sondern: "Was genau ist hier ungesund?"

Status ist das Dashboard, nicht der Mechaniker

openclaw status ist die schnelle Betreiber-Ansicht. Sie beantwortet die langweiligen Fragen, die dir am meisten Zeit sparen.

• Ist das Gateway erreichbar?
• Läuft das Setup lokal oder remote?
• Sind Channels verknüpft und wie alt ist dieser Auth-Stand?
• Gibt es aktuelle Session-Aktivität?
• Gibt es offensichtliche Warnungen zu Memory, Secrets, Pricing oder Updates?

Der normale Befehl bleibt auf dem schnellen read-only Pfad. Genau deshalb ist er der richtige erste Schritt, wenn der Agent plötzlich still wird. Du siehst früh, ob du es mit einem breiten Health-Problem oder nur mit einer engen Fehlerspur zu tun hast.

openclaw status --deep ist der Eskalationsschritt. Er fragt Live-Probes an und gibt dir eine stärkere Antwort, wenn das Dashboard noch zu unklar bleibt.

# schneller erster Blick
openclaw status

# stärkere read-only Diagnose mit Live-Probes
openclaw status --deep

# breiterer lokaler Bericht zum Teilen oder Vergleichen
openclaw status --all

Health ist die Snapshot-Spur des Gateways

openclaw health ist etwas anderes als status. Der Befehl fragt das laufende Gateway per Gateway-RPC nach seinem Health-Snapshot.

Das klingt klein, ist aber wichtig. Die CLI öffnet nicht selbst direkte Provider-Sockets. Sie fragt das Gateway, was das Gateway gerade sieht. Genau deshalb ist health stark für die Live-Sicht des Gateways, aber kein magischer Nebenkanal, der die Realität des Gateways umgeht.

Standardmäßig kann health einen frischen gecachten Snapshot zurückgeben und die Auffrischung im Hintergrund anstoßen. openclaw health --verbose erzwingt einen Live-Probe und zeigt mehr Verbindungsdetails. Das ist ideal, wenn du eine frischere Aussage über den aktuellen Zustand brauchst, ohne gleich in Reparaturmodus zu springen.

# Health-Snapshot des Gateways
openclaw health

# maschinenlesbare Ausgabe
openclaw health --json

# Live-Probe erzwingen und mehr Details sehen
openclaw health --verbose

Doctor ist das Reparatur- und Migrationswerkzeug

Bei doctor entsteht die meiste Verwirrung. Viele behandeln es wie eine hübschere Version von status. Das ist es nicht.

openclaw doctor ist die Health-Check- und Reparatur-Oberfläche für Gateway-Config, Channels, Plugins, Skills, Model-Auth, lokalen State und Migrationen. Denk eher an einen Mechaniker mit Checkliste und Werkzeugkasten als an das Warnlampenfeld im Auto.

Wichtig ist diese Trennung:

• openclaw doctor: menschenlesbare Prüfung und geführte Hinweise
• openclaw doctor --lint: read-only strukturierte Findings für CI, Preflight und disziplinierte Fehlersuche
• openclaw doctor --fix: unterstützte Reparaturen anwenden, wenn du echte Änderungen willst
• openclaw doctor --non-interactive: konservativer No-Prompt-Pfad, der Reparaturen mit nötiger Bestätigung auslässt

Genau hier verbrennen sich viele Nutzer. --non-interactive ist nicht dasselbe wie --fix. Das eine ist vorsichtige Automatisierung. Das andere ist eine bewusst gestartete Reparatur-Spur.

# zuerst read-only Findings
openclaw doctor --lint

# auf einen Check eingrenzen, wenn du die Spur schon kennst
openclaw doctor --lint --only core/doctor/gateway-config --json

# unterstützte Reparaturen anwenden
openclaw doctor --fix

# konservativer Automationsmodus, nicht gleichbedeutend mit Reparatur
openclaw doctor --non-interactive

Wie du Config-, Runtime- und Channel-Probleme auseinanderhältst

Ein sinnvoller erster Troubleshooting-Durchgang sollte Symptome nach Schichten trennen.

• Status sieht sofort schlecht aus: wahrscheinlich Gateway-Erreichbarkeit, Auth-Alter, offensichtlicher State oder eine Top-Level-Warnung
• Health-Probe wirkt schwach: wahrscheinlich laufende Gateway-Konnektivität oder Channel-Gesundheit im Gateway
• Doctor lint findet Probleme: wahrscheinlich Config-Drift, stale state, Migrationen, Berechtigungen oder andere bekannte reparierbare Zustände
• Alle drei wirken gesund, aber ein Workflow scheitert trotzdem: wahrscheinlich ein engeres Runtime-, Tool- oder Codepfad-Problem

Genau im letzten Fall neigen Leute zu Neuinstallationen, obwohl gar nicht die Installation kaputt ist. Lass das lieber. Ein gesundes Gateway mit genau einem kaputten Workflow braucht meist gezieltes Debugging, keine Opfergabe.

Wo Diagnose-Flags hineinpassen

Sobald status, health oder doctor dir zeigen, welche Spur verdächtig riecht, helfen Diagnose-Flags beim Sprung vom groben Signal zum konkreten Beleg.

Sie sind ideal, wenn du schon ein verdächtiges Subsystem hast und gezielte Logs willst, ohne global alles in Lärm zu verwandeln. Flags sind opt-in, nicht case-sensitiv und unterstützen Wildcards wie gateway.*.

# gezielte Gateway-Diagnose für einen Lauf
OPENCLAW_DIAGNOSTICS=gateway.* openclaw gateway run

# nur Timing im Reply-Pfad
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

# alle Diagnose-Flags für diesen Prozess deaktivieren
OPENCLAW_DIAGNOSTICS=0 openclaw gateway run

Wenn du die volle Diagnose-Geschichte willst, lies weiter bei Diagnose- & Debug-Flags. Diese Seite soll dir zuerst helfen, die richtige Oberfläche zu wählen, nicht dich in Minute eins in Logfluten zu ertränken.

Ein vernünftiger Troubleshooting-Ablauf

Wenn du eine wiederholbare Betreiber-Gewohnheit willst, nimm diese Reihenfolge:

1. openclaw status ausführen
2. bei Bedarf zu openclaw status --deep eskalieren
3. openclaw health --verbose nutzen, wenn du einen frischen Live-Probe brauchst
4. vor jeder Reparaturaktion openclaw doctor --lint ausführen
5. openclaw doctor --fix nur für unterstützte Änderungen einsetzen, die du wirklich willst
6. gezielte Diagnose-Flags erst dann einschalten, wenn klar ist, welches Subsystem die Aufmerksamkeit verdient

Diese Reihenfolge ist nicht glamourös. Gut so. Zuverlässiger Betrieb ist es selten.

Die Kurzfassung

• status ist die schnelle Übersicht
• status --deep ist die stärkere read-only Eskalation
• health fragt das laufende Gateway nach seinem Health-Snapshot
• health --verbose erzwingt einen Live-Probe
• doctor --lint ist die sichere read-only Findings-Spur
• doctor --fix ist die unterstützte Reparatur-Spur

Erst Status prüfen. Dann Health bestätigen. Erst danach reparieren. Diese Reihenfolge allein spart dir schon erstaunlich viel selbst verursachten Ärger.