Windows (原生) 指南 —— 早期 Beta 版

Windows (原生) 使用指南

早期 Beta 阶段

原生 Windows 支持目前处于 早期 Beta 阶段。它虽然可以安装、运行，并已通过了针对 Windows 常见 “地雷” 的校验（lint），但尚未像 Linux/macOS/WSL2 路径那样经过大规模的实战压力测试。请做好遇到小问题的心理准备 —— 特别是在子进程处理、路径怪癖和非 ASCII 字符的控制台输出方面。如果你遇到了问题，请提交带有复现步骤的 Issue。如果你现在就需要一个经受过实战检验的环境，请改为在 WSL2 中使用 Linux/macOS 安装程序。

Hermes 可以原生运行在 Windows 10 和 Windows 11 上 —— 无需 WSL，无需 Cygwin，也无需 Docker。本页面是深度解析：哪些功能可以原生工作、哪些仅限 WSL、安装程序实际执行了什么操作，以及你可能需要调整的 Windows 专用配置项。

如果你只想安装，只需使用首页或安装页面上的单行命令即可。当遇到出乎意料的情况时再回到这里。

快速安装

打开 PowerShell（或 Windows Terminal）并运行：

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`	off	跳过 venv 创建（高级用法 —— 由你自行管理 Python）
`-SkipSetup`	off	跳过安装后的 `hermes setup` 设置向导
`-HermesHome`	`%LOCALAPPDATA%\hermes`	覆盖数据目录
`-InstallDir`	`%LOCALAPPDATA%\hermes\hermes-agent`	覆盖代码位置

安装程序具体执行的操作

按先后顺序如下：

引导安装 uv —— Astral 开发的高速 Python 管理器。安装至 %USERPROFILE%\.local\bin。
通过 uv 安装 Python 3.11。无需预装 Python。
安装 Node.js 22（如果可用则通过 winget 安装，否则将便携版 Node 压缩包解压至 %LOCALAPPDATA%\hermes\node）。用于浏览器工具和 WhatsApp 桥接。
安装便携版 Git —— 如果 PATH 中已有 git，安装程序将直接使用；否则它会下载一个精简、自包含的 PortableGit（约 45 MB，来自官方 git-for-windows 发行版）至 %LOCALAPPDATA%\hermes\git。无需管理员权限，不涉及 Windows 安装程序注册表，不干扰系统中任何其他内容。
克隆仓库至 %LOCALAPPDATA%\hermes\hermes-agent 并在其内部创建虚拟环境（virtualenv）。
分级 uv pip install —— 首先尝试 .[all]，如果因 GitHub 速率限制导致 git+https 依赖安装失败，则退而求其次尝试较小的集合（[messaging,dashboard,ext] → [messaging] → .）。防止 “单点故障导致安装完全失败”。
根据 .env 自动安装消息 SDK —— 如果存在 TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN / SLACK_BOT_TOKEN / SLACK_APP_TOKEN / WHATSAPP_ENABLED，则运行 python -m ensurepip --upgrade 并执行针对性的 pip install 调用，确保各平台的 SDK 均可被正常导入。
设置 HERMES_GIT_BASH_PATH 指向确定的 bash.exe 路径，以便 Hermes 在新 Shell 中能准确找到它。
将 %LOCALAPPDATA%\hermes\bin 添加到用户 PATH —— 在你打开新终端后即可使用 hermes 命令。
运行 hermes setup —— 标准的首次运行向导（配置模型、供应商、工具集）。使用 -SkipSetup 可跳过此步骤。

功能矩阵

除了仪表盘（Dashboard）的嵌入式终端面板外，所有功能均在 Windows 上原生运行。

功能	原生 Windows	WSL2
CLI (`hermes chat`, `hermes setup`, `hermes gateway`, …)	✓	✓
交互式 TUI (`hermes --tui`)	✓	✓
消息网关（Telegram, Discord, Slack, WhatsApp, 15+ 平台）	✓	✓
Cron 调度器	✓	✓
浏览器工具（通过 Node 驱动 Chromium）	✓	✓
MCP 服务器（stdio 和 HTTP）	✓	✓
本地 Ollama / LM Studio / llama-server	✓	✓ (通过 WSL 网络)
Web 仪表盘（会话、任务、指标、配置）	✓	✓
仪表盘 `/chat` 嵌入式终端面板	✗ (需要 POSIX PTY)	✓
登录时自动启动	✓ (schtasks)	✓ (systemd)

仪表盘的 /chat 标签页通过 POSIX PTY (ptyprocess) 嵌入了一个真实的终端。原生 Windows 没有等效的基元；Python 的 pywinpty / Windows ConPTY 虽然可行但属于独立的实现 —— 目前将其视为未来工作。仪表盘的其余部分均可原生工作 —— 仅该标签页会显示 “请使用 WSL2 以运行此功能” 的横幅。

Hermes 如何在 Windows 上运行 Shell 命令

Hermes 的终端工具通过 Git Bash 运行命令，这与 Claude Code 采用的策略相同。这样可以在不重写每个工具的情况下避开 POSIX 与 Windows 之间的差异。

bash.exe 的解析顺序：

HERMES_GIT_BASH_PATH 环境变量（如果已设置）。
%LOCALAPPDATA%\hermes\git\usr\bin\bash.exe（安装程序管理的 PortableGit）。
%LOCALAPPDATA%\hermes\git\bin\bash.exe（旧版 Git-for-Windows 布局）。
系统安装的 Git-for-Windows（%ProgramFiles%\Git\bin\bash.exe 等）。
作为最后手段，使用 PATH 中的 MSYS2、Cygwin 或任何 bash.exe。

安装程序会显式设置 HERMES_GIT_BASH_PATH，因此新的 PowerShell 会话无需重新查找。如果你希望 Hermes 使用特定的 bash（例如系统 Git Bash 或通过符号链接指向的 WSL bash），可以覆盖此变量。

陷阱： MinGit 的布局与完整的 Git-for-Windows 安装程序不同 —— bash 位于 usr\bin\bash.exe 而不是 bin\bash.exe。Hermes 会同时检查这两个路径。如果你是手动解压 MinGit 压缩包，请确保选择 非 busybox 版本（MinGit-*-64-bit.zip，而不是 MinGit-*-busybox*.zip） —— busybox 构建版本提供的是 ash 而非 bash，且缺少大部分 coreutils。

Windows 上的 UTF-8 控制台

Windows 上 Python 默认的 stdio 使用控制台的活动代码页（通常是 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）早期被调用。它会执行：

通过 kernel32.SetConsoleCP / SetConsoleOutputCP 将控制台代码页切换为 CP_UTF8 (65001)。
使用 errors='replace' 将 sys.stdout / sys.stderr / sys.stdin 重新配置为 UTF-8。
设置 PYTHONIOENCODING=utf-8 和 PYTHONUTF8=1（通过 setdefault 设置，因此用户显式设置的值优先），使子 Python 进程继承 UTF-8 设置。
如果未设置 EDITOR 或 VISUAL，则将 EDITOR 设置为 notepad（见下文编辑器部分）。

该操作是幂等的。在非 Windows 系统上不执行任何操作。

退出选项： 在环境中设置 HERMES_DISABLE_WINDOWS_UTF8=1 将回退到传统的 cp1252 stdio 路径。这对于排查编码错误有用，但在正常操作中不建议使用。

编辑器 (Ctrl-X Ctrl-E, /edit)

在 #21561 之前，在 Windows 上按下 Ctrl-X Ctrl-E 或输入 /edit 会静默失效。prompt_toolkit 有一个硬编码的 POSIX 绝对路径回退列表（/usr/bin/nano, /usr/bin/pico, /usr/bin/vi, …），这些路径在 Windows 上永远无法解析 —— 即使安装了完整的 Git for Windows。

Hermes 的 Windows stdio 补丁现在将 EDITOR=notepad 设为默认值。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"`

