Claude Code Windows: установка, Git Bash, WSL и грабли по пути

Что это решает

Claude Code Windows — самый частый запрос тех, у кого рабочая машина не на macOS: официальные инструкции написаны в расчёте на Unix-оболочку, и на первом же шаге начинаются расхождения. Пакет ставится, claude запускается, а дальше агент пытается выполнить ls -la, натыкается на отсутствие bash, путается в путях с обратным слэшем и в кавычках PowerShell. Отдельная порция граблей ждёт тех, кто ставит всё внутрь WSL: там свои проблемы с версией Node, с производительностью на дисках /mnt/c и с переводами строк, которые после первой же правки превращают диф в полностью переписанный файл. Ниже — оба рабочих контура и список поломок, которые встречаются почти у всех.

Как устроено

На Windows есть два самостоятельных способа запуска, и выбирать между ними лучше один раз, а не смешивать.

Контур 1: нативный Windows. CLI ставится в Windows, работает с файлами NTFS напрямую, PowerShell остаётся основным терминалом. Ключевая деталь — инструмент запуска команд рассчитан на POSIX-оболочку, поэтому нативной установке нужен Git for Windows: команды агента уходят в bash.exe из его комплекта. Если Git не установлен или лежит не там, где ожидается, путь задаётся переменной окружения CLAUDE_CODE_GIT_BASH_PATH.

Контур 2: WSL2. Внутри дистрибутива ставится Node и CLI, дальше всё ведёт себя как обычный Linux — без оговорок про оболочку, пути и права. Плата — раздельные файловые системы: проект, лежащий в /mnt/c/Users/..., читается и пишется через прослойку и работает заметно медленнее, особенно на каталогах вроде node_modules с десятками тысяч мелких файлов.

