Ошибки вайб-кодинга: симптом → причина → фикс
Коротко
Когда «агент не работает», в девяти случаях из десяти сломан не агент. Сломан один из трёх слоёв под ним: установка (бинарник не в PATH, две конфликтующие копии), доступ (регион, подписка, лимиты, роль в организации) или конфигурация (MCP-сервер не подхватился, хук не сработал, правила не загрузились). Отладка идёт снизу вверх, а не наоборот.
Три команды закрывают большую часть случаев в Claude Code: claude doctor — здоровье установки и настроек, /mcp — статус каждого MCP-сервера, claude --safe-mode — сессия со всеми расширениями выключенными. Если в безопасном режиме проблема исчезла, виноват ваш конфиг, а не CLI.
Отдельная категория, которую не чинит ни одна команда, — регион. Россия не входит в список поддерживаемых стран Anthropic, и App unavailable in region означает ровно это. То же касается части CLI других вендоров: ошибка выглядит как сетевая, но настройками не лечится.
Ниже — таблицы «симптом → причина → фикс» по четырём слоям: установка, доступ, MCP, поведение агента.
Как пользоваться каталогом
Ищите точную строку ошибки, а не её пересказ: по формулировке слой определяется почти однозначно. command not found и 403 Forbidden — разные вселенные, хотя описывают их одинаково: «не запускается». Если строки ошибки нет вообще и агент просто делает не то, это четвёртый слой, он в конце статьи.
Четыре слоя, на которых ломается
| Слой | Что это | Как понять, что дело в нём | Основной инструмент |
|---|---|---|---|
| 1. Установка | бинарник, PATH, права, версия | ошибка появляется до того, как открылся чат | claude doctor, which -a claude |
| 2. Доступ | аккаунт, подписка, регион, лимиты | CLI запускается, но первый же запрос падает с кодом | /status, страница статуса вендора |
| 3. Конфигурация | MCP, хуки, скилы, правила, права | всё работает, но конкретная функция «не видна» | /mcp, /hooks, /context, --safe-mode |
| 4. Поведение | качество кода, контекст, промпт | ничего не падает, но результат плохой | ревью и тесты, не команды |
Практический вывод: не начинайте с переустановки. Она чинит только слой 1 и легко добавляет вторую конфликтующую копию — самый частый источник «а вчера работало».
Первые три команды
claude doctor— из обычной оболочки, даже если самclaudeне стартует. Показывает состояние установки, невалидные файлы настроек, дубли установок и неиспользуемые расширения. По документации это первое, что стоит запускать; порядок отладки Claude Code разобран отдельно в диагностике через /doctor./mcp— внутри сессии. Показывает каждый сервер, статус подключения и одобрен ли он для проекта.claude --safe-mode— сессия безCLAUDE.md, скилов, плагинов, хуков, MCP и пользовательских команд. Работает как бинарный поиск: проблема пропала — значит, она в вашем конфиге, и дальше вы возвращаете куски по одному.
Для любого чужого MCP-сервера есть четвёртая проверка, которая экономит часы: возьмите точную команду из его конфига (command + args) и запустите руками в терминале. Если она падает там — вопрос не к агенту, а к пакету, ноде или окружению.
Установка и запуск CLI
| Симптом | Причина | Фикс |
|---|---|---|
command not found: claude |
каталог установки не в PATH | добавить ~/.local/bin в PATH и перезапустить терминал |
Установщик отработал, но claude --version показывает старую версию |
вторая, конфликтующая установка | which -a claude, снести лишние копии |
| Стоит только расширение VS Code, в терминале команды нет | расширение держит приватную копию CLI и не кладёт её в PATH | поставить отдельно standalone-установку |
syntax error near unexpected token '<', curl: (22) ... 403 |
скачался HTML вместо скрипта (блокировка/перехват трафика) | проверить сеть и прокси, скачать установщик заново |
TLS connect error, unable to get local issuer certificate |
корпоративный TLS-перехват, устаревшие CA | обновить CA-сертификаты, настроить корпоративный CA |
Killed / exit code 137 при установке на Linux |
не хватило памяти на VPS | добавить swap или ставить на машине побольше |
Error loading shared library, Illegal instruction |
не тот вариант бинарника (musl/glibc, архитектура) | взять сборку под свою систему |
EACCES при npm install -g |
глобальная установка через sudo |
не ставить агентские CLI под root, использовать штатный установщик |
| В WSL поиск находит меньше файлов, чем должен | проект лежит на /mnt/c/, а не на файловой системе Linux |
перенести проект в /home/, claude doctor при этом честно показывает Search как OK |
Доступ, регион и лимиты
| Симптом | Причина | Фикс |
|---|---|---|
App unavailable in region |
страна не в списке поддерживаемых | конфигом не лечится, см. ниже |
API Error: 403 {"error":{"type":"forbidden"...}} после входа |
нет активной подписки или роли в организации | проверить подписку; в Console роль Claude Code или Developer назначает админ |
OAuth error: Invalid code |
код входа протух или обрезался при копировании | нажать c, скопировать полный URL, войти быстрее; на SSH браузер открывается не на той машине |
429 |
упёрлись в лимит ключа или проекта | /status, снизить параллелизм, взять модель поменьше |
529 Overloaded |
перегружен API целиком | подождать, проверить status.claude.com, сменить модель |
500 |
сбой на стороне вендора | повторяется автоматически до 10 раз, дальше /feedback |
Model ... is not a recognized model id |
опечатка в ID или ограничение организации | выбирать через /model, использовать алиасы, а не версионные ID |
Prompt is too long |
диалог и файлы не влезли в контекст | /compact, /clear, отключить лишние MCP-серверы |
Request too large |
тело запроса больше 30 МБ | ссылаться на файлы путями, а не вставлять содержимое |
Про регион честно. Россия и Беларусь отсутствуют в списке поддерживаемых стран Anthropic (проверено 28 июля 2026 года). Это не баг сети и не проблема прокси: аккаунт может быть заблокирован по совокупности признаков, а не только по IP. Что из этого следует на практике — разобрано в материале про доступ к Claude API из России; там же про то, какие обходные схемы ломаются первыми. Тот же класс ошибок бывает у CLI других вендоров, и выглядит он одинаково: запросы уходят, ответ — 403 или пустая страница логина.
MCP: сервер не подключается
| Симптом | Причина | Фикс |
|---|---|---|
Сервер вообще не появляется в /mcp |
конфиг лежит в .claude/.mcp.json или в формате Claude Desktop |
проектный .mcp.json кладётся в корень репозитория |
Добавили серверы в mcpServers внутри settings.json — тишина |
settings.json не читает ключ mcpServers |
.mcp.json в корне или claude mcp add --scope user |
| Сервер виден, но отключён | проектные серверы требуют разового одобрения, а вы его отклонили | одобрить из /mcp |
Статус failed |
относительный путь в command/args: он резолвится от каталога запуска, а не от .mcp.json |
абсолютные пути; npx/uvx из PATH работают как есть |
connected, но 0 инструментов |
сервер стартовал, но не отдал список | Reconnect из /mcp; если ноль — claude --debug mcp и смотреть stderr |
| Сервер стартует без своих ключей | env из settings.json не пробрасывается в дочерние процессы MCP |
задавать env для каждого сервера внутри .mcp.json |
Playwright MCP: Browser is already in use for ... |
залипший профиль браузера после аварийного выхода | флаг --isolated, перезапуск сервера (issue #942) |
| Playwright MCP на сервере без дисплея | по умолчанию headed-режим | --headless либо запуск через --port и подключение по HTTP; нужен Node.js 20+ |
| В ChatGPT нет вкладки MCP-коннекторов | режим разработчика выключен или недоступен на тарифе | включить Developer mode в настройках коннекторов; список тарифов — в справке OpenAI |
| Коннектор включён, но модель его не видит в новом чате | в бете коннектор включается для каждого чата отдельно | включить его в самом чате |
Если сервер поднимается, но вы не понимаете, что он вообще умеет, начните с подключения MCP к Claude Code — там разобран порядок скоупов и одобрений. Перед тем как ставить чужой сервер в рабочий проект, прочитайте про безопасное подключение инструментов: MCP-сервер выполняется с вашими правами.
Агент работает, но делает не то
| Симптом | Причина | Фикс |
|---|---|---|
CLAUDE.md будто игнорируется |
файл в подпапке грузится лениво — когда агент читает файл в этой папке | проверить /memory; важное держать в корневом файле |
| Настройка не применяется | тот же ключ переопределён в settings.local.json или переменной окружения |
/status, проверить приоритет областей |
| Права и хуки прописаны глобально и не работают | попали в ~/.claude.json вместо ~/.claude/settings.json |
это два разных файла |
| Хук не срабатывает никогда | matcher массивом, в нижнем регистре или с запятой на версиях до v2.1.191 |
одна строка вида "Edit|Write", имена инструментов с заглавной |
Скил не появляется в /skills |
лежит как skills/name.md, а не папкой |
skills/name/SKILL.md |
| Скил виден, но не вызывается | disable-model-invocation: true или описание не совпадает с формулировкой запроса |
смотреть метку user-only в /skills |
Запрет Bash(rm *) не блокирует /bin/rm |
префиксные правила матчат строку команды, а не исполняемый файл | PreToolUse-хук или песочница |
| Расширение в VS Code висит на «API Request…» | обрыв стриминга, прокси, VPN, WSL | Developer: Reload Window, обновить расширение, проверить провайдера (FAQ Roo Code) |
Ошибки конфигурации почти всегда «тихие»: ничего не падает, функция просто не существует. Поэтому дефолтная проверка — не «почему сломалось», а «загрузилось ли вообще»: /context показывает, что реально занимает контекст сессии.
Что этот каталог не чинит
- Регион и платёжки. Ни один флаг не делает недоступный регион доступным.
- Корпоративный периметр. Если админ режет
downloads.claude.ai, помогает только разговор с админом. - Качество результата. Агент, который написал работающий, но небезопасный код, не выдаст ошибки. Здесь работают только ревью и тесты, а типовые дыры перечислены в разборе рисков вайб-кодинга.
- Цену ошибки в проде. Диагностика вернёт инструмент в строй, но не откатит то, что он успел сделать.
Частые вопросы
С чего начинать, если непонятно вообще ничего?
claude doctor из оболочки, затем claude --safe-mode. Первая команда закрывает слой установки и настроек, вторая за один шаг отделяет «сломан CLI» от «сломан мой конфиг». Дальше вы уже знаете, в какой таблице искать.
Почему сервер показывает connected, но инструментов нет?
Процесс стартовал и ответил на рукопожатие, но не вернул список инструментов. Сначала Reconnect из /mcp. Если счётчик остался нулевым, запускайте claude --debug mcp и читайте stderr сервера: обычно там лежит внятная ошибка вроде отсутствующего ключа или несовместимой версии Node.
Помогает ли переустановка?
Редко и не бесплатно. Она чинит только повреждённую установку, а типичный побочный эффект — вторая копия бинарника в другом каталоге, после чего версии начинают расходиться. Сначала which -a claude, потом решение.
Что делать, если ошибка появляется только на работе?
Смотрите на прокси и TLS. Корпоративный перехват трафика даёт unable to get local issuer certificate и обрывы загрузок; управляемые настройки организации при этом сохраняются даже в безопасном режиме и в чистом профиле. Проверьте /status — он показывает, действуют ли управляемые политики.
Ошибки в редакторных агентах отличаются от CLI?
Слои те же, но диагностика беднее: расширения часто прячут причину за общей фразой про сбой запроса. Рабочий приём — воспроизвести тот же запрос в CLI того же вендора. Если в CLI всё хорошо, проблема в расширении или окружении редактора, а не в модели и не в аккаунте.