Gateway-Fehlerbehebung in OpenClaw

Wenn die Seite zur schnellen Triage nicht reicht, schickt Sie die Dokumentation zum ausführlichen Gateway-Runbook. Es ist ein Index statt einer Wand aus Fixes: eine Befehlsleiter, die Signale, die ein gesundes Gateway zeigt, und sechs Seiten nach Symptombereich mit stabilen Ankern. Sein nützlichster Abschnitt ist die kurze Liste der Dinge, die direkt nach einem Upgrade kaputtgehen. Hier ist die Übersicht.

Die Leiter und die sechs Seiten

• Führen Sie die Befehle für Status, Gateway-Status, Log-Verfolgung, doctor und Kanal-Probe in dieser Reihenfolge aus; gesund heißt: Der Gateway-Status zeigt eine laufende Runtime, eine Konnektivitätsprobe mit ok und eine Capability-Zeile, doctor meldet kein blockierendes Konfigurations- oder Dienstproblem, und die Probe zeigt den Live-Transportstatus pro Konto mit einer Markierung works oder audit ok, sofern unterstützt.
• Updates und Rollbacks behandelt ein Gateway, das durch ein Update, ein Downgrade oder eine Split-Brain-Installation ausgefallen ist oder nicht mehr zusammenpasst: nach einem Update, das Timeout bei der Veröffentlichung der vorbereiteten Modell-Runtime, die Schutzregel für neuere Konfigurationen, das Korrigieren des Suchpfads, die Neuinstallation des Dienstes, das Entfernen veralteter Wrapper und eine Protokollabweichung nach einem Rollback. Skills und Modellanbieter behandelt ein übersprungenes Skill-Stammverzeichnis, den Rate-Limit-Fehler bei langem Kontext mit seinen Lösungen über Standardfenster, berechtigte Zugangsdaten und Fallback-Modell, blockierte Upstream-Antworten und ein lokales OpenAI-kompatibles Backend, das Probes besteht, aber bei Agent-Läufen scheitert.
• Agent-Antworten und die Steueroberfläche behandelt einen Lauf, der mit einem Speicherfehler scheitert, ausbleibende Antworten, die Dashboard-Konnektivität, die Connect- und Auth-Signaturen mit einer Kurzübersicht der Auth-Detailcodes sowie die Schritte für die Connect-Challenge, die Payload-Signierung und die Geräte-Nonce. Gateway-Dienst und Prozess behandelt einen Dienst, der nicht startet oder nicht dauerhaft läuft, ein macOS-Gateway, das still stoppt, bis das Dashboard angefasst wird, eine Supervisor-Schleife mit doppelten Launch Agents und einen Abbruch bei hohem Speicherverbrauch.
• Konfigurationsvalidierung und Probes behandelt eine abgelehnte ungültige Konfiguration (was passiert ist, Prüfen und Reparieren, ihre häufigen Signaturen und Lösungsoptionen) sowie Warnungen der Gateway-Probe. Kanalzustellung und Tools behandelt einen verbundenen Kanal, über den keine Nachrichten fließen, geplante und Heartbeat-Zustellung, einen gekoppelten Node, dessen Tool scheitert, Fehler des Browser-Tools, Plugin- und Executable-Signaturen, Browser-Sitzungs-Signaturen sowie Element-, Screenshot- und Upload-Signaturen; jeder alte Anker der einzelnen Seite führt weiterhin zu seinem neuen Ort.

Die meisten Probleme nach einem Upgrade sind Konfigurationsdrift oder strengere Standardwerte, die jetzt durchgesetzt werden.

Wenn nach einem Upgrade etwas kaputt ist

