​

Przełączanie awaryjne modeli

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

​

Przepływ działania w czasie wykonywania

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

1. Ustal aktywny model sesji i preferencję profilu uwierzytelniania.
2. Zbuduj łańcuch kandydatów modeli.
3. Spróbuj bieżącego dostawcy z regułami rotacji/cooldownu profilu uwierzytelniania.
4. Jeśli możliwości tego dostawcy się wyczerpią z błędem kwalifikującym się do przełączenia awaryjnego, przejdź do następnego kandydata modelu.
5. Zapisz wybrane nadpisanie awaryjne przed rozpoczęciem ponownej próby, aby inni czytelnicy sesji widzieli tego samego dostawcę/model, którego moduł wykonawczy zaraz użyje.
6. Jeśli kandydat awaryjny się nie powiedzie, wycofaj tylko pola nadpisania sesji należące do przełączenia awaryjnego, o ile nadal odpowiadają temu nieudanemu kandydatowi.
7. Jeśli wszyscy kandydaci zawiodą, zgłoś FallbackSummaryError ze szczegółami dla każdej próby i najbliższym terminem wygaśnięcia cooldownu, jeśli jest znany.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Przechowywanie uwierzytelniania (klucze + OAuth)

• Sekrety są przechowywane w ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (starsza ścieżka: ~/.openclaw/agent/auth-profiles.json).
• Stan routingu uwierzytelniania w czasie wykonywania jest przechowywany w ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Konfiguracja auth.profiles / auth.order to tylko 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 dostawcó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 odfiltrowane według dostawcy.
3. Zapisane profile: wpisy w auth-profiles.json dla danego dostawcy.

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

​

Przyklejenie do sesji (przyjazne dla cache)

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

​

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

• Przypnij za pomocą auth.order[provider] = ["provider:profileId"], lub
• Użyj nadpisania per sesja przez /model … z nadpisaniem profilu (jeśli jest obsługiwane przez Twój interfejs użytkownika/powierzchnię czatu).

​

Cooldowny

• OpenClaw zapisuje cooldownModel dla błędów limitu szybkości, gdy identyfikator błędnego modelu jest znany.
• Model siostrzany u tego samego dostawcy 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"
    }
  }
}

• Czas wycofania po błędach rozliczeniowych zaczyna się od 5 godzin, podwaja się przy każdym takim błędzie i osiąga maksymalnie 24 godziny.
• Liczniki wycofania są resetowane, jeśli profil nie zawiódł przez 24 godziny (konfigurowalne).
• Ponowne próby przy przeciążeniu pozwalają na 1 rotację profilu u tego samego dostawcy przed przełączeniem awaryjnym modelu.
• Ponowne próby przy przeciążeniu domyślnie używają wycofania 0 ms.

​

Przełączanie awaryjne modelu

​

Reguły łańcucha kandydatów

• Żądany model jest zawsze pierwszy.
• Jawnie skonfigurowane modele awaryjne są deduplikowane, ale nie są filtrowane przez listę dozwolonych modeli. Są traktowane jako jawna intencja operatora.
• Jeśli bieżące uruchomienie już działa na skonfigurowanym modelu awaryjnym z tej samej rodziny dostawców, OpenClaw nadal używa całego skonfigurowanego łańcucha.
• Jeśli bieżące uruchomienie działa na innym dostawcy niż w konfiguracji i ten bieżący model nie jest już częścią skonfigurowanego łańcucha modeli awaryjnych, OpenClaw nie dołącza niezwiązanych skonfigurowanych modeli awaryjnych od innego dostawcy.
• Gdy uruchomienie rozpoczęło się od nadpisania, skonfigurowany model podstawowy jest dołączany na końcu, aby łańcuch mógł wrócić do zwykłego ustawienia domyślnego po wyczerpaniu wcześniejszych kandydatów.

​

Które błędy powodują przejście do kolejnego modelu

• błędach uwierzytelniania
• limitach szybkości i wyczerpaniu cooldownu
• błędach przeciążenia/zajętości dostawcy
• błędach timeoutu kwalifikujących się do przełączenia awaryjnego
• wyłączeniach rozliczeniowych
• LiveSessionModelSwitchError, które jest normalizowane do ścieżki przełączania awaryjnego, aby nieaktualny zapisany model nie tworzył zewnętrznej pętli ponownych prób
• innych nierozpoznanych błędach, gdy nadal pozostają kandydaci

• jawnych przerwaniach, które nie mają charakteru timeoutu/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 pozostał już żaden kandydat

​

Pomijanie cooldownu a zachowanie sondowania

• Trwałe błędy uwierzytelniania powodują natychmiastowe pominięcie całego dostawcy.
• Wyłączenia rozliczeniowe zwykle powodują pominięcie, ale podstawowy kandydat nadal może być sondowany z ograniczeniem, aby odzyskanie było możliwe bez restartu.
• Podstawowy kandydat może być sondowany blisko wygaśnięcia cooldownu, z ograniczeniem per dostawca.
• Modele siostrzane tego samego dostawcy mogą zostać wypró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 i model siostrzany może nadal odzyskać dostęp natychmiast.
• Przejściowe sondowania cooldownu są ograniczone do jednego na dostawcę w jednym przebiegu przełączania awaryjnego, aby pojedynczy dostawca nie blokował przełączeń między dostawcami.

​

Nadpisania sesji i przełączanie modelu na żywo

• Tylko jawne zmiany modelu inicjowane przez użytkownika oznaczają oczekujące przełączenie na żywo. Dotyczy to /model, session_status(model=...) i sessions.patch.
• Zmiany modelu inicjowane przez system, takie jak rotacja awaryjna, nadpisania heartbeat lub kompaktowanie, nigdy same z siebie nie oznaczają oczekującego przełączenia na żywo.
• Przed rozpoczęciem ponownej próby przełączenia awaryjnego moduł wykonujący odpowiedź zapisuje wybrane pola nadpisania awaryjnego do wpisu sesji.
• Uzgadnianie sesji na żywo preferuje zapisane nadpisania sesji zamiast nieaktualnych pól modelu w czasie wykonywania.
• Jeśli próba awaryjna się nie powiedzie, moduł wykonawczy wycofuje tylko te pola nadpisania, które sam zapisał, i tylko wtedy, gdy nadal odpowiadają temu nieudanemu kandydatowi.

1. Model podstawowy zawodzi.
2. Kandydat awaryjny zostaje wybrany w pamięci.
3. Magazyn sesji nadal wskazuje stary model podstawowy.
4. Uzgadnianie sesji na żywo odczytuje nieaktualny stan sesji.
5. Ponowna próba zostaje cofnięta do starego modelu, zanim rozpocznie się próba awaryjna.

​

Obserwowalność i podsumowania błędów

• próbowany dostawca/model
• przyczyna (rate_limit, overloaded, billing, auth, model_not_found i podobne przyczyny przełączenia 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 dostawca/model
• jeśli pozostałą blokadą jest pasujący limit szybkości ograniczony do modelu, OpenClaw podaje ostatni pasujący termin 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