為什么要把 API 中轉站接入流水線

本地接入成功只說明開發機上的鏈路是通的，不能說明團隊協作環境也穩定。真實項目里，Codex 可能被用于代碼**、提交前解釋、測試失敗分析、接口變更梳理、文檔生成和腳本檢查。如果這些動作只依賴某個同事電腦里的配置，一旦換機器、換賬號、換 Key 或切換模型，排查成本會被放大。

把靈能API和 CC Switch 放進 CI/CD 流水線，并不是讓模型自動修改生產代碼，而是先讓它成為一個可檢查、可追蹤、可回滾的工具入口。流水線只需要完成三類動作：確認環境變量存在，確認中轉站可訪問，確認 Codex 能在只讀約束下完成短任務。這樣團隊在合并代碼前就能發現配置問題，而不是等到真正要用時才臨時救火。

• 本地驗證關注能不能跑通，流水線驗證關注能不能持續跑通。
• 個人配置適合試用，團隊配置必須有變量命名、權限邊界和失敗處理。
• CI 里先做只讀任務，可以降低誤寫文件、誤提**置和泄露密鑰的風險。

流程總覽：從控制臺到自動化任務

這套流程可以拆成五段：第一段進入靈能API控制臺，確認賬號、余額、模型權限和接口說明；第二段在 CC Switch 中保存可復用的中轉站配置；第三段把 CI 所需字段拆成環境變量；**段編寫預檢腳本，先檢查變量和網絡，再做 Codex 短任務；第五段把錯誤碼、日志摘要和處理動作寫成團隊手冊。

建議不要一開始就把 Codex 任務放進主發布流程。更穩妥的做法是新增一條獨立的檢查任務，例如 codex-relay-preflight，讓它只在手動觸發或預合并階段運行。等這條任務連續穩定后，再把它接入更靠前的質量門禁。

• 控制臺負責生成憑證和確認權限。
• CC Switch 負責保存本地和團隊可復用的配置模板。
• CI 負責檢查變量、執行短任務、輸出可讀診斷結果。

第一步：準備 CI 專用憑證，不混用個人 Key

如果流水線要長期使用 Codex，最好為 CI 單獨創建一枚憑證。不要直接拿個人電腦里的 Key 填到自動化平臺里，更不要把 Key 寫進倉庫文件。CI Key 的命名要清楚，例如 codex-ci-readonly-20260903，看到名稱就知道它的用途、環境和創建日期。

通過 https://www.lnsns.com/ 進入靈能API后，可以把 CI Key 與日常開發 Key 分開管理。這樣做的好處是：某個成員離開項目時，不需要連帶影響流水線；流水線用量異常時，也能快速判斷是不是自動化任務造成的；需要暫停自動化調用時，只停 CI Key，不影響個人開發。

• CI Key 只用于自動化檢查，不用于個人聊天、臨時測試或共享給多人。
• CI Key 的權限盡量收斂，先滿足只讀檢查和短任務調用。
• 團隊文檔只記錄 Key 名稱、負責人、用途和輪換日期，不記錄完整密鑰值。

第二步：核對接口文檔和模型權限

自動化任務失敗時，最容易被忽略的是接口層級和模型 ID。開發機里可能已經配置過舊地址，CI 里卻是重新填變量；本地能跑的模型，CI Key 所在賬號不一定有同樣權限。所以在寫腳本之前，先從靈能API控制臺核對 *ase **L、接口兼容方式、可用模型和余額狀態。

這里建議建立一張配置核對表，把“字段名、來源、用途、是否敏感、示例值”寫清楚。比如 *ase **L 屬于非密字段，可以寫進示例文檔；API Key 屬于敏感字段，只能存入 CI 的 Secret 區；模型 ID 不是密鑰，但寫錯會導致任務失敗，也需要固定維護。

字段：CODEX_*ASE_**L
來源：靈能API控制臺接入說明
用途：Codex 請求入口
是否敏感：否

字段：CODEX_API_KEY
來源：靈能API控制臺創建的 CI 專用憑證
用途：自動化任務鑒權
是否敏感：是

字段：CODEX_MODEL
來源：當前賬號可用模型列表
用途：指定流水線檢查模型
是否敏感：否

• *ase **L 寫錯，多數表現為連接失敗、404 或接口路徑不匹配。
• 模型 ID 寫錯，多數表現為模型不存在或權限不足。
• 余額不足或權限不完整，會讓腳本看起來像網絡問題，其實是賬號狀態問題。

第三步：在 CC Switch 里保存團隊配置模板

CC Switch 的價值在于把“能跑通的一組字段”保存成配置卡，而不是每次都靠記憶重新輸入。建議為流水線準備一個模板卡，名稱可以寫成“靈能API-Codex-CI-Template”。這張卡不一定直接保存 CI Key，但要明確 *ase **L、模型 ID、接口類型和備注說明。

如果團隊里有多條路線，例如日常開發、低成本檢查、長上下文任務和緊急備用路線，就不要把它們寫在同一張卡里。每張卡只服務一個目標，命名時寫清楚場景。流水線使用的卡應該最保守，優先穩定、清晰、易診斷，而不是追求所有能力一次塞滿。

