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

# Резервний перехід моделей

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

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

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

## Потік виконання під час роботи

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

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

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

Послідовність верхнього рівня:

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

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

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

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

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

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

- Секрети зберігаються в `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (застарілий шлях: `~/.openclaw/agent/auth-profiles.json`).
- Стан маршрутизації автентифікації під час роботи зберігається в `~/.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` (найдавніші першими в межах кожного типу).
- **Профілі в охолодженні/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим завершенням терміну дії.

### Закріплення сеансу (сприятливе для кешу)

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

- сеанс не скинуто (`/new` / `/reset`)
- не завершиться компакція (лічильник компакції збільшується)
- профіль не перебуває в охолодженні/не вимкнений

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

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

### Чому OAuth може «здаватися втраченим»

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

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

## Періоди охолодження

Коли профіль завершується помилкою через помилки автентифікації/ліміту швидкості (або тайм-аут, схожий
на обмеження швидкості), OpenClaw позначає його як такий, що перебуває в охолодженні, і переходить до наступного профілю.
Ця категорія обмежень швидкості ширша за звичайний `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)
вважаються такими, що допускають резервний перехід, і використовують ті самі періоди охолодження.
Сумісні з OpenAI помилки причини зупинки, такі як `Unhandled stop reason: error`,
`stop reason: error` і `reason: error`, класифікуються як сигнали
тайм-ауту/резервного переходу.
Загальний текст серверних помилок на рівні провайдера також може потрапляти до цієї категорії тайм-аутів, коли
джерело відповідає відомому тимчасовому шаблону. Наприклад, у Anthropic просте
`An unknown error occurred` і JSON-повідомлення `api_error` із тимчасовим серверним
текстом, таким як `internal server error`, `unknown error, 520`, `upstream error`,
або `backend error`, вважаються такими, що допускають резервний перехід через тайм-аут. Специфічний для OpenRouter
загальний upstream-текст, такий як просте `Provider returned error`, також розглядається як
тайм-аут, але лише тоді, коли контекст провайдера справді OpenRouter. Загальний внутрішній
резервний текст, такий як `LLM request failed with an unknown error.`, залишається
консервативним і сам по собі не запускає резервний перехід.

Періоди охолодження через ліміти швидкості також можуть бути прив’язані до моделі:

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

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

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

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

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

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

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

Не кожна відповідь, схожа на проблему з білінгом, має код `402`, і не кожен HTTP `402` потрапляє
сюди. OpenClaw зберігає явний текст, пов’язаний із білінгом, у категорії білінгу навіть тоді, коли
провайдер натомість повертає `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`. Це стосується помилок автентифікації, лімітів швидкості та
тайм-аутів, які вичерпали ротацію профілів (інші помилки не просувають резервний перехід).

Помилки перевантаження та ліміту швидкості обробляються агресивніше, ніж періоди охолодження через білінг.
За замовчуванням OpenClaw дозволяє одну повторну спробу з іншим профілем автентифікації в того самого провайдера,
а потім без очікування перемикається на наступну налаштовану резервну модель.
Сигнали зайнятості провайдера, такі як `ModelNotReadyException`, належать до цієї категорії перевантаження.
Налаштуйте це за допомогою `auth.cooldowns.overloadedProfileRotations`,
`auth.cooldowns.overloadedBackoffMs` і
`auth.cooldowns.rateLimitedProfileRotations`.

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

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

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

Правила:

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

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

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

- збої автентифікації
- ліміти швидкості та вичерпання періоду охолодження
- помилки перевантаження/зайнятості провайдера
- помилки резервного переходу, схожі на тайм-аут
- вимкнення через білінг
- `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного переходу, щоб
  застаріла збережена модель не створювала зовнішній цикл повторних спроб
- інші нерозпізнані помилки, коли ще залишаються кандидати

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

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

### Поведінка пропуску через охолодження та пробних спроб

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

- Стійкі збої автентифікації відразу пропускають увесь провайдер.
- Вимкнення через білінг зазвичай пропускаються, але основного кандидата все одно можна пробно перевірити
  із обмеженням частоти, щоб відновлення було можливим без перезапуску.
- Основного кандидата можна пробно перевірити ближче до завершення періоду охолодження, з
  обмеженням частоти для кожного провайдера.
- Резервні споріднені моделі того самого провайдера можна пробувати попри охолодження, коли
  збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий).
  Це особливо важливо, коли обмеження швидкості прив’язане до моделі, а споріднена модель може
  все ще відновитися негайно.
- Тимчасові пробні спроби під час охолодження обмежуються однією на провайдера за один запуск резервного переходу, щоб
  один провайдер не затримував міжпровайдерний резервний перехід.

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

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

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

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

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

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

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

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

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

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

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

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

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