Windows (Native) Guide 分析

Hermes Windows 原生安装指南

官方文档 — 适用于 Windows 10/11，无需 WSL/Cygwin/Docker

安装方式

  • PowerShell 一行安装：iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)，无需管理员权限
  • Desktop GUI 安装器 (.exe)：适合非开发者，底层同样调用 install.ps1
  • 参数选项：-Branch/-Commit/-Tag/-NoVenv/-SkipSetup/-HermesHome/-InstallDir

安装器执行流程（install.ps1）

  1. 安装 uv（Python 包管理器）→ %USERPROFILE%\.local\bin
  2. 通过 uv 安装 Python 3.11
  3. 安装 Node.js 22（winget 或 portable 方式）
  4. 安装 PortableGit（~45MB，非 busybox 版）
  5. Clone 仓库到 %LOCALAPPDATA%\hermes\hermes-agent\，创建虚拟环境
  6. 分层 uv pip install：尝试 .[all] → [messaging,dashboard,ext] → [messaging] → .
  7. 根据 .env 自动安装消息平台 SDK
  8. 设置 HERMES_GIT_BASH_PATH、添加 User PATH、运行 hermes setup

依赖引导（dep_ensure）

依赖用途
PortableGit提供 bash.exe（terminal 工具）和 git
Node.js 22browser 工具、TUI web bridge、WhatsApp bridge
ffmpeg音频格式转换（TTS/语音消息）
ripgrep快速文件搜索

功能矩阵 — 原生 vs WSL2

功能原生 WindowsWSL2
CLI（chat、setup、gateway...）✅✅
交互式 TUI✅✅
消息网关（Telegram/Discord/Slack/WhatsApp 等 15+ 平台）✅✅
Cron 调度器✅✅
Browser 工具（Chromium）✅✅
MCP 服务器（stdio 和 HTTP）✅✅
本地 Ollama/LM Studio✅✅（通过 WSL 网络）
Web Dashboard（会话、任务、指标、配置）✅✅
Dashboard /chat 嵌入式终端❌（需 POSIX PTY）✅
开机自启✅（schtasks）✅（systemd）

除 Dashboard 的嵌入式终端窗格外，所有功能原生运行。

shell 命令运行机制

Hermes 通过 Git Bash 运行终端命令（与 Claude Code 策略相同）。bash.exe 解析顺序：

  1. HERMES_GIT_BASH_PATH 环境变量
  2. %LOCALAPPDATA%\hermes\git\usr\bin\bash.exe（安装器管理的 PortableGit）
  3. %LOCALAPPDATA%\hermes\git\bin\bash.exe（旧版路径）
  4. 系统 Git-for-Windows 安装
  5. MSYS2/Cygwin 或其他 PATH 中的 bash.exe

UTF-8 控制台

Python 在 Windows 上默认使用控制台代码页（cp1252/cp437）。configure_windows_stdio() 自动：

  • 切换控制台代码页为 CP_UTF8（65001）
  • 配置 sys.stdout/stderr/stdin 为 UTF-8（errors='replace'）
  • 设置 PYTHONIOENCODING=utf-8 和 PYTHONUTF8=1
  • 默认 EDITOR=notepad

可通过 HERMES_DISABLE_WINDOWS_UTF8=1 退出。

编辑器设置

编辑器PowerShell 命令
VS Code$env:EDITOR = "code --wait"
Notepad++$env:EDITOR = "..."

Gateway 开机自启

hermes gateway install 使用 Scheduled Tasks（ONLOGON），无需管理员权限。无 UAC 弹窗。若 schtasks 被封锁则回退到 Startup 文件夹快捷方式。Gateway 通过 pythonw.exe 分离启动。

数据布局

路径内容
%LOCALAPPDATA%\hermes\hermes-agent\Git checkout + venv，可删后重装
%LOCALAPPDATA%\hermes\git\PortableGit
%LOCALAPPDATA%\hermes\node\Portable Node.js
%LOCALAPPDATA%\hermes\（根目录）配置、认证、skills、会话、日志 — 重装时保留

⚠️ 慎用 Remove-Item -Recurse %LOCALAPPDATA%\hermes，会清除配置数据。

进程管理内部原理

Python 在 Windows 上 os.kill(pid, 0) 映射为 CTRL_C_EVENT（信号值碰撞），会广播 Ctrl+C 给整个控制台进程组。Hermes 已将所有 14 处调用迁移到 psutil.pid_exists()。

常见陷阱汇总

  • hermes: command not found — 打开新 PowerShell 窗口
  • WinError 193 — 绕过了 .cmd shim，始终用 .cmd 变体
  • [scriptblock]::Create 失败 — UTF-8 BOM 问题，回退到 irm | iex 形式
  • Gateway 重启后不运行 — schtasks /Query /TN HermesGateway /V /FO LIST 查原因
  • /edit 无效 — EDITOR 环境变量未持久化，设 User 作用域
  • 中/日/阿字符显示为 ? — UTF-8 shim 未生效，换 Windows Terminal