CLIProxyAPI: envolver Codex, Claude Code y Gemini CLI en una API unificada

Sun, 24 May 2026 10:03:33 +0800

CLIProxyAPI es un proyecto con mucho sabor a ingeniería práctica de comunidad. No es otro gran modelo, ni un simple reenviador de API. Lo que hace es volver a empaquetar un conjunto de herramientas de IA que originalmente son interactivas, orientadas a CLI o basadas en login OAuth, para exponerlas como un servicio API unificado.

Soporta Gemini CLI, OpenAI Codex, Claude Code, Amp CLI, AI Studio Build y servicios ascendentes compatibles con OpenAI. Dicho de otra forma, intenta resolver esta pregunta:

Tengo herramientas CLI, cuentas de suscripción y sesiones OAuth. ¿Puedo conectar esas capacidades a mi propio cliente, scripts, IDE o servicios internos como si llamara a una API normal?

La respuesta de CLIProxyAPI es sí: añadir una capa proxy en medio y convertir capacidades CLI de distintas fuentes en interfaces compatibles con OpenAI, Gemini, Claude y Codex.

El problema real que resuelve

Muchas herramientas de programación con IA son potentes, pero su forma de uso por defecto no encaja bien con la automatización.

Por ejemplo:

Gemini CLI puede usarse con login de cuenta, pero tu programa probablemente prefiera llamar a una API HTTP.
Claude Code es muy útil para programación interactiva, pero al integrarlo con otros clientes aparecen diferencias de protocolo.
Codex CLI soporta login OAuth y capacidades estilo Responses, pero no todas las herramientas superiores saben cómo hablar con él.
Un equipo puede tener varias cuentas y necesitar rotación, balanceo de carga, exclusión de cuentas anómalas y visibilidad de cuotas.
Quizá quieras que algunas herramientas solo vean un formato OpenAI, aunque el backend real sea Gemini, Claude o Codex.

CLIProxyAPI se posiciona como una capa de adaptación de protocolo entre esas herramientas y los clientes.

Oculta el lado complejo detrás: OAuth, login CLI, varias cuentas, diferentes protocolos y distintos providers. En la parte frontal expone interfaces más familiares, como OpenAI Chat Completions, OpenAI Responses, Gemini, Claude Messages y endpoints relacionados con Codex.

Resumen de capacidades

Según el README y la documentación oficiales, CLIProxyAPI se centra actualmente en:

Ofrecer endpoints API compatibles con OpenAI, Gemini, Claude y Codex para modelos CLI.
Conectar OpenAI Codex y Claude Code mediante login OAuth.
Soportar respuestas en streaming y sin streaming, además de WebSocket en algunos escenarios.
Soportar function calling, tool calling y entrada multimodal.
Soportar rotación de varias cuentas y balanceo de carga para Gemini, OpenAI y Claude.
Soportar claves API de Gemini AI Studio.
Soportar pools de cuentas para AI Studio Build, Gemini CLI, Claude Code y OpenAI Codex.
Conectar upstreams compatibles con OpenAI mediante configuración, por ejemplo OpenRouter.
Ofrecer un SDK en Go para incrustar la capacidad proxy en tus propios servicios.

El valor de este tipo de proyecto no está en “soportar unos cuantos nombres de modelo más”, sino en empaquetar login de cuentas, traducción de protocolos y enrutamiento de solicitudes.

Para quién encaja

CLIProxyAPI encaja mejor con varios tipos de usuarios.

El primer grupo son usuarios intensivos de programación con IA. Ya usas Codex, Claude Code y Gemini CLI, pero quieres conectarlos a Cursor, Cline, RooCode, Amp, scripts internos o flujos de trabajo propios.

El segundo grupo son usuarios con pools de varias cuentas. Por ejemplo, tienes varias sesiones de Gemini, OpenAI o Claude y no quieres cambiar manualmente. Quieres rotación automática, uso equilibrado y diagnóstico rápido cuando una cuenta falla.

El tercer grupo son quienes construyen gateways internos para equipos. El equipo no quiere que cada cliente adapte por separado Gemini, Claude y Codex, sino exponer una API unificada mediante una capa intermedia.

El cuarto grupo son quienes disfrutan trabajando con protocolos. Te puede interesar cómo convertir entre Responses, Chat Completions, Claude Messages y Gemini v1beta, o quizá quieras alternar backends desde el mismo cliente.

Si solo haces preguntas ocasionales a la IA, o solo usas las apps oficiales para chatear, el coste de desplegar y mantener CLIProxyAPI puede parecer excesivo.

En qué se diferencia de un proxy API normal

Un proxy API típico suele ser:

`1`	`Cliente -> API proxy -> API del modelo upstream`

La cadena de CLIProxyAPI se parece más a:

`1`	`Cliente -> CLIProxyAPI -> CLI / sesión OAuth / pool de cuentas -> servicio de modelo`

La diferencia es que no solo reenvía API keys. También maneja herramientas CLI, cuentas OAuth, superficies de protocolo y alias de modelos.

