一、先看懂整條鏈路：你到底在配置什么

第一次接入 Codex 時，最容易把“命令行工具”“配置切換器”“API 服務”混成一個東西。實際上它們負責的是三件不同的事：Codex 負責接收任務并執行；cc-switch 負責保存、切換和寫入供應商配置；中轉站負責接收請求、完成鑒權，再把請求轉發到可用模型。

因此，排錯時不要只盯著一個界面。命令找不到，通常是 Node.js 或 PATH；401/403，通常是 API Key、權限或啟用狀態；模型不存在，通常是模型名與賬戶可用列表不一致；改完配置卻沒有變化，通常是舊終端或舊進程仍在讀取舊配置。把問題歸類后，處理速度會快很多。

• Codex：在項目目錄中運行的命令行 AI 編程工具。
• cc-switch：把不同供應商的配置集中管理，并切換到當前要使用的一套。
• API Key：證明請求來自哪個賬戶，并決定賬戶具有什么調用權限。
• *ase **L：Codex 發起請求時要訪問的 API 根地址，通常填寫到 /v1。
• Model：實際請求使用的模型標識，必須以控制臺顯示的可用名稱為準。

? 二、開始前準備：先把四個檢查點做完

建議在 Windows 10/11 上使用 PowerShell 或 Windows Terminal 操作。整個流程需要瀏覽器、Node.js、Codex、cc-switch 和一個已經開通 API 權限的賬戶。為了讓后面的排錯有依據，先不要急著改配置，依次確認下面四件事。

這里有一個很實用的習慣：把“安裝是否成功”和“接口是否可用”分開驗證。前者只看版本號，后者才看 API Key、*ase **L 和模型。分開以后，即使接口暫時不可用，也不需要反復重裝 Codex。

• 終端能夠正常打開，并且當前用戶有權限安裝 Node.js 全局包。
• 賬戶**能夠創建 API Key，并能看到可用模型名稱。
• 本機沒有同時運行多套會改寫 Codex 配置的工具。
• 準備一個小型測試項目，不要一上來就在生產倉庫中驗證。

三、安裝 Node.js 并確認 npm 環境

Codex 的安裝依賴 Node.js。建議使用當前仍在維護的 LTS 版本，安裝過程保留默認選項即可。安裝結束后，關閉已經打開的舊終端，再新開一個 PowerShell，讓系統重新加載 PATH。

node -v
npm -v
where.exe node
where.exe npm

正常情況下，前兩條會返回版本號，后兩條會返回可執行文件路徑。如果 node -v 有結果而 npm -v 沒有結果，通常是安裝不完整或 PATH 沒有刷新；如果兩條都找不到，先重新打開終端，仍然無效再檢查 Node.js 安裝目錄是否加入系統 PATH。

如果下載依賴速度不穩定，可以只調整 npm 的下載源，不要把它和 API 的 *ase **L 混為一談。npm 源只影響安裝包下載，和后面請求模型的地址是兩條獨立鏈路。

npm config set registry https://registry.npmmirror.com
npm config get registry

四、安裝 Codex：先驗證命令，再進入配置

在確認 Node.js 和 npm 都可用后，再安裝 Codex。全局安裝的好處是可以在不同項目目錄直接調用；如果電腦上已經存在舊版本，先記錄當前版本，后續出現問題時更容易判斷是否與升級有關。

npm install -g @openai/codex
codex --version
Get-Com**nd codex

看到版本號后，不要立刻開始復雜任務。先用 codex --help 確認命令能夠啟動，再關閉當前終端，重新打開一個 PowerShell。重新打開這一步看似多余，但可以排除全局 npm **n 目錄尚未進入當前會話的問題。

codex --help

? 五、打開 cc-switch，進入 Codex 配置頁

啟動 cc-switch 后，先確認當前頁面對應的是 Codex，而不是其他命令行工具。不同工具的配置文件和字段并不完全相同，頁面選錯會導致你填完后看似保存成功，實際 Codex 并沒有讀取這套配置。

