設定指南

中轉站設定指南

依工具瀏覽設定步驟與問題排查。

中轉站設定指南/Codex 客戶端配置

Codex 客戶端配置

Codex 客戶端是 OpenAI 的桌面應用。它可以直接登錄 ChatGPT，也可以用 API Key 走本地 Codex 工作流。新手最容易混淆的是：官方賬號登錄、OpenAI API Key、中轉站 Key 不是一回事。

官方信息 下載和文檔以官方站點為準
官方文檔 Codex 官方入口 認證與 Key ChatGPT 登錄和 API Key 登錄 配置基礎 config.toml、模型和 Provider Windows 客戶端 Windows 下載和安裝說明

先分清兩種登錄方式

這個頁面只講桌面客戶端裡和 Key、模型、Provider 有關的配置。命令行安裝、終端命令和更完整的 CLI 用法放在 CLI 工具 頁面。

ChatGPT 登錄API Key 登錄config.toml模型選擇自定義 Provider中轉站 Key
方式適合誰Key 怎麼處理
ChatGPT 登錄已經有 ChatGPT Plus / Pro / Business / Enterprise 等賬號，希望直接使用官方 Codex。按客戶端登錄引導登錄賬號，一般不需要手動填寫 API Key。
OpenAI API Key 登錄想用 OpenAI Platform 賬號按量計費，或本地工作流需要 API Key。使用 OpenAI 控制臺生成的 Key，不是中轉站 Key。
中轉站 / 代理服務服務商給了自己的 API 地址、Key、模型名。不要在官方 API Key 登錄框裡亂填；通常要通過 config.toml 配自定義 Provider。
Windows 文件管理器中的 Codex 配置目錄截圖：C:\Users\guoguo\.codex 和 config.toml

示例路徑：C:\Users\你的用戶名\.codex

Key 怎麼配置

Codex 的本地配置目錄叫 .codex。Windows 客戶端使用 %USERPROFILE%\.codex，macOS / Linux 通常使用 ~/.codex。如果你只用 ChatGPT 登錄，先不要手動寫 Key；如果你用中轉站或第三方服務商 Key，建議把 Key 放進系統環境變量，再讓 config.toml 讀取這個變量。

系統配置文件Key 建議放哪裡
Windows%USERPROFILE%\.codex\config.toml用戶環境變量，例如 MZ_PROXY_API_KEY。
macOS / Linux~/.codex/config.toml當前終端環境變量，確認成功後再按自己的系統習慣長期保存。
WSL~/.codex/config.tomlWSL 有自己的 home，不會自動讀取 Windows 的 %USERPROFILE%\.codex。
先臨時測試 Key 下面只保留當前窗口臨時生效的命令。確認能跑通後，再到系統環境變量或你熟悉的終端配置里長期保存。
PowerShell 臨時測試
$env:MZ_PROXY_API_KEY = "你的_Key"

不要把真實 Key 寫進網頁、截圖、聊天記錄或項目倉庫。能用環境變量就不要直接把 Key 寫進 config.toml。Windows 長期保存時，可以在系統“環境變量”裡新增用戶變量；macOS / Linux 長期保存方式取決於你實際使用的終端。

模型怎麼配置

默認模型寫在 config.toml 頂部。官方文檔當前推薦從 gpt-5.5 開始；如果你使用中轉站，就填服務商後臺模型列表裡用於 API 調用的那串名稱。它可能被後臺叫作“模型 ID”“模型名”或“模型名稱”，都要原樣複製，不要自己改大小寫、橫線或點號。

模型配置示例
model = "gpt-5.5"
配置項怎麼填容易錯的地方
model模型 ID / 模型名，也就是後臺模型列表裡用於 API 調用的原始標識。把自己起的中文顯示名當成模型標識，或自己改了大小寫、橫線和點號。
model_provider選擇下面定義的 Provider ID。寫了 Provider 表，但這裡沒有切過去。
openai_base_url只在你要改內置 OpenAI Provider 的請求地址時使用。把它和自定義 Provider 混用，導致請求走錯。
wire_api一般使用 responses。服務商不支持 Responses API 時可能無法正常使用。

中轉站 Provider 怎麼配置

中轉站配置的核心是三件事：模型名、Base URL、Key 環境變量。如果你的服務商提供 OpenAI 兼容接口，優先讓它支持 Responses API；只支持舊 Chat Completions 的服務商，後續兼容性會更差。

Provider 配置示例
model = "服務商後臺顯示的模型 ID 或模型名" model_provider = "mz_proxy" [model_providers.mz_proxy] name = "某某中轉站" base_url = "https://你的服務商API地址" env_key = "MZ_PROXY_API_KEY" wire_api = "responses"
如果你用的是中轉站自己的 Key，更推薦“自定義 Provider 示例”這一種；如果只是企業代理、數據駐留或 OpenAI 官方項目的轉發地址，才考慮 openai_base_url。
檢查項正確做法不正確做法
Base URL複製服務商後臺給出的 API 地址，是否帶 /v1 看服務商說明。把網站首頁、控制臺首頁當 API 地址。
Key使用環境變量名，例如 MZ_PROXY_API_KEY。把 Key 直接寫進項目文件或截圖發出去。
Provider ID自己起一個英文 ID，例如 mz_proxy。使用 openai、ollama、lmstudio 這類保留 ID。
模型 ID / 模型名複製後臺模型列表裡用於 API 調用的原始標識。用自己起的顯示名、套餐名或憑印象猜的名字。

