先判斷：這是模型問題，還是網(wǎng)絡(luò)鏈路問題

Codex 調(diào)用失敗時(shí)，很多人第一反應(yīng)是“模型不穩(wěn)定”。但在 API中轉(zhuǎn)站接入場(chǎng)景里，失敗鏈路更長(zhǎng)：本機(jī)終端、環(huán)境變量、CC Switch 配置卡、**軟件、DNS、網(wǎng)絡(luò)出口、中轉(zhuǎn)站入口、模型權(quán)限，每一層都可能出問題。只看最后一行報(bào)錯(cuò)，很容易誤判。

更穩(wěn)的排查方式是先把鏈路拆開。能打開靈能API控制臺(tái)，不代表終端里的請(qǐng)求能走同一條網(wǎng)絡(luò)；瀏覽器能訪問官網(wǎng)，也不代表命令行進(jìn)程繼承了**設(shè)置；短任務(wù)能跑通，也不代表長(zhǎng)上下文任務(wù)不會(huì)超時(shí)。把這些差異講清楚，排查速度會(huì)快很多。

• 瀏覽器可訪問，只能說明網(wǎng)頁鏈路可用，不能代表 Codex 進(jìn)程可用。
• 短任務(wù)成功，只能說明基礎(chǔ)連接可用，不能代表長(zhǎng)任務(wù)一定穩(wěn)定。
• 錯(cuò)誤碼、超時(shí)時(shí)間和配置卡名稱要一起看，不能孤立判斷。

第一步：確認(rèn)統(tǒng)一入口和當(dāng)前賬號(hào)

先通過 https://www.lnsns.com/ 進(jìn)入靈能API，確認(rèn)當(dāng)前賬號(hào)、控制臺(tái)入口、接口地址、模型列表和賬戶狀態(tài)。這個(gè)動(dòng)作看似基礎(chǔ)，但很多網(wǎng)絡(luò)問題其實(shí)從這里就能排除：賬號(hào)是否登錯(cuò)、模型是否可用、余額是否正常、接口說明是否更新。

不要拿舊文章、舊截圖或別人電腦里的字段作為唯一依據(jù)。團(tuán)隊(duì)協(xié)作時(shí)，最穩(wěn)的是每次排查都回到靈能API當(dāng)前控制臺(tái)核對(duì)一次。只要入口、賬號(hào)和權(quán)限確認(rèn)無誤，再繼續(xù)看本機(jī)環(huán)境和**鏈路。

• 確認(rèn)賬號(hào)：右上角賬號(hào)或個(gè)人中心是否是當(dāng)前項(xiàng)目使用的賬號(hào)。
• 確認(rèn)入口：*ase **L 是否來自當(dāng)前控制臺(tái)說明。
• 確認(rèn)狀態(tài)：余額、模型權(quán)限和接口說明是否正常。

第二步：把 *ase **L 和模型 ID 分開排查

*ase **L 錯(cuò)誤和模型 ID 錯(cuò)誤的表現(xiàn)很像，都可能讓 Codex 無**常返回。但它們的排查方向不同：*ase **L 關(guān)注入口和路徑，模型 ID 關(guān)注賬號(hào)權(quán)限和可用模型。不要同時(shí)修改兩者，否則你很難知道到底是哪一項(xiàng)修好了問題。

如果你剛剛從舊配置遷移到靈能API，建議先只替換 *ase **L 和 API Key，模型 ID 暫時(shí)保持文檔推薦值；等短任務(wù)通過后，再做模型切換測(cè)試。這樣可以把變量數(shù)量壓到最低，問題也更容易定位。

排查順序建議：
1. 只核對(duì) *ase **L，不改模型
2. 只核對(duì) API Key，不改其他字段
3. 跑空目錄短任務(wù)
4. 再切換目標(biāo)模型
5. 記錄每次修改前后的錯(cuò)誤變化

• 404 多數(shù)優(yōu)先看 *ase **L、路徑層級(jí)和模型 ID。
• 403 多數(shù)優(yōu)先看賬號(hào)權(quán)限、余額和模型授權(quán)。
• 不要一次同時(shí)改地址、模型、Key 和**設(shè)置。

