Przełączanie awaryjne modelu

OpenClaw obsługuje awarie w dwóch etapach:

1. Rotacja profilu uwierzytelniania w obrębie bieżącego dostawcy.
2. Przełączenie awaryjne modelu na następny model w agents.defaults.model.fallbacks.

Przepływ wykonania

Jest to celowo węższe niż „zapisz i przywróć całą sesję”. Moduł wykonawczy odpowiedzi utrwala tylko należące do niego pola wyboru modelu używane przez mechanizm przełączania awaryjnego: providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Zapobiega to nadpisaniu przez nieudaną ponowną próbę awaryjną nowszych, niezwiązanych z nią zmian sesji, takich jak ręczna zmiana /model lub aktualizacja rotacji sesji, która nastąpiła podczas wykonywania próby.

Zasady źródła wyboru

Źródło wyboru określa, czy użycie łańcucha awaryjnego jest dozwolone:

• Skonfigurowana wartość domyślna: agents.defaults.model.primary używa agents.defaults.model.fallbacks.
• Model podstawowy agenta: agents.list[].model działa ściśle, chyba że obiekt modelu tego agenta zawiera własne fallbacks. Użyj fallbacks: [], aby jawnie włączyć ścisłe zachowanie, lub niepustej listy, aby zezwolić temu agentowi na awaryjne przełączanie modeli.
• Automatyczne nadpisanie awaryjne: mechanizm awaryjny podczas wykonania zapisuje providerOverride, modelOverride, modelOverrideSource: "auto" oraz wybrany model źródłowy przed ponowieniem próby. To nadpisanie umożliwia dalsze przechodzenie po skonfigurowanym łańcuchu awaryjnym bez sprawdzania modelu podstawowego przy każdej wiadomości, ale OpenClaw sprawdza skonfigurowany model źródłowy co 5 minut (wartość nie jest konfigurowalna) i usuwa nadpisanie po przywróceniu jego działania. /new, /reset i sessions.reset również usuwają nadpisania pochodzące z automatycznego wyboru. Uruchomienia Heartbeat bez jawnego heartbeat.model usuwają bezpośrednie automatyczne nadpisania, gdy ich model źródłowy nie odpowiada już bieżącej skonfigurowanej wartości domyślnej.
• Nadpisanie sesji przez użytkownika: /model, selektor modelu, session_status(model=...) i sessions.patch zapisują modelOverrideSource: "user". Jest to dokładny wybór dla sesji. Jeśli wybrany dostawca lub model zawiedzie przed wygenerowaniem odpowiedzi, OpenClaw zgłosi błąd zamiast odpowiadać przy użyciu niezwiązanego, skonfigurowanego modelu awaryjnego.
• Starsze nadpisanie sesji: starsze wpisy sesji mogą zawierać modelOverride bez modelOverrideSource. OpenClaw traktuje je jako nadpisania użytkownika, aby jawny starszy wybór nie został po cichu przekształcony w zachowanie awaryjne.
• Model w ładunku Cron: payload.model / --model zadania cron jest modelem podstawowym zadania, a nie nadpisaniem sesji przez użytkownika. Używa skonfigurowanych modeli awaryjnych, chyba że zadanie zawiera payload.fallbacks; payload.fallbacks: [] wymusza ścisłe wykonanie zadania cron.

OpenClaw zapamiętuje ostatnie sprawdzenia modelu podstawowego dla każdej sesji i każdego modelu podstawowego, aby niesprawny model podstawowy nie był ponownie sprawdzany przy każdej turze. Wysyła widoczne powiadomienie, gdy sesja przechodzi na model awaryjny, oraz kolejne, gdy wraca do wybranego modelu podstawowego; powiadomienie nie jest powtarzane przy każdej turze korzystającej z utrwalonego modelu awaryjnego.

Pamięć podręczna pomijania błędów uwierzytelniania

