Przełączanie awaryjne modelu

1. Rotacja profilu uwierzytelniania w ramach bieżącego dostawcy.
2. Fallback modelu do następnego modelu w agents.defaults.model.fallbacks.

​

Przepływ w czasie wykonania

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

​

Zasady źródła wyboru

• 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ć fallback modelu dla tego agenta.
• Automatyczne nadpisanie fallback: fallback w czasie wykonania zapisuje providerOverride, modelOverride, modelOverrideSource: "auto" i wybrany model źródłowy przed ponowną próbą. To automatyczne nadpisanie może dalej przechodzić przez skonfigurowany łańcuch fallback bez sprawdzania modelu głównego przy każdej wiadomości, ale OpenClaw okresowo ponownie sprawdza skonfigurowane źródło i czyści automatyczne nadpisanie, gdy ono się odtworzy. /new, /reset i sessions.reset również czyszczą nadpisania pochodzące z automatycznego źródła. Uruchomienia Heartbeat bez jawnego heartbeat.model czyszczą bezpośrednie automatyczne nadpisania, gdy ich źródło nie odpowiada już bieżącej skonfigurowanej wartości domyślnej.
• Nadpisanie sesji użytkownika: /model, selektor modelu, session_status(model=...) i sessions.patch zapisują modelOverrideSource: "user". To jest dokładny wybór sesji. Jeśli wybrany dostawca/model zawiedzie przed wygenerowaniem odpowiedzi, OpenClaw zgłasza awarię zamiast odpowiadać z niepowiązanego skonfigurowanego fallback.
• 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 fallback.
• Model ładunku Cron: payload.model / --model zadania cron jest modelem głównym zadania, a nie nadpisaniem sesji użytkownika. Używa skonfigurowanych fallbacków, chyba że zadanie podaje payload.fallbacks; payload.fallbacks: [] sprawia, że uruchomienie cron jest ścisłe.

​

Pamięć podręczna pomijania awarii uwierzytelniania

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

Powiadomienia fallback widoczne dla użytkownika

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

↪️ Model Fallback cleared: <primary> (was <fallback>)

​

Przechowywanie uwierzytelniania (klucze + OAuth)

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

• 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

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

​

Lepkość sesji (przyjazna dla pamięci podręcznych)

• sesja zostanie zresetowana (/new / /reset)
• zakończy się compaction (licznik compaction wzrośnie)
• profil jest w ochłodzeniu/wyłączony

​

Subskrypcja OpenAI Codex plus zapasowy klucz API

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

​

Ochłodzenia

• 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"
    }
  }
}

• Opóźnienie rozliczeniowe zaczyna się od 5 godzin, podwaja się przy każdym błędzie rozliczeniowym i ma limit 24 godzin.
• Liczniki opóźnień resetują się, jeśli profil nie zawiódł przez 24 godziny (konfigurowalne).
• Ponowienia przy przeciążeniu pozwalają na 1 rotację profilu tego samego dostawcy przed awaryjnym przełączeniem modelu.
• Ponowienia przy przeciążeniu domyślnie używają opóźnienia 0 ms.

​

Awaryjne przełączenie modelu

​

Reguły łańcucha kandydatów

​

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

​

Pomijanie wyciszenia a zachowanie sondowania

​

Zastąpienia sesji i przełączanie modelu na żywo

• Tylko jawne zmiany modelu inicjowane 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 awaryjna, zastąpienia Heartbeat albo Compaction, nigdy same nie oznaczają oczekującego przełączenia na żywo.
• Zastąpienia modelu inicjowane przez użytkownika są traktowane jako dokładne wybory dla polityki przełączeń awaryjnych, więc nieosiągalny wybrany dostawca ujawnia się jako błąd zamiast być maskowany przez agents.defaults.model.fallbacks.
• Zanim rozpocznie się ponowienie przełączenia awaryjnego, moduł uruchamiający odpowiedź utrwala wybrane pola zastąpienia awaryjnego we wpisie sesji.
• Automatyczne zastąpienia awaryjne pozostają wybrane w kolejnych turach, aby OpenClaw nie sondował znanego wadliwego modelu podstawowego przy każdej wiadomości. OpenClaw okresowo ponownie sonduje skonfigurowane źródło i czyści automatyczne zastąpienie, gdy odzyska ono działanie; /new, /reset i sessions.reset natychmiast czyszczą zastąpienia pochodzące automatycznie.
• Odpowiedzi użytkownika ogłaszają przejścia awaryjne i przywrócenie po wyczyszczeniu przełączenia awaryjnego raz na zmianę stanu. Tury z utrwalonym przełączeniem awaryjnym nie powtarzają powiadomienia.
• /status pokazuje wybrany model oraz, gdy stan przełączenia awaryjnego się różni, aktywny model awaryjny i powód.
• Uzgadnianie sesji na żywo preferuje utrwalone zastąpienia sesji zamiast przestarzałych 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 przełączenia awaryjnego zawiedzie, moduł uruchamiający wycofuje tylko pola zastąpienia, które zapisał, i tylko jeśli nadal pasują do tego nieudanego kandydata.

​

Obserwowalność i podsumowania błędów

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

• niepowiązane limity szybkości ograniczone do modelu są ignorowane dla próbowanego łańcucha dostawca/model
• jeśli pozostała blokada jest pasującym limitem szybkości ograniczonym do modelu, OpenClaw zgłasza 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
• routowanie agents.defaults.imageModel