Hermes Agent 安装配置教程：Linux、WSL2、macOS 从安装到可用完整步骤

这篇教程只解决一件事：把 Hermes Agent 从安装、配置到可用，按顺序走通。

不讲太多背景，也不铺一堆概念。你如果只是想尽快把 Hermes 跑起来，照着下面的步骤执行即可。

一、先确认安装环境是否受支持

这一步不要省。Hermes Agent 当前更适合运行在这些环境里：

• Linux
• macOS
• WSL2
• Android / Termux

如果你现在用的是原生 Windows，优先建议先装 WSL2，再进入 WSL2 里执行安装。这样比在原生 Windows 上硬装更稳，也更接近官方支持路径。

二、安装前先想清楚两件事

1. 你准备用哪家模型

Hermes 本体装好，不代表模型一定能直接调用成功。安装之前最好先想清楚：

• 你准备使用哪个 provider
• API Key 放在哪里
• 当前网络能否访问对应服务

很多人第一次卡住，不是在安装阶段，而是在安装完成后第一次启动时发现模型没配好。

2. 你是普通用户安装，还是系统级安装

两种方式的目录布局不一样。

普通用户安装 一般会落在下面这些位置：

• ~/.hermes/hermes-agent/
• ~/.local/bin/hermes
• ~/.hermes/

root / 系统级安装 常见位置通常是：

• /usr/local/lib/hermes-agent/
• /usr/local/bin/hermes
• /root/.hermes/ 或自定义的 HERMES_HOME

如果是你自己的个人开发机，优先建议普通用户安装；如果是共用服务器或需要系统级部署，再考虑 root 模式。

三、执行官方安装命令

Hermes Agent 常用的安装方式就是运行官方脚本：

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

这条命令适用于 Linux、macOS、WSL2，Termux 也走这个入口，由脚本自动识别环境。

如果你对生产环境比较谨慎，不想直接 curl | bash，可以先把脚本下载下来检查内容，再手动执行。

四、安装脚本通常会帮你做什么

它不只是拉一个仓库那么简单，通常还会顺手处理运行 Hermes 所需的基础条件，例如：

• Python 依赖环境
• Node.js 相关依赖
• ripgrep
• ffmpeg
• 项目仓库 clone
• Python virtual environment
• 全局 hermes 命令入口
• 后续的 provider 配置引导

也正因为 Hermes 不是一个单纯的轻量命令行，而是一个 Agent 框架，所以安装器往往会把高频依赖一起补齐。

五、安装完成后先刷新 shell

这一步很容易漏掉。装完以后如果你立刻输入 hermes，结果提示 command not found，不要第一时间怀疑安装失败，很多时候只是 shell 还没刷新。

bash 用户执行：

source ~/.bashrc

zsh 用户执行：

source ~/.zshrc

刷新后再测试：

hermes

六、安装后建议先做这 5 个验证命令

1. 查看版本和安装目录

hermes version

这条命令至少应该返回这些信息：

• Hermes 版本号
• Project 安装目录
• Python 版本

如果这里就报找不到命令，优先排查：

• shell 是否已经刷新
• hermes 是否进了 PATH
• 安装脚本是否中途失败

2. 做一次完整健康检查

hermes doctor

这条命令很有用，因为它会按模块告诉你哪些地方正常、哪些地方缺配置。通常会覆盖：

• Python 环境
• 依赖包是否齐全
• ~/.hermes/.env 是否存在
• ~/.hermes/config.yaml 是否存在
• 外部工具是否齐全
• provider 是否完成认证或配置

如果你看到了 warning，不代表一定安装失败。先看它是在提醒核心链路缺失，还是只是在提示某些可选能力没有配置。

3. 确认配置文件位置

hermes config path

这条命令的作用很直接：先搞清楚 Hermes 现在实际读取的是哪一份 config.yaml。不要一边改 A 文件，一边程序读 B 文件。

4. 确认密钥文件位置

hermes config env-path

这条命令用来确认 .env 文件的真实位置。后面所有 API Key、token、密码类敏感信息，应该优先写在这里。

5. 检查当前配置缺项

hermes config check

它会把变量分成 Required 和 Optional，并告诉你当前哪些已配置、哪些未配置。

一个很关键的认知是：不是所有 Optional 变量都必须第一次就配齐。先把你真正要用的 provider 配通，其他能力后面再按需补。