Der Index enthält drei Prüfungen direkt. Erstens das Verhalten bei Auth- und URL-Overrides: Lesen Sie den Gateway-Modus, die Remote-URL und den Auth-Modus aus, denn wenn der Modus auf remote steht, zielt die Kommandozeile womöglich auf ein entferntes Gateway, während der lokale Dienst in Ordnung ist, und Aufrufe mit expliziter URL greifen nicht auf gespeicherte Zugangsdaten zurück; eine connect-failed-Signatur bedeutet das falsche URL-Ziel, eine unauthorized-Signatur bedeutet, dass der Endpunkt erreichbar ist, aber mit der falschen Authentifizierung angesprochen wird. Zweitens sind die Schutzregeln für Bind und Auth strenger: Nicht-Loopback-Binds brauchen einen gültigen Auth-Pfad, also ein gemeinsames Token oder Passwort oder einen korrekt konfigurierten vertrauenswürdigen Nicht-Loopback-Proxy, und der alte Token-Schlüssel ersetzt nicht den aktuellen Auth-Token-Schlüssel; die Weigerung, ohne Auth zu binden, und eine fehlgeschlagene Konnektivitätsprobe bei laufender Runtime sind die Signaturen. Drittens der Status von Kopplung und Geräteidentität: Listen Sie Geräte und Kanalkopplungen auf und suchen Sie nach ausstehenden Gerätefreigaben für das Dashboard oder Nodes sowie nach ausstehenden Freigaben nach einer Richtlinien- oder Identitätsänderung; device identity required und pairing required sind die Signaturen. Wenn Dienstkonfiguration und Runtime immer noch nicht übereinstimmen, installieren Sie die Dienst-Metadaten aus demselben Profil und State-Verzeichnis neu und starten Sie neu.

Die Signale lesen

• Eine laufende Runtime mit fehlgeschlagener Konnektivitätsprobe ist die aussagekräftigste Kombination überhaupt: Der Prozess lebt, aber die Kommandozeile erreicht ihn mit ihrer aktuellen URL und Authentifizierung nicht, also liegt die Lösung im Modus, in der URL oder im Token, nicht im Dienst.
• Die Signatur device identity required nach einem Upgrade ist kein Fehler im Client; die Geräteauthentifizierung wird jetzt durchgesetzt, und das Dashboard oder der Node braucht seine ausstehende Freigabe, die in den Geräte- und Kopplungslisten erscheint.
• Die Probe arbeitet pro Konto: Ein Kanal mit zwei Konten kann einen funktionierenden und einen fehlschlagenden Transport zeigen, was die Statuszeile allein nicht verrät.

Kanal-Fehlerbehebung in OpenClaw ist das Gegenstück auf Kanalebene für den Fall, dass der Transport verbindet, das Verhalten aber falsch ist, und OpenClaw doctor erklärt den Reparaturbefehl, auf den die Leiter setzt.

Warum ein Index

Die Aufteilung des Runbooks nach Symptombereich hält jede Seite kurz genug, um sie zu lesen, während etwas ausgefallen ist, und die erhaltenen Anker sorgen dafür, dass Links aus älteren Threads und Issues weiterhin im richtigen Abschnitt landen. Auch die Reihenfolge der Leiter ist bewusst gewählt: Sie geht vom breitesten zum engsten Signal, und doctor steht vor der Probe, weil es die Fehlkonfigurationen repariert, die die Probe sonst als Fehler melden würde. Kopplung in OpenClaw behandelt die Freigaben, nach denen die dritte Prüfung sucht, und Konfiguration von OpenClaw die Schlüssel, die die ersten beiden Prüfungen auslesen.

Bei Diali

Bei Diali wird die Runtime-Konfiguration aus dem Dashboard erzeugt und bei jedem Release ersetzt, was den größten Teil der Drift beseitigt, die der Abschnitt zu Upgrades beschreibt, und dieselbe Leiter läuft auch auf der gehosteten Runtime. Gehostetes OpenClaw bei Diali beschreibt den gehosteten Assistenten und die Diali-Sicherheitsseite die Grenze um ihn herum.

• Fünf Befehle der Reihe nach; laufende Runtime plus Probe ok heißt gesund.
• Sechs Symptomseiten; jeder alte Anker führt weiterhin zum Ziel.
• Nach einem Upgrade: Modus und URL, Bind und Auth, Kopplungsstatus.