Резервне перемикання моделі

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

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

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

Це навмисно вужче, ніж «зберегти й відновити весь сеанс». Виконавець відповіді зберігає лише ті поля вибору моделі, якими він керує для резервного перемикання: providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Це не дає невдалій повторній спробі резервного перемикання перезаписати новіші непов’язані зміни сеансу, як-от ручну зміну через /model або оновлення ротації сеансу, що відбулося під час виконання спроби.

Політика джерела вибору

Джерело вибору визначає, чи дозволено ланцюжок резервного перемикання:

• Налаштоване типове значення: agents.defaults.model.primary використовує agents.defaults.model.fallbacks.
• Основна модель агента: agents.list[].model є строгим вибором, якщо об’єкт моделі цього агента не містить власного списку fallbacks. Використовуйте fallbacks: [], щоб явно встановити строгу поведінку, або непорожній список, щоб увімкнути для цього агента резервне перемикання моделей.
• Автоматичне резервне перевизначення: під час виконання резервний механізм записує providerOverride, modelOverride, modelOverrideSource: "auto" і вибрану початкову модель перед повторною спробою. Це перевизначення продовжує рух налаштованим ланцюжком резервного перемикання, не перевіряючи основну модель для кожного повідомлення, але OpenClaw перевіряє налаштовану початкову модель кожні 5 хвилин (це не налаштовується) та скасовує перевизначення після її відновлення. /new, /reset і sessions.reset також скасовують автоматичні перевизначення. Запуски Heartbeat без явного heartbeat.model скасовують прямі автоматичні перевизначення, коли їхня початкова модель більше не відповідає поточному налаштованому типовому значенню.
• Користувацьке перевизначення сеансу: /model, засіб вибору моделі, session_status(model=...) і sessions.patch записують modelOverrideSource: "user". Це точний вибір для сеансу. Якщо вибраний постачальник або модель зазнає невдачі до створення відповіді, OpenClaw повідомляє про збій замість відповіді від непов’язаного налаштованого резервного варіанта.
• Застаріле перевизначення сеансу: старіші записи сеансів можуть містити modelOverride без modelOverrideSource. OpenClaw розглядає їх як користувацькі перевизначення, щоб явний старий вибір не було непомітно перетворено на резервну поведінку.
• Модель у корисному навантаженні Cron: payload.model / --model завдання cron є основною моделлю завдання, а не користувацьким перевизначенням сеансу. Вона використовує налаштовані резервні варіанти, якщо завдання не містить payload.fallbacks; payload.fallbacks: [] робить виконання cron строгим.

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

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

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

Щоб уникнути повторних помилок автентифікації, увімкніть:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

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

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

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

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

↪️ Резервне перемикання моделі: <fallback> (вибрано <primary>; <reason>)

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

↪️ Резервне перемикання моделі скасовано: <primary> (раніше <fallback>)

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

Зберігання даних автентифікації (ключі й 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 для деяких постачальників)
• type: "token" → статичний токен типу bearer, за потреби з терміном дії; OpenClaw не оновлює його (використовується для aws-sdk та інших режимів автентифікації через ланцюжок облікових даних)

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

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

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

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

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

Коли постачальник має кілька профілів, OpenClaw визначає порядок так:

Якщо явний порядок не налаштовано, OpenClaw використовує циклічний порядок:

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

Прив’язка до сеансу (зручна для кешування)

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

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

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

Передплата OpenAI Codex із резервним ключем API

Для агентних моделей OpenAI автентифікація та середовище виконання розділені. openai/gpt-* залишається в середовищі Codex, тоді як автентифікація може перемикатися між профілем передплати 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. Після настання часу скидання профіль передплати знову стає доступним, і наступний автоматичний вибір може повернутися до нього.

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

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

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

Звичайні періоди очікування (не пов’язані з оплатою чи постійним збоєм автентифікації) збільшуються залежно від кількості нещодавніх помилок профілю:

• 1-й збій: 30 секунд
• 2-й збій: 1 хвилина
• 3-й і наступні збої: 5 хвилин (максимум)

Лічильники скидаються після завершення вікна збоїв профілю (auth.cooldowns.failureWindowHours, за замовчуванням 24).

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

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

Вимкнення через оплату

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

Постійні збої автентифікації з високою достовірністю (відкликані або деактивовані ключі, деактивовані робочі простори) обробляються подібним шляхом вимкнення, але відновлюються значно швидше, ніж після збоїв оплати, оскільки під час інцидентів деякі провайдери можуть тимчасово повертати дані, схожі на помилки автентифікації.

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

{  "usageStats": {    "provider:profile": {      "disabledUntil": 1736178000000,      "disabledReason": "billing"    }  }}

Значення за замовчуванням (auth.cooldowns.*):

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

Перехід на резервну модель

Якщо всі профілі провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в agents.defaults.model.fallbacks. Це стосується збоїв автентифікації, обмежень частоти запитів і тайм-аутів, після яких вичерпано перемикання профілів (інші помилки не спричиняють переходу до резервної моделі). Помилки провайдера, що не містять достатньо подробиць, усе одно точно позначаються в стані резервного переходу: empty_response означає, що провайдер не повернув придатного повідомлення або стану, no_error_details означає, що провайдер явно повернув Unknown error (no error details in response), а unclassified означає, що OpenClaw зберіг необроблений попередній перегляд, але жоден класифікатор іще не знайшов відповідності.

Сигнали зайнятості провайдера, як-от ModelNotReadyException, потрапляють до категорії перевантаження та дотримуються тієї самої політики: одне перемикання профілю, а потім перехід до резервної моделі, як і для обмежень частоти запитів (див. таблицю значень за замовчуванням вище).

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

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

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

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

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

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

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

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

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

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

Це запобігає класичному стану гонитви:

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

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

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

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

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

Коли всі кандидати завершуються помилкою, OpenClaw створює виняток FallbackSummaryError. Зовнішній засіб виконання відповіді може використати його, щоб сформувати точніше повідомлення, наприклад «для всіх моделей тимчасово перевищено ліміт запитів», і вказати найближчий час завершення періоду очікування, якщо він відомий.

Це зведення про період очікування враховує модель:

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

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

Див. конфігурацію Gateway, щоб дізнатися про:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• маршрутизацію agents.defaults.imageModel

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