如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

连接到网关

配置模型网关,并使用网关原生 OAuth、API 密钥或凭据助手进行身份验证。

使用网关团队提供的模型提供方设置和身份验证方式,将 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 密钥或凭据助手。

启用 ChatGPT 登录(推荐)

如果您的组织使用 ChatGPT 工作空间,用户登录后即可使用其有权访问的功能,例如第一方插件。工作空间的管控设置会生效,模型请求仍由网关处理。比较可用功能。

如果您手动配置 Codex,请在登录前更新已有的 [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 密钥,请使用自定义身份验证请求头。请将 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 路由,请将管理员迁移检查清单发给他们。

相关文档