Modell-Failover

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

Laufzeitablauf

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Richtlinie für Auswahlquellen

• Konfigurierter Standard: agents.defaults.model.primary verwendet agents.defaults.model.fallbacks.
• Agent-Primärmodell: agents.list[].model ist strikt, sofern dieses Agent-Modellobjekt keine eigenen fallbacks enthält. Verwenden Sie fallbacks: [], um das strikte Verhalten explizit zu machen, oder geben Sie eine nicht leere Liste an, um diesen Agent für Modell-Fallback zu aktivieren.
• Automatischer Fallback-Override: Ein Laufzeit-Fallback schreibt vor dem erneuten Versuch providerOverride, modelOverride, modelOverrideSource: "auto" und das ausgewählte Ursprungsmodell. Dieser automatische Override kann die konfigurierte Fallback-Kette weiter durchlaufen und wird durch /new, /reset und sessions.reset gelöscht. Heartbeat-Läufe ohne explizites heartbeat.model löschen außerdem einen direkten automatischen Override, wenn dessen Ursprung nicht mehr dem aktuellen konfigurierten Standard entspricht.
• Benutzersitzungs-Override: /model, die Modellauswahl, session_status(model=...) und sessions.patch schreiben modelOverrideSource: "user". Das ist eine exakte Sitzungsauswahl. Wenn der ausgewählte Provider oder das ausgewählte Modell fehlschlägt, bevor eine Antwort erzeugt wird, meldet OpenClaw den Fehler, statt von einem nicht zusammenhängenden konfigurierten Fallback aus zu antworten.
• Legacy-Sitzungs-Override: Ältere Sitzungseinträge können modelOverride ohne modelOverrideSource enthalten. OpenClaw behandelt diese als Benutzer-Overrides, damit eine explizite alte Auswahl nicht stillschweigend in Fallback-Verhalten umgewandelt wird.
• Cron-Payload-Modell: Ein Cron-Auftrag payload.model / --model ist ein primäres Auftragsmodell, kein Benutzersitzungs-Override. Es verwendet konfigurierte Fallbacks, sofern der Auftrag kein payload.fallbacks bereitstellt; payload.fallbacks: [] macht den Cron-Lauf strikt.

​

Auth-Speicher (Schlüssel + OAuth)

• Secrets liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (Legacy: ~/.openclaw/agent/auth-profiles.json).
• Der Laufzeitstatus für Auth-Routing liegt in ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Konfiguration auth.profiles / auth.order sind nur Metadaten + Routing (keine Secrets).
• Legacy-Datei nur für OAuth-Import: ~/.openclaw/credentials/oauth.json (wird bei der ersten 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

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

​

Sitzungsbindung (cachefreundlich)

• die Sitzung zurückgesetzt wird (/new / /reset)
• eine Compaction abgeschlossen ist (Compaction-Zähler wird erhöht)
• das Profil in einer Abkühlphase/deaktiviert ist

​

OpenAI Codex-Abonnement plus API-Schlüssel-Backup

{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
    },
  },
}

​

Abkühlphasen

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

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

​

Abrechnungsdeaktivierungen

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

• Der 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).
• Overloaded-Wiederholungen erlauben 1 Profilrotation beim selben Provider vor dem Modell-Fallback.
• Overloaded-Wiederholungen verwenden standardmäßig 0 ms Backoff.

​

Modell-Fallback

​

Regeln für die Kandidatenkette

​

Welche Fehler den Fallback fortsetzen

​

Verhalten bei Cooldown-Überspringen vs. Probe

​

Sitzungs-Overrides und Live-Modellwechsel

• Nur explizite benutzergesteuerte Modelländerungen markieren einen ausstehenden Live-Wechsel. Dazu gehören /model, session_status(model=...) und sessions.patch.
• Systemgesteuerte Modelländerungen wie Fallback-Rotation, Heartbeat-Overrides oder Compaction markieren für sich allein nie einen ausstehenden Live-Wechsel.
• Benutzergesteuerte Modell-Overrides werden für die Fallback-Richtlinie als exakte Auswahlen behandelt, sodass ein nicht erreichbarer ausgewählter Provider als Fehler sichtbar wird, statt durch agents.defaults.model.fallbacks maskiert zu werden.
• Bevor eine Fallback-Wiederholung startet, persistiert der Reply-Runner die ausgewählten Fallback-Override-Felder im Sitzungseintrag.
• Automatische Fallback-Overrides bleiben in nachfolgenden Turns ausgewählt, damit OpenClaw nicht bei jeder Nachricht ein bekanntermaßen defektes Primärmodell prüft. /new, /reset und sessions.reset löschen automatisch gesetzte Overrides und setzen die Sitzung auf den konfigurierten Standard zurück.
• /status zeigt das ausgewählte Modell und, wenn der Fallback-Zustand abweicht, das aktive Fallback-Modell und den Grund.
• Die Live-Sitzungsabstimmung bevorzugt persistierte Sitzungs-Overrides gegenüber veralteten Laufzeit-Modellfeldern.
• Wenn ein Live-Wechsel-Fehler auf einen späteren Kandidaten in der aktiven Fallback-Kette verweist, springt OpenClaw direkt zu diesem ausgewählten Modell, statt zuerst nicht zugehörige Kandidaten zu durchlaufen.
• Wenn der Fallback-Versuch fehlschlägt, setzt der Runner nur die von ihm geschriebenen Override-Felder zurück, und nur wenn sie noch zu diesem fehlgeschlagenen Kandidaten passen.

​

Observability und Fehlersummaries

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

• nicht zugehörige modellbezogene Rate Limits werden für die versuchte Provider-/Modell-Kette ignoriert
• wenn die verbleibende Blockade ein passendes modellbezogenes Rate Limit 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