Аварійне перемикання моделей

OpenClaw обробляє збої у два етапи:

1. Ротація профілю автентифікації в межах поточного провайдера.
2. Перехід на резервну модель до наступної моделі в agents.defaults.model.fallbacks.

У цьому документі пояснено правила виконання та дані, на яких вони базуються.

Потік виконання

Для звичайного текстового запуску OpenClaw оцінює кандидатів у такому порядку:

Це навмисно вужче, ніж «зберегти та відновити всю сесію». 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" і вибрану вихідну модель перед повторною спробою. Це автоматичне перевизначення може продовжувати рухатися налаштованим ланцюжком резервних моделей без перевірки основної моделі для кожного повідомлення, але OpenClaw періодично знову перевіряє налаштоване джерело й очищає автоматичне перевизначення після його відновлення. /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-запуск суворим.

Інтервал автоматичної перевірки основної моделі для резервного переходу становить п’ять хвилин і не налаштовується. OpenClaw запам’ятовує останні перевірки для кожної сесії та основної моделі, щоб основна модель, яка зазнає збою, не перевірялася на кожному ході. OpenClaw надсилає видиме сповіщення, коли сесія переходить на резервну модель, і ще одне сповіщення, коли повертається до вибраної основної моделі; він не повторює сповіщення на кожному ході з фіксованою резервною моделлю.

Кеш пропуску збоїв автентифікації

За замовчуванням кожен новий хід зберігає наявну поведінку повторних спроб резервного переходу: OpenClaw знову спробує кожного налаштованого резервного кандидата, включно з неосновними кандидатами, які нещодавно зазнали збою з auth або auth_permanent.

Оператори, які хочуть приглушити такі повторні збої автентифікації, можуть увімкнути це за допомогою:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Коли це ввімкнено, OpenClaw записує в пам’яті, в межах сесії, маркер пропуску для неосновного резервного кандидата після збою класу автентифікації. Маркер ключується за ідентифікатором сесії, провайдером і моделлю. Основні кандидати ніколи не пропускаються, тож явний користувацький вибір моделі все одно показує реальну помилку автентифікації. Кеш є локальним для процесу й очищається після перезапуску Gateway.

Значення є TTL у мілісекундах. 0 або невстановлене значення вимикає кеш. Додатні значення обмежуються діапазоном від 1 секунди до 10 хвилин.

Видимі для користувача сповіщення про резервний перехід

Коли сесія переходить на автоматично вибрану резервну модель, OpenClaw надсилає сповіщення про стан у тій самій поверхні відповіді:

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

Коли пізніша перевірка успішна й сесія повертається до вибраної основної моделі, OpenClaw надсилає:

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

Ці сповіщення є операційними повідомленнями, а не вмістом асистента. Вони доставляються один раз для кожної зміни стану, зокрема для ходів лише з побічними ефектами, коли це можливо, але ходи з фіксованою резервною моделлю не повторюють їх. Доставка обходить звичайне приглушення відповіді джерелу, сповіщення не займає перший слот відповіді асистента для каналів із тредами, і воно виключається з text-to-speech та витягання commitment.

Сховище автентифікації (ключі + OAuth)

OpenClaw використовує профілі автентифікації і для API-ключів, і для токенів OAuth.

• Секрети та стан маршрутизації автентифікації під час виконання зберігаються в ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Конфігурація auth.profiles / auth.order є лише метаданими + маршрутизацією (без секретів).
• Застарілий файл OAuth лише для імпорту: ~/.openclaw/credentials/oauth.json (імпортується в сховище автентифікації окремого агента під час першого використання).
• Застарілі файли auth-profiles.json, auth-state.json і auth.json окремих агентів імпортуються командою openclaw doctor --fix.

Докладніше: OAuth

Типи облікових даних:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl для деяких провайдерів)

Ідентифікатори профілів

Входи OAuth створюють окремі профілі, щоб кілька облікових записів могли співіснувати.

• Типово: provider:default, коли email недоступний.
• OAuth з email: provider:<email> (наприклад, google-antigravity:user@gmail.com).

Профілі зберігаються в сховищі профілів автентифікації openclaw-agent.sqlite окремого агента.

