先把問題說清楚：不是“連不上”，而是哪一層沒通

使用 Codex 接入 API 中轉(zhuǎn)站時，錯誤可能來自本地命令、CC Switch 配置、靈能API賬號狀態(tài)、模型權(quán)限、****、請求格式或任務(wù)本身。只說“連不上”沒有排查價值，因?yàn)槊恳粚拥奶幚矸绞蕉疾煌Ｒ粋€可用的診斷報告，應(yīng)該能讓別人不看你電腦也知道當(dāng)前卡在哪一步。

本文不鼓勵把完整控制臺截圖、完整請求頭或完整日志一股腦發(fā)出去。更穩(wěn)妥的做法是只采樣必要字段：錯誤碼、發(fā)生時間、使用的配置卡名稱、*ase **L 層級、模型 ID、任務(wù)類型和脫敏后的報錯片段。靈能API相關(guān)信息可以通過官網(wǎng)入口復(fù)核，但密鑰本身不應(yīng)該出現(xiàn)在排查材料里。

• 本地層：Codex 是否能啟動，終端是否讀到最新配置。
• 配置層：CC Switch 當(dāng)前啟用的卡片是否正確。
• 賬號層：靈能API賬號、余額、Key 和模型權(quán)限是否正常。
• 請求層：*ase **L、模型 ID、**和任務(wù)長度是否合理。

一份合格診斷報告應(yīng)該包含什么

好的排查材料不是越多越好，而是剛好足夠復(fù)現(xiàn)問題。你可以把它理解成“最小可復(fù)現(xiàn)上下文”：別人能根據(jù)這些信息判斷是賬號問題、地址問題、模型問題還是網(wǎng)絡(luò)問題，但看不到你的 Key、用戶數(shù)據(jù)、生產(chǎn)庫地址和隱私日志。

問題標(biāo)題：Codex 通過 CC Switch 接入靈能API時返回 401
發(fā)生時間：2026-08-31 14:20
配置卡名稱：靈能API-Codex-日常開發(fā)
*ase **L 層級：https://www.lnsns.com/v1
模型 ID：以控制臺當(dāng)前復(fù)制值為準(zhǔn)
錯誤碼：401
脫敏報錯：Authentication failed / invalid API key
已做動作：重啟終端、重新啟用配置卡、空目錄短任務(wù)測試
未包含內(nèi)容：完整 API Key、完整請求頭、生產(chǎn)日志原文

這類報告的重點(diǎn)是結(jié)構(gòu)，而不是截圖堆疊。靈能API和 CC Switch 的頁面截圖可以作為位置說明，但真正排查時要靠字段和現(xiàn)象對應(yīng)。尤其是 401、403、404 這種錯誤，看到錯誤碼往往比看到一大張截圖更有用。

• 必須有：錯誤碼、配置卡名稱、*ase **L 層級、模型 ID、復(fù)現(xiàn)步驟。
• 最好有：發(fā)生時間、終端環(huán)境、是否剛輪換 Key、是否剛切模型。
• 不要有：完整 Key、真實(shí)用戶數(shù)據(jù)、生產(chǎn)連接串、未脫敏日志。

第一步：從靈能API入口確認(rèn)賬號上下文

先通過靈能API官網(wǎng)進(jìn)入控制臺：https://www.lnsns.com/。排錯時不要直接翻舊截圖，因?yàn)橘~號狀態(tài)、余額、模型權(quán)限和頁面入口都可能變化。你需要確認(rèn)當(dāng)前瀏覽器登錄的是哪個賬號、這個賬號是否就是 CC Switch 配置里 Key 的來源，以及當(dāng)前賬號是否還有可用額度。

如果團(tuán)隊(duì)里有多人共用文章或教程，建議統(tǒng)一寫靈能API官網(wǎng)入口，但不要把個人控制臺里的 Key、余額截圖或訂單信息寫進(jìn)公開材料。排查時只需要說明“已確認(rèn)賬號可登錄、余額正常、模型在列表中可見”，不需要展示完整賬戶細(xì)節(jié)。

