使用网关团队提供的模型提供方设置和身份验证方式,将 Codex 连接到您组织的模型网关。网关会将模型请求路由到您的后端,例如 Amazon Bedrock。
如需在整个组织中部署网关,请参阅部署网关。有关 API 必须支持的行为,请参阅网关兼容性。如需直接连接 Bedrock 而不经过网关,请参阅 Amazon Bedrock。
检查现有配置
安装管理员测试过的 Codex 客户端,并确保版本与测试时一致。如果您的组织统一管理设置,请打开该客户端,按照管理员提供的说明完成登录。您可以跳过下文中的提供方配置示例。
- 对于 CLI,请检查当前选用的配置方案并运行
codex doctor。启动 CLI 后,使用/status确认当前生效的模型和提供方。 - 对于 macOS 应用,请检查
~/.codex/config.toml或组织下发的托管配置。 - 对于 Windows 应用,请检查
%USERPROFILE%\.codex\config.toml或组织下发的系统配置。
如果预期的网关提供方和模型已经生效,请先完成管理员要求的登录步骤,然后验证连接。避免在受管理的计算机上再添加一份提供方配置。如果当前设置与管理员提供的说明不符,请先向管理员确认这些设置应由哪一层配置提供,再编辑本地文件。
获取网关连接信息
手动配置前,请确认您需要登录 ChatGPT 工作空间、通过网关身份验证,还是两者都需要。
如果您要自行配置 Codex,请向网关团队获取以下信息:
- 网关的 HTTPS 基础 URL,需包含 API 路径,例如
https://gateway.example.com/v1。 - 要使用的模型名称和提供方 ID。
- 身份验证方式:网关原生 OAuth、限定权限范围的 API 密钥及其对应的环境变量,或已安装的凭据助手。
- 对于 OAuth,需要授权 URL、令牌 URL、公共客户端 ID,以及所需的授权范围(如有)。如果网关使用 cookie 或自定义请求头,还需要相应的 cookie 名称或请求头名称。
- 所需的模型目录 URL,或者模型目录文件及其在本地的绝对路径。
配置模型提供方
在交互式 CLI 中运行 /config,打开会话 > 模型提供方。选择创建自定义提供方或网关,输入名称和基础 URL,并按需输入存储 API 密钥的环境变量名称。要修改可编辑的提供方,请打开其详情并选择编辑配置。如果您有权更改默认提供方,请将光标移到所需的提供方上,按下空格键,然后使用 /new 开始聊天。
要在登录 CLI 时设置网关,请运行 codex --enable gateway_setup_wizard,然后选择使用其他方式登录 > 使用自定义提供方或网关。此可选登录流程默认关闭。启用后,只有在 CLI 尚未登录、使用内嵌的 App Server,且同时满足以下条件时,才会显示此流程:默认提供方为 OpenAI,允许使用 API 密钥登录,且托管设置和启动时的覆盖设置均未指定提供方。
如需手动配置或设置其他身份验证选项,请打开 config.toml。在 macOS 或 Linux 上,文件路径为 ~/.codex/config.toml,在 Windows 上则为 %USERPROFILE%\.codex\config.toml。
将以下示例合并到现有配置中,并将 URL 和模型名称替换为管理员提供的值。不要重复定义已有的键或表。本示例使用 gpt-6-sol。只有当管理员确认您使用的 Codex 版本能够识别该模型,且内置的模型元数据与网关匹配时,才可以省略自定义模型目录。
请将 model、model_provider、model_catalog_json 和 web_search 放在第一个 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"
requires_openai_auth = false
然后添加网关团队提供的身份验证设置。
enterprise-gateway 是示例提供方 ID。请在 model_provider、对应的提供方表和身份验证表中使用同一个 ID。本示例在首次测试连接时禁用了网页搜索。管理员应先确认网关支持此功能,再将其启用。
配置模型目录
请与网关团队确认 Codex 通过哪种方式获取所选模型的能力信息和指令:
- 内置名称: 如果网关接受当前 Codex 版本内置的完整模型名称,并将请求路由到与该名称匹配的模型,请将
model设为该名称。Codex 已内置该模型的元数据。 - 目录端点: 如果网关提供与 Codex 兼容的元数据,请使用完整的目录 URL。该 URL 可以指向
/v1/models端点,前提是该端点按 Codex 目录响应格式返回数据。仅列出模型 ID 的响应无法满足自定义别名的要求。 - 目录文件: 如果网关使用自定义别名,且管理员分发了目录文件,请参照本地 models.json 示例进行配置。
如果管理员提供了模型目录 URL,请将其添加到已有的 [model_providers.enterprise-gateway] 表中:
model_catalog_url = "https://gateway.example.com/codex/models.json"
如果网关 OAuth 是您唯一的凭据来源,目录 URL 的协议、主机和端口必须与 base_url 一致。请先登录网关,Codex 会使用已有的网关会话获取目录。
移除所有已生效的 model_catalog_json 设置,因为它们的优先级高于目录 URL。管理员可在设置远程模型目录中查看端点要求。
如果管理员提供的是本地模型目录文件,请先保存文件,再将 model_catalog_json 添加到第一个 TOML 表之前,并将其值设为文件的绝对路径。自定义模型别名必须有相匹配的目录元数据。例如:
model_catalog_json = "/etc/codex/gateway-models.json"
请使用管理员配套提供的模型名称和目录。只有确认文件位于指定位置后,才可添加目录路径。
选择身份验证方式
如需通过浏览器或设备代码登录,请使用网关原生 OAuth。如需使用限定权限范围的凭据,请使用 API 密钥。如果组织提供了获取凭据的命令,请使用凭据助手。
使用网关原生 OAuth
网关 OAuth 独立于 ChatGPT 登录。如果网关接受由您组织的身份提供方(例如 Microsoft Entra ID)签发的访问令牌,即可使用此方式。Codex 负责处理浏览器登录并加密存储凭据。如果授权服务器签发了刷新令牌,Codex 还会负责刷新访问令牌。
如果只使用网关身份验证,Codex CLI 0.166.0 及更高版本默认通过 Authorization: Bearer <gateway access token> 发送访问令牌。请移除此提供方的 Authorization 条目,无论该条目位于 http_headers 还是 env_http_headers 中。
网关团队必须注册一个支持 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
# device_authorization_url = "https://login.example.com/oauth/device"在此表中添加 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 密钥,必须先让网关支持 OAuth 令牌及其传递方式,才能使用此流程。网关仍自行管理上游凭据,例如用于访问 Bedrock 的 AWS 凭据。
如果 OAuth 是您唯一的凭据来源,请保留 requires_openai_auth = false,并移除之前用于配置网关凭据的 env_key、experimental_bearer_token 或 auth 设置。
重新启动桌面应用,按照网关登录提示打开浏览器。如果您使用 CLI,请启动 codex 并按提示登录。完成组织要求的登录和 MFA 后,返回 Codex。如果授权已过期或 Codex 无法刷新授权,请在收到提示时重新登录。
如果通过 SSH 连接或使用没有浏览器的终端,请将 device_authorization_url 设为身份提供方给出的设备授权端点。需要登录时,交互式 CLI 会显示验证 URL 和一次性代码。在浏览器中打开该 URL 并输入代码即可。此流程无需端口转发。
如果身份提供方仅支持浏览器登录,且您通过 SSH 运行 CLI,请设置 redirect_port = 43127,并注册相应的重定向 URI。启动 Codex 之前,请在浏览器所在的计算机上运行以下命令,转发该端口:
ssh -L 43127:127.0.0.1:43127 user@remote在该 SSH 会话中启动 codex,并在本地浏览器中打开网关登录 URL。在容器中使用浏览器登录流程时,也需要确保浏览器可以访问回调地址。如果浏览器无法访问该地址,请使用设备授权、API 密钥或凭据助手。
使用 API 密钥
如果网关要求通过 Authorization 请求头传递 API 密钥,请使用此设置。
在已有的 [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。在这种情况下,Codex 不会执行远程目录发现。
使用组织提供的凭据助手
如果凭据助手为提供方提供主要身份验证凭据,请使用管理员安装的助手及其配置,无需设置 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 登录,同时通过助手获取网关令牌,请省略提供方的 auth 表,并设置 requires_openai_auth = true。配置网关凭据导出命令,并指定网关接受的请求头或 cookie:
[model_providers.enterprise-gateway.gateway_oauth]
delivery = { kind = "cookie", name = "gateway_session" }
[model_providers.enterprise-gateway.gateway_oauth.credential_export]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]该命令必须向标准输出写入一个访问令牌。首次需要令牌时,Codex 会运行该命令,并将令牌缓存在内存中。如果网关返回 HTTP 401 拒绝推理请求,Codex 会再次运行该命令,然后重试一次请求。使用 credential_export 时,请省略 OAuth 客户端 ID 和端点设置。
您也可以在启动 Codex 之前运行助手,并通过自定义网关请求头传递令牌。令牌过期后,请更新令牌并重新启动 Codex。
助手可执行文件和模型目录文件都应使用解析后的绝对路径。
启用 ChatGPT 登录(推荐)
如果您的组织使用 ChatGPT 工作空间,用户登录后即可使用其有权访问的功能,例如第一方插件。工作空间的管控设置会生效,模型请求仍由网关处理。比较可用功能。
如果您手动配置 Codex,请在登录前更新已有的 [model_providers.enterprise-gateway] 表:
- 设置
requires_openai_auth = true,并确保base_url仍指向您的网关。移除已有的env_key、experimental_bearer_token以及提供方的auth设置,以便 Codex 使用您的 OpenAI 凭据进行主要身份验证。 - 单独发送网关凭据。如果使用网关原生 OAuth 或网关凭据导出命令,请配置
gateway_oauth.delivery,指定网关接受的 cookie 或自定义请求头。如果使用静态 API 密钥,请使用自定义身份验证请求头。请将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 服务器和插件也可能使用其他网络路径。
启动客户端
如果使用 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 服务器和插件。模型网关凭据不授予访问工具或已连接系统的权限。
验证连接
请使用管理员提供的提供方 ID 和模型别名。提供方 ID 标识已配置的连接,模型别名标识通过该连接访问的模型。ChatGPT 登录和网关身份验证分别控制访问权限,您可能需要同时完成两项验证。
更改配置后,请重新启动客户端。在 CLI 中启动 codex,然后使用 /status 查看当前生效的模型和提供方。在桌面应用中,请检查选用的模型和配置。
在新任务中发送以下提示词:
请只回复以下内容:gateway-ok
预期回复为 gateway-ok。仅凭回复无法确定处理请求的路由。请让管理员确认网关已记录您的用户身份、模型别名和预期的上游路由。不要通过询问模型自身的名称来判断其身份。
排查连接问题
| 问题 | 检查方法 |
|---|---|
| 预期的提供方未生效。 | 检查当前选用的配置方案和配置优先级。确认顶层键没有被放入提供方表中。 |
| OAuth 登录或令牌传递失败。 | 检查公共客户端注册信息、重定向 URI、授权范围,以及配置的 cookie 或请求头。确认网关接受已签发的访问令牌。 |
| 使用 API 密钥或凭据助手进行身份验证时失败。 | 检查客户端进程能否读取存储凭据的环境变量,或已安装的助手能否获取有效令牌。请管理员确认失败的是网关身份验证还是上游身份验证。 |
| 找不到模型。 | 核实管理员提供的模型名称,并请管理员检查该模型的路由。 |
| 模型使用的功能与预期不符。 | 请管理员检查目录元数据是否与别名指向的模型匹配。 |
| 流式响应停滞或后续对话失败。 | 请网关负责人检查代理缓冲设置、标志响应结束的 response.completed 事件,以及网关兼容性。 |
| 模型目录或凭据助手的路径无效。 | 确认在运行 Codex 的环境中,配置的绝对路径下确实存在相应文件。 |
请求帮助时,请说明客户端版本、操作系统、预期使用的提供方和模型别名、身份验证方式,以及具体在哪一步失败。请附上错误消息和请求时间,以便网关负责人查找该请求。发送前请移除令牌、cookie、授权请求头和敏感提示词。不要发送凭据文件或含有机密信息的配置转储。
使用现有网关部署
请向网关团队获取 Codex 的提供方设置和已获批准的模型别名。如果团队还需要启用 Codex 路由,请将管理员迁移检查清单发给他们。