hermes update 升级失败、卡住、升级后报错怎么办

升级前先留一条退路

升级最怕的从来不是失败本身,而是升到一半坏了、又退不回去。所以 hermes update 之前,先记两样东西:

hermes --version
hermes backup

hermes --version 记下当前版本号(输出里括号中的日期就是版本 tag,比如 2026.5.29 对应 v2026.5.29),Project 一行是安装目录,回退时两样都用得上;hermes backup 把 Hermes home 里的配置和数据打成一个 zip,~/.hermes/config.yaml、~/.hermes/.env、会话、技能和记忆都在里面。要分清它管什么:backup 只管数据,不含 Hermes 代码本身,所以它能救回配置和会话,但退不回版本——版本回退靠的是 git,见最后一节。新版 hermes update 升级前自己也会做一次轻量快照;想要一份完整 zip,可以直接用 hermes update --backup。zip 按日期命个名,顺手挪到这台机器以外的地方更稳妥。

卡在下载:多半还是 GitHub 那一跳

hermes update 要从上游拉新版本,国内卡在这一步,和当初装的时候卡 install.sh 是同一类毛病——到 GitHub 这一跳不稳。先给当前终端配上你自己的代理,再重试:

export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890
hermes update

端口换成你本机代理实际的端口。这里有个常被忽略的因果:如果你当初是配了代理或镜像才把 Hermes 装上的,那升级同样需要这套网络条件,别指望裸连能成。判断是不是网络卡死也简单——同一时刻单独 curl 一下 GitHub 上任意一个文件,半天没反应,就先把网络治好,而不是对着 hermes update 反复重跑。

不是卡死:在等网关把手头的活干完

新版(v0.21 起)还有一种看起来像卡住、其实是正常的情况:代码已经拉完,升级停在重启网关这一步,终端每 30 秒打印一次 still draining。这是网关在等进行中的对话、定时任务跑完再重启,免得把长任务拦腰截断,最长等 30 分钟(由 config.yaml 里的 agent.restart_after_turn_timeout 控制)。输出里会列出它在等哪个任务,等它跑完或者手动结束那个任务就会继续。Windows 上还有一种:如果另一个 hermes.exe 正在运行(桌面版的后台、另一个终端里开着的 hermes、或者网关),hermes update 会直接拒绝执行,先把它们关掉再升。

升级后命令报错:先补非 Python 依赖

有一类问题长这样:hermes update 本身跑完了、没报错,但升级后用某些功能时报错,提示找不到 node、ripgrep、ffmpeg 或者浏览器。这不是升级坏了,而是新版本引入或更新了非 Python 依赖,本体升上去了、这些外部依赖没跟着补上。不必整体重装:

hermes doctor
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --ensure node,browser,ripgrep,ffmpeg
hermes status

hermes doctor 逐项列出缺了什么,并给出对应的安装命令;安装脚本的 --ensure 只补指定的依赖,不会重新 clone 仓库、也不会重建环境(Windows 原生安装用 install.ps1 的 -Ensure 参数);补完用 hermes status 看组件总览,确认整体回到就绪状态。旧教程里的 hermes postinstall 在新版已经删除,照着敲会报错。

想看升级到底出了什么岔:翻升级日志

如果升级过程不顺、又说不清卡在哪一步,别凭印象猜。升级的全部输出都会另存一份到升级日志里:

tail -n 200 ~/.hermes/logs/update.log
hermes status

注意 hermes logs 看的是 agent、gateway 这些运行日志,不含升级过程,升级失败要看的是这个 update.log。失败原因、卡在哪个环节往往写得清清楚楚;hermes status 配合着看当前各组件还正不正常。翻日志时只读出问题那几分钟的记录就够,从头读到尾是最浪费时间的走法。

真升坏了:用 git 回到升级前的版本

如果升级后行为明显不对、hermes doctor 一堆报错,按官方文档的回退方式,进安装目录切回旧版本的 tag:

cd ~/.hermes/hermes-agent
git tag --sort=-version:refname | head
git checkout v2026.5.29
uv pip install -e ".[all]"
hermes gateway restart
hermes doctor

cd 的目录换成你 hermes --version 里 Project 那一行;git checkout 后面换成升级前记下的那个版本 tag;uv pip install 把依赖装回与旧版本匹配的状态;有网关在跑就重启一下,最后用 hermes doctor 确认恢复正常。如果数据也被改坏了,再用 hermes import <zip 路径> 从升级前的 backup 恢复配置和会话。另外新版升级时如果拉下来的代码连语法检查都过不了,hermes update 会自己回滚到升级前的提交,这种情况等上游修好再升即可。回退之后别立刻原样再升一遍——先搞清上次为什么坏:是网络半路断了,还是依赖没补齐?把根因解决了再升,否则只是把同一个坑重踩一次。

别动不动就 uninstall 重装

升级一出问题,很多人第一反应是 hermes uninstall 卸掉重装一遍。这几乎总是性价比最低的选择,而且重装会把你的配置环境一起搅乱,没必要。把上面几步过一遍,你会发现绝大多数升级故障都落在几类里:网络没治好(配代理重试)、网关在等任务(等它或结束任务)、依赖没补齐(doctor 加 --ensure)、新版本不合用(git 回到旧 tag)。这几类没有一类需要卸载重装来解决。真正该考虑重装的,只有一种极端情况——安装目录被改得乱七八糟、doctor 和 git 回退都救不回来。换句话说,重装是穷尽其他办法后的最后一招,不是遇到升级报错的第一反应。

一句话把次序记牢:升级前记下 --version 并 backup,卡下载先治网络,still draining 是在等任务,升完缺依赖用 doctor 和 --ensure,说不清就翻 update.log,真坏了用 git 切回旧 tag,实在无解才轮到 uninstall 重装。

还没有真实场景？可以先领取 Free Starter 模板包，从低风险只读任务开始试跑。