Claude Code Router — dirige Claude Code a cualquier modelo o prescinde completamente del router

La mayoría de las personas que buscan Claude Code Router quieren una de dos cosas distintas: enrutar Claude Code entre varios proveedores de modelos o simplemente ejecutar Claude Code en un lugar más barato que el precio de lista de Anthropic. Solo la primera opción necesita el router. Claude Code lee ANTHROPIC_BASE_URL de forma nativa, así que la segunda requiere tres variables de entorno y ningún software adicional.

Esta guía cubre ambas rutas, con los nombres exactos de las variables, la trampa de las credenciales que produce un 401 silencioso y una lista honesta de lo que deja de funcionar detrás de cualquier pasarela. Si has leído recientemente otro artículo sobre CCR, ve primero a Opción B: el config.json que esos artículos te indican editar ya no es la configuración que lee el router.

¿Cuál necesitas realmente?

El router es un servicio local: un proceso más que ejecutar, configurar y mantener actualizado y, desde 2026, una aplicación de escritorio con su propia interfaz en lugar de un archivo que editas. Justifica ese coste cuando realmente necesitas enrutamiento entre varios proveedores, contabilidad por solicitud o selección de modelos a nivel de subagente. No lo justifica cuando habría bastado con una URL base.

Opción A: cambiar la URL base (sin instalación)

Kunavo sirve la API Anthropic Messages nativa en /v1/messages, que es el endpoint al que llama Claude Code. Dirígelo allí:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL solo es el origen; Claude Code añade /v1/messages por sí mismo, así que no incluyas una ruta. Conserva las líneas de los modelos: el valor predeterminado integrado de Claude Code y su alias opus apuntan al Opus más reciente, y si Kunavo aún no ofrece ese modelo, la primera solicitud devuelve 404. El alias sonnet solicita Sonnet 5.5, que Kunavo no ofrece, por lo que sin la línea ANTHROPIC_DEFAULT_SONNET_MODEL /model sonnet, la fase de ejecución de opusplan y cualquier subagente configurado con model: sonnet devuelven 404. El alias opus está fijado en Opus 5.5 (claude-opus-5-5), lo que requiere Claude Code v2.1.280 o posterior; ejecuta claude update si tu versión es anterior. Obtén la clave del panel de control después de registrarte y añadir $10 de saldo; se muestra una sola vez.

Qué variable de credencial usar y por qué importa

Claude Code envía las dos variables de credenciales en cabeceras HTTP diferentes, y una clave en la cabecera que el servidor no lee falla con 401:

Prefiere ANTHROPIC_AUTH_TOKEN por una razón concreta: ANTHROPIC_API_KEY necesita una aprobación única en una sesión interactiva, y una clave que rechazaste una vez se ignora después sin mostrar ninguna solicitud; es un fallo confuso en el que la variable está claramente establecida y claramente no se usa. El descubrimiento de modelos no decide esto en Kunavo. El descubrimiento de modelos de la pasarela de Claude Code envía solo el token bearer cuando se establece ANTHROPIC_AUTH_TOKEN y usa x-api-key como alternativa; el endpoint /v1/models de Kunavo lee la clave desde cualquiera de las dos cabeceras.

Haz que persista

Las exportaciones del shell solo se aplican a ese terminal y a todo lo que se inicie desde él; un editor abierto desde el dock no las verá, ni tampoco los agentes en segundo plano. Coloca los valores en un archivo de configuración para cubrirlo todo:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Usa ~/.claude/settings.json para todos los proyectos. Nunca pongas una clave en el .claude/settings.json de un proyecto: ese archivo se confirma en el repositorio.

Verifica antes de confiar en ello

Prueba primero el endpoint directamente, para que un fallo apunte a la configuración y no a Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Después, inicia claude desde el mismo shell y ejecuta /status. Una línea Anthropic base URL que muestre api.kunavo.com y una línea Auth token que nombre tu variable confirman que ambas partes están activas.

Establece un modelo personalizado: elige explícitamente el slug

Kunavo resuelve los slugs de modelos mediante una coincidencia exacta y no crea alias para nombres con fecha, por lo que claude-sonnet-4-5-20250929 devuelve 404 mientras que claude-sonnet-5 funciona. Establece siempre ANTHROPIC_MODEL en lugar de depender del valor predeterminado integrado:

Las variables de alias permiten enrutar por tarea sin ningún router: ANTHROPIC_DEFAULT_OPUS_MODEL respalda el alias opus y el modo de planificación, ANTHROPIC_DEFAULT_SONNET_MODEL respalda sonnet y la fase de ejecución de opusplan, y ANTHROPIC_DEFAULT_HAIKU_MODEL respalda haiku además del trabajo en segundo plano de Claude Code —los resúmenes y títulos que acumulan costes silenciosamente. Apuntar esa variable a claude-haiku-4-5 es la línea de mayor valor de toda la configuración. (ANTHROPIC_SMALL_FAST_MODEL es la denominación obsoleta de la misma configuración.)

