Przełączanie awaryjne modelu

OpenClaw obsługuje awarie w dwóch etapach:

1. Rotacja profilu uwierzytelniania w obrębie bieżącego dostawcy.
2. Awaryjny wybór modelu do następnego modelu w agents.defaults.model.fallbacks.

Ten dokument wyjaśnia reguły działania w czasie wykonywania oraz dane, na których się opierają.

Przepływ w czasie wykonywania

Dla zwykłego przebiegu tekstowego OpenClaw ocenia kandydatów w tej kolejności:

To celowo węższe niż „zapisz i przywróć całą sesję”. Runner odpowiedzi utrwala tylko pola wyboru modelu, które posiada na potrzeby awaryjnego wyboru:

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

Zapobiega to nadpisaniu nowszych, niezwiązanych mutacji sesji przez nieudaną ponowną próbę awaryjną, takich jak ręczne zmiany /model albo aktualizacje rotacji sesji, które wystąpiły w trakcie wykonywania próby.

Zasady źródła wyboru

OpenClaw oddziela wybranego dostawcę/model od powodu tego wyboru. To źródło kontroluje, czy łańcuch awaryjny jest dozwolony:

• Skonfigurowana wartość domyślna: agents.defaults.model.primary używa agents.defaults.model.fallbacks.
• Model główny agenta: agents.list[].model jest ścisły, chyba że obiekt modelu tego agenta zawiera własne fallbacks. Użyj fallbacks: [], aby jawnie wskazać ścisłe zachowanie, albo podaj niepustą listę, aby włączyć awaryjny wybór modelu dla tego agenta.
• Automatyczne nadpisanie awaryjne: awaryjny wybór w czasie wykonywania zapisuje providerOverride, modelOverride, modelOverrideSource: "auto" oraz wybrany model pochodzenia przed ponowną próbą. To automatyczne nadpisanie może dalej przechodzić przez skonfigurowany łańcuch awaryjny i jest czyszczone przez /new, /reset oraz sessions.reset. Przebiegi Heartbeat bez jawnego heartbeat.model również czyszczą bezpośrednie automatyczne nadpisanie, gdy jego pochodzenie nie odpowiada już bieżącej skonfigurowanej wartości domyślnej.
• Nadpisanie sesji użytkownika: /model, selektor modelu, session_status(model=...) oraz sessions.patch zapisują modelOverrideSource: "user". To jest dokładny wybór sesji. Jeśli wybrany dostawca/model zawiedzie przed wygenerowaniem odpowiedzi, OpenClaw zgłosi błąd zamiast odpowiedzieć z niepowiązanego skonfigurowanego modelu awaryjnego.
• Starsze nadpisanie sesji: starsze wpisy sesji mogą mieć modelOverride bez modelOverrideSource. OpenClaw traktuje je jako nadpisania użytkownika, aby jawny stary wybór nie został po cichu przekształcony w zachowanie awaryjne.
• Model z ładunku Cron: payload.model / --model zadania cron jest modelem głównym zadania, a nie nadpisaniem sesji użytkownika. Używa skonfigurowanych modeli awaryjnych, chyba że zadanie podaje payload.fallbacks; payload.fallbacks: [] powoduje ścisłe wykonanie zadania cron.

Przechowywanie uwierzytelniania (klucze + OAuth)

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

• Sekrety znajdują się w ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (starsza ścieżka: ~/.openclaw/agent/auth-profiles.json).
• Stan routingu uwierzytelniania w czasie wykonywania znajduje się 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).

Więcej szczegółów: OAuth

Typy poświadczeń:

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

Identyfikatory profili

Logowania OAuth tworzą osobne profile, aby wiele kont mogło współistnieć.

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

Profile znajdują się w ~/.openclaw/agents/<agentId>/agent/auth-profiles.json w sekcji profiles.

Kolejność rotacji

Gdy dostawca ma wiele profili, OpenClaw wybiera kolejność tak:

Jeśli nie skonfigurowano jawnej kolejności, OpenClaw używa kolejności round-robin:

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

Przywiązanie sesji (przyjazne dla cache)

OpenClaw przypina wybrany profil uwierzytelniania do sesji, aby utrzymać ciepłe cache dostawców. Nie rotuje go 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 wzrośnie)
• profil nie jest w okresie wyciszenia/wyłączony

Ręczny wybór przez /model …@<profileId> ustawia nadpisanie użytkownika dla tej sesji i nie jest automatycznie rotowany aż do rozpoczęcia nowej sesji.

Subskrypcja OpenAI Codex plus zapasowy klucz API

