Гайд по Windows (WSL2)

Hermes Agent работает и в нативной Windows, и в WSL2. Здесь разбираем путь через WSL2; про установку напрямую в PowerShell читайте отдельный гайд по нативной Windows.

Когда 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, сеть в обоих направлениях и грабли, на которые люди наступают на практике.

инфо

简体中文

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

Почему WSL2, а не нативная Windows

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

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

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

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

Установка 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

На WSL1 Hermes стабильно не работает: WSL1 транслирует системные вызовы Linux на лету, и часть поведения (procfs, сигналы, сеть) расходится с настоящим Linux.

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

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

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

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

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

Когда открыт shell 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	`/home/you/code`	`\\wsl$\Ubuntu\home\you\code` (или `\\wsl.localhost\Ubuntu\...` на новых сборках)

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

Куда класть Hermes и свои проекты

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

Установка Hermes (~/.hermes/) — на стороне Linux. Установщик уже так и делает.
Git-репозитории, с которыми вы работаете из WSL, — на стороне Linux (~/code/..., ~/projects/...).
Модели, датасеты, виртуальные окружения — на стороне Linux.

Что вы за это получаете:

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

Кладите файлы на /mnt/c только тогда, когда файл должен жить на стороне Windows: например, вы хотите открыть его в GUI-приложении 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 (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, shell-скрипты ломаются с ошибкой 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. Всегда, если только нет конкретной причины поступить иначе. Типичный рабочий процесс Hermes (hermes chat, вызовы инструментов, которые гоняют 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-процесса был рабочий каталог с буквой диска.

Сеть: WSL ↔ Windows

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

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

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

Самое частое: на Windows у вас крутится Ollama, LM Studio или llama-server, а Hermes (внутри 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 (или в вашей локальной сети) обращается к Hermes в WSL

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

открыть веб-дашборд Hermes из браузера на Windows;
использовать API-сервер, совместимый с OpenAI (его поднимает hermes 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) встроенная в WSL2 «переадресация localhost» обычно прокидывает Linux-привязки 127.0.0.1 на localhost Windows, так что сервис Hermes, запущенный с --host 127.0.0.1, как правило, доступен из Windows как http://localhost:PORT. Если нет:

привяжитесь внутри WSL явно к 0.0.0.0;
узнайте IP виртуалки WSL командой ip -4 addr show eth0 | grep inet и стучитесь по нему из Windows.

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

Вот где настоящая боль. Трафик идёт устройство в сети → хост Windows → виртуалка WSL, и настроить надо оба перехода:

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

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

# Берём текущий IP виртуалки WSL (под NAT он меняется при каждом перезапуске WSL)
$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 "Hermes WSL 8080" `
  -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

Удалить позже: netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080.

Направьте устройство из сети на http://<windows-lan-ip>:8080.

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

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

Долгоживущие сервисы Hermes на Windows

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

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

Если вам просто нужен лаунчер по двойному клику для интерактивного shell Hermes, создайте его на стороне Windows, и пусть он сам ныряет в WSL:

Кликните правой кнопкой по рабочему столу Windows и выберите Создать -> Ярлык.
В качестве цели укажите имя своего дистрибутива (замените Ubuntu, если нужно):
```
wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "hermes"
```
Назовите его понятно, например Hermes.

Ярлык откроет Windows Terminal, запустит ваш дистрибутив WSL, поместит вас в домашний каталог Linux и запустит Hermes. Если hermes ещё не в PATH, откройте WSL один раз вручную и выполните source ~/.bashrc — либо замените команду на python hermes внутри чекаута проекта, активированного через PM.

Опциональные штрихи:

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

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

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

hermes 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 поддерживает GPU NVIDIA нативно начиная с ядра WSL 5.10.43+ — поставьте на Windows стандартный драйвер NVIDIA (Linux-драйвер NVIDIA внутри WSL ставить не надо), и nvidia-smi внутри WSL увидит видеокарту. Оттуда CUDA-тулкиты, torch, vllm, sglang и llama-server собираются под реальный GPU как обычно.

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

Если у вас крутится нативный для 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 / hermes 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. Рабочий каталог Hermes находится внутри Linux-файловой системы, и cmd.exe в Windows не знает, что с ним делать. Запустите Hermes из /mnt/c/... на эту сессию или используйте обёртку, которая делает cd в доступный из Windows путь перед вызовом Windows-исполняемого файла.

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

sudo hwclock -s

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

DNS перестаёт работать после включения зеркального режима или при подключённом VPN. Зеркальный режим проксирует сетевые настройки хоста в WSL — если с DNS в Windows что-то не так (split-tunnel у 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 Defender тормозит на файлах WSL. Defender сканирует файлы через мост 9P при доступе из Windows, а это усиливает и без того низкую скорость доступа через границу в стиле /mnt/c. Если вы трогаете файлы WSL только изнутри WSL, проблемы нет. Если же вы часто работаете Windows-инструментами по \\wsl$\..., подумайте о том, чтобы исключить путь дистрибутива WSL из проверки в реальном времени.

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

Куда дальше

Установка — собственно шаги установки (Linux и WSL2 используют один и тот же установщик).
Интеграции → Провайдеры → Сеть WSL2 — каноническое подробное руководство по сети для серверов локальных моделей.
Гайд по MCP → WSL → Windows Chrome — управление залогиненным Windows-Chrome из Hermes в WSL.
Tool Gateway и Веб-дашборд — долгоживущие сервисы, которые чаще всего хочется пробросить из WSL в остальную сеть.