Herramientas como Codex y Claude Code no siguen exactamente el patrón tradicional de “dame una API key y puedo llamarlo de forma estable”. CLIProxyAPI envuelve esas sesiones de login y la lógica de llamada para que clientes externos puedan acceder a ellas como si fueran APIs normales.

Eso es lo que lo hace atractivo, y también lo que lo vuelve complejo.

Malentendidos comunes al usarlo

Primero, no asumas que un /v1/... unificado elimina todas las diferencias de protocolo.

La documentación de CLIProxyAPI recuerda que, cuando necesitas la forma de solicitud y respuesta de un tipo concreto de backend, conviene usar rutas provider-specific. Por ejemplo, para estilo messages usa /api/provider/{provider}/v1/messages; para rutas de modelo Gemini usa /api/provider/{provider}/v1beta/models/...; para estilo chat-completions usa /api/provider/{provider}/v1/chat/completions.

Una entrada unificada es cómoda, pero la semántica de cada protocolo no desaparece. Tool calling, respuestas en streaming, entrada multimodal y manejo de mensajes de sistema pueden variar según el backend.

Segundo, el nombre del modelo no identifica de forma única el backend.

Si varios backends exponen el mismo nombre de modelo visible para el cliente, la ruta por sí sola puede no fijar cuál ejecuta realmente la inferencia. Para fijarlo estrictamente, usa alias únicos, prefijos, o evita que varios backends expongan el mismo nombre de modelo.

Tercero, la rotación de varias cuentas no significa cuota infinita.

La rotación solo reparte mejor el uso entre el pool de cuentas. No evita los límites reales del servicio upstream. Cuentas anómalas, cuota agotada, controles de riesgo y sesiones OAuth expiradas necesitan monitoreo separado.

Cuarto, no es una caja mágica sin mantenimiento.

Una vez que lo incorporas a tu flujo diario, tendrás que preocuparte por configuración, logs, estado de cuentas upstream, actualizaciones, compatibilidad de clientes y límites de seguridad.

Gestión y monitoreo

El README oficial indica que desde v6.10.0, CLIProxyAPI y CPAMC ya no incluyen estadísticas de datos integradas. Si necesitas estadísticas de uso, puedes combinarlo con proyectos independientes:

CPA Usage Keeper: sincroniza datos de CLIProxyAPI, los guarda en SQLite y ofrece API de agregación y dashboard.
CLIProxyAPI Usage Dashboard: panel local-first de uso y cuotas, con cuentas, modelos, ventanas de tiempo y cuota restante de Codex.
CPA-Manager: centro de gestión más completo para monitoreo de solicitudes, estimación de costes, inspección de pools de cuentas, localización de cuentas anómalas y sugerencias de limpieza.

Esto muestra que el núcleo de CLIProxyAPI está más cerca de una capa de proxy y protocolo que de un backend comercial todo en uno. Si lo usa un equipo, conviene pensar desde el principio en logs, monitoreo y gestión de cuentas.

Una forma razonable de probarlo

Si quieres probarlo, un orden sensato sería:

Levantarlo con el Quick Start de la documentación oficial.
Conectar solo un provider, por ejemplo Gemini CLI o Codex, y confirmar que las solicitudes básicas funcionan.
Probar después capacidades de mayor riesgo, como streaming, tool calling y entrada multimodal.
Confirmar qué endpoint usa realmente el cliente, sin mezclar rutas de protocolo.
Añadir al final rotación de varias cuentas, paneles de gestión y estadísticas de uso.

No conectes desde el principio Gemini, Codex, Claude, OpenRouter, varias cuentas y todos los clientes a la vez. Cuando algo falle, será difícil saber si el problema es autenticación, protocolo, nombre de modelo o cuenta upstream.

También hay que pensar en el límite de seguridad

CLIProxyAPI puede tocar sesiones de login de cuentas, API keys, credenciales OAuth y contenido de solicitudes. Si solo corre en tu propia máquina, el riesgo es relativamente controlable. Si lo expones a internet o a una intranet de equipo, debes tratar en serio la autenticación, el control de acceso, el enmascaramiento de logs y el aislamiento de red.

Los endpoints de administración, en especial, deberían limitarse a localhost o a una red interna confiable. No expongas interfaces de administración directamente solo por ahorrar tiempo.

Conclusión

El valor de CLIProxyAPI está en reunir capacidades de IA dispersas entre múltiples CLI, cuentas y protocolos en una capa API programable.

Encaja con usuarios intensivos de programación con IA, usuarios con varias cuentas y escenarios de gateway interno para equipos. Encaja menos con usuarios ligeros que solo quieren algo de “abrir y usar” sin mantenimiento.

Si estás experimentando con Codex, Claude Code y Gemini CLI, y quieres conectarlos a tu propio cliente o flujo de automatización, CLIProxyAPI merece una mirada seria. Pero conviene tratarlo como infraestructura, no como una pequeña herramienta desechable.

Referencias:

Gemini CLI on KnightLi Blog