第三步：在 CC Switch 里保留“網(wǎng)絡(luò)診斷卡”

日常開發(fā)配置卡和網(wǎng)絡(luò)診斷配置卡最好分開。日常卡用于真實(shí)項(xiàng)目，診斷卡用于空目錄短任務(wù)、連接測(cè)試和錯(cuò)誤復(fù)現(xiàn)。這樣做有兩個(gè)好處：一是排查時(shí)不會(huì)誤改主配置，二是每次網(wǎng)絡(luò)異常都能用同一張卡做對(duì)照。

診斷卡名稱建議寫清楚用途，例如“靈能API-Codex-Network-Check”。備注里寫上 *ase **L 來源、模型 ID、最近驗(yàn)證日期和適用場(chǎng)景。不要在備注里寫完整 Key，密鑰仍然放在安全位置。

• 診斷卡只用于排查，不作為長(zhǎng)期開發(fā)默認(rèn)卡。
• 每次排查先復(fù)制診斷卡，再單項(xiàng)修改。
• 診斷卡驗(yàn)證通過后，再回到日常卡同步必要字段。

? **步：檢查終端是否繼承了**設(shè)置

瀏覽器能打開網(wǎng)頁，不代表 PowerShell、Windows Terminal 或腳本進(jìn)程也能使用同一套**。很多桌面**默認(rèn)只接管瀏覽器，命令行程序需要額外設(shè)置 ****_PROXY、****S_PROXY 或系統(tǒng)**。Codex 是從終端里發(fā)起請(qǐng)求的，所以要看終端環(huán)境，而不是只看瀏覽器。

如果你使用**軟件，先確認(rèn)它是否提供本地端口，再確認(rèn)終端變量是否正確。不要把**變量和 API中轉(zhuǎn)站地址混在一起：**變量指向本機(jī)****，*ase **L 指向靈能API接口入口，它們不是同一個(gè)東西。

$env:****_PROXY
$env:****S_PROXY
$env:NO_PROXY

# 示例：只用于說明變量位置，端口請(qǐng)按自己的**工具填寫
$env:****S_PROXY = "http://127.0.0.1:7890"

• 瀏覽器可用但終端不可用，優(yōu)先檢查終端**變量。
• **端口要以本機(jī)實(shí)際工具顯示為準(zhǔn)，不要照抄別人的端口。
• 修改**變量后，最好重啟終端再測(cè)試。

第五步：用最短請(qǐng)求測(cè)試連通性

網(wǎng)絡(luò)排查時(shí)，不要一上來就讓 Codex 分析整個(gè)項(xiàng)目。長(zhǎng)任務(wù)失敗可能是上下文太大、模型響應(yīng)慢、網(wǎng)絡(luò)抖動(dòng)或配置錯(cuò)誤，很難判斷。最短請(qǐng)求的目標(biāo)只有一個(gè)：確認(rèn)當(dāng)前鏈路能否完成一次基礎(chǔ)調(diào)用。

mkdir codex-network-check
cd codex-network-check
codex "請(qǐng)只回復(fù)：連接測(cè)試通過。不要?jiǎng)?chuàng)建、修改或刪除文件。"

如果短請(qǐng)求能穩(wěn)定通過，再逐步增加任務(wù)復(fù)雜度：先問三句話，再讀取 README，再讀取少量日志片段。每次只增加一個(gè)變量。這樣你能判斷問題到底出現(xiàn)在基礎(chǔ)連接、讀取文件、上下文長(zhǎng)度還是模型響應(yīng)時(shí)間上。

• 先測(cè)一句話，不要先測(cè)長(zhǎng)文檔。
• 每次只增加一個(gè)輸入范圍，方便定位。
• 短請(qǐng)求失敗時(shí)，不要繼續(xù)嘗試真實(shí)項(xiàng)目任務(wù)。

?? 第六步：區(qū)分連接超時(shí)和模型響應(yīng)慢

