安装 / 更新 / 环境问题LCP

一句话结论：这一页只处理“命令起不来、装不上、更新后变怪、环境边界混乱”这类问题。只要你还没确认 hermes 命令本身是否正常，就先不要跳去查模型、Gateway、Tools。

如果你现在很急，先记住：

先确认是不是命令层 / PATH / shell / 终端类型问题；不要一上来就删目录重装。

🇨🇳 国内安装速答：换 4 个源，90% 的"装不上"立即解决

速答：国内网络下 Hermes 安装失败，根因绝大多数是 GitHub / PyPI / npm / Playwright 四个下载源没换。把这 4 行先跑一遍，再装 Hermes，问题立刻少 90%。详细解释见本页 FAQ 11｜国内镜像源速查。

# 1. PyPI（pip 包）
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

# 2. npm（Node 包）
npm config set registry https://registry.npmmirror.com/

# 3. Playwright 浏览器二进制（最容易卡的一步）
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright

# 4. GitHub 脚本 / Release 下载（手动替换域名为 ghfast.top / gh-proxy.com / gitcode.com）

不想手动配？社区有 fast-mirror-skill，自动检测并切换（见 FAQ 12）。

⚡ 先按症状选路

你现在最像哪一种，直接跳：

🚫 命令根本起不来

• hermes: command not found
• hermes version 也跑不通
• 安装完后终端里还是找不到命令
• 先看：01｜执行就报 hermes: command not found

⬇️ 安装一开始就失败

• 安装脚本拉不下来
• 脚本刚启动就报错
• git / curl / 网络链路异常
• 先看：02｜安装脚本一开始就失败

🪟 Windows / WSL2 边界混乱

• 在 PowerShell / CMD 里直接装
• 安装器卡住
• 路径和 shell 行为很奇怪
• 先看：03｜Windows 为什么总装不对

🔄 更新后突然异常

• 之前能用，现在突然不对
• 更新后命令指向不对
• 开始怀疑是不是新版本坏了
• 先看：04｜更新之后突然变怪，是不是新版本坏了

🧭 不确定这是不是安装问题

• hermes 能跑，但 doctor / provider / model 报错
• 不知道该继续查环境，还是跳去模型页
• 先看：05｜怎么判断现在还是安装层问题

🧪 先做最小判断

先跑这 3 条，只做分层，不要同时乱改配置：

which hermes
hermes version
hermes doctor

怎么理解结果：

• which hermes 都找不到：优先还是安装 / PATH / shell 问题
• hermes version 跑不起来：还没进入模型层
• hermes version 正常、hermes doctor 开始报 provider / model：大概率已经该跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

✅ 先做什么：5 步排查清单

按这个顺序排，最不容易越改越乱：

1. 确认你是不是在受支持环境里
   • 官方基线：Linux / macOS / WSL2 / Android（Termux）
   • Native Windows 先不要继续深挖
2. 确认安装命令是不是官方命令
3. 确认 git、curl、网络至少能工作
4. 确认 shell 已 reload，~/.local/bin 已进 PATH
5. 只有前 4 步都没问题，才讨论手动安装或重装

📌 先记住这 4 个官方基线

1）标准安装命令只有这一条

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

2）标准更新命令只有这一条

hermes update

如果更新过程中跳过了新配置迁移，立刻补：

hermes config check
hermes config migrate

3）官方只要求你先有 Git

git --version

官方安装器会自动处理的大头依赖包括：

• Python 3.11
• Node.js
• ripgrep
• ffmpeg

所以装不上时，不要一上来就手动补一堆依赖；先确认是不是环境或网络链路问题。

4）更新后先做最小验收，不要靠感觉判断

hermes version
hermes doctor
hermes gateway status

怎么看：

• hermes version 正常：至少命令层活着
• hermes doctor 正常：基础环境大概率没坏
• hermes gateway status 正常：如果你本来就在跑消息平台，更新没有把服务层带坏

❓FAQ

01｜执行就报 hermes: command not found

❓ 问题

执行 hermes 就报 command not found。

💡 先说结论

最常见不是“完全没装上”，而是 shell 没 reload、PATH 没生效，或者你还停留在旧终端窗口。

🔎 先做什么

source ~/.bashrc

如果你用的是 zsh：

source ~/.zshrc

然后再查：

which hermes
ls ~/.local/bin/hermes

如果你确认文件在，但命令还是找不到，临时补 PATH：

