Hermes Agent 安装失败自救：9 个阶段、3 份日志、5 步恢复
【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent
Hermes Agent 是 Nous Research 出品的自进化 AI 智能体——从执行经验里沉淀技能，还能检索自己的历史会话。装它通常一行命令的事，但依赖检查链任何一环断裂，终端就从转圈变成满屏报错。这时候别急着重跑安装。
安装器不是"一把梭"，而是"阶段清单 + 有限重试 + 取证日志"。它先取一份阶段 manifest，再逐阶段执行、逐阶段判定成败；只有"宿主进程异常退出但没返回结果"这类抖动才会自动重试，上限 3 次，确定性错误立即失败。所以失败永远发生在某个具体阶段上，而不是某个不确定的时刻——你的任务就是找到那个阶段。
满屏红字：先定位你卡在 9 个阶段中的哪一个
scripts/install.sh 的 manifest 固定列出 9 个阶段：prerequisites、repository、venv、python-deps、config、products、setup、gateway、complete。
报错时先翻日志里最后一条带阶段名的输出，再对号入座：
prerequisites/repository挂：多为系统缺依赖或 clone 网络中断，重跑整条安装即可，这两步都是幂等的。venv/python-deps挂：问题出在 uv 或 Python 版本上。uv 按 pm/lock.json 里钉死的版本和 sha256 校验下载，Python 解释器版本同样由锁文件说了算。手动建环境时别自己指定系统里随便哪个版本，版本漂移的账最后都在装完那一刻还。config挂：对照 .env.example 检查模板是否缺文件，别凭空猜变量名。- 想只补跑一段：
./scripts/install.sh --stage venv。单阶段重跑是安装器自己干的事，你手动干也不越权。
定位完阶段还是没救活，往下看取证层。
两条命令把范围缩到一步：doctor 与 forensic log
- 跑
hermes doctor。配置、环境、常见故障一次诊断完，加--fix还能直接修一部分。比人工逐条猜快得多。 - 翻取证日志。每次 bootstrap 运行都会落一份
~/.hermes/logs/bootstrap-<时间戳>.log，安装脚本的每一行 stdout/stderr 都双写进去；安装器自身的运行日志在同目录的bootstrap-installer.log。只看最后失败的那几行，错误归属通常当场就清楚。
看日志看阶段名，不看不认识的栈。最后 20 行里最近的阶段标记，就是你这次重跑的起点：在它之前的阶段不用管，它之后的是这次要修的。
装完却启动不了：PATH、.env、版本三坑
hermes命令不存在：脚本把启动器发布到~/.local/bin并往~/.bashrc/~/.zshrc追加了 PATH。装完必须source ~/.bashrc（zsh 用户source ~/.zshrc）再试。"装了但命令找不到"里一大半是 shell 没重载。- 启动报配置缺失：安装器默认从模板生成
.env并收紧权限到 600。如果你的.env是被别处带进来的残缺文件，按 .env.example 补齐变量。 - 装完才报语法错误：十有八九是 Python 版本不对。
.python-version和锁文件钉的解释器版本是唯一真相源，手动建 venv 时照着钉。
Windows 专属：白名单圈文件夹，脚本缓存会骗你
- 杀毒把
uv.exe隔离：Defender、Bitdefender 这类 ML 引擎常把 hermesbin目录下的uv.exe当病毒——未签名 Rust 二进制加会下载文件的特征。处置要点只有一条：加白名单时圈整个目录，别圈文件哈希。uv 每次升级哈希都变，按哈希加白等于每周重新报修一次。 - 缓存的安装脚本：commit 钉（40 位 SHA）是不可变引用，本地有缓存就永久复用不再联网；branch 钉每次尝试刷新，只有刷新失败才退回旧缓存——防止"一次下坏的脚本被无限期复用"。早年缓存下来的
.ps1可能带 BOM 编码缺陷，安装器交付前会就地升级修复。旧机器上"没改代码却突然报错"，优先怀疑这一层。
症状速查表
| 你看到的症状 | 第一步做什么 |
|---|---|
| 卡在"安装中"无进展 | 看 bootstrap 日志最后 20 行，定位卡住的阶段 |
prerequisites/repository阶段失败 | 直接重跑整条安装，这两步幂等 |
venv/python-deps报校验或版本错误 | 对照 pm/lock.json 确认 uv 与 Python 钉的版本 |
hermes命令不存在 | 重载 shell 配置，确认~/.local/bin在 PATH |
uv.exe被杀毒隔离 | 给 hermesbin整个目录加白名单 |
| 启动报配置缺失 | 对照 .env.example 补齐变量 |
清单走完还有问题，别用"现象描述"求助——把bootstrap-<时间戳>.log尾段原样贴出来，谁接手都能继续。
如果你打算改安装脚本本身，从 CONTRIBUTING.md 入手：CI 里有安装脚本的端到端测试和 apps/bootstrap-installer/ 安装器测试，改动必须在那套真实安装流程里跑通才算完。
【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
