Как восстановить Claude Code: safe mode и диагностика сбоев

Практические материалы по работе с ИИ-инструментами — в документации Ailoot.

Что нового появилось в Claude Code в июне 2026 года?#

Если Claude Code зависает, закрывается при запуске, перестаёт учитывать CLAUDE.md или пропускает hook, раньше приходилось вручную менять .claude/settings.json, отключать MCP-серверы по одному, а иногда удалять ~/.claude и устанавливать всё заново. В одном описанном случае после удаления ~/.claude пришлось восстанавливать настройки MCP-серверов, на которые ушло полтора часа. Позже обнаружилось, что причиной была одна строка в CLAUDE.md, которую можно было найти за несколько секунд.

В июне 2026 года Anthropic выпустил три функции, меняющие порядок такой диагностики:

Ниже разберём каждую функцию и последовательность действий при сбое Claude Code.

Из-за чего чаще всего возникают сбои Claude Code?#

В одном описанном примере начальная версия CLAUDE.md содержала 80 строк и работала около месяца. Затем Claude стал регулярно нарушать инструкции: обращался к .env, выполнял git push --force и заходил в node_modules. Однажды был удалён .gitignore, а источник проблемы сразу не обнаружился. Подробнее о таких инструкциях рассказывает руководство по CLAUDE.md.

Когда CLAUDE.md превышает 400 строк, важные указания могут теряться среди второстепенных, а сам файл занимает значительную часть контекстного окна в начале сессии. Claude продолжает читать его, поэтому причина может выглядеть как случайное несоблюдение правил.

Ещё один источник проблем — hooks. Важно учитывать разницу между кодами завершения в Claude Code hooks:

То есть sys.exit(1) в Python-hook или обычный для Unix сигнал ошибки сам по себе не остановит Claude. Блокирующим считается код 2. В одном описанном случае hook задумывался как строгий запрет, но лишь записывал сообщение и позволял действию продолжиться.

MCP-серверы составляют ещё один возможный источник сбоев. Часто команды MCP остаются доступными, но отвечают failed, не выводя traceback. Если вы настраиваете MCP через claude mcp add, подробности есть в отдельном руководстве.

На поведение также влияет иерархия настроек: ~/.claude/settings.json на пользовательском уровне, .claude/settings.json в проекте, .claude/settings.local.json и, если они заданы администратором организации, управляемые настройки. Значения объединяются с учётом приоритетов. Например, запись MCP-сервера в настройках проекта может конфликтовать с пользовательской записью, запускающей тот же сервер иначе.

Что отключает параметр --safe-mode?#

В журнале изменений Anthropic для v2.1.169 описана возможность запустить Claude Code с отключёнными настройками CLAUDE.md, плагинами, skills, hooks и MCP-серверами, чтобы диагностировать сбой.

В руководстве Anthropic по настройке моделей также рекомендуется запустить claude --safe-mode, если нужно выяснить, вызвана ли проблема пользовательскими настройками. Согласно этому руководству, Git-статус и имена каталогов не считаются такими настройками и остаются доступными.

Safe mode — средство диагностики, а не полностью изолированная среда. Он помогает проверить, связана ли проблема со стандартной работой Claude Code или с добавленными настройками. Если в этом режиме всё работает, проверяйте надстройки по одной. Если сбой остаётся, проверьте установку, авторизацию, сеть и журналы, а также запустите claude doctor.

В официальном описании Anthropic к отключаемым слоям относятся:

• CLAUDE.md на пользовательском и проектном уровнях
• Плагины
• Skills
• Hooks
• MCP-серверы

В safe mode сохраняются:

• Авторизация через OAuth-сессию или API-ключ
• Выбор модели, например --model sonnet или --model opus
• Встроенные инструменты, в том числе Read, Write, Bash и Grep
• Разрешения
• Git-статус
• Имена каталогов

Учтите, что корпоративные управляемые настройки и политики не отключаются. Например, заданные через Bedrock GovCloud или MDM ограничения на availableModels останутся в силе: safe mode затрагивает пользовательские настройки, но не корпоративную политику.

Как за минуту найти проблемный слой?#

Для описанных ниже действий требуется Claude Code v2.1.169 или новее. Если установлена более ранняя версия, обновите её командой npm update -g @anthropic-ai/claude-code или воспользуйтесь нативным установщиком Anthropic.