• 確認(rèn)當(dāng)前賬號是不是生成 Key 的賬號。
• 確認(rèn)靈能API控制臺能打開，而不是只確認(rèn)官網(wǎng)首頁能打開。
• 確認(rèn)排查時使用的新舊 Key 是否來自同一個賬號體系。

第二步：判斷錯誤發(fā)生在啟動前還是請求后

有些問題并沒有真正發(fā)出請求。例如 codex 命令不存在、npm 全局路徑?jīng)]加載、舊終端沒有刷新配置，這些都屬于啟動前問題。還有一些問題發(fā)生在請求后，例如 401、403、404、timeout、model not found，這些才需要回到靈能API和 CC Switch 的接口字段里排查。

codex --version
where.exe codex
node -v
npm -v

如果這些命令都不能正常返回，先處理本地環(huán)境，不要急著改靈能API的 Key。反過來，如果 Codex 能啟動，并且進(jìn)入會話后才報接口錯誤，就應(yīng)該進(jìn)入 CC Switch 配置卡和靈能API控制臺核對參數(shù)。把這兩類問題分開，會少走很多彎路。

• 啟動前失敗：看安裝、PATH、終端重啟和本地權(quán)限。
• 請求后失敗：看 Key、*ase **L、模型 ID、余額、**和接口狀態(tài)。
• 無法判斷時：先做空目錄短任務(wù)，把項(xiàng)目因素排除掉。

第三步：截取 CC Switch 配置時只截必要區(qū)域

CC Switch 截圖很有用，但截圖也容易泄露。建議只截配置卡名稱、當(dāng)前啟用狀態(tài)、*ase **L 層級和模型字段；API Key 區(qū)域必須遮擋。如果工具界面不能單獨(dú)隱藏 Key，就不要截圖該區(qū)域，改用文字描述“Key 已重新粘貼，首尾無空格”。

為了讓排查更高效，配置卡名稱要能說明用途。例如“靈能API-Codex-日常開發(fā)”“靈能API-Codex-輪換驗(yàn)證”“靈能API-Codex-只讀排查”。看到名稱就能知道這張卡用于哪個場景，而不是一排 test、new、*ackup 讓人猜。

• 可展示：卡片名稱、啟用狀態(tài)、非敏感字段位置。
• 需遮擋：API Key、賬號郵箱、訂單編號、完整請求頭。
• 建議補(bǔ)充：是否剛剛切換過卡片，切換后是否重啟終端。

? **步：逐項(xiàng)核對 *ase **L 與模型 ID

很多 404 和 model not found 都不是服務(wù)不可用，而是字段填錯。*ase **L 常見錯誤是重復(fù) /v1、少寫 /v1、把完整接口路徑填到基礎(chǔ)地址里；模型 ID 常見錯誤是復(fù)制了展示名稱、漏掉版本后綴、大小寫不一致或使用了當(dāng)前賬號無權(quán)限的模型。

*ase **L 正確思路：以靈能API控制臺說明為準(zhǔn)，通常到 /v1 層級
不要寫成：https://www.lnsns.com/v1/v1
不要寫成：完整 chat/completions 路徑，除非工具明確要求
模型 ID：復(fù)制接口字段，不復(fù)制頁面展示標(biāo)題

排查時一次只改一個字段。先只改 *ase **L，保存、啟用、重啟終端、短任務(wù)測試；再只改模型 ID，同樣測試。一次改三個字段看起來快，失敗后反而不知道是哪一項(xiàng)導(dǎo)致。

• 404：優(yōu)先看地址層級和模型路徑。
• model not found：優(yōu)先從靈能API當(dāng)前模型列表重新復(fù)制 ID。
• 403：不要只改模型名，還要看賬號是否有權(quán)限。

第五步：用空目錄短任務(wù)采樣請求結(jié)果

真實(shí)項(xiàng)目里可能存在環(huán)境變量、**腳本、權(quán)限限制、依賴安裝殘留和歷史配置，排查時很容易**擾。更干凈的做法是新建空目錄，只跑一條短提示，把任務(wù)復(fù)雜度降到最低。

