Codex 怎麼接入國產大模型？用 CCX 統一管理 OpenAI 相容 API

Wed, 13 May 2026 23:20:40 +0800

CCX 是一個 AI API 代理與協定轉換閘道。它把 Claude Messages、OpenAI Chat Completions、OpenAI Images、Codex Responses 和 Gemini API 放到同一個服務入口下，同時提供 Web 管理介面，用來配置渠道、金鑰、模型映射、優先級、故障轉移和流量監控。

如果你平時同時使用 Claude、OpenAI、Gemini、Codex，或維護多個相容 OpenAI API 的上游服務，CCX 的價值就在於統一入口和統一管理。客戶端只需要連接一個服務地址，後面的上游渠道由 CCX 負責調度。

專案地址：https://github.com/BenedictKing/ccx

CCX 解決什麼問題

多個 AI API 混用時，最容易遇到幾個問題：

每個供應商的介面路徑、鑑權方式、請求格式都不一樣。
同一類模型可能有多個上游，需要手動切換 base URL 和 API key。
某個 key 或渠道失敗後，客戶端通常不會自動換備用渠道。
團隊使用時，很難集中管理模型白名單、代理、自訂請求標頭和呼叫日誌。
想同時接 Claude、Gemini、OpenAI Chat、圖像介面和 Codex Responses 時，配置會越來越分散。

CCX 的思路是把這些差異收斂到一個代理層。前端工具、腳本或業務服務只存取 CCX；CCX 再根據介面類型、模型、渠道狀態、優先級和健康情況，把請求轉發到合適的上游。

支援哪些介面

CCX 對外提供一個統一後端入口，預設連接埠是 3000。主要路徑包括：

