词元之母TOK.MOM - 平台充值汇率 1:1 即 1 人民币充值到账 1 美元,支持一个 Key 调用近 600+ 海内外模型,限时特价模型低至 1 折,欢迎上岸!
fork 语义、Linux 风格文件监视器等),请参阅 Windows(WSL2)指南。两者可以干净共存:原生数据存放在 %LOCALAPPDATA%\hermes,WSL 数据存放在 ~/.hermes。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| 参数 | 默认值 | 用途 |
|---|---|---|
-Branch | main | 克隆指定分支(用于测试 PR) |
-Commit | 未设置 | 将安装固定到指定 commit SHA(覆盖 -Branch) |
-Tag | 未设置 | 将安装固定到指定 git tag(如 v0.14.0) |
-NoVenv | 关闭 | 跳过 venv 创建(高级用法——由你自行管理 Python) |
-SkipSetup | 关闭 | 跳过安装后的 hermes setup 向导 |
-HermesHome | %LOCALAPPDATA%\hermes | 覆盖数据目录 |
-InstallDir | %LOCALAPPDATA%\hermes\hermes-agent | 覆盖代码存放位置 |
install.ps1 内容中的 BOM,因此 HTTP 传输中携带的 UTF-8 BOM 不再会破坏 [scriptblock]::Create((irm ...)) 形式。.exe 而非打开 PowerShell,可以使用它。下载 Hermes Desktop,运行安装程序,首次启动时 GUI 会在后台调用 install.ps1 来配置 Python(通过 uv)、Node、PortableGit 以及下文描述的其余依赖引导流程。首次运行后,桌面应用与 PowerShell 安装的 hermes CLI 共享同一个 %LOCALAPPDATA%\hermes\hermes-agent 安装目录和 %USERPROFILE%\.hermes 数据目录——可以在 GUI 和 CLI 之间自由切换。dep_ensure)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 <dep>)。非交互式运行(gateway、cron、无头桌面启动)会跳过提示,并直接给出清晰的 this feature needs <dep> 错误。uv — Astral 的快速 Python 管理器。安装到 %USERPROFILE%\.local\bin。uv 安装 Python 3.11。无需预先安装 Python。%LOCALAPPDATA%\hermes\node)。用于浏览器工具和 WhatsApp 桥接。git 已在 PATH 中,安装程序直接使用;否则从官方 git-for-windows 发布版下载精简的自包含 PortableGit(约 45 MB)到 %LOCALAPPDATA%\hermes\git。无需管理员权限,不写入 Windows 安装程序注册表,不干扰系统上的其他任何内容。%LOCALAPPDATA%\hermes\hermes-agent 并在其中创建 virtualenv。uv pip install — 先尝试 .[all],如果 git+https 依赖在 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 跳过。hermes setup --portal 完成配置。| 功能 | 原生 Windows | WSL2 |
|---|---|---|
CLI(hermes chat、hermes setup、hermes gateway 等) | ✓ | ✓ |
交互式 TUI(hermes --tui) | ✓ | ✓ |
| 消息 gateway(Telegram、Discord、Slack、WhatsApp,15+ 平台) | ✓ | ✓ |
| Cron 调度器 | ✓ | ✓ |
| 浏览器工具(通过 Node 驱动 Chromium) | ✓ | ✓ |
| MCP 服务器(stdio 和 HTTP) | ✓ | ✓ |
| 本地 Ollama / LM Studio / llama-server | ✓ | ✓(通过 WSL 网络) |
| Web dashboard(会话、任务、指标、配置) | ✓ | ✓ |
Dashboard /chat 内嵌终端面板 | ✗(需要 POSIX PTY) | ✓ |
| 登录时自动启动 | ✓(schtasks) | ✓(systemd) |
/chat 标签页通过 POSIX PTY(ptyprocess)内嵌了真实终端。原生 Windows 没有等效的原语;Python 的 pywinpty / Windows ConPTY 可以实现,但需要单独的实现——视为未来工作。dashboard 的其余部分均可原生运行——只有该标签页会显示"请使用 WSL2"的提示横幅。bash.exe 的解析顺序:HERMES_GIT_BASH_PATH 环境变量,优先使用。%LOCALAPPDATA%\hermes\git\usr\bin\bash.exe(安装程序管理的 PortableGit)。%LOCALAPPDATA%\hermes\git\bin\bash.exe(旧版 Git-for-Windows 布局)。%ProgramFiles%\Git\bin\bash.exe 等)。bash.exe 作为最后手段。HERMES_GIT_BASH_PATH,使新 PowerShell 会话无需重新发现。如果你想让 Hermes 使用特定的 bash——例如系统 Git Bash 或通过符号链接的 WSL bash——可以覆盖此变量。usr\bin\bash.exe,而非 bin\bash.exe。Hermes 会同时检查两个路径。如果你手动解压 MinGit zip,请确保选择非 busybox 变体(MinGit-*-64-bit.zip,而非 MinGit-*-busybox*.zip)——busybox 构建附带的是 ash 而非 bash,且大多数 coreutils 工具缺失 。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。setdefault 设置 PYTHONIOENCODING=utf-8 和 PYTHONUTF8=1(用户显式设置的值优先),使子 Python 进程继承 UTF-8。EDITOR 和 VISUAL 均未设置,则设置 EDITOR=notepad(详见下方编辑器章节)。HERMES_DISABLE_WINDOWS_UTF8=1 可回退到旧版 cp1252 stdio 路径。用于排查编码 bug;正常使用中不建议设置。Ctrl-X Ctrl-E、/edit)Ctrl-X Ctrl-E 或输入 /edit 会静默无响应。prompt_toolkit 有一个硬编码的 POSIX 绝对路径回退列表(/usr/bin/nano、/usr/bin/pico、/usr/bin/vi 等),在 Windows 上永远无法解析——即使安装了完整的 Git for Windows 也不行。EDITOR=notepad 设为默认值。Notepad 随每个 Windows 安装附带,可作为阻塞式编辑器使用——subprocess.call(["notepad", file]) 会阻塞直到窗口关闭。| 编辑器 | 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" |
--wait 标志至关重要——没有它,编辑器会立即返回,Hermes 收到的是空缓冲区。# In $PROFILE
$env:EDITOR = "code --wait"Ctrl+Enter 换行Ctrl+Enter 作为独立按键序列传递。Hermes 将其绑定为"插入换行",使你可以在 CLI 中编写多行 prompt(提示词)而无需回退到 Esc-然后-Enter。适用于 Windows Terminal、VS Code 集成终端以及任何支持 VT 转义序列的现代 Windows 控制台宿主。cmd.exe 控制台上,Ctrl+Enter 会折叠为普通 Enter——请改用 Esc Enter,或升级到 Windows Terminal(免费,Windows 11 默认已安装)。hermes gateway install 使用计划任务,并以 Startup 文件夹作为回退——无需管理员权限。hermes gateway installschtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway — 注册一个在你登录时以标准(非提升)权限运行的任务。无 UAC 提示。%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup 中写入 start /min cmd.exe /d /c <wrapper> 快捷方式。效果相同,稍显粗糙。pythonw.exe 以分离方式生成 gateway——而非 python.exe。pythonw.exe 没有附加控制台,可免疫来自同一进程组中兄弟进程的 CTRL_C_EVENT 广播(这是一个真实问题,曾导致在同一进程组中 Ctrl+C 任何进程时 gateway 被杀死)。DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB。hermes gateway status # 合并视图:schtasks + Startup 文件夹 + 运行中的 PID
hermes gateway start # 立即启动计划任务
hermes gateway stop # 等效于优雅的 SIGTERM(通过 psutil 调用 TerminateProcess)
hermes gateway restart
hermes gateway uninstall # 移除 schtasks 条目、Startup 快捷方式、pid 文件hermes gateway status 是幂等的——调用一千次也不会意外杀死 gateway。(PR #21561 之前它会静默地这样做,原因是 os.kill(pid, 0) 在 C 层与 CTRL_C_EVENT 发生碰撞——如果你想了解来龙去脉,请参阅下方"进程管理内部机制"。)nssm 或 sc create——但你可能并不需要。| 路径 | 内容 |
|---|---|
%LOCALAPPDATA%\hermes\hermes-agent\ | Git 检出 + venv。可安全执行 Remove-Item -Recurse 后重新安装。 |
%LOCALAPPDATA%\hermes\git\ | PortableGit(仅在安装程序配置时存在)。 |
%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 上:agent-browser 添加到 PATH。shutil.which("agent-browser", path=...) 会自动找到 .cmd 垫片——CreateProcessW 无法执行无扩展名的 shebang 脚本,因此 Hermes 始终解析到 .CMD 包装器。不要手动调用 shebang 脚本;始终通过 .cmd 调用。npx playwright install chromium)。如果安装失败,hermes doctor 会给出修复提示。[Environment]::SetEnvironmentVariable 将 %LOCALAPPDATA%\hermes\bin 添加到你的用户 PATH。已打开的终端不会获取此更新——安装完成后请打开新的 PowerShell 窗口(或 Windows Terminal 标签页)。关闭并重新打开,不要手动执行 $env:PATH += …,除非你清楚自己在做什么。Get-Command hermes # 应输出 C:\Users\<you>\AppData\Local\hermes\bin\hermes.cmd
hermes --version$env:X(进程作用域)和用户环境变量(永久,在系统属性 → 环境变量中设置)。将 API key 放在 %USERPROFILE%\.hermes\.env 中是标准做法——与 Linux 相同:OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=...| 变量 | 效果 |
|---|---|
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。 |
hermes uninstallhermes.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 子命令还能处理 schtasks 条目以不同任务名注册的情况(旧版安装)——它通过安装路径而非硬编码任务名来搜索。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 已将所有此类位置(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 — <reason> 标记。hermes: command not found。%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 的纯 UTF-8。hermes gateway status——它会合并 schtasks 条目、Startup 文件夹快捷方式(如有)和运行中的 PID。如果 schtasks 已注册但未运行,组策略可能阻止了 ONLOGON 触发器。运行 schtasks /Query /TN HermesGateway /V /FO LIST 查看任务失败原因,或通过卸载后使用 HERMES_GATEWAY_FORCE_STARTUP=1 重新安装来回退到 Startup 文件夹路径。$env:EDITOR 后 /edit 仍然无响应。echo $env:EDITOR 验证。hermes doctor——它会检测缺失的 Chromium 并打印修复所需的确切 npx playwright install chromium 命令。agent-browser 报奇怪的 Node 版本错误。%LOCALAPPDATA%\hermes\node 配置了 Node 22,但你的 PATH 中可能有更靠前的旧版系统 Node 18。要么将 Hermes 的 node 目录移到 PATH 前面,要么如果你不在其他地方使用 Node,删除系统安装。?。HERMES_DISABLE_WINDOWS_UTF8 是否未设置(Get-ChildItem env:HERMES_DISABLE_WINDOWS_UTF8)。如果该变量为空但仍然看到 ?,控制台宿主(非常旧的 cmd.exe)可能完全不支持 UTF-8——请切换到 Windows Terminal。BadRequest: payload contains invalid characters"。str(Path(...))。git pull 后出现"在我另一台机器上能用"的编码怪象。utf-8-sig,但折叠 YAML 标量(description: >)内部的 BOM 会静默破坏 YAML 解析。请将文件重新保存为不带 BOM 的纯 UTF-8。hermes 子命令。