Hermes Agent install.sh 下载失败、卡住、超时怎么办

先分清是哪一段在卡

官方一键安装命令只有一行,但它背后串了两件事:先从 GitHub 把 `install.sh` 脚本本身下载下来,再由这个脚本去拉 Python 依赖。国内网络下这两段会在完全不同的位置卡住,而它们的解法也不一样。不分清就开始换镜像、配代理,基本是乱试,运气好碰对了也不知道为什么对。

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

判断方法很直接:把 `| bash` 去掉,单独下一次脚本,把它落到本地文件。

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/install.sh

这一条几秒内拿到文件、`/tmp/install.sh` 里有内容,说明脚本下载这段是通的,真正的卡点在后面拉依赖那段;这一条本身就转半天、超时退出,卡点就在连 GitHub 这一跳。先用这一刀把问题切成两半,后面才好对症。

脚本下载这跳:配代理或换加速前缀

卡在连 `raw.githubusercontent.com`,本质是国内直连 GitHub 不稳,跟 Hermes 一点关系没有。两条路,二选一就够。

第一条,给 curl 指你自己的 HTTP 代理,再跑原命令:

export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

端口换成你本机代理实际监听的端口,别照抄 7890。这里有个容易忽略的点:`export` 出来的代理只对当前这个终端窗口有效,你新开一个窗口它就没了。所以从下载到后面装依赖、跑验收,尽量在同一个终端里一口气做完,别中途换窗口。

第二条,用你常用的 GitHub 加速服务做前缀,把脚本地址套在它后面下下来再执行。加速只解决"下载到"这一步,脚本内容和官方仓库里的一字不差,执行逻辑完全一样。两条路都试不通的话,就走下一节,把脚本先存到本地再本地执行,绕开命令对 GitHub 的实时依赖。

依赖拉取这跳:给 uv 指国内 PyPI 镜像

脚本下来了、也跑起来了,却卡在装 Python 包一直转圈,是依赖源走了境外。安装器用 uv 管理 Python 依赖,给它指一个国内 PyPI 镜像即可。镜像只是换了个下载源,装出来的 Hermes 和官方完全一致,不用担心被改过:

export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

清华、阿里这类国内镜像都行,挑一个平时拉包快的。注意它和上一节的代理是可以叠加的:GitHub 那跳走代理、PyPI 这跳走镜像,两条慢链路各自治各自的,互不冲突。如果你想一劳永逸,别每次都手敲这行 `export`——把它写进你的 shell 配置文件,以后每开一个新终端都自动带上镜像设置,既省事,也避免下次升级、重装时又忘了配。临时装一次就用 `export`,长期用就写进配置,按需选。

装完先验收,别急着配模型

无论上面走了哪条路,装完只确认一件事:CLI 能起来、依赖齐了。这一步不通,后面配什么都白搭。

hermes --version
hermes doctor
hermes status

三条各管一段:`hermes --version` 确认命令本身在、版本号能正常打印;`hermes doctor` 检查配置和依赖是否齐全,这是安装是否真的成功的硬指标;`hermes status` 给出所有组件的状态总览,让你一眼看清还有哪块没就绪。三条都过,安装这关才算真过,而不是"脚本跑完没报错"就完事。

过了这关再去配模型——国内用户这一步顺手把默认 Provider 选成可直连的那几家(用 `hermes model` 交互式选),后面日常用起来就不必再为网络发愁。要记住:安装阶段的下载网络问题,和运行阶段连不连得上模型,是两件独立的事,别挤在一次折腾里搅成一团。安装关只对"装上没装上"负责;模型能不能通,是装完之后另起一步的事。

一个常见的假象:脚本跑完不等于装好了

国内网络下还有一种坑人的情况:脚本看着跑完了、终端回到了提示符、也没刷红色报错,但其实中途某个依赖下载被悄悄跳过或截断了,装出来是个半成品。这种"假成功"光看脚本输出发现不了,只有靠上面那三条验收命令兜底。所以无论你觉得装得多顺,`hermes --version`、`hermes doctor`、`hermes status` 这三条都别省——`doctor` 但凡报出缺这缺那,就说明刚才那次下载有东西没拉全,回到对应的网络或镜像设置重跑一遍安装即可,不是什么大问题,就怕你不验收、直接拿半成品去配模型,到时候把安装没装全的锅记到模型头上,排查方向就全偏了。判断一次安装到底成没成,认 `doctor` 的输出,别认脚本有没有报错。

还没有真实场景？可以先领取 [Free Starter 模板包](/free-template-pack)，从低风险只读任务开始试跑。