首页
手游
资讯
专题
首页 > 教程攻略 > ai教程 >Hermes Desktop 多模型接入的实现步骤

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

来源：互联网 时间：2026-07-10 07:11:26

写 Hermes Agent 的配置指南真是个大坑。文档是有的，但细节里藏着无数让人抓狂的暗坑。这篇东西，是我折腾讯飞星火 MaaS Coding API 接入过程的完整记录——从单模型怎么配，到多个模型一起上，再到大跌眼镜的下拉菜单不显示问题，以及最终怎样搞定。末尾放了可直接复用的模板，以及一份避坑清单，免得你重复踩雷。

背景

先交代一下背景。Hermes Agent 是 Nous Research 开源的 AI Agent 框架，支持 CLI、Telegram、Discord、Slack，还有桌面版 Desktop。Desktop 有个看似方便的功能——支持自定义 OpenAI 兼容 API，而且能搞“命名自定义 Provider”，也就是 Named Custom Providers。但这东西的配置细节，官方文档讲得很克制，实际操作起来，是该踩的坑一个都没少。

这篇文章以

讯飞星火 MaaS Coding API

为例，把完整的配置流程和踩坑经验给你捋一遍。

Desktop 模型下拉菜单：配置过程中遇到的问题

配置完 custom_providers 之后，XUNFEI 确实出现在下拉菜单里了，但只显示 model 字段里指定的那个模型（xopglm51），xopkimik26 直接没影了。

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

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 中

三、踩坑记录

坑 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 列表被跳过。

解决方案

：只保留 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

相关阅读

相关下载