export PATH="$HOME/.local/bin:$PATH"
hermes version

🚦 什么时候该跳转

• hermes version 还是完全跑不起来：继续留在本页
• hermes version 正常了，但开始报模型 / Key / endpoint：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

02｜安装脚本一开始就失败

❓ 问题

安装脚本刚开始执行就失败，或者根本拉不下来。

💡 先说结论

先别怀疑 Hermes 本体，先查命令、Git、网络、代理。

🔎 先做什么

git --version
curl --version

官方一键安装命令：

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

优先检查这几件事：

• 你执行的是不是官方完整命令
• 当前终端能不能正常访问 GitHub 原始脚本
• 代理是不是只让浏览器通，不让终端通
• 机器上是不是连 git 都没装好

🚦 什么时候该跳转

• git / curl 本身异常：先修基础环境
• 安装器能跑，但后面卡在 provider / model：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

03｜Windows 为什么总装不对

❓ 问题

我明明在 Windows 上执行了命令，但安装过程总是很怪。

💡 先说结论

因为 Hermes 官方不支持 Native Windows。Windows 用户默认应该在 WSL2 里安装和运行。

🔎 先做什么

• 先确认你是不是还在 PowerShell / CMD
• 如果是，先切到 WSL2 的 Linux 终端
• 再在 WSL2 里重新执行官方安装命令

你现在该怎么判断：

• 还在 Native Windows → 不要继续深挖细节，先换环境
• 已经在 WSL2 → 回到本页继续查 shell / PATH / 安装链路

🚦 什么时候该跳转

• 你还没把基础安装主线走通：可先回看 [04-把 Hermes 装上去](../01-从这开始/01-先跑起来/04-把 Hermes 装上去.md)
• 你已经在 WSL2 且命令正常，只是模型报错：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

04｜更新之后突然变怪，是不是新版本坏了

❓ 问题

更新之后突然不对劲，我要不要先怀疑新版本坏了。

💡 先说结论

不一定。更新后异常，最常见还是旧终端没关、shell 没 reload、PATH 指到了旧位置，或者更新其实已经引入了新的配置项，你跳过了迁移。

🔎 先做什么

hermes update
hermes config check
hermes config migrate
which hermes
hermes version
hermes doctor

如果你本来就在跑消息平台，再补一条：

hermes gateway status

按结果拆：

• which hermes 不对：先修 PATH / shell
• hermes config check 提示缺配置：先完成迁移，再继续判断
• hermes version 正常、doctor 报 provider / model：已经不只是安装问题
• gateway status 异常：说明更新可能影响了服务层，但不等于安装器坏了
• 两个都正常：优先去查后续层，而不是继续在这里怀疑安装器

补充一个 v2026.5.29.2 之后的判断口径：官方该版本只修复了 wheel / sdist 包里 bundled plugin.yaml manifests 没有随包发布的问题。如果你是在升级后遇到“插件清单 / bundled plugin manifest 缺失”这类异常，先执行 hermes update 更新到 v2026.5.29.2 或更高版本，再重新跑 hermes doctor；不要把它误判成 provider、API Key 或 endpoint 配置错误。

如果更新过程像卡住了，可以看日志：

tail -f ~/.hermes/logs/update.log

🚦 什么时候该跳转

• provider / model 报错：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)
• CLI / 会话行为异常：跳到 [04-CLI / TUI / 会话问题](./04-CLI TUI 与会话问题.md)
• 消息平台恢复不了：跳到 [05-Gateway / Messaging / 推送问题](./05-Gateway Messaging 与推送问题.md)

05｜怎么判断现在还是安装层问题

❓ 问题

我现在到底还在安装层，还是其实已经进入模型 / 配置层了？

💡 先说结论

最实用的分界线就是 hermes version 和 hermes doctor。

🔎 先做什么

• 看命令本身能不能执行
• 看 doctor 报的是命令层，还是 provider / model 层

快速判断：

• 命令都起不来 → 安装 / 环境层
• 命令能起、开始报 Key / model / endpoint → 模型层
• 命令和模型都没问题，只是交互异常 → [04-CLI / TUI / 会话问题](./04-CLI TUI 与会话问题.md)

🚦 什么时候该跳转

• 只要你已经能稳定跑 hermes version，就不要再把所有问题都归成安装失败
• 明显进入鉴权 / 模型 / endpoint：跳到下一页