Opcional: muestra todos los modelos en el selector

Establece CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) y Claude Code consulta GET /v1/models al iniciarse, añadiendo lo que encuentra al selector /model etiquetado como From gateway. Kunavo sirve ese endpoint, por lo que aparece cada modelo de Claude habilitado y /model se convierte en un menú activo en lugar de una lista que mantienes manualmente. Cualquiera de las dos variables de credenciales funciona para ello; consulta la explicación anterior.

Opción B: claude-code-router, tal como funciona ahora

Empieza aquí, porque casi todo lo escrito sobre CCR describe una versión que ya no existe. Antes, el router era un archivo JSON y un comando ccr code. Ahora es un plano de control local con una aplicación de escritorio, una interfaz de administración, registros de solicitudes y una pasarela de modelos, y el config.json que aparece en todos los tutoriales ya no lo configura.

CCR mantiene su configuración de ejecución en ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite en Windows). Un config.json heredado se lee una vez, como fuente de migración, cuando todavía no existe una configuración SQLite. Después de esa primera ejecución, editarlo no afecta a la configuración en ejecución, sin ningún error ni advertencia. El bloque Providers que pegaste cuidadosamente simplemente no es la configuración.

Eso incluye esta página antes del 2026-09-06: el fragmento JSON que solía estar aquí era incorrecto, y era el tipo de error que cuesta una tarde, porque nada te indica que se ignoró. La configuración ahora se realiza en la interfaz de usuario (o, como respaldo, Settings → Export data; no copies archivos SQLite activos mientras CCR esté ejecutándose).

Instalar e iniciar

CCR se distribuye de dos formas: una aplicación de escritorio desde GitHub Releases (bandeja del sistema, actualización automática e integraciones de escritorio) y una CLI de npm para implementaciones sin interfaz o supervisadas. Ambas comparten el mismo directorio de configuración.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Añadir Kunavo requiere una entrada de proveedor — Providers → Add provider, el ajuste predefinido Other / custom API endpoint, el endpoint https://api.kunavo.com y tu clave sk-kn- — y un perfil de Agent Config → Add profile → Claude Code. La versión campo por campo, incluidos Check Connection y el descubrimiento de modelos, está en la página de integración de Claude Code Router. El resto de esta sección cubre lo que esa página no explica: las credenciales, los costes y los modos de fallo.

Tres credenciales y de cuál se trata un 401

Esta es la forma más habitual en que una configuración funcional parece estar rota. CCR tiene tres secretos independientes y cada uno autentica un salto distinto:

La correspondencia de puertos también confunde: la administración usa de forma predeterminada 127.0.0.1:3458 y la puerta de enlace de modelos, 127.0.0.1:3456. Una URL base dirigida a 3458 llega a la interfaz, no a la puerta de enlace. (Docker agrupa deliberadamente ambos servicios detrás de un único endpoint de Nginx, por eso las instrucciones de Docker son diferentes). Una interfaz accesible no implica que la puerta de enlace funcione: comprueba /health en la dirección de la puerta de enlace y confirma que Server muestre Running.

El mapa por nivel es lo importante

Claude Code no solicita un modelo, sino un nivel: el bucle principal necesita Sonnet u Opus, mientras que el trabajo en segundo plano (subagentes, búsquedas, resúmenes y títulos de conversaciones) necesita el modelo pequeño y rápido. Un perfil de Claude Code en Agent Config expone estos valores en campos independientes: un Model predeterminado y, opcionalmente, sustituciones para Fable, Opus, Sonnet y Haiku, cada una con un valor Provider/model. Si dejas un nivel vacío, Claude Code lo selecciona.

Lee esa tabla antes de copiar el mapa de niveles de otra persona, porque la división obvia es la primera palanca: claude-sonnet-5 cuesta un 50% menos que claude-opus-5-5 en Kunavo ($1.40 / $7.00 frente a $2.80 / ). La segunda palanca es el nivel Haiku: a $0.70 / $3.50 es 2× más barato que Sonnet 5, y absorbe un volumen que nunca ves: cada subagente, cada pasada de clasificación de archivos, cada título generado. claude-sonnet-4-6 ya no es el Sonnet barato: a $2.10 / $10.50 cuesta un 50% más que Sonnet 5, por eso los fragmentos anteriores establecen ANTHROPIC_MODEL=claude-sonnet-5.

Enrutamiento de subagentes: lo que el mapa de niveles no puede hacer

