hermes教程-Windows（原生）指南

快速安装

打开 PowerShell（或 Windows 终端）并运行：

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

无需管理员权限。安装程序将文件放入 %LOCALAPPDATA%\hermes\ 并将 hermes 添加到你的 用户 PATH 中——完成后打开一个新终端。

安装程序选项（需要脚本块形式来传递参数）：

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main

安装程序会自动重试不稳定的 git 拉取，并从任何下载的 install.ps1 负载中去除 BOM，因此 HTTP 传输过程中捕获的 UTF-8 BOM 不再破坏 [scriptblock]::Create((irm ...)) 形式。

桌面安装程序（替代方案）

还提供了一个轻量级 GUI 安装程序——如果你更愿意双击 .exe 而不是打开 PowerShell，这会很有用。下载 Hermes Desktop，运行安装程序，首次启动时 GUI 会在后台调用 install.ps1 来配置 Python（通过 uv）、Node、PortableGit 以及下面描述的其余依赖引导。首次运行后，桌面应用和通过 PowerShell 安装的 hermes CLI 共享同一个 %LOCALAPPDATA%\hermes\hermes-agent 安装目录和 %LOCALAPPDATA%\hermes 数据目录——你可以在 GUI 和 CLI 之间自由切换。

当你想要熟悉的 Windows 安装体验，或者将 Hermes 交给非开发者时，使用桌面安装程序；当你已经在终端中时，使用 PowerShell 一行命令。

依赖引导（dep_ensure）

在首次启动时（以及检测到缺少工具时按需），Hermes 会运行一个小的 Python 引导程序——hermes_cli/dep_ensure.py——它检查并惰性安装所需的非 Python 依赖。在 Windows 上，相关的依赖有：

每个依赖都有一个 shutil.which(...) 风格的检查；如果二进制文件缺失且运行是交互式的，dep_ensure 会提供安装选项（将实际安装逻辑委托给 scripts\install.ps1 -ensure <dep>）。非交互式运行（网关、cron、无头桌面启动）会跳过提示，并显示清晰的 此功能需要 <dep> 错误。

安装程序实际做了什么

从上到下，按顺序：

1. 引导 uv——Astral 的快速 Python 管理器。安装到 %USERPROFILE%\.local\bin。
2. 通过 uv 安装 Python 3.11。无需现有 Python。
3. 安装 Node.js 22（如果可用则使用 winget，否则将可移植 Node tarball 解压到 %LOCALAPPDATA%\hermes\node）。用于浏览器工具和 WhatsApp 桥接。
4. 安装可移植 Git——如果 git 已在 PATH 上，安装程序会使用它；否则它会下载一个精简的、自包含的 PortableGit（约 45 MB，来自官方的 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. 根据 .env 自动安装消息 SDK——如果存在 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 在新 shell 中确定性地找到它。
9. 将 %LOCALAPPDATA%\hermes\hermes-agent\venv\Scripts 添加到用户 PATH 并设置 HERMES_HOME=%LOCALAPPDATA%\hermes——在你打开新终端后暴露 hermes 命令（并将其指向你的数据目录）。
10. 运行 hermes setup——正常的首次运行向导（模型、提供者、工具集）。使用 -SkipSetup 跳过。

提示——在 Windows 上跳过提供者搜索

在 Windows 上，每个工具的 API 密钥设置（Firecrawl、FAL、Browser Use、OpenAI TTS）是获得一个有用代理的最高摩擦部分。一个 Nous Portal 订阅通过一次 OAuth 登录涵盖了模型和所有这些工具。安装程序完成后，运行 hermes setup --portal 来连接所有内容。

功能矩阵

除了仪表板的嵌入式终端窗格外，所有功能都在 Windows 上原生运行。

仪表板的 /chat 标签通过 POSIX PTY（ptyprocess）嵌入了一个真正的终端。原生 Windows 没有等效的原语；Python 的 pywinpty / Windows ConPTY 可以工作，但需要单独实现——视为未来工作。仪表板的其余部分原生工作——只有那个标签显示“为此功能请使用 WSL2”的横幅。

Hermes 如何在 Windows 上运行 shell 命令

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 或 PATH 上的任何 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 zip，请确保选择非 busybox 变体（MinGit-*-64-bit.zip，而不是 MinGit-*-busybox*.zip）——busybox 构建提供 ash 而不是 bash，并且大多数 coreutils 缺失。

Windows 上的 UTF-8 控制台

Python 在 Windows 上的默认 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）早期被调用。它：

1. 通过 kernel32.SetConsoleCP / SetConsoleOutputCP 将控制台代码页切换为 CP_UTF8（65001）。
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 会回退到传统的 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。记事本随每个 Windows 安装一起提供，并作为阻塞编辑器工作——subprocess.call(["notepad", file]) 会阻塞直到窗口关闭。

用户覆盖仍然优先（它们在 setdefault 之前被检查）：

VS Code 上的 --wait 标志至关重要——没有它，编辑器会立即返回，Hermes 会得到一个空白缓冲区。

