Claude Code: cambiar de proveedor con CC Switch en 5 minutos

Este tutorial está basado en CC Switch v4.0.26 (noviembre de 2026). Las etiquetas de los botones pueden cambiar en versiones posteriores; el modelo de configuración es estable.

Cambiar de proveedor en Claude Code suele implicar editar ~/.claude/settings.json: la URL base, la clave de API y, a veces, el modelo. Con un solo proveedor, es manejable. Con dos o tres, se convierte en una pequeña tarea de mantenimiento, y el problema puede pasar desapercibido: una variable ANTHROPIC_* obsoleta exportada en la shell puede sobrescribir el archivo que acabas de editar.

CC Switch convierte el cambio en una tarjeta que puedes pulsar. Su preset integrado de AiHubMix completa el endpoint y tú pegas una clave de API. Por lo general, Claude Code recarga el cambio sin reiniciarse. Este tutorial explica toda la configuración y, luego, qué escribe CC Switch, la trampa de las variables de entorno y cuándo basta con el modo directo.

Si solo quieres la versión breve: instala CC Switch, crea una clave de AIHubMix, elige el preset de AiHubMix en Claude Code, pega la clave, añade ANTHROPIC_MODEL=claude-sonnet-5-5 al proveedor, pulsa Cambiar y ejecuta claude -p "1+1, output only the answer" --model claude-sonnet-5-5. El resto de esta publicación explica esos pasos en detalle.

Qué es CC Switch

CC Switch es una aplicación de escritorio de código abierto (MIT, Tauri + Rust + React) para administrar configuraciones de proveedores en Claude Code, Codex, Gemini CLI, OpenCode y otras herramientas de programación. Incluye más de 90 presets de proveedores y admite proveedores personalizados.

Es más que un selector de claves:

• El modo directo reescribe los campos de clave en el archivo de configuración del cliente y permite que este se comunique con el proveedor.
• El modo de enrutamiento ejecuta una pasarela local en 127.0.0.1:15721, con conversión de formatos de API, conmutación por error, comprobaciones de estado y registros de solicitudes.
• El modo de agregación reúne modelos de varios proveedores en una sola lista de /model.

El repositorio y el manual de usuario están en github.com/farion1231/cc-switch. Solo ccswitch.io y la página GitHub Releases son fuentes oficiales de descarga; cualquier sitio que solicite un pago o las credenciales de una cuenta no lo es.

Antes de empezar

Necesitas tres cosas:

• Claude Code instalado y ejecutable desde una terminal. Compruébalo con claude --version. Si no está instalado, usa el instalador oficial: curl -fsSL https://claude.ai/install.sh | bash, o bien npm i -g @anthropic-ai/claude-code con Node.js 22 o posterior.
• Una cuenta de AIHubMix y una clave de API. Crea una en la consola de AIHubMix. La clave suele empezar por sk-.
• Un instalador de CC Switch. Descárgalo desde ccswitch.io o GitHub Releases.

Paso 1: Instala CC Switch

Al iniciar por primera vez, CC Switch importa la configuración existente de Claude Code como un proveedor llamado default y añade un proveedor oficial. Tu configuración original no se pierde; puedes volver a ella en cualquier momento.

Si aún no tienes Claude Code instalado, la página Aplicaciones de CC Switch puede instalarlo o actualizarlo.

Paso 2: Crea una clave de API de AIHubMix

Abre la página de claves de API de AIHubMix, crea una clave y cópiala.

El marcador de posición AIHUBMIX_API_KEY de la documentación no es una clave real. Si lo pegas tal cual, la solicitud falla con 401 invalid key: AIHUBMIX_API_KEY.

Paso 3: Añade AIHubMix a Claude Code

1. Selecciona Claude Code en la barra lateral izquierda.
2. Pulsa el botón + de la esquina superior derecha.
3. Busca AiHubMix o encuéntralo en la categoría de plataformas de terceros.
4. El nombre y el endpoint se completan automáticamente: https://aihubmix.com. Pega tu clave en Clave de API.
5. Pulsa Añadir.

