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

Hermes Agent 的模型配置，和 Cherry Studio、Dify 不是一类东西。

Cherry Studio 更像客户端；Dify 更像应用搭建平台；Hermes Agent 是一个能长期运行、能用终端、文件、记忆、技能和消息网关的 Agent。也就是说，你给 Hermes 配模型，不只是为了“聊两句”，而是在给一个会执行任务的代理选择大脑。

所以接入 DeepAI 时，重点不是把 Base URL 填进去就完了，而是先确认三件事：

Hermes 版本支持 Custom Endpoint；
DeepAI 的接口按 OpenAI Compatible API 使用；
选的模型上下文足够 Hermes 做多步工具调用。

我看了 NousResearch/hermes-agent 的 GitHub README 和官方文档。官方 README 里明确写了 Hermes 可以使用 OpenRouter、OpenAI、Hugging Face、Nous Portal，或者 “your own endpoint”；Quickstart 里也把 Custom Endpoint 标成可接 vLLM、SGLang、Ollama 或任何 OpenAI-compatible API 的入口。DeepAI 就按这个路径接。

GitHub 地址：

https://github.com/NousResearch/hermes-agent

DeepAI API 地址：

https://api.deepai.wang/

这篇只解决一个问题

把 Hermes Agent 的主模型切到 DeepAI 的 OpenAI Compatible API。

不讲 Telegram、Discord、微信网关；不讲 Skills；不讲 OpenClaw 迁移；不讲 API Server 反向暴露。那些是 Hermes 跑起来之后的下一层。

本文示例值：

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

先确认 Hermes 装得起来

Hermes 官方 GitHub README 给的 Linux / macOS / WSL2 安装命令是：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Windows 原生也有 PowerShell 安装方式，但官方 README 同时提醒：Native Windows 仍是 early beta；如果想稳，Windows 用户优先用 WSL2。

安装结束后，重新加载 shell：

source ~/.bashrc
# 或者
source ~/.zshrc

然后运行：

hermes doctor

如果 doctor 已经报 Python、Node、uv、权限或 PATH 问题，先修 Hermes 本身。不要急着配置 DeepAI，否则你分不清是模型没通，还是 Hermes 环境没好。

Hermes 的配置文件在哪里

官方配置文档写得比较清楚：Hermes 的配置主要在 ~/.hermes/ 下面。

常见文件是：

文件	放什么
`~/.hermes/config.yaml`	模型、终端后端、工具、上下文等非密钥配置
`~/.hermes/.env`	API Key、Token、Bot Token 等密钥
`~/.hermes/SOUL.md`	Agent 个性与身份
`~/.hermes/memories/`	长期记忆
`~/.hermes/logs/`	错误日志、gateway 日志

官方也强调：密钥放 .env，普通配置放 config.yaml。

更省事的方式是用命令：

hermes config set KEY VALUE

Hermes 会尽量把值放到正确位置。比如 API Key 会进 .env，普通配置会进 config.yaml。

推荐方式：用 hermes model 选择 Custom Endpoint

官方 Quickstart 里建议：配置模型优先用 hermes model。

原因很简单：Hermes 的 provider 比普通聊天客户端复杂，手改 YAML 很容易漏字段。尤其是 Custom Endpoint，还涉及 provider、base_url、model、context length、API Key。

运行：

hermes model

在交互向导里找类似选项：

Custom Endpoint

官方文档说明 Custom Endpoint 可以用于：

vLLM；
SGLang；
Ollama；
任何 OpenAI-compatible API。

选择 Custom Endpoint 后，按提示填：

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

这里不要写：

https://api.deepai.wang/v1/chat/completions

Hermes 需要的是 OpenAI-compatible 的 Base URL，通常不是完整接口路径。

如果你要手动写 config.yaml

更推荐 hermes model，但有些人部署服务器时就是想手写配置。

可以参考这个方向：

model:
  provider: "custom"
  default: "YOUR_MODEL_ID"
  base_url: "https://api.deepai.wang/v1"

API Key 不建议直接写在这个 YAML 里。放到：

~/.hermes/.env

示例：

CUSTOM_API_KEY=YOUR_DEEPAI_API_KEY

不过这里有一个要注意的地方：不同 Hermes 版本对 Custom Endpoint 的密钥变量名可能有调整。最稳的是用 hermes model 交互向导保存一次，然后再打开 ~/.hermes/config.yaml 和 ~/.hermes/.env 看它实际写了什么。

不要照搬别人旧版本教程里的变量名。

Hermes 对模型上下文有要求

这是 Hermes 和普通聊天工具差异很大的地方。

官方 Quickstart 里写了一个很关键的限制：Hermes Agent 需要至少 64K tokens 的上下文窗口。上下文太小的模型，不适合 Hermes 做多步工具调用和长会话，启动时可能会被拒绝。

所以你在 DeepAI 控制台选模型时，不要只看价格，也要看上下文长度。

建议顺序：

1. 先选一个上下文足够的聊天模型； 2. 在 Hermes 里完成第一次普通对话； 3. 再让它做文件、终端、项目分析这些多步任务； 4. 如果长任务频繁失败，再考虑换更大上下文模型。

