Конфигурация

Резервирование моделей

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

Ротация профилей аутентификации в рамках текущего провайдера.
Переключение на резервную модель к следующей модели в списке 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 выбирает порядок следующим образом:

Явная конфигурация: auth.order[provider] (если задано).
Настроенные профили: профили из auth.profiles, отфильтрованные по провайдеру.
Сохраненные профили: записи в auth-profiles.json для данного провайдера.

Если явный порядок не настроен, OpenClaw использует циклический порядок (round‑robin):

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

Закрепление сессии (дружелюбно к кешу)

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

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

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

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

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

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

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

Когда профиль выходит из строя из-за ошибок аутентификации/лимитов запросов (или таймаута, похожего на ограничение скорости), OpenClaw помечает его как находящийся в периоде охлаждения и переходит к следующему профилю. Ошибки формата/некорректного запроса (например, сбои валидации ID вызова инструмента Cloud Code Assist) рассматриваются как достаточные для переключения и используют те же периоды охлаждения. Ошибки, совместимые с OpenAI, такие как Unhandled stop reason: error, stop reason: error и reason: error, классифицируются как сигналы таймаута/переключения. Периоды охлаждения используют экспоненциальную отсрочку:

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. Это применяется к сбоям аутентификации, лимитам запросов и таймаутам, исчерпавшим ротацию профилей (другие ошибки не приводят к переходу на резервную модель). Когда запуск начинается с переопределения модели (хуки или CLI), перебор резервных моделей все равно завершается на agents.defaults.model.primary после попытки всех настроенных резервных вариантов.

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

См. Конфигурация шлюза для:

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

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

Провайдеры моделей Anthropic