Переключение на резервную модель

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

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

Выполнение

Это намеренно более узкий подход, чем «сохранить и восстановить весь сеанс». Исполнитель ответа сохраняет только принадлежащие ему поля выбора модели для резервирования: providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Благодаря этому неудачная повторная попытка с резервной моделью не перезапишет более новые несвязанные изменения сеанса, например ручное изменение /model или обновление ротации сеанса, произошедшее во время выполнения попытки.

Политика источника выбора

Источник выбора определяет, разрешена ли цепочка резервных моделей:

• Настроенное значение по умолчанию: agents.defaults.model.primary использует agents.defaults.model.fallbacks.
• Основная модель агента: agents.list[].model применяется строго, если объект модели этого агента не содержит собственный fallbacks. Используйте fallbacks: [], чтобы явно задать строгое поведение, или непустой список, чтобы разрешить этому агенту переход на резервные модели.
• Автоматическое резервное переопределение: перед повторной попыткой механизм резервирования среды выполнения записывает providerOverride, modelOverride, modelOverrideSource: "auto" и исходную выбранную модель. Это переопределение продолжает движение по настроенной цепочке резервных моделей, не проверяя основную модель при каждом сообщении, однако OpenClaw проверяет настроенную исходную модель каждые 5 минут (это не настраивается) и удаляет переопределение после её восстановления. /new, /reset и sessions.reset также удаляют автоматически созданные переопределения. Запуски Heartbeat без явного heartbeat.model удаляют непосредственные автоматические переопределения, если их исходная модель больше не соответствует текущему настроенному значению по умолчанию.
• Пользовательское переопределение сеанса: /model, средство выбора модели, session_status(model=...) и sessions.patch записывают modelOverrideSource: "user". Это точный выбор для сеанса. Если выбранный провайдер или модель завершается сбоем до формирования ответа, OpenClaw сообщает об ошибке, а не отвечает с помощью несвязанной настроенной резервной модели.
• Устаревшее переопределение сеанса: старые записи сеансов могут содержать modelOverride без modelOverrideSource. OpenClaw рассматривает их как пользовательские переопределения, чтобы явный старый выбор не был незаметно преобразован в резервное поведение.
• Модель полезной нагрузки Cron: payload.model / --model задания Cron является основной моделью задания, а не пользовательским переопределением сеанса. Она использует настроенные резервные модели, если задание не предоставляет payload.fallbacks; payload.fallbacks: [] задаёт строгий режим запуска Cron.

OpenClaw запоминает последние проверки основной модели отдельно для каждого сеанса и основной модели, чтобы не повторять попытку с неработающей основной моделью при каждом ходе. При переходе сеанса на резервную модель отображается уведомление, а при возврате к выбранной основной модели — ещё одно; уведомление не повторяется при каждом ходе с закреплённой резервной моделью.

Кэш пропуска сбоев аутентификации

По умолчанию каждый новый ход сохраняет существующее поведение повторных попыток с резервными моделями: OpenClaw снова пробует каждого настроенного резервного кандидата, включая неосновных кандидатов, которые недавно завершились с auth или auth_permanent.

Чтобы отключить повторение сбоев аутентификации, задайте:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Если эта возможность включена, после ошибки класса аутентификации OpenClaw записывает в память маркер пропуска неосновного резервного кандидата, привязанный к сеансу и определяемый идентификатором сеанса, провайдером и моделью. Основные кандидаты никогда не пропускаются, поэтому при явном пользовательском выборе модели по-прежнему отображается фактическая ошибка аутентификации. Кэш локален для процесса и очищается при перезапуске Gateway.

Значение задаёт TTL в миллисекундах. 0 или отсутствие значения отключает кэш. Положительные значения ограничиваются диапазоном от 1 секунды до 10 минут.

Видимые пользователю уведомления о резервировании

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

↪️ Резервная модель: <fallback> (выбрана <primary>; <reason>)

Когда последующая проверка завершается успешно и сеанс возвращается к выбранной основной модели, OpenClaw отправляет:

↪️ Резервная модель отключена: <primary> (ранее <fallback>)

Эти уведомления являются служебными сообщениями, а не содержимым ответа ассистента. Они доставляются один раз при каждом изменении состояния, по возможности включая ходы, содержащие только побочные эффекты, но не повторяются при ходе с закреплённой резервной моделью. Доставка обходит обычное подавление ответа источнику, не занимает место первого ответа ассистента в каналах с ветками обсуждений и исключается из преобразования текста в речь и извлечения обязательств.

