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

在组织内推广网关

为组织分发 Codex 网关连接配置并验证连接

作为网关管理员,请先配置模型路由,并为一位试点用户授权。在向开发者分发设置之前,请在每种受支持的客户端上测试连接。网关身份验证可使用网关原生 OAuth、API 密钥或凭据助手。如果需要同时使用网关身份验证和 ChatGPT 工作空间登录,请参阅通过网关使用 ChatGPT 登录。

如果您已收到配置值,要在自己的机器上配置 Codex,请参阅配置提供商。在选择或推广网关之前,请先查看网关兼容性要求。

前提条件

在向开发者部署 Codex 之前,请确认以下条件均已满足:

  • 网关通过 HTTPS 提供服务,其基础 URL 与您将分发的地址完全一致。
  • 网关持有上游提供商的凭据。
  • 已获批的 Codex 模型别名均已映射到预期的上游模型。
  • 已测试所选的身份验证方式:网关原生 OAuth、限定权限范围的网关 API 密钥或凭据助手。
  • 如果使用 OAuth,已注册公共客户端,已授权测试用户登录,并且网关支持验证 OAuth 访问令牌。
  • 如果使用 API 密钥或凭据助手,已有安全分发凭据的机制或经过测试的凭据助手。
  • 有办法分发配置、所需的凭据助手和模型目录文件。

网关要求

在连接 Codex 之前,请验证网关产品能否满足以下要求:

  • 在 POST /v1/responses 接受 Codex 的 Responses API 请求。
  • 以流式方式转发 SSE 事件,不做缓冲,并以 response.completed 结束事件流。
  • 支持重放输入,使后续请求能够延续对话。
  • 仅在启用 WebSocket 或增量传输时保留 previous_response_id。
  • 保留函数调用及其对应的 function_call_output 项。
  • 将 Codex 使用的每个模型别名路由到预期的上游模型。
  • 分别验证每个用户的身份,并返回能帮助排查问题的错误信息,明确说明出错原因。

仅凭健康检查端点、/v1/models、Chat Completions 响应或一次纯文本回复,无法确认网关符合要求。详细规范请参阅网关兼容性要求。

需要配置示例?Codex 部署指南代码仓库提供了多种 LLM 网关产品的完整配置示例。确认您的网关满足上述要求后,即可参考这些示例。

在组织内推广网关

网关部署完成后,请依次完成以下五个步骤,验证开发者可以通过网关使用 Codex:

  1. 选择模型名称并验证路由。
  2. 选择身份验证方式。
  3. 通过网关测试 Codex。
  4. 分发配置。
  5. 在开发者机器上验证。

选择模型名称和路由

将 Codex 的 model 设为网关使用的模型名称。配置网关,将使用该名称的请求路由到获批的上游模型。

网关模型名称 Codex 配置
您使用的 Codex 版本包含的内置模型名称 将 model 在 config.toml 中的值设为与该名称完全一致的字符串。
自定义别名,例如 company-coding-model 提供远程或本地模型目录,其中包含该别名及对应模型的元数据。

为自定义名称提供模型目录

如果使用本地目录,可以从 models.json 示例入手。

如果 Codex 无法识别网关使用的模型名称,请提供模型目录。目录指定 Codex 使用该名称时应采用的指令、推理选项、上下文限制和工具能力。如果没有匹配的条目,即使请求到达预期的上游模型,Codex 也可能使用通用设置。

您可以托管远程目录并通过 model_providers.<id>.model_catalog_url 指定其地址,以便集中更新模型元数据,也可以分发本地目录文件并通过 model_catalog_json 指定其路径。有关这两项设置,请参阅配置参考。

请向云服务提供商或网关提供商获取与您的 Codex 版本兼容的目录端点或文件,确认其中包含每个获批的别名及对应模型的元数据。有关目录的实现方式,请参阅为网关和云服务实现模型目录。

提供远程目录

使用提供商提供的 HTTPS 目录端点。在分发配置时,将完整的端点 URL 写入 config.toml 中所选提供商对应的表:

model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"

确保 Codex 进程可以读取 CODEX_GATEWAY_API_KEY。另行设置 base_url,以便通过网关路由推理请求。如果省略该设置,Codex 会使用当前身份验证模式对应的默认 OpenAI 端点。

