🏠 Главная › Документация › Руководство

Windows (WSL2) — Быстрый старт

Hermes Agent теперь поддерживает оба варианта: нативный Windows и WSL2. На этой странице описан путь через WSL2; для установки через нативный PowerShell обратитесь к Руководству по Windows (нативный).

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

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

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

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

info 简体中文 |A Chinese-language walkthrough of the minimum install path is maintained on this same page — switch via the language menu (top right) and select 简体中文. |

Почему WSL2 (а не нативный Windows)

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

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

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

Установка WSL2

Из Admin 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

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

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

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

Шлюзом 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

После того как вы открыли оболочку WSL2:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/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.

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

Размещайте файлы на /mnt/c только тогда, когда файл должен находиться на стороне Windows — например, если вы хотите открыть его из GUI-приложения Windows, или если Chrome DevTools MCP от Windows требует, чтобы текущий каталог был доступен из 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 читают их, скрипты оболочки ломаются с ошибкой 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

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

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

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

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

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

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

Подслучай 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 обычно пробрасывает привязки Linux-стороны на 127.0.0.1 в Windows localhost, так что сервис Hermes, запущенный с --host 127.0.0.1, обычно доступен как http://localhost:PORT из Windows. Если нет:

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

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

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

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

```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 "Hermes WSL 8080" ` -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow ```

Удалить правило позже можно командой netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080.

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

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

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

Запуск сервисов Hermes на постоянной основе в Windows

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

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

hermes gateway setup

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

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

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

Это поддерживает виртуальную машину в активном состоянии, чтобы шлюз, управляемый через 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 toolkit, torch, vllm, sglang и llama-server будут работать с реальным GPU как обычно.

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

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

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

sudo hwclock -s

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

DNS перестаёт работать после включения зеркального режима или при подключении VPN. Зеркальный режим передаёт сетевые настройки хоста в WSL — если DNS на Windows работает нестабильно (VPN split-tunnel, корпоративный резолвер), 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, затем из Admin PowerShell выполните Optimize-VHD -Path <путь-к-ext4.vhdx> -Mode Full (требуются средства Hyper-V) — или более простой путь через diskpart, описанный в документации WSL.

Что дальше