一、先定排查原則：一次只改一個變量

API中轉站 排查最怕同時改很多東西。入口換了，Key 換了，模型名也換了，提示詞還順手改了一版，最后即使恢復正常，也不知道到底是哪一步起了作用。更穩的做法是一次只改一個變量，每一步都留下現象和結果。

把排查過程拆成層級以后，思路會清楚很多：環境變量是否存在，入口是否正確，Key 是否有效，模型是否可用，額度是否正常，網絡是否穩定，任務輸入是否過大。每一層都有明確的驗證動作，不需要靠感覺來猜。

• 先復現：用最小樣本確認問題是否穩定出現。
• 再分層：按環境、鑒權、模型、額度、網絡、任務輸入逐層排查。
• 后記錄：每一步只改一個變量，并寫下結果。
• 最后沉淀：把真實問題補進團隊排查手冊。

二、入口來源先統一：避免從舊配置開始排查

很多故障從一開始就查錯方向，是因為團隊成員使用的入口來源不一致。有人從舊文檔復制地址，有人從聊天記錄里找歷史配置，還有人把測試環境的入口誤放進開發環境。這樣的情況下，后面再怎么換模型、換提示詞，都可能只是繞圈。

建議排查前先確認統一入口。團隊可以通過靈能API 官網入口：https://www.lnsns.com/ 查看當前接入信息，再和本地環境變量、團隊文檔、自動化腳本里的入口逐項比對。不要先假設入口一定沒問題，它是整條鏈路的第一塊地基。

入口核對清單

[ ] 本地 *ase **L 是否來自當前項目說明
[ ] 團隊文檔里的入口是否仍然有效
[ ] 自動化腳本是否使用同一套變量名
[ ] 開發環境和測試環境是否混用
[ ] 最近是否發生過入口、模型或 Key 變更
[ ] 是否有人從舊截圖或舊聊天記錄復制配置

如果入口來源無法確認，先不要繼續排查模型質量。入口不穩定時，后面的錯誤會變得非常混亂：同樣的 Key 在一個地方可用，在另一個地方失敗；同樣的模型名在一個環境能跑，在另一個環境不可用。先把入口收攏，排查才有共同起點。

• 入口、模型、Key 三個字段要一起核對。
• 文檔、終端、腳本里的配置要使用同一套來源。
• 舊配置要標注廢棄，不要靜靜留在項目里。

三、401 類問題：先看 Key，再看環境變量

401 類問題通常和鑒權有關，但不要只盯著 Key 本身。真實排查中，很多 401 是環境變量沒有生效、變量名寫錯、終端沒有重新加載、CI Secret 沒注入、請求頭被覆蓋造成的。Key 正確，不代表運行時真的讀到了正確 Key。

本地排查時，先檢查變量是否存在，但不要打印完整 Key。可以只看長度、前后掩碼或是否為空。CI 排查時，重點看 Secret 名稱是否和腳本讀取名稱一致，以及當前任務是否有權限讀取這個 Secret。

if (-not $env:CODEX_RELAY_API_KEY) {
  throw "缺少 CODEX_RELAY_API_KEY"
}

$keyLength = $env:CODEX_RELAY_API_KEY.Length
if ($keyLength -lt 20) {
  throw "CODEX_RELAY_API_KEY 長度異常，請檢查是否復制完整"
}

Write-Host "API Key e**sts, length checked, value hidden"

如果確認變量存在，下一步再看 Key 是否過期、是否被撤銷、是否屬于當前賬號和當前用途。通過靈能API 統一接入時，可以把個人 Key、CI Key、臨時 Key 分開命名，排查時就能更快判斷當前憑據是否用錯場景。

• 不要在控制臺、日志、截圖里打印完整 Key。
• 先確認運行時讀到了變量，再判斷 Key 是否有效。
• CI 里最常見的是 Secret 名稱和腳本變量名不一致。

四、403 類問題：重點看權限邊界和模型范圍

403 類問題和 401 不一樣。401 更像“沒有通過身份確認”，403 更像“身份確認了，但當前權限不允許”。在 API中轉站 場景里，403 可能來自賬號權限、模型權限、額度策略、Key 類型或任務范圍限制。