Las sustituciones de nivel fijan todos los subagentes a un único modelo. CCR puede ser más preciso: cuando una solicitud de Claude Code coincide con la ruta integrada, inserta la lista de modelos disponibles en la descripción de la herramienta Agent / Task, y Claude Code antepone al prompt de cada agente generado una etiqueta con el modelo que quiere:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR elimina la etiqueta y enruta esa solicitud en consecuencia, de modo que un subagente de búsqueda puede ejecutarse en Haiku mientras uno de revisión se ejecuta en Opus, elegido por tarea en lugar de quedar fijado. El interruptor es fácil de pasar por alto: el mecanismo está desactivado hasta que al menos un modelo tenga una Description en la página Models. Sin descripciones, CCR no inserta nada y todos los subagentes vuelven silenciosamente al modelo predeterminado del perfil. Escribe las descripciones según la tarea: «búsqueda de código, clasificación de archivos, subagentes paralelos económicos» para Haiku; «análisis de arquitectura, revisión de alto riesgo» para Opus. Cuando funciona, los registros de solicitudes muestran builtin:claude-code-subagent como motivo de la ruta.

Elección del protocolo y su coste en caché

CCR sondea el endpoint y elige un protocolo de red. Proporciónale el origen sin más https://api.kunavo.com y se comunicará mediante Anthropic Messages; proporciónale https://api.kunavo.com/v1 y utilizará el formato compatible con OpenAI. Ambas superficies están activas con la misma clave, y puedes anular la detección automática en la configuración avanzada.

Prefiere el formato Anthropic Messages. Mantiene cache_control en las solicitudes transmitidas, por lo que el almacenamiento en caché de prompts llega al modelo y la entrada almacenada en caché se factura al 10 % de la tarifa de entrada (cómo funciona): en un bucle de agente que reenvía un prefijo estable en cada paso, es el mayor ahorro individual disponible. La salvedad honesta es que un router en la ruta sigue editando las solicitudes: CCR elimina el mensaje del sistema de encabezado de facturación que Claude Code inyecta y añade la lista de modelos a las descripciones de herramientas cuando el enrutamiento de subagentes está activado. Ambos elementos se encuentran antes de tus puntos de ruptura de caché, así que cada cambio en ese contenido cuesta un fallo de caché mientras se calienta el nuevo prefijo. Después se mantiene estable, pero es una razón real por la que la opción A almacena en caché ligeramente mejor que la opción B, además de tener menos componentes que ejecutar.

Alternativa: reintento frente a conmutación por error

Conviene configurar Default on failure de la página Routing antes de necesitarlo. Retry reenvía al mismo modelo en 408, 409, 429 y 5xx, respetando Retry-After y, en caso contrario, aplicando una espera exponencial de 1 s hasta un máximo de 30 s. Fallback targets recorre una lista ordenada de modelos de respaldo y se activa ante cualquier código 4xx o 5xx, bajo la premisa de que la ausencia del modelo o el rechazo del proveedor podrían afectar solo al destino actual. Las reglas individuales pueden anular la configuración global. Cuando se ejecuta una alternativa, la respuesta incluye x-ccr-fallback-attempts y x-ccr-fallback-model para que puedas identificarlo posteriormente.

Verifica que realmente esté en la ruta

Inicia Claude Code desde el perfil, envía un mensaje y abre después Request logs en CCR. La fila muestra request model (lo que solicitó Claude Code), resolved provider y resolved model (adónde se envió); esa triple coincidencia es la prueba. Dentro de la CLI, /model muestra los modelos que expone CCR. Si Claude Code responde pero no aparece ninguna fila en el registro, lo iniciaste por tu cuenta en lugar de hacerlo mediante CCR, y el alcance del perfil es Only opened from CCR.

Cuánto cuesta una sesión de programación

Claude Code reenvía el prompt del sistema, la conversación y el contexto de archivos actualizado en cada paso, por lo que la tarifa por token se acumula rápidamente. A las tarifas de Kunavo para claude-sonnet-5:

Eso supone aproximadamente un 30% de descuento en el modelo principal, antes del almacenamiento en caché de prompts. Las tarifas completas están en la guía de precios de la API de Claude, y la calculadora de costes utiliza tus propios recuentos de tokens.

Qué sigue funcionando y qué no

Dirigir Claude Code a cualquier puerta de enlace cambia algunas cosas. La lista es breve y conviene conocerla antes de comprometerte:

En la última fila: el recuento de tokens es el único endpoint que la especificación de puerta de enlace de Anthropic marca como opcional, y Claude Code estima localmente el uso del contexto cuando no está disponible. Kunavo no ofrece /v1/messages/count_tokens actualmente, por lo que tu cifra de /context es una estimación, no un recuento exacto. Nada se degrada más allá de ese número: la compactación automática y la sesión en sí no se ven afectadas.

Solución de problemas

La ruta de la URL base

…y cuando el router está en la ruta

Las correcciones específicas de cada error de la API están en las páginas de solución de problemas invalid API key y rate limit.

Preguntas frecuentes