如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

閘道相容性要求

檢查閘道是否符合 Codex 的要求

這些要求適用於使用 API 或供應商憑證透過閘道連線的情境。如果閘道轉送的是 ChatGPT 工作區請求,請參閱透過閘道使用 ChatGPT 登入。

採用這種連線方式時,閘道必須保留以下各節說明的 Responses API 行為,包括端點、串流、對話延續、工具呼叫、驗證、路由,以及可用於診斷問題的錯誤資訊。

如要部署閘道,請參閱部署閘道。如要設定開發人員的電腦,請參閱使用 API 或供應商憑證。

請求與端點

設定閘道供應商時,請使用 wire_api = "responses"。以基底 URL https://gateway.example.com/v1 為例,閘道必須接受 POST /v1/responses,並保留用戶端使用的請求與回應欄位。即使 Chat Completions 或 Anthropic Messages 端點運作正常,也無法據此確認閘道與 Responses API 相容。

健康檢查和模型清單端點可協助維運,但並非必要。呼叫這些端點不會實際執行 Codex 對話,也無法驗證是否支援工具。

串流

請在收到伺服器傳送事件(SSE)時逐一轉送,不要等到整個回答都寫入緩衝區才傳送。保留事件類型和承載資料,包括表示回應成功結束的 response.completed 事件。請一併轉送錯誤和失敗事件,讓用戶端能區分回應失敗與連線停滯。

驗證完整串流時,除了閘道,也要檢查串流經過的負載平衡器和反向代理伺服器。即使收到文字回覆,只要串流未正常結束,就不足以通過驗證。

對話延續

在後續回合中,請保留用戶端重新傳送的對話輸入。閘道必須接受下一回合所需的先前訊息、工具呼叫和工具結果。

如果啟用 WebSocket 或增量傳輸,也請驗證 previous_response_id 的行為。透過無狀態 HTTP 連線使用 Responses API 時,可以重新傳送先前的輸入來延續對話,無須使用上述延續機制。

工具

保留函式呼叫項目及其對應的 function_call_output 項目,包括用來配對呼叫與結果的識別碼。整個流程都必須能順利完成:Codex 收到呼叫、執行工具、提交工具結果,最後收到最終回答。

文字請求成功並不足以驗證這個流程。請使用預計啟用的模型和用戶端功能進行測試。即使閘道接受某個請求欄位,也不能據此認定上游模型支援對應的功能。

驗證與標頭

閘道必須支援部署時選用的用戶端驗證機制:使用 env_key 或透過指令取得的 Bearer Token,或使用 env_http_headers 在自訂標頭中傳送憑證。機密的標頭值應透過環境變數提供,請勿直接寫入設定。如需瞭解設定方式和憑證輔助程式須遵循的規格,請參閱自訂供應商參考文件。

請分開驗證開發人員的身分,以及閘道存取上游供應商時使用的身分。管理員金鑰和上游憑證應保存在閘道上。保留路由和使用者歸屬判定所需的標頭,並測試憑證到期、更新與撤銷時的行為。

模型路由與中繼資料

對於提供給 Codex 的每個模型名稱,閘道都必須將請求轉送至預定的上游模型。請查看閘道紀錄以確認實際路由,不要只憑模型對自身身分的描述來判斷。

請使用已部署的 Codex 版本能辨識的名稱,或為自訂別名提供相符的模型目錄。也請檢查模型可用性與遷移相關的中繼資料。任何替代模型的請求都必須經由閘道轉送。如果組織自有的別名沒有對應的遷移安排,請將其目錄項目的 upgrade 設為 null。用戶端會根據目錄中繼資料調整行為,但這些資料無法為模型新增功能,也不會建立閘道路由。請依據實際使用的上游模型和供應商,驗證上下文限制、推理選項和工具支援情形。一般閘道連線不會自動套用 Codex 內建供應商整合所做的中繼資料調整。

Codex 可辨識的模型名稱

請使用已部署的 Codex 版本能辨識的完整模型名稱,將閘道別名和 Codex 的 model 都設為這個名稱。確認上游供應商支援該模型,且組織已核准使用。

執行 codex --version 查看版本,然後選取對應的 rust-v<version> 標籤,查看該版本的 Codex 模型目錄。如果使用自訂建置版本,請以建置時所用的原始碼提交為準。如果部署桌面版,則以隨附的 CLI 版本為準。查看各項目的 slug 值,即可找出該版本能辨識的模型名稱。如果閘道改變了模型的功能,即使 Codex 能辨識該名稱,仍須提供反映這些差異的目錄中繼資料。

錯誤

錯誤資訊應能區分用戶端驗證錯誤、未知的模型路由、觸及速率限制,以及上游服務失敗。請勿一律以通用的 500 回應表示所有失敗。傳回的資訊應足以診斷哪一層發生問題,同時避免洩漏 Token、供應商憑證或敏感的請求內容。

資料與工具的邊界

模型流量會經過下列路徑:

Codex client -> LLM gateway -> model provider

用戶端使用開發人員憑證向閘道驗證身分。閘道則使用自己的上游供應商憑證存取模型。模型請求中包含的提示詞、原始碼片段、工具引數和工具結果都可能經過閘道。請據此設定日誌記錄、資料保留、敏感資訊遮蔽、存取和匯出的控管措施。

Codex 建立的連線只有一部分會經過模型閘道。本機指令會在用戶端的執行環境中執行。MCP 伺服器、外掛程式服務、與瀏覽器及應用程式的互動,以及其他已啟用的服務,都可能使用各自的網路路徑和憑證。模型供應商設定不會授予這些服務所需的權限,也無法取代各自的網路控管措施。如需瞭解這些邊界,請參閱智慧體核准與安全性和 MCP。

相容性驗證清單

針對每一組實際部署的用戶端、閘道和模型,請記錄下列各項的驗證證據:

  • Responses API 的請求與回應欄位均有保留。
  • SSE 事件逐一送達,且串流成功結束。
  • 重新傳送先前的輸入後,對話能在後續回合延續。
  • 如果選用的傳輸方式會使用 previous_response_id,其行為符合預期。
  • 函式呼叫與結果正確配對,且用戶端收到最終回答。
  • 模型路由正確,且中繼資料與模型相符。
  • 能辨識每個請求所屬的使用者,並能更新和撤銷憑證。
  • 驗證、路由、速率限制和上游服務的錯誤資訊足以協助診斷。
  • 診斷資訊中的敏感內容已遮蔽,且日誌記錄符合預定政策。

在分發設定前,請依照部署測試程序收集上述驗證證據。