使用閘道團隊提供的供應商設定和驗證方式,將 Codex 連線至組織的模型閘道。閘道會將模型請求轉送至 Amazon Bedrock 等後端服務。
若要在整個組織部署閘道,請參閱部署閘道。如需瞭解 API 必須支援的行為,請參閱閘道相容性。若要略過閘道,直接連線至 Bedrock,請參閱 Amazon Bedrock。
檢查現有設定
請安裝管理員測試過的 Codex 用戶端,並確認版本與測試時相同。如果設定由組織管理,請開啟該用戶端,依照管理員提供的說明完成登入。這種情況下,可以略過下方的供應商設定範例。
- 如果使用 CLI,請檢查所選的設定檔並執行
codex doctor。啟動後,使用/status確認目前使用的模型和供應商。 - 如果使用 macOS 應用程式,請檢查
~/.codex/config.toml或組織提供的受管理設定。 - 如果使用 Windows 應用程式,請檢查
%USERPROFILE%\.codex\config.toml或組織提供的系統設定。
如果目前使用的閘道供應商和模型符合預期,請先完成管理員指定的登入步驟,再繼續驗證連線。請避免在受管理的電腦上新增第二組供應商設定。如果目前的設定與管理員提供的說明不符,請先向管理員確認這些設定應由哪個設定層級提供,再編輯本機檔案。
取得閘道連線資訊
手動設定前,請先確認是否需要登入 ChatGPT 工作區、通過閘道驗證,或兩者都需要。
若要自行設定 Codex,請向閘道團隊取得下列資訊:
- 閘道的 HTTPS 基底 URL,須包含 API 路徑,例如
https://gateway.example.com/v1。 - 要使用的模型名稱和供應商 ID。
- 驗證方式:閘道原生 OAuth、具特定權限範圍的 API 金鑰及其環境變數,或已安裝的憑證輔助程式。
- 如果使用 OAuth,請取得授權 URL、權杖 URL、公開用戶端 ID 和所需的權限範圍。如果閘道使用 Cookie 或自訂標頭,也請取得該 Cookie 或標頭的名稱。
- 所需的模型目錄 URL,或模型目錄檔案及其在本機的絕對路徑。
設定供應商
在互動式 CLI 中執行 /config,開啟工作階段 > 模型供應商。選擇建立自訂供應商或閘道,輸入名稱和基底 URL,並視需要輸入儲存 API 金鑰的環境變數名稱。若要修改可編輯的供應商,請開啟該供應商的詳細資料,然後選擇編輯設定。如果你可以變更預設供應商,請將游標移至要使用的供應商,按下 空白鍵,再使用 /new 開始對話。
若要在 CLI 登入期間設定閘道,請執行 codex --enable gateway_setup_wizard,然後選擇使用其他方式登入 > 使用自訂供應商或閘道。這個選用的登入流程預設為關閉。CLI 必須處於未登入狀態並使用內嵌的應用程式伺服器,且同時符合下列條件,才會顯示此流程:預設供應商為 OpenAI、允許使用 API 金鑰登入,而且受管理設定和啟動時的覆寫設定都未指定供應商。
若要手動設定或指定其他驗證設定,請開啟 config.toml。在 macOS 或 Linux 上,檔案位於 ~/.codex/config.toml,在 Windows 上則位於 %USERPROFILE%\.codex\config.toml。
將下列範例合併到現有設定,並將 URL 和模型名稱替換為管理員提供的值。請勿重複定義已有的鍵或資料表。此範例使用 gpt-6-sol。只有在管理員確認你的 Codex 版本能辨識此模型,且隨附的模型中繼資料與閘道相符時,才可省略自訂目錄。
請將 model、model_provider、model_catalog_json 和 web_search 放在第一個 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"
requires_openai_auth = false
接著加入閘道團隊提供的驗證設定。
enterprise-gateway 是供應商 ID 的範例。請在 model_provider 及對應的供應商和驗證資料表中使用相同的 ID。此範例會在初次測試連線時停用網頁搜尋。管理員應先確認閘道支援這項功能,再啟用網頁搜尋。
設定模型目錄
請向閘道團隊確認 Codex 如何取得所選模型的功能資訊和指示:
- 內建名稱: 如果閘道接受的模型名稱與你的 Codex 版本內建的名稱完全一致,而且閘道會將請求轉送至對應的模型,請將
model設為該名稱。Codex 已有該模型的中繼資料。 - 目錄端點: 如果閘道提供與 Codex 相容的中繼資料,請使用完整的目錄 URL。這可以是
/v1/models端點,其回應須符合 Codex 目錄回應規格。如果使用自訂別名,僅列出模型 ID 的回應不足以提供所需資訊。 - 目錄檔案: 如果閘道使用自訂別名,且管理員提供了目錄檔案,請依照本機 models.json 範例設定。
如果管理員提供了目錄 URL,請將 URL 加入現有的 [model_providers.enterprise-gateway] 資料表:
model_catalog_url = "https://gateway.example.com/codex/models.json"
如果閘道 OAuth 是唯一的憑證來源,目錄 URL 的通訊協定、主機和連接埠都必須與 base_url 相同。請先登入閘道,Codex 會使用現有的閘道工作階段取得目錄。
請移除任何目前生效的 model_catalog_json 設定,因為此設定的優先順序高於目錄 URL。管理員可在設定遠端目錄中查看端點需求。
如果管理員提供的是本機模型目錄檔案,請儲存檔案,並在第一個 TOML 資料表之前加入 model_catalog_json,將其值設為檔案的絕對路徑。自訂別名必須有相符的目錄中繼資料。例如:
model_catalog_json = "/etc/codex/gateway-models.json"
請搭配使用管理員一併提供的模型名稱和目錄。請先確認檔案位於指定位置,再加入目錄路徑。
選擇驗證方式
若要透過瀏覽器或裝置碼登入,請使用閘道原生 OAuth。若要使用具特定權限範圍的憑證,請使用 API 金鑰。如果組織提供取得憑證的指令,請使用憑證輔助程式。
使用閘道原生 OAuth
閘道 OAuth 可獨立於 ChatGPT 登入運作。如果閘道接受組織的身分識別提供者(例如 Microsoft Entra ID)核發的存取權杖,即可使用這種方式。Codex 會處理瀏覽器登入,並加密儲存憑證。如果授權伺服器核發重新整理權杖,Codex 也會負責更新存取權杖。
如果只使用閘道驗證,Codex CLI 0.166.0 及更新版本預設會透過 Authorization: Bearer <gateway access token> 傳送存取權杖。若有名為 Authorization 的項目設定在此供應商的 http_headers 或 env_http_headers 中,請將該項目移除。
閘道團隊必須註冊一個支援 PKCE 授權碼流程的公開 OAuth 用戶端。在 config.toml 的供應商設定中加入下列資料表,並將 URL 和用戶端 ID 替換為閘道團隊提供的值:
[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127
# device_authorization_url = "https://login.example.com/oauth/device"將 scopes 加入此資料表,並視需要加入 resource。兩者都應使用身分識別提供者和閘道要求的值。如果提供者要求特定權限範圍才會核發重新整理權杖,請一併要求這些權限。Codex 預設會使用可用的迴路連接埠。如果身分識別提供者要求固定的重新導向 URI,請設定 redirect_port,並註冊對應的 URI。在此範例中,URI 為 http://127.0.0.1:43127/callback。
如果閘道要求透過 Cookie 或自訂標頭傳送權杖,請在 OAuth 資料表中設定選用的 delivery 欄位。請依閘道實際驗證權杖的方式,選擇下列其中一項設定:
delivery = { kind = "cookie", name = "auth-openid" }delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }如果你的部署也要求登入 ChatGPT,請依照上例,使用 Cookie 或獨立的閘道標頭。請參閱啟用 ChatGPT 登入。
如果閘道只接受靜態 API 金鑰,必須先讓閘道支援 OAuth 權杖及其傳送方式,才能使用此流程。閘道仍會自行管理上游憑證,例如存取 Bedrock 所需的 AWS 憑證。
如果 OAuth 是唯一的憑證來源,請保留 requires_openai_auth = false,並移除先前用於閘道憑證的 env_key、experimental_bearer_token 或 auth 設定。
重新啟動桌面應用程式,依照閘道登入提示開啟瀏覽器。如果使用 CLI,請執行 codex 並依照提示登入。完成組織的登入流程和 MFA 後,返回 Codex。如果授權到期,或 Codex 無法更新授權,請依照提示重新登入。
如果透過 SSH 連線,或使用沒有瀏覽器的終端,請將 device_authorization_url 設為身分識別提供者提供的裝置授權端點。需要登入時,互動式 CLI 會顯示驗證 URL 和一次性驗證碼。請在瀏覽器中開啟該 URL 並輸入驗證碼。這個流程不需要轉送連接埠。
如果身分識別提供者只支援透過瀏覽器登入,而你透過 SSH 執行 CLI,請設定 redirect_port = 43127 並註冊相符的重新導向 URI。啟動 Codex 前,請在執行瀏覽器的電腦上轉送該連接埠:
ssh -L 43127:127.0.0.1:43127 user@remote在該 SSH 工作階段中執行 codex,並在本機瀏覽器開啟閘道登入 URL。在容器內使用瀏覽器登入流程時,瀏覽器同樣必須能連線至回呼位址。如果無法連線至該位址,請改用裝置授權、API 金鑰或憑證輔助程式。
使用 API 金鑰
如果閘道要求透過 Authorization 標頭傳送 API 金鑰,請使用這項設定。
在現有的 [model_providers.enterprise-gateway] 資料表中加入下列設定:
env_key = "CODEX_GATEWAY_API_KEY"使用組織的機密資料傳遞機制,在啟動 Codex 的程序環境中,將 CODEX_GATEWAY_API_KEY 設為閘道憑證。請勿將憑證寫入 TOML 或程式碼庫。從桌面啟動的應用程式不一定能讀取在終端中設定的變數。
使用自訂驗證標頭
如果閘道要求使用 X-API-Key 等標頭,而非持有人權杖,請將供應商資料表中的 env_key 替換為:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }標頭名稱必須與管理員提供的名稱完全一致。Codex 會從指定的環境變數讀取其值,請勿將憑證寫入設定檔。請參閱設定參考文件,瞭解 model_providers.<id>.env_http_headers 的用法。
搭配 ChatGPT 登入時,請使用自訂標頭傳送閘道金鑰,讓 Codex 能透過 Authorization 傳送使用者的 OpenAI 憑證。
如果自訂標頭是唯一的驗證機制,請使用 model_catalog_json,因為 Codex 不會執行遠端目錄探索。
使用組織的憑證輔助程式
如果供應商的主要驗證憑證由輔助程式提供,請使用管理員安裝的輔助程式和提供的設定,取代 env_key。請勿同時設定這兩種機制。你的電腦上必須已有該輔助程式,Codex 不會代為安裝。例如,加入下列資料表時,請勿設定 env_key,並請使用管理員提供的憑證解析程式路徑和引數:
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000請參閱自訂供應商驗證參考文件,瞭解指令、引數、逾時時間、更新間隔和權杖輸出規格。如果輔助程式無法再取得權杖,請向管理員確認如何更新登入狀態。
如果使用 ChatGPT 登入,並由輔助程式提供閘道權杖,請省略供應商的 auth 資料表,並設定 requires_openai_auth = true。請設定用來匯出閘道憑證的指令,並指定閘道接受的標頭或 Cookie:
[model_providers.enterprise-gateway.gateway_oauth]
delivery = { kind = "cookie", name = "gateway_session" }
[model_providers.enterprise-gateway.gateway_oauth.credential_export]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]這個指令必須將一個存取權杖寫入標準輸出。Codex 會在首次需要權杖時執行指令,並將權杖快取在記憶體中。如果閘道以 HTTP 401 拒絕推論請求,Codex 會再次執行指令,並重試該請求一次。使用 credential_export 時,請省略 OAuth 用戶端 ID 和端點設定。
你也可以在啟動 Codex 前執行輔助程式,並透過自訂閘道標頭傳送權杖。權杖到期時,請更新權杖並重新啟動 Codex。
指定輔助程式的執行檔和目錄檔案時,請使用解析後的絕對路徑。
啟用 ChatGPT 登入(建議)
如果組織使用 ChatGPT 工作區,使用者登入後即可使用符合資格的功能,例如第一方外掛程式。工作區的控管設定會生效,模型請求仍由閘道處理。比較功能可用性。
如果採用手動設定,請在登入前更新現有的 [model_providers.enterprise-gateway] 資料表:
- 設定
requires_openai_auth = true,並讓base_url繼續指向閘道。移除此供應商設定中的所有env_key、experimental_bearer_token和auth設定,讓 Codex 使用你的 OpenAI 憑證進行主要驗證。 - 另外傳送閘道憑證。如果使用閘道原生 OAuth 或閘道憑證匯出指令,請設定
gateway_oauth.delivery,指定閘道接受的 Cookie 或自訂標頭。如果使用靜態 API 金鑰,請使用自訂驗證標頭。請將Authorization保留給 OpenAI 憑證使用。
登入管理員指定的 ChatGPT 工作區。如果系統提示你登入閘道,請先完成登入,再驗證連線。
管理員可以發送受管理的供應商設定,並驗證憑證是否正確轉送。
在閘道處理憑證
閘道會在每個模型請求中收到兩組憑證。例如,當 Codex 透過 Cookie 傳送閘道 OAuth 權杖時,請求如下:
POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>
驗證閘道憑證後,請移除用來傳送該憑證的 Cookie 或自訂標頭。請遮蔽記錄中的憑證和敏感請求資料,並選擇上游請求要使用的憑證:
- 轉送使用者的憑證,直接使用 OpenAI 推論服務(建議)。 這樣 OpenAI 就能將用量歸入該使用者名下,並套用其推論設定。使用此路由時,閘道必須將
/models和/responses請求代理至https://chatgpt.com/backend-api/codex,並原樣轉送Authorization及任何ChatGPT-Account-ID標頭。 - 讓閘道向推論供應商進行驗證。 使用閘道上為該供應商設定的憑證。上游請求不得包含使用者的 OpenAI 權杖或任何
ChatGPT-Account-ID標頭。
下圖顯示使用 OpenAI 推論服務時建議採用的路由。
閘道金鑰如何搭配 ChatGPT 登入運作
閘道 OAuth 如何搭配 ChatGPT 登入運作
加入路由標頭(選用)
請使用管理員提供的路由設定。閘道維運人員可以發送這些設定,並在閘道記錄中查看實際選用的路由。
只有送往模型供應商的請求會使用這條閘道路由。語音工作階段會使用獨立的路由。工作區登入、MCP 伺服器和外掛程式也可能使用其他網路路徑。
啟動用戶端
如果使用 ChatGPT 登入,請啟動用戶端並登入提供受管理設定的工作區。如果也使用閘道原生 OAuth,請在出現提示時完成組織的閘道登入流程。接著驗證連線。
如果在本機設定供應商,請依照所用用戶端的說明操作。
設定 CLI
在 macOS 或 Linux 上,CLI 預設會讀取 ~/.codex/config.toml。儲存供應商設定後,請執行 codex。在 WSL 中,除非 CODEX_HOME 指向其他位置,否則請使用 Linux 的設定和路徑。
設定 macOS 應用程式
macOS 應用程式會讀取同一個 ~/.codex/config.toml。儲存供應商設定後,請重新啟動應用程式。如果透過環境變數提供憑證,請確認應用程式的程序能讀取該變數。
設定 Windows 應用程式
將供應商設定寫入 %USERPROFILE%\.codex\config.toml,然後重新啟動應用程式。如果透過指令進行驗證,請使用管理員安裝的憑證解析程式。例如,將 Unix 的驗證資料表替換為:
[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000
在 Windows 的 TOML 設定中,以單引號括住的字面字串會保留反斜線。也請將 Unix 的目錄檔案路徑替換為 Windows 路徑,例如 'C:\ProgramData\OpenAI\Codex\models.json'。請以管理員提供的實際路徑為準。
MCP 伺服器和外掛程式必須另外設定。模型閘道憑證不會授予工具或已連線系統的存取權。
驗證連線
請使用管理員提供的供應商 ID 和模型別名。供應商 ID 用來識別已設定的連線,模型別名則用來識別透過該連線存取的模型。ChatGPT 登入和閘道驗證都用於控管存取權,你可能需要完成這兩項驗證。
變更設定後,請重新啟動用戶端。如果使用 CLI,請執行 codex,再使用 /status 查看目前使用的模型和供應商。如果使用桌面應用程式,請檢查所選的模型和設定。
在新任務中傳送以下提示詞:
請只回覆以下內容:gateway-ok
預期回覆為 gateway-ok。單憑回覆無法確定是哪一條路由處理了請求。請管理員確認閘道記錄中包含你的使用者身分、模型別名和預期的上游路由。請勿透過詢問模型名稱來判斷實際使用的模型。
排解連線問題
| 現象 | 檢查項目 |
|---|---|
| 目前使用的供應商與預期不符。 | 檢查所選的設定檔和設定的優先順序。確認最上層的鍵沒有放在供應商資料表內。 |
| OAuth 登入或權杖傳送失敗。 | 檢查公開用戶端的註冊資訊、重新導向 URI、權限範圍,以及設定的 Cookie 或標頭。確認閘道接受核發的存取權杖。 |
| 使用 API 金鑰或憑證輔助程式時驗證失敗。 | 確認用戶端程序能讀取存放憑證的環境變數,或已安裝的輔助程式能取得有效的權杖。請管理員釐清失敗的是閘道驗證還是上游驗證。 |
| 找不到模型。 | 確認提供的模型名稱,並請管理員檢查該模型的路由。 |
| 模型實際使用的功能與預期不符。 | 請管理員確認目錄中繼資料與別名對應的實際模型相符。 |
| 串流停滯或後續對話回合失敗。 | 請閘道負責人檢查代理伺服器的緩衝設定、串流結束時的 response.completed 事件,以及閘道相容性。 |
| 無法透過指定路徑存取目錄檔案或輔助程式。 | 在執行 Codex 的環境中,確認檔案位於設定的絕對路徑。 |
尋求協助時,請提供用戶端版本、作業系統、預期使用的供應商和模型別名、驗證方式,以及失敗的步驟。請一併提供錯誤訊息和發出請求的時間,方便閘道負責人找出該筆請求。傳送前請移除權杖、Cookie、授權標頭和敏感提示詞。請勿傳送憑證檔案,或任何含有機密資料的設定傾印內容。
使用已部署的閘道
請向閘道團隊索取 Codex 的供應商設定和已核准的模型別名。如果團隊尚未啟用 Codex 路由,請將管理員遷移檢查清單提供給他們。