Troubleshooting
Установка · Частые ошибки

Troubleshooting —
частые ошибки
установки

Найди симптом в таблице — следуй решению для Mac или Win.

13 проблем — реальные случаи с занятия
Mac & Windows
Помощь в чате поддержка курса
Прокрути вниз
Карта проблем
Быстрый поиск

Найди свой симптом

# Симптом Где происходит
01 npm: команда не распознана (Win) / npm: command not found (Mac) После установки nvm/Node, при попытке npm install Перейти
02 command not found: nvm (Mac) После установки nvm, при попытке nvm install Перейти
03 Mac требует Xcode Command Line Tools (23 ГБ) При первой команде в Терминале Перейти
04 VPN не подключается / страна не подходит Перед установкой Z.AI или при запуске claude Перейти
05 Drag-drop .plugin из Telegram не срабатывает При установке плагина Перейти
06 401 token expired после установки memory-плагинов После /plugin install memory-architect Перейти
07 Запись Телемоста идёт кусками, обрывается На рабочих созвонах Перейти
08 Онбординг плагина: писать текстом или галочками? Во время /onboarding Перейти
09 После закрытия терминала команды снова «не найдены» После перезапуска Перейти
10 claude запускается, но не отвечает на запросы После успешной установки Перейти
11 «Settings Error / Invalid or malformed JSON» при старте После правки settings.local.json Перейти
12 claude-code-router — установочный скрипт выдаёт 404 Когда кто-то посоветовал «поставь через router» Перейти
13 Уже всё снёс через rm -rf, не знаю что делать После попыток самостоятельной починки Перейти

Симптом не из списка? Пиши Олегу в Telegram-чат курса со скриншотом — разберёмся вместе.

Проблема 1 из 13
01
PATH не обновился

npm — команда не распознана

Причина: ты установил Node.js / nvm, но PATH в текущем окне терминала ещё не обновился. Старое окно «помнит» старый PATH.

Шаги решения: закрой ВСЕ окна PowerShell (Win) или Терминала (Mac). Открой свежее. На Win — от администратора (правый клик → «Запуск от имени администратора»). Повтори команду.

