Перейти к основному содержанию

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

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

Вы можете столкнуться со следующими проблемами в WSL: Проблемы обнаружения ОС/платформы: Если вы получаете ошибку во время установки, WSL может использовать Windows npm. Попробуйте:
  • Запустите npm config set os linux перед установкой
  • Установите с помощью npm install -g @anthropic-ai/claude-code --force --no-os-check (НЕ используйте sudo)
Ошибки “Node not found”: Если вы видите 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 и т. д.): 
# Load nvm if it exists
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"
Избегайте отключения импорта Windows PATH (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: 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell: 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
Эта команда устанавливает соответствующую сборку Claude Code для вашей операционной системы и архитектуры и добавляет символическую ссылку на установку в ~/.local/bin/claude.
Убедитесь, что у вас есть каталог установки в системном PATH.
Проверьте установку: 
claude doctor # Check installation health

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

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

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

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

Если у вас возникают проблемы с аутентификацией:
  1. Запустите /logout, чтобы полностью выйти
  2. Закройте Claude Code
  3. Перезагрузитесь с помощью claude и завершите процесс аутентификации заново
Если проблемы сохраняются, попробуйте: 
rm -rf ~/.config/claude-code/auth.json
claude
Это удаляет вашу сохраненную информацию об аутентификации и принудительно выполняет чистый вход.

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

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

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

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

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

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

Если инструмент Search, упоминания @file, пользовательские агенты и пользовательские команды slash не работают, установите системный 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 будет показывать Search как OK в этом случае.
Решения:
  1. Отправляйте более конкретные поиски: Уменьшите количество файлов, которые нужно искать, указав каталоги или типы файлов: “Search for JWT validation logic in the auth-service package” или “Find use of md5 hash in JS files”.
  2. Переместите проект на файловую систему Linux: Если возможно, убедитесь, что ваш проект находится на файловой системе Linux (/home/), а не на файловой системе Windows (/mnt/c/).
  3. Используйте собственный Windows: Рассмотрите возможность запуска Claude Code в собственном Windows вместо WSL для лучшей производительности файловой системы.

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

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

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

​
Режимы сети WSL2

WSL2 по умолчанию использует сетевое взаимодействие NAT, которое может препятствовать обнаружению IDE. У вас есть два варианта: Вариант 1: Настройте брандмауэр Windows (рекомендуется)
  1. Найдите ваш IP-адрес WSL2: 
    wsl hostname -I
# Example output: 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.

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

Если вы испытываете проблемы с интеграцией IDE на Windows, пожалуйста, создайте проблему со следующей информацией: используете ли вы собственный (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 добавить теги языка: Просто запросите “Please add appropriate language tags to all code blocks in this markdown file.”
  2. Используйте хуки постобработки: Установите автоматические хуки форматирования для обнаружения и добавления отсутствующих тегов языка. См. пример хука форматирования markdown для деталей реализации.
  3. Ручная проверка: После создания файлов markdown проверьте их на правильное форматирование блоков кода и запросите исправления при необходимости.

​
Несогласованный интервал и форматирование

Если сгенерированный markdown имеет чрезмерные пустые строки или несогласованный интервал: Решения:
  1. Запросите исправления форматирования: Попросите Claude “Fix spacing and formatting issues in this markdown file.”
  2. Используйте инструменты форматирования: Установите хуки для запуска форматировщиков markdown, таких как prettier, или пользовательских скриптов форматирования на сгенерированных файлах markdown.
  3. Укажите предпочтения форматирования: Включите требования форматирования в ваши подсказки или файлы памяти проекта.

​
Лучшие практики для создания markdown

Чтобы минимизировать проблемы форматирования:
  • Будьте явными в запросах: Попросите “properly formatted markdown with language-tagged code blocks”
  • Используйте соглашения проекта: Задокументируйте ваш предпочтительный стиль markdown в CLAUDE.md
  • Установите хуки валидации: Используйте хуки постобработки для автоматической проверки и исправления распространенных проблем форматирования

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

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