先看三種接入方式怎么選

如果你只需要讓 Codex 調用一條靈能API線路，CC Switch 是較容易維護的方式；如果你希望理解底層配置，可以手動編輯 Codex 的配置文件；如果需要同時管理多個供應商、做路由或兼容不同協議，再考慮增加**。

新手建議先完成一條 CC Switch 渠道，確認 Codex 能完成最小請求，再嘗試手動配置或**組合。

• 手動配置：透明、可控，適合想理解配置原理的人。
• CC Switch：圖形化管理，適合多渠道切換。
• **模式：適合多供應商、協議轉換和統一路由。

開始前準備好這些信息

無論選擇哪種方案，都需要先準備服務地址、模型標識和令牌。配置時不要使用截圖中的示例值，也不要把完整 Key 放進項目倉庫。

首次測試最好使用一枚單獨令牌和一個空目錄，成功后再進入正式項目。

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

第一步：確認靈能API的模型和接口

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

靈能API入口：https://www.lnsns.com/。官網地址用于進入服務頁面，真實密鑰不會寫入本文示例。

• *ase **L：只填寫接口文檔要求的基礎地址。
• Model ID：從當前列表復制精確名稱。
• 分組：選擇有 Codex 使用權限的分組。
• API Key：單獨創建并保存在本機安全位置。

第二步：創建用途明確的 API Key

進入令牌管理后，建議創建一枚用于 Codex 的令牌，例如‘codex-local-test’。如果以后還要用于自動化、團隊協作或不同項目，可以分別創建不同令牌，便于統計和撤銷。

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

• 名稱寫用途和環境，不寫完整密鑰。
• 分組按照當前服務說明選擇。
• 測試令牌和長期開發令牌分開。
• 令牌暴露后立即撤銷，不要繼續觀察。

? 方案一：手動配置 Codex

手動配置的優點是每個字段都透明，便于理解和排查；缺點是字段名稱、文件位置和客戶端版本必須匹配。修改前先備份，出現認證錯誤時可以快速恢復。

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

不同系統的配置目錄可能不同，先以當前 Codex 版本的說明為準。不要因為網上示例使用了某個路徑，就直接覆蓋本機文件。

• 配置文件負責模型、供應商和請求地址。
• 環境變量負責注入 API Key。
• 客戶端重啟后才會讀取新的進程環境。

手動配置中的關鍵字段

下面是兼容型配置的示意結構，具體字段要根據當前 Codex 版本和服務接口要求調整。示例中的地址、模型和令牌都是占位符。

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

如果字段拼寫或層級錯誤，Codex 可能直接忽略配置，或者啟動后繼續使用舊的官方登錄態。

• `model_provider` 要與供應商配置塊名稱完全一致。
• `*ase_url` 通常填寫基礎路徑，不要重復追加固定接口路徑。
• `wire_api` 是否使用 Responses，要以當前客戶端和上游兼容性為準。
• API Key 優先通過環境變量注入，不要硬編碼在配置文件。

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

如果你不想手動維護 TOML 文件，可以在 CC Switch 中創建渠道。它的價值不是替你判斷模型是否可用，而是把多個供應商的地址、模型和 Key 放到可切換的配置卡中。

添加渠道時只改變必要字段。先讓一張卡跑通，再復制卡片測試其他模型，不要一次性修改地址、模型和協議。

• 供應商名稱：寫明靈能API和使用環境。
• API Key：粘貼剛剛創建的令牌。
• API 請求地址：填寫當前 *ase **L。
• 高級參數：不確定時先保留默認值。

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

填寫完成后點擊獲取模型列表。如果返回成功，說明基本地址和鑒權已經連通。選擇一個明確的 Model ID 保存渠道，然后點擊啟用或切換。

切換完成后必須關閉并重新啟動 Codex。界面上的啟用狀態，不代表已經運行的進程自動加載了新配置。

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

方案三：什么時候需要增加**

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

增加**后，鏈路會變成 Codex → CC Switch → ** → 靈能API，上下游任意一層出錯都可能表現為請求失敗，因此要記錄每層地址和端口。

• 多個供應商：統一管理不同 *ase **L。
• 協議不一致：在**層做兼容轉換。
• 模型映射：將項目模型名映射到不同上游。
• 團隊使用：集中控制訪問密鑰和路由。

第一次驗證：只讀任務優先

完成手動配置或 CC Switch 切換后，先進入空目錄執行只讀請求。不要馬上讓 Codex 掃描整個倉庫，更不要在還沒確認線路時執行刪除、安裝或批量修改。

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

測試提示可以寫成：‘請確認當前工作目錄，并用三句話說明當前連接狀態，不要修改任何文件。’確認正常后，再進入真實項目。

常見踩坑與排查順序

每次只調整一個變量，記錄錯誤碼、渠道名稱和測試時間。不要把完整 Key 發給協助排查的人。

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

? 最終選擇建議

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

• 只使用一條線路：優先 CC Switch，維護成本較低。
• 想理解底層：先學習配置文件和環境變量。
• 多個模型切換：為不同用途建立獨立卡片。
• 多個供應商或協議不兼容：再考慮**。
• 任何配置修改前：先備份并保留可回滾狀態。