El preset almacena dos variables de entorno:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com"
  }
}

El preset no establece un modelo. La guía de AIHubMix considera ANTHROPIC_MODEL una variable esencial, así que añádela al mismo bloque env antes de cambiar de proveedor:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

Si no especificas un modelo, Claude Code envía el ID de modelo predeterminado, que puede no estar disponible en AIHubMix.

Conviene tener en cuenta dos detalles.

No añadas /v1 a la URL base. Claude Code usa el protocolo Anthropic Messages y construye la ruta de la solicitud por su cuenta. https://aihubmix.com es correcto; https://aihubmix.com/v1 es la URL base compatible con OpenAI para otros clientes, y Claude Code le añadiría su propio /v1/messages.

El preset usa ANTHROPIC_API_KEY, mientras que la guía de AIHubMix para Claude Code usa ANTHROPIC_AUTH_TOKEN. AIHubMix acepta ambas: ANTHROPIC_AUTH_TOKEN envía una cabecera Bearer y ANTHROPIC_API_KEY envía x-api-key. Elige una. No rellenes ambas con valores distintos. Encontrarás los detalles de configuración, los ID de modelos y la referencia de errores de AIHubMix en la documentación de Claude Code de AIHubMix.

Si falta el preset, por ejemplo, en una versión anterior o porque eliminaste la tarjeta, elige Configuración personalizada y pega el JSON anterior. El administrador de endpoints de la tarjeta del proveedor puede comprobar la latencia; el preset también incluye https://api.aihubmix.com como endpoint alternativo si no se resuelve aihubmix.com.

Paso 4: Cambia de proveedor y verifica

En la pestaña Directo, pulsa Cambiar en la tarjeta de AiHubMix. El botón cambiará a En uso cuando se haya escrito la configuración.

Claude Code recarga la configuración automáticamente; normalmente no hace falta reiniciarlo. Si la sesión actual sigue usando el proveedor anterior, sal y vuelve a iniciarla.

Verifica el flujo de extremo a extremo:

claude -p "1+1, output only the answer" --model claude-sonnet-5-5

Una respuesta de 2 significa que la solicitud llegó a AIHubMix. En una sesión interactiva, la línea Anthropic base URL de /status debería mostrar https://aihubmix.com.

Para cambiar rápidamente, usa la bandeja del sistema: haz clic derecho en el icono de CC Switch, abre el submenú Claude Code y pulsa un proveedor. El título del submenú muestra el proveedor activo y un resumen de la cuota.

Para volver al proveedor oficial, cambia a Claude Official, reinicia Claude Code y completa el proceso de inicio de sesión.

Qué cambia realmente al cambiar de proveedor

En el modo directo, CC Switch reemplaza únicamente los campos de conexión y compatibilidad de ~/.claude/settings.json: ANTHROPIC_*, AWS_*, selectores de protocolo como CLAUDE_CODE_USE_BEDROCK, model, apiKeyHelper y algunas opciones de compatibilidad específicas del proveedor, como CLAUDE_CODE_DISABLE_ARTIFACT y la ventana de contexto.

permissions, hooks, enabledPlugins, statusLine, la configuración de MCP, los comentarios y cualquier otro elemento que hayas añadido se mantienen intactos. La lista exacta está en la referencia del archivo de configuración.

Antes de reescribir por primera vez la configuración de una herramienta, CC Switch guarda una copia de seguridad del original en ~/.cc-switch/backups/live-first-write/. Si el JSON está mal formado, se niega a escribir, indica la línea y la columna y deja el archivo sin cambios.

La trampa: variables ANTHROPIC_* obsoletas

Este es el fallo que hace pensar que CC Switch no funcionó.

Si anteriormente seguiste una guía de configuración manual y añadiste export ANTHROPIC_BASE_URL=... o export ANTHROPIC_AUTH_TOKEN=... a ~/.zshrc o ~/.bash_profile, esas variables pueden sobrescribir los valores que escribe CC Switch. Cambias la tarjeta a AIHubMix, pero las solicitudes siguen dirigiéndose al endpoint anterior.

