Hermes Agent auxiliary 报 HTTP 404？anthropic_messages、base_url 与 /v1 路径改写排错指南

如果你在 Hermes Agent 里配置了一个 Anthropic-native 或 Kimi/Claude 风格的自定义 endpoint，主流程看起来没问题，但辅助任务突然全部失败：

Title generation failed: Cannot POST /v1/chat/completions

或者日志里出现：

Auxiliary title generation failed: HTTP 404

并且你的配置里明明写的是：

api_mode: anthropic_messages
base_url: http://localhost:6655/anthropic/

那就要警惕：Hermes Agent 的 auxiliary client 可能把你的 /anthropic/ endpoint 错误改写成了 OpenAI 风格的 /v1，导致请求打到了不存在的路由。

这篇文章基于 NousResearch/hermes-agent issue #17086，整理一个非常典型的 404 endpoint path / api_mode mismatch 排错案例。

适合搜索关键词：Hermes Agent auxiliary HTTP 404 anthropic_messages、Cannot POST /v1/chat/completions Hermes、anthropic_messages base_url /anthropic rewritten to /v1、Hermes title_generation 404 custom endpoint、AnthropicAuxiliaryClient 404。

先给结论：这不是 API Key 问题，而是请求路径被改成了另一种协议

HTTP 401 通常是认证问题；HTTP 404 更多时候是 URL path 或 API mode 不匹配。

在 issue #17086 里，用户配置的是 Anthropic Messages 风格的 auxiliary endpoint：

auxiliary:
  title_generation:
    provider: custom
    base_url: http://localhost:6655/anthropic/
    api_mode: anthropic_messages
    model: claude-haiku

预期行为是：

保留 /anthropic/ 路径；
使用 Anthropic Messages client；
请求 Anthropic-native proxy 支持的接口。

但问题路径里，custom provider branch 会把 explicit_base_url 传入 _to_openai_base_url()：

custom_base = _to_openai_base_url(explicit_base_url).strip()

于是：

http://localhost:6655/anthropic/

被改写成：

http://localhost:6655/v1

然后 auxiliary 任务发起 OpenAI-style 请求：

POST /v1/chat/completions

但你的代理只支持 Anthropic-native 路由，不支持 OpenAI /v1/chat/completions，所以返回：

Cannot POST /v1/chat/completions

这就是为什么它看起来像“模型不可用”，实际却是“客户端把路由改错了”。

典型报错现象

你可能会看到：

WARNING agent.title_generator: Title generation failed: <!DOCTYPE html>
<html><body><pre>Cannot POST /v1/chat/completions</pre></body></html>

或者：

Auxiliary title generation failed: HTTP 404

也可能不是 title generation，而是这些 auxiliary 任务之一：

title_generation
compression
session_search
vision
web_extract
其他依赖 auxiliary client 的后台任务

只要它们走的是同一条 custom auxiliary client 路径，就可能一起失败。

为什么会只在 auxiliary 任务里出问题？

Hermes Agent 内部对主模型和 auxiliary 任务可能使用不同的 client 构造逻辑。

issue #17086 指向的关键点是：resolve_provider_client() 的 custom provider branch 对 explicit_base_url 做了 OpenAI 化改写，却没有在这一条路径里正确尊重：

api_mode: anthropic_messages

而其他路径已经有类似 guard，例如：

_try_custom_endpoint()
named provider branches

这导致同样是 api_mode: anthropic_messages，在不同路径里的行为不一致。

404 和 401 不一样：不要用错排查方向

前一类 Hermes auxiliary 问题常见是：

401 Missing Authentication header

它通常说明请求没有带 Authorization header，常见原因是 provider:auto + base_url + 空 api_key 被解析成 custom + api_key=None。

但 #17086 这类是：

404 Cannot POST /v1/chat/completions

它通常说明：

请求确实发出去了；
但打到了错误 path；
客户端用 OpenAI /v1/chat/completions 去请求 Anthropic-native endpoint；
代理没有这个路由，所以返回 404。

可以按这个表快速判断：

报错	更可能的原因	优先检查
401 Missing Authentication header	没带 API Key	`api_key`、环境变量、provider resolution
401 Invalid API key	Key 不正确或过期	Key 内容、权限、额度
404 Cannot POST /v1/chat/completions	path/API mode 错	`base_url`、`api_mode`、是否被改写到 `/v1`
400 Bad Request	请求体协议错	messages/tools/thinking 字段

复现配置：/anthropic 被改写成 /v1

问题配置大致是：

auxiliary:
  title_generation:
    provider: custom
    base_url: http://localhost:6655/anthropic/
    api_mode: anthropic_messages
    model: claude-haiku

如果代理真实支持的是：

/anthropic/messages

或者类似 Anthropic Messages 风格路由，那么你不希望 Hermes 把它变成：

/v1/chat/completions

但问题版本里，由于 _to_openai_base_url() 参与了 custom auxiliary path，路径可能被 OpenAI 化。

修复状态：merged commit 4e296dcdd

这个 issue 已 closed/completed，评论里给出更明确的修复信息：

Fixed by #17467
merged as commit 4e296dcdd
root cause：_to_openai_base_url() 把 /anthropic 改写到 /v1
detector 看到 /v1 后没有识别为 Anthropic transport
结果没有走 Anthropic wrap，所有 auxiliary call 都打到 OpenAI-style path，返回 404
follow-up regression tests 提到 #18026

