很多人给 Codex 配第三方 API 时只在浏览器里打开一下地址页面能访问、HTTP 返回 200就认为接口没问题。结果真正启动 Codex 后还是会遇到404 Not Found stream disconnected before completion response.failed event received Missing environment variable问题在于“网站能访问”不等于“Codex 能调用”。根据当前官方配置文档Codex 自定义模型提供商使用的是Responses APIwire_api目前唯一支持的值也是responses。因此一个只兼容/v1/chat/completions的平台即使普通 OpenAI SDK 可以调用也不代表它能直接供 Codex 使用。这篇文章不靠“看起来能通”判断而是用三步依次检查/v1/responses路由和鉴权是否存在非流式 Responses 返回结构是否正确SSE 流式事件能否完整结束。说明本文包含作者使用和推广的 API 服务示例。路径检查使用 Genvis 的 OpenAI 兼容端点完成其他服务可以替换 Base URL 和模型名后执行同样的检测。[TOC]一、一句话结论Codex 第三方 API 至少要满足以下条件支持POST /v1/responses使用 Bearer Token 等客户端可配置的鉴权方式返回 Responses API 数据结构而不是 Chat Completions 结构stream: true时返回合法的text/event-stream流中能看到 Responses 事件并最终正常出现完成事件配置中的模型名确实存在且当前 Key 有权调用。仅仅出现 HTTP 200最多只能证明“某个网页返回了内容”。二、为什么普通 OpenAI 兼容接口不一定能给 Codex 用大家最熟悉的旧式对话接口通常是POST /v1/chat/completionsResponses API 使用的是POST /v1/responses两者不只是 URL 不同请求和响应结构也不同。Chat Completions 常见请求{ model: YOUR_MODEL_ID, messages: [ { role: user, content: Reply OK } ] }Responses API 的最小请求则是{ model: YOUR_MODEL_ID, input: Reply OK }OpenAI 官方 API 参考将创建响应定义为POST /responses。当前 Codex 配置参考也明确写明自定义提供商的wire_api只有responses这一种支持值而且省略时默认就是它。所以下面几种情况都可能发生/v1/models可以获取模型列表但/v1/responses是 404/v1/chat/completions能对话但 Codex 无法启动任务非流式请求正常切换stream: true后立即断开服务返回 HTTP 200但响应体其实是网站首页 HTML能输出文字却缺少 Codex 需要处理的 Responses 事件。三、第一步检查路由和鉴权先不要急着修改config.toml直接从命令行检查端点。macOS、Linux 或 Git Bashexport API_BASEhttps://genvis.xyz/v1 export API_KEYYOUR_API_KEY export MODELYOUR_MODEL_IDPowerShell$env:API_BASEhttps://genvis.xyz/v1 $env:API_KEYYOUR_API_KEY $env:MODELYOUR_MODEL_ID先发送一个真正的POST请求curl -i --max-time 30 \ -X POST $API_BASE/responses \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ --data {\model\:\$MODEL\,\input\:\Reply OK\}不要用浏览器地址栏或下面这种请求代替curl $API_BASE/responses因为它发送的是GET而 Responses 创建接口要求POST。GET /v1/responses返回 404 或 405并不能证明POST /v1/responses不存在。我在无有效 Token 的情况下进行路径检查时得到的是HTTP/1.1 401 Unauthorized Content-Type: application/json {error:{message:Invalid token, ...}}这个结果说明请求已经进入 API 鉴权层路由不是被前端网页接走但它仍然不能证明模型可调用因为还没有通过鉴权和模型检查。不同返回值可以这样判断返回结果通常说明什么下一步401 JSON 错误路由大概率存在但 Key 缺失或错误检查环境变量、Token 和请求头403 JSON 错误Key 已识别但权限、分组或访问策略拒绝检查模型权限、IP 白名单和账号状态404 JSON 错误路径错误或服务没有实现 Responses API检查 Base URL 和接口能力404/200 HTML请求打到了官网、反向代理或前端回退页检查 API 域名、路径和网关配置400 unknown model路由和鉴权可能已通过但模型名不可用查询模型列表或控制台权限405 Method Not Allowed请求方法错误确认使用POST四、第二步检查非流式响应结构通过鉴权后正常的 Responses API 返回不应该是 Chat Completions 的choices数组而应当具有 Responses 对象特征例如{ id: resp_..., object: response, status: completed, model: YOUR_MODEL_ID, output: [], usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 } }这里不要求字段顺序完全一致也不要求所有可选字段都出现但至少需要确认响应是 JSON不是 HTMLobject是response有明确的status文本位于 Responses 的output结构中错误时返回结构化错误而不是网关生成的一段普通网页Token 用量能正确记录避免调用成功却无法计费或对账。如果返回长这样{ choices: [ { message: { role: assistant, content: OK } } ] }这更像 Chat Completions 返回。普通 SDK 可能可以读取但不能据此认为 Codex 的 Responses 调用链已经兼容。五、第三步检查 SSE 流式事件Codex 是长时间运行的 Agent 客户端。只验证一次非流式回答还不够还要验证流式连接。执行curl -N -i --max-time 120 \ -X POST $API_BASE/responses \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -H Accept: text/event-stream \ --data {\model\:\$MODEL\,\input\:\Reply with exactly OK\,\stream\:true}首先检查响应头HTTP/1.1 200 OK Content-Type: text/event-stream然后检查事件流。事件内容会因模型和实现不同而变化但应当符合 Responses API 的 SSE 结构并能看到类似阶段event: response.created data: {...} event: response.output_text.delta data: {...} event: response.completed data: {...}OpenAI 官方文档说明Responses 流式传输使用 Server-Sent Events并通过stream: true开启。下面这些情况都值得警惕状态码 200但Content-Type是text/html返回一整块 JSON 后立即关闭并不是真正 SSE只有文本片段没有事件类型流到一半直接 EOF没有完成事件完成事件中的状态仍是failed或incomplete服务长时间不发送数据也没有心跳或合理超时网关把上游错误包装成 200 文本。这类问题常常在 Codex 中表现为stream disconnected before completion response.failed event received因此“能返回第一段文字”也不代表整个流式协议合格。六、确认通过后再配置 Codex当前官方配置参考显示用户级配置文件位于~/.codex/config.tomlWindows 通常对应%USERPROFILE%\.codex\config.toml有一个很容易忽略的变化model_provider和model_providers属于机器本地提供商配置。官方文档说明把它们写到项目目录的.codex/config.toml中会被忽略因此第三方提供商应放在用户级配置里。配置示例model YOUR_MODEL_ID model_provider genvis [model_providers.genvis] name Genvis base_url https://genvis.xyz/v1 env_key GENVIS_API_KEY wire_api responseswire_api responses当前可以省略因为它就是默认值。但排错时建议显式写出来避免以后看到配置时无法确认协议意图。不要把 Key 直接写进 TOML# not recommended experimental_bearer_token sk-xxxxxxxx官方配置参考也明确建议使用env_key而不是直接保存 Bearer Token。macOS/Linux 设置环境变量export GENVIS_API_KEYYOUR_API_KEYPowerShell$env:GENVIS_API_KEYYOUR_API_KEY配置后要从同一个新终端启动 Codex。VS Code 已经打开时插件进程可能仍然保留旧环境变量需要彻底退出后重新打开。七、Base URL 最常见的三个错误1. 重复拼接/v1如果客户端会在 Base URL 后追加/responses那么Base URL: https://api.example.com/v1 final URL: https://api.example.com/v1/responses但如果配置和网关同时追加版本路径就可能变成https://api.example.com/v1/v1/responses这种情况通常返回 404。2. 把完整接口写成 Base URL错误示例base_url https://api.example.com/v1/responses客户端继续追加/responses后可能得到https://api.example.com/v1/responses/responsesBase URL 应填公共前缀而不是某个具体操作接口除非服务商文档明确要求特殊格式。3. API 域名和官网域名混用有些网站会把未知路径统一返回首页因此错误请求也可能得到 HTTP 200。判断时必须同时看最终 URLHTTP 状态码Content-Type响应体是否为 SSE是否出现完整结束事件。八、stream disconnected不一定是换模型能解决遇到流中断时很多人的第一反应是切换模型。但可能的故障层至少有五层本机、代理、证书或网络连接Codex 客户端版本和配置API 网关的超时、缓冲或 SSE 转发上游模型的响应时间和流式实现Responses 事件格式不完整。当前官方 Codex 配置参考中自定义提供商默认的 SSE 空闲超时是 300000 毫秒流中断重试次数默认是 5。可以通过[model_providers.genvis] stream_idle_timeout_ms 300000 stream_max_retries 5进行明确配置但不要把“无限加大超时”当成通用修复。如果接口每次都在同一个固定时长中断应检查代理或网关超时如果第一条事件就解析失败应优先检查协议如果只有某个模型失败应检查模型映射、上下文和上游能力。九、一张表完成最终判断检查项合格表现不合格表现请求方法POST用浏览器或GET测试路径/v1/responses只有/v1/chat/completions鉴权结构化 401/403 或正常通过HTML 登录页、重定向页面非流式响应object: response只有choices或普通文本流式响应头text/event-streamtext/html、下载文件、普通 JSON流式过程Responses SSE 事件无事件类型、半途 EOF结束状态response.completedfailed、incomplete或无结束事件模型权限当前 Key 可调用余额有但分组无权限Codex 配置位置用户级~/.codex/config.toml把 provider 写进项目级配置Key 保存使用env_key明文写进配置或 Git十、总结判断一个第三方 API 能否供 Codex 使用不应该问“这个地址能不能打开”而应该依次问POST /v1/responses是否存在鉴权和模型权限是否通过返回的是 Responses 对象还是 Chat Completions 对象stream: true是否得到真正的 SSE事件流是否完整到达response.completedCodex 的 provider 是否写在用户级配置并从正确环境变量读取 Key完成这六项检查才能把“配置问题”“接口不兼容”“模型无权限”和“流式链路中断”分开。否则不停换模型、改 TOML、重装客户端很可能只是在重复试错。如果你正在排查可以只留下以下信息操作系统、Codex 版本、最终请求路径、HTTP 状态码、Content-Type和错误原文。不要发布 API Key、完整请求头或包含业务代码的原始日志。参考资料OpenAI 官方 Codex Configuration ReferenceOpenAI 官方 Responses APICreate a model responseOpenAI 官方 Streaming API responses更新记录2026-08-23根据当日官方配置参考核对model_providers、env_key、wire_api、SSE 超时和重试配置完成无有效 Token 的路由与鉴权层检查。 
长河君 · 2026/8/24 23:05:03 · 阅读 1.2k Codex 第三方 API 兼容检测：别只看 HTTP 200，3 步验证 Responses API
很多人给 Codex 配第三方 API 时只在浏览器里打开一下地址页面能访问、HTTP 返回 200就认为接口没问题。结果真正启动 Codex 后还是会遇到404 Not Found stream disconnected before completion response.failed event received Missing environment variable问题在于“网站能访问”不等于“Codex 能调用”。根据当前官方配置文档Codex 自定义模型提供商使用的是Responses APIwire_api目前唯一支持的值也是responses。因此一个只兼容/v1/chat/completions的平台即使普通 OpenAI SDK 可以调用也不代表它能直接供 Codex 使用。这篇文章不靠“看起来能通”判断而是用三步依次检查/v1/responses路由和鉴权是否存在非流式 Responses 返回结构是否正确SSE 流式事件能否完整结束。说明本文包含作者使用和推广的 API 服务示例。路径检查使用 Genvis 的 OpenAI 兼容端点完成其他服务可以替换 Base URL 和模型名后执行同样的检测。[TOC]一、一句话结论Codex 第三方 API 至少要满足以下条件支持POST /v1/responses使用 Bearer Token 等客户端可配置的鉴权方式返回 Responses API 数据结构而不是 Chat Completions 结构stream: true时返回合法的text/event-stream流中能看到 Responses 事件并最终正常出现完成事件配置中的模型名确实存在且当前 Key 有权调用。仅仅出现 HTTP 200最多只能证明“某个网页返回了内容”。二、为什么普通 OpenAI 兼容接口不一定能给 Codex 用大家最熟悉的旧式对话接口通常是POST /v1/chat/completionsResponses API 使用的是POST /v1/responses两者不只是 URL 不同请求和响应结构也不同。Chat Completions 常见请求{ model: YOUR_MODEL_ID, messages: [ { role: user, content: Reply OK } ] }Responses API 的最小请求则是{ model: YOUR_MODEL_ID, input: Reply OK }OpenAI 官方 API 参考将创建响应定义为POST /responses。当前 Codex 配置参考也明确写明自定义提供商的wire_api只有responses这一种支持值而且省略时默认就是它。所以下面几种情况都可能发生/v1/models可以获取模型列表但/v1/responses是 404/v1/chat/completions能对话但 Codex 无法启动任务非流式请求正常切换stream: true后立即断开服务返回 HTTP 200但响应体其实是网站首页 HTML能输出文字却缺少 Codex 需要处理的 Responses 事件。三、第一步检查路由和鉴权先不要急着修改config.toml直接从命令行检查端点。macOS、Linux 或 Git Bashexport API_BASEhttps://genvis.xyz/v1 export API_KEYYOUR_API_KEY export MODELYOUR_MODEL_IDPowerShell$env:API_BASEhttps://genvis.xyz/v1 $env:API_KEYYOUR_API_KEY $env:MODELYOUR_MODEL_ID先发送一个真正的POST请求curl -i --max-time 30 \ -X POST $API_BASE/responses \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ --data {\model\:\$MODEL\,\input\:\Reply OK\}不要用浏览器地址栏或下面这种请求代替curl $API_BASE/responses因为它发送的是GET而 Responses 创建接口要求POST。GET /v1/responses返回 404 或 405并不能证明POST /v1/responses不存在。我在无有效 Token 的情况下进行路径检查时得到的是HTTP/1.1 401 Unauthorized Content-Type: application/json {error:{message:Invalid token, ...}}这个结果说明请求已经进入 API 鉴权层路由不是被前端网页接走但它仍然不能证明模型可调用因为还没有通过鉴权和模型检查。不同返回值可以这样判断返回结果通常说明什么下一步401 JSON 错误路由大概率存在但 Key 缺失或错误检查环境变量、Token 和请求头403 JSON 错误Key 已识别但权限、分组或访问策略拒绝检查模型权限、IP 白名单和账号状态404 JSON 错误路径错误或服务没有实现 Responses API检查 Base URL 和接口能力404/200 HTML请求打到了官网、反向代理或前端回退页检查 API 域名、路径和网关配置400 unknown model路由和鉴权可能已通过但模型名不可用查询模型列表或控制台权限405 Method Not Allowed请求方法错误确认使用POST四、第二步检查非流式响应结构通过鉴权后正常的 Responses API 返回不应该是 Chat Completions 的choices数组而应当具有 Responses 对象特征例如{ id: resp_..., object: response, status: completed, model: YOUR_MODEL_ID, output: [], usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 } }这里不要求字段顺序完全一致也不要求所有可选字段都出现但至少需要确认响应是 JSON不是 HTMLobject是response有明确的status文本位于 Responses 的output结构中错误时返回结构化错误而不是网关生成的一段普通网页Token 用量能正确记录避免调用成功却无法计费或对账。如果返回长这样{ choices: [ { message: { role: assistant, content: OK } } ] }这更像 Chat Completions 返回。普通 SDK 可能可以读取但不能据此认为 Codex 的 Responses 调用链已经兼容。五、第三步检查 SSE 流式事件Codex 是长时间运行的 Agent 客户端。只验证一次非流式回答还不够还要验证流式连接。执行curl -N -i --max-time 120 \ -X POST $API_BASE/responses \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -H Accept: text/event-stream \ --data {\model\:\$MODEL\,\input\:\Reply with exactly OK\,\stream\:true}首先检查响应头HTTP/1.1 200 OK Content-Type: text/event-stream然后检查事件流。事件内容会因模型和实现不同而变化但应当符合 Responses API 的 SSE 结构并能看到类似阶段event: response.created data: {...} event: response.output_text.delta data: {...} event: response.completed data: {...}OpenAI 官方文档说明Responses 流式传输使用 Server-Sent Events并通过stream: true开启。下面这些情况都值得警惕状态码 200但Content-Type是text/html返回一整块 JSON 后立即关闭并不是真正 SSE只有文本片段没有事件类型流到一半直接 EOF没有完成事件完成事件中的状态仍是failed或incomplete服务长时间不发送数据也没有心跳或合理超时网关把上游错误包装成 200 文本。这类问题常常在 Codex 中表现为stream disconnected before completion response.failed event received因此“能返回第一段文字”也不代表整个流式协议合格。六、确认通过后再配置 Codex当前官方配置参考显示用户级配置文件位于~/.codex/config.tomlWindows 通常对应%USERPROFILE%\.codex\config.toml有一个很容易忽略的变化model_provider和model_providers属于机器本地提供商配置。官方文档说明把它们写到项目目录的.codex/config.toml中会被忽略因此第三方提供商应放在用户级配置里。配置示例model YOUR_MODEL_ID model_provider genvis [model_providers.genvis] name Genvis base_url https://genvis.xyz/v1 env_key GENVIS_API_KEY wire_api responseswire_api responses当前可以省略因为它就是默认值。但排错时建议显式写出来避免以后看到配置时无法确认协议意图。不要把 Key 直接写进 TOML# not recommended experimental_bearer_token sk-xxxxxxxx官方配置参考也明确建议使用env_key而不是直接保存 Bearer Token。macOS/Linux 设置环境变量export GENVIS_API_KEYYOUR_API_KEYPowerShell$env:GENVIS_API_KEYYOUR_API_KEY配置后要从同一个新终端启动 Codex。VS Code 已经打开时插件进程可能仍然保留旧环境变量需要彻底退出后重新打开。七、Base URL 最常见的三个错误1. 重复拼接/v1如果客户端会在 Base URL 后追加/responses那么Base URL: https://api.example.com/v1 final URL: https://api.example.com/v1/responses但如果配置和网关同时追加版本路径就可能变成https://api.example.com/v1/v1/responses这种情况通常返回 404。2. 把完整接口写成 Base URL错误示例base_url https://api.example.com/v1/responses客户端继续追加/responses后可能得到https://api.example.com/v1/responses/responsesBase URL 应填公共前缀而不是某个具体操作接口除非服务商文档明确要求特殊格式。3. API 域名和官网域名混用有些网站会把未知路径统一返回首页因此错误请求也可能得到 HTTP 200。判断时必须同时看最终 URLHTTP 状态码Content-Type响应体是否为 SSE是否出现完整结束事件。八、stream disconnected不一定是换模型能解决遇到流中断时很多人的第一反应是切换模型。但可能的故障层至少有五层本机、代理、证书或网络连接Codex 客户端版本和配置API 网关的超时、缓冲或 SSE 转发上游模型的响应时间和流式实现Responses 事件格式不完整。当前官方 Codex 配置参考中自定义提供商默认的 SSE 空闲超时是 300000 毫秒流中断重试次数默认是 5。可以通过[model_providers.genvis] stream_idle_timeout_ms 300000 stream_max_retries 5进行明确配置但不要把“无限加大超时”当成通用修复。如果接口每次都在同一个固定时长中断应检查代理或网关超时如果第一条事件就解析失败应优先检查协议如果只有某个模型失败应检查模型映射、上下文和上游能力。九、一张表完成最终判断检查项合格表现不合格表现请求方法POST用浏览器或GET测试路径/v1/responses只有/v1/chat/completions鉴权结构化 401/403 或正常通过HTML 登录页、重定向页面非流式响应object: response只有choices或普通文本流式响应头text/event-streamtext/html、下载文件、普通 JSON流式过程Responses SSE 事件无事件类型、半途 EOF结束状态response.completedfailed、incomplete或无结束事件模型权限当前 Key 可调用余额有但分组无权限Codex 配置位置用户级~/.codex/config.toml把 provider 写进项目级配置Key 保存使用env_key明文写进配置或 Git十、总结判断一个第三方 API 能否供 Codex 使用不应该问“这个地址能不能打开”而应该依次问POST /v1/responses是否存在鉴权和模型权限是否通过返回的是 Responses 对象还是 Chat Completions 对象stream: true是否得到真正的 SSE事件流是否完整到达response.completedCodex 的 provider 是否写在用户级配置并从正确环境变量读取 Key完成这六项检查才能把“配置问题”“接口不兼容”“模型无权限”和“流式链路中断”分开。否则不停换模型、改 TOML、重装客户端很可能只是在重复试错。如果你正在排查可以只留下以下信息操作系统、Codex 版本、最终请求路径、HTTP 状态码、Content-Type和错误原文。不要发布 API Key、完整请求头或包含业务代码的原始日志。参考资料OpenAI 官方 Codex Configuration ReferenceOpenAI 官方 Responses APICreate a model responseOpenAI 官方 Streaming API responses更新记录2026-08-23根据当日官方配置参考核对model_providers、env_key、wire_api、SSE 超时和重试配置完成无有效 Token 的路由与鉴权层检查。