Codex 中转 API 验收与排错

结论先说： Codex 显示了自定义模型、能回答一句话，不代表中转 API 已经适合代码 Agent。至少要确认当前进程真的加载了目标 Provider，并分别验证 Responses 路径、持续流式事件、工具调用、文件回写、上下文压缩和会话恢复。

本文从 V2EX Codex 节点和 openai/codex GitHub Issues 中归类公开求助，再使用 OpenAI 官方配置、认证和 Responses API 文档校正解决步骤。论坛浏览量和回复数只反映社区关注度，不等同于搜索量、故障概率或产品能力证明。

社区反复出现的八类问题

问题	常见现象	应检查的层级
配置没有生效	写了 Provider，实际仍请求原地址	配置文件位置、优先级、Profile、`CODEX_HOME`
认证方式混淆	ChatGPT 已登录，但第三方请求 401	登录状态、Provider 的 `env_key`、当前终端环境
协议或路径不匹配	404、`/v1/v1/responses`、HTML 错误页	Base URL、Responses 入口、重定向
普通对话成功但工具失败	400、工具参数丢失、执行后卡住	Responses 工具事件、工具结果回传、事件顺序
流式响应中断	`stream disconnected`、重试后仍卡住	SSE、代理缓冲、空闲超时、`response.completed`
上下文压缩失败	`/compact` 或自动压缩报参数、模型、超时错误	压缩请求、字段兼容、路由模型和长连接
切换账号后会话异常	历史列表不同、旧会话无法继续	登录身份、Provider、客户端表面与本地状态
Token 与成本不可解释	用量突增、缓存或账单难以核对	上下文、工具循环、重试、usage 与控制台记录

这些是问题分类，不代表某个服务必然存在故障。尤其是输出风格变化、一次 5xx 或一次压缩失败，都不能单独证明模型被替换。

先分清表面、认证、配置和协议

1. Codex 表面不是同一个运行环境

Codex CLI、IDE、桌面 App、云任务和自动化的可用功能、认证要求与配置承接范围可能不同。本文优先验收 Codex CLI 的自定义模型提供商。CLI 跑通后，仍要在目标表面单独确认 Provider、模型和工具能力，不能把 CLI 结果直接外推到 App 或云任务。

2. ChatGPT 登录不等于第三方 Provider 已认证

codex login status 用于查看 Codex 当前登录方式；自定义 Provider 则可通过 env_key 从环境变量读取自己的凭证。两者属于不同层级。ChatGPT 已登录，不能证明第三方 API Key 已加载；设置了第三方 Key，也不会自动获得依赖 ChatGPT 工作区的功能。

3. Provider 不能放在项目配置里期待覆盖

官方配置优先级从高到低包括：CLI 参数、可信项目配置、Profile、用户配置、系统配置和内置默认值。但出于安全原因，项目级 .codex/config.toml 不能改写 model_provider、model_providers 和 Provider 认证等重定向配置。

自定义 Provider 应放在用户级 ~/.codex/config.toml。当前官方 Profile 方式使用独立的 ~/.codex/名称.config.toml 文件，并通过 --profile 名称 选择。旧教程中的内联 [profiles.名称] 写法可能不再被当前版本读取。

4. 本文验收的是 Responses 路径

当前官方自定义 Provider 示例使用 wire_api = "responses"。当 Base URL 是 https://www.aifast.club/v1 时，常规最终请求地址应为 https://www.aifast.club/v1/responses，而不是 /v1/v1/responses。中转服务必须正确处理 Responses 请求、流式事件和工具结果，不能用 Chat Completions 的一次文本成功代替。

本文以 Responses 的 HTTPS/SSE 路径作为基础验收。若 Provider 明确配置并支持 WebSocket，还应单独验证 WebSocket 握手、事件完整性与 HTTPS 回退；一个传输方式通过，不能自动证明另一个也通过。其他本地或特定 Provider 路径可能不同，应以当前 Codex 和服务商文档为准。

20 分钟完成八项验收

先创建不含客户代码的临时仓库和独立低额度 Key。不要在真实生产仓库第一次测试第三方 Provider。

1. 记录版本、认证和诊断信息

codex --version
codex login status
codex doctor

codex doctor 可检查安装、配置、认证、运行环境、Git 和线程信息。向外部求助前必须脱敏：删除完整 API Key、用户目录、仓库名、内部域名、Token 和会话内容。

2. 确认 Key 在同一个终端生效

test -n "$AIFAST_API_KEY" && echo "AIFAST_API_KEY 已设置" || echo "AIFAST_API_KEY 未设置"

不要执行 echo "$AIFAST_API_KEY"，也不要把完整环境变量截图发到论坛或客服群。

