CCX es una pasarela de proxy y conversión de protocolos para APIs de IA. Coloca Claude Messages, OpenAI Chat Completions, OpenAI Images, Codex Responses y Gemini API detrás de una única entrada de servicio, y ofrece una interfaz web para configurar canales, claves, mapeos de modelos, prioridades, failover y monitoreo de tráfico.

Si usas Claude, OpenAI, Gemini y Codex al mismo tiempo, o mantienes varios servicios aguas arriba compatibles con OpenAI API, el valor de CCX está en unificar la entrada y la gestión. Los clientes se conectan a una sola dirección; CCX decide qué canal aguas arriba debe atender cada solicitud.

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

Qué problema resuelve CCX

Cuando se mezclan varias APIs de IA, aparecen rápidamente algunos problemas:

• Cada proveedor tiene rutas, autenticación y formatos de solicitud diferentes.
• Una misma clase de modelos puede tener varios upstreams, lo que obliga a cambiar manualmente base URL y API key.
• Cuando una clave o canal falla, el cliente normalmente no cambia automáticamente a un canal de respaldo.
• En equipos, cuesta centralizar allowlists de modelos, proxies, cabeceras personalizadas y logs.
• Al conectar Claude, Gemini, OpenAI Chat, APIs de imagen y Codex Responses, la configuración se dispersa.

La idea de CCX es concentrar esas diferencias en una capa proxy. Las herramientas frontend, scripts o servicios de negocio llaman a CCX; luego CCX enruta la solicitud al upstream adecuado según tipo de API, modelo, estado del canal, prioridad y salud.

Endpoints soportados

CCX expone una entrada backend unificada. El puerto predeterminado es 3000. Las rutas principales incluyen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

