Устранение неполадок (FAQ / Troubleshooting)
📚 Навигация по серии: Предыдущая статья 50 Антипаттерны: распространенные ошибки использования подробно разобрала ловушки, которые выглядят разумно, но на деле вредят вам. Эта статья сфокусирована на поиске неисправностей — как найти и устранить первопричину, если Claude Code работает со сбоями. Проблемы с установкой или входом, блокировки прав, неработающий MCP, медленная работа или сообщения об ошибках в консоли — здесь вы найдете руководство «симптом → куда смотреть и что делать».
Начнем с очень типичного сценария, в который легко попасть. Поняв его, вы поймете, какую проблему решает эта статья.
Представьте ситуацию: вы только что перешли на новый Mac, установили Claude Code для рабочего проекта, а при запуске сразу получаете ошибку This organization has been disabled. Первая мысль: «Все пропало, аккаунт заблокировали!». Вы спешно заходите на claude.ai проверить подписку — все в порядке, план Max активен. Затем вы думаете на сеть, настраиваете прокси, пробуете снова — и видите то же сообщение. Провозившись так почти сорок минут и дважды переустановив Claude Code, вы уже готовы писать в поддержку.
А в чем была первопричина? При переносе настроек со старого Mac в файле ~/.zshrc осталась строчка export ANTHROPIC_API_KEY=..., о которой вы давно забыли. Это был старый ключ полугодовой давности от уже закрытого проекта. Приоритет переменной среды оказался выше авторизации по подписке, и Claude Code добросовестно использовал этот недействительный ключ для аутентификации, в ответ на что сервер сообщал о блокировке организации. Всего одна команда unset ANTHROPIC_API_KEY — и всё заработало за секунду.
Я привел этот пример, чтобы вы запомнили главное правило: никогда не пытайтесь угадать причину неисправности. Те сорок минут ушли на пустые догадки — проблемы с аккаунтом, сетью и т.д. Чем больше вы гадаете, тем дальше уходите от истины. На самом деле в Claude Code встроен инструмент самодиагностики. Команда /status сразу покажет, какие учетные данные используются в данный момент. Угадывать ничего не нужно. В этой статье мы научимся локализовать проблемы строго по алгоритму.
После прочтения этой статьи вы получите:
- Общую таблицу маршрутизации «симптом → решение»: сначала сопоставьте ошибку, не пробуйте всё подряд
- Две важнейшие команды для самопомощи:
/doctorдля диагностики и/feedbackдля отправки отчетов — и правила их применения - Разделы «проблема → решение», сгруппированные по шести категориям (установка, авторизация, права доступа, MCP, производительность, сообщения об ошибках)
- Инструкции по использованию флагов отладки
--debugи главный секрет поиска багов — метод чистой конфигурации - Практическое задание с ожидаемыми результатами: проведение самодиагностики с помощью
/doctor
01 Главное правило: определите категорию проблемы, а не гадайте
Сразу к главному выводу, который важнее любых команд: столкнувшись с проблемой, не спешите ее чинить. Сначала поймите, к какой категории она относится: установка, авторизация, конфигурация или сбой на стороне API. Неверно определив категорию, вы потратите время впустую.
Аналогия: при протечке сначала перекройте вентиль, а не ломайте плитку. Опытный сантехник не начнет крушить стены при виде влаги. Он сначала выяснит источник: течет ли смеситель, пробито ли соединение труб или вода капает от соседей сверху. Если ошибиться на этом шаге, можно разломать весь пол и так и не найти течь. С Claude Code всё точно так же: сначала диагностика, потом действия.
Почему это так важно? Потому что официальная документация по Claude Code разделена именно по категориям: страница установки и авторизации, страница ошибок выполнения, отладки конфигурации, производительности. Не зная категорию, вы даже не будете знать, какую страницу документации открыть. В начале официального руководства по устранению неполадок приводится таблица маршрутизации. Вот ее адаптированный перевод с наиболее частыми симптомами:
| Симптом | Категория проблемы / Куда обратиться |
|---|---|
command not found: claude, ошибки при установке, проблемы с PATH, EACCES | Установка (подробнее в Статье 02 + Раздел 02 этой статьи) |
Бесконечные запросы авторизации, 403 Forbidden, organization disabled | Авторизация и вход (Раздел 03 этой статьи) |
| Настройки не применяются, хуки не запускаются, MCP-серверы не загружаются, правила доступа не работают | Конфигурация (Раздел 04 этой статьи + Отладка конфигурации) |
API Error: 5xx, 529 Overloaded, 429 | Ошибки API (Раздел 06 этой статьи, обычно это сбой на стороне сервера) |
model not found / you may not have access to it | Ошибки моделей (Раздел 06 этой статьи, неверная модель или отсутствие прав) |
| Зависания, высокая загрузка CPU / памяти, файлы не находятся через поиск | Производительность (Раздел 05 этой статьи) |
Пользоваться таблицей очень просто: найдите в левой колонке фразу, похожую на вашу ошибку, а в правой колонке вы увидите направление для поиска. В последующих разделах этой статьи мы детально разберем каждую категорию.
Важная цитата из официального руководства: «Если вы не уверены, какая категория подходит, запустите команду
/doctorвнутри сессии Claude Code. Она автоматически проверит вашу установку, конфигурацию, MCP-серверы и объем используемого контекста. Еслиclaudeвообще не запускается, выполните командуclaude doctorв вашей консоли (shell)».
Другими словами, если вы не можете определить категорию ошибки — не гадайте, просто запустите /doctor. Эта команда укажет вам нужное направление. В следующем разделе мы подробно разберем работу этих команд самопомощи.
💡 Краткий вывод: Первым делом всегда определяйте категорию проблемы и не пробуйте всё подряд. Найдите симптом в таблице маршрутизации и переходите к нужному разделу. Если сомневаетесь — запустите
/doctor.
02 Команды самопомощи: /doctor для диагностики и /feedback для отчетов
Перед тем как искать ответы на форумах или обращаться к коллегам, воспользуйтесь встроенными инструментами Claude Code. В 90% случаев команда /doctor укажет на причину сбоя, а если решить проблему не удастся, вы сможете отправить отчет с помощью /feedback. Освоив эти две команды, вы сэкономите массу времени.
Аналогия: при недомогании сначала пройдите обследование. Ни один врач не начнет операцию без результатов анализов — показатели давления, пульса и крови сразу укажут на очаг воспаления. Команда /doctor — это диагностический сканер для Claude Code: одна команда проверит состояние установки, корректность конфигурационных файлов, доступность MCP-серверов и объем используемого контекста.
/doctor: Диагностика в один клик
Команда /doctor — это первое, что нужно запустить при возникновении неполадок. Она проверяет: состояние установки, корректность настроек (наличие неизвестных ключей, ошибок валидации схемы JSON), доступность MCP-серверов и объем контекста.
Как запустить команду:
- Если сессия запускается: введите
/doctorпрямо в окне Claude. - Если
claudeне запускается вовсе (например, выдаетcommand not foundили падает на старте): выполнитеclaude doctorв вашей консоли (shell) — обратите внимание, что эта команда пишется без косой черты (/), так как это независимая консольная команда.
У /doctor есть удобная функция: если обнаружены ошибки, вы можете нажать f, чтобы отправить диагностический отчет в текущую сессию Claude, и искусственный интеллект поможет вам исправить их шаг за шагом. Это похоже на то, как врач комментирует результаты ваших анализов прямо на приеме.
/feedback: Если ничего не помогло, отправьте отчет
Если вы изучили документацию, выполнили /doctor, но ошибка не исчезла — не тратьте время на бесплодные попытки, используйте /feedback для отправки отчета в Anthropic. Это передаст историю диалога и ваше описание проблемы. Для сложных случаев (например, если модель начала выдавать некачественные ответы без явных ошибок в консоли) это самый быстрый способ получить помощь. Команда также может автоматически создать черновик issue на GitHub с заполненными данными. Обратите внимание: если вы используете сторонних провайдеров (Bedrock, Vertex), команда /feedback сохранит лог локально, и вам нужно будет отправить его менеджеру вашего аккаунта вручную.
Ранее использовалась команда
/bug. Теперь она устарела и заменена на/feedback. Запомните именно ее для отправки логов и описания ошибок разработчикам.
Таблица выбора команд самопомощи:
| Ситуация | Используйте команду | Что она делает |
|---|---|---|
| Непонятна категория проблемы | /doctor | Проводит диагностику и указывает направление |
claude не запускается | claude doctor (в терминале) | Запускает проверку до старта приложения |
/doctor нашел ошибку, нужна помощь | Нажмите f в выводе /doctor | Передает отчет в сессию Claude для разбора |
| Документация не помогла | /feedback | Отправляет историю сессии и описание в Anthropic |
| Подозрение на сбой серверов | Откройте в браузере status.claude.com | Показывает статус доступности API |
Адрес status.claude.com стоит выписать отдельно. При получении ошибок вида 5xx или 529 первым делом проверьте эту страницу, не пытаясь перенастраивать клиент. Чаще всего это означает временные сбои на стороне Anthropic, и ваши настройки тут ни при чем. Мы подробнее поговорим об этом в Разделе 06.
💡 Краткий вывод: Начните отладку с двух команд:
/doctor(илиclaude doctorв консоли) для общей диагностики и/feedbackдля отправки отчетов при сложных сбоях. При подозрении на падение серверов проверяйтеstatus.claude.com.
03 Авторизация и вход: Бесконечные запросы входа, блокировка организации
Начнем разбор по категориям. Первая группа — авторизация. Эти ошибки пугают новичков больше всего из-за страшных слов вроде disabled, Forbidden, revoked, хотя реальная причина обычно банальна.
Аналогия: пропуск не срабатывает на турникете. Это не значит, что вас уволили. Возможно, карта размагнитилась, вы случайно взяли старый бейдж или сбились часы на турникете. Ошибка доступа не означает отсутствие прав. В случае проблем с авторизацией: сначала выясните, с какими учетными данными Claude Code обращается к серверу, а не паникуйте сразу.
Шаг 1: Проверьте текущие учетные данные
Это универсальный шаг для отладки входа, который сэкономил бы сорок минут из нашего примера. Введите в окне Claude:
/statusОжидаемый результат: Команда выведет текущий активный метод авторизации — OAuth (подписка) или конкретный API-ключ. Если у вас оформлена подписка, но в выводе указан API-ключ, причина проблемы найдена.
Классический баг: переменная ANTHROPIC_API_KEY перекрывает подписку
Именно на этом попался разработчик в нашем примере. Официальное правило приоритетов гласит:
Переменные среды имеют приоритет перед командой
/login. Таким образом, ключ, экспортированный в конфигурационном файле вашей оболочки (shell) или загруженный из файла.env, будет использоваться даже при наличии активной подписки Pro или Max. В неинтерактивном режиме (-p) при наличии ключа всегда используется именно он.
Поэтому, если в окружении объявлена переменная ANTHROPIC_API_KEY (допустим, это старый забытый ключ из прошлогоднего проекта), Claude Code будет использовать ее. Если этот ключ недействителен или принадлежит заблокированной организации, вы увидите ошибку This organization has been disabled. Решение:
unset ANTHROPIC_API_KEY
claudeКоманда unset действует только в рамках текущей сессии терминала. Для окончательного решения удалите строку export ANTHROPIC_API_KEY=... из файлов ~/.zshrc, ~/.bashrc или ~/.profile (в Windows проверьте переменные среды пользователя и профиль PowerShell $PROFILE). После удаления перезапустите claude и выполните /status для проверки. Эти приоритеты подробно описаны в Статье 04 (настройка API).
Решение других частых ошибок авторизации
| Ошибка | Значение | Как исправить |
|---|---|---|
Not logged in · Please run /login | В сессии отсутствуют валидные учетные данные | Запустите команду /login; если используете переменные среды, убедитесь, что ANTHROPIC_API_KEY экспортирован |
OAuth token revoked / has expired | Сохраненный токен авторизации недействителен | Повторно выполните /login; если ошибка повторяется, сделайте сначала /logout, а затем /login |
| Бесконечные запросы авторизации при каждом запуске | Токен постоянно сбрасывается | Проверьте системное время (проверка токенов критична к системному времени); в macOS это также может быть вызвано блокировкой Keychain, запустите claude doctor для проверки доступа к Keychain |
403 Forbidden (после авторизации) | Проблема с подпиской, ролями или прокси | Для подписок Pro/Max проверьте статус на claude.ai/settings; для пользователей Console убедитесь, что у вашего аккаунта есть роль Claude Code или Developer |
Invalid API key | Ключ API отклонен сервером | Проверьте написание ключа, убедитесь, что он не отозван в консоли управления; выполните `env |
Совет о проверке системного времени при постоянных запросах авторизации очень важен. На виртуальных машинах без доступа к интернету время часто отстает на пару дней, из-за чего выданный токен сразу же признается сервером просроченным. Синхронизируйте время, и проблема решится.
💡 Краткий вывод: При ошибках авторизации сначала выполните
/status, чтобы узнать используемые учетные данные. Самая частая проблема — оставшийся в shell ключANTHROPIC_API_KEY, который перекрывает подписку (используйтеunsetи отредактируйте конфигурационный файл). При сбросе авторизации проверяйте системное время и доступ к macOS Keychain.
04 Конфигурация: Настройки, хуки или MCP не применяются
Вторая категория проблем — игнорирование настроек. Вы прописали правила в settings.json, настроили хуки или добавили MCP-сервер, но Claude делает вид, что этих изменений нет. В документации этому посвящена страница «Отладка конфигурации». Главный принцип здесь: убедитесь в том, что именно загрузил Claude Code на самом деле, не полагаясь на то, что вы просто написали правила в файл.
Аналогия: сдать тетрадь с домашней работой не значит передать ее учителю. Вы могли положить ее не на тот стол, вложить в чужую тетрадь или ее закрыли другой папкой. С настройками то же самое: если они не работают, сначала проверьте, какой файл был прочитан клиентом, вместо того чтобы бесконечно редактировать тот, который вы считаете верным.
Команды для проверки загруженной конфигурации
Этот набор команд поможет узнать состояние различных компонентов конфигурации:
| Команда | Что проверяет |
|---|---|
/context | Объем и состав текущего контекста (системный промпт, файлы в памяти, Skills, инструменты MCP, сообщения) |
/memory | Загруженные файлы CLAUDE.md и файлы правил |
/skills | Доступные Skills из проекта, настроек пользователя или плагинов |
/agents | Сконфигурированные субагенты (subagents) и их параметры |
/hooks | Зарегистрированные в текущей сессии хуки |
/mcp | Подключенные MCP-серверы и их текущий статус |
/permissions | Действующие правила разрешений и запретов доступа |
/debug [описание проблемы] | Включает логирование отладки для сессии и просит Claude использовать эти логи для диагностики |
/status | Активные источники настроек (включая использование управляемых настроек) |
Правило использования простое: если настройка не работает, запустите соответствующую команду для проверки. Например, если не срабатывает хук, проверьте /hooks, чтобы убедиться в его регистрации. Если хука нет в списке — файл не был прочитан; если он есть, но не работает — проблема в регулярном выражении совпадения (matcher).
Типичные ошибки конфигурации новичков
Вот список самых частых ошибок настройки, взятый из официального руководства:
| Симптом | Возможная причина | Как исправить |
|---|---|---|
| Хук никогда не срабатывает | matcher написан в нижнем регистре (например, "bash") | Имена инструментов чувствительны к регистру и начинаются с заглавной буквы: Bash, Edit, Write, Read |
| Хук никогда не срабатывает | Хук вынесен в отдельный файл | Хуки проекта или пользователя должны располагаться внутри ключа "hooks" файла settings.json |
Настройки из settings.json игнорируются | Тот же ключ задан в файле settings.local.json | Параметры в settings.local.json переопределяют значения из settings.json, а оба они перекрывают глобальный ~/.claude/settings.json (подробнее в Статье 31) |
MCP-серверы из .mcp.json не загружаются | Файл сохранен внутри папки .claude/ | Конфигурация MCP проекта должна находиться в файле .mcp.json в корневом каталоге репозитория, а не в .claude/ |
| MCP-серверы проекта отсутствуют в списке | Было отключено всплывающее окно однократного подтверждения | Серверы уровня проекта требуют подтверждения запуска, выполните /mcp для проверки статуса и одобрения (подробнее в Статье 22) |
Правила CLAUDE.md во вложенных папках не работают | Они загружаются «по запросу» | Файлы правил во вложенных каталогах считываются только при использовании инструмента Read для этой папки, а не при старте клиента (подробнее в Статье 18) |
Ошибка с регистром в поле matcher для хуков случается очень часто. Вы создаете хук PostToolUse, указываете matcher "edit|write", но он не запускается при редактировании. Выполнив /hooks, вы видите хук в списке и не понимаете, в чем дело, пока не вспомните, что имена инструментов пишутся с заглавной буквы: "Edit|Write". Официальная цитата: «Сопоставление чувствительно к регистру». Подобные скрытые нюансы могут отнять много времени на поиск причин, если о них не знать заранее.
Права доступа: «Я настроил правила, почему они не работают / меня постоянно спрашивают подтверждение?»
Вопросы прав доступа (permissions) также относятся к категории настроек. Вы можете столкнуться с двумя ситуациями:
Первая: «Инструкции-запреты из CLAUDE.md не работают». Важное понимание: фраза «никогда не изменяй файл .env» в CLAUDE.md — это лишь «просьба», а не «гарантия». Разработчики подчеркивают: CLAUDE.md направляет решения Claude, но жесткие ограничения, которые должны соблюдаться в любом случае, настраиваются через правила доступа или хуки (подробнее в Статьях 20 и 21). Если вам нужно гарантированно запретить операцию, не полагайтесь на CLAUDE.md, используйте правила deny или хуки PreToolUse.
Вторая, более сложная: правила deny не блокируют аналогичные команды. Например, вы запретили команду Bash(rm *), чтобы избежать удаления файлов, но Claude может вызвать /bin/rm или find . -delete и обойти запрет. Причина в том, что правила префиксов анализируют текстовую строку команды, а не запускаемый исполняемый файл. Для защиты необходимо прописать все возможные варианты команд либо использовать хук PreToolUse или песочницу (sandbox) для надежного контроля. Для отладки прав запустите /permissions и сверьтесь со списком активных правил.
Это иллюстрирует тот же антипаттерн из Статьи 50: попытка выстроить контур безопасности на основе текстовых инструкций на естественном языке не работает. Инструкции носят рекомендательный характер, тогда как правила и хуки обеспечивают принудительное исполнение.
💡 Краткий вывод: Если настройки не применились, используйте
/context,/memory,/hooks,/mcpи/permissionsдля проверки фактически загруженной конфигурации. Типичные ошибки: неверный регистр букв в matcher для хука, перезапись параметров файломsettings.local.json, сохранение.mcp.jsonне в той папке или попытка задать жесткие запреты в CLAUDE.md вместо правилdeny.
05 Производительность: Медленная работа, нехватка памяти, проблемы поиска
Третья группа проблем — производительность. Медленные ответы, утечки памяти или отсутствие автодополнения для @file. Большинство таких сбоев вызваны переполнением окна контекста или мелкими ошибками окружения, а не багами в коде клиента.
Аналогия: компьютер начинает тормозить из-за обилия открытых в фоне программ. При первых зависаниях вы не потащите ПК в ремонт, а просто закроете тяжелые вкладки и очистите кэш. С Claude Code то же самое: сначала приберитесь на «рабочем столе» (контексте), не спешите переустанавливать приложение.
Медленная работа и нехватка памяти: оптимизация контекста
Официальные рекомендации по оптимизации просты:
- Регулярно запускайте команду
/compactдля сжатия истории сессии (подробнее в Статье 19). - Перезапускайте клиент Claude Code при переходе к крупным новым задачам.
- Добавляйте папки сборки и кэша в
.gitignore, чтобы избежать их сканирования.
Если потребление памяти остается высоким, вы можете выполнить команду /heapdump — она сохранит снимок кучи JavaScript (heap dump) на ваш рабочий стол ~/Desktop (или в домашний каталог в Linux). Его можно прикрепить к баг-репорту на GitHub. В повседневной работе эта команда не требуется.
При зависании процесса: нажмите Ctrl+C для прерывания текущей задачи. Если реакции нет, просто перезапустите терминал. История диалога не сотрется — запустите
claude --resumeв том же каталоге, чтобы продолжить прерванную сессию.
Циклическое автосжатие (thrashing): пугающее сообщение
Вы можете увидеть сообщение: Autocompact is thrashing: the context refilled to the limit.... Не пугайтесь. Это означает, что автосжатие выполнилось успешно, но чтение огромного файла или вывод консольной команды мгновенно забили контекст заново. Чтобы избежать бесполезной траты токенов API, Claude Code приостановил процесс. Как исправить: попросите Claude читать большой файл по частям (указывая диапазоны строк или конкретные функции вместо чтения всего файла), используйте /compact с указанием сохранить только план и diff или выполните /clear для новой сессии.
Проблемы с автодополнением @file или поиском файлов
Если инструменты поиска, автодополнение @file или пользовательские Skills не видят файлы в каталоге, скорее всего, встроенная в Claude Code утилита ripgrep (быстрый инструмент поиска) не может запуститься в вашей системе. Решение — установить системную версию ripgrep и настроить использование внешнего бинарного файла:
# macOS
brew install ripgrepПосле установки добавьте переменную среды USE_BUILTIN_RIPGREP=0 (подробнее о настройке переменных в Статье 42).
Быстрый чек-лист при проблемах с производительностью:
| Симптом | Что делать в первую очередь |
|---|---|
| Медленная работа, утечки памяти | Выполнить /compact и перезапустить сессию |
| Процесс полностью завис | Нажать Ctrl+C; если не помогло, перезапустить терминал и ввести claude --resume |
Ошибка Autocompact is thrashing | Разбить чтение файлов на части, запустить /compact с фильтром |
Проблемы с @file или поиском файлов | Установить системный ripgrep, задать переменную USE_BUILTIN_RIPGREP=0 |
| Искажение шрифтов/символов в терминале | Запустить /terminal-setup в сессии Claude и отключить GPU-ускорение терминала |
Искажение шрифтов (отображение квадратиков вместо букв) иногда случается во встроенном терминале VS Code. Выполнение команды /terminal-setup для отключения GPU-ускорения рендеринга терминала решает проблему после перезапуска вкладки. Это проблема визуального рендеринга консоли, не связанная с логикой Claude.
💡 Краткий вывод: При снижении производительности в первую очередь сжимайте контекст — комбинация
/compact+ перезапуск клиента решает большинство проблем. Зависания прерывайте по Ctrl+C или через перезапуск сclaude --resume. При сбоях поиска установите системныйripgrep, а при графических артефактах в консоли выполните/terminal-setup.
06 Ошибки API: Разберитесь, на чьей стороне сбой
Четвертая категория — ошибки API, выводящиеся красным цветом. Не стоит паниковать при их появлении. Главное — понять, произошел ли сбой на стороне сервера или на стороне клиента, так как подходы к исправлению кардинально различаются.
Аналогия: сайт не открывается на вашем ПК. Если упал сам сервер сайта, бессмысленно обновлять страницу — нужно просто ждать починки. Если же у вас пропал интернет, нужно проверять роутер. С ошибками API логика та же: выясните, кто виноват в сбое, и решите — ждать или настраивать конфигурацию.
Важно: Claude Code выполняет автоматические повторные попытки
Полезно знать о встроенном защитном механизме: при возникновении серверных ошибок, перегрузок, таймаутов, временных лимитов или обрывов связи Claude Code автоматически совершает до 10 повторных попыток с экспоненциальной задержкой. Во время повтора вы увидите счетчик вида Retrying in Ns · attempt x/y. Таким образом, если вы все же увидели красную ошибку в консоли, значит, все 10 попыток автоматического восстановления уже исчерпаны, клиент не сдался сразу.
Три основные группы ошибок и варианты действий:
| Ошибка | Кто виноват | Что делать |
|---|---|---|
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests | Сервер (не ваш клиент) | Немного подождать; проверить статус на status.claude.com; выполнить /model для выбора другой модели (лимиты считаются отдельно для каждой модели) |
You've hit your session/weekly/Opus limit | Ваш лимит исчерпан | Подождать сброса лимитов; проверить остаток через /usage; докупить баланс или сменить тариф через /usage-credits |
Prompt is too long / Request too large | Ваш запрос слишком велик | Запустить /compact или /clear; передавать файлы большого объема по частям, не копировать гигантские куски текста целиком |
Стратегии для этих трех групп совершенно разные: в первом случае нужно просто подождать, во втором — пополнить баланс или дождаться сброса лимитов, а в третьем — уменьшить объем запроса. Если запутаться, можно начать стирать историю диалога во время падения серверов Anthropic или бесконечно повторять запросы при нулевом балансе.
Также вы можете столкнуться с проблемами подключения к API (Unable to connect to API, fetch failed, Request timed out с рекомендацией проверить соединение). Обычно это вызвано проблемами с вашей сетью, VPN, настройками прокси или брандмауэра. Первым шагом проверьте доступность узла API в том же терминале:
curl -I https://api.anthropic.comЕсли ответ получен успешно, то сеть работает нормально, а проблема кроется на уровне выше (например, настройки прокси или SSL-сертификаты). Ошибки Could not resolve host или таймауты говорят о блокировке трафика. При работе в некоторых регионах или корпоративных сетях часто требуется настройка прокси-сервера через переменную HTTPS_PROXY. При медленном соединении можно увеличить время ожидания ответа с помощью двух переменных среды (подробнее о их настройке в Статье 42):
| Переменная среды | Значение по умолчанию | Описание |
|---|---|---|
API_TIMEOUT_MS | 600000 (10 минут) | Время ожидания ответа API, увеличьте при медленном соединении или работе через прокси |
CLAUDE_CODE_MAX_RETRIES | 10 | Количество попыток автоповтора, уменьшите для быстрой отдачи ошибки в скриптах |
Две частые ошибки новичков, вызывающие непонимание
model not found / you may not have access to it: указанная модель не распознана сервером или у вашего аккаунта нет к ней доступа. Запустите /model в интерактивном CLI для выбора модели из списка доступных. Если ошибка с неверной моделью повторяется, проверьте, где прописан устаревший ID. Сверяйтесь по приоритету: флаг --model → переменная среды ANTHROPIC_MODEL → settings.local.json → файлы settings.json. Удалите устаревшее значение, чтобы сбросить настройку на значение по умолчанию. Полезная рекомендация от разработчиков: используйте псевдонимы (например, sonnet, opus) вместо указания полных версий с номерами. Псевдонимы автоматически указывают на актуальные версии моделей и не устаревают (подробнее о настройке моделей и переменной ANTHROPIC_MODEL в Статье 04).
Claude Code is unable to respond to this request, which appears to violate our Usage Policy: запрос заблокирован системой контроля соблюдения правил использования. Важная деталь: анализируется весь контекст диалога, а не только ваша последняя реплика. Поэтому попытка переформулировать последнее предложение в той же сессии часто ни к чему не приводит. Правильное решение — нажать дважды Esc или выполнить /rewind, чтобы откатить историю диалога до момента возникновения конфликта (подробнее в Статье 37), и изменить подход к формулированию задачи; если найти причину не удается, просто очистите историю командой /clear и начните заново.
💡 Краткий вывод: Разделяйте ошибки API на три группы: серверные сбои
5xx/529(подождать, проверить статус серверов, сменить модель), исчерпание лимитовlimit(пополнить счет или подождать сброса) и переполнение контекстаtoo long/too large(использовать/compactили читать файлы по частям). Ошибки соединенияUnable to connectговорят о проблемах с вашей сетью (проверьте доступность черезcurl, настройте прокси). При ошибках выбора моделей перейдите на использование псевдонимов.
07 Секретное оружие: Логи --debug и метод чистой конфигурации
Предыдущие разделы описывают большинство ситуаций. Но если вы столкнулись с редкой и нестандартной ошибкой, которую не удается локализовать по инструкции, воспользуйтесь двумя продвинутыми методами отладки.
Аналогия: диагностика электропроводки с помощью мультиметра и поочередного отключения приборов. При сложных поломках мастер сначала замерит показатели тока в разных точках (анализ логов отладки), а затем начнет отключать потребители по одному, фиксируя момент исчезновения проблемы (пошаговое исключение). Два этих подхода идеально проецируются на отладку Claude Code.
Метод 1: --debug для анализа логирования в реальном времени
Если по тексту ошибки сложно понять причину, запустите client с флагом --debug, чтобы видеть внутренние процессы в реальном времени. Для локализации вы можете использовать уточняющие флаги отладки:
| Команда | Что проверяет |
|---|---|
claude --debug | Общие логи отладки для анализа работы всего приложения |
claude --debug mcp | Логи ошибок stderr при запуске и подключении MCP-серверов (помогает, если сервер подключен, но инструменты недоступны) |
claude --debug hooks | Выводит события хуков в реальном времени: совпадения matcher, коды возврата и логи (помогает при сбоях хуков) |
Также доступна встроенная команда /debug [описание], которая включает отладку прямо в текущей сессии и просит Claude проанализировать логи.
Пример использования: ваш хук отображается в выводе /hooks, но не запускается при работе. Запустите claude --debug hooks и вызовите инструмент. Лог детально покажет: «Зарегистрировано событие хука, проверка совпадения matcher, результат проверки». Это гораздо эффективнее, чем пытаться найти опечатку в JSON на глаз.
Метод 2: Сравнение с чистой конфигурацией (недооцененный прием)
Этот способ незаменим, когда нужно понять, вызвана ли ошибка вашими файлами настроек или поведением самого приложения. Мы создаем изолированную сессию без загрузки каких-либо локальных конфигураций и сравниваем поведение. Если в чистой сессии все работает стабильно, проблема в ваших файлах настроек. Команда для запуска:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeЭта команда переопределяет переменную CLAUDE_CONFIG_DIR, направляя ее в пустую временную папку, тем самым игнорируя настройки из глобального каталога ~/.claude. Также запуск из каталога /tmp гарантирует, что клиент не считает файлы настроек проекта, файлы .mcp.json или CLAUDE.md. В такой сессии отсутствуют любые ваши хуки, серверы MCP, плагины или сохраненная память.
- Если ошибка пропала → проблема кроется в вашей глобальной конфигурации
~/.claudeили настройках проекта. Начинайте добавлять компоненты обратно по одному (скопируйте один конфигурационный файл или запустите клиент из папки проекта), фиксируя момент появления ошибки для поиска причины. - Если ошибка сохраняется → причина лежит глубже конфигурационных файлов (например, в системных переменных окружения, управляемых настройках или в повреждении самой установки клиента).
Метод исключения — это стандартный подход к поиску неисправностей. Сокращая количество влияющих факторов, вы быстро локализуете проблему. Например, если Claude упорно игнорирует правило из CLAUDE.md, чистая сессия поможет понять, что дело не в баге клиента, а в конфликте между двумя файлами CLAUDE.md в разных подкаталогах проекта.
💡 Краткий вывод: Для сложных случаев используйте два приема: запуск с флагом
claude --debug [mcp/hooks]для детального анализа работы механизмов хуков или MCP, и метод чистой конфигурации (переопределениеCLAUDE_CONFIG_DIRна пустую папку) для изоляции ваших настроек и пошагового поиска сбойного конфигурационного файла.
08 Практика: Проведение самодиагностики системы
Лучший способ закрепить материал — выполнить диагностику на практике. Ниже приведена инструкция для запуска проверки /doctor и проверки статуса авторизации в вашей системе. Для этого нужен только установленный клиент Claude Code.
Шаг 1: Проверьте версию установленного клиента в консоли
claude --versionОжидаемый результат: вывод версии клиента вида 2.1.xxx (Claude Code). Наличие версии подтверждает корректность установки бинарного файла. Если выводится ошибка command not found: claude, то путь к файлу не прописан в системной переменной PATH. Обратитесь к Статье 02 для настройки переменной PATH для вашей операционной системы (в macOS/Linux исполняемый файл обычно устанавливается в ~/.local/bin).
Шаг 2: Запустите сессию и выполните диагностику
claudeПосле запуска введите в окне Claude:
/doctorОжидаемый результат: отображение диагностической панели, содержащей сведения о состоянии файлов установки, валидности JSON-схемы настроек (ошибки подсвечиваются красным), доступности серверов MCP и объеме контекста. Отсутствие ошибок говорит о корректности вашей конфигурации. Если обнаружены предупреждения, нажмите клавишу f для отправки отчета в Claude и разбора причин прямо в текущей сессии.
Шаг 3: Проверьте текущий профиль авторизации
Запустите команду:
/statusОжидаемый результат: вывод активных учетных данных. Для пользователей с подпиской должен отображаться тип OAuth (подписка), а не API-ключ. Если вы видите использование API-ключа вопреки вашим ожиданиям, выполните команду unset ANTHROPIC_API_KEY в терминале и удалите соответствующую строку экспорта из настроек профиля shell.
Шаг 4 (Опционально): Запуск чистой сессии
Для отработки метода отладки из Раздела 07 выполните запуск чистой сессии:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeОжидаемый результат: сессия запустится без считывания ваших локальных файлов CLAUDE.md, пользовательских команд или серверов MCP (команды /memory или /mcp покажут пустые списки). Это ваш эталон для будущей отладки. Обратите внимание: в Linux и Windows клиент может запросить повторный вход (так как токены авторизации хранятся в папке конфигурации), тогда как в macOS сессия восстановится автоматически за счет считывания Keychain. Для завершения просто закройте сессию. Временная папка /tmp/claude-clean не повлияет на ваши постоянные настройки в ~/.claude.
Выполнив эти шаги, вы на практике прошли весь маршрут отладки: запуск диагностики → проверка учетных данных → запуск в чистом окружении. При возникновении реальных ошибок используйте именно эту последовательность действий вместо хаотичных попыток перенастройки.
💡 Краткий вывод: Самостоятельно пройдите всю цепочку проверки:
claude --version→/doctor→/status→ чистая сессия. Помните:/doctorуказывает на область сбоя, а/statusпроверяет учетные данные. Это решает 90% проблем при старте.
09 Резюме
В этой статье мы сформировали надежный алгоритм поиска неисправностей, основанный на точном определении категории ошибки и применении нужного инструмента вместо интуитивных догадок.
Давайте закрепим основные выводы:
| Ситуация | Действие | Ключевой момент |
|---|---|---|
| Категория проблемы непонятна | Сверить симптомы по таблице маршрутизации + запустить /doctor | Начинайте с диагностики, не пробуйте всё подряд |
| Сброс авторизации / блокировка организации | Выполнить /status для проверки учетных данных | Часто вызвано оставшейся в shell переменной ANTHROPIC_API_KEY |
| Настройки, хуки или MCP не работают | Проверить состояние через /context, /hooks, /mcp | Убедитесь, что конфигурация загружена; проверьте регистр букв и приоритеты файлов |
| Зависания, нехватка памяти, ошибки поиска | Запустить /compact, перезапустить сессию или установить системный ripgrep | Обычно вызвано переполнением контекста или сбоем окружения |
| Появление ошибок API в консоли | Разделить сбои по типу: серверные, лимиты баланса или превышение размера запроса | При ошибках 5xx проверьте статус серверов, при limit пополните баланс, при too long уменьшите запрос |
| Нестандартная сложная ошибка | Запуск с флагом --debug или использование чистой конфигурации | Изучайте логи отладки и исключайте файлы настроек для локализации багов |
Теперь вы можете: столкнувшись с любыми сбоями в работе Claude Code, не паниковать при виде сообщений об ошибках. Сначала сверяйтесь с таблицей симптомов, запускайте /doctor для локализации области сбоя и команду /status для проверки учетных данных. Действуйте по инструкциям для конкретной категории (установка, вход, конфигурация, производительность, API). При сложных багах используйте логирование --debug и метод чистой конфигурации для сужения круга поиска. Если решить проблему не удалось — отправляйте отчет через /feedback. Превратив эту последовательность действий в привычку, вы научитесь быстро находить решения для любых сбоев.
Теперь вы полностью освоили практические аспекты работы с клиентом — от первоначальной установки и оптимизации сессий до устранения неполадок. Осталось лишь систематизировать профессиональные термины, с которыми мы сталкивались на протяжении курса.
В следующей статье 52 «Глоссарий (для новичков)» мы соберем воедино все понятия: CLAUDE.md, окно контекста, MCP, Subagent, Hook, контрольные точки, auto-compact... Мы дадим простые и понятные определения для каждого термина с наглядными аналогиями, сгруппировав их по темам для быстрого поиска. Задумайтесь: если вас попросят объяснить простыми словами связь между токенами и окном контекста, сможете ли вы сформулировать ответ в одном предложении?