Tutorial de OmniRoute: creación de una puerta de enlace API de IA local y cambio automático de varios modelos

OmniRoute es una puerta de enlace API de IA que se ejecuta localmente y que coloca diferentes proveedores de modelos, cuentas de suscripción y cuotas gratuitas detrás de una interfaz unificada. Clientes como Codex, Claude Code, Cursor, Cline y OpenCode solo necesitan conectarse a una dirección compatible con OpenAI y luego OmniRoute selecciona el modelo según la cuota disponible, el costo, la latencia y el estado de salud.

Es adecuado para desarrolladores que utilizan múltiples servicios modelo al mismo tiempo, que a menudo encuentran limitaciones actuales o que desean ver de manera uniforme el volumen de llamadas. Es importante tener en cuenta que la puerta de enlace no genera créditos gratuitos de la nada: cada proveedor ascendente aún determina el registro de la cuenta, el precio de la API, los límites de tarifas y el uso aceptable.

Respuesta rápida

Instalar y comenzar globalmente:

1
2

npm install -g omniroute
omniroute

Dirección predeterminada:

1
2

Dashboard: http://localhost:20128
API:       http://localhost:20128/v1

Vaya a la página Proveedores del Panel para conectarse al menos a un proveedor de modelo y luego vaya a la página Puntos finales para copiar la clave API local. Usos del cliente de IA:

1
2
3

Base URL: http://localhost:20128/v1
API Key:  Dashboard 中生成的 Key
Model:    auto

Lista de modelos de verificación:

1
2

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

Si se devuelve un modelo conectado, la puerta de enlace está básicamente disponible. Antes de conectarse oficialmente al agente de codificación, pruebe el diálogo normal, la salida de transmisión, la invocación de herramientas y el contexto largo, respectivamente, para evitar juzgar la compatibilidad basándose únicamente en la lista de modelos.

Cómo funciona OmniRoute

El cliente ya no se conecta directamente a cada API modelo, sino que envía la solicitud al OmniRoute local. La puerta de enlace lee el nombre del modelo y las reglas de enrutamiento, selecciona el proveedor actualmente disponible y convierte la respuesta en un protocolo que el cliente pueda entender.

1
2
3
4
5
6
7
8
9

Codex / Claude Code / Cursor
              |
              v
 http://localhost:20128/v1
              |
              v
      OmniRoute 路由与回退
       /       |        \
   Provider A  B         C

Esta arquitectura trae tres efectos directos:

1. El cliente sólo mantiene una URL base y una clave de acceso;
2. Cuando un Proveedor es limitado o falla, puede cambiar al modelo candidato;
3. El volumen de llamadas, el coste, la demora y los errores se concentran en un mismo plano de control para la observación.

La desventaja es que OmniRoute se convierte en un componente crítico en la ruta de solicitud. Cuando está inactivo, mal configurado o el directorio de datos está dañado, todos los clientes reenviados por él se verán afectados, por lo que los entornos de producción requieren persistencia, copias de seguridad, control de acceso y soluciones alternativas claras.

Requisitos medioambientales e instalación.

Actualmente, los funcionarios requieren Node.js 22 o 24 LTS y recomiendan Node.js 24 LTS. Primero verifique la versión:

1
2

node --version
npm --version

Instalar usando npm:

1

npm install -g omniroute

Puede ingresar al proceso de inicio cuando se ejecuta por primera vez:

1

omniroute setup

Inicie la puerta de enlace y el panel de control:

1

omniroute

Chat de terminal interactivo:

1

omniroute chat

Ejecute diagnósticos cuando encuentre problemas de proveedor, puerto o dependencia nativa:

1

omniroute doctor

Si la máquina no tiene un archivo precompilado better-sqlite3 adaptado, el proyecto intentará utilizar otras implementaciones de SQLite. Cuando la instalación es anormal, primero debe leer el registro completo. No cierre directamente todos los scripts de instalación ni los reinstale repetidamente con derechos de administrador.

Ejecutar usando Docker

