先設定目標：完成一次可回退的項目接入

本教程的目標不是把所有選項一次性改滿，而是完成一條可以重復執行的最小閉環：本地命令能啟動，CC Switch 能保存并啟用配置，Codex 能完成只讀請求，最后在一個真實但低風險的項目中讀取文件。每一步都保留結果，后面排錯才有依據。

只要某一關沒有通過，就不要跳到下一關。這樣做看起來慢一點，但能避免把本地環境問題誤判成接口問題。

• 第一關：確認 Node.js、npm 和 Codex 命令可用。
• 第二關：確認靈能API參數與模型信息完整。
• 第三關：確認 CC Switch 當前啟用的是目標配置。
• **關：確認空目錄和真實項目都能完成只讀任務。

? 先看配置地圖：每個字段到底負責什么

可以把一次請求想象成一張路線圖：Codex 是發起任務的客戶端，CC Switch 是配置切換層，*ase **L 決定請求發送到哪里，API Key 負責身份認證，Model ID 決定使用哪一個模型。配置卡的名稱和備注只幫助你管理，不會改變請求本身。

Codex
  └─ 讀取當前啟用配置
       ├─ *ase **L：請求入口
       ├─ API Key：身份認證
       ├─ Model ID：目標模型
       └─ 協議類型：請求格式

最常見的誤區是把官網首頁、接口地址和模型名稱混為一談。官網用于登錄和查看服務信息，*ase **L 用于接口請求，Model ID 必須使用服務端實際識別的字符串。

第一步：從靈能API頁面確認可用模型

打開靈能API公開頁面或控制臺，先確認當前可用模型和模型 ID。不要直接復制舊文章里的模型名稱，因為模型列表、版本后綴和計費規則都可能發生變化。截圖只用于幫助定位頁面，實際配置以當天頁面信息為準。

接下來準備一枚只給 Codex 使用的 API Key。建議按設備或用途命名，例如 Codex-Windows-****。專用密鑰的好處是出現異常用量時可以單獨停用，不會連帶影響其他應用。完整 Key 不要寫進文章、截圖、倉庫或終端日志。

• 官網入口：https://www.lnsns.com/
• 模型 ID：從當天模型列表復制。
• API Key：由自己的控制臺創建，不使用示例值。

? 第二步：檢查 Windows 工具鏈

在新的 PowerShell 窗口中逐條執行下面的命令。命令有返回結果后再繼續，避免把安裝失敗和請求失敗混在一起。

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

如果 node 或 npm 無法識別，先安裝 Node.js LTS 并重新打開終端。若版本號正常但路徑異常，檢查 PATH 是否包含 Node.js 安裝目錄。工具鏈沒有通過時，不要急著修改中轉配置。

npm install -g @openai/codex
codex --version
codex --help

到這里，正確結果應該是三個命令都能返回版本或幫助信息。若 Codex 能啟動但請求失敗，問題就可以集中到 CC Switch、賬戶狀態或接口字段，而不是繼續重裝軟件。

? 第三步：創建一張可識別的配置卡

進入 CC Switch 的 Codex 配置區域，新增一張自定義服務商卡。名稱建議同時包含服務、客戶端和用途，例如“靈能API-Codex-項目測試”。以后你看到終端異常時，可以直接根據卡片名稱判斷當前啟用的是什么線路。

建議保留一張已知可用的舊配置，不要把所有卡片都覆蓋掉。新配置測試失敗時，切回舊卡片就能快速判斷問題來自新線路還是本地 Codex。

• 服務名稱：靈能API-Codex-項目測試。
• 備注：Windows / 低風險驗證 / 主線路。
• 舊配置：保留，不刪除，用于回退對照。

?? **步：按順序填寫 API Key、地址與模型

字段填寫建議遵循‘地址先行、模型其次、密鑰最后’的順序。先確認請求入口和模型 ID，再粘貼密鑰，可以減少把鑒權錯誤誤判成地址錯誤的情況。

服務名稱：靈能API-Codex-項目測試
協議類型：按客戶端當前選項選擇兼容協議
*ase **L：https://www.lnsns.com/v1
Model ID：以當前控制臺列表為準
API Key：粘貼自己的密鑰并保持隱藏

