Codex 中轉 API 故障排查教程：靈能API CC Switch 定位超時、401 與 404
Codex 接入中轉線路后，真正讓人困擾的往往不是填寫字段，而是錯誤出現時不知道從哪里查起。同一個‘請求失敗’，可能來自 *ase **L、模型名、令牌權限、網絡超時，也可能是本地進程仍在使用舊配置。本文用一套從現象到證據的排查順序，把常見問題拆成可復現、可回滾的檢查步驟。
先判斷：問題發生在哪一層
排查不要從‘重新填一遍 Key’開始。先把故障拆成四層：網絡層、接口層、鑒權層和客戶端層。網絡層關注是否能建立連接；接口層關注路徑和協議；鑒權層關注令牌與權限；客戶端層關注 CC Switch 是否真的切換成功。
每次只改變一個變量，并保留錯誤碼、請求時間和當前配置卡名稱，后續才能判斷哪一步真正起作用。
- 網絡層：DNS、**、防火墻、超時。
- 接口層：*ase **L、路徑、請求方法和模型字段。
- 鑒權層：API Key 狀態、額度、分組和模型權限。
- 客戶端層：配置卡、緩存進程、工作目錄和環境變量。
第一步：確認服務入口和當前線路
先打開靈能API的公開入口，確認服務狀態、當前可用模型和接口說明。不要直接照抄舊文章里的地址，因為中轉接口可能會調整路徑、模型標識或兼容參數。
官網入口可從靈能API主頁進入：https://www.lnsns.com/。本文只展示排查方法，不在正文中放置真實令牌。
- 接口地址以當前說明為準。
- Model ID 從當前列表復制，不手打近似名稱。
- API Key 僅在本機安全位置保存，不寫進文章、倉庫或截圖。
? 第二步：檢查 CC Switch 是否真的切換
配置卡選中并不等于已經被正在運行的 Codex 進程讀取。先在 CC Switch 中確認卡片名稱、啟用狀態和最后更新時間，再關閉舊進程，重新啟動客戶端。
- 當前卡片是否是項目真正使用的那一張。
- 是否存在同名或相似名稱的舊卡片。
- 修改后是否保存成功。
- Codex 是否在切換前已經啟動并緩存了舊值。
第三步：逐項核對四個核心字段
遇到 401、404 或 model not found 時，先把配置字段拆開核對。不要同時修改地址、Key 和模型，否則即使恢復正常，也無法知道原始原因。
尤其注意 *ase **L 重復版本路徑的情況。客戶端會自動拼接固定路徑時，手動再填一次可能導致 404。
- *ase **L：確認協議、域名、版本路徑和末尾斜杠。
- Model ID：確認大小寫、連字符和版本后綴。
- API Key：確認沒有復制空格、換行或截斷。
- 兼容設置：確認客戶端沒有額外覆蓋請求頭或路徑。
?? 遇到超時：先區分連接超時和響應超時
‘超時’不是一個足夠具體的錯誤。連接超時通常發生在請求還沒有建立時，可能與網絡、**或域名解析有關；響應超時則可能是服務處理時間較長、客戶端等待時間過短或請求內容過大。
Resolve-DnsName example.com
****-NetConnection example.com -Port 443
Get-Date
如果網頁入口正常而本地請求超時，優先檢查本機網絡、**和客戶端進程；如果多個客戶端同時超時，再考慮服務側狀態。
- 先用短提示詞做最小請求，排除上下文過大的影響。
- 確認系統**與客戶端**沒有重復設置。
- 不要用連續重試掩蓋服務端限流，記錄每次間隔和返回碼。
401 與 403：鑒權問題的最短排查路徑
401 通常代表令牌沒有被接受，403 則更常見于權限、額度或模型分組限制。兩者都不要通過公開粘貼完整 Key 的方式排查。
如果令牌已經暴露在日志、截圖或聊天記錄中，應優先撤銷并重新生成，不要繼續使用舊值。
- 確認當前啟用的配置卡，而不是只看編輯頁面。
- 重新復制令牌到本地安全字段，檢查前后空格。
- 換一個明確有權限的模型做最小請求。
- 檢查額度、有效期、項目分組和并發限制。
404 與模型不存在：看請求最終落到哪里
404 可能是地址拼接錯誤，也可能是模型標識在當前線路中不存在。把完整請求地址拆成 *ase **L、固定路徑和模型字段三部分，分別核對，不要只看界面上縮短后的地址。
*ase **L 客戶端固定路徑 = 最終接口路徑
Model ID = 當前線路允許使用的精確標識修復后先在空目錄測試，再回到真實項目。這樣可以把接口問題和項目代碼問題分開。
- 刪除重復的 /v1、/api 或版本路徑后重新測試。
- 從當前模型列表復制精確 Model ID。
- 確認項目環境變量沒有覆蓋 CC Switch 的模型值。
第六步：用最小請求做回歸驗證
完成修改后，不要馬上開始大范圍代碼變更。先關閉舊終端，啟用目標卡片，在空目錄發起一個只讀、短上下文的請求，確認線路、模型和權限都已經生效。
New-Item -ItemType Directory codex-relay-check
Set-Location codex-relay-check
codex回歸驗證至少記錄三項：使用的配置卡、測試時間、返回結果。之后再進入項目目錄，讓 Codex 先讀取一個文件并給出摘要，避免一上來執行寫入操作。
常見現象與對應動作
排障記錄中保留錯誤碼和脫敏后的地址即可，不要記錄完整 API Key、Cookie 或項目敏感代碼。
- 切換后仍返回舊模型：關閉舊進程并檢查環境變量覆蓋。
- 偶發超時：縮小請求、延長合理等待時間并觀察是否集中發生。
- 只有某個項目失敗：比較工作目錄、項目變量和啟動腳本。
- 網頁能打開但 Codex 失敗：檢查 API 路徑、請求頭和模型權限。
- 修改后錯誤更多：回滾到上一張已知可用配置卡，重新單變量驗證。
? 一份可復用的排查清單
把故障從‘憑感覺重試’變成‘按層取證’，才能讓 Codex 中轉線路在不同項目里保持穩定，也能讓問題更快交給正確的處理環節。
- 確認服務入口、模型列表和線路狀態。
- 確認 CC Switch 目標卡片已保存并啟用。
- 核對 *ase **L、固定路徑、Model ID 和 API Key。
- 區分網絡超時、接口錯誤和鑒權錯誤。
- 檢查項目環境變量是否覆蓋客戶端配置。
- 用空目錄最小請求做回歸驗證。
- 記錄配置卡、時間、錯誤碼和修復動作。