Documentación

CC Switch

CC Switch cambia Claude Code y Codex entre proveedores desde una aplicación de escritorio. Kunavo se configura como Custom Configuration: raíz del servicio, autenticación Bearer, Messages de Anthropic nativo y sin enrutamiento local.

Tres campos y dos menús desplegables. https://api.kunavo.com como endpoint, tu clave sk-kn-… y —el detalle que la mayoría de las guías omiten— deja API Format en Anthropic Messages (Native) y Auth Field en ANTHROPIC_AUTH_TOKEN. Kunavo ofrece la API Messages de forma nativa, así que no hay enrutamiento local en el lado de Claude Code.

CC Switch → pestaña Claude Code → Añadir proveedor

Provider Name   Kunavo
API Key         sk-kn-...
API Endpoint    https://api.kunavo.com      <- service root, no /v1, no trailing slash

Advanced Options
  API Format    Anthropic Messages (Native) <- the default; do NOT switch
  Auth Field    ANTHROPIC_AUTH_TOKEN (Default)

El endpoint es la raíz del servicio: sin /v1 ni barra final. Los clientes de estilo Anthropic añaden /v1/messages por su cuenta; por eso este campo es distinto de todos los ejemplos de OpenAI, donde /v1 forma parte de la URL base. Consulta la explicación completa en la página ANTHROPIC_BASE_URL.

Paso a paso (pestaña Claude Code)

Cree una clave en /app/keys y cópiela: se muestra una sola vez.
Abre CC Switch en la pestaña principal Claude Code y haz clic en el botón más. Mantén Custom Configuration como opción predeterminada en lugar de elegir un ajuste preestablecido.
Completa Provider Name, API Key y API Endpoint = https://api.kunavo.com.
Despliega Advanced Options y confirma que API Format sea Anthropic Messages (Native) y que Auth Field sea ANTHROPIC_AUTH_TOKEN (Default). Ambos son los valores predeterminados; la idea es comprobarlos, no cambiarlos.
Guarda y luego Activate. La tarjeta no debería mostrar el indicador Needs Routing: ese indicador solo aparece en proveedores cuyo protocolo debe traducirse.

Por qué no aparece el indicador «Needs Routing»

El enrutamiento local de CC Switch sirve para conectar protocolos distintos. Claude Code envía solicitudes Anthropic Messages a /v1/messages; una pasarela que solo ofrece OpenAI Chat Completions o la API Responses no puede responderlas, así que la ruta convierte la solicitud al enviarla y convierte la respuesta al recibirla. Esa conversión adapta los eventos de streaming, las llamadas a herramientas y la configuración de razonamiento. Funciona, y añade otro componente entre tu editor y el modelo.

Kunavo ofrece POST /v1/messages directamente, así que en el lado de Claude Code no hay nada que convertir: el proveedor sigue siendo Anthropic Messages (Native) y la ruta no interviene. También ofrece POST /v1/chat/completions y POST /v1/responses con la misma clave, lo que permite la configuración de Codex que se explica a continuación.

Pestaña de CC Switch	Establece el formato en	Enrutamiento local
Claude Code	`Anthropic Messages (Native)`	No hace falta
Codex	`Anthropic Messages (routing required)`	Obligatorio: la ruta reescribe /responses como /v1/messages

Ejecutar modelos Claude dentro de Codex

Esta es la configuración que no cubren las guías de otros proveedores. Codex se comunica con la API OpenAI Responses, así que si lo apuntas directamente a un endpoint /v1/messages, recibirás un error 404. CC Switch lo resuelve manteniendo Codex en la ruta local y traduciendo las solicitudes. En la pestaña Codex no hay un ajuste preestablecido de Anthropic, así que también se trata de una Custom Configuration:

CC Switch → pestaña Codex → Añadir proveedor

Provider Name      Kunavo
API Key            sk-kn-...
API Request URL    https://api.kunavo.com
Default Model      claude-sonnet-5

Advanced Options
  Upstream Format  Anthropic Messages (routing required)

La guía de CC Switch incluye una advertencia que conviene repetir: algunos proveedores restringen su API Claude al cliente Claude Code, por lo que una clave de ese tipo podría generar un error al usarse a través de Codex. Kunavo no tiene esa restricción: la misma clave sk-kn-… permite usar la interfaz Messages y la interfaz Responses, y ninguna de las dos tiene una lista de clientes permitidos. Si prefieres omitir por completo la traducción, Codex CLI también puede conectarse directamente a la interfaz nativa /v1/responses de Kunavo; encontrarás ese procedimiento en la página de Codex CLI.

Asignación de modelos

CC Switch asigna los tres niveles de Claude Code a identificadores de modelo reales. Completa los tres campos y el Default fallback model: de lo contrario, las solicitudes que no coincidan se enviarán con el nombre original de Claude y generarán un error en el proveedor ascendente. Las tarifas están en USD por 1M de tokens, entrada / salida, y se consultan en vivo en el catálogo.

Nivel	ID de modelo	Entrada / salida de Kunavo	Por qué
Haiku	`claude-haiku-4-5`	$0.70 / $3.50	Claude Code dirige aquí las subtareas en segundo plano: el nivel más económico es el indicado
Sonnet	`claude-sonnet-5`	$1.40 / $7.00	La opción predeterminada para editar
Opus	`claude-opus-5-5`	$2.80 / $14.00	Cambios a nivel de arquitectura

Deja desmarcada la casilla 1M a menos que el nivel realmente admita una ventana de un millón de tokens. Declarar un contexto que el proveedor ascendente no admite no amplía nada: solo traslada el fallo a un punto avanzado de una conversación larga.