mkdir codex-diagnostic-check
cd codex-diagnostic-check
codex

請只回復(fù)一句話：當(dāng)前連接測試已收到。
不要創(chuàng)建文件，不要修改文件，不要讀取上級目錄。

如果短任務(wù)成功，而真實(shí)項(xiàng)目失敗，說明靈能API和 CC Switch 線路大概率可用，問題可能在項(xiàng)目環(huán)境、提示詞長度或本地權(quán)限。如果短任務(wù)也失敗，就回到 Key、*ase **L、模型 ID 和****上繼續(xù)排查。

• 短任務(wù)成功：進(jìn)入項(xiàng)目因素排查。
• 短任務(wù)失敗：進(jìn)入接口字段排查。
• 短任務(wù)超時：縮短提示詞后再試，排除長上下文影響。

第六步：按錯誤碼拆解處理路徑

錯誤碼就是排查路線圖。看到錯誤碼以后不要先憑感覺重裝，也不要連續(xù)新建多個 Key。先把現(xiàn)象歸類，再決定下一步。靈能API接入 Codex 的常見問題，基本可以按下面幾類處理。

診斷報告里不要寫“已經(jīng)全部檢查過”。要寫清楚檢查了哪一項(xiàng)、怎么檢查、結(jié)果是什么。例如“已從靈能API控制臺重新復(fù)制模型 ID，仍返回 model not found”，這比“模型沒問題”更可信。

• 401：Key 不正確、復(fù)制不完整、Key 被撤銷、當(dāng)前配置卡仍在使用舊 Key。
• 403：賬號權(quán)限不足、余額不足、模型未開通、訪問策略不允許。
• 404：*ase **L 層級錯誤、接口路徑重復(fù)、模型 ID 不存在。
• timeout：****、DNS、請求過長、服務(wù)端響應(yīng)慢或本地安全軟件攔截。
• model not found：模型 ID 不是接口實(shí)際接受的 ID，或當(dāng)前賬號沒有該模型權(quán)限。

第七步：疑似 Key 泄露時不要繼續(xù)調(diào)試舊 Key

如果完整 Key 出現(xiàn)在截圖、文檔、聊天窗口、工單、日志、倉庫提交或視頻錄屏里，不要再花時間判斷有沒有人看見。最務(wù)實(shí)的處理是：立即停用舊 Key，創(chuàng)建新 Key，在 CC Switch 里復(fù)制一張新配置卡，只替換 Key，完成短任務(wù)驗(yàn)證。

泄露處理順序：
1. 停用舊 Key
2. 創(chuàng)建新 Key
3. 更新 CC Switch 新配置卡
4. 重啟終端
5. 空目錄短任務(wù)驗(yàn)證
6. 檢查倉庫、文檔、截圖是否仍殘留舊 Key

如果你不確定舊 Key 是否泄露，也建議按泄露處理。Key 輪換的成本通常遠(yuǎn)低于追蹤一次真實(shí)泄露的成本。通過 https://www.lnsns.com/ 進(jìn)入靈能API控制臺處理，比在本地反復(fù)試錯更干凈。

• 只要完整 Key 曾經(jīng)離開安全保存位置，就按泄露處理。
• 舊 Key 停用后再排查新線路，避免舊風(fēng)險繼續(xù)存在。
• 排查記錄中保留事件和時間，不保留密鑰值。

第八步：項(xiàng)目日志如何脫敏后再交給 Codex

很多人排查 timeout 或接口異常時，會把整段生產(chǎn)日志直接貼給 Codex。這很危險，也通常沒有必要。你需要保留的是請求時間、錯誤碼、調(diào)用路徑、模型字段、異常棧結(jié)構(gòu)和少量上下文，而不是用戶手機(jī)號、郵箱、IP、Cookie、數(shù)據(jù)庫連接串和完整 Token。

原始內(nèi)容：Authorization: *earer sk-真實(shí)密鑰
脫敏后：Authorization: *earer sk-***