七、搞清楚 config.yaml 和 .env 分别放什么

这两个文件分工要尽早养成习惯。

适合写进 .env 的内容

• OPENROUTER_API_KEY
• ANTHROPIC_API_KEY
• GOOGLE_API_KEY
• DEEPSEEK_API_KEY
• 各种 token、密钥、密码

适合写进 config.yaml 的内容

• 默认模型
• provider 名称
• terminal backend
• memory 设置
• toolsets 开关
• 显示和行为类配置

如果你懒得手工判断放哪，最省事的方法是直接用：

hermes config set KEY VALUE

一般来说，API Key 这类敏感值会自动写入 .env，普通配置项会写入 config.yaml。

例如：

hermes config set OPENROUTER_API_KEY sk-or-xxxx
hermes config set terminal.backend docker

八、第一次安装建议跑一遍 setup

hermes setup

它不是绝对必须，但第一次安装时通常很省事。因为它可以帮助你更快补齐：

• 模型 / provider 选择
• 终端相关配置
• gateway 配置
• tools 配置
• agent 基础设置

如果你已经很熟悉 Hermes，也可以直接自己改配置文件；但第一次安装，先跑一次 setup 往往更稳。

九、一套最小可用配置流程

如果你不想一上来研究太多选项，可以直接按这条最短链路走：

1. 执行安装脚本
2. 刷新 shell
3. 运行 hermes version 确认命令可用
4. 运行 hermes doctor 做健康检查
5. 通过 hermes setup 或 hermes config set 配置模型与密钥
6. 用 hermes config path 和 hermes config env-path 确认文件路径
7. 运行 hermes config check 检查缺项
8. 最后执行 hermes 或 hermes chat -q "Hello" 做实际调用验证

如果 hermes chat -q "Hello" 能正常返回，通常就说明“安装 + 配置 + 调用”这条基础链路已经走通。

十、安装后常用目录，建议先认一下

~/.hermes/
├── config.yaml
├── .env
├── auth.json
├── SOUL.md
├── memories/
├── skills/
├── cron/
├── sessions/
└── logs/

实际排障时，最常回头看的通常就是这几个位置：

• config.yaml
• .env
• logs/
• sessions/

十一、第一次安装最常见的几个坑

1. 装完以后提示 hermes: command not found

先做这两件事：

source ~/.bashrc
hermes version

如果还不行，再看 hermes doctor 有没有给出 symlink 或 PATH 相关提示。

2. 配置文件明明改了，但没生效

先确认 Hermes 现在实际读取的是哪份文件：

hermes config path
hermes config env-path

不要盲改。

3. 把密钥直接写进了 config.yaml

不推荐。敏感值优先放进 .env，或者直接通过 hermes config set 来写。

4. 以为所有 Optional 变量必须一次配满

不是。先把你要用的模型 provider 跑通，其他工具能力再按需补。

5. 看到 warning 就以为安装失败

先分清 warning 指向的是核心调用链路，还是只是某些可选功能没开。如果以下这些都能通过，通常就已经可以先用了：

• hermes version
• hermes doctor
• hermes config path
• hermes config env-path
• hermes chat -q "Hello" 或直接 hermes

十二、一组建议收藏的检查命令

hermes version
hermes doctor
hermes config path
hermes config env-path
hermes config check
hermes
hermes chat -q "Hello"

这组命令足够覆盖大多数首次安装问题，后面排错时也很高频。

十三、最后给一个最短结论

如果你只想记住核心顺序，就记下面这 6 步：

1. 确认系统在支持范围内
2. 运行官方安装脚本
3. 刷新 shell
4. 用 hermes version 和 hermes doctor 验证安装
5. 用 hermes setup 或 hermes config set 完成模型与密钥配置
6. 用 hermes chat -q "Hello" 或 hermes 验证实际可用

安装本身并不复杂，真正影响体验的，是你有没有把“安装 → 配置 → 验证”这条链路完整走完。

如果你后面准备继续折腾更深一点的能力，再在这个基础上补 toolsets、memory、browser 或其他 provider 配置，会轻松很多。

常用检查命令

hermes version
hermes doctor
hermes config path
hermes config env-path
hermes config check
hermes
hermes chat -q "Hello"