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

​
Проблемы установки в 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 и получаете ошибки “No available IDEs detected”, это, вероятно, связано с конфигурацией сети 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. Перейдите в Settings → Tools → Terminal
  2. Либо:
    • Снимите флажок “Move focus to the editor with Escape”, или
    • Нажмите “Configure terminal keybindings” и удалите ярлык “Switch focus to Editor”
  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 имеет встроенный доступ к своей документации