timeout 不是一個(gè)單一問題。它可能表示請(qǐng)求根本沒連到入口，也可能表示入口連通但模型響應(yīng)太慢，還可能表示任務(wù)輸入太大導(dǎo)致等待時(shí)間變長(zhǎng)。排查時(shí)要記錄超時(shí)發(fā)生在哪個(gè)階段：?jiǎn)?dòng)即失敗、等待一段時(shí)間失敗、輸出到一半中斷，三者含義不同。

啟動(dòng)即失敗通常看**、DNS、*ase **L；等待很久才失敗通常看模型響應(yīng)、任務(wù)長(zhǎng)度、網(wǎng)絡(luò)穩(wěn)定性；輸出到一半中斷則可能和長(zhǎng)連接、終端環(huán)境或中間網(wǎng)絡(luò)波動(dòng)有關(guān)。靈能API入口確認(rèn)正常后，就要回到本機(jī)和任務(wù)規(guī)模上做拆分。

啟動(dòng)即失敗：檢查**、DNS、*ase **L、Key 是否缺失
等待后失敗：檢查任務(wù)長(zhǎng)度、模型響應(yīng)時(shí)間、網(wǎng)絡(luò)波動(dòng)
輸出中斷：檢查終端穩(wěn)定性、連接保持、是否有網(wǎng)絡(luò)切換
偶發(fā)失敗：記錄時(shí)間段、任務(wù)類型、當(dāng)前配置卡

• 不要把所有 timeout 都當(dāng)成同一種錯(cuò)誤。
• 長(zhǎng)任務(wù)先縮小輸入范圍，再判斷是否需要換模型。
• 偶發(fā)問題要記錄時(shí)間和配置卡，否則很難復(fù)現(xiàn)。

第七步：準(zhǔn)備一張備用線路卡

備用線路不是為了讓團(tuán)隊(duì)隨意切換，而是為了在主配置異常時(shí)快速恢復(fù)。建議在 CC Switch 里保留一張“靈能API-Codex-*ackup”卡，字段來自同一套接入說明，但模型、Key 或策略可以和主卡區(qū)分。備用卡必須提前驗(yàn)證，不要等主卡出問題時(shí)才臨時(shí)創(chuàng)建。

啟用備用卡時(shí)要寫清原因。比如主卡連續(xù)三次超時(shí)、某個(gè)模型臨時(shí)不可用、CI 檢查失敗但本地任務(wù)需要繼續(xù)。備用卡啟用后不要長(zhǎng)期忘記切回，否則用量歸因和錯(cuò)誤定位都會(huì)變復(fù)雜。

備用卡啟用條件：
- 主卡連續(xù)失敗 3 次
- 錯(cuò)誤不是本地缺少變量
- 短任務(wù)在備用卡上驗(yàn)證通過

備用卡恢復(fù)條件：
- 主卡短任務(wù)恢復(fù)正常
- 已記錄異常時(shí)間和處理人
- 團(tuán)隊(duì)通知切回主卡

• 備用卡要提前驗(yàn)證。
• 啟用備用卡要記錄開始時(shí)間和原因。
• 主卡恢復(fù)后要及時(shí)切回。

第八步：結(jié)合額度頁面判斷異常用量

網(wǎng)絡(luò)問題有時(shí)會(huì)變成成本問題。比如某個(gè)自動(dòng)化腳本失敗后不斷重試，或者某個(gè)成員以為請(qǐng)求沒發(fā)出去，于是重復(fù)運(yùn)行長(zhǎng)任務(wù)。排查連接穩(wěn)定性時(shí)，也要順手看用量變化。靈能API的賬戶狀態(tài)和模型信息可以作為輔助判斷，幫助你發(fā)現(xiàn)是不是有異常重試。

如果短時(shí)間內(nèi)用量增長(zhǎng)異常，先暫停自動(dòng)化任務(wù)，再檢查最近是否有人切換了備用卡、是否有腳本循環(huán)重試、是否有長(zhǎng)任務(wù)被頻繁觸發(fā)。不要只從模型價(jià)格上找原因，很多異常消耗來自任務(wù)觸發(fā)方式。

