遷移前先承認(rèn)一個(gè)現(xiàn)實(shí)：舊配置通常不干凈

很多 Codex 接入并不是一開(kāi)始就按團(tuán)隊(duì)標(biāo)準(zhǔn)做的。最初可能只是某個(gè)成員為了試用，臨時(shí)填了一個(gè) *ase **L，隨手建了一枚 Key，再把配置截圖發(fā)給同事。后來(lái)項(xiàng)目越用越多，配置慢慢進(jìn)入真實(shí)開(kāi)發(fā)、腳本檢查、文檔生成和問(wèn)題排查流程。等你想切到新的 API 中轉(zhuǎn)站時(shí)，才發(fā)現(xiàn)舊配置已經(jīng)分散在多臺(tái)電腦和多個(gè)文檔里。

遷移最忌諱的動(dòng)作，是直接覆蓋舊配置?？雌饋?lái)省事，實(shí)際上沒(méi)有回滾點(diǎn)。更穩(wěn)的做法是把舊線路保留，把靈能API新線路作為獨(dú)立配置接入，在同一臺(tái)機(jī)器、同一套任務(wù)、同一個(gè)項(xiàng)目里逐步對(duì)比。確認(rèn)穩(wěn)定后，再通知團(tuán)隊(duì)分批切換。

• 舊配置可能散在 CC Switch、終端環(huán)境變量、CI Secret 和團(tuán)隊(duì)文檔里。
• 遷移不是刪除舊線路，而是先建立**證的新線路。
• 每次只改一項(xiàng)變量，才能知道問(wèn)題來(lái)自哪里。

第一階段：盤(pán)點(diǎn)舊配置在哪里

開(kāi)始遷移前，先做一份舊配置清單。不要只問(wèn)“現(xiàn)在誰(shuí)能用”，而要問(wèn)“現(xiàn)在有哪些地方正在用”。常見(jiàn)位置包括開(kāi)發(fā)者本機(jī)的 CC Switch 配置卡、PowerShell 環(huán)境變量、項(xiàng)目 README、腳本模板、CI 平臺(tái) Secret、內(nèi)部知識(shí)庫(kù)和歷史問(wèn)題記錄。

盤(pán)點(diǎn)時(shí)不需要收集完整 API Key，甚至不應(yīng)該收集完整 Key。你只需要記錄配置名稱(chēng)、用途、負(fù)責(zé)人、是否仍在使用、是否影響自動(dòng)化任務(wù)。敏感值仍保留在原安全位置里，遷移清單只記錄元信息。

盤(pán)點(diǎn)項(xiàng)：
配置名稱(chēng)：舊-Codex-日常開(kāi)發(fā)
所在位置：成員 A 的 CC Switch
用途：本地代碼解釋和排錯(cuò)
負(fù)責(zé)人：成員 A
是否仍在使用：是
遷移風(fēng)險(xiǎn)：低，先復(fù)制新卡驗(yàn)證

配置名稱(chēng)：舊-Codex-CI-檢查
所在位置：CI Secret
用途：合并前只讀檢查
負(fù)責(zé)人：項(xiàng)目負(fù)責(zé)人
是否仍在使用：是
遷移風(fēng)險(xiǎn)：中，需要單獨(dú)灰度

• 盤(pán)點(diǎn)清單寫(xiě)用途和位置，不寫(xiě)完整密鑰。
• 自動(dòng)化配置要單獨(dú)標(biāo)記，不能和個(gè)人配置混在一起。
• 沒(méi)人認(rèn)領(lǐng)的舊配置先不要?jiǎng)h除，等確認(rèn)無(wú)依賴(lài)后再處理。

第二階段：從靈能API確認(rèn)新入口

遷移的新入口要從當(dāng)前控制臺(tái)獲取。通過(guò) https://www.lnsns.com/ 進(jìn)入靈能API，確認(rèn)賬號(hào)、控制臺(tái)入口、接入說(shuō)明、可用模型和余額狀態(tài)。不要從舊聊天記錄復(fù)制地址，也不要用幾個(gè)月前保存的截圖作為依據(jù)。

這里要特別注意賬號(hào)上下文。團(tuán)隊(duì)如果有多個(gè)賬號(hào)，遷移時(shí)一定要確認(rèn)新 Key、*ase **L、模型權(quán)限來(lái)自同一套靈能API賬號(hào)。舊線路能跑通，不代表新賬號(hào)具備相同模型權(quán)限；新入口能打開(kāi)，也不代表所有項(xiàng)目都應(yīng)該立刻切過(guò)去。

