连接到网关
配置模型网关,并使用原生网关 OAuth、API key 或凭据辅助程序进行身份验证。
使用网关团队提供的提供商设置和身份验证方法,将 Codex 连接到组织的模型网关。网关会将模型请求路由到你的后端,例如 Amazon Bedrock。
检查现有配置
安装管理员测试过的 Codex 客户端及版本。如果你的组织统一管理设置,请打开该客户端,并完成交接说明中的登录步骤。你可以跳过下方的提供商配置示例。
- 对于 CLI,检查所选配置档案并运行
codex doctor。启动后,使用/status确认当前模型和提供商。 - 对于 macOS 应用,检查
~/.codex/config.toml或组织下发的托管配置。 - 对于 Windows 应用,检查
%USERPROFILE%\.codex\config.toml或组织下发的系统配置。
如果预期的网关提供商和模型已处于启用状态,请完成管理员提供的登录步骤,然后继续验证连接。避免向受管理的计算机添加第二份提供商配置。如果设置与管理员的交接说明不符,请先询问这些设置应由哪个配置层提供,再编辑本地文件。
获取网关连接信息
手动设置时,请确认你需要登录 ChatGPT 工作区、进行网关身份验证,还是两者都需要。
要自行配置 Codex,请向网关团队获取以下值:
- HTTPS 网关基础 URL,包括其 API 路径,例如
https://gateway.example.com/v1。 - 要使用的模型名称和提供商 ID。
- 身份验证方式:原生网关 OAuth、限定权限范围的 API key 及其环境变量,或已安装的凭据辅助程序。
- 对于 OAuth,需要授权 URL、令牌 URL、公共客户端 ID 以及所有必需的权限范围。对于使用 cookie 或自定义标头的网关,需要相应的名称。
- 任何必需的模型目录 URL,或目录文件及其本地绝对路径。
配置提供商
在 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"
requires_openai_auth = false然后添加网关团队提供的身份验证设置。
enterprise-gateway 是示例提供商 ID。请在
model_provider 及其提供商表和身份验证表中使用相同的 ID。此示例在初始连接测试时禁用网页搜索功能;管理员应先验证功能支持情况,再启用该功能。
配置模型目录
向网关团队确认 Codex 如何获取所选模型的能力信息和指令:
- 内置名称: 如果网关接受当前 Codex 版本内置的确切模型名称,并将其路由到对应模型,请将
model设置为该名称。Codex 已有其元数据。 - 目录端点: 如果网关提供与 Codex 兼容的元数据,请使用其完整的目录 URL。该 URL 可以是实现了 Codex 目录响应的
/v1/models端点。仅列出模型 ID 的响应不足以支持自定义别名。 - 目录文件: 如果网关使用自定义别名,且管理员分发了文件,请使用本地 models.json 示例。当原生网关 OAuth 是唯一凭据且你需要自定义元数据时,请使用本地文件。
对于使用 API key 或辅助程序的身份验证,如果管理员提供了模型目录
URL,请将其添加到现有的
[model_providers.enterprise-gateway] 表中:
model_catalog_url = "https://gateway.example.com/codex/models.json"移除所有生效的 model_catalog_json 设置;它的优先级高于 URL。管理员可参阅远程目录设置,了解端点要求。
如果管理员提供了本地模型目录文件,请将其保存到本地,并在第一个 TOML 表之前添加 model_catalog_json,使用该文件的绝对路径。自定义别名需要匹配的目录元数据。例如:
model_catalog_json = "/etc/codex/gateway-models.json"使用管理员配套提供的模型名称和目录。只有文件确实存在于指定位置时,才添加目录路径。
选择身份验证方法
使用原生网关 OAuth 通过浏览器登录,使用 API key 作为具有特定权限范围的凭据,或在组织提供相应命令时使用凭据辅助程序。
{/* prettier-ignore */}
使用原生网关 OAuth
网关 OAuth 独立于 ChatGPT 登录。当网关接受由你的组织身份提供商(例如 Microsoft Entra ID)签发的访问令牌时,可使用此方式。Codex 负责浏览器登录、凭据加密存储,以及在授权服务器签发刷新令牌时刷新令牌。
仅使用网关身份验证时,Codex CLI 0.166.0 及更高版本默认通过 Authorization: Bearer <gateway access token> 发送访问令牌。请移除此提供商的 http_headers 或 env_http_headers 中的所有 Authorization 条目。
网关团队必须注册一个支持带 PKCE 的授权码流程的公共 OAuth 客户端。将此表添加到
config.toml 中的提供商配置,并将 URL 和客户端 ID 替换为实际值:
[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127根据身份提供商和网关的要求,在此表中添加 scopes,并在需要时添加 resource。如果提供商要求使用特定权限范围才能签发刷新令牌,请请求这些权限范围。Codex 默认使用可用的回环端口。如果身份提供商要求固定的重定向 URI,请设置 redirect_port,并为此示例注册 http://127.0.0.1:43127/callback。
如果网关要求使用 cookie 或自定义标头,请在 OAuth 表中设置可选的 delivery 字段。选择网关验证的方式:
delivery = { kind = "cookie", name = "auth-openid" }delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }如果部署还要求登录 ChatGPT,请使用上述 cookie 或单独的网关标头。请参阅启用 ChatGPT 登录。
对于仅接受静态 API key 的网关,必须先添加对 OAuth 令牌及其传递方式的支持,才能使用此流程。网关继续管理自己的上游凭据,例如用于 Bedrock 的 AWS 凭据。
当 OAuth 是唯一凭据时,保留 requires_openai_auth = false,并移除之前用于网关凭据的 env_key、experimental_bearer_token 或 auth
设置。如果需要自定义模型元数据,请使用本地模型目录;仅使用 OAuth 无法启用远程目录发现。
重启桌面应用,并按照网关登录提示打开浏览器。在 CLI 中,启动 codex,并在 Codex 首次访问网关时按照提示通过浏览器登录。完成组织的登录和 MFA,然后返回客户端。如果授权过期或 Codex 无法刷新授权,请在收到提示时重新登录。
原生网关 OAuth 需要浏览器和可访问的回环回调地址。它不提供设备代码备用方式。如果通过 SSH 运行 CLI,请在
OAuth 表中设置 redirect_port = 43127,并注册上述匹配的重定向 URI。在运行浏览器的计算机上,先转发该端口,再启动 Codex:
ssh -L 43127:127.0.0.1:43127 user@remote在该 SSH 会话中,启动 codex,并在本地浏览器中打开网关登录 URL。容器内的 CLI 同样需要能从浏览器访问的回调地址。如果无法使回调地址可访问,请改用 API key 或凭据辅助程序。
使用 API key
当网关要求在 Authorization 标头中提供 API key 时,使用此设置。
在现有的
[model_providers.enterprise-gateway] 表中添加以下设置:
env_key = "CODEX_GATEWAY_API_KEY"通过组织的敏感信息下发机制,在启动 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,请参阅配置参考。
使用 ChatGPT 登录时,通过自定义标头传递网关密钥,以便 Codex 在 Authorization 中发送用户的 OpenAI 凭据。
如果自定义请求头是唯一的身份验证机制,请使用
model_catalog_json;远程目录发现不会运行。
使用组织的凭据辅助程序
如果管理员提供了基于命令的身份验证,请使用其安装的辅助程序和配置来替代 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自定义提供商身份验证参考 定义了命令、参数、超时、刷新间隔和令牌输出约定。如果辅助程序无法再获取令牌,请向管理员询问如何重新登录。
使用 ChatGPT 登录时,请在启动 Codex 之前运行辅助程序,并通过自定义网关标头传递其输出,而不是配置 auth 表。密钥过期后,请获取新密钥并重新启动 Codex。
为辅助程序可执行文件和目录文件使用解析后的绝对路径。
启用 ChatGPT 登录(推荐)
如果你的组织使用 ChatGPT 工作区,登录后用户即可使用符合使用条件的功能,例如第一方插件。工作区的管控设置仍然适用,模型请求仍由网关处理。比较功能可用性。
手动设置时,请在登录前更新现有的 [model_providers.enterprise-gateway] 表:
- 设置
requires_openai_auth = true,并保持base_url指向网关。移除所有env_key、experimental_bearer_token和提供商auth设置,使 Codex 使用你的 OpenAI 凭据进行主要身份验证。 - 单独发送网关凭据。对于原生网关 OAuth,请配置
gateway_oauth.delivery,以使用网关接受的 cookie 或自定义标头。对于 API key 或凭据辅助程序,请使用自定义身份验证标头。将Authorization专用于 OpenAI 凭据。
登录管理员指定的 ChatGPT 工作区。如果出现提示,请完成网关登录,然后验证连接。
管理员可以分发托管的提供商设置并验证凭据转发。
在网关处处理凭据
网关在每个模型请求中都会收到两个凭据。例如,Codex 在 cookie 中发送网关 OAuth 令牌时:
POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>验证网关凭据,并移除其 cookie 或自定义标头。对日志中的凭据和敏感请求数据进行脱敏。选择用于上游请求的凭据:
- 转发用户凭据,直接使用 OpenAI 推理(推荐)。 这样,OpenAI 就能将用量归属到该用户,并应用该用户的推理设置。采用此路由时,网关必须将
/models和/responses代理到https://chatgpt.com/backend-api/codex,并原样转发Authorization和任何ChatGPT-Account-ID标头。 - 让网关向推理提供商进行身份验证。 使用网关上为该提供商配置的凭据。不要在上游请求中包含用户的 OpenAI 令牌或任何
ChatGPT-Account-ID标头。
以下示意图展示了 OpenAI 推理的推荐路由。
网关密钥如何与 ChatGPT 登录配合使用


