Cómo ejecutar tu propio enrutador de modelos de IA con 9router

9router es un proxy de enrutamiento de código abierto con licencia MIT que se ejecuta en tu propia máquina o servidor y agrupa todos los proveedores de IA que conectes detrás de un único endpoint compatible con OpenAI en http://localhost:20128/v1.

Si usas Claude Code en una terminal, Cline en tu editor y el SDK de OpenAI en un proyecto paralelo, probablemente tengas tres juegos de claves y tres URL base, y cada herramienta requiere su propio cambio de configuración cada vez que cambias de modelo. 9router sustituye todo eso por un único endpoint local. Esta guía explica cómo instalarlo con npm o Docker, cómo comprobar que funciona con curl, cómo apuntar tus herramientas hacia él y cómo protegerlo antes de que cualquier cosa fuera de localhost pueda acceder a él.

¿Qué es 9router?

9router es un proxy autoalojado que acepta peticiones en formato OpenAI, las enruta al proveedor upstream que tengas configurado y traduce entre los formatos de petición de OpenAI, Claude y Gemini según sea necesario. El README del proyecto enumera más de 40 proveedores compatibles, y la CLI se distribuye como el paquete npm 9router.

La principal diferencia entre 9router y OpenRouter es dónde se ejecuta el enrutador. OpenRouter es un servicio alojado al que envías tus peticiones. 9router es software que ejecutas tú mismo, y OpenRouter figura en su lista de proveedores, por lo que puedes colocar una cuenta de OpenRouter detrás de tu propio enrutador.

Por qué ejecutar un enrutador de modelos autoalojado

Un enrutador local ofrece el mismo endpoint a todas las herramientas y mantiene las credenciales de los proveedores en un solo lugar, de modo que puedes cambiar de modelo sin modificar la configuración de las herramientas ni el código de la aplicación.

• Un único endpoint. Todos los clientes compatibles con OpenAI usan la misma URL base.
• Claves en un solo lugar. Añades las cuentas de los proveedores una sola vez, en el dashboard. Cada herramienta solo necesita una clave de API de 9router.
• Cambio de modelo mediante una cadena. Cambiar de modelo significa cambiar el valor de model y nada más.
• Combos. Un combo es una lista ordenada y con nombre de modelos que se usa como nombre de modelo. Cuando el primer modelo agota su cuota, alcanza un límite de tasa (429) o devuelve un error, el enrutador prueba con el siguiente.

El patrón habitual es poner primero tu modelo preferido y, a continuación, modelos más económicos. Para comparar los precios por token antes de elegir los modelos de respaldo, utiliza la calculadora de costes de API de LLM.

Cómo instalar y ejecutar 9router

9router se instala como una CLI global de npm con npm install -g 9router y se inicia con el comando 9router. El servidor escucha en el puerto 20128.

npm install -g 9router
9router
# Dashboard: http://localhost:20128
# API:       http://localhost:20128/v1

Si no quieres hacer una instalación global, npx 9router lo ejecuta una sola vez.

Para ejecutarlo en Docker, usa la imagen oficial decolua/9router, que también se publica en ghcr.io/decolua/9router:

docker run -d --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  -e INITIAL_PASSWORD='change-me' \
  decolua/9router:latest

El montaje del volumen conserva la base de datos SQLite (/app/data/db/data.sqlite dentro del contenedor) cuando el contenedor se reinicia. Se publican nuevas versiones con frecuencia y la etiqueta latest se actualiza con ellas, así que fija una etiqueta de versión concreta si necesitas despliegues reproducibles.

Una vez iniciado 9router, completa la configuración en el dashboard:

1. Abre http://localhost:20128 e inicia sesión en el dashboard.
2. Añade al menos una cuenta de proveedor.
3. Crea una clave de API para tus herramientas.

Verificar el enrutador con curl

La forma más rápida de verificar que 9router funciona es enviar una petición GET a /v1/models antes de configurar cualquier herramienta. La respuesta es una lista JSON con todos los modelos y combos que el enrutador puede servir, en el formato de lista estándar de OpenAI.

curl http://localhost:20128/v1/models

La lista de modelos responde sin necesidad de clave. Con las peticiones de chat es distinto: la opción “Require API key” del dashboard está activada de forma predeterminada, por lo que requieren una clave generada en el dashboard. También es buena práctica enviar la clave en la petición de la lista de modelos, ya que una clave limitada a ciertos modelos solo ve esos modelos:

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_API_KEY"

Si un ID de modelo de tu proveedor aparece en la lista, el enrutamiento funciona. Si la lista está vacía, el proveedor todavía no está conectado.

Apunta tus herramientas a 9router

Cualquier cliente que acepte una URL base personalizada de OpenAI puede usar 9router. Establece la URL base en http://localhost:20128/v1 y proporciona una clave de API creada en el dashboard.

SDK de OpenAI

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:20128/v1",
  apiKey: process.env.NINE_ROUTER_API_KEY, // created in the 9router dashboard
});