• 確認(rèn) *ase **L 來(lái)自當(dāng)前控制臺(tái)說(shuō)明。
• 確認(rèn)模型列表和舊配置里使用的模型是否能對(duì)應(yīng)。
• 確認(rèn)賬戶(hù)狀態(tài)正常，再進(jìn)行 CC Switch 配置。

第三階段：不要改舊卡，先復(fù)制一張新卡

打開(kāi) CC Switch 后，先找到舊配置卡。不要直接覆蓋舊卡里的字段，而是復(fù)制一張新卡，命名為“靈能API-Codex-遷移驗(yàn)證”。這張新卡只用于遷移測(cè)試，舊卡繼續(xù)保留，確保新線路失敗時(shí)可以立即切回。

新卡里先只替換靈能API相關(guān)字段：*ase **L、API Key、必要的模型 ID。其他參數(shù)保持舊配置一致。這樣做的好處是變量更少，問(wèn)題更容易定位。如果你同時(shí)換地址、換模型、換**、換提示詞，一旦失敗，就很難判斷是哪一項(xiàng)造成的。

舊卡：Codex-舊線路-日常
狀態(tài)：保留，不修改

新卡：靈能API-Codex-遷移驗(yàn)證
第一輪：只替換 *ase **L 和 API Key
第二輪：再核對(duì)模型 ID
第三輪：通過(guò)短任務(wù)后再進(jìn)入真實(shí)項(xiàng)目

• 舊卡不動(dòng)，遷移失敗時(shí)可以立即切回。
• 新卡先只改中轉(zhuǎn)站字段，不同時(shí)改多項(xiàng)。
• 新卡名稱(chēng)要寫(xiě)明遷移驗(yàn)證，避免被當(dāng)成正式配置長(zhǎng)期使用。

**階段：核對(duì)新舊字段差異

新舊線路對(duì)比時(shí)，不要只看能不能返回。要逐項(xiàng)核對(duì)字段：*ase **L、接口兼容方式、模型 ID、Key 來(lái)源、**設(shè)置、超時(shí)策略、默認(rèn)提示詞和使用場(chǎng)景。尤其是模型 ID，舊配置里寫(xiě)的名稱(chēng)未必能在新入口下直接使用。

建議把字段差異寫(xiě)成一份遷移表。表里不**實(shí)密鑰，只寫(xiě)字段來(lái)源和處理動(dòng)作。例如 *ase **L 從靈能API當(dāng)前控制臺(tái)復(fù)制，API Key 由***新建并安全分發(fā)，模型 ID 由項(xiàng)目負(fù)責(zé)人確認(rèn)。這樣遷移不是某個(gè)人憑記憶完成，而是有記錄可復(fù)查。

• *ase **L：確認(rèn)入口和路徑層級(jí)。
• API Key：確認(rèn)是新建 Key，而不是舊 Key 繼續(xù)沿用。
• Model ID：確認(rèn)在新賬號(hào)中可用。
• Proxy：確認(rèn)終端**和瀏覽器**不是兩套邏輯。

第五階段：先跑空目錄短任務(wù)

新線路配置好后，第一輪驗(yàn)證必須在空目錄里做。不要直接拿真實(shí)項(xiàng)目做遷移測(cè)試，因?yàn)檎鎸?shí)項(xiàng)目失敗時(shí)變量太多：可能是讀取范圍大，可能是模型響應(yīng)慢，可能是某個(gè)文件權(quán)限問(wèn)題，也可能是新線路本身沒(méi)有通。空目錄短任務(wù)能把問(wèn)題壓縮到連接層。

mkdir codex-migration-check
cd codex-migration-check
codex "請(qǐng)只回復(fù)：遷移驗(yàn)證通過(guò)。不要?jiǎng)?chuàng)建、修改或刪除文件。"

如果這一步失敗，先不要進(jìn)真實(shí)項(xiàng)目，也不要急著換模型。優(yōu)先檢查靈能API控制臺(tái)入口、Key 是否復(fù)制完整、CC Switch 當(dāng)前是否選中新卡、終端是否繼承**、*ase **L 是否多寫(xiě)或少寫(xiě)路徑。每次只改一項(xiàng)，改完重新跑同一條短任務(wù)。

