Hermes 配置自定义 API Endpoint
解决中转接口无法使用的问题：从验证 endpoint、确认模型、写入密钥到重启应用的完整排查流程。
前言
很多用户在使用 Hermes 时会遇到这样的问题：已有 OpenAI 兼容中转接口和 API Key，但 Hermes 里还是无法正常调用模型。这类问题通常不是接口本身不可用，而是 base_url、模型名、API Key 或 /v1 路径配置不一致导致的。
验证 endpoint 是否可用
在修改 Hermes 配置前，建议先测试 /v1/models。
$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 里的索引。例如第一个 provider 对应 custom_providers.0，第二个对应 custom_providers.1。
base_url 保留 /v1
如果测试发现 https://xxx/v1/models 可以返回模型列表，而 https://xxx/models 返回网页或报错，那么 Hermes 里的 base_url 应该配置为 https://xxx/v1，不要只写 https://xxx。这是很多用户配置失败的主要原因。
完整配置示例
推荐结构如下：
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。
端到端测试
配置完成后，建议用一次真实对话请求验证。
$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 进程不一定会自动重新读取配置。建议完全退出 Hermes 桌面端，关闭相关 CLI 会话，重新打开 Hermes，再次测试模型调用。否则可能出现配置文件已经改了，但 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 时，重点检查四件事：
- base_url 是否带 /v1
- API Key 是否有效
- 模型名是否存在
- 修改后是否重启 Hermes
大多数"中转无法使用"的问题，最终都出在 base_url 和密钥写入方式上。推荐排查顺序是：先测 /v1/models，再确认模型名，再用 hermes config set 写入 key，最后重启 Hermes。
文章来源
本文内容整理自以下原始出处：