3. 用独立 Profile 切换 Provider

Provider 定义放在 ~/.codex/config.toml：

[model_providers.aifast]
name = "AI快站"
base_url = "https://www.aifast.club/v1"
env_key = "AIFAST_API_KEY"
wire_api = "responses"

aifast 是自定义 Provider ID。不要把自定义 Provider 命名为 Codex 保留的 openai、ollama 或 lmstudio，也不要尝试用 [model_providers.openai] 覆盖内置 Provider。

创建 ~/.codex/aifast.config.toml，只写需要覆盖的选择项：

model = "YOUR_REAL_MODEL_ID"
model_provider = "aifast"

模型 ID、Responses 支持状态和开放范围属于动态信息。使用前应以控制台、服务商文档和实际接口为准，不要把示例名称直接当作可用模型。

启动并检查：

codex --strict-config --profile aifast

--strict-config 会在当前版本无法识别配置字段时直接报错，适合首次验收；配置通过后可使用 codex --profile aifast 正常启动。

进入后运行 /status，确认活动模型、权限和工作目录。/status 不能单独证明最终请求主机；Provider 选择还应结合 codex doctor 的脱敏结果、启动配置和服务端请求日志核对。若结果与 Profile 不同，检查是否有更高优先级的 CLI 参数、项目配置或不同的 CODEX_HOME。

4. 先隔离验证 Responses 端点

在目标模型当前明确支持 Responses API 的前提下，先绕开 Codex 客户端发送最小请求：

curl --fail-with-body --silent --show-error \
  https://www.aifast.club/v1/responses \
  -H "Authorization: Bearer $AIFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_REAL_MODEL_ID",
    "input": "只回复 RESPONSES_OK"
  }'

这一步成功、Codex 仍失败，优先排查 Codex 配置和 Agent 事件；这一步也失败，先按状态码处理 API、模型权限或协议支持，不要继续调整 Codex 提示词。若服务商当前文档规定了不同的专用 Responses 地址，以服务商文档为准。

5. 最小只读任务

只读取当前目录的 README，不修改文件。返回文件标题、一级标题数量和三条摘要。

通过标准：内容与文件一致；没有产生修改；请求日志显示目标 Provider、目标模型和预期 Responses 路径。

6. 真实工具与文件回写

在临时分支中输入：

新建 codex-gateway-check.txt，只写一行 CODEX_GATEWAY_OK；读取文件确认，然后显示 git diff。不要修改其他文件。

通过标准：工具调用、文件写入、读取和结果汇报都完成；git diff 只有预期文件。普通文本回答不能替代工具链验收。

7. 流式事件与会话恢复

让 Codex 执行一个会产生多段说明和至少一次工具调用的小任务。内容应持续出现，工具完成后仍能进入下一轮，最终正常结束。再退出当前会话并使用正常的恢复入口继续一个只读问题。

如果流在工具调用之后、response.completed 之前中断，可能造成工具结果不完整、重试异常或线程无法恢复。此时保存状态码、请求 ID、最后一个事件类型和发生时间，不要立即在原会话重复执行有副作用的命令。

8. 分级测试上下文压缩

先读 1 个文件，再扩大到 5 个相关文件，最后测试模块级任务。在测试会话中运行 /compact，记录是否成功以及请求日志中的最终路径、模型、状态码和错误正文。

压缩可能暴露普通短请求没有触发的字段、模型路由和长连接问题。社区帖子中出现过额外压缩请求或模型映射，但这些实现会随版本与服务商变化；应以自己的实时日志为准，不能照搬帖子中的固定模型名。

按现象定位 401、404、429、5xx 与压缩错误

现象	优先检查	不要先做什么
Profile 没生效	Profile 文件名、`--profile`、配置优先级、`CODEX_HOME`	在项目配置里反复写 Provider
Provider ID 冲突	是否误用 `openai`、`ollama`、`lmstudio` 等保留 ID	尝试覆盖内置 Provider
仍请求官方地址	`codex doctor`、启动配置、最终请求主机、更高优先级参数	只凭 `/status` 推断 Provider
401	`env_key`、环境变量、Key 状态、认证头、启动终端	把完整 Key 发给他人
403	模型权限、Key 权限、来源限制、服务策略	默认判断为客户端 Bug
404	最终 URL、是否重复 `/v1`、是否真实支持 Responses	反复更换模型碰运气
400 / unknown parameter	服务是否支持该字段、客户端与网关版本、错误正文	用重试掩盖协议不兼容
429	余额、配额、并发、退避与 `Retry-After`	无限并发重试
502 / 504	上游状态、代理超时、请求体大小、流式缓冲	只凭一次失败判断稳定性
工具调用后卡住	工具事件、结果回传、事件顺序、结束事件	只增加总超时
`/compact` 失败	最终请求、压缩字段、路由模型、空闲超时	按论坛旧型号硬编码映射
恢复会话失败	上次流是否完整结束、工具结果是否落盘、客户端版本	直接编辑本地状态数据库

