Modell-Failover

OpenClaw behandelt Fehler in zwei Stufen:

1. Rotation von Auth-Profilen innerhalb des aktuellen Providers.
2. Modell-Fallback auf das nächste Modell in agents.defaults.model.fallbacks.

Dieses Dokument erklärt die Laufzeitregeln und die Daten, auf denen sie basieren.

Laufzeitablauf

Für einen normalen Textlauf bewertet OpenClaw Kandidaten in dieser Reihenfolge:

Dies ist absichtlich enger gefasst als „die ganze Sitzung speichern und wiederherstellen“. Der Reply-Runner persistiert nur die Felder für die Modellauswahl, die er für den Fallback besitzt:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Das verhindert, dass ein fehlgeschlagener Fallback-Wiederholungsversuch neuere, nicht zusammenhängende Sitzungsmutationen überschreibt, etwa manuelle /model-Änderungen oder Aktualisierungen der Sitzungsrotation, die während des laufenden Versuchs passiert sind.

Richtlinie für Auswahlquellen

OpenClaw trennt den ausgewählten Provider und das Modell davon, warum sie ausgewählt wurden. Diese Quelle steuert, ob die Fallback-Kette erlaubt ist:

• Konfigurierter Standardwert: agents.defaults.model.primary verwendet agents.defaults.model.fallbacks.
• Primäres Agent-Modell: agents.list[].model ist strikt, es sei denn, dieses Agent-Modellobjekt enthält eigene fallbacks. Verwenden Sie fallbacks: [], um das strikte Verhalten explizit zu machen, oder geben Sie eine nicht leere Liste an, um diesen Agent für Modell-Fallback zu aktivieren.
• Automatischer Fallback-Override: Ein Laufzeit-Fallback schreibt providerOverride, modelOverride, modelOverrideSource: "auto" und das ausgewählte Ursprungsmodell, bevor er es erneut versucht. Dieser automatische Override kann die konfigurierte Fallback-Kette weiter durchlaufen, ohne bei jeder Nachricht das primäre Modell zu prüfen, aber OpenClaw prüft den konfigurierten Ursprung regelmäßig erneut und entfernt den automatischen Override, wenn er sich erholt. /new, /reset und sessions.reset entfernen ebenfalls automatisch gesetzte Overrides. Heartbeat-Läufe ohne explizites heartbeat.model entfernen direkte automatische Overrides, wenn deren Ursprung nicht mehr dem aktuellen konfigurierten Standard entspricht.
• Benutzer-Override in der Sitzung: /model, die Modellauswahl, session_status(model=...) und sessions.patch schreiben modelOverrideSource: "user". Das ist eine exakte Sitzungsauswahl. Wenn der ausgewählte Provider oder das ausgewählte Modell fehlschlägt, bevor eine Antwort erzeugt wird, meldet OpenClaw den Fehler, statt aus einem nicht zusammenhängenden konfigurierten Fallback zu antworten.
• Legacy-Sitzungs-Override: Ältere Sitzungseinträge können modelOverride ohne modelOverrideSource enthalten. OpenClaw behandelt diese als Benutzer-Overrides, damit eine explizite alte Auswahl nicht stillschweigend in Fallback-Verhalten umgewandelt wird.
• Cron-Nutzlastmodell: Ein Cron-Job payload.model / --model ist ein primäres Job-Modell, kein Benutzer-Override in der Sitzung. Es verwendet konfigurierte Fallbacks, sofern der Job nicht payload.fallbacks bereitstellt; payload.fallbacks: [] macht den Cron-Lauf strikt.

Das Intervall für die Primärprüfung beim automatischen Fallback beträgt fünf Minuten und ist nicht konfigurierbar. OpenClaw merkt sich aktuelle Prüfungen pro Sitzung und primärem Modell, damit ein fehlschlagendes primäres Modell nicht bei jedem Turn erneut versucht wird. OpenClaw sendet einen sichtbaren Hinweis, wenn eine Sitzung auf einen Fallback wechselt, und einen weiteren Hinweis, wenn sie zum ausgewählten primären Modell zurückkehrt; der Hinweis wird nicht bei jedem Sticky-Fallback-Turn wiederholt.

