Отказоустойчивое переключение модели

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

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

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

Поток runtime

Для обычного текстового запуска OpenClaw оценивает кандидатов в таком порядке:

Это намеренно уже, чем «сохранить и восстановить всю сессию». Runner ответов сохраняет только поля выбора модели, которыми он владеет для fallback:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Это не позволяет неудачной повторной попытке fallback перезаписать более новые несвязанные мутации сессии, такие как ручные изменения /model или обновления ротации сессии, произошедшие во время выполнения попытки.

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

OpenClaw отделяет выбранного провайдера/модель от причины выбора. Этот источник управляет тем, разрешена ли цепочка fallback:

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

Интервал проверки основной модели для автоматического fallback составляет пять минут и не настраивается. OpenClaw запоминает недавние проверки для каждой сессии и основной модели, чтобы отказавшая основная модель не повторялась на каждом ходе. OpenClaw отправляет видимое уведомление, когда сессия переходит на fallback, и еще одно уведомление, когда она возвращается к выбранной основной модели; уведомление не повторяется на каждом закрепленном fallback-ходе.

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

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

Операторы, которые предпочитают подавлять такие повторяющиеся сбои аутентификации, могут включить это с помощью:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

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

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

Пользовательские уведомления fallback

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

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

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

↪️ Model Fallback cleared: <primary> (was <fallback>)

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

Хранилище аутентификации (ключи + OAuth)

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

• Секреты и состояние runtime-маршрутизации аутентификации находятся в ~/.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 для некоторых провайдеров)

ID профилей

Входы OAuth создают отдельные профили, чтобы несколько аккаунтов могли сосуществовать.

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

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

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

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

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

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

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

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

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

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

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

Для моделей агентов OpenAI аутентификация и runtime разделены. openai/gpt-* остается на harness 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 его предоставляет, пробует следующий упорядоченный профиль аутентификации и сохраняет запуск внутри harness Codex. После того как время сброса проходит, профиль подписки снова становится допустимым, и следующий автоматический выбор может вернуться к нему.

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

Охлаждения

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

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

• 1 минута
• 5 минут
• 25 минут
• 1 час (предел)

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

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

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

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

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

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

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

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

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

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

Ошибки перегрузки и ограничения частоты обрабатываются агрессивнее, чем биллинговые периоды ожидания. По умолчанию OpenClaw допускает одну повторную попытку с профилем авторизации того же провайдера, а затем без ожидания переключается на следующую настроенную резервную модель. Сигналы занятости провайдера, такие как ModelNotReadyException, попадают в этот набор перегрузки. Настройте это с помощью auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs и auth.cooldowns.rateLimitedProfileRotations.

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

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

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

Какие ошибки продвигают резервную цепочку

Пропуск периода ожидания и поведение проб

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

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

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

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

• Только явные пользовательские изменения модели помечают ожидающее живое переключение. Это включает /model, session_status(model=...) и sessions.patch.
• Системные изменения модели, такие как резервная ротация, переопределения Heartbeat или compaction, сами по себе никогда не помечают ожидающее живое переключение.
• Пользовательские переопределения модели трактуются как точные выборы для политики резервного переключения, поэтому недоступный выбранный провайдер показывается как сбой, а не маскируется agents.defaults.model.fallbacks.
• Перед запуском резервной повторной попытки runner ответа сохраняет выбранные поля резервного переопределения в запись сеанса.
• Автоматические резервные переопределения остаются выбранными в последующих ходах, чтобы OpenClaw не проверял заведомо неисправную основную модель при каждом сообщении. OpenClaw периодически снова проверяет настроенный источник и очищает автоматическое переопределение, когда он восстанавливается; /new, /reset и sessions.reset сразу очищают автоматически полученные переопределения.
• Ответы пользователю объявляют о резервных переходах и восстановлении с очисткой резервного состояния один раз на каждое изменение состояния. Ходы с закрепленной резервной моделью не повторяют уведомление.
• /status показывает выбранную модель и, когда резервное состояние отличается, активную резервную модель и причину.
• Согласование live-сеанса предпочитает сохраненные переопределения сеанса устаревшим полям модели runtime.
• Если ошибка live-переключения указывает на более позднего кандидата в активной резервной цепочке, OpenClaw переходит прямо к этой выбранной модели, а не проходит сначала по несвязанным кандидатам.
• Если резервная попытка завершается сбоем, runner откатывает только поля переопределения, которые он записал, и только если они все еще соответствуют этому неудавшемуся кандидату.

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

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

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

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

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

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

Когда все кандидаты дают сбой, OpenClaw выбрасывает FallbackSummaryError. Внешний runner ответа может использовать это, чтобы построить более конкретное сообщение, например "all models are temporarily rate-limited", и включить ближайшее истечение периода ожидания, когда оно известно.

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

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

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

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

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

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