连接到网关

使用组织提供的网关 URL、模型别名以及凭据 或令牌解析器，将 Codex 连接到 LLM 网关。

检查现有配置

添加任何配置前，先检查管理员是否已经配置了 Codex。

• 对于 CLI，检查所选配置档案并运行 codex doctor。启动后， 使用 /status 确认当前模型和提供商。
• 对于 macOS 应用，检查 ~/.codex/config.toml 或组织下发的托管 配置。
• 对于 Windows 应用，检查 %USERPROFILE%\.codex\config.toml 或组织下发的系统 配置。

如果预期的网关提供商和模型已启用，请继续 验证连接。

获取网关连接信息

安装 Codex CLI 或组织批准的桌面 应用。要自行配置 Codex，请向网关团队获取以下值：

• HTTPS 网关基础 URL，包括其 API 路径，例如 https://gateway.example.com/v1。
• 要使用的模型名称和提供商 ID。
• 具有限定权限范围的网关凭据及其环境变量，或已安装的 令牌解析器及其配置。
• 所需的模型目录文件及其本地绝对路径。

配置提供商

在 macOS 或 Linux 上，打开位于 ~/.codex/config.toml 的 config.toml；在 Windows 上，打开 %USERPROFILE%\.codex\config.toml。

将此示例合并到现有配置中，用管理员提供的值替换 URL 和模型。 不要重复定义已有的 键或表。此示例使用 gpt-6-sol；只有管理员确认你的 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"
env_key = "CODEX_GATEWAY_API_KEY"

如果管理员提供了模型目录，请将其保存到本地，并在 第一个 TOML 表之前添加 model_catalog_json，使用该文件的绝对路径。 自定义别名需要匹配的目录元数据。例如：

model_catalog_json = "/etc/codex/gateway-models.json"

使用管理员配套提供的模型名称和目录。只有文件确实存在于 指定位置时，才添加目录路径。

enterprise-gateway 是示例提供商 ID。在 model_provider、[model_providers.<id>] 和 [model_providers.<id>.auth] 中使用相同的 ID。 此示例禁用了网页搜索， 以便进行初始连接测试；管理员应在启用该功能前验证 网关是否支持。

通过组织的敏感信息下发机制，在启动 Codex 的进程环境中， 将网关凭据提供为 CODEX_GATEWAY_API_KEY。 不要将凭据放入 TOML 或仓库。在终端中设置的变量 可能无法被从桌面启动的应用访问。

使用自定义身份验证请求头

如果网关要求使用 X-API-Key 等请求头，而不是 bearer 令牌， 请将提供商表中的 env_key 替换为：

env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }

使用管理员提供的准确请求头名称。Codex 会从 指定的环境变量中读取值；不要将凭据写入配置文件。 有关 model_providers.<id>.env_http_headers，请参阅配置参考 。

使用组织的凭据辅助程序

如果管理员提供基于命令的身份验证，请使用其已安装的 辅助程序和配置，代替 env_key。不要同时配置这两种机制。 辅助程序必须已存在于你的计算机上；Codex 不会安装它。例如， 使用管理员提供的解析器路径和参数，将示例中的 env_key 设置 替换为以下表：

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

自定义提供商身份验证参考 定义了命令、参数、超时、刷新间隔和令牌输出 约定。如果辅助程序无法再获取令牌，请向管理员询问如何 重新登录。

为辅助程序可执行文件和目录文件使用解析后的绝对路径。

配置 CLI

在 macOS 或 Linux 上，CLI 默认读取 ~/.codex/config.toml。保存 提供商设置后，运行 codex。在 WSL 中，使用 Linux 配置和 路径，除非 CODEX_HOME 指向其他位置。

配置 macOS 应用

macOS 应用读取同一个 ~/.codex/config.toml。保存提供商 设置后，重启应用。如果使用环境变量提供凭据， 请确保应用进程可以访问该变量。

配置 Windows 应用

将提供商设置放入 %USERPROFILE%\.codex\config.toml，然后重启 应用。对于基于命令的身份验证，使用管理员安装的 解析器。例如，将 Unix 身份验证表替换为：

[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

在 Windows TOML 中，单引号字面量字符串会保留反斜杠。还要替换 Unix 目录路径，例如替换为 'C:\ProgramData\OpenAI\Codex\models.json'，并使用管理员提供的 实际路径。

单独配置 MCP server和插件。模型网关凭据并不 授予访问工具或已连接系统的权限。

验证连接

更改配置后，重启客户端。在 CLI 中，启动 codex 并使用 /status 检查当前模型和提供商。在桌面应用中， 检查所选模型和配置。

在新任务中发送以下提示词：

Reply with exactly: gateway-ok

预期得到 gateway-ok。仅凭响应无法证明由哪条路由处理了请求：请让 管理员确认网关记录了你的用户、模型别名 和预期的上游路由。不要通过询问模型的名称来识别模型。

这可以验证初始连接。管理员还应完成 推广部署检查， 验证流式传输、工具和后续对话轮次。

排查连接问题

请求帮助时，请附上已移除令牌和敏感提示词的错误消息。

使用现有网关部署

如果组织已通过网关使用其他编程工具，你或许可以 复用其网络路径、日志记录和提供商访问权限。与 网关团队协作，配置并测试 Codex 连接：

1. 确认现有网关 URL、凭据机制、必需的请求头、 模型路由和配置下发方式。
2. 请网关团队确认网关支持 Codex 所需的 API 行为，并 配置 Codex 模型路由。
3. 向网关团队获取具有限定权限范围的网关凭据或凭据辅助程序、模型名称， 以及所需的模型目录。
4. 使用这些值配置 Codex。
5. 在你计划使用的 CLI 或桌面应用中验证连接。 请网关团队完成 流式传输、工具和后续对话检查。
6. 试点通过后，按照 通过网关部署 Codex 的说明，将 配置分发给其他开发者。

有关管理员迁移检查清单和配置映射，请参阅 复用现有网关部署。

相关文档

• Codex CLI
• MCP server
• 插件