身為閘道管理員,請先設定模型路由,並授權一位使用者參與試行。在每個支援的用戶端上測試連線後,再將設定分發給開發人員。閘道驗證可使用閘道原生 OAuth、API 金鑰或認證輔助程式。如要搭配使用閘道驗證與 ChatGPT 工作區登入,請參閱透過閘道使用 ChatGPT 登入。
先決條件
為開發人員部署 Codex 前,請確認已具備以下條件:
- 閘道透過 HTTPS 提供服務,且其基底 URL 與即將分發的 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:
選擇模型名稱與路由
將 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 目錄端點。分發設定時,請在 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 端點。
如果閘道 OAuth 是唯一的憑證,請明確指定目錄 URL,並確認其通訊協定、主機及連接埠都與 base_url 相同。Codex 會沿用現有的閘道工作階段,不會提示使用者登入,也無須透過 API 金鑰探索目錄。
已核准的模型有變動時,請與供應商協調更新目錄。變更用戶端設定後,請重新啟動用戶端。
移除所有會生效的 model_catalog_json 設定,包括透過 requirements.toml 強制套用的設定。這項設定的優先順序高於遠端 URL,會使 Codex 略過遠端目錄的擷取作業。
分發本機目錄
使用 model_catalog_json,讓 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
- 註冊支援 PKCE 授權碼流程的公開 OAuth 用戶端,並核准可登入的使用者或群組。
- 設定閘道,讓它驗證指定 Cookie 或自訂標頭中已核發的存取權杖。依各使用者的身分套用已核准的模型、速率限制及預算。
- 依照閘道原生 OAuth 的說明,取得授權 URL、權杖 URL、公開用戶端 ID、授權範圍、選用的資源、權杖傳遞設定,以及固定的重新導向連接埠(如有)。向身分提供者註冊相符的回送重新導向 URI。如果身分提供者支援裝置授權,請一併將
device_authorization_url分發給遠端 CLI 使用者。 - 在預計部署的 CLI 或桌面應用程式上,使用測試帳號測試瀏覽器登入、權杖更新及存取權撤銷。針對遠端 CLI 使用者,請測試以裝置代碼登入,或確認瀏覽器能連線至本機回送位址上的回呼端點。
每位使用者都要個別登入。只需分發 OAuth 設定,無須分發用戶端密鑰、閘道 API 金鑰或輔助程式的執行檔。上游供應商的憑證應保留在閘道上。
API 金鑰或認證輔助程式
- 為每位開發人員核發一份限定存取範圍的閘道憑證,以便按人追蹤用量及個別撤銷存取權。
- 為每份憑證設定已核准的模型、速率限制、預算、到期時間及續期週期。
- 透過機密資料管理工具或已安裝的認證輔助程式傳遞憑證。請勿將上游供應商或閘道管理員的憑證存放在開發人員的電腦上。
- 如果輔助程式提供用於向供應商驗證身分的主要憑證,請遵循透過指令驗證的規格。如果使用者透過 ChatGPT 登入,並由輔助程式另外提供閘道憑證,請設定閘道憑證匯出指令。分發前,請測試權杖的取得與更新。
- 告知開發人員如何為憑證續期,以及需要協助時應聯絡誰。
透過閘道測試 Codex
分發任何設定或檔案前,請依照設定供應商的說明,為一個獨立的測試帳號套用預計分發的供應商設定區塊及驗證方式。
如果模型目錄由閘道提供,請確認閘道傳回與 Codex 相容的 models 陣列。如果使用者以自己的憑證使用 OpenAI 推論服務,請確認閘道會將必要的 ChatGPT 標頭轉送至 Codex 後端。
記錄試行時使用的用戶端版本、作業系統、供應商 ID、模型別名及驗證方式。在每個預計支援的 CLI 或桌面用戶端上執行下列檢查。如果同時支援單獨使用閘道驗證,以及搭配使用閘道驗證與 ChatGPT 登入,請分別測試這兩種組合。
| 檢查項目 | 操作 | 通過條件 |
|---|---|---|
| 實際生效的設定 | 檢查各設定層級,確認供應商、模型及強制設定均符合預期。 | 試行帳號使用分發的設定,使用者或設定檔的預設值未導致請求改走其他路由。 |
| 連線 | 依照驗證連線的說明操作。 | 預期的供應商與別名已生效,測試提示詞成功取得回應,且閘道記錄可辨識出測試使用者。 |
| 串流 | 請 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 無法覆寫涉及供應商或驗證路由的敏感設定鍵。
在開發人員的電腦上驗證
請依照以下步驟,確認開發人員的電腦已收到分發的設定:
- 確認已安裝核准的用戶端,以及所有必要的輔助程式或目錄檔案。重新啟動 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 金鑰或認證輔助程式,並授權一位測試使用者。如果使用靜態憑證,請透過
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 模型目錄。
將 model_catalog_json 設為該檔案的絕對路徑,並將此設定寫入 config.toml。重新啟動 Codex,選取 Gateway model,然後送出請求。確認閘道收到的模型 ID 與您在 slug 中設定的值相符。
如要為內建模型設定別名,請從所用 Codex 版本的目錄中複製該模型的完整項目,再變更其 slug 和 display_name。如果該別名沒有遷移目標,請將 upgrade 設為 null。這樣可以保留模型的上下文視窗、推理選項及工具設定。
向用戶端提供目錄
本節供實作 Codex Models 格式的開發人員參考。這個格式定義了模型目錄,也是模型選擇器的運作依據。如果您正在建置閘道或雲端服務等推論服務,請依循這項規格,讓 Codex 桌面應用程式與 CLI 能探索您提供的模型,並使用各模型的指示及功能設定。
如果您是企業管理員,想要管控模型目錄,請參閱 model_catalog_url 設定指南。
如要支援此格式,請實作需要身分驗證的目錄端點。依發出請求的 Codex 版本,向上游供應商擷取目前的預設值,套用您的覆寫設定,再傳回產生的目錄。
client_version 實作目錄端點
預設的目錄端點為 /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。您也可以指定預設的 /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,請選擇與用戶端相符的版本:
- 查看
ModelsResponse和ModelInfo回應型別,以瞭解結構描述。 - 如需完整範例,請查看隨附的
models.json。這是目錄資料,而非 JSON Schema 文件。
隨附的檔案是該版本發行時的快照。產生目錄前,請先擷取目前的預設值。
擷取上游目前的預設值
提供 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 套件:
- 使用
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。這個函式不會擷取上游目前的預設值。