Claude Code 2.1.310: ошибки шлюза и исправления хуков Windows

Если Claude Code при работе через шлюз возвращает Unexpected value(s) с упоминанием effort-2025-11-24 или Unexpected role "system", обновите клиент до 2.1.310 или новее и повторите запрос в проблемном диалоге. В Windows отдельно проверьте, блокируется ли вызов инструмента при сбое интерпретатора хука — обработчика события. Если при очень большом значении cleanupPeriodDays пропали вставленные изображения, сначала сохраните оставшиеся данные и лишь затем меняйте срок хранения.

По состоянию на 2026-10-25 официальное описание выпуска 2.1.310 подтверждает исправления этих ошибок шлюзов, хуков Windows и очистки данных. Для каждого случая ниже приведена отдельная проверка.

Убедитесь, что запускается версия 2.1.310 или новее

Сначала проверьте исполняемый файл, который запускает ваш терминал, а затем обновите его тем же способом, которым устанавливали. В Bash или без изменений в Windows PowerShell выполните:

claude --version
claude doctor

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

Выберите подходящую команду из инструкции Anthropic по установке и обновлению:

Способ установки	Оболочка	Команда обновления
Нативный установщик	Bash или PowerShell	`claude update`
Homebrew, пакет канала stable	Bash	`brew upgrade claude-code`
Homebrew, пакет канала latest	Bash	`brew upgrade claude-code@latest`
WinGet	PowerShell	`winget upgrade Anthropic.ClaudeCode`
npm	Bash или PowerShell	`npm install -g @anthropic-ai/claude-code@latest`

Нативная установка обновляется в рамках выбранного канала выпусков. В Homebrew пакет claude-code следует каналу stable, а claude-code@latest — каналу latest. Поэтому обновление может завершиться успешно, но установленная версия всё равно окажется ниже нужной.

Для существующей нативной установки CLI позволяет установить конкретную версию командой claude install 2.1.310. Если установкой управляет пакетный менеджер, выберите пакет или канал с нужной версией в рамках принятого у вас процесса обновления.

Снова выполните claude --version, затем запустите новую сессию Claude Code. Если номер остался прежним, проверьте конфликтующие установки: в Bash используйте which -a claude, в PowerShell — where.exe claude. Чтобы встроенный терминал редактора увидел изменённый PATH, иногда требуется перезапустить сам редактор.

Определите по тексту ошибки, какой повтор запроса должен сработать

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

В руководстве Anthropic по совместимости шлюзов описаны следующие варианты восстановления:

Признак в ответе	Что делает клиент при повторе	Что проверить
`400` с текстом, начинающимся с `Unexpected value(s)` и указывающим `effort-2025-11-24` для `anthropic-beta`	Убирает поле effort и соответствующий beta-флаг для этой модели до выхода из Claude Code.	Если вы вручную добавили это значение в `ANTHROPIC_BETAS`, удалите его из списка.
`400` с упоминанием `output_config.effort` и текстом `Extra inputs are not permitted` либо сообщением, что effort не поддерживается	Применяет тот же механизм повторного запроса без effort.	Убедитесь, что отклонено именно поле effort.
`400`, например с текстом `Unexpected role "system"`	Переносит системный текст, добавленный в ходе диалога, в пользовательские сообщения. Этот формат сохраняется до `/clear` или сжатия контекста.	Повторите запрос в проблемном диалоге.

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

Воспроизведите ошибку в том же диалоге

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

Сначала запустите Claude Code и выполните /status. В инструкции по подключению к шлюзу описано, как проверить там используемый базовый URL и источник учётных данных. Если нужный шлюз не отображается, исправьте конфигурацию подключения прежде, чем разбираться с поддержкой beta-возможностей.

Затем завершите сессию и снова откройте проблемный диалог с записью локального диагностического лога. В Bash:

claude --resume --debug-file ./claude-gateway-debug.log

Выберите проблемную сессию в списке и повторите минимальный запрос, на котором воспроизводится ошибка. Эти флаги описаны в справочнике CLI.

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

Для BetterToken инструкция по настройке Claude Code указывает ANTHROPIC_BASE_URL=https://bettertoken.ai без /v1; проверяйте обновлённый клиент с этим документированным адресом. Он относится к API: загрузка клиента, сторонние сайты, вход в аккаунты и обновления имеют отдельные условия доступа.