Proporciona oficialmente imágenes Docker de múltiples arquitecturas:

1
2
3
4
5
6
7

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Verificar estado y registros:

1
2

docker ps --filter name=omniroute
docker logs -f omniroute

omniroute-data Guarde la configuración, la base de datos y el estado de ejecución, y no los elimine aleatoriamente al actualizar o reconstruir el contenedor. Los entornos de producción también deben reemplazar latest con una etiqueta de versión explícita y validada y realizar una copia de seguridad del volumen antes de actualizar.

El -p 20128:20128 anterior puede publicar el puerto en todas las interfaces de red del host. Cuando se usa solo en esta máquina, se puede restringir a la dirección de loopback:

1
2
3
4
5
6
7

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Cuando se requiere acceso remoto, se debe utilizar HTTPS, autenticación sólida, restricciones de IP o redes privadas, y el Panel y la API no deben exponerse a Internet.

Conectar proveedor de modelos

Abrir después del inicio:

1

http://localhost:20128

Ingrese a la página de Proveedores y agregue un Proveedor según la cuenta o clave API que realmente tenga. Se recomienda operar en el siguiente orden:

1. Conéctese primero a una cuenta de prueba de bajo riesgo;
2. Confirme que el directorio de modelos y la conversación única estén disponibles;
3. Establecer límite de presupuesto o cuota;
4. Agregue un segundo recurso de verificación del proveedor;
5. Finalmente, conéctese al cliente de codificación diaria.

No exponga tokens de OAuth, claves API ni claves de acceso al panel en capturas de pantalla, registros o comentarios. Las credenciales de descripción del almacén se cifrarán y guardarán localmente, pero aún pueden representar un riesgo cuando la máquina se ve comprometida, se filtra la clave maestra o el proceso de lectura se extiende maliciosamente.

Utilice auto enrutamiento automático

La configuración más sencilla es establecer el modelo de cliente en:

1

auto

OmniRoute también proporciona nombres de modelos automáticos para diferentes objetivos:

El enrutamiento automático no garantiza que diferentes modelos se comporten exactamente igual. Los formatos de llamada de herramientas, las ventanas contextuales, las capacidades de razonamiento y los estilos de salida pueden variar. Las tareas clave deben arreglar el modelo o limitar el conjunto de candidatos para evitar cambiar silenciosamente a modelos con capacidades obviamente diferentes en una tarea larga.

Personalizar la cadena de respaldo y la estrategia de enrutamiento

OmniRoute llama combo a un conjunto de destinos de respaldo del modelo. Los objetivos se pueden seleccionar por prioridad, peso, costo, saldo restante, latencia o estado de éxito reciente.

Las estrategias comunes incluyen:

• priority: Usar en un orden fijo, pasar al siguiente después del fallo;
• round-robin: Encuesta entre objetivos;
• cost-optimized: favorecer los modelos disponibles de menor precio;
• headroom: Favorecer las conexiones con más saldo restante;
• context-optimized: Seleccionar modelo según el tamaño del contexto actual;
• lkgp: Conserva la ruta que se ha verificado exitosamente recientemente.

Al configurar la cadena alternativa, no se limite a comparar los nombres de los modelos. Considere también los precios de insumos y productos, restricciones contextuales, llamadas de herramientas, capacidades de imágenes, regiones de datos y términos de proveedores. Para las sesiones en las que se debe mantener la coherencia del modelo, se debe habilitar una estrategia de adherencia adecuada o se debe fijar al proveedor directamente.

Acceder al cliente compatible con OpenAI

Por lo general, se pueden utilizar herramientas que pueden personalizar la URL base de OpenAI:

1

http://localhost:20128/v1

Se recomienda pasar la clave de acceso a través del encabezado de la solicitud:

1

Authorization: Bearer YOUR_KEY

Los clientes que no pueden agregar encabezados personalizados pueden usar alias compatibles con Token, pero la URL contendrá la clave, lo que facilitará el acceso al historial del navegador, a los registros de los agentes o a las capturas de pantalla. Utilice este método sólo cuando la autenticación del encabezado sea absolutamente imposible y rote la clave con regularidad.

