Modell-Failover

OpenClaw behandelt Ausfaelle in zwei Stufen:

Auth-Profil-Rotation innerhalb des aktuellen Providers.
Modell-Fallback auf das naechste Modell in agents.defaults.model.fallbacks.

Dieses Dokument erklaert die Runtime-Regeln und die zugrundeliegenden Daten.

Auth-Speicher (Schluessel + OAuth)

OpenClaw nutzt Auth-Profile sowohl fuer API-Schluessel als auch fuer OAuth-Tokens.

Secrets liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (Legacy: ~/.openclaw/agent/auth-profiles.json).
Config auth.profiles / auth.order sind nur Metadaten und Routing (keine Secrets).
Legacy-Import-Only-OAuth-Datei: ~/.openclaw/credentials/oauth.json (wird beim ersten Gebrauch in auth-profiles.json importiert).

Mehr Details: /concepts/oauth

Credential-Typen:

type: "api_key" -> { provider, key }
type: "oauth" -> { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl fuer einige Provider)

Profil-IDs

OAuth-Logins erstellen eigene Profile, damit mehrere Accounts koexistieren koennen.

Standard: provider:default, wenn keine E-Mail verfuegbar ist.
OAuth mit E-Mail: provider:<email> (zum Beispiel google-antigravity:[email protected]).

Profile liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json unter profiles.

Rotationsreihenfolge

Wenn ein Provider mehrere Profile hat, waehlt OpenClaw eine Reihenfolge wie folgt:

Explizite Config: auth.order[provider] (wenn gesetzt).
Konfigurierte Profile: auth.profiles gefiltert nach Provider.
Gespeicherte Profile: Eintraege in auth-profiles.json fuer den Provider.

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

Primaerer Schluessel: Profiltyp (OAuth vor API-Schluesseln).
Sekundaerer Schluessel: usageStats.lastUsed (aelteste zuerst, innerhalb jedes Typs).
Cooldown/deaktivierte Profile werden ans Ende verschoben, sortiert nach naechstem Ablauf.

Session-Stickiness (cache-freundlich)

OpenClaw fixiert das gewaehlte Auth-Profil pro Sitzung, um Provider-Caches warm zu halten. Es rotiert nicht bei jedem Request. Das fixierte Profil wird wiederverwendet, bis:

die Sitzung zurueckgesetzt wird (/new / /reset)
eine Compaction abgeschlossen wird (Compaction-Zaehler erhoehen sich)
das Profil im Cooldown/deaktiviert ist

Manuelle Auswahl ueber /model ...@<profileId> setzt ein Nutzer-Override fuer diese Sitzung und wird nicht automatisch rotiert, bis eine neue Sitzung startet.

Automatisch fixierte Profile (vom Session-Router gewaehlt) werden als Praeferenz behandelt: sie werden zuerst versucht, aber OpenClaw kann bei Rate-Limits/Timeouts zu einem anderen Profil rotieren. Nutzer-fixierte Profile bleiben bei diesem Profil; wenn es fehlschlaegt und Modell-Fallbacks konfiguriert sind, wechselt OpenClaw zum naechsten Modell, statt Profile zu wechseln.

Warum OAuth “verloren” wirken kann

Wenn du sowohl ein OAuth-Profil als auch ein API-Key-Profil fuer denselben Provider hast, kann Round-Robin zwischen ihnen wechseln, sofern nicht fixiert. Um ein einzelnes Profil zu erzwingen:

Fixiere mit auth.order[provider] = ["provider:profileId"], oder
Verwende ein pro-Sitzungs-Override ueber /model ... mit einem Profil-Override (wenn von deiner UI/Chat-Oberflaeche unterstuetzt).

Cooldowns

Wenn ein Profil aufgrund von Auth-/Rate-Limit-Fehlern (oder einem Timeout, das wie Rate-Limiting aussieht) fehlschlaegt, markiert OpenClaw es im Cooldown und wechselt zum naechsten Profil. Format-/Invalid-Request-Fehler (zum Beispiel Cloud Code Assist Tool-Call-ID-Validierungsfehler) werden als failover-wuerdig behandelt und nutzen dieselben Cooldowns. OpenAI-kompatible Stop-Reason-Fehler wie Unhandled stop reason: error, stop reason: error und reason: error werden als Timeout-/Failover-Signale klassifiziert.

Cooldowns nutzen exponentiellen Backoff:

1 Minute
5 Minuten
25 Minuten
1 Stunde (Maximum)

Der Zustand wird in auth-profiles.json unter usageStats gespeichert:

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

Billing-Deaktivierungen

Abrechnungs-/Guthaben-Fehler (zum Beispiel “insufficient credits” / “credit balance too low”) werden als failover-wuerdig behandelt, sind aber normalerweise nicht voruebergehend. Statt eines kurzen Cooldowns markiert OpenClaw das Profil als deaktiviert (mit laengerem Backoff) und rotiert zum naechsten Profil/Provider.

Der Zustand wird in auth-profiles.json gespeichert:

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

Standardwerte:

Billing-Backoff startet bei 5 Stunden, verdoppelt sich pro Abrechnungsfehler und begrenzt sich bei 24 Stunden.
Backoff-Zaehler werden zurueckgesetzt, wenn das Profil 24 Stunden lang nicht fehlgeschlagen ist (konfigurierbar).

Modell-Fallback

Wenn alle Profile eines Providers fehlschlagen, wechselt OpenClaw zum naechsten Modell in agents.defaults.model.fallbacks. Das gilt fuer Auth-Fehler, Rate-Limits und Timeouts, die die Profil-Rotation erschoepft haben (andere Fehler loesen keinen Fallback aus).

Wenn ein Durchlauf mit einem Modell-Override startet (Hooks oder CLI), enden Fallbacks trotzdem bei agents.defaults.model.primary, nachdem konfigurierte Fallbacks versucht wurden.