如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

网关兼容性要求

检查网关是否满足 Codex 的要求

这些要求适用于使用 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 在所选传输方式使用它时能正常工作。
  • 函数调用能获得匹配的结果,客户端能收到最终回答。
  • 模型路由正确,元数据与模型匹配。
  • 能识别请求所属的用户,并能按用户续期和撤销凭据。
  • 身份验证、路由、速率限制和上游故障均能返回有助于诊断的错误信息。
  • 诊断信息已脱敏,日志记录符合预期策略。

分发配置前,请按照部署测试步骤收集上述验证证据。