记录Hermes Agent 安装与使用过程

这份文档记录本地开发环境中安装、启动和使用 Hermes Agent 的常用流程，并补充几个容易踩坑的问题。

1. 环境要求

• macOS / Linux / WSL2
• Python 3.11+
• uv
• Git
• 可选：Node.js、ripgrep、Docker、Ollama

检查命令：

python3 --version
uv --version
git --version

如果使用本地模型，需要先启动 Ollama：

ollama serve
ollama list

2. 克隆项目

cd /Users/biao.xie/java/github
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

如果已经克隆过，直接进入项目目录即可：

cd /Users/biao.xie/java/github/hermes-agent

3. 安装依赖

推荐使用项目自带安装脚本：

./setup-hermes.sh

脚本会完成这些事情：

• 创建 venv
• 安装 Python 依赖
• 同步内置 skills 到 ~/.hermes/skills
• 创建 ~/.hermes/config.yaml 和 ~/.hermes/.env
• 可选安装 ripgrep
• 可选进入 hermes setup 配置向导

手动安装方式：

uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"

4. 启动前先进入虚拟环境

很多启动报错都是因为没有进入项目的 venv。

每次打开新终端后，先执行：

cd /Users/biao.xie/java/github/hermes-agent
source venv/bin/activate

确认当前 Python 是否来自项目虚拟环境：

which python
python -c "import sys; print(sys.executable)"

正常应看到类似：

/Users/biao.xie/java/github/hermes-agent/venv/bin/python

不想激活虚拟环境时，也可以直接指定 venv 里的 Python：

venv/bin/python -m hermes_cli.main

5. 首次配置

启动配置向导：

hermes setup

或者分模块配置：

hermes setup model      # 配置模型/Provider
hermes setup gateway    # 配置飞书、Telegram 等消息平台
hermes setup tools      # 配置工具能力
hermes setup terminal   # 配置终端执行后端

配置文件位置：

~/.hermes/config.yaml   # 普通配置
~/.hermes/.env          # API Key 等密钥
~/.hermes/logs/         # 日志

6. 配置模型

使用本地 Ollama

先确认 Ollama 服务可用：

ollama serve
ollama list

然后执行：

hermes setup model

选择本地 provider，例如：

Provider: ollama-local
URL: http://127.0.0.1:11434/v1
Model: qwen3.5:4b

使用 OpenRouter / OpenAI / Nous Portal

执行：

hermes setup model

按提示选择 provider，并填入对应 API Key。也可以直接编辑：

nano ~/.hermes/.env

常见变量示例：

OPENROUTER_API_KEY=...
OPENAI_API_KEY=...

7. 启动方式

普通 CLI

source venv/bin/activate
hermes

或：

venv/bin/python -m hermes_cli.main

运行效果

TUI

source venv/bin/activate
hermes --tui

Web Dashboard

source venv/bin/activate
hermes dashboard

消息网关

source venv/bin/activate
hermes gateway

查看网关状态：

hermes gateway status

查看网关日志：

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

8. 飞书 / Lark 配对

配置飞书：

hermes setup gateway

当飞书机器人提示需要配对时，在系统终端中查看 pending code：

hermes pairing list

输出示例：

Pending Pairing Requests:
Platform     Code       User ID
feishu       ZX5A9359   ou_xxx

批准配对：

hermes pairing approve feishu ZX5A9359

注意：

• 平台名必须是 feishu
• Code 要完整复制，少一位会失败
• 要在系统终端运行，不要在 Hermes 聊天输入框里运行
• hermes pair --token ... 不是当前 CLI 的有效命令

飞书运行效果

9. 终端命令和 Hermes 聊天的区别

看到这种提示符时，是系统终端：

(venv) biao.xie@K3DJ70HFCY hermes-agent %

系统终端里可以运行：

hermes pairing approve feishu ZX5A9359
hermes setup
hermes gateway status

看到这种输入框时，是 Hermes 聊天：

● 请输入消息

这里输入的内容会发给 AI 模型，不会作为系统命令执行。比如在聊天里输入：

hermes pairing approve feishu ZX5A9359

模型只会“回答你”，不会真的完成配对。

10. 常见问题

ModuleNotFoundError: No module named ‘dotenv’

原因：没有进入 venv，使用了系统 Python。

解决：

cd /Users/biao.xie/java/github/hermes-agent
source venv/bin/activate
hermes

或：

venv/bin/python -m hermes_cli.main

ModuleNotFoundError: No module named ‘yaml’

原因同上：没有使用项目虚拟环境。

解决：

source venv/bin/activate
./hermes

It looks like Hermes isn’t configured yet

原因：还没有配置可用的模型 provider 或 API Key。

解决：

hermes setup model

如果用本地 Ollama，先确认：

ollama serve
ollama list

hermes: invalid choice: ‘pair’

原因：当前 CLI 没有 pair 子命令。

正确命令：

hermes pairing list
hermes pairing approve feishu <CODE>

Code not found or expired

可能原因：

• Code 输错或少输字符
• 平台名写错，例如写成了 feish
• Code 已过期
• 命令是在 Hermes 聊天里输入的，不是在系统终端执行的

处理方式：

hermes pairing list
hermes pairing approve feishu <最新完整Code>

uv 提示 pyproject.toml 的 exclude-newer 解析警告

如果看到类似：

Failed to parse pyproject.toml
exclude-newer = "7 days"

通常不影响 fallback 安装流程。安装脚本会在 lockfile 安装失败后回退到普通安装。只要最后出现：

✓ Dependencies installed
✓ Setup complete!

就可以继续使用。

Docker compose 命令

新版 Docker 推荐：

docker compose up -d

如果本机只支持旧版命令：

docker-compose up -d

启动指定服务的写法：

docker compose up -d mysql
docker compose up -d redis

不是：

docker-compose mysql up -d

11. 推荐日常命令

cd /Users/biao.xie/java/github/hermes-agent
source venv/bin/activate

hermes                 # 启动 CLI
hermes --tui           # 启动 TUI
hermes setup model     # 修改模型
hermes setup gateway   # 配置消息平台
hermes pairing list    # 查看待配对用户
hermes doctor          # 诊断环境
hermes logs            # 查看日志
hermes gateway status  # 查看网关状态

12. 停止与重启

退出 Hermes CLI 后，重新启动时仍然要先进入虚拟环境：

cd /Users/biao.xie/java/github/hermes-agent
source venv/bin/activate
hermes

如果是 launchd 后台网关服务：

hermes gateway status
hermes gateway stop
hermes gateway start

如果启动失败，优先看日志：

tail -n 100 ~/.hermes/logs/gateway.log
tail -n 100 ~/.hermes/logs/errors.log