從寫程式碼,到創作下一幕

探索 字節跳動 - 火山方舟 的 AI 程式設計與影片創作活動。

Agent Plan & Coding Plan

一站體驗多款熱門模型,為 AI 程式設計與智能體開發提供更多選擇。新使用者可聯絡(微信: goo_lvyouyou)免費體驗 9.9 agent plan。

Seedance 2.5

讓創意,躍然成片。探索 30 秒影片、多模態參考與局部編輯,把腦海中的畫面變成下一支作品。

繁體中文

連線到閘道器

設定模型閘道器,並使用原生閘道器 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 或憑證輔助程式。

啟用 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 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 登入配合使用
透過啟動輔助程式複用憑證命令。同一個閘道器金鑰從 Authorization 移至 X-Gateway-Key,而 Authorization 則由 ChatGPT 登入提供。
閘道器驗證並移除 X-Gateway-Key,然後將 ChatGPT Authorization 和任何帳戶 ID 原樣轉發到 Codex 後端。
閘道器 OAuth 如何與 ChatGPT 登入配合使用
在使用 ChatGPT 登入的同時,以原生閘道器 OAuth 替代基於 API key 的閘道器身分驗證。
閘道器處理其 OAuth cookie,並將 ChatGPT 憑證轉發到 Codex 後端。

新增路由標頭(可選)

使用管理員提供的路由設定。閘道器營運人員可以分發這些設定,並在閘道器日誌中檢查所選路由。

只有模型供應商請求使用此閘道器路由。語音會話使用單獨的路由。工作區登入、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 路由,請分享管理員遷移檢查清單。

相關文件