Al autenticar la interfaz de chat, puede enviar una solicitud mínima:

1
2
3
4

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Reply with OK"}]}'

El comportamiento de alias y comillas de curl puede diferir en Windows PowerShell; se recomienda usar curl.exe o construir la solicitud de acuerdo con la versión actual de PowerShell.

Riesgos de acceso y permiso de MCP

OmniRoute no solo reenvía solicitudes de modelo, sino que también proporciona MCP para permitir que el Agente administre proveedores, enrutamiento, combinación, almacenamiento en caché, compresión y otras funciones de puerta de enlace.

modo estándar:

1

omniroute --mcp

Dirección HTTP MCP:

1

http://localhost:20128/api/mcp/stream

Ejemplo de Código Claude:

1
2
3

claude mcp add-server omniroute \
  --type http \
  --url http://localhost:20128/api/mcp/stream

Los permisos de MCP son más sensibles que las llamadas de modelo normales porque el agente puede modificar las configuraciones de enrutamiento o conexión. Se debe utilizar un alcance mínimo, un token de acceso independiente y registros de auditoría antes de acceder; operaciones como eliminar un proveedor, rotar claves o ajustar las cuotas del equipo deben conservar la confirmación manual.

¿Cómo se debe evaluar la compresión del token?

El almacén proporciona tuberías de procesamiento y compresión de múltiples etapas, como RTK y Caveman, y el índice de ahorro oficialmente demostrado varía ampliamente. El efecto real depende de la salida de la herramienta, el contenido duplicado, la estructura contextual y el nivel de compresión. El ratio del README no puede considerarse directamente como una garantía para cada proyecto.

Se recomienda utilizar tareas fijas para las pruebas A/B:

1. Guarde el mensaje original, la salida de la herramienta y el resultado final;
2. Desactive la compresión y ejecútela una vez;
3. Ejecute nuevamente usando la configuración estándar o RTK;
4. Compare el token de entrada, el retraso, el costo y la exactitud de la respuesta;
5. Ejecute el mismo conjunto de pruebas o comandos de verificación en la modificación del código.

La compresión puede eliminar información considerada de baja relevancia. Las auditorías de seguridad, los diagnósticos de registros extensos y las revisiones precisas del código no deberían centrarse únicamente en el ahorro de tokens, sino también comprobar las tasas de errores y preservar las rutas para ver los resultados sin procesar.

Términos de proveedores y crédito gratuito

OmniRoute agrega información sobre el nivel gratuito, la cuota de prueba y la limitación publicada por varios proveedores. El número cambiará según las políticas de los proveedores, las regiones, los tipos de cuentas y el tiempo, por lo que el artículo no cita de manera fija un cierto “número total de tokens gratuitos por mes”. Deben prevalecer el catálogo actual de Dashboard y la página de precios oficial ascendente.

También hay tres tipos de recursos a distinguir:

1. Nivel gratuito a largo plazo;
2. Cuota de prueba única después del registro;
3. Créditos adicionales que requieren pago o suscripción para desbloquearse.

Debe verificar los términos de servicio del proveedor antes de utilizar cuentas de suscripción, flujos OAuth no estándar o agregación de varias cuentas. Ser técnicamente capaz de acceder no significa que el proveedor permita compartir suscripciones individuales con equipos, realizar llamadas automatizadas o eludir los límites de cuota.

Consideraciones de implementación remota

Cuando OmniRoute se implementa en un VPS, todas las indicaciones del cliente, el contexto del código y las respuestas del modelo pasan por ese host. Al menos requerido:

• Utilice HTTPS para evitar la transmisión de texto claro de Token y Prompt;
• Restringir las fuentes de acceso al Panel, API y MCP;
• Emitir claves con diferentes alcances para diferentes usuarios o clientes;
• Haga una copia de seguridad del directorio de datos y cifre la copia de seguridad al mismo tiempo;
• Establecer el período de retención de registros para evitar el almacenamiento a largo plazo de código confidencial;
• Supervisar los costos de las llamadas, las tasas de fallas, la latencia y los inicios de sesión anormales.

