Hermes Agent на Windows: нативная установка

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

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

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

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

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

Права администратора не нужны. Инсталлятор разворачивается в %LOCALAPPDATA%\hermes\ и добавляет hermes в ваш User PATH — после завершения откройте новый терминал.

Параметры инсталлятора передаются через scriptblock:

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -NonInteractive -Branch main

Флаги -NoVenv и -Tag текущий скрипт не принимает. -SkipSetup по-прежнему принимается как устаревший псевдоним -NonInteractive, чтобы старые обёртки установки продолжали работать. Если путь в Windows получился неожиданно коротким, начните диагностику с -ShowResolvedPaths.

MSIX / App Installer и Microsoft Store

Бандл десктопа не связан со скриптом установки из исходников. Его пакету MSIX нужна Windows 11 22H2 или новее. То, что скрипт из исходников поддерживает Windows 10, не значит, что пакет MSIX её тоже поддерживает.

Откройте скачанный файл .appinstaller в Windows App Installer. Он ставит подписанный универсальный бандл и запоминает источник обновлений. В пакет уже входят Python, Node, поддерживаемые зависимости и собранные интерфейсы. При первом запуске он не клонирует checkout и не собирает базовую среду выполнения.

Псевдонимы выполнения MSIX дают команды hermes, hermes-agent и hermes-acp. Если псевдоним перекрывает другая установка, посмотрите Get-Command hermes -All. Управляются псевдонимы в «Параметры Windows» → «Приложения» → «Дополнительные параметры приложений» → «Псевдонимы выполнения приложений».

Sideload-обновления идут через кнопку Update в приложении и Windows App Installer. Hermes скачивает локальный дескриптор до остановки процессов и регистрирует автоматический перезапуск. Протокол URL ms-appinstaller: для этого не нужен. Неизвестный результат проверки обновлений не означает, что пакет актуален.

Вариант из Microsoft Store использует идентичность пакета из Partner Center и обновления Store, а не sideload-фид. hermes update внутри любой из бандл-сред не запускает Git по файлам пакета.

Hermes-Setup.exe — другой, бутстрап-инсталлятор. Он разворачивает checkout исходников через скрипты. Не путайте его с самодостаточным пакетом MSIX. См. Обновление и удаление.

Бутстрап зависимостей

Управляемыми инструментами владеет PM. Код конкретной функции просит у PM нужный пакет (pm.ensure("<package>"), например cua-driver для Computer Use), а не перезапускает инсталлятор. Уже установленные инструменты переиспользуются по записанному состоянию PM; недостающий необязательный инструмент докачивается по требованию, только если это разрешает security.allow_lazy_installs. Режима -Ensure у install.ps1 нет.

hermes pm doctor
hermes pm install

Что делает инсталлятор из исходников

1. Находит Git или, если его нет, разворачивает проверенную закреплённую версию Git for Windows.
2. Клонирует выбранную ветку репозитория и, если задано, переключается на закреплённый коммит.
3. Поднимает uv и создаёт начальное окружение Python.
4. Запускает PM, который ставит Python 3.14, нужные инструменты и Python-extra all.
5. Создаёт лаунчеры CLI в каталоге bin домашнего каталога данных и добавляет его в User PATH.
6. Готовит конфигурацию и запускает интерактивные этапы настройки и шлюза, если их не пропустили.
7. Если попросили, собирает десктоп и создаёт ярлыки в меню «Пуск» и на рабочем столе.
8. Записывает маркер завершения бутстрапа.

Лаунчер среды выполнения запускает Python из хранилища PM и выбирает окружение зависимостей до импортов. PM может опубликовать новое записываемое окружение, не заменяя библиотеки, уже загруженные работающим процессом. Многоуровневого отката pip, который молча урезал бы набор установленных возможностей, нет.

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

Поддержка Windows зависит от конкретной функции и архитектуры. Базовые интерфейсы работают нативно, но некоторые необязательные SDK для отдельных целевых платформ исключены.

На Windows дашборд использует мост pywinpty/ConPTY, на POSIX — ptyprocess. Если нативная зависимость отсутствует или сломана, терминал может оказаться недоступен; WSL — это альтернатива, а не требование текущей архитектуры.

Ограничения необязательных зависимостей

