Fehlerbehebung

• model_not_found mit einem lokalen MLX/vLLM-artigen Server → prüfen Sie, ob baseUrl /v1 enthält, api für /v1/chat/completions-Backends "openai-completions" ist und models.providers.<provider>.models[].id die reine provider-lokale ID ist. Wählen Sie sie einmal mit dem Provider-Präfix aus, zum Beispiel mlx/mlx-community/Qwen3-30B-A3B-6bit; belassen Sie den Katalogeintrag als mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → Backend lehnt strukturierte Chat-Completions-Inhaltsteile ab. Behebung: Setzen Sie models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → das Backend hat die Chat-Completions-Anfrage abgeschlossen, aber für diesen Turn keinen für Benutzer sichtbaren Assistententext zurückgegeben. OpenClaw wiederholt replay-sichere leere OpenAI-kompatible Turns einmal; anhaltende Fehler bedeuten normalerweise, dass das Backend leere/Nicht-Text-Inhalte ausgibt oder Final-Answer-Text unterdrückt.
• direkte winzige Anfragen sind erfolgreich, aber OpenClaw-Agentenläufe schlagen mit Backend-/Modellabstürzen fehl (zum Beispiel Gemma auf einigen inferrs-Builds) → der OpenClaw-Transport ist wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Prompt-Struktur der Agent-Runtime.
• Fehler nehmen nach dem Deaktivieren von Tools ab, verschwinden aber nicht → Tool-Schemas waren Teil des Drucks, aber das verbleibende Problem ist weiterhin Upstream-Modell-/Serverkapazität oder ein Backend-Fehler.

1. Setzen Sie compat.requiresStringContent: true für Chat-Completions-Backends, die nur Zeichenfolgen unterstützen.
2. Setzen Sie compat.supportsTools: false für Modelle/Backends, die OpenClaws Tool-Schema-Oberfläche nicht zuverlässig verarbeiten können.
3. Reduzieren Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzere Sitzungshistorie, leichteres lokales Modell oder ein Backend mit stärkerer Long-Context-Unterstützung.
4. Wenn winzige direkte Anfragen weiterhin funktionieren, während OpenClaw-Agenten-Turns noch im Backend abstürzen, behandeln Sie dies als Upstream-Server-/Modellbeschränkung und reichen Sie dort eine Reproduktion mit der akzeptierten Payload-Struktur ein.

• device identity required → nicht sicherer Kontext oder fehlende Geräteauthentifizierung.
• origin not allowed → Browser-Origin ist nicht in gateway.controlUi.allowedOrigins (oder Sie verbinden sich von einem Nicht-Loopback-Browser-Ursprung ohne explizite Allowlist).
• device nonce required / device nonce mismatch → Client schließt den Challenge-basierten Geräteauthentifizierungsablauf (connect.challenge + device.nonce) nicht ab.
• device signature invalid / device signature expired → Client hat die falsche Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
• AUTH_TOKEN_MISMATCH mit canRetryWithDeviceToken=true → Client kann einen vertrauenswürdigen Wiederholungsversuch mit zwischengespeichertem Geräte-Token ausführen.
• Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet den zwischengespeicherten Scope-Satz, der mit dem gekoppelten Geräte-Token gespeichert ist. Aufrufer mit explizitem deviceToken / expliziten scopes behalten stattdessen ihren angeforderten Scope-Satz.
• Außerhalb dieses Wiederholungsversuchspfads gilt für Connect-Authentifizierung die Rangfolge: zuerst explizites Shared-Token/Passwort, dann explizites deviceToken, dann gespeichertes Geräte-Token, dann Bootstrap-Token.
• Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für denselben {scope, ip} serialisiert, bevor der Limiter den Fehler erfasst. Zwei fehlerhafte gleichzeitige Wiederholungen vom selben Client können daher beim zweiten Versuch retry later statt zwei einfacher Abweichungen anzeigen.
• too many failed authentication attempts (retry later) von einem Browser-Origin-Loopback-Client → wiederholte Fehler von demselben normalisierten Origin werden vorübergehend gesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
• wiederholt unauthorized nach diesem Wiederholungsversuch → Shared-Token-/Geräte-Token-Drift; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie bei Bedarf das Geräte-Token erneut.
• gateway connect failed: → falsches Host-/Port-/URL-Ziel.