06｜什么情况先不要重装

❓ 问题

是不是一旦出问题，最稳就是删掉重装？

💡 先说结论

只要命令还能给出有效输出，就先不要把它判成“必须重装”。

🔎 先做什么

先排掉这几类高频误判：

• shell 没 reload
• PATH 里没有 ~/.local/bin
• 还在旧终端里测试
• 实际问题已经在 provider / model 层
• Windows 用户跑错到了 Native Windows

🚦 什么时候该跳转

• 你只是想靠重装跳过定位：先不要跳
• 你已经确认一键安装链路、shell、PATH、终端类型都没问题，才看下一题

07｜什么情况才该看手动安装

❓ 问题

我是不是应该直接放弃一键安装，改走手动安装？

💡 先说结论

只有当一键安装反复失败，而且你已经确认不是环境 / shell / PATH 问题时，手动安装才值得看。

🔎 先做什么

• 先把一键安装链路排清楚
• 先确认问题不在 Git、网络、PATH、终端类型
• 再决定要不要进入官方 Installation 页里的手动安装部分

更适合手动安装的场景：

• 你明确要自己控制 Python / uv / extras
• 机器环境比较特殊
• 一键安装在正确环境里反复失败

🚦 什么时候该跳转

• 只是普通安装失败：先留在本页
• 你已经明确要自定义依赖链路：再去看官方 Installation 文档

08｜中国环境里最容易伪装成“安装失败”的是什么

❓ 问题

我在国内环境里安装总失败，这是不是 Hermes 本体 bug？

💡 先说结论

最常见不是 Hermes 自己坏了，而是 GitHub 下载、终端代理、WSL2 / Windows 混用这些环境问题。

🔎 先做什么

先把下面 4 层拆开：

1. 终端环境对不对
2. Git / curl 能不能用
3. 安装器能不能拉到脚本
4. shell / PATH 有没有真正生效

中文环境里最常见的伪装项：

• GitHub 脚本下载慢或失败
• 浏览器能访问，终端不能访问
• 云主机缺 Git 或基础依赖
• WSL2 和 Windows 路径、终端混用

🚦 什么时候该跳转

• 基础命令一旦跑通，再进入 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)、[05-Gateway / Messaging / 推送问题](./05-Gateway Messaging 与推送问题.md)、[06-Tools / Skills / MCP 问题](./06-Tools Skills MCP 问题.md)

09｜官方安装器卡在依赖安装提示怎么办

❓ 问题

官方安装器卡在依赖安装提示，我现在该不该开始改命令？

💡 先说结论

如果你是在 Windows 场景里卡住，优先判断是不是终端用错了；很多案例不是命令要魔改，而是应该回到 WSL 终端再执行。

🔎 先做什么

• 先确认当前是不是 WSL2 里的 Linux 终端
• 如果不是，先切回去
• 不要在错误终端里反复试各种第三方命令

🚦 什么时候该跳转

• 还在 Native Windows：先不要跳别页，先换环境
• 切到 WSL2 后命令正常了，但模型阶段报错：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

10｜明明装过 node / pyenv / asdf，为什么 Hermes 还是像没看到

❓ 问题

我明明已经有 Node、Python 或版本管理器，但 Hermes 运行时还是像没看到这些工具。

💡 先说结论

这通常不是 Hermes "忘了识别"，而是你的环境初始化只写在 ~/.bashrc，但登录 shell 读的是 ~/.profile 或 ~/.bash_profile。

🔎 先做什么

• 先确认你现在依赖的是不是 nvm、pyenv、asdf、cargo 这类 shell 初始化工具
• 如果这些初始化只写在 ~/.bashrc，把关键 PATH / init 也补到 ~/.profile 或 ~/.bash_profile
• 改完以后，重新开一个终端窗口，再跑一次：

which node
which python3
which hermes
hermes version

🚦 什么时候该跳转

• 这些基础命令都已经正常，后面只剩 provider / model：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)
• 你真正卡的是 CLI 交互或会话恢复：跳到 [04-CLI / TUI / 会话问题](./04-CLI TUI 与会话问题.md)

11｜国内安装 Hermes 总卡在 GitHub / pip / Playwright 下载，国内镜像源速查

❓ 问题

在国内网络下，安装脚本拉不下来、pip install 超时、Playwright 浏览器下载失败、npm 包慢。

💡 先说结论

