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

Руководство по Windows (WSL2)

VibeOS теперь поддерживает как нативную Windows, так и WSL2. Эта страница описывает путь через WSL2; для установки через нативный PowerShell смотрите отдельное Руководство по Windows (нативное).

Когда выбирать WSL2 вместо нативного варианта:

  • Вы хотите использовать встроенный терминал панели управления (вкладка /chat) — эта панель требует POSIX PTY и доступна только в WSL2.
  • Вы занимаетесь разработкой, активно использующей POSIX, и хотите, чтобы сессии VibeOS использовали ту же файловую систему и пути, что и ваши инструменты разработки.
  • У вас уже есть среда WSL2, и вы не хотите поддерживать вторую установку.

Когда нативный вариант подходит (или лучше):

  • Интерактивный чат, шлюз (Telegram/Discord и т.д.), планировщик cron, инструмент браузера, MCP-серверы и большинство функций VibeOS работают в нативной Windows.
  • Вы не хотите каждый раз думать о пересечении границы WSL↔Windows при обращении к файлу или открытии URL.

В WSL2 фактически задействованы два компьютера: ваш хост Windows и виртуальная машина Linux, управляемая WSL. Большинство путаницы возникает из-за непонимания, на каком из них вы находитесь в данный момент.

Это руководство охватывает те аспекты этого разделения, которые напрямую влияют на VibeOS: установка WSL2, передача файлов между Windows и Linux, сетевое взаимодействие в обоих направлениях и типичные ошибки, с которыми сталкиваются пользователи.

简体中文

Китайское пошаговое руководство по минимальной установке поддерживается на этой же странице — переключитесь через меню language (вверху справа) и выберите 简体中文.

Зачем нужен WSL2 (вместо нативной Windows)​

Нативная установка Windows работает непосредственно в Windows: ваш терминал Windows (PowerShell, Windows Terminal и т.д.), пути файловой системы Windows (C:\Users\…) и процессы Windows. VibeOS использует Git Bash для выполнения команд оболочки — это то, как Claude Code и другие агенты работают с Windows сегодня; это обходит разрыв между POSIX и Windows без полной переработки.

WSL2 запускает настоящее ядро Linux в легковесной виртуальной машине, поэтому VibeOS внутри него практически идентичен работе на Ubuntu. Это ценно, когда вам нужна настоящая среда POSIX: fork, /tmp, UNIX-сокеты, семантика сигналов, терминалы на основе PTY, оболочки типа bash/zsh и инструменты вроде rg, git, ffmpeg, которые ведут себя так же, как на Linux.

Практические последствия использования WSL2:

  • CLI VibeOS, шлюз, сессии, память, навыки и среды выполнения инструментов находятся внутри виртуальной машины Linux.
  • Программы Windows (браузеры, нативные приложения, Chrome с вашим вошедшим профилем) находятся снаружи.
  • Каждый раз, когда вы хотите, чтобы они взаимодействовали — обменивались файлами, открывали URL, управляли Chrome, обращались к локальному серверу моделей, открывали шлюз VibeOS для вашего телефона — вы пересекаете границу. Именно об этих границах и пойдет речь в этом руководстве.

Установка WSL2​

Из административной PowerShell или Windows Terminal:

wsl --install

На свежей Windows 10 22H2+ или Windows 11 эта команда устанавливает ядро WSL2, компонент Virtual Machine Platform и дистрибутив Ubuntu по умолчанию. Перезагрузитесь, когда будет предложено. После перезагрузки Ubuntu откроется и запросит имя пользователя Linux + пароль — это новый пользователь Linux, не связанный с вашей учетной записью Windows.

Убедитесь, что вы используете WSL2 (а не устаревший WSL1):

wsl --list --verbose

Вы должны увидеть VERSION 2. Если дистрибутив показывает VERSION 1, преобразуйте его:

wsl --set-version Ubuntu 2
wsl --set-default-version 2

VibeOS нестабильно работает на WSL1 — WSL1 транслирует системные вызовы Linux «на лету», и некоторые аспекты поведения (procfs, сигналы, сеть) отличаются от реального Linux.

Выбор дистрибутива​

Мы тестируем на Ubuntu (LTS). Debian работает. Arch и NixOS работают для тех, кто хочет их использовать, но установщик в одну строку предполагает систему на основе apt (Debian) — для этого пути смотрите руководство по установке Nix.

