Claude Code Router 3.1.1: instalación, rutas y solución de errores

Quieres que Claude Code use DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM u otro endpoint compatible, pero la guía que encontraste todavía habla de config.json y ccr code. O quizá la interfaz abre, pero el gateway en 127.0.0.1:3456 nunca llega a funcionar. Esta guía sigue el flujo actual de la versión 3.1.1 y te lleva desde la instalación hasta un perfil de Claude Code verificado, con una ruta clara para diagnosticar cada fallo habitual.

Empieza por la versión: 3.1.1 ya no gira alrededor de un config.json escrito a mano

Configura proveedores, rutas y Agent Profiles desde la Web UI en lugar de copiar un bloque JSON antiguo. A 26 de septiembre de 2026, la etiqueta latest de npm apunta a la versión 3.1.1. El paquete actual guarda la configuración principal en config.sqlite y genera gateway.config.json para el gateway en ejecución, según los metadatos del registro de npm y el README actual del proyecto.

Esta diferencia de versión explica dos callejones sin salida frecuentes. La referencia actual de la CLI inicia un agente con ccr <profile-name-or-id> y no incluye ccr code. Además, gateway.config.json es un archivo generado, no la fuente que debes mantener manualmente. Si un tutorial exige config.json o ccr code, comprueba para qué generación de CCR fue escrito antes de interpretar el error como un problema de instalación.

Prepara Node.js, un proveedor upstream y Claude Code

Necesitas Node.js 22 o posterior, acceso a un servicio de modelos y Claude Code instalado localmente. CCR enruta peticiones; no instala Claude Code y el acceso mediante API no equivale a una suscripción de Claude.ai o Claude Max.

Comprueba primero Node.js:

node --version

Actualiza Node.js si la versión principal es inferior a 22. El upstream puede ser un preset integrado, como OpenRouter, DeepSeek, Gemini, Moonshot/Kimi o Z.AI, o un endpoint personalizado que implemente un protocolo OpenAI-compatible o Anthropic-compatible admitido.

Instala la CLI de npm y verifica el comando antes de configurar nada

Ejecuta la ayuda justo después de la instalación global. Así separas un problema de npm o de PATH de un problema de Provider o Routing.

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

Para actualizar o desinstalar:

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

Desinstalar el paquete de npm no borra la configuración ni las bases de datos locales. El directorio de datos es ~/.claude-code-router en macOS/Linux y %APPDATA%\claude-code-router en Windows.

Configura en este orden: Provider → Check Connection → Client Key → Routing → Server → Profile → prueba integral

Haz funcionar una sola ruta predeterminada antes de añadir condiciones o modelos fallback. Si configuras a la vez varios proveedores, rewrites, retries y fallbacks, será difícil distinguir un 401 de un Model ID inválido o de un protocolo incorrecto.

Abre la interfaz de administración:

ccr ui

La UI usa por defecto http://127.0.0.1:3458 y el gateway de modelos http://127.0.0.1:3456. Utiliza la URL autenticada que CCR imprime o abre. Si 3458 ya está ocupado, CCR puede elegir otro puerto de administración y mostrar la dirección real.

1. Añade el upstream en Providers

Usa un preset cuando exista y recurre a custom endpoint solo cuando sea necesario. En Providers → Add Provider, selecciona el servicio, introduce la API Key propia de ese proveedor, elige el protocolo correcto y añade Model ID disponibles para tu cuenta.

No deduzcas el protocolo por el nombre comercial del modelo. Anthropic Messages, OpenAI Chat/Responses y Gemini utilizan formatos distintos. Base URL, protocolo y Model ID deben coincidir con la documentación actual del upstream.

Después de guardar el Provider, ejecuta Check Connection. Es una comprobación exclusiva del upstream; no demuestra toda la ruta Claude Code → CCR gateway → Routing → Provider.

2. Crea una CCR client key en API Keys

Una CCR client key no es el management token. El management token protege la Web UI y la RPC API; la client key autentica las peticiones de modelo que Claude Code envía al gateway. Trata como contraseña cualquier URL que contenga ccr_web_token y no la pegues en logs, tickets o chats.

3. Define primero una ruta predeterminada

Apunta la ruta predeterminada a un solo Provider que haya superado Check Connection y a un modelo de ese Provider. Guarda la ruta, pero todavía no envíes la petición desde Claude Code: inicia primero el gateway y crea el Agent Profile.

Después de que funcione la petición integral del paso 6, añade condiciones, retries, rewrites o fallbacks ordenados en Routing. Agrega un comportamiento cada vez y vuelve a probar. El modelo fallback también debe admitir las herramientas, el contexto y el protocolo que requiere la tarea; dos modelos no son intercambiables solo porque ambos conversen.

