🏠 Главная › user guide › windows native

Руководство по Windows (родная установка) — ранняя бета:::предупреждение Ранняя бета

Нативная поддержка Windows в настоящее время находится на ранней стадии бета-тестирования. Она настроена, обеспечивает и проходит наши проверки совместимости с Windows, но ещё не было проведено такого же масштабного реального тестирования, как Linux/macOS/WSL2. Ожидайте некоторых шероховатостей — особенно при обработке дочерних процессов, особенностей путей и вывода не-ASCII-символов в консоль. Если вы столкнулись с проблемой, пожалуйста, создайте проблему с шагами для вывода. Если вам нужно проверенное решение сегодня, воспользуйтесь установщик Linux/macOS под WSL2.

Hermes работает оперативно на Windows 10 и Windows 11 — без WSL, Cygwin или Docker. На этой странице представлена ​​подробная информация: какие функции доступны изначально, какие только в WSL, что на самом деле делает установщик и какие настройки Windows вам, возможно, придется подкорректировать.

Если вы просто хотите установить, достаточно одной строчной команды с главной страницы или страницы установки. Возвращайтесь сюда, когда столкнетесь с чем-то неожиданным.

💡 Tip

Хотите WSL? Если вы предпочитаете настоящее окружение POSIX (встроенный терминал для панели управления, семантика fork, файловые наблюдатели в стиле Linux и т.д.), обратитесь к Windows (WSL2). Оба решения могут сосуществовать без проблем: собственные данные отслеживаются в %LOCALAPPDATA%\hermes, данные WSL — в ~/.hermes.

Быстрая установка

Откройте PowerShell (или терминал Windows) и выполните:

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

Права администратора не требуются. Установщик поместит файлы в %LOCALAPPDATA%\hermes\ и добавит hermes в ваш пользовательский PATH — после заключения нового терминала.

Параметры установщика (для передачи параметров необходима форма скриптового блока):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main
Параметр По умолчанию Назначение
-Branch main Клонировать определённую ветку (для тестирования PR)
-NoVenv выкл. Пропустить создание виртуального окружения (продвинутый режим — вы сами управляете Python)
-SkipSetup выкл. Пропустить мастер hermes setup после установки
-HermesHome %LOCALAPPDATA%\hermes Переопределить каталог данных
-InstallDir %LOCALAPPDATA%\hermes\hermes-agent Переопределить расположение кода

Что на самом деле делает установщик

Сверху вниз, по порядку:

  1. Устанавливает uv — быстрый менеджер Python от Astral. Устанавливается в %USERPROFILE%\.local\bin.
  2. Устанавливает Python 3.11 через uv. Не требует предустановленного Python.
  3. Устанавливает Node.js 22 (через winget, если доступен, иначе распаковывает портативный tarball Node в %LOCALAPPDATA%\hermes\node). Используется для инструментов браузера и моста WhatsApp.
  4. Устанавливает портативный Git — если git уже есть в PATH, установщик использует его; в противном случае загружает компактный, самодостаточный PortableGit (около 45 МБ, из официального дистрибутива git-for-windows) в %LOCALAPPDATA%\hermes\git. Не требует прав администратора, не затрагивает реестр установщика Windows, не конфликтует ни с чем в системе.
  5. Клонирует репозиторий в %LOCALAPPDATA%\hermes\hermes-agent и создаёт в нём виртуальное окружение.
  6. Многоуровневая установка uv pip install — сначала пытается .[all], если зависимости git+https не удаётся установить из-за ограничений скорости GitHub, откатывается к постепенно меньшим наборам ([messaging,dashboard,ext] → [messaging] → .). Предотвращает ситуацию «один сбой приводит к пустой установке».
  7. Автоматически устанавливает SDK для обмена сообщениями на основе .env — если существуют TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN / SLACK_BOT_TOKEN / SLACK_APP_TOKEN / WHATSAPP_ENABLED, выполняет python -m ensurepip --upgrade и целевые вызовы pip install, чтобы SDK каждой платформы были импортируемы.
  8. Устанавливает HERMES_GIT_BASH_PATH в разрешённый путь bash.exe, чтобы Hermes мог детерминированно найти его в новой оболочке.
  9. Добавляет %LOCALAPPDATA%\hermes\bin в пользовательский PATH — после открытия нового терминала становится доступна команда hermes.
  10. Запускает hermes setup — обычный мастер первого запуска (модель, провайдер, наборы инструментов). Пропускается с флагом -SkipSetup.

