English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Start here

Allgemeine Fehlerbehebung

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:

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.

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.<provider>.models[].compat.requiresStringContent: true.
  2. Wenn das Backend weiterhin nur bei OpenClaw-Agent-Durchläufen fehlschlägt, setzen Sie models.providers.<provider>.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

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 <package> erneut aus.

Beispiel:

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Referenz: Plugin-Architektur

Plugin vorhanden, aber durch verdächtige Eigentümerschaft blockiert

Wenn openclaw doctor, Setup oder Startwarnungen Folgendes anzeigen:

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:

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:

sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

Ausführlichere Dokumentation:

Entscheidungsbaum

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/]
Keine Antworten 
openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
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:

Dashboard oder Control UI stellt keine Verbindung her 
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 startet nicht oder Dienst ist installiert, läuft aber nicht 
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:

Kanal verbindet sich, aber Nachrichten fließen nicht 
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:

Cron oder Heartbeat wurde nicht ausgelöst oder nicht zugestellt 
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --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:

Node ist gekoppelt, aber Tool schlägt bei Kamera, Canvas, Bildschirm oder Ausführung fehl 
openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
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:

Exec fragt plötzlich nach Genehmigung 
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:

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:

Browser-Tool schlägt fehl 
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 "<name>" 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 <name> aus, um die aktive Steuersitzung zu schließen und den Emulationszustand freizugeben, ohne das Gateway neu zu starten.

Detailseiten:

Verwandt