Включение systemd (рекомендуется)​

Шлюзом Vibeos (и всем остальным, что вы хотите держать запущенным) проще управлять с помощью systemd. В современном WSL включите его один раз внутри вашего дистрибутива:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[automount]
options = "metadata,umask=22,fmask=11"
EOF

Затем из PowerShell:

wsl --shutdown

Снова откройте терминал WSL. ps -p 1 -o comm= должно вывести systemd.

Параметр монтирования metadata выше важен — без него файлы на /mnt/c/... не могут хранить реальные биты разрешений Linux, что ломает такие вещи, как chmod +x для скриптов, находящихся по путям Windows.

Установка VibeOS внутри WSL​

Как только у вас откроется оболочка WSL2:

curl -fsSL https://vibeos.com.ru/downloads/install.sh | bash
source ~/.bashrc
vibeos

Установщик рассматривает WSL2 как обычный Linux — ничего специфичного для WSL не требуется. Полную структуру смотрите в разделе Установка.

Файловая система: пересечение границы Windows ↔ WSL2​

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

Два направления​

НаправлениеПуть внутриИспользуемый путь
Диск Windows, видимый из WSLC:\Users\you\Documents/mnt/c/Users/you/Documents
Диск WSL, видимый из Windows/home/you/code\\wsl$\Ubuntu\home\you\code (или \\wsl.localhost\Ubuntu\... в новых сборках)

Оба пути реальны, оба работают, но это не одна и та же файловая система — под капотом они соединены сетевым протоколом 9P. Это имеет реальные последствия для производительности и семантики.

Где размещать VibeOS и ваши проекты​

Эмпирическое правило: храните всё, что связано с Linux, внутри файловой системы Linux.

  • Ваша установка VibeOS (~/.vibeos/) — на стороне Linux. Установщик уже делает это.
  • Ваши git-репозитории, с которыми вы работаете из WSL — на стороне Linux (~/code/..., ~/projects/...).
  • Ваши модели, наборы данных, виртуальные окружения — на стороне Linux.

Что вы получаете, следуя этому правилу:

  • Быстрый ввод-вывод. Операции с /mnt/c/... проходят через 9P и в 10–100 раз медленнее, чем с родной ext4. git status в репозитории с 10 000 файлов, который кажется мгновенным в ~/code, может занимать 15+ секунд в /mnt/c.
  • Корректные разрешения. Биты разрешений Linux на /mnt/c эмулируются по мере возможности. Часто встречаются ситуации, когда ssh отказывается от ключа с сообщением «bad permissions» или chmod +x молча не срабатывает.
  • Надежные наблюдатели за файлами. inotify через 9P работает нестабильно — наблюдатели за файлами (серверы разработки, тестовые раннеры) регулярно пропускают изменения на /mnt/c.
  • Отсутствие сюрпризов с регистром символов. Пути Windows по умолчанию нечувствительны к регистру; Linux чувствителен. Проекты, содержащие как Readme.md, так и README.md, ведут себя по-разному в зависимости от того, на какой стороне вы находитесь.

Размещайте файлы на /mnt/c только тогда, когда вам нужно, чтобы файл находился на стороне Windows — например, вы хотите открыть его из приложения с графическим интерфейсом Windows, или MCP Chrome DevTools от Windows требует, чтобы текущий каталог был доступен по пути Windows.

Передача файлов туда и обратно​

Из Windows → в WSL: проще всего открыть Проводник и ввести \\wsl.localhost\Ubuntu в адресной строке. Затем вы можете перетаскивать файлы в \home\&lt;you&gt;\.... Или из PowerShell:

wsl cp /mnt/c/Users/you/Downloads/file.pdf ~/incoming/

Из WSL → в Windows: скопируйте в /mnt/c/Users/&lt;you&gt;/..., и файл сразу появится в Проводнике Windows:

cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/

Открыть файл WSL в приложении Windows (редакторе с GUI, браузере и т.д.): используйте explorer.exe или wslview:

sudo apt install wslu     # один раз — дает wslview, wslpath, wslopen и т.д.
wslview ~/reports/output.pdf    # открывается обработчиком по умолчанию в Windows
explorer.exe .                  # открывает текущий каталог WSL в Проводнике Windows

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