Dla modeli agentów OpenAI uwierzytelnianie i runtime są oddzielne. openai/gpt-* pozostaje na harnessie Codex, podczas gdy uwierzytelnianie może rotować między profilem subskrypcji Codex a zapasowym kluczem API OpenAI.

Użyj auth.order.openai dla kolejności widocznej dla użytkownika:

{  auth: {    order: {      openai: ["openai-codex:[email protected]", "openai:api-key-backup"],    },  },}

Istniejące profile subskrypcji Codex mogą nadal używać starszego identyfikatora profilu openai-codex:*. Uporządkowany zapasowy klucz API może być zwykłym profilem klucza API openai:*. Gdy subskrypcja osiągnie limit użycia Codex, OpenClaw zapisuje dokładny czas resetu, jeśli Codex go podaje, próbuje następnego uporządkowanego profilu uwierzytelniania i utrzymuje przebieg w harnessie Codex. Gdy czas resetu minie, profil subskrypcji znów 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ć jedno konto/klucz dla tej sesji. Profile przypięte przez użytkownika są celowo ścisłe i nie przeskakują po cichu do innego profilu.

Okresy wyciszenia

Gdy profil zawiedzie z powodu błędów uwierzytelniania/limitów szybkości (albo przekroczenia czasu wyglądającego jak limitowanie), OpenClaw oznacza go jako będący w okresie wyciszenia i przechodzi do następnego profilu.

Okresy wyciszenia używają wykładniczego backoffu:

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

Stan jest przechowywany w auth-state.json w sekcji usageStats:

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

Wyłączenia rozliczeniowe

Awarie rozliczeń/kredytów (na przykład „insufficient credits” / „credit balance too low”) są traktowane jako kwalifikujące się do przełączenia awaryjnego, ale zwykle nie są przejściowe. Zamiast krótkiego okresu wyciszenia OpenClaw oznacza profil jako wyłączony (z dłuższym backoffem) i rotuje do następnego profilu/dostawcy.

Stan jest przechowywany w auth-state.json:

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

Wartości domyślne:

• Odczekanie po błędzie rozliczeń zaczyna się od 5 godzin, podwaja się po każdej awarii rozliczeń i jest ograniczone do 24 godzin.
• Liczniki odczekania resetują się, jeśli profil nie zawiódł przez 24 godziny (konfigurowalne).
• Ponowienia przy przeciążeniu pozwalają na 1 rotację profilu u tego samego dostawcy przed awaryjnym przełączeniem modelu.
• Ponowienia przy przeciążeniu domyślnie używają odczekania 0 ms.

Awaryjne przełączanie modeli

Jeśli wszystkie profile dostawcy zawiodą, OpenClaw przechodzi do następnego modelu w agents.defaults.model.fallbacks. Dotyczy to awarii uwierzytelniania, limitów szybkości i przekroczeń czasu, które wyczerpały rotację profili (inne błędy nie uruchamiają awaryjnego przełączenia). Błędy dostawcy, które nie ujawniają wystarczających szczegółów, nadal są precyzyjnie oznaczane w stanie awaryjnego przełączenia: 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 żaden klasyfikator jeszcze do niego nie pasował.

Błędy przeciążenia i limitu szybkości są obsługiwane bardziej agresywnie niż odczekania rozliczeniowe. Domyślnie OpenClaw pozwala na jedną ponowną próbę profilu uwierzytelniania u tego samego dostawcy, a następnie bez czekania przełącza się na następny skonfigurowany model awaryjny. Sygnały zajętości dostawcy, takie jak ModelNotReadyException, trafiają do tego koszyka przeciążenia. Dostosuj to za pomocą auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs i auth.cooldowns.rateLimitedProfileRotations.

Gdy przebieg zaczyna się od skonfigurowanego domyślnego modelu podstawowego, podstawowego modelu zadania cron, podstawowego modelu agenta z jawnymi modelami awaryjnymi albo automatycznie wybranego nadpisania awaryjnego, OpenClaw może przejść przez pasujący skonfigurowany łańcuch awaryjny. Podstawowe modele agentów bez jawnych modeli awaryjnych oraz jawne wybory użytkownika (na przykład /model ollama/qwen3.5:27b, selektor modelu, sessions.patch albo jednorazowe nadpisania dostawcy/modelu w CLI) są ścisłe: jeśli ten dostawca/model jest nieosiągalny albo zawiedzie przed wygenerowaniem odpowiedzi, OpenClaw zgłasza błąd zamiast odpowiadać z niepowiązanego modelu awaryjnego.

