Перейти к содержанию

Windows wsl quickstart

На этой странице

Hermes Agent разрабатывается и тестируется на Linux и macOS. Нативная Windows не поддерживается — на Windows вы запускаете Hermes внутри WSL2 (подсистема Windows для Linux, версия 2). Это означает, что фактически у вас два компьютера: ваш хост Windows и виртуальная машина Linux под управлением WSL. Бо́льшая часть путаницы возникает из-за непонимания, на каком из них вы находитесь в данный момент.

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

简体中文

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

Почему WSL2 (а не «просто Windows»)​

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

Практические последствия этого выбора:

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

Установка WSL2​

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

[code] wsl --install

[/code]

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

Проверьте, что вы действительно на WSL2 (а не на устаревшем WSL1):

[code] wsl --list --verbose

[/code]

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

[code] wsl --set-version Ubuntu 2
wsl --set-default-version 2

[/code]

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

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

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

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

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

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

[interop]  
enabled=true  
appendWindowsPath=true

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

[/code]

Затем из PowerShell:

[code] wsl --shutdown

[/code]

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

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

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

Когда у вас открыта оболочка WSL2:

[code] curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes

[/code]

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

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

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

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

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

[/code]

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

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

[/code]

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

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

[/code]

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

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

[/code]

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

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

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

[code] git config --global core.autocrlf input
git config --global core.eol lf

[/code]

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

[code] sudo apt install dos2unix
dos2unix path/to/script.sh

[/code]

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

Клонируйте внутри WSL. Всегда, если у вас нет особой причины поступать иначе. Типичный рабочий процесс Hermes (hermes chat, вызовы инструментов, использующие rg/ripgrep в репозитории, файловые watcher'ы, фоновый шлюз) будет значительно быстрее и надёжнее в ~/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-server на Windows, и 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 Firewall) смотрите по ссылке выше — не дублируйте её здесь.

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

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

  • Использования веб-панели Hermes из браузера Windows.
  • Использования API-сервера (hermes api) из инструмента на стороне Windows.
  • Тестирования шлюза обмена сообщениями (Telegram, Discord и т. д.), где платформа отправляет запросы на локальный webhook-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 обычно перенаправляет привязки Linux к 127.0.0.1 на Windows localhost, поэтому сервис 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 нужно делать это вручную, для каждого порта, в PowerShell с правами администратора:

[code] # Получаем текущий 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

[/code]

Удалить позже: 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. Смотрите руководство по вебхукам.

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

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

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

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

[code] hermes gateway setup

[/code]

Он предложит установить пользовательский юнит 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+ — установите стандартный драйвер NVIDIA на Windows (не устанавливайте драйвер NVIDIA для Linux внутри WSL), и nvidia-smi внутри WSL увидит GPU. После этого инструментарии CUDA, 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, и cmd.exe Windows не знает, что с ним делать. Запустите Hermes из /mnt/c/... для этой сессии или используйте обёртку, которая переходит в доступный из Windows путь перед вызовом исполняемого файла Windows.

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

[code] sudo hwclock -s

[/code]

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

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