网关 OAuth 如何与 ChatGPT 登录配合使用


添加路由标头(可选)
使用管理员提供的路由设置。网关运营人员可以分发这些设置,并在网关日志中检查所选路由。
只有模型提供商请求使用此网关路由。语音会话使用单独的路由。工作区登录、MCP server 和插件也可能使用其他网络路径。
启动客户端
使用 ChatGPT 登录时,请启动客户端并登录提供受管配置的工作区。如果使用原生网关 OAuth,还需在收到提示时完成组织的网关登录。然后验证连接。
对于在本地配置的提供商,请按照所用客户端的说明操作。
配置 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 和插件。模型网关凭据并不授予访问工具或已连接系统的权限。
验证连接
使用管理员交接资料中的提供商 ID 和模型别名。提供商标识已配置的连接;模型别名标识通过该连接路由的模型。ChatGPT 登录和网关身份验证用于控制访问权限,可能需要同时使用。
更改配置后,重启客户端。在 CLI 中,启动 codex
并使用 /status 检查当前模型和提供商。在桌面应用中,检查所选模型和配置。
在新任务中发送以下提示词:
Reply with exactly: gateway-ok预期得到 gateway-ok。仅凭响应无法证明由哪条路由处理了请求:请让管理员确认网关记录了你的用户、模型别名和预期的上游路由。不要通过询问模型的名称来识别模型。
排查连接问题
| 症状 | 检查项 |
|---|---|
| 预期的提供商未启用。 | 检查所选配置档案和配置优先级。确认顶层键未放在提供商表内。 |
| OAuth 登录或令牌传递失败。 | 检查公共客户端注册信息、重定向 URI、作用域以及配置的 cookie 或请求头。确认网关接受已签发的访问令牌。 |
| API key 或辅助程序身份验证失败。 | 检查凭据变量是否传入客户端进程,或已安装的辅助程序是否能获取当前有效的令牌。请管理员区分网关身份验证和上游身份验证。 |
| 找不到模型。 | 确认提供的模型名称,并请管理员检查其路由。 |
| 模型使用了非预期的能力。 | 请管理员检查目录元数据是否与别名背后的模型匹配。 |
| 流式传输停滞或后续交互失败。 | 请网关负责人检查代理缓冲、表示结束的 response.completed 事件以及网关兼容性。 |
| 目录或辅助程序路径不可用。 | 确认文件位于运行 Codex 的环境中配置的绝对路径下。 |
请求帮助时,请提供客户端版本、操作系统、预期的提供商和模型别名、身份验证方式以及失败的步骤。附上错误消息和请求时间,以便网关负责人定位请求。移除令牌、cookie、授权标头和敏感提示词。不要发送凭据文件或包含密钥的配置转储。
使用现有网关部署
向网关团队索取 Codex 提供商设置和获准使用的模型别名。如果团队仍需启用 Codex 路由,请分享管理员迁移检查清单。