• 短任務(wù)成功，說(shuō)明基礎(chǔ)鏈路可用。
• 短任務(wù)失敗，先查配置，不查業(yè)務(wù)代碼。
• 不要每次換一條提示詞，否則驗(yàn)證結(jié)果不可對(duì)比。

第六階段：真實(shí)項(xiàng)目只做只讀驗(yàn)證

空目錄通過(guò)后，第二輪才進(jìn)入真實(shí)項(xiàng)目。這里依舊不建議讓 Codex 直接改文件，而是做只讀驗(yàn)證：讀取 README、依賴(lài)文件、目錄結(jié)構(gòu)和少量核心源碼，輸出項(xiàng)目概覽和后續(xù)檢查建議。這樣能確認(rèn)新線路處理真實(shí)上下文的能力，同時(shí)把風(fēng)險(xiǎn)控制住。

如果項(xiàng)目很大，不要讓 Codex 一次掃描全部目錄。遷移驗(yàn)證階段的目標(biāo)不是全面**，而是確認(rèn)新線路在真實(shí)項(xiàng)目中能穩(wěn)定讀取和回答?？梢韵冗x擇一個(gè)低風(fēng)險(xiǎn)模塊，例如工具函數(shù)、文檔目錄或測(cè)試目錄。

推薦只讀提示：
請(qǐng)只讀取 README、依賴(lài)配置和 src 頂層目錄，概括項(xiàng)目結(jié)構(gòu)。
不要讀取 .env、logs、*ackups、customer-**ta 目錄。
不要?jiǎng)?chuàng)建、修改或刪除文件。
輸出分為：項(xiàng)目用途、主要模塊、遷移后觀察點(diǎn)。

• 真實(shí)項(xiàng)目第一輪只讀，不寫(xiě)入。
• 先選低風(fēng)險(xiǎn)模塊，不掃描全倉(cāng)庫(kù)。
• 輸出里記錄新線路響應(yīng)速度和錯(cuò)誤情況。

第七階段：雙線路并行觀察，不要立刻停舊線路

新線路通過(guò)驗(yàn)證后，也不要馬上停掉舊線路。建議保留一段觀察期，讓舊卡和新卡并行存在，但明確新卡優(yōu)先使用、舊卡只用于回滾。觀察期可以按項(xiàng)目節(jié)奏設(shè)定，比如三天、一周或一個(gè)迭代周期。

并行觀察不是讓大家隨便切換，而是為了降低遷移風(fēng)險(xiǎn)。團(tuán)隊(duì)文檔要寫(xiě)清楚：日常任務(wù)開(kāi)始使用靈能API新卡，舊卡只在新卡連續(xù)失敗且短任務(wù)無(wú)法通過(guò)時(shí)啟用。每次切回舊卡都要記錄原因，否則遷移狀態(tài)會(huì)變得模糊。

觀察期規(guī)則：
新卡：默認(rèn)使用
舊卡：僅作回滾
切回條件：新卡連續(xù)失敗 3 次，且排除本地變量錯(cuò)誤
記錄內(nèi)容：時(shí)間、使用者、配置卡、錯(cuò)誤碼、處理動(dòng)作

• 觀察期要有明確開(kāi)始和結(jié)束日期。
• 舊卡只作為回滾，不再作為日常默認(rèn)配置。
• 每次回滾都要記錄原因，避免長(zhǎng)期停留在舊線路。

第八階段：遷移 CI 和腳本時(shí)更要謹(jǐn)慎

個(gè)人本機(jī)遷移成功，不代表 CI 和腳本也能直接切換。自動(dòng)化環(huán)境里可能有獨(dú)立的 Secret、獨(dú)立**、獨(dú)立網(wǎng)絡(luò)出口和不同的執(zhí)行目錄。把靈能API接入自動(dòng)化任務(wù)時(shí)，建議單獨(dú)創(chuàng)建 CI Key，并在非主發(fā)布流程里先跑預(yù)檢。

遷移 CI 時(shí)，先增加一條獨(dú)立任務(wù)，例如 codex-relay-migration-check。它只檢查變量、連接和短任務(wù)，不影響原有構(gòu)建流程。等這條任務(wù)穩(wěn)定后，再把 Codex 分析任務(wù)切到新線路。不要在同一次提交里既換中轉(zhuǎn)站，又改構(gòu)建腳本，又改模型策略。

