网关兼容性要求

Codex 网关必须保留此处介绍的 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 时，其行为正常。
• 函数调用、对应结果和最终回答。
• 正确的模型路由和匹配的元数据。
• 按用户归属请求，以及凭据续期和撤销。
• 有助于排查问题的身份验证、路由、速率限制和上游错误。
• 经过脱敏的诊断信息和预期的日志策略。

使用推广测试流程 在分发配置前收集这些证据。