怎么跑起来
在 Windows 与 WSL 上装 Hermes Agent
在 Windows 上,安装就是一条命令:uv tool install hermes-agent。它留下三个可执行文件和一个 116 MB 的工具目录(随时可删),而真正删不掉的状态在另一个地方——%LOCALAPPDATA%\hermes。macOS 我们没测,这一页就写「没测」。
Hermes Agent 有不止一条安装路径,我们只跑了其中一条。这一页写的就是 2026-11-19 跑的那条:Windows 11 上 uv tool install hermes-agent,装进一个用完就删的工具目录,所以整件事可以原样撤销。
它花了一条命令,产出三个可执行文件和一个 116 MB 的工具目录,并且没有碰机器上已经装好的那一份。下面每一段都是从那次会话里抄出来的。
跑之前得有什么
- Python 3.11–3.13。 发布的包声明了
<3.14,>=3.11。系统里的解释器不在这个范围时,uv 会自己拉一个——这也是它「自带环境」的主要成本。 - 约 120 MB 磁盘,只算工具目录;装完实测 116 MB。
- 一个 uv 能写的路径。 Windows 上默认在用户目录下,整个过程不需要管理员权限。
安装命令,以及它当时吐出来的东西
$ uv tool install hermes-agent
Resolved 64 packages in 1.21s
+ pydantic==2.13.4
+ pywinpty==2.0.15
+ rich==14.3.3
+ uvicorn==0.54.0
+ websockets==15.0.1
+ ...
Installed 3 executables: hermes, hermes-acp, hermes-agent
warning: `...\bin` is not on your PATH. To use installed tools, run
$env:PATH = "...\bin;$env:PATH" or `uv tool update-shell`.
依赖有六十多行,上面只挑了几个:一个 HTTP 栈、一个 PTY 层、一个终端渲染器。没有稀奇东西,不需要显卡。
最后两行要先看。 装出来的是三个可执行文件而不是一个;而且那个 bin 目录默认不在 PATH 里,除非你跑 uv tool update-shell 或者用全路径调。大多数人第一次撞的就是这条 warning——它不是安装失败。
配任何东西之前,先验证
$ hermes --version
Hermes Agent v0.19.0 (2026.7.20) · upstream 0d5fdd60 · local 18a76be1 (+26736 carried commits)
Install directory: ...\tools\hermes-agent\Lib\site-packages
Install method: pip
Python: 3.11.15
OpenAI SDK: 2.24.0
两行值得读两遍:
- Install directory——这是代码所在,位置由你的工具管理器决定,不是你记笔记的地方。
- Install method: pip——明明是用 uv 装的,它仍然报 pip。这是打包方式在说话,不是错误;两种情况装下去都是标准的 Python 发行包。
如果提示命令找不到,回到上面那条 PATH warning。如果命令能跑但什么都不打印,那是版本没实现 --version;我们这份是 0.19.0,实现了。
它装到哪,和你的状态存在哪(两回事)
这张表比任何参数都重要:
| 东西 | 位置 | 能删吗 |
|---|---|---|
| 代码 + Python 环境 | uv 的工具目录(uv tool dir 会打印;Windows 默认 %APPDATA%\uv\tools) |
能——重装就回来了 |
状态:config.yaml、skills、cron、profiles |
%LOCALAPPDATA%\hermes |
不能——这是你要备份的部分 |
重装便宜,因为它只替换左列。删掉右列才是贵的那个错,而那个目录不会告诉你哪些文件是承重的——那份读法在安装目录那一页。
有一点我们不写结论:%LOCALAPPDATA%\hermes 到底是首次运行建的还是首次配置建的,我们答不上来,因为测这次之前它就已经在机器上了。装完先去看一眼这个目录在不在,别假定。
Windows 上断掉的三个地方
三个都在装完之后出现——你想用脚本驱动它、而不是手打的时候。
- git-bash 会替你翻译路径,直到它不翻译。
git -C /d/project rev-parse HEAD在 git-bash 里能跑,传给原生程序就变成fatal: cannot change to '/d/project': No such file or directory。换成D:/project。交给 agent 的 shell 工具的任何路径同理。 - 一个裸换行不会提交交互式提示。 走 PTY 时发
\n会让子进程一直等,它要的行结束符是\r。我们在这个坑上坐了很久——如果你打完字提示符像冻住了,就是这个原因。
WSL 与远程后端
WSL 里安装本身一样,变的是桌面端怎么找到它。桌面客户端不会自己发现后端——它只读一个文件,而失败时的表现跟原因完全不像。两段答案在桌面端接 WSL 后端:connection.json 决定什么,以及那个「看着像后端坏了」的停着的发行版。
我们没测什么
- macOS。 没装过。你在 macOS 上遇到什么,这一页答不了。
- Android / Termux。 没设备,所以没这页——排在前面的那些站是真跑过,我们没有。
- 一键 shell 安装脚本。 如果存在,我们没用过。安装目录那一页的目录读法跟用哪条路径装进来无关。
pip install装进系统 Python。 同一个 wheel,不同解析器——说得通,但没量。
装完到底装了什么:六个数字
一张表,全部来自同一次会话,每一行都能用右边的命令复算:
| 量的东西 | 实测值 | 怎么量的 |
|---|---|---|
| 解析出的依赖包 | 64 个 | uv tool install 输出的首行 |
| 工具目录占盘 | 116 MB | 装完对目录跑 du -sh |
| 装出的可执行文件 | 3 个(hermes、hermes-acp、hermes-agent) |
uv 的汇总行 + ls bin 目录 |
| 二进制自报版本 | 0.19.0(构建 2026.7.20) | hermes --version |
| 实际使用的 Python | 3.11.15 | hermes --version |
| 卸载后 bin 里剩下的文件 | 0 个 | uv tool uninstall 后 ls -A |
三条命令重跑一遍,形状应该一样;体积随版本变,所以版本写进表里而不是写进句子里。安装耗时我们没测——那测的是我们的网络,不是安装器。
怎么知道它真的有效
三条检查,按顺序,每条失败的样子都不一样:
$ uv tool list
hermes-agent v0.19.0
- hermes
- hermes-acp
- hermes-agent
$ hermes --version
Hermes Agent v0.19.0 ...
$ ls "$LOCALAPPDATA/hermes"
config.yaml skills cron profiles ...
uv tool list 空 ⇒ 安装没完成。列出了包但 hermes 找不到 ⇒ 是上面那条 PATH。两样都对但目录不存在 ⇒ 你有代码、还没配置过,这是一个状态,不是错误。
怎么回滚
$ uv tool uninstall hermes-agent
Uninstalled 3 executables: hermes, hermes-acp, hermes-agent
测完我们就是这么收的:bin 目录清空,工具目录消失。%LOCALAPPDATA%\hermes 下的状态在卸载后照旧存在——这正是重点——所以只在你读过里面是什么之后,再手动删它。
如果你是用别的方式装的,回滚是同一句话换个动词:删掉包,留住状态目录。
相关档案
常见问题
不用 uv,直接 pip 装行不行?
大概率行——wheel 就挂在 PyPI 上,`pip install hermes-agent` 装进 venv 应该得到同样三个可执行文件。但我们没跑这条路,所以不写成结论;下面只有 uv 那条是实测的。
为什么装了三个可执行文件?
包里声明了三个入口点:`hermes`(你会用的 CLI)、`hermes-agent`、以及给 ACP 适配器用的 `hermes-acp`。我们只跑了 `hermes`。
Python 环境在哪?
在 uv 建的工具目录里。最快的找法是跑 `hermes --version`,它会打印自己实际在用的 site-packages 路径。
来源
本文最后一次核验:2026-11-19 · 在一次性工具目录里装 → 跑 --version → 卸载,全程留了原始输出;116 MB 是装完后 du 实测;macOS 与 Android 未测