Матрица возможностей

Все функции, кроме встроенной панели терминала в панели управления, работают на Windows нативно.

Функция Нативная Windows WSL2
CLI (hermes chat, hermes setup, hermes gateway и т.д.) ✓ ✓
Интерактивный TUI (hermes --tui) ✓ ✓
Шлюз сообщений (Telegram, Discord, Slack, WhatsApp, 15+ платформ) ✓ ✓
Планировщик Cron ✓ ✓
Инструменты браузера (Chromium через Node) ✓ ✓
MCP-серверы (stdio и HTTP) ✓ ✓
Локальный Ollama / LM Studio / llama-server ✓ ✓ (через сеть WSL)
Веб-панель (сессии, задания, метрики, конфигурация) ✓ ✓
Встроенная панель терминала в /chat ✗ (требуется POSIX PTY) ✓
Автозапуск при входе в систему ✓ (schtasks) ✓ (systemd)

Вкладка /chat в панели управления использует настоящий терминал через POSIX PTY (ptyprocess). В нативной Windows нет эквивалентного примитива; Python pywinpty / Windows ConPTY могут работать, но требуют отдельной реализации — это запланировано на будущее. Остальная часть панели работает нативно — только эта вкладка показывает баннер «Используйте WSL2 для этой функции».

Как Hermes выполняет команды оболочки в Windows

Инструмент терминала Hermes запускает команды через Git Bash, используя ту же стратегию, что и Claude Code. Это обходит разрыв между POSIX и Windows без необходимости переписывать каждый инструмент.

Порядок разрешения bash.exe:

  1. Если установлена переменная окружения HERMES_GIT_BASH_PATH, используется она.
  2. %LOCALAPPDATA%\hermes\git\usr\bin\bash.exe (PortableGit, управляемый установщиком).
  3. %LOCALAPPDATA%\hermes\git\bin\bash.exe (более старая структура Git-for-Windows).
  4. Системная установка Git-for-Windows (%ProgramFiles%\Git\bin\bash.exe и т.д.).
  5. Последнее средство: MSYS2, Cygwin или любой bash.exe в PATH.

Установщик явно устанавливает HERMES_GIT_BASH_PATH, чтобы новые сеансы PowerShell не должны были заново его находить. Если вы хотите, чтобы Hermes использовал определённый bash, вы можете переопределить его — например, ваш системный Git Bash или bash, размещённый в WSL через символическую ссылку.

Подводный камень: Структура MinGit отличается от полного установщика Git-for-Windows — bash находится в usr\bin\bash.exe, а не в bin\bash.exe. Hermes проверяет оба варианта. Если вы вручную распаковываете zip-архив MinGit, убедитесь, что выбрали не busybox вариант (MinGit-*-64-bit.zip, а не MinGit-*-busybox*.zip) — сборка busybox предоставляет ash вместо bash, и большинство coreutils отсутствуют.

Консоль UTF-8 в Windows

Стандартный ввод-вывод Python в Windows использует активную кодовую страницу консоли (обычно cp1252 или cp437). Баннеры Hermes, списки слеш-команд, обратная связь от инструментов, панели Rich и описания навыков содержат Unicode. Без вмешательства любое из них вызовет UnicodeEncodeError: 'charmap' codec can't encode character….

Исправление находится в hermes_cli/stdio.py::configure_windows_stdio(), вызывается на раннем этапе в каждой точке входа (cli.py::main, hermes_cli/main.py::main, gateway/run.py::main). Оно:

  1. Переключает кодовую страницу консоли на CP_UTF8 (65001) через kernel32.SetConsoleCP / SetConsoleOutputCP.
  2. Перенастраивает sys.stdout / sys.stderr / sys.stdin на UTF-8 с errors='replace'.
  3. Устанавливает PYTHONIOENCODING=utf-8 и PYTHONUTF8=1 (через setdefault, поэтому явные пользовательские значения имеют приоритет), чтобы дочерние процессы Python наследовали UTF-8.
  4. Если не установлены ни EDITOR, ни VISUAL, устанавливает EDITOR=notepad (см. раздел о редакторе ниже).

Идемпотентно. На не-Windows системах ничего не делает.

Отключение: Переменная окружения HERMES_DISABLE_WINDOWS_UTF8=1 возвращает к традиционному пути stdio cp1252. Используется для диагностики проблем с кодировкой; при нормальной работе вряд ли это правильная настройка.

