在接入自定义模型 Provider 时，准确区分错误类型是高效排障的前提。401、404 与 timeout 代表了完全不同的故障层级。

快速判断矩阵

| 状态码 | 故障层级 | 第一优先级排查 | 常见误区 |

| :--- | :--- | :--- | :--- |

| 401 | 认证层 | API Key / 认证方式 | 不要盲目更换模型名 |

| 404 | 资源层 | Base URL / Model 标识 | 不要以为是账号欠费 |

| timeout | 网络层 | 代理 / 超时配置 / 服务商状态 | 不要先去修改 API Key |

1. 401 Unauthorized (认证失败)

本质：请求已送达服务商，但身份验证未通过。

  • 重点检查：API Key 是否包含空格、是否已在控制台删除、环境变量名是否匹配。
  • 注意：确认 config.toml 中定义的 requires_openai_auth 或 env_key 是否指向了正确的凭证。

2. 404 Not Found (资源不存在)

本质：请求的地址或目标模型标识无法被服务商识别。

  • 常见原因 A：Base URL 写错。将完整接口路径（如 /v1/chat/completions）写进了基础地址中。
  • 常见原因 B：Model 字段错误。使用了过期名称、漏写前缀，或误将产品名当做接入点 ID。

3. Timeout (请求超时)

本质：请求发出后在预设时间内未获得响应。

  • 排查方向：本地网络波动、企业级代理拦截、服务商响应过慢，或 Codex 配置中的 timeout_ms 设置过短。
  • 建议：先通过浏览器或 curl 验证基础连通性，排除网络层干扰。

核心操作原则

  • 分层定位：先确定是认证、地址还是网络问题，再进行针对性调整。
  • 一次一变：严禁同时修改 Key、URL 和模型，这会导致无法确定真正有效的修复点。
  • 只读验证：在未定位根因前，不要进行大范围的配置重构或工具重装。

掌握这三类错误的本质区别，能让你在模型接入过程中少走 80% 的弯路。