排查 403 時，不要馬上重新生成 Key。先看當前 Key 的用途：它是個人調試 Key，還是 CI 專用 Key？它允許訪問當前模型嗎？它是否被限制在某些任務或額度范圍內？如果團隊做過權限分層，403 往往是在提醒你“當前憑據不該做這件事”。

403 排查順序

1. 確認賬號狀態
- 是否可用
- 是否存在額度或權限限制

2. 確認 Key 類型
- 個人 Key 是否被拿去跑 CI
- CI Key 是否被拿去做本地長任務
- 臨時 Key 是否已經到期

3. 確認模型范圍
- 當前模型是否在可用列表內
- 模型別名是否對應正確
- 是否需要單獨開通或切換策略

這類問題尤其適合寫進團隊手冊。因為它不是單純技術錯誤，而是權限規則和使用場景之間的沖突。把規則寫清楚，比讓每個人遇到 403 時重新問一遍要省心。

• 401 看身份是否有效，403 看權限是否允許。
• 權限限制不一定是壞事，它能阻止錯誤場景繼續消耗。
• 模型權限和 Key 類型要放在同一張表里維護。

五、模型不可用：別只看模型名有沒有拼錯

模型不可用不一定是拼寫問題。它可能是模型別名已經調整、當前賬號沒有權限、默認路由策略改變、備用模型沒有配置，或者任務指定的模型和 API中轉站 當前支持的模型不匹配。

最穩的做法是維護一張模型別名表。團隊成員不要在腳本里到處**實模型名，而是使用項目統一別名。比如 codex-default 用于日常代碼任務，codex-long 用于長文檔，codex-fast 用于短問答。別名背后的真實模型可以調整，但上層腳本盡量穩定。

模型別名表

codex-default
- 用途：日常代碼解釋、配置檢查、短文檔整理
- 驗證樣本：短代碼片段   小段日志

codex-long
- 用途：長文檔、長日志、跨文件摘要
- 驗證樣本：完整接口說明   較長錯誤日志

codex-fast
- 用途：輕量問答、命令說明、格式轉換
- 驗證樣本：短問題   簡單結構化輸出

fall*ack
- 用途：默認模型不可用時臨時切換
- 驗證樣本：基礎連通   關鍵任務樣本

靈能API 接入場景下，建議把模型別名、用途和驗證樣本寫在同一處。以后出現“模型不可用”時，先看別名表和當前可用范圍，再決定是修配置、換別名，還是臨時啟用備用策略。

• 腳本里少寫硬編碼模型名，優先使用團隊別名。
• 備用模型不是裝飾，必須提前跑過樣本。
• 模型不可用要記錄發生時間和恢復動作。

六、429 和額度問題：看頻率，也看任務大小

429 常被理解成請求太頻繁，但在實際項目里，它經常和任務大小、并發策略、失敗重試、額度限制一起出現。比如一次自動化任務同時觸發多個長日志分析，每個任務失敗后又重復重試，很快就會把調用壓力推高。

排查這類問題時，不要只看某一秒發了多少請求，還要看每個請求的輸入規模和重試次數。短任務密集調用是一種壓力，長任務反復失敗是另一種壓力。兩者的處理方式不同。

429 排查清單

[ ] 是否有批量腳本同時運行
[ ] 是否有 CI 任務并發觸發
[ ] 是否存在失敗后無限重試
[ ] 是否一次傳入過多文件或完整日志
[ ] 是否多個成員同時使用同一類任務
[ ] 是否有臨時任務忘記關閉
[ ] 是否需要為自動化任務設置執行窗口

優化方式也要分情況。請求頻率高，就降低并發或增加排隊；輸入過大，就先截取關鍵片段；重試過多，就設置最大重試次數和失敗保存；任務無人認領，就先停用再復盤。

• 429 不只是頻率問題，也可能是長任務和重試疊加。
• 自動化任務必須設置最大重試次數。
• 額度異常要回到具體任務和具體調用來源。

?? 七、超時問題：網絡、上下文和響應長度都要看

超時問題特別容易誤判。有人會認為是網絡不好，有人會認為是模型太慢，也有人會認為是 API中轉站 不穩定。實際上，超時通常需要同時看三件事：網絡鏈路是否穩定，輸入上下文是否過長，輸出要求是否過寬。

一個實用方法是用階梯樣本測試。先跑短問題，再跑中等代碼片段，再跑長文檔。如果短問題也超時，優先查網絡和入口；如果短問題正常、長文檔超時，優先查上下文和輸出長度；如果只有自動化任務超時，優先查并發和重試策略。