原始內(nèi)容：postgres://user:password@prod-d*.internal:5432/app
脫敏后：postgres://USER:PASSWORD@HOST:5432/D*

原始內(nèi)容：user_e**il=real@example.com
脫敏后：user_e**il=<EMAIL>

給 Codex 分析時，可以明確說：“以下日志已脫敏，請只分析錯誤結(jié)構(gòu)和可能原因，不要要求我提供真實(shí) Key。”這類提示能讓排查更聚焦，也能減少后續(xù)對敏感信息的追問。

• 保留錯誤碼和棧結(jié)構(gòu)，刪除真實(shí)憑證。
• 保留字段名，替換字段值。
• 保留請求路徑層級，隱藏內(nèi)部域名和真實(shí)用戶數(shù)據(jù)。

? 第九步：讓 Codex 幫你寫排查結(jié)論，而不是替你猜

當(dāng)你把脫敏材料準(zhǔn)備好后，可以讓 Codex 輸出結(jié)構(gòu)化結(jié)論。不要只問“哪里錯了”，而是要求它按概率排序、說明每個判斷依據(jù)、列出下一步只改一項(xiàng)的驗(yàn)證動作。這樣更適合靈能API CC Switch 這類多層鏈路的排查。

請根據(jù)以下脫敏診斷材料，按概率從高到低列出原因：
1. 判斷依據(jù)
2. 下一步驗(yàn)證動作
3. 不要建議我提供完整 API Key
4. 每一步只修改一個變量
5. 如果需要截圖，請說明需要哪個區(qū)域，并提醒遮擋敏感字段

這類提示會讓 Codex 更像一個排查助手，而不是把你帶進(jìn)無休止的猜測。尤其在團(tuán)隊(duì)協(xié)作中，結(jié)構(gòu)化結(jié)論可以直接進(jìn)入工單或內(nèi)部文檔。

• 要求按概率排序，不要只列清單。
• 要求每一步只改一個變量，便于復(fù)現(xiàn)。
• 要求提醒敏感信息遮擋，形成安全習(xí)慣。

第十步：保存一份團(tuán)隊(duì)通用排查模板

當(dāng)你第一次把問題排清楚后，不要讓經(jīng)驗(yàn)只停留在聊天記錄里。把診斷字段整理成模板，放進(jìn)團(tuán)隊(duì)文檔，以后每次有人反饋 Codex API 中轉(zhuǎn)站異常，都按同一套格式收集信息。

【Codex 接入診斷模板】
日期：
操作者：
使用入口：靈能API / https://www.lnsns.com/
CC Switch 配置卡名稱：
當(dāng)前模型 ID：
*ase **L 層級：
錯誤碼：
復(fù)現(xiàn)步驟：
已驗(yàn)證動作：
脫敏日志片段：
是否疑似 Key 泄露：
下一步負(fù)責(zé)人：

模板最大的價值是讓排查變快，也讓溝通變穩(wěn)。你不需要每次從零解釋“怎么截圖、怎么脫敏、怎么說清楚錯誤碼”，新人照著模板填，就能交出可用材料。

• 模板里可以固定寫靈能API官網(wǎng)入口。
• 模板里不要出現(xiàn)任何真實(shí) Key。
• 模板里保留復(fù)現(xiàn)步驟，方便以后回看。

? 收尾：排查效率來自干凈材料

Codex 通過 API 中轉(zhuǎn)站調(diào)用模型，本質(zhì)上是一條由本地工具、配置管理、賬號權(quán)限和模型服務(wù)組成的鏈路。靈能API負(fù)責(zé)提供統(tǒng)一入口，CC Switch負(fù)責(zé)切換本地配置，而一份干凈的診斷報告負(fù)責(zé)把問題定位到具體層級。

遇到問題時，先別急著重裝，也別急著把所有截圖發(fā)出去。先用空目錄短任務(wù)采樣，再按錯誤碼分類，最后用脫敏材料讓 Codex 輔助判斷。這樣既能更快恢復(fù)使用，也能避免在排錯過程中制造新的安全問題。