Редактор (Ctrl-X Ctrl-E, /edit)

До #21561 нажатие Ctrl-X Ctrl-E или ввод /edit в Windows молча ничего не делали. У prompt_toolkit был жёстко заданный список POSIX-путей (/usr/bin/nano, /usr/bin/pico, /usr/bin/vi и т.д.), которые в Windows никогда не разрешались — даже при установленном полном Git for Windows.

Заглушка Windows stdio в Hermes теперь по умолчанию устанавливает EDITOR=notepad. Блокнот поставляется с каждой установкой Windows и работает как блокирующий редактор — subprocess.call(["notepad", file]) блокируется до закрытия окна.

Пользовательские переопределения по-прежнему имеют приоритет (они проверяются до setdefault):

Редактор Команда PowerShell
VS Code $env:EDITOR = "code --wait"
Notepad++ $env:EDITOR = "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -nosession"
Neovim $env:EDITOR = "nvim"
Helix $env:EDITOR = "hx"

Флаг --wait в VS Code критически важен — без него редактор возвращается немедленно, и Hermes получает пустой буфер.

Чтобы установить навсегда в вашем профиле PowerShell:

# В $PROFILE
$env:EDITOR = "code --wait"

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

Перенос строки по Ctrl+Enter в CLI

Терминал Windows передаёт Ctrl+Enter как восстановление последовательности клавиш. Гермес привязывает ее к «вставить строки перевода», чтобы вы могли писать многострочные подсказки в CLI, не прибегая к клавишам «Esc», а затем «Enter». Работает в терминале Windows, интегрированном терминале VS Code и любом современном хост-процессе консоли Windows, поддерживающем последовательность VT-escape-последовательности.

В традиционной консоли cmd.exe Ctrl+Enter возникает обычный Enter — воспользуйтесь Esc Enter или обновитесь в терминале Windows (по умолчанию установлено в Windows 11).

Запуск шлюза при входе в Windows

«Установка шлюза Hermes» в Windows использует запланированное задание с резервным источником через ключ автозагрузки — без прав администратора.

Установка

hermes gateway install

Что происходит под капотом:

  1. schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway — регистрирует задачу, которая запускается при входе в систему с обычными (не повышенными) правами. Без запроса ОАК.
  2. Если schtasks заблокированы групповой политикой, запасной вариант — запишите ярлык start /min cmd.exe /d /c <wrapper> в %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup. Тот же эффект, но немного грубее.
  3. Запускает шлюз отдельно через pythonw.exe — а не python.exe. pythonw.exe не имеет прикреплённой консоли, которая защищает его от широковещательных CTRL_C_EVENT от ускорения процессов (это была реальная проблема: раньше Ctrl+C в любом процессе той же группы процессов убивал шлюз).

Флаги при запуске: DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB.

Управление

hermes gateway status      # Объединённое представление: schtasks + папка автозагрузки + запущенный PID
hermes gateway start       # Немедленный запуск запланированного задания
hermes gateway stop        # Эквивалент graceful SIGTERM (через psutil TerminateProcess)
hermes gateway restart
hermes gateway uninstall   # Удаляет запись schtasks, ярлык автозагрузки, pid-файл

