Hermes Agent 安装失败怎么排查：command not found、PATH、Python 和 API Key

先判断失败发生在哪一步

安装失败不要先重装。先把问题分成四段：命令能不能被终端识别、基础依赖是否可用、Hermes 配置是否完整、模型 Provider 是否能请求成功。每一段只改一个变量，才容易判断是哪一步恢复了。

1. hermes: command not found

这是最常见的问题，通常不是 Hermes 本身坏了，而是当前终端没有加载 PATH。

which hermes
printf '%s\n' "$PATH"
source ~/.zshrc
source ~/.bashrc

macOS 默认常见是 zsh，Linux 和 WSL2 常见是 bash。执行 `source` 后仍然找不到，就新开一个终端窗口再试。Windows 用户如果同时用了 PowerShell 和 WSL2，要确认你在哪个环境里安装，就在哪个环境里运行。

2. Git、curl、Python 或 Node 不可用

安装脚本能跑，不代表依赖都可用。先让这些命令在当前终端里返回版本号。

git --version
curl --version
python3 --version
node --version
npm --version

如果某一项不存在，先补基础环境，再重跑 Hermes 安装。不要在依赖缺失时继续改模型配置，否则后面会把安装问题和 Provider 问题混在一起。

3. Windows 路线选错

Windows 新手优先用 WSL2。PowerShell 原生路线适合快速体验，但路径、权限和后台进程会比 WSL2 更容易出现差异。已经在 PowerShell 里装过，也不要把配置目录和 WSL2 混着用。

wsl --install
wsl --set-default-version 2

进入 Ubuntu 终端后，再按 Linux 路线安装。确认 `pwd` 显示的是 Linux 路径，而不是 Windows 盘符路径。

4. setup 卡在 Provider 或 API Key

如果 `hermes setup` 能启动，但 Provider 配置失败，先单独检查模型 Key 和模型名。不要同时改 Prompt、Gateway 和 Skills。

hermes model
hermes config check
hermes doctor

OpenRouter 用户重点看模型名是否完整、API Key 是否加载到当前 shell、配置后是否重启了会话。先用一个明确可用的模型跑短问答，再切回目标模型。

5. Memory 或 Skills 目录异常

Memory 和 Skills 目录失败，多数是目录权限、路径混用或安装中断。先确认当前用户能读写项目目录和用户目录。

pwd
ls -la
hermes skills browse

不要直接给整个系统目录加最高权限。更稳的做法是换到用户目录下的干净项目文件夹，重新跑一次 setup。

最小恢复顺序

• 新开终端，确认当前系统路线。
• 检查 `git`、`curl`、`python3`、`node` 是否可用。
• 检查 `which hermes` 和 PATH。
• 跑 `hermes doctor` 和 `hermes config check`。
• 只用一个 Provider 做短问答。
• 再看 Memory、Skills 和 Gateway。

什么时候可以重装

只有在安装脚本中断、目录明显不完整、或者 PATH 指向了错误版本时，才考虑重装。重装前先保存配置、错误日志和当前 shell 信息。能定位的问题，不要靠反复重装解决。

下一步

如果你还没有真实场景，可以先领取 Free Starter 模板包，从每日简报、Issue 分类和内容选题三个低风险任务开始。