Claude Code не работает: порядок диагностики
Коротко
Если Claude Code сломался, не гадайте — идите сверху вниз по слоям: запуск → сеть → аутентификация → модель и лимиты → конфигурация → MCP. Первая команда — /doctor внутри сессии; если claude вообще не стартует, claude doctor из терминала. Она проверяет установку, файлы настроек, расширения и предлагает исправления, которые применяет только после вашего подтверждения. Дальше /status показывает, какая аутентификация активна и какие источники настроек действуют, /context — что заняло контекстное окно, /mcp — состояние каждого MCP-сервера. Если проблема осталась, запустите claude --safe-mode: сессия без CLAUDE.md, скиллов, плагинов, хуков и MCP. Пропало — виновата одна из этих поверхностей, и её ищут включением по одной. Отдельно проверьте ANTHROPIC_API_KEY в профиле оболочки: если переменная задана, она перебивает подписку и даёт чужие лимиты либо ошибку про отключённую организацию. Весь маршрут занимает около десяти минут и в большинстве случаев заканчивается раньше, чем вы напишете в поддержку.
Почему «не работает» — это шесть разных поломок
Фраза «Claude Code не работает» описывает как минимум шесть непохожих состояний. Пока вы не определили слой, любое действие — это тыканье наугад: люди переустанавливают CLI, когда у них истёк OAuth-токен, и чистят кэш npm, когда сломан один MCP-сервер.
| Слой | Как выглядит | Чем проверить |
|---|---|---|
| Запуск | command not found: claude, падение при старте |
claude --version, ls -la "$(command -v claude)" |
| Сеть | таймауты, Failed to fetch version, TLS-ошибки |
curl -sI https://downloads.claude.ai/claude-code-releases/latest |
| Аутентификация | 403 Forbidden, циклы логина, «войдите снова» |
/status, /logout → /login |
| Модель и лимиты | 429, 529 Overloaded, «hit your weekly limit» |
/status, /usage, /model |
| Конфигурация | настройки не применяются, хуки молчат | /doctor, /hooks, /memory, claude --safe-mode |
| MCP | инструментов нет, сервер «failed» | /mcp, claude --debug mcp |
Дальше — маршрут, который проходит эти слои по порядку. Он устроен так, что каждый следующий шаг имеет смысл только если предыдущий дал «ОК».
Пошагово: десять минут по порядку
Шаг 1. Запустите диагностику (1 минута). Внутри работающей сессии — /doctor. Она проверяет здоровье установки, находит битые файлы настроек, дублирующиеся установки, неиспользуемые расширения и одноимённые субагенты в одной папке. С версии 2.1.206 она ещё и предлагает вычищенное содержимое CLAUDE.md. Если claude не стартует вообще — claude doctor из оболочки: он печатает ту же диагностику в режиме только для чтения, без запуска сессии.
Шаг 2. Если CLI не находится — это PATH, а не установка (1 минута). Установщик кладёт бинарь в ~/.local/bin/claude (на Windows — %USERPROFILE%\.local\bin\claude.exe). Проверка:
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
Пусто — добавьте каталог в конфиг оболочки (echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc) и откройте новый терминал. Отдельная ловушка: расширение VS Code держит приватную копию CLI внутри себя и в PATH ничего не кладёт. Если вы ставили только расширение, ~/.local/bin/claude не существует — и это нормально, нужна отдельная установка.
Шаг 3. Проверьте сеть до серверов (1 минута).
curl -sI https://downloads.claude.ai/claude-code-releases/latest
HTTP/2 200 — сеть в порядке. Пусто, Could not resolve host или таймаут — блокирует прокси, фаервол или провайдер. За корпоративным прокси задайте HTTP_PROXY и HTTPS_PROXY перед установкой. В PowerShell пишите curl.exe -sI: встроенный алиас curl уводит на Invoke-WebRequest, который не понимает флаги -sI.
Шаг 4. Разберитесь с аутентификацией (2 минуты). /status покажет активный метод входа. Три типичных исхода:
403 Forbiddenпосле логина — на Pro/Max проверьте, что подписка активна; в Console аккаунту нужна роль Claude Code или Developer, её назначает админ в Settings → Members.400 ... This organization has been disabledпри живой подписке — почти всегда виноватANTHROPIC_API_KEYв профиле оболочки: когда переменная есть, она перебивает OAuth-подписку. Лечитсяunset ANTHROPIC_API_KEYи вычисткой строки из~/.zshrc,~/.bashrcили~/.profile.- «Войдите снова» каждую сессию — истекает токен. Сделайте
/logout, закройте Claude Code, стартуйте заново. Проверьте системные часы: валидация токена завязана на корректные метки времени. На macOS вход ломается и при заблокированном Keychain —security unlock-keychain ~/Library/Keychains/login.keychain-db.
При входе по SSH, в WSL2 или в контейнере браузер открывается не на той машине. Нажмите c, чтобы скопировать OAuth-URL, откройте его локально и вставьте код в приглашение. Если вставка в интерактивное поле не срабатывает — claude auth login читает код из стандартного ввода.
Шаг 5. Отделите лимиты от сбоев (1 минута). 429 — упёрлись в rate limit ключа или проекта. 529 Overloaded — перегружены серверы, ёмкость считается по каждой модели отдельно, поэтому /model с переключением иногда решает вопрос мгновенно. 500 — проверьте status.claude.com, это не ваша сторона. Сообщения про session/weekly limit — это исчерпанная квота плана, смотрите /usage. Как устроены сами квоты, разбираем в тарифах и оплате Claude Code.
Шаг 6. Проверьте конфигурацию (2 минуты). Если запускается, авторизуется, но ведёт себя не так — сравните с чистым состоянием:
claude --safe-mode
Это сессия со всеми выключенными настройками: без CLAUDE.md, скиллов, плагинов, хуков, MCP-серверов и пользовательских команд. Аутентификация, модели и встроенные инструменты работают. Проблема исчезла — причина в одной из выключенных поверхностей. Дальше сужайте: /memory (какие CLAUDE.md подхватились), /skills, /hooks, /permissions. Если и в safe-mode всё плохо, обойдите пользовательский каталог целиком:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
Шаг 7. Разберитесь с MCP (2 минуты). /mcp показывает статус каждого сервера. Три состояния и три разных лечения: сервер с областью проекта в .mcp.json требует одноразового одобрения — если промпт отклонили, он так и висит отключённым; сервер со статусом «failed» чаще всего запускается по относительному пути в command или args, а путь разрешается от каталога запуска Claude Code, а не от места .mcp.json; сервер «connected», но с нулём инструментов — жмите Reconnect, а если счётчик не меняется, смотрите stderr через claude --debug mcp. Ещё частая ошибка — класть mcpServers в settings.json: этот ключ там не читается, конфиг проекта живёт в .mcp.json в корне репозитория. Подробнее — в подключении MCP к Claude Code.
Проверка результата
Считайте, что диагностика закончена, когда одновременно выполняется:
| Проверка | Ожидаемый результат |
|---|---|
claude --version |
печатает номер версии |
curl -sI https://downloads.claude.ai/... |
HTTP/2 200 |
/status |
видно активный метод входа и источники настроек |
/doctor |
нет строк про битые файлы настроек и дубли установок |
/mcp |
все нужные серверы connected, счётчик инструментов больше нуля |
| простой запрос в сессии | приходит ответ без API-ошибки |
Если все шесть строк зелёные, а поведение всё равно странное — проблема не в установке, а в формулировках и памяти проекта. Это уже другой класс задач: смотрите гайд по Claude Code для начинающих.
Подводные камни
/doctor не проверяет доступность региона. Это главный источник путаницы у российских пользователей. Установка может быть идеально здоровой, сеть — доступной, а API отвечать App unavailable in region. России и Беларуси нет в списке поддерживаемых стран Anthropic — ни для API, ни для claude.ai. Никакая локальная диагностика это не покажет: с точки зрения claude doctor всё «ОК». Признак именно регионального отказа — сеть проходит, логин проходит, а запросы отбиваются. Что с этим делать и какие обходные маршруты реально работают, разбираем в доступе к Claude API из России.
Автоповторы маскируют проблему. Claude Code сам повторяет запрос до 10 раз при 5xx, 529, таймаутах и временных 429. Поэтому «просто медленно» может означать «каждый запрос падает и переотправляется». Не повторяются ошибки проверки TLS-сертификата и сбои после того, как часть вывода уже показана.
Поиск на WSL врёт, а claude doctor показывает Search как OK. При работе с файлами через /mnt/c/ штрафы на чтение диска приводят к тому, что поиск возвращает меньше совпадений, чем есть. Формально всё работает — фактически агент не видит половину проекта. Лечение: держать проект в файловой системе Linux (/home/).
~/.claude.json — это не файл настроек. Туда часто кладут permissions, hooks и env и удивляются, что их игнорируют. Эти ключи живут в ~/.claude/settings.json. Два разных файла с похожими именами.
Хук не срабатывает молча. Если matcher записан массивом вместо строки — это ошибка схемы, и Claude Code отклоняет весь файл настроек целиком, а не одну запись. Ни один хук из этого файла не появится в /hooks.
Дамп памяти нельзя прикладывать к issue. Если ловите утечку через /heapdump, помните: файл .heapsnapshot содержит каждую строку в процессе, включая переписку и секреты. В репозиторий прикладывают только -diagnostics.json.
Частые вопросы
Чем /doctor отличается от claude doctor?
Это одна проверка в двух режимах. /doctor запускается внутри сессии, показывает найденные проблемы и предлагает исправления, которые применяет после вашего подтверждения. claude doctor запускается из терминала и печатает диагностику установки и настроек только для чтения, ничего не меняя. Второй вариант — единственный доступный, когда claude вообще не поднимается.
Я переустановил Claude Code, но версия осталась старой. Почему?
Скорее всего, в системе две установки, и PATH находит не ту. Проверьте ls -la "$(command -v claude)" — путь покажет, какой бинарь реально запускается. /doctor отдельно сообщает про дублирующиеся установки. На Windows частая причина — Claude Desktop, который перехватывает команду claude.
Может ли /compact починить зависания?
Иногда да: при большом контексте растёт потребление CPU и памяти. Но если вы видите Autocompact is thrashing, дело не в размере как таковом — сжатие сработало, а файл или вывод инструмента тут же снова заполнили окно. Лечится чтением файла кусками, /compact с фокусом («оставь только план и диф») или выносом тяжёлой работы в субагента с отдельным контекстом.
Стоит ли ставить Claude Code через sudo npm install -g?
Нет. Установка «под рутом» ломает права на файлы в ~/.claude и ~/.local, и потом установщик не может писать в собственные каталоги. Если уже поставили так — создайте каталог заново и верните владельца: sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local.
Что делать, если ничего из списка не помогло?
Зафиксируйте, на каком шаге маршрут обрывается, и приложите это к обращению: вывод claude --version, результат curl-проверки, вывод /status и скриншот /mcp. Команда /feedback отправляет отчёт напрямую в Anthropic. Перед этим стоит поискать симптом в issues репозитория — половина «уникальных» поломок оказывается известной регрессией конкретной версии, которая чинится обновлением.