• 模板卡用于對齊字段，不承擔密鑰分**能。
• CI 卡優先選擇穩定模型，避免頻繁切換造成檢查結果波動。
• 每次調整字段后，先在本地空目錄驗證，再同步更新自動化變量。

?? **步：把敏感信息放進環境變量

CI 接入最重要的一條原則是：配置可以版本化，密鑰不能版本化。也就是說，變量名、示例說明、預檢腳本可以放進倉庫；真實的 CODEX_API_KEY 必須放進自動化平臺的 Secret 管理區域。這樣即使倉庫被多人查看，也不會暴露真實憑證。

建議最少準備三個變量：CODEX_*ASE_**L、CODEX_API_KEY、CODEX_MODEL。若團隊要區分環境，可以再增加 CODEX_PROFILE 或 CODEX_RELAY_VENDOR，但不要過度拆分。變量越多，排查越復雜；變量越少，職責又容易混在一起。三到五個變量通常比較均衡。

$env:CODEX_*ASE_**L = "https://www.lnsns.com/"
$env:CODEX_API_KEY = "從 CI Secret 注入，不寫入腳本"
$env:CODEX_MODEL = "按控制臺可用模型填寫"

if (-not $env:CODEX_API_KEY) {
  throw "缺少 CODEX_API_KEY，請先在 CI Secret 中配置"
}

• 腳本里可以寫變量名，不能**實 Key。
• 本地示例可以使用占位符，例如 YO**_API_KEY_HERE。
• 流水線日志中要避免打印完整請求頭和完整密鑰。

第五步：寫一個最小預檢腳本

預檢腳本不需要復雜，先做到三件事：變量是否存在，*ase **L 是否可達，Codex 是否能完成只讀短任務。它的目標不是生成大量內容，也不是自動修代碼，而是判斷“今天這條中轉鏈路是否可用”。一旦這一步失敗，后續長任務就沒有必要繼續跑。

$required = @("CODEX_*ASE_**L", "CODEX_API_KEY", "CODEX_MODEL")
foreach ($name in $required) {
  if (-not [Environment]::GetEnvironmentVaria*le($name)) {
    throw "缺少環境變量：$name"
  }
}

Write-Host "變量檢查通過，開始執行 Codex 只讀短任務"
# 示例：讓 Codex 只解釋當前目錄結構，不寫入文件
codex "請只讀取當前目錄，概括項目結構，不要創建、修改或刪除任何文件。"

如果團隊擔心 Codex 在自動化環境中產生寫入動作，可以把任務限定在空目錄或專門的臨時目錄中運行，并在命令提示里明確“不要創建、修改或刪除文件”。更進一步，可以讓預檢腳本在執行前后統計文件列表，如果前后不一致，就直接判定失敗。

• 預檢任務越短越好，避免把模型輸出質量和連接可用性混在一起。
• 只讀提示要寫在任務開頭，不要放在很長描述的最后。
• 輸出里只保留摘要和錯誤碼，不保存敏感請求詳情。

第六步：把流水線分成三層門禁

不要把所有檢查寫進一個大腳本。推薦分成三層：變量門禁、連接門禁、任務門禁。變量門禁只檢查必填項是否存在；連接門禁只確認中轉站可訪問；任務門禁再調用 Codex 做只讀短任務。這樣失敗時能立即知道是哪一層出了問題。

例如變量門禁失敗，處理人應該去 CI Secret 區檢查配置；連接門禁失敗，處理人應該檢查網絡、*ase **L 和控制臺狀態；任務門禁失敗，才進入模型權限、請求格式、提示詞和 Codex 本身的排查。分層越清楚，越不容易把所有問題都誤判成“模型不可用”。

第一層：變量門禁
結果：缺變量 -> 檢查 CI Secret

第二層：連接門禁
結果：連接失敗 -> 檢查 *ase **L、網絡、賬號狀態

第三層：任務門禁
結果：調用失敗 -> 檢查模型 ID、權限、請求格式、Codex 配置

• 門禁腳本要短，不要把治理邏輯和業務邏輯混在一起。
• 每一層都輸出明確的下一步動作。
• 失敗時默認停止后續任務，避免浪費額度和制造更多日志噪聲。

第七步：為不同場景設計獨立任務

同樣是 Codex，通過靈能API接入后可以服務很多場景，但不同場景不應該共用同一條自動化任務。提交前只讀檢查、測試失敗分析、依賴升級摘要、接口變更說明和發版文檔草稿，它們的輸入、權限、耗時和失敗容忍度都不一樣。

建議先從低風險場景開始：比如讓 Codex 讀取最近一次提交的文件列表，輸出改動摘要；或者讀取測試日志，解釋失敗原因。等團隊確認成本、速度和穩定性都能接受，再把它擴展到更復雜的代碼**或文檔生成。

• 提交摘要任務：讀取變更文件，輸出面向評審者的改動說明。
• 測試失敗任務：讀取日志片段，整理失敗模塊、可能原因和排查入口。
• 依賴升級任務：讀取鎖文件變化，提示重點關注的版本跨度。
• 發版草稿任務：讀取合并記錄，生成待人工確認的發布說明。