CC Switch detecta el conflicto. Un aviso amarillo en la parte superior de la ventana indica que las variables de entorno podrían sobrescribir tu configuración; los detalles muestran el nombre, el valor y el origen de la variable. Eliminar seleccionadas las quita y, antes, guarda una copia de seguridad en ~/.cc-switch/backups/env-backup-<timestamp>.json.

Para comprobarlo manualmente:

grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

Comenta las exportaciones anteriores y luego ejecuta source ~/.zshrc o abre una terminal nueva. La documentación de AIHubMix recomienda eliminar las variables globales ANTHROPIC_* cuando CC Switch administra la configuración. El flujo completo para resolver conflictos está en la referencia de variables de entorno.

Alias de modelos y cambios

Con ANTHROPIC_MODEL configurada, el modelo predeterminado de Claude Code es Sonnet 5.5. Si quieres que los alias de /model (opus, sonnet, haiku, fable) correspondan a los ID de modelos de AIHubMix, también tienes que asignarlos. Añade estas claves dentro de env:

La configuración completa del proveedor quedaría así:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1"
  }
}

Prioridad de selección del modelo, de mayor a menor: /model <name> → claude --model <name> → ANTHROPIC_MODEL → el campo model de settings.json. Copia los ID de modelos de la lista de modelos de AIHubMix; distinguen entre mayúsculas y minúsculas.

Cuándo usar el enrutamiento o la agregación

El modo directo es la opción predeterminada recomendada para AIHubMix. El endpoint ya usa el protocolo Anthropic Messages, así que no hace falta convertir el protocolo.

Usa el enrutamiento si quieres una cola de conmutación por error o necesitas conectar a Claude Code un proveedor con formato OpenAI. El enrutamiento apunta Claude Code a http://127.0.0.1:15721, reemplaza la clave de la configuración por PROXY_MANAGED e inyecta la clave real desde CC Switch. La aplicación debe permanecer en ejecución; al salir de CC Switch, se restaura la configuración directa. Las suscripciones oficiales de Claude no pasan por el enrutamiento; para ellas, usa el modo directo.

Usa la agregación cuando quieras tener modelos de varios proveedores en una sola lista de /model. El proveedor predeterminado gestiona las solicitudes sin prefijo; los modelos de otros proveedores aparecen con el prefijo ccs-. La agregación no ofrece conmutación por error. Solo está disponible para Claude Code y Codex, y no admite las suscripciones oficiales de Claude. La lista de modelos ccs- requiere Claude Code 2.1.243 o una versión posterior. Claude Code detecta los cambios en la lista de modelos de inmediato; Codex requiere un reinicio completo.

Qué más gestiona CC Switch

• Uso: el panel combina los registros de solicitudes enrutadas con los registros de sesiones locales. El análisis de sesiones funciona sin enrutamiento y calcula los precios según el modelo registrado en el historial; las solicitudes enrutadas se registran por separado.
• MCP: un panel unificado para servidores MCP, sincronizado con las aplicaciones que selecciones.
• Skills: descubre, instala y elimina skills desde un solo lugar.
• Sesiones: busca, consulta, exporta y reanuda sesiones locales.
• Proyectos: guarda el proveedor, los servidores MCP, las skills y los archivos de memoria de un proyecto en una instantánea y, después, cambia todo el conjunto para cada proyecto.

Los datos se guardan en ~/.cc-switch/, con una base de datos SQLite como elemento central. Las copias de seguridad automáticas conservan las 10 más recientes de forma predeterminada, y también está disponible la sincronización con WebDAV o S3 compatible. La base de datos y las copias de seguridad exportadas incluyen las configuraciones de proveedores, incluidas las claves; trátalas como secretos.

Solución de problemas

Los mensajes de error siguientes están citados de la documentación de AIHubMix sobre Claude Code.