Хранение данных аутентификации (ключи и OAuth)

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

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

Подробнее: OAuth

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

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl для некоторых провайдеров)
• type: "token" → статический токен типа bearer, необязательно с ограниченным сроком действия; OpenClaw не обновляет его (используется для aws-sdk и других режимов аутентификации по цепочке учётных данных)

Идентификаторы профилей

При входе через OAuth создаются отдельные профили, поэтому несколько учётных записей могут сосуществовать.

• По умолчанию: provider:default, если адрес электронной почты недоступен.
• OAuth с адресом электронной почты: provider:<email> (например, google-antigravity:user@gmail.com).

Профили хранятся в хранилище профилей аутентификации openclaw-agent.sqlite отдельного агента.

Порядок ротации

Если у провайдера есть несколько профилей, OpenClaw выбирает порядок следующим образом:

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

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

Закрепление в сеансе (для эффективного кэширования)

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

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

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

Подписка OpenAI Codex с резервным ключом API

Для агентных моделей OpenAI аутентификация и среда выполнения разделены. openai/gpt-* остаётся в среде Codex, а аутентификация может переключаться между профилем подписки Codex и резервным ключом API OpenAI.

Используйте auth.order.openai, чтобы задать отображаемый пользователю порядок:

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

Используйте openai:* как для профилей OAuth ChatGPT/Codex, так и для профилей с ключами API OpenAI. Когда подписка достигает лимита использования Codex, OpenClaw записывает точное время сброса, если Codex его предоставляет, пробует следующий упорядоченный профиль аутентификации и продолжает выполнение в среде Codex. После времени сброса профиль подписки снова становится доступен, и следующий автоматический выбор может вернуться к нему.

Используйте закреплённый пользователем профиль только тогда, когда хотите принудительно использовать одну учётную запись или ключ для этого сеанса. Закреплённые пользователем профили намеренно применяются строго и не переключаются незаметно на другой профиль.

Периоды недоступности

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

Обычные периоды ожидания (не связанные с биллингом или постоянной ошибкой аутентификации) увеличиваются в зависимости от количества недавних ошибок профиля:

• 1-й сбой: 30 секунд
• 2-й сбой: 1 минута
• 3-й и последующие сбои: 5 минут (максимум)

Счётчики сбрасываются после завершения окна сбоев профиля (auth.cooldowns.failureWindowHours, по умолчанию 24).

Состояние хранится в состоянии аутентификации SQLite для отдельного агента в разделе usageStats:

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

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

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

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

Состояние хранится в состоянии аутентификации SQLite для отдельного агента:

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

Значения по умолчанию (auth.cooldowns.*):

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

Резервная модель

Если все профили провайдера завершаются сбоем, OpenClaw переходит к следующей модели в agents.defaults.model.fallbacks. Это применяется к ошибкам аутентификации, ограничениям частоты запросов и тайм-аутам, исчерпавшим возможности смены профиля (другие ошибки не приводят к переходу к резервной модели). Ошибки провайдера, не содержащие достаточно подробностей, всё равно получают точные метки в состоянии переключения: empty_response означает, что провайдер не вернул пригодного сообщения или статуса, no_error_details означает, что провайдер явно вернул Unknown error (no error details in response), а unclassified означает, что OpenClaw сохранил предварительный фрагмент исходного ответа, но ни один классификатор пока не смог его распознать.

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

Когда запуск начинается с настроенной основной модели по умолчанию, основной модели задания Cron, основной модели агента с явно заданными резервными моделями или автоматически выбранного переопределения резервной модели, OpenClaw может пройти по соответствующей настроенной цепочке резервных моделей. Основные модели агента без явно заданных резервных моделей и явные пользовательские выборы (например, /model ollama/qwen3.5:27b, средство выбора модели, sessions.patch или разовые переопределения провайдера или модели через CLI) обрабатываются строго: если выбранные провайдер или модель недоступны либо завершаются сбоем до формирования ответа, OpenClaw сообщает об ошибке, а не отвечает с помощью не связанной с выбором резервной модели.

Правила цепочки кандидатов

OpenClaw формирует список кандидатов из запрошенного в данный момент provider/model и настроенных резервных моделей.

