先看三種接入方式怎么選

如果你只需要讓 Codex 調(diào)用一條靈能API線路，CC Switch 是較容易維護(hù)的方式；如果你希望理解底層配置，可以手動(dòng)編輯 Codex 的配置文件；如果需要同時(shí)管理多個(gè)供應(yīng)商、做路由或兼容不同協(xié)議，再考慮增加**。

新手建議先完成一條 CC Switch 渠道，確認(rèn) Codex 能完成最小請(qǐng)求，再嘗試手動(dòng)配置或**組合。

• 手動(dòng)配置：透明、可控，適合想理解配置原理的人。
• CC Switch：圖形化管理，適合多渠道切換。
• **模式：適合多供應(yīng)商、協(xié)議轉(zhuǎn)換和統(tǒng)一路由。

開(kāi)始前準(zhǔn)備好這些信息

無(wú)論選擇哪種方案，都需要先準(zhǔn)備服務(wù)地址、模型標(biāo)識(shí)和令牌。配置時(shí)不要使用截圖中的示例值，也不要把完整 Key 放進(jìn)項(xiàng)目倉(cāng)庫(kù)。

首次測(cè)試最好使用一枚單獨(dú)令牌和一個(gè)空目錄，成功后再進(jìn)入正式項(xiàng)目。

• Codex 已安裝并可以啟動(dòng)。
• CC Switch 已安裝并能進(jìn)入 Codex 菜單。
• 靈能API賬戶和可用額度。
• 當(dāng)前接口說(shuō)明中的 *ase **L。
• 當(dāng)前模型列表中的精確 Model ID。

第一步：確認(rèn)靈能API的模型和接口

打開(kāi)靈能API服務(wù)入口，查看模型列表、接口地址和令牌管理頁(yè)面。Model ID 可能包含版本后綴或特殊分隔符，建議直接復(fù)制，不要手動(dòng)輸入。

靈能API入口：https://www.lnsns.com/。官網(wǎng)地址用于進(jìn)入服務(wù)頁(yè)面，真實(shí)密鑰不會(huì)寫(xiě)入本文示例。

• *ase **L：只填寫(xiě)接口文檔要求的基礎(chǔ)地址。
• Model ID：從當(dāng)前列表復(fù)制精確名稱。
• 分組：選擇有 Codex 使用權(quán)限的分組。
• API Key：?jiǎn)为?dú)創(chuàng)建并保存在本機(jī)安全位置。

第二步：創(chuàng)建用途明確的 API Key

進(jìn)入令牌管理后，建議創(chuàng)建一枚用于 Codex 的令牌，例如‘codex-local-test’。如果以后還要用于自動(dòng)化、團(tuán)隊(duì)協(xié)作或不同項(xiàng)目，可以分別創(chuàng)建不同令牌，便于統(tǒng)計(jì)和撤銷。

復(fù)制 Key 后不要粘貼到公共聊天、代碼注釋、截圖或 `.env.example`。模板只保留變量名和占位符。

• 名稱寫(xiě)用途和環(huán)境，不寫(xiě)完整密鑰。
• 分組按照當(dāng)前服務(wù)說(shuō)明選擇。
• 測(cè)試令牌和長(zhǎng)期開(kāi)發(fā)令牌分開(kāi)。
• 令牌暴露后立即撤銷，不要繼續(xù)觀察。

? 方案一：手動(dòng)配置 Codex

手動(dòng)配置的優(yōu)點(diǎn)是每個(gè)字段都透明，便于理解和排查；缺點(diǎn)是字段名稱、文件位置和客戶端版本必須匹配。修改前先備份，出現(xiàn)認(rèn)證錯(cuò)誤時(shí)可以快速恢復(fù)。

# 先備份配置文件
~/.codex/config.toml -> ~/.codex/config.toml.*ackup
~/.codex/auth.json -> ~/.codex/auth.json.*ackup

不同系統(tǒng)的配置目錄可能不同，先以當(dāng)前 Codex 版本的說(shuō)明為準(zhǔn)。不要因?yàn)榫W(wǎng)上示例使用了某個(gè)路徑，就直接覆蓋本機(jī)文件。

• 配置文件負(fù)責(zé)模型、供應(yīng)商和請(qǐng)求地址。
• 環(huán)境變量負(fù)責(zé)注入 API Key。
• 客戶端重啟后才會(huì)讀取新的進(jìn)程環(huán)境。

手動(dòng)配置中的關(guān)鍵字段

下面是兼容型配置的示意結(jié)構(gòu)，具體字段要根據(jù)當(dāng)前 Codex 版本和服務(wù)接口要求調(diào)整。示例中的地址、模型和令牌都是占位符。

model = "<MODEL_ID>"
model_provider = "lingneng"

[model_providers.lingneng]
name = "靈能API"
*ase_url = "<*ASE_**L>"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = false

如果字段拼寫(xiě)或?qū)蛹?jí)錯(cuò)誤，Codex 可能直接忽略配置，或者啟動(dòng)后繼續(xù)使用舊的官方登錄態(tài)。

