Hermes 的 Custom Endpoint 和 API Server 不是一回事：接 DeepAI 前先别搞反

很多人第一次看 Hermes Agent 的文档，会被两个“OpenAI-compatible”绕晕。

一个地方说 Hermes 可以接 Custom Endpoint，也就是接入 OpenAI-compatible 模型服务。另一个地方又说 Hermes 自己可以暴露 OpenAI-compatible API Server，让 Open WebUI、LobeChat、LibreChat、ChatBox 这类前端来连。

这两个方向完全相反。

如果你把 DeepAI 接进 Hermes，DeepAI 是 Hermes 的“上游模型”。

如果你把 Open WebUI 接到 Hermes，Hermes 是 Open WebUI 的“后端 Agent”。

这篇就讲清这件事。因为这里一搞反，后面 Base URL、API Key、/v1、hermes-agent 模型名都会填错。

一句话分清方向

先看这张图：

方向 A：DeepAI → Hermes

Hermes Agent 作为客户端
DeepAI API 中转站作为模型服务

Hermes  --请求模型-->  https://api.deepai.wang/v1

方向 B：Open WebUI → Hermes

Open WebUI 作为前端
Hermes Agent 作为后端 Agent

Open WebUI  --请求 Agent-->  http://localhost:8642/v1

它们都叫 OpenAI-compatible，但含义不一样。

方向 A 解决的是：Hermes 用哪个大模型。

方向 B 解决的是：用户从哪个前端和 Hermes 聊。

方向 A：把 DeepAI 接进 Hermes，当 Hermes 的模型来源

这个方向用的是 Hermes 的模型供应商配置。

官方文档里叫 Inference Providers，里面列了 Nous Portal、OpenRouter、Anthropic、GitHub Copilot、Kimi、MiniMax、DeepSeek、Hugging Face、LM Studio，以及：

Custom Endpoint

DeepAI 接 Hermes，就属于 Custom Endpoint / OpenAI-compatible API 这条路。

你要配置的是：

Base URL: https://api.deepai.wang/v1
API Key: YOUR_DEEPAI_API_KEY
Model ID: DeepAI 控制台里的可用模型

最推荐的入口是：

hermes model

在向导里选择 Custom Endpoint，然后填 DeepAI 的 Base URL、API Key 和模型 ID。

这个方向的关键问题是：Hermes 能不能成功调用 DeepAI 模型。

常见错误包括：

DeepAI Key 填错；
Base URL 填成了完整接口路径；
模型 ID 不是 DeepAI 控制台里的真实 ID；
模型上下文太小，不适合 Hermes；
主 agent 可以用，但后台 auxiliary/review 没继承正确配置。

这类问题要查：

~/.hermes/config.yaml
~/.hermes/.env
~/.hermes/logs/errors.log

如果你只是想让 Hermes 用 DeepAI 当模型，看这篇基础教程更合适：

Hermes Agent 接入 DeepAI 教程：用 Custom Endpoint 配 OpenAI Compatible API

方向 B：把 Hermes 暴露成 API，让 Open WebUI 来连

另一个方向是 Hermes API Server。

官方 API Server 文档说得很明确：它会把 hermes-agent 暴露成一个 OpenAI-compatible HTTP endpoint。Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 等前端都可以把 Hermes 当后端连上。

这时 Hermes 的地址通常是：

http://localhost:8642/v1

注意，这不是 DeepAI 地址。

这里的 API Key 也不是 DeepAI API Key，而是你自己给 Hermes API Server 设置的：

API_SERVER_KEY

你需要在 ~/.hermes/.env 里打开：

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-to-a-strong-secret

然后启动：

hermes gateway

看到类似输出：

[API Server] API server listening on http://127.0.0.1:8642

再在 Open WebUI 里添加 OpenAI 连接：

URL: http://localhost:8642/v1
API Key: 你设置的 API_SERVER_KEY

如果 Open WebUI 跑在 Docker 里，官方文档提醒要把 localhost 换成：

http://host.docker.internal:8642/v1

Linux Docker 没有 Docker Desktop 时，host.docker.internal 可能不解析，要额外加 host mapping，或者用 host network / bridge IP。

最容易填错的两个 API Key

这两个 Key 不是一回事。

位置	应该填什么	用途
Hermes Custom Endpoint	DeepAI API Key	Hermes 调用 DeepAI 模型
Open WebUI 连接 Hermes	API_SERVER_KEY	Open WebUI 调用 Hermes API Server

如果你在 Open WebUI 里填 DeepAI Key，但 URL 却是：

http://localhost:8642/v1

那就是错的。

因为这个地址是 Hermes，不是 DeepAI。

反过来，如果你在 Hermes 的 Custom Endpoint 里填 API_SERVER_KEY，那也错。

因为 DeepAI 不认识这个 Key。

最容易填错的两个 Base URL

Base URL 也有两个。

场景	Base URL
Hermes 调 DeepAI	`https://api.deepai.wang/v1`
Open WebUI 调 Hermes	`http://localhost:8642/v1`

这两个不能互换。

如果你在 Hermes 的模型配置里填：

http://localhost:8642/v1

那 Hermes 会尝试把自己当模型提供商，逻辑就乱了。

