Hermes 使用教程：从启动到故障排查的完整记录

环境概览

网络架构

Hermes 的部署拓扑：

• 管理节点通过 WireGuard 接入公司内网，网段 10.10.0.0/24
• 10.10.0.4 上运行 Nginx 反向代理，监听 0.0.0.0:8000，后端接 DeepSeek 网关
• 所有 API 请求统一走 http://10.10.0.4:8000/v1

这条链路踩过坑。Nginx 不传 Authorization 头、超时不够、Host 路由不对都遇到过，后面踩坑记录里展开。

可用模型

日常启动与退出

启动

hermes

在钉钉群里 @机器人 或在私聊里直接发消息即可交互。命令行环境下直接输入文本对话。

对话中常用操作

模型选择与切换

规则引擎速查

Hermes 支持通过 config.yaml 中的 rules 配置按关键词自动匹配模型。例如：

rules:
  - keywords: ["架构", "架构设计", "系统设计"]
    model: deepseek-v4-pro
    provider: company-deepseek-v4
  - keywords: ["翻译", "translate"]
    model: deepseek-v4-flash
    provider: company-deepseek-v4-flash

每条规则包括：

• keywords — 匹配用户输入的关键词列表
• model — 指定使用的模型名
• provider — 对应的后端 provider（可选）
• priority — 规则优先级（数值越大越优先，默认 0）

匹配后自动切换，不需要手动干预。

临时切换模型

在对话里随时切，不影响上下文：

/model deepseek-v4-pro

也可以传 provider+model：

/model company-deepseek-v4/deepseek-v4-pro

多话题会话管理

这是近期新增的功能：一个 Hermes 实例里同时跑多个独立会话，互不干扰。

使用场景

假设你同时处理三个话题：

每个会话有自己的对话历史、上下文和模型配置。启动新话题：

/new 技术架构

然后在对话中设置模型：

/model deepseek-v4-pro
/title 技术架构

这样下次通过 hermes --continue 技术架构 就能直接回到这个对话。

查看所有会话

hermes sessions list

输出会列出每个会话的 ID、名称、最后活跃时间。也可以用交互式界面浏览：

hermes sessions browse

会话操作速查

进阶：Profile 完全隔离

如果希望话题之间完全隔离——独立的记忆、独立的配置、甚至独立的 API Key——可以创建多个 Profile：

# 创建新 profile
hermes profile create 工作-架构设计

# 在该 profile 下配置不同的模型
hermes config set model deepseek-v4-pro --profile 工作-架构设计

# 使用指定 profile 启动
hermes --profile 工作-架构设计

每个 Profile 有自己独立的 skills、plugins、cron 和 memories。

常用命令速查

基础命令

模型切换

会话管理

系统维护

踩坑记录

以下是实际部署过程中踩过的坑。

❌ Nginx 反代导致 401 认证错误

现象：客户端配置了正确的 API Key，但请求始终返回 401。

原因：Nginx 默认不会透传 Authorization 请求头。反向代理到后端时，这个头被丢了。

修复：在 Nginx 的 location 块里显式加上：

proxy_set_header Authorization $http_authorization;

这个坑踩了两次——正常对话没问题，但上下文压缩（生成大请求）时偶发 401，因为压缩请求走了不同的连接路径，偶尔触发同一根因。

❌ Realm 转发导致 404

现象：使用 Realm 做流量转发，所有请求返回 404。

原因：Realm 不支持修改 Host 头，公司网关依赖 Host 做路由决策。

解决：放弃 Realm，改为 Nginx proxy_pass 直接反代。

❌ 请求超时

现象：长文本生成或复杂推理中途被断开，客户端收到超时错误。

原因：Nginx 的 proxy_read_timeout 默认只有 60 秒，AI 后端生成长回复时经常超过这个时间。

修复：

proxy_read_timeout 600s;
proxy_connect_timeout 60s;
proxy_send_timeout 60s;

确保同时使用 HTTP/1.1 长连接：

proxy_http_version 1.1;
proxy_set_header Connection "";

故障排查

快速诊断

遇到问题时按顺序执行：

# 1. 检查 WireGuard 连通性
ping 10.10.0.4

# 2. 检查 Nginx 是否存活
curl -s -o /dev/null -w "%{http_code}" http://10.10.0.4:8000/v1/models

# 3. 检查 Hermes 自身状态
hermes doctor

# 4. 查看最近日志
tail -100 ~/.hermes/logs/hermes.log

常见问题

附录 A：Nginx 优化配置参考

server {
    listen 8000;
    server_name _;

    location /v1 {
        proxy_pass http://<upstream>;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header Authorization $http_authorization;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 600s;
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
    }
}

三个要点：超时设到 600 秒、显式转发 Authorization 头、用 HTTP/1.1 长连接避免频繁握手。

文档基于 Hermes Agent 公开发布版本及公司内部部署实践整理，配置参数和功能以实际部署版本为准。文档编号：DOC-2026-0708-HERMES-V2。