CCX：Claude/Codex/Gemini API 代理网关

这是什么

CCX 是一个基于 Go 语言开发的高性能 AI API 代理与协议转换网关。它旨在为 Claude、OpenAI Chat、OpenAI Images、Codex Responses 以及 Gemini 等主流大模型服务提供一个统一的接入入口。

该项目采用后端 + 前端一体化的架构，支持单端口部署，并内置了 Web 管理控制台。通过 CCX，开发者和管理员可以集中管理多个上游服务商的 API Key，实现流量调度、故障转移（Failover）以及模型路由，从而简化多模型集成的复杂度。

解决的问题

在当前的 AI 应用开发中，开发者通常面临以下痛点：

1. 多模型接入碎片化：不同的大模型提供商（如 Anthropic、OpenAI、Google）使用不同的 API 协议和端点。集成多个模型需要编写大量的适配代码，维护成本高。
2. 密钥管理混乱：随着业务扩展，需要管理多个服务商的多个 API Key。手动轮换密钥、处理限流或故障切换变得极其困难。
3. 缺乏统一的监控与治理：分散的 API 调用使得追踪请求成功率、延迟以及整体流量分布变得复杂，难以进行精细化的成本控制和性能优化。
4. 部署与维护繁琐：传统的微服务架构可能需要单独部署前端、后端、数据库等多个组件，对于中小型项目或个人开发者来说，运维负担较重。

CCX 通过提供一个标准化的中间层，将上述问题统一解决，允许客户端只需对接 CCX 的一个标准接口，即可访问背后所有的 AI 模型服务。

核心功能

• 统一协议转换：
  • 将 Claude Messages、OpenAI Chat Completions、Codex Responses、OpenAI Images 和 Gemini API 的请求转换为上游服务商所需的格式。
  • 暴露标准的 /v1/messages、/v1/chat/completions、/v1/responses、/v1/images/* 等端点，兼容主流客户端库。
• 智能流量调度与高可用：
  • 优先级调度：支持为不同渠道设置优先级。
  • 故障转移（Failover）：当主用渠道不可用时，自动切换至备用渠道。
  • 熔断与恢复：内置健康检查机制，支持电路熔断与自动恢复，防止雪崩效应。
  • 促销窗口：支持在特定时间段内提升某些渠道的优先级。
• 多密钥管理与轮换：
  • 支持每个渠道配置多个 API Key，并自动进行轮换，以应对单 Key 的速率限制（Rate Limiting）。
  • 支持代理（Proxy）设置、自定义请求头、模型白名单及路由前缀配置。
• 双重认证机制：
  • PROXY_ACCESS_KEY：用于客户端访问 API 代理。
  • ADMIN_ACCESS_KEY（可选）：用于访问 Web 管理控制台，保障管理安全。
• 内置 Web 管理控制台：
  • 提供可视化的渠道管理界面，支持拖拽调整优先级。
  • 实时监控系统健康状态、各渠道的请求流量、成功率和延迟。
  • 支持日志查看和模型测试。
• 会话追踪：
  • 支持多轮对话工作流的响应会话追踪，便于调试和分析上下文管理。

亮点 / 与同类相比

• 单体架构，极简部署： 与许多需要依赖 Kubernetes、Redis 或独立数据库的复杂网关不同，CCX 采用嵌入式前端资源的单体架构。只需一个二进制文件或一个 Docker 容器即可运行，极大地降低了部署门槛。
• 开箱即用的多模型支持： 原生支持 Claude、OpenAI (Chat/Images/Codex) 和 Gemini。无需编写额外的适配器代码，即可享受统一的 API 体验。
• 灵活的客户端兼容性： 除了提供 API 代理，CCX 还推出了 CCX Desktop 桌面应用，并提供了详细的客户端配置指南。这意味着它不仅是一个后端网关，还能直接作为 AI 客户端的前置代理，兼容支持 OpenAI 协议的第三方客户端（如 ChatGPT-Next-Web, LobeChat 等）。
• 完善的监控与可视化： 内置的 Web UI 提供了实时的渠道健康监控和流量统计，这是许多轻量级代理工具所缺乏的。管理员可以直观地看到哪个渠道响应慢、哪个渠道报错多，从而快速做出调整。
• 跨平台与容器化支持： 提供 Windows、macOS、Linux 的二进制文件，以及 Docker 镜像和 Docker Compose 配置。支持 Watchtower 自动更新，适合各种运行环境。

适合谁用 / 上手

适合人群：

• 独立开发者 / 小团队：希望快速集成多个 AI 模型，但不想维护复杂的微服务架构。
• AI 应用开发者：需要构建支持多模型切换的聊天应用或工作流，需要一个稳定的代理层来处理密钥轮换和故障转移。
• 企业 IT 管理员：需要集中管理公司内部的 AI 模型访问权限，控制成本，并监控 API 使用情况。
• 追求高可用的用户：依赖单一模型存在风险，希望通过多 Key 轮换和故障转移提高服务稳定性。

快速上手指南：

1. 下载二进制文件： 从 GitHub Releases 页面下载最新版本的 CCX 二进制文件。Windows 用户也可关注 Microsoft Store 版本。

2. 配置环境变量： 在二进制文件同级目录下创建 .env 文件：

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

3. 启动服务：

   • 直接运行：执行二进制文件，然后访问 http://localhost:3000。
     • 注意：如果在 Windows 的 cmd/PowerShell/WSL/Docker 中访问 localhost 失败，请尝试使用宿主机的 IPv4 地址（如 http://192.168.1.23:3000）。
   • Docker 运行：

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

   • Docker Compose：

     docker compose up -d
     

4. 配置渠道： 登录 Web 管理控制台，添加上游服务商（如 OpenAI、Anthropic）的 API Key，配置模型映射，并调整优先级。

5. 客户端对接： 在你的 AI 客户端（如 CCX Desktop 或第三方聊天客户端）中，将 API 地址指向 CCX 的地址，并填入 PROXY_ACCESS_KEY 即可开始使用。