直接答案
404 可能是资源路径不存在，也可能是模型名在当前 provider 中不可见；先判断返回的是路由 404 还是模型 404。
这篇内容解决什么问题
解决 model_not_found、unknown model、resource not found 和错误 Base URL 导致的 404。
先确认症状与影响范围
请求返回 404 Not Found、model_not_found 或 unknown model。HTML 404 页面通常更像请求打到站点或代理的错误路径；JSON 错误体带模型名时更像模型映射问题。
模型列表可用但生成请求 404，需要比较请求中的模型 ID 是否与列表完全一致，包括大小写、前缀和提供商别名。
- 判断响应 Content-Type 是 JSON 还是 HTML。
- 记录最终 URL，检查
/v1和资源路径是否重复。 - 从当前账号的模型目录复制模型 ID，不凭教程截图手输。
常见原因与责任边界
404 发生在 URL 路由或模型路由两层。只有先区分这两层，才能决定修改 Base URL、接口名称还是模型 ID。
- Base URL 已包含资源路径，SDK 再次追加后形成重复路径。
- 请求使用展示名称、旧别名或另一 provider 的模型 ID。
- 账号无权看到目标模型，服务以 404 隐藏资源存在性。
- Chat Completions、Responses 或 Messages 请求发往了不支持的路径。
按层执行最小诊断
先请求当前 Base URL 下的模型列表，再从响应中选择模型 ID 发起最小生成请求。若模型列表本身返回 HTML 404，优先修正主机和路径。
Codex 还需检查 model_provider 与 provider 配置是否匹配；Claude Code Gateway 需检查模型映射和 Messages 路由。
- 01检查响应类型HTML 404 指向站点或代理路径，JSON model_not_found 指向模型路由。
- 02列出模型从当前账号与当前 Base URL 获取真实可见模型。
- 03复制模型 ID保留完整 ID，不替换前缀、版本或大小写。
- 04对照客户端确认 Codex provider 或 Claude Gateway 实际发送相同 ID。
API_BASE_URL='https://<your-api-host>/v1'
curl -sS -D /tmp/model-headers.txt "$API_BASE_URL/models" -H "Authorization: Bearer ${API_KEY:?set API_KEY first}" -o /tmp/models.json
sed -n '1,20p' /tmp/model-headers.txt
针对根因完成修复
路由错误时按接入教程配置 Base URL，不要把 /chat/completions 写入 base。模型错误时从当前模型列表选取受支持 ID，并同步修改客户端中的 provider 或映射。
- 01修正 Base URL只保留 SDK 或客户端要求的基础层级。
- 02更新模型 ID使用当前目录返回的完整 ID，并删除过期别名。
- 03检查映射确认 Gateway 没有把客户端模型名映射到不存在的上游 ID。
验证修复而不是只看一次成功
用模型目录中的同一 ID 分别执行 curl 与目标客户端最小请求。两者都成功后，再恢复原任务和高级参数。
- 模型列表与生成请求来自同一主机和 API 版本。
- 客户端状态或日志显示预期 provider 与完整模型 ID。
- 旧模型别名已从配置、CI 和文档示例中移除。
安全边界与升级证据
不要为了查看隐藏模型而枚举大量 ID，也不要把完整模型目录与账号信息公开。支持请求只需目标 ID、状态码、时间和 request ID。
- 不把 API Key 放进模型列表 URL。
- 不使用来源不明的模型别名绕过授权。
- 不在未确认协议兼容前强制改写路径。
官方来源与核验范围
本文以协议规范和客户端官方文档为事实依据。错误文案、重试头和配置字段可能随服务或客户端版本变化；执行前请核对来源，并对日志与请求样例脱敏。
查看技术核验方法