• 失敗重試要有限制，不要無限循環(huán)。
• 長(zhǎng)任務(wù)失敗后不要盲目重復(fù)運(yùn)行。
• 異常用量要同時(shí)看任務(wù)、模型和觸發(fā)頻率。

第九步：記錄一份網(wǎng)絡(luò)診斷模板

如果團(tuán)隊(duì)經(jīng)常遇到連接問題，建議保留一份固定診斷模板。模板不需要復(fù)雜，但要包含時(shí)間、使用者、配置卡、任務(wù)類型、錯(cuò)誤碼、是否使用**、是否切換網(wǎng)絡(luò)、是否使用備用卡。這樣后續(xù)復(fù)盤才有材料。

診斷記錄里不要寫完整 API Key，也不要貼完整請(qǐng)求頭。如果需要定位某枚 Key，可以只寫 Key 名稱或末尾幾位。真正敏感的信息仍然放在靈能API控制臺(tái)和安全保存位置里。

時(shí)間：2026-09-03 14:30
使用者：項(xiàng)目成員 A
配置卡：靈能API-Codex-Network-Check
任務(wù)類型：空目錄短任務(wù)
錯(cuò)誤表現(xiàn)：等待 60 秒后 timeout
**狀態(tài)：終端已設(shè)置 ****S_PROXY
處理動(dòng)作：切換備用卡驗(yàn)證，通過后記錄并通知***

• 記錄現(xiàn)象，不記錄完整密鑰。
• 記錄配置卡名稱，方便復(fù)現(xiàn)。
• 記錄處理動(dòng)作，避免下次從零開始排查。

第十步：把排查順序?qū)戇M(jìn)團(tuán)隊(duì)手冊(cè)

網(wǎng)絡(luò)問題最怕每個(gè)人用不同順序排查。有人先改 Key，有人先換模型，有人先開**，有人直接刪配置，最后問題更難復(fù)現(xiàn)。建議把排查順序固定下來：先確認(rèn)入口，再看配置卡，再測(cè)終端**，再跑短任務(wù)，再判斷是否需要備用卡。

這份手冊(cè)可以寫得很短，但要足夠明確。通過 https://www.lnsns.com/ 進(jìn)入靈能API核對(duì)接入信息，是排查的起點(diǎn)；通過 CC Switch 選擇診斷卡，是本地復(fù)現(xiàn)的起點(diǎn)；通過空目錄短任務(wù)驗(yàn)證，是判斷鏈路可用性的起點(diǎn)。

• 第一步：確認(rèn)靈能API入口、賬號(hào)、模型和余額。
• 第二步：確認(rèn) CC Switch 當(dāng)前配置卡。
• 第三步：確認(rèn)終端**變量和網(wǎng)絡(luò)出口。
• **步：運(yùn)行空目錄短任務(wù)。
• 第五步：必要時(shí)啟用備用卡，并記錄原因。

? 收尾：穩(wěn)定連接靠流程，不靠運(yùn)氣

Codex 接入 API中轉(zhuǎn)站后，穩(wěn)定性不是靠多試幾次碰運(yùn)氣，而是靠清晰的鏈路拆分。靈能API負(fù)責(zé)統(tǒng)一入口和賬號(hào)側(cè)接入，CC Switch負(fù)責(zé)本地配置卡和線路切換，團(tuán)隊(duì)手冊(cè)負(fù)責(zé)規(guī)定排查順序、**設(shè)置、備用卡啟用條件和日志記錄方式。

如果你正在處理偶發(fā)超時(shí)或連接失敗，可以先從最小閉環(huán)做起：確認(rèn)入口，核對(duì) *ase **L，檢查終端**，使用診斷卡跑空目錄短任務(wù)，再逐步擴(kuò)大到真實(shí)項(xiàng)目。這樣每一步都有證據(jù)，問題自然會(huì)從“玄學(xué)不通”變成可以被定位、復(fù)現(xiàn)和修復(fù)的工程問題。