如果网关 OAuth 是唯一的凭据来源,请显式指定目录 URL,并确保其协议、主机和端口均与 base_url 一致。Codex 会复用现有的网关会话,无需用户重新登录,也无需通过 API 密钥发现目录。

获批的模型发生变化时,请与提供商协调更新目录。更改客户端配置后,请重启客户端。

移除所有已生效的 model_catalog_json 设置,包括通过 requirements.toml 强制设置的值。该设置的优先级高于远程 URL,会导致 Codex 不再获取远程目录。

分发本地目录

使用 model_catalog_json,让 Codex 在启动时加载提供商提供的文件。自定义本地目录会替换 Codex 自带的目录。

将网关别名、目录中的 slug 和 Codex 的 model 均设为 company-coding-model。在要分发的 Codex 配置中,将以下设置添加到第一个 TOML 表之前,并填写文件的实际绝对路径:

model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"

Codex 在启动时加载目录,因此更改目录后,请重启 CLI 或桌面应用。

验证模型路由

针对每个模型发送实际的 Responses 请求,并结合网关记录验证路由。/v1/models 响应有助于查找模型名称,但无法证明模型支持所需的请求和工具行为。

模型路由和工具授权是推广过程中的两个独立环节。请单独配置 MCP 连接、插件分发及其相关策略。

选择身份验证方式

网关原生 OAuth

  1. 注册支持 PKCE 授权码流程的公共 OAuth 客户端,并授权指定用户或用户组登录。
  2. 配置网关,使其验证通过指定 Cookie 或自定义请求头传入的已签发访问令牌。根据每个用户的身份,为其设置可用的获批模型,并应用相应的速率限制和预算。
  3. 按照网关原生 OAuth 的说明,收集授权端点和令牌端点的 URL、公共客户端 ID、授权范围、可选的资源参数、令牌传递设置,以及固定的重定向端口(如有)。在身份提供商处注册与之匹配的环回重定向 URI。如果身份提供商支持设备授权,还请向远程 CLI 用户分发 device_authorization_url。
  4. 在计划部署的 CLI 或桌面应用中,使用测试用户验证浏览器登录、令牌刷新和访问权限撤销。对于远程 CLI 用户,请测试设备代码登录,或确认浏览器可以访问环回回调地址。

每个用户分别登录。仅分发 OAuth 配置,不要分发客户端密钥、网关 API 密钥或凭据助手可执行文件。上游提供商的凭据应保留在网关上。

API 密钥或凭据助手

  1. 为每位开发者签发一份限定权限范围的网关凭据,以便按人统计用量,并可单独撤销访问权限。
  2. 为每份凭据设置获批的模型、速率限制、预算、到期时间和续期周期。
  3. 通过密钥管理器或已安装的凭据助手分发凭据。不要在开发者机器上存放上游提供商凭据或网关管理员凭据。
  4. 如果凭据助手提供用于向提供商验证身份的主要凭据,请遵循基于命令的身份验证规范。如果用户使用 ChatGPT 登录,同时由凭据助手提供网关凭据,请配置网关凭据导出命令。分发前,请测试令牌获取和刷新。
  5. 告知开发者如何为凭据续期,以及需要帮助时应联系谁。

通过网关测试 Codex

在分发任何内容之前,请按照配置提供商的说明,为一个隔离的测试用户配置您计划分发的提供商配置块和身份验证方式。

如果网关提供模型目录,请确认其返回与 Codex 兼容的 models 数组。如果使用用户的凭据访问 OpenAI 推理服务,请确认网关将所需的 ChatGPT 请求头转发到 Codex 后端。

记录试点使用的客户端版本、操作系统、提供商 ID、模型别名和身份验证方式。在计划支持的每种 CLI 或桌面客户端上执行以下检查。如果既支持仅通过网关验证身份,也支持在网关身份验证的同时登录 ChatGPT,请分别测试这两种组合。