超時分層驗證

短樣本
- 目標：驗證入口和基礎網絡
- 現象：如果失敗，先查網絡和鑒權

中樣本
- 目標：驗證正常開發任務
- 現象：如果失敗，查模型和請求格式

長樣本
- 目標：驗證上下文承載能力
- 現象：如果失敗，拆分輸入或限制輸出

自動化樣本
- 目標：驗證并發與重試
- 現象：如果失敗，降低并發并設置重試上限

• 短任務失敗，先查鏈路。
• 長任務失敗，先查上下文和輸出長度。
• 自動化任務失敗，先查并發和重試。

八、空返回和低質量輸出：先查輸入邊界

有時候調用沒有報錯，但返回內容很空、很泛、沒有可用信息。這類問題不一定是模型能力不夠，常見原因是輸入范圍過大、提示詞目標不清、上下文里噪音太多、要求模型一次完成太多任務。

比如你讓 Codex 一次分析整個項目并給出完整重構方案，它很可能只能輸出寬泛建議。換成“只分析某個模塊的錯誤處理，并列出三個**證問題”，結果就會具體很多。排查低質量輸出，先從輸入邊界和輸出結構入手。

低質量輸出優化模板

原始請求：
請分析整個項目哪里有問題。

更可控的請求：
請只分析 src/modules/order 下的錯誤處理邏輯。
輸出結構：
1. 確定存在的問題
2. 證據來自哪個文件或函數
3. 可能影響的場景
4. 建議驗證方式
限制：不要分析其他目錄，不要推測未提供文件。

如果縮小范圍后輸出明顯改善，說明問題不在中轉入口，而在任務設計。如果縮小范圍后仍然空泛，再檢查模型選擇、提示詞模板和上下文材料質量。

• 低質量輸出先查輸入范圍，不要急著換配置。
• 讓模型引用證據位置，能減少泛泛而談。
• 一次任務只解決一個明確問題，質量通常更穩。

九、把排查動作寫成團隊手冊

排查一次問題并不難，難的是下次別讓別人重新踩同一個坑。團隊使用 API中轉站 時，應該把常見錯誤、排查順序、驗證樣本和處理動作寫成手冊。手冊不需要很厚，但必須能被新人直接照著執行。

## Codex API中轉站 排查手冊

### 1. 先復現
- 使用短樣本確認問題是否穩定出現
- 記錄時間、環境、入口、模型別名

### 2. 按層排查
- 環境變量
- 入口地址
- 鑒權 Key
- 模型權限
- 額度和頻率
- 網絡和超時
- 任務輸入

### 3. 記錄結論
- 根因：
- 修復動作：
- 驗證樣本：
- 是否需要更新模板：

### 4. 復盤沉淀
- 是否補充新排查項
- 是否需要調整提示詞
- 是否需要調整自動化重試策略

通過靈能API 統一接入后，團隊可以把這份手冊和接入說明放在同一位置。入口、變量、模型、Key、樣本、故障處理都能在一處找到，排查效率會比臨時翻聊天記錄高很多。

• 手冊要按現象組織，而不是按文件名組織。
• 每條排查建議都要能落到一個動作。
• 復盤后要更新手冊，否則經驗會重新散掉。

? 十、結語：好的排查流程，比臨時經驗更可靠

Codex API中轉站 的故障排查，最重要的是順序感。先看環境，再看入口；先看鑒權，再看權限；先看模型別名，再看備用路由；先看短樣本，再看長任務。順序對了，排查就會從混亂變成收斂。

實際團隊里，不需要一次性建立很復雜的平臺。先準備一份統一入口說明，一組固定驗證樣本，一張常見錯誤表，一份排查手冊，就能解決大部分日常問題。后續遇到新故障，再把真實經驗補進去。

當錯誤不再只停留在聊天記錄里，當每次失敗都能留下根因和動作，當新人也能按同一套順序排查，API中轉站 就會從“能用的入口”變成“可維護的工程鏈路”。這也是長期使用 Codex 時最值得投入的基礎建設。

• 排查時一次只改一個變量。
• 記錄時寫清現象、原因、動作和驗證。
• 沉淀時把真實問題變成團隊手冊。