先判斷是否真的需要**

**不是接入 Codex 的必選組件。它會增加一個服務進程、一個端口和一層鑒權。如果靈能API已經提供 Codex 所需協議，直接在 CC Switch 中添加渠道通常更簡單。

如果只是想切換兩張配置卡，不必為了‘看起來更完整’而額外部署**。

• 單一供應商：優先直連，鏈路更短。
• 多家供應商：需要統一入口和快速切換。
• 協議不同：需要在**層做格式轉換。
• 團隊使用：需要集中控制路由和權限。

先畫清楚請求鏈路

部署前先明確每一層負責什么。一個典型鏈路是：Codex 發起請求，CC Switch 提供當前入口配置，CCX 接收請求并路由到上游，靈能API返回模型響應。任何一層的地址、令牌或協議不匹配，都會造成失敗。

Codex
  -> CC Switch 當前渠道
  -> CCX **地址和端口
  -> 靈能API上游渠道
  -> 模型響應返回 Codex

• 入口 Key：Codex 訪問**的憑證。
• 上游 Key：**訪問靈能API的憑證。
• 模型映射：客戶端模型名與上游模型名的關系。

第一步：準備靈能API上游渠道

打開靈能API服務入口，先確認作為上游需要的 *ase **L、Model ID 和專用 API Key。建議為**單獨創建令牌，不要復用個人開發令牌。

靈能API入口：https://www.lnsns.com/。完整上游 Key 只寫入**的受控配置，不進入倉庫和截圖。

• 上游地址：填寫當前接口說明中的 *ase **L。
• 上游模型：使用當前列表中的精確 Model ID。
• 上游令牌：單獨創建，便于撤銷和審計。

第二步：準備 Docker 和持久化目錄

CCX 需要一個穩定運行環境。使用 Docker 時，先確認 Docker Desktop 或 Docker Engine 正常運行，再為配置和數據準備持久化目錄。不要把所有配置都放在容器臨時層，否則容器重建后可能丟失。

docker --version
docker ps
New-Item -ItemType Directory -Force .\ccx-**ta

生產環境不要直接把管理端**露到公網，至少增加訪問控制和安全邊界。

• 容器名稱固定，便于查看日志和重啟。
• 配置目錄映射到宿主機。
• 入口端口只暴露給需要訪問的網絡。

第三步：啟動 CCX **

啟動命令中的鏡像名稱、端口和環境變量要以當前 CCX 版本文檔為準。下面只展示部署結構，密鑰使用占位符，不要直接把示例值當作生產配置。

docker run -d `
  --name codex-gateway `
  -p 127.0.0.1:3000:3000 `
  -e PROXY_ACCESS_KEY=<GATEWAY_ACCESS_KEY> `
  -e APP_UI_LANGUAGE=zh-CN `
  -v ${PWD}\ccx-**ta:/app/.config `
  <CCX_IMAGE>

啟動后先查看容器狀態和日志，不要馬上把地址填入所有項目。

• 入口 Key：只用于 Codex 訪問**。
• 端口綁定：本機使用時優先綁定 127.0.0.1。
• 配置掛載：確保容器重啟后配置仍在。

**步：先在**內測試上游

進入 CCX 管理界面，添加靈能API上游渠道。填寫上游地址、令牌、模型和必要的協議設置，然后使用**自帶的測試功能驗證。上游測試未通過時，CC Switch 和 Codex 還沒有排查價值。

• 渠道名稱：寫清靈能API和模型用途。
• 上游 *ase **L：不要把**入口地址誤填成上游地址。
• 上游 Key：使用**專用令牌。
• 測試模型：先選一個明確可用的模型。

第五步：設置模型映射和協議轉換

如果客戶端使用的模型名與靈能API上游模型名不同，需要在**中配置映射。協議轉換也要在這一層明確：Codex 發來的請求是什么格式，**轉換后發給上游的格式是什么，響應返回時如何還原。

客戶端模型：codex-default
上游模型：<靈能API當前 Model ID>
客戶端入口：http://127.0.0.1:3000/v1
上游入口：<靈能API *ase **L>
轉換：按當前**支持情況啟用

• 映射名稱必須唯一且容易識別。
• 不要把不存在的模型映射成默認值。
• 協議轉換失敗時先查看**日志。

? 第六步：讓 CC Switch 只連接**入口

**測試通過后，在 CC Switch 中創建一張‘Codex-CCX-靈能API’渠道。此時 API Key 填**入口 Key，*ase **L 填**地址，不再把靈能API的上游 Key 直接放進 CC Switch。

客戶端和上游使用兩套 Key，是**方案的重要邊界。

• 供應商名稱：Codex-CCX-靈能API。
• API Key：**訪問 Key。
• *ase **L：**本地或內網地址。
• Model ID：填寫**暴露的映射名稱。

第七步：重啟 Codex 并做鏈路測試

啟用 CC Switch 渠道后，關閉舊 Codex 進程并重新打開。首次測試要記錄**日志、上游調用記錄和客戶端返回結果，三處至少要能對應到同一次請求。

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

• 客戶端是否連接到**入口。
• **是否收到請求并選擇正確路由。
• 靈能API是否返回模型結果。
• 響應是否被**正確轉換并返回。

**模式常見問題

排查順序是客戶端入口、**服務、上游渠道、模型映射和響應格式，不要一出錯就重新生成所有 Key。

• 客戶端連接失敗：檢查**容器、端口和本機地址。
• ** 401：檢查入口 Key，不要檢查上游 Key。
• 上游 401：檢查**保存的靈能API令牌。
• 模型不存在：檢查**映射和上游 Model ID。
• 404：檢查客戶端、**和上游各自的路徑。
• 響應解析失敗：檢查協議轉換和響應日志。
• 重啟丟配置：檢查宿主機目錄掛載。

**上線前的安全檢查

**的價值是統一管理，不是把所有密鑰集中后就不再管理。集中配置更需要權限和日志邊界。

• 管理端口沒有直接暴露到公網。
• 入口 Key 與上游 Key 分離。
• 配置目錄已持久化并限制訪問權限。
• 日志沒有記錄完整令牌和敏感請求體。
• 不同項目使用不同入口或路由權限。
• 停止、重啟和回滾流程已經測試。

? 最終驗收清單

當你確實需要多供應商或協議轉換時，CCX CC Switch 靈能API可以形成清晰的路由鏈路；如果只有一條線路，優先使用更短的直連方式。

• 靈能API上游地址和模型已經確認。
• CCX 容器可以穩定運行。
• 上游渠道測試通過。
• 模型映射和協議轉換已明確。
• CC Switch 只保存**入口信息。
• Codex 重啟后最小請求通過。
• **日志和上游調用可以對應同一請求。
• 入口、上游密鑰和管理端口已經隔離。