• Нативный адаптер Matrix с шифрованием работает только на Linux; на Windows используйте поддерживаемый маршрут через прокси или Linux-бэкенд.
• На нативной Windows ARM64 исключены SDK-extra google-chat, а также движок openWakeWord. Sherpa поддерживает нативную Windows ARM64 и на этой платформе автоматически становится движком wake-word по умолчанию.
• Локальный STT на Faster-Whisper на нативной Windows ARM64 исключён. Используйте облачного или командного провайдера STT. Porcupine остаётся альтернативным движком wake-word.

Упакованный набор зависимостей определяют маркеры платформ в pyproject.toml. Общее заявление о поддержке шлюза или голосовых функций эти маркеры не отменяет.

Как Hermes выполняет shell-команды на Windows

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

Поиском Bash заведует pm.shell(). Сначала он проверяет пакет Git, записанный в фактах PM, затем подготовленный PATH. Если кандидат из PATH принадлежит пакету WindowsApps, резолвер предпочитает обычную установку Git for Windows, когда она есть.

Упакованные инструменты — не установки общего назначения на хосте. Внешний процесс Python может не суметь запустить исполняемый файл из WindowsApps и получить WinError 5. Используйте собственный лаунчер пакета или обычные инструменты для checkout исходников. Не отключайте механизмы безопасности Windows, чтобы обойти эту границу.

Текущий инсталлятор не задаёт HERMES_GIT_BASH_PATH. MinGit не заменяет Git for Windows с Bash.

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

По умолчанию stdio 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=notepad, если не заданы ни EDITOR, ни VISUAL (см. раздел про редактор ниже).

Идемпотентна. На не-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 по умолчанию. Notepad есть в любой установке Windows и работает как блокирующий редактор — subprocess.call(["notepad", file]) блокируется, пока окно не закроется.

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

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

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

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

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

Ctrl+Enter для переноса строки в CLI

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

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

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

hermes gateway install на Windows использует Scheduled Tasks с откатом на папку «Автозагрузка» — права администратора не нужны.

Установка

hermes gateway install

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

1. schtasks /Create /SC ONLOGON /RL LIMITED /TN Hermes_Gateway — регистрирует задачу, которая запускается при вашем входе со стандартными (не повышенными) правами. Без запроса UAC.
2. Если schtasks заблокирован групповой политикой, откатывается на запись небольшого лаунчера Hermes_Gateway.vbs (запускается скрыто через wscript.exe) в %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup. Эффект тот же, способ чуть грубее. VBScript выбран вместо ярлыка на cmd.exe потому, что выделенная при входе консоль может получить событие закрытия и убить шлюз, не дав ему толком запуститься. Остаётся только один из двух вариантов: успешная установка задачи удаляет любую запись из папки автозагрузки (включая устаревший Hermes_Gateway.cmd), запасной вариант пропускается, пока задача ещё зарегистрирована, а hermes update / hermes doctor --fix чистят старые установки, где есть оба, — иначе при входе шлюз запускался бы дважды.
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      # Merged view: schtasks + Startup folder + running PID
hermes gateway start       # Starts the gateway in the background (asks about login auto-start only on a TTY when nothing is installed)
hermes gateway stop        # Пишет маркер плановой остановки, ждёт, пока шлюз доработает (≤ agent.restart_drain_timeout, не более 30 с), и убивает принудительно, только если он всё ещё жив
hermes gateway restart     # Та же остановка с ожиданием, затем свежий запуск
hermes gateway uninstall   # Removes schtasks entry, Startup shortcut, pid file

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

Автозапуск при входе ставится только по явному ответу: hermes gateway install, Y в настоящем терминале или HERMES_GATEWAY_INSTALL_START_ON_LOGIN=1. Скриптовый или запущенный через pipe hermes gateway start (без TTY или с HERMES_NONINTERACTIVE=1) запускает шлюз, не трогая ни Scheduled Task, ни папку «Автозагрузка»; чтобы не задавать этот вопрос и в терминале, задайте HERMES_GATEWAY_INSTALL_START_ON_LOGIN=0.

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

Службы требуют прав администратора для установки и привязывают жизненный цикл шлюза к загрузке машины, а не к входу пользователя. Типичный пользователь Hermes хочет: вошёл — шлюз доступен, вышел — шлюз исчез. Scheduled Tasks делают ровно это, без повышения прав. Если служба вам действительно нужна, поднимите её вручную через nssm или sc create — но скорее всего она вам ни к чему. Если всё же решились, назовите её Hermes* или укажите путь к бинарнику внутри установки Hermes (venv\Scripts\hermes.exe, checkout или gateway-service\): hermes update останавливает и перезапускает только те службы, которые может однозначно опознать как принадлежащие Hermes через Service Control Manager, а шлюз, запущенный через Scheduled Task, приостанавливает по PID (сам планировщик заданий не трогается).

