Gateway Troubleshooting Guide – So bringst du openclaw wieder zum Laufen

Du kennst das: Gestern lief noch alles perfekt, heute antwortet das Gateway plötzlich nicht mehr. Fehlersuche kann extrem nervig sein, besonders wenn man unter Zeitdruck steht und nicht weiß, an welchem Ende man anfangen soll. Oft sind es nur Kleinigkeiten in der Config oder fehlende Berechtigungen, die den Flow blockieren.

Anstatt wahllos Einstellungen zu ändern, solltest du systematisch vorgehen. Dieser Guide zeigt dir, wie du die Ursache schnell isolierst und behebst.

Voraussetzungen

Bevor du startest, stelle sicher, dass du Zugriff auf folgende Komponenten hast:

Eine installierte Version von openclaw
Zugriff auf das Terminal oder die CLI der Instanz
Die entsprechenden Log-Dateien deines Systems

Quick Start: Die 5-Minuten-Analyse

Wenn etwas nicht stimmt, arbeite diese Befehle in genau dieser Reihenfolge ab. Das ist der schnellste Weg, um den Status zu prüfen:

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

Woran du erkennst, dass alles okay ist:

openclaw gateway status zeigt Runtime: running und RPC probe: ok.
openclaw doctor findet keine blockierenden Config- oder Service-Probleme.
openclaw channels status --probe zeigt verbundene und bereite Kanäle.

Fehlerbehebung

Hier sind die häufigsten Szenarien und wie du sie löst.

Keine Antworten (No replies)

Falls die Kanäle zwar “up” sind, aber niemand antwortet, liegt es meist am Routing oder an den Policies. Prüfe das mit:

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

Achte in den Logs auf diese Signale:

drop guild message (mention required): Gruppen-Nachrichten werden ignoriert, bis eine Mention erfolgt.
pairing request: Der Absender benötigt erst eine Freigabe.
blocked / allowlist: Der Absender oder Kanal wurde durch eine Policy gefiltert.

Dashboard und Control UI verbinden nicht

Wenn das Dashboard keine Verbindung bekommt, liegt es oft an der URL, dem Auth-Modus oder dem Kontext.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

Häufige Ursachen:

device identity required: Ein nicht-sicherer Kontext oder fehlende Device-Auth.
unauthorized / Reconnect-Loop: Token oder Passwort stimmen nicht überein.
gateway connect failed:: Falscher Host, Port oder Ziel-URL.

Gateway-Dienst läuft nicht

Nutze diese Befehle, wenn der Dienst zwar installiert ist, aber der Prozess immer wieder abbricht:

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

Suche nach diesen Fehlern:

Gateway start blocked: set gateway.mode=local: Der lokale Modus ist nicht aktiviert.
refusing to bind gateway ... without auth: Bindung an eine IP (außer Loopback) ohne Token/Passwort.
EADDRINUSE: Ein anderer Prozess belegt bereits den Port.

Kanal verbunden, aber keine Nachrichten

Der Status ist grün, aber es fließen keine Daten? Dann sind meist Berechtigungen oder Policy-Regeln schuld.

openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Checke diese Punkte:

mention required: Die Group-Mention-Policy blockiert die Nachricht.
missing_scope, Forbidden, 401/403: Probleme mit der Channel-API oder den Berechtigungen.

Cron-Jobs und Heartbeats

Wenn geplante Aufgaben nicht laufen, prüfe zuerst den Scheduler und dann das Ziel.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Typische Meldungen:

cron: scheduler disabled: Die automatische Ausführung ist deaktiviert.
heartbeat skipped mit reason=quiet-hours: Du befindest dich außerhalb des aktiven Zeitfensters.

Node-Tools oder Browser-Fehler

Falls ein Node zwar gepairt ist, aber Tools fehlschlagen, liegt es oft an OS-Berechtigungen oder dem Fokus.

Für Nodes:

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

NODE_BACKGROUND_UNAVAILABLE: Die App muss im Vordergrund laufen.
SYSTEM_RUN_DENIED: Die Freigabe für den Befehl fehlt.

Für Browser-Tools:

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw logs --follow

browser.executablePath not found: Der Pfad zur Browser-Executable ist falsch.
Chrome extension relay is running, but no tab is connected: Die Extension ist nicht aktiv.

Probleme nach einem Upgrade

Nach Upgrades liegt es meist an strengeren Sicherheitsregeln oder Config-Änderungen.

Auth & URL Verhalten: Wenn gateway.mode=remote aktiv ist, zielen CLI-Aufrufe eventuell auf ein Remote-Ziel, während dein lokaler Service eigentlich läuft.
Strenge Bind-Regeln: Binds an lan oder tailnet erfordern jetzt zwingend eine konfigurierte Authentifizierung. Prüfe gateway.auth.token.
Identity-Status: Prüfe mit openclaw devices list, ob die Geräte-ID noch autorisiert ist.

Falls gar nichts mehr hilft, installiere die Service-Metadaten neu:

openclaw gateway install --force
openclaw gateway restart

Du hast noch Fragen oder brauchst Hilfe bei einem speziellen Fehler? Frag unseren AI Setup Assistant.

Nächste Schritte

OpenClaw Expert

Noch festgefahren?

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