• Gateway start blocked: set gateway.mode=local oder existing config is missing gateway.mode → lokaler Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde überschrieben und hat gateway.mode verloren. Lösung: Setzen Sie gateway.mode="local" in Ihrer Konfiguration, oder führen Sie erneut openclaw onboard --mode local / openclaw setup aus, um die erwartete lokale Moduskonfiguration neu zu setzen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardkonfigurationspfad ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder trusted-proxy, falls konfiguriert).
• another gateway instance is already listening / EADDRINUSE → Portkonflikt.
• Other gateway-like services detected (best effort) → veraltete oder parallele launchd-/systemd-/schtasks-Units sind vorhanden. Die meisten Setups sollten ein Gateway pro Maschine verwenden; wenn Sie mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Status/Workspace. Siehe /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected von doctor → Eine systemd-System-Unit ist vorhanden, während der Dienst auf Benutzerebene fehlt. Entfernen oder deaktivieren Sie das Duplikat, bevor Sie doctor erlauben, einen Benutzerdienst zu installieren, oder setzen Sie OPENCLAW_SERVICE_REPAIR_POLICY=external, wenn die System-Unit der beabsichtigte Supervisor ist.
• Gateway service port does not match current gateway config → Der installierte Supervisor fixiert weiterhin den alten --port. Führen Sie openclaw doctor --fix oder openclaw gateway install --force aus, und starten Sie dann den Gateway-Dienst neu.

• Die Konfiguration wurde beim Start, beim Hot Reload oder bei einem von OpenClaw verantworteten Schreibvorgang nicht validiert.
• Der Gateway-Start schlägt geschlossen fehl, statt openclaw.json umzuschreiben.
• Hot Reload überspringt ungültige externe Bearbeitungen und hält die aktuelle Laufzeitkonfiguration aktiv.
• Von OpenClaw verantwortete Schreibvorgänge lehnen ungültige/destruktive Payloads vor dem Commit ab und speichern .rejected.*.
• openclaw doctor --fix ist für Reparaturen zuständig. Es kann Nicht-JSON-Präfixe entfernen oder die letzte bekannte gute Kopie wiederherstellen, während die abgelehnte Payload als .clobbered.* erhalten bleibt.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* ist vorhanden → doctor hat eine beschädigte externe Bearbeitung bewahrt, während die aktive Konfiguration repariert wurde.
• .rejected.* ist vorhanden → Ein von OpenClaw verantworteter Konfigurationsschreibvorgang ist vor dem Commit an Schema- oder Clobber-Prüfungen gescheitert.
• Config write rejected: → Der Schreibvorgang versuchte, erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder ungültige Konfiguration zu persistieren.
• config reload skipped (invalid config): → Eine direkte Bearbeitung hat die Validierung nicht bestanden und wurde vom laufenden Gateway ignoriert.
• Invalid config at ... → Der Start ist fehlgeschlagen, bevor Gateway-Dienste gestartet wurden.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good oder size-drop-vs-last-good:* → Ein von OpenClaw verantworteter Schreibvorgang wurde abgelehnt, weil er im Vergleich zur letzten bekannten guten Sicherung Felder oder Größe verloren hat.
• Config last-known-good promotion skipped → Der Kandidat enthielt redigierte Secret-Platzhalter wie ***.

1. Führen Sie openclaw doctor --fix aus, damit doctor eine vorangestellte/überschriebene Konfiguration repariert oder die letzte bekannte gute Version wiederherstellt.
2. Kopieren Sie nur die beabsichtigten Schlüssel aus .clobbered.* oder .rejected.*, und wenden Sie sie dann mit openclaw config set oder config.patch an.
3. Führen Sie openclaw config validate aus, bevor Sie neu starten.
4. Wenn Sie manuell bearbeiten, behalten Sie die vollständige JSON5-Konfiguration bei, nicht nur das Teilobjekt, das Sie ändern wollten.

• cron: scheduler disabled; jobs will not run automatically → Cron deaktiviert.
• cron: timer tick failed → Scheduler-Tick fehlgeschlagen; prüfen Sie Datei-/Log-/Runtime-Fehler.
• heartbeat skipped mit reason=quiet-hours → außerhalb des aktiven Zeitfensters.
• heartbeat skipped mit reason=empty-heartbeat-file → HEARTBEAT.md existiert, enthält aber nur Leerzeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf.
• heartbeat skipped mit reason=no-tasks-due → HEARTBEAT.md enthält einen tasks:-Block, aber keine der Aufgaben ist bei diesem Tick fällig.
• heartbeat: unknown accountId → ungültige Konto-ID für das Heartbeat-Zustellungsziel.
• heartbeat skipped mit reason=dm-blocked → Heartbeat-Ziel wurde zu einem DM-ähnlichen Ziel aufgelöst, während agents.defaults.heartbeat.directPolicy (oder eine agentenspezifische Überschreibung) auf block gesetzt ist.