不要一上来就拿小上下文模型跑 Hermes，然后把失败归因到 DeepAI。

接入后怎么验证

Hermes 官方 Quickstart 的思路很对：先验证一个普通聊天，不要马上加网关和自动化。

配置完 DeepAI 后，运行：

hermes

或者：

hermes --tui

进去后先问一个很短的问题：

用一句话说说你当前使用的模型提供商是什么。

如果能正常回答，再试一个带工具倾向但风险低的问题：

查看当前目录，告诉我这里像不像一个项目目录，不要修改文件。

Hermes 如果能完成这个任务，说明：

DeepAI 模型调用正常；
Hermes 会话能启动；
工具调用链没有立刻崩；
模型上下文至少能支撑基础任务。

这时再考虑接入 Telegram、Discord、Slack、WhatsApp、Signal 或 API Server。

用 curl 先排除 DeepAI API 问题

如果 Hermes 配好后没响应、空响应、或者提示 provider 错误，先别在 Hermes 里乱改。

用 curl 测 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 能通，Hermes 不通，重点查 Hermes 的 provider、base_url、model 和 .env。

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

这篇有更完整的 curl / Python 测试方法：

从 curl 到 Python：如何确认 DeepAI OpenAI 兼容接口真的能用

常见卡点

1. 把 Hermes 当普通聊天壳

Hermes 不是只把 prompt 发给模型。它会用工具、读文件、跑命令、管理记忆和技能。模型太弱或上下文太小，体验会明显差。

2. Base URL 填成完整 endpoint

不要填：

https://api.deepai.wang/v1/chat/completions

优先填：

https://api.deepai.wang/v1

3. 手写配置但变量名抄错

Hermes 还在快速迭代，GitHub 上的 README 和官方文档比二手教程更可信。

如果手写配置不生效，先用：

hermes model

让它自己写一遍。

4. Windows 原生环境踩坑

官方 README 说 Windows native 是 early beta。想少踩坑，Windows 用户优先 WSL2。

5. 还没跑通主聊天就接网关

Hermes 官方 Quickstart 也建议：普通 chat 先跑通，再加 gateway、cron、skills、voice、routing。

如果主模型都没通，Telegram / Discord / WhatsApp 接得再好也没用。

和 Dify、Cherry Studio 的区别

DeepAI 接入 Hermes 时，不要完全照搬 Dify 或 Cherry Studio 的思路。

工具	更像什么	DeepAI 接入重点
Cherry Studio	桌面聊天客户端	模型列表、Base URL、模型是否显示
Dify	AI 应用/Workflow 平台	LLM、Embedding、Rerank、工作流节点
Hermes Agent	长期运行的工具型 Agent	Custom Endpoint、上下文、工具调用、终端安全

所以 Hermes 文章不能只写“填 Key 就能用”。它真正需要关注的是：这个模型能不能稳定支撑 Agent 做多步任务。

如果你从 OpenClaw 迁移到 Hermes

Hermes GitHub README 里还提到：如果你来自 OpenClaw，hermes setup 会检测 ~/.openclaw 并提供迁移；也可以之后运行：

hermes claw migrate
hermes claw migrate --dry-run
hermes claw migrate --preset user-data

它可能迁移 SOUL、记忆、技能、消息设置、allowlist 和部分 API Key。

这里要谨慎：迁移 API Key 前，先确认你真的想把旧环境里的密钥带过去。团队机器或共享服务器上尤其要小心。

最小可用路径

如果你只想最快跑通 Hermes + DeepAI，顺序是：

安装 Hermes
→ hermes doctor
→ hermes model
→ Custom Endpoint
→ Base URL 填 https://api.deepai.wang/v1
→ 填 DeepAI API Key
→ 填 DeepAI 控制台可用模型 ID
→ hermes
→ 发一句短问题测试
→ 再测试一个低风险工具任务

这条路径跑通后，再去加 gateway、API Server、cron、skills。

不要倒过来。

继续阅读

Hermes GitHub：

https://github.com/NousResearch/hermes-agent

DeepAI API 中转站：

https://api.deepai.wang/

如果你还不清楚 OpenAI Compatible API、Base URL、Model ID 的关系：

OpenAI Compatible API 是什么？Base URL、API Key、Model ID 与 DeepAI 接入教程

如果你想先用 curl / Python 确认 DeepAI 接口可用：

从 curl 到 Python：如何确认 DeepAI OpenAI 兼容接口真的能用

如果你还在对比 Dify、Cherry Studio、Open WebUI 这类工具：

DeepAI 与 Cherry Studio、Dify、Open WebUI 的关系：谁负责前端，谁负责 API

收尾

Hermes 接 DeepAI 的关键入口是 Custom Endpoint，不是某个写死的 “DeepAI Provider”。

按官方 GitHub 和文档的说法，Hermes 可以使用自己的 OpenAI-compatible endpoint；DeepAI 的接入就走这条路：https://api.deepai.wang/v1、DeepAI API Key、DeepAI 控制台里的模型 ID。

但 Hermes 是 Agent，不是普通聊天壳。跑通以后，真正要观察的是长任务、工具调用、上下文和稳定性。先让最小聊天成功，再逐层加能力，这是接入 Hermes 最不容易翻车的路线。