Przełączanie awaryjne modelu

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

Przepływ w czasie wykonywania

• 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ć 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)

• 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).

• 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 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)

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

​

Subskrypcja OpenAI Codex plus zapasowy klucz API

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

​

Okresy wyciszenia

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

• 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

​

Reguły łańcucha kandydatów

​

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

​

Zachowanie pomijania odczekania kontra sondowania

​

Nadpisania sesji i przełączanie 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.

​

Obserwowalność i podsumowania awarii

• 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

• 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

• 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