VS Code 的 --wait 标志至关重要 —— 如果没有它，编辑器会立即返回，导致 Hermes 获取到一个空的缓冲区。

你可以将其永久设置在 PowerShell 配置文件中：

# 在 $PROFILE 中
$env:EDITOR = "code --wait"

或者在系统设置中将其设为 “用户环境变量”，以便每个新 Shell 都能自动获取。

CLI 中的 Ctrl+Enter 换行

Windows Terminal 将 Ctrl+Enter 作为专门的键序列传递。Hermes 将其绑定为 “插入换行符”，这样你就可以在 CLI 中撰写多行提示词，而无需回退到 Esc 后按 Enter 的方式。该功能在 Windows Terminal、VS Code 集成终端以及任何遵循 VT 转义序列的现代 Windows 控制台宿主中均有效。

在旧版 cmd.exe 控制台中，Ctrl+Enter 会退化为普通的 Enter —— 此时请改用 Esc Enter，或升级到 Windows Terminal（它是免费的，且在 Windows 11 中默认安装）。

在 Windows 登录时运行网关

在 Windows 上，hermes gateway install 使用 计划任务（Scheduled Tasks），并以 “启动文件夹（Startup-folder）” 作为回退方案 —— 无需管理员权限。

安装

hermes gateway install

底层执行的操作：

schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway —— 注册一个在登录时以标准（非提权）权限运行的任务。无 UAC 弹窗。
如果 schtasks 被组策略禁用，则回退到在 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup 中写入一个 start /min cmd.exe /d /c <wrapper> 快捷方式。效果相同，但稍显简陋。
通过 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      # 合并视图：显示计划任务 + 启动文件夹 + 正在运行的 PID
hermes gateway start       # 立即启动计划任务
hermes gateway stop        # 等效于优雅的 SIGTERM（通过 psutil 执行 TerminateProcess）
hermes gateway restart
hermes gateway uninstall   # 移除计划任务条目、启动快捷方式和 pid 文件

hermes gateway status 是幂等的 —— 连续调用一千次也不会误杀网关。（在 PR #21561 之前，由于 os.kill(pid, 0) 在 C 语言层面与 CTRL_C_EVENT 冲突，它确实会误杀网关 —— 如果你对这段往事感兴趣，请参阅下文的 “进程管理内部机制”。）

为什么不使用 Windows 服务？

服务安装需要管理员权限，且会将网关的生命周期绑定到机器启动而非用户登录。典型的 Hermes 用户需求是：登录 → 网关可用，注销 → 网关退出。计划任务在无需提权的情况下完美实现了这一点。如果你确实需要服务，请手动使用 nssm 或 sc create —— 但你大概率不需要。

数据布局