1. Откройте каталог, в котором возникла проблема.
2. Запустите claude --safe-mode.
3. Повторите запрос, вызвавший сбой. Если теперь всё работает, вероятная причина находится в одном из отключённых слоёв. Перейдите к следующему пункту.
4. Если проблема сохраняется и в safe mode, пока не меняйте конфиги. Запустите claude doctor и проверьте авторизацию, версию и наличие нескольких установок.

Если safe mode помог, включайте слои по одному, начиная с наиболее вероятного:

1. CLAUDE.md. Запустите Claude без safe mode, временно переименовав файл: mv CLAUDE.md CLAUDE.md.bak. Если проблема исчезла, проверьте содержимое файла. Можно разделить его на части и проверять по одной половине.
2. Hooks. В .claude/settings.json временно задайте пустой список [] для секции hooks. Перезапустите claude. Если сбой исчез, возвращайте hooks по одному.
3. MCP-серверы. В ~/.claude.json или .claude/settings.json временно задайте для mcpServers пустой объект. Перезапустите Claude и проверьте результат.
4. Skills. Переместите .claude/skills/ во временный каталог, затем перезапустите Claude и проверьте поведение.

При временном отключении конфиги не удаляются. Команды mv и git stash позволяют вернуть прежнее состояние, если проверяемый слой не оказался причиной.

Как сменить рабочий каталог командой /cd, сохранив контекст?#

В журнале изменений Anthropic от 8 июня 2026 года указано, что команда /cd позволяет переключить сессию на новый рабочий каталог без сброса prompt cache.

Предположим, Claude Code работает некорректно в ~/work/myapp. Раньше для проверки приходилось завершить сессию, перейти в другой каталог и запустить Claude снова — вместе с сессией терялись её контекст, история и прогретый prompt cache. Теперь можно выполнить команду в той же сессии:

# Прямо в той же сессии:
/cd ~/sandbox/test

Claude перейдёт в новый каталог и, если там есть CLAUDE.md, прочитает его как сообщение, не заменяя system prompt. Благодаря этому prompt cache сохраняется. Если в ~/sandbox/test всё работает, неисправность может быть связана с настройками ~/work/myapp.

В v2.1.176 от 12 июня исправили проблему, из-за которой после /cd отображалась прежняя ветка Git. Если у вас более ранняя версия, обновите Claude Code. До обновления учитывайте, что после переключения сведения в git status могут обновиться не сразу.

Как задать резервные модели на случай ошибки 529?#

Представьте, что вы запустили продолжительную задачу на Opus и через десять минут получили ошибку 529 Overloaded. Раньше оставалось ждать или вручную выбирать Sonnet с помощью --model sonnet, начиная работу заново с новым контекстом. Если проект большой и включает каталог business/ со структурой второго мозга, восстановление рабочего контекста может занять около двадцати минут.

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

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

Настроить цепочку можно через CLI:

claude --fallback-model sonnet,haiku

Или в ~/.claude/settings.json:

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

Ошибки 429 не запускают цепочку резервных моделей. Anthropic сохраняет обычную логику повторов и задержек для таких ошибок, чтобы переключение моделей не использовалось для обхода ограничения частоты запросов. Fallback предназначен для случаев перегрузки, недоступности основной модели и некоторых серверных ошибок, например 529 Overloaded.

В v2.1.174 от 12 июня 2026 года также исправили ситуацию, когда compaction не учитывал --fallback-model. Если вы используете длинные сессии с /compact или оставляете /loop работать на ночь, используйте версию не ниже v2.1.174.

Как устранить причину, если виноваты CLAUDE.md, hook, MCP или skill?#

Если проблема связана с CLAUDE.md

Проверьте длину файла. По приведённой рекомендации, активный CLAUDE.md лучше ограничить 200 строками, а дополнительные инструкции вынести в связанные документы проекта. Структура второго мозга описана в руководстве по второму мозгу. Если файл содержит более 400 строк, проверьте, не он ли вызывает проблему:

1. Сохраните копию: cp CLAUDE.md CLAUDE.md.full.
2. Временно замените файл коротким рабочим шаблоном. Пример приведён в руководстве по настройке CLAUDE.md.
3. Перезапустите Claude Code и проверьте поведение.
4. Если всё работает, добавляйте инструкции небольшими блоками по 10–20 строк и проверяйте результат после каждого блока.
5. Найдя проблемный фрагмент, при необходимости перенесите соответствующий запрет в hook и задайте ему подходящий код завершения. Подробнее об этом — в следующем подразделе.

