原生 Windows 支持目前处于早期 beta阶段。它可以安装、运行并且通过了我们的 Windows-footgun lint 检查但尚未像 Linux/macOS/WSL2 路径那样经过大规模实际测试。预计会存在一些粗糙边缘——尤其是在子进程处理、路径怪癖和非 ASCII 控制台输出方面。遇到问题时请附上复现步骤提交 issue。如果你现在想要一个经过实战检验的配置请改用 WSL2 下的 Linux/macOS 安装程序。Hermes 可以在 Windows 10 和 Windows 11 上原生运行——无需 WSL、无需 Cygwin、无需 Docker。本页是深度指南哪些功能原生可用哪些只有 WSL 才支持安装程序实际做了什么以及你可能需要调整的 Windows 专属旋钮。如果你只想安装首页或安装页面上的一行命令就足够了。当遇到意外情况时再回到这里查看。想要使用 WSL如果你更喜欢真正的 POSIX 环境用于仪表板的嵌入式终端、fork语义、Linux 风格的文件监视器等请参阅WindowsWSL2指南。两者可以干净地共存原生数据位于%LOCALAPPDATA%\hermesWSL 数据位于~/.hermes。快速安装打开PowerShell或 Windows Terminal并运行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参数默认值用途-Branchmain克隆特定分支用于测试 PR 时有用-Commit未设置固定安装到特定的提交 SHA覆盖-Branch-Tag未设置固定安装到特定的 git 标签例如v0.14.0-NoVenv关闭跳过虚拟环境创建高级——你自行管理 Python-SkipSetup关闭跳过安装后的hermes setup向导-HermesHome%LOCALAPPDATA%\hermes覆盖数据目录-InstallDir%LOCALAPPDATA%\hermes\hermes-agent覆盖代码位置安装程序会自动重试不稳定的 git 拉取操作并去除任何下载的install.ps1负载中的 BOM这样通过 HTTP 传输时产生的 UTF-8 BOM 就不会再破坏[scriptblock]::Create((irm ...))形式。桌面安装程序备选此外还提供了一个轻量级的 GUI 安装程序——如果你更愿意双击.exe而不是打开 PowerShell这会很方便。下载 Hermes Desktop运行安装程序首次启动时 GUI 会在后台调用install.ps1来准备 Python通过uv、Node、PortableGit 以及下面描述的其他依赖引导程序。首次运行后桌面应用和通过 PowerShell 安装的hermesCLI 共享同一个%LOCALAPPDATA%\hermes\hermes-agent安装目录和%USERPROFILE%\.hermes数据目录——你可以在 GUI 和 CLI 之间自由切换。 当你想要使用熟悉的 Windows 安装体验或者将 Hermes 交给非开发者使用时请使用桌面安装程序如果你已经在终端中请使用 PowerShell 一行命令。依赖引导dep_ensure首次启动时以及在检测到缺少工具时按需运行Hermes 会运行一个小型的 Python 引导脚本——hermes_cli/dep_ensure.py——它会检查并延迟安装所需的非 Python 依赖项。在 Windows 上相关的依赖项如下依赖项Hermes 为什么需要它PortableGit为终端工具提供bash.exe并为会话内的克隆操作提供git。在安装时预置不由dep_ensure处理。Node.js 22浏览器工具agent-browser、TUI 的 Web 桥接以及 WhatsApp 桥接所需。ffmpeg用于 TTS / 语音消息的音频格式转换。ripgrep快速文件搜索——如果不可用则回退到grep。npm 包agent-browser、Playwright Chromium 以及每个工具集所需的 Node 依赖项在首次使用浏览器工具时一次性安装。每个依赖项都有一个shutil.which(...)风格的检查如果某个二进制文件缺失且运行环境为交互式dep_ensure会提供安装选项实际安装逻辑委托给scripts\install.ps1 -ensure lt;depgt;。非交互式运行网关、定时任务、无头桌面启动会跳过提示并给出清晰的错误信息“此功能需要dep”。安装程序实际执行的操作自上而下按顺序进行引导uv—— Astral 的快速 Python 管理器。安装到%USERPROFILE%\.local\bin。通过uv安装 Python 3.11。无需已有 Python。安装 Node.js 22如果可用则使用 winget否则在%LOCALAPPDATA%\hermes\node下解压便携版 Node tarball。用于浏览器工具和 WhatsApp 桥接。安装便携版 Git—— 如果git已在 PATH 中安装程序会直接使用它否则会从官方的git-for-windows发布版下载一个精简的自包含PortableGit约 45 MB到%LOCALAPPDATA%\hermes\git。无需管理员权限不写入 Windows 安装程序注册表不会干扰系统上的其他任何东西。克隆仓库到%LOCALAPPDATA%\hermes\hermes-agent并在其中创建虚拟环境。分层uv pip install—— 首先尝试.[all]如果某个githttps依赖因 GitHub 限速而失败则逐步回退到较小的集合[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可跳过。功能矩阵除了仪表盘的嵌入式终端面板外所有功能均能在 Windows 上原生运行。功能原生 WindowsWSL2CLIhermes chat、hermes setup、hermes gateway等✓✓交互式 TUIhermes --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 PTYptyprocess嵌入了一个真实终端。原生 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等路径。最后尝试 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 cant 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_UTF865001。将sys.stdout/sys.stderr/sys.stdin重新配置为 UTF-8并设置errorsreplace。设置PYTHONIOENCODINGutf-8和PYTHONUTF81通过setdefault因此用户显式设置的值会优先让子 Python 进程继承 UTF-8。如果既未设置EDITOR也未设置VISUAL则将EDITOR设为notepad参见下面的“编辑器”章节。 幂等。在非 Windows 系统上无操作。选择退出环境变量HERMES_DISABLE_WINDOWS_UTF81会回退到传统的 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 垫片现在默认设置EDITORnotepad。记事本随每个 Windows 安装附带并且可以作为阻塞编辑器工作——subprocess.call([notepad, file])会阻塞直到窗口关闭。用户覆盖仍然优先它们会在设置默认值之前被检查编辑器PowerShell 命令VS Code$env:EDITOR code --waitNotepad$env:EDITOR C:\Program Files\Notepad\notepad.exe -multiInst -nosessionNeovim$env:EDITOR nvimHelix$env:EDITOR hxVS Code 的--wait标志至关重要——没有它编辑器会立即返回Hermes 会得到一个空缓冲区。在您的 PowerShell 配置文件中永久设置# In $PROFILE $env:EDITOR code --wait或者作为系统设置中的用户环境变量以便每个新的 shell 都能读取它。CLI 中的CtrlEnter换行Windows Terminal 将CtrlEnter作为专用键序列传递。Hermes 将其绑定为“插入换行”这样您就可以在 CLI 中编写多行提示而无需退回到先按Esc再按Enter。适用于 Windows Terminal、VS Code 集成终端以及任何支持 VT 转义序列的现代 Windows 控制台主机。在传统的cmd.exe控制台中CtrlEnter等同于普通Enter——请改用Esc Enter或升级到 Windows Terminal它免费且在 Windows 11 上默认安装。在 Windows 登录时运行网关在 Windows 上hermes gateway install使用计划任务并回退到启动文件夹——无需管理员权限。Installhermes gateway install幕后发生了什么schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway— 注册一个在登录时以标准非提权权限运行的任务。不会弹出 UAC 提示。如果 schtasks 被组策略阻止则回退到将start /min cmd.exe /d /c lt;wrappergt;快捷方式写入%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup。效果相同但略微粗糙。通过pythonw.exe分离式启动网关——而不是python.exe。pythonw.exe没有附加控制台这使其免受来自兄弟进程的CTRL_C_EVENT广播影响这是一个真实问题曾经当你在同一进程组中 CtrlC 任何内容时都会杀死网关。启动时使用的标志DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB。Managehermes gateway status # Merged view: schtasks Startup folder running PID hermes gateway start # Starts the scheduled task now hermes gateway stop # Graceful SIGTERM equivalent (TerminateProcess via psutil) hermes gateway restart hermes gateway uninstall # Removes schtasks entry, Startup shortcut, pid filehermes gateway status是幂等的——连续调用一千次也不会意外杀死网关。在 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\便携版 Git仅当安装程序配置了它时。%LOCALAPPDATA%\hermes\node\便携版 Node.js仅当安装程序配置了它时。%LOCALAPPDATA%\hermes\bin\hermes.cmd存根已添加到用户 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_KEYsk-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 垫片回退使用区域设置代码页。用于排查编码相关 Bug。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\hermeshermes uninstallCLI 子命令也能处理计划任务条目以不同任务名称注册的情况老版本安装—— 它通过安装路径而非硬编码的任务名称进行搜索。进程管理内部机制以下为背景资料 —— 除非你在调试“自我杀死”这类诡异问题否则可跳过。在 Linux 和 macOS 上POSIX 习惯用法os.kill(pid, 0)是一个无操作权限检查“该 PID 是否存活且我能向其发送信号” 在 Windows 上Python 的os.kill将sig0映射为CTRL_C_EVENT—— 它们在整数值 0 处冲突 —— 并通过GenerateConsoleCtrlEvent(0, pid)路由该函数会向包含目标 PID 的整个控制台进程组广播 CtrlC。这是 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 footguns (blocking)检查失败除非该行带有# windows-footgun: ok — lt;reasongt;标记。常见陷阱安装后立即出现hermes: command not found。打开一个新的 PowerShell 窗口。安装程序已将%LOCALAPPDATA%\hermes\bin添加到用户 PATH但已存在的 shell 需要重启才能生效。在此期间你可以运行 $env:LOCALAPPDATA\hermes\bin\hermes.cmd。WinError 193: %1 不是有效的 Win32 应用程序运行工具时出现你遇到了一个绕过.cmd垫片的 shebang 脚本调用。Hermes 通过shutil.which(cmd, pathlocal_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 的文件。重启后 Gateway 无法保持运行。检查hermes gateway status——它会合并 schtasks 条目、启动文件夹快捷方式如果使用以及实时 PID。如果 schtasks 已注册但未运行可能是组策略阻止了ONLOGON触发器。运行schtasks /Query /TN HermesGateway /V /FO LIST查看任务的失败原因或者通过设置HERMES_GATEWAY_FORCE_STARTUP1卸载并重新安装回退到启动文件夹路径。设置$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 Terminal。Gateway 无法发送 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。
Hermes 如何在 Windows 原生安装
发布时间：2026/5/25 23:55:09
原生 Windows 支持目前处于早期 beta阶段。它可以安装、运行并且通过了我们的 Windows-footgun lint 检查但尚未像 Linux/macOS/WSL2 路径那样经过大规模实际测试。预计会存在一些粗糙边缘——尤其是在子进程处理、路径怪癖和非 ASCII 控制台输出方面。遇到问题时请附上复现步骤提交 issue。如果你现在想要一个经过实战检验的配置请改用 WSL2 下的 Linux/macOS 安装程序。Hermes 可以在 Windows 10 和 Windows 11 上原生运行——无需 WSL、无需 Cygwin、无需 Docker。本页是深度指南哪些功能原生可用哪些只有 WSL 才支持安装程序实际做了什么以及你可能需要调整的 Windows 专属旋钮。如果你只想安装首页或安装页面上的一行命令就足够了。当遇到意外情况时再回到这里查看。想要使用 WSL如果你更喜欢真正的 POSIX 环境用于仪表板的嵌入式终端、fork语义、Linux 风格的文件监视器等请参阅WindowsWSL2指南。两者可以干净地共存原生数据位于%LOCALAPPDATA%\hermesWSL 数据位于~/.hermes。快速安装打开PowerShell或 Windows Terminal并运行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参数默认值用途-Branchmain克隆特定分支用于测试 PR 时有用-Commit未设置固定安装到特定的提交 SHA覆盖-Branch-Tag未设置固定安装到特定的 git 标签例如v0.14.0-NoVenv关闭跳过虚拟环境创建高级——你自行管理 Python-SkipSetup关闭跳过安装后的hermes setup向导-HermesHome%LOCALAPPDATA%\hermes覆盖数据目录-InstallDir%LOCALAPPDATA%\hermes\hermes-agent覆盖代码位置安装程序会自动重试不稳定的 git 拉取操作并去除任何下载的install.ps1负载中的 BOM这样通过 HTTP 传输时产生的 UTF-8 BOM 就不会再破坏[scriptblock]::Create((irm ...))形式。桌面安装程序备选此外还提供了一个轻量级的 GUI 安装程序——如果你更愿意双击.exe而不是打开 PowerShell这会很方便。下载 Hermes Desktop运行安装程序首次启动时 GUI 会在后台调用install.ps1来准备 Python通过uv、Node、PortableGit 以及下面描述的其他依赖引导程序。首次运行后桌面应用和通过 PowerShell 安装的hermesCLI 共享同一个%LOCALAPPDATA%\hermes\hermes-agent安装目录和%USERPROFILE%\.hermes数据目录——你可以在 GUI 和 CLI 之间自由切换。 当你想要使用熟悉的 Windows 安装体验或者将 Hermes 交给非开发者使用时请使用桌面安装程序如果你已经在终端中请使用 PowerShell 一行命令。依赖引导dep_ensure首次启动时以及在检测到缺少工具时按需运行Hermes 会运行一个小型的 Python 引导脚本——hermes_cli/dep_ensure.py——它会检查并延迟安装所需的非 Python 依赖项。在 Windows 上相关的依赖项如下依赖项Hermes 为什么需要它PortableGit为终端工具提供bash.exe并为会话内的克隆操作提供git。在安装时预置不由dep_ensure处理。Node.js 22浏览器工具agent-browser、TUI 的 Web 桥接以及 WhatsApp 桥接所需。ffmpeg用于 TTS / 语音消息的音频格式转换。ripgrep快速文件搜索——如果不可用则回退到grep。npm 包agent-browser、Playwright Chromium 以及每个工具集所需的 Node 依赖项在首次使用浏览器工具时一次性安装。每个依赖项都有一个shutil.which(...)风格的检查如果某个二进制文件缺失且运行环境为交互式dep_ensure会提供安装选项实际安装逻辑委托给scripts\install.ps1 -ensure lt;depgt;。非交互式运行网关、定时任务、无头桌面启动会跳过提示并给出清晰的错误信息“此功能需要dep”。安装程序实际执行的操作自上而下按顺序进行引导uv—— Astral 的快速 Python 管理器。安装到%USERPROFILE%\.local\bin。通过uv安装 Python 3.11。无需已有 Python。安装 Node.js 22如果可用则使用 winget否则在%LOCALAPPDATA%\hermes\node下解压便携版 Node tarball。用于浏览器工具和 WhatsApp 桥接。安装便携版 Git—— 如果git已在 PATH 中安装程序会直接使用它否则会从官方的git-for-windows发布版下载一个精简的自包含PortableGit约 45 MB到%LOCALAPPDATA%\hermes\git。无需管理员权限不写入 Windows 安装程序注册表不会干扰系统上的其他任何东西。克隆仓库到%LOCALAPPDATA%\hermes\hermes-agent并在其中创建虚拟环境。分层uv pip install—— 首先尝试.[all]如果某个githttps依赖因 GitHub 限速而失败则逐步回退到较小的集合[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可跳过。功能矩阵除了仪表盘的嵌入式终端面板外所有功能均能在 Windows 上原生运行。功能原生 WindowsWSL2CLIhermes chat、hermes setup、hermes gateway等✓✓交互式 TUIhermes --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 PTYptyprocess嵌入了一个真实终端。原生 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等路径。最后尝试 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 cant 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_UTF865001。将sys.stdout/sys.stderr/sys.stdin重新配置为 UTF-8并设置errorsreplace。设置PYTHONIOENCODINGutf-8和PYTHONUTF81通过setdefault因此用户显式设置的值会优先让子 Python 进程继承 UTF-8。如果既未设置EDITOR也未设置VISUAL则将EDITOR设为notepad参见下面的“编辑器”章节。 幂等。在非 Windows 系统上无操作。选择退出环境变量HERMES_DISABLE_WINDOWS_UTF81会回退到传统的 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 垫片现在默认设置EDITORnotepad。记事本随每个 Windows 安装附带并且可以作为阻塞编辑器工作——subprocess.call([notepad, file])会阻塞直到窗口关闭。用户覆盖仍然优先它们会在设置默认值之前被检查编辑器PowerShell 命令VS Code$env:EDITOR code --waitNotepad$env:EDITOR C:\Program Files\Notepad\notepad.exe -multiInst -nosessionNeovim$env:EDITOR nvimHelix$env:EDITOR hxVS Code 的--wait标志至关重要——没有它编辑器会立即返回Hermes 会得到一个空缓冲区。在您的 PowerShell 配置文件中永久设置# In $PROFILE $env:EDITOR code --wait或者作为系统设置中的用户环境变量以便每个新的 shell 都能读取它。CLI 中的CtrlEnter换行Windows Terminal 将CtrlEnter作为专用键序列传递。Hermes 将其绑定为“插入换行”这样您就可以在 CLI 中编写多行提示而无需退回到先按Esc再按Enter。适用于 Windows Terminal、VS Code 集成终端以及任何支持 VT 转义序列的现代 Windows 控制台主机。在传统的cmd.exe控制台中CtrlEnter等同于普通Enter——请改用Esc Enter或升级到 Windows Terminal它免费且在 Windows 11 上默认安装。在 Windows 登录时运行网关在 Windows 上hermes gateway install使用计划任务并回退到启动文件夹——无需管理员权限。Installhermes gateway install幕后发生了什么schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway— 注册一个在登录时以标准非提权权限运行的任务。不会弹出 UAC 提示。如果 schtasks 被组策略阻止则回退到将start /min cmd.exe /d /c lt;wrappergt;快捷方式写入%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup。效果相同但略微粗糙。通过pythonw.exe分离式启动网关——而不是python.exe。pythonw.exe没有附加控制台这使其免受来自兄弟进程的CTRL_C_EVENT广播影响这是一个真实问题曾经当你在同一进程组中 CtrlC 任何内容时都会杀死网关。启动时使用的标志DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB。Managehermes gateway status # Merged view: schtasks Startup folder running PID hermes gateway start # Starts the scheduled task now hermes gateway stop # Graceful SIGTERM equivalent (TerminateProcess via psutil) hermes gateway restart hermes gateway uninstall # Removes schtasks entry, Startup shortcut, pid filehermes gateway status是幂等的——连续调用一千次也不会意外杀死网关。在 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\便携版 Git仅当安装程序配置了它时。%LOCALAPPDATA%\hermes\node\便携版 Node.js仅当安装程序配置了它时。%LOCALAPPDATA%\hermes\bin\hermes.cmd存根已添加到用户 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_KEYsk-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 垫片回退使用区域设置代码页。用于排查编码相关 Bug。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\hermeshermes uninstallCLI 子命令也能处理计划任务条目以不同任务名称注册的情况老版本安装—— 它通过安装路径而非硬编码的任务名称进行搜索。进程管理内部机制以下为背景资料 —— 除非你在调试“自我杀死”这类诡异问题否则可跳过。在 Linux 和 macOS 上POSIX 习惯用法os.kill(pid, 0)是一个无操作权限检查“该 PID 是否存活且我能向其发送信号” 在 Windows 上Python 的os.kill将sig0映射为CTRL_C_EVENT—— 它们在整数值 0 处冲突 —— 并通过GenerateConsoleCtrlEvent(0, pid)路由该函数会向包含目标 PID 的整个控制台进程组广播 CtrlC。这是 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 footguns (blocking)检查失败除非该行带有# windows-footgun: ok — lt;reasongt;标记。常见陷阱安装后立即出现hermes: command not found。打开一个新的 PowerShell 窗口。安装程序已将%LOCALAPPDATA%\hermes\bin添加到用户 PATH但已存在的 shell 需要重启才能生效。在此期间你可以运行 $env:LOCALAPPDATA\hermes\bin\hermes.cmd。WinError 193: %1 不是有效的 Win32 应用程序运行工具时出现你遇到了一个绕过.cmd垫片的 shebang 脚本调用。Hermes 通过shutil.which(cmd, pathlocal_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 的文件。重启后 Gateway 无法保持运行。检查hermes gateway status——它会合并 schtasks 条目、启动文件夹快捷方式如果使用以及实时 PID。如果 schtasks 已注册但未运行可能是组策略阻止了ONLOGON触发器。运行schtasks /Query /TN HermesGateway /V /FO LIST查看任务的失败原因或者通过设置HERMES_GATEWAY_FORCE_STARTUP1卸载并重新安装回退到启动文件夹路径。设置$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 Terminal。Gateway 无法发送 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。