GET  /                         -> Interfaz web de administración
GET  /health                   -> Health check
/api/*                         -> API de administración
POST /v1/messages              -> Proxy de Claude Messages
POST /v1/chat/completions      -> Proxy de OpenAI Chat
POST /v1/responses             -> Proxy de Codex Responses
POST /v1/images/generations    -> Generación con OpenAI Images
POST /v1/images/edits          -> Edición con OpenAI Images
POST /v1/images/variations     -> Variaciones con OpenAI Images
GET  /v1/models                -> Lista de modelos
POST /v1beta/models/*          -> Proxy de Gemini

Es decir, CCX no se limita a un protocolo. Gestiona APIs comunes de IA como tipos de canal separados: Messages, Chat, Responses, Gemini e Images. Cada protocolo mantiene su propio estado de salud y espacio de logs, lo que ayuda al diagnóstico.

Arquitectura

CCX usa backend en Go y frontend en Vue 3. El build del frontend se incrusta en el binario del backend, por lo que puede desplegarse en un solo puerto: el mismo servicio ofrece Web UI, API de administración y API proxy.

Una solicitud pasa aproximadamente por esta cadena:

1

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

Los módulos principales:

• handlers: reciben solicitudes de distintos protocolos y operaciones de administración.
• providers: encapsulan el manejo de solicitudes y respuestas del upstream.
• converters: gestionan conversiones de protocolo en escenarios como Responses.
• scheduler: elige canales según prioridad, periodo promocional, salud, circuito abierto y afinidad de traza.
• metrics: registra volumen, tasa de éxito, latencia, logs y estado de circuit breaker.
• config: mantiene configuración en tiempo de ejecución, con hot reload y respaldo.

El objetivo no es forzar todas las APIs a un único formato, sino proxyar cada tipo de protocolo por separado y unificar gestión, planificación, logs y autenticación.

Diferencias entre CCX y CodexBridge

CCX y CodexBridge están relacionados con Codex y las APIs compatibles con OpenAI, pero resuelven problemas distintos.

CodexBridge es más bien un puente dedicado para Codex. Su objetivo principal es encapsular Codex CLI/SDK como un servicio /v1/chat/completions compatible con OpenAI, para que OpenWebUI, Cherry Studio, scripts u otros clientes compatibles puedan llamar a Codex local. En resumen, CodexBridge se centra en exponer Codex.

CCX se parece más a una pasarela unificada de APIs de IA. No solo maneja Codex Responses; también soporta Claude Messages, OpenAI Chat, OpenAI Images y Gemini API, con interfaz web, prioridad de canales, failover, monitoreo de logs y gestión de múltiples claves. En resumen, CCX se centra en gestionar varios modelos y proveedores juntos.

Comparación rápida:

Si solo quieres conectar Codex a OpenWebUI o Cherry Studio, CodexBridge es más directo. Si quieres gestionar Codex, Claude, Gemini, DeepSeek, Qwen, Kimi y otros upstreams juntos, CCX encaja mejor.

Despliegue rápido

La forma más sencilla es descargar el binario. Luego crea .env en el mismo directorio:

1
2
3
4

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

Tras iniciar, abre:

1

http://localhost:3000

Si desde WSL, Docker, PowerShell u otro entorno en Windows localhost no funciona, usa la IPv4 LAN del host Windows, por ejemplo:

1

http://192.168.1.23:3000

CCX escucha por defecto en :PORT para todas las interfaces, así que debes controlar el acceso si lo expones a la LAN.

Despliegue con Docker

Docker es adecuado para mantener el servicio en ejecución:

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

Si el repositorio ya incluye docker-compose.yml, también puedes ejecutar:

1

docker compose up -d

Para actualizaciones automáticas, añade la configuración de Watchtower:

1

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

Tras desplegar, .config guarda configuración de runtime y datos persistentes. Conviene montarlo en el host para no perder configuración al recrear el contenedor.

Ejecutar desde código fuente

Para desarrollo o builds personalizados:

1
2
3
4

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

Comandos comunes:

1
2
3
4

make dev
make run
make build
make frontend-dev

Desarrollo solo del frontend:

1
2
3

cd frontend
bun install
bun run dev

Desarrollo solo del backend:

1
2

cd backend-go
make dev

Variables de entorno clave

Una configuración mínima suele incluir:

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

Notas:

• PROXY_ACCESS_KEY se usa para la API proxy y debe cambiarse.
• ADMIN_ACCESS_KEY se usa para la Web UI y /api/*; conviene separarlo de la clave proxy.
• ENABLE_WEB_UI controla si la interfaz de administración está activa.
• REQUEST_TIMEOUT controla el timeout; aumenta el valor para contextos largos o tareas de imagen.
• LOG_LEVEL controla la verbosidad; en producción suele usarse info o warn.

Para limitar el tamaño del cuerpo:

1

MAX_REQUEST_BODY_SIZE_MB=50

La edición de imágenes, imágenes base64 y solicitudes multimodales pueden aumentar mucho el cuerpo.

Orquestación de canales y failover

La interfaz de CCX permite configurar múltiples canales, con opciones como:

• Tipo de servicio upstream.
• API key o rotación de múltiples claves.
• Dirección proxy.
• Cabeceras personalizadas.
• Allowlist de modelos.
• Prefijo de ruta.
• Prioridad.
• Health checks y recuperación de circuit breaker.

La planificación considera estado del canal, prioridad, periodo promocional, afinidad de traza, estado de circuit breaker y claves disponibles. En simple:

• Normalmente se usan primero los canales de mayor prioridad.
• Si un canal falla, CCX puede cambiar a un canal de respaldo.
• El circuit breaker evita seguir llamando a un upstream claramente no disponible.
• La afinidad de traza intenta mantener sesiones relacionadas en canales adecuados.

Estas funciones son útiles con múltiples claves, proveedores o upstreams regionales. Para uso personal ligero, también puedes configurar un solo canal y usar CCX como capa proxy con Web UI.

Logs y monitoreo

CCX ofrece métricas de canal y logs de solicitudes, incluyendo:

• Volumen de solicitudes.
• Tasa de éxito.
• Tasa de fallo.
• Latencia media.
• Historial por modelo.
• Estado de canales y circuit breakers.

En producción conviene una configuración de logs contenida:

1
2
3
4

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

Así conservas información básica sin escribir respuestas completas en logs. Para investigar problemas puedes activar logs más detallados temporalmente, pero después deberías volver a una configuración segura, sobre todo en producción.

Recomendaciones de seguridad

CCX es una pasarela proxy y almacena API keys aguas arriba, así que no basta con que “funcione”. Como mínimo:

• No uses un PROXY_ACCESS_KEY predeterminado o demasiado corto.
• Define un ADMIN_ACCESS_KEY separado.
• No expongas directamente la Web UI a internet.
• Si necesitas acceso público, colócala detrás de reverse proxy, VPN, control de acceso o SSO.
• No subas .env, .config ni logs a Git.
• No mantengas logs completos de cuerpo de solicitud y respuesta en producción.

Puedes generar claves aleatorias así:

1
2

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

Para quién es adecuado

CCX encaja mejor en estos escenarios:

• Mantener Claude, OpenAI, Gemini, Codex o APIs de imagen al mismo tiempo.
• Tener varias API keys que requieren rotación, enrutamiento y failover.
• Gestionar upstreams desde una Web UI en vez de editar archivos manualmente.
• Observar tasa de éxito, latencia y logs de cada canal.
• Proporcionar a un equipo una entrada AI API unificada.

Si solo llamas ocasionalmente a un modelo en tu equipo local, el SDK oficial o un proxy compatible con OpenAI más simple será suficiente. La ventaja de CCX está en múltiples canales, múltiples protocolos y operación unificada.

Resumen

CCX es una pasarela AI API, no un cliente para un modelo concreto. Coloca Claude Messages, OpenAI Chat, OpenAI Images, Codex Responses y Gemini en una capa proxy, y ofrece orquestación de canales, failover, logs, monitoreo y Web UI.

Para usuarios individuales, reduce la molestia de cambiar direcciones API y claves. Para equipos o servicios de larga duración, se parece más a una pasarela ligera de IA. Antes de producción, lo importante no es solo configurar modelos, sino también claves, entrada de administración, niveles de log, prioridades de canal y estrategia de failover.

Referencias

• Proyecto GitHub: https://github.com/BenedictKing/ccx
• Arquitectura: https://github.com/BenedictKing/ccx/blob/main/ARCHITECTURE.md
• Variables de entorno: https://github.com/BenedictKing/ccx/blob/main/ENVIRONMENT.md