Skip-Cache für Auth-Fehler

Standardmäßig behält jeder neue Turn das bestehende Fallback-Wiederholungsverhalten bei: OpenClaw versucht jeden konfigurierten Fallback-Kandidaten erneut, einschließlich nicht primärer Kandidaten, die kürzlich mit auth oder auth_permanent fehlgeschlagen sind.

Betreiber, die diese wiederholten Auth-Fehler unterdrücken möchten, können dies aktivieren mit:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Wenn aktiviert, zeichnet OpenClaw nach einem Fehler der Auth-Klasse einen sitzungsbezogenen Skip-Marker im Arbeitsspeicher für einen nicht primären Fallback-Kandidaten auf. Der Marker wird nach Sitzungs-ID, Provider und Modell geschlüsselt. Primäre Kandidaten werden nie übersprungen, sodass eine explizite Benutzermodellauswahl weiterhin den echten Auth-Fehler sichtbar macht. Der Cache ist prozesslokal und wird bei einem Gateway-Neustart gelöscht.

Der Wert ist eine TTL in Millisekunden. 0 oder ein nicht gesetzter Wert deaktiviert den Cache. Positive Werte werden auf einen Bereich zwischen 1 Sekunde und 10 Minuten begrenzt.

Für Benutzer sichtbare Fallback-Hinweise

Wenn eine Sitzung auf einen automatisch ausgewählten Fallback wechselt, sendet OpenClaw einen Statushinweis auf derselben Antwortoberfläche:

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

Wenn eine spätere Prüfung erfolgreich ist und die Sitzung zum ausgewählten primären Modell zurückkehrt, sendet OpenClaw:

↪️ Model Fallback cleared: <primary> (was <fallback>)

Diese Hinweise sind operative Nachrichten, keine Assistenteninhalte. Sie werden einmal pro Statusänderung zugestellt, einschließlich nur aus Seiteneffekten bestehender Turns, wenn möglich, aber Sticky-Fallback-Turns wiederholen sie nicht. Die Zustellung umgeht die normale Unterdrückung von Quellantworten, der Hinweis belegt nicht den ersten Assistentenantwort-Slot für Thread-Kanäle, und er ist von Text-to-Speech und Commitment-Extraktion ausgeschlossen.

Auth-Speicher (Schlüssel + OAuth)

OpenClaw verwendet Auth-Profile sowohl für API-Schlüssel als auch für OAuth-Token.

• Secrets und Laufzeitstatus für Auth-Routing liegen in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Die Konfiguration auth.profiles / auth.order ist nur Metadaten + Routing (keine Secrets).
• Legacy-OAuth-Datei nur für Import: ~/.openclaw/credentials/oauth.json (wird bei der ersten Verwendung in den Auth-Speicher pro Agent importiert).
• Legacy-Dateien auth-profiles.json, auth-state.json und agentbezogene auth.json-Dateien werden von openclaw doctor --fix importiert.

Weitere Details: OAuth

Zugangsdaten-Typen:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl für einige Provider)

Profil-IDs

OAuth-Anmeldungen erstellen eigene Profile, damit mehrere Konten nebeneinander bestehen können.

• Standard: provider:default, wenn keine E-Mail verfügbar ist.
• OAuth mit E-Mail: provider:<email> (zum Beispiel google-antigravity:user@gmail.com).

Profile liegen im Auth-Profilspeicher openclaw-agent.sqlite pro Agent.

Rotationsreihenfolge

Wenn ein Provider mehrere Profile hat, wählt OpenClaw eine Reihenfolge wie diese:

Wenn keine explizite Reihenfolge konfiguriert ist, verwendet OpenClaw eine Round-Robin-Reihenfolge:

