CCX is an AI API proxy and protocol-conversion gateway. It puts Claude Messages, OpenAI Chat Completions, OpenAI Images, Codex Responses, and Gemini API behind one service entry point, while also providing a web management UI for configuring channels, keys, model mappings, priorities, failover, and traffic monitoring.

If you use Claude, OpenAI, Gemini, and Codex at the same time, or maintain multiple upstream services compatible with OpenAI API, CCX is valuable because it gives you one entry point and one management layer. Clients connect to a single service address; CCX decides which upstream channel should handle each request.

Project: https://github.com/BenedictKing/ccx

What problem does CCX solve?

When multiple AI APIs are used together, several problems appear quickly:

• Each provider has different paths, authentication, and request formats.
• One class of models may have multiple upstreams, requiring manual switching of base URL and API key.
• When a key or channel fails, the client usually does not automatically switch to a backup channel.
• In team use, it is hard to centrally manage model allowlists, proxies, custom headers, and request logs.
• When Claude, Gemini, OpenAI Chat, image APIs, and Codex Responses all need to coexist, configuration becomes scattered.

CCX’s approach is to consolidate these differences into a proxy layer. Frontend tools, scripts, or business services call CCX; CCX then routes the request to a suitable upstream based on API type, model, channel status, priority, and health.

Supported endpoints

CCX exposes one backend entry point. The default port is 3000. Main paths include:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