如果你在 Open WebUI 的 Hermes 连接里填：

https://api.deepai.wang/v1

那 Open WebUI 连到的是 DeepAI 模型服务，不是 Hermes Agent。你得到的是普通模型对话，不是带终端、文件、记忆和 skills 的 Hermes。

`/v1/models` 看到的模型名也不一样

这点很容易让人误判。

访问 DeepAI：

curl https://api.deepai.wang/v1/models \
  -H "Authorization: Bearer YOUR_DEEPAI_API_KEY"

你期望看到的是 DeepAI 可用模型列表。

访问 Hermes API Server：

curl http://localhost:8642/v1/models \
  -H "Authorization: Bearer YOUR_API_SERVER_KEY"

你通常看到的是：

hermes-agent

或者 profile 名。

官方 API Server 文档也提到：/v1/models 会列出 agent 作为可用模型，默认模型名是 profile 名，默认 profile 下通常是 hermes-agent。

所以 Open WebUI 下拉框里出现 hermes-agent 是正常的。它不是 DeepAI 的模型 ID，而是 Hermes 这个 Agent 后端的名字。

model 字段在 Hermes API Server 里有点“表面”

还有一个细节也容易误会。

Hermes API Server 文档写到：请求里的 model 字段会被接受，但实际使用的 LLM 模型由 Hermes 服务端的 config.yaml 决定。

也就是说，当 Open WebUI 请求：

{
  "model": "hermes-agent",
  "messages": [{"role": "user", "content": "hello"}]
}

这里的 hermes-agent 更像 Open WebUI 看到的后端入口名。

真正 Hermes 背后调用 DeepAI 的哪个模型，要看 Hermes 自己的模型配置。

所以不要在 Open WebUI 里强行填 DeepAI 的真实模型 ID，指望 Hermes 自动切换。先把 Hermes 端的模型配置好。

安全边界：不要把 Hermes API Server 裸奔到公网

DeepAI 是模型 API，Hermes API Server 是你的 Agent API。

区别非常大。

Hermes API Server 后面连着：

终端；
文件操作；
web search；
memory；
skills；
可能还有 cron 和各种消息平台。

官方文档也提醒：API Server 默认绑定在 127.0.0.1，如果绑定到 0.0.0.0 这种非 loopback 地址，一定要设置 API_SERVER_KEY，CORS 也要收窄。

如果只是本机 Open WebUI，优先保持：

API_SERVER_HOST=127.0.0.1

不要为了图方便直接公网开放。

如果必须远程访问，至少要考虑：

强随机 API_SERVER_KEY；
反向代理 HTTPS；
IP allowlist；
VPN / Tailscale；
不要开放不必要的 CORS origin；
定期看 Hermes 日志。

这不是普通聊天 API，泄露后风险更高。

排错时按方向查

Open WebUI 里没有模型

这属于方向 B。

查：

curl http://localhost:8642/health
curl http://localhost:8642/v1/models \
  -H "Authorization: Bearer YOUR_API_SERVER_KEY"

如果 health 正常但 models 不出来，确认 Open WebUI 里 URL 有没有带 /v1。

Open WebUI 官方 Hermes 文档也强调：连接测试通过但模型不加载，通常是少了 /v1。

Hermes 里模型调用失败

这属于方向 A。

查 DeepAI：

curl https://api.deepai.wang/v1/chat/completions \
  -H "Authorization: Bearer YOUR_DEEPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "回复 ok"}]
  }'

curl 不通，先修 DeepAI Key、模型 ID、网络。

curl 能通，Hermes 不通，再查 Hermes provider 配置。

Open WebUI 能连，但回答很慢

这不一定是故障。

Open WebUI 官方文档也提醒：Hermes Agent 可能在返回最终答案前执行多个工具调用，比如终端、文件、搜索。复杂任务慢是正常的。

你要判断它是在“卡住”，还是在“做事”。

看 Hermes 终端输出、gateway 日志，以及 Open WebUI 里是否有工具进度提示。

一个完整链路长什么样

如果你同时用了 DeepAI、Hermes、Open WebUI，真实链路是：

用户
  ↓
Open WebUI
  ↓  http://localhost:8642/v1 + API_SERVER_KEY
Hermes API Server / Gateway
  ↓
Hermes Agent 决定是否用工具
  ↓
Hermes 模型 provider
  ↓  https://api.deepai.wang/v1 + DEEPAI_API_KEY
DeepAI API 中转站
  ↓
底层大模型

所以排错要从链路上定位。

Open WebUI 连不上，不一定是 DeepAI。

Hermes 主模型失败，不一定是 Open WebUI。

工具执行慢，不一定是模型慢。

403/401，也要先看是哪一段的 Key 错。

结论

Hermes 里有两个 OpenAI-compatible：

一个是 Custom Endpoint，用来让 Hermes 调 DeepAI 这样的模型服务。

另一个是 API Server，用来让 Open WebUI、LobeChat 这样的前端调 Hermes。

前者的地址是：

https://api.deepai.wang/v1

后者的地址通常是：

http://localhost:8642/v1

前者用 DeepAI API Key，后者用 API_SERVER_KEY。

只要把这两个方向分清，Hermes + DeepAI + Open WebUI 的配置就不会乱成一团。