Hermes 配置自定义 API Endpoint 教程：解决中转接口无法使用的问题

很多用户在使用 Hermes 时，会遇到这样的问题：

已经有 OpenAI 兼容中转接口，也有 API Key，但 Hermes 里还是无法正常调用模型。

这类问题通常不是接口本身不可用，而是 Hermes 的 base_url 、模型名、API Key 或 /v1
路径配置不一致导致的。

经过群友【武杰】的提供解决方案，整理成如下文章，文末提供群友原文，提供给 AI 学习可以秒连接。

本文通过一个实际排查案例，说明如何在 Hermes 中正确配置自定义 API endpoint。

一、问题背景

用户希望在 Hermes 中使用自己的 API 中转地址，例如：

https://openai.mozhevip.top

同时配置自己的 API Key：

sk-xxxxxxxxxxxxxxxx

Hermes 当前已有一个自定义 provider，配置结构类似：

model:  base_url: https://openai.example.com/v1  default: gpt-5.5  provider: custom:my-endpoint  api_key: ''  
custom_providers:  - name: my-endpoint    base_url: https://openai.example.com/v1    api_key: '***'    model: gpt-5.5    key_env: ''

这里有一个关键点：

base_url 必须是 API 地址，不一定等于网站首页地址。

很多 OpenAI 兼容接口实际 API 地址是：

https://openai.mozhevip.top/v1

而不是：

https://openai.mozhevip.top

如果少了 /v1 ，请求可能会打到网页首页，而不是 API 服务。

二、先验证 endpoint 是否可用

在修改 Hermes 配置前，建议先测试 /v1/models 。

PowerShell 示例：

$baseUrl = "https://openai.mozhevip.top/v1"$apiKey = "sk-你的密钥"  
Invoke-WebRequest `  -Uri "$baseUrl/models" `  -Headers @{ Authorization = "Bearer $apiKey" } `  -UseBasicParsing

如果返回 JSON，并且里面有模型列表，说明 endpoint 和 key 基本可用。

如果返回的是 HTML 页面，通常说明访问的是网站首页，不是 API 地址。这时大概率需要补上：

/v1

三、确认模型是否存在

如果接口能返回模型列表，还需要确认你配置的模型名确实存在。

例如 Hermes 配置里是：

model: gpt-5.5

那么 /v1/models 返回结果里也应该能看到：

gpt-5.5

如果模型名不存在，即使 endpoint 和 API Key 正确，也会调用失败。

四、不要直接手改 api_key

Hermes 配置文件里经常会看到：

api_key: '***'

这通常表示 Hermes 对密钥做了脱敏或加密存储。

因此，不建议直接用文本编辑器把 *** 改成真实 key。更稳妥的方式是使用 Hermes 自带命令写入。

示例：

hermes config set custom_providers.0.api_key "sk-你的新密钥"

如果你的自定义 provider 不是第一个，需要先确认它在 custom_providers 里的索引。

例如：

custom_providers:  - name: my-endpoint

这里对应：

custom_providers.0

如果是第二个 provider，则对应：

custom_providers.1

五、base_url 建议保留 /v1

如果测试发现：

https://openai.mozhevip.top/v1/models

可以返回模型列表，而：

https://openai.mozhevip.top/models

返回网页或报错，那么 Hermes 里的 base_url 应该配置为：

base_url: https://openai.mozhevip.top/v1

不要只写：

base_url: https://openai.mozhevip.top

这是很多用户配置失败的主要原因。

六、完整配置示例

推荐结构如下：

model:  base_url: https://openai.example.com/v1  default: gpt-5.5  provider: custom:my-endpoint  api_key: ''  
custom_providers:  - name: my-endpoint    base_url: https://openai.example.com/v1    api_key: '***'    model: gpt-5.5    key_env: ''

其中：

provider: custom:my-endpoint

要和下面的 provider 名称保持一致：

name: my-endpoint

七、端到端测试

配置完成后，建议用一次真实对话请求验证。

PowerShell 示例：

$baseUrl = "https://openai.example.com/v1"$apiKey = "sk-你的密钥"  
$body = @{  model = "gpt-5.5"  messages = @(    @{      role = "user"      content = "只回复 HERMES_OK"    }  )} | ConvertTo-Json -Depth 10  
Invoke-RestMethod `  -Uri "$baseUrl/chat/completions" `  -Method Post `  -Headers @{    Authorization = "Bearer $apiKey"    "Content-Type" = "application/json"  } `  -Body $body

如果返回内容里模型正常回复：

HERMES_OK

说明 endpoint、API Key 和模型名都已经打通。

八、最后必须重启 Hermes

修改配置后，正在运行中的 Hermes 进程不一定会自动重新读取配置。

建议操作：

1. 完全退出 Hermes 桌面端  
2. 关闭相关 CLI 会话  
3. 重新打开 Hermes  
4. 再次测试模型调用

否则可能出现这种情况：

配置文件已经改了，但 Hermes 运行中仍然使用旧 key。

九、常见错误排查

现象	常见原因	处理方式
`/models` 返回 HTML	`base_url` 少了 `/v1`	改成 `https://xxx/v1`
模型调用失败	模型名不存在	检查 `/v1/models` 返回列表
改了 key 仍无效	Hermes 进程未重启	完全退出后重开
配置里显示 `***`	密钥被脱敏	正常现象，不代表 key 丢失
直接改 YAML 不生效	Hermes 使用加密存储	用 `hermes config set` 写入

