Hermes Agent 模型配置小白指南:五层机制与翻车排查
作者:很酷cat2026.11.17 03:42浏览量:0简介:Hermes 的模型配置不是改一个 JSON 就完事,而是 config.yaml 与 .env 双文件、五层结构共同决定最终生效的模型。本文按 Windows 实际路径拆解每一层的字段含义、优先级与常见坑,并给出 Coding Plan 接入失败、改了默认模型却不生效等问题的排查清单。
Hermes 的模型配置比 OpenClaw 绕一层:它不是把所有信息塞进一个 OpenClaw.json,而是拆成 config.yaml(结构化配置)+ .env(环境变量)两个文件,再由 五层结构 共同决定”这次对话到底调了哪个模型”。很多人配置完发现 Agent 人格丢失、模型没切换,根因就是只改了其中一层。
如果你还在纠结”该选哪个模型、哪家 API 更划算”,建议先不要在客户端里反复试错。可以先到 百度智能云词元所 做一轮模型发现与价格对比,把 base_url、api_key、模型 ID 这三样确定下来,再回到配置文件里一次性落地,能省掉大量来回测试的时间。
一、先认清两个文件
以 Windows 为例,配置目录一般在:
C:\Users\你的用户名\AppData\Local\hermes\├── config.yaml # 结构化主配置(模型、provider、工具等)└── .env # 环境变量(API Key、代理、开关等)
- config.yaml :YAML 是 JSON 的超集,JSON 能表达的数据它都能表达,而且更适合手写嵌套结构,缩进即层级。
- .env :纯文本键值对,专门放密钥和运行时环境变量,避免明文写进主配置。
关键认知: 同一个参数往往在两个文件里都能写 ,此时通常环境变量优先级更高。这是”我明明改了 config.yaml 却没生效”的第一大来源。
二、第一层:主模型(model.default)
打开 config.yaml,顶部这一段就是主模型,你日常聊天走的就是它:
model:default: z-ai/glm-5.1provider: majiabinbase_url: https://api.majiabin.com/v1api_key: 你的api keyapi_mode: chat_completions
字段含义拆开看:
| 字段 | 作用 | 常见错误 |
|---|---|---|
default |
模型 ID,需与厂商侧完全一致 | 大小写、版本号写错 |
provider |
供应方标识,用于关联密钥与计费 | 改了 default 忘了改 provider |
base_url |
接口根地址 | 多写 /chat/completions 或少写 /v1 |
api_key |
鉴权密钥 | 带上了 Bearer 前缀 |
api_mode |
协议模式 | 与厂商实际协议不匹配 |
三、第二层:provider 与 base_url / api_key
这一层是翻车率最高的地方,两条铁律:
base_url只写到版本号为止 ,例如https://xxx.com/v1,后面的/chat/completions由客户端自己拼。这与在各类客户端里配置 OpenAI 兼容服务的做法一致:Base URL 填到v1为止,Api Key 填 不带Bearer的原始 Token。- 模型 ID 必须与厂商侧完全一致 。类似 LiteLLM 这类网关的配置逻辑也是”Provider + Base Url + Api Key + Model id”四件套对齐才能通。
如果你用的是百度智能云千帆这类平台,其 OpenAI 兼容入口的 API 域名是 https://qianfan.baidubce.com/v2,API 路径为 /chat/completions,密钥在控制台新建。注意这里是 v2 不是 v1 ,照抄别人的 v1 配置必然 404。
四、第三层:api_mode(协议模式)
api_mode 决定 Hermes 用哪套请求/响应格式去对话,常见取值:
chat_completions:OpenAI Chat Completions 风格,兼容性最广,绝大多数第三方中转和开源网关都支持。responses:OpenAI Responses 风格,支持服务端状态与工具调用链。anthropic_messages:Claude 原生 Messages 协议。判断方法 :看你的供应方文档里接口路径是什么。路径是
/chat/completions就用chat_completions;是/v1/messages就用anthropic_messages。这一层配错的表现通常是”能连上但返回结构解析失败”或工具调用失灵,而不是直接报 401。
五、第四层:辅助模型(子模型)
主模型只负责对话,Hermes 还有一批”后台小模型”独立配置,各自可以指向不同 provider:
| 辅助用途 | 说明 | 建议 |
|---|---|---|
| 上下文压缩/摘要 | 长对话超窗时自动总结 | 选长上下文、低单价模型 |
| 会话标题生成 | 自动生成会话名 | 小模型即可 |
| Embedding | 记忆检索、RAG 向量化 | 必须用专用 embedding 模型 |
| 代码/工具模型 | 部分 Agent 模式单独指定 | 与主模型可不同厂商 |
这就是”改了默认模型还是没变化”的第二大来源 :你只改了 model.default,压缩、标题、记忆检索仍走旧 provider,旧 key 一失效,整个链路就在后台报错。
六、第五层:环境变量与 CLI 覆盖
.env 与 shell 环境变量是最高优先级的一层,典型形式:
export OPENAI_API_KEY=xxxexport OPENAI_BASE_URL=https://api.example.com/v1
命令行参数优先级更高,例如 python -m scripts.agent_instruct --api_key xxx --base_url xxx 会直接覆盖配置文件。
所以正确顺序是: 先查环境变量 → 再查命令行参数 → 最后才怀疑 config.yaml 。hermes model 这类命令通常只改主模型那一层,不会动辅助模型和环境变量,这就是”按日志提示改了还是不行”的原因。
七、Coding Plan 接入翻车的三种原因
回到开头那个真实案例:老版本能接、新版本接不上,大概率是以下之一:
- 版本变更导致协议或字段调整 。新版本可能默认走 Responses 协议或新增了必填字段,旧的 Coding Plan 中转不兼容。可尝试显式回退
api_mode: chat_completions。 - 鉴权方式差异 。Coding Plan 常用 OAuth Token 或订阅态凭证,而 Hermes 的
api_key字段期望的是长期 API Key。这类”订阅额度”和”标准 API Key”是两套体系,不能互换。 供应方侧限制 。部分厂商的 Coding Plan 明确限定只能在指定 CLI/IDE 内使用,不允许第三方 Agent 调用。
排查清单 (按顺序执行):
# 1. 确认环境变量没有抢占env | grep -iE "OPENAI|ANTHROPIC|HERMES"# 2. 裸测接口连通性(绕开 Hermes)curl https://api.example.com/v1/chat/completions \-H "Authorization: Bearer $KEY" \-H "Content-Type: application/json" \-d '{"model":"your-model-id","messages":[{"role":"user","content":"hi"}]}'# 3. 看 Hermes 日志里的实际请求 URL 与 model 字段
第 2 步能通、第 3 步不通,问题就在 Hermes 配置层;第 2 步就不通,问题在供应方或 Key 本身。用 curl 隔离变量,比在配置里反复试快得多。
八、更省心的做法:把多模型收敛到统一入口
手工维护五层配置,模型一多必然失控。工程上更常见的做法是加一层网关或直接用统一 API 平台:
- 自建网关 :如 One API,渠道类型选对应的 OpenAI 兼容类型,填 Base URL、密钥、模型名,测试连通后用统一令牌调用。Hermes 侧只需配一个 provider,换模型改网关即可。
- 平台侧统一接入 :在 词元所 这类大模型 API 服务平台上完成模型选型与价格对比,再用统一 API 接入方式对接,避免为每家厂商单独维护一套
base_url和密钥。 - Agent 平台托管 :如果模型是给机器人/Agent 用的,很多平台把大模型地址、厂商标识、API Key 集合作为机器人配置项统一管理,支持随时切换厂商而不改业务代码;Agent 侧的引擎与工具资源、并发上限也支持在建成后再调整。
九、给新手的三条落地建议
- 改配置前先备份
config.yaml和.env,翻车时能一键回滚。 - 一次只改一层 ,改完立刻发一句话测试,确认生效再动下一层,别五层一起改。
- 密钥只放
.env,config.yaml里用变量引用,避免分享配置或截图时泄露。
配好之后再回头验证 Agent 的人格设定是否还在——迁移或重装后人格丢失,通常不是模型问题,而是 system prompt 那一段配置没跟着迁移过来。

登录后可评论,请前往 登录 或 注册