修复方向可以概括成一句话：

> 保留 raw URL 用于 transport detection，同时只在需要 OpenAI client 时使用 rewritten URL。

也就是说，系统可以为了 OpenAI SDK 准备 /v1 URL，但不能用被改写后的 URL 去判断“这是不是 Anthropic-native endpoint”。

用户能立即做什么？

1. 升级 Hermes Agent

如果你命中了这个问题，第一优先级是升级到包含 4e296dcdd 之后的版本或 main 分支。

升级后再观察：

Cannot POST /v1/chat/completions

是否消失。

2. 检查 auxiliary 配置

确认你的配置是否明确写了：

api_mode: anthropic_messages

并且 base_url 是否真的是 Anthropic-native endpoint：

base_url: http://localhost:6655/anthropic/

如果你接的是 OpenAI-compatible endpoint，就不要写 api_mode: anthropic_messages；如果你接的是 Anthropic-native endpoint，就不要让它被当成 OpenAI /v1/chat/completions。

3. 看日志里的请求路径

重点找：

/v1/chat/completions

如果你的预期是 /anthropic/，但日志或错误 HTML 出现 /v1/chat/completions，那就是路径改写方向的问题。

4. 临时 workaround

如果短期不能升级，可以考虑：

改用 OpenAI-compatible proxy route；
或把 auxiliary task 暂时切到已知可用的 OpenAI-compatible provider；
或避免在 auxiliary custom endpoint 中混用 Anthropic-native path 和 OpenAI client path。

但最干净的解决方式仍然是升级到修复版本。

和 DeepAI API 中转站的关系

这个问题本身不是 DeepAI API 中转站的问题。它是 Hermes auxiliary client 对 api_mode: anthropic_messages 和 custom base_url 处理不一致导致的客户端路由问题。

DeepAI API 中转站更适合下面这种场景：

你的客户端支持 OpenAI Compatible API；
你希望统一 Base URL、API Key 和模型管理；
你在 Cherry Studio、Cline、Dify、Open WebUI 等工具里接入多模型；
你需要更稳定地管理团队或个人的模型调用入口。

如果你使用 DeepAI 这类 OpenAI-compatible endpoint，配置重点通常是：

api_mode: openai
base_url: https://your-openai-compatible-endpoint/v1

而不是：

api_mode: anthropic_messages
base_url: .../anthropic/

所以边界要说清楚：DeepAI 可以提供统一 OpenAI-compatible 基础设施，但不会自动修复 Hermes 把 Anthropic-native auxiliary endpoint 改写成 /v1/chat/completions 的客户端 bug。你需要升级 Hermes 或调整 api_mode/base_url 组合。

OpenAI-compatible 与 Anthropic-native endpoint 不要混用

很多 404 的根源都来自“endpoint 类型”和“client 类型”没对齐。

OpenAI-compatible 通常长这样

api_mode: openai
base_url: https://example.com/v1

请求路径通常是：

POST /v1/chat/completions

Anthropic-native 通常长这样

api_mode: anthropic_messages
base_url: https://example.com/anthropic/

请求路径可能是 Anthropic Messages 风格，而不是 OpenAI Chat Completions。

二者不是简单换个模型名就能互通。你必须确认代理到底支持哪种协议。

FAQ

为什么我看到的是 HTML 404 页面？

因为请求打到了代理或本地服务不存在的 route，例如 /v1/chat/completions。服务返回 HTML 错误页，Hermes 日志就把它打印出来了。

`api_mode: anthropic_messages` 写了为什么还会走 `/v1`？

问题版本里，custom auxiliary path 对 base_url 做了 _to_openai_base_url() 改写，并且 transport detection 使用了被改写后的 URL，导致没有识别为 Anthropic transport。

升级后还 404 怎么办？

先确认当前安装版本是否包含 commit 4e296dcdd 或对应修复；再检查 base_url 是否多写/少写 path，例如 /anthropic、/v1、尾部 slash 等。

这和 provider:auto + 空 api_key 的 401 是同一个问题吗？

不是。401 是认证头没带；这里的 404 是路径/API mode 不匹配。但它们都发生在 auxiliary client 配置解析路径里，所以排查时容易混淆。

DeepAI API 中转站能用于这个场景吗？

如果你的客户端走 OpenAI Compatible API，可以用 DeepAI 统一 Base URL 和 Key。但如果你配置的是 api_mode: anthropic_messages 和 /anthropic/ endpoint，就不要把它当成 OpenAI-compatible /v1 来用。

总结

Hermes Agent auxiliary 报 HTTP 404，尤其日志里出现：

Cannot POST /v1/chat/completions

而你配置的是：

api_mode: anthropic_messages
base_url: .../anthropic/

那就要优先怀疑 endpoint 被错误改写成 OpenAI path。

这个问题的关键不是 API Key，也不是模型不可用，而是 Anthropic-native endpoint、OpenAI-compatible path 和 Hermes auxiliary client transport detection 没对齐。

最稳的处理方式是升级到包含 4e296dcdd 修复的版本；如果暂时不能升级，就确保 auxiliary task 的 api_mode、base_url 和代理协议完全一致，不要让 /anthropic/ 被当成 /v1/chat/completions。