Hermes Agent 大模型配置指南：可复用经验总结

一、核心心智模型（先看这个，避免 80% 坑）

1.1 三层配置来源

┌──────────────────────────────────────────────────────┐
│  第 3 层：命令行临时覆盖                               │
│  hermes -m <模型> --provider <provider> --in DIR      │
│  仅本次会话有效，不改文件                              │
├──────────────────────────────────────────────────────┤
│  第 2 层：用户配置文件（最常用）                       │
│  ~/.hermes/config.yaml  — 模型、provider、fallback    │
│  ~/.hermes/.env       — API Key / Base URL            │
├──────────────────────────────────────────────────────┤
│  第 1 层：内置 provider 注册表                        │
│  hermes_cli/providers.py — 别名 / 传输协议 / env 变量 │
│  不可修改，是所有配置的”字典“                          │
└──────────────────────────────────────────────────────┘

1.2 配置写入的优先级（禁止事项）

1.3 Provider 别名表（核心！别自己瞎写名字）

来自 providers.py 中 ALIASES 字典：

黄金法则：不知道写啥 → 写 hermes model 交互式选，别自造名。

二、三条配置路线

路线 A：云端 API Key（最省事，推荐入门）

# 1. 交互式配置最快
hermes setup
# 2. 选模型 + 验证
hermes doctor
hermes status
hermes chat -q Hello

单命令模式：

# 智谱 GLM-4-Flash（永久免费，国内可用）
echo ZAI_API_KEY=你的KEY >> ~/.hermes/.env
hermes config set model glm-4-flash
hermes chat -q 你好

# DeepSeek
echo DEEPSEEK_API_KEY=你的KEY >> ~/.hermes/.env
hermes config set model deepseek-v3

显式指定 provider 的安全写法（config.yaml）：

model:
  name: glm-4-flash
  provider: zai

路线 B：本地大模型（自建 OpenAI 兼容端点）

适用：Ollama / oMLX / LM Studio / vLLM / llama.cpp / node-llama-cpp / 任何能开 OpenAI REST 端口的东西。

B-1 选择通用壳：lmstudio

• 它是内置 provider，transport=openai_chat
• 通过 LM_BASE_URL + LM_API_KEY 环境变量注入

B-2 最小可行配置
.env：

LM_BASE_URL=http://127.0.0.1:8080/v1
LM_API_KEY=local    # 无鉴权也写占位符，不能为空

config.yaml：

model:
  name: qwen2.5-3b
  provider: lmstudio

B-3 致命坑：SSE 流式支持
Hermes 默认所有请求 stream=true！本地端点必须实现 text/event-stream 流式输出，否则 EmptyStreamError → 3 次后走 fallback。
标准 SSE 格式：每行 data: {...}

，最后 data: [DONE]

收尾。

B-4 验证链路（按顺序，一步不通别往下走）：

# 1 端点
curl http://127.0.0.1:8080/v1/models
# 2 非流式
curl -s http://127.0.0.1:8080/v1/chat/completions -H Content-Type:application/json -d {"model":"qwen2.5-3b","stream":false,"messages":[{"role":"user","content":"你好"}]}
# 3 流式（关键）
curl -sN http://127.0.0.1:8080/v1/chat/completions -H Content-Type:application/json -d {"model":"qwen2.5-3b","stream":true,"messages":[{"role":"user","content":"你好"}]} | head -20
# 4 Hermes 真走通了吗
hermes chat -q 你好 2>&1  # 必须没 Primary model failed

路线 C：故障转移 Fallback 链

fallback_model:
  provider: zai
  model: glm-4-flash

注意：fallback 账户必须真实可用；目前只有一层。

三、高级：自定义 Provider（providers 段）

providers:
  my-local-qwen:
    name: 本地 Qwen
    api: http://127.0.0.1:8080/v1
    key_env: MY_LOCAL_API_KEY
    transport: openai_chat
model:
  name: qwen2.5-3b
  provider: my-local-qwen

四、常见坑与解决方案速查表

五、“永不失败”的配置执行顺序（复制即用）

场景1：云端 API Key

KEY=xxxx; echo ZAI_API_KEY=$KEY >> ~/.hermes/.env
hermes config set model glm-4-flash
hermes config show | grep -A5 Model:
hermes chat -q Hi

场景2：本地 OpenAI 兼容端点
先 curl 验证健康（/v1/models + stream=true chat），再写 LM_BASE_URL/LM_API_KEY 进 .env，config.yaml 写 model.name/model.provider=lmstudio，最后 hermes chat -q Hi 验证。

场景3：本地模型长期运行脚本：建议写 bash case 脚本，start 节点后台进程 + PID 文件，就绪循环 poll /v1/models，stop 读 PID 文件结束进程。

六、调试清单：6 件事按顺序确认

1. 配置是否被读了？ → hermes config show 看 Model / API Keys 区
2. 端点是否活着？ → curl /v1/models
3. 流式能通吗？ → curl stream=true 看 SSE 格式
4. API Key 带了吗？ → Authorization 头（或端点日志）
5. 模型名一致吗？ → config.yaml 的 model.name 与 /v1/models 返回 id 一致
6. provider 真对吗？ → 不要自造，查别名表；或自定义 providers 段绕开