客戶端設置裡先看這些

打開 Codex 客戶端設置後，左側會按“個人、集成、編碼、已歸檔”分組。新手先從 常規 開始，主要確認工作模式、權限範圍、默認打開位置、終端和語言；模型、Key、Provider 仍然回到前面的 config.toml 配置部分處理。

Codex 客戶端中文常規設置頁截圖
設置項圖裡是什麼意思新手建議
工作模式選擇 Codex 回覆時顯示多少技術細節。適用於編程會更偏代碼和控制，適用於日常工作會減少技術細節。做代碼配置、排查報錯時選“適用於編程”；只是寫文案或整理內容時選“適用於日常工作”。
默認權限允許 Codex 讀取並編輯當前工作區裡的文件；需要訪問工作區外的內容時再請求額外權限。保持默認即可。每次授權前看清楚它要訪問哪裡。
自動審核Codex 可以自動判斷一部分額外訪問權限請求，但頁面裡也提醒自動審核可能會出錯。新手不確定時先關閉，改為自己逐次確認；熟悉後再按需要開啟。
完全訪問權限讓 Codex 無需審批就能編輯電腦上的任何文件並運行聯網命令，風險明顯更高。不要默認開啟。只有在你明確知道後果，並且當前任務確實需要時再臨時打開。
默認打開目標決定客戶端默認打開文件或文件夾時使用哪個應用。截圖裡顯示的是 Antigravity。選你平時實際用的編輯器或工作區，不確定就先保持當前值。
集成終端 Shell決定 Codex 在集成終端裡使用 PowerShell、CMD、Git Bash 等哪一種 Shell。Windows 新手優先用 PowerShell，除非教程明確要求其他終端。
語言控制客戶端界面語言。截圖裡是自動檢測。想保持中文說明，就選擇中文或自動檢測。
底部面板 / 默認終端位置控制底部面板是否顯示，以及終端標籤頁默認出現在底部還是右側。按屏幕大小選擇：筆記本一般放底部，寬屏可以放右側。
代碼審查決定啟動 /review 時是在當前對話中審查，還是拆成單獨的審查對話。新手先用“行內視圖”，上下文更集中。
建議提示根據項目文件和已連接應用，提示下一步可以做什麼。可以打開；如果覺得打擾，再關閉。

驗證和排查

改完 Key、模型或 Provider 後，重啟客戶端，新建一個測試線程。先不要讓它改文件，只讓它確認當前項目和模型能正常工作。

首次驗證提問模板
請先說明你能看到哪些文件。 不要修改任何文件，也不要運行命令。 請只回覆當前項目是否可讀，以及你正在使用的模型 ID / 模型名。
現象通常原因怎麼處理
提示沒有 Key 或認證失敗環境變量沒生效，或客戶端還沒重啟。重新打開終端/客戶端；Windows 用新窗口檢查環境變量。
模型不可用模型 ID / 模型名寫錯，或服務商沒有開通該模型。回到服務商後臺複製模型列表裡的原始標識。
404 / endpoint not foundBase URL 路徑不對，常見是 /v1 多了或少了。按服務商文檔確認 API 地址，不要猜。
請求走到官方 OpenAIProvider 沒切到自定義 ID，或用了 openai_base_url 但不是這個場景。檢查 model_provider 是否等於你的 Provider ID。
WSL 裡生效，Windows 客戶端不生效Windows 和 WSL 使用不同的 .codex 目錄。確認你改的是客戶端實際讀取的那個配置文件。
如果你只是用官方 ChatGPT 登錄，不需要先配置中轉站 Key。只有當你明確要走 API Key、企業代理或第三方服務商時，才需要改 config.toml。

權限與安全

Codex 客戶端可以讀取項目文件，也可能根據你的確認修改文件、執行檢查或打開頁面查看。新手最重要的是先看清楚它要做什麼，再允許它繼續。

位置要重點看什麼新手建議
審批提示是否要修改文件、運行檢查或訪問外部服務。看不懂就先拒絕，讓 Codex 用中文解釋原因。
文件改動新增、刪除、修改了哪些文件。提交前逐個看 diff，不要只看總結。
項目範圍這次對話連的是你電腦上的哪個項目。確認不是舊項目或測試項目。
改動放在哪看它是不是在一份隔離的副本里改，而不是直接動你的原項目不確定風險時優先用隔離副本。
瀏覽器頁面查看打開的是不是本地開發頁面。涉及賬號、付款、後臺權限時自己手動確認。