​

Modell-Failover

1. Auth-Profilrotation innerhalb des aktuellen Providers.
2. Modell-Fallback auf das nächste 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 von einer Überschreibung gestartet wurde.

1. Aktives Sitzungsmodell und Auth-Profil-Präferenz auflösen.
2. Die Modell-Kandidatenkette 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 speichern, bevor der Retry startet, damit andere Sitzungsleser denselben Provider/dasselbe Modell sehen, den bzw. das der Runner gleich verwenden wird.
6. Wenn der Fallback-Kandidat fehlschlägt, nur die sitzungseigenen Override-Felder des Fallbacks zurücksetzen, sofern sie noch mit diesem fehlgeschlagenen Kandidaten übereinstimmen.
7. Wenn jeder Kandidat fehlschlägt, einen FallbackSummaryError mit Details pro Versuch und dem frühesten Cooldown-Ablauf werfen, sofern einer bekannt ist.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Auth-Speicher (Schlüssel + OAuth)

• Secrets liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (Legacy: ~/.openclaw/agent/auth-profiles.json).
• Konfiguration auth.profiles / auth.order ist nur Metadaten + Routing (keine Secrets).
• Legacy-Datei nur für OAuth-Importe: ~/.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 ans Ende verschoben und nach dem frühesten Ablauf sortiert.

​

Sitzungs-Stickiness (cache-freundlich)

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

​

Warum OAuth „verloren“ aussehen kann

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

​

Cooldowns

• OpenClaw zeichnet cooldownModel für Rate-Limit-Fehler auf, wenn die fehlschlagende Modell-ID bekannt ist.
• Ein Schwester-Modell desselben Providers kann weiterhin versucht werden, wenn der Cooldown auf ein anderes Modell begrenzt ist.
• Billing-/Deaktivierungsfenster blockieren das gesamte Profil weiterhin modellübergreifend.

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

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

​

Billing-Deaktivierungen

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

• Billing-Backoff beginnt bei 5 Stunden, verdoppelt sich pro Billing-Fehler und ist auf 24 Stunden begrenzt.
• Backoff-Zähler werden zurückgesetzt, wenn das Profil 24 Stunden lang nicht fehlgeschlagen ist (konfigurierbar).
• Überlastete Retries erlauben 1 Rotation desselben Provider-Profils, bevor auf Modell-Fallback umgeschaltet wird.
• Überlastete Retries verwenden standardmäßig 0 ms Backoff.

​

Modell-Fallback

​

Regeln für Kandidatenketten

• Das angeforderte Modell ist immer zuerst.
• Explizit konfigurierte Fallbacks werden dedupliziert, aber nicht durch die Modell- Allowlist gefiltert. Sie gelten als explizite Operator-Absicht.
• Wenn der aktuelle Lauf bereits auf einem konfigurierten Fallback 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 noch nicht Teil der konfigurierten Fallback-Kette ist, hängt OpenClaw keine nicht zusammenhängenden konfigurierten Fallbacks eines anderen Providers an.
• Wenn der Lauf von einer Überschreibung gestartet wurde, wird das konfigurierte primäre Modell am Ende angehängt, damit sich die Kette wieder auf den normalen Standard einpendeln kann, sobald frühere Kandidaten ausgeschöpft sind.

​

Welche Fehler Fallback voranbringen

• Auth-Fehlern
• Rate Limits und erschöpftem Cooldown
• überlasteten/Provider-busy-Fehlern
• timeoutförmigen Failover-Fehlern
• Billing-Deaktivierungen
• LiveSessionModelSwitchError, das in einen Failover-Pfad normalisiert wird, damit ein veraltetes persistiertes Modell keine äußere Retry-Schleife erzeugt
• anderen nicht erkannten Fehlern, wenn noch Kandidaten übrig sind

• expliziten Abbrüchen, die nicht timeout-/failover-förmig sind
• Kontextüberlauf-Fehlern, die innerhalb der Kompaktierungs-/Retry-Logik bleiben sollen (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-Skip vs. Probe-Verhalten

• Persistente Auth-Fehler überspringen sofort den gesamten Provider.
• Billing-Deaktivierungen führen normalerweise zum Überspringen, aber der primäre Kandidat kann weiterhin gedrosselt geprobt werden, damit eine Wiederherstellung ohne Neustart möglich ist.
• Der primäre Kandidat kann nahe am Cooldown-Ablauf geprobt werden, mit einer Drossel pro Provider.
• Schwester-Fallbacks desselben Providers können trotz Cooldown versucht werden, wenn der Fehler transient aussieht (rate_limit, overloaded oder unbekannt). Das ist besonders relevant, wenn ein Rate Limit auf ein Modell begrenzt ist und ein Schwester-Modell sich möglicherweise sofort wieder erholt.
• Transiente Cooldown-Probes sind auf eine pro Provider und Fallback-Lauf begrenzt, damit ein einzelner Provider nicht providerübergreifendes Fallback blockiert.

​

Sitzungsüberschreibungen und Live-Modellwechsel

• Nur explizite benutzergesteuerte Modelländerungen markieren einen ausstehenden Live-Switch. Das umfasst /model, session_status(model=...) und sessions.patch.
• Systemgesteuerte Modelländerungen wie Fallback-Rotation, Heartbeat-Überschreibungen oder Kompaktierung markieren niemals selbst einen ausstehenden Live-Switch.
• Bevor ein Fallback-Retry startet, speichert der Reply-Runner die ausgewählten Fallback-Override-Felder im Sitzungseintrag.
• Live-Session-Reconciliation bevorzugt persistierte Sitzungsüberschreibungen gegenüber veralteten Laufzeit-Modellfeldern.
• Wenn der Fallback-Versuch fehlschlägt, setzt der Runner nur die Override-Felder zurück, die er geschrieben hat, und auch nur dann, wenn sie noch mit diesem fehlgeschlagenen Kandidaten übereinstimmen.

1. Primäres Modell schlägt fehl.
2. Fallback-Kandidat wird im Speicher ausgewählt.
3. Der Sitzungsspeicher sagt weiterhin das alte primäre Modell.
4. Live-Session-Reconciliation liest den veralteten Sitzungsstatus.
5. Der Retry wird zurück auf das alte Modell gezogen, bevor der Fallback-Versuch startet.

​

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 Rate Limits werden für die versuchte Provider-/Modellkette ignoriert
• wenn der verbleibende Block ein passendes modellbezogenes Rate Limit ist, meldet OpenClaw den letzten passenden Ablauf, der dieses Modell weiterhin blockiert

​

Verwandte 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