网关兼容性要求
查看 Codex 的网关要求
这些要求适用于通过网关使用 API/提供商凭据的连接路径。对于转发 ChatGPT 工作区请求的网关,请参阅通过网关使用 ChatGPT 登录。
采用这种接入方式时,网关必须保留此处描述的 Responses API 行为:端点、流式传输、对话延续、工具调用、身份验证、路由,以及有助于排查问题的错误信息。
请求和端点
使用 wire_api = "responses" 配置网关提供商。对于
https://gateway.example.com/v1 这样的基础 URL,网关必须接受
POST /v1/responses,并保留客户端使用的请求和响应字段。可用的 Chat Completions 或 Anthropic Messages 端点并不能证明
Responses 兼容性。
健康检查和模型列表端点是可选的运维辅助功能。它们不会测试 Codex 对话,也无法证明工具支持情况。
流式传输
以增量方式转发服务器发送事件(SSE),而不是缓冲整个回答。保留事件类型和载荷,包括表示成功结束的
response.completed 事件。转发错误和失败事件,让客户端能够区分响应失败与连接停滞。
验证经过负载均衡器、反向代理和网关的完整流。只有文本回复而没有完整结束的流是不够的。
对话延续
在后续轮次中保留重放的对话输入。网关必须接受下一轮所需的先前消息、工具调用和工具结果。
如果启用了 WebSocket 或增量传输,还需验证其
previous_response_id 行为。无状态的 HTTP Responses 路径可以使用重放的输入,而不需要该延续机制。
工具
保留函数调用项及其对应的 function_call_output 项,包括将调用与结果关联起来的标识符。完整循环必须正常工作:Codex 接收调用、执行工具、提交结果,并收到最终回答。
成功的文本请求无法验证这个循环。请测试计划启用的实际模型和客户端功能。网关接受某个请求字段,并不能证明其上游模型实现了对应能力。
身份验证和标头
支持部署时选定的客户端身份验证机制:
env_key 或基于命令的 Bearer 令牌,或者使用 env_http_headers 将凭据放在自定义标头中发送。对包含敏感信息的标头值使用环境变量;不要将其硬编码到配置中。有关配置和凭据辅助程序约定,请参阅
自定义提供商参考。
对开发者进行身份验证时,应与网关的上游提供商身份分开。将管理员密钥和上游凭据保留在网关上。保留路由和请求归属所依赖的标头,并测试凭据过期、续期和撤销。
模型路由和元数据
每个面向 Codex 的模型名称都必须路由到预期的上游模型。请在网关记录中验证路由,而不要依赖模型的自我描述。
使用已部署 Codex 版本能够识别的名称,或
为自定义别名提供匹配的目录。同时检查模型可用性和迁移元数据:任何替代模型都必须通过网关路由。对于组织自有且不涉及迁移的别名,将其目录条目的 upgrade 设置为 null。目录元数据用于指导客户端行为;它不会为模型增加能力,也不会创建网关路由。请根据实际的上游模型和提供商验证上下文限制、推理选项和工具支持情况。通用网关连接不会自动获得 Codex 内置提供商集成所做的元数据调整。
可识别的模型名称
使用已部署 Codex 版本能够识别的确切模型名称,作为网关别名和 Codex 的 model。确认上游提供商支持该模型,且组织已批准使用。
检查 codex --version,并在 Codex 模型目录中选择匹配的 rust-v<version> 标签。对于自定义构建,使用其源代码提交;对于桌面部署,匹配随附的 CLI 版本。检查条目的 slug 值,找出该版本能够识别的名称。如果网关改变了模型能力,即使名称可被识别,也应提供反映这些差异的目录元数据。
错误
保留客户端身份验证错误、未知模型路由、速率限制和上游故障之间的有效区别。不要将所有故障都归并为通用的 500 响应。返回足够的信息来诊断出错层,同时避免暴露令牌、提供商凭据或敏感的请求内容。
数据和工具边界
模型流量遵循以下路径:
Codex client -> LLM gateway -> model provider客户端使用开发者凭据向网关进行身份验证。网关使用自己的上游提供商凭据访问模型。模型请求中包含的提示词、源代码摘录、工具参数和工具结果可能会经过网关。请据此设置日志记录、保留、脱敏、访问和导出控制。
模型网关不会路由 Codex 建立的所有连接。本地命令在客户端执行环境中运行。MCP server、插件服务、浏览器和应用交互,以及其他已启用的服务,可能使用独立的网络路径和凭据。模型提供商配置不会授予这些权限,也不会替代其网络控制。有关这些边界,请参阅智能体审批与安全 和 MCP。
兼容性验证清单
为每种已部署的客户端、网关和模型组合记录以下证据:
- Responses 请求和响应字段。
- SSE 逐步传输并成功结束。
- 使用重放输入的后续对话轮次。
- 所选传输使用
previous_response_id时,其行为正常。 - 函数调用、对应结果和最终回答。
- 正确的模型路由和匹配的元数据。
- 按用户归属请求,以及凭据续期和撤销。
- 有助于排查问题的身份验证、路由、速率限制和上游错误。
- 经过脱敏的诊断信息和预期的日志策略。
使用推广测试流程 在分发配置前收集这些证据。