十、安全建议

不要在公开文章、截图或群聊里暴露真实 API Key。

如果 key 已经出现在聊天记录、截图或日志中，建议立即去服务商后台重新生成一个新的 key，并废弃旧 key。

更安全的做法是使用环境变量：

key_env: OPENAI_API_KEY

然后把真实密钥放到环境变量中，而不是写进配置文件。

总结

Hermes 配置自定义 API endpoint 时，重点检查四件事：

1. base_url 是否带 /v1  
2. API Key 是否有效  
3. 模型名是否存在  
4. 修改后是否重启 Hermes

大多数“中转无法使用”的问题，最终都出在 base_url 和密钥写入方式上。

推荐排查顺序是：

先测 /v1/models  
再确认模型名  
再用 hermes config set 写入 key  
最后重启 Hermes

这样可以最大程度避免盲目修改配置导致的问题。

群友提供原文：

想配置自定义 API endpoint好的。配置自定义 API endpoint（"bring your own endpoint"）。我先了解两件事：① Hermes 的 endpoint 配置格式，② 你当前的 config.yaml 结构长什么样，这样才能准确地帮你改。let me 并行读取当前配置和官方文档：Read a file, browsed the web我读到了关键信息 —— 你其实已经配置过一个自定义 endpoint 了。当前配置如下：# 当前激活的模型model:  base_url: https://openai.mozhevip.top/v1  default:  gpt-5.5  provider: custom:mozhevip  api_key:  ''# 已注册的自定义 providercustom_providers:  - name:     mozhevip    base_url: https://openai.mozhevip.top/v1    api_key:  '***'          # 已设置（出于安全已脱敏）    model:    gpt-5.5    key_env:  ''也就是说，现在 Hermes 正用着 mozhevip 这个自定义端点（https://openai.mozhevip.top/v1，模型 gpt-5.5）。所以在动手前，我需要先搞清楚你具体想做什么。先让我查一下 Hermes 管理自定义 provider 的正确命令（推荐用 CLI 命令而不是直接改 YAML —— 因为 Hermes 正在运行，直接改文件可能在进程退出时被覆盖掉）：Used PowerShellhermes model 是交互式选择器（没法脚本化驱动），但 hermes config set 可以非交互地设置单个值。让我看一下它的具体语法：Used PowerShellhermes config set <key> <value> 可以非交互地设置任意点路径的配置项（比如 model.base_url、model.default）。机制我都清楚了。现在关键是确认你的具体意图 —— 因为你已经有一个能用的自定义 endpoint 了，"配置" 可能指好几种不同操作。我用一个问题来确认：Asked操作类型你已经配置了一个自定义 endpoint(mozhevip → https://openai.mozhevip.top/v1, 模型 gpt-5.5)。这次你想做哪种操作?修改现有的 mozhevip明白，修改现有的 mozhevip 端点。现在请告诉我你想改哪些字段、改成什么。三个字段你只需要填要改的，不改的留空即可：字段	当前值	改成base_url（接口地址）	https://openai.mozhevip.top/v1	？model（模型名）	gpt-5.5	？api_key（密钥）	（已设置，脱敏）	？几点说明：API key 的安全方式 —— 如果你不想把密钥直接贴在对话里，有两个更安全的选择：你自己跑一条命令我提供的命令（密钥不经过我）；或用环境变量：把密钥放进 .env，配置里设 key_env: 你的变量名，配置文件里就不存明文。当然你也可以直接发给我，我帮你写进去 —— 你决定。生效需要重启 —— Hermes 桌面端和会话现在正在运行，改完配置后，正在跑的会话要重启才会读到新值（我改的是磁盘上的 config.yaml）。我会同时更新 model: 区块和 custom_providers 列表里的 mozhevip 条目，保证两处一致。请回复你要改的字段和新值，比如："模型改成 gpt-5.5-turbo""地址换成 https://xxx/v1，key 换成 sk-xxx""只把 key 换成 sk-新的密钥"https://openai.mozhevip.top  sk-2d3XXXXXXXXXXXXXXXXXXX收到。我理解为：API key → 换成新的 sk-2d3XXXXXXXXXXXXXXXXXXXbase_url → 你给的是 https://openai.mozhevip.top（注意：少了 /v1，当前是 https://openai.mozhevip.top/v1）model → 没提，保持 gpt-5.5那个 /v1 很关键 —— OpenAI 兼容接口通常要求 base_url 带 /v1（客户端会在后面拼 /chat/completions）。与其猜，我直接测一下这个端点+新 key 到底哪种地址能通，顺便验证 key 是否有效（只发只读的 GET /models 请求，密钥只发给该服务本身）：Used PowerShell测试结果很关键，证实了 /v1 必须保留：地址	结果https://openai.mozhevip.top/v1/models	✅ 200 + JSON 模型列表（这才是 API，新 key 有效）https://openai.mozhevip.top/models（你给的，无 /v1）	❌ 200 但返回的是网页 HTML，不是 API所以你少打的 /v1 是必需的 —— 去掉它请求会打到网站首页而不是接口。base_url 我保留 https://openai.mozhevip.top/v1，实际只改 API key（你给的新 key 已验证可用，模型列表里有 gpt-5.3-codex、codex-auto-review 等）。在写入前，我先搞清楚 Hermes 是怎么存这个 key 的 —— 配置文件里那条 api_key: '***' 是脱敏占位还是真实存储，决定了我该用 CLI 命令还是直接改文件。让我查一下密钥存储机制，并确认 gpt-5.5 在不在可用模型里：Used PowerShell完全清楚了。关键发现：config.yaml 第 608 行真的就是 api_key: '***'（原始文件内容）—— 说明 Hermes 把真实密钥存在单独的加密存储里，配置文件只留 *** 占位符（因为 security.redact_secrets: true）。所以不能直接改 YAML，得用 Hermes 自己的命令写入，否则它读不到。mozhevip 的 key_env 是空的，密钥不在 .env 里（.env 里那些 OPENAI_API_KEY/DEEPSEEK_API_KEY 是别的 provider 的）。✅ gpt-5.5 确认在可用模型列表里（共 5 个：gpt-5.3-codex、gpt-5.4、gpt-5.4-mini、gpt-5.5、codex-auto-review）。我用官方的 hermes config set 来写入新 key（它会正确存进加密存储）。先备份配置，再设置：Used PowerShellhermes config set 支持列表索引路径，写入成功（exit=0，确认 ✓ Set custom_providers.0.api_key = sk-…612）。让我读回配置确认实际写入状态，并看一下 model: 区块是否也需要同步：Readconfig.yaml(1–8, 604–611)新 key 已正确写入 custom_providers 的 mozhevip 条目（第 608 行），结构与之前一致：custom_providers:- name: mozhevip  base_url: https://openai.mozhevip.top/v1   # /v1 保留 ✓  api_key: sk-2d33…c92612                     # ← 新 key 已写入  model: gpt-5.5                              # 保持不变 ✓  key_env: ''model: 区块的 api_key 保持空 —— 这跟你原来的结构完全一致（provider 是 custom:mozhevip，Hermes 会从 custom_providers 条目里取 key），所以无需改动。最后做一次端到端验证：用新 key 真正调一次 gpt-5.5 对话接口，确认不只是能列模型、而是能真正推理：Used PowerShell✅ 配置完成，并已端到端验证通过。最终验证结果（用新 key 真实调用了一次 gpt-5.5）：STATUS : OKmodel  : gpt-5.5reply  : HERMES_OK      ← 模型按指令准确回复usage  : prompt=321  completion=8改了什么项目	结果API key	已更新为新 key sk-2d33…c92612（通过官方 hermes config set 写入，已验证有效）base_url	保留 https://openai.mozhevip.top/v1 —— 你给的地址漏了 /v1，实测去掉会打到网页而非 API，所以没采用model	保持 gpt-5.5（确认在可用模型列表中）结构	写在 custom_providers[mozhevip].api_key，与你原有结构一致，model: 区块无需改动备份	旧配置已备份到 config.yaml.bak.manual_20260607_172612，需要可随时回滚⚠️ 你需要做一件事：重启 Hermes现在正在运行的 Hermes（桌面应用 + CLI 会话 + 网关）内存里还是旧 key，磁盘配置已更新但运行中的进程不会自动重载。要让新 key 生效：完全退出 Hermes 桌面应用（托盘图标右键 → 退出），关闭正在跑的 CLI 会话；重新打开即可，新 key 自动加载。小提示：当前 key 在 config.yaml 里是明文（之前那条 *** 是 Hermes 对旧 key 的脱敏存储形式）。重启后 Hermes 很可能会自动把它重新脱敏成 *** 并转入加密存储 —— 这是正常行为，不影响使用。需要的话，我可以帮你确认重启后进程是否都干净重载了。

预览时标签不可点