Mechanizm failover
OpenClaw stosuje dwuetapową obsługę awarii: najpierw rotuje profile uwierzytelniania w ramach providera, a dopiero potem przechodzi na alternatywne modele z listy agents.defaults.model.fallbacks.
Przebieg runtime
System ewaluuje kandydatów sekwencyjnie:
- Bieżący model sesji
- Skonfigurowane modele zapasowe w kolejności
- Model główny (jeśli uruchomienie rozpoczęto od nadpisania)
W ramach każdego kandydata, rotacja profili uwierzytelniania następuje przed przejściem do kolejnego modelu.
Przechowywanie poświadczeń
Poświadczenia przechowywane są w pliku ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. System obsługuje zarówno klucze API, jak i tokeny OAuth, rozróżniając sekrety (przechowywane lokalnie) od metadanych (używanych do routingu).
Strategia rotacji profili
Gdy istnieje wiele profili dla jednego providera, kolejność wyboru jest następująca:
- Jawna konfiguracja przez
auth.order[provider] - Skonfigurowane profile filtrowane po providerze
- Zapisane profile z
auth-profiles.json
Porządkowanie round-robin priorytetyzuje OAuth przed kluczami API, a następnie sortuje od najdawniej używanego. Profile z cooldownem trafiają na koniec kolejki.
Sticky sessions (przypinanie per sesja)
System przypina wybrany profil auth do sesji, aby utrzymać efektywność cache'u providera. Rotacja nie następuje, dopóki sesja nie zostanie zresetowana lub nie aktywuje się cooldown.
Mechanizm cooldown
Błędy rate-limit i auth wyzwalają wykładnicze opóźnienie: 1 minuta, potem 5 minut, 25 minut, aż do maksymalnie 1 godziny. Błędy billingowe otrzymują dłuższe okresy cooldownu (5-24 godziny).
Klasyfikacja błędów
System rozróżnia dwa typy błędów:
- Przejściowe — wyzwalają rotację profili w ramach providera
- Trwałe — powodują przejście na kolejny model zapasowy
Przepełnienie kontekstu (context overflow) i jawne przerwanie nie wyzwalają failoveru.
Koordynacja z nadpisaniami sesji
Zmiana modelu na żywo jest koordynowana z ponowieniami fallback poprzez utrwalone pola nadpisania. Zapobiega to wyścigom między kandydatami runtime a zapisanym stanem sesji.