Если проблема связана с hook

Проверьте код завершения hook в Claude Code:

• Код 0 — действие считается успешным и продолжается.
• Код 1 — ошибка не блокирует действие; Claude продолжает работу.
• Код 2 — ошибка блокирует действие.

Если в shell-hook или Python-скрипте используется exit 1 либо sys.exit(1) с расчётом остановить Claude, измените логику с учётом того, что такой код не блокирует действие. Для блокировки используется код 2. Подробная инструкция по настройке hooks приведена в отдельном руководстве.

Hook может также выводить в stdout невалидный JSON. Если Claude Code ожидает JSON, посторонний текст, сообщения о ходе выполнения или эмодзи могут помешать разбору ответа. Оставляйте в stdout только JSON, а прочие сообщения направляйте в stderr.

Если hook пытается прочитать данные в ~/.claude/, недоступные в safe mode, проверьте, запущен ли этот режим. Например, в начале скрипта можно проверить os.environ.get('CLAUDE_CODE_SAFE_MODE') и завершить работу с кодом 0.

Если проблема связана с MCP-сервером

Если команды MCP видны, но возвращают failed без понятного traceback, действуйте так:

1. Выполните claude mcp list, чтобы посмотреть определённые серверы.
2. Отключайте их по одному в ~/.claude.json: например, временно переименуйте ключ claude-server-A в _claude-server-A.
3. Перезапустите claude и проверьте, какие команды работают.
4. Определив сервер, изучите его журнал командой claude mcp logs <name>.
5. Если сервер поддерживается сторонним проектом, например @modelcontextprotocol/server-postgres, проверьте наличие более свежей версии.

Если Claude Code закрывается при запуске, попробуйте повторить запуск в safe mode без MCP-серверов и сравните результат.

Если проблема связана со skill

Skill включает файл SKILL.md и код в .claude/skills/<name>/. Возможные признаки: Claude не применяет skill, запускает его не в подходящий момент или выдаёт неподходящий результат. Проверьте следующее:

1. Откройте SKILL.md и изучите поле description. В нём следует кратко, в одном-двух предложениях, конкретно указать, когда применять skill. Неопределённое описание вроде «универсальный помощник для всего» затрудняет выбор момента запуска.
2. Сопоставьте инструкции skill с CLAUDE.md. Например, требование всегда писать тесты может конфликтовать с описанием skill для быстрого прототипирования без тестов.
3. Если skill запускает внешние команды, например npm, python или git, проверьте, доступны ли они в системном PATH.

Если safe mode не помог: диагностика и сохранение состояния до исправления#

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

1. Выполните claude doctor. Anthropic рекомендует запустить эту команду для автоматического диагностического отчёта, если claude --version работает, но другие функции ведут себя неправильно.

2. Проверьте, нет ли нескольких установок. Одновременное наличие глобальной npm-версии и нативного установщика может привести к несовпадению версий или неожиданному поведению.

3. Убедитесь, что ANTHROPIC_API_KEY не подменяет OAuth-авторизацию. Если эта переменная задана и подтверждена, Claude Code использует API-ключ вместо OAuth-учётных данных подписки.

Чтобы проверить текущую сессию оболочки, выполните unset ANTHROPIC_API_KEY. Если переменная задаётся в ~/.zshrc или ~/.bashrc, удалите её оттуда при необходимости.

4. Исправляйте только установленную диагностикой копию программы; сначала сохраните всё состояние пользователя. Сбой safe mode или неясный doctor не доказывают необходимость удаления данных. Остановите сессии Claude и другие процессы записи перед согласованной копией. Сохраните Unix-пользователя, HOME, хранилище учётных данных ОС и аккаунт Anthropic. Не меняйте ключи и не создавайте новую личность.

Пример ниже предназначен для Linux с GNU tar. В macOS и Windows нужен инструмент, сохраняющий ACL, расширенные атрибуты, ссылки и метаданные платформы, с проверкой восстановления. Не считайте GNU-флаги переносимыми. Архив содержит ключи и историю сессий: храните его приватно вне репозиториев.

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