const res = await client.chat.completions.create({
  model: "<an id or combo name from /v1/models>",
  messages: [{ role: "user", content: "Say hello" }],
});
console.log(res.choices[0].message.content);

Para cambiar a otro modelo o a un combo, cambia la cadena model. Nada más cambia en el código.

Agentes de programación

En Cline, elige OpenAI Compatible como proveedor de API y rellena tres valores: la URL base http://localhost:20128/v1, tu clave de API del dashboard y un ID de modelo copiado de /v1/models. Los agentes de terminal que permiten usar tu propio proveedor, como OpenCode, requieren esos mismos tres valores.

Pi con pi-9router-ext

La extensión pi-9router-ext conecta el agente de programación Pi con 9router mediante dos variables de entorno:

pi install npm:pi-9router-ext
NINE_ROUTER_BASE_URL=http://localhost:20128 NINE_ROUTER_API_KEY=<key> pi
# inside Pi:
/9router-models

Al iniciarse, la extensión lee los modelos de chat desde /v1/models. En la versión 0.2.4, también consulta /v1/models/web para descubrir las rutas de búsqueda web y de obtención de contenido (fetch) de 9router. Ejecuta /9router-models dentro de Pi para ver lo que ha encontrado.

¿Cómo proteger 9router antes de exponerlo?

Para proteger 9router antes de que otra máquina pueda acceder a él, establece una contraseña para el dashboard y los secretos de JWT y de las claves de API, y deja activada la opción “Require API key”. Los valores predeterminados son adecuados en localhost, pero no fuera de él. Si no se define INITIAL_PASSWORD, el primer inicio de sesión en el dashboard usa 123456 hasta que se guarde una contraseña. Define estos valores a partir del .env.example oficial antes de abrir un puerto o desplegar en un host público:

INITIAL_PASSWORD=<long-random-string>   # first login otherwise uses 123456
JWT_SECRET=<long-random-string>         # listed under "Required" in .env.example
API_KEY_SECRET=<long-random-string>     # the example default is publicly known
AUTH_COOKIE_SECURE=true                 # set when serving behind an HTTPS reverse proxy

La verificación de la clave de API en sí es una opción del dashboard. Abre la página Endpoint y confirma que Require API key está activada, de modo que se rechacen las peticiones sin una clave válida. Está activada de forma predeterminada, y el dashboard muestra una advertencia si el endpoint es accesible desde un host remoto sin ella.

Define AUTH_COOKIE_SECURE=true solo cuando la terminación TLS se realice delante de 9router. Sobre HTTP sin cifrar, el navegador no devolverá la cookie de autenticación.

Conclusión

Un enrutador autoalojado como 9router ofrece a todas tus herramientas un único endpoint y un único conjunto de credenciales, y cambiar de modelo solo implica cambiar la cadena model. Instálalo, comprueba que /v1/models muestra los modelos de tu proveedor y, después, apunta una herramienta a http://localhost:20128/v1. Establece la contraseña y los secretos, y mantén activada la opción “Require API key”, antes de que el enrutador salga de localhost.

Preguntas frecuentes

¿Cómo ejecuto 9router en un puerto distinto del 20128?

Inicia la CLI de npm con 9router --port 8080 para usar un puerto personalizado. Si lo ejecutas desde el código fuente, define la variable de entorno PORT, junto con NEXT_PUBLIC_BASE_URL apuntando al mismo puerto. En Docker, cambia el lado del host en el mapeo de puertos, por ejemplo -p 8080:20128. Después, todas las herramientas necesitarán la nueva URL base, como http://localhost:8080/v1.

¿Dónde almacena 9router su configuración y sus datos?

9router almacena sus datos en el directorio definido por DATA_DIR, que de forma predeterminada es ~/.9router, y guarda su base de datos SQLite en db/data.sqlite dentro de ese directorio. Si no se define JWT_SECRET, también se almacena allí un secreto de firma generado automáticamente, en ~/.9router/jwt-secret. La imagen oficial de Docker establece DATA_DIR en /app/data, por lo que montar un volumen en /app/data conserva todos los datos.

¿Cómo apunto las herramientas de otra máquina a un servidor remoto de 9router?

Ejecuta npx 9router connect http://server-host:20128 en la máquina cliente. El comando no inicia ningún servidor local. Inicia sesión con la contraseña del dashboard, reutiliza o crea una clave de API llamada cli- seguida del nombre del host y escribe la configuración de cada herramienta seleccionada. Hace una copia de seguridad de cada configuración original una sola vez con el sufijo .bak-9router. Usa --tools claude,codex para elegir las herramientas de antemano y --reset para deshacer los cambios.

¿Puede 9router usar más de una cuenta para el mismo proveedor?

Sí. 9router admite varias cuentas por proveedor y distribuye las peticiones entre ellas mediante enrutamiento round-robin o basado en prioridades. Cuando una cuenta alcanza su cuota, el enrutador cambia a la siguiente. Esto es independiente de los combos: la rotación de cuentas mantiene el mismo modelo y cambia las credenciales que hay detrás, mientras que un combo pasa a un modelo diferente.