Работа в WSL¶

Windows Subsystem for Linux (WSL) позволяет запускать Linux прямо в Windows. Проект при этом лежит в Linux-окружении, а работать с ним можно и из VS Code, и из IDE на платформе IntelliJ.

Главное правило: Koda работает там же, где находится проект, — то есть внутри WSL. Команды, чтение и запись файлов, поиск, индексация и настройки выполняются на стороне WSL.

Как это устроено¶

VS Code IntelliJ

В удалённом окне VS Code держит проект и всё, что с ним связано, на стороне WSL. Koda работает там же:

чтение и запись файлов происходят в WSL;
инструменты агента — чтение, редактирование, поиск и запуск команд — видят файлы внутри WSL;
терминал открывается внутри WSL;
индекс кодовой базы и настройки хранятся в WSL.

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

В IDE на платформе IntelliJ WSL поддерживается двумя способами, и от выбора зависит, где работает Koda.

Нативная интеграция. IDE запущена на Windows, а проект открыт прямо из файловой системы WSL — по пути вида \\wsl.localhost\.... Тогда Koda работает вместе с IDE на стороне Windows: команды выполняются в оболочке Windows, а файлы проекта читаются и записываются по пути к WSL.

Удалённый запуск. Бэкенд IDE запускается внутри WSL — через Remote Development или прямо в WSL. Тогда Koda устанавливается в бэкенд и работает внутри WSL:

файлы читаются и записываются в WSL;
команды выполняются оболочкой WSL;
индекс кодовой базы и настройки хранятся в WSL.

Чтобы Koda работала именно внутри WSL, используйте удалённый запуск.

Простая проверка

Попросите агента выполнить в терминале команду pwd. Если путь начинается с /home/..., значит Koda работает внутри WSL.

Что это значит на практике

Файлы вашей системы Windows при работе в WSL Koda не затрагивает. Всё, что она делает с проектом, происходит внутри WSL.

Что нужно сделать¶

Установить WSL и дистрибутив на Windows-хост — см. раздел Установка WSL.
Открыть проект в WSL — см. раздел Открытие проекта.
Установить Koda в WSL, а не только на Windows — см. раздел Установка Koda.
Войти в аккаунт — так же, как при обычной работе.
Убедиться, что изнутри WSL доступен api.kodacode.ru — см. раздел Сеть.
Установить в WSL ripgrep — тогда поиск по коду будет быстрым, см. раздел Поиск по коду.
Держать файлы проекта в родной файловой системе Linux, а не на диске Windows — см. раздел Индексация.

Установка WSL¶

Перед работой с проектом установите саму подсистему и дистрибутив Linux на стороне Windows.

На Windows включите компонент Windows Subsystem for Linux — через диалог «Включение и отключение компонентов Windows» или командой в PowerShell от имени администратора:
```
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```
После этого потребуется перезагрузка.
Установите дистрибутив Linux — например, Ubuntu из Microsoft Store. При первом запуске дистрибутива создайте пользователя и пароль.

Дополнительная информация — на сайте microsoft.com.

Открытие проекта¶

VS Code IntelliJ

Сначала убедитесь, что выполнены условия:

WSL установлен на вашей Windows-машине;
VS Code установлен на стороне Windows, а не внутри WSL;
установлено расширение WSL (ms-vscode-remote.remote-wsl).

Открыть проект можно одним из способов.

Из терминала WSL (самый простой путь):

Откройте терминал WSL — из меню «Пуск» или командой wsl в командной строке.
Перейдите в папку проекта командой cd.
Выполните code . — откроется окно VS Code, подключённое к WSL.
При первом запуске VS Code установит в WSL сервер и нужные компоненты — это занимает немного времени и требуется только один раз.

Открытие проекта из WSL

cd ~/projects/my-app
code .

Из VS Code:

Нажмите F1 и выберите WSL: Connect to WSL для дистрибутива по умолчанию или WSL: Connect to WSL using Distro для конкретного дистрибутива.
Через меню Файл откройте нужную папку.

Если папка уже открыта локально, выполните команду WSL: Reopen Folder in WSL — VS Code предложит выбрать дистрибутив.

Из командной строки Windows. Если нужно открыть конкретный путь:

code --remote wsl+Ubuntu /home/jim/projects/c

Здесь wsl+Ubuntu — имя дистрибутива, а /home/jim/projects/c — путь внутри WSL.

Как убедиться, что всё получилось. В левом нижнем углу окна появится индикатор WSL: Ubuntu (имя вашего дистрибутива). Любой терминал, открытый через Терминал → Новый терминал, будет работать внутри WSL. Вернуться к локальному окну можно командой Файл → Закрыть удалённое подключение.

Подробнее о работе с WSL в VS Code: WSL, WSL Tutorial