4. Inicia y comprueba el gateway en Server

Que la UI esté abierta no demuestra que el gateway de 3456 sea utilizable. En Server, inicia el gateway y anota la URL orientada al cliente que se muestra. La predeterminada es http://127.0.0.1:3456; usa la URL real que indique CCR. Si falla el arranque, ejecuta CCR en primer plano para ver el error:

ccr serve

La salida en primer plano permite distinguir un conflicto de puerto de un Provider incompleto, un modelo ausente o un problema de permisos en los archivos locales.

5. Crea y habilita un Agent Profile de Claude Code

La CLI actual inicia Claude Code mediante un Agent Profile habilitado. En Agent Profiles, crea un perfil para Claude Code, elige el modelo usado por la ruta predeterminada del Provider que superó Check Connection, guárdalo y actívalo. En modo CCR, Claude Code se conecta al CCR gateway que aparece en Server (por defecto http://127.0.0.1:3456), no a la URL del Provider upstream. Puedes darle cualquier nombre, por ejemplo Claude - Review.

Inícialo por nombre o ID:

ccr "Claude - Review"

Coloca los argumentos propios de Claude Code después de -- para que CCR no los interprete como opciones suyas:

ccr "Claude - Review" cli -- --model sonnet

Sustituye Claude - Review por el nombre o ID real de tu perfil.

6. Envía una petición desde Claude Code y revisa Logs

Ahora sí haces la primera prueba integral real. Desde el Profile iniciado, envía una petición sencilla en Claude Code y comprueba en Logs que se seleccionaron el Provider y el modelo previstos y que el estado fue correcto.

Check Connection del Provider solo cubre la conexión upstream. La petición real también valida la CCR client key, el gateway, Routing, el Agent Profile y la llamada al modelo.

Entiende la diferencia entre ccr start, ui, serve y stop

Usa ccr ui o ccr start en el trabajo diario y ccr serve para diagnosticar.

Comando	Mejor uso	Qué hace
ccr start	Servicio persistente en segundo plano	Inicia el servicio de administración y el gateway en modo detached, y muestra una URL autenticada
ccr ui	Configuración interactiva local	Reutiliza o inicia el servicio en segundo plano y abre la UI
ccr serve	Diagnóstico o process supervisor	Se mantiene en primer plano para mostrar errores de arranque y peticiones; ccr web es un alias
ccr stop	Recrear ajustes del servicio	Detiene el servicio detached iniciado por start o ui

start, ui y serve aceptan --host, --port, --open/--no-open y --gateway/--no-gateway. Su opción --port se refiere al puerto preferido de administración, no necesariamente al gateway de modelos de 3456.

Corrige “ccr: command not found” revisando Node y el bin global de npm

Verifica el runtime y el prefijo global antes de reinstalar una y otra vez. Ejecuta:

node --version
npm prefix -g

Confirma que Node.js sea 22 o posterior y que el directorio global de ejecutables de npm esté incluido en el PATH de la shell actual. Abre un terminal nuevo después de instalar, porque algunas shells almacenan en caché las ubicaciones de los comandos.

Si también instalaste la aplicación de escritorio, recuerda que esta proporciona el comando relacionado ccr-app. El paquete npm instala ccr; que exista ccr-app no demuestra que la CLI de npm esté en el PATH.

Corrige un gateway que no escucha en 127.0.0.1:3456

Primero averigua si el gateway no arrancó o si otro proceso ya ocupa el puerto. Una UI sana en 3458 no dice nada sobre 3456.

En macOS/Linux:

lsof -nP -iTCP:3456 -sTCP:LISTEN

En Windows:

netstat -ano | findstr :3456

Si un proceso antiguo de CCR u otro programa posee el puerto, identifica el PID antes de detenerlo. Después ejecuta ccr serve, vuelve a Server y confirma que existen un Provider, un modelo y una client key antes de iniciar otra vez el gateway.

Corrige 401, model not found y errores de protocolo comprobando tres correspondencias

Revisa credenciales, protocolo y Model ID en ese orden. Entre los fallos más comunes están usar el management token como client key, poner una CCR client key en el Provider upstream o llamar a un endpoint Anthropic-compatible mediante una ruta OpenAI-compatible.

Sigue esta secuencia:

1. Claude Code se autentica ante CCR con una CCR client key, no con ccr_web_token.
2. La entrada de Provider almacena la API Key propia del upstream.
3. El protocolo seleccionado coincide con el endpoint.
4. El Model ID enrutado existe para ese proveedor y esa cuenta.
5. Logs resuelve el Provider y el modelo que esperabas.

No te quedes solo con el mensaje final de Claude Code. CCR Logs puede mostrar si el fallo ocurrió en la autenticación del cliente, la resolución de ruta, la autenticación upstream o la propia petición al modelo.

Corrige perfiles ausentes y servicios en segundo plano con opciones antiguas

Solo se pueden iniciar Agent Profiles habilitados. Los nombres se comparan sin distinguir mayúsculas y se aceptan nombres normalizados, pero un nombre ambiguo exige el ID. Vuelve a guardar el perfil si falta el launcher generado.

Un proceso en segundo plano reutilizado no adopta nuevos ajustes de host, port o gateway. Deténlo y créalo de nuevo:

ccr stop
ccr start --host 127.0.0.1 --port 3458

Por eso un comando puede terminar correctamente mientras el servicio continúa con los ajustes del día anterior.

Usa ANTHROPIC_BASE_URL directamente cuando solo necesites un endpoint

La conexión directa suele ser más sencilla con un único endpoint Anthropic-compatible, un modelo principal y sin necesidad de rutas condicionales, fallback, logs compartidos o varios perfiles. Sigue la documentación de Claude Code del proveedor para configurar ANTHROPIC_BASE_URL, su variable de autenticación y el mapeo del modelo, sin añadir un gateway local.

CCR encaja mejor cuando se cumple cualquiera de estas condiciones:

• alternas entre DeepSeek, OpenRouter, Gemini, Kimi, Z.AI o endpoints personalizados;
• distintas tareas o perfiles deben usar modelos diferentes;
• necesitas retries, rutas condicionales, rewrites o fallback ordenado;
• quieres inspeccionar rutas resueltas, estado, tokens, latencia y errores en un solo lugar;
• varios clientes deben compartir un gateway local.

Situación	Opción recomendada
Un endpoint Anthropic-compatible estable	ANTHROPIC_BASE_URL directo
Varios proveedores, modelos o perfiles	CCR
Necesitas visibilidad de la ruta de cada petición	CCR
Solo quieres la vía más rápida a un servicio	Empieza directo y migra a CCR cuando crezca el flujo

Ejemplo de endpoint compatible: añadir BetterToken a CCR

BetterToken es un posible Provider Anthropic-compatible personalizado, no la única respuesta. En Providers de CCR, introduce https://bettertoken.ai en el campo upstream API endpoint/Base URL —no en la Base URL de Claude Code— y no añadas /v1. Selecciona explícitamente Anthropic Messages, introduce tu propia BetterToken API Key y un Model ID disponible, guarda el Provider y ejecuta Check Connection.

Al usar CCR, Claude Code se conecta al CCR gateway mostrado en Server, normalmente http://127.0.0.1:3456. Inicia el Agent Profile, envía una petición y confirma en Logs que se enruta al modelo de BetterToken previsto. No apuntes Claude Code directamente a https://bettertoken.ai en este modo, porque omitirías CCR.

Solo si decides omitir CCR y conectarte directamente a este único endpoint debes seguir la documentación de BetterToken para Claude Code y definir la Base URL en macOS/Linux:

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

En PowerShell:

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

En ese modo directo, la variable de autenticación y el mapeo del modelo siguen viniendo de la documentación actual. No reutilices para Claude Code la Base URL OpenAI-compatible https://www.bettertoken.ai/v1.

Protege las credenciales locales y haz copias de seguridad con seguridad

Mantén el listener de administración en 127.0.0.1 salvo que el acceso remoto sea intencional. Para acceso remoto, utiliza un firewall o una red privada y TLS en un reverse proxy de confianza. No expongas el gateway al exterior sin CCR client keys.

Las credenciales upstream, los logs y las bases de runtime viven en el directorio local de CCR. No edites ni copies config.sqlite mientras CCR escribe en él. Usa la exportación de la UI o detén CCR antes de hacer una copia del sistema de archivos.

Verifica toda la ruta, no solo la interfaz

El éxito significa que una petición de Claude Code siguió la ruta prevista y devolvió una respuesta normal. Comprueba:

• node --version muestra 22 o posterior;
• ccr --help funciona;
• Providers contiene al menos un upstream que superó Check Connection;
• API Keys contiene una CCR client key;
• Server muestra el gateway activo y su URL orientada al cliente (por defecto http://127.0.0.1:3456);
• el Agent Profile está guardado y habilitado;
• ccr <profile-name-or-id> inicia Claude Code;
• se envió una petición real desde Claude Code y Logs muestra el Provider, el modelo y un estado correcto;
• cada nueva ruta o fallback se ha vuelto a probar.

Este orden mantiene separadas la instalación, la autenticación, el enrutamiento y el inicio del agente. Cuando algo falla, puedes corregir la capa responsable en lugar de reinstalar CCR o editar al azar un config.json obsoleto.