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

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

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

Выполнение

Определение состояния сеанса

Определить активную модель сеанса и предпочтение профиля аутентификации.

Формирование цепочки кандидатов

Сформировать цепочку моделей-кандидатов на основе текущего выбора модели и политики резервирования для источника этого выбора. Настроенные значения по умолчанию, основные модели заданий Cron и автоматически выбранные резервные модели могут использовать настроенные резервные варианты; явные пользовательские выборы для сеанса применяются строго.

Попытка с текущим провайдером

Попробовать текущего провайдера с учётом правил ротации и периода недоступности профилей аутентификации.

Переход при ошибках, допускающих переключение

Если все варианты текущего провайдера исчерпаны с ошибкой, допускающей переключение, перейти к следующей модели-кандидату.

Сохранение резервного переопределения

Сохранить выбранное резервное переопределение до начала повторной попытки, чтобы другие читатели сеанса видели того же провайдера и модель, которые собирается использовать исполнитель. Сохранённое переопределение модели помечается modelOverrideSource: "auto".

Точечный откат при сбое

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

Выдача FallbackSummaryError при исчерпании вариантов

Если все кандидаты завершаются сбоем, выдать FallbackSummaryError с подробностями каждой попытки и ближайшим временем окончания периода недоступности, если оно известно.

Это намеренно более узкий подход, чем «сохранить и восстановить весь сеанс». Исполнитель ответа сохраняет только принадлежащие ему поля выбора модели для резервирования: 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 выбирает порядок следующим образом:

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

auth.order[provider] (если задано).

Настроенные профили

auth.profiles, отфильтрованные по провайдеру.

Сохранённые профили

Записи профилей аутентификации провайдера в SQLite для отдельного агента.

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

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

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

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

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

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

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

Подписка 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 переводит его в период недоступности и переходит к следующему профилю.

Что относится к категории ограничений частоты запросов и тайм-аутов

Эта категория ограничений частоты запросов шире, чем простой 429: она также включает сообщения провайдеров, такие как Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, throttled, resource exhausted, а также периодические ограничения окна использования, такие как weekly limit reached или monthly limit exhausted.Ошибки формата или недопустимого запроса обычно являются окончательными, поскольку повторная отправка той же полезной нагрузки завершится сбоем таким же образом, поэтому OpenClaw отображает их вместо ротации профилей аутентификации. Известные механизмы исправления при повторной попытке могут явно включить такое поведение: например, ошибки проверки идентификатора вызова инструмента Cloud Code Assist очищаются и один раз повторяются в соответствии с политикой allowFormatRetry. Совместимые с OpenAI ошибки причины остановки, такие как Unhandled stop reason: error, stop reason: error и reason: error, классифицируются как сигналы тайм-аута или переключения.Общий текст ошибки сервера также может попасть в эту категорию тайм-аутов, если источник соответствует известному шаблону временной ошибки. Например, необрамлённое сообщение оболочки потока среды выполнения модели An unknown error occurred считается допускающим переключение для каждого провайдера, поскольку общая среда выполнения модели выдаёт его, когда потоки провайдера завершаются с stopReason: "aborted" или stopReason: "error" без конкретных подробностей. Полезные нагрузки JSON api_error с текстом временной ошибки сервера, таким как internal server error, unknown error, 520, upstream error или backend error, также считаются тайм-аутами, допускающими переключение.Специфичный для OpenRouter общий текст вышестоящего сервера, такой как необрамлённый Provider returned error, считается тайм-аутом только тогда, когда контекст провайдера действительно относится к OpenRouter. Общий внутренний текст резервного механизма, такой как LLM request failed with an unknown error., обрабатывается консервативно и сам по себе не запускает переключение.

Ограничения retry-after в SDK

В противном случае некоторые SDK провайдеров могут приостановить выполнение на длительный период Retry-After, прежде чем вернуть управление OpenClaw. Для SDK на основе Stainless, таких как Anthropic и OpenAI, OpenClaw по умолчанию ограничивает внутренние ожидания SDK retry-after-ms / retry-after 60 секундами и немедленно передаёт более длительные повторяемые ответы, чтобы мог запуститься этот путь переключения при сбое. Настройте или отключите ограничение с помощью OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS; см. Поведение повторных попыток.

Периоды ожидания для отдельных моделей

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

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

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

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

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

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

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

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