wslpath -w ~/code/project        # → \\wsl.localhost\Ubuntu\home\you\code\project
wslpath -u 'C:\Users\you'        # → /mnt/c/Users/you

Окончания строк, BOM и git​

Если вы редактируете файлы на стороне Windows с помощью редактора Windows, они могут получить окончания строк CRLF. Когда bash или Python на стороне Linux читают их, скрипты оболочки ломаются с ошибкой bad interpreter: /bin/bash^M, а Python может выдать ошибку на файлах .env с BOM.

Решение — правильная конфигурация git внутри WSL (не в Windows):

git config --global core.autocrlf input
git config --global core.eol lf

Для файлов, которые уже содержат CRLF:

sudo apt install dos2unix
dos2unix path/to/script.sh

«Клонировать внутри WSL или на /mnt/c?»​

Клонируйте внутри WSL. Всегда, если у вас нет особой причины поступить иначе. Типичный рабочий процесс VibeOS (vibeos chat, вызовы инструментов, использующие rg/ripgrep для поиска по репозиторию, наблюдатели за файлами, фоновый шлюз) будет значительно быстрее и надежнее в ~/code/myrepo, чем в /mnt/c/Users/you/myrepo.

Одно исключение: MCP-мосты, запускающие двоичные файлы Windows. Если вы используете chrome-devtools-mcp через cmd.exe (см. Руководство по MCP: WSL → Windows Chrome), Windows может выдать предупреждение UNC, если текущий рабочий каталог VibeOS — ~. В этом случае запустите VibeOS из какого-нибудь места в /mnt/c/, чтобы у процесса Windows был cwd с буквой диска.

Сеть: WSL ↔ Windows​

WSL2 работает в легковесной виртуальной машине с собственным сетевым стеком. Это означает, что localhost внутри WSL — это не то же самое, что localhost в Windows; с точки зрения сети это два разных хоста. Для каждого сервиса вам нужно решить, в каком направлении движется трафик, и выбрать правильный мост.

Постоянно возникают два случая.

Случай 1 — VibeOS в WSL обращается к сервису на Windows​

Самый распространенный: вы запускаете Ollama, LM Studio или llama-server на Windows, и VibeOS (внутри WSL) должен к нему обращаться.

Каноническая инструкция находится в руководстве по провайдерам: Сетевые настройки WSL2 для локальных моделей →

Краткая версия:

  • Windows 11 22H2+: включите режим зеркальной сети (networkingMode=mirrored в %USERPROFILE%\.wslconfig, затем wsl --shutdown). После этого localhost будет работать в обоих направлениях.
  • Windows 10 или старые сборки: используйте IP-адрес хоста Windows (шлюз по умолчанию виртуальной сети WSL) и убедитесь, что сервер на Windows привязывается к 0.0.0.0, а не только к 127.0.0.1. Брандмауэру Windows обычно также требуется правило для порта.

Полную таблицу (адреса привязки Ollama / LM Studio / vLLM / SGLang, однострочные команды для правил брандмауэра, помощники для динамического IP, обходной путь для Hyper-V брандмауэра) смотрите по ссылке выше — не дублируйте её здесь.

Случай 2 — Что-то на Windows (или в вашей локальной сети) обращается к VibeOS в WSL​

Это обратное направление, которое менее документировано в других местах, но оно необходимо для:

  • Использования веб-панели управления VibeOS из браузера Windows.
  • Использования OpenAI-совместимого API-сервера (предоставляемого vibeos gateway, когда API_SERVER_ENABLED=true) из инструмента на стороне Windows. Смотрите страницу функции API-сервера.
  • Тестирования шлюза обмена сообщениями (Telegram, Discord и т.д.), где платформа отправляет запросы на локальный URL вебхука — обычно для этого лучше использовать cloudflared/ngrok, а не прямое перенаправление портов.

Подслучай 2a: с самого хоста Windows​

В Windows 11 22H2+ с включенным зеркальным режимом ничего делать не нужно. Процесс в WSL, который привязывается к 0.0.0.0:8080 (или даже 127.0.0.1:8080), доступен из браузера Windows по адресу http://localhost:8080. WSL автоматически публикует привязку обратно на хост.