Para síntomas que no sean errores:

• Pantalla de inicio de sesión o Not logged in: comprueba /status; activa Skip Claude Code first-run confirmation en Settings → App config → Claude Code; reinicia y confirma que la clave esté introducida.
• El cambio no surte efecto: puede haber una variable de shell obsoleta o una sesión en caché; abre una terminal nueva o reinicia Claude Code.
• La prueba de conexión de la tarjeta se completa, pero fallan las solicitudes: la prueba verifica la conectividad, no la clave ni el modelo; ejecuta el comando de extremo a extremo claude -p.
• Quieres volver al proveedor oficial: cambia a Claude Official, reinicia Claude Code y vuelve a iniciar sesión.

Si no se encuentra el comando claude en macOS, el instalador oficial suele colocarlo en ~/.local/bin/claude. Añade export PATH="$HOME/.local/bin:$PATH" al perfil de tu shell y abre una terminal nueva.

Lista de verificación

• [ ] Instala CC Switch desde ccswitch.io o GitHub Releases.
• [ ] Crea una clave de API en la consola de AIHubMix.
• [ ] En Claude Code → + → AiHubMix → pega la clave → Añadir.
• [ ] Añade ANTHROPIC_MODEL=claude-sonnet-5-5 al JSON del proveedor.
• [ ] Haz clic en Switch y confirma que la tarjeta muestre In use.
• [ ] Elimina las exportaciones obsoletas ANTHROPIC_* del perfil de tu shell.
• [ ] Ejecuta claude -p "1+1, output only the answer" --model claude-sonnet-5-5 y comprueba que la respuesta sea 2.

Si el último comando devuelve 2, el cambio de proveedor está completo. Solo queda añadir los alias de modelos que quieras y decidir si necesitas enrutamiento o agregación; para la mayoría de los usuarios de AIHubMix, el modo directo es suficiente.

Preguntas frecuentes

¿CC Switch es gratis?
Sí. Es de código abierto bajo la licencia MIT. Solo pagas al proveedor cuya API utilices.

¿Al cambiar de proveedor se eliminan mis hooks, servidores MCP o plugins?
No. El cambio directo sustituye el endpoint, la clave, el modelo y algunas opciones específicas del proveedor. Los hooks, los permisos, los servidores MCP, los plugins y la configuración de la barra de estado permanecen en el archivo.

¿CC Switch sube mi clave de API?
Las configuraciones de los proveedores se guardan localmente en ~/.cc-switch/cc-switch.db. Si activas la sincronización con WebDAV o S3, se sincronizan con el almacenamiento que controlas. Las bases de datos y las copias de seguridad contienen claves, así que trátalas como secretos.

¿Tengo que mantener CC Switch en ejecución?
No, en el modo directo. El enrutamiento y la agregación requieren que la aplicación esté en ejecución; si cierras CC Switch, el cliente vuelve al modo directo.

¿Puedo usar Claude Official y AIHubMix al mismo tiempo?
El modo directo permite un solo proveedor activo a la vez. La agregación puede incluir los modelos de varios proveedores en una lista, pero no admite la suscripción oficial de Claude; vuelve al modo directo para usarla.

¿Funciona en Windows?
Sí. CC Switch es compatible con Windows 10 y versiones posteriores mediante un instalador .msi o una compilación portable. Linux requiere glibc 2.35+ y WebKitGTK 4.1.

¿Por qué la tarjeta del proveedor indica que la conexión funciona, pero Claude Code sigue fallando?
La prueba de conectividad de la tarjeta comprueba si se puede acceder al endpoint. No valida la clave de API ni el modelo. Usa el comando de extremo a extremo claude -p para probar el flujo completo.

Fuentes

• Repositorio de CC Switch
• Manual de usuario de CC Switch: añadir un proveedor
• Manual de usuario de CC Switch: cambiar de proveedor
• Manual de usuario de CC Switch: archivos de configuración
• Documentación de AIHubMix: Claude Code