• `model_provider` 要與供應(yīng)商配置塊名稱完全一致。
• `*ase_url` 通常填寫(xiě)基礎(chǔ)路徑，不要重復(fù)追加固定接口路徑。
• `wire_api` 是否使用 Responses，要以當(dāng)前客戶端和上游兼容性為準(zhǔn)。
• API Key 優(yōu)先通過(guò)環(huán)境變量注入，不要硬編碼在配置文件。

? 方案二：使用 CC Switch 管理渠道

如果你不想手動(dòng)維護(hù) TOML 文件，可以在 CC Switch 中創(chuàng)建渠道。它的價(jià)值不是替你判斷模型是否可用，而是把多個(gè)供應(yīng)商的地址、模型和 Key 放到可切換的配置卡中。

添加渠道時(shí)只改變必要字段。先讓一張卡跑通，再?gòu)?fù)制卡片測(cè)試其他模型，不要一次性修改地址、模型和協(xié)議。

• 供應(yīng)商名稱：寫(xiě)明靈能API和使用環(huán)境。
• API Key：粘貼剛剛創(chuàng)建的令牌。
• API 請(qǐng)求地址：填寫(xiě)當(dāng)前 *ase **L。
• 高級(jí)參數(shù)：不確定時(shí)先保留默認(rèn)值。

獲取模型列表并完成第一次切換

填寫(xiě)完成后點(diǎn)擊獲取模型列表。如果返回成功，說(shuō)明基本地址和鑒權(quán)已經(jīng)連通。選擇一個(gè)明確的 Model ID 保存渠道，然后點(diǎn)擊啟用或切換。

切換完成后必須關(guān)閉并重新啟動(dòng) Codex。界面上的啟用狀態(tài)，不代表已經(jīng)運(yùn)行的進(jìn)程自動(dòng)加載了新配置。

• 列表為空：檢查接口地址和分組。
• 401：檢查 Key 是否完整和有效。
• 403：檢查額度、權(quán)限和模型范圍。
• 404：檢查 *ase **L 是否重復(fù)拼接路徑。

方案三：什么時(shí)候需要增加**

如果上游已經(jīng)提供與 Codex 兼容的接口，通常不需要額外增加**。只有在多個(gè)供應(yīng)商需要統(tǒng)一入口、上游協(xié)議不同、需要模型映射或需要集中路由時(shí)，才考慮使用**。

增加**后，鏈路會(huì)變成 Codex → CC Switch → ** → 靈能API，上下游任意一層出錯(cuò)都可能表現(xiàn)為請(qǐng)求失敗，因此要記錄每層地址和端口。

• 多個(gè)供應(yīng)商：統(tǒng)一管理不同 *ase **L。
• 協(xié)議不一致：在**層做兼容轉(zhuǎn)換。
• 模型映射：將項(xiàng)目模型名映射到不同上游。
• 團(tuán)隊(duì)使用：集中控制訪問(wèn)密鑰和路由。

第一次驗(yàn)證：只讀任務(wù)優(yōu)先

完成手動(dòng)配置或 CC Switch 切換后，先進(jìn)入空目錄執(zhí)行只讀請(qǐng)求。不要馬上讓 Codex 掃描整個(gè)倉(cāng)庫(kù)，更不要在還沒(méi)確認(rèn)線路時(shí)執(zhí)行刪除、安裝或批量修改。

New-Item -ItemType Directory codex-config-check
Set-Location codex-config-check
codex

測(cè)試提示可以寫(xiě)成：‘請(qǐng)確認(rèn)當(dāng)前工作目錄，并用三句話說(shuō)明當(dāng)前連接狀態(tài)，不要修改任何文件。’確認(rèn)正常后，再進(jìn)入真實(shí)項(xiàng)目。

常見(jiàn)踩坑與排查順序

每次只調(diào)整一個(gè)變量，記錄錯(cuò)誤碼、渠道名稱和測(cè)試時(shí)間。不要把完整 Key 發(fā)給協(xié)助排查的人。

• 切換后沒(méi)有變化：關(guān)閉舊進(jìn)程并重新啟動(dòng)。
• 認(rèn)證錯(cuò)誤：檢查 API Key、環(huán)境變量和當(dāng)前渠道。
• 接口路徑錯(cuò)誤：檢查 *ase **L 是否多寫(xiě)了固定路徑。
• 模型不存在：重新復(fù)制當(dāng)前 Model ID。
• 響應(yīng)格式錯(cuò)誤：檢查客戶端協(xié)議和上游兼容性。
• 插件或擴(kuò)展不可用：確認(rèn)當(dāng)前接入方式和客戶端版本是否支持。
• 改錯(cuò)配置：恢復(fù)備份，不要繼續(xù)在失敗文件上疊加修改。

? 最終選擇建議

靈能API接入 Codex 的關(guān)鍵不是把所有工具都裝上，而是先選擇一條清晰鏈路，完成最小請(qǐng)求，再逐步擴(kuò)展模型和項(xiàng)目范圍。

• 只使用一條線路：優(yōu)先 CC Switch，維護(hù)成本較低。
• 想理解底層：先學(xué)習(xí)配置文件和環(huán)境變量。
• 多個(gè)模型切換：為不同用途建立獨(dú)立卡片。
• 多個(gè)供應(yīng)商或協(xié)議不兼容：再考慮**。
• 任何配置修改前：先備份并保留可回滾狀態(tài)。