Cómo Usar Claude Code con OpenRouter

Si disfrutas del flujo de trabajo fluido de Claude Code (la herramienta CLI de Anthropic), probablemente sabes que, por defecto, espera el formato de la API de Anthropic. Pero, ¿qué pasa si quieres usar un modelo diferente o explorar nuevos modelos que no están disponibles a través de la API directa de Anthropic? ¡Y ahí es donde entra OpenRouter! Proporciona un acceso unificado a la API, compatible con OpenAI, a cientos de modelos de muchos proveedores diferentes.

Al unir los dos sistemas, puedes obtener lo mejor de ambos mundos: la interfaz amigable para desarrolladores de Claude Code y el amplio catálogo de modelos de OpenRouter. A esta integración nos referimos como "Claude Code con OpenRouter".

El truco consiste en usar un "enrutador / proxy" que traduce entre los dos formatos de API. Una vez que lo tienes configurado, puedes ejecutar Claude Code como de costumbre, pero con OpenRouter impulsando el backend.

Ventajas clave de usar Claude Code con OpenRouter

Combinar Claude Code y OpenRouter desbloquea una serie de potentes beneficios:

• Acceso a más de 400 modelos — incluyendo variantes de Claude, modelos estilo GPT, LLMs de código abierto y más.
• No se necesita suscripción a Anthropic — pagas solo por lo que usas a través del modelo de pago por uso de OpenRouter.
• Cambio de modelo flexible — cambia de modelo a mitad de sesión en Claude Code con /model, o enruta según el tipo de tarea (ligera vs. razonamiento, costo vs. rendimiento).
• Optimización de costos — modelos de bajo costo o gratuitos para tareas rutinarias, modelos potentes solo cuando sea necesario: ideal para desarrolladores conscientes del presupuesto.
• Enrutamiento local o basado en la nube — ejecuta todo localmente para privacidad, o aloja tu enrutador para uso compartido en equipo, CI/CD o automatización en la nube.
• Herramientas y flexibilidad — algunos enrutadores admiten funciones avanzadas como transmisión, respaldo de modelos, multiplexación de múltiples proveedores e integración con flujos de trabajo de desarrollo más amplios.

Requisitos previos

Antes de comenzar, asegúrate de tener:

1. Claude Code instalado globalmente (por ejemplo, a través de npm install -g @anthropic-ai/claude-code).

2. Una cuenta de OpenRouter con una clave API válida (sk-or-...) (Crea una cuenta en OpenRouter).

3. Una herramienta de enrutador/proxy (Docker es lo más fácil, pero los enrutadores basados en Node.js también funcionan) para manejar la conversión de formato.

4. Una familiaridad básica con el uso de variables de entorno y la línea de comandos.

Con esta configuración, podrás dirigir Claude Code al enrutador, que luego reenviará las solicitudes a OpenRouter y las respuestas de vuelta.

Método 1: y-router (el más sencillo y recomendado)

Uno de los enrutadores más utilizados para esta configuración es y-router. Actúa como un traductor entre el formato de API esperado de Anthropic y la API estilo OpenAI de OpenRouter (ver repositorio en: GitHub). Aquí te explicamos cómo hacerlo paso a paso con y-router:

1. Despliega y-router localmente (Docker recomendado):

git clone https://github.com/luohy15/y-router.git
cd y-router
docker compose up -d

Esto inicia un servicio de enrutador local escuchando (por defecto) en http://localhost:8787.

2. Configura tus variables de entorno para que Claude Code envíe sus solicitudes a y-router, no directamente a Anthropic:

export ANTHROPIC_BASE_URL="http://localhost:8787"
export ANTHROPIC_AUTH_TOKEN="sk-or-<your-openrouter-key>"
export ANTHROPIC_MODEL="z-ai/glm-4.5-air"   # para un modelo rápido y ligero
# o export ANTHROPIC_MODEL="z-ai/glm-4.5"   # para un modelo más potente

3. Ejecuta Claude Code:

claude

La interfaz se iniciará como de costumbre. Si escribes /model, verás seleccionado el modelo impulsado por OpenRouter. ¡Felicidades, ahora estás usando Claude Code con OpenRouter! (ishan.rs)

Este método mantiene el enrutamiento local, simple y bajo tu control, ideal para desarrolladores que aprecian la privacidad y una sobrecarga mínima.

Método 2: Claude Code Router (basado en npm, con muchas funciones)

Si prefieres no usar Docker, existe otra opción robusta: Claude Code Router, una herramienta de enrutador basada en Node.js diseñada para dar acceso a Claude Code a proveedores externos (ver repositorio en GitHub). Aquí te explicamos cómo configurarlo:

1. Instala globalmente:

npm install -g @musistudio/claude-code-router

Luego crea un archivo de configuración (por ejemplo, ~/.claude-code-router/config.json) con tus configuraciones y modelos preferidos. Muchos usuarios incluyen OpenRouter como proveedor, especificando su clave API y listando los modelos compatibles (más detalles sobre este método en lgallardo.com).

2. Inicia el enrutador:

ccr start