Domyślnie każda nowa tura zachowuje dotychczasowe działanie ponownych prób awaryjnych: OpenClaw ponownie próbuje użyć każdego skonfigurowanego kandydata awaryjnego, w tym kandydatów innych niż podstawowy, którzy niedawno zawiedli z błędem auth lub auth_permanent.

Aby włączyć pomijanie powtarzających się błędów uwierzytelniania, ustaw:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Po włączeniu tej funkcji OpenClaw zapisuje w pamięci znacznik pominięcia o zasięgu sesji dla kandydata awaryjnego innego niż podstawowy po błędzie klasy uwierzytelniania. Kluczem jest identyfikator sesji, dostawca i model. Kandydaci podstawowi nigdy nie są pomijani, dzięki czemu jawny wybór modelu przez użytkownika nadal ujawnia rzeczywisty błąd uwierzytelniania. Pamięć podręczna ma zasięg procesu i jest czyszczona po ponownym uruchomieniu Gateway.

Wartość określa TTL w milisekundach. Wartość 0 lub brak ustawienia wyłącza pamięć podręczną. Wartości dodatnie są ograniczane do przedziału od 1 sekundy do 10 minut.

Widoczne dla użytkownika powiadomienia o przełączeniu awaryjnym

Gdy sesja przechodzi na automatycznie wybrany model awaryjny, OpenClaw wysyła powiadomienie o stanie w tym samym kanale odpowiedzi:

↪️ Przełączenie awaryjne modelu: <fallback> (wybrano <primary>; <reason>)

Gdy późniejsze sprawdzenie zakończy się powodzeniem i sesja wróci do wybranego modelu podstawowego, OpenClaw wysyła:

↪️ Wyłączono przełączenie awaryjne modelu: <primary> (poprzednio <fallback>)

Te powiadomienia są komunikatami operacyjnymi, a nie treścią asystenta. Są dostarczane jednokrotnie przy każdej zmianie stanu, w miarę możliwości również w turach obejmujących wyłącznie skutki uboczne, ale nie są powtarzane w turach korzystających z utrwalonego modelu awaryjnego. Dostarczanie omija zwykłe pomijanie odpowiedzi do źródła, nie zajmuje pierwszego miejsca odpowiedzi asystenta w kanałach z wątkami oraz jest wyłączone z syntezy mowy i wyodrębniania zobowiązań.

Przechowywanie danych uwierzytelniających (klucze i OAuth)

OpenClaw używa profili uwierzytelniania zarówno dla kluczy API, jak i tokenów OAuth.

• Sekrety i stan routingu uwierzytelniania podczas wykonania znajdują się w ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Konfiguracje auth.profiles / auth.order zawierają wyłącznie metadane i routing (bez sekretów).
• Starszy plik OAuth przeznaczony wyłącznie do importu: ~/.openclaw/credentials/oauth.json (importowany do magazynu uwierzytelniania agenta przy pierwszym użyciu).
• Starsze pliki auth-profiles.json, auth-state.json oraz pliki auth.json poszczególnych agentów są importowane przez openclaw doctor --fix.

Więcej szczegółów: OAuth

Typy danych uwierzytelniających:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl dla niektórych dostawców)
• type: "token" → statyczny token typu bearer, opcjonalnie wygasający; OpenClaw go nie odświeża (używany przez aws-sdk i inne tryby uwierzytelniania oparte na łańcuchu danych uwierzytelniających)

Identyfikatory profili

Logowania OAuth tworzą odrębne profile, dzięki czemu może współistnieć wiele kont.

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

Profile znajdują się w magazynie profili uwierzytelniania openclaw-agent.sqlite danego agenta.

Kolejność rotacji

Gdy dostawca ma wiele profili, OpenClaw wybiera kolejność w następujący sposób:

Jeśli nie skonfigurowano jawnej kolejności, OpenClaw używa kolejności cyklicznej:

• Klucz podstawowy: typ profilu (OAuth, następnie token statyczny, a następnie klucz API).
• Klucz pomocniczy: usageStats.lastUsed (najstarsze najpierw w obrębie każdego typu).
• Profile w okresie karencji lub wyłączone są przenoszone na koniec i porządkowane według najbliższego terminu wygaśnięcia.