No reemplace simplemente http://localhost:20128 en el ejemplo local con la IP pública y póngala en uso. Se recomienda verificar a través de Tailscale, WireGuard o SSH Tunnel antes de decidir si configurar un proxy inverso y un nombre de dominio público.

Preguntas frecuentes

No se puede abrir el panel

Ejecute diagnósticos y verifique los puertos:

1

omniroute doctor

Confirme que el proceso aún se está ejecutando y 20128 no está ocupado por otras aplicaciones. Los usuarios de Docker ven registros de contenedores y asignaciones de puertos.

/v1/models devuelve 401

Confirme que la solicitud utiliza la clave local generada por Panel → Puntos finales y contiene:

1

Authorization: Bearer YOUR_KEY

No confunda la clave del proveedor ascendente con la clave del punto final de OmniRoute.

auto Se seleccionó un modelo inadecuado.

Fije primero un modelo verificado para confirmar la compatibilidad del cliente y luego ajuste los candidatos combinados, las estrategias, los presupuestos y los requisitos del contexto. Los flujos de trabajo críticos pueden usar auto/coding, pero aún así deben restringir los modelos que no cumplen con los requisitos de contexto o llamada de herramienta.

El estilo de respuesta cambia repentinamente después de la alternativa de enrutamiento

Los diferentes modelos tienen diferentes capacidades de cumplimiento de comandos del sistema y formatos de herramientas. Habilite la permanencia de las sesiones, cierre las brechas en los modelos candidatos y preserve el estado de las tareas necesarias en todos los conmutadores. Modelos fijos directamente para tareas que requieren determinismo.

¿Puede OmniRoute reducir todos los costos de la IA?

No garantizado. Puede enrutar según precios y cuotas, y reducir cierta duplicación de contexto, pero la puerta de enlace en sí no puede cambiar las reglas de facturación ascendentes. Las revisiones de fusión, canalización o multimodelo también pueden aumentar el número total de llamadas.

¿Para qué escenarios es adecuado OmniRoute?

OmniRoute es adecuado para personas y equipos que mantienen múltiples cuentas modelo al mismo tiempo, necesitan una entrada unificada compatible con OpenAI, desean retroceder automáticamente cuando la corriente es limitada o desean observar de forma centralizada los costos y el estado de salud. Para proyectos simples que solo utilizan un proveedor estable, la introducción de una puerta de enlace completa puede aumentar la complejidad del mantenimiento.

Antes de adoptarlo en el entorno de producción del equipo, se recomienda completar cuatro verificaciones: compatibilidad del protocolo del cliente, términos del proveedor, aislamiento de claves y permisos, y ruta de degradación en caso de falla de la puerta de enlace.

OmniRoute remoto con Caddy HTTPS y conmutación por error

Este tutorial de OmniRoute solo trata la tarea específica del título. Para la implementación remota, 20128 solo debe escuchar la dirección de bucle invertido y luego Caddy proporciona TLS; Codex utiliza tokens de punto final restringidos y el respaldo automático debe ser observable y no puede cambiar los modelos de manera silenciosa.

Todas las operaciones siguientes se colocan primero en el repositorio de prueba, la cuenta de prueba o el servicio que solo escucha en la interfaz de loopback. El nombre de dominio, el nombre de usuario, la ruta y la clave del comando son marcadores de posición y deben reemplazarse antes de la ejecución.

La ruta de datos real de la puerta de enlace remota

1

docker version

Prepare Docker y volúmenes persistentes en VPS

1

docker volume create omniroute-data

Permitir que OmniRoute solo escuche en 127.0.0.1

1

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

Lea la lista de modelos por primera vez.

1

curl.exe http://127.0.0.1:20128/v1/models -H 'Authorization: Bearer YOUR_KEY'

Configuración mínima del proxy inverso Caddy

1

caddy validate --config Caddyfile

Verifique la cadena de certificados después de emitir HTTPS