Не каждый ответ, похожий на ошибку биллинга, является 402, и не каждый HTTP 402 попадает сюда. OpenClaw относит явный текст об ошибке биллинга к категории биллинга, даже если провайдер вместо этого возвращает 401 или 403, но сопоставители, специфичные для провайдера, применяются только к своему провайдеру (например, OpenRouter 403 Key limit exceeded).При этом временные ошибки 402, связанные с окном использования и ограничением расходов организации или рабочего пространства, классифицируются как rate_limit, если сообщение указывает на возможность повторной попытки (например, weekly usage limit exhausted, daily limit reached, resets tomorrow или organization spending limit exceeded). Они остаются в пути короткого периода ожидания и переключения при сбое, а не переходят в путь длительного отключения из-за биллинга.

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

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

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

Ключ	По умолчанию	Назначение
`billingBackoffHours`	5	Начальная задержка после ошибки биллинга, удваивается с каждым таким сбоем
`billingMaxHours`	24	Максимальная задержка после ошибки биллинга
`authPermanentBackoffMinutes`	10	Начальная задержка для сбоев, с высокой уверенностью указывающих на постоянную ошибку аутентификации
`authPermanentMaxMinutes`	60	Максимум для этой задержки
`failureWindowHours`	24	Счётчики сбоев сбрасываются, если в течение этого окна не происходит сбоев
`overloadedProfileRotations`	1	Допустимое количество смен профиля того же провайдера перед переходом к резервной модели при перегрузке
`overloadedBackoffMs`	0	Фиксированная задержка перед повторной попыткой после смены профиля из-за перегрузки
`rateLimitedProfileRotations`	1	Допустимое количество смен профиля того же провайдера перед переходом к резервной модели при ограничении частоты запросов

Ошибки перегрузки и ограничения частоты запросов обрабатываются агрессивнее, чем периоды ожидания после ошибок биллинга: по умолчанию 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 продолжает использовать полную настроенную цепочку.
Если явное переопределение резервных моделей не задано, настроенные резервные модели проверяются перед настроенной основной моделью, даже если запрошенная модель использует другого провайдера.
Если исполнителю переключения не передано явное переопределение резервных моделей, настроенная основная модель добавляется в конец, чтобы после исчерпания предыдущих кандидатов цепочка могла вернуться к обычной модели по умолчанию.
Когда вызывающая сторона передаёт fallbacksOverride, исполнитель использует только запрошенную модель и этот список переопределений. Пустой список отключает переключение между моделями и не позволяет скрыто добавлять настроенную основную модель как цель повторной попытки.

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

Продолжает при
Не продолжает при

ошибках аутентификации
ограничениях частоты запросов и исчерпании периода ожидания
ошибках перегрузки или занятости провайдера
ошибках переключения, похожих на тайм-аут
отключениях из-за биллинга
LiveSessionModelSwitchError, которая нормализуется в путь переключения, чтобы устаревшая сохранённая модель не создавала внешний цикл повторных попыток
других нераспознанных ошибках, если остаются другие кандидаты

явных прерываниях, не похожих на тайм-аут или ошибку переключения
ошибках переполнения контекста, которые должны обрабатываться внутри логики Compaction или повторных попыток (например, request_too_large, input token count exceeds the maximum number of input tokens, input exceeds the maximum number of tokens, input too long for the model или ollama error: context length exceeded)
последней неизвестной ошибке, когда кандидатов больше нет
отказах Claude Fable 5 по соображениям безопасности; запросы напрямую с ключом API обрабатывают их на уровне провайдера посредством серверного переключения Anthropic на claude-opus-4-8 (см. Anthropic)

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

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

Решения для отдельных кандидатов

При постоянных ошибках аутентификации весь провайдер немедленно пропускается.
Отключения из-за биллинга обычно приводят к пропуску, но основной кандидат всё ещё может периодически проверяться, чтобы восстановление было возможно без перезапуска.
Ближе к завершению периода ожидания основной кандидат может быть проверен с отдельным ограничением частоты для каждого провайдера.
Резервные модели того же провайдера можно пробовать несмотря на период ожидания, если сбой выглядит временным (rate_limit, overloaded или неизвестный). Это особенно важно, когда ограничение частоты запросов относится к отдельной модели, а другая модель может восстановиться немедленно.
Временные проверки во время периода ожидания ограничены одной на провайдера за один запуск переключения, чтобы один провайдер не задерживал переключение между провайдерами.

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

Изменения модели сеанса являются общим состоянием. Активный исполнитель, команда /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

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

Overview

Concepts and configuration

Providers

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

Выполнение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

​Выполнение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выполнение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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