为网关和云服务实现模型目录

本页面向实现 Codex Models 格式的开发者，该格式定义了模型目录，并为模型选择器提供支持。如果你正在构建推理提供商服务，例如网关或云服务，可使用此规范，让 Codex 桌面应用和 CLI 发现你的模型，并使用其指令和能力设置。

如果你是企业管理员，希望控制模型目录，请参阅model_catalog_url 配置指南。

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

实现目录端点

默认目录端点是提供商 base_url 下的 /models。例如，使用 base_url = "https://gateway.example.com/v1" 时，Codex 会请求：

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

默认发现机制支持基于命令的身份验证和 Codex 后端身份验证，例如 ChatGPT。对于使用 API key 身份验证但不使用基于命令的身份验证的自定义提供商，请显式设置 model_providers.<id>.model_catalog_url，以启用远程发现。仅有 API key 不会触发默认路径上的发现。

使用 model_catalog_url 指定完整的目录 URL，例如https://gateway.example.com/codex/models。它也可以指向默认的/v1/models 端点。Codex 会直接使用此 URL，不会追加 /models。对于通过 API key 进行的发现，请保持 features.api_key_model_discovery 启用；此设置默认启用。仅配置自定义请求头不会启用发现。

Codex 会发送所选提供商的身份验证信息和配置的请求头，并追加 client_version 以及提供商的所有 query_params。请将目录托管在获准接收这些凭据的服务上。

验证调用方身份，获取相应的上游默认配置，应用你的覆盖配置，然后直接返回完整的 ModelsResponse JSON。为每个条目提供唯一且非空的 slug。对于显式指定的 model_catalog_url，Codex 会拒绝重定向和大于 1 MiB 的响应。仍需在推理请求中强制执行模型访问控制。

对于使用此端点的客户端，请移除任何生效的 model_catalog_json 设置：本地文件的优先级更高，会阻止远程获取。

匹配客户端的模式

读取目录请求中的 client_version 查询参数。Codex 会将其 CLI 版本作为 major.minor.patch 发送，并移除所有预发布后缀。对于桌面客户端，此版本是其内置的 CLI 版本。

使用公共 Codex 仓库中匹配的 rust-v<version> 标签，或自定义构建所用的确切源代码提交。以下链接使用 rust-v0.162.1；请选取与你的客户端匹配的修订版本：

• 阅读 ModelsResponse 和 ModelInfo 响应类型，了解模式。
• 查看内置的 models.json，获取完整示例。这是目录数据，不是 JSON Schema 文档。

内置文件是发布时的快照。在生成目录之前，请获取当前默认配置。

获取当前上游默认配置

提供 OpenAI 模型的云提供商从 OpenAI 获取默认配置。网关读取其云提供商或上游提供商的目录，以保留已部署模型的设置以及账户和区域可用性。每一步都应传递发起请求的 Codex 版本，并分别对每个端点进行身份验证。

要直接从 OpenAI 获取默认配置，请使用相同的client_version 调用 Codex 模型端点。例如，使用 OpenAI API key：

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 key 无法用于向 OpenAI 进行身份验证。

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

即使 Codex 版本未更改，也应刷新这些默认配置。将请求限定在预期的上游身份范围内，并遵循响应中的缓存控制指令：目录可能取决于调用方的访问权限。将覆盖配置单独保存，以便重新应用到最新的默认配置上。

应用提供商覆盖配置

修改字段值，同时保留该版本的响应结构：

• 筛选出调用方可以使用的模型。将每个 slug 映射到受支持的 推理路由，并调整 display_name、description 或 priority。 对于不涉及模型迁移的别名，将 upgrade 设置为 null。
• 将推理选项、上下文限制、输入模态和服务层级设置为 你的模型和路由支持的值。默认值应处于受支持的 选项范围内。对于没有服务层级的路由，请清空 service_tiers 和 additional_speed_tiers，并将 default_service_tier 设置为 null。
• 保留上游指令和工具设置，除非你已测试过 替代配置。元数据不会增加模型能力，也不会授予推理访问权限。

对于通过 LiteLLM 使用 Bedrock 的情况，请应用必需的目录修改。使用每个受支持的 Codex 版本测试生成的目录。

使用公共 Rust 类型

使用与客户端模式相同的公共 Git 标签或提交中的 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。它不会获取当前上游默认配置。