? 第八步：失敗診斷不要只看一句報錯

流水線失敗時，很多人會直接復制最后一行報錯去搜索，但 API 中轉站接入類問題通常要看完整上下文。至少要記錄四類信息：失敗階段、**** 狀態碼、模型 ID、當前配置版本。注意這里說的是記錄摘要，不是記錄完整密鑰或完整請求頭。

401 通常優先看 Key 是否缺失、復制是否完整、變量是否被覆蓋；403 優先看權限、余額、模型授權和賬號狀態；404 優先看 *ase **L 和路徑層級；429 優先看頻率、并發和額度；timeout 則要拆分網絡超時、上游響應慢和任務本身太長。

401：檢查 CODEX_API_KEY 是否為空、是否過期、是否復制完整
403：檢查靈能API賬號權限、余額、模型授權
404：檢查 CODEX_*ASE_**L 和接口路徑
429：檢查并發、頻率、額度策略
timeout：檢查網絡、任務長度、模型響應時間

• 日志里可以打印 Key 前后 4 位用于定位，但不要打印完整 Key。
• 每次失敗都要帶上配置版本，避免排查時不知道腳本改過什么。
• 同一個錯誤連續出現三次，先停止自動化任務，再集中排查。

第九步：把成功配置沉淀成團隊手冊

當流水線第一次穩定跑通后，不要只把腳本留在倉庫里。應該同步整理一份團隊手冊，說明如何從靈能API進入控制臺、如何創建 CI 專用憑證、哪些變量需要配置、如何用 CC Switch 在本地復現、失敗時先看哪一層門禁。

手冊越具體，后續交接越輕松。比如“CODEX_*ASE_**L 從哪里復制”“CODEX_MODEL 改動前要找誰確認”“CI Key 多久輪換一次”“臨時停用自動化任務時改哪個開關”，這些信息比一句“配置一下中轉站”有價值得多。

• 寫清入口：靈能API官網、控制臺位置、團隊負責人。
• 寫清變量：變量名、用途、是否敏感、維護位置。
• 寫清診斷：每個錯誤碼對應的第一排查動作。
• 寫清邊界：哪些任務可以自動跑，哪些任務必須人工確認。

第十步：用模型和額度策略控制成本

自動化任務的特點是頻率高、觸發多、容易被忽略。如果每次提交都讓 Codex 做長上下文分析，成本會很快失控。更合理的策略是：預檢用輕量模型，失敗分析按需觸發，長文檔生成只在發版階段運行。模型選擇要和任務價值匹配，而不是所有任務都用同一檔。

通過靈能API查看可用模型和賬戶狀態時，可以順手把團隊的默認策略寫清楚。例如：預檢任務只跑短提示；測試失敗分析只在測試失敗后觸發；發版說明只在打標簽前觸發；大體量代碼**必須人工點選。這樣既保留 Codex 的效率，也不會讓自動化調用變成不可見成本。

• 輕量任務優先低成本模型，重任務再切換高能力模型。
• 默認只在必要階段觸發，不要所有分支所有提交都跑長任務。
• 每周查看一次用量，把異常增長和具體任務對應起來。

第十一步：準備停用和回滾開關

任何自動化接入都要有停用方案。最簡單的方式是在 CI 里增加一個開關變量，例如 CODEX_CI_ENA*LED。默認開啟，一旦出現額度異常、接口異常或任務誤觸發，先把開關關閉，讓其他構建流程繼續運行。不要把 Codex 檢查寫成所有發布流程都繞不開的硬依賴，除非團隊已經驗證了足夠長時間。

if ($env:CODEX_CI_ENA*LED -eq "false") {
  Write-Host "Codex 自動化檢查已臨時關閉"
  e**t 0
}

Write-Host "Codex 自動化檢查開啟，繼續執行預檢"

回滾也要分兩類：配置回滾和憑證回滾。配置回滾是把 *ase **L、模型 ID 或任務參數切回上一個版本；憑證回滾是停用當前 CI Key，切換到備用 Key。為了避免誤操作，備用 Key 不建議常駐啟用，只有在確有需要時再按流程打開。

• 停用開關要能快速生效，不需要改代碼。
• 回滾記錄要寫明時間、原因、負責人和恢復條件。
• 備用路線只用于應急，不建議長期并行造成成本歸因混亂。

? 收尾：讓 Codex 接入從個人技巧變成團隊能力

Codex 接入 API 中轉站的重點，不只是把請求轉出去，而是把“誰在用、怎么用、失敗怎么查、成本怎么控”這些問題一起解決。靈能API提供統一的接入入口，CC Switch幫助團隊在本地保存清晰配置，CI/CD 則把可用性檢查變成穩定動作。三者組合起來，才適合長期放進真實項目。

落地時不要急著把范圍做大。先建立 CI 專用憑證，再保存 CC Switch 模板卡，然后寫最小預檢腳本，最后逐步加入測試失敗分析、提交摘要和發版說明。每一步都保留診斷日志和回滾開關，團隊就能把 Codex 從“某個人會用的工具”變成“項目里可維護的基礎能力”。