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

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

​
Проблемы установки 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"
Избегайте отключения импорта 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. Используйте следующую команду для запуска встроенного установщика. 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 (или %USERPROFILE%\.local\bin\claude.exe в Windows).
Убедитесь, что у вас есть каталог установки в системном PATH.

​
Windows: “Claude Code on Windows requires git-bash”

Claude Code на нативном Windows требует Git for Windows, который включает Git Bash. Если Git установлен, но не обнаружен:
  1. Установите путь явно в PowerShell перед запуском Claude: 
    $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
  2. Или добавьте его в переменные окружения вашей системы постоянно через Свойства системы → Переменные окружения.
Если Git установлен в нестандартном месте, отрегулируйте путь соответственно.

​
Windows: “installMethod is native, but claude command not found”

Если вы видите эту ошибку после установки, команда claude не находится в вашем PATH. Добавьте её вручную:
1

Open Environment Variables

Нажмите Win + R, введите sysdm.cpl и нажмите Enter. Нажмите Advanced → Environment Variables.
2

Edit User PATH

В разделе “User variables” выберите Path и нажмите Edit. Нажмите New и добавьте:
%USERPROFILE%\.local\bin
3

Restart your terminal

Закройте и снова откройте PowerShell или CMD, чтобы изменения вступили в силу.
Проверьте установку: 
claude doctor # Check installation health

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

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

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

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

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

​
Расположение файлов конфигурации

Claude Code хранит конфигурацию в нескольких местах:
ФайлНазначение
~/.claude/settings.jsonПараметры пользователя (разрешения, хуки, переопределения модели)
.claude/settings.jsonПараметры проекта (проверены в системе управления версиями)
.claude/settings.local.jsonЛокальные параметры проекта (не коммитятся)
~/.claude.jsonГлобальное состояние (тема, OAuth, серверы MCP, разрешённые инструменты)
.mcp.jsonСерверы MCP проекта (проверены в системе управления версиями)
managed-settings.jsonУправляемые параметры
managed-mcp.jsonУправляемые серверы MCP
В Windows ~ относится к вашему домашнему каталогу пользователя, например C:\Users\YourName. Расположение управляемых файлов:
  • macOS: /Library/Application Support/ClaudeCode/
  • Linux/WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
Для получения подробной информации о настройке этих файлов см. Параметры и MCP.

​
Сброс конфигурации

Чтобы сбросить Claude Code на параметры по умолчанию, вы можете удалить файлы конфигурации: 
# Reset all user settings and state
rm ~/.claude.json
rm -rf ~/.claude/

# Reset project-specific settings
rm -rf .claude/
rm .mcp.json
Это удалит все ваши параметры, разрешённые инструменты, конфигурации серверов MCP и историю сеансов.

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

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

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

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

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

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

Если инструмент Search, упоминания @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 будет показывать 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 JetBrains.

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

Если вы испытываете проблемы с интеграцией IDE на Windows, создайте проблему со следующей информацией:
  • Тип окружения: нативный Windows (Git Bash) или WSL1/WSL2
  • Режим сети WSL (если применимо): NAT или зеркальный
  • Имя и версия IDE
  • Версия расширения/плагина Claude Code
  • Тип оболочки: Bash, Zsh, PowerShell и т. д.

​
Клавиша Escape не работает в терминалах 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 добавить теги языка: Запросите “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 имеет встроенный доступ к своей документации