绝大多数国内安装失败，不是 Hermes 本身 bug，而是 GitHub、PyPI、npm、Playwright 四个下载源都没换。下面这张速查表是社区踩坑后总结出来的可用镜像源（截至 2026-06）。

🔎 五源速查表

最常用的一段前置配置（放在执行安装命令之前）：

# pip 镜像（Hermes 安装器会调 pip）
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

# npm 镜像（Hermes 装依赖会调 npm）
npm config set registry https://registry.npmmirror.com/

# Playwright 浏览器镜像（最容易卡的一步）
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright

然后再跑官方安装命令：

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

🚦 什么时候该跳转

• 镜像源换过还是不行：可能是终端代理没生效，先 curl -v https://raw.githubusercontent.com 看握手
• 装上了但 hermes doctor 报错：跳到下方 FAQ 12
• 装上了但模型连接失败：跳到 [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

来源：cnblogs.com/itech — 国内安装踩坑全记录、官方 Installation 文档。

12｜fast-mirror-skill 是什么？Hermes 官方推荐用吗？

❓ 问题

社区教程里提到一个叫 fast-mirror-skill 的工具，自动配国内镜像源，是 Hermes 官方的吗？

💡 先说结论

fast-mirror-skill 是社区开发的 Claude Skill，不是 Hermes 官方组件。它的工作原理是自动检测你当前的网络环境，把 GitHub、PyPI、npm、Playwright 等常用下载源切换到国内镜像。

🔎 适合谁

• 你已经会用 Claude Code Skills，知道怎么装 skill
• 你不想手动一个一个配镜像源
• 你能在 OpenClaw / Hermes / 其他 Claude 兼容环境里通用

不适合谁：

• 第一次装 Hermes、还没搞清 skill 是什么的新手——优先按 FAQ 11 手动配，理解原理
• 已经有自己稳定的镜像源配置体系

🚦 什么时候该跳转

• 你只是想搞清楚 Hermes 安装流程：回 [04-把 Hermes 装上去](../01-从这开始/01-先跑起来/04-把 Hermes 装上去.md)
• 你想看 Hermes 官方的 Skills 系统：15-自定义 Skills

来源：cnblogs.com/itech — fast-mirror-skill 介绍。

13｜hermes doctor 输出字段都代表什么？怎么根据它判断问题在哪？

❓ 问题

跑完 hermes doctor，看到一堆打勾打叉的项，不知道每项代表什么。

💡 先说结论

hermes doctor 是 Hermes 的环境健康检查命令，输出按层分段，每段对应一个可能的故障层。看懂字段含义，就能直接定位问题。

🔎 字段对照表

最常见三种组合判断：

• 全绿 → 环境健康，问题不在安装层
• Python / Hermes 红 → 安装层问题，留在本页
• Provider / Gateway 红 → 已经离开安装层，跳对应故障页

🚦 什么时候该跳转

• doctor 显示 Provider / Model 有问题：跳 [03-模型 / Provider](./03-模型 Provider 与自定义 endpoint 问题.md)
• doctor 显示 Gateway 有问题：跳 [05-Gateway / Messaging](./05-Gateway Messaging 与推送问题.md)
• doctor 显示 SOUL.md 路径错位：跳 [07-配置 / Profiles 与环境隔离问题](./07-配置 Profiles 与环境隔离问题.md#faq-soul-path)

来源：官方 CLI 命令参考、cnblogs.com/addozhang — hermes doctor 实测输出。

🔹 官方依据

• Installation
• Quickstart
• Updating & Uninstalling
• FAQ & Troubleshooting
• Windows WSL2 安装说明
• 官方 Issue：安装器卡在依赖安装提示时，Windows 用户应切回 WSL 终端

✅ 看完这页，你应该立刻能判断

• 我是不是还在错误环境里装 Hermes
• 我的问题是 PATH / shell 没生效，还是安装器根本没跑起来
• 我现在该继续排环境，还是该转去查模型 / Provider
• 我现在到底有没有必要重装

➡️ 下一步

完成后进入：

• [03-模型 / Provider / 自定义 endpoint 问题](./03-模型 Provider 与自定义 endpoint 问题.md)

如果你想先回到上一阶段入口重新确认位置：

• 01-总览

🔗 相关排查入口

• 从这开始
• 先准备运行环境
• 把 Hermes 装上去
• CLI 命令参考

如果当前页没有命中症状，先回到遇到问题总入口重新按问题类型分流。