Состояние шлюза Гермеса идемпотентен — тысячи последовательных вызовов никогда случайно не убьют шлюз. (До PR #21561 он молча делал это через os.kill(pid, 0), конфликтуя на уровне C с CTRL_C_EVENT — если вам интересна эта история, см. «Внутреннее управление процессами» ниже.)

Почему не служба Windows?

Службы требуют прав администратора для установки и привязывают жизненный цикл шлюза к запуску машины, а не ко входу пользователя. Типичный пользователь Hermes хочет: вход → шлюз доступен, выход → шлюз исчезает. Запланированное задание делает именно это без повышения прав. Если вам действительно нужна служба, воспользуйтесь nssm или sc create вручную — но вам это, вероятно, не нужно.

Структура данных

Путь Содержимое
%LOCALAPPDATA%\hermes\hermes-agent\ Git-клон + виртуальное окружение. Можно безопасно удалить Remove-Item -Recurse и переустановить.
%LOCALAPPDATA%\hermes\git\ PortableGit (только если предоставлен установщиком).
%LOCALAPPDATA%\hermes\node\ Портативный Node.js (только если предоставлен установщиком).
%LOCALAPPDATA%\hermes\bin\ Заглушка hermes.cmd, добавленная в пользовательский PATH.
%USERPROFILE%\.hermes\ Ваши стороны, аутентификация, навыки, сессия, логи. Сохраняется после переустановки.

Это разделение сделано намеренно: %LOCALAPPDATA%\hermes — это disposable-инфраструктура (вы можете удалить ее, одна команда восстановит). %USERPROFILE%\.hermes — ваши данные: структура, память, навыки, история сессий — и она имеет ту же структуру, что и установка Linux. Скопируйте ее между машинами, и ваш Гермес последует за вами.

Переопределение HERMES_HOME: Установите переменную окружность, чтобы указать другой каталог данных. Работает так же, как в Linux.

Инструменты браузера

Инструменты браузера используют агент-браузер (вспомогательный Node-модуль) для управления Chromium. В Windows:

Запуск Hermes в Windows — практические замечания

ПУТЬ после установки

Установщик добавляет %LOCALAPPDATA%\hermes\bin в ваш пользовательский PATH через [Environment]::SetEnvironmentVariable. Существующие терминалы не удовлетворяют этому изменению — включение нового окна PowerShell (или вкладки Windows Terminal) после установки. Чтобы закрыть и внести изменения заново, не делайте $env:PATH += … вручную, если вы не уверены.

Проверка:

Get-Command hermes        # Должно показать C:\Users\<you>\AppData\Local\hermes\bin\hermes.cmd
hermes --version

Переменные окружения

Hermes поддерживает $env:X (в рамках процесса), а также пользовательские переменные окружения (постоянные, поддерживающие в Свойствах системы → Переменные среды). Установка ключей API в %USERPROFILE%\.hermes\.env — обычный путь, как в Linux:

OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=...

Не оставляйте секреты в переменных окружениях пользователя, если вы специально не хотите, чтобы каждый процесс Windows имел к ним доступ (а это не то, что вам нужно).

Специальные для Windows переменные окружения

Эти переменные настройки применяются только к исходной установке Windows:

Переменная Эффект
HERMES_GIT_BASH_PATH Переопределяет поиск bash.exe. Указывает на любой bash — полный Git-for-Windows, bash через WSL по символической ссылке, MSYS2, Cygwin. Установщик устанавливает эту переменную автоматически.
HERMES_DISABLE_WINDOWS_UTF8 Установите 1, чтобы отключить заглушку UTF-8 stdio и вернуться на страницу кодовой локали. Используется для решения проблем с кодировкой.
РЕДАКТОР / ВИЗУАЛ Редактор для /edit и Ctrl-X Ctrl-E. Если ни один из них не установлен, Гермес по умолчанию использует блокнот.

Удаление

Из PowerShell:

hermes uninstall

Это чистый путь — удаляет записи Schtasks, ярлык автозагрузки, заглушку hermes.cmd, удаляет %LOCALAPPDATA%\hermes\hermes-agent\ и очищает пользовательский PATH. Он сохраняет %USERPROFILE%\.hermes\ (ваши изменения, аутентификация, навыки, сессия, логи) на случай переустановки.

Чтобы полностью сохранить всё: ``powershell hermes uninstall Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes" Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"

Подкоманда CLI hermes uninstall также обрабатывает случаи, когда запись schtasks была зарегистрирована под другим именем (более старые установки) — она ищет по пути установки, а не по жёстко заданному имени задачи.

Внутреннее управление процессами

Это справочная информация — пропустите, если не отлаживаете странную проблему «самоубийства».

В Linux и macOS идиома POSIX os.kill(pid, 0) — это безоперационная проверка прав: «Жив ли этот PID и могу ли я отправить ему сигнал?» В Windows Python os.kill отображает sig=0 на CTRL_C_EVENT — они конфликтуют по целочисленному значению 0 — и направляет его через GenerateConsoleCtrlEvent(0, pid), который рассылает Ctrl+C всей группе процессов консоли, содержащей целевой PID. Это bpo-14484, открытый с 2012 года. Он не будет исправлен, потому что изменение сломает скрипты, полагающиеся на текущее поведение.

Последствие: любой код, который «проверяет, жив ли этот PID» через os.kill(pid, 0) в Windows, молча убивает цель. Hermes перенёс каждый такой участок (14 в 11 файлах) на gateway.status._pid_exists(), который использует psutil.pid_exists() (в Windows он использует OpenProcess + GetExitCodeProcess — без сигналов). Если вы пишете плагин или патч, используйте напрямую psutil.pid_exists() или gateway.status._pid_exists() — никогда не используйте os.kill(pid, 0).

scripts/check-windows-footguns.py в CI обеспечивает это: любой новый вызов os.kill(pid, 0) приводит к провалу проверки Windows footguns (blocking), если строка не помечена # windows-footgun: ok — <reason>.

Частые проблемы

hermes: command not found сразу после установки. Откройте новое окно PowerShell. Установщик добавил %LOCALAPPDATA%\hermes\bin в пользовательский PATH, но существующим оболочкам нужно перезапуститься, чтобы подхватить его. Пока можно запускать & "$env:LOCALAPPDATA\hermes\bin\hermes.cmd".

WinError 193: %1 is not a valid Win32 application при запуске инструментов. Вы наткнулись на вызов shebang-скрипта в обход заглушки .cmd. Hermes разрешает команды через shutil.which(cmd, path=local_bin), чтобы PATHEXT подхватывал .CMD — если вы вызываете инструмент по жёсткому пути, используйте вариант .cmd (например, npx.cmd, а не npx).

[scriptblock]::Create(...) завершается ошибкой The assignment expression is not valid. Скачанный install.ps1 содержит BOM UTF-8. Форма irm | iex автоматически удаляет BOM; [scriptblock]::Create((irm...)) — нет. Перезапустите с простой формой irm | iex или скачайте скрипт вручную и сохраните без BOM через [IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false)).

