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的博客