GET  /                         -> Web 管理介面
GET  /health                   -> 健康檢查
/api/*                         -> 管理 API
POST /v1/messages              -> Claude Messages 代理
POST /v1/chat/completions      -> OpenAI Chat 代理
POST /v1/responses             -> Codex Responses 代理
POST /v1/images/generations    -> OpenAI Images 生成
POST /v1/images/edits          -> OpenAI Images 編輯
POST /v1/images/variations     -> OpenAI Images 變體
GET  /v1/models                -> 模型清單
POST /v1beta/models/*          -> Gemini 代理

也就是說，它不是只代理一種協定，而是把常見 AI API 分成 Messages、Chat、Responses、Gemini、Images 幾類渠道分別管理。不同協定之間不會共用同一套健康狀態和日誌空間，這對排查問題很重要。

架構思路

CCX 使用 Go 後端加 Vue 3 前端。前端建置產物會嵌入後端二進位檔，因此可以做單連接埠部署：同一個服務既提供 Web UI，也提供管理 API 和代理 API。

一次請求大致會經過這樣的鏈路：

`1`	`Client -> Auth Middleware -> Route Handler -> Channel Scheduler -> Provider / Converter -> Upstream API -> Metrics / Channel Logs -> Client Response`

幾個核心模組的分工可以這樣理解：

handlers：接收不同協定的請求和管理操作。
providers：封裝上游 API 的請求和回應處理。
converters：處理 Responses 等場景下的協定轉換。
scheduler：根據優先級、促銷期、健康狀態、熔斷狀態和會話親和性選擇渠道。
metrics：記錄請求量、成功率、延遲、日誌和熔斷狀態。
config：維護執行時配置，支援熱重載和備份。

這個設計的重點不是「把所有介面強行變成一種格式」，而是按協定類型分別代理，再在管理、調度、日誌和認證層做統一。

CCX 和 CodexBridge 有什麼區別

CCX 和 CodexBridge 都和 Codex、OpenAI 相容介面有關，但它們解決的問題不一樣。

CodexBridge 更像一個專門的 Codex 橋接器。它的核心目標是把 Codex CLI/SDK 封裝成 OpenAI 相容的 /v1/chat/completions 服務，讓 OpenWebUI、Cherry Studio、腳本或其他 OpenAI 相容客戶端可以呼叫本地 Codex。也就是說，CodexBridge 的重點是「把 Codex 接出來」。

CCX 更像一個統一 AI API 閘道。它不只處理 Codex Responses，還同時支援 Claude Messages、OpenAI Chat、OpenAI Images 和 Gemini API，並提供 Web 管理介面、渠道優先級、故障轉移、日誌監控和多 key 管理。也就是說，CCX 的重點是「把多個模型和多個供應商統一管起來」。

簡單對比：

對比項	CodexBridge	CCX
核心定位	Codex 本地橋接器	多協定 AI API 閘道
主要目標	讓 Codex 變成 OpenAI 相容介面	統一管理 Claude、OpenAI、Gemini、Codex 等渠道
管理介面	側重 API 服務本身	提供 Web 管理介面
多渠道調度	不是重點	支援渠道優先級、故障轉移和日誌監控
適合場景	本機或單服務呼叫 Codex	團隊、多 key、多供應商、多協定統一入口

如果只是想把 Codex 接進 OpenWebUI 或 Cherry Studio，CodexBridge 更直接；如果想同時管理 Codex、Claude、Gemini、DeepSeek、Qwen、Kimi 等多個上游，CCX 更合適。

快速部署

最簡單的方式是下載二進位檔。下載後，在同目錄建立 .env：

PROXY_ACCESS_KEY=your-proxy-access-key
PORT=3000
ENABLE_WEB_UI=true
APP_UI_LANGUAGE=zh-CN

啟動後存取：

`1`	`http://localhost:3000`

如果在 Windows 下從 WSL、Docker、PowerShell 或其他環境存取 localhost 不通，可以改用 Windows 主機的區域網路 IPv4 地址，例如：

`1`	`http://192.168.1.23:3000`

CCX 預設透過 :PORT 監聽所有網卡地址，所以暴露到區域網路時要注意存取控制。

Docker 部署

Docker 方式適合長期執行：

docker run -d \
  --name ccx \
  -p 3000:3000 \
  -e PROXY_ACCESS_KEY=your-proxy-access-key \
  -e APP_UI_LANGUAGE=zh-CN \
  -v $(pwd)/.config:/app/.config \
  crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest

如果倉庫裡已經有 docker-compose.yml，也可以直接：

`1`	`docker compose up -d`

需要自動更新時，可以疊加 Watchtower 配置：

`1`	`docker compose -f docker-compose.yml -f docker-compose.watchtower.yml up -d`

部署完成後，.config 目錄會保存執行時配置和持久化資料，建議掛載到宿主機，避免容器重建後配置遺失。

原始碼執行

開發或自訂建置可以走原始碼方式：

git clone https://github.com/BenedictKing/ccx
cd ccx
cp backend-go/.env.example backend-go/.env
make run

常用命令：

make dev
make run
make build
make frontend-dev

前端單獨開發：

1
2
3

cd frontend
bun install
bun run dev

後端單獨開發：

1
2

cd backend-go
make dev

關鍵環境變數

最小可用配置通常包括：

PORT=3000
ENV=production
ENABLE_WEB_UI=true
PROXY_ACCESS_KEY=your-proxy-access-key
ADMIN_ACCESS_KEY=your-admin-secret-key
APP_UI_LANGUAGE=zh-CN
LOG_LEVEL=info
REQUEST_TIMEOUT=300000

其中：

PROXY_ACCESS_KEY 用於代理 API，是必須修改的金鑰。
ADMIN_ACCESS_KEY 用於 Web 管理介面和 /api/*，建議和代理金鑰分開。
ENABLE_WEB_UI 控制是否啟用管理介面。
REQUEST_TIMEOUT 控制請求逾時時間，長上下文或圖像任務可以適當調大。
LOG_LEVEL 控制日誌級別，生產環境一般用 info 或 warn。

如果需要限制請求體大小，可以關注：

`1`	`MAX_REQUEST_BODY_SIZE_MB=50`

圖像編輯、base64 圖片、多模態請求都可能讓請求體變大。

渠道編排和故障轉移

CCX 的管理介面可以配置多個渠道，並為每個渠道設定：

上游服務類型。
API key 或多 key 輪換。
代理地址。
自訂請求標頭。
模型白名單。
路由前綴。
優先級。
健康檢查與熔斷恢復。

調度時會綜合考慮渠道狀態、優先級、促銷期、Trace 親和性、熔斷狀態和可用 key。簡單理解：

正常情況下，優先級高的渠道先被使用。
某個渠道失敗後，可以故障轉移到備用渠道。
熔斷機制會避免持續打到明顯不可用的上游。
Trace 親和性會盡量讓同一類會話保持在合適的渠道上。

這類能力適合有多個 key、多個供應商或多個地區上游的場景。個人輕量使用時，也可以只配置一個渠道，把 CCX 當成帶 Web UI 的代理層。

日誌和監控

CCX 提供渠道指標和請求日誌，可以看到：

請求量。
成功率。
失敗率。
平均延遲。
按模型統計的歷史資料。
渠道狀態和熔斷情況。

生產環境建議使用相對克制的日誌配置：

ENV=production
LOG_LEVEL=info
ENABLE_REQUEST_LOGS=true
ENABLE_RESPONSE_LOGS=false

這樣可以保留基本請求資訊，又避免把完整回應內容寫入日誌。排查問題時可以臨時打開更詳細的日誌，但完成後應恢復，尤其不要在生產環境長期輸出請求體和回應體。

安全建議

CCX 是代理閘道，裡面會保存上游 API key，所以部署時不要只追求「能跑起來」。至少要注意這些點：

不要使用預設或過短的 PROXY_ACCESS_KEY。
建議單獨設定 ADMIN_ACCESS_KEY。
不要把 Web 管理介面直接暴露到公網。
如果必須公網存取，建議放在反向代理、VPN、存取控制或單點登入之後。
.env、.config、日誌檔案都不要提交到 Git 倉庫。
生產環境不要長期啟用完整請求體和回應體日誌。

可以用下面的方式產生隨機金鑰：

1
2

PROXY_ACCESS_KEY=$(openssl rand -base64 32)
ADMIN_ACCESS_KEY=$(openssl rand -base64 32)

適合誰使用

CCX 更適合這些場景：

同時維護 Claude、OpenAI、Gemini、Codex 或圖像介面。
有多個 API key，需要輪換、分流和故障轉移。
想用 Web UI 管理上游渠道，而不是手動改配置檔。
想觀察每個渠道的成功率、延遲和請求日誌。
想給團隊提供一個統一 AI API 入口。

如果你只是本機偶爾呼叫一個模型，直接用官方 SDK 或單一 OpenAI 相容代理會更簡單。CCX 的優勢主要在多渠道、多協定和統一維運。

小結

CCX 的定位是 AI API 閘道，而不是某個模型的客戶端。它把 Claude Messages、OpenAI Chat、OpenAI Images、Codex Responses 和 Gemini 放到一個代理層裡，並提供渠道編排、故障轉移、日誌監控和 Web 管理介面。

對個人使用者來說，它可以減少切換 API 地址和金鑰的麻煩；對團隊或長期執行的服務來說，它更像一個輕量級 AI 閘道。真正上線前，重點不只是配置模型，還要配置好金鑰、管理入口、日誌級別、渠道優先級和故障轉移策略。

參考

GitHub 專案：https://github.com/BenedictKing/ccx
架構說明：https://github.com/BenedictKing/ccx/blob/main/ARCHITECTURE.md
環境變數說明：https://github.com/BenedictKing/ccx/blob/main/ENVIRONMENT.md

CCX on KnightLi的博客