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

​
Проблемы установки в 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 имеет встроенный доступ к своей документации