Przywiązanie do sesji (sprzyjające pamięci podręcznej)

OpenClaw przypina wybrany profil uwierzytelniania do sesji, aby utrzymać aktywność pamięci podręcznych dostawcy. Nie wykonuje rotacji przy każdym żądaniu. Przypięty profil jest używany ponownie, dopóki:

• sesja nie zostanie zresetowana (/new / /reset)
• nie zakończy się Compaction (licznik Compaction zostanie zwiększony)
• profil nie znajdzie się w okresie karencji lub nie zostanie wyłączony

Ręczny wybór za pomocą /model …@<profileId> ustawia nadpisanie użytkownika dla tej sesji i nie podlega automatycznej rotacji do czasu rozpoczęcia nowej sesji.

Subskrypcja OpenAI Codex z zapasowym kluczem API

W przypadku modeli agentowych OpenAI uwierzytelnianie i środowisko wykonawcze są odrębne. openai/gpt-* pozostaje w środowisku Codex, natomiast uwierzytelnianie może rotować między profilem subskrypcji Codex a zapasowym kluczem API OpenAI.

Użyj auth.order.openai, aby określić kolejność widoczną dla użytkownika:

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

Używaj openai:* zarówno dla profili OAuth ChatGPT/Codex, jak i profili kluczy API OpenAI. Gdy subskrypcja osiągnie limit użycia Codex, OpenClaw zapisuje dokładny czas resetowania, jeśli Codex go udostępnia, próbuje użyć następnego profilu uwierzytelniania w kolejności i utrzymuje wykonanie w środowisku Codex. Po upływie czasu resetowania profil subskrypcji ponownie kwalifikuje się do użycia, a następny automatyczny wybór może do niego wrócić.

Używaj profilu przypiętego przez użytkownika tylko wtedy, gdy chcesz wymusić użycie jednego konta lub klucza w danej sesji. Profile przypięte przez użytkownika są celowo ścisłe i nie przełączają się po cichu na inny profil.

Okresy karencji

Gdy profil zawiedzie z powodu błędów uwierzytelniania lub limitu żądań (albo przekroczenia limitu czasu przypominającego ograniczenie liczby żądań), OpenClaw umieszcza go w okresie karencji i przechodzi do następnego profilu.

Zwykłe okresy karencji (niezwiązane z rozliczeniami ani trwałym błędem uwierzytelniania) wydłużają się wraz z liczbą ostatnich błędów profilu:

• 1. błąd: 30 sekund
• 2. błąd: 1 minuta
• 3. i kolejne błędy: 5 minut (limit)

Liczniki są resetowane po upływie okna błędów profilu (auth.cooldowns.failureWindowHours, domyślnie 24).

Stan jest przechowywany w stanie uwierzytelniania SQLite danego agenta, w sekcji usageStats:

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

Wyłączenia z powodu rozliczeń

Błędy rozliczeń lub środków (na przykład „niewystarczająca liczba środków” / „zbyt niskie saldo środków”) są traktowane jako uzasadniające przełączenie awaryjne, ale zwykle nie są przejściowe. Zamiast krótkiego okresu karencji OpenClaw oznacza profil jako wyłączony (z dłuższym okresem oczekiwania) i przełącza się na następny profil lub kolejnego dostawcę.

Trwałe błędy uwierzytelniania rozpoznane z wysoką pewnością (unieważnione lub dezaktywowane klucze, dezaktywowane obszary robocze) trafiają do podobnej kategorii wyłączenia, ale przywrócenie następuje znacznie szybciej niż w przypadku rozliczeń, ponieważ podczas incydentów niektórzy dostawcy przejściowo zwracają dane przypominające błędy uwierzytelniania.

Stan jest przechowywany w stanie uwierzytelniania SQLite danego agenta:

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

Wartości domyślne (auth.cooldowns.*):

