​

Przełączanie awaryjne modeli

1. Rotacja profili uwierzytelniania w obrębie bieżącego providera.
2. Przełączenie awaryjne modelu do następnego modelu w agents.defaults.model.fallbacks.

​

Przebieg działania w runtime

1. Aktualnie wybrany model sesji.
2. Skonfigurowane agents.defaults.model.fallbacks w podanej kolejności.
3. Skonfigurowany model podstawowy na końcu, gdy uruchomienie zaczęło się od nadpisania.

1. Rozwiąż aktywny model sesji i preferencję profilu uwierzytelniania.
2. Zbuduj łańcuch kandydatów modeli.
3. Spróbuj bieżącego providera z regułami rotacji/cooldownu profili uwierzytelniania.
4. Jeśli ten provider zostanie wyczerpany z błędem kwalifikującym do przełączenia awaryjnego, przejdź do następnego kandydata modelu.
5. Utrwal wybrane nadpisanie fallback przed rozpoczęciem ponownej próby, aby inni czytelnicy sesji widzieli tego samego providera/model, którego runner zaraz użyje.
6. Jeśli kandydat fallback zakończy się niepowodzeniem, wycofaj tylko pola nadpisania sesji należące do fallbacku, gdy nadal odpowiadają temu nieudanemu kandydatowi.
7. Jeśli każdy kandydat zawiedzie, rzuć FallbackSummaryError ze szczegółami dla każdej próby i najbliższym czasem wygaśnięcia cooldownu, gdy jest znany.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Przechowywanie uwierzytelniania (klucze + OAuth)

• Sekrety znajdują się w ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (starsza lokalizacja: ~/.openclaw/agent/auth-profiles.json).
• Konfiguracja auth.profiles / auth.order to wyłącznie metadane + routing (bez sekretów).
• Starszy plik OAuth tylko do importu: ~/.openclaw/credentials/oauth.json (importowany do auth-profiles.json przy pierwszym użyciu).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl dla niektórych providerów)

​

Identyfikatory profili

• Domyślnie: provider:default, gdy adres e-mail nie jest dostępny.
• OAuth z adresem e-mail: provider:<email> (na przykład google-antigravity:user@gmail.com).

​

Kolejność rotacji

1. Jawna konfiguracja: auth.order[provider] (jeśli ustawiono).
2. Skonfigurowane profile: auth.profiles przefiltrowane według providera.
3. Zapisane profile: wpisy w auth-profiles.json dla providera.

• Klucz główny: typ profilu (OAuth przed kluczami API).
• Klucz pomocniczy: usageStats.lastUsed (najstarszy najpierw, w obrębie każdego typu).
• Profile w cooldownie/wyłączone są przenoszone na koniec, uporządkowane według najbliższego wygaśnięcia.

​

Przyklejenie do sesji (cache-friendly)

• sesja nie zostanie zresetowana (/new / /reset)
• nie zakończy się kompaktowanie (licznik kompaktowania wzrośnie)
• profil nie będzie w cooldownie/wyłączony

​

Dlaczego OAuth może „wyglądać na utracone”

• Przypnij przez auth.order[provider] = ["provider:profileId"], lub
• Użyj nadpisania dla sesji przez /model … z nadpisaniem profilu (gdy jest obsługiwane przez Twój interfejs/UI czatu).

​

Cooldowny

• OpenClaw zapisuje cooldownModel dla niepowodzeń z powodu limitów szybkości, gdy znany jest identyfikator nieudanego modelu.
• Pokrewny model tego samego providera nadal może zostać wypróbowany, gdy cooldown jest ograniczony do innego modelu.
• Okna rozliczeniowe/wyłączenia nadal blokują cały profil we wszystkich modelach.

• 1 minuta
• 5 minut
• 25 minut
• 1 godzina (limit)

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

​

Wyłączenia rozliczeniowe

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

• Backoff rozliczeniowy zaczyna się od 5 godzin, podwaja się przy każdym błędzie rozliczeniowym i jest ograniczony do 24 godzin.
• Liczniki backoffu są resetowane, jeśli profil nie zawiódł przez 24 godziny (konfigurowalne).
• Ponowne próby przy przeciążeniu dopuszczają 1 rotację profilu tego samego providera przed przełączeniem awaryjnym modelu.
• Ponowne próby przy przeciążeniu używają domyślnie 0 ms backoffu.

​

Przełączanie awaryjne modelu

​

Reguły łańcucha kandydatów