*ase **L 通常填寫到 /v1，不要在后面再拼接完整的聊天接口路徑；也不要重復寫成 /v1/v1。若客戶端明確要求完整 **L，則以客戶端字段提示為準。模型 ID 不要照抄網頁標題，優先使用列表里的接口字符串。

API Key 粘貼后檢查首尾是否多了空格或換行。若測試失敗，不要把 Key 直接發到聊天或日志里，優先回到控制臺確認密鑰狀態，必要時重新生成并撤銷舊 Key。

第五步：先做空目錄只讀驗收

保存配置后，確認卡片顯示為已啟用，然后關閉舊的 Codex 終端并重新打開 PowerShell。CC Switch 修改了配置狀態，但已經啟動的進程不一定會自動刷新。

mkdir codex-first-check
cd codex-first-check
codex

進入 Codex 后，先發送一個只讀任務：請確認當前目錄是否為空，并說明如果這里是一個代碼項目，你會按什么順序檢查文件；不要創建、刪除或修改任何文件。這個任務可以驗證命令啟動、接口鑒權、模型響應和當前工作目錄。

如果這里失敗，不要進入真實項目。先確認卡片啟用狀態、地址、模型 ID 和 Key。空目錄測試通過后，再繼續下一步。

第六步：進入項目時采用‘只讀、局部、可回退’

第一次在真實項目中使用，建議遵循三個限制：只讀、局部、可回退。先讓 Codex 查看一個指定文件或列出目錄結構，不要一上來就允許它重構項目。執行任何修改前，先確認 Git 或其他版本控制工具的工作區狀態。

cd D:\path\to\your-project
git status
codex

第一條項目任務可以是：請只閱讀 src 目錄下的指定文件，概括入口、依賴和可能的風險，不要修改文件。第二條任務再讓它提出一個小范圍修改方案，等你確認后再執行。這樣即使模型選擇或線路狀態不符合預期，也不會立刻改變項目。

如果同一任務在空目錄能返回、在項目目錄超時，優先檢查上下文大小、項目文件數量和網絡穩定性，而不是馬上更換 API Key。先縮小讀取范圍，通常能更快判斷是任務規模問題還是接口問題。

按錯誤現象排查：不要一上來重裝

排錯時每次只改一項。先切回已知可用卡片，再逐字段比較新卡片；不要同時升級客戶端、換模型、改**和重裝 Node.js。

• 401：檢查 API Key 是否完整、是否被撤銷，以及啟用卡片是否正確。
• 403：檢查額度、模型權限和服務訪問策略。
• 404：重點查看 *ase **L，確認沒有重復 /v1 或誤填完整接口路徑。
• model not found：回到模型列表復制精確 ID，檢查大小寫和版本后綴。
• timeout：先用短文本和空目錄測試，再逐步增加上下文。
• 改完仍走舊線路：關閉 Codex、舊 PowerShell 和相關**進程后重新啟動。

第七步：給配置加上安全邊界

一條能用的線路還需要基本的安全管理。API Key 采用最小權限和專用用途，定期查看用量，發現異常時及時撤銷。不要把配置截圖當成文檔附件公開保存，尤其要檢查是否包含完整密鑰、賬號郵箱或本地路徑。

需要查看當前模型、額度或服務說明時，通過可點擊的靈能API官網入口進入：https://www.lnsns.com/。實際頁面信息優先于舊截圖。

• 每個應用或設備盡量使用獨立 Key。
• 截圖只保留字段位置，不展示完整密鑰。
• 不要把包含密鑰的配置文件提交到 Git。
• 更換密鑰后撤銷舊 Key，并重新測試主線路。

? 最終驗收表：通過后再開始日常開發

完成這份驗收表后，才適合把 Codex 用到日常開發中。之后新增模型或更換線路，也可以沿用同樣的順序，先小范圍驗證，再逐步擴大任務。

• node、npm、codex 命令均能返回結果。
• 模型 ID 來自當前列表，*ase **L 版本路徑沒有重復。
• CC Switch 卡片已保存并啟用，舊終端已經關閉。
• 空目錄只讀任務成功，真實項目只讀取局部文件。
• API Key 沒有出現在文章、截圖、倉庫和公開日志中。
• 出現問題時可以切回已知可用配置。