• Primärer Schlüssel: Profiltyp (OAuth vor API-Schlüsseln).
• Sekundärer Schlüssel: usageStats.lastUsed (älteste zuerst, innerhalb jedes Typs).
• Profile im Cooldown oder deaktivierte Profile werden ans Ende verschoben, sortiert nach frühestem Ablauf.

Sitzungshaftung (cachefreundlich)

OpenClaw pinnt das ausgewählte Auth-Profil pro Sitzung, um Provider-Caches warm zu halten. Es rotiert nicht bei jeder Anfrage. Das gepinnte Profil wird wiederverwendet, bis:

• die Sitzung zurückgesetzt wird (/new / /reset)
• eine Compaction abgeschlossen wird (Compaction-Zähler erhöht sich)
• das Profil im Cooldown oder deaktiviert ist

Die manuelle Auswahl über /model …@<profileId> setzt einen Benutzer-Override für diese Sitzung und wird nicht automatisch rotiert, bis eine neue Sitzung startet.

OpenAI-Codex-Abonnement plus API-Schlüssel-Backup

Für OpenAI-Agent-Modelle sind Auth und Laufzeit getrennt. openai/gpt-* bleibt auf dem Codex-Harness, während Auth zwischen einem Codex-Abonnementprofil und einem OpenAI-API-Schlüssel-Backup rotieren kann.

Verwenden Sie auth.order.openai für die benutzerseitige Reihenfolge:

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

Verwenden Sie openai:* sowohl für ChatGPT/Codex-OAuth-Profile als auch für OpenAI-API-Schlüssel- Profile. Wenn das Abonnement ein Codex-Nutzungslimit erreicht, zeichnet OpenClaw die exakte Rücksetzzeit auf, sofern Codex eine bereitstellt, versucht das nächste geordnete Auth-Profil und hält den Lauf im Codex-Harness. Sobald die Rücksetzzeit verstrichen ist, ist das Abonnementprofil wieder auswählbar und die nächste automatische Auswahl kann zu ihm zurückkehren.

Verwenden Sie ein vom Benutzer gepinntes Profil nur, wenn Sie für diese Sitzung ein bestimmtes Konto oder einen bestimmten Schlüssel erzwingen möchten. Vom Benutzer gepinnte Profile sind absichtlich strikt und springen nicht stillschweigend zu einem anderen Profil.

Cooldowns

Wenn ein Profil wegen Auth- oder Ratenlimitfehlern fehlschlägt (oder wegen eines Timeouts, der wie Ratenbegrenzung aussieht), markiert OpenClaw es im Cooldown und wechselt zum nächsten Profil.

Cooldowns verwenden exponentielles Backoff:

• 1 Minute
• 5 Minuten
• 25 Minuten
• 1 Stunde (Obergrenze)

Der Zustand wird im SQLite-Authentifizierungszustand pro Agent unter usageStats gespeichert:

{  "usageStats": {    "provider:profile": {      "lastUsed": 1736160000000,      "cooldownUntil": 1736160600000,      "errorCount": 2    }  }}

Abrechnungsdeaktivierungen

Abrechnungs-/Guthabenfehler (zum Beispiel „insufficient credits“ / „credit balance too low“) werden als Failover-würdig behandelt, sind aber normalerweise nicht vorübergehend. Statt eines kurzen Cooldowns markiert OpenClaw das Profil als deaktiviert (mit längerem Backoff) und rotiert zum nächsten Profil/Provider.

Der Zustand wird im SQLite-Authentifizierungszustand pro Agent gespeichert:

{  "usageStats": {    "provider:profile": {      "disabledUntil": 1736178000000,      "disabledReason": "billing"    }  }}

Standardwerte:

• Das Abrechnungs-Backoff beginnt bei 5 Stunden, verdoppelt sich pro Abrechnungsfehler und ist auf 24 Stunden begrenzt.
• Backoff-Zähler werden zurückgesetzt, wenn das Profil 24 Stunden lang nicht fehlgeschlagen ist (konfigurierbar).
• Überlastungs-Wiederholungen erlauben 1 Profilrotation beim selben Provider vor dem Modell-Fallback.
• Überlastungs-Wiederholungen verwenden standardmäßig 0 ms Backoff.

Modell-Fallback

Wenn alle Profile für einen Provider fehlschlagen, wechselt OpenClaw zum nächsten Modell in agents.defaults.model.fallbacks. Dies gilt für Authentifizierungsfehler, Ratenlimits und Timeouts, die die Profilrotation ausgeschöpft haben (andere Fehler lösen keinen Fallback aus). Provider-Fehler, die nicht genügend Details offenlegen, werden im Fallback-Zustand dennoch präzise gekennzeichnet: empty_response bedeutet, dass der Provider keine verwendbare Nachricht oder keinen verwendbaren Status zurückgegeben hat, no_error_details bedeutet, dass der Provider ausdrücklich Unknown error (no error details in response) zurückgegeben hat, und unclassified bedeutet, dass OpenClaw die Rohvorschau beibehalten hat, aber noch kein Klassifikator darauf gepasst hat.

Überlastungs- und Ratenlimitfehler werden aggressiver behandelt als Abrechnungs-Cooldowns. Standardmäßig erlaubt OpenClaw einen Wiederholungsversuch mit einem Authentifizierungsprofil beim selben Provider und wechselt dann ohne Wartezeit zum nächsten konfigurierten Modell-Fallback. Provider-Auslastungssignale wie ModelNotReadyException landen in diesem Überlastungsbereich. Passen Sie dies mit auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs und auth.cooldowns.rateLimitedProfileRotations an.

Wenn ein Lauf vom konfigurierten Standard-Primärmodell, einem Cron-Job-Primärmodell, einem Agent-Primärmodell mit expliziten Fallbacks oder einer automatisch ausgewählten Fallback-Überschreibung startet, kann OpenClaw die passende konfigurierte Fallback-Kette durchlaufen. Agent-Primärmodelle ohne explizite Fallbacks und explizite Benutzerauswahlen (zum Beispiel /model ollama/qwen3.5:27b, die Modellauswahl, sessions.patch oder einmalige CLI-Provider-/Modellüberschreibungen) sind strikt: Wenn dieser Provider/dieses Modell nicht erreichbar ist oder vor einer Antwort fehlschlägt, meldet OpenClaw den Fehler, statt über einen nicht verwandten Fallback zu antworten.

Regeln für Kandidatenketten

OpenClaw baut die Kandidatenliste aus dem aktuell angeforderten provider/model plus konfigurierten Fallbacks auf.

Welche Fehler den Fallback fortsetzen

Cooldown-Überspringen gegenüber Probeverhalten

Wenn jedes Authentifizierungsprofil für einen Provider bereits im Cooldown ist, überspringt OpenClaw diesen Provider nicht automatisch dauerhaft. Es trifft eine Entscheidung pro Kandidat:

Sitzungsüberschreibungen und Live-Modellwechsel

Sitzungsmodelländerungen sind gemeinsamer Zustand. Der aktive Runner, der Befehl /model, Compaction-/Sitzungsaktualisierungen und die Live-Sitzungsabstimmung lesen oder schreiben alle Teile desselben Sitzungseintrags.

Das bedeutet, dass Fallback-Wiederholungen mit Live-Modellwechseln koordiniert werden müssen:

• Nur explizite benutzergesteuerte Modelländerungen markieren einen ausstehenden Live-Wechsel. Dazu gehören /model, session_status(model=...) und sessions.patch.
• Systemgesteuerte Modelländerungen wie Fallback-Rotation, Heartbeat-Überschreibungen oder Compaction markieren von sich aus nie einen ausstehenden Live-Wechsel.
• Benutzergesteuerte Modellüberschreibungen werden für die Fallback-Richtlinie als exakte Auswahlen behandelt, sodass ein nicht erreichbarer ausgewählter Provider als Fehler sichtbar wird, statt durch agents.defaults.model.fallbacks verdeckt zu werden.
• Bevor eine Fallback-Wiederholung startet, persistiert der Antwort-Runner die ausgewählten Fallback-Überschreibungsfelder im Sitzungseintrag.
• Automatische Fallback-Überschreibungen bleiben in folgenden Turns ausgewählt, damit OpenClaw nicht bei jeder Nachricht einen bekannt fehlerhaften Primärpfad prüft. OpenClaw prüft den konfigurierten Ursprung regelmäßig erneut und entfernt die automatische Überschreibung, wenn er sich erholt; /new, /reset und sessions.reset entfernen automatisch erzeugte Überschreibungen sofort.
• Benutzerantworten kündigen Fallback-Übergänge und die Wiederherstellung nach aufgehobenem Fallback einmal pro Zustandsänderung an. Sticky-Fallback-Turns wiederholen den Hinweis nicht.
• /status zeigt das ausgewählte Modell und, wenn der Fallback-Zustand abweicht, das aktive Fallback-Modell und den Grund.
• Die Live-Sitzungsabstimmung bevorzugt persistierte Sitzungsüberschreibungen gegenüber veralteten Laufzeitmodellfeldern.
• Wenn ein Live-Wechsel-Fehler auf einen späteren Kandidaten in der aktiven Fallback-Kette verweist, springt OpenClaw direkt zu diesem ausgewählten Modell, statt zuerst nicht verwandte Kandidaten zu durchlaufen.
• Wenn der Fallback-Versuch fehlschlägt, setzt der Runner nur die Überschreibungsfelder zurück, die er geschrieben hat, und nur wenn sie noch diesem fehlgeschlagenen Kandidaten entsprechen.

Dies verhindert das klassische Rennen:

Die persistierte Fallback-Überschreibung schließt dieses Fenster, und das enge Rollback hält neuere manuelle oder Laufzeit-Sitzungsänderungen intakt.

Beobachtbarkeit und Fehlerzusammenfassungen

runWithModelFallback(...) zeichnet Details pro Versuch auf, die Logs und benutzerseitige Cooldown-Meldungen speisen:

• versuchter Provider/versuchtes Modell
• Grund (rate_limit, overloaded, billing, auth, model_not_found und ähnliche Failover-Gründe)
• optionaler Status/Code
• menschenlesbare Fehlerzusammenfassung

Strukturierte model_fallback_decision-Logs enthalten auch flache fallbackStep*-Felder, wenn ein Kandidat fehlschlägt, übersprungen wird oder ein späterer Fallback erfolgreich ist. Diese Felder machen den versuchten Übergang explizit (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), damit Log- und Diagnoseexporter den primären Fehler rekonstruieren können, selbst wenn auch der terminale Fallback fehlschlägt.

Wenn jeder Kandidat fehlschlägt, löst OpenClaw FallbackSummaryError aus. Der äußere Antwort-Runner kann dies verwenden, um eine spezifischere Nachricht wie „all models are temporarily rate-limited“ zu erstellen und den frühesten Cooldown-Ablauf einzuschließen, wenn einer bekannt ist.

Diese Cooldown-Zusammenfassung ist modellbewusst:

• nicht verwandte modellbezogene Ratenlimits werden für die versuchte Provider-/Modellkette ignoriert
• wenn die verbleibende Blockade ein passendes modellbezogenes Ratenlimit ist, meldet OpenClaw den letzten passenden Ablauf, der dieses Modell noch blockiert

Zugehörige Konfiguration

Siehe Gateway-Konfiguration für:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel-Routing

Siehe Modelle für die umfassendere Übersicht zur Modellauswahl und zu Fallbacks.