Codex 自定义 API 常见错误与排查
自定义 API 出错时，先记录 Codex 版本、模型 ID、base URL、HTTP 状态码和脱敏后的错误文本。不要一上来同时更换模型、地址、密钥和配置字段，否则即使恢复也无法确定根因。
先检查最小配置
APIBest 的基础结构应类似：
model = "gpt-5.6-sol"
model_provider = "apibest"
[model_providers.apibest]
name = "APIBest"
base_url = "https://apibest.org/v1"
env_key = "APIBEST_API_KEY"
wire_api = "responses"这个配置要放在 ~/.codex/config.toml，而不是项目的 .codex/config.toml。确认启动 Codex 的同一个终端能读取环境变量：
test -n "$APIBEST_API_KEY" && echo "key exists"不要用 echo $APIBEST_API_KEY 把完整密钥打印到终端日志。
401 或 403：鉴权失败
常见原因：
- 环境变量没有设置，或 Codex 从另一个终端/进程启动。
env_key拼写与环境变量名称不同。- API Key 已过期、禁用、额度受限或没有目标模型权限。
- 密钥复制时包含额外空格或引号。
- 上游需要不同的鉴权格式。
先用 APIBest 文档提供的最小请求验证同一密钥。如果 curl 也返回 401，优先处理服务端账号与密钥；如果 curl 正常而 Codex 失败，再检查配置加载和协议路径。
404：地址或端点不匹配
base_url 应为：
https://apibest.org/v1不要写成具体的 /responses 地址，也不要重复为 .../v1/v1。如果普通 /models 可访问，但 Codex 请求返回 404，可能是服务商没有开放 Responses 端点，或当前路由不支持该模型。
模型不存在或无权限
模型 ID 必须与 APIBest 控制台显示的实际字符串一致，大小写、连字符都不能随意修改。gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 和 gpt-5.5 是当前提供的示例，账号可见范围仍可能不同。
Claude、Gemini、Grok 和画图模型应使用控制台给出的确切 ID，不能把产品名称直接当成 API ID。即使模型能完成聊天，也要单独确认 Responses 和工具调用兼容。
能回复文本，但工具调用失败
这是第三方兼容 API 中最关键的一类问题。可能表现为 Codex 一直输出“准备执行”，却没有工具调用；流式事件无法解析；工具结果回传后会话中断。
原因通常不是提示词，而是协议转换不完整：
- 上游只兼容 Chat Completions，不兼容 Responses API。
- 流式事件类型、顺序或结束标记不符合 Codex 预期。
- 模型本身没有稳定的工具调用能力。
- 提供商没有正确转换工具参数或工具结果。
用一个最小任务验证：要求 Codex 读取单个文本文件并总结。如果纯聊天正常、读取工具失败，应把脱敏后的请求时间、模型 ID 和错误交给 APIBest 支持排查。
流式中断、超时或空响应
先缩短任务，排除上下文过大。再检查：
- 网络连接是否会中断长时间的流式响应。
- 模型是否处于高负载或限流状态。
- 上游网关和客户端超时是否过短。
- 请求包含的仓库上下文是否超过模型限制。
- 模型是否返回 Codex 尚不能解析的响应项。
不要在失败后无限自动重试，尤其是按 token 计费的请求。先确认服务端是否已经产生计费响应。
429：限流或额度不足
429 可能表示每分钟请求数、token 速率、并发数或账号余额达到限制。减少并行任务、缩短上下文、等待限流窗口恢复，并在 APIBest 控制台确认额度。切换模型可能改变限额和价格，但不应把它当作唯一解决办法。
回到可验证的基线
排错时保持以下顺序：
codex --version正常。- 配置文件语法正确且位于用户级目录。
- 同一终端中存在 API Key 环境变量。
/v1/models的最小请求可以通过鉴权。- 目标模型 ID 确实对当前账号可用。
- 纯文本短响应正常。
- 流式响应和单个工具调用正常。
- 最后再测试长上下文和复杂代理任务。
如果第 4 步之前失败，重点检查网络与账号；第 6 步之后失败，则更可能是 Responses、流式事件或工具协议兼容问题。