fallbackModel в Claude Code: трёхуровневый failover (2026)

Настройка трёхуровневого failover за 4 шага

Когда Anthropic возвращает 529 overloaded_error, ненастроенная сессия Claude Code повторяет запрос к той же модели, а затем отдаёт вам ошибку. Резервная цепочка превращает этот тупик в понижение уровня: перегрузка на Opus, повтор на Sonnet, а если и он недоступен, Haiku.

Вся конфигурация, это один массив:

{
  "model": "opus",
  "fallbackModel": ["sonnet", "haiku"]
}

Это трёхуровневая цепочка: opus, основная модель, sonnet и haiku, резервные. Остальная часть руководства о том, что из массива неочевидно: какие ошибки его действительно запускают, почему 429 не запускает, как ведёт себя цепочка в команде и где цепочка в рамках одного аккаунта перестаёт помогать.

Что вы сможете после этой настройки (и что нет)

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

Вот что резервная цепочка делает для вас:

• Переживает кратковременную перегрузку Anthropic (529 overloaded_error) без потери хода.
• Продолжает работать, когда конкретная модель недоступна, например если модель закреплена в настройках, но уже выведена из эксплуатации.
• Осознанно понижает возможности, так что сложная задача, начавшаяся на Opus, завершится на Sonnet, а не провалится вовсе.

Вот что она не сделает:

• Не проведёт вас мимо лимита запросов 429 или ограничения по использованию. Это проблемы квоты, а каждая модель в цепочке черпает из квоты одного и того же аккаунта.
• Не переключится на другого провайдера. Элементы цепочки разрешаются в модели Claude на одном аккаунте, поэтому полный сбой Anthropic кладёт цепочку вместе с собой.
• Не изменит вашу основную модель навсегда. Переключение происходит на один ход, и следующее сообщение снова стартует на вашей основной модели.

Если ваша постоянная боль, это «usage limit reached», а не «overloaded», резервная цепочка, это неверное решение. См. отдельное руководство про достигнутый лимит запросов в Claude Code, а про версию самой перегрузки на уровне API, ошибка Claude API 529.

Рамка решения: когда применять эту настройку (и когда НЕ применять)

Когда применять

• Вы запускаете Claude Code без присмотра или в скриптовом контексте (CI, длинный прогон агента, ночная задача), где 529 в середине хода иначе прервал бы всю работу.
• Вы на платном API или высоком тарифе, где обычная причина прерываний, это перегрузки, а не квота.
• Вы можете смириться с понижением качества до конца хода в обмен на его завершение.

Когда НЕ применять

• Ваши прерывания, это 429 или «usage limit reached». Цепочка здесь ничего не даёт; вместо этого правьте квоту или кэширование (оптимизация токенов, вот рычаг).
• Вам нужен каждый ход на конкретной модели ради воспроизводимости. Тихое понижение до Haiku в середине прогона может изменить качество вывода так, что от него будет зависеть более поздний шаг.
• Вам нужна устойчивость на уровне провайдера. Один аккаунт не может переключиться на самого себя; для этого нужен шлюз (описан ниже).

Правило остановки

Если всё, что вам нужно, это одна автоматическая резервная модель при перегрузке, добавьте одну запись и остановитесь: "fallbackModel": ["sonnet"]. Трёхуровневая цепочка важна только когда вы ожидаете, что Sonnet будет под нагрузкой одновременно с Opus, а это в основном случается во время широкого инцидента платформы.

Системные требования

Три алиаса и то, во что они сегодня разрешаются на Anthropic API:

Две детали из этой таблицы формируют разумную цепочку. Sonnet 5 имеет вводную цену $2 / $10 за MTok до 31 августа 2026, так что средний уровень сейчас дешевле прайс-листа. А у Haiku 4.5 окно контекста 200K, а не 1M, как у Opus и Sonnet, поэтому длинная сессия, переполняющая 200K, на уровень Haiku не поместится. Стройте цепочку с этим в уме: Haiku, это крайнее средство по причинам ёмкости, а не только качества.

Пошаговая настройка

Шаг 1: Подтвердите основную модель и версию

claude --version
claude   # then run /status inside the session

/status показывает активную модель. Если opus не разрешается в Opus 4.8 или sonnet не Sonnet 5, сначала запустите claude update. Ожидаемый результат: версия не ниже 2.1.197 и узнаваемая основная модель.

Шаг 2: Проверьте цепочку на одну сессию флагом

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

claude --model opus --fallback-model sonnet,haiku

