--- read_when: - Діагностика ротації профілів автентифікації, періодів очікування або поведінки резервного перемикання моделі - Оновлення правил відмовостійкого перемикання для профілів автентифікації або моделей - Розуміння того, як перевизначення моделі сеансу взаємодіють із резервними повторними спробами sidebarTitle: Model failover summary: Як OpenClaw ротує профілі автентифікації та виконує резервне перемикання між моделями title: Аварійне перемикання моделі x-i18n: generated_at: "2026-05-11T20:32:31Z" model: gpt-5.5 provider: openai source_hash: d3983218c9de67bbd100eab655c319ed97350d43e00c826febd47cb014cbe6cf source_path: concepts/model-failover.md workflow: 16 --- OpenClaw обробляє збої у два етапи: 1. **Ротація профілів автентифікації** в межах поточного провайдера. 2. **Резервне перемикання моделі** на наступну модель у `agents.defaults.model.fallbacks`. У цьому документі пояснено правила виконання та дані, на яких вони базуються. ## Потік виконання Для звичайного текстового запуску OpenClaw оцінює кандидатів у такому порядку: Визначає активну модель сеансу й налаштування профілю автентифікації. Будує ланцюжок моделей-кандидатів із поточного вибору моделі та політики резервного перемикання для джерела цього вибору. Налаштовані значення за замовчуванням, основні моделі завдань cron і автоматично вибрані резервні моделі можуть використовувати налаштовані резервні варіанти; явні вибори користувача в сеансі є строгими. Пробує поточного провайдера з правилами ротації та cooldown профілів автентифікації. Якщо цей провайдер вичерпано через помилку, що заслуговує на failover, переходить до наступної моделі-кандидата. Зберігає вибране резервне перевизначення до початку повторної спроби, щоб інші читачі сеансу бачили того самого провайдера/модель, які runner збирається використати. Збережене перевизначення моделі позначається як `modelOverrideSource: "auto"`. Якщо резервний кандидат зазнає невдачі, відкочує лише поля перевизначення сеансу, що належать резервному перемиканню, коли вони все ще відповідають цьому невдалому кандидату. Якщо всі кандидати зазнають невдачі, кидає `FallbackSummaryError` з деталями кожної спроби та найранішим завершенням cooldown, якщо воно відоме. Це навмисно вужче, ніж «зберегти й відновити весь сеанс». Reply runner зберігає лише ті поля вибору моделі, якими він володіє для резервного перемикання: - `providerOverride` - `modelOverride` - `modelOverrideSource` - `authProfileOverride` - `authProfileOverrideSource` - `authProfileOverrideCompactionCount` Це запобігає тому, щоб невдала повторна спроба резервного перемикання перезаписала новіші непов’язані мутації сеансу, як-от ручні зміни `/model` або оновлення ротації сеансу, що сталися під час виконання спроби. ## Політика джерела вибору OpenClaw відокремлює вибраного провайдера/модель від причини вибору. Це джерело керує тим, чи дозволено ланцюжок резервного перемикання: - **Налаштоване значення за замовчуванням**: `agents.defaults.model.primary` використовує `agents.defaults.model.fallbacks`. - **Основна модель агента**: `agents.list[].model` є строгим, якщо об’єкт моделі цього агента не містить власних `fallbacks`. Використовуйте `fallbacks: []`, щоб зробити строгу поведінку явною, або надайте непорожній список, щоб увімкнути для цього агента резервне перемикання моделей. - **Автоматичне резервне перевизначення**: під час виконання резервне перемикання записує `providerOverride`, `modelOverride`, `modelOverrideSource: "auto"` і вибрану початкову модель перед повторною спробою. Це автоматичне перевизначення може продовжувати проходити налаштований ланцюжок резервного перемикання та очищується командами `/new`, `/reset` і `sessions.reset`. Запуски Heartbeat без явного `heartbeat.model` також очищують пряме автоматичне перевизначення, коли його походження більше не відповідає поточному налаштованому значенню за замовчуванням. - **Користувацьке перевизначення сеансу**: `/model`, вибір моделі, `session_status(model=...)` і `sessions.patch` записують `modelOverrideSource: "user"`. Це точний вибір сеансу. Якщо вибраний провайдер/модель зазнає невдачі до створення відповіді, OpenClaw повідомляє про збій замість відповіді з непов’язаного налаштованого резервного варіанта. - **Застаріле перевизначення сеансу**: старіші записи сеансу можуть мати `modelOverride` без `modelOverrideSource`. OpenClaw трактує їх як користувацькі перевизначення, щоб явний старий вибір не було непомітно перетворено на поведінку резервного перемикання. - **Модель у payload Cron**: `payload.model` / `--model` завдання cron є основною моделлю завдання, а не користувацьким перевизначенням сеансу. Вона використовує налаштовані резервні варіанти, якщо завдання не надає `payload.fallbacks`; `payload.fallbacks: []` робить запуск cron строгим. ## Зберігання автентифікації (ключі + OAuth) OpenClaw використовує **профілі автентифікації** як для ключів API, так і для токенів OAuth. - Секрети зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (застаріле: `~/.openclaw/agent/auth-profiles.json`). - Стан маршрутизації автентифікації під час виконання зберігається в `~/.openclaw/agents//agent/auth-state.json`. - Конфігурація `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів). - Застарілий файл OAuth лише для імпорту: `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання). Докладніше: [OAuth](/uk/concepts/oauth) Типи облікових даних: - `type: "api_key"` → `{ provider, key }` - `type: "oauth"` → `{ provider, access, refresh, expires, email? }` (+ `projectId`/`enterpriseUrl` для деяких провайдерів) ## Ідентифікатори профілів Входи OAuth створюють окремі профілі, щоб кілька облікових записів могли співіснувати. - За замовчуванням: `provider:default`, коли email недоступний. - OAuth з email: `provider:` (наприклад, `google-antigravity:user@gmail.com`). Профілі зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` у `profiles`. ## Порядок ротації Коли провайдер має кілька профілів, OpenClaw вибирає порядок так: `auth.order[provider]` (якщо встановлено). `auth.profiles`, відфільтровані за провайдером. Записи в `auth-profiles.json` для провайдера. Якщо явний порядок не налаштовано, OpenClaw використовує циклічний порядок: - **Основний ключ:** тип профілю (**OAuth перед ключами API**). - **Вторинний ключ:** `usageStats.lastUsed` (найстаріші першими, у межах кожного типу). - **Профілі в cooldown або вимкнені** переміщуються в кінець, упорядковані за найранішим завершенням. ### Закріплення сеансу (зручне для кешування) OpenClaw **закріплює вибраний профіль автентифікації за сеансом**, щоб кеші провайдерів залишалися прогрітими. Він **не** перемикає його під час кожного запиту. Закріплений профіль повторно використовується, доки: - сеанс не буде скинуто (`/new` / `/reset`) - не завершиться Compaction (лічильник Compaction збільшиться) - профіль не перебуває в cooldown/вимкненому стані Ручний вибір через `/model …@` установлює **перевизначення користувача** для цього сеансу й не перемикається автоматично, доки не почнеться новий сеанс. Автоматично закріплені профілі (вибрані маршрутизатором сеансу) розглядаються як **перевага**: їх пробують першими, але OpenClaw може перейти на інший профіль у разі обмежень частоти запитів або таймаутів. Коли початковий профіль знову стає доступним, нові запуски можуть знову віддавати йому перевагу без зміни вибраної моделі чи runtime. Закріплені користувачем профілі залишаються прив’язаними до цього профілю; якщо він завершується помилкою, а резервні моделі налаштовані, OpenClaw переходить до наступної моделі замість перемикання профілів. ### Передплата OpenAI Codex плюс резервний API-ключ Для агентських моделей OpenAI автентифікація й runtime розділені. `openai/gpt-*` залишається на Codex harness, тоді як автентифікація може перемикатися між профілем передплати Codex і резервним API-ключем OpenAI. Використовуйте `auth.order.openai` для порядку, видимого користувачу: ```json5 { auth: { order: { openai: ["openai-codex:user@example.com", "openai:api-key-backup"], }, }, } ``` Наявні профілі передплати Codex усе ще можуть використовувати застарілий ідентифікатор профілю `openai-codex:*`. Упорядкована резервна копія API-ключа може бути звичайним профілем API-ключа `openai:*`. Коли передплата досягає ліміту використання Codex, OpenClaw записує точний час скидання, якщо Codex його надає, пробує наступний упорядкований профіль автентифікації та зберігає запуск усередині Codex harness. Після того як час скидання минув, профіль передплати знову стає придатним, і наступний автоматичний вибір може повернутися до нього. Використовуйте закріплений користувачем профіль лише тоді, коли потрібно примусово використовувати один обліковий запис або ключ для цього сеансу. Закріплені користувачем профілі навмисно суворі й не перемикаються непомітно на інший профіль. ## Cooldown-и Коли профіль зазнає помилки через проблеми автентифікації чи обмеження частоти запитів (або таймаут, схожий на обмеження частоти), OpenClaw позначає його як такий, що перебуває в cooldown, і переходить до наступного профілю. Цей кошик обмеження частоти ширший за звичайний `429`: він також містить повідомлення провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted`, а також періодичні ліміти вікна використання, як-от `weekly/monthly limit reached`. Помилки формату або некоректного запиту зазвичай є термінальними, бо повторна спроба з тим самим payload завершиться так само, тому OpenClaw показує їх замість перемикання профілів автентифікації. Відомі шляхи повторної спроби з виправленням можуть явно вмикати таку поведінку: наприклад, помилки перевірки ID виклику інструмента Cloud Code Assist очищаються й повторюються один раз через політику `allowFormatRetry`. OpenAI-сумісні помилки причини зупинки, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали таймауту або failover. Узагальнений серверний текст також може потрапити до цього кошика таймаутів, коли джерело відповідає відомому тимчасовому шаблону. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається вартим failover для кожного провайдера, бо pi-ai видає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних деталей. JSON payload-и `api_error` з тимчасовим серверним текстом, як-от `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також вважаються таймаутами, вартими failover. Специфічний для OpenRouter узагальнений текст upstream, як-от просте `Provider returned error`, вважається таймаутом лише тоді, коли контекст провайдера справді є OpenRouter. Узагальнений внутрішній текст резервного шляху, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам собою не запускає failover. Деякі SDK провайдерів інакше можуть очікувати протягом довгого вікна `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на основі Stainless, як-от Anthropic і OpenAI, OpenClaw за замовчуванням обмежує SDK-внутрішні очікування `retry-after-ms` / `retry-after` до 60 секунд і негайно показує довші retryable-відповіді, щоб цей шлях failover міг виконатися. Налаштуйте або вимкніть обмеження за допомогою `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry). Cooldown-и обмеження частоти також можуть бути обмежені моделлю: - OpenClaw записує `cooldownModel` для помилок обмеження частоти, коли ідентифікатор моделі, що завершилася помилкою, відомий. - Споріднену модель того самого провайдера все ще можна спробувати, коли cooldown обмежено іншою моделлю. - Вікна billing/вимкнення все одно блокують увесь профіль для всіх моделей. Cooldown-и використовують експоненційний backoff: - 1 хвилина - 5 хвилин - 25 хвилин - 1 година (верхня межа) Стан зберігається в `auth-state.json` у `usageStats`: ```json { "usageStats": { "provider:profile": { "lastUsed": 1736160000000, "cooldownUntil": 1736160600000, "errorCount": 2 } } } ``` ## Вимкнення через billing Помилки billing/кредитів (наприклад, "insufficient credits" / "credit balance too low") вважаються вартими failover, але зазвичай вони не тимчасові. Замість короткого cooldown OpenClaw позначає профіль як **вимкнений** (із довшим backoff) і переходить до наступного профілю або провайдера. Не кожна відповідь, схожа на billing, є `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний текст billing у відповідній лінії навіть тоді, коли провайдер натомість повертає `401` або `403`, але специфічні для провайдера зіставлення залишаються обмеженими тим провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`). Тим часом тимчасові помилки вікна використання `402` і лімітів витрат організації/робочого простору класифікуються як `rate_limit`, коли повідомлення виглядає придатним до повторної спроби (наприклад `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на короткому шляху періоду очікування/перемикання на резервний варіант замість довгого шляху вимкнення через білінг. Стан зберігається в `auth-state.json`: ```json { "usageStats": { "provider:profile": { "disabledUntil": 1736178000000, "disabledReason": "billing" } } } ``` Типові значення: - Відкладення через білінг починається з **5 годин**, подвоюється після кожного збою білінгу й обмежується **24 годинами**. - Лічильники відкладення скидаються, якщо профіль не зазнавав збою протягом **24 годин** (налаштовується). - Повторні спроби при перевантаженні дозволяють **1 ротацію профілю того самого провайдера** перед переходом до резервної моделі. - Повторні спроби при перевантаженні типово використовують відкладення **0 мс**. ## Резервний перехід моделі Якщо всі профілі для провайдера зазнають збою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це стосується збоїв автентифікації, лімітів частоти та таймаутів, які вичерпали ротацію профілів (інші помилки не просувають резервний перехід). Помилки провайдера, які не розкривають достатньо деталей, усе одно точно позначаються в стані резервного переходу: `empty_response` означає, що провайдер не повернув придатного повідомлення або статусу, `no_error_details` означає, що провайдер явно повернув `Unknown error (no error details in response)`, а `unclassified` означає, що OpenClaw зберіг сирий попередній перегляд, але жоден класифікатор ще його не зіставив. Помилки перевантаження та ліміту частоти обробляються агресивніше, ніж періоди очікування білінгу. Типово OpenClaw дозволяє одну повторну спробу з auth-профілем того самого провайдера, а потім без очікування перемикається на наступну налаштовану резервну модель. Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють у цю групу перевантаження. Налаштуйте це за допомогою `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`. Коли запуск починається з налаштованої типової основної моделі, основної моделі cron-завдання, основної моделі агента з явними резервними варіантами або автоматично вибраного перевизначення резервного варіанта, OpenClaw може пройти відповідний налаштований ланцюг резервних моделей. Основні моделі агентів без явних резервних варіантів і явні вибори користувача (наприклад `/model ollama/qwen3.5:27b`, вибір моделі, `sessions.patch` або одноразові CLI-перевизначення провайдера/моделі) є строгими: якщо цей провайдер/модель недоступний або зазнає збою до створення відповіді, OpenClaw повідомляє про збій замість відповіді від непов’язаної резервної моделі. ### Правила ланцюга кандидатів OpenClaw будує список кандидатів із поточного запитаного `provider/model` плюс налаштовані резервні варіанти. - Запитана модель завжди перша. - Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за allowlist моделей. Вони трактуються як явний намір оператора. - Якщо поточний запуск уже перебуває на налаштованому резервному варіанті в тій самій родині провайдерів, OpenClaw продовжує використовувати повний налаштований ланцюг. - Коли явне перевизначення резервних варіантів не надано, налаштовані резервні варіанти пробуються перед налаштованою основною моделлю, навіть якщо запитана модель використовує іншого провайдера. - Коли runner резервного переходу не отримує явного перевизначення резервних варіантів, налаштована основна модель додається в кінець, щоб ланцюг міг повернутися до звичайного типового варіанта після вичерпання попередніх кандидатів. - Коли викликач надає `fallbacksOverride`, runner використовує саме запитану модель плюс цей список перевизначення. Порожній список вимикає резервний перехід моделі й запобігає додаванню налаштованої основної моделі як прихованої цілі повторної спроби. ### Які помилки просувають резервний перехід - збої автентифікації - ліміти частоти й вичерпання періодів очікування - помилки перевантаження/зайнятості провайдера - помилки перемикання, схожі на таймаут - вимкнення через білінг - `LiveSessionModelSwitchError`, яка нормалізується в шлях перемикання на резервний варіант, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб - інші нерозпізнані помилки, коли ще залишаються кандидати - явні переривання, які не схожі на таймаут/перемикання - помилки переповнення контексту, які мають залишатися всередині логіки Compaction/повторної спроби (наприклад `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `The input is too long for the model` або `ollama error: context length exceeded`) - фінальна невідома помилка, коли кандидатів більше немає ### Пропуск періоду очікування порівняно з поведінкою проби Коли всі auth-профілі для провайдера вже перебувають у періоді очікування, OpenClaw не пропускає цього провайдера автоматично назавжди. Він ухвалює рішення для кожного кандидата: - Постійні збої автентифікації негайно пропускають увесь провайдер. - Вимкнення через білінг зазвичай пропускаються, але основного кандидата все одно можна пробувати з обмеженням частоти, щоб відновлення було можливим без перезапуску. - Основного кандидата можна пробувати близько до завершення періоду очікування, з обмеженням частоти для кожного провайдера. - Однорівневі резервні варіанти того самого провайдера можна пробувати попри період очікування, коли збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо актуально, коли ліміт частоти діє на рівні моделі, а споріднена модель може відновитися негайно. - Тимчасові проби періоду очікування обмежені однією на провайдера за один запуск резервного переходу, щоб один провайдер не затримував міжпровайдерний резервний перехід. ## Перевизначення сесії та живе перемикання моделі Зміни моделі сесії є спільним станом. Активний runner, команда `/model`, оновлення Compaction/сесії та узгодження live-сесії читають або записують частини одного й того самого запису сесії. Це означає, що повторні спроби резервного переходу мають координуватися з живим перемиканням моделі: - Лише явні зміни моделі, ініційовані користувачем, позначають очікуване live-перемикання. Це включає `/model`, `session_status(model=...)` і `sessions.patch`. - Зміни моделі, ініційовані системою, як-от ротація резервних варіантів, перевизначення Heartbeat або Compaction, самі по собі ніколи не позначають очікуване live-перемикання. - Перевизначення моделі, ініційовані користувачем, трактуються як точні вибори для політики резервного переходу, тому недоступний вибраний провайдер показується як збій, а не маскується `agents.defaults.model.fallbacks`. - Перед початком повторної спроби резервного переходу reply runner зберігає вибрані поля перевизначення резервного варіанта в записі сесії. - Автоматичні перевизначення резервного варіанта залишаються вибраними в наступних ходах, щоб OpenClaw не пробував завідомо несправну основну модель у кожному повідомленні. `/new`, `/reset` і `sessions.reset` очищають автоматично отримані перевизначення та повертають сесію до налаштованого типового варіанта. - `/status` показує вибрану модель і, коли стан резервного переходу відрізняється, активну резервну модель і причину. - Узгодження live-сесії надає перевагу збереженим перевизначенням сесії над застарілими runtime-полями моделі. - Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюгу резервного переходу, OpenClaw переходить безпосередньо до цієї вибраної моделі, а не спершу обходить непов’язаних кандидатів. - Якщо спроба резервного переходу зазнає збою, runner відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату. Це запобігає класичній гонці: Вибрана основна модель зазнає збою. Резервний кандидат вибирається в пам’яті. Сховище сесії все ще відображає стару основну модель. Узгодження live-сесії читає застарілий стан сесії. Повторна спроба повертається до старої моделі до початку спроби резервного переходу. Збережене перевизначення резервного варіанта закриває це вікно, а вузький відкат залишає новіші ручні або runtime-зміни сесії недоторканими. ## Спостережуваність і підсумки збоїв `runWithModelFallback(...)` записує деталі кожної спроби, які живлять журнали та орієнтовані на користувача повідомлення про періоди очікування: - провайдер/модель, які пробувалися - причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` і подібні причини перемикання) - необов’язковий статус/код - зрозумілий для людини підсумок помилки Структуровані журнали `model_fallback_decision` також містять плоскі поля `fallbackStep*`, коли кандидат зазнає збою, пропускається або пізніший резервний варіант успішний. Ці поля роблять спробу переходу явною (`fallbackStepFromModel`, `fallbackStepToModel`, `fallbackStepFromFailureReason`, `fallbackStepFromFailureDetail`, `fallbackStepFinalOutcome`), щоб експортери журналів і діагностики могли реконструювати збій основної моделі навіть тоді, коли кінцевий резервний варіант також зазнає збою. Коли всі кандидати зазнають збою, OpenClaw викидає `FallbackSummaryError`. Зовнішній reply runner може використати це, щоб побудувати конкретніше повідомлення, наприклад "усі моделі тимчасово обмежені лімітом частоти", і включити найраніший час завершення періоду очікування, якщо він відомий. Цей підсумок періоду очікування враховує модель: - непов’язані ліміти частоти на рівні моделі ігноруються для ланцюга провайдер/модель, який пробувався - якщо залишкове блокування є відповідним лімітом частоти на рівні моделі, OpenClaw повідомляє останній відповідний час завершення, який усе ще блокує цю модель ## Пов’язана конфігурація Див. [конфігурацію Gateway](/uk/gateway/configuration) для: - `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` - маршрутизації `agents.defaults.imageModel` Див. [Моделі](/uk/concepts/models) для ширшого огляду вибору моделей і резервного переходу.