Устранение неполадок

Откройте для себя решения распространенных проблем с установкой и использованием Claude Code.

Распространенные проблемы установки

Проблемы установки в Windows: ошибки в WSL

Вы можете столкнуться со следующими проблемами в WSL:

Проблемы с определением ОС/платформы: Если вы получаете ошибку во время установки, WSL может использовать Windows npm. Попробуйте:

• Выполните npm config set os linux перед установкой
• Установите с помощью npm install -g @anthropic-ai/claude-code --force --no-os-check (НЕ используйте sudo)

Ошибки “Node не найден”: Если вы видите exec: node: not found при запуске claude, ваша среда WSL может использовать установку Node.js для Windows. Вы можете подтвердить это с помощью which npm и which node, которые должны указывать на пути Linux, начинающиеся с /usr/, а не с /mnt/c/. Чтобы исправить это, попробуйте установить Node через менеджер пакетов вашего дистрибутива Linux или через nvm.

Конфликты версий nvm: Если у вас установлен nvm как в WSL, так и в Windows, вы можете столкнуться с конфликтами версий при переключении версий Node в WSL. Это происходит потому, что WSL по умолчанию импортирует PATH Windows, что приводит к тому, что Windows nvm/npm имеют приоритет над установкой WSL.

Вы можете определить эту проблему по:

• Выполнению which npm и which node - если они указывают на пути Windows (начинающиеся с /mnt/c/), используются версии Windows
• Нарушению функциональности после переключения версий Node с помощью nvm в WSL

Чтобы решить эту проблему, исправьте ваш Linux PATH, чтобы обеспечить приоритет версий Linux node/npm:

Основное решение: Убедитесь, что nvm правильно загружен в вашей оболочке

Наиболее распространенная причина заключается в том, что nvm не загружается в неинтерактивных оболочках. Добавьте следующее в файл конфигурации вашей оболочки (~/.bashrc, ~/.zshrc, и т.д.):

# Загрузить nvm, если он существует
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Или выполните напрямую в вашей текущей сессии:

source ~/.nvm/nvm.sh

Альтернатива: Настройка порядка PATH

Если nvm правильно загружен, но пути Windows все еще имеют приоритет, вы можете явно добавить ваши пути Linux в начало PATH в конфигурации вашей оболочки:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Избегайте отключения импорта PATH Windows (appendWindowsPath = false), поскольку это нарушает возможность легко вызывать исполняемые файлы Windows из WSL. Аналогично, избегайте удаления Node.js из Windows, если вы используете его для разработки под Windows.

Проблемы установки в Linux и Mac: ошибки разрешений или команда не найдена

При установке Claude Code с помощью npm проблемы с PATH могут препятствовать доступу к claude. Вы также можете столкнуться с ошибками разрешений, если ваш глобальный префикс npm недоступен для записи пользователем (например, /usr или /usr/local).

Рекомендуемое решение: Нативная установка Claude Code

Claude Code имеет нативную установку, которая не зависит от npm или Node.js.

Нативный установщик Claude Code в настоящее время находится в бета-версии.

Используйте следующую команду для запуска нативного установщика.

macOS, Linux, WSL:

# Установить стабильную версию (по умолчанию)
curl -fsSL https://claude.ai/install.sh | bash

# Установить последнюю версию
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Установить конкретный номер версии
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# Установить стабильную версию (по умолчанию)
irm https://claude.ai/install.ps1 | iex

# Установить последнюю версию
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Установить конкретный номер версии
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Эта команда устанавливает подходящую сборку Claude Code для вашей операционной системы и архитектуры и добавляет символическую ссылку на установку в ~/.local/bin/claude.

Убедитесь, что у вас есть каталог установки в системном PATH.

Альтернативное решение: Миграция на локальную установку

Альтернативно, если Claude Code будет работать, вы можете мигрировать на локальную установку:

claude migrate-installer

