通过网关部署 Codex

通过组织的 LLM 网关部署 Codex。配置模型路由、签发开发者凭据，并分发经过验证的 Codex 配置。

前提条件

向开发者部署 Codex 之前，请确认已具备：

• 在将要分发的确切基础 URL 上提供 HTTPS 服务的网关。
• 由网关持有的上游提供商凭据。
• 已获批准、面向 Codex 的模型别名，并已映射到预期的上游模型。
• 限定权限范围的测试网关凭据。
• 敏感信息分发机制或经过测试的凭据辅助程序。
• 分发配置、辅助程序可执行文件及目录文件的方式。

网关要求

连接 Codex 之前，请验证网关产品是否保留以下必需行为：

• 在 POST /v1/responses 接受 Codex Responses API 请求。
• 无缓冲地流式传输 SSE 事件，并以 response.completed 结束。
• 支持通过重放输入延续后续对话。
• 仅在启用 WebSocket 或增量传输时保留 previous_response_id。
• 保留函数调用及对应的 function_call_output 项。
• 将每个面向 Codex 的模型别名路由到预期的上游模型。
• 分别对用户进行身份验证，并返回有助于排查问题且不掩盖原因的错误。

健康检查端点、/v1/models、Chat Completions 响应或一次纯文本回复，都不足以证明网关符合要求。有关详细约定，请参阅网关兼容性要求。

推广网关

要从已部署的网关过渡到经过验证的开发者使用环境，请按顺序完成以下五项检查：

1. 选择模型名称并验证路由。
2. 签发开发者凭据。
3. 通过网关测试 Codex。
4. 分发配置。
5. 在开发者机器上验证。

选择模型名称和路由

将 Codex 的 model 设置为网关的模型名称。配置网关，将该名称路由到已获批准的上游模型。

为自定义名称使用模型目录

如果网关使用的模型名称无法被 Codex 识别，请使用 model_catalog_json。目录提供 Codex 针对该名称使用的指令、推理选项、上下文限制和工具能力。如果没有匹配的条目，请求可能会到达预期的上游模型，但 Codex 会使用通用设置。

例如，要将 company-coding-model 用作 gpt-6-luna 的别名：

1. 在网关上创建 company-coding-model 别名，并将其路由到已获批准的上游 gpt-6-luna 模型。
2. 下载适用于你的 Codex 版本的 Codex 模型目录，并将副本保存为 gateway-models.json。以此文件为起点。
3. 编辑副本中的 gpt-6-luna 条目：将 slug 设置为 company-coding-model，并检查其余元数据是否与上游模型和网关能力匹配。对于不涉及模型迁移的别名，将 upgrade 设置为 null。
4. 将条目保留在顶层 models 数组中，并将文件分发到每个客户端。自定义目录会替换随附目录，因此应包含用户需要选择的所有模型。

通过 LiteLLM 使用 Bedrock 时，请应用必需的目录修改。

将网关别名、目录中的 slug 和 Codex 的 model 设置为 company-coding-model。在分发的 Codex 配置中，将以下设置添加到第一个 TOML 表之前，并使用文件的实际绝对路径：

model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"

更改目录后，请重启 CLI 或桌面应用，因为 Codex 会在启动时加载目录。

验证模型路由

对每个模型，使用真实的 Responses 请求和网关 记录验证路由。/v1/models 响应可以帮助发现名称，但不能证明 模型支持所需的请求和工具行为。

模型路由和工具授权是推广过程中的两个独立部分。请分别配置 MCP 连接、插件分发及其策略。

签发开发者凭据

1. 为每位开发者签发一个限定权限范围的网关凭据，以便将用量归属于具体开发者 并单独撤销访问权限。
2. 为每个凭据设置获准使用的模型、速率限制、预算、有效期和续期周期 。
3. 通过敏感信息管理器或已安装的凭据 辅助程序分发凭据。不要将上游提供商和网关管理员凭据存放在 开发者机器上。
4. 如果使用辅助程序，请遵循 基于命令的身份验证约定 ，并在分发前测试令牌获取和刷新。
5. 告知开发者如何续期凭据，以及遇到问题时应联系谁。

通过网关测试 Codex

