> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Failover моделей

# Failover моделей

OpenClaw обрабатывает сбои в два этапа:

1. **Ротация профилей аутентификации** в рамках текущего провайдера.
2. **Fallback модели** к следующей модели в `agents.defaults.model.fallbacks`.

В этом документе объясняются правила выполнения во время работы и данные, на которых они основаны.

## Хранилище аутентификации (ключи + OAuth)

OpenClaw использует **профили аутентификации** как для ключей API, так и для OAuth‑токенов.

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

Подробнее: [/concepts/oauth](/concepts/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/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` (сначала самые старые, в пределах каждого типа).
* **Профили в кулдауне/отключённые** перемещаются в конец, упорядоченные по ближайшему времени окончания.

### Привязка к сеансу (cache‑friendly)

OpenClaw **закрепляет выбранный профиль аутентификации за сеансом**, чтобы поддерживать тёплые кэши провайдера.
Ротация **не** выполняется на каждый запрос. Закреплённый профиль используется повторно, пока:

* сеанс не будет сброшен (`/new` / `/reset`)
* уплотнение завершает (прибавление количества уплотнений)
* профиль не окажется в кулдауне/отключён

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

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

### Почему OAuth может «казаться потерянным»

Если у вас есть и OAuth‑профиль, и профиль с ключом API для одного и того же провайдера, round‑robin может переключаться между ними от сообщения к сообщению, если профиль не закреплён. Чтобы принудительно использовать один профиль:

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

## Перезарядки

Когда профиль терпит неудачу из‑за ошибок аутентификации/ограничений скорости (или таймаута, который выглядит
как ограничение скорости), OpenClaw помечает его кулдауном и переходит к следующему профилю.
Ошибки формата/некорректного запроса (например, сбои валидации ID вызова инструмента Cloud Code Assist)
считаются достойными failover и используют те же кулдауны.

Кулдауны используют экспоненциальную задержку:

* 1 минута
* 5 минут
* 25 минут
* 1 час (предел)

Состояние хранится в `auth-profiles.json` в разделе `usageStats`:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}
```

## Отключения из‑за биллинга

Сбои биллинга/кредитов (например, «недостаточно кредитов» / «слишком низкий кредитный баланс») считаются достойными failover, но обычно они не временные. Вместо короткого кулдауна OpenClaw помечает профиль как **отключённый** (с более длительной задержкой) и выполняет ротацию к следующему профилю/провайдеру.

Состояние хранится в `auth-profiles.json`:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}
```

Значения по умолчанию:

* Задержка биллинга начинается с **5 часов**, удваивается при каждом сбое биллинга и ограничивается **24 часами**.
* Счётчики задержки сбрасываются, если профиль не терпел неудач в течение **24 часов** (настраивается).

## Fallback моделей

Если все профили для провайдера не срабатывают, OpenClaw переходит к следующей модели в
`agents.defaults.model.fallbacks`. Это применяется к сбоям аутентификации, ограничениям скорости и
таймаутам, исчерпавшим ротацию профилей (другие ошибки не продвигают fallback).

Когда запуск начинается с переопределением модели (хуки или CLI), fallback всё равно заканчиваются на
`agents.defaults.model.primary` после попыток всех настроенных fallback.

## Связанная конфигурация

См. [Конфигурация Gateway (шлюз)](/gateway/configuration) для:

* `auth.profiles` / `auth.order`
* `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider`
* `auth.cooldowns.billingMaxHours` / `auth.cooldowns.failureWindowHours`
* `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
* маршрутизации `agents.defaults.imageModel`

См. [Модели](/concepts/models) для более общего обзора выбора моделей и fallback.