• unknown command "browser" oder unknown command 'browser' → das gebündelte Browser-Plugin wird durch plugins.allow ausgeschlossen.
• Browser-Tool fehlt / nicht verfügbar, während browser.enabled=true → plugins.allow schließt browser aus, daher wurde das Plugin nie geladen.
• Failed to start Chrome CDP on port → Browser-Prozess konnte nicht gestartet werden.
• browser.executablePath not found → konfigurierter Pfad ist ungültig.
• browser.cdpUrl must be http(s) or ws(s) → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema wie file: oder ftp:.
• browser.cdpUrl has invalid port → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des Bereichs liegenden Port.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → der aktuellen Gateway-Installation fehlt die zentrale Browser-Runtime-Abhängigkeit; installieren oder aktualisieren Sie OpenClaw erneut und starten Sie dann den Gateway neu. ARIA-Snapshots und einfache Seiten-Screenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session konnte noch nicht an das ausgewählte Browser-Datenverzeichnis anhängen. Öffnen Sie die Browser-Inspect-Seite, aktivieren Sie Remote-Debugging, lassen Sie den Browser geöffnet, genehmigen Sie die erste Attach-Aufforderung und versuchen Sie es erneut. Wenn der angemeldete Zustand nicht erforderlich ist, bevorzugen Sie das verwaltete openclaw-Profil.
• No Chrome tabs found for profile="user" → das Chrome-MCP-Attach-Profil hat keine geöffneten lokalen Chrome-Tabs.
• Remote CDP for profile "<name>" is not reachable → der konfigurierte Remote-CDP-Endpunkt ist vom Gateway-Host aus nicht erreichbar.
• Browser attachOnly is enabled ... not reachable oder Browser attachOnly is enabled and CDP websocket ... is not reachable → Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber der CDP-WebSocket konnte trotzdem nicht geöffnet werden.

• fullPage is not supported for element screenshots → Screenshot-Anforderung hat --full-page mit --ref oder --element kombiniert.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome-MCP- / existing-session-Screenshot-Aufrufe müssen Seitenerfassung oder eine Snapshot---ref verwenden, nicht CSS---element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome-MCP-Upload-Hooks benötigen Snapshot-Refs, keine CSS-Selektoren.
• existing-session file uploads currently support one file at a time. → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf.
• existing-session dialog handling does not support timeoutMs. → Dialog-Hooks auf Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
• existing-session type does not support timeoutMs overrides. → lassen Sie timeoutMs für act:type bei profile="user"- / Chrome-MCP-existing-session-Profilen weg, oder verwenden Sie ein verwaltetes/CDP-Browser-Profil, wenn ein benutzerdefinierter Timeout erforderlich ist.
• existing-session evaluate does not support timeoutMs overrides. → lassen Sie timeoutMs für act:evaluate bei profile="user"- / Chrome-MCP-existing-session-Profilen weg, oder verwenden Sie ein verwaltetes/CDP-Browser-Profil, wenn ein benutzerdefinierter Timeout erforderlich ist.
• response body is not supported for existing-session profiles yet. → responsebody erfordert weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil.
• veraltete Viewport- / Dark-Mode- / Locale- / Offline-Überschreibungen auf Attach-only- oder Remote-CDP-Profilen → führen Sie openclaw browser stop --browser-profile <name> aus, um die aktive Steuersitzung zu schließen und den Playwright-/CDP-Emulationszustand freizugeben, ohne den gesamten Gateway neu zu starten.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Was zu prüfen ist:

• Wenn gateway.mode=remote, zielen CLI-Aufrufe möglicherweise auf die Remote-Instanz, während Ihr lokaler Dienst in Ordnung ist.
• Explizite --url-Aufrufe fallen nicht auf gespeicherte Anmeldedaten zurück.

Häufige Signaturen:

• gateway connect failed: → falsches URL-Ziel.
• unauthorized → Endpunkt erreichbar, aber falsche Authentifizierung.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Was zu prüfen ist:

• Nicht-Loopback-Binds (lan, tailnet, custom) benötigen einen gültigen Gateway-Authentifizierungspfad: Authentifizierung per gemeinsamem Token/Passwort oder eine korrekt konfigurierte Nicht-Loopback-trusted-proxy-Bereitstellung.
• Alte Schlüssel wie gateway.token ersetzen gateway.auth.token nicht.

Häufige Signaturen:

• refusing to bind gateway ... without auth → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad.
• Connectivity probe: failed, während die Runtime läuft → Gateway ist aktiv, aber mit aktueller Authentifizierung/URL nicht zugänglich.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Was zu prüfen ist:

• Ausstehende Gerätegenehmigungen für Dashboard/Nodes.
• Ausstehende DM-Kopplungsgenehmigungen nach Richtlinien- oder Identitätsänderungen.

Häufige Signaturen:

• device identity required → Geräteauthentifizierung nicht erfüllt.
• pairing required → Absender/Gerät muss genehmigt werden.