Раскладка данных

Это пути по умолчанию: HERMES_HOME и аргументы путей инсталлятора могут их изменить. Полное удаление %LOCALAPPDATA%\hermes стирает и пользовательские данные, а заодно может задеть другие установки, которые делят этот каталог. Чтобы починить приложение, используйте команду удаления или удаление пакета Windows, а не сносите этот корень.

Браузерный инструмент

Настройка браузера зависит от выбранного бэкенда. Для встроенного бэкенда PM поставляет закреплённые пакеты agent-browser и Chromium. У Browser Use своя управляемая установка CLI через hermes tools. Самодостаточный MSIX включает поддерживаемые браузерные инструменты прямо в пакет.

На Windows ARM64 закреплённые бинарники Chromium и agent-browser могут работать через эмуляцию x64 в Windows — в отличие от нативной ARM64-среды Python. Выбор бэкенда описан в разделе Автоматизация браузера.

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

PATH после установки

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

Проверка:

Get-Command hermes        # should print C:\Users\<you>\AppData\Local\hermes\bin\hermes.exe
hermes --version

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

Hermes уважает и $env:X (область процесса), и пользовательские переменные окружения (постоянные, задаются в System Properties → Environment Variables). Прописать API-ключи в %LOCALAPPDATA%\hermes\.env (ваш HERMES_HOME) — обычный путь, как и на Linux:

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

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

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

Влияют только на нативные установки Windows:

Удаление

Из PowerShell:

hermes uninstall

Для установок из исходников деинсталлятор удаляет свои лаунчеры, записи служб и файлы приложения. Перед удалением посмотрите вывод hermes uninstall --dry-run. --full удаляет и данные; --data удаляет данные, не трогая упакованный код. Установки из MSIX или Store удаляйте через «Параметры Windows» → «Приложения» → «Установленные приложения». Удалять код, которым владеет пакет, 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 года. Баг не исправят: изменение поведения сломает скрипты, которые на него полагаются.

Следствие: любой путь кода, который через os.kill(pid, 0) «проверял, жив ли PID», на 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 в User PATH, но уже открытым оболочкам нужно перезапуститься, чтобы это подхватить. А пока можно запустить & "$env:LOCALAPPDATA\hermes\bin\hermes.exe".

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 подцепила UTF-8 BOM. Форма 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 Hermes_Gateway /V /FO LIST (для именованного профиля — Hermes_Gateway_<profile>), чтобы увидеть причину сбоя задачи. Откат на «Автозагрузку» включается сам и только тогда, когда schtasks не смог зарегистрировать задачу: ни переменной окружения, ни флага, чтобы вызвать его принудительно, нет.

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

Браузерный инструмент запускается, но инструменты отваливаются по тайм-ауту. Выполните hermes doctor и hermes pm doctor. Выбранный браузерный бэкенд можно посмотреть через hermes tools. Не ставьте постороннюю ревизию Playwright внутрь подписанного пакета приложения.

agent-browser сообщает об ошибке версии Node. Выполните hermes pm doctor и посмотрите, какой лаунчер Hermes запустил процесс. Управляемую версию Node поставляет PM. Не удаляйте постороннюю системную установку Node, чтобы починить Hermes.

Китайские / японские / арабские символы показываются как ? в 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-редакторе (Notepad на старых версиях Windows, некоторые китайские IME), файл мог сохраниться с BOM. Hermes терпит utf-8-sig при чтении большинства конфигов, но BOM внутри свёрнутого YAML-скаляра (description: >) молча ломает разбор YAML. Пересохраните файл как обычный UTF-8 без BOM.

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

• Установка — полная страница установки, включая Linux/macOS/WSL2.
• Руководство по Windows (WSL2) — если нужна POSIX-семантика или панель терминала в дашборде.
• Справочник CLI — каждая подкоманда hermes.
• FAQ — частые вопросы, не привязанные к Windows.
• Шлюз сообщений — запуск Telegram/Discord/Slack на Windows.