連線到閘道器
設定模型閘道器,並使用原生閘道器 OAuth、API key 或憑證輔助程式進行身分驗證。
使用閘道器團隊提供的供應商設定和身分驗證方法,將 Codex 連線到組織的模型閘道器。閘道器會將模型請求路由到你的後端,例如 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 key 及其環境變數,或已安裝的憑證輔助程式。
- 對於 OAuth,需要授權 URL、權杖 URL、公開用戶端 ID 以及所有必需的權限範圍。對於使用 cookie 或自訂標頭的閘道器,需要相應的名稱。
- 任何必需的模型目錄 URL,或目錄檔案及其本機絕對路徑。
設定供應商
在 macOS 或 Linux 上,開啟位於 ~/.codex/config.toml 的 config.toml;在 Windows 上,開啟
%USERPROFILE%\.codex\config.toml。
將此範例合併到現有設定中,用管理員提供的值替換 URL 和模型。不要重複定義已有的鍵或表。此範例使用 gpt-6-sol;只有管理員確認你的 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。該 URL 可以是實現了 Codex 目錄回應的
/v1/models端點。僅列出模型 ID 的回應不足以支援自訂別名。 - 目錄檔案: 如果閘道器使用自訂別名,且管理員分發了檔案,請使用本機 models.json 範例。當原生閘道器 OAuth 是唯一憑證且你需要自訂後設資料時,請使用本機檔案。
對於使用 API key 或輔助程式的身分驗證,如果管理員提供了模型目錄
URL,請將其新增到現有的
[model_providers.enterprise-gateway] 表中:
model_catalog_url = "https://gateway.example.com/codex/models.json"移除所有生效的 model_catalog_json 設定;它的優先順序高於 URL。管理員可參閱遠端目錄設定,瞭解端點要求。
如果管理員提供了本機模型目錄檔案,請將其儲存到本機,並在第一個 TOML 表之前新增 model_catalog_json,使用該檔案的絕對路徑。自訂別名需要匹配的目錄後設資料。例如:
model_catalog_json = "/etc/codex/gateway-models.json"使用管理員配套提供的模型名稱和目錄。只有檔案確實存在於指定位置時,才新增目錄路徑。
選擇身分驗證方法
使用原生閘道器 OAuth 透過瀏覽器登入,使用 API key 作為具有特定權限範圍的憑證,或在組織提供相應命令時使用憑證輔助程式。
{/* prettier-ignore */}
使用原生閘道器 OAuth
閘道器 OAuth 獨立於 ChatGPT 登入。當閘道器接受由你的組織身分供應商(例如 Microsoft Entra ID)簽發的存取權杖時,可使用此方式。Codex 負責瀏覽器登入、憑證加密儲存,以及在授權伺服器簽發重新整理權杖時重新整理權杖。
僅使用閘道器身分驗證時,Codex CLI 0.166.0 及更高版本預設透過 Authorization: Bearer <gateway access token> 傳送存取權杖。請移除此供應商的 http_headers 或 env_http_headers 中的所有 Authorization 條目。
閘道器團隊必須註冊一個支援帶 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根據身分供應商和閘道器的要求,在此表中新增 scopes,並在需要時新增 resource。如果供應商要求使用特定權限範圍才能簽發重新整理權杖,請請求這些權限範圍。Codex 預設使用可用的迴環埠。如果身分供應商要求固定的重新導向 URI,請設定 redirect_port,並為此範例註冊 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 key 的閘道器,必須先新增對 OAuth 權杖及其傳遞方式的支援,才能使用此流程。閘道器繼續管理自己的上游憑證,例如用於 Bedrock 的 AWS 憑證。
當 OAuth 是唯一憑證時,保留 requires_openai_auth = false,並移除之前用於閘道器憑證的 env_key、experimental_bearer_token 或 auth
設定。如果需要自訂模型後設資料,請使用本機模型目錄;僅使用 OAuth 無法啟用遠端目錄發現。
重啟桌面應用,並按照閘道器登入提示開啟瀏覽器。在 CLI 中,啟動 codex,並在 Codex 首次存取閘道器時按照提示透過瀏覽器登入。完成組織的登入和 MFA,然後返回用戶端。如果授權過期或 Codex 無法重新整理授權,請在收到提示時重新登入。
原生閘道器 OAuth 需要瀏覽器和可存取的迴環回呼地址。它不提供裝置碼備用方式。如果透過 SSH 執行 CLI,請在
OAuth 表中設定 redirect_port = 43127,並註冊上述匹配的重新導向 URI。在執行瀏覽器的電腦上,先轉發該埠,再啟動 Codex:
ssh -L 43127:127.0.0.1:43127 user@remote在該 SSH 會話中,啟動 codex,並在本機瀏覽器中開啟閘道器登入 URL。容器內的 CLI 同樣需要能從瀏覽器存取的回呼地址。如果無法使回呼地址可存取,請改用 API key 或憑證輔助程式。
使用 API key
當閘道器要求在 Authorization 標頭中提供 API key 時,使用此設定。
在現有的
[model_providers.enterprise-gateway] 表中新增以下設定:
env_key = "CODEX_GATEWAY_API_KEY"透過組織的敏感資訊下發機制,在啟動 Codex 的程序環境中,將閘道器憑證提供為 CODEX_GATEWAY_API_KEY。不要將憑證放入 TOML 或儲存庫。在終端中設定的變數可能無法被從桌面啟動的應用存取。
使用自訂身分驗證請求標頭
如果閘道器要求使用 X-API-Key 等請求標頭,而不是 Bearer 權杖,請將供應商表中的 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;遠端目錄發現不會執行。
使用組織的憑證輔助程式
如果管理員提供了基於命令的身分驗證,請使用其安裝的輔助程式和設定來替代 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 登入時,請在啟動 Codex 之前執行輔助程式,並透過自訂閘道器標頭傳遞其輸出,而不是設定 auth 表。金鑰過期後,請取得新金鑰並重新啟動 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 key 或憑證輔助程式,請使用自訂身分驗證標頭。將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 server 和外掛也可能使用其他網路路徑。
啟動用戶端
使用 ChatGPT 登入時,請啟動用戶端並登入提供受管設定的工作區。如果使用原生閘道器 OAuth,還需在收到提示時完成組織的閘道器登入。然後驗證連線。
對於在本機設定的供應商,請按照所用用戶端的說明操作。
設定 CLI
在 macOS 或 Linux 上,CLI 預設讀取 ~/.codex/config.toml。儲存供應商設定後,執行 codex。在 WSL 中,使用 Linux 設定和路徑,除非 CODEX_HOME 指向其他位置。
設定 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 目錄路徑,例如替換為
'C:\ProgramData\OpenAI\Codex\models.json',並使用管理員提供的實際路徑。
單獨設定 MCP server 和外掛。模型閘道器憑證並不授予存取工具或已連線系統的權限。
驗證連線
使用管理員交接資料中的供應商 ID 和模型別名。供應商識別已設定的連線;模型別名識別透過該連線路由的模型。ChatGPT 登入和閘道器身分驗證用於控制存取權限,可能需要同時使用。
更改設定後,重啟用戶端。在 CLI 中,啟動 codex
並使用 /status 檢查當前模型和供應商。在桌面應用中,檢查所選模型和設定。
在新任務中傳送以下提示詞:
Reply with exactly: gateway-ok預期得到 gateway-ok。僅憑回應無法證明由哪條路由處理了請求:請讓管理員確認閘道器記錄了你的使用者、模型別名和預期的上游路由。不要透過詢問模型的名稱來識別模型。
排查連線問題
| 症狀 | 檢查項 |
|---|---|
| 預期的供應商未啟用。 | 檢查所選設定檔和設定優先順序。確認頂層鍵未放在供應商表內。 |
| OAuth 登入或權杖傳遞失敗。 | 檢查公開用戶端註冊資訊、重新導向 URI、作用域以及設定的 cookie 或請求標頭。確認閘道器接受已簽發的存取權杖。 |
| API key 或輔助程式身分驗證失敗。 | 檢查憑證變數是否傳入用戶端程序,或已安裝的輔助程式是否能取得當前有效的權杖。請管理員區分閘道器身分驗證和上游身分驗證。 |
| 找不到模型。 | 確認提供的模型名稱,並請管理員檢查其路由。 |
| 模型使用了非預期的能力。 | 請管理員檢查目錄後設資料是否與別名背後的模型匹配。 |
| 流式傳輸停滯或後續互動失敗。 | 請閘道器負責人檢查代理緩衝、表示結束的 response.completed 事件以及閘道器相容性。 |
| 目錄或輔助程式路徑不可用。 | 確認檔案位於執行 Codex 的環境中設定的絕對路徑下。 |
請求幫助時,請提供用戶端版本、作業系統、預期的供應商和模型別名、身分驗證方式以及失敗的步驟。附上錯誤訊息和請求時間,以便閘道器負責人定位請求。移除權杖、cookie、授權標頭和敏感提示詞。不要傳送憑證檔案或包含金鑰的設定轉儲。
使用現有閘道器部署
向閘道器團隊索取 Codex 供應商設定和獲准使用的模型別名。如果團隊仍需啟用 Codex 路由,請分享管理員遷移檢查清單。