Claude Code на Windows: установка через WSL и частые ошибки

Claude Code на Windows устанавливается через WSL — подсистему Windows для запуска Linux-окружения, а не напрямую в обычном PowerShell или командной строке. Так сложилось потому, что сам инструмент и большинство его зависимостей изначально рассчитаны на Linux. Ниже — пошаговая установка, частые ошибки новичков и то, на что стоит обратить внимание, чтобы не тратить время на обход проблем, которых легко избежать на старте.

Почему именно через WSL

Claude Code и многие инструменты разработки вокруг него — пакетные менеджеры, скрипты сборки, системы контроля версий — изначально ориентированы на команды и структуру путей, привычную для Linux и Mac. Обычная командная строка Windows или PowerShell воспроизводит это окружение лишь частично, и часть зависимостей на них работает нестабильно или вовсе не работает.

WSL решает эту проблему, не требуя отдельной виртуальной машины или двойной загрузки системы — Linux-окружение запускается внутри Windows и доступно из обычного терминала, настроенного на работу с WSL.

Пошаговая установка

1. Включите WSL. В терминале Windows с правами администратора выполните команду установки WSL — система предложит перезагрузку после завершения.
2. Установите дистрибутив Linux внутри WSL. Чаще всего используют Ubuntu — он хорошо документирован и совместим с большинством инструментов разработки.
3. Обновите пакеты внутри WSL-окружения. Перед установкой Claude Code стоит обновить менеджер пакетов самого Linux-дистрибутива, чтобы избежать конфликтов версий зависимостей.
4. Установите Node.js внутри WSL, если он не предустановлен. Claude Code рассчитан на определённую версию Node.js — её стоит установить именно внутри WSL, отдельно от версии, которая может уже стоять в обычной Windows.
5. Установите сам Claude Code через менеджер пакетов внутри WSL-терминала. После установки команда запуска доступна из того же терминала.
6. Откройте рабочий проект внутри файловой системы WSL. Если проект хранится в обычной папке Windows, его сначала стоит скопировать или клонировать внутрь WSL — это избавляет от проблем с путями на следующем шаге.

# внутри WSL-терминала, после установки Node.js
npm install -g @anthropic-ai/claude-code
claude

Частые ошибки на старте

Где хранить проект, чтобы не было проблем с путями

Главная практическая деталь, которую часто упускают новички: файловая система Windows и файловая система WSL — это формально разные пространства, и обращение к файлам Windows из WSL работает медленнее и менее предсказуемо, чем работа внутри самого WSL. С самого начала разумно клонировать или создавать рабочий проект внутри домашней папки WSL-дистрибутива, а не в обычной папке вроде рабочего стола Windows.

Если проект уже существует в папке Windows и нужно продолжить работу с ним через Claude Code, его стоит скопировать внутрь WSL перед началом работы. Постоянный доступ через примонтированный путь кажется более быстрым решением на первый взгляд, но на практике чаще приводит к проблемам с правами доступа и скоростью файловой системы, чем простое перемещение проекта внутрь WSL.

Чем работа дальше отличается от Linux или Mac

После завершения установки WSL и Claude Code внутри него дальнейшая работа почти не отличается от работы на Linux или Mac: те же команды, тот же способ запуска, та же логика работы с проектом из терминала. Основная разница остаётся на этапе установки — именно здесь чаще всего возникают вопросы, связанные с особенностями Windows как платформы.

Это значит, что инструкции и примеры, написанные для Linux или Mac, в большинстве случаев подходят и для Windows с WSL без изменений. Достаточно убедиться, что команды выполняются именно в WSL-терминале, который открывается отдельно от обычной командной строки Windows.

Что делать, если WSL уже установлен для других задач

Часто WSL на компьютере уже стоит ради другого инструмента разработки — и в этом случае Claude Code можно установить в тот же дистрибутив без создания нового окружения с нуля. Стоит только проверить версию Node.js: если она старше требуемой для Claude Code, разумнее обновить именно её, а не ставить второй параллельный дистрибутив только из-за версии одного пакета.

Если на компьютере уже настроено несколько дистрибутивов WSL под разные проекты, Claude Code стоит ставить в тот, где фактически лежит рабочий проект — установка в неправильный дистрибутив — частая причина путаницы, когда команда вроде бы работает, но не видит нужные файлы.

Типичные вопросы при переходе с Mac или Linux на Windows с WSL

Специалисты, которые раньше работали с Claude Code на Mac или Linux и переходят на рабочий компьютер с Windows, чаще всего спрашивают про производительность и про доступ к привычным инструментам. Производительность внутри WSL на современном железе обычно сопоставима с нативным Linux для большинства задач разработки — заметная разница появляется в основном при частом обращении к файлам на диске Windows, а не внутри самого WSL.

Доступ к привычным инструментам — редакторам, системам контроля версий, менеджерам пакетов — в WSL работает так же, как на отдельном Linux-компьютере, поскольку это и есть полноценное Linux-окружение, а не его имитация. Переучиваться заново почти не приходится: разница касается в основном первого шага настройки, а не повседневной работы после него.

Было и стало: первая установка на рабочем ноутбуке с Windows

Было. Разработчик попытался установить Claude Code прямо в обычном PowerShell, получил ошибки на этапе установки зависимостей, потратил вечер на поиск причины и в итоге узнал про необходимость WSL уже после нескольких неудачных попыток.

Стало. Перед установкой разработчик сразу включил WSL, поставил внутри него Ubuntu и Node.js нужной версии, перенёс рабочий проект в файловую систему WSL и установил Claude Code одной командой — весь процесс занял меньше часа без единой ошибки, потому что порядок шагов был известен заранее.

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

Где ИИ ошибается

Сам Claude Code не связан с ошибками установки — они возникают на уровне операционной системы и путей к файлам, а не из-за качества ответов модели. Но после успешной установки стоит помнить общее ограничение агентных инструментов: при работе с файлами проекта Claude Code выполняет реальные действия — изменяет файлы, выполняет команды, — и промежуточные шаги стоит проверять, особенно на первых запусках в новом проекте.

Также не стоит путать ошибки окружения Windows с ошибками самого инструмента: если команда не срабатывает, в первую очередь стоит проверить, что терминал действительно открыт внутри WSL, а не в обычной командной строке Windows — это самая частая причина проблем на старте.

Стоит ли ждать прямой поддержки Windows без WSL

Вопрос «когда уберут необходимость в WSL» звучит часто, но практического смысла ждать этого немного: даже если прямая поддержка появится, экосистема инструментов разработки вокруг Claude Code ещё долго будет ориентирована на Linux-команды и пути файлов. WSL уже сейчас даёт стабильный результат, и настройка один раз избавляет от повторных вопросов на каждом новом проекте.

Время, потраченное на правильную установку WSL в самом начале, окупается на первом же проекте — дальнейшая работа не требует постоянного решения проблем совместимости, которые иначе всплывали бы на каждом шаге.

Что дальше

Базовая настройка Claude Code за пять шагов — в статье настройка Claude Code. С чего начать новичку в работе с Claude Code — в статье Claude Code: с чего начать новичку. Какие плагины, скиллы и MCP-серверы стоит установить дальше — в статье плагины для Claude Code.

Ярослав Сажнев — преподаватель ИИ в РАНХиГС, внедрение ИИ в компании. Подробнее об авторе