Если обновлённый клиент по-прежнему выдаёт ошибку

Передавайте тело ошибки от сервера, к которому обращается шлюз, без изменений. Если шлюз заменит узнаваемый отказ собственным неинформативным сообщением, клиент может не распознать условие для автоматического повтора. Переменная CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 тоже не решает все такие случаи: она оставляет effort и системные записи внутри диалога.

Дальнейшие действия выбирайте по оставшимся признакам:

Снова приходит один из перечисленных отказов: проверьте запускаемый исполняемый файл, вручную заданные beta-значения и то, не переписывает ли шлюз исходную ошибку.
Не проходит аутентификация: следуйте инструкции своего шлюза. Руководство по подключению различает ANTHROPIC_AUTH_TOKEN для Bearer-аутентификации и ANTHROPIC_API_KEY для x-api-key; используйте схему, которую документирует ваш провайдер.
В ошибке указано другое поле: проверьте требования к совместимости именно этого поля. Не стоит относить любую ошибку схемы запроса к проблеме effort.
Соединение обрывается до получения ответа API: проверьте адрес API, прокси, DNS и TLS.

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

Проверьте, что хуки Windows действительно блокируют вызов

Обновитесь как минимум до 2.1.310, затем воспроизведите сбой тех хуков, которыми вы обеспечиваете соблюдение правил. Два соседних выпуска исправляют разные случаи:

2.1.309 исправляет обработку кодов завершения хуков PowerShell и пропуск операций при отсутствии Git, когда в хуке явно выбран PowerShell.
2.1.310 закрывает дополнительный случай: Git Bash отсутствует, а команда хука состоит только из строк в кавычках.

Ошибка хука сама по себе не означает запрета операции. В справочнике хуков предусмотрен параметр onFailure: "block" для хуков, выполняющих команду или HTTP-запрос: он нужен, когда сбой проверки должен останавливать вызвавшее её действие.

Проверьте ошибку с командой в кавычках

Используйте отдельную тестовую среду с нативной Windows без Git Bash. Подключение Claude Code должно работать, а посторонние хуки и плагины не должны влиять на результат. Так вы проверите режим без Git Bash, сохранив установку Git на рабочей машине.

В PowerShell создайте новый тестовый каталог и безобидный файл:

$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --version

Test-Path должен вернуть False, а версия клиента должна быть не ниже 2.1.310.

Создайте в тестовом каталоге файл .claude/settings.local.json со следующим содержимым:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
          }
        ]
      }
    ]
  }
}

Поля shell, args и onFailure здесь намеренно отсутствуют: на этом этапе проверяется обработка команды из строк в кавычках при выборе оболочки по умолчанию.

Запустите сессию из PowerShell:

claude --tools Read --debug-file .\phase1.log

Подтвердите доверие к созданному тестовому каталогу, затем выполните /hooks и убедитесь, что хук события PreToolUse настроен на Read. Отправьте запрос:

Используй инструмент Read ровно один раз, чтобы прочитать probe.txt. Если вызов заблокирован, сообщи об этом и остановись. Не используй другие способы.

Ожидаемый результат: вызов Read заблокирован, а в ошибке или диагностике присутствует PowerShell started no program. PowerShell обычно воспринимает путь в кавычках как строковое выражение. В документации Microsoft по оператору вызова объясняется, почему для запуска программы по такому пути нужен другой синтаксис.

Если Read действительно прочитал файл, проверка блокировки провалена. Если Claude вообще не попытался вызвать Read, сделать вывод нельзя. Смотрите на результат инструмента и записи в логе, а не только на объяснение модели.

Если /hooks не показывает конфигурацию, выполните проверки загрузки хуков. Настройки обычно перечитываются автоматически, но перезапуск принудительно загрузит их заново, если наблюдатель за файлами пропустил изменение. Если политика организации разрешает только хуки из управляемых настроек, этот проектный тестовый хук также не запустится.

Проверьте отказ при запуске отсутствующего интерпретатора

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

{
  "type": "command",
  "command": "C:\\__claude_hook_probe_missing__\\python.exe",
  "args": [],
  "onFailure": "block"
}