進入 Codex 頁面后，點擊右上角的“添加”按鈕，選擇“自定義配置”。第一次配置建議只添加一套線路，先把最小閉環跑通，再逐步增加其他模型或備用線路。配置越少，出錯時越容易確認到底是哪一項造成影響。

六、逐項填寫供應商：每個字段都講清楚

下面以靈能API作為接入示例。打開控制臺后，先登錄賬戶并創建一枚專門給 Codex 使用的 API Key。API Key 只在本機配置窗口中粘貼，不要放到文章、截圖、代碼倉庫或聊天窗口里；如果懷疑已經泄露，應立即在控制臺撤銷并重新生成。

在自定義供應商頁面，按照下面的含義填寫。字段名稱可能會隨著 cc-switch 版本變化，但它們表達的含義基本一致：

最常見的錯誤有三個：把官網地址填進 API 請求地址；只填寫域名而漏掉接口版本路徑；模型名憑記憶填寫，實際與賬戶可用列表不一致。出現請求失敗時，優先逐字對照控制臺和配置窗口，不要先反復點擊保存。

如果頁面提供“獲取模型列表”或“管理與測速”，可以在 API Key 和請求地址填寫完成后使用。能獲取列表，說明基礎連通性和鑒權大概率已經通過；如果獲取失敗，先處理地址、密鑰或權限問題，再繼續填寫模型。

• 供應商名稱：填寫一個便于識別的名稱，例如“靈能API-Codex”。這個名稱只用于本機區分配置。
• 備注：可以填寫“Codex 主線路”或項目名稱，方便之后切換時確認用途。
• 官網鏈接：可選，填寫控制臺地址即可，不參與 API 請求。
• API Key：粘貼控制臺生成的完整密鑰，注意不要帶空格、引號或換行。
• API 請求地址：填寫兼容接口的完整 *ase **L，例如 靈能API/v1" target="_*lank" rel="noopener">靈能API。不要重復追加 /v1/v1。
• 模型名稱：填寫賬戶實際可用的模型 ID。標題中的 GPT-5.6 只是本教程的示例，最終以你的控制臺模型列表為準。

七、保存不等于啟用：完成一次完整切換

填寫完成后點擊“添加”或“保存”。保存的含義是把這套供應商記錄到 cc-switch 的配置列表中；只有點擊“啟用”或切換到當前使用狀態，Codex 才會讀取它。這個區別是很多新手第一次失敗的原因。

啟用后，建議觀察卡片是否出現“使用中”“已啟用”或類似狀態。若狀態沒有變化，先確認你操作的是 Codex 頁面中的卡片，而不是其他工具的同名配置。cc-switch 的切換動作通常會更新 Codex 的配置文件，配置文件被其他程序占用或權限不足時，可能會出現寫入失敗。

完成啟用后，關閉已經打開的 Codex 終端和相關進程，再新開 PowerShell。Codex 通常在啟動時讀取配置，舊終端不會自動獲得新配置；這也是“界面顯示已啟用，但命令行仍然報舊錯誤”的常見原因。

八、先在 cc-switch 內測試，再啟動 Codex

如果供應商卡片上有測試按鈕，先進行一次輕量測試。測試的目標不是驗證復雜功能，而是確認請求能夠到達接口并返回響應。測試時不要使用過長提示詞，也不要上傳項目源碼，避免把網絡問題和上下文長度問題混在一起。

測試成功后，新開 PowerShell，進入一個空目錄或測試項目，再啟動 Codex。第一輪只做只讀任務，例如讓它列出項目目錄、解釋某個函數或給出修改計劃，不要立即授權大范圍寫入。這樣可以同時驗證模型、工作目錄和 Codex 進程是否正常。

mkdir codex-check
cd codex-check
codex

進入 Codex 后，可以輸入：請先只讀分析當前目錄，列出你看到的文件，并說明下一步需要哪些信息，不要修改文件。如果能正常返回結構化分析，說明從終端到中轉接口的最小鏈路已經打通。