七、环境变量速查表

八、参考文件路径速查

一句话总结：云端 → hermes config set model + .env 写 Key；本地 → lmstudio 通用壳 + LM_BASE_URL/LM_API_KEY + 强制 SSE 流式；provider 名绝不要自造。

花絮：这篇文档是怎么被踩坑逼出来的

以下记录了 2026-08-19 到 2026-08-20 这 24 小时里，为搞定「Intel Mac + 本地 3B 模型 + 正确接入 Hermes Agent」这一件事，踩过的 6 个真坑。
后面的正文是把这些坑系统化后的操作手册，但如果你赶时间，先读下面 6 条，能帮你少走 90% 的弯路。

坑 1：本地端点能 curl 通，但 Hermes 永远报 EmptyStreamError？？？

我第一版写的 node-llama-cpp 服务器只返回普通 JSON，curl 直接测 200 正常，结果 Hermes 一连上就报：EmptyStreamError — switching to fallback，连 fallback 都挂。
原因：Hermes 默认对所有调用都发 stream=true，它期待的是 text/event-stream SSE 格式，而不是 application/json。一行 data: ...、两个换行，最后还要 data: [DONE] 收尾，差一个格式都不行。
教训：写本地 OpenAI 兼容服务器，第一行代码就要先把 stream=true 的分支实现好。

坑 2：写了 OPENAI_BASE_URL 也配了 model=qwen2.5-3b，为什么不走本地？

我一开始在 .env 里写了裸 OPENAI_BASE_URL=...，又在 config 里只写 model 名不写 provider。结果 qwen2.5-3b 这个名字被 Hermes 的 models.dev 误匹配到了云端的 alibaba provider，请求打到了阿里云 401。
原因：provider 的选择是「先按别名表/注册表匹配，找不到才走自定义」。本地模型名如果刚好撞了云端前缀，你不显式写 provider 就是赌博。
教训：本地端点必须显式写 provider，最简单的做法是用 lmstudio 这个内置壳 + LM_BASE_URL / LM_API_KEY 两个环境变量，既干净又不会撞名。

坑 3：写 openai provider 怎么请求全跑到 OpenRouter 了？

裸 openai 在 Hermes 内置的 ALIASES 字典里被强制映射到 openrouter（聚合路由）。不是官方 api.openai.com，是聚合！
教训：provider 名 绝不要靠猜，一定要查内置 ALIASES 表（见正文 1.3 节）。要用官方 OpenAI 写 openai-api，不要写 openai。

坑 4：hermes config set 为什么一写就报 Operation not permitted？

Agent 沙箱默认禁写 ~/.hermes 目录，hermes config set 会在那建临时 .tmp 原子文件，一跑就 PermissionError。
教训：在自动化脚本里对 Hermes 配置做修改，shell 命令必须用沙箱外执行（或让用户在自己的终端跑）。

坑 5：Kimi 账户显示「有 Key」，一用就 429？

我一开始把 fallback_model 设成了 kimi-coding-cn + moonshot-v1-128k，API Key 也写了。结果主模型失败一切就 429：account suspended due to insufficient balance。
教训：有 Key ≠ 有余额。配 fallback 之后一定要模拟一次主模型故障来验证 fallback 真能工作。我现在的 fallback 固定是 zai + glm-4-flash（智谱清言免费额度）。

坑 6：YAML 改坏了怎么办？

我试过把 model 改成 model_provider: openai 这种自造的键，结果被 Hermes 标成「未识别配置键」被忽略；又试过整段覆盖 config.yaml 导致缩进错位，schema 校验红。
教训：改 YAML 的原则是「最小增量改动」——只加/改你要的字段，其他一个字别动。能 hermes config set 就不要手改；手改就只改目标行。改坏了跑 hermes config migrate 救。

适用版本：Hermes Agent v0.20+ ｜ 更新时间：2026-08-20
适用环境：macOS / Linux / Windows ｜ 配置入口：hermes config + ~/.hermes/config.yaml + ~/.hermes/.env

文章导出 收起 ✕

预览框 📱 手机 📄 A4

生成预览中...

📱 手机 🖥 PC 深灰 纯黑 墨蓝 墨绿 棕 酒红 黛紫 浅白(深底) 仿宋 宋体 黑体 楷体 雅黑 衬线 小 (20px) 中 (26px) 大 (32px) 特大 (38px) 纯白 米黄 薄荷绿 雾蓝 淡粉 深墨 紧凑 标准 宽松 首行缩进 封面头 品牌 副标题 标题 封面脚 来源 二维码 当前时间 时间 二维码·原文链接 二维码·自定义链接 二维码·文件提取 二维码·图片粘贴 仅品牌名 生成二维码 上传二维码图片提取链接 ⚠️ 注:微信二维码官方已升级,新生成的微信码无法识别,仅支持旧版/其他来源的二维码图片。 上传图片, 框选二维码区域

拖动框选二维码区域

取消 确定裁剪

🖼 导出图片 📝 导出 Word