為閘道器和雲服務實現模型目錄

本頁面向實現 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。它不會取得當前上游預設設定。