1

curl.exe -I https://ai.example.com/v1/models

Crear un token de acceso privado para Codex

1

curl.exe https://ai.example.com/v1/models -H 'Authorization: Bearer YOUR_KEY'

Cómo elegir el enrutamiento automático y los modelos fijos

1

curl.exe http://127.0.0.1:20128/v1/chat/completions -H 'Content-Type: application/json' -d '{"model":"auto","messages":[{"role":"user","content":"ping"}]}'

El proveedor observa una reversión al limitar la corriente

1

docker logs --since 10m omniroute

La función de compresión se evalúa primero fuera de línea.

1

docker exec omniroute npm run eval:compression

Haga una copia de seguridad de los datos omniroute en lugar de simplemente hacer una copia de seguridad de la imagen

1

docker run --rm -v omniroute-data:/data -v ${PWD}:/backup alpine tar czf /backup/omniroute-data.tgz -C /data .

Permitir que Codex vuelva al punto final original en caso de falla

1

docker stop omniroute

Diferenciar errores de puerta de enlace y de flujo ascendente de los registros de Caddy

1

caddy validate --config Caddyfile

Limitar los modelos que pueden ser llamados por tokens remotos

1

curl.exe https://ai.example.com/v1/models -H 'Authorization: Bearer YOUR_KEY'

Simular falla del proveedor principal

1

docker logs --follow omniroute

Se corrigió la etiqueta de reversión al actualizar la imagen.

1

docker image ls diegosouzapw/omniroute

Validación del despliegue y reversión

Un contenedor en ejecución no demuestra que el despliegue esté terminado. Antes de conectar Codex en producción, complete una solicitud con modelo fijo, una con auto, una prueba de fallo del proveedor principal y un simulacro de recuperación. Conserve marcas de tiempo, etiquetas de imagen, versiones de configuración y registros redactados.

Cambie una sola variable cada vez: valide primero el modelo fijo, después auto y, por último, simule limitación o fallo del proveedor. Ante cualquier señal de detención, restaure el endpoint original de Codex. Si falla una actualización, vuelva a la imagen estable anterior y restaure la copia verificada de omniroute-data. No amplíe permisos, exponga 20128 ni desactive la redacción de registros para forzar una prueba.

Preguntas frecuentes sobre OmniRoute

¿Es posible omitir el entorno de prueba y usar OmniRoute directamente en el proyecto oficial?

No recomendado. Primero complete al menos una solicitud de éxito mínimo, una falla intencional y un simulacro de recuperación.

El comando OmniRoute se puede ejecutar pero el resultado es incorrecto, ¿dónde debo verificar primero?

Primero verifique el rango de entrada, la configuración efectiva real y la respuesta ascendente, y luego verifique el resumen del modelo. Un proceso normal no significa que los resultados del negocio sean correctos.

¿Cómo evitar que las claves o tokens de OmniRoute ingresen a Git?

Utilice variables de entorno del sistema, administración de secretos o archivos de configuración fuera del proyecto y busque diferencias antes de confirmar. Las claves deben rotarse después de que se descubre una infracción.

¿Qué es lo que más comúnmente se pasa por alto al actualizar OmniRoute?

Es más fácil pasar por alto el formato de configuración, la dirección de escucha predeterminada, el alcance de los permisos y la compatibilidad de la caché. Guarde la versión y los ejemplos de verificación antes de actualizar.

Resumen

OmniRoute usa http://localhost:20128/v1 local para conectar múltiples proveedores de modelos a una API unificada y usa auto y combo para implementar costos, velocidad, cuotas y enrutamiento basado en el estado. La instalación de npm es adecuada para la experiencia local y Docker es adecuada para operaciones persistentes; HTTPS, control de acceso, copia de seguridad y auditoría deben completarse durante la implementación remota. La cuota libre y el índice de compresión son indicadores dinámicos y deben evaluarse junto con los términos ascendentes y sus propios puntos de referencia.

Dirección del proyecto: diegosouzapw/OmniRoute

Sitio web oficial: omniroute.online