检查项 操作 通过标准
实际生效的配置 检查各个配置层,确认使用了预期的提供商、模型和强制设置。 试点用户使用的是分发的设置,用户或配置档案中的默认值未将请求切换到其他路由。
连接 按照验证连接的说明操作。 预期的提供商和模型别名已生效,Codex 成功响应测试提示词,网关日志能识别测试用户。
流式传输 请 Codex 分几段简短作答。 文本逐步到达,当前使用的传输方式发出 response.completed 事件。单独测试 HTTP,验证网关转发 SSE 事件时不做缓冲。
本地工具调用流程 在权限设为只读的临时文件夹中,请 Codex 列出顶层文件并概述其内容。 Codex 调用本地工具,返回调用结果并给出最终答复,期间未修改任何文件。
追问 在同一对话线程中继续提问。 回答使用了上一轮对话的内容,网关接受重放的输入。如果启用了 WebSocket 或增量传输,网关还会保留 previous_response_id。
错误处理和用量归属 故意使用无效的测试别名或已过期的测试凭据,重复测试。 客户端收到有助于排查路由或身份验证问题的错误信息,有效请求仍归属于测试用户。

如果启用了自动审批,请在临时测试文件夹中触发一项按预定审批策略需要审查的工具操作。确认网关能够处理审查请求,且客户端会执行审批决定。无需审批的只读工具调用无法验证这一流程。扩大试点范围之前,请记录所有尚不支持的工作流程。

如果此次推广会更改现有用户的提供商,请在每种受支持的客户端上分别测试新对话和更改前创建的对话。记录用户能否查看或继续已有对话,以及能否从中创建分支。对于受阻的工作流程,请向用户提供恢复步骤。不要假定更改默认提供商会迁移对话历史记录。

这些检查通过后,请准备交付给开发者的配置说明。

分发配置

为确保每台机器都通过同一路径连接,请分发网关基础 URL、提供商 ID、获批的模型别名和身份验证设置。

需要分发的内容

对于网关原生 OAuth,请分发提供商表和 [model_providers.<id>.gateway_oauth] 表。请按连接指南中的示例填写这两个表,使用上面收集的注册信息。如果 OAuth 是网关唯一的凭据来源,请保留 requires_openai_auth = false,并省略 env_key、experimental_bearer_token 和基于命令的 auth 表。

如果凭据助手提供用于向提供商验证身份的主要凭据,请通过您选择的配置层分发以下 config.toml 配置块。请使用您的 Codex 版本可识别的模型,或按上述说明提供匹配的目录。将令牌获取程序安装到配置中指定的命令路径:

将 model 和 model_provider 放在第一个 TOML 表之前。如果设置了 model_catalog_json,也应将其放在此处。TOML 会将 [model_providers...] 之后的键视为该表的一部分,而非 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"

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

如果使用短期有效的静态测试密钥,请移除 auth 配置块,将 env_key = "CODEX_GATEWAY_API_KEY" 写入 [model_providers.enterprise-gateway] 表,并在 TOML 之外设置该环境变量。不要同时使用 env_key 和基于命令的身份验证。

分发默认设置和强制设置

如果用户不使用 ChatGPT 登录 Codex,您可以从自己的服务器分发团队设置。无论模型请求采用哪种路由方式,Codex 都会独立获取这些设置。

请参阅配置优先级,选择在哪一层分发默认设置。有关强制设置和 macOS MDM 配置载荷,请参阅托管配置。

在 macOS 或 Linux 上,请使用 /etc/codex/config.toml 设置整台主机的默认值。在 Windows 上,请将 config.toml 放在 %ProgramData%\OpenAI\Codex\ 中。用户配置和配置档案均可覆盖这些默认值。上述参考文档列出了支持的强制设置及其文件位置。

配置中引用的凭据助手可执行文件和本地目录文件需要单独分发。

要强制使用某个远程目录 URL,请在 requirements.toml 的 [model_providers.<id>] 表中填写完整的提供商定义。强制设置的提供商定义会替换常规配置中对应的提供商表,因此务必包含 base_url、身份验证设置和其他必填字段。如果还需要强制选择该提供商,请使用 model_provider 强制设置。

model_catalog_json 指向本地 JSON 文件。通过 requirements.toml 强制设置此项只能固定路径,文件本身需要另行分发。请在 Codex 启动前,将目录文件放到该绝对路径下。

在 TOML 中,请填写已展开的 Windows 绝对路径。Codex 不会展开 %ProgramData%,无论它出现在 model_catalog_json 中,还是出现在提供商身份验证的 command 值中。例如,仅当文件实际部署在以下位置时,才使用这些路径:

model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'

[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]

在 WSL 内运行的 CLI 读取 Linux 路径和 Linux 环境中的 CODEX_HOME,不会自动继承原生 Windows 配置。

分发路由请求头