Verifica antes de depurar la aplicación

Un par de solicitudes permite determinar si el fallo se debe a la clave, al endpoint o a CC Switch. Si ambas devuelven 200, cualquier problema restante está en un campo del formulario, casi siempre en Auth Field o en un /v1 que no debería estar en el endpoint.

# Settles whether a failure is the key, the endpoint, or CC Switch.
# 200 + a JSON list of model ids means the same key works in the app.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

# The Anthropic face, which is the one the Claude Code tab actually calls.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Referencia

CC Switch es de código abierto y está disponible en github.com/farion1231/cc-switch. Los nombres de los campos y el comportamiento descritos arriba proceden de sus propias guías: la guía de enrutamiento de Claude Code y la guía de enrutamiento de Codex, ambas indican que se aplican a la versión 3.17.0 y posteriores. En versiones anteriores, el formulario es distinto; consulta la sección «Acerca de» de la aplicación si falta alguno de los campos mencionados. La configuración de Kunavo está documentada en la API Messages, Chat Completions y el centro de integraciones.

Preguntas frecuentes

¿Cómo añado un proveedor personalizado en CC Switch?

En la pestaña Claude Code, haz clic en el botón más, deja seleccionada la opción predeterminada Custom Configuration y completa Provider Name, API Key y API Endpoint. API Endpoint es la raíz del servicio de la pasarela, sin una barra final: para Kunavo, https://api.kunavo.com, sin /v1. Después, abre Advanced Options y comprueba dos campos: API Format y Auth Field. Esos dos determinan si el proveedor funciona y son los que la mayoría de las guías de configuración omiten.

¿Tengo que activar el enrutamiento local de CC Switch para Kunavo?

No. El enrutamiento local sirve para traducir entre protocolos: convierte la solicitud /v1/messages de Claude Code a OpenAI Responses o Chat Completions cuando el proveedor ascendente solo admite esos protocolos. Kunavo ofrece de forma nativa la API Anthropic Messages en https://api.kunavo.com/v1/messages, así que API Format se mantiene en el valor predeterminado Anthropic Messages (Native), la tarjeta del proveedor no muestra el indicador Needs Routing y las solicitudes van directamente al proveedor ascendente. Una pasarela que solo ofrezca Chat Completions debe usar la ruta local para cada solicitud.

¿Por qué API Endpoint no incluye /v1, a diferencia de los ejemplos de OpenAI?

Porque las dos convenciones difieren deliberadamente. Los clientes de estilo Anthropic añaden /v1/messages por su cuenta, así que solo necesitan el origen: https://api.kunavo.com. Los SDK de OpenAI esperan que /v1 ya esté en base_url, así que necesitan https://api.kunavo.com/v1. La pestaña Claude Code de CC Switch usa el protocolo de Anthropic, por eso se omite /v1. Confundir estos formatos es el error de configuración más habitual en todos los clientes; la página ANTHROPIC_BASE_URL explica ambos formatos.

¿Debo establecer Auth Field en ANTHROPIC_API_KEY?

No: conserva el valor predeterminado ANTHROPIC_AUTH_TOKEN. Con ese valor, CC Switch envía Authorization: Bearer <key>. Si eliges ANTHROPIC_API_KEY, envía en su lugar un encabezado x-api-key, que Kunavo también acepta; por tanto, el encabezado no es el problema, sino la autorización. Antes de usar ANTHROPIC_API_KEY en una sesión interactiva, Claude Code solicita una autorización única. Si la rechazas, después ignora la clave: se produce un error de autenticación que parece deberse a una clave incorrecta, aunque la clave sea válida.

¿Puedo ejecutar modelos Claude en Codex mediante CC Switch?

Sí; esta es la parte que suelen omitir las guías de proveedores. En la pestaña Codex, añade una Custom Configuration con la URL de solicitud de API https://api.kunavo.com y un modelo predeterminado como claude-sonnet-5; luego, en Advanced Options, establece Upstream Format en Anthropic Messages (routing required). El enrutamiento local debe estar activado para este sentido, porque Codex usa la API Responses y la ruta reescribe /responses como /v1/messages. La guía de CC Switch advierte que algunos proveedores limitan su API de Claude al cliente Claude Code y esas claves fallan con Codex. Kunavo no tiene esa limitación: la misma clave sk-kn- sirve para ambos.

¿Qué ID de modelo debo introducir en la asignación de modelos de CC Switch?

Utiliza los identificadores de catálogo de Kunavo. Una buena división predeterminada es claude-haiku-4-5 ($0.70 / $3.50 por 1 M de tokens) en el nivel Haiku, porque Claude Code envía allí las subtareas en segundo plano; claude-sonnet-5 ($1.40 / $7.00) en Sonnet; y claude-opus-5-5 ($2.80 / $14.00) en Opus. Completa siempre también el modelo de reserva predeterminado: si lo dejas vacío, CC Switch pasa las solicitudes no coincidentes con el nombre original de Claude y estas fallan en el upstream. La lista actualizada está en GET /v1/models.

¿Dónde guarda CC Switch mi clave de API?

En su propio almacén, no en la configuración del cliente. CC Switch guarda los proveedores en ~/.cc-switch/cc-switch.db y, cuando el enrutamiento local toma el control de un cliente, solo escribe la dirección de la ruta local en ~/.claude/settings.json, con un marcador de posición en la entrada de autenticación. La ruta inyecta la clave real al reenviar cada solicitud. Esta característica pertenece a CC Switch, no a Kunavo; conviene saberlo porque la clave que pegas no es la que aparece en el archivo que quizá estés a punto de incluir en un commit.