🏠 Главная › user guide › windows wsl quickstart

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

Агент Hermes теперь поддерживает как родную систему Windows, а также WSL2. На этой странице описан путь WSL2; информация о собственной установке PowerShell см. специально Руководстве по Windows (Native).

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

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

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

В этом руководстве рассматриваются части этого разделения, которые конкретно затрагивают Hermes: установка WSL2, обмен файлами между Windows и Linux, работа в сети в ближних направлениях, а также подводные камни, с которыми действительно сталкиваются люди.:::информация На этой же странице имеется пошаговое руководство по минимальному пути установки на китайском языке — переключите меню через язык (вверху справа) и выберите 简体中文.

Почему WSL2 (по сравнению с родной Windows)

Собственная установка Windows выполняется непосредственно в Windows: ваш терминал Windows (PowerShell, терминал Windows и т. д.), путь файловой системы Windows (C:\Users\…) и процессы Windows. Hermes использует Git Bash для запуска командной обработки, и именно так Клод Код и другие агенты сегодня обрабатывают Windows — это позволяет избежать разрыва POSIX-vs-Windows без переписывания.

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

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

Установить WSL2

Из Admin PowerShell или терминала Windows:

wsl --install

В новой версии Windows 10 22H2+ или Windows 11 установлены ядро ​​WSL2, функция платформы мобильных машин и дистрибутив Ubuntu по умолчанию. Перезагрузитесь при получении запроса. После перезагрузки откроется Ubuntu и запросит имя пользователя и пароль Linux — это новый пользователь Linux, не связанный с вашей учетной записью Windows.

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

wsl --list --verbose

Вы должны увидеть «ВЕРСИЯ 2». Если в дистрибутиве отображается «ВЕРСИЯ 1», преобразуйте ее:

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

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

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

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

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

Шлюзом Гермес (и всем сотрудникам, которые вы хотите продолжать работать) проще управлять с помощью 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.

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

Установить Гермес внутри WSL

Если вы открыли окно WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes

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

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

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

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

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

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

Куда девать Гермес и ваши проекты

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

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

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

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

Из Windows → в WSL: проще всего открыть проводник и ввести адресную строку \\wsl.localhost\Ubuntu. Затем вы можете перевезти его в \home\<you>\.... Или из PowerShell:

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

Из WSL → в Windows: скопируйте в /mnt/c/Users/<you>/..., и он сразу же появится в проводнике Windows:

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

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

sudo apt install wslu     # once — gives you wslview, wslpath, wslopen, etc.
wslview ~/reports/output.pdf    # opens with the Windows default handler
explorer.exe.                  # opens the current WSL dir in Windows Explorer

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

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

Окончания строк, характеристик и git

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

Исправление — это нормальная форма 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. Всегда, если у вас нет особой причины не делать этого. Типичный рабочий процесс Hermes (чат Hermes, инструмент вызывает репозиторий rg/ripgrep, средства наблюдения за файлами, фоновый шлюз) будет значительно быстрее и надежнее в отношении ~/code/myrepo, чем /mnt/c/Users/you/myrepo.

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

Сеть: WSL ↔ Windows

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

Постоянно всплывают два случая.

Случай 1 — Hermes в WSL обращается к службе в Windows

Чаще всего: вы используете Ollama, LM Studio или сервер llama в Windows, и Hermes (внутри WSL) должен его запустить.

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

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

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

Случай 2. Что-то в Windows (или в вашей локальной сети) взаимодействует с Hermes в WSL.

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

Подслучай 2а: с самого хоста 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) «переадресация локального хоста» по умолчанию в WSL2 обычно перенаправляет привязки 127.0.0.1 на стороне Linux к localhost Windows, поэтому служба Hermes, запущенная с --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 VM. В зеркальном режиме это происходит автоматически. В режиме NAT вам придется сделать это самостоятельно для каждого порта в Admin PowerShell: ```powershell # Grab the WSL VM's current IP (it changes on every WSL restart under NAT) $wslIp = (wsl hostname -I).Trim().Split(' ')[0]

# Forward Windows port 8080 → WSL:8080 netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8080 connectaddress=$wslIp connectport=8080

# Allow it through Windows Firewall New-NetFirewallRule -DisplayName "Hermes WSL 8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow ``` Удалите позже с помощьюnetsh Interface portproxy delete v4tov4 Listenaddress=0.0.0.0 Listenport=8080`.

  1. Укажите адрес сетевого устройства http://<windows-lan-ip>:8080.

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

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

Долгосрочная работа службы Гермес в Windows

Hermes Tool Gateway и серверный API — это долгоживущие процессы. В WSL2 у вас есть несколько вариантов их поддержки.

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

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

  1. Нажмите правый зажим мыши на рабочем столе Windows и выберите Создать -> Ярлык.
  2. В качестве цели воспользуйтесь именем вашего дистрибутива (при необходимости замены дистрибутива «Ubuntu»): text wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "hermes"
  3. Назовите его, например, «Гермес».

Это открывает терминал Windows, запускает ваш дистрибутив WSL и отправляет вас в Linux. домашний каталог и запускает Hermes. Если «Гермес» все еще не находится в PATH, вступит в силу WSL. один раз вручную запустите source ~/.bashrc или замените команду замены на ув беги Гермес внутри оформления заказа.

Дополнительная полировка:

Внутри WSL с помощью systemd (рекомендуется)

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

hermes gateway setup

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

Запуск самого WSL при входе в Windows

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

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

Сквозная передача графического процессора (локальные модели)

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

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

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

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

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

Огромное замедление работы git status/hermeschat в репозитории. Вероятно, вы работаете под /mnt/c/.... Переместите репозиторий в ~/code/... (стороны Linux). На порядок быстрее.

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

Предупреждение «UNC-пути не упоминаются» в двоичных файлах Windows, запущенных через MCP. CWD Гермеса находится внутри файлов системы Linux и Windows. cmd.exe не знает, что с ним делать. Запустите Hermes из /mnt/c/... для этого сеанса или вскормите оболочку, которая cds перейдет по доступному для 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).

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

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

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

Куда идти дальше