Если не помогло — Win: вручную добавить в PATH
PS> 
[System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\nodejs", "User")
После команды
Закрой PowerShell, открой свежий. Проверь: node --version
Если не помогло — Mac: проверить .zshrc
$ 
cat ~/.zshrc | grep nvm
Должны увидеть
Две строки про NVM. Если их нет — повтори установку nvm (шаг 2.2 в macos-install.html).

Если до сих пор «не найдено» на Win — переустанови Node с nodejs.org. На экране «Custom Setup» убедись что «Add to PATH» включён (иконка диска, не красный крестик).

Проблема 2 из 13
02
nvm не активен в сессии

command not found: nvm (Mac)

Причина: nvm-инсталлятор добавил подключение в ~/.zshrc, но в текущем окне Терминала оно ещё не активно.

Быстрое решение — активировать без перезапуска
$ 
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
После этого
nvm install --lts сработает здесь и сейчас
Проверить существование папки nvm
$ 
ls -la ~/.nvm/ | head
Если папки нет
nvm не установился — повторить установку (шаг 2.2 из macos-install.html)

Долгое решение: закрой Терминал, открой новый — nvm подхватится автоматически из ~/.zshrc.

Проблема 3 из 13
03
Только Mac

Xcode Command Line Tools — 23 ГБ?

Симптом: при первой команде выскакивает диалог «xcode-select: error: invalid developer directory» или «The xcode-select command requires the command line developer tools».

Соглашайся, нажми «Установить» (Install) в диалоге Терминала. Это нужно один раз — даёт компиляторы и утилиты которые требуются nvm/Node.

Размер: 1.5–3 ГБ, не 23 ГБ. 23 ГБ — это полный Xcode IDE из App Store. Его не нужно ставить.

Если предлагают «Установить Xcode» через App Store — отмени. Выбери именно «Установить» во всплывающем окне Терминала. Время: 15–30 минут в зависимости от интернета. После установки — заново открой Терминал и продолжи.

Проблема 4 из 13
04
Проверка IP

VPN не подключается / страна не подходит

Причина: Claude Code (через Z.AI) проверяет IP. С российского IP запросы не пройдут — 403 Forbidden или Claude молча зависнет.

  • Проверь текущий IP: открой whatismyipaddress.com. Если показывает Россию — VPN не работает.
  • Переключи VPN на США, Канаду, Германию, Нидерланды, Великобританию.
  • Перезапусти claude.

Не работают: Россия, Беларусь, Иран, Северная Корея, Турция (50/50). Бесплатные VPN (Free VPN, Chrome-расширения) почти всегда забанены у Z.AI. Олег рекомендует: Mullvad, ProtonVPN, NordVPN. Если совсем не помогает — напиши в чат, Олег поможет лично.

Проблема 5 из 13
05
Путь через Finder / Проводник

Drag-drop .plugin из Telegram не работает

Причина: Telegram отдаёт файл через временный путь, которого Claude не видит. Нужен «настоящий» путь в файловой системе.

  • В Telegram нажми правой кнопкой по файлу → «Показать в Finder» (Mac) / «Показать в папке» (Win).
  • Откроется Finder/Проводник с этим файлом.
  • Перетащи файл из Finder/Проводника в окно claude (где приглашение >). Должна появиться полная строка типа /Users/.../Downloads/xwaters-marketing.plugin.
  • Нажми Enter.
Альтернатива — через /plugin install
> 
/plugin install /полный/путь/к/файлу.plugin
Как найти путь
Mac: правый клик → «Get Info» → «Where». Win: правый клик → «Свойства» → «Расположение».
Проблема 6 из 13
06
Z.AI настройки затёрты

401 token expired — после memory-плагинов

Причина: плагины memory-architect или memory-systems при установке трогают ~/.claude/settings.json и/или ~/.claude.json и затирают Z.AI настройки.

Полная инструкция восстановления — в отдельном документе 01-install/recovery-z-ai.md. Там детально для Mac и Win, плюс способ проверки JSON.

Кратко — шаги (Mac)
$ 
rm ~/.claude.json
# Восстановить Z.AI блок в ~/.claude/settings.json
# Перезапустить claude
Кратко — шаги (Win)
PS> 
Remove-Item "$env:USERPROFILE\.claude.json"
# Восстановить Z.AI в User Environment Variables
# Перезапустить claude

За деталями — recovery-z-ai.md. Там готовые блоки настроек для Mac и Win — не нужно вручную набирать JSON.

Проблема 7 из 13
07
Экранкаст как решение

Запись Телемоста режется кусками

Причина: баг Телемоста при долгих созвонах + слабый интернет одного из участников. Встроенная запись ненадёжна.

  • Не полагайся на встроенную запись для важных созвонов.
  • Используй внешний экранкаст: OBS Studio (бесплатно, кроссплатформенно), QuickTime (Mac), Win+G Game Bar (Win 10/11), Loom (онлайн).
  • Запись ведёт организатор — у него она проходит полностью. Остальным не нужно дублировать.

Если обязательно нужна запись своего рабочего обсуждения — запусти OBS параллельно с Телемостом. Ты сам контролируешь результат.

Проблема 8 из 13
08
Управление клавиатурой

Онбординг — текстом или галочками?

Во время /onboarding Claude задаёт вопрос с вариантами A/B/C/D — непонятно как ответить.

  • Вопрос со списком (A/B/C/D или ●/○) — используй стрелки: ↑ ↓ двигают выделение, Enter подтверждает.
  • Пробел — иногда нужен для отметки checkbox-ов (если ответов можно выбрать несколько).
  • Вопрос открытый («Опиши свою роль») — пиши текстом, потом Enter.

Выделенный пункт обычно подкрашен или помечен ▶. Если непонятно где курсор — нажми ↓ один раз, увидишь движение. Если случайно ответил неправильно — продолжи онбординг, потом запусти /onboarding ещё раз.

Проблема 9 из 13
09
PATH сбросился

После перезапуска терминала снова не найдены

Mac: конфиг shell-а (~/.zshrc) повредился или удалился.
Win: PATH потерял запись про Node после обновления Windows.

Mac — проверить .zshrc
$ 
ls -la ~/.zshrc && cat ~/.zshrc | grep -E "nvm|claude" | head
Должны увидеть
Строки export NVM_DIR=... и [ -s ... nvm.sh ]. Если их нет — переустанови nvm.
Win — проверить PATH
PS> 
$env:Path -split ";" | Where-Object { $_ -like "*nodejs*" }
Если ничего не вернул
Добавь: [System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\nodejs", "User")
Проблема 10 из 13
10
Диагностика по коду ошибки

claude запускается, но не отвечает

Посмотри на текст ошибки в нижней части экрана — это основной ключ к диагнозу.

Текст ошибки Куда смотреть
401 / token / Authentication failed Проблема 6 — recovery-z-ai.md
ECONNREFUSED / network error / timeout Проблема 4 — VPN
403 Forbidden Проблема 4 — VPN (IP в чёрном списке Z.AI)
429 rate limit Подожди 5 минут, попробуй снова. Если повторяется — Олег пришлёт новый ключ
500 / 502 / 503 Сервера Z.AI временно недоступны. Подожди 10–20 минут
Ничего не происходит, курсор мигает Проверь VPN (Проблема 4). Нажми Ctrl+C и попробуй заново
Проблема 11 из 13
11
Невалидный JSON в конфиге

Settings Error / Invalid JSON

Причина: в settings.json или settings.local.json лишняя/недостающая запятая или кавычка. Claude пропускает весь файл. Если там был Z.AI-блок — он не применяется, следующим шагом будет 401.

Mac — сохранить резерв и удалить битый файл
$ 
mkdir -p ~/.claude-backup
cp ~/.claude/settings.local.json ~/.claude-backup/ 2>/dev/null
rm -f ~/.claude/settings.local.json
claude
Win — то же самое в PowerShell
PS> 
Copy-Item "$env:USERPROFILE\.claude\settings.local.json" "$env:USERPROFILE\.claude-backup\" -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.claude\settings.local.json" -ErrorAction SilentlyContinue
claude

В диалоге Claude можно попробовать «1. Fix with Claude» — иногда чинит. Но удалить и создать заново надёжнее. Детали: recovery-z-ai.md раздел 6.

Проблема 12 из 13
12
Не наш путь

claude-code-router — скрипт выдаёт 404

Что это: claude-code-router — сторонний роутер для подмены AI-провайдера. Активно меняется в апстриме — URL установочного скрипта переезжал, путь /scripts/install.sh на 2026-05-15 не существует.

Не ставь его. Это НЕ рекомендованный путь для курса. Мы работаем через ~/.claude/settings.json (Mac) или User Environment Variables (Win) — стандартный способ из macos-install.html / windows-install.html.

Если уже пытался поставить и теперь странности — recovery-z-ai.md раздел 7 (полный сброс с нуля). Раздел 8 там же объясняет почему именно не ставим router.

Проблема 13 из 13
13
Полный сброс

Уже всё снёс через rm -rf

Файлов нет — Claude либо не стартует, либо стартует на оригинальный Anthropic API (где нет логина) и сразу 401. Это не катастрофа.

Решение: recovery-z-ai.md раздел 7 — «Полный сброс с нуля». Там готовый скрипт под Mac и Win. Выполнить блоком, подставить свой Z.AI-ключ из чата курса.

Не делай: claude /login (пробудит OAuth в оригинальный Anthropic, который не используется), не ставь claude-code-router (см. Проблема 12), не переустанавливай Node/npm/Claude — они не виноваты, проблема в конфиге.