路径	内容
`%LOCALAPPDATA%\hermes\hermes-agent\`	Git 检出内容 + venv。可以安全地执行 `Remove-Item -Recurse` 并重新安装。
`%LOCALAPPDATA%\hermes\git\`	便携版 Git（仅当安装程序自动准备时）。
`%LOCALAPPDATA%\hermes\node\`	便携版 Node.js（仅当安装程序自动准备时）。
`%LOCALAPPDATA%\hermes\bin\hermes.cmd`	填充脚本（shim），已添加到用户 PATH。
`%USERPROFILE%\.hermes\`	你的配置、身份验证、技能、会话和日志。重新安装后仍会保留。

这种拆分是刻意为之的：%LOCALAPPDATA%\hermes 是 可丢弃的基础设施（你可以直接删掉它，然后用一行命令恢复）。而 %USERPROFILE%\.hermes 是 你的数据 —— 配置、记忆、技能、会话历史 —— 其结构与 Linux 安装完全一致。在机器之间镜像此文件夹，你的 Hermes 就会随你迁移。

覆盖 HERMES_HOME： 设置该环境变量以指向不同的数据目录。其工作方式与 Linux 相同。

浏览器工具

浏览器工具使用 agent-browser（一个 Node 助手）来驱动 Chromium。在 Windows 上：

安装程序通过 npm 将 agent-browser 添加到 PATH。
shutil.which("agent-browser", path=...) 会自动获取 .cmd 填充脚本 —— CreateProcessW 无法执行无扩展名的 shebang 脚本，因此 Hermes 总是解析为 .CMD 包装器。不要手动调用 shebang 脚本，务必通过 .cmd 运行。
Playwright Chromium 在首次运行时自动安装（npx playwright install chromium）。如果安装失败，hermes doctor 会显示修复提示。

在 Windows 上运行 Hermes —— 实践说明

安装后的 PATH

安装程序通过 [Environment]::SetEnvironmentVariable 将 %LOCALAPPDATA%\hermes\bin 添加到你的 用户 PATH。现有的终端不会识别此更改 —— 安装后请打开新的 PowerShell 窗口（或 Windows Terminal 标签页）。请关闭并重新打开，除非你非常清楚自己在做什么，否则不要手动执行 $env:PATH += …。

验证方式：

Get-Command hermes        # 应打印 C:\Users\<用户名>\AppData\Local\hermes\bin\hermes.cmd
hermes --version

环境变量

Hermes 同时支持 $env:X（进程作用域）和用户环境变量（永久性，在系统属性 → 环境变量中设置）。在 %USERPROFILE%\.hermes\.env 中设置 API 密钥是常规路径 —— 与 Linux 相同：

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

不要将秘密信息放在 “用户环境变量” 中，除非你明确希望每个 Windows 进程都能看到它们（通常你并不希望这样）。

Windows 专用环境变量

这些变量仅影响原生 Windows 安装：

变量	效果
`HERMES_GIT_BASH_PATH`	覆盖 `bash.exe` 查找路径。可指向任何 bash —— 完整版 Git-for-Windows、通过符号链接指向的 WSL bash、MSYS2 或 Cygwin。安装程序会自动设置此项。
`HERMES_DISABLE_WINDOWS_UTF8`	设置为 `1` 以禁用 UTF-8 stdio 补丁并回退到区域设置代码页。用于排查编码错误。
`EDITOR` / `VISUAL`	用于 `/edit` 和 `Ctrl-X Ctrl-E` 的编辑器。如果两者均未设置，Hermes 默认使用 `notepad`。

卸载

在 PowerShell 中运行：

hermes uninstall

这是标准的清理路径 —— 移除计划任务条目、启动文件夹快捷方式、hermes.cmd 填充脚本，删除 %LOCALAPPDATA%\hermes\hermes-agent\，并清理用户 PATH。它会保留 %USERPROFILE%\.hermes\（你的配置、认证、技能、会话、日志），以便你重新安装。

若要彻底删除所有内容：

hermes uninstall
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"

hermes uninstall CLI 子命令还会处理计划任务条目以不同任务名称注册的情况（针对旧版本安装） —— 它通过安装路径而非硬编码的任务名称进行搜索。

进程管理内部机制

此内容为背景资料 —— 除非你正在调试 “它在自杀” 之类的怪异问题，否则可以跳过。

在 Linux 和 macOS 上，POSIX 惯用语 os.kill(pid, 0) 是一个不执行操作的权限检查：“此 PID 是否存活，我能否向其发送信号？”。而在 Windows 上，Python 的 os.kill 将 sig=0 映射到 CTRL_C_EVENT —— 它们的整数值都是 0 —— 并通过 GenerateConsoleCtrlEvent(0, pid) 进行路由，这会将 Ctrl+C 广播到包含目标 PID 的整个控制台进程组。这就是自 2012 年以来一直挂起的 bpo-14484 问题。它不会被修复，因为改变它会破坏依赖当前行为的脚本。

后果： 在 Windows 上，任何通过 os.kill(pid, 0) 来 “检查此 PID 是否存活” 的代码路径都会静默地杀死目标。Hermes 已经将所有此类位置（涉及 11 个文件的 14 处）迁移到了 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 隐患（阻塞）” 检查失败，除非该行带有 # windows-footgun: ok — <reason> 标记。

常见坑点

**安装后提示 hermes: command not found**：打开一个新的 PowerShell 窗口。安装程序已将 %LOCALAPPDATA%\hermes\bin 添加到用户 PATH，但现有的 Shell 需要重启才能识别。在此期间，你可以运行 & "$env:LOCALAPPDATA\hermes\bin\hermes.cmd"。
**运行工具时出现 WinError 193: %1 is not a valid Win32 application**：你触发了一个绕过 .cmd 填充脚本的 shebang 脚本调用。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 形式，或者手动下载脚本并使用 [IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false)) 保存为无 BOM 格式。
网关在重启后无法保持运行：检查 hermes gateway status —— 它合并了计划任务条目、启动文件夹快捷方式（如果已使用）和实时 PID。如果计划任务已注册但未运行，可能是组策略阻止了 ONLOGON 触发器。运行 schtasks /Query /TN HermesGateway /V /FO LIST 查看任务失败原因，或者卸载后通过 HERMES_GATEWAY_FORCE_STARTUP=1 重新安装以回退到启动文件夹路径。
设置 $env:EDITOR 后 /edit 仍无反应：你只在当前进程中设置了它；请关闭并重新打开 Shell，或者在系统属性 → 环境变量的用户作用域中设置它。在新的 PowerShell 窗口中通过 echo $env:EDITOR 验证。
浏览器工具启动但工具超时：Chromium 在首次运行时自动安装。如果安装失败（由于 GitHub 速率限制或 Playwright CDN 故障），请运行 hermes doctor —— 它会指出缺失的 Chromium 并打印具体的 npx playwright install chromium 修复命令。
agent-browser 报错提示 Node 版本怪异：安装程序在 %LOCALAPPDATA%\hermes\node 准备了 Node 22，但你的 PATH 中可能先排了一个旧版的系统 Node 18。要么将 Hermes 的 node 目录移到 PATH 的更前面，要么如果你在别处不用 Node，直接删除系统安装的 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 后出现“在另一台机器上正常”的编码灵异现象：如果你在 Windows 上使用非 UTF-8 编辑器（旧版 Windows 的记事本、某些中文输入法）编辑了 Hermes 配置或技能，文件可能被保存带有了 BOM。Hermes 在读取大多数配置时容忍 utf-8-sig，但折叠式 YAML 标量（description: >）内部的 BOM 会静默破坏 YAML 解析。请将文件重新保存为不带 BOM 的纯 UTF-8 格式。

下一步行动

安装 —— 完整的安装页面，包括 Linux/macOS/WSL2/Termux。
Windows (WSL2) 指南 —— 如果你需要 POSIX 语义或仪表盘终端面板。
CLI 参考 —— 每一个 hermes 子命令。
FAQ —— 常见的非 Windows 特定问题。
消息网关 —— 在 Windows 上运行 Telegram/Discord/Slack。

核心能力

自动化

媒体与网页

管理

技能目录

高级

架构

扩展

内部机制