Сначала убедитесь, что WSL установлен на вашей Windows-машине.

Нативная интеграция. IDE работает на Windows, а проект берётся из файловой системы WSL:

В окне приветствия нажмите Открыть (или выберите Файл → Открыть).
Укажите папку проекта в файловой системе WSL — например, \\wsl.localhost\Ubuntu\home\test\MyProject.
Проект откроется как обычный, а запуск и отладка будут выполняться в WSL.

Новый проект в WSL создаётся так же: в окне приветствия нажмите Создать проект и в поле Расположение укажите путь вида \\wsl.localhost\Ubuntu\home\test\MyProject.

Каталог, который IDE предлагает по умолчанию, можно задать в настройках: Настройки → Каталоги → Каталог проектов по умолчанию.

Удалённый запуск.

Убедитесь, что включён плагин Remote Development Gateway.
В окне приветствия IntelliJ IDEA выберите Remote Development, затем WSL, и нажмите New Connection. То же доступно из JetBrains Toolbox App и JetBrains Gateway.
Выберите экземпляр WSL и нажмите Next.
Выберите версию IDE и проект, затем нажмите Start IDE and Connect.

Бэкенд IDE скачается и запустится внутри WSL, а проект откроется в JetBrains Client.

Плагин Koda устанавливается уже в запущенный бэкенд — см. раздел Установка Koda.

Про путь к проекту

В нативной интеграции путь к проекту в WSL начинается с \\wsl.localhost\<Дистрибутив>\..., где <Дистрибутив> — имя вашего дистрибутива, например Ubuntu. Внутри WSL тот же проект лежит по обычному Linux-пути, например /home/test/MyProject.

Подробнее о работе с WSL в JetBrains — в документации JetBrains.

Установка Koda¶

VS Code IntelliJ

Откройте проект в WSL — как описано в разделе Открытие проекта.
Откройте раздел Расширения.
Найдите Koda.koda и нажмите Установить в WSL.
Дождитесь установки и при необходимости перезагрузите окно.

Если расширение уже стоит на вашем компьютере, VS Code обычно сам предлагает установить его и в WSL.

Где установлено расширение

В списке расширений есть отдельные категории: Local - Installed — расширения на стороне Windows, и WSL: Ubuntu — Installed — расширения внутри WSL. Расширения, установленные локально, но нужные в WSL, показаны приглушёнными: рядом с ними есть кнопка Установить. Установить сразу все локальные расширения в WSL можно кнопкой с облаком рядом с заголовком Local - Installed.

Нативная интеграция. Установите плагин Koda в IDE обычным способом — через раздел Настройки → Плагины → Marketplace.

Удалённый запуск. Установите плагин Koda в бэкенд IDE, работающий внутри WSL, — так же, как другие плагины в режиме Remote Development.

Общая инструкция по установке — на странице Установка плагина.

Файлы, пути и терминал¶

Koda работает с файлами проекта напрямую, поэтому пути указываются так, как они выглядят в WSL.

Относительные пути (например, src/index.ts) ищутся в корне проекта.
Абсолютные пути внутри WSL (например, /home/user/project) разрешаются в файловой системе WSL.
Пути Windows (например, D:\project) указывают на файловую систему Windows.

Команды выполняются в терминале на стороне WSL.

Команды работают в том же окружении, что и проект, поэтому доступны все установленные в WSL утилиты.
Терминал Koda переиспользуется: если команда активировала виртуальное окружение или изменила переменные, это сохраняется между вызовами.
Команды можно останавливать — Koda прерывает их и при необходимости закрывает терминал.
Слишком большой вывод команды сокращается до 2000 строк или 50 КиБ, а полный текст сохраняется в файл — см. «Большой вывод инструментов».

Файлы вне проекта

Инструменты работают в первую очередь с файлами открытого проекта. Если путь ведёт за пределы проекта, Koda может его не найти.

Оболочка окружения

Koda использует оболочку WSL, а не вашу локальную. Если команда ведёт себя иначе, чем в вашем обычном терминале, проверьте оболочку по умолчанию в WSL.

Поиск по коду¶

VS Code IntelliJ

Поиск по содержимому выполняется на стороне WSL. Koda сама проверяет, какие средства поиска доступны внутри WSL, и выбирает из двух вариантов:

ripgrep (rg) — быстрый поиск, как в локальном окружении;
обычный grep — запасной вариант, если ripgrep не установлен.

Ограничения запасного варианта

У grep нет части возможностей ripgrep: часть шаблонов поиска переводится в упрощённый вид, а очень длинные строки обрезаются. Для надёжного поиска по содержимому установите ripgrep внутри WSL.

Если ни ripgrep, ни grep не найдены, поиск по содержимому в проекте недоступен.

