Перейти к основному содержанию

​
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:[email protected]).
Профили находятся в ~/.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.