--- read_when: - OpenClaw funktioniert nicht und Sie benötigen den schnellsten Weg zur Behebung - Sie möchten einen Triage-Ablauf, bevor Sie in detaillierte Runbooks einsteigen summary: Symptomorientierte zentrale Anlaufstelle zur Fehlerbehebung für OpenClaw title: Allgemeine Fehlerbehebung x-i18n: generated_at: "2026-05-06T06:52:01Z" model: gpt-5.5 provider: openai source_hash: 624fa34cda3b440fa9cc636beb3fe6e3608a77a332933fa593097ebc556ac745 source_path: help/troubleshooting.md workflow: 16 --- Wenn Sie nur 2 Minuten haben, verwenden Sie diese Seite als Triage-Einstieg. ## Erste 60 Sekunden Führen Sie diese genaue Abfolge der Reihe nach aus: ```bash openclaw status openclaw status --all openclaw gateway probe openclaw gateway status openclaw doctor openclaw channels status --probe openclaw logs --follow ``` Gute Ausgabe in einer Zeile: - `openclaw status` → zeigt konfigurierte Kanäle und keine offensichtlichen Authentifizierungsfehler. - `openclaw status --all` → vollständiger Bericht ist vorhanden und teilbar. - `openclaw gateway probe` → erwartetes Gateway-Ziel ist erreichbar (`Reachable: yes`). `Capability: ...` zeigt Ihnen, welche Authentifizierungsstufe der Probe nachweisen konnte, und `Read probe: limited - missing scope: operator.read` bedeutet eingeschränkte Diagnose, keinen Verbindungsfehler. - `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` und eine plausible Zeile `Capability: ...`. Verwenden Sie `--require-rpc`, wenn Sie zusätzlich einen RPC-Nachweis mit Lesebereich benötigen. - `openclaw doctor` → keine blockierenden Konfigurations-/Dienstfehler. - `openclaw channels status --probe` → ein erreichbares Gateway gibt den Live-Transportstatus pro Konto plus Probe-/Audit-Ergebnisse wie `works` oder `audit ok` zurück; wenn das Gateway nicht erreichbar ist, fällt der Befehl auf reine Konfigurationszusammenfassungen zurück. - `openclaw logs --follow` → stetige Aktivität, keine wiederholten fatalen Fehler. ## Anthropic Long-Context 429 Wenn Sie Folgendes sehen: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`, gehen Sie zu [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/de/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). ## Lokales OpenAI-kompatibles Backend funktioniert direkt, schlägt aber in OpenClaw fehl Wenn Ihr lokales oder selbst gehostetes `/v1`-Backend kleine direkte `/v1/chat/completions`-Probes beantwortet, aber bei `openclaw infer model run` oder normalen Agent-Durchläufen fehlschlägt: 1. Wenn der Fehler erwähnt, dass `messages[].content` eine Zeichenfolge erwartet, setzen Sie `models.providers..models[].compat.requiresStringContent: true`. 2. Wenn das Backend weiterhin nur bei OpenClaw-Agent-Durchläufen fehlschlägt, setzen Sie `models.providers..models[].compat.supportsTools: false` und versuchen Sie es erneut. 3. Wenn winzige direkte Aufrufe weiterhin funktionieren, größere OpenClaw-Prompts das Backend aber zum Absturz bringen, behandeln Sie das verbleibende Problem als Einschränkung des Upstream-Modells/-Servers und fahren Sie im ausführlichen Runbook fort: [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/de/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) ## Plugin-Installation schlägt wegen fehlender openclaw extensions fehl Wenn die Installation mit `package.json missing openclaw.extensions` fehlschlägt, verwendet das Plugin-Paket eine alte Struktur, die OpenClaw nicht mehr akzeptiert. Beheben Sie dies im Plugin-Paket: 1. Fügen Sie `openclaw.extensions` zu `package.json` hinzu. 2. Verweisen Sie Einträge auf gebaute Runtime-Dateien, üblicherweise `./dist/index.js`. 3. Veröffentlichen Sie das Plugin erneut und führen Sie `openclaw plugins install ` erneut aus. Beispiel: ```json { "name": "@openclaw/my-plugin", "version": "1.2.3", "openclaw": { "extensions": ["./dist/index.js"] } } ``` Referenz: [Plugin-Architektur](/de/plugins/architecture) ## Plugin vorhanden, aber durch verdächtige Eigentümerschaft blockiert Wenn `openclaw doctor`, Setup oder Startwarnungen Folgendes anzeigen: ```text blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) plugin present but blocked ``` gehören die Plugin-Dateien einem anderen Unix-Benutzer als dem Prozess, der sie lädt. Entfernen Sie die Plugin-Konfiguration nicht. Korrigieren Sie die Dateieigentümerschaft oder führen Sie OpenClaw als denselben Benutzer aus, dem das Statusverzeichnis gehört. Docker-Installationen laufen normalerweise als `node` (uid `1000`). Reparieren Sie für das Standard-Docker-Setup die Host-Bind-Mounts: ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace openclaw doctor --fix ``` Wenn Sie OpenClaw absichtlich als root ausführen, reparieren Sie stattdessen das verwaltete Plugin-Stammverzeichnis auf root-Eigentümerschaft: ```bash sudo chown -R root:root /path/to/openclaw-config/npm openclaw doctor --fix ``` Ausführlichere Dokumentation: - [Plugin-Pfadeigentümerschaft](/de/tools/plugin#blocked-plugin-path-ownership) - [Docker-Berechtigungen](/de/install/docker#permissions-and-eacces) ## Entscheidungsbaum ```mermaid flowchart TD A[OpenClaw is not working] --> B{What breaks first} B --> C[No replies] B --> D[Dashboard or Control UI will not connect] B --> E[Gateway will not start or service not running] B --> F[Channel connects but messages do not flow] B --> G[Cron or heartbeat did not fire or did not deliver] B --> H[Node is paired but camera canvas screen exec fails] B --> I[Browser tool fails] C --> C1[/No replies section/] D --> D1[/Control UI section/] E --> E1[/Gateway section/] F --> F1[/Channel flow section/] G --> G1[/Automation section/] H --> H1[/Node tools section/] I --> I1[/Browser section/] ``` ```bash openclaw status openclaw gateway status openclaw channels status --probe openclaw pairing list --channel [--account ] openclaw logs --follow ``` Gute Ausgabe sieht so aus: - `Runtime: running` - `Connectivity probe: ok` - `Capability: read-only`, `write-capable` oder `admin-capable` - Ihr Kanal zeigt, dass der Transport verbunden ist, und, sofern unterstützt, `works` oder `audit ok` in `channels status --probe` - Absender erscheint genehmigt, oder die DM-Richtlinie ist offen/eine Allowlist Häufige Log-Signaturen: - `drop guild message (mention required` → Mention-Gating hat die Nachricht in Discord blockiert. - `pairing request` → Absender ist nicht genehmigt und wartet auf DM-Pairing-Genehmigung. - `blocked` / `allowlist` in Kanal-Logs → Absender, Raum oder Gruppe wird gefiltert. Ausführliche Seiten: - [/gateway/troubleshooting#no-replies](/de/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/de/channels/troubleshooting) - [/channels/pairing](/de/channels/pairing) ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` Gute Ausgabe sieht so aus: - `Dashboard: http://...` wird in `openclaw gateway status` angezeigt - `Connectivity probe: ok` - `Capability: read-only`, `write-capable` oder `admin-capable` - Keine Authentifizierungsschleife in Logs Häufige Log-Signaturen: - `device identity required` → HTTP-/nicht sicherer Kontext kann Geräteauthentifizierung nicht abschließen. - `origin not allowed` → Browser-`Origin` ist für das Control-UI-Gateway-Ziel nicht erlaubt. - `AUTH_TOKEN_MISMATCH` mit Wiederholungshinweisen (`canRetryWithDeviceToken=true`) → ein vertrauenswürdiger Wiederholungsversuch mit Geräte-Token kann automatisch erfolgen. - Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet den zwischengespeicherten Scope-Satz wieder, der mit dem gekoppelten Geräte-Token gespeichert ist. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihren angeforderten Scope-Satz. - Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, ip}` serialisiert, bevor der Limiter den Fehler aufzeichnet; daher kann ein zweiter gleichzeitiger fehlerhafter Wiederholungsversuch bereits `retry later` anzeigen. - `too many failed authentication attempts (retry later)` von einem localhost- Browser-Ursprung → wiederholte Fehler von demselben `Origin` werden vorübergehend ausgesperrt; ein anderer localhost-Ursprung verwendet einen separaten Bucket. - wiederholtes `unauthorized` nach diesem Wiederholungsversuch → falscher Token/falsches Passwort, Authentifizierungsmodus stimmt nicht überein oder veralteter gekoppelter Geräte-Token. - `gateway connect failed:` → UI zielt auf die falsche URL/den falschen Port oder ein nicht erreichbares Gateway. Ausführliche Seiten: - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/de/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/de/web/control-ui) - [/gateway/authentication](/de/gateway/authentication) ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` Gute Ausgabe sieht so aus: - `Service: ... (loaded)` - `Runtime: running` - `Connectivity probe: ok` - `Capability: read-only`, `write-capable` oder `admin-capable` Häufige Log-Signaturen: - `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → Gateway-Modus ist remote, oder der Konfigurationsdatei fehlt der Local-Mode-Stempel und sie sollte repariert werden. - `refusing to bind gateway ... without auth` → Non-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder trusted-proxy, wo konfiguriert). - `another gateway instance is already listening` oder `EADDRINUSE` → Port bereits belegt. Ausführliche Seiten: - [/gateway/troubleshooting#gateway-service-not-running](/de/gateway/troubleshooting#gateway-service-not-running) - [/gateway/background-process](/de/gateway/background-process) - [/gateway/configuration](/de/gateway/configuration) ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` Gute Ausgabe sieht so aus: - Kanaltransport ist verbunden. - Pairing-/Allowlist-Prüfungen bestehen. - Mentions werden erkannt, wo sie erforderlich sind. Häufige Log-Signaturen: - `mention required` → Gruppen-Mention-Gating hat die Verarbeitung blockiert. - `pairing` / `pending` → DM-Absender ist noch nicht genehmigt. - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → Problem mit Kanalberechtigungs-Token. Ausführliche Seiten: - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/de/gateway/troubleshooting#channel-connected-messages-not-flowing) - [/channels/troubleshooting](/de/channels/troubleshooting) ```bash openclaw status openclaw gateway status openclaw cron status openclaw cron list openclaw cron runs --id --limit 20 openclaw logs --follow ``` Gute Ausgabe sieht so aus: - `cron.status` zeigt aktiviert mit nächstem Aufwachen. - `cron runs` zeigt aktuelle `ok`-Einträge. - Heartbeat ist aktiviert und nicht außerhalb aktiver Stunden. Häufige Log-Signaturen: - `cron: scheduler disabled; jobs will not run automatically` → Cron ist deaktiviert. - `heartbeat skipped` mit `reason=quiet-hours` → außerhalb der konfigurierten aktiven Stunden. - `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` existiert, enthält aber nur leeres/nur aus Überschriften bestehendes Gerüst. - `heartbeat skipped` mit `reason=no-tasks-due` → `HEARTBEAT.md`-Aufgabenmodus ist aktiv, aber keines der Aufgabenintervalle ist bereits fällig. - `heartbeat skipped` mit `reason=alerts-disabled` → gesamte Heartbeat-Sichtbarkeit ist deaktiviert (`showOk`, `showAlerts` und `useIndicator` sind alle aus). - `requests-in-flight` → Haupt-Lane beschäftigt; Heartbeat-Aufwecken wurde zurückgestellt. - `unknown accountId` → Heartbeat-Zustellzielkonto existiert nicht. Ausführliche Seiten: - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/de/gateway/troubleshooting#cron-and-heartbeat-delivery) - [/automation/cron-jobs#troubleshooting](/de/automation/cron-jobs#troubleshooting) - [/gateway/heartbeat](/de/gateway/heartbeat) ```bash openclaw status openclaw gateway status openclaw nodes status openclaw nodes describe --node openclaw logs --follow ``` Gute Ausgabe sieht so aus: - Node wird als verbunden und für Rolle `node` gekoppelt aufgeführt. - Capability existiert für den Befehl, den Sie aufrufen. - Berechtigungsstatus ist für das Tool gewährt. Häufige Log-Signaturen: - `NODE_BACKGROUND_UNAVAILABLE` → Node-App in den Vordergrund bringen. - `*_PERMISSION_REQUIRED` → OS-Berechtigung wurde verweigert/fehlt. - `SYSTEM_RUN_DENIED: approval required` → Exec-Genehmigung steht aus. - `SYSTEM_RUN_DENIED: allowlist miss` → Befehl steht nicht auf der Exec-Allowlist. Detailseiten: - [/gateway/troubleshooting#node-paired-tool-fails](/de/gateway/troubleshooting#node-paired-tool-fails) - [/nodes/troubleshooting](/de/nodes/troubleshooting) - [/tools/exec-approvals](/de/tools/exec-approvals) ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security openclaw config get tools.exec.ask openclaw gateway restart ``` Was sich geändert hat: - Wenn `tools.exec.host` nicht gesetzt ist, ist der Standardwert `auto`. - `host=auto` wird zu `sandbox` aufgelöst, wenn eine Sandbox-Runtime aktiv ist, andernfalls zu `gateway`. - `host=auto` steuert nur das Routing; das promptfreie „YOLO“-Verhalten kommt von `security=full` plus `ask=off` auf Gateway/Node. - Auf `gateway` und `node` ist der Standardwert für nicht gesetztes `tools.exec.security` `full`. - Der Standardwert für nicht gesetztes `tools.exec.ask` ist `off`. - Ergebnis: Wenn Sie Genehmigungen sehen, hat eine host-lokale oder sitzungsbezogene Richtlinie Exec gegenüber den aktuellen Standardwerten verschärft. Aktuelles Standardverhalten ohne Genehmigung wiederherstellen: ```bash openclaw config set tools.exec.host gateway openclaw config set tools.exec.security full openclaw config set tools.exec.ask off openclaw gateway restart ``` Sicherere Alternativen: - Setzen Sie nur `tools.exec.host=gateway`, wenn Sie lediglich stabiles Host-Routing möchten. - Verwenden Sie `security=allowlist` mit `ask=on-miss`, wenn Sie Host-Exec möchten, Allowlist-Fehltreffer aber weiterhin prüfen wollen. - Aktivieren Sie den Sandbox-Modus, wenn `host=auto` wieder zu `sandbox` aufgelöst werden soll. Häufige Log-Signaturen: - `Approval required.` → Befehl wartet auf `/approve ...`. - `SYSTEM_RUN_DENIED: approval required` → Node-Host-Exec-Genehmigung steht aus. - `exec host=sandbox requires a sandbox runtime for this session` → implizite/explizite Sandbox-Auswahl, aber der Sandbox-Modus ist deaktiviert. Detailseiten: - [/tools/exec](/de/tools/exec) - [/tools/exec-approvals](/de/tools/exec-approvals) - [/gateway/security#what-the-audit-checks-high-level](/de/gateway/security#what-the-audit-checks-high-level) ```bash openclaw status openclaw gateway status openclaw browser status openclaw logs --follow openclaw doctor ``` Gute Ausgabe sieht so aus: - Browser-Status zeigt `running: true` und einen ausgewählten Browser/ein ausgewähltes Profil. - `openclaw` startet, oder `user` kann lokale Chrome-Tabs sehen. Häufige Log-Signaturen: - `unknown command "browser"` oder `unknown command 'browser'` → `plugins.allow` ist gesetzt und enthält `browser` nicht. - `Failed to start Chrome CDP on port` → lokaler Browser-Start ist fehlgeschlagen. - `browser.executablePath not found` → konfigurierter Binärpfad ist falsch. - `browser.cdpUrl must be http(s) or ws(s)` → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema. - `browser.cdpUrl has invalid port` → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des Bereichs liegenden Port. - `No Chrome tabs found for profile="user"` → das Chrome-MCP-Attach-Profil hat keine geöffneten lokalen Chrome-Tabs. - `Remote CDP for profile "" is not reachable` → der konfigurierte Remote-CDP-Endpunkt ist von diesem 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 aktives CDP-Ziel. - veraltete Viewport-/Dark-Mode-/Locale-/Offline-Overrides bei Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile ` aus, um die aktive Steuersitzung zu schließen und den Emulationszustand freizugeben, ohne das Gateway neu zu starten. Detailseiten: - [/gateway/troubleshooting#browser-tool-fails](/de/gateway/troubleshooting#browser-tool-fails) - [/tools/browser#missing-browser-command-or-tool](/de/tools/browser#missing-browser-command-or-tool) - [/tools/browser-linux-troubleshooting](/de/tools/browser-linux-troubleshooting) - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/de/tools/browser-wsl2-windows-remote-cdp-troubleshooting) ## Verwandt - [FAQ](/de/help/faq) — häufig gestellte Fragen - [Gateway-Fehlerbehebung](/de/gateway/troubleshooting) — Gateway-spezifische Probleme - [Doctor](/de/gateway/doctor) — automatisierte Integritätsprüfungen und Reparaturen - [Kanal-Fehlerbehebung](/de/channels/troubleshooting) — Probleme mit der Kanalkonnektivität - [Automatisierungs-Fehlerbehebung](/de/automation/cron-jobs#troubleshooting) — Cron- und Heartbeat-Probleme