Все команды должны завершиться успешно. Копируется всё существующее дерево .claude, включая игнорируемые сессии и плагины, а также .claude.json, не только отслеживаемые Git настройки. Если путь — символическая ссылка или данные вынесены в другую настроенную папку, остановитесь и включите разрешённую цель в ту же проверенную копию: архив ссылки не сохраняет её содержимое. Архив не содержит macOS Keychain и другие внешние хранилища авторизации; сохраните их прежнюю личность.

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

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

Удаляйте npm-установку только при подтверждённом конфликте и намерении сохранить нативную. Затем используйте официальный нативный установщик без удаления .claude и .claude.json:

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

В Windows нативная команда:

irm https://claude.ai/install.ps1 | iex

Восстановление выполняйте отдельно. Снова остановите процессы записи. Проверьте контрольную сумму и извлеките архив в пустую папку, затем успешно сравните, как выше. Для возврата перемещённой установки сначала подтвердите отсутствие $HOME/.claude/local и только затем верните $backup_dir/legacy-local по этому точному пути. Диагностированный файл настроек восстанавливайте из проверенного извлечения, сохранив нынешнюю замену. Не накладывайте всё дерево вслепую. Сессии, MCP и прежняя личность сохраняются. Одного Git-снимка недостаточно для игнорируемых бесед, ключей и метаданных файловой системы.

Чего избегать при сбое Claude Code?#

Не меняйте ключи до диагностики

Если авторизация не работает, сначала проверьте, не переопределяет ли ANTHROPIC_API_KEY OAuth-сессию, не отображает ли интерфейс ошибку hook и не завершился ли MCP-сервер. Ротация ключей эти причины не устранит, зато потребует отозвать старый ключ, выпустить новый и обновить его в CI и производственных переменных. Начните с claude --safe-mode. Если он работает, проверяйте надстройки, не меняя ключи.

Не начинайте с полного сброса

Удаление .claude может уничтожить сессии, MCP и другие неотслеживаемые данные. Сначала диагностика и проверенная приватная копия. Обратимо перемещайте только действительно затронутый слой установки или конфигурации.

Не делайте вывод по сообщению об ошибке hook в интерфейсе

Перед исправлением проверьте, действительно ли hook выполнялся: добавьте запись в stderr или явный вывод. Это поможет отличить сбой hook от неверного индикатора в интерфейсе.

Не меняйте код завершения hook, не проверив его логику

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

Не меняйте рабочий CLAUDE.md без возможности проверить настройки

Если после правки Claude начал вести себя иначе, параллельно могли измениться MCP-серверы или hooks. Перед откатом проверьте ту же задачу в safe mode. Если проблема сохраняется, она может быть связана с другим слоем, а не с изменённой инструкцией.

Не поручайте Claude самостоятельно переписывать сломанный конфиг MCP

Типичный сценарий: вы просите Claude добавить инструмент на MCP-сервер, он переписывает рабочую конфигурацию, после чего команды перестают работать. Затем несколько ходов уходит на исправление вызванной им же проблемы, расходуя квоту сессии. При сбое MCP сохраните и проверьте конфиг вручную: инструменты для диагностики тоже могут зависеть от MCP.

Что сделать после восстановления Claude Code?#

Перед возвращением к обычной работе стоит предусмотреть защиту от повторных сбоев. Восстановление структуры проекта и инструкций CLAUDE.md может потребовать много времени. Минимальный набор настроек:

1. В ~/.claude/settings.json установите permissions.disableBypassPermissionsMode: "disable", чтобы отключить режим обхода разрешений и предотвратить запуск с --dangerously-skip-permissions.
2. Настройте hooks для защиты от чтения Read(./env*), команды Bash(git push --force) и записи в Write(./node_modules/**).
3. Подготовьте конфигурацию sandbox для длительных автономных задач с /loop или /schedule.
4. Определите правила /compact, чтобы контролировать, какие сведения удаляются из контекста.

Подробнее о четырёх слоях защиты рассказывает руководство по настройке Claude Code для ночной работы над проектом. Оно дополняет это руководство: одно посвящено профилактике, другое — восстановлению после сбоя.

Практические материалы по работе с ИИ-инструментами доступны в документации Ailoot.

Больше материалов и инструментов — на сайте Ailoot.