• Żądany model jest zawsze pierwszy.
• Jawnie skonfigurowane fallbacki są deduplikowane, ale nie są filtrowane przez allowlistę modeli. Są traktowane jako jawna intencja operatora.
• Jeśli bieżące uruchomienie jest już na skonfigurowanym fallbacku w tej samej rodzinie providera, OpenClaw nadal używa pełnego skonfigurowanego łańcucha.
• Jeśli bieżące uruchomienie jest na innym providerze niż w konfiguracji i ten bieżący model nie jest już częścią skonfigurowanego łańcucha fallbacków, OpenClaw nie dołącza niezwiązanych skonfigurowanych fallbacków z innego providera.
• Gdy uruchomienie zaczęło się od nadpisania, skonfigurowany model podstawowy jest dołączany na końcu, aby łańcuch mógł wrócić do normalnego ustawienia domyślnego po wyczerpaniu wcześniejszych kandydatów.

​

Które błędy przesuwają fallback dalej

• błędach uwierzytelniania
• limitach szybkości i wyczerpaniu cooldownu
• błędach przeciążenia/zajętości providera
• błędach timeoutów kwalifikujących do przełączenia awaryjnego
• wyłączeniach rozliczeniowych
• LiveSessionModelSwitchError, który jest normalizowany do ścieżki przełączenia awaryjnego, aby przestarzały utrwalony model nie tworzył zewnętrznej pętli ponownych prób
• innych nierozpoznanych błędach, gdy nadal są dostępni kolejni kandydaci

• jawnych przerwaniach, które nie mają charakteru timeoutu/błędu kwalifikującego do przełączenia awaryjnego
• błędach przepełnienia kontekstu, które powinny pozostać w logice kompaktowania/ponownych prób (na przykład 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 lub ollama error: context length exceeded)
• końcowym nieznanym błędzie, gdy nie ma już kandydatów

​

Pomijanie cooldownu a zachowanie sondujące

• Trwałe błędy uwierzytelniania powodują natychmiastowe pominięcie całego providera.
• Wyłączenia rozliczeniowe zwykle powodują pominięcie, ale podstawowy kandydat może być nadal sondowany z ograniczeniem, aby odzyskanie było możliwe bez restartu.
• Podstawowy kandydat może być sondowany blisko końca cooldownu, z ograniczeniem dla danego providera.
• Fallbackowe modele tego samego providera mogą być próbowane mimo cooldownu, gdy błąd wygląda na przejściowy (rate_limit, overloaded lub nieznany). Jest to szczególnie istotne, gdy limit szybkości jest ograniczony do modelu, a pokrewny model może nadal odzyskać dostęp natychmiast.
• Przejściowe sondy cooldownu są ograniczone do jednej na providera na jedno uruchomienie fallbacku, aby pojedynczy provider nie blokował fallbacku między providerami.

​

Nadpisania sesji i przełączanie modelu na żywo

• Tylko jawne zmiany modelu sterowane przez użytkownika oznaczają oczekujące przełączenie na żywo. Dotyczy to /model, session_status(model=...) oraz sessions.patch.
• Zmiany modelu sterowane przez system, takie jak rotacja fallbacku, nadpisania heartbeat czy kompaktowanie, nigdy same z siebie nie oznaczają oczekującego przełączenia na żywo.
• Zanim rozpocznie się ponowna próba fallbacku, runner odpowiedzi utrwala wybrane pola nadpisania fallbacku we wpisie sesji.
• Uzgadnianie live-session preferuje utrwalone nadpisania sesji względem przestarzałych pól modelu runtime.
• Jeśli próba fallback się nie powiedzie, runner wycofuje tylko te pola nadpisania, które sam zapisał, i tylko wtedy, gdy nadal odpowiadają temu nieudanemu kandydatowi.

1. Model podstawowy zawodzi.
2. Kandydat fallback zostaje wybrany w pamięci.
3. Magazyn sesji nadal wskazuje stary model podstawowy.
4. Uzgadnianie live-session odczytuje przestarzały stan sesji.
5. Ponowna próba zostaje cofnięta do starego modelu, zanim rozpocznie się próba fallbacku.

​

Obserwowalność i podsumowania błędów

• próbowany provider/model
• powód (rate_limit, overloaded, billing, auth, model_not_found oraz podobne powody przełączania awaryjnego)
• opcjonalny status/kod
• czytelne dla człowieka podsumowanie błędu

• niezwiązane limity szybkości ograniczone do modelu są ignorowane dla próbowanego łańcucha provider/model
• jeśli pozostałą blokadą jest pasujący limit szybkości ograniczony do modelu, OpenClaw raportuje ostatni pasujący czas wygaśnięcia, który nadal blokuje ten model

​

Powiązana konfiguracja

• 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
• routing agents.defaults.imageModel