Model Failover

OpenClaw behandelt Fehler in zwei Stufen:

Auth-Profil-Rotation innerhalb des aktuellen Providers.
Model Fallback zum nächsten Modell in agents.defaults.model.fallbacks.

Dieses Dokument erklärt die Laufzeitregeln und die zugrundeliegenden Daten.

Auth-Speicherung (Keys + OAuth)

OpenClaw verwendet Auth-Profile sowohl für API Keys als auch für OAuth Tokens.

Secrets liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (Legacy: ~/.openclaw/agent/auth-profiles.json).
Die Config auth.profiles / auth.order enthält nur Metadaten + Routing (keine Secrets).
Legacy OAuth-Datei (nur Import): ~/.openclaw/credentials/oauth.json (wird bei erster Nutzung 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 bei manchen Providern)

Profil-IDs

OAuth-Logins erstellen separate Profile, damit mehrere Accounts nebeneinander existieren können.

Standard: provider:default wenn keine E-Mail verfügbar 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, wählt OpenClaw die Reihenfolge so:

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

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

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

Session Stickiness (Cache-freundlich)

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

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

Manuelle Auswahl via /model …@<profileId> setzt ein User Override für diese Session und wird nicht automatisch rotiert bis eine neue Session startet.

Auto-gepinnte Profile (vom Session Router ausgewählt) werden als Präferenz behandelt: sie werden zuerst versucht, aber OpenClaw kann bei Rate Limits/Timeouts zu einem anderen Profil rotieren. User-gepinnte Profile bleiben an dieses Profil gebunden; wenn es fehlschlägt und Model Fallbacks konfiguriert sind, wechselt OpenClaw zum nächsten Modell statt das Profil zu wechseln.

Warum OAuth “verloren” aussehen kann

Wenn du sowohl ein OAuth-Profil als auch ein API-Key-Profil für denselben Provider hast, kann Round-Robin zwischen ihnen wechseln, es sei denn du pinnst eines. Um ein einzelnes Profil zu erzwingen:

Pinne mit auth.order[provider] = ["provider:profileId"], oder
Nutze ein Session-Override via /model … mit einem Profil-Override (wenn von deiner UI/Chat-Oberfläche unterstützt).

Cooldowns

Wenn ein Profil wegen Auth-/Rate-Limit-Fehlern fehlschlägt (oder einem Timeout, das wie Rate Limiting aussieht), markiert OpenClaw es im Cooldown und wechselt zum nächsten Profil. Format-/Invalid-Request-Fehler (zum Beispiel Cloud Code Assist Tool Call ID Validierungsfehler) werden als Failover-würdig behandelt und nutzen dieselben Cooldowns.

Cooldowns verwenden exponentielles Backoff:

1 Minute
5 Minuten
25 Minuten
1 Stunde (Maximum)

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

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

Billing-Deaktivierungen

Billing-/Credit-Fehler (zum Beispiel “insufficient credits” / “credit balance too low”) werden als Failover-würdig behandelt, sind aber meist 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 Status wird in auth-profiles.json gespeichert:

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

Standardwerte:

Billing-Backoff startet bei 5 Stunden, verdoppelt sich pro Billing-Fehler und ist bei 24 Stunden gedeckelt.
Backoff-Zähler werden zurückgesetzt, wenn das Profil 24 Stunden lang nicht fehlgeschlagen ist (konfigurierbar).

Model Fallback

Wenn alle Profile für einen Provider fehlschlagen, wechselt OpenClaw zum nächsten Modell in agents.defaults.model.fallbacks. Das gilt für Auth-Fehler, Rate Limits und Timeouts, die die Profil-Rotation erschöpft haben (andere Fehler lösen keinen Fallback aus).

Wenn ein Run mit einem Model Override startet (Hooks oder CLI), enden Fallbacks trotzdem bei agents.defaults.model.primary nachdem alle konfigurierten Fallbacks versucht wurden.