Hermes Desktop 多模型接入的实现步骤

作者：袖梨 2026-07-09

摘要：本文记录了在 Hermes Agent Desktop 中配置讯飞星火 MaaS Coding API 作为自定义 Provider 的完整过程，包括单模型配置、多模型接入、Desktop 下拉菜单不显示的排查，以及最终的解决方案。附带实用配置模板和避坑指南。

背景

Hermes Agent 是 Nous Research 开源的 AI Agent 框架，支持 CLI、Telegram、Discord、Slack 等多平台。它的 Desktop 桌面版支持自定义 OpenAI 兼容 API，但文档中对命名自定义 Provider（Named Custom Providers）的配置细节不够清晰，实际操作中踩了不少坑。

本文以讯飞星火 MaaS Coding API 为例，记录完整的配置过程和踩坑经验。

Desktop 模型下拉菜单：配置过程中

配置 custom_providers 后，XUNFEI 出现在下拉菜单，但只显示了 model 字段指定的模型（xopglm51），xopkimik26 没有出现：

img_6a4f1a248393530.webp

一、基础配置：接入单个自定义模型

1.1 准备信息

项目值
API 地址https://maas-coding-api.cn-huabei-1.xf-yun.com/v2
API Key
模型 IDxopkimik26
接口协议OpenAI 兼容

1.2 四条命令搞定

hermes config set model.provider custom
hermes config set model.default xopkimik26
hermes config set model.base_url "https://maas-coding-api.cn-huabei-1.xf-yun.com/v2"
hermes config set model.api_key ""

写入 ~/.hermes/config.yaml 的结果：

model:
  default: xopkimik26
  provider: custom
  base_url: https://maas-coding-api.cn-huabei-1.xf-yun.com/v2
  api_key:

1.3 验证

curl -s "https://maas-coding-api.cn-huabei-1.xf-yun.com/v2/chat/completions" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer " 
  -d '{"model":"xopkimik26","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

返回 HTTP 200 即成功。

二、进阶配置：接入多个模型（命名 Provider）

2.1 场景

同一个 API 端点下有两个模型：

  • xopglm51 — 备选模型
  • xopkimik26 — 原有模型

需要在 Hermes Desktop 下拉菜单中同时显示，且能自由切换。

2.2 正确的配置格式

在 ~/.hermes/config.yaml 中添加以下两个 section：

# 1. custom_providers — 运行时路由（必须有 models 列表）
custom_providers:
  - name: xunfei
    base_url: https://maas-coding-api.cn-huabei-1.xf-yun.com/v2
    api_key: 
    models:
      - xopglm51
      - xopkimik26
# 2. providers — 供 /model 命令使用（可选，但建议清空避免冲突）
providers: {}

2.3 Desktop 下拉菜单效果

配置完成后，重启 Desktop 应用，下拉菜单应显示：

DEEPSEEK
  Deepseek V4 Pro 中
  Deepseek V4 Flash 中
XIAOMI
  Mimo V2.5 Pro 中
  Mimo V2.5 中
XUNFEI                    ← 新增
  Xopglm51 中
  Xopkimik26 中

img_6a4f1a248393a31.webp

三、踩坑记录

坑 1：providers:和custom_providers:缺一不可（但格式有讲究）

Hermes 内部有两个 config section 都会影响模型显示：

Section作用格式
providers:/model 命令的模型列表来源dict，key 为 provider 名
custom_providers:运行时 API 路由 + Desktop 下拉菜单list，每个 entry 有 name/base_url/api_key/model(s)

关键发现：如果 providers: 和 custom_providers: 同时存在同名条目，Desktop 下拉菜单会优先使用 providers: 的内容，导致 custom_providers: 的 models 列表被跳过。

img_6a4f1a248393d32.webp

解决方案：只保留 custom_providers:，将 providers: 清空为 {}。

# ✅ 正确：providers 清空，custom_providers 包含所有模型
providers: {}
custom_providers:
  - name: xunfei
    base_url: https://...
    api_key: ...
    models: [xopglm51, xopkimik26]

坑 2：providers:里的default字段不被识别

# ❌ 错误 — "default" 是未知字段，被静默丢弃
providers:
  xunfei:
    default: xopglm51
# ✅ 正确 — 必须用 "model" 字段
providers:
  xunfei:
    model: xopglm51

Hermes 的 _normalize_custom_provider_entry() 函数只识别 _KNOWN_KEYS 中的字段，default 不在其中。

坑 3：custom_providers里用model（单数）只显示一个模型

# ❌ 只能显示一个模型
custom_providers:
  - name: xunfei
    model: xopglm51
# ✅ 用 models 列表显示多个模型
custom_providers:
  - name: xunfei
    models:
      - xopglm51
      - xopkimik26

