Установка Claude Code: выбор между Native и npm, исправление PATH и первый запуск

Для нативной установки (Native Install) Claude Code среда выполнения Node.js не требуется вовсе. Установщик npm в настоящее время требует Node.js 22+, однако сам установленный бинарный файл работает без рантайма Node. Официальная документация Anthropic рекомендует использовать именно Native Install (подробнее см. руководство по установке). Для работы с кодовым агентом в терминале разработчику необходимо выбрать способ установки, запустить команду в подходящей оболочке и убедиться, что исполняемый файл корректно обнаружен операционной системой. При возникновении ошибок с вызовом команды важно точно локализовать источник проблемы — различия между нативным дистрибутивом и установкой через пакетный менеджер определяют, где именно искать причину сбоя.

Native или npm: границы выбора и роль Node.js

Официальная документация Anthropic рекомендует использовать Native Install (руководство по установке). В этом варианте среда выполнения Node.js не требуется: инсталлятор загружает скомпилированный автономный бинарный файл, который в процессе работы вообще не обращается к Node.

Установка через глобальный пакет npm остается доступной альтернативой. В настоящее время установщик npm требует наличия Node.js 22 или выше. Если запустить инсталляцию на более ранней версии Node.js, npm выведет предупреждение EBADENGINE, однако сама процедура, как правило, завершается успешно: пакет подтягивает платформозависимый предкомпилированный бинарный файл и создает на него ссылку. Установленный бинарник Claude Code в рантайме также не исполняется внутри Node.js.

Таким образом, утверждение о том, что для запуска Claude Code всегда необходим Node.js, технически неверно. Проверять версию Node.js требуется только тогда, когда вы целенаправленно используете установку через npm.

Команды установки для поддерживаемых систем

Для корректной инсталляции используйте официальные скрипты в соответствии с вашей операционной системой и используемой оболочкой.

macOS, Linux и WSL (Bash / Zsh)

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows Командная строка (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Альтернативная установка через npm

npm install -g @anthropic-ai/claude-code

Важно: не запускайте команду с sudo npm install -g. Использование суперпользователя приводит к конфликтам прав доступа к файлам в домашнем каталоге и создает риски безопасности.

На нативной платформе Windows наличие пакета Git for Windows теперь опционально. Если Git for Windows присутствует, агент сможет запускать Bash-команды через Git Bash; если утилита не установлена, Claude Code использует встроенный инструмент PowerShell.

Проверка работоспособности установки

После завершения скрипта проверьте, что бинарный файл доступен в системе:

claude --version

Корректный вывод версии подтверждает, что файл скачан, распакован и зарегистрирован в окружении. Обратите внимание: успешное отображение версии подтверждает лишь работоспособность самого бинарного файла, но не означает, что клиент авторизован или способен выполнять запросы к модели.

Для расширенного аудита среды выполните диагностическую команду:

claude doctor

Команда claude doctor выполняет диагностику окружения: она проверяет состояние файлов настроек, права доступа и компоненты системы, выявляя возможные проблемы конфигурации без запуска интерактивного сеанса работы с кодом.

Диагностика: что делать при ошибке command not found

Если терминал сообщает, что команда claude не найдена (или в Windows выводится сообщение о том, что команда не является внутренней или внешней), последовательно выполните следующие шаги:

[Ошибка вызова: claude не найден]
         │
         ▼
[Шаг 1: Открыть новый сеанс терминала]
         │
    Помогло? ──Да──> Завершено
         │ Нет
         ▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
         │
    Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
         │ Да
         ▼
[Шаг 3: Проверить тип установки и PATH]
         │
 ┌───────┴────────────────────────┐
 ▼                                ▼
[Native Install]                [npm Install]
Проверить PATH:                 Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin            - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)

1. Откройте новый терминал

Скрипты установки вносят изменения в конфигурационные файлы оболочки (.bashrc, .zshrc) или в переменные среды пользователя Windows. Уже открытые окна терминала эти изменения на лету не подхватывают. Полностью закройте текущую сессию и откройте новое окно.

2. Проверьте физический путь к файлу

При Native Install исполняемый файл по умолчанию размещается по стандартным путям (если они не были переопределены):

