​

Modell-Failover

1. Auth-Profilrotation innerhalb des aktuellen Providers.
2. Modell-Fallback zum nächsten Modell in agents.defaults.model.fallbacks.

​

Laufzeitablauf

1. Das aktuell ausgewählte Sitzungsmodell.
2. Konfigurierte agents.defaults.model.fallbacks in Reihenfolge.
3. Das konfigurierte primäre Modell am Ende, wenn der Lauf mit einer Überschreibung begonnen hat.

1. Das aktive Sitzungsmodell und die Auth-Profil-Präferenz auflösen.
2. Die Modellkandidatenkette erstellen.
3. Den aktuellen Provider mit Auth-Profilrotation-/Cooldown-Regeln versuchen.
4. Wenn dieser Provider mit einem Failover-würdigen Fehler ausgeschöpft ist, zum nächsten Modellkandidaten wechseln.
5. Die ausgewählte Fallback-Überschreibung beibehalten, bevor die Wiederholung beginnt, damit andere Sitzungsleser denselben Provider/dasselbe Modell sehen, das der Runner gleich verwenden wird.
6. Wenn der Fallback-Kandidat fehlschlägt, nur die dem Fallback gehörenden Sitzungs- Überschreibungsfelder zurücksetzen, wenn sie noch diesem fehlgeschlagenen Kandidaten entsprechen.
7. Wenn jeder Kandidat fehlschlägt, einen FallbackSummaryError mit Details pro Versuch und dem frühesten Cooldown-Ablauf auslösen, sofern einer bekannt ist.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Auth-Speicherung (Schlüssel + OAuth)

• Secrets liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (alt: ~/.openclaw/agent/auth-profiles.json).
• Der Laufzeitstatus für Auth-Routing liegt in ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Config auth.profiles / auth.order sind nur Metadaten + Routing (keine Secrets).
• Alte OAuth-Datei nur für Import: ~/.openclaw/credentials/oauth.json (wird bei erster Verwendung in auth-profiles.json importiert).

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

​

Profil-IDs

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

​

Rotationsreihenfolge

1. Explizite Konfiguration: auth.order[provider] (falls gesetzt).
2. Konfigurierte Profile: auth.profiles, nach Provider gefiltert.
3. Gespeicherte Profile: Einträge in auth-profiles.json für den Provider.

• Primärschlüssel: Profiltyp (OAuth vor API-Schlüsseln).
• Sekundärschlüssel: usageStats.lastUsed (älteste zuerst, innerhalb jedes Typs).
• Cooldown-/deaktivierte Profile werden an das Ende verschoben, sortiert nach dem frühesten Ablauf.

​

Sitzungs-Stickiness (cachefreundlich)

• die Sitzung zurückgesetzt wird (/new / /reset)
• eine Kompaktierung abgeschlossen ist (die Kompaktierungsanzahl erhöht sich)
• das Profil im Cooldown/deaktiviert ist

​

Warum OAuth „verloren wirken“ kann

• Mit auth.order[provider] = ["provider:profileId"] pinnen, oder
• Eine Überschreibung pro Sitzung über /model … mit einer Profilüberschreibung verwenden (wenn von Ihrer UI-/Chat-Oberfläche unterstützt).

​

Cooldowns

• OpenClaw zeichnet cooldownModel für Ratenlimit-Fehler auf, wenn die ID des fehlgeschlagenen Modells bekannt ist.
• Ein verwandtes Modell beim selben Provider kann trotzdem versucht werden, wenn der Cooldown auf ein anderes Modell begrenzt ist.
• Abrechnungs-/deaktivierte Zeitfenster blockieren weiterhin das gesamte Profil über Modelle hinweg.

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

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

​

Durch Abrechnung bedingte Deaktivierungen

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

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

​

Modell-Fallback

​

Regeln für die Kandidatenkette

