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:
|
|
Dirección predeterminada:
|
|
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:
|
|
Lista de modelos de verificación:
|
|
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.
|
|
Esta arquitectura trae tres efectos directos:
- El cliente sólo mantiene una URL base y una clave de acceso;
- Cuando un Proveedor es limitado o falla, puede cambiar al modelo candidato;
- 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:
|
|
Instalar usando npm:
|
|
Puede ingresar al proceso de inicio cuando se ejecuta por primera vez:
|
|
Inicie la puerta de enlace y el panel de control:
|
|
Chat de terminal interactivo:
|
|
Ejecute diagnósticos cuando encuentre problemas de proveedor, puerto o dependencia nativa:
|
|
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:
|
|
Verificar estado y registros:
|
|
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:
|
|
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:
|
|
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:
- Conéctese primero a una cuenta de prueba de bajo riesgo;
- Confirme que el directorio de modelos y la conversación única estén disponibles;
- Establecer límite de presupuesto o cuota;
- Agregue un segundo recurso de verificación del proveedor;
- 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:
|
|
OmniRoute también proporciona nombres de modelos automáticos para diferentes objetivos:
| Nombre del modelo | Enfoque de enrutamiento |
|---|---|
auto |
Equilibre las opciones y opte por el camino exitoso más reciente |
auto/coding |
Priorizar la calidad de la generación de código |
auto/fast |
Priorizar la baja latencia |
auto/cheap |
Priorizar menores costos de llamadas |
auto/offline |
Cuota restante prioritaria o espacio límite actual |
auto/smart |
Calidad primero y retener una pequeña cantidad de tráfico de exploración |
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:
|
|
Se recomienda pasar la clave de acceso a través del encabezado de la solicitud:
|
|
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:
|
|
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:
|
|
Dirección HTTP MCP:
|
|
Ejemplo de Código Claude:
|
|
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:
- Guarde el mensaje original, la salida de la herramienta y el resultado final;
- Desactive la compresión y ejecútela una vez;
- Ejecute nuevamente usando la configuración estándar o RTK;
- Compare el token de entrada, el retraso, el costo y la exactitud de la respuesta;
- 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:
- Nivel gratuito a largo plazo;
- Cuota de prueba única después del registro;
- 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:
|
|
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:
|
|
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.
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