Где живут настройки. Каталог пользователя — %USERPROFILE%\.claude (в WSL — ~/.claude), настройки проекта — .claude\settings.json и личный .claude\settings.local.json рядом с кодом, память проекта — CLAUDE.md в корне репозитория. Правила разрешений пишутся с прямыми слэшами (Read(./src/**)) независимо от того, как выглядят пути в проводнике.

Что ломается на стыке. PATH после глобальной установки npm, политика выполнения скриптов PowerShell для .ps1-обёртки, предел длины пути в 260 символов, кириллица в имени пользователя, антивирус, который проверяет каждый файл в node_modules, и корпоративный прокси с подменой TLS-сертификата.

Правило одной строкой: если в проекте есть Makefile, bash-скрипты или docker-compose — ставить в WSL; если стек чисто виндовый (.NET, PowerShell, MSBuild) — ставить нативно, но обязательно с Git for Windows.

Как подключить

Нативная установка

Шаг 1. Терминал и Node. Windows Terminal с PowerShell — рабочий минимум; классический cmd.exe хуже справляется с цветами и переносами. Node.js ставится актуальной LTS-версией (требуемый минимум указан на странице установки).

node --version
npm --version

Шаг 2. Пакет.

npm install -g @anthropic-ai/claude-code
where.exe claude
claude --version

Если where.exe claude ничего не находит, каталог глобальных пакетов не попал в PATH. Смотреть так:

npm config get prefix

Полученный путь (обычно внутри %APPDATA%\npm) добавляется в переменную PATH пользователя, после чего терминал перезапускается — открытая сессия старую PATH не перечитывает.

Шаг 3. Ошибка про запрет выполнения скриптов. Если запуск claude падает с сообщением о политике выполнения, снимается это на уровне текущего пользователя, без прав администратора:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Шаг 4. Git for Windows. Ставится с официального сайта. Если агент жалуется, что не может выполнить команду оболочки, путь к bash задаётся явно:

setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"

Переменная читается при старте процесса — терминал после setx перезапускается.

Шаг 5. Первый запуск.

cd C:\projects\my-app
claude

Внутри: /login, затем /status (аккаунт, модель, рабочий каталог) и /init для стартового CLAUDE.md.

Установка в WSL2

Шаг 1. Дистрибутив. wsl --install из PowerShell с правами администратора, перезагрузка, создание пользователя.

Шаг 2. Node внутри дистрибутива. Самая частая ошибка — использовать Node, установленный в Windows: он виден из WSL через PATH и внешне работает. Проверка:

which node && which npm

Пути должны начинаться с /usr или /home, а не с /mnt/c. Если начинаются с /mnt/c, Node ставится внутрь дистрибутива (через пакетный менеджер или менеджер версий), а виндовые пути убираются из начала PATH.

Шаг 3. Пакет.

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

Если npm отказывается ставить пакет, ссылаясь на несовпадение платформы (последствие смешанной установки), помогает явное указание платформы в конфиге npm перед повторной попыткой.

Шаг 4. Где держать проект. В файловой системе Linux — ~/projects/..., не в /mnt/c/Users/.... Открывать такой проект из редактора Windows можно через режим удалённого подключения к WSL, а вот класть исходники на диск C и работать с ними из WSL — верный способ получить медленную сборку и пропущенные события файловых наблюдателей.

Гигиена репозитория (обоим контурам)

Переводы строк — источник дифов, где «изменён весь файл»:

git config --global core.autocrlf input

и файл .gitattributes в репозитории:

* text=auto eol=lf

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

git config --global core.longpaths true

Антивирусу задаются исключения на каталог проекта и кеш npm — иначе каждый шаг агента упирается в проверку файлов. За корпоративным прокси с подменой сертификата понадобятся переменные HTTPS_PROXY и NODE_EXTRA_CA_CERTS с путём к корневому сертификату компании.

Полезные сценарии

Виндовый стек без bash-обвязки (.NET, MSBuild, PowerShell-скрипты) — нативная установка плюс Git for Windows ради оболочки.
Веб-проект с docker-compose и shell-скриптами — WSL2, проект в домашнем каталоге Linux.
Разбор упавшей сборки: вывод команды кладётся в контекст через ! прямо из сессии, без копипасты из другого окна.
Разовая задача на чужой машине без прав администратора: установка npm-пакетом в профиль пользователя, без установщика.
Работа с двумя репозиториями сразу — --add-dir на второй каталог вместо запуска из общего родителя.
Автоматическая проверка перед пушем: claude -p с дифом на входе, вызванный из Git-хука, который в Windows-репозитории всё равно исполняется Git-овским bash.

Ограничения

Инструмент запуска команд ждёт POSIX-оболочку. Без Git for Windows нативная установка остаётся полурабочей: чтение и правка файлов есть, запуск команд отваливается.
Смешанная установка не поддерживается по-хорошему: Node из Windows плюс CLI внутри WSL дают плавающие ошибки, которые не диагностируются по сообщению.
Проект на /mnt/c при работе из WSL медленный, и это не лечится настройками — только переносом в файловую систему Linux.
Кириллица и пробелы в имени пользователя ломают часть цепочки инструментов раньше, чем сам CLI; в спорном случае проще завести профиль с латинским именем, чем чинить каждый пакет отдельно.
Предел длины пути упирается не только в Git: сборщики и пакетные менеджеры создают глубокие вложенные каталоги, и без включённых длинных путей падает именно установка зависимостей.
Сочетания клавиш совпадают с терминальными не полностью: перенос строки в многострочном вводе и вставка изображения из буфера зависят от терминала, часть настраивается через /terminal-setup.
Хуки и правила разрешений, написанные под Unix-утилиты, на нативной установке работают только пока рядом есть Git-овский bash; в командном репозитории это стоит записать в CLAUDE.md.

Как проверить результат

claude doctor — показывает тип установки, версию и проблемы окружения; это первая команда при любом «не запускается».
where.exe claude (или which claude в WSL) — путь ровно один; два найденных исполняемых файла означают, что параллельно живут нативная установка и установка из WSL.
/status в сессии — рабочий каталог совпадает с проектом, а не с домашним каталогом пользователя.
Проверка оболочки: попросить агента выполнить pwd && ls -la. Ответ с содержимым каталога — Git-овский bash найден; ошибка запуска — проверять CLAUDE_CODE_GIT_BASH_PATH.
Проверка переводов строк: попросить изменить одну строку в существующем файле и посмотреть git diff. В дифе должна быть одна строка, а не весь файл.
Проверка WSL-установки: which node возвращает путь внутри Linux, pwd в каталоге проекта не начинается с /mnt/c.
Проверка сети и прокси: если авторизация или обновление падают на таймауте, npm ping из того же терминала покажет, дело в CLI или в корпоративном прокси.
Контрольный прогон: claude -p "Выведи имя текущей ветки и число незакоммиченных файлов" — короткая задача, которой хватает, чтобы одновременно проверить оболочку, права и доступ к репозиторию.