Установить ripgrep в WSL на базе Debian и Ubuntu можно так:

Установка ripgrep в WSL

sudo apt-get update && sudo apt-get install -y ripgrep

Поиск по содержимому работает обычным для JetBrains способом — через упакованный или системный ripgrep. Отдельно устанавливать ripgrep в WSL не нужно.

Поиск файлов по имени учитывает правила .gitignore и .kodaignore.

Запуск и отладка¶

VS Code IntelliJ

Запуск и отладка работают так же, как в локальном проекте, но выполняются внутри WSL. Выберите конфигурацию в launch.json и запустите отладку — приложение стартует в WSL, а отладчик подключается к нему.

Код проекта запускается и отлаживается в WSL.

При нативной интеграции WSL в конфигурации запуска указывается как локальная машина, а результат выполнения виден в окне Run.
Если проект лежит в Windows, а запускать его нужно в WSL, используйте цели запуска (run targets): добавьте цель WSL в конфигурации запуска.

Брандмауэр Windows при отладке

Чтобы сборка и отладка проектов в WSL работали корректно, разрешите подключения к WSL в брандмауэре Windows. Откройте PowerShell от имени администратора и выполните команду:

New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow

Если имя интерфейса отличается, уточните его командой Get-NetAdapter. При запуске отладки, когда появится запрос брандмауэра Windows, разрешите доступ для общественных сетей.

Индексация¶

Данные индексации хранятся на стороне WSL, в каталоге ~/.koda/index внутри WSL. Поэтому индекс не переносится между Windows и WSL автоматически.

Впервые открыв проект в WSL, Koda построит индекс заново.
Проекты на смонтированных дисках Windows работают медленнее, чем файлы внутри Linux-файловой системы.

Где хранить проект

Держите файлы в родной файловой системе Linux (например, ~/projects/...), а не на смонтированном диске Windows (например, /mnt/c/...). Это заметно ускоряет и поиск, и индексацию.

Индексация включается на вкладке Индексация в настройках — см. Настройки индексации. Подробнее о решении проблем с индексацией — на странице Индексация.

Настройки¶

В WSL Koda читает настройки со стороны WSL — как если бы она была запущена в этой системе.

Глобальный файл config.yaml лежит в ~/.koda/config.yaml внутри WSL, а не в ~/.koda вашей системы Windows.
Проектный файл .kodarc.json — в корне проекта внутри WSL.
Правила из файла .kodarules и игноры из .kodaignore — также в корне проекта в WSL.
Локальные навыки из .koda/skills, .claude/skills и .agents/skills ищутся относительно корня проекта в WSL.

Настройки у каждой стороны свои

У Windows и WSL разные домашние каталоги, поэтому ~/.koda/config.yaml у них не общий. Настройки, сделанные в Windows, не переносятся в WSL автоматически. Если настройки нужны и там, скопируйте файл конфигурации в ~/.koda внутри WSL.

Если индексация в WSL идёт слишком тяжело, её нагрузку можно снизить в секции indexingOptions:

~/.koda/config.yaml

indexingOptions:
  concurrency: 2
  batchSize: 50

Полностью отключить индексацию можно параметром disableIndexing.

Сеть¶

Запросы к моделям Koda выполняет та же сторона, где работает Koda, — то есть WSL.

Изнутри WSL должен быть доступен api.kodacode.ru.
Если вы используете прокси или VPN, настройте их доступность и внутри WSL, а не только в Windows.

Типичные проблемы¶

Koda не видит файлы проекта¶

Убедитесь, что Koda установлена внутри WSL, а проект открыт в WSL. Проверьте, что папка проекта действительно открыта как рабочая область.

Команды выполняются не там, где ожидается¶

Команды всегда выполняются на стороне WSL. Если вы ожидали команды Windows, откройте проект локально.

Поиск по содержимому ничего не находит¶

Проверьте, установлен ли ripgrep или grep внутри WSL. Также убедитесь, что искомый текст не исключён правилами .gitignore или .kodaignore.

Медленная индексация или поиск¶

Перенесите проект в родную файловую систему Linux. Для проектов на смонтированных дисках Windows (например, /mnt/...) операции ввода-вывода значительно медленнее.

Koda не отвечает¶

Проверьте, что изнутри WSL есть доступ к api.kodacode.ru — см. раздел Сеть. Если вы используете прокси или VPN, они тоже должны быть доступны внутри WSL.

Не запускайте IDE через WSLg¶

Запускать IDE на платформе IntelliJ через WSLg не рекомендуется: у WSLg есть ограничения по отрисовке, всплывающим окнам, управлению окнами и вводу. Для работы с WSL используйте нативную интеграцию или удалённый запуск — см. раздел Открытие проекта.