OpenClaw Model Failover: Ausfallzeiten sicher vermeiden

Es gibt kaum etwas Frustrierenderes, als wenn deine App mitten in einer wichtigen Aufgabe stehen bleibt, nur weil ein API-Key das Limit erreicht hat oder ein Provider kurzzeitig offline ist. Manuell einzugreifen kostet Zeit und nervt.

OpenClaw löst dieses Problem durch ein zweistufiges System: Zuerst werden verschiedene Auth-Profile innerhalb eines Providers rotiert. Wenn das nicht hilft, erfolgt ein Model-Fallback auf das nächste Model, das du in agents.defaults.model.fallbacks definiert hast. In diesem Guide erfährst du, wie diese Regeln zur Laufzeit funktionieren.

Auth-Speicher (Keys + OAuth)

OpenClaw nutzt Auth-Profile sowohl für API-Keys als auch für OAuth-Tokens. Das ist der sauberste Weg, um verschiedene Zugänge zu verwalten.

• Deine Secrets liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (Legacy-Pfad: ~/.openclaw/agent/auth-profiles.json).
• Die Konfigurationen auth.profiles und auth.order dienen nur als Metadaten und für das Routing; dort werden keine Secrets gespeichert.
• Es gibt eine Legacy-OAuth-Datei unter ~/.openclaw/credentials/oauth.json, die beim ersten Start automatisch in die auth-profiles.json importiert wird.

Mehr Details findest du hier: /concepts/oauth

Das sind die unterstützten Credential-Typen:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (plus projectId/enterpriseUrl bei bestimmten Providern)

Profile-IDs

Wenn du dich über OAuth einloggst, erstellt OpenClaw eindeutige Profile. So können mehrere Accounts problemlos nebeneinander existieren.

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

Diese Profile findest du in der auth-profiles.json unter dem Key profiles.

Reihenfolge der Rotation

Wenn für einen Provider mehrere Profile hinterlegt sind, wählt OpenClaw die Reihenfolge nach dieser Logik aus:

1. Explizite Konfiguration: Was du in auth.order[provider] festgelegt hast.
2. Profile-Matching: Alle Profile aus auth.profiles oder der auth-profiles.json, die zum Provider passen.

Falls du keine feste Reihenfolge vorgibst, nutzt OpenClaw ein Round-Robin-Verfahren mit folgenden Prioritäten:

• Primärer Faktor: Der Profil-Typ (OAuth wird vor API-Keys bevorzugt).
• Sekundärer Faktor: usageStats.lastUsed (das am längsten nicht verwendete Profil zuerst).
• Cooldowns: Profile im Cooldown oder deaktivierte Profile landen ganz hinten, sortiert nach dem Zeitpunkt, an dem sie wieder verfügbar sind.

Session-Stickiness (Cache-freundlich)

OpenClaw “pinnt” das gewählte Auth-Profil pro Session. Das ist wichtig, um die Caches der Provider warm zu halten. Es wird also nicht bei jedem Request rotiert. Das Profil bleibt aktiv, bis:

• die Session zurückgesetzt wird (/new / /reset)
• eine Compaction abgeschlossen ist
• das Profil in den Cooldown geht oder deaktiviert wird

Wenn du manuell ein Model via /model …@<profileId> auswählst, setzt du einen User Override. Dieser bleibt für die Session gesperrt und rotiert nicht automatisch.

Automatisch gepinnte Profile (vom Session-Router gewählt) werden als Präferenz behandelt: Sie werden zuerst versucht, aber OpenClaw rotiert bei Rate-Limits oder Timeouts trotzdem zu einem anderen Profil. User-gepinnte Profile bleiben hingegen fest; wenn diese scheitern, wechselt OpenClaw direkt zum nächsten Model-Fallback, statt das Profil zu tauschen.

Warum OAuth manchmal “verschwindet”

Wenn du sowohl ein OAuth-Profil als auch einen API-Key für denselben Provider hast, kann Round-Robin ohne Pinning zwischen ihnen hin- und herwechseln. Um ein bestimmtes Profil zu erzwingen, hast du zwei gute Optionen:

• Nutze auth.order[provider] = ["provider:profileId"].
• Verwende einen Session-Override via /model … mit einer Profile-ID.

Cooldowns

Wenn ein Profil wegen Auth-Fehlern, Rate-Limits oder Timeouts (die wie Rate-Limiting wirken) fehlschlägt, setzt OpenClaw es auf Cooldown. Auch Format-Fehler oder ungültige Requests (wie Tool-Call-Validierungsfehler bei Cloud Code Assist) lösen einen Failover aus. Signale wie Unhandled stop reason: error oder reason: error bei OpenAI-kompatiblen Endpunkten werden ebenfalls als Timeout gewertet.

Der Cooldown nutzt einen exponentiellen Backoff:

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

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

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

Billing-Deaktivierung

Fehler beim Guthaben (z. B. “insufficient credits”) lösen ebenfalls einen Failover aus. Da diese meist nicht von selbst verschwinden, markiert OpenClaw das Profil als disabled mit einem deutlich längeren Backoff.

Der Status sieht in der auth-profiles.json so aus:

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

Hier sind die Standardwerte:

• Der Billing-Backoff startet bei 5 Stunden, verdoppelt sich bei jedem weiteren Fehler und deckelt bei 24 Stunden.
• Die Zähler werden zurückgesetzt, wenn das Profil 24 Stunden lang fehlerfrei war.
• Bei Überlastung (Overloaded) erlaubt OpenClaw eine Rotation innerhalb desselben Providers, bevor der Model-Fallback greift.
• Standardmäßig wird bei Overloaded-Retries ein 0 ms Backoff genutzt.

Model-Fallback

Wenn alle Profile eines Providers erschöpft sind, greift OpenClaw auf das nächste Model in agents.defaults.model.fallbacks zurück. Das passiert bei Auth-Fehlern, Rate-Limits und Timeouts. Andere Fehlertypen lösen keinen Fallback aus.

Fehler durch Überlastung oder Rate-Limits werden aggressiver behandelt als Billing-Probleme. OpenClaw versucht in der Regel einen Retry mit einem anderen Profil desselben Providers und wechselt dann sofort zum nächsten konfigurierten Fallback-Model. Das kannst du über Parameter wie auth.cooldowns.overloadedProfileRotations feinjustieren.

Falls du einen Run mit einem Model-Override startest (via CLI oder Hooks), enden die Fallbacks trotzdem immer bei agents.defaults.model.primary, nachdem alle anderen Optionen durchprobiert wurden.

Zugehörige Konfiguration

Schau dir die Gateway-Konfiguration an für:

• 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

Weitere Infos zur Auswahl findest du in der Übersicht zu Models.

---

Nächste Schritte:

• Gateway-Konfiguration anpassen
• Mehr über OAuth erfahren

Hast du Fragen zum Setup? Frag den AI Setup Assistant.