Hermes Agent配置自定义AI模型

如果你在用 Hermes Agent，想接入自定义 AI 模型，最核心的不是“模型多不多”，而是：

Hermes 读哪里配置
上游接口是什么协议
模型名怎么映射
改完后怎么验证

这篇按通用、真实可落地的方式整理。

一、先确认 Hermes Agent 的模型接入方式

Hermes Agent 常见会有两种路径：

1. 直接在配置文件里声明模型

也就是你在 Hermes 的配置文件、环境变量或 Agent 配置里，直接填：

provider
base URL
api key
model name

2. 通过中间层统一转发

比如：

One API
New API
其它 OpenAI兼容接口兼容网关

这种做法的好处是：

Hermes 只认一个兼容接口
你底层换模型更方便
后面维护更轻松

---

二、你需要准备的参数

无论哪种方式，通常都需要这几项：

Provider 类型

- OpenAI兼容接口兼容 / 其它兼容协议 / 其它

Base URL
API Key
实际模型名
Hermes 内部使用的名字或路由名

---

三、最常见的接法：走 OpenAI兼容接口兼容接口

如果你的 Hermes Agent 支持 OpenAI兼容接口风格配置，那么最常见的写法会类似：

{
  "provider": "openai",
  "base_url": "https://api.example.com/v1",
  "api_key": "sk-xxxx",
  "model": "deepseek-chat"
}

这里真正重要的是：

base_url 指向可用接口
model 填服务商支持的真实模型名
api_key 可正常调用

---

四、如果你想用“自定义模型名”

很多时候，Hermes 配置里你可以人为定义一个逻辑名，例如：

{
  "default_model": "coder-main",
  "models": {
    "coder-main": {
      "provider": "openai",
      "base_url": "https://api.example.com/v1",
      "api_key": "sk-xxxx",
      "model": "qwen-plus"
    }
  }
}

这样做的好处是：

以后要换底层模型，只改一处
Hermes 内部调用统一
提示词、Agent 配置不用跟着一起改名字

---

五、如果你的上游是其它兼容协议风格

如果 Hermes 当前版本支持其它兼容协议接入，那就按对应字段配。

思路不变：

endpoint 对上
key 对上
model 对上

不要混用 OpenAI兼容接口风格字段和其它兼容协议风格接口。

很多报错都来自这一步。

---

六、推荐的实际做法：先接兼容网关，再给 Hermes 用

如果你后面可能经常换模型，我更建议这样：

方案

Hermes Agent → 统一兼容接口
兼容接口背后 → 你自己切不同模型

例如：

Hermes 始终连 https://api.your-domain.com/v1
真正的上游模型在中间层切换

好处

不用频繁改 Hermes
更容易统一日志和额度
后面扩展别的模型也方便

---

七、配置后怎么验证

建议这样测：

1. 先最小测试

给 Agent 一个极简单输入：

请只返回“模型接入成功”

2. 再测一条需要推理的任务

比如：

请用三句话说明接口幂等是什么意思

3. 观察是否出现这些问题

401：Key 不对
404：Base URL 或模型路径不对
400：模型名错误或协议字段不匹配
超时：网络或上游响应问题

---

八、常见踩坑点

1. Base URL 多写或少写 `/v1`

这个很常见。

2. 把“显示名称”当成“真实模型名”

有些平台页面显示的是别名，但接口真正要填的是内部模型 ID。

3. Hermes 改了配置但没重新加载

如果 Hermes Agent 有重载/重启动作，记得执行，不然它还在读旧配置。

---

九、一句话总结

Hermes Agent 接自定义模型，最稳的路线是：

先确定协议
再对齐 base URL、key、model
最好给模型做一层逻辑别名

这样既能真实可用，后面也更容易维护。