九、需要手動兜底時：檢查 config.toml 與 auth.json

如果 cc-switch 保存后沒有生效，可以用手動檢查確認它究竟寫入了什么。Codex 常見配置目錄位于用戶目錄下的 .codex 文件夾，常見文件包括 config.toml 和 auth.json。不同版本的字段可能存在差異，手動修改前建議先復制備份，避免把原有可用配置覆蓋掉。

$codexHome = Join-Path $HOME '.codex'
Get-ChildItem $codexHome -Force
Get-Content (Join-Path $codexHome 'config.toml') -ErrorAction SilentlyContinue

一個便于理解的 TOML 結構示例如下。這里展示的是字段關系，不代表所有版本都必須逐字照抄；model 應替換為賬戶實際可用的模型，wire_api 等字段也應以當前 Codex 版本文檔和中轉接口兼容方式為準。

model_provider = "lingneng"
model = "gpt-5.6"

[model_providers.lingneng]
name = "靈能API"
*ase_url = "https://www.lnsns.com/v1"
wire_api = "responses"
requires_openai_auth = true

如果你在配置文件中看到了正確的 *ase **L 和模型，但 Codex 仍然鑒權失敗，再檢查 auth.json 是否存在舊憑據，或者當前終端是否設置了覆蓋配置的環境變量。不要同時修改多個位置；一次只改一個變量，改完重啟終端再測試。

十、按錯誤現象排查：不要盲目重裝

下面這張排查表按現象分類，適合第一次接入失敗時逐項核對。每處理一類問題，都用最小請求重新驗證一次，避免多個改動疊加后無法判斷真正原因。

如果問題仍未解決，可以按“版本號、當前啟用卡片、請求地址、模型名稱、錯誤碼、是否重啟終端”的順序記錄信息。排錯記錄越完整，越容易判斷是本地配置問題還是接口側問題。

• 提示找不到 codex：重新打開終端，執行 where.exe codex；確認全局 npm **n 路徑在 PATH 中。
• 401 Unauthorized：重新生成或復制 API Key，檢查是否帶空格、是否已撤銷、當前配置是否真的已啟用。
• 403 For**dden：檢查賬戶權限、額度、模型權限或接口側的訪問限制，不要只更換模型名。
• model not found：從控制臺復制精確模型 ID，注意大小寫、連字符、版本號和前后空格。
• 404 Not Found：檢查 *ase **L 是否重復 /v1，或者是否把完整接口路徑誤當成根地址。
• 請求超時：先用 cc-switch 的短請求測試，再檢查網絡、**、接口地址和提示詞長度。
• 改完仍走舊線路：完全退出 Codex 和舊終端，重新啟用卡片，再打開新的 PowerShell。

? 十一、穩定使用前的安全清單

尤其要注意：截圖示例中的字段可以幫助你找到位置，但不能替代你自己的賬戶信息。API Key、模型列表和權限狀態都屬于賬戶級數據，實際操作時必須以自己的控制臺為準。

• 不要把 API Key 寫進 Git 倉庫、截圖、公開文章或前端代碼。
• 為不同項目使用不同密鑰，便于單獨撤銷和定位用量。
• 修改 cc-switch 配置前保留一份可回滾的備份。
• 先讓 Codex 只讀分析，再逐步開放寫入和命令執行權限。
• 定期查看賬戶用量、密鑰狀態和可用模型，不要長期依賴過期配置。

十二、最后***四步驗收

到這里，完整接入流程應該能用四個結果來驗收：Node.js 和 Codex 能返回版本號；cc-switch 中的 Codex 卡片處于啟用狀態；cc-switch 內置測試能返回成功；新終端啟動 Codex 后能夠完成一次只讀分析。四項全部通過，再把它用于真實項目。

后續如果要增加備用模型或切換不同線路，建議一次只新增一張卡片，并為每張卡片寫清用途。這樣以后遇到模型波動、額度變化或項目切換時，只需要切換配置并重啟終端，不需要重新搭建整套環境。