分发任何内容之前，请按照连接到网关中的说明，为一个隔离的测试用户配置计划分发的提供商配置块和凭据机制。

在开发者将使用的同一种 CLI 或桌面界面中运行以下检查：

这些检查通过后，引导开发者参阅连接到网关，配置并验证自己的机器。

分发配置

要让每台机器使用相同的连接方式，请分发网关基础 URL、 提供商 ID、获准使用的模型别名和凭据机制。

分发内容

要设置提供商默认值，请通过选定的配置层分发以下 config.toml 配置块。使用你的 Codex 版本能够识别的模型，或提供上文所述的匹配目录。将令牌解析程序安装到配置的命令路径：

model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

对于短期有效的静态测试密钥，移除身份验证配置块，将 env_key = "CODEX_GATEWAY_API_KEY" 放入 [model_providers.enterprise-gateway] 中，并在 TOML 之外设置该变量。不要将 env_key 与基于命令的身份验证结合使用。

分发默认值和强制要求

使用配置优先级 选择分发默认值的位置。有关强制设置和 macOS MDM 载荷，请参阅受管配置。

对于 macOS 或 Linux 上的整机默认值，使用 /etc/codex/config.toml。在 Windows 上，将 config.toml 放入 %ProgramData%\OpenAI\Codex\。用户和 配置档案可以覆盖这些默认值。链接中的参考资料介绍了支持的 强制要求及其文件位置。

单独分发引用的辅助程序可执行文件和目录文件。

model_catalog_json 指向本地 JSON 文件。如果通过 requirements.toml 强制设置它，该要求只会固定路径；不会分发 文件。请在 Codex 启动前将目录放到该绝对路径。

在 TOML 中写入已解析的 Windows 绝对路径。Codex 不会展开 model_catalog_json 或提供商身份验证 command 值中的 %ProgramData%。例如， 只有在部署时将文件放到以下位置后，才能使用这些路径：

model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'

[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]

WSL 中的 CLI 读取 Linux 路径和 Linux 的 CODEX_HOME；不会自动 继承原生 Windows 配置。

向开发者提供配置值

如果没有受管分发机制，请向每位开发者提供网关 URL、提供商 ID、模型别名、凭据变量或解析程序，以及所需的目录路径。引导他们参阅连接到网关，配置并验证自己的机器。

手动设置不是强制配置渠道。项目本地的 .codex/config.toml 无法覆盖敏感的提供商或身份验证路由键。

在开发者机器上验证

要确认分发的设置已到达开发者机器：

1. 重启 Codex，并确认预期的提供商和模型。
2. 运行连接到网关中的简短测试。
3. 继续提问一次以确认对话延续正常，然后在网关日志中检查该 开发者的请求。

排查推广过程中的故障

根据问题定位需要处理的配置层、凭据层或网关层：

复用现有网关部署

如果组织已经通过网关使用 Claude Code，你或许可以 复用网关产品、网络路径、日志记录和 Bedrock 访问。添加 面向 Codex 的 Responses 路由、凭据、模型别名和 config.toml，同时 保留现有可用配置。Claude 客户端设置和 /v1/messages 约定不会配置 Codex。

要安全迁移，请按顺序完成以下步骤：

1. 盘点当前 Claude 的连接路径：网关 URL、凭据来源、必需标头、模型别名、Bedrock 配置档案映射和受管分发渠道。
2. 并行添加面向 Codex 的 Responses 路由和 Codex 模型别名。
3. 签发一个限定权限范围的 Codex 凭据。如果 Codex 将使用静态凭据，通过 env_key 提供该新凭据；如果 Claude 使用凭据辅助程序，则实现并测试 Codex 基于命令的解析程序约定。
4. 使用提供商配置块为该开发者进行配置。对于受管推广，按照通过网关部署 Codex中介绍的 Codex 路径和优先级转换载荷。
5. 在开发者实际使用的 CLI 或桌面界面中运行简短连接检查，然后运行通过网关测试 Codex中的完整流式传输、对话延续、工具调用、错误、日志记录和别名路由检查。
6. 试点通过后，向其余开发者分发配置。

相关文档

• 连接到网关
• MCP
• 插件
• 受管配置