Ожидаемый результат: сессия стартует на Opus. Резервные модели вы не увидите, пока реально не случится перегрузка, и тогда Claude Code напечатает уведомление с именем модели, на которую он переключился.

Шаг 3: Закрепите цепочку в settings.json

Как только флаг ведёт себя правильно, перенесите его в настройки, чтобы каждая сессия его наследовала. Используйте либо алиасы, либо полные ID моделей; полные ID закрепляют версию и переживают изменения алиасов.

{
  "model": "opus",
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

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

Шаг 4: Проверьте условия срабатывания, а не удачный сценарий

Настоящий 529 по требованию не сфабрикуешь, поэтому вместо ожидания сбоя проверьте те части, о которых можно рассуждать. Убедитесь, что каждый элемент разрешается в достижимую модель, и убедитесь, что понимаете, что не запустит переключение. Не полагайтесь на ошибку, которая скажет, что цепочка прочитана: Claude Code не проверяет fallbackModel при запуске (проверено на v2.1.208), поэтому некорректное значение молча игнорируется, а не выбрасывает ошибку. Именно этот последний момент, что не запустит переключение, и есть место, где прячется большинство неправильных настроек, поэтому ему посвящён отдельный раздел.

Что запускает переключение (и что нет)

Вот таблица, которую стоит усвоить. Переключение срабатывает на сбоях доступности и молчит на всём остальном.

Строка про 429, вот где люди спотыкаются. Лимит запросов означает, что вы исчерпали квоту, а каждая модель в вашей цепочке списывает средства с одного и того же аккаунта, поэтому переключение с Opus на Haiku запаса не создаёт. Claude Code это знает и отказывается тратить переключение на такой случай. Если ваши логи показывают, что переключения не срабатывают во время инцидента, проверьте, не является ли инцидент на самом деле 429.

Та же логика в виде схемы:

flowchart TD
    A[Model request] --> B{Response}
    B -->|529 / unavailable / non-retryable 5xx| C{More models in chain?}
    B -->|429 / auth / billing / size| D[Normal retry, then surface error]
    B -->|success| E[Return result for this turn]
    C -->|yes| F[Switch to next model, show notice]
    C -->|no| D
    F --> A
    E --> G[Next message tries primary first again]

Как выбрать порядок цепочки

Порядок массива, это порядок, в котором Claude Code пробует модели, поэтому массив, это список приоритетов, а не множество. Два варианта по умолчанию покрывают большинство случаев в зависимости от того, что вы оптимизируете.

Приоритет возможностей (["sonnet", "haiku"] при основной opus) держит качество настолько высоким, насколько позволяет доступность, и опускается до Haiku, только когда обе крупные модели перегружены одновременно. Используйте для интерактивной работы, где понижение уровня, это действительно крайнее средство.

Приоритет стоимости (основная sonnet, резервная ["haiku"]) вообще не тянется к Opus. Используйте в CI и циклах агентов, где пропускная способность и предсказуемые траты важнее потолка. Аргумент гибридной маршрутизации применим здесь: большинству ходов Opus не нужен, поэтому делать его основным лишь ради высокой цепочки, значит впустую тратить деньги на типичный случай.

Одно ограничение перевешивает оба предпочтения, и его легко упустить: окно контекста. У Haiku 4.5 окно 200K против 1M, которые дают Opus 4.8 и Sonnet 5. Сессия, уже выросшая за 200K, вообще не сможет приземлиться на уровень Haiku, поэтому на длинном контексте Haiku фактически отсутствует в цепочке, куда бы вы его ни поставили. Если ваши сессии обычно крупные, держите цепочку на уровнях с окном 1M и смиритесь с тем, что одновременный сбой Opus и Sonnet провалит ход, а не молча обрежет контекст.

Как выглядит переключение

Переключение никогда не бывает тихим. Когда оно срабатывает, Claude Code печатает в транскрипте уведомление с именем модели, на которую он перешёл. Поскольку переключение ограничено ходом, вы видите это уведомление снова при следующей перегрузке, а не сессию, которая тихо осела на Haiku. Неправильная настройка, напротив, тиха: некорректное значение fallbackModel игнорируется без предупреждения (проверено на v2.1.208), поэтому сломанная цепочка выглядит в точности как рабочая, пока перегрузка не найдёт брешь. Чтобы убедиться, что цепочка действительно активна, не ищите ошибку при запуске; проверяйте её по полю modelUsage из JSON-прогона, как описано далее.

В неинтерактивных прогонах (-p / --print), выдающих JSON, текстовое уведомление подавляется, поэтому читайте модель, которая реально ответила, из поля modelUsage результирующего сообщения, а не предполагайте, что ход обработала основная модель. Это надёжный способ по факту проверить, как часто цепочка что-то ловила и какой уровень принял нагрузку. Если цепочка ни разу не показывает срабатывания за реальное окно инцидента, ещё раз проверьте, не был ли инцидент 429, который никакая цепочка не покрывает.

Частые ошибки при настройке (и исправления)

Поведение без слияния заслуживает акцента, потому что оно противоположно тому, как работает большинство настроек-массивов. Если вы отладили аккуратную трёхуровневую цепочку в пользовательских настройках, а репозиторий поставляет .claude/settings.json со своим одномодельным fallbackModel, репозиторий выигрывает целиком, и ваша цепочка отбрасывается без предупреждения. Приоритет идёт так: managed-настройки, затем флаги командной строки, затем project-local, затем project, затем user. Кладите нужную вам цепочку в файл с наивысшим приоритетом, который будет прочитан для конкретной сессии.

Конфигурация для команды / нескольких разработчиков

Для одного разработчика достаточно fallbackModel в ~/.claude/settings.json. В команде интересный вопрос в том, кто владеет цепочкой и могут ли отдельные разработчики её переопределить.

Важны два командных взаимодействия. Во-первых, если вы также используете availableModels, чтобы ограничить, какие модели разработчикам разрешено запускать, любой резервный элемент вне этого allowlist отбрасывается при чтении цепочки, поэтому принудительная цепочка и allowlist должны согласовываться. Во-вторых, поскольку резервные цепочки не объединяются, закоммиченная проектная цепочка полностью заменяет личную цепочку каждого разработчика внутри этого репозитория. Обычно это то, что нужно для CI и общих агентов, но это значит, что разработчик, отладивший личную цепочку, молча её теряет, работая в репозитории. Задокументируйте проектную цепочку, чтобы никто не отлаживал «пропавший» fallback, который был переопределён по замыслу.

Разумная закоммиченная проектная цепочка для команды, запускающей агентов в CI:

{
  "model": "sonnet",
  "fallbackModel": ["haiku"],
  "availableModels": ["sonnet", "haiku"]
}

Это держит CI на более дешёвом уровне Sonnet, переключается на Haiku при перегрузке и запрещает кому-либо тихо переводить CI-задачу на Opus.

Продвинутое: кросс-провайдерный failover через шлюз

У резервной цепочки есть жёсткий потолок: каждая модель в ней живёт на одном и том же аккаунте Anthropic. Когда у самой Anthropic широкий инцидент, все три уровня перегружены разом, и в цепочке уже нечего пробовать. Сбой 18 марта 2026, растянувшийся более чем на три часа, это форма отказа, которую цепочка в рамках одного аккаунта покрыть не может.

Устойчивость на уровне провайдера требует слоя над Claude Code. Направьте Claude Code на шлюз через ANTHROPIC_BASE_URL, и шлюз (а не ваш единственный аккаунт) решает, куда попадёт запрос. ANTHROPIC_BASE_URL меняет то, куда идут запросы, а не то, какая модель отвечает, поэтому цепочка fallbackModel под ним по-прежнему работает для failover на уровне моделей, а шлюз добавляет failover на уровне провайдера сверху.

Агрегирующий шлюз вроде ofox выставляет одну совместимую с OpenAI и Anthropic конечную точку, объединяющую множество провайдеров, поэтому цепочка может перейти от модели Claude к не-Claude, когда Anthropic целиком недоступна, чего нативная цепочка fallbackModel физически сделать не может. Компромисс в том, что вы теперь доверяете второму прыжку и настраиваете маршрутизацию на шлюзе, а не в settings.json. Про настройку со стороны Claude Code см. руководство по конфигурации Claude Code + ofox; про вариант той же идеи маршрутизации, продиктованный стоимостью, см. гибридную маршрутизацию моделей.

Одно разграничение перед альтернативами. У Claude Code также есть функция, буквально называемая «automatic model fallback», и это не та функция. Тот механизм специфичен для Fable 5: когда классификатор безопасности помечает запрос (чаще всего работу по кибербезопасности или биологии), Claude Code перезапускает его на Opus и показывает уведомление. Он не имеет отношения к перегрузкам или цепочке fallbackModel. Если вы видите переключения на сессии Fable 5, которые не настраивали, это классификатор. Запуск claude --safe-mode отключает ваши локальные настройки (CLAUDE.md, скиллы, хуки, MCP), поэтому изолирует, не они ли его провоцируют, но безопасный режим всё равно отправляет вещи вроде вашего git status и имён каталогов, поэтому содержимое репозитория само по себе может спровоцировать классификатор даже тогда.

Альтернативы, которые обеспечивают failover

fallbackModel, это встроенный вариант без зависимостей, и он должен быть вашим первым выбором для устойчивости к перегрузкам на уровне моделей. Когда нужно больше, вот слои над ним.

• ofox выставляет единственную совместимую с Anthropic конечную точку, объединяющую несколько провайдеров, так что failover может перейти от Claude к семейству другой модели во время полного инцидента Anthropic. Лучше всего, когда устойчивость на уровне провайдера важнее, чем оставаться у одного вендора.
• LiteLLM, это опенсорсный прокси с собственным списком повторов и резервов между провайдерами. Лучше всего, когда вы хотите разместить слой маршрутизации у себя и уже держите инфраструктуру.
• OpenRouter, это агрегатор с автоматическим резервированием провайдеров для заданной модели. Лучше всего для широты каталога моделей при минимальной настройке.
• Portkey, это шлюз с настраиваемыми политиками резервирования и балансировки нагрузки. Лучше всего, когда вам нужны правила маршрутизации, а не статичный список, плюс наблюдаемость.

Все четыре располагаются над Claude Code и дополняют, а не заменяют цепочку fallbackModel: держите цепочку для дешёвого failover моделей внутри CLI и добавьте шлюз для случая на уровне провайдера.

FAQ

Что такое fallbackModel в Claude Code?

Это ключ settings.json и флаг CLI --fallback-model, который перечисляет резервные модели, перебираемые Claude Code по порядку, когда основная перегружена или недоступна. Указать можно до трёх. Переключение действует только в рамках текущего хода; следующее сообщение снова сначала пробует вашу основную модель.

Переключается ли Claude Code автоматически при ошибке 529?

Только если вы настроили fallbackModel. 529, это overloaded_error, одно из условий, запускающих переключение. Без настройки Claude Code повторяет запрос к той же модели с задержкой, а затем выдаёт ошибку.

Помогает ли fallbackModel при ошибках лимита запросов (429)?

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

Сколько резервных моделей может использовать Claude Code?

Три. Цепочки ограничены тремя после удаления дубликатов, а лишние записи игнорируются. Распространённая цепочка: opus, затем sonnet, затем haiku.

Как задать резервную модель в Claude Code?

Для одной сессии запустите claude --fallback-model sonnet,haiku. Чтобы закрепить, добавьте массив fallbackModel в settings.json, например ["claude-sonnet-5", "claude-haiku-4-5"]. Флаг бьёт настройку.

Остаётся ли резервная модель активной на всю сессию?

Нет. Переключение применяется только к текущему ходу, так что кратковременная перегрузка не запирает сессию на более низком уровне.

В чём разница между fallbackModel и автоматическим переключением модели?

fallbackModel (цепочки резервных моделей) отвечает за доступность, срабатывая при перегрузке или недоступности. Автоматическое переключение модели, это отдельный механизм Fable 5, где классификатор безопасности перенаправляет помеченный запрос на Opus. У них совпадает только слово fallback.

Может ли Claude Code переключиться на модель не от Anthropic?

Через fallbackModel нет. Каждый элемент разрешается в модель Claude на том же аккаунте, поэтому полный сбой Anthropic кладёт всю цепочку разом. Кросс-провайдерный failover требует шлюза, объединяющего более одного провайдера.

Проверенные источники для этого обновления

• Документация по конфигурации моделей Claude Code, раздел Fallback model chains (проверено 2026-07-15): https://code.claude.com/docs/en/model-config
• Справочник настроек Claude Code, ключ fallbackModel (проверено 2026-07-15): https://code.claude.com/docs/en/settings
• Справочник ошибок Anthropic API, 529 overloaded_error (проверено 2026-07-15): https://platform.claude.com/docs/en/api/errors
• Обзор моделей Anthropic, цены и окна контекста для Opus 4.8 / Sonnet 5 / Haiku 4.5 (проверено 2026-07-15): https://platform.claude.com/docs/en/about-claude/models/overview
• Практическая проверка на Claude Code v2.1.208 (2026-07-15): некорректные значения fallbackModel и значения с опечатками принимаются без ошибки при запуске и молча пропускаются; отвечавшая модель подтверждена по полю modelUsage из вывода JSON --print.