坑 4：Desktop GUI 的自定义 API 表单有 bug

根据 4SAPI 博客 的分析：

桌面版 GUI 的自定义 API 表单当前有 bug，光在界面里填不生效，必须中断当前运行的模型、用 hermes model 手动重选一次才能生效。

规避方法：用命令行配置（hermes config set），不要依赖 GUI 表单。

坑 5：/model命令不支持自定义 Provider

/model 的解析依赖 _PROVIDER_MODELS 静态目录（hermes_cli/models.py）。自定义 Provider 不在其中，需要手动添加：

# ~/.hermes/hermes-agent/hermes_cli/models.py
_PROVIDER_MODELS = {
    ...
    "xunfei": [
        "xopkimik26",
        "xopglm51",
    ],
}

修改后需要 /quit + 重启 Hermes 生效。

四、完整配置模板

# ── 默认模型 ──
model:
  default: mimo-v2.5          # 或你的默认模型
  provider: xiaomi             # 内置 provider
# ── 命名自定义 Provider（多个模型） ──
custom_providers:
  - name: xunfei
    base_url: https://maas-coding-api.cn-huabei-1.xf-yun.com/v2
    api_key: 
    models:
      - xopglm51
      - xopkimik26
# ── providers 清空（避免与 custom_providers 冲突） ──
providers: {}

五、命令速查

场景命令
配置默认模型hermes config set model.default
配置 Providerhermes config set model.provider
会话中切换模型/model 或 /model custom::
验证 YAML 格式python -c "import yaml; yaml.safe_load(open('config.yaml')); print('OK')"
查看当前配置hermes config
重启生效退出会话 (/quit) 后重新运行 hermes

六、总结

问题原因解决方案
Desktop 下拉菜单不显示自定义模型providers: 和 custom_providers: 同名冲突只用 custom_providers:，清空 providers:
providers: 里的模型不显示default 是未知字段改用 model 字段
只显示一个模型用了 model（单数）而非 models（列表）改用 models: [model1, model2]
GUI 填的 API 不生效Desktop GUI 表单 bug用 hermes config set 命令行配置
/model 命令找不到自定义模型_PROVIDER_MODELS 静态目录缺少条目在 models.py 中添加模型列表

参考资料

  • Hermes Agent 官方文档
  • Hermes Agent 配置指南
  • Hermes Agent Provider 配置
  • 4SAPI - Hermes Desktop 自定义 API Bug 修复
  • GitHub Issue #7054 - Named custom providers config split

本文档由 Hermes Agent 自动生成，基于 2026 年 6 月的实测经验。如有更新请参考官方文档。

七、让 AI 帮你自动配置（直接复制使用）

如果你想让 AI Agent（如 Hermes、Claude Code、Cursor 等）帮你完成上述所有配置，直接把下面的 prompt 复制粘贴发给 AI 即可。把 <占位符> 替换成你自己的值。

Prompt 模板

请帮我配置 Hermes Agent 的自定义 API 模型，要求如下：

API 地址：
API Key：
模型列表：
Provider 名称：<自定义名称，如 xunfei>

具体操作：

1. 用 hermes config set 命令配置默认模型：
   - model.provider 设为 custom
   - model.default 设为 
   - model.base_url 设为 
   - model.api_key 设为 

2. 编辑 ~/.hermes/config.yaml（或 Windows 上的 C:Users<用户名>AppDataLocalhermesconfig.yaml），添加 custom_providers section：
   custom_providers:
     - name: <自定义名称>
       base_url: 
       api_key: 
       models:
         - 
         - 

3. 将 providers section 清空为 providers: {}，避免与 custom_providers 冲突。

4. 编辑 hermes_cli/models.py，在 _PROVIDER_MODELS 字典中添加：
   "<自定义名称>": ["", ""]
   这样 /model 命令才能自动识别这些模型。

5. 用 curl 测试每个模型的连通性，确认返回 HTTP 200。

6. 用 python yaml.safe_load 验证 config.yaml 格式正确。

7. 提示我重启 Hermes Desktop 以生效。

更简短的版本（适合只有一两个模型）

帮我配置 Hermes Agent 接入一个第三方 API：

API: 
Key: 
模型: 

用 hermes config set 设好默认模型，然后在 config.yaml 里加 custom_providers，记得把 providers 清空避免冲突。

如果你已经有一个模型，想追加第二个

我现在 Hermes 已经配了一个自定义模型 （provider 名叫 ）。
请帮我追加同一个 API 下的另一个模型 ，要求：
1. 在 config.yaml 的 custom_providers 里把 models 改成列表，包含两个模型
2. 在 hermes_cli/models.py 的 _PROVIDER_MODELS 里也加上第二个模型
3. 不要动 model.default，保留原来的默认模型

相关文章

精彩推荐