GET  /                         -> Web management UI
GET  /health                   -> Health check
/api/*                         -> Management API
POST /v1/messages              -> Claude Messages proxy
POST /v1/chat/completions      -> OpenAI Chat proxy
POST /v1/responses             -> Codex Responses proxy
POST /v1/images/generations    -> OpenAI Images generation
POST /v1/images/edits          -> OpenAI Images editing
POST /v1/images/variations     -> OpenAI Images variations
GET  /v1/models                -> Model list
POST /v1beta/models/*          -> Gemini proxy

In other words, CCX does not proxy only one protocol. It manages common AI APIs as separate channel types: Messages, Chat, Responses, Gemini, and Images. Different protocols do not share the same health state or log space, which matters when troubleshooting.

Architecture overview

CCX uses a Go backend and Vue 3 frontend. The frontend build is embedded into the backend binary, so it can be deployed on a single port: the same service provides the Web UI, management API, and proxy API.

A request roughly follows this path:

1

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

The main modules can be understood as follows:

• handlers: receive requests for different protocols and management operations.
• providers: wrap upstream API request and response handling.
• converters: handle protocol conversion for scenarios such as Responses.
• scheduler: choose channels based on priority, promotion period, health state, circuit breaker state, and trace affinity.
• metrics: record request counts, success rate, latency, logs, and circuit breaker state.
• config: maintain runtime configuration, with hot reload and backup support.

The design is not about forcing every API into one format. It proxies each protocol type separately, while unifying management, scheduling, logging, and authentication.

CCX vs CodexBridge

CCX and CodexBridge are both related to Codex and OpenAI-compatible APIs, but they solve different problems.

CodexBridge is more like a dedicated Codex bridge. Its main goal is to wrap Codex CLI/SDK as an OpenAI-compatible /v1/chat/completions service, so OpenWebUI, Cherry Studio, scripts, or other OpenAI-compatible clients can call local Codex. In short, CodexBridge focuses on exposing Codex.

CCX is more like a unified AI API gateway. It does not only handle Codex Responses; it also supports Claude Messages, OpenAI Chat, OpenAI Images, and Gemini API, with a web management UI, channel priority, failover, log monitoring, and multi-key management. In short, CCX focuses on managing multiple models and providers together.

Quick comparison:

If you only want to connect Codex to OpenWebUI or Cherry Studio, CodexBridge is more direct. If you want to manage Codex, Claude, Gemini, DeepSeek, Qwen, Kimi, and other upstreams together, CCX is a better fit.

Quick deployment

The simplest way is to download the binary. After downloading it, create .env in the same directory:

1
2
3
4

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

After startup, open:

1

http://localhost:3000

If localhost does not work from WSL, Docker, PowerShell, or another Windows environment, use the Windows host’s LAN IPv4 address instead, for example:

1

http://192.168.1.23:3000

By default, CCX listens on :PORT for all network interfaces, so access control matters if it is exposed to a LAN.

Docker deployment

Docker is suitable for long-running service deployment:

1
2
3
4
5
6
7

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

If the repository already has docker-compose.yml, you can also run:

1

docker compose up -d

For automatic updates, add the Watchtower configuration:

1

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

After deployment, .config stores runtime configuration and persistent data. Mount it to the host to avoid losing configuration when the container is recreated.

Running from source

For development or custom builds:

1
2
3
4

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

Common commands:

1
2
3
4

make dev
make run
make build
make frontend-dev

Frontend-only development:

1
2
3

cd frontend
bun install
bun run dev

Backend-only development:

1
2

cd backend-go
make dev

Key environment variables

Minimal usable configuration usually includes:

1
2
3
4
5
6
7
8

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

Notes:

• PROXY_ACCESS_KEY is used for the proxy API and must be changed.
• ADMIN_ACCESS_KEY is used for the Web UI and /api/*; it should be separate from the proxy key.
• ENABLE_WEB_UI controls whether the management UI is enabled.
• REQUEST_TIMEOUT controls request timeout; increase it for long-context or image tasks.
• LOG_LEVEL controls log verbosity; production usually uses info or warn.

To limit request body size, check:

1

MAX_REQUEST_BODY_SIZE_MB=50

Image editing, base64 images, and multimodal requests can all increase request body size.

Channel orchestration and failover

The CCX management UI can configure multiple channels, with options such as:

• Upstream service type.
• API key or multi-key rotation.
• Proxy address.
• Custom request headers.
• Model allowlist.
• Route prefix.
• Priority.
• Health checks and circuit-breaker recovery.

Scheduling considers channel state, priority, promotion period, trace affinity, circuit-breaker state, and available keys. In simple terms:

• Under normal conditions, higher-priority channels are used first.
• If one channel fails, CCX can fail over to a backup channel.
• Circuit breaking avoids repeatedly hitting an obviously unavailable upstream.
• Trace affinity tries to keep related sessions on suitable channels.

These features are useful when you have multiple keys, providers, or regional upstreams. For personal lightweight use, you can also configure only one channel and use CCX as a proxy layer with a Web UI.

Logs and monitoring

CCX provides channel metrics and request logs, including:

• Request volume.
• Success rate.
• Failure rate.
• Average latency.
• Historical data by model.
• Channel status and circuit-breaker state.

For production, use relatively conservative logging:

1
2
3
4

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

This keeps basic request information while avoiding full response content in logs. You can temporarily enable more detailed logs for troubleshooting, but restore the safer configuration afterward, especially in production.

Security recommendations

CCX is a proxy gateway and stores upstream API keys, so deployment should not stop at “it runs.” At minimum:

• Do not use a default or short PROXY_ACCESS_KEY.
• Set a separate ADMIN_ACCESS_KEY.
• Do not expose the Web UI directly to the public internet.
• If public access is required, place it behind a reverse proxy, VPN, access control, or SSO.
• Do not commit .env, .config, or log files to Git.
• Do not keep full request and response body logging enabled in production.

You can generate random keys like this:

1
2

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

Who should use it?

CCX is better suited to these scenarios:

• Maintaining Claude, OpenAI, Gemini, Codex, or image APIs at the same time.
• Having multiple API keys that need rotation, routing, and failover.
• Managing upstream channels through a Web UI instead of editing config files manually.
• Observing success rate, latency, and logs for each channel.
• Providing one unified AI API entry point for a team.

If you only call one model occasionally on your own machine, the official SDK or a single OpenAI-compatible proxy is simpler. CCX’s advantage is multi-channel, multi-protocol, unified operation.

Summary

CCX is an AI API gateway, not a client for one specific model. It puts Claude Messages, OpenAI Chat, OpenAI Images, Codex Responses, and Gemini into one proxy layer, with channel orchestration, failover, logs, monitoring, and a Web management UI.

For individuals, it reduces the trouble of switching API addresses and keys. For teams or long-running services, it is closer to a lightweight AI gateway. Before production use, the important work is not only configuring models, but also securing keys, the management entry point, logging levels, channel priority, and failover strategy.

References

• GitHub project: https://github.com/BenedictKing/ccx
• Architecture notes: https://github.com/BenedictKing/ccx/blob/main/ARCHITECTURE.md
• Environment variables: https://github.com/BenedictKing/ccx/blob/main/ENVIRONMENT.md