English | 简体中文
CCX is a high-performance AI API proxy and protocol translation gateway for Claude, OpenAI Chat, OpenAI Images, Codex Responses, and Gemini. It provides a unified entrypoint, built-in web administration, channel orchestration, failover, multi-key management, and model routing.
- Integrated backend + frontend architecture with single-port deployment
- Dual-key authentication with PROXY_ACCESS_KEY and optional ADMIN_ACCESS_KEY
- Web admin console for channel management, testing, logs, and monitoring
- Support for Claude Messages, OpenAI Chat Completions, OpenAI Images, Codex Responses, and Gemini APIs
- Smart scheduling with priorities, promotion windows, health checks, failover, and circuit recovery
- Context routing filters candidate channels by actual model context window and max output capability
- Per-channel API key rotation, proxy support, custom headers, model allowlists, and route prefixes
- Responses session tracking for multi-turn workflows
- Embedded frontend assets for simple binary deployment
Thanks to Youyun Zhisuan for sponsoring this project! Youyun Zhisuan is UCloud’s AI cloud platform, offering cost-effective domestic AI model Agent Plan packages by monthly subscription or pay-as-you-go, starting from 49 CNY/month. It also provides stable access to official overseas models, supports Claude Code, Codex, and API integrations, and offers enterprise-grade high concurrency, 24/7 technical support, and self-service invoicing. Users who register through this link can receive a free 5 CNY platform trial credit. Thanks to RunAPI for sponsoring this project! RunAPI is an efficient and stable API platform—an alternative to OpenRouter. A single API Key gives you access to 150+ leading models, including OpenAI, Claude, Gemini, DeepSeek, Grok, and more, at prices as low as 10% of the original (up to 90% off), with exceptional stability. It’s seamlessly compatible with tools like Claude Code, OpenClaw, and others. RunAPI offers an exclusive perk for CCX users: register and contact an administrator to claim ¥7 in free credit. Thanks to Unity2.ai for sponsoring this project! Unity2.ai is a high-performance AI model API relay platform for individual developers, teams, and enterprises. It serves top domestic companies with over 30 billion tokens per day and supports 5000+ RPM concurrency. A single API Key seamlessly integrates with Claude Code, Codex, OpenAI models, IDE plugins, and Agent workflows. With enterprise-grade stable supply, it maintains low latency and high availability under high concurrency and sustained usage. It supports balance billing, subscription plans, first-recharge bonuses, enterprise invoicing, and dedicated 1v1 support—ideal for both individual high-frequency use and long-term enterprise integration. Register now to claim $2 balance, join the official group for an additional $10, totaling up to $12 in free credits. Register at: https://unity2.ai/register?source=ccx
Visual channel management with drag-and-drop priority adjustment and real-time health monitoring.
Supports multiple upstream service types and flexible API key, model mapping, and request parameter configuration.
Real-time monitoring of per-channel request traffic, success rate, and latency.
CCX exposes one backend entrypoint:
Images endpoints currently include:
- POST /v1/images/generations
- POST /v1/images/edits
- POST /v1/images/variations
See ARCHITECTURE.md for the detailed design.
CCX Desktop provides a native desktop experience with GUI for managing channels, keys, and agent configuration.
Platform Install Method Notes Windows Search CCX Desktop in Microsoft Store Recommended. Auto-update, no manual signing. Also available as setup.exe from GitHub Releases. macOS brew tap BenedictKing/ccx && brew install -cask ccx-desktop Or download .dmg (arm64/amd64) from GitHub Releases. Linux Download .AppImage from GitHub Releases Mark as executable and run.
See CCX Desktop Guide for detailed setup instructions.
- Download the latest binary from Releases.
- Create a .env file next to the binary:
- Run the binary and open http://localhost:3000
On Windows, if the client runs from cmd, PowerShell, WSL, or Docker and localhost does not reach CCX, use the Windows host IPv4 address instead, for example http://192.168.1.23:3000. CCX listens on all interfaces by default through :PORT.
For background startup without Docker, see Service Startup.
Run in the background with Docker Compose:
Enable Watchtower auto-update:
Pull the latest image immediately after setup if needed:
Prerequisites: Go 1.25+, Bun, and Make (macOS: xcode-select -install).
Useful commands:
- Web UI: GET /
- Health: GET /health
- Admin API: /api/*
- Claude Messages: POST /v1/messages
- OpenAI Chat: POST /v1/chat/completions
- Codex Responses: POST /v1/responses
- OpenAI Images: POST /v1/images/generations, POST /v1/images/edits, POST /v1/images/variations
- Gemini: POST /v1beta/models/{model}:generateContent
- Models API: GET /v1/models
Recommended local workflow:
Frontend only:
Backend only:
- CCX Desktop
- Client Setup
- CCX Desktop (中文)
- Client Setup (中文)
- README.zh-CN.md
- backend-go/README.md
- ARCHITECTURE.md
- DEVELOPMENT.md
- ENVIRONMENT.md
- docs/service/README.md – non-Docker service startup
- RELEASE.md
Join the QQ group for discussion: 642217364
MIT