Порядок ротації

Коли провайдер має кілька профілів, OpenClaw вибирає порядок так:

Якщо явний порядок не налаштовано, OpenClaw використовує порядок round-robin:

• Основний ключ: тип профілю (OAuth перед API-ключами).
• Вторинний ключ: usageStats.lastUsed (найстаріші спочатку, в межах кожного типу).
• Профілі в періоді очікування/вимкнені профілі переміщуються в кінець, упорядковані за найближчим завершенням періоду.

Фіксація сесії (дружня до кешу)

OpenClaw закріплює вибраний профіль автентифікації за сесією, щоб кеші провайдера залишалися прогрітими. Він не ротатує профіль для кожного запиту. Закріплений профіль повторно використовується, доки:

• сесію не скинуто (/new / /reset)
• не завершиться Compaction (лічильник Compaction збільшується)
• профіль перебуває в періоді очікування/вимкнений

Ручний вибір через /model …@<profileId> встановлює користувацьке перевизначення для цієї сесії та не ротатується автоматично до початку нової сесії.

Підписка OpenAI Codex плюс резервний API-ключ

Для агентних моделей OpenAI автентифікація та runtime є окремими. openai/gpt-* залишається на Codex harness, тоді як автентифікація може ротуватися між профілем підписки Codex і резервним API-ключем OpenAI.

Використовуйте auth.order.openai для порядку, видимого користувачу:

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

Використовуйте openai:* і для профілів OAuth ChatGPT/Codex, і для профілів API-ключів OpenAI. Коли підписка досягає ліміту використання Codex, OpenClaw записує точний час скидання, якщо Codex його надає, пробує наступний упорядкований профіль автентифікації та залишає запуск усередині Codex harness. Після проходження часу скидання профіль підписки знову придатний, і наступний автоматичний вибір може повернутися до нього.

Використовуйте закріплений користувачем профіль лише тоді, коли потрібно примусово використовувати один обліковий запис/ключ для цієї сесії. Закріплені користувачем профілі навмисно суворі й не перемикаються непомітно на інший профіль.

Періоди очікування

Коли профіль зазнає збою через помилки автентифікації/rate-limit (або timeout, схожий на rate limiting), OpenClaw позначає його як такий, що перебуває в періоді очікування, і переходить до наступного профілю.

Періоди охолодження використовують експоненційне відкладення:

• 1 хвилина
• 5 хвилин
• 25 хвилин
• 1 година (обмеження)

Стан зберігається в SQLite-стані автентифікації окремого агента в usageStats:

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

Вимкнення через білінг

Збої білінгу/кредитів (наприклад, "insufficient credits" / "credit balance too low") вважаються придатними для резервного перемикання, але зазвичай вони не є тимчасовими. Замість короткого періоду охолодження OpenClaw позначає профіль як вимкнений (із довшим відкладенням) і переходить до наступного профілю/провайдера.

Стан зберігається в SQLite-стані автентифікації окремого агента:

{  "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 дозволяє одну повторну спробу профілю автентифікації того самого провайдера, а потім без очікування перемикається на наступну налаштовану резервну модель. Сигнали зайнятості провайдера, такі як ModelNotReadyException, потрапляють у цей кошик перевантаження. Налаштуйте це за допомогою auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs і auth.cooldowns.rateLimitedProfileRotations.

Коли запуск починається з налаштованої основної моделі за замовчуванням, основної моделі Cron-завдання, основної моделі агента з явними резервними варіантами або автоматично вибраного перевизначення резервного варіанта, OpenClaw може пройти відповідний налаштований ланцюжок резервних варіантів. Основні моделі агентів без явних резервних варіантів і явні вибори користувача (наприклад, /model ollama/qwen3.5:27b, вибір моделі, sessions.patch або одноразові перевизначення провайдера/моделі CLI) є строгими: якщо цей провайдер/модель недоступні або зазнають збою до створення відповіді, OpenClaw повідомляє про збій замість того, щоб відповідати з непов’язаного резервного варіанта.

Правила ланцюжка кандидатів

OpenClaw будує список кандидатів із поточного запитаного provider/model плюс налаштованих резервних варіантів.

Які помилки просувають резервний перехід

Пропуск періоду охолодження і поведінка перевірки

Коли кожен профіль автентифікації для провайдера вже перебуває в періоді охолодження, OpenClaw не пропускає цього провайдера автоматично назавжди. Він ухвалює рішення для кожного кандидата:

Перевизначення сесії та живе перемикання моделі

Зміни моделі сесії є спільним станом. Активний runner, команда /model, оновлення Compaction/сесії та узгодження живої сесії читають або записують частини одного й того самого запису сесії.

Це означає, що повторні спроби резервного переходу мають координуватися з живим перемиканням моделі:

• Лише явні зміни моделі, ініційовані користувачем, позначають очікуване живе перемикання. Це включає /model, session_status(model=...) і sessions.patch.
• Системні зміни моделі, такі як ротація резервних варіантів, перевизначення Heartbeat або Compaction, самі по собі ніколи не позначають очікуване живе перемикання.
• Перевизначення моделі, ініційовані користувачем, вважаються точними виборами для політики резервного переходу, тому недоступний вибраний провайдер показується як збій, а не маскується agents.defaults.model.fallbacks.
• Перед початком повторної спроби резервного переходу runner відповіді зберігає вибрані поля перевизначення резервного варіанта в записі сесії.
• Автоматичні перевизначення резервного варіанта залишаються вибраними в наступних ходах, щоб OpenClaw не перевіряв відому несправну основну модель у кожному повідомленні. OpenClaw періодично знову перевіряє налаштоване джерело та очищає автоматичне перевизначення, коли воно відновлюється; /new, /reset і sessions.reset негайно очищають перевизначення з автоматичного джерела.
• Відповіді користувачу оголошують переходи до резервного варіанта та відновлення після очищення резервного варіанта один раз на зміну стану. Ходи з липким резервним варіантом не повторюють сповіщення.
• /status показує вибрану модель і, коли стан резервного переходу відрізняється, активну резервну модель і причину.
• Узгодження живої сесії надає перевагу збереженим перевизначенням сесії над застарілими полями моделі runtime.
• Якщо помилка живого перемикання вказує на пізнішого кандидата в активному ланцюжку резервних варіантів, OpenClaw переходить безпосередньо до цієї вибраної моделі замість того, щоб спершу проходити непов’язаних кандидатів.
• Якщо спроба резервного переходу зазнає збою, runner відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату.

Це запобігає класичній гонці:

Збережене перевизначення резервного варіанта закриває це вікно, а вузький відкат зберігає новіші ручні або runtime-зміни сесії недоторканими.

Спостережуваність і підсумки збоїв

runWithModelFallback(...) записує деталі кожної спроби, які живлять журнали та користувацькі повідомлення про період охолодження:

• спробуваний провайдер/модель
• причина (rate_limit, overloaded, billing, auth, model_not_found і подібні причини резервного перемикання)
• необов’язковий статус/код
• зрозумілий людині підсумок помилки

Структуровані журнали model_fallback_decision також містять плоскі поля fallbackStep*, коли кандидат зазнає збою, пропускається або пізніший резервний варіант успішний. Ці поля роблять спробу переходу явною (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), щоб експортери журналів і діагностики могли відтворити збій основної моделі навіть тоді, коли кінцевий резервний варіант також зазнає збою.

Коли всі кандидати зазнають збою, OpenClaw викидає FallbackSummaryError. Зовнішній runner відповіді може використати це, щоб побудувати конкретніше повідомлення, наприклад "all models are temporarily rate-limited", і включити найближче завершення періоду охолодження, коли воно відоме.

Цей підсумок періоду охолодження враховує модель:

• непов’язані обмеження частоти на рівні моделі ігноруються для спробуваного ланцюжка провайдер/модель
• якщо залишкове блокування є відповідним обмеженням частоти на рівні моделі, OpenClaw повідомляє останній відповідний час завершення, який усе ще блокує цю модель

Пов’язана конфігурація

Див. Конфігурація Gateway для:

• 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

Див. Моделі, щоб отримати ширший огляд вибору моделі та резервних варіантів.