先理解什么叫接口兼容

API 兼容不是‘地址能打開’這么簡單。客戶端需要按照約定的路徑、請求方法、請求體和響應格式工作。即使同一個模型名稱在不同服務里都存在，只要協議或字段不匹配，Codex 仍然可能返回 404、400、解析失敗或空響應。

排查時要把這四層拆開，不要只盯著 API Key。

• 地址兼容：*ase **L 和固定路徑能夠正確拼接。
• 協議兼容：客戶端和上游使用相同的請求形態。
• 模型兼容：Model ID 在當前線路中真實存在。
• 響應兼容：返回字段能被 Codex 正確解析。

第一步：確認靈能API當前接口能力

打開靈能API服務入口，確認當前接口說明、模型列表和推薦接入方式。重點查看 *ase **L、支持的請求協議、模型標識和令牌權限。不要把其他服務的路徑直接拼到當前地址后面。

靈能API入口：https://www.lnsns.com/。所有協議判斷以當前服務說明為準。

• *ase **L：只使用當前說明中的基礎地址。
• Model ID：從當前模型列表復制。
• 協議：確認是否支持 Codex 所需請求形態。
• 權限：確認令牌可以訪問目標模型。

Responses API 和 Chat Completions 有什么區別

可以把兩種協議理解為不同的請求和響應約定。Codex 當前配置可能要求使用 Responses API 形態，而某些上游或舊兼容服務只提供 Chat Completions。兩者不能只靠把地址改一下就自動互換。

先確認上游能力，再決定是調整客戶端字段還是引入**。不要把協議字段當作普通模型參數反復嘗試。

• Responses API：使用新的請求結構和響應事件約定。
• Chat Completions：使用另一套消息、補全和響應字段。
• 直接兼容：客戶端和上游支持同一種協議。
• **轉換：由中間層把一種協議轉換成另一種。

第三步：創建一個可追蹤的令牌

協議排查需要多次測試，建議使用用途明確的專用令牌。名稱寫明 Codex、環境和測試目的，方便在服務端查看調用記錄；完整 Key 仍然只放在受控位置。

不要因為協議錯誤就連續生成大量 Key。先保留錯誤碼和請求時間，逐項修改配置。

• 測試令牌與日常開發令牌分開。
• 權限只覆蓋需要驗證的模型。
• 發現泄露時先撤銷再繼續排查。

? **步：在 CC Switch 中固定基礎字段

打開 CC Switch 的 Codex 頁面，新建一張協議測試卡。先只填寫供應商名稱、API Key、*ase **L 和 Model ID，其他字段保持默認。這樣第一輪測試的變量最少。

配置卡保存后先獲取模型列表。列表都無法返回時，不要繼續分析響應協議。

• 供應商名稱：寫清靈能API和協議測試用途。
• API Key：使用專用測試令牌。
• *ase **L：不要追加未經確認的固定路徑。
• Model ID：使用當前列表中的精確名稱。

第五步：用錯誤碼判斷問題位置

錯誤碼可以幫助你縮小范圍，但不能脫離請求鏈路解讀。先記錄當前卡片、模型和時間，再按以下順序判斷。

• 401：請求到達了鑒權層，但令牌沒有被接受。
• 403：令牌存在，但權限、額度或分組不滿足。
• 404：地址路徑或模型標識不正確。
• 400：請求字段、協議或參數結構可能不匹配。
• 解析錯誤：響應格式與客戶端預期不一致。

第六步：確認 *ase **L 不重復拼接

許多客戶端會自動在 *ase **L 后面拼接固定路徑。如果你把完整的 `/v1/responses` 也填入 *ase **L，最終請求就可能變成重復路徑。配置時要區分‘基礎地址’和‘客戶端內部路徑’。

正確思路：*ase **L   客戶端固定路徑
需要確認：最終請求是否只出現一次版本路徑
不要做：把完整接口路徑重復填入 *ase **L

如果出現 404，先記錄最終請求路徑；不要同時修改模型和 API Key。路徑修復后再觀察錯誤是否變化。

第七步：上游不兼容時再考慮**

如果靈能API當前線路已經支持 Codex 所需協議，直接連接更簡單。只有在你必須使用一個只支持另一種協議的上游，或者需要統一多家供應商時，才增加**做轉換。

**會增加端口、鑒權、網絡和日志等故障點。部署前先確認必要性，并限制管理入口訪問范圍。

• Codex 指向**入口。
• **保存上游地址和令牌。
• **負責協議轉換或模型映射。
• 日志中同時記錄入口請求和上游結果。

第八步：用最小請求驗證響應格式

協議驗證不能直接用大型代碼任務。先在空目錄發送一個短請求，確認模型返回內容、結束狀態和錯誤處理都正常。隨后再發送一個短只讀任務，觀察客戶端是否能持續完成對話。

New-Item -ItemType Directory codex-protocol-check
Set-Location codex-protocol-check
codex

只要小請求仍然出現解析錯誤，就不要進入真實項目；先回到協議和響應格式排查。

• 測試一：短文本請求。
• 測試二：只讀目錄確認。
• 測試三：讀取一個無敏感內容的文件。

? 第九步：配置文件中常見的協議字段

如果你采用手動配置，常見字段包括供應商名稱、Model ID、*ase **L、環境變量名和協議類型。字段名稱會隨客戶端版本變化，因此下面只作為檢查思路，不是無條件復制的固定模板。

model = "<MODEL_ID>"
model_provider = "lingneng"

[model_providers.lingneng]
name = "靈能API"
*ase_url = "<*ASE_**L>"
wire_api = "<按當前版本確認>"
env_key = "OPENAI_API_KEY"

修改前備份配置文件，修改后完全退出并重新啟動 Codex，再執行最小測試。

• 供應商引用名必須和配置塊名稱一致。
• 協議字段以客戶端版本文檔為準。
• 令牌通過環境變量或安全存儲注入。

協議兼容性排查清單

修復時一次只調整協議、地址、模型或令牌中的一個變量，并記錄每次測試結果。

• 服務端是否支持當前客戶端需要的協議。
• *ase **L 是否只填寫基礎地址。
• Model ID 是否來自當前模型列表。
• API Key 是否具備目標模型權限。
• CC Switch 是否真正啟用了目標卡片。
• 舊 Codex 進程是否已經退出。
• **是否做了正確的協議和模型映射。

? 最后給新手的建議

靈能API接入 Codex 時，真正重要的是讓地址、協議、模型和響應格式形成一條完整鏈路。把這些邊界確認清楚，很多看似復雜的報錯都能快速定位。

• 優先使用已經兼容 Codex 的直連線路。
• 先用 CC Switch 跑通，再研究手動配置。
• 協議不兼容時再增加**。
• 始終保留一張穩定卡片作為回滾點。
• 先做空目錄小請求，再進入真實項目。
• 不把完整令牌寫入配置示例、日志和截圖。