Hermes 接入任意 AI 模型：一文讲透 provider 配置，告别「配了用不了」

作者码锅 | 个人原创未经授权禁止转载系列定位Hermes Agent 入门实战系列 · 第 3 篇 / 共 8 篇前面两篇第 1 篇讲了为什么装 Hermes第 2 篇教你从装好到跑通。这篇解决一个新手指望最大的问题——怎么把 Hermes 接入自己的 API让它可以调用任意模型。先说结论原理只有一句话Hermes 调模型的方式和其他工具一样——所有 provider 底层都是 OpenAI 兼容格式的 API。这就意味着任何提供 OpenAI 格式接口的平台都能接入 Hermes。OpenAI、Anthropic → 直接用内置支持DeepSeek、商汤日日新、MiniMax → 走custom_providers自定义你公司自建的网关 → 也能配进去今天这篇把这个配置从「能配」讲到「配对了」。一个让 80% 新手困惑的问题评论区有人问“我在 config.yaml 里写的是custom:token.sensenova.cn但界面上下拉框显示的是Token.sensenova.cn两个对不上我是不是配错了”你没配错。就是这个设计。看这个对照位置值格式model.providercustom:token.sensenova.cn带custom:前缀全小写custom_providers[].nameToken.sensenova.cn不带前缀首字母大写Hermes 内部用custom:xxx作为 key 来定位 provider界面上显示的是name作为给人看的标签。key 和标签是两个东西格式自然不一样。记住一条规则配置里写custom:xxx界面上找xxx。能对上就行别纠结格式。完整配置文件详解打开~/.hermes/config.yamlprovider 相关部分长这样model:provider:custom:token.sensenova.cndefault:sensenova-6.8-flash-litebase_url:https://token.sensenova.cn/v1custom_providers:-name:Token.sensenova.cnbase_url:https://token.sensenova.cn/v1api_key:你的keymodels:-sensenova-6.8-flash-lite-deepseek-v4-flash-glm-5.24 个关键字段新手最容易搞混字段作用新手常犯错误model.provider告诉 Hermes 用哪个 provider填成了模型名应该填custom:xxxmodel.default默认用哪个模型填了一个没在custom_providers.models里声明过的名字base_urlAPI 地址漏掉末尾的/v1报 404api_key你的密钥格式不对或漏空格报 401base_url漏/v1是最常见的错误——几乎所有平台都是/v1结尾。填错之后每次调用都报 404。验证你配对了跑hermes config看 Model 这一段输出◆ Model Model: {provider: custom:token.sensenova.cn, default: sensenova-6.8-flash-lite, base_url: https://token.sensenova.cn/v1}能看到你填的 provider 和 default 配置生效了。再跑一次实际调用hermes-msensenova-6.8-flash-lite你好报错对照错误码原因解决404base_url 填错检查末尾有没有/v1401API key 不对重新复制注意别带空格429被限流换个模型或等一会Timeout网络问题国内换 DeepSeek / OpenRouter多 provider 切换两种方式方式一命令行临时切换hermes--providercustom:token.sensenova.cn--modeldeepseek-v4-flash只影响当前会话下次启动恢复默认。方式二改 config.yaml 持久生效改model.provider和model.default两个字段model:provider:custom:token.sensenova.cndefault:deepseek-v4-flash保存后下次启动生效。方式生效范围适合场景命令行指定当前会话临时换模型试试效果改 config.yaml持久生效固定用一个模型内置 provider 和自定义 providerHermes 支持两类 provider内置的OpenAI、OpenRouter、Anthropic 等主流平台直接用 key 就能跑。◆ API Keys OpenRouter (not set) OpenAI (not set) Anthropic (not set)自定义的走custom_providers前面已经讲过任何 OpenAI 兼容的 API 都能配。两者的关系底层机制一样。OpenAI 格式的 API 就是 OpenAI 格式的 API——不管是商汤日日新、DeepSeek 官方还是你公司自建网关只要 endpoint 是/v1/chat/completions就能配。进阶模型自动降级fallback用单个模型最怕的就是它挂了或者被限流整个 Hermes 就停摆了。Hermes 有一个 fallback 机制——主模型挂了自动切到备选模型不用你手动干预。配置hermes fallbackadd选一个备选模型。之后行为是主模型限流429→ 自动切到 fallback主模型挂了connection error→ 自动切到 fallback主模型恢复 → 切回去查看当前降级链hermes fallback list什么时候值得配 fallback你用的是一个经常限流的免费模型比如商汤日日新的 glm-5.2 经常 429配一个备选是合理的。高阶让多个模型一起回答问题MoAHermes 还有一个 MoAMixture of Agents功能——同时问多个模型然后用一个模型做聚合输出比单模型质量更高。默认 preset 的设定1. openai-codex:gpt-5.5 ← 参考模型 2. openrouter:deepseek-v4-pro ← 参考模型 聚合openrouter:claude-opus-4.8 ← 聚合模型三个模型各答一遍Claude Opus 再做一个总结。效果确实不错但默认 preset 全是付费模型。想用免费模型的自定义 presethermes moa configure选两个参考模型 一个聚合模型。比如商汤日日新的两个模型 DeepSeek 免费档做聚合。这个功能属于高阶玩法先把基础配置跑通有余力再玩。避坑速查表症状原因解决配置里的名字和界面对不上custom:xxxvsxxx格式不同正常现象能对上就行界面下拉框找不到我的 providercustom_providers段没写检查 config.yaml界面显示 “not configured”API key 没填重新填 key配置改了没生效改的不是~/.hermes/config.yaml路径别搞错模型列表没更新本地缓存了旧列表跑hermes model --refresh作者简介码锅一个喜欢研究 AI 技术的程序员。CSDN 上写技术教程和概念科普分享深度实操和避坑指南。版权声明本文为作者原创本文为博主「Hermes Agent 实战系列」第 3 篇。转载需注明出处。系列导航[第 1 篇] 用 ChatGPT 两年了为什么我要自己装一个 AI Agent[第 2 篇] 从零装 Hermes Agent5 步搞定附完整配置代码第 3 篇Hermes 接入任意 AI 模型一文讲透 provider 配置 ←你在这里[第 4 篇] Hermes v0.20.5 正式版解析待发布[第 5 篇] Hermes v0.21 正式版变化待发布