Błędy przeciążenia i limitu żądań są obsługiwane bardziej agresywnie niż okresy karencji związane z rozliczeniami: domyślnie OpenClaw zezwala na jedną ponowną próbę z profilem uwierzytelniania tego samego dostawcy, a następnie bez oczekiwania przełącza się na kolejny skonfigurowany model zapasowy.

Model zapasowy

Jeśli zawiodą wszystkie profile dostawcy, OpenClaw przechodzi do następnego modelu z agents.defaults.model.fallbacks. Dotyczy to błędów uwierzytelniania, limitów żądań i przekroczeń czasu, dla których wyczerpano możliwości zmiany profilu (inne błędy nie powodują przejścia do modelu zapasowego). Błędy dostawcy, które nie zawierają wystarczających szczegółów, nadal otrzymują precyzyjne etykiety w stanie przełączania awaryjnego: empty_response oznacza, że dostawca nie zwrócił użytecznej wiadomości ani statusu, no_error_details oznacza, że dostawca jawnie zwrócił Unknown error (no error details in response), a unclassified oznacza, że OpenClaw zachował surowy podgląd, ale nie dopasował go jeszcze żaden klasyfikator.

Sygnały zajętości dostawcy, takie jak ModelNotReadyException, trafiają do kategorii przeciążenia i podlegają tej samej zasadzie jednej zmiany profilu przed przełączeniem awaryjnym co limity żądań (zobacz powyższą tabelę wartości domyślnych).

Gdy uruchomienie rozpoczyna się od skonfigurowanego domyślnego modelu głównego, modelu głównego zadania Cron, modelu głównego agenta z jawnymi modelami zapasowymi lub automatycznie wybranego nadpisania modelu zapasowego, OpenClaw może przejść przez odpowiedni skonfigurowany łańcuch modeli zapasowych. Modele główne agentów bez jawnych modeli zapasowych oraz jawne wybory użytkownika (na przykład /model ollama/qwen3.5:27b, selektor modelu, sessions.patch lub jednorazowe nadpisania dostawcy lub modelu w CLI) są traktowane ściśle: jeśli dany dostawca lub model jest nieosiągalny albo ulegnie awarii przed wygenerowaniem odpowiedzi, OpenClaw zgłasza błąd zamiast odpowiadać za pomocą niepowiązanego modelu zapasowego.

Reguły łańcucha kandydatów

OpenClaw tworzy listę kandydatów z aktualnie żądanego provider/model oraz skonfigurowanych modeli zapasowych.

Błędy powodujące przejście do modelu zapasowego

Pomijanie okresu karencji a zachowanie sondowania

Gdy wszystkie profile uwierzytelniania dostawcy są już objęte okresem karencji, OpenClaw nie pomija automatycznie tego dostawcy na zawsze. Podejmuje decyzję osobno dla każdego kandydata:

Nadpisania sesji i przełączanie modelu na żywo

Zmiany modelu sesji stanowią współdzielony stan. Aktywny wykonawca, polecenie /model, aktualizacje Compaction lub sesji oraz uzgadnianie sesji na żywo odczytują lub zapisują części tego samego wpisu sesji.

Oznacza to, że ponowne próby przełączenia awaryjnego muszą być skoordynowane z przełączaniem modelu na żywo:

• Tylko jawne zmiany modelu zainicjowane przez użytkownika oznaczają oczekujące przełączenie na żywo. Obejmuje to /model, session_status(model=...) i sessions.patch.
• Zmiany modelu inicjowane przez system, takie jak rotacja modeli zapasowych, nadpisania Heartbeat lub Compaction, nigdy same nie oznaczają oczekującego przełączenia na żywo.
• Nadpisania modelu zainicjowane przez użytkownika są traktowane jako dokładne wybory na potrzeby zasad przełączania awaryjnego, dlatego nieosiągalny wybrany dostawca powoduje zgłoszenie błędu zamiast jego ukrycia przez agents.defaults.model.fallbacks.
• Przed rozpoczęciem ponownej próby przełączenia awaryjnego wykonawca odpowiedzi utrwala pola nadpisania wybranego modelu zapasowego we wpisie sesji.
• Automatyczne nadpisania modelu zapasowego pozostają wybrane w kolejnych turach, dzięki czemu OpenClaw nie sonduje znanego jako niesprawny modelu głównego przy każdej wiadomości. OpenClaw okresowo ponownie sonduje skonfigurowany model pierwotny i usuwa automatyczne nadpisanie po odzyskaniu przez niego działania; /new, /reset i sessions.reset natychmiast usuwają nadpisania pochodzące z automatycznego wyboru.
• Odpowiedzi dla użytkownika informują o przejściu na model zapasowy i przywróceniu działania po usunięciu tego przełączenia raz na każdą zmianę stanu. Kolejne tury korzystające z zachowanego modelu zapasowego nie powtarzają tego powiadomienia.
• /status pokazuje wybrany model, a gdy stan przełączania awaryjnego jest inny — również aktywny model zapasowy i przyczynę.
• Uzgadnianie sesji na żywo preferuje utrwalone nadpisania sesji względem nieaktualnych pól modelu środowiska wykonawczego.
• Jeśli błąd przełączenia na żywo wskazuje późniejszego kandydata w aktywnym łańcuchu modeli zapasowych, OpenClaw przechodzi bezpośrednio do tego wybranego modelu zamiast najpierw sprawdzać niepowiązanych kandydatów.
• Jeśli próba użycia modelu zapasowego zakończy się niepowodzeniem, wykonawca wycofuje tylko zapisane przez siebie pola nadpisania i tylko wtedy, gdy nadal odpowiadają temu kandydatowi, który uległ awarii.

Zapobiega to klasycznemu wyścigowi:

Utrwalone nadpisanie modelu zapasowego zamyka to okno, a wąski zakres wycofania zachowuje nowsze ręczne lub wykonawcze zmiany sesji.

Obserwowalność i podsumowania błędów

runWithModelFallback(...) zapisuje szczegóły każdej próby, które są wykorzystywane w dziennikach i komunikatach dla użytkownika dotyczących okresu karencji:

• podjęta próba użycia dostawcy/modelu
• przyczyna (rate_limit, overloaded, billing, auth, model_not_found i podobne przyczyny przełączenia awaryjnego)
• opcjonalny stan/kod
• czytelne dla człowieka podsumowanie błędu

Ustrukturyzowane dzienniki model_fallback_decision zawierają również płaskie pola fallbackStep*, gdy kandydat zawiedzie, zostanie pominięty lub późniejsze przełączenie awaryjne zakończy się powodzeniem. Pola te jednoznacznie opisują podjętą próbę przejścia (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), dzięki czemu eksportery dzienników i danych diagnostycznych mogą odtworzyć pierwotną awarię, nawet gdy końcowe przełączenie awaryjne również zawiedzie.

Gdy wszyscy kandydaci zawiodą, OpenClaw zgłasza FallbackSummaryError. Zewnętrzny mechanizm obsługi odpowiedzi może użyć tego błędu do utworzenia bardziej szczegółowego komunikatu, na przykład „wszystkie modele są tymczasowo objęte limitami szybkości”, i podać najbliższy termin wygaśnięcia okresu karencji, jeśli jest znany.

To podsumowanie okresów karencji uwzględnia modele:

• niepowiązane limity szybkości dotyczące konkretnych modeli są ignorowane w przypadku rozpatrywanego łańcucha dostawców/modeli
• jeśli pozostałą blokadą jest pasujący limit szybkości dotyczący konkretnego modelu, OpenClaw podaje ostatni pasujący termin wygaśnięcia, który nadal blokuje ten model

Powiązana konfiguracja

Zobacz konfigurację Gateway, aby uzyskać informacje o:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• routingu agents.defaults.imageModel

Szersze omówienie wyboru modeli i przełączania awaryjnego znajdziesz w sekcji Modele.