Modell-Failover

OpenClaw behandelt Fehler in zwei Stufen:

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

Laufzeitablauf

Dies ist absichtlich enger gefasst als „die gesamte Sitzung speichern und wiederherstellen“. Der Antwort-Runner speichert nur die Felder zur Modellauswahl, für die er beim Fallback verantwortlich ist: providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Dadurch wird verhindert, dass ein fehlgeschlagener erneuter Fallback-Versuch neuere, nicht damit zusammenhängende Sitzungsänderungen überschreibt, etwa eine manuelle Änderung mit /model oder eine Aktualisierung der Sitzungsrotation, die während des laufenden Versuchs erfolgt ist.

Richtlinie für die Auswahlquelle

Die Auswahlquelle bestimmt, ob die Fallback-Kette zulässig ist:

• Konfigurierter Standardwert: agents.defaults.model.primary verwendet agents.defaults.model.fallbacks.
• Primäres Agentenmodell: agents.list[].model ist strikt, sofern das Modellobjekt dieses Agenten keine eigenen fallbacks enthält. Verwenden Sie fallbacks: [], um das strikte Verhalten ausdrücklich festzulegen, oder eine nicht leere Liste, um den Modell-Fallback für diesen Agenten zu aktivieren.
• Automatische Fallback-Überschreibung: Ein Laufzeit-Fallback schreibt vor dem erneuten Versuch providerOverride, modelOverride, modelOverrideSource: "auto" und das ausgewählte Ursprungsmodell. Mit dieser Überschreibung wird die konfigurierte Fallback-Kette weiter durchlaufen, ohne das primäre Modell bei jeder Nachricht erneut zu prüfen. OpenClaw prüft jedoch alle 5 Minuten den konfigurierten Ursprung (nicht konfigurierbar) und entfernt die Überschreibung, sobald er wieder verfügbar ist. /new, /reset und sessions.reset entfernen ebenfalls automatisch erzeugte Überschreibungen. Heartbeat-Ausführungen ohne explizites heartbeat.model entfernen direkte automatische Überschreibungen, wenn deren Ursprung nicht mehr dem aktuell konfigurierten Standardwert entspricht.
• Benutzerdefinierte Sitzungsüberschreibung: /model, die Modellauswahl, session_status(model=...) und sessions.patch schreiben modelOverrideSource: "user". Dies ist eine exakte Modellauswahl für die Sitzung. Wenn der ausgewählte Provider oder das ausgewählte Modell fehlschlägt, bevor eine Antwort erzeugt wurde, meldet OpenClaw den Fehler, anstatt mit einem nicht damit zusammenhängenden konfigurierten Fallback zu antworten.
• Veraltete Sitzungsüberschreibung: Ältere Sitzungseinträge können modelOverride ohne modelOverrideSource enthalten. OpenClaw behandelt diese als Benutzerüberschreibungen, damit eine explizite alte Auswahl nicht unbemerkt in Fallback-Verhalten umgewandelt wird.
• Modell in Cron-Nutzdaten: payload.model beziehungsweise --model eines Cron-Auftrags ist das primäre Modell des Auftrags und keine benutzerdefinierte Sitzungsüberschreibung. Es verwendet konfigurierte Fallbacks, sofern der Auftrag keine payload.fallbacks angibt; mit payload.fallbacks: [] wird die Cron-Ausführung strikt.

OpenClaw merkt sich kürzlich erfolgte Prüfungen des primären Modells je Sitzung und primärem Modell, damit ein fehlerhaftes primäres Modell nicht bei jedem Durchlauf erneut versucht wird. Es sendet einen sichtbaren Hinweis, wenn eine Sitzung zu einem Fallback wechselt, und einen weiteren Hinweis, wenn sie zum ausgewählten primären Modell zurückkehrt. Der Hinweis wird nicht bei jedem Durchlauf mit beibehaltenem Fallback wiederholt.

Cache zum Überspringen von Auth-Fehlern

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