Шлюз не остаётся запущенным после перезагрузки. Проверьте hermes gateway status — он объединяет запись schtasks, ярлык автозагрузки (если используется) и активный PID. Если schtasks зарегистрирована, но не запускается, групповая политика может блокировать триггер ONLOGON. Выполните schtasks /Query /TN HermesGateway /V /FO LIST, чтобы увидеть причину сбоя задачи, или откатитесь к пути через папку автозагрузки, переустановив с HERMES_GATEWAY_FORCE_STARTUP=1.

/edit всё ещё ничего не делает после установки $env:EDITOR. Вы установили его только в текущем процессе; закройте и откройте оболочку заново или установите его как пользовательскую переменную в Свойствах системы → Переменные среды. Проверьте echo $env:EDITOR в новом окне PowerShell.

Инструменты браузера запускаются, но инструменты истекают по тайм-ауту. Chromium автоматически устанавливается при первом запуске. Если установка не удалась (ограничение скорости GitHub, проблемы с CDN Playwright), выполните hermes doctor — он покажет отсутствующий Chromium и выведет точную команду npx playwright install chromium для исправления.

agent-browser завершается ошибкой со странной ошибкой версии Node. Установщик предоставляет Node 22 в %LOCALAPPDATA%\hermes\node, но ваш PATH может сначала содержать более старую системную Node 18. Переместите каталог node от Hermes в начало PATH или удалите системную установку (если вы не используете Node в других целях).

Символы китайского / японского / арабского языков отображаются как ? в CLI. Заглушка UTF-8 stdio не активирована. Проверьте, не установлена ли HERMES_DISABLE_WINDOWS_UTF8 (Get-ChildItem env:HERMES_DISABLE_WINDOWS_UTF8). Если она пуста, а вы всё ещё видите ?, то хост консоли (очень старый cmd.exe) может вообще не поддерживать UTF-8 — переключитесь на Windows Terminal.

Шлюз не может отправить фото в Telegram — "BadRequest: payload contains invalid characters". Это не связано с Windows, но иногда проявляется в первую очередь там. Обычно означает, что ваш путь к файлу содержит неэкранированные обратные косые черты в JSON-теле. Telegram должен получать нормализованные пути от Hermes, а не сырые пути Windows — если вы видите эту проблему в пользовательском плагине, убедитесь, что передаёте путь, предоставленный Hermes, а не str(Path(...)) из пользовательского ввода.

Странные проблемы с кодировкой после git pull «работало на другой машине». Если вы редактировали конфигурацию Hermes или навыки в Windows с помощью не-UTF-8 редактора (Блокнот на старых версиях Windows, некоторые китайские методы ввода), файл мог быть сохранён с BOM. Hermes терпим к utf-8-sig при чтении большинства конфигураций, но BOM внутри свёрнутых YAML-скаляров (description: >) молча ломает парсинг YAML. Пересохраните файл как чистый UTF-8 без BOM.

Дальнейшие шаги