DeepAI Paper Hermes Agent 教程,Hermes 模型与 Provider API Hermes Provider 兼容性排错：reasoning_content、custom headers、上下文长度和 api_mode 继承

Hermes Provider 兼容性排错：reasoning_content、custom headers、上下文长度和 api_mode 继承

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午2:54
Categories:

把 Hermes Agent 接到 DeepAI 或其他 OpenAI-compatible API 中转站时，很多人以为“兼容 OpenAI API”就等于所有行为完全一样。

实际不是。

OpenAI-compatible 主要解决的是接口形态：/v1/chat/completions、messages、model、stream、Authorization header 这些大框架。

但不同 provider、聚合商、推理模型、辅助任务路径，在细节上仍然会有差异：

  • 有的 thinking 模型要求回放 reasoning_content；
  • 有的中转站在 Cloudflare / WAF 后面，需要 User-Agent 或自定义 headers；
  • 有的 custom provider 上下文长度没有被辅助压缩逻辑正确识别；
  • 有的 delegate/subagent 切换 provider 时，不应该继承父模型的 api_mode；
  • 有的聚合商虽然能用 Custom Endpoint，但缺少一等 provider UX。

这篇继续基于 Hermes GitHub Issues / PR，专门讲 Provider 兼容性层面的排错。

先讲清：OpenAI-compatible 不是“所有 provider 细节都一样”

DeepAI API 中转站的价值，是提供统一的 OpenAI-compatible 入口，让 Dify、Hermes、Open WebUI、LobeChat 等工具能用相似方式接入不同模型。

对 Hermes 来说，基础配置一般是：

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

但 Hermes 是 Agent，不只是发一轮聊天请求。它还会做：

  • 工具调用；
  • 多轮历史回放；
  • context compression；
  • title generation；
  • background review；
  • delegate/subagent；
  • provider/profile 切换；
  • vision / non-vision 消息预处理。

这些路径都会碰到 provider 兼容性细节。

所以当你看到 400、403、上下文压缩异常、子 agent 请求失败，不要只检查 Base URL 和 Key。还要看 Hermes 是通过哪条路径调用 provider。

Issue 1：thinking 模型可能要求 reasoning_content 回传

相关 PR：

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

这个 PR 处理的是 Xiaomi MiMo thinking mode。

问题描述很有代表性：MiMo 通过 OpenAI 的 reasoning_content 字段输出推理内容，并且在 replay history 时，要求每个 assistant tool-call message 都带回 reasoning_content。

如果没有回传，后续 API 调用会失败：

HTTP 400: The reasoning_content in the thinking mode must be passed back to the API

PR 里提到，它的形态和 DeepSeek、Kimi / Moonshot thinking modes 类似。

这类问题说明：即便接口是 OpenAI-compatible，不同 reasoning / thinking 模型对历史消息字段的要求也可能不同。

对 Hermes 用户意味着什么

如果你用的是普通聊天模型，可能永远不会碰到这个问题。

但如果你用的是 reasoning / thinking 模型，并且 Hermes 发生了：

  • 第一轮能回答；
  • 工具调用后第二轮失败；
  • 多轮历史 replay 后报 400；
  • 错误里出现 reasoning_content；
  • only after tool call 才出错；

那就要怀疑：Hermes 对该 provider 的 reasoning_content echo-back 支持不完整。

这不是 DeepAI API Key 问题，也不是 Base URL 问题。

它是 provider-specific message replay 兼容性。

排查建议

  • 换普通非 thinking 模型测试；
  • 缩短对话，避免工具调用，看是否还报错；
  • 查错误是否包含 reasoning_content；
  • 查 Hermes 版本是否已支持该 provider 的 thinking mode；
  • 如果通过 DeepAI 使用某个 reasoning 模型，确认 DeepAI 返回字段与 Hermes 当前适配是否匹配。

Issue 2：Cloudflare / WAF 后的 Custom Provider 可能需要 custom headers

相关 Issue：

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

这个问题前面文章提过，但放在 Provider 兼容性里非常关键。

Issue 说的是：Custom OpenAI-compatible provider 位于 Cloudflare WAF 后面时，Hermes 因为没有发送合适 User-Agent 或 custom headers，被 403 拦截。

核心点包括：

  • headers 没有被列入 custom provider 有效配置字段；
  • 未知 provider 的 default_headers 可能被移除；
  • switch_model 时 headers 可能丢失；
  • 用户希望在 config.yaml 里给 custom provider 配 headers。

这类问题对中转站用户很现实。

因为很多 OpenAI-compatible 服务不只是裸 API，它们前面可能有：

  • Cloudflare；
  • Nginx；
  • WAF；
  • API Gateway；
  • 风控规则；
  • 聚合商自己的请求策略。

怎么区分 Key 错和 Header 问题

看状态码和对比请求。

401 更像鉴权失败
403 更像被策略拒绝

