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