如果网关按配置或工具路由请求,请在托管的 requirements.toml 中为相应提供商添加网关所需的请求头。以下示例提供路由配置 ID,并将客户端标识为 Codex:

[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'

如果请求头的值由客户端环境提供,请使用 env_http_headers。发送测试请求,并在网关日志中确认实际选用的路由。有关请求头选项,请参阅自定义模型提供商。

向开发者提供配置值

向开发者提供一套与试点中验证过的流程一致的配置步骤。即使集中分发配置,也请提供以下信息:

交付项 需要提供的信息
获批的客户端 试点使用的客户端、版本、操作系统,以及安装或更新步骤。
配置分发方式 说明设置是否已由组织管理,还是需要开发者在本地配置,并列出单独安装的凭据助手或目录文件。
预期的连接信息 提供商 ID、模型别名和包含 API 路径的网关 URL。说明用户可以更改哪些值。
登录步骤 说明用户需要登录 ChatGPT 工作空间、向网关验证身份,还是两项都要完成。注明所需的工作空间和网关身份验证方式。
凭据和目录 根据身份验证方式,提供 OAuth 注册信息、存放凭据的环境变量或已安装的凭据助手配置。如使用目录,还需提供目录 URL 或已展开的本地路径。通过组织批准的保密信息分发机制交付密钥等敏感值。
验证和支持 提供连接测试、预期结果、网关负责人,以及报告故障时应附上的信息。

对于托管机器,请让开发者参阅检查现有配置。如果需要手动配置,请让他们参阅配置提供商。

如果此次推广会更改提供商,请附上经过测试的已有对话处理步骤。保留之前可用的配置,供推广负责人在试点发现问题时使用。

手动配置无法强制执行设置。项目本地的 .codex/config.toml 无法覆盖控制提供商路由或身份验证路由的敏感配置键。

在开发者机器上验证

要确认开发者机器已收到分发的设置,请执行以下步骤:

  1. 确认已安装获批的客户端以及所需的凭据助手或目录文件。重启 Codex,并按交付说明完成登录。
  2. 确认当前使用的是预期的提供商和模型。在 CLI 中,可使用 /status 查看。如果实际生效的设置与交付说明不符,请使用 /debug-config 检查各个配置层。
  3. 运行连接到网关中的简短测试。
  4. 追问一次,确认对话能够延续,然后在网关日志中查找该开发者的请求。

在所有受支持的客户端和身份验证组合上完成试点并通过验证后,再向更多用户开放访问。将经过测试的配置和测试结果与推广说明一同保存,以便在客户端、网关或策略更新后重新执行检查。

排查推广过程中的故障

根据故障现象,确定需要检查的是配置、凭据还是网关:

问题 处理方法
重启后找不到预期的提供商。 检查最终生效的配置层。用户配置或配置档案可能覆盖系统默认值。
所有用户都无法通过身份验证。 检查网关身份验证和上游提供商凭据,确定是哪个服务拒绝了请求。
只有一位用户无法通过身份验证。 检查该用户在身份提供商处的访问权限、网关凭据或令牌获取程序。
流式传输停滞。 检查网关是否缓冲了事件,以及是否转发了结束事件 response.completed。
找不到某个模型,或模型使用了通用能力设置。 对于自定义别名,请确认网关别名、Codex 的 model 和目录中的 slug 完全一致。检查目录路径是否正确,并确认目录与已安装的 Codex 版本兼容,然后重启 Codex。
Windows 路径无法使用。 使用已展开的绝对路径。在 TOML 中,使用单引号字符串填写 Windows 路径,路径分隔符使用单个反斜杠。

复用现有网关部署

如果您的组织已经通过网关使用 Claude Code,您或许可以复用网关产品、网络路径、日志记录机制和 Bedrock 访问权限。保留当前可用的配置,同时为 Codex 添加 Responses 路由、凭据、模型别名和 config.toml。Claude 客户端设置和 /v1/messages 接口规范无法用于配置 Codex。

现有 Claude 部署 迁移到 Codex 时的做法
网关产品、DNS、TLS、专用网络、日志记录、脱敏和监控 保留这些服务。为 Codex 添加符合网关兼容性要求的路由。
Bedrock 账户、提供商凭据、IAM 权限边界、推理配置档案和凭据轮换机制 仅在这些配置允许访问新 Codex 别名对应的上游模型时才予以保留。提供商凭据仍保留在网关上。
Claude 的 /v1/messages 路由、Bedrock InvokeModel 请求格式、Anthropic 请求头,以及 Claude 特有的重试或错误处理机制 这些机制不能作为网关兼容 Codex 的依据。Codex 要求网关支持 POST /v1/responses、Responses 流式传输、对话延续和工具调用,并返回有助于排查问题的错误信息。
ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 或 apiKeyHelper Codex 不支持 apiKeyHelper。请从以下三种方式中选择一种:使用网关原生 OAuth,通过 env_key 指定存放限定权限范围密钥的环境变量,或配置 Codex 基于命令的令牌获取程序。
Claude 模型名称、ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL、modelOverrides 和 Bedrock 配置档案映射 请网关团队选择模型名称并配置所需的自定义别名。使用团队提供的模型名称,以及他们提供的模型目录 JSON(如有)。
Claude 的 settings.json、managed-settings.json、JSON env 配置块、plist 或注册表配置载荷 继续使用原有的 MDM 或配置管理渠道,改为分发 Codex 的 config.toml 和 requirements.toml 支持的配置值。

为安全迁移,请依次完成以下步骤:

  1. 盘点 Claude 当前的连接配置,包括网关 URL、凭据来源、必需的请求头、模型别名、Bedrock 配置档案映射和托管分发渠道。
  2. 在保留现有路由的同时,为 Codex 添加 Responses 路由和模型别名。
  3. 选择网关原生 OAuth、API 密钥或凭据助手,并为一位测试用户授权。如果使用静态凭据,请通过 env_key 让 Codex 读取凭据。如果使用凭据助手,请按照 Codex 基于命令的令牌获取规范实现并测试该程序。
  4. 使用第 3 步选择的身份验证方式,为该开发者配置提供商。如果采用托管分发,请按照在组织内推广网关中说明的 Codex 配置路径和优先级,调整要分发的配置载荷。
  5. 在开发者实际使用的 CLI 或桌面应用中运行简短的连接检查,然后按照通过网关测试 Codex的说明,全面检查流式传输、对话延续、工具调用、错误处理、日志记录和别名路由。
  6. 试点验证通过后,向其余开发者分发配置。

模型目录参考

从本地 models.json 文件开始

首先,在运行 Codex 的机器上配置并选择网关提供商。

在运行 Codex 的机器上,将以下目录保存为 models.json。将 gateway-model 替换为网关接受的模型 ID,确保完全一致。显示名称是用户在模型选择器中看到的标签。

{
  "models": [
    {
      "slug": "gateway-model",
      "display_name": "Gateway model",
      "base_instructions": "Help the user with their coding tasks.",
      "supported_reasoning_levels": [],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 0,
      "support_verbosity": false,
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "experimental_supported_tools": []
    }
  ]
}

要查看包含更多条目的示例,请参阅 Codex 的模型目录。

将 model_catalog_json 在 config.toml 中的值设为该文件的绝对路径。重启 Codex,选择 Gateway model,然后发送请求。确认网关收到的模型 ID 与您在 slug 中设置的值一致。

如果要为 Codex 自带的模型设置别名,请从您使用的 Codex 版本中复制该模型的完整目录条目,并修改其 slug 和 display_name。如果别名没有迁移目标,请将 upgrade 设为 null。这样可以保留该模型的上下文窗口、推理选项和工具设置。

向客户端提供目录

本节面向实现 Codex Models 格式的开发者。该格式定义模型目录,模型选择器根据目录展示模型。如果您正在开发网关或云服务等推理服务,请遵循此规范,以便 Codex 桌面应用和 CLI 能够发现您的模型,并使用相应的指令和能力设置。

如果您是企业管理员,需要管理模型目录,请参阅 model_catalog_url 配置指南。

要支持此格式,请实现一个需要身份验证的目录端点。根据发出请求的 Codex 版本,从上游提供商获取当前默认设置,应用您的覆盖设置,然后返回生成的目录。

实现目录端点

默认目录端点是 /models,相对于提供商的 base_url。例如,设置 base_url = "https://gateway.example.com/v1" 后,Codex 会发送以下请求:

GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>

默认的目录发现机制支持基于命令的身份验证,以及 ChatGPT 登录等 Codex 后端身份验证方式。如果自定义提供商使用 API 密钥验证身份,且未使用基于命令的身份验证,请显式设置 model_providers.<id>.model_catalog_url 以启用远程目录发现。仅提供 API 密钥不会触发默认路径上的目录发现。

使用 model_catalog_url 指定完整的目录 URL,例如 https://gateway.example.com/codex/models。该 URL 也可以指向默认的 /v1/models 端点。Codex 直接使用此 URL,不会在末尾追加 /models。要通过 API 密钥发现目录,请保持 features.api_key_model_discovery 启用(默认已启用)。仅设置自定义请求头无法启用目录发现。

Codex 会发送所选提供商的身份验证信息和已配置的请求头,并在 URL 中追加 client_version 和提供商设置的 query_params(如有)。请将目录托管在有权接收这些凭据的服务上。

验证调用方的身份,获取对应的上游默认设置,应用您的覆盖设置,然后直接返回完整的 ModelsResponse JSON。为每个条目指定唯一且非空的 slug。如果显式设置了 model_catalog_url,Codex 会拒绝重定向。处理推理请求时,仍须检查调用方是否有权访问模型。

对于使用该端点的客户端,请移除所有已生效的 model_catalog_json 设置。本地文件的优先级更高,会导致 Codex 不再获取远程目录。

匹配客户端的模式

读取目录请求中的 client_version 查询参数。Codex 会移除预发布版本后缀,以 major.minor.patch 格式发送 CLI 版本号。对于桌面客户端,该值是其内置 CLI 的版本号。

在 Codex 公共代码仓库中选择匹配的 rust-v<version> 标签。如果使用自定义构建,请选择构建所用的确切源码提交。以下链接使用 rust-v0.162.1,请切换到与您的客户端匹配的版本:

随版本提供的文件是发布时的快照。生成自己的目录之前,请先获取当前的默认设置。

获取上游当前的默认设置

提供 OpenAI 模型的云服务提供商从 OpenAI 获取默认设置。网关从云服务提供商或上游提供商读取目录,以保留已部署模型的设置,以及模型在各账户和区域的可用情况。每一步都应传递发出请求的 Codex 版本,并分别向各端点验证身份。

要直接从 OpenAI 获取默认设置,请使用相同的 client_version 调用 Codex 模型端点。例如,使用 OpenAI API 密钥时,请运行:

curl --fail --silent --show-error \
  'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果与 ChatGPT 集成,请使用调用方的 ChatGPT 访问令牌,并在适用时发送 ChatGPT-Account-ID 请求头。请使用有权访问上游端点的凭据。网关自身的 API 密钥无法用于向 OpenAI 验证身份。

解析完整的响应,包括顶层 models 数组。该端点返回 Codex 元数据,包括指令、默认推理设置、工具设置、上下文限制和服务层级。公共的 /v1/models 端点不提供此目录。

即使 Codex 版本未变,也应刷新这些默认设置。目录内容可能取决于调用方的访问权限,因此请仅以预期的上游身份发出请求,并遵循响应中的缓存控制指令。单独保存您的覆盖设置,以便在获取最新默认设置后重新应用。

应用提供商的覆盖设置

修改字段值时,请保留对应版本的响应结构:

  • 筛选模型,仅保留调用方有权使用的模型。将每个 slug 映射到受支持的推理路由,并调整 display_name、description 或 priority。如果别名没有模型迁移目标,请将 upgrade 设为 null。
  • 根据模型和路由支持的范围设置推理选项、上下文限制、输入模态和服务层级。默认值也必须在支持的选项范围内。如果路由不提供服务层级,请清空 service_tiers 和 additional_speed_tiers,并将 default_service_tier 设为 null。
  • 除非已测试替代方案,否则请保留上游指令和工具设置。元数据不能为模型增添能力,也不能授予推理访问权限。

如果使用网关模型别名,请参阅提供模型元数据。使用每个受支持的 Codex 版本测试生成的目录。

使用公开的 Rust 类型

请使用与客户端模式来自同一公共 Git 标签或提交的 Rust crate:

  • 使用 codex-protocol 中的 codex_protocol::openai_models::{ModelsResponse, ModelInfo}。使用 serde_json::from_slice::<ModelsResponse>() 解析响应,修改 catalog.models,然后使用 serde_json::to_vec() 序列化整个封装对象。该对象负责处理模型指令的兼容性字段。
  • 使用 codex-models-manager::bundled_models_response() 将该版本自带的静态目录加载为 ModelsResponse。此函数不会获取上游当前的默认设置。

相关文档