如果 curl 能通，但 Hermes 403，要比较：

  • curl 有没有 User-Agent；
  • Hermes 请求有没有默认 headers；
  • Hermes 是否在 provider 切换时丢 headers；
  • base_url 是否经过 Hermes 改写；
  • 请求到底从 main agent、auxiliary client 还是 background task 发出。

对 DeepAI 用户的实践建议

DeepAI 标准接入仍建议：

https://api.deepai.wang/v1
Authorization: Bearer YOUR_DEEPAI_API_KEY

如果 DeepAI curl 测试正常，而 Hermes 某条路径 403，就要查 Hermes 请求路径，不要急着重置 Key。

尤其是：

  • main agent 正常，auxiliary 失败；
  • 当前模型正常，switch_model 后失败；
  • 一个 provider 正常，另一个 custom provider 403；
  • 只有某些网络环境下 403。

这都可能是 provider headers / WAF / client path 问题。

Issue 3：聚合商能用 Custom Endpoint，但缺少一等 provider 体验

相关 Issue：

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

这个 Issue 是请求添加 AI/ML API 作为内置 provider。

它的核心不是“Custom Endpoint 不能用”。相反，Issue 里明确说：

Using a custom OpenAI-compatible endpoint technically works

但问题是 UX 不够好：

  • provider 不出现在 hermes model 选择列表里；
  • 无法通过环境变量自动识别，比如 AIMLAPI_API_KEY；
  • 不进入标准 provider/model flow；
  • doctor/status/model normalization 等体验不完整；
  • 聚合商特有的 model catalog 和价格体系不容易表达。

这个问题对 DeepAI 也有启发。

DeepAI 可以通过 Custom Endpoint 接入 Hermes，这是最直接、最通用的路径。但“能接入”和“成为 Hermes 内置一等 provider”是两件事。

Custom Endpoint 的优点

  • 不等 Hermes 官方合并 provider；
  • 任何 OpenAI-compatible API 都能先用；
  • 配置简单，适合快速测试；
  • 对 DeepAI 这类中转站非常实用。

Custom Endpoint 的限制

  • provider 名称、模型列表、环境变量自动识别不一定完善；
  • doctor/status 的提示可能不如内置 provider；
  • 特殊 headers、特殊 api_mode、特殊 reasoning 字段可能需要 Hermes 适配；
  • 上下文长度、vision 能力、pricing 等元信息可能无法自动识别。

所以文章里建议：生产使用 DeepAI 接 Hermes，可以先走 Custom Endpoint，但要保留 provider 兼容性排查意识。

Issue 4：custom_providers 上下文长度没传给 compression 检测

相关 PR：

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

这个 PR 修的是 auxiliary / compression 路径的问题。

它的描述很短，但非常关键：

get_model_context_length 接受 custom_providers，这样用户使用 custom provider 配置时，可以获得正确的 context length。

但 _check_compression_model_feasibility 调用它时没有传 custom_providers，导致 custom provider 用户在压缩决策中拿到错误的上下文长度。

这意味着什么？

Hermes 主对话能跑，不代表 context compression 的判断也一定正确。

如果上下文长度识别错，可能出现：

  • 该压缩时没压缩；
  • 不该压缩时提前压缩；
  • 压缩模型可用性判断错误；
  • 长上下文任务表现不稳定；
  • custom provider 看起来“上下文很短”。

对 DeepAI 用户怎么排查

如果你用 DeepAI 接入长上下文模型，但 Hermes 表现得像上下文很小：

  • 查 Hermes 是否识别了 custom provider 的 context length；
  • 查 compression model feasibility 日志；
  • 查 auxiliary compression 是否走了同一 provider 配置；
  • 升级到包含 custom_providers forwarding 修复的版本；
  • 临时减少上下文长度压力，观察是否稳定。

这个问题不一定是 DeepAI 模型上下文能力不足，而可能是 Hermes 辅助路径没有正确读取 custom provider 元信息。

Issue 5：delegate/subagent 切 provider 时不应继承父 api_mode

相关 PR：

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

这个 PR 处理的是 delegate_task 跨 provider 切换时的 api_mode 继承问题。

描述很直接：当 delegate_task 在 session 中切换 provider 时，child agent 继承了 parent 的 api_mode，比如父 provider 使用 codex_responses。

如果新 provider 不支持这个 wire protocol，比如切到 OpenRouter，就会请求失败。

修复方向是：

  • provider 不变时保留 api_mode；
  • provider 改变时不要继承父 api_mode。

为什么这对中转站用户重要

Hermes 会用 delegate/subagent 做复杂任务。

如果主模型、辅助模型、子 agent 模型来自不同 provider，api_mode 继承错误就会导致：

  • 主会话正常；
  • 子任务失败；
  • delegate 后突然 400 / 404 / 415；
  • 错误像“provider 不支持这个接口”；
  • 用户误以为 DeepAI 或中转站不兼容。

实际可能只是 Hermes 把父 provider 的协议模式带到了不该带的地方。

排查建议

