OpenClaw Troubleshooting Guide

Du kennst das: Alles ist konfiguriert, aber irgendwo hakt es. Keine Fehlermeldung ist auf den ersten Blick sichtbar und du klickst dich planlos durch Logs. Es ist frustrierend, wenn Tools nicht so reagieren, wie sie sollen, und du in einer Endlosschleife aus Ausprobieren und Scheitern steckst.

Wenn die Technik streikt, brauchst du eine klare Strategie statt Rätselraten. Dieser Guide hilft dir, Fehler in deinem Setup präzise zu isolieren und direkt zu beheben.

Voraussetzungen

Installiertes OpenClaw CLI
Zugriff auf dein Terminal

Quick Start: Fehlerdiagnose in 5 Minuten

Wenn es schnell gehen muss, nutze diese Befehlsabfolge als erste Anlaufstelle. Führe diese Befehle nacheinander aus:

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

So sieht ein gutes Ergebnis aus:

openclaw status: Zeigt konfigurierte Channels ohne offensichtliche Auth-Fehler.
openclaw status --all: Der vollständige Report ist vorhanden und kann geteilt werden.
openclaw gateway probe: Das Gateway-Ziel ist erreichbar.
openclaw gateway status: Zeigt Runtime: running und RPC probe: ok.
openclaw doctor: Keine blockierenden Config- oder Service-Fehler.
openclaw channels status --probe: Channels melden connected oder ready.
openclaw logs --follow: Kontinuierliche Aktivität ohne wiederkehrende Fatal-Errors.

Troubleshooting Entscheidungsbaum

Identifiziere zuerst, an welcher Stelle die Kette reißt:

flowchart TD
  A[OpenClaw funktioniert nicht] --> B{Was bricht zuerst ab}
  B --> C[Keine Antworten]
  B --> D[Dashboard oder Control UI verbindet nicht]
  B --> E[Gateway startet nicht oder Service läuft nicht]
  B --> F[Channel verbindet, aber Nachrichten fließen nicht]
  B --> G[Cron oder Heartbeat wurde nicht ausgelöst]
  B --> H[Node ist gepaart, aber Camera Canvas Screen Exec schlägt fehl]
  B --> I[Browser Tool schlägt fehl]

  C --> C1[/Keine Antworten Sektion/]
  D --> D1[/Control UI Sektion/]
  E --> E1[/Gateway Sektion/]
  F --> F1[/Channel Flow Sektion/]
  G --> G1[/Automation Sektion/]
  H --> H1[/Node Tools Sektion/]
  I --> I1[/Browser Sektion/]

Keine Antworten

Prüfe den Status mit diesen Befehlen:

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow

Guter Output:

Runtime: running
RPC probe: ok
Channel zeigt connected/ready
Sender ist approved (oder DM Policy ist offen)

Häufige Log-Einträge:

drop guild message (mention required: Mention-Gating blockiert Discord-Nachrichten.
pairing request: Sender ist nicht genehmigt und wartet auf DM-Pairing.
blocked: Sender oder Gruppe ist gefiltert.
allowlist: Filter in den Channel-Logs aktiv.

Dashboard oder Control UI verbindet nicht

Nutze diese Befehle zur Diagnose:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Guter Output:

Dashboard: http://... wird in openclaw gateway status angezeigt.
RPC probe: ok
Kein Auth-Loop in den Logs.

Häufige Log-Einträge:

device identity required: HTTP/unsicherer Kontext verhindert Device-Auth.
unauthorized: Falscher Token oder Passwort.
reconnect loop: Auth-Modus Mismatch.
gateway connect failed: UI nutzt falsche URL/Port oder Gateway ist unerreichbar.

Gateway startet nicht oder Service läuft nicht

Prüfe den Service-Status:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Guter Output:

Service: ... (loaded)
Runtime: running
RPC probe: ok

Häufige Log-Einträge:

Gateway start blocked: set gateway.mode=local: Modus ist ungesetzt oder remote.
refusing to bind gateway ... without auth: Non-Loopback Bind ohne Token.
another gateway instance is already listening: Port belegt.
EADDRINUSE: Adresse wird bereits verwendet.

Channel verbindet, aber Nachrichten fließen nicht

    openclaw status
    openclaw gateway status
    openclaw logs --follow
    openclaw doctor
    openclaw channels status --probe

Guter Output:

Channel Transport ist verbunden.
Pairing/Allowlist Checks sind erfolgreich.
Mentions werden erkannt, falls erforderlich.

Häufige Log-Einträge:

mention required: Group Mention Gating blockiert die Verarbeitung.
pairing / pending: DM-Sender ist noch nicht genehmigt.
not_in_channel / missing_scope: Berechtigungsproblem mit dem Token.
Forbidden / 401 / 403: Zugriff verweigert.

Cron oder Heartbeat wurde nicht ausgelöst

    openclaw status
    openclaw gateway status
    openclaw cron status
    openclaw cron list
    openclaw cron runs --id <jobId> --limit 20
    openclaw logs --follow

Guter Output:

cron.status ist enabled mit nächstem Wake-Zeitpunkt.
cron runs zeigt aktuelle ok Einträge.
Heartbeat ist aktiv und innerhalb der aktiven Stunden.

Häufige Log-Einträge:

cron: scheduler disabled: Jobs laufen nicht automatisch.
heartbeat skipped (reason=quiet-hours): Außerhalb der aktiven Stunden.
requests-in-flight: Main Lane belegt, Heartbeat verzögert.
unknown accountId: Ziel-Account für Heartbeat existiert nicht.

Node gepaart, aber Tool-Ausführung schlägt fehl

    openclaw status
    openclaw gateway status
    openclaw nodes status
    openclaw nodes describe --node <idOrNameOrIp>
    openclaw logs --follow

Guter Output:

Node ist als verbunden und gepaart gelistet.
Capability für den Befehl ist vorhanden.
Berechtigungen für das Tool sind erteilt.

Häufige Log-Einträge:

NODE_BACKGROUND_UNAVAILABLE: Node App muss in den Vordergrund.
*_PERMISSION_REQUIRED: OS-Berechtigung fehlt oder wurde abgelehnt.
SYSTEM_RUN_DENIED: approval required: Freigabe für Exec steht aus.
SYSTEM_RUN_DENIED: allowlist miss: Befehl nicht auf der Exec-Allowlist.

Browser Tool schlägt fehl

    openclaw status
    openclaw gateway status
    openclaw browser status
    openclaw logs --follow
    openclaw doctor

Guter Output:

Browser Status zeigt running: true.
Profil startet oder Chrome Relay hat einen verbundenen Tab.

Häufige Log-Einträge:

Failed to start Chrome CDP on port: Lokaler Browser-Start fehlgeschlagen.
browser.executablePath not found: Pfad zur Binary ist falsch.
Chrome extension relay is running, but no tab is connected: Extension nicht verbunden.
Browser attachOnly is enabled ... not reachable: Kein CDP-Ziel gefunden.

AI Setup Assistant

Nächste Schritte

Hier findest du vertiefende Informationen zu den einzelnen Bereichen:

OpenClaw Expert

Noch festgefahren?

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