Переключение моделей

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

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

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

Хранилище auth (ключи + OAuth)

OpenClaw использует профили auth как для ключей 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 для некоторых провайдеров)

ID профилей

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 использует круговой порядок:

  • Первичный ключ: тип профиля (OAuth перед ключами API).
  • Вторичный ключ: usageStats.lastUsed (сначала самые старые, в пределах каждого типа).
  • Профили с периодом ожидания/отключенные перемещаются в конец, упорядоченные по ближайшему истечению.

Привязка к сессии (удобная для кэша)

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

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

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

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

Почему OAuth может "выглядеть потерянным"

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

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

Периоды ожидания

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

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

  • 1 минута
  • 5 минут
  • 25 минут
  • 1 час (максимум)

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

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

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

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

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

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

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

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

Переключение модели

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

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

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

См. Конфигурация 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 маршрутизация

См. Models для более широкого обзора выбора модели и переключения.

← Назад к документации