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

連線至閘道

設定模型閘道,並使用閘道原生 OAuth、API 金鑰或憑證輔助程式進行驗證。

使用閘道團隊提供的供應商設定和驗證方式,將 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 金鑰或憑證輔助程式。

啟用 ChatGPT 登入(建議)

如果組織使用 ChatGPT 工作區,使用者登入後即可使用符合資格的功能,例如第一方外掛程式。工作區的控管設定會生效,模型請求仍由閘道處理。比較功能可用性。

如果採用手動設定,請在登入前更新現有的 [model_providers.enterprise-gateway] 資料表:

  1. 設定 requires_openai_auth = true,並讓 base_url 繼續指向閘道。移除此供應商設定中的所有 env_key、experimental_bearer_token 和 auth 設定,讓 Codex 使用你的 OpenAI 憑證進行主要驗證。
  2. 另外傳送閘道憑證。如果使用閘道原生 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 路由,請將管理員遷移檢查清單提供給他們。

相關文件