在 Hermes Agent 里接入 GPT-5.x、Copilot、OpenRouter 或其它 OpenAI-compatible provider 时，一个很容易让人误判的错误是：配置里明明写了 api_mode: codex_responses，但运行一段时间后，请求却漂移到了 /chat/completions，最后返回：
model "gpt-5.4" is not accessible via the /chat/completions endpoint
code: unsupported_api_for_model这类问题表面像“OpenRouter 不能用 GPT-5”或“Copilot 配置失效”，但更准确地说，它暴露的是一个 API 模式选择策略问题：有些模型不是普通 Chat Completions 模型，而是必须走 Responses API / Codex Responses 路径。
本文基于 Hermes Agent 中一个已关闭并完成修复的真实问题，整理 GPT-5.x 模型在 Copilot、OpenRouter、OpenAI-compatible 端点之间切换时的排查思路。标题不写 issue 编号，直接面向搜索这个报错的人。
先说结论：GPT-5.x 不能只按 provider 判断 API 模式
如果你看到类似错误：
{
"error": {
"message": "model \"gpt-5.4\" is not accessible via the /chat/completions endpoint",
"code": "unsupported_api_for_model"
}
}重点不是先去怀疑：
- API Key 是否一定错了；
- OpenRouter 是否完全不支持这个模型；
- Copilot 是否突然坏了；
- Telegram / Discord 网关是否把消息弄丢了。
更应该先确认：
> 当前模型是否必须使用 Responses API，而客户端却把它发到了 /v1/chat/completions。
在 Hermes 这次修复里，维护者给出的根因是：GPT-5.x 模型在 OpenAI 和 OpenRouter 上都需要 Responses API 路径；旧逻辑只按 provider / base_url 判断 API mode，导致 fallback 到 OpenRouter 时错误使用 chat_completions。
典型场景：配置是 Copilot，失败请求却去了 OpenRouter
问题报告里的典型配置类似：
model:
default: gpt-5.4
provider: copilot
base_url: https://api.githubcopilot.com
api_mode: codex_responses正常预期是：
- provider 保持 Copilot；
- GPT-5.4 使用
codex_responses； - 不应该自动漂到 OpenRouter 的
/chat/completions。
但实际失败日志里出现了：
Endpoint: https://openrouter.ai/api/v1/chat/completions
model: gpt-5.4
code: unsupported_api_for_model这就说明故障不只是“配置文件写错”。更像是 agent 在某次 provider fallback、gateway cached agent、会话恢复或内部重试路径中，把 provider / base_url / api_mode 的组合状态弄乱了。
为什么 fallback 会把问题放大？
Agent 系统通常会有 fallback 机制：主 provider 暂时失败时，切到备用 provider 继续完成任务。
这本来是提高可用性的设计，但对 GPT-5.x 这类模型有一个坑：
| 判断方式 | 看起来合理 | 隐患 |
| 按 provider 判断 | OpenAI direct 用 Responses，OpenRouter 用 Chat Completions | GPT-5.x 在 OpenRouter 也可能要求 Responses |
| 按 base_url 判断 | api.openai.com 用 Responses | fallback 到其它兼容端点时会漏判 |
| 按模型判断 | GPT-5.x 统一走 Responses | 更符合模型契约 |
Hermes 旧逻辑的问题就在这里：当 Copilot 用户的主 provider 出现临时失败，fallback 链路切到 OpenRouter，但 api mode 重新按 provider 默认值设成了 chat_completions。于是 GPT-5.4 被发到了不支持它的接口上。
官方修复思路：模型级 API mode 检测
对应修复里，Hermes 增加了一个模型级判断函数，大意是：
def _model_requires_responses_api(model: str) -> bool:
m = model.lower()
if "/" in m:
m = m.rsplit("/", 1)[-1]
return m.startswith("gpt-5")然后在两个关键位置使用：
1. Agent 初始化时：如果模型本身需要 Responses API，即使 provider 不是 direct OpenAI，也切到 codex_responses； 2. fallback 激活时：如果 fallback provider 仍然承载 GPT-5.x，也必须保留 codex_responses，不能回退到 chat_completions。
这个设计比“OpenRouter 特判一下”更稳，因为真正的约束来自模型能力和接口契约，而不是某一个 provider 名称。
排查清单：遇到 unsupported_api_for_model 先看这 6 件事
1. 看失败 URL 是 /chat/completions 还是 Responses 路径
如果错误里明确写：
not accessible via the /chat/completions endpoint优先怀疑 api mode 错了。
不要只看配置文件里的 api_mode，要看实际 request dump / 日志里的 URL。很多问题恰恰发生在运行时 fallback 或 cached session 中。
2. 看模型名是否属于 GPT-5.x / Codex Responses 类
例如：
gpt-5
gpt-5.4
gpt-5-codex
openai/gpt-5.4这类模型更应该被视为“Responses API 模型”，而不是普通 chat completions 模型。
3. 看 provider fallback 是否改变了 api_mode
如果日志里一边显示：
provider=copilot model=gpt-5.4另一边 request dump 又显示：
base_url=https://openrouter.ai/api/v1
url=/chat/completions说明状态可能已经漂移：provider 标签、base_url、api_mode 三者不一致。
4. 看 gateway 是否缓存 agent runtime
很多 messaging gateway 为了性能会缓存 agent 实例。如果 fallback 后没有在下一轮恢复 primary runtime，就可能让后续消息继续沿用错误状态。
Hermes 这次修复也顺手更正了一个注释：gateway 并不是每条消息都创建全新 agent，而是会通过 _agent_cache 缓存，所以 _restore_primary_runtime() 对 gateway 场景同样重要。
5. 区分认证错误和 API 模式错误
不要把所有 400 都混在一起。
| 错误 | 更可能的问题 |
unsupported_api_for_model | 模型被发到不支持的 endpoint |
invalid_api_key / User not found | API Key、Authorization header 或 provider auth |
Personal Access Tokens are not supported | Copilot token 类型不符合 endpoint 要求 |
model not found | 模型名、供应商权限或路由表问题 |
如果错误已经明确说 /chat/completions endpoint，就先查 API 模式，不要先改 key。
6. 升级到包含模型级检测的版本
如果你用的是旧版 Hermes，最直接的修复是升级到包含 _model_requires_responses_api() 这类逻辑的版本。
如果你维护的是自己的 OpenAI-compatible client，也可以参考这个策略：
- 不要只按 provider 决定 API path；
- 把模型能力也纳入路由决策；
- fallback 时复制/重算 api mode；
- gateway 缓存 agent 时，每轮开始恢复 primary runtime。
对 OpenAI-compatible API 代理的启发
很多人会把多个模型接到统一代理或中转站，例如：
- DeepAI API 中转站；
- OpenRouter；
- 自建 New API / One API；
- 公司内部统一 LLM Gateway；
- Cherry Studio、Cline、Dify、Open WebUI 等工具的统一 Base URL。
这里有一个关键经验：
> OpenAI-compatible 不等于所有模型都能走同一个 /chat/completions。
统一 Base URL 很有价值，但客户端仍需要知道：
- 哪些模型支持 Chat Completions；
- 哪些模型必须走 Responses API；
- 哪些模型有特殊 tool calling / reasoning / multimodal 约束；
- fallback 到备用 provider 时是否要重算 API mode。
DeepAI API 中转站适合用来统一 API Key、Base URL、模型选择和账单管理，但前提是你的客户端把模型名、接口路径、参数契约配置正确。否则，把 GPT-5.x 发到错误 endpoint，换哪个兼容代理都可能继续报错。
推荐的配置思路
如果你在 Hermes 或类似 agent 中使用 GPT-5.x，建议这样检查：
model:
default: gpt-5.4
provider: your-provider
api_mode: codex_responses
base_url: https://your-endpoint.example.com然后再确认运行时日志里：
model = gpt-5.4
api_mode = codex_responses
endpoint != /chat/completions如果你配置了 fallback，还要确认 fallback 后：
fallback_model = gpt-5.4
fallback_api_mode = codex_responses而不是：
fallback_model = gpt-5.4
fallback_api_mode = chat_completions临时绕法和长期修复
临时绕法
如果你现在必须先恢复可用：
- 暂时禁用会漂移到错误 endpoint 的 fallback；
- 显式指定
api_mode: codex_responses； - 换一个确定支持当前接口路径的模型；
- 清理旧 session / cached agent 状态；
- 查看 request dump，确认实际 URL。
这些能缓解，但不一定根治。
长期修复
更稳的长期修复应该是：
- 按模型能力选择 API path；
- provider fallback 时重新计算 api mode；
- gateway cached agent 每轮恢复 primary runtime；
- 把模型能力表集中维护，而不是到处手写 if；
- 对
unsupported_api_for_model提供更明确的错误提示。
Hermes 的修复方向就是这个：模型级 helper + fallback 路径统一应用。
FAQ
unsupported_api_for_model 一定是模型不可用吗？
不一定。它可能表示模型可用，但你用了错误的接口路径。例如 GPT-5.x 被发到 /chat/completions，供应商会拒绝。
配了 api_mode: codex_responses 为什么还会走 chat_completions？
可能是 fallback、会话恢复、gateway cached agent 或内部 helper client 没有继承/重算 api_mode。要看实际 request dump，而不是只看配置文件。
OpenRouter 上的 GPT-5.x 也需要 Responses API 吗？
在这次 Hermes 修复结论里，维护者明确提到 GPT-5.x 在 OpenAI 和 OpenRouter 上都会被 /chat/completions 拒绝，因此要按模型强制走 Responses API 路径。
DeepAI API 中转站能解决这个错误吗？
DeepAI 可以帮助统一 OpenAI-compatible API 的 Base URL、API Key、模型和账单管理，但如果客户端把 GPT-5.x 发到错误 endpoint，仍然可能报错。正确做法是先保证模型与 API path 匹配，再接入统一中转。
这个问题和 Telegram / Discord 网关有关吗？
网关可能放大问题，因为 agent runtime 会缓存、fallback 状态可能跨消息残留。但根因仍然是模型、provider、base_url、api_mode 的组合状态不一致。
小结
当 Hermes Agent 使用 GPT-5.x 报：
unsupported_api_for_model
not accessible via /chat/completions最重要的排查方向是：
> 不要只按 provider 判断接口路径，要按模型能力强制选择 Responses API。
对 agent、LLM gateway、OpenAI-compatible 中转和多 provider fallback 系统来说，这个问题很典型：统一入口很方便，但模型契约不能被抹平。GPT-5.x 这类模型需要 Responses API，就必须让主路径、fallback 路径、gateway 缓存路径都保持一致。