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

Типы учетных данных:

• 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:

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

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

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

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

{
  "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 (шлюз) для:

• 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

См. Модели для более общего обзора выбора моделей и fallback.