---
read_when:
    - Діагностика ротації профілів автентифікації, cooldown і поведінки fallback моделей
    - Оновлення правил failover для профілів автентифікації або моделей
    - Розуміння того, як перевизначення моделі сесії взаємодіють із повторними спробами fallback
summary: Як OpenClaw ротує профілі автентифікації та виконує fallback між моделями
title: Failover моделей
x-i18n:
    generated_at: "2026-04-23T20:50:29Z"
    model: gpt-5.4
    provider: openai
    source_hash: 8921c9edd4699d8c623229cd3c82a92768d720fa9711862c270d6edb665841af
    source_path: concepts/model-failover.md
    workflow: 15
---

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

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

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

## Потік runtime

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

1. Поточна вибрана модель сесії.
2. Налаштовані `agents.defaults.model.fallbacks` у вказаному порядку.
3. Налаштована основна модель наприкінці, якщо запуск почався з override.

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

Послідовність на високому рівні:

1. Розв’язати активну модель сесії та налаштування профілю автентифікації.
2. Побудувати ланцюжок кандидатів моделей.
3. Спробувати поточного провайдера з правилами ротації/cooldown профілів автентифікації.
4. Якщо цей провайдер вичерпано через помилку, що підходить для failover, перейти до наступного
   кандидата моделі.
5. Зберегти вибраний fallback override до початку повторної спроби, щоб інші читачі
   сесії бачили того самого провайдера/модель, яких runner збирається використати.
6. Якщо fallback-кандидат завершується помилкою, відкотити лише поля override сесії, що належать fallback,
   якщо вони все ще відповідають цьому кандидату, що завершився помилкою.
7. Якщо всі кандидати завершилися помилкою, викинути `FallbackSummaryError` з деталями
   по кожній спробі та найближчим часом завершення cooldown, якщо він відомий.

Це навмисно вужче, ніж "зберегти й відновити всю сесію". Runner
відповіді зберігає лише поля вибору моделі, якими він володіє для fallback:

- `providerOverride`
- `modelOverride`
- `authProfileOverride`
- `authProfileOverrideSource`
- `authProfileOverrideCompactionCount`

Це не дозволяє невдалому повторному запуску через fallback перезаписати новіші, не пов’язані мутації сесії,
як-от ручні зміни `/model` або оновлення ротації сесії, що відбулися під час виконання спроби.

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

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

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

Докладніше: [/concepts/oauth](/uk/concepts/oauth)

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

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

## ID профілів

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

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

Профілі зберігаються в `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` у розділі `profiles`.

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

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

1. **Явна конфігурація**: `auth.order[provider]` (якщо задано).
2. **Налаштовані профілі**: `auth.profiles`, відфільтровані за провайдером.
3. **Збережені профілі**: записи в `auth-profiles.json` для провайдера.

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

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

### Липкість сесії (дружня до кешу)

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

- сесію не буде скинуто (`/new` / `/reset`)
- не завершиться Compaction (лічильник Compaction збільшиться)
- профіль не опиниться в cooldown/disabled

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

Автоматично закріплені профілі (вибрані маршрутизатором сесії) розглядаються як **перевага**:
їх пробують першими, але OpenClaw може переключитися на інший профіль за rate limit/timeouts.
Профілі, закріплені користувачем, залишаються жорстко прив’язаними до цього профілю; якщо він завершується помилкою і налаштовано fallback моделей,
OpenClaw переходить до наступної моделі замість перемикання профілів.

### Чому OAuth може "виглядати втраченим"

Якщо для того самого провайдера у вас є і OAuth-профіль, і профіль API-ключа, round‑robin може перемикатися між ними між повідомленнями, якщо немає закріплення. Щоб примусово використовувати один профіль:

- Закріпіть через `auth.order[provider] = ["provider:profileId"]`, або
- Використайте override для конкретної сесії через `/model …` з override профілю (якщо це підтримується вашим UI/чат-поверхнею).

## Cooldown