Una vez en funcionamiento, establece ANTHROPIC_BASE_URL a la URL del enrutador y usa claude como de costumbre. El enrutador traducirá las solicitudes y permitirá el cambio dinámico entre modelos, incluyendo el comportamiento de respaldo, reglas de enrutamiento y más.

Este método es potente si deseas más control sobre el enrutamiento de modelos, políticas de respaldo o integración en cadenas de herramientas más grandes (como CI/CD, scripts automatizados o experimentos con múltiples modelos).

Método 3: Proxy directo de OpenRouter (configuración mínima para pruebas rápidas)

Si solo quieres una verificación o prueba rápida, sin ejecutar un enrutador completo, puedes intentar dirigir Claude Code directamente a un proxy compatible con OpenRouter o a un adaptador mínimo. Existen algunas soluciones comunitarias para facilitar esto (ver su repositorio en GitHub).

Por ejemplo, podrías establecer:

export ANTHROPIC_BASE_URL="https://proxy-your-choice.com"
export ANTHROPIC_AUTH_TOKEN="sk-or-<your-key>"
export ANTHROPIC_MODEL="openrouter/model-name"

Luego, ejecuta Claude Code. Este enfoque es útil para pruebas efímeras o experimentos rápidos. Sin embargo, puede carecer de robustez (por ejemplo, para streaming, llamadas a herramientas o sesiones de larga duración), dependiendo de la implementación del proxy.

Mejores prácticas y consejos para una experiencia fluida

1. Verifica la compatibilidad del modelo — no todos los modelos admiten funciones avanzadas como llamadas a herramientas o ventanas de contexto largas. Usa modelos más ligeros para tareas sencillas, y modelos más capaces para tareas pesadas como el razonamiento o la codificación.
2. Asegura tu clave API — trata tu clave API de OpenRouter como un secreto; guárdala de forma segura y nunca la expongas en el lado del cliente.
3. Gestiona los costos — monitorea el uso de tokens al emplear modelos grandes; considera el almacenamiento en caché de prompts, modelos de respaldo o enrutamiento basado en tareas para optimizar el equilibrio costo/rendimiento.
4. Prueba la configuración de enrutamiento — después de la configuración, siempre prueba con comandos simples (por ejemplo, claude --model <model>) para asegurarte de que todo se enrute correctamente.
5. Usa el enrutamiento de respaldo para la fiabilidad — en configuraciones de múltiples modelos, configura opciones de respaldo para que si un modelo no está disponible, el enrutador pueda cambiar a otro automáticamente.

Preguntas frecuentes

P1. ¿Necesito pagar a Anthropic para usar Claude Code con OpenRouter?
No. Cuando se configura con OpenRouter (a través de un enrutador o proxy), Claude Code utiliza tu clave API de OpenRouter para las solicitudes; no necesitas una suscripción pagada a Anthropic.

P2. ¿Puedo cambiar de modelo sobre la marcha dentro de la misma sesión de Claude Code?
Sí. Muchos enrutadores (y el propio Claude Code) te permiten cambiar de modelo usando /model <nombre_del_modelo>. Esto funciona a mitad de la conversación en la mayoría de los casos.

P3. ¿Son todos los modelos de OpenRouter compatibles con las funciones de Claude Code (como la ejecución de herramientas, el streaming)?
No siempre. Algunos modelos "solo de texto" o más ligeros podrían no ser compatibles con las llamadas a herramientas, el contexto largo o el streaming. Para flujos de trabajo complejos, utiliza modelos que se sabe que admiten esas funciones.

P4. ¿Es un enrutador Docker local más seguro que uno alojado?
Generalmente sí. Ejecutar un enrutador localmente te da control total y evita exponer tu clave API a servicios externos. Los enrutadores alojados son convenientes, pero pueden presentar compromisos de seguridad o fiabilidad.

P5. ¿Puedo integrar esta configuración en CI/CD o flujos de trabajo automatizados?
Absolutamente. Herramientas como Claude Code Router admiten archivos de configuración y variables de entorno, lo que los hace fáciles de integrar en pipelines de automatización (GitHub Actions, scripts, etc.).

Conclusión

Usar Claude Code con OpenRouter es una forma elegante y potente de liberarte de los bloqueos de un solo proveedor, manteniendo una interfaz de desarrollador familiar y optimizada. Ya sea que elijas ejecutar un enrutador local a través de Docker, usar un enrutador basado en Node.js o probar a través de un proxy mínimo, estás abriendo la puerta a un enorme catálogo de modelos, opciones de costos flexibles y flujos de trabajo personalizados.

Para desarrolladores, proyectos paralelos o equipos que buscan optimizar la codificación asistida por IA sin grandes gastos generales, esta configuración ofrece un equilibrio convincente de control, flexibilidad y escalabilidad. Con solo unos pocos pasos de configuración, puedes expandir drásticamente lo que tu asistente de IA puede hacer, y luego cambiar o escalar a medida que tus necesidades evolucionan.

Pruébalo: tu próxima sesión de codificación pronto podría estar impulsada por un modelo que nunca creíste posible, todo bajo la familiar interfaz de Claude Code.