遇到错误时，先用最小只读任务复现。401、404 和确定的 400 配置错误通常不应自动重试；429、部分 5xx 和短暂断流才适合有限次数、带退避的重试。有副作用的工具调用必须先确认幂等性。

配置不生效与账号切换怎么处理

按以下顺序检查，通常比删除配置或重新安装更快：

运行 codex --version，确认当前调用的不是另一份旧安装。
运行 codex doctor，确认实际 CODEX_HOME 和配置位置。
检查 Provider 是否位于用户配置，而不是项目 .codex/config.toml。
检查自定义 Provider ID 没有使用内置保留名称。
使用 codex --strict-config --profile aifast 检查未知字段和旧配置。
清除本次启动中不需要的 --model 或 -c 覆盖参数。
从设置 Key 的同一个终端启动 Codex。
用 /status 核对模型和权限，再从请求日志确认最终主机。

官方 ChatGPT 登录和自定义 Provider 可以服务不同工作流，但不要假定两种身份下的模型、云功能、自动化和会话列表完全一致。切换前先完成当前任务并保存 git diff，新开会话验证，不要依据论坛偏方直接修改 Codex 的 SQLite、JSONL 或认证文件。

保存证据并选择下一步

测试日期：____________________
Codex 版本：__________________
使用表面：CLI / IDE / App / 其他
活动 Profile：_______________
活动 Provider：______________
请求模型 / 响应模型：________
Base URL（脱敏）：____________
最终请求 URL（脱敏）：_________
传输方式：SSE / WebSocket / 其他

[ ] /status 与目标配置一致
[ ] /v1/responses 最小请求通过
[ ] 最小只读任务通过
[ ] Responses 流式事件通过
[ ] 工具调用与文件回写通过
[ ] 会话恢复通过
[ ] /compact 分级测试通过
[ ] usage 与账单可核对

HTTP 状态码：_________________
请求 ID：_____________________
最后事件类型：_______________
最小复现与错误正文：_________
复测时间与结果：______________

根据当前阶段选择入口：

还在配置： 查看Codex 接入 OpenAI Compatible API 配置教程和API 兼容性矩阵。
需要排查通用错误： 查看401、429、502 API 错误排查和流式 SSE 教程。
需要比较 Chat Completions 入口： 使用免费模型与中转站检测工具。该工具当前不直接测试 Responses API，不能代替本文的 Codex 验收。
准备接入： 先查看当前模型与价格，确认目标模型当前支持 Responses API。
准备创建测试 Key： 注册 AI快站，创建独立限额 Key 后从只读任务开始。

“OpenAI Compatible”不能自动推导出 Codex 所需的 Responses、流式工具事件、压缩和会话恢复全部兼容。每项能力都应留下可复核证据。

社区反复出现的八类问题

先分清表面、认证、配置和协议

1. Codex 表面不是同一个运行环境

2. ChatGPT 登录不等于第三方 Provider 已认证

3. Provider 不能放在项目配置里期待覆盖

4. 本文验收的是 Responses 路径

20 分钟完成八项验收

1. 记录版本、认证和诊断信息

2. 确认 Key 在同一个终端生效

3. 用独立 Profile 切换 Provider

4. 先隔离验证 Responses 端点

5. 最小只读任务

6. 真实工具与文件回写

7. 流式事件与会话恢复

8. 分级测试上下文压缩

按现象定位 401、404、429、5xx 与压缩错误

配置不生效与账号切换怎么处理

保存证据并选择下一步

参考与核对来源

创建 API Key，按本文配置直接验证

社区反复出现的八类问题

先分清表面、认证、配置和协议

1. Codex 表面不是同一个运行环境

2. ChatGPT 登录不等于第三方 Provider 已认证

3. Provider 不能放在项目配置里期待覆盖

4. 本文验收的是 Responses 路径

20 分钟完成八项验收

1. 记录版本、认证和诊断信息

2. 确认 Key 在同一个终端生效

3. 用独立 Profile 切换 Provider

4. 先隔离验证 Responses 端点

5. 最小只读任务

6. 真实工具与文件回写

7. 流式事件与会话恢复

8. 分级测试上下文压缩

按现象定位 401、404、429、5xx 与压缩错误

配置不生效与账号切换怎么处理

保存证据并选择下一步

参考与核对来源

创建 API Key，按本文配置直接验证

继续阅读