В режиме NAT (Windows 10 / старая Windows 11) стандартное «перенаправление localhost» в WSL2 обычно перенаправляет привязки 127.0.0.1 со стороны Linux на localhost Windows, поэтому сервис VibeOS, запущенный с --host 127.0.0.1, обычно доступен как http://localhost:PORT из Windows. Если это не так:

  • Явно укажите привязку к 0.0.0.0 внутри WSL.
  • Найдите IP-адрес виртуальной машины WSL с помощью ip -4 addr show eth0 | grep inet и используйте его из Windows.

Подслучай 2b: с другого устройства в вашей локальной сети (телефон, планшет, другой ПК)​

Это самая сложная часть. Трафик идет устройство в локальной сети → хост Windows → виртуальная машина WSL, и вам нужно настроить оба перехода:

  1. Привязка на всех интерфейсах внутри WSL. Процесс, слушающий на 127.0.0.1, никогда не будет доступен извне виртуальной машины. Используйте 0.0.0.0.

  2. Перенаправление портов Windows → виртуальная машина WSL. В зеркальном режиме это автоматически. В режиме NAT вам нужно делать это вручную, для каждого порта, в административной PowerShell:

    # Получаем текущий IP-адрес виртуальной машины WSL (он меняется при каждом перезапуске WSL в режиме NAT)
    $wslIp = (wsl hostname -I).Trim().Split(' ')[0]

    # Перенаправляем порт Windows 8080 → WSL:8080
    netsh interface portproxy add v4tov4 `
      listenaddress=0.0.0.0 listenport=8080 `
      connectaddress=$wslIp connectport=8080

    # Разрешаем через брандмауэр Windows
    New-NetFirewallRule -DisplayName "VibeOS WSL 8080" `
      -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

    Удалить позже можно с помощью netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080.

  3. Укажите устройству в локальной сети адрес http://&lt;windows-lan-ip&gt;:8080.

Поскольку IP-адрес виртуальной машины WSL меняется при каждом перезапуске в режиме NAT, одноразовое правило действует только до следующего wsl --shutdown. Для постоянной работы либо используйте зеркальный режим, либо поместите шаг перенаправления портов в скрипт, запускаемый при входе в Windows.

Для вебхуков от облачных провайдеров обмена сообщениями (Telegram setWebhook, события Slack и т.д.) не боритесь с перенаправлением портов — используйте туннели cloudflared. Смотрите руководство по вебхукам.

Долгосрочный запуск сервисов VibeOS на Windows​

Шлюз инструментов VibeOS и API-сервер являются долгоживущими процессами. В WSL2 у вас есть несколько вариантов их поддержания.

Ярлык на рабочем столе для быстрого открытия VibeOS​

Если вам нужен просто лаунчер по двойному щелчку для интерактивной оболочки VibeOS, создайте его на стороне Windows, чтобы он автоматически переключался в WSL:

  1. Щелкните правой кнопкой мыши на рабочем столе Windows и выберите Создать -> Ярлык.

  2. В качестве объекта используйте имя вашего дистрибутива (замените Ubuntu при необходимости):

    wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "vibeos"

  3. Назовите его как-нибудь понятно, например VibeOS.

Это откроет Windows Terminal, запустит ваш дистрибутив WSL, перейдет в ваш домашний каталог Linux и запустит VibeOS. Если vibeos еще нет в PATH, откройте WSL один раз вручную и выполните source ~/.bashrc, или замените команду на uv run vibeos внутри вашего проекта.

Дополнительные улучшения:

  • Пользовательская иконка: откройте Свойства -> Сменить значок и укажите путь к файлу .ico, например, к фавикону VibeOS из репозитория.
  • Закрепленный лаунчер: после того как ярлык заработает, закрепите его в меню «Пуск» или на панели задач, чтобы не искать его снова.

Внутри WSL с systemd (рекомендуется)​

Если вы включили systemd, как описано в разделе настройки выше, vibeos gateway и API-сервер работают так же, как на любом Linux-компьютере. Используйте мастер настройки шлюза:

vibeos gateway setup

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

Автоматический запуск самого WSL при входе в Windows​

Виртуальная машина WSL остается активной только пока кто-то ее использует. Чтобы ваш шлюз был доступен без открытого окна терминала, запустите процесс WSL при входе в Windows через Планировщик заданий:

  • Триггер: При входе в систему (ваш пользователь).
  • Действие: Запуск программы
    • Программа: C:\Windows\System32\wsl.exe
    • Аргументы: -d Ubuntu --exec /bin/sh -c "sleep infinity"

Это поддерживает виртуальную машину активной, чтобы управляемый systemd шлюз продолжал работать. В Windows 11 также работают более новые потоки wsl --install --no-launch + автозапуск; трюк с sleep infinity — это переносимый вариант.

Передача GPU (локальные модели)​

WSL2 поддерживает NVIDIA GPU нативно, начиная с ядра WSL 5.10.43+ — установите стандартный драйвер NVIDIA на Windows (не устанавливайте драйвер NVIDIA для Linux внутри WSL), и nvidia-smi внутри WSL увидит GPU. После этого инструментарии CUDA, torch, vllm, sglang и llama-server будут работать с реальным GPU как обычно.

Поддержка AMD ROCm и Intel Arc внутри WSL2 все еще развивается и находится за пределами тестовой матрицы VibeOS — это может работать с текущими драйверами, но у нас нет готовой инструкции.

Если вы запускаете нативный для Windows локальный сервер моделей (Ollama для Windows, LM Studio), который уже использует ваш GPU через драйверы Windows, вам вообще не нужна передача GPU через WSL — просто следуйте Случаю 1 выше и обращайтесь к нему по сети из WSL.

Типичные ошибки​

«Connection refused» к моему Ollama / LM Studio, размещенному на Windows. Смотрите Сетевые настройки WSL2. В девяноста процентах случаев сервер привязан к 127.0.0.1 и его нужно привязать к 0.0.0.0 (Ollama: OLLAMA_HOST=0.0.0.0), или отсутствует правило брандмауэра.

Сильное замедление git status / vibeos chat в репозитории. Вероятно, вы работаете в /mnt/c/.... Переместите репозиторий в ~/code/... (на сторону Linux). Ускорение на порядок.

bad interpreter: /bin/bash^M в скриптах. Окончания строк CRLF из редактора Windows. Выполните dos2unix script.sh и установите core.autocrlf input в вашей конфигурации git в WSL.

Предупреждение «UNC paths are not supported» от двоичных файлов Windows, запущенных через MCP. Текущий рабочий каталог VibeOS находится внутри файловой системы Linux, и cmd.exe в Windows не знает, что с ним делать. Запустите VibeOS из /mnt/c/... для этой сессии или используйте обертку, которая переходит в каталог, доступный из Windows, перед вызовом исполняемого файла Windows.

Дрейф часов после сна/гибернации. Часы WSL2 могут отставать на минуты после выхода хоста из сна, что ломает все, что использует сертификаты (OAuth, HTTPS API). Исправьте по требованию:

sudo hwclock -s

Или установите ntpdate и запускайте его при входе.

DNS перестает работать после включения зеркального режима или при подключении VPN. Зеркальный режим передает сетевые настройки хоста в WSL — если DNS в Windows работает некорректно (туннель VPN, корпоративный резолвер), WSL наследует это. Обходной путь: вручную переопределите resolv.conf (установите generateResolvConf=false в /etc/wsl.conf, затем создайте свой /etc/resolv.conf с 1.1.1.1 или DNS вашего VPN).

vibeos не найден после запуска установщика. Установщик добавляет ~/.local/bin в PATH вашей оболочки через ~/.bashrc. Вам нужно выполнить source ~/.bashrc (или открыть новый терминал), чтобы это вступило в силу в текущей сессии.

Защитник Windows замедляет работу с файлами WSL. Защитник сканирует файлы через мост 9P при доступе из Windows, что усиливает замедление при кросс-граничном доступе типа /mnt/c. Если вы обращаетесь к файлам WSL только изнутри WSL, это не имеет значения. Если вы часто используете инструменты Windows для работы с \\wsl$\..., рассмотрите возможность исключения пути к дистрибутиву WSL из сканирования в реальном времени.

Заканчивается место на диске. WSL2 хранит диск своей виртуальной машины как разреженный VHDX в %LOCALAPPDATA%\Packages\.... Он растет, но не сжимается автоматически при удалении файлов. Чтобы освободить место: wsl --shutdown, затем из административной PowerShell выполните Optimize-VHD -Path &lt;путь-к-ext4.vhdx&gt; -Mode Full (требуются инструменты Hyper-V) — или более простой путь через diskpart, описанный в документации WSL.

Куда двигаться дальше​