在你的 PowerShell 配置文件中永久设置它：

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

或者作为系统设置中的用户环境变量，以便每个新 shell 都能获取它。

CLI 中的 Ctrl+Enter 换行

Windows 终端将 Ctrl+Enter 作为专用键序列传递。Hermes 将其绑定为“插入换行”，这样你就可以在 CLI 中编写多行提示，而无需回退到 Esc 然后 Enter。在 Windows 终端、VS Code 集成终端以及任何支持 VT 转义序列的现代 Windows 控制台主机中工作。

在传统的 cmd.exe 控制台中，Ctrl+Enter 会退化为普通的 Enter——请改用 Esc Enter，或者升级到 Windows 终端（它是免费的，并且在 Windows 11 上默认安装）。

在 Windows 登录时运行网关

hermes gateway install 在 Windows 上使用 计划任务，并带有启动文件夹回退——无需管理员权限。

安装

hermes gateway install

幕后发生的事情：

1. schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway——注册一个任务，该任务在你登录时以标准（非提升）权限运行。没有 UAC 提示。
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        # 优雅的 SIGTERM 等效（通过 psutil 的 TerminateProcess）
hermes gateway restart
hermes gateway uninstall   # 删除 schtasks 条目、启动快捷方式、pid 文件

hermes gateway status 是幂等的——连续调用一千次也永远不会意外杀死网关。（在 PR #21561 之前，它通过 os.kill(pid, 0) 在 C 级别与 CTRL_C_EVENT 冲突而静默地这样做——如果你关心这个故事，请参阅下面的“进程管理内部”部分。）

为什么不是 Windows 服务？

服务需要管理员权限才能安装，并将网关的生命周期绑定到机器启动，而不是用户登录。典型的 Hermes 用户想要：登录 → 网关可用，注销 → 网关消失。计划任务正好做到这一点，无需提升权限。如果你真的想要一个服务，请手动使用 nssm 或 sc create——但你可能不需要。

数据布局

在原生 Windows 上，安装程序设置 HERMES_HOME=%LOCALAPPDATA%\hermes，因此你的数据和可丢弃的安装位于相同的 %LOCALAPPDATA%\hermes 根目录下：安装/运行时是 hermes-agent\、git\、node\ 和 bin\ 子目录，而你的数据文件直接位于 %LOCALAPPDATA%\hermes 中。重新安装只会替换 hermes-agent\ 检出，因此你的数据会保留——但由于两者共享一个根目录，不要 Remove-Item -Recurse %LOCALAPPDATA%\hermes 如果你想保留数据；而是删除 hermes-agent\ 子目录。你的数据目录在结构上与 Linux 的 ~/.hermes 相同，因此你可以在机器之间镜像它。

覆盖 HERMES_HOME： 设置环境变量指向不同的数据目录（例如 %USERPROFILE%\.hermes 以匹配 Linux/WSL 布局）。与 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\hermes-agent\venv\Scripts 添加到你的用户 PATH。现有终端不会拾取此更改——安装后打开一个新的 PowerShell 窗口（或 Windows 终端标签页）。关闭并重新打开，不要手动 $env:PATH += …，除非你知道自己在做什么。

验证：

Get-Command hermes        # 应打印 C:\Users\<you>\AppData\Local\hermes\hermes-agent\venv\Scripts\hermes.exe
hermes --version

环境变量

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

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

不要将秘密放在用户环境变量中，除非你特别希望每个 Windows 进程都能看到它们（这不是你想要的）。

Windows 特定的环境变量

这些仅影响原生 Windows 安装：

卸载

从 PowerShell：

hermes uninstall

这是干净的路径——删除 schtasks 条目、启动文件夹快捷方式、hermes.cmd 填充，删除 %LOCALAPPDATA%\hermes\hermes-agent\，并修剪用户 PATH。它保留 %LOCALAPPDATA%\hermes\ 的其余部分（你的配置、认证、技能、会话、日志），以防你重新安装。

要彻底清除所有内容：

hermes uninstall
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"
## 如果你曾经使用过，也删除旧的 CLI/WSL 数据目录：
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"

hermes uninstall CLI 子命令还处理 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 年以来一直开放。它不会被修复，因为更改它会破坏依赖当前行为的脚本。

后果：任何在 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——它合并了 schtasks 条目、启动文件夹快捷方式（如果使用）和实时 PID。如果 schtasks 已注册但未运行，组策略可能正在阻止 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，则删除系统安装。

中文 / 日文 / 阿拉伯文字符在 CLI 中显示为 ?。 UTF-8 stdio 填充未激活。检查 HERMES_DISABLE_WINDOWS_UTF8 是否未设置（Get-ChildItem env:HERMES_DISABLE_WINDOWS_UTF8）。如果它为空并且你仍然看到 ?，则控制台主机（非常旧的 cmd.exe）可能根本不支持 UTF-8——切换到 Windows 终端。

网关无法发送 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 子命令。
• 常见问题——常见的非 Windows 特定问题。
• 消息网关——在 Windows 上运行 Telegram/Discord/Slack。