• на macOS, Linux и WSL: ~/.local/bin/claude (версии хранятся в ~/.local/share/claude);
• на Windows: %USERPROFILE%\.local\bin\claude.exe.

Указанные пути являются стандартными по умолчанию, а не неизменяемыми при наличии пользовательских переопределений. Если файла в каталоге нет, процесс установки, возможно, завершился аварийно из-за блокировки сети или прав записи.

3. Запустите команды диагностики оболочки

Для выяснения того, видит ли оболочка исполняемый файл, используйте штатные средства:

• в Zsh / Bash: выполните command -v claude или type -a claude;
• в PowerShell: вызовите Get-Command claude, а также утилиту where.exe claude;
• в CMD: используйте команду where claude.

4. Разделяйте переменные PATH для Native и npm

Распространенная ошибка — попытка восстановить пути Node.js при сбое Native Install.

• Если вы ставили программу через Native Install, каталоги Node.js или npm prefix -g не имеют отношения к проблеме. Проверять и добавлять в переменную PATH требуется директорию ~/.local/bin (для Unix-систем) либо %USERPROFILE%\.local\bin (для Windows).
• Для установки через npm install -g каталог исполняемых файлов определяется командой npm prefix -g:
  • на Unix-подобных системах (macOS, Linux, WSL) исполняемый файл помещается в <prefix>/bin;
  • на Windows исполняемый файл находится непосредственно в корне <prefix>. Команды npm bin -g и npm root -g не указывают на верный путь к исполняемым файлам.

Если бинарный файл присутствует на диске, но команда не найдена, сначала проверьте PATH и то, как оболочка разрешает исполняемый файл. Если запуск по его полному пути также завершается ошибкой, изучите точный текст ошибки и официальное руководство по устранению неполадок установки: внимания могут потребовать права доступа, совместимость бинарного файла с платформой или неполная установка. Не выполняйте переустановку вслепую только из-за ошибки command not found.

Первый запуск и безопасное ознакомление

После подтверждения доступности команды перейдите в каталог небольшого проекта и запустите сессию:

cd /path/to/test-project
claude

При первом старте интерфейс предложит пройти стандартную процедуру авторизации через браузер. Внутри запущенного сеанса команда /status позволяет проверить текущую директорию, идентификатор учетной записи и используемую модель.

Для первого знакомства выполните упражнение с вводным запросом:

Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.

Конкретный ожидаемый ответ: агент перечисляет основные файлы и объясняет их назначение, не генерируя diff и не производя правок. После завершения задачи выполните команду git diff, чтобы убедиться в отсутствии изменений в кодовой базе.

Важно понимать: текстовая инструкция в промпте — это лишь указание модели в тексте запроса, а не принудительный режим выполнения (enforced mode) и не системная песочница. Если для репозитория требуется ограничить автоматическое редактирование файлов, используйте режим планирования:

claude --permission-mode plan

В режиме plan агент по умолчанию читает файлы и использует команды оболочки только для чтения, не редактируя исходный код, однако этот режим не является изолированной песочницей на уровне ОС: когда доступно автоматическое выполнение, могут запускаться команды, одобренные классификатором (не следует заявлять о жесткой системной изоляции; сведения подтверждены документацией от 2026-09-15).

Подробное описание политик подтверждения действий приведено в руководстве по разрешениям. Для завершения работы с агентом используйте сочетание клавиш Ctrl+D.

Подключение независимого API-провайдера

Установка клиентской утилиты и последующая настройка поставщика моделей — это два независимых шага. Если вместо стандартной учетной записи вы используете подключение через сторонний Anthropic-совместимый шлюз, настройку параметров доступа выполняют отдельно после проверки работы CLI.

В частности, независимый API-провайдер BetterToken предоставляет разработчикам персональный API Key, а статистика обращений к моделям, расход токенов и биллинг отслеживаются в панели управления Dashboard. Инструкции по экспорту переменных окружения и указанию базового адреса API приведены в документации BetterToken по Claude Code. Сама загрузка, обновление и локальный запуск бинарного файла производятся штатными средствами CLI согласно шагам из этого руководства.