如果你看到“主聊天正常，delegate/subagent 失败”，优先查：

  • child agent 用的是哪个 provider；
  • child agent 是否继承了 parent api_mode；
  • 父 provider 和子 provider 是否使用不同 wire protocol；
  • Hermes 版本是否包含这个修复。

Provider 兼容性问题速查表

现象可能原因优先检查
thinking 模型工具调用后 400reasoning_content 未回传Hermes 版本、provider thinking mode 支持
curl 正常但 Hermes 403custom headers / WAF / CloudflareHermes 请求 headers、provider path
Custom Endpoint 能用但 UX 不完整非内置 providerprovider registry、doctor/status、env auto-detect
长上下文模型像短上下文custom_providers 未传给 compression 检测context length、compression logs
主 agent 正常，delegate 失败api_mode 跨 provider 继承错误child provider、api_mode、wire protocol

DeepAI 接 Hermes 的实用建议

如果你用 DeepAI API 中转站作为 Hermes 的上游模型服务，建议这样配置和排错。

1. Base URL 只填到 /v1

https://api.deepai.wang/v1

不要填：

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

2. 模型 ID 以 DeepAI 控制台为准

不要照抄别的 provider 文档里的模型名。

如果工具不能直接证明某模型在 DeepAI 可用，就不要在文章或配置里虚构。

3. 先用 curl 验证，再查 Hermes 路径

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": "reply ok"}]
  }'

curl 通，只说明 DeepAI 上游服务可用。

Hermes 仍然可能在 auxiliary、compression、delegate、thinking replay、headers 等路径出问题。

4. 对 reasoning 模型保持谨慎

如果你使用 reasoning / thinking 模型，特别要关注：

  • reasoning_content；
  • tool call history replay；
  • 多轮对话；
  • Hermes 是否支持该 provider 的 thinking mode。

5. 长任务和多 agent 场景要测 auxiliary / delegate

不要只测一句 hello。

至少测试：

  • 多轮对话；
  • 一次工具调用；
  • 一次长上下文压缩；
  • 一次 delegate/subagent；
  • 一次 title generation 或 session summary。

这样才能发现 Custom Endpoint 在 Hermes 全链路中的兼容性问题。

相关 Issue / PR

Xiaomi MiMo reasoning_content echo-back：

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

Custom Provider headers / Cloudflare 403：

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

AI/ML API provider support：

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

custom_providers context-length forwarding for compression：

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

delegate/subagent provider api_mode inheritance：

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

DeepAI API 中转站：

https://api.deepai.wang/

Hermes 接入 DeepAI 基础教程：

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

总结

OpenAI-compatible 不等于 provider 细节完全一致。

Hermes 作为 Agent，会在主对话之外调用辅助模型、压缩上下文、回放工具历史、切换 provider、委派子 agent。每一条路径都可能触发 provider 兼容性问题。

reasoning_content 400、Cloudflare 403、context length 误判、api_mode 继承错误，都不是简单的“DeepAI Key 错了”。

用 DeepAI 接 Hermes，最稳的方法是：先验证 /v1/chat/completions，再测试 Hermes 的主对话、工具调用、compression、auxiliary 和 delegate。只有这样，才能确认不是“能聊一句”，而是整条 Agent 链路都稳。

Related Post

Ollama 本地模型记不住上一轮？Hermes Agent num_ctx 与 2048 上下文截断排错指南Ollama 本地模型记不住上一轮？Hermes Agent num_ctx 与 2048 上下文截断排错指南

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午4:53

Hermes Agent 接入 Ollama 后同一会话记不住上一轮？这可能不是 memory tool 坏了，而是 Ollama num_ctx 回落到 2048 导致历史被服务端静默截断。本文解释 context_length、ollama_num_ctx、/api/show 探测失败和 PR #19613 的修复方向。

Read MoreRead More

Hermes Agent 跨平台排错：Windows 代理 502、Docker 后端残留和飞书表格源码显示Hermes Agent 跨平台排错：Windows 代理 502、Docker 后端残留和飞书表格源码显示

2026年5月14日2026年5月14日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午2:45

基于 Hermes GitHub Issues，总结 Windows 系统代理导致 auxiliary client 502、terminal.backend=local 仍跑 Docker、飞书 Markdown 表格显示源码等跨平台问题，帮助区分 DeepAI 模型层和 Hermes 运行环境层。

Read MoreRead More
Hermes agent deepai custom provider auxiliary.png

Hermes Agent 接入 DeepAI API 中转站：custom Provider 辅助任务走错端点怎么排查Hermes Agent 接入 DeepAI API 中转站：custom Provider 辅助任务走错端点怎么排查

2026年5月31日2026年5月31日| DeepAI Paper 编辑部DeepAI Paper 编辑部| 0 Comment| 下午6:49

Hermes Agent 使用 custom OpenAI-compatible Provider 时，主模型能用但 approval、compression、title generation 等辅助任务 fallback 到错误端点怎么办？本文结合 Hermes Agent GitHub 已关闭 Issue，整理 DeepAI API 中转站接入、config.yaml 显式配置和日志排查方法。

Read MoreRead More