OpenClaw noch nicht installiert? Klicken Sie hier fur die Ein-Klick-Installationsanweisung
curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Besorgt uber Auswirkungen auf Ihren Computer? ClawTank lauft in der Cloud ohne Installation -- kein Risiko versehentlicher Dateiloschung
Key Findings
  • openclaw doctor ist das in OpenClaw integrierte All-in-One-Diagnosetool, das automatisch die Konfigurationsdatei-Syntax, den Modellauthentifizierungsstatus, die Gateway-Verbindung und die Node.js-Versionskompatibilitat pruft[1]
  • Mit dem --fix-Flag kann doctor die meisten haufigen Probleme automatisch beheben, darunter fehlende Konfigurationswerte, abgelaufene Token und beschadigte Workspace-Indizes[1]
  • Gateway-Verbindungsfehler (der Fehler „Pairing Required") sind das haufigste Problem fur Einsteiger -- in der Regel genugt es, den Gateway Token neu zu generieren[2]
  • Die Hauptursache fur „hangende" Agenten sind LLM-Anfrage-Timeouts -- eine Erhoehung von timeoutSeconds oder die Konfiguration eines Fallback-Modells schafft wirksam Abhilfe[4]

1. openclaw doctor: Ihre erste Verteidigungslinie

Wenn OpenClaw ungewoehnliches Verhalten zeigt, sollten Sie als Erstes immer openclaw doctor ausfuhren. Dieser Befehl fuhrt einen umfassenden Gesundheitscheck des gesamten Systems durch und meldet den Status jedes Elements mit ubersichtlicher Rot-/Gelb-/Grun-Kennzeichnung zuruck.[1]

1.1 Grundlegende Diagnose

openclaw doctor

Dieser Befehl pruft der Reihe nach:

  1. Node.js-Version: OpenClaw erfordert Node.js 22 oder hoher
  2. Integritat der Konfigurationsdatei: Syntax und erforderliche Felder von openclaw.json
  3. Modellauthentifizierung: Ob die konfigurierten Provider erfolgreich verbunden werden koennen
  4. Gateway-Status: Ob das Gateway lauft und der Port erreichbar ist
  5. Kanalverbindungen: Ob die konfigurierten Channels (Telegram, WhatsApp usw.) normal funktionieren

1.2 Automatische Reparatur

openclaw doctor --fix

Mit dem --fix-Flag diagnostiziert doctor nicht nur Probleme, sondern versucht auch, diese zu beheben. Zu den haufigen automatischen Reparaturen gehoeren:

1.3 Gateway Token generieren

openclaw doctor --generate-gateway-token

Dieser Befehl dient speziell zur Generierung oder Neugenerierung des Gateway-Authentifizierungstokens. Wenn Sie den Fehler „Pairing Required" sehen, reicht es in der Regel aus, diesen einen Befehl auszufuhren.[2]

2. Die funf haufigsten Probleme und ihre Loesungen

2.1 „Pairing Required" — Gateway-Verbindung fehlgeschlagen

Symptom: In der Web-UI (http://127.0.0.1:18789) oder in den Kommunikationskanalen erscheint die Meldung „Pairing Required".

Ursache: Gateway Token fehlt, ist abgelaufen oder stimmt nicht uberein.

Loesung:

openclaw doctor --generate-gateway-token
# Anschliessend Gateway neu starten
openclaw gateway restart

2.2 „LLM Request Timed Out" — Modellanfrage-Timeout

Symptom: Der Agent reagiert mitten in der Aufgabenausfuhrung nicht mehr, die Logs zeigen einen Timeout-Fehler.[4]

Ursache: Die Antwortzeit der LLM-API uberschreitet das Standardlimit -- haufig bei komplexen Aufgaben oder in API-Spitzenlastzeiten.

Loesung:

# Timeout erhoehen (Einheit: Sekunden)
openclaw config set agents.defaults.timeoutSeconds 600

# Fallback-Modell konfigurieren, das bei Timeout des Hauptmodells automatisch einspringt
openclaw config set agents.defaults.model.fallbacks '["claude-sonnet-4-6"]'

2.3 Agent „hangt" und reagiert nicht

Symptom: Der Agent reagiert uberhaupt nicht -- nach dem Senden von Nachrichten kommt keine Antwort und keine Fehlermeldung.

Ursache: Moeglicherweise ist der Gateway-Prozess eingefroren, der Node-Prozess abgesturzt oder der Workspace-Zustand beschadigt.

Loesung (von leicht nach schwer):

# 1. Gateway neu starten
openclaw gateway restart

# 2. Falls der Gateway-Neustart nicht normal funktioniert, erzwungenes Stoppen und Neustart
openclaw gateway stop
openclaw gateway start

# 3. Falls das Problem weiterhin besteht, vollstandige Diagnose und Reparatur ausfuhren
openclaw doctor --fix

2.4 Port 18789 ist belegt

Symptom: Beim Starten des Gateways wird angezeigt, dass der Port bereits belegt ist.

Loesung:

# Pruefen, wer den Port belegt
lsof -i :18789

# Option A: Den belegenden Prozess beenden
kill -9 PID

# Option B: Port andern
openclaw config set gateway.port 28789

2.5 Modellauthentifizierung fehlgeschlagen

Symptom: Der Agent meldet „Model not allowed" oder „Authentication failed".[4]

Loesung:

# Modellstatus prufen
openclaw models status

# API-Schlussel neu konfigurieren
openclaw models auth setup-token --provider anthropic

# Oder den OAuth-Ablauf erneut durchfuhren
openclaw models auth login --provider openai

3. Neustart- und Reset-Ablaufe

3.1 Normaler Neustart (alle Daten bleiben erhalten)

openclaw gateway restart

Dies ist die sicherste Methode fur einen Neustart. Das Gateway schreibt zunachst den aktuellen Zustand in den persistenten Speicher und startet dann neu. Alle Workspaces, Erinnerungen und Konfigurationen bleiben erhalten.

3.2 Vollstandiges Stoppen und erneutes Starten

openclaw gateway stop
# Einige Sekunden warten
openclaw gateway start

Geeignet fur Situationen, in denen gateway restart nicht funktioniert. Der stop-Befehl stellt sicher, dass alle zugehoerigen Prozesse vollstandig beendet werden.

3.3 Daemon-Modus-Neustart (systemd)

Wenn Sie den systemd-Dienst mit openclaw onboard --install-daemon installiert haben:

systemctl --user restart openclaw-gateway

3.4 Kontext leeren (Soft-Reset)

Wenn der Dialogkontext des Agenten durcheinandergeraten ist, koennen Sie nur den Kontext leeren, ohne das gesamte System neu zu starten:

openclaw tui

Dies oeffnet eine neue interaktive Dialog-Oberflache, ohne das Langzeitgedachtnis im Workspace zu beeintrachtigen.

4. Log-Analyse und fortgeschrittenes Debugging

4.1 Echtzeit-Logs anzeigen

openclaw logs --follow

Dieser Befehl gibt die Laufzeit-Logs des Gateways in Echtzeit aus, ahnlich wie tail -f. Sie koennen den Verarbeitungsprozess jeder Anfrage, die Latenz der Modellaufrufe und Fehlermeldungen einsehen.[7]

4.2 Haufige Log-Meldungen interpretieren

Log-MeldungBedeutungEmpfohlene Aktion
Gateway started on :18789Normaler StartKeine Aktion erforderlich
Pairing requiredToken-Verifizierung fehlgeschlagendoctor --generate-gateway-token ausfuhren
LLM request timed outModell-Antwort-TimeouttimeoutSeconds erhoehen oder Fallback konfigurieren
Model not allowedModell nicht in der ErlaubnislisteAllowlist-Konfiguration prufen
Agent bootstrap pendingAgent wird initialisiertAbwarten -- dauert normalerweise 10--30 Sekunden
WebSocket connection closedWebSocket getrenntNetzwerkverbindung oder Reverse-Proxy-Konfiguration prufen

5. Empfehlungen zur praventiven Wartung

Anstatt reaktiv Fehler zu beheben, ist proaktive Pravention sinnvoller. Nachfolgend finden Sie eine Wartungs-Checkliste, die auf unserer Praxiserfahrung basiert:[5][6]

  1. Fuhren Sie wochentlich openclaw doctor aus: Auch wenn das System normal lauft, koennen regelmaessige Prufungen potenzielle Probleme fruhzeitig erkennen
  2. Halten Sie OpenClaw aktuell: Fuhren Sie npm update -g openclaw aus, um die neuesten Sicherheitspatches und Funktionsverbesserungen zu erhalten
  3. Konfigurieren Sie ein Fallback-Modell: Verlassen Sie sich niemals nur auf einen einzigen Modellanbieter
  4. Uberwachen Sie den Speicherverbrauch des Gateways: Langfristig laufende Gateways koennen Speicherlecks entwickeln -- ein wochentlicher Neustart wird empfohlen
  5. Sichern Sie das Verzeichnis ~/.openclaw/: Es enthalt alle Ihre Konfigurationen, Authentifizierungsdaten und Workspace-Daten

Fazit

openclaw doctor mit dem --fix-Flag kann uber achtzig Prozent der haufigen Probleme automatisch loesen.[1] Fur komplexere Probleme bieten die in diesem Artikel vorgestellte Log-Analyse und der systematische Fehlerbehebungsprozess Hilfe, um die Ursache schnell zu lokalisieren.

Wenn Sie gerade erst mit OpenClaw beginnen, empfehlen wir, zunachst unseren Leitfaden zur Architekturanalyse und Praxisbereitstellung zu lesen, um ein vollstandiges Systemverstandnis aufzubauen. Wenn Sie Konfigurationen anpassen muessen, konsultieren Sie den Konfigurationsleitfaden.