Reguły łańcucha kandydatów

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

Które błędy uruchamiają awaryjne przełączenie

Zachowanie pomijania odczekania kontra sondowania

Gdy każdy profil uwierzytelniania dla dostawcy jest już w okresie odczekania, OpenClaw nie pomija automatycznie tego dostawcy na zawsze. Podejmuje decyzję dla każdego kandydata:

Nadpisania sesji i przełączanie modelu na żywo

Zmiany modelu sesji są stanem współdzielonym. Aktywny mechanizm uruchamiający, polecenie /model, aktualizacje Compaction/sesji oraz uzgadnianie sesji na żywo odczytują lub zapisują części tego samego wpisu sesji.

Oznacza to, że ponowienia awaryjne muszą koordynować się 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 zainicjowane przez system, takie jak rotacja awaryjna, nadpisania Heartbeat czy Compaction, nigdy same nie oznaczają oczekującego przełączenia na żywo.
• Nadpisania modelu zainicjowane przez użytkownika są traktowane jako dokładne wybory dla polityki awaryjnej, więc nieosiągalny wybrany dostawca ujawnia się jako awaria zamiast być maskowany przez agents.defaults.model.fallbacks.
• Przed rozpoczęciem ponownej próby awaryjnej mechanizm odpowiedzi utrwala wybrane pola nadpisania awaryjnego we wpisie sesji.
• Automatyczne nadpisania awaryjne pozostają wybrane w kolejnych turach, aby OpenClaw nie sondował znanego wadliwego modelu podstawowego przy każdej wiadomości. /new, /reset i sessions.reset czyszczą nadpisania pochodzące z automatyki i przywracają sesję do skonfigurowanej wartości domyślnej.
• /status pokazuje wybrany model, a gdy stan awaryjny się różni, aktywny model awaryjny i przyczynę.
• Uzgadnianie sesji na żywo preferuje utrwalone nadpisania sesji względem nieaktualnych pól modelu środowiska uruchomieniowego.
• Jeśli błąd przełączenia na żywo wskazuje późniejszego kandydata w aktywnym łańcuchu awaryjnym, OpenClaw przechodzi bezpośrednio do tego wybranego modelu zamiast najpierw przechodzić przez niepowiązanych kandydatów.
• Jeśli próba awaryjna zawiedzie, mechanizm uruchamiający wycofuje tylko pola nadpisania, które sam zapisał, i tylko jeśli nadal pasują do tego nieudanego kandydata.

Zapobiega to klasycznemu wyścigowi:

Utrwalone nadpisanie awaryjne zamyka to okno, a wąskie wycofanie pozostawia nowsze ręczne lub środowiskowe zmiany sesji bez zmian.

Obserwowalność i podsumowania awarii

runWithModelFallback(...) rejestruje szczegóły każdej próby, które zasilają dzienniki oraz komunikaty o odczekaniu widoczne dla użytkownika:

• próbowany dostawca/model
• przyczyna (rate_limit, overloaded, billing, auth, model_not_found oraz podobne przyczyny przełączenia awaryjnego)
• opcjonalny status/kod
• czytelne dla człowieka podsumowanie błędu

Strukturalne dzienniki model_fallback_decision zawierają też płaskie pola fallbackStep*, gdy kandydat zawodzi, jest pomijany albo późniejszy model awaryjny kończy się sukcesem. Te pola czynią próbowane przejście jawnym (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), aby eksportery dzienników i diagnostyki mogły odtworzyć awarię modelu podstawowego, nawet gdy końcowy model awaryjny także zawiedzie.

Gdy każdy kandydat zawiedzie, OpenClaw zgłasza FallbackSummaryError. Zewnętrzny mechanizm odpowiedzi może użyć tego do zbudowania bardziej szczegółowej wiadomości, takiej jak „wszystkie modele są tymczasowo objęte limitem szybkości”, i uwzględnić najbliższe wygaśnięcie odczekania, jeśli jest znane.

To podsumowanie odczekania uwzględnia model:

• niepowiązane limity szybkości o zakresie modelu są ignorowane dla próbowanego łańcucha dostawca/model
• jeśli pozostała blokada jest pasującym limitem szybkości o zakresie modelu, OpenClaw zgłasza ostatnie pasujące wygaśnięcie, które nadal blokuje ten model

Powiązana konfiguracja

Zobacz Konfiguracja Gateway, aby uzyskać informacje o:

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

Zobacz Modele, aby uzyskać szerszy przegląd wyboru modelu i awaryjnego przełączania.