Это перемещает Claude Code в ~/.claude/local/ и настраивает псевдоним в конфигурации вашей оболочки. Для будущих обновлений sudo не требуется.

После миграции перезапустите вашу оболочку, а затем проверьте вашу установку:

На macOS/Linux/WSL:

which claude  # Должен показать псевдоним на ~/.claude/local/claude

На Windows:

where claude  # Должен показать путь к исполняемому файлу claude

Проверьте установку:

claude doctor # Проверить состояние установки

Разрешения и аутентификация

Повторяющиеся запросы разрешений

Если вы постоянно одобряете одни и те же команды, вы можете разрешить конкретным инструментам работать без одобрения, используя команду /permissions. См. документацию по разрешениям.

Проблемы с аутентификацией

Если вы испытываете проблемы с аутентификацией:

1. Выполните /logout для полного выхода из системы
2. Закройте Claude Code
3. Перезапустите с помощью claude и завершите процесс аутентификации снова

Если проблемы сохраняются, попробуйте:

rm -rf ~/.config/claude-code/auth.json
claude

Это удаляет вашу сохраненную информацию аутентификации и принуждает к чистому входу в систему.

Производительность и стабильность

Высокое использование CPU или памяти

Claude Code разработан для работы с большинством сред разработки, но может потреблять значительные ресурсы при обработке больших кодовых баз. Если вы испытываете проблемы с производительностью:

1. Используйте /compact регулярно для уменьшения размера контекста
2. Закрывайте и перезапускайте Claude Code между основными задачами
3. Рассмотрите добавление больших каталогов сборки в ваш файл .gitignore

Команда зависает или замерзает

Если Claude Code кажется неотзывчивым:

1. Нажмите Ctrl+C, чтобы попытаться отменить текущую операцию
2. Если неотзывчив, вам может потребоваться закрыть терминал и перезапустить

Проблемы с поиском и обнаружением

Если инструмент поиска, упоминания @file, пользовательские агенты и пользовательские слэш-команды не работают, установите системный ripgrep:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Затем установите USE_BUILTIN_RIPGREP=0 в вашем окружении.

Медленные или неполные результаты поиска в WSL

Штрафы за производительность чтения диска при работе через файловые системы в WSL могут привести к меньшему количеству совпадений, чем ожидалось (но не к полному отсутствию функциональности поиска) при использовании Claude Code в WSL.

/doctor покажет поиск как OK в этом случае.

Решения:

1. Отправляйте более конкретные поисковые запросы: Уменьшите количество файлов для поиска, указав каталоги или типы файлов: “Поиск логики валидации JWT в пакете auth-service” или “Найти использование хэша md5 в JS файлах”.

2. Переместите проект в файловую систему Linux: Если возможно, убедитесь, что ваш проект расположен в файловой системе Linux (/home/), а не в файловой системе Windows (/mnt/c/).

3. Используйте нативный Windows вместо этого: Рассмотрите запуск Claude Code нативно в Windows вместо WSL для лучшей производительности файловой системы.

Проблемы интеграции с IDE

JetBrains IDE не обнаружена в WSL2

Если вы используете Claude Code в WSL2 с JetBrains IDE и получаете ошибки “Доступные IDE не обнаружены”, это, вероятно, связано с конфигурацией сети WSL2 или блокировкой соединения брандмауэром Windows.

Режимы сети WSL2

WSL2 использует NAT-сеть по умолчанию, что может препятствовать обнаружению IDE. У вас есть два варианта:

Вариант 1: Настройка брандмауэра Windows (рекомендуется)

1. Найдите ваш IP-адрес WSL2:

   wsl hostname -I
   # Пример вывода: 172.21.123.456
   

2. Откройте PowerShell от имени администратора и создайте правило брандмауэра:

   New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
   

   (Настройте диапазон IP на основе вашей подсети WSL2 из шага 1)

3. Перезапустите как вашу IDE, так и Claude Code

Вариант 2: Переключение на зеркальную сеть

Добавьте в .wslconfig в каталоге пользователя Windows:

[wsl2]
networkingMode=mirrored

Затем перезапустите WSL с помощью wsl --shutdown из PowerShell.

Эти проблемы с сетью затрагивают только WSL2. WSL1 использует сеть хоста напрямую и не требует этих конфигураций.

Для дополнительных советов по конфигурации JetBrains см. наше руководство по интеграции с IDE.

Сообщение о проблемах интеграции с Windows IDE (как нативной, так и WSL)

Если вы испытываете проблемы с интеграцией IDE в Windows, пожалуйста, создайте issue со следующей информацией: являетесь ли вы нативным (git bash) или WSL1/WSL2, режим сети WSL (NAT или зеркальный), имя/версия IDE, версия расширения/плагина Claude Code и тип оболочки (bash/zsh/и т.д.)

Клавиша ESC не работает в терминалах JetBrains (IntelliJ, PyCharm, и т.д.)

Если вы используете Claude Code в терминалах JetBrains и клавиша ESC не прерывает агента, как ожидается, это, вероятно, связано с конфликтом привязок клавиш с горячими клавишами JetBrains по умолчанию.

Чтобы исправить эту проблему:

1. Перейдите в Настройки → Инструменты → Терминал
2. Либо:
   • Снимите флажок “Переместить фокус в редактор с помощью Escape”, или
   • Нажмите “Настроить привязки клавиш терминала” и удалите ярлык “Переключить фокус на редактор”
3. Примените изменения

Это позволяет клавише ESC правильно прерывать операции Claude Code.

Проблемы форматирования Markdown

Claude Code иногда генерирует файлы markdown с отсутствующими тегами языка в блоках кода, что может повлиять на подсветку синтаксиса и читаемость в GitHub, редакторах и инструментах документации.

Отсутствующие теги языка в блоках кода

Если вы замечаете блоки кода вроде этого в сгенерированном markdown:

```
function example() {
  return "hello";
}
```

Вместо правильно помеченных блоков вроде:

```javascript
function example() {
  return "hello";
}
```

Решения:

1. Попросите Claude добавить теги языка: Просто запросите “Пожалуйста, добавьте соответствующие теги языка ко всем блокам кода в этом файле markdown.”

2. Используйте хуки постобработки: Настройте автоматические хуки форматирования для обнаружения и добавления отсутствующих тегов языка. См. пример хука форматирования markdown для деталей реализации.

3. Ручная проверка: После генерации файлов markdown просмотрите их на предмет правильного форматирования блоков кода и запросите исправления при необходимости.

Непоследовательные пробелы и форматирование

Если сгенерированный markdown имеет избыточные пустые строки или непоследовательные пробелы:

Решения:

1. Запросите исправления форматирования: Попросите Claude “Исправить проблемы с пробелами и форматированием в этом файле markdown.”

2. Используйте инструменты форматирования: Настройте хуки для запуска форматировщиков markdown, таких как prettier или пользовательских скриптов форматирования на сгенерированных файлах markdown.

3. Укажите предпочтения форматирования: Включите требования к форматированию в ваши запросы или файлы памяти проекта.

Лучшие практики для генерации markdown

Чтобы минимизировать проблемы форматирования:

• Будьте явными в запросах: Просите “правильно отформатированный markdown с блоками кода, помеченными языком”
• Используйте соглашения проекта: Документируйте ваш предпочтительный стиль markdown в CLAUDE.md
• Настройте хуки валидации: Используйте хуки постобработки для автоматической проверки и исправления распространенных проблем форматирования

Получение дополнительной помощи

Если вы испытываете проблемы, не освещенные здесь:

1. Используйте команду /bug в Claude Code для прямого сообщения о проблемах в Anthropic
2. Проверьте репозиторий GitHub на предмет известных проблем
3. Выполните /doctor для проверки состояния вашей установки Claude Code
4. Спросите Claude напрямую о его возможностях и функциях - Claude имеет встроенный доступ к своей документации