Hermes Desktop 接入第三方 API 模型全攻略从踩坑到完美配置摘要本文记录了在 Hermes Agent Desktop 中配置讯飞星火 MaaS Coding API 作为自定义 Provider 的完整过程包括单模型配置、多模型接入、Desktop 下拉菜单不显示的排查以及最终的解决方案。附带实用配置模板和避坑指南。目录一、基础配置接入单个自定义模型1.1 准备信息1.2 四条命令搞定1.3 验证二、进阶配置接入多个模型命名 Provider2.1 场景2.2 正确的配置格式2.3 Desktop 下拉菜单效果三、踩坑记录坑 1providers 和 custom_providers 同名冲突坑 2providers 里的 default 字段不被识别坑 3custom_providers 里用 model单数只显示一个模型坑 4Desktop GUI 的自定义 API 表单有 bug坑 5/model 命令不支持自定义 Provider四、完整配置模板五、命令速查六、总结七、让 AI 帮你自动配置直接复制使用Prompt 模板更简短的版本追加第二个模型参考资料背景Hermes Agent 是 Nous Research 开源的 AI Agent 框架支持 CLI、Telegram、Discord、Slack 等多平台。它的 Desktop 桌面版支持自定义 OpenAI 兼容 API但文档中对命名自定义 ProviderNamed Custom Providers的配置细节不够清晰实际操作中踩了不少坑。本文以讯飞星火 MaaS Coding API为例记录完整的配置过程和踩坑经验。Desktop 模型下拉菜单配置过程中配置custom_providers后XUNFEI 出现在下拉菜单但只显示了model字段指定的模型xopglm51xopkimik26 没有出现一、基础配置接入单个自定义模型1.1 准备信息项目值API 地址https://maas-coding-api.cn-huabei-1.xf-yun.com/v2API Keyyour-api-key模型 IDxopkimik26接口协议OpenAI 兼容1.2 四条命令搞定hermes configsetmodel.provider custom hermes configsetmodel.default xopkimik26 hermes configsetmodel.base_urlhttps://maas-coding-api.cn-huabei-1.xf-yun.com/v2hermes configsetmodel.api_keyyour-api-key写入~/.hermes/config.yaml的结果model:default:xopkimik26provider:custombase_url:https://maas-coding-api.cn-huabei-1.xf-yun.com/v2api_key:your-api-key1.3 验证curl-shttps://maas-coding-api.cn-huabei-1.xf-yun.com/v2/chat/completions\-HContent-Type: application/json\-HAuthorization: Bearer your-api-key\-d{model:xopkimik26,messages:[{role:user,content:hi}],max_tokens:10}返回 HTTP 200 即成功。二、进阶配置接入多个模型命名 Provider2.1 场景同一个 API 端点下有两个模型xopglm51— 备选模型xopkimik26— 原有模型需要在 Hermes Desktop 下拉菜单中同时显示且能自由切换。2.2 正确的配置格式在~/.hermes/config.yaml中添加以下两个 section# 1. custom_providers — 运行时路由必须有 models 列表custom_providers:-name:xunfeibase_url:https://maas-coding-api.cn-huabei-1.xf-yun.com/v2api_key:your-api-keymodels:-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 中三、踩坑记录坑 1providers:和custom_providers:缺一不可但格式有讲究Hermes 内部有两个 config section 都会影响模型显示Section作用格式providers:/model命令的模型列表来源dictkey 为 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:xunfeibase_url:https://...api_key:...models:[xopglm51,xopkimik26]坑 2providers:里的default字段不被识别# ❌ 错误 — default 是未知字段被静默丢弃providers:xunfei:default:xopglm51# ✅ 正确 — 必须用 model 字段providers:xunfei:model:xopglm51Hermes 的_normalize_custom_provider_entry()函数只识别_KNOWN_KEYS中的字段default不在其中。坑 3custom_providers里用model单数只显示一个模型# ❌ 只能显示一个模型custom_providers:-name:xunfeimodel:xopglm51# ✅ 用 models 列表显示多个模型custom_providers:-name:xunfeimodels:-xopglm51-xopkimik26坑 4Desktop GUI 的自定义 API 表单有 bug根据 4SAPI 博客 的分析桌面版 GUI 的自定义 API 表单当前有 bug光在界面里填不生效必须中断当前运行的模型、用hermes model手动重选一次才能生效。规避方法用命令行配置hermes config set不要依赖 GUI 表单。坑 5/model命令不支持自定义 Provider/model model-name的解析依赖_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:xunfeibase_url:https://maas-coding-api.cn-huabei-1.xf-yun.com/v2api_key:your-api-keymodels:-xopglm51-xopkimik26# ── providers 清空避免与 custom_providers 冲突 ──providers:{}五、命令速查场景命令配置默认模型hermes config set model.default model-id配置 Providerhermes config set model.provider provider会话中切换模型/model model-id或/model custom:name:model-id验证 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 地址https://your-api.com/v2 API Keyyour-api-key 模型列表model-id-1, model-id-2, ... Provider 名称自定义名称如 xunfei 具体操作 1. 用 hermes config set 命令配置默认模型 - model.provider 设为 custom - model.default 设为 model-id-1 - model.base_url 设为 API地址 - model.api_key 设为 API Key 2. 编辑 ~/.hermes/config.yaml或 Windows 上的 C:\Users\用户名\AppData\Local\hermes\config.yaml添加 custom_providers section custom_providers: - name: 自定义名称 base_url: API地址 api_key: API Key models: - model-id-1 - model-id-2 3. 将 providers section 清空为 providers: {}避免与 custom_providers 冲突。 4. 编辑 hermes_cli/models.py在 _PROVIDER_MODELS 字典中添加 自定义名称: [model-id-1, model-id-2] 这样 /model 命令才能自动识别这些模型。 5. 用 curl 测试每个模型的连通性确认返回 HTTP 200。 6. 用 python yaml.safe_load 验证 config.yaml 格式正确。 7. 提示我重启 Hermes Desktop 以生效。更简短的版本适合只有一两个模型帮我配置 Hermes Agent 接入一个第三方 API API: https://your-api.com/v2 Key: your-api-key 模型: model-id 用 hermes config set 设好默认模型然后在 config.yaml 里加 custom_providers记得把 providers 清空避免冲突。如果你已经有一个模型想追加第二个我现在 Hermes 已经配了一个自定义模型 model-id-1provider 名叫 provider-name。 请帮我追加同一个 API 下的另一个模型 model-id-2要求 1. 在 config.yaml 的 custom_providers 里把 models 改成列表包含两个模型 2. 在 hermes_cli/models.py 的 _PROVIDER_MODELS 里也加上第二个模型 3. 不要动 model.default保留原来的默认模型