透過閘道器部署 Codex

透過組織的 LLM 閘道器部署 Codex。設定模型路由、簽發開發者憑證，並分發經過驗證的 Codex 設定。

前提條件

向開發者部署 Codex 之前，請確認已具備：

• 在將要分發的確切基礎 URL 上提供 HTTPS 服務的閘道器。
• 由閘道器持有的上游供應商憑證。
• 已獲核准、面向 Codex 的模型別名，並已對映到預期的上游模型。
• 限定權限範圍的測試閘道器憑證。
• 敏感資訊分發機制或經過測試的憑證輔助程式。
• 分發設定、輔助程式執行檔及目錄檔案的方式。

閘道器要求

連線 Codex 之前，請驗證閘道器產品是否保留以下必需行為：

• 在 POST /v1/responses 接受 Codex Responses API 請求。
• 無緩衝地串流傳輸 SSE 事件，並以 response.completed 結束。
• 支援透過重放輸入延續後續對話。
• 僅在啟用 WebSocket 或增量傳輸時保留 previous_response_id。
• 保留函式呼叫及對應的 function_call_output 項。
• 將每個面向 Codex 的模型別名路由到預期的上游模型。
• 分別對使用者進行身分驗證，並傳回有助於排查問題且不掩蓋原因的錯誤。

健康檢查端點、/v1/models、Chat Completions 回應或一次純文字回覆，都不足以證明閘道器符合要求。有關詳細約定，請參閱閘道器相容性要求。

推廣閘道器

要從已部署的閘道器過渡到經過驗證的開發者使用環境，請按順序完成以下五項檢查：

1. 選擇模型名稱並驗證路由。
2. 簽發開發者憑證。
3. 透過閘道器測試 Codex。
4. 分發設定。
5. 在開發者機器上驗證。

選擇模型名稱和路由

將 Codex 的 model 設定為閘道器的模型名稱。設定閘道器，將該名稱路由到已獲核准的上游模型。

為自訂名稱使用模型目錄

如果閘道器使用的模型名稱無法被 Codex 識別，請使用 model_catalog_json。目錄提供 Codex 針對該名稱使用的指令、推理選項、上下文限制和工具能力。如果沒有匹配的條目，請求可能會到達預期的上游模型，但 Codex 會使用通用設定。

例如，要將 company-coding-model 用作 gpt-6-luna 的別名：

1. 在閘道器上建立 company-coding-model 別名，並將其路由到已獲核准的上游 gpt-6-luna 模型。
2. 下載適用於你的 Codex 版本的 Codex 模型目錄，並將副本儲存為 gateway-models.json。以此檔案為起點。
3. 編輯副本中的 gpt-6-luna 條目：將 slug 設定為 company-coding-model，並檢查其餘後設資料是否與上游模型和閘道器能力匹配。對於不涉及模型遷移的別名，將 upgrade 設定為 null。
4. 將條目保留在頂層 models 陣列中，並將檔案分發到每個用戶端。自訂目錄會替換隨附目錄，因此應包含使用者需要選擇的所有模型。

透過 LiteLLM 使用 Bedrock 時，請應用必需的目錄修改。

將閘道器別名、目錄中的 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 連線、外掛分發及其策略。

簽發開發者憑證

1. 為每位開發者簽發一個限定權限範圍的閘道器憑證，以便將用量歸屬於具體開發者 並單獨撤銷存取權限。
2. 為每個憑證設定獲准使用的模型、速率限制、預算、有效期和續期週期 。
3. 透過敏感資訊管理器或已安裝的憑證 輔助程式分發憑證。不要將上游供應商和閘道器管理員憑證存放在 開發者機器上。
4. 如果使用輔助程式，請遵循 基於命令的身分驗證約定 ，並在分發前測試權杖取得和重新整理。
5. 告知開發者如何續期憑證，以及遇到問題時應聯絡誰。

透過閘道器測試 Codex

分發任何內容之前，請按照連線到閘道器中的說明，為一個隔離的測試使用者設定計劃分發的供應商設定塊和憑證機制。

在開發者將使用的同一種 CLI 或桌面介面中執行以下檢查：

這些檢查通過後，引導開發者參閱連線到閘道器，設定並驗證自己的機器。

分發設定

要讓每臺機器使用相同的連線方式，請分發閘道器基礎 URL、 供應商 ID、獲准使用的模型別名和憑證機制。

分發內容

要設定供應商預設值，請透過選定的設定層分發以下 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 與基於命令的身分驗證結合使用。

分發預設值和強制要求

使用設定優先順序 選擇分發預設值的位置。有關強制設定和 macOS MDM 載荷，請參閱受管設定。

對於 macOS 或 Linux 上的整機預設值，使用 /etc/codex/config.toml。在 Windows 上，將 config.toml 放入 %ProgramData%\OpenAI\Codex\。使用者和 設定檔可以覆蓋這些預設值。連結中的參考資料介紹了支援的 強制要求及其檔案位置。

單獨分發引用的輔助程式執行檔和目錄檔案。

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 設定。

向開發者提供設定值

如果沒有受管分發機制，請向每位開發者提供閘道器 URL、供應商 ID、模型別名、憑證變數或解析程式，以及所需的目錄路徑。引導他們參閱連線到閘道器，設定並驗證自己的機器。

手動設定不是強制設定管道。專案本機的 .codex/config.toml 無法覆蓋敏感的供應商或身分驗證路由鍵。

在開發者機器上驗證

要確認分發的設定已到達開發者機器：

1. 重啟 Codex，並確認預期的供應商和模型。
2. 執行連線到閘道器中的簡短測試。
3. 繼續提問一次以確認對話延續正常，然後在閘道器日誌中檢查該 開發者的請求。

排查推廣過程中的故障

根據問題定位需要處理的設定層、憑證層或閘道器層：

重用現有閘道器部署

如果組織已經透過閘道器使用 Claude Code，你或許可以 重用閘道器產品、網路路徑、日誌記錄和 Bedrock 存取。新增 面向 Codex 的 Responses 路由、憑證、模型別名和 config.toml，同時 保留現有可用設定。Claude 用戶端設定和 /v1/messages 約定不會設定 Codex。

要安全遷移，請按順序完成以下步驟：

1. 盤點當前 Claude 的連線路徑：閘道器 URL、憑證來源、必需標頭、模型別名、Bedrock 設定檔對映和受管分發管道。
2. 並行新增面向 Codex 的 Responses 路由和 Codex 模型別名。
3. 簽發一個限定權限範圍的 Codex 憑證。如果 Codex 將使用靜態憑證，透過 env_key 提供該新憑證；如果 Claude 使用憑證輔助程式，則實現並測試 Codex 基於命令的解析程式約定。
4. 使用供應商設定塊為該開發者進行設定。對於受管推廣，按照透過閘道器部署 Codex中介紹的 Codex 路徑和優先順序轉換載荷。
5. 在開發者實際使用的 CLI 或桌面介面中執行簡短連線檢查，然後執行透過閘道器測試 Codex中的完整串流傳輸、對話延續、工具呼叫、錯誤、日誌記錄和別名路由檢查。
6. 試點通過後，向其餘開發者分發設定。

相關文件

• 連線到閘道器
• MCP
• 外掛
• 受管設定