Conectar Claude Code a 9Router no consiste solo en pegar una configuración. El cliente, el Provider de 9Router y el nombre del modelo deben coincidir. Si aparece un 401, 404 o «modelo no disponible», aísla primero la capa del problema en lugar de cambiar la API key repetidamente.
Confirma tres elementos antes de configurar
- El servicio 9Router está iniciado y se abre su interfaz de administración local.
- Hay un Provider añadido en 9Router con clave y conectividad correctas.
- Tienes la Base URL compatible con OpenAI, la API key y los nombres de modelo o Combo disponibles que expone 9Router.
Claude Code solo debe solicitar la Base URL de 9Router. Las reglas de 9Router deciden el Provider y el modelo. Consulta la guía de 9Router para la instalación y el contexto.
Orden recomendado de conexión
Primero crea en 9Router una ruta de prueba con un único Provider y apunta Claude Code a ella. Añade fallback, varias cuentas o modelos locales solo después de completar una conversación sencilla.
Comprueba lo siguiente:
- La Base URL es el endpoint compatible con OpenAI de 9Router, no la URL de un proveedor ascendente.
- La API key fue emitida por la instancia actual de 9Router.
- El nombre de modelo en Claude Code coincide exactamente con un modelo o Combo expuesto por 9Router.
- Has reiniciado la terminal y Claude Code tras cambiar variables de entorno o configuración.
No disperses las claves del Provider ascendente entre configuraciones de proyectos. Guárdalas en 9Router y deja en Claude Code solo las credenciales mínimas del router local; migrar y revocar será más sencillo.
Cómo diagnosticar errores comunes
401 o Unauthorized
Primero confirma que la solicitud llega al 9Router local y luego revisa la API key. Si el panel de administración funciona pero el cliente devuelve 401, normalmente usa una clave incorrecta o apunta a otra instancia.
404 o endpoint not found
Suele indicar que falta o sobra una parte de la ruta en la Base URL. No añadas /v1 por intuición; usa la dirección compatible con OpenAI que muestra actualmente 9Router y valídala con la solicitud más simple.
model not found
Revisa la lista de modelos en 9Router. El nombre original del Provider, un alias personalizado y un nombre Combo pueden ser distintos. Claude Code debe usar el nombre expuesto por el router.
La solicitud funciona, pero siempre usa fallback
Revisa el estado, saldo o cuota, permisos del modelo y registros de solicitudes del Provider preferido. El fallback es una red de seguridad, no sustituye corregir la causa del fallo del modelo principal.
Conserva una configuración mínima de prueba
Antes de aplicar rutas complejas, conserva una línea base con un Provider, un modelo y sin fallback. Ante un problema, vuelve primero a ella: si funciona, el problema está en las reglas; si falla, revisa red, credenciales o Provider.
Para problemas de instalación, permisos o entorno de proyecto de Claude Code, consulta memoria y Hooks de Claude Code para varios proyectos.
Resumen
La idea central es dirigir la Base URL al router, hacer coincidir el nombre de modelo del router y mantener la lógica ascendente en el router. Revisa conectividad, autenticación, nombre del modelo y reglas de enrutamiento en ese orden.
Un modelo de configuración fácil de depurar
Piensa en la cadena como cuatro capas: Claude Code → 9Router endpoint → Provider → modelo real. Cada una responde una sola pregunta: si el cliente llegó al router, si el router aceptó las credenciales, si una regla seleccionó un Provider y si ese Provider puede llamar al modelo. Separa también pruebas y registros por esas capas.
Por ejemplo, comienza con un nombre de modelo fijo en Claude Code y asígnalo a un solo Provider en 9Router. Cuando sea estable, conviértelo en Combo y añade un segundo Provider. No expongas directamente muchos nombres ascendentes a Claude Code, o cada proyecto acumulará su propia configuración difícil de mantener.
Valida con una solicitud mínima, no con una tarea larga
Después de configurar cada capa, realiza una prueba de bajo coste:
- Confirma que el servicio escucha mediante la información de salud o la interfaz de 9Router.
- Envía una solicitud simple sin herramientas para validar API key y modelo.
- Pide a Claude Code que explique un texto breve del directorio actual.
- Solo entonces prueba lectura de archivos, ejecución de pruebas, contextos largos o Agents en paralelo.
Las tareas largas mezclan red, permisos de herramientas, contexto y reintentos. Guarda una solicitud mínima en tus notas de diagnóstico para reutilizarla tras actualizaciones o en otro equipo.
Diseño de reglas de enrutamiento estables
Separa un modelo predeterminado de uno de alto coste. Usa el predeterminado para preguntas rutinarias, formato y cambios de bajo riesgo; selecciona explícitamente el más potente para razonamiento complejo, revisión de código o contexto largo. Así el gasto resulta explicable y los registros muestran qué tareas realmente requieren una mejora.
Sé conservador con los activadores de fallback. Los errores de red, de cuota explícitos o una caída del Provider pueden justificar el cambio; una respuesta poco satisfactoria no debería reintentar automáticamente con varios Providers. Eso multiplica el consumo de tokens y dificulta reproducir resultados.
Lista de seguridad para despliegue y credenciales
- No expongas 9Router en una dirección pública sin controles de acceso.
- Trata
DATA_DIR, copias de seguridad y registros como datos sensibles, pues pueden contener información de Providers. - No incluyas claves ascendentes en repositorios, capturas ni instrucciones de proyectos Claude Code.
- Haz una copia antes de actualizar; prueba con una solicitud mínima antes de restaurar rutas de producción.
FAQ: ¿Debo configurar 9Router en cada proyecto?
Normalmente no. Una variable de entorno a nivel de cliente o una herramienta de gestión puede reutilizar un endpoint entre proyectos. La configuración por proyecto solo aporta valor cuando un repositorio necesita realmente un modelo, permisos o facturación aislados.
FAQ: ¿Por qué un modelo local usa fallback con frecuencia?
Consulta los registros de servicio en busca de falta de memoria, límite de contexto, cola de concurrencia o un nombre de modelo incorrecto. Antes de usarlo como ruta principal, valídalo de forma continua con longitudes de tareas reales, no solo con un prompt corto.