从写代码,到创作下一幕

探索 字节跳动 - 火山方舟 的 AI 编程与视频创作活动。

Agent Plan & Coding Plan

一站体验多款热门模型,为 AI 编程与智能体开发提供更多选择。新用户可联系(微信: goo_lvyouyou)免费体验 9.9 agent plan。

Seedance 2.5

让创意,跃然成片。探索 30 秒视频、多模态参考与局部编辑,把脑海中的画面变成下一支作品。

中文

连接到网关

配置模型网关,并使用原生网关 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 或凭据辅助程序。

启用 ChatGPT 登录(推荐)

如果你的组织使用 ChatGPT 工作区,登录后用户即可使用符合使用条件的功能,例如第一方插件。工作区的管控设置仍然适用,模型请求仍由网关处理。比较功能可用性。

手动设置时,请在登录前更新现有的 [model_providers.enterprise-gateway] 表:

  1. 设置 requires_openai_auth = true,并保持 base_url 指向网关。移除所有 env_key、experimental_bearer_token 和提供商 auth 设置,使 Codex 使用你的 OpenAI 凭据进行主要身份验证。
  2. 单独发送网关凭据。对于原生网关 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 登录配合使用
通过启动辅助程序复用凭据命令。同一个网关密钥从 Authorization 移至 X-Gateway-Key,而 Authorization 则由 ChatGPT 登录提供。
网关验证并移除 X-Gateway-Key,然后将 ChatGPT Authorization 和任何账户 ID 原样转发到 Codex 后端。
网关 OAuth 如何与 ChatGPT 登录配合使用
在使用 ChatGPT 登录的同时,以原生网关 OAuth 替代基于 API key 的网关身份验证。
网关处理其 OAuth cookie,并将 ChatGPT 凭据转发到 Codex 后端。

添加路由标头(可选)

使用管理员提供的路由设置。网关运营人员可以分发这些设置,并在网关日志中检查所选路由。

只有模型提供商请求使用此网关路由。语音会话使用单独的路由。工作区登录、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 路由,请分享管理员迁移检查清单。

相关文档