• Das angeforderte Modell steht immer an erster Stelle.
• Explizit konfigurierte Fallbacks werden dedupliziert, aber nicht anhand der Modell- Allowlist gefiltert. Sie gelten als explizite Betreiberabsicht.
• Wenn der aktuelle Lauf bereits auf einem konfigurierten Fallback in derselben Provider- Familie läuft, verwendet OpenClaw weiterhin die vollständige konfigurierte Kette.
• Wenn der aktuelle Lauf auf einem anderen Provider als in der Konfiguration läuft und dieses aktuelle Modell nicht bereits Teil der konfigurierten Fallback-Kette ist, hängt OpenClaw keine nicht zusammenhängenden konfigurierten Fallbacks eines anderen Providers an.
• Wenn der Lauf mit einer Überschreibung begonnen hat, wird das konfigurierte primäre Modell am Ende angehängt, damit die Kette sich wieder auf dem normalen Standard einpendeln kann, sobald frühere Kandidaten ausgeschöpft sind.

​

Welche Fehler zum nächsten Fallback führen

• Auth-Fehlern
• Ratenlimits und Ausschöpfung von Cooldowns
• Überlastungs-/Provider-ausgelastet-Fehlern
• Timeout-förmigen Failover-Fehlern
• durch Abrechnung bedingten Deaktivierungen
• LiveSessionModelSwitchError, das in einen Failover-Pfad normalisiert wird, damit ein veraltetes persistiertes Modell keine äußere Wiederholungsschleife erzeugt
• anderen nicht erkannten Fehlern, wenn noch Kandidaten übrig sind

• expliziten Abbrüchen, die nicht Timeout-/Failover-förmig sind
• Kontextüberlauffehlern, die innerhalb der Kompaktierungs-/Wiederholungslogik bleiben sollten (zum Beispiel request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model oder ollama error: context length exceeded)
• einem letzten unbekannten Fehler, wenn keine Kandidaten mehr übrig sind

​

Cooldown-Überspringen vs. Probe-Verhalten

• Persistente Auth-Fehler überspringen sofort den gesamten Provider.
• Durch Abrechnung bedingte Deaktivierungen führen normalerweise zum Überspringen, aber der primäre Kandidat kann dennoch gedrosselt geprüft werden, damit eine Wiederherstellung ohne Neustart möglich ist.
• Der primäre Kandidat kann kurz vor Ablauf des Cooldowns geprüft werden, mit einer providerbezogenen Drosselung.
• Fallback-Geschwister beim selben Provider können trotz Cooldown versucht werden, wenn der Fehler transient aussieht (rate_limit, overloaded oder unbekannt). Dies ist besonders relevant, wenn ein Ratenlimit modellbezogen ist und ein verwandtes Modell sich möglicherweise sofort wieder erholen kann.
• Transiente Cooldown-Probes sind auf eine pro Provider und Fallback-Lauf begrenzt, damit ein einzelner Provider nicht das providerübergreifende Fallback blockiert.

​

Sitzungsüberschreibungen und Live-Modellwechsel

• Nur explizite, vom Benutzer ausgelöste 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 Kompaktierung markieren niemals selbstständig einen ausstehenden Live-Wechsel.
• Bevor eine Fallback-Wiederholung beginnt, persistiert der Antwort-Runner die ausgewählten Fallback-Überschreibungsfelder im Sitzungseintrag.
• Der Live-Sitzungs-Abgleich bevorzugt persistierte Sitzungsüberschreibungen gegenüber veralteten Laufzeit-Modellfeldern.
• 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.

1. Das primäre Modell schlägt fehl.
2. Ein Fallback-Kandidat wird im Speicher ausgewählt.
3. Der Sitzungsspeicher enthält noch das alte primäre Modell.
4. Der Live-Sitzungs-Abgleich liest den veralteten Sitzungszustand.
5. Die Wiederholung wird zurück auf das alte Modell geschnappt, bevor der Fallback-Versuch beginnt.

​

Beobachtbarkeit und Fehlerzusammenfassungen

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

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

​

Zugehörige Konfiguration

• 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