Какие ошибки приводят к переходу к резервной модели

Пропуск периода ожидания и пробный запрос

Когда все профили аутентификации провайдера уже находятся в периоде ожидания, OpenClaw не начинает автоматически пропускать этого провайдера навсегда. Решение принимается отдельно для каждого кандидата:

Переопределения сеанса и переключение модели в реальном времени

Изменения модели сеанса являются общим состоянием. Активный исполнитель, команда /model, обновления Compaction или сеанса и согласование активного сеанса читают или записывают части одной и той же записи сеанса.

Поэтому повторные попытки переключения должны координироваться с переключением модели в реальном времени:

• Только явные изменения модели, инициированные пользователем, помечают ожидающее переключение в реальном времени. К ним относятся /model, session_status(model=...) и sessions.patch.
• Изменения модели, инициированные системой, например смена резервной модели, переопределения Heartbeat или Compaction, сами по себе никогда не помечают ожидающее переключение в реальном времени.
• Пользовательские переопределения модели считаются точным выбором для политики переключения, поэтому недоступность выбранного провайдера отображается как ошибка, а не маскируется с помощью agents.defaults.model.fallbacks.
• Перед началом повторной попытки с резервной моделью исполнитель ответа сохраняет в записи сеанса выбранные поля переопределения резервной модели.
• Автоматические переопределения резервной модели сохраняются для последующих обращений, чтобы OpenClaw не проверял заведомо неисправную основную модель при каждом сообщении. OpenClaw периодически снова проверяет настроенную исходную модель и удаляет автоматическое переопределение после её восстановления; /new, /reset и sessions.reset немедленно удаляют автоматически созданные переопределения.
• Ответы пользователю однократно сообщают о переходе на резервную модель и восстановлении с её отключением при каждом изменении состояния. Последующие обращения к закреплённой резервной модели не повторяют уведомление.
• /status показывает выбранную модель, а если состояние переключения отличается — активную резервную модель и причину.
• При согласовании активного сеанса сохранённым переопределениям сеанса отдаётся приоритет перед устаревшими полями модели среды выполнения.
• Если ошибка переключения в реальном времени указывает на более позднего кандидата в активной цепочке резервных моделей, OpenClaw сразу переходит к этой выбранной модели, не проверяя сначала не связанные с ней кандидатуры.
• Если попытка с резервной моделью завершается сбоем, исполнитель откатывает только записанные им поля переопределения и только в том случае, если они всё ещё соответствуют этому кандидату, завершившемуся сбоем.

Это предотвращает классическое состояние гонки:

Сохранённое переопределение резервного варианта закрывает это окно, а точечный откат сохраняет более новые изменения сеанса, внесённые вручную или во время выполнения.

Наблюдаемость и сводки сбоев

runWithModelFallback(...) записывает сведения о каждой попытке, которые используются в журналах и сообщениях для пользователей о периоде ожидания:

• проверенный провайдер/модель
• причина (rate_limit, overloaded, billing, auth, model_not_found и аналогичные причины переключения при сбое)
• необязательный статус/код
• понятная человеку сводка ошибки

Структурированные журналы model_fallback_decision также содержат плоские поля fallbackStep*, когда кандидат завершается сбоем, пропускается или последующий резервный вариант успешно срабатывает. Эти поля явно описывают выполненный переход (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), чтобы средства экспорта журналов и диагностических данных могли восстановить сведения об исходном сбое, даже если конечный резервный вариант также завершается сбоем.

Если все кандидаты завершаются сбоем, OpenClaw выдаёт FallbackSummaryError. Внешний обработчик ответа может использовать это для формирования более конкретного сообщения, например «для всех моделей временно действует ограничение частоты запросов», и указать ближайшее время окончания периода ожидания, если оно известно.

Эта сводка периода ожидания учитывает модель:

• ограничения частоты запросов на уровне моделей, не связанных с проверяемой цепочкой провайдеров/моделей, игнорируются
• если оставшаяся блокировка представляет собой соответствующее ограничение частоты запросов на уровне модели, OpenClaw сообщает последнее соответствующее время окончания, до которого эта модель остаётся заблокированной

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

См. раздел Конфигурация Gateway, посвящённый следующим параметрам:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• маршрутизация agents.defaults.imageModel

Более общий обзор выбора моделей и резервных вариантов см. в разделе Модели.