Здесь args включает прямой запуск исполняемого файла. Теперь возникает настоящая ошибка запуска отсутствующего интерпретатора, а не вычисление строкового выражения с путём.

Снова запустите клиент из PowerShell и повторите тот же запрос на чтение:

claude --tools Read --debug-file .\phase2.log

Ожидаемый результат: Read заблокирован, потому что интерпретатор не удалось запустить. Эта проверка подтверждает работу явно заданной политики обработки сбоев независимо от наличия Git Bash. Она проверяет другой механизм, чем предыдущий сценарий с командой в кавычках.

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

Эти два сценария проверяют PreToolUse. Для PermissionRequest нужен отдельный сценарий, в котором операция доходит до этапа запроса разрешения. Штатный отказ задаётся значением "deny" в hookSpecificOutput.decision.behavior; код завершения 2 сам по себе не запрещает операцию на этом событии. При реальном сбое хука параметр onFailure: "block" обеспечивает отказ.

Уберите чрезмерное значение cleanupPeriodDays

Выберите документированное значение по умолчанию — 30 дней, если у команды нет особых требований к хранению. Прежде чем уменьшать уже заданный срок, скопируйте нужную историю в архив.

Исправление очистки устраняет ошибочное удаление недавних файлов при очень больших значениях cleanupPeriodDays. Сам параметр при этом не становится системой архивирования и не восстанавливает уже удалённые файлы.

Сначала сохраните оставшиеся данные

Остановите активные сессии и скопируйте нужные данные в отдельное хранилище вне каталогов, которыми управляет Claude Code. Включите необходимые данные из ~/.claude, или %USERPROFILE%\.claude в Windows, а также сохранившиеся изображения-вложения.

В актуальной документации о данных приложения указано, что новые вставленные изображения хранятся в каталогах images/ отдельных сессий под временным корневым каталогом Claude Code. Его расположением управляет CLAUDE_CODE_TMPDIR. Поэтому копия одного лишь ~/.claude ещё не подтверждает, что текущие копии изображений сохранены.

Скопировав данные, внесите это значение в нужный файл настроек:

{
  "cleanupPeriodDays": 30
}

Для личных настроек по умолчанию используйте ~/.claude/settings.json, или %USERPROFILE%\.claude\settings.json в Windows. Сохраните остальные ключи этого файла.

По документации на 2026-10-25 минимальное значение — 1; 0 не проходит проверку настроек. После уменьшения срока более старые данные могут попасть под очистку, поэтому копии нужно сделать заранее.

Выполните claude doctor, чтобы проверить корректность настроек. Если нужное значение не применяется, разберитесь с приоритетом источников настроек: управляемые настройки организации и более приоритетные параметры сессии или проекта могут переопределять личный файл. /status показывает загруженные источники, но не итоговое значение каждого отдельного ключа.

Восстанавливайте пропавшие вложения отдельно

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

Изменение срока хранения не вернёт удалённые байты. Не стоит рассчитывать и на /rewind: снимки файлов для контрольных точек тоже удаляются по сроку хранения, и без нужных снимков восстановление может не сработать.

Если у вас уже настроен экспорт телеметрии, найдите событие claude_code.retention_sweep завершённого прохода очистки. В справочнике мониторинга описаны result: "complete" и строковый атрибут period_days; значение "30" подтверждает, что именно этот проход использовал срок 30 дней.

Короткая сессия после перезапуска ещё не доказывает, что очистка состоялась. Она выполняется в фоне не чаще одного раза за сессию. Если на той же машине очистка уже запускалась в течение предыдущих 24 часов, её запуск в новой сессии откладывается как минимум на 10 минут. Проверяйте доступность вложений и факт завершения прохода очистки как два отдельных результата.

Доступность Monitor изменилась отдельно

Версия 2.1.310 также делает инструмент Monitor и мониторы плагинов доступными на Bedrock, Vertex и Foundry, в том числе при отключении телеметрии или необязательного сетевого трафика. В описании выпуска также указано, что длительные паузы ожидания на переднем плане теперь блокируются и в этих конфигурациях.

Если Monitor отсутствовал в одном из таких развёртываний, проверьте запускаемую версию прежде, чем менять политику телеметрии. Это изменение доступности не определяет, принимает ли конкретный шлюз настройки effort или системные записи внутри диалога.