Коли профіль завершується помилкою через автентифікацію/rate limit (або timeout, що
схожий на rate limiting), OpenClaw позначає його як такий, що перебуває в cooldown, і переходить до наступного профілю.
Цей кошик rate limit ширший, ніж просто `429`: він також включає повідомлення
провайдерів на кшталт `Too many concurrent requests`, `ThrottlingException`,
`concurrency limit reached`, `workers_ai ... quota limit exceeded`,
`throttled`, `resource exhausted` і ліміти періодичних вікон використання на кшталт
`weekly/monthly limit reached`.
Помилки формату/невалідного запиту (наприклад, помилки перевірки ID виклику інструмента Cloud Code Assist)
вважаються придатними для failover і використовують ті самі cooldown.
Помилки stop reason у стилі OpenAI-compatible, як-от `Unhandled stop reason: error`,
`stop reason: error` і `reason: error`, класифікуються як timeout/failover-
сигнали.
Загальний текст помилок сервера на рівні провайдера також може потрапляти до цього кошика timeout, коли
джерело відповідає відомому тимчасовому шаблону. Наприклад, для Anthropic простий текст
`An unknown error occurred` і JSON-payload `api_error` з тимчасовим серверним
текстом, як-от `internal server error`, `unknown error, 520`, `upstream error`,
або `backend error`, вважаються придатними для failover timeout. Специфічний для OpenRouter
загальний текст upstream на кшталт простого `Provider returned error` також вважається
timeout лише тоді, коли контекст провайдера справді є OpenRouter. Загальний внутрішній
fallback-текст на кшталт `LLM request failed with an unknown error.` залишається
консервативним і сам по собі не запускає failover.