• CI 使用獨(dú)立 Key，不混用個(gè)人 Key。
• 先新增遷移檢查任務(wù)，再替換正式任務(wù)。
• 自動(dòng)化遷移失敗時(shí)，先停任務(wù)，不要無(wú)限重試。
• CI 日志不要打印完整 API Key 或完整請(qǐng)求頭。

第九階段：給回滾寫(xiě)一個(gè)明確開(kāi)關(guān)

遷移方案沒(méi)有回滾開(kāi)關(guān)，就不算完整。個(gè)人本機(jī)可以通過(guò) CC Switch 切回舊卡，CI 則應(yīng)該有明確變量控制。例如 CODEX_RELAY_PROFILE=legacy 或 CODEX_RELAY_PROFILE=lingneng。這樣出現(xiàn)異常時(shí)，不需要臨時(shí)改代碼，只改變量就能切換。

回滾不是失敗，而是工程里的正常保護(hù)動(dòng)作。真正的問(wèn)題是回滾后沒(méi)人追蹤，舊線路繼續(xù)長(zhǎng)期使用。建議每次回滾都寫(xiě)明恢復(fù)條件：新卡短任務(wù)通過(guò)、真實(shí)項(xiàng)目只讀驗(yàn)證通過(guò)、自動(dòng)化任務(wù)連續(xù)兩次正常，再切回靈能API新線路。

if ($env:CODEX_RELAY_PROFILE -eq "legacy") {
  Write-Host "當(dāng)前使用舊線路，僅用于臨時(shí)回滾"
}

if ($env:CODEX_RELAY_PROFILE -eq "lingneng") {
  Write-Host "當(dāng)前使用靈能API新線路"
}

• 回滾要能快速執(zhí)行，不依賴(lài)改代碼。
• 回滾后要設(shè)恢復(fù)條件，不能無(wú)限期拖著。
• 舊線路停用前，確認(rèn)沒(méi)有成員和腳本仍在依賴(lài)。

第十階段：遷移完成后歸檔舊配置

觀察期結(jié)束后，如果靈能API新線路穩(wěn)定，就可以開(kāi)始?xì)w檔舊配置。歸檔不是簡(jiǎn)單刪除，而是先確認(rèn)舊卡、舊 Key、舊文檔、舊 CI 變量都不再被使用。確認(rèn)后再停用舊 Key，更新團(tuán)隊(duì)文檔，把舊配置標(biāo)記為 deprecated。

建議保留遷移記錄，內(nèi)容包括遷移日期、負(fù)責(zé)人、舊配置名稱(chēng)、新配置名稱(chēng)、驗(yàn)證結(jié)果、回滾次數(shù)和最終停用時(shí)間。這些記錄以后做問(wèn)題復(fù)盤(pán)、人員交接或再次遷移時(shí)很有用。

• 舊 CC Switch 卡：標(biāo)記 deprecated 后再刪除。
• 舊 API Key：確認(rèn)無(wú)依賴(lài)后停用。
• 舊文檔：保留歷史記錄，但明顯標(biāo)注已過(guò)期。
• 舊 CI 變量：確認(rèn)新任務(wù)穩(wěn)定后再清理。

? 收尾：遷移要慢一點(diǎn)，后面才會(huì)快很多

Codex Claude中轉(zhuǎn)或 API 中轉(zhuǎn)站遷移，最穩(wěn)的節(jié)奏不是一口氣替換所有配置，而是先盤(pán)點(diǎn)、再?gòu)?fù)制、再驗(yàn)證、再灰度、再回收。靈能API提供新的統(tǒng)一入口，CC Switch保留新舊配置卡對(duì)照，團(tuán)隊(duì)文檔記錄每一步變化，這樣遷移過(guò)程就不會(huì)靠記憶和運(yùn)氣。

如果你現(xiàn)在手里有一套舊 Codex 配置，建議先不要?jiǎng)铀?。通過(guò)靈能API建立新線路，用空目錄短任務(wù)跑通，再進(jìn)入真實(shí)項(xiàng)目只讀驗(yàn)證，最后分批切換團(tuán)隊(duì)成員和自動(dòng)化任務(wù)。遷移看起來(lái)多走了幾步，但每一步都在為后續(xù)穩(wěn)定性省時(shí)間。