部署閘道器
為組織分發並驗證 Codex 閘道器連線
作為閘道器管理員,請設定模型路由並授權一名試點使用者。在向開發者分發設定之前,請在支援的每個用戶端上測試連線。使用原生閘道器 OAuth、API key 或憑證輔助程式進行閘道器身分驗證。要將閘道器身分驗證與 ChatGPT 工作區登入結合使用,請參閱 透過閘道器登入 ChatGPT。
前提條件
向開發者部署 Codex 之前,請確認已具備:
- 一個透過 HTTPS 提供服務的閘道器,其基礎 URL 與你將分發的 URL 完全一致。
- 由閘道器持有的上游供應商憑證。
- 已核准的面向 Codex 的模型別名,且已對映到預期的上游模型。
- 經過測試的身分驗證方式:原生閘道器 OAuth、限定作用域的閘道器 API key,或憑證輔助程式。
- 對於 OAuth,已註冊的公開用戶端、已核准的測試使用者,以及閘道器對 OAuth 存取權杖驗證的支援。
- 對於 API key 或輔助程式,金鑰分發機制或經過測試的輔助程式。
- 用於分發設定、任何必需的輔助程式和目錄檔案的方式。
閘道器要求
連線 Codex 之前,請驗證閘道器產品是否保留以下必需行為:
- 在
POST /v1/responses接受 Codex Responses API 請求。 - 無緩衝地流式傳輸 SSE 事件,並以
response.completed結束。 - 支援透過重放輸入延續後續對話。
- 僅在啟用 WebSocket 或增量傳輸時保留
previous_response_id。 - 保留函式呼叫及對應的
function_call_output項。 - 將每個面向 Codex 的模型別名路由到預期的上游模型。
- 分別對使用者進行身分驗證,並傳回有助於排查問題且不掩蓋原因的錯誤。
健康檢查端點、/v1/models、Chat Completions 回應或一次純文字回覆,都不足以證明閘道器符合要求。有關詳細約定,請參閱閘道器相容性要求。
推廣閘道器
要從已部署的閘道器過渡到經過驗證的開發者使用環境,請按順序完成以下五項檢查:
選擇模型名稱和路由
將 Codex 的 model 設定為閘道器的模型名稱。設定閘道器,將該名稱路由到已獲核准的上游模型。
| 閘道器模型名稱 | Codex 設定 |
|---|---|
| Codex 版本中包含的內建模型名稱 | 將 config.toml 中的 model 設定為這個確切名稱。 |
自訂別名,例如 company-coding-model |
提供包含該別名及對應模型後設資料的遠端或本機目錄。 |
為自訂名稱使用模型目錄
對於本機目錄,請從 models.json 範例開始。
如果閘道器使用的模型名稱無法被 Codex 識別,請提供模型目錄。目錄提供 Codex 針對該名稱使用的指令、推理選項、上下文限制和工具能力。如果沒有匹配的條目,請求可能會到達預期的上游模型,但 Codex 會使用通用設定。
使用 model_providers.<id>.model_catalog_url 託管遠端目錄,以集中更新模型後設資料,或使用 model_catalog_json 分發本機檔案。當原生閘道器 OAuth 是唯一的憑證時,請使用本機目錄;僅靠 OAuth 無法啟用遠端目錄發現。有關這兩項設定,請參閱設定參考。
從雲端服務供應商或閘道器供應商處取得與當前 Codex 版本相容的目錄端點或檔案。確保其中包含每個獲准使用的別名及其模型後設資料。有關目錄實現,請參閱 為閘道器和雲端服務實現模型目錄。
提供遠端目錄
使用供應商提供的 HTTPS 目錄端點。在所選供應商的 config.toml 表中分發完整的端點 URL:
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 端點。
目錄發現需要透過 API key、命令或 Codex 後端進行身分驗證。僅使用原生閘道器 OAuth 或自訂請求標頭不會觸發目錄發現。
獲准使用的模型發生變化時,請與供應商協調更新目錄。更改設定後,重啟用戶端。
移除所有生效的 model_catalog_json 設定,包括透過 requirements.toml
強制設定的值。它的優先順序高於遠端 URL,會阻止遠端取得。
分發本機目錄
使用 model_catalog_json 在啟動時載入供應商提供的檔案。本機自訂目錄會替換內建目錄。
將閘道器別名、目錄中的 slug 和 Codex 的 model 設定為 company-coding-model。在分發的 Codex 設定中,將以下設定新增到第一個 TOML 表之前,並使用檔案的實際絕對路徑:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"更改目錄後,請重啟 CLI 或桌面應用,因為 Codex 會在啟動時載入目錄。
驗證模型路由
對每個模型,使用真實的 Responses 請求和閘道器記錄驗證路由。/v1/models 回應可以幫助發現名稱,但不能證明模型支援所需的請求和工具行為。
模型路由和工具授權是推廣過程中的兩個獨立部分。請分別設定 MCP 連線、外掛分發及其策略。
選擇身分驗證方式
原生閘道器 OAuth
- 註冊支援帶 PKCE 的授權碼流程的公開 OAuth 用戶端,並核准可以登入的使用者或群組。
- 設定閘道器,使其驗證透過所選 cookie 或自訂請求標頭傳遞的已簽發存取權杖。將核准的模型、速率限制和預算應用於每個使用者的身分。
- 按照原生閘道器 OAuth中的說明,收集授權和權杖 URL、公開用戶端 ID、作用域、可選資源、權杖傳遞設定以及任何固定重新導向埠。向身分供應商註冊匹配的迴環重新導向 URI。
- 在計畫部署的 CLI 或桌面應用上,使用測試使用者測試瀏覽器登入、權杖重新整理和存取權限撤銷。確認瀏覽器能夠存取回呼地址,包括遠端 CLI 使用者的使用場景。
使用者各自登入。你分發的是 OAuth 設定,而非用戶端金鑰、閘道器 API key 或輔助程式執行檔。將上游供應商憑證保留在閘道器上。
API key 或憑證輔助程式
- 為每位開發者簽發一個限定權限範圍的閘道器憑證,以便將用量歸屬於具體開發者並單獨撤銷存取權限。
- 為每個憑證設定獲准使用的模型、速率限制、預算、有效期和續期週期。
- 透過敏感資訊管理器或已安裝的憑證輔助程式分發憑證。不要將上游供應商和閘道器管理員憑證存放在開發者機器上。
- 如果使用輔助程式,請遵循 基於命令的身分驗證約定,並在分發前測試權杖取得和重新整理。
- 告知開發者如何續期憑證,以及遇到問題時應聯絡誰。
透過閘道器測試 Codex
在分發任何內容之前,請按照設定供應商中的說明,使用計畫分發的供應商設定塊和身分驗證方式,為一個獨立的測試使用者進行設定。
如果閘道器提供模型目錄,請確認它傳回與 Codex 相容的 models 陣列。對於使用使用者憑證的 OpenAI 推理,請確認閘道器將所需的 ChatGPT 標頭轉發到 Codex 後端。
記錄試點所用的用戶端版本、作業系統、供應商 ID、模型別名和身分驗證方式。在計畫支援的每個 CLI 或桌面端介面中執行以下檢查。如果同時提供僅透過閘道器進行身分驗證的方式,以及閘道器身分驗證與 ChatGPT 登入相結合的方式,請分別測試每種組合。
| 檢查項 | 操作 | 驗證依據 |
|---|---|---|
| 生效設定 | 檢查各設定層,確認供應商、模型和要求符合預期。 | 試點使用已分發的設定。使用者或設定檔的預設設定未選擇其他路由。 |
| 連線 | 按照驗證連線中的步驟操作。 | 預期的供應商和別名已啟用,測試提示詞執行成功,且閘道器日誌中可識別測試使用者。 |
| 流式傳輸 | 要求生成包含多個段落的簡短回答。 | 文字逐步到達,且當前傳輸方式發出 response.completed。單獨測試 HTTP,驗證閘道器轉發 SSE 事件時不會緩衝。 |
| 本機工具迴圈 | 在具有唯讀權限的臨時資料夾中,要求 Codex 列出頂層檔案並概述其內容。 | Codex 發起本機工具呼叫、傳回結果,並在不修改檔案的情況下生成最終回答。 |
| 追問 | 在同一對話串中追問。 | 回答使用上一輪的內容;閘道器接受重放的輸入。如果啟用了 WebSocket 或增量傳輸,還會保留 previous_response_id。 |
| 錯誤與歸屬 | 使用故意設為無效的測試別名或已過期的測試憑證重複測試。 | 用戶端收到有助於排查問題的路由或身分驗證錯誤,且有效請求仍歸屬於測試使用者。 |
如果啟用了自動核准,請使用臨時測試資料夾,觸發一項根據預期策略需要審查的工具操作。確認閘道器能夠處理審查請求,且用戶端會應用核准決定。不需要核准的唯讀工具呼叫無法測試此流程。在擴大試點範圍之前,記錄所有不受支援的工作流程。
如果此次部署會更改現有使用者的供應商,請在每個受支援的用戶端上測試新對話和更改前建立的對話。記錄使用者能否檢視、繼續現有對話或從中建立分支,並為任何受阻的工作流程提供恢復步驟。不要假定更改預設供應商會遷移對話歷史記錄。
這些檢查成功後,準備向開發者交接。
分發設定
要讓所有電腦使用相同的連線路徑,請分發閘道器基礎 URL、供應商 ID、已核准的模型別名和身分驗證設定。
分發內容
對於原生閘道器 OAuth,請分發供應商表和
[model_providers.<id>.gateway_oauth] 表,具體參見連線指南,並填入上面收集的註冊資訊。保留 requires_openai_auth = false,並省略
env_key、experimental_bearer_token 和基於命令的 auth 表,前提是
OAuth 是唯一的閘道器憑證。
對於憑證輔助程式,請透過所選的設定層分發以下 config.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"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000對於短期有效的靜態測試金鑰,移除身分驗證設定塊,將 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 不會展開
model_catalog_json 或供應商身分驗證 command 值中的 %ProgramData%。例如,只有在部署時將檔案放到以下位置後,才能使用這些路徑:
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、模型別名和閘道器 URL(包括其 API 路徑)。說明使用者可以更改哪些值。 |
| 登入步驟 | 說明使用者是否必須登入 ChatGPT 工作區、向閘道器進行身分驗證,或同時完成兩者。明確所需的工作區和閘道器身分驗證方式。 |
| 憑證和目錄 | OAuth 註冊參數值、憑證環境變數或已安裝的輔助程式設定,以及任何目錄 URL 或解析後的本機路徑。透過已核准的金鑰分發機制交付金鑰。 |
| 驗證與支援 | 連線測試、預期結果、閘道器負責人,以及報告故障時需要提供的資訊。 |
對於受管裝置,請引導開發者參閱檢查現有設定。對於手動設定,請引導他們參閱設定供應商。
如果此次部署會更改供應商,請附上經過測試的現有對話處理說明。為部署負責人保留先前可用的設定,以便在試點發現問題時使用。
手動設定不是強制設定管道。專案本機的 .codex/config.toml 無法覆蓋敏感的供應商或身分驗證路由鍵。
在開發者機器上驗證
要確認分發的設定已到達開發者機器:
- 確認已安裝獲准的用戶端以及所有必需的輔助程式或目錄檔案。重啟 Codex,並完成交接說明中的登入步驟。
- 確認供應商和模型符合預期。在 CLI 中,使用
/status。當生效設定與交接說明不一致時,使用/debug-config檢查各設定層。 - 執行連線到閘道器中的簡短測試。
- 追問一次以確認對話可以繼續,然後檢查閘道器日誌中該開發者的請求。
在所支援的用戶端和身分驗證組合上成功完成試點測試後,再擴大存取範圍。將經過測試的設定和結果與部署說明一並儲存,以便在用戶端、閘道器或策略更新後重複檢查。
排查推廣過程中的故障
根據問題定位需要處理的設定層、憑證層或閘道器層:
| 問題 | 解決方法 |
|---|---|
| 重啟後未顯示預期的供應商。 | 檢查最終生效的設定層。使用者設定或設定檔可以覆蓋系統預設值。 |
| 所有使用者的身分驗證均失敗。 | 檢查閘道器身分驗證和上游供應商憑證;確定是哪個服務拒絕了請求。 |
| 某個使用者的身分驗證失敗。 | 檢查該使用者的身分供應商存取權限、閘道器憑證或權杖解析程式。 |
| 流式傳輸停滯。 | 檢查閘道器緩衝以及表示結束的 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 需要 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 值。 |
要安全遷移,請按順序完成以下步驟:
- 盤點當前 Claude 的接入路徑:閘道器 URL、憑證來源、必需的請求標頭、模型別名、Bedrock 設定檔對映和受管分發管道。
- 新增一條並行的、面向 Codex 的 Responses 路由,以及 Codex 模型別名。
- 選擇閘道器原生 OAuth、API key 或憑證輔助程式,並授權一名測試使用者。對於靜態憑證,透過
env_key提供;對於輔助程式,實現並測試 Codex 基於命令的解析器契約。 - 使用第 3 步所選的身分驗證方式,為該開發者設定供應商。對於受管部署,將酬載轉換為部署閘道器中所述的 Codex 路徑和優先順序。
- 在開發者實際使用的 CLI 或桌面端介面中執行簡短的連線檢查,然後執行透過閘道器測試 Codex中的完整檢查,涵蓋流式傳輸、對話繼續、工具呼叫、錯誤、日誌和別名路由。
- 試點成功後,向其餘開發者分發設定。
模型目錄參考
從本機 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 的模型目錄。
將 config.toml 中的 model_catalog_json 設定為該檔案的絕對路徑。重啟 Codex,選擇 Gateway model,然後傳送請求。檢查閘道器是否收到了你在 slug 中設定的模型 ID。
對於內建模型的別名,複製與你的 Codex
版本對應的完整目錄條目,並更改其中的 slug 和 display_name。如果該別名沒有遷移目標,請將 upgrade 設定為 null。這樣可以保留模型的上下文視窗、推理選項和工具設定。
向用戶端提供目錄
本頁面向實現 Codex Models 格式的開發者,該格式定義了模型目錄,並為模型選擇器提供支援。如果你正在建置推理供應商(例如閘道器或雲端服務),可使用本規範,讓 Codex 桌面應用和 CLI 發現你的模型,並使用其指令和能力設定。
如果你是企業管理員,希望控制模型目錄,請參閱
model_catalog_url 設定指南。
要支援此格式,請實現一個需要身分驗證的目錄端點。根據發起請求的 Codex 版本,取得上游供應商當前的預設設定,應用你的覆蓋設定,然後傳回生成的目錄。
client_version 實現目錄端點
預設目錄端點位於供應商的 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 會以
major.minor.patch 格式傳送其 CLI 版本,並移除所有預發布字尾。對於桌面用戶端,該版本是其捆綁的 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。 - 保留上游指令和工具設定,除非你已測試過替代設定。後設資料不會增加模型能力,也不會授予推理存取權限。
對於閘道器模型別名,請參閱如何 提供模型後設資料。使用每個受支援的 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。它不會取得當前上游預設設定。