Деякі SDK провайдерів інакше можуть заснути на довге вікно `Retry-After`, перш ніж
повернути керування OpenClaw. Для SDK на базі Stainless, як-от Anthropic і
OpenAI, OpenClaw типово обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60
секунд і негайно показує довші відповіді, які можна повторити, щоб цей шлях
failover міг спрацювати. Налаштувати або вимкнути обмеження можна через
`OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [/concepts/retry](/uk/concepts/retry).

Cooldown rate limit також можуть бути прив’язані до моделі:

- OpenClaw записує `cooldownModel` для збоїв через rate limit, коли відомий id
  моделі, що завершилася помилкою.
- Сусідню модель на тому самому провайдері все ще можна спробувати, якщо cooldown
  прив’язано до іншої моделі.
- Вікна billing/disabled, як і раніше, блокують увесь профіль для всіх моделей.

Cooldown використовують експоненційний backoff:

- 1 хвилина
- 5 хвилин
- 25 хвилин
- 1 година (максимум)

Стан зберігається в `auth-state.json` у розділі `usageStats`:

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

## Вимкнення через billing

Помилки billing/credit (наприклад, “insufficient credits” / “credit balance too low”) вважаються придатними для failover, але зазвичай вони не є тимчасовими. Замість короткого cooldown OpenClaw позначає профіль як **disabled** (з довшим backoff) і переходить до наступного профілю/провайдера.

Не кожна відповідь, схожа на billing, має код `402`, і не кожен HTTP `402` потрапляє
сюди. OpenClaw залишає явний текст billing у гілці billing навіть тоді, коли
провайдер повертає натомість `401` або `403`, але специфічні для провайдера matcher-и залишаються
обмеженими провайдером, якому вони належать (наприклад OpenRouter `403 Key limit
exceeded`). Тим часом тимчасові вікна використання `402` і
помилки лімітів витрат організації/робочого простору класифікуються як `rate_limit`, коли
повідомлення виглядає придатним для повтору (наприклад `weekly usage limit exhausted`, `daily
limit reached, resets tomorrow` або `organization spending limit exceeded`).
Вони залишаються на шляху короткого cooldown/failover замість довгого
шляху вимкнення через billing.

Стан зберігається в `auth-state.json`:

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

Типові значення:

- Backoff для billing починається з **5 годин**, подвоюється при кожному збої billing і обмежується **24 годинами**.
- Лічильники backoff скидаються, якщо профіль не зазнавав помилок протягом **24 годин** (можна налаштувати).
- Повторні спроби для overloaded дозволяють **1 ротацію профілю в межах того самого провайдера** перед fallback моделі.
- Повторні спроби для overloaded використовують backoff **0 мс** за замовчуванням.

## Failover моделі

Якщо всі профілі для провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в
`agents.defaults.model.fallbacks`. Це стосується збоїв автентифікації, rate limit і
timeout, які вичерпали ротацію профілів (інші помилки не просувають fallback).

Помилки overloaded і rate limit обробляються агресивніше, ніж billing
cooldown. Типово OpenClaw дозволяє одну повторну спробу з профілем автентифікації в межах того самого провайдера,
а потім без очікування перемикається на наступну налаштовану fallback-модель.
Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють у цей кошик overloaded.
Це можна налаштувати через `auth.cooldowns.overloadedProfileRotations`,
`auth.cooldowns.overloadedBackoffMs` і
`auth.cooldowns.rateLimitedProfileRotations`.

Коли запуск починається з override моделі (hooks або CLI), fallback усе одно завершуються на
`agents.defaults.model.primary` після спроб усіх налаштованих fallback.

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

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

Правила:

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

### Які помилки просувають fallback

Failover моделі продовжується для:

- збоїв автентифікації
- rate limit і вичерпання cooldown
- помилок overloaded/provider-busy
- помилок failover, схожих на timeout
- вимкнень через billing
- `LiveSessionModelSwitchError`, який нормалізується в шлях failover, щоб
  застаріла збережена модель не створювала зовнішній цикл повторних спроб
- інших нерозпізнаних помилок, коли ще залишаються кандидати

Failover моделі не продовжується для:

- явних переривань, які не схожі на timeout/failover
- помилок переповнення контексту, які мають залишатися в логіці compaction/retry
  (наприклад `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`)
- фінальної невідомої помилки, коли кандидатів більше не залишилося

### Поведінка пропуску cooldown проти probe

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

- Постійні збої автентифікації одразу пропускають увесь провайдер.
- Вимкнення через billing зазвичай пропускаються, але primary-кандидат усе ще може бути перевірений
  із throttle, щоб відновлення було можливим без перезапуску.
- Primary-кандидат може бути перевірений ближче до завершення cooldown із throttle
  на рівні провайдера.
- Сусідні fallback у межах того самого провайдера можна пробувати попри cooldown, коли
  збій виглядає тимчасовим (`rate_limit`, `overloaded` або unknown). Це
  особливо важливо, коли rate limit прив’язаний до моделі, а сусідня модель може
  все ще відновитися негайно.
- Тимчасові probe cooldown обмежуються одним на провайдера за один запуск fallback, щоб
  один провайдер не затримував fallback між різними провайдерами.

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

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

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

- Лише явні зміни моделі, ініційовані користувачем, позначають очікуване live-перемикання. Це
  включає `/model`, `session_status(model=...)` і `sessions.patch`.
- Зміни моделі, ініційовані системою, як-от ротація fallback, Heartbeat override
  або Compaction, ніколи самі по собі не позначають очікуване live-перемикання.
- Перед початком повторної спроби fallback runner відповіді зберігає вибрані
  поля fallback override у запис сесії.
- Узгодження live session віддає перевагу збереженим override сесії над застарілими
  полями моделі runtime.
- Якщо спроба fallback завершується помилкою, runner відкочує лише ті поля override,
  які він записав, і лише якщо вони все ще відповідають цьому кандидату, що завершився помилкою.

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

1. Primary завершується помилкою.
2. Fallback-кандидат вибирається в пам’яті.
3. Сховище сесії все ще вказує стару primary.
4. Узгодження live session читає застарілий стан сесії.
5. Повторну спробу повертає назад до старої моделі до того, як
   почнеться спроба fallback.

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

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

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

- спробуваний provider/model
- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та
  подібні причини failover)
- необов’язковий status/code
- зрозумілий для людини підсумок помилки

Коли всі кандидати завершуються помилкою, OpenClaw викидає `FallbackSummaryError`. Зовнішній
runner відповіді може використати це, щоб побудувати точніше повідомлення на кшталт "усі моделі
тимчасово обмежені rate limit" і включити найближчий час завершення cooldown, якщо він відомий.

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

- не пов’язані rate limit, прив’язані до інших моделей, ігноруються для
  спробуваного ланцюжка provider/model
- якщо залишкове блокування — це відповідний rate limit, прив’язаний до моделі, 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) для ширшого огляду вибору моделей і fallback.