Aktivieren Sie die Unterdrückung wiederholter Auth-Fehler mit:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Wenn diese Option aktiviert ist, zeichnet OpenClaw nach einem Fehler der Auth-Klasse für einen nicht primären Fallback-Kandidaten eine sitzungsbezogene Überspringmarkierung im Arbeitsspeicher auf. Der Schlüssel besteht aus Sitzungs-ID, Provider und Modell. Primäre Kandidaten werden niemals übersprungen, sodass bei einer expliziten Benutzerauswahl eines Modells weiterhin der tatsächliche Auth-Fehler angezeigt wird. Der Cache ist prozesslokal und wird bei einem Neustart des Gateways geleert.

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 zu einem automatisch ausgewählten Fallback wechselt, sendet OpenClaw einen Statushinweis über dieselbe 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 Betriebsnachrichten und keine Inhalte des Assistenten. Sie werden einmal je Zustandsänderung zugestellt, soweit möglich auch bei Durchläufen, die ausschließlich Nebeneffekte auslösen. Bei Durchläufen mit beibehaltenem Fallback werden sie jedoch nicht wiederholt. Die Zustellung umgeht die normale Unterdrückung von Antworten an die Quelle, belegt bei Kanälen mit Threads nicht den Platz der ersten Assistentenantwort und wird von der Sprachsynthese sowie der Extraktion von Zusagen ausgeschlossen.

Auth-Speicherung (Schlüssel und OAuth)

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

• Geheimnisse und der Laufzeitstatus der Auth-Weiterleitung befinden sich in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Die Konfigurationen auth.profiles und auth.order enthalten nur Metadaten und Weiterleitungsinformationen (keine Geheimnisse).
• Veraltete, ausschließlich für den Import bestimmte OAuth-Datei: ~/.openclaw/credentials/oauth.json (wird bei der ersten Verwendung in den Auth-Speicher des jeweiligen Agenten importiert).
• Veraltete Dateien auth-profiles.json, auth-state.json und agentenspezifische auth.json-Dateien werden durch openclaw doctor --fix importiert.

Weitere Einzelheiten: OAuth

Typen von Zugangsdaten:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl bei einigen Providern)
• type: "token" → statisches Token im Bearer-Stil, optional mit Ablaufzeit; OpenClaw aktualisiert es nicht (wird für aws-sdk und andere Auth-Modi mit Zugangsdatenketten verwendet)

Profil-IDs

OAuth-Anmeldungen erstellen getrennte Profile, damit mehrere Konten gleichzeitig verwendet werden können.

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

Die Profile befinden sich im Auth-Profilspeicher der agentenspezifischen openclaw-agent.sqlite.

Rotationsreihenfolge

Wenn ein Provider über mehrere Profile verfügt, bestimmt OpenClaw die Reihenfolge folgendermaßen:

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

• Primärer Schlüssel: Profiltyp (OAuth, dann statisches Token, dann API-Schlüssel).
• Sekundärer Schlüssel: usageStats.lastUsed (innerhalb jedes Typs zuerst der älteste Wert).
• Profile mit Abklingzeit oder deaktivierte Profile werden ans Ende verschoben und nach dem frühesten Ablaufzeitpunkt sortiert.

Sitzungsbindung (cachefreundlich)

OpenClaw bindet das ausgewählte Auth-Profil an die jeweilige Sitzung, damit die Provider-Caches verfügbar bleiben. Es rotiert nicht bei jeder Anfrage. Das gebundene Profil wird wiederverwendet, bis:

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

Eine manuelle Auswahl über /model …@<profileId> legt für diese Sitzung eine Benutzerüberschreibung fest und wird bis zum Beginn einer neuen Sitzung nicht automatisch rotiert.

OpenAI-Codex-Abonnement mit API-Schlüssel als Reserve

Bei OpenAI-Agentenmodellen sind Authentifizierung und Laufzeit voneinander getrennt. openai/gpt-* verbleibt im Codex-Harness, während die Authentifizierung zwischen einem Codex-Abonnementprofil und einem OpenAI-API-Schlüssel als Reserve 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üsselprofile. Wenn das Abonnement ein Codex-Nutzungslimit erreicht, speichert OpenClaw den genauen Zeitpunkt der Zurücksetzung, sofern Codex einen bereitstellt, versucht das nächste Auth-Profil in der festgelegten Reihenfolge und belässt die Ausführung im Codex-Harness. Sobald der Zeitpunkt der Zurücksetzung verstrichen ist, ist das Abonnementprofil wieder verfügbar, und die nächste automatische Auswahl kann zu ihm zurückkehren.

Verwenden Sie ein vom Benutzer gebundenes Profil nur, wenn Sie für diese Sitzung die Verwendung eines bestimmten Kontos oder Schlüssels erzwingen möchten. Vom Benutzer gebundene Profile sind absichtlich strikt und wechseln nicht unbemerkt zu einem anderen Profil.

Abklingzeiten

Wenn ein Profil aufgrund von Auth- oder Ratenbegrenzungsfehlern fehlschlägt oder eine Zeitüberschreitung auftritt, die wie eine Ratenbegrenzung wirkt, versetzt OpenClaw es in eine Abklingzeit und wechselt zum nächsten Profil.

Reguläre Abklingzeiten (weder Abrechnungsfehler noch dauerhafte Authentifizierungsfehler) skalieren mit der Anzahl der kürzlich aufgetretenen Fehler des Profils:

• 1. Fehler: 30 Sekunden
• 2. Fehler: 1 Minute
• Ab dem 3. Fehler: 5 Minuten (Obergrenze)

Die Zähler werden zurückgesetzt, sobald das Fehlerzeitfenster des Profils abgelaufen ist (auth.cooldowns.failureWindowHours, Standardwert 24).

Der Status wird im agentenspezifischen SQLite-Authentifizierungsstatus unter usageStats gespeichert:

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

Deaktivierungen aufgrund von Abrechnungsfehlern

Abrechnungs- oder Guthabenfehler (beispielsweise „unzureichendes Guthaben“ / „Guthabenstand zu niedrig“) werden als Grund für einen Failover behandelt, sind jedoch normalerweise nicht vorübergehend. Statt einer kurzen Abklingzeit markiert OpenClaw das Profil als deaktiviert (mit einer längeren Wartezeit) und wechselt zum nächsten Profil beziehungsweise Provider.

Mit hoher Sicherheit dauerhafte Authentifizierungsfehler (widerrufene oder deaktivierte Schlüssel sowie deaktivierte Arbeitsbereiche) werden ähnlich behandelt und führen ebenfalls zu einer Deaktivierung. Die Wiederherstellung erfolgt jedoch deutlich früher als bei Abrechnungsfehlern, da manche Provider bei Störungen vorübergehend Antworten liefern, die wie Authentifizierungsfehler aussehen.

Der Status wird im agentenspezifischen SQLite-Authentifizierungsstatus gespeichert:

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

Standardwerte (auth.cooldowns.*):

Überlastungs- und Ratenbegrenzungsfehler werden aggressiver behandelt als Abklingzeiten bei Abrechnungsfehlern: Standardmäßig erlaubt OpenClaw einen erneuten Versuch mit einem anderen Authentifizierungsprofil desselben Providers und wechselt anschließend ohne Wartezeit zum nächsten konfigurierten Fallback-Modell.

Modell-Fallback

Wenn alle Profile eines Providers fehlschlagen, wechselt OpenClaw zum nächsten Modell in agents.defaults.model.fallbacks. Dies gilt für Authentifizierungsfehler, Ratenbegrenzungen und Zeitüberschreitungen, nachdem sämtliche Profilwechsel ausgeschöpft wurden. Andere Fehler lösen keinen Wechsel zum Fallback aus. Providerfehler, die nicht genügend Details enthalten, werden im Fallback-Status dennoch präzise gekennzeichnet: empty_response bedeutet, dass der Provider weder eine verwendbare Meldung noch einen 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 unverarbeitete Vorschau beibehalten hat, aber noch keine Klassifizierung darauf zutraf.

Signale für einen ausgelasteten Provider wie ModelNotReadyException werden der Überlastungskategorie zugeordnet und folgen derselben Richtlinie „ein Profilwechsel, dann Fallback“ wie Ratenbegrenzungen (siehe die Tabelle mit den Standardwerten oben).

Wenn ein Durchlauf mit dem konfigurierten primären Standardmodell, dem primären Modell eines Cron-Auftrags, dem primären Modell eines Agenten mit expliziten Fallbacks oder einer automatisch ausgewählten Fallback-Überschreibung beginnt, kann OpenClaw die passende konfigurierte Fallback-Kette durchlaufen. Primäre Agentenmodelle ohne explizite Fallbacks und explizite Benutzerauswahlen (beispielsweise /model ollama/qwen3.5:27b, die Modellauswahl, sessions.patch oder einmalige CLI-Überschreibungen für Provider und Modell) werden strikt behandelt: Wenn dieser Provider beziehungsweise dieses Modell nicht erreichbar ist oder vor der Ausgabe einer Antwort fehlschlägt, meldet OpenClaw den Fehler, statt über einen nicht zugehörigen Fallback zu antworten.

Regeln für die Kandidatenkette

OpenClaw erstellt die Kandidatenliste aus dem aktuell angeforderten provider/model und den konfigurierten Fallbacks.

Welche Fehler den Fallback fortsetzen

Verhalten beim Überspringen und Prüfen von Abklingzeiten

Wenn sich alle Authentifizierungsprofile eines Providers bereits in der Abklingzeit befinden, überspringt OpenClaw diesen Provider nicht automatisch dauerhaft. Stattdessen trifft es für jeden Kandidaten eine eigene Entscheidung:

Sitzungsüberschreibungen und Modellwechsel während des Betriebs

Änderungen des Sitzungsmodells sind ein gemeinsamer Status. Der aktive Runner, der Befehl /model, Compaction- und Sitzungsaktualisierungen sowie der Abgleich laufender Sitzungen lesen oder schreiben jeweils Teile desselben Sitzungseintrags.

Daher müssen Fallback-Wiederholungsversuche mit Modellwechseln während des Betriebs koordiniert werden:

• Nur explizite, vom Benutzer veranlasste Modelländerungen markieren einen ausstehenden Modellwechsel während des Betriebs. Dazu gehören /model, session_status(model=...) und sessions.patch.
• Systemgesteuerte Modelländerungen wie Fallback-Wechsel, Heartbeat-Überschreibungen oder Compaction markieren niemals selbstständig einen ausstehenden Modellwechsel während des Betriebs.
• Vom Benutzer veranlasste Modellüberschreibungen gelten für die Fallback-Richtlinie als exakte Auswahl. Daher wird ein nicht erreichbarer ausgewählter Provider als Fehler angezeigt, statt durch agents.defaults.model.fallbacks verdeckt zu werden.
• Bevor ein Fallback-Wiederholungsversuch beginnt, persistiert der Antwort-Runner die ausgewählten Felder der Fallback-Überschreibung im Sitzungseintrag.
• Automatische Fallback-Überschreibungen bleiben in nachfolgenden Durchläufen ausgewählt, damit OpenClaw nicht bei jeder Nachricht ein bekanntermaßen fehlerhaftes primäres Modell prüft. OpenClaw prüft den konfigurierten Ursprung regelmäßig erneut und entfernt die automatische Überschreibung nach dessen Wiederherstellung. /new, /reset und sessions.reset entfernen automatisch erzeugte Überschreibungen sofort.
• Benutzerantworten kündigen Fallback-Übergänge und die Wiederherstellung nach Aufhebung des Fallbacks einmal pro Statusänderung an. Durchläufe mit beibehaltenem Fallback wiederholen den Hinweis nicht.
• /status zeigt das ausgewählte Modell und, wenn der Fallback-Status davon abweicht, das aktive Fallback-Modell sowie den Grund.
• Beim Abgleich laufender Sitzungen haben persistierte Sitzungsüberschreibungen Vorrang vor veralteten Modellfeldern der Laufzeit.
• Wenn ein Fehler beim Modellwechsel während des Betriebs auf einen späteren Kandidaten in der aktiven Fallback-Kette verweist, springt OpenClaw direkt zu diesem ausgewählten Modell, statt zunächst nicht zugehörige Kandidaten zu durchlaufen.
• Wenn der Fallback-Versuch fehlschlägt, setzt der Runner nur die von ihm geschriebenen Überschreibungsfelder zurück und auch nur dann, wenn sie weiterhin diesem fehlgeschlagenen Kandidaten entsprechen.

Dies verhindert den klassischen Wettlauf:

Die persistierte Fallback-Überschreibung schließt dieses Zeitfenster, während das gezielte Zurücksetzen neuere manuelle oder laufzeitbedingte Sitzungsänderungen beibehält.

Beobachtbarkeit und Fehlerzusammenfassungen

runWithModelFallback(...) zeichnet Details zu jedem Versuch auf, die in Protokolle und benutzerseitige Meldungen zu Abklingzeiten einfließen:

• 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-Protokolle enthalten außerdem 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), sodass Protokoll- und Diagnoseexporter den primären Fehler rekonstruieren können, selbst wenn auch der abschließende Fallback fehlschlägt.

Wenn alle Kandidaten fehlschlagen, löst OpenClaw FallbackSummaryError aus. Der äußere Antwort-Runner kann damit eine spezifischere Meldung wie „für alle Modelle gelten vorübergehend Ratenbegrenzungen“ erstellen und, sofern bekannt, das früheste Ende einer Abkühlphase angeben.

Diese Zusammenfassung der Abkühlphasen berücksichtigt das jeweilige Modell:

• nicht zugehörige, modellspezifische Ratenbegrenzungen werden für die versuchte Provider-/Modellkette ignoriert
• wenn die verbleibende Sperre eine passende modellspezifische Ratenbegrenzung ist, meldet OpenClaw den letzten passenden Ablaufzeitpunkt, der dieses Modell weiterhin blockiert

Zugehörige Konfiguration

Unter Gateway-Konfiguration finden Sie Informationen zu:

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

Unter Modelle finden Sie einen umfassenderen Überblick über die Modellauswahl und Fallbacks.