OmniRoute Dashboard # 🚀 OmniRoute — El Gateway de IA Gratuito ### Nunca dejes de programar. Enrutamiento inteligente hacia **modelos de IA GRATUITOS y económicos** con fallback automático. _Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inactividad._ **Chat Completions • Embeddings • Generación de Imágenes • Audio • Reranking • 100% TypeScript** --- ### 🤖 Proveedor de IA Gratuito para tus agentes de programación favoritos _Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gateway de API gratuito para programación ilimitada._
OpenClaw
OpenClaw
⭐ 205K 		NanoBot
NanoBot
⭐ 20.9K 		PicoClaw
PicoClaw
⭐ 14.6K 		ZeroClaw
ZeroClaw
⭐ 9.9K 		IronClaw
IronClaw
⭐ 2.1K
OpenCode
OpenCode
⭐ 106K 		Codex CLI
Codex CLI
⭐ 60.8K 		Claude Code
Claude Code
⭐ 67.3K 		Gemini CLI
Gemini CLI
⭐ 94.7K 		Kilo Code
Kilo Code
⭐ 15.5K
📡 Todos los agentes se conectan vía http://localhost:20128/v1 o http://cloud.omniroute.online/v1 — una configuración, modelos y cuota ilimitados --- [![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) [![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) [![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE) [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) [![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) [🌐 Website](https://omniroute.online) • [🚀 Inicio Rápido](#-inicio-rápido) • [💡 Características](#-características-principales) • [📖 Docs](#-documentación) • [💰 Precios](#-precios-resumidos) 🌐 **Disponible en:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](README.pt-BR.md) | 🇪🇸 [Español](README.es.md) | 🇫🇷 [Français](README.fr.md) | 🇮🇹 [Italiano](README.it.md) | 🇷🇺 [Русский](README.ru.md) | 🇨🇳 [中文 (简体)](README.zh-CN.md) | 🇩🇪 [Deutsch](README.de.md) | 🇮🇳 [हिन्दी](README.in.md) | 🇹🇭 [ไทย](README.th.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇸🇦 [العربية](README.ar.md) | 🇯🇵 [日本語](README.ja.md) | 🇻🇳 [Tiếng Việt](README.vi.md) | 🇧🇬 [Български](README.bg.md) | 🇩🇰 [Dansk](README.da.md) | 🇫🇮 [Suomi](README.fi.md) | 🇮🇱 [עברית](README.he.md) | 🇭🇺 [Magyar](README.hu.md) | 🇮🇩 [Bahasa Indonesia](README.id.md) | 🇰🇷 [한국어](README.ko.md) | 🇲🇾 [Bahasa Melayu](README.ms.md) | 🇳🇱 [Nederlands](README.nl.md) | 🇳🇴 [Norsk](README.no.md) | 🇵🇹 [Português (Portugal)](README.pt.md) | 🇷🇴 [Română](README.ro.md) | 🇵🇱 [Polski](README.pl.md) | 🇸🇰 [Slovenčina](README.sk.md) | 🇸🇪 [Svenska](README.sv.md) | 🇵🇭 [Filipino](README.phi.md)
--- ## 🤔 ¿Por qué OmniRoute? **Deja de desperdiciar dinero y chocar con límites:** - La cuota de suscripción expira sin usar cada mes - Los límites de tasa te detienen en medio de la programación - APIs caras ($20-50/mes por proveedor) - Cambiar manualmente entre proveedores **OmniRoute resuelve esto:** - ✅ **Maximiza suscripciones** - Rastrea cuotas, usa cada bit antes del reset - ✅ **Fallback automático** - Suscripción → API Key → Barato → Gratuito, cero tiempo de inactividad - ✅ **Multi-cuenta** - Round-robin entre cuentas por proveedor - ✅ **Universal** - Funciona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, cualquier herramienta CLI --- ## 🔄 Cómo Funciona ``` ┌─────────────┐ │ Tu CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...) │ Tool │ └──────┬──────┘ │ http://localhost:20128/v1 ↓ ┌─────────────────────────────────────────┐ │ OmniRoute (Enrutador Inteligente) │ │ • Traducción de formato (OpenAI ↔ Claude) │ │ • Rastreo de cuota + Embeddings + Imágenes │ │ • Renovación automática de tokens │ └──────┬──────────────────────────────────┘ │ ├─→ [Tier 1: SUSCRIPCIÓN] Claude Code, Codex, Gemini CLI │ ↓ cuota agotada ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc. │ ↓ límite de presupuesto ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M) │ ↓ límite de presupuesto └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado) Resultado: Nunca dejes de programar, costo mínimo ``` --- ## 🎯 What OmniRoute Solves — 16 Real Pain Points > **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to zero observability.
💸 1. "I pay for an expensive subscription but still get interrupted by limits" Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity. **How OmniRoute solves it:** - **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention - **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next - **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) - **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
🔌 2. "I need to use multiple providers but each has a different API" OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints. **How OmniRoute solves it:** - **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 36+ providers - **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API - **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE - **Think Tag Extraction** — Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content` - **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion - **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
🌐 3. "My AI provider blocks my region/country" Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries. **How OmniRoute solves it:** - **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key - **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP - **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory` - **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass) - **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing - **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
🆓 4. "I want to use AI for coding but I have no money" Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost. **How OmniRoute solves it:** - **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free) - **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime - **NVIDIA NIM Free Credits** — 1000 free credits integrated - **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider
🔒 5. "I need to protect my AI gateway from unauthorized access" When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse. **How OmniRoute solves it:** - **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page - **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle - **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing - **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens - **Rate Limiter** — Per-IP rate limiting with configurable windows - **IP Filtering** — Allowlist/blocklist for access control - **Prompt Injection Guard** — Sanitization against malicious prompt patterns - **AES-256-GCM Encryption** — Credentials encrypted at rest
🛑 6. "My provider went down and I lost my coding flow" AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application. **How OmniRoute solves it:** - **Circuit Breaker per-provider** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open) - **Exponential Backoff** — Progressive retry delays - **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms - **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention - **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain - **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
🔧 7. "Configuring each AI tool is tedious and repetitive" Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. **How OmniRoute solves it:** - **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** — Guided 4-step setup for first-time users - **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 36+ providers
🔑 8. "Managing OAuth tokens from multiple providers is hell" Claude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic. **How OmniRoute solves it:** - **Auto Token Refresh** — OAuth tokens refresh in background before expiration - **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow - **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction - **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers - **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility - **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker
📊 9. "I don't know how much I'm spending or where" Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up. **How OmniRoute solves it:** - **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider - **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback - **Per-Model Pricing Configuration** — Configurable prices per model - **Usage Statistics Per API Key** — Request count and last-used timestamp per key - **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency
🐛 10. "I can't diagnose errors and problems in AI calls" When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error. **How OmniRoute solves it:** - **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console - **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter - **SQLite Proxy Logs** — Persistent logs that survive server restarts - **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing - **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation
🏗️ 11. "Deploying and maintaining the gateway is complex" Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction. **How OmniRoute solves it:** - **npm global install** — `npm install -g omniroute && omniroute` — done - **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi) - **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw) - **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode - **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking) - **Cloud Sync** — Config synchronization across devices via Cloudflare Workers - **DB Backups** — Automatic backup, restore, export and import of all settings
🌍 12. "The interface is English-only and my team doesn't speak English" Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors. **How OmniRoute solves it:** - **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English - **RTL Support** — Right-to-left support for Arabic and Hebrew - **Multi-Language READMEs** — 30 complete documentation translations - **Language Selector** — Globe icon in header for real-time switching
🔄 13. "I need more than chat — I need embeddings, images, audio" AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format. **How OmniRoute solves it:** - **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models - **Image Generation** — `/v1/images/generations` with 4 providers and 9+ models - **Audio Transcription** — `/v1/audio/transcriptions` — Whisper-compatible - **Text-to-Speech** — `/v1/audio/speech` — Multi-provider audio synthesis - **Moderations** — `/v1/moderations` — Content safety checks - **Reranking** — `/v1/rerank` — Document relevance reranking - **Responses API** — Full `/v1/responses` support for Codex
🧪 14. "I have no way to test and compare quality across models" Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist. **How OmniRoute solves it:** - **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal - **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function) - **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison - **Chat Tester** — Full round-trip with visual response rendering - **Live Monitor** — Real-time stream of all requests flowing through the proxy
📈 15. "I need to scale without losing performance" As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected. **How OmniRoute solves it:** - **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency - **Request Idempotency** — 5s deduplication window for identical requests - **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking - **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence - **API Key Validation Cache** — 3-tier cache for production performance - **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
🤖 16. "I want to control model behavior globally" Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical. **How OmniRoute solves it:** - **System Prompt Injection** — Global prompt applied to all requests - **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) - **6 Routing Strategies** — Global strategies that determine how requests are distributed - **Wildcard Router** — `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard - **Provider Toggle** — Enable/disable all connections for a provider with one click - **Blocked Providers** — Exclude specific providers from `/v1/models` listing
## ⚡ Inicio Rápido **1. Instala globalmente:** ```bash npm install -g omniroute omniroute ``` 🎉 El Dashboard se abre en `http://localhost:20128` | Comando | Descripción | | ----------------------- | ---------------------------------------------- | | `omniroute` | Iniciar servidor (puerto predeterminado 20128) | | `omniroute --port 3000` | Usar puerto personalizado | | `omniroute --no-open` | No abrir navegador automáticamente | | `omniroute --help` | Mostrar ayuda | **2. Conecta un proveedor GRATUITO:** Dashboard → Proveedores → Conectar **Claude Code** o **Antigravity** → Login OAuth → ¡Listo! **3. Usa en tu herramienta CLI:** ``` Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configuración: Endpoint: http://localhost:20128/v1 API Key: [copiar del dashboard] Model: if/kimi-k2-thinking ``` **¡Eso es todo!** Comienza a programar con modelos de IA GRATUITOS. **Alternativa — ejecutar desde código fuente:** ```bash cp .env.example .env npm install PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev ``` --- ## 🐳 Docker OmniRoute está disponible como imagen Docker pública en [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute). **Ejecución rápida:** ```bash docker run -d \ --name omniroute \ --restart unless-stopped \ -p 20128:20128 \ -v omniroute-data:/app/data \ diegosouzapw/omniroute:latest ``` **Con archivo de entorno:** ```bash # Copia y edita el .env primero cp .env.example .env docker run -d \ --name omniroute \ --restart unless-stopped \ --env-file .env \ -p 20128:20128 \ -v omniroute-data:/app/data \ diegosouzapw/omniroute:latest ``` **Usando Docker Compose:** ```bash # Perfil base (sin herramientas CLI) docker compose --profile base up -d # Perfil CLI (Claude Code, Codex, OpenClaw integrados) docker compose --profile cli up -d ``` | Imagen | Tag | Tamaño | Descripción | | ------------------------ | -------- | ------ | ---------------------- | | `diegosouzapw/omniroute` | `latest` | ~250MB | Última versión estable | | `diegosouzapw/omniroute` | `1.0.6` | ~250MB | Versión actual | --- --- ## 🖥️ Aplicación de Escritorio — Sin Conexión y Siempre Activo > 🆕 **¡NUEVO!** OmniRoute ahora está disponible como **aplicación de escritorio nativa** para Windows, macOS y Linux. Ejecuta OmniRoute como una aplicación de escritorio autónoma — sin terminal, sin navegador, sin internet necesario para modelos locales. La app basada en Electron incluye: - 🖥️ **Ventana Nativa** — Ventana dedicada con integración en la bandeja del sistema - 🔄 **Inicio Automático** — Inicia OmniRoute al iniciar sesión - 🔔 **Notificaciones Nativas** — Recibe alertas sobre cuota o problemas de proveedores - ⚡ **Instalación con Un Clic** — NSIS (Windows), DMG (macOS), AppImage (Linux) - 🌐 **Modo Sin Conexión** — Funciona completamente offline con servidor incluido ### Inicio Rápido ```bash npm run electron:dev # Modo desarrollo npm run electron:build # Plataforma actual npm run electron:build:win # Windows (.exe) npm run electron:build:mac # macOS (.dmg) npm run electron:build:linux # Linux (.AppImage) ``` 📖 Documentación completa: [`electron/README.md`](electron/README.md) --- ## 💰 Precios Resumidos | Tier | Proveedor | Costo | Reset de Cuota | Mejor Para | | ------------------ | ----------------- | ---------------------------- | ----------------- | ----------------------- | | **💳 SUSCRIPCIÓN** | Claude Code (Pro) | $20/mes | 5h + semanal | Ya suscrito | | | Codex (Plus/Pro) | $20-200/mes | 5h + semanal | Usuarios OpenAI | | | Gemini CLI | **GRATUITO** | 180K/mes + 1K/día | ¡Todos! | | | GitHub Copilot | $10-19/mes | Mensual | Usuarios GitHub | | **🔑 API KEY** | NVIDIA NIM | **GRATUITO** (1000 créditos) | Único | Pruebas gratuitas | | | DeepSeek | Por uso | Ninguno | Mejor precio/calidad | | | Groq | Tier gratuito + pago | Limitado | Inferencia ultra-rápida | | | xAI (Grok) | Por uso | Ninguno | Modelos Grok | | | Mistral | Tier gratuito + pago | Limitado | IA Europea | | | OpenRouter | Por uso | Ninguno | 100+ modelos | | **💰 BARATO** | GLM-4.7 | $0.6/1M | Diario 10h | Respaldo económico | | | MiniMax M2.1 | $0.2/1M | Rotativo 5h | Opción más barata | | | Kimi K2 | $9/mes fijo | 10M tokens/mes | Costo predecible | | **🆓 GRATUITO** | iFlow | $0 | Ilimitado | 8 modelos gratuitos | | | Qwen | $0 | Ilimitado | 3 modelos gratuitos | | | Kiro | $0 | Ilimitado | Claude gratuito | **💡 Consejo Pro:** ¡Comienza con Gemini CLI (180K gratis/mes) + iFlow (ilimitado gratis) = $0 de costo! --- ## 💡 Características Principales ### 🧠 Enrutamiento e Inteligencia | Característica | Qué Hace | | -------------------------------------- | ------------------------------------------------------------------------------- | | 🎯 **Fallback Inteligente 4 Tiers** | Auto-enrutamiento: Suscripción → API Key → Barato → Gratuito | | 📊 **Rastreo de Cuota en Tiempo Real** | Conteo de tokens en vivo + countdown de reset por proveedor | | 🔄 **Traducción de Formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente | | 👥 **Soporte Multi-Cuenta** | Múltiples cuentas por proveedor con selección inteligente | | 🔄 **Renovación Automática de Token** | Tokens OAuth se renuevan automáticamente con reintentos | | 🎨 **Combos Personalizados** | 6 estrategias: fill-first, round-robin, p2c, random, least-used, cost-optimized | | 🧩 **Modelos Personalizados** | Agrega cualquier ID de modelo a cualquier proveedor | | 🌐 **Enrutador Wildcard** | Enruta patrones `provider/*` a cualquier proveedor dinámicamente | | 🧠 **Presupuesto de Razonamiento** | Modos passthrough, auto, custom y adaptativo para modelos de razonamiento | | 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) | | ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models | | 💬 **Inyección de System Prompt** | System prompt global aplicado en todas las solicitudes | | 📄 **API Responses** | Soporte completo de la API Responses de OpenAI (`/v1/responses`) para Codex | ### 🎵 APIs Multi-Modal | Característica | Qué Hace | | ----------------------------- | ------------------------------------------------------ | | 🖼️ **Generación de Imágenes** | `/v1/images/generations` — 4 proveedores, 9+ modelos | | 📐 **Embeddings** | `/v1/embeddings` — 6 proveedores, 9+ modelos | | 🎤 **Transcripción de Audio** | `/v1/audio/transcriptions` — Compatible con Whisper | | 🔊 **Texto a Voz** | `/v1/audio/speech` — Síntesis de audio multi-proveedor | | 🛡️ **Moderaciones** | `/v1/moderations` — Verificaciones de seguridad | | 🔀 **Reranking** | `/v1/rerank` — Reranking de relevancia de documentos | ### 🛡️ Resiliencia y Seguridad | Característica | Qué Hace | | ---------------------------------- | ---------------------------------------------------------------------------- | | 🔌 **Circuit Breaker** | Auto-apertura/cierre por proveedor con umbrales configurables | | 🛡️ **Anti-Thundering Herd** | Mutex + semáforo rate-limit para proveedores con API key | | 🧠 **Caché Semántico** | Caché de dos niveles (firma + semántico) reduce costo y latencia | | ⚡ **Idempotencia de Solicitud** | Ventana de dedup de 5s para solicitudes duplicadas | | 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js | | 🌐 **Filtrado de IP** | Allowlist/blocklist para control de acceso a la API | | 📊 **Rate Limits Editables** | RPM, gap mínimo y concurrencia máxima configurables | | 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness | | 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt | ### 📊 Observabilidad y Analytics | Característica | Qué Hace | | ------------------------------ | --------------------------------------------------------------------- | | 📝 **Logs de Solicitud** | Modo debug con logs completos de request/response | | 💾 **Logs SQLite** | Logs de proxy persistentes sobreviven a reinicios | | 📊 **Dashboard de Analytics** | Recharts: cards de estadísticas, gráfico de uso, tabla de proveedores | | 📈 **Rastreo de Progreso** | Eventos de progreso SSE opt-in para streaming | | 🧪 **Evaluaciones de LLM** | Pruebas con conjunto golden y 4 estrategias de match | | 🔍 **Telemetría de Solicitud** | Agregación de latencia p50/p95/p99 + rastreo X-Request-Id | | 📋 **Logs + Cuotas** | Páginas dedicadas para navegación de logs y rastreo de cuotas | | 🏥 **Dashboard de Salud** | Uptime, estados de circuit breaker, lockouts, stats de caché | | 💰 **Rastreo de Costos** | Gestión de presupuesto + configuración de precios por modelo | ### ☁️ Deploy y Sincronización | Característica | Qué Hace | | --------------------------------- | ------------------------------------------------------------------------------- | | 💾 **Cloud Sync** | Sincroniza configuraciones entre dispositivos vía Cloudflare Workers | | 🌐 **Deploy en Cualquier Lugar** | Localhost, VPS, Docker, Cloudflare Workers | | 🔑 **Gestión de API Keys** | Genera, rota y define alcance de API keys por proveedor | | 🧙 **Asistente de Configuración** | Setup guiado en 4 pasos para nuevos usuarios | | 🔧 **Dashboard CLI Tools** | Configuración en un clic para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity | | 🔄 **Backups de DB** | Backup y restauración automáticos de todas las configuraciones |
📖 Detalles de Características ### 🎯 Fallback Inteligente 4 Tiers Crea combos con fallback automático: ``` Combo: "my-coding-stack" 1. cc/claude-opus-4-6 (tu suscripción) 2. nvidia/llama-3.3-70b (API NVIDIA gratuita) 3. glm/glm-4.7 (respaldo barato, $0.6/1M) 4. if/kimi-k2-thinking (fallback gratuito) → Cambia automáticamente cuando la cuota se agota o ocurren errores ``` ### 📊 Rastreo de Cuota en Tiempo Real - Consumo de tokens por proveedor - Countdown de reset (5 horas, diario, semanal) - Estimación de costo para tiers pagos - Reportes de gastos mensuales ### 🔄 Traducción de Formato Traducción transparente entre formatos: - **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** - Tu herramienta CLI envía formato OpenAI → OmniRoute traduce → El proveedor recibe formato nativo - Funciona con cualquier herramienta que soporte endpoints OpenAI personalizados ### 👥 Soporte Multi-Cuenta - Agrega múltiples cuentas por proveedor - Round-robin automático o enrutamiento por prioridad - Fallback a la siguiente cuenta cuando una alcanza la cuota ### 🔄 Renovación Automática de Token - Los tokens OAuth se renuevan automáticamente antes de expirar - Sin necesidad de re-autenticación manual - Experiencia transparente en todos los proveedores ### 🎨 Combos Personalizados - Crea combinaciones ilimitadas de modelos - 6 estrategias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized - Comparte combos entre dispositivos con Cloud Sync ### 🏥 Dashboard de Salud - Estado del sistema (uptime, versión, uso de memoria) - Estados de circuit breaker por proveedor (Closed/Open/Half-Open) - Estado de rate limit y lockouts activos - Estadísticas de caché de firma - Telemetría de latencia (p50/p95/p99) + caché de prompt - Reset de salud con un clic ### 🔧 Playground del Traductor - Debug, prueba y visualiza traducciones de formato de API - Envía solicitudes y ve cómo OmniRoute traduce entre formatos de proveedores - Invaluable para troubleshooting de problemas de integración ### 💾 Cloud Sync - Sincroniza proveedores, combos y configuraciones entre dispositivos - Sincronización automática en segundo plano - Almacenamiento cifrado seguro
--- ## 🎯 Casos de Uso ### Caso 1: "Tengo suscripción Claude Pro" **Problema:** La cuota expira sin usar, límites de tasa durante programación intensa ``` Combo: "maximize-claude" 1. cc/claude-opus-4-6 (usar suscripción al máximo) 2. glm/glm-4.7 (respaldo barato cuando la cuota se agota) 3. if/kimi-k2-thinking (fallback de emergencia gratuito) Costo mensual: $20 (suscripción) + ~$5 (respaldo) = $25 total vs. $20 + chocar con límites = frustración ``` ### Caso 2: "Quiero costo cero" **Problema:** No puede pagar suscripciones, necesita IA confiable para programar ``` Combo: "free-forever" 1. gc/gemini-3-flash (180K gratis/mes) 2. if/kimi-k2-thinking (ilimitado gratis) 3. qw/qwen3-coder-plus (ilimitado gratis) Costo mensual: $0 Calidad: Modelos listos para producción ``` ### Caso 3: "Necesito programar 24/7, sin interrupciones" **Problema:** Plazos ajustados, no puede permitirse tiempo de inactividad ``` Combo: "always-on" 1. cc/claude-opus-4-6 (mejor calidad) 2. cx/gpt-5.2-codex (segunda suscripción) 3. glm/glm-4.7 (barato, reset diario) 4. minimax/MiniMax-M2.1 (más barato, reset 5h) 5. if/kimi-k2-thinking (gratuito ilimitado) Resultado: 5 capas de fallback = cero tiempo de inactividad ``` ### Caso 4: "Quiero IA GRATUITA en OpenClaw" **Problema:** Necesita asistente de IA en apps de mensajería, completamente gratuito ``` Combo: "openclaw-free" 1. if/glm-4.7 (ilimitado gratis) 2. if/minimax-m2.1 (ilimitado gratis) 3. if/kimi-k2-thinking (ilimitado gratis) Costo mensual: $0 Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... ``` --- ## 📖 Guía de Configuración
💳 Proveedores por Suscripción ### Claude Code (Pro/Max) ```bash Dashboard → Proveedores → Conectar Claude Code → Login OAuth → Renovación automática de token → Rastreo de cuota 5h + semanal Modelos: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` **Consejo Pro:** Usa Opus para tareas complejas, Sonnet para velocidad. ¡OmniRoute rastrea cuota por modelo! ### OpenAI Codex (Plus/Pro) ```bash Dashboard → Proveedores → Conectar Codex → Login OAuth (puerto 1455) → Reset 5h + semanal Modelos: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` ### Gemini CLI (¡GRATUITO 180K/mes!) ```bash Dashboard → Proveedores → Conectar Gemini CLI → Google OAuth → 180K completions/mes + 1K/día Modelos: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` **Mejor Valor:** ¡Tier gratuito enorme! Úsalo antes de los tiers pagos. ### GitHub Copilot ```bash Dashboard → Proveedores → Conectar GitHub → OAuth vía GitHub → Reset mensual (1ro del mes) Modelos: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro ```
🔑 Proveedores por API Key ### NVIDIA NIM (¡GRATUITO 1000 créditos!) 1. Regístrate: [build.nvidia.com](https://build.nvidia.com) 2. Obtén API key gratuita (1000 créditos de inferencia incluidos) 3. Dashboard → Agregar Proveedor → NVIDIA NIM: - API Key: `nvapi-your-key` **Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, y 50+ más **Consejo Pro:** ¡API compatible con OpenAI — funciona perfectamente con la traducción de formato de OmniRoute! ### DeepSeek 1. Regístrate: [platform.deepseek.com](https://platform.deepseek.com) 2. Obtén API key 3. Dashboard → Agregar Proveedor → DeepSeek **Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` ### Groq (¡Tier Gratuito Disponible!) 1. Regístrate: [console.groq.com](https://console.groq.com) 2. Obtén API key (tier gratuito incluido) 3. Dashboard → Agregar Proveedor → Groq **Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` **Consejo Pro:** ¡Inferencia ultra-rápida — mejor para programación en tiempo real! ### OpenRouter (100+ Modelos) 1. Regístrate: [openrouter.ai](https://openrouter.ai) 2. Obtén API key 3. Dashboard → Agregar Proveedor → OpenRouter **Modelos:** Accede a 100+ modelos de todos los principales proveedores a través de una única API key.
💰 Proveedores Baratos (Respaldo) ### GLM-4.7 (Reset diario, $0.6/1M) 1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/) 2. Obtén API key del Plan Coding 3. Dashboard → Agregar API Key: - Proveedor: `glm` - API Key: `your-key` **Usa:** `glm/glm-4.7` **Consejo Pro:** ¡El Plan Coding ofrece 3× cuota a 1/7 del costo! Reset diario 10:00 AM. ### MiniMax M2.1 (Reset 5h, $0.20/1M) 1. Regístrate: [MiniMax](https://www.minimax.io/) 2. Obtén API key 3. Dashboard → Agregar API Key **Usa:** `minimax/MiniMax-M2.1` **Consejo Pro:** ¡Opción más barata para contexto largo (1M tokens)! ### Kimi K2 ($9/mes fijo) 1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/) 2. Obtén API key 3. Dashboard → Agregar API Key **Usa:** `kimi/kimi-latest` **Consejo Pro:** ¡$9/mes fijo por 10M tokens = $0.90/1M de costo efectivo!
🆓 Proveedores GRATUITOS (Respaldo de Emergencia) ### iFlow (8 modelos GRATUITOS) ```bash Dashboard → Conectar iFlow → Login OAuth iFlow → Uso ilimitado Modelos: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 if/minimax-m2 if/deepseek-r1 ``` ### Qwen (3 modelos GRATUITOS) ```bash Dashboard → Conectar Qwen → Autorización por código de dispositivo → Uso ilimitado Modelos: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` ### Kiro (Claude GRATUITO) ```bash Dashboard → Conectar Kiro → AWS Builder ID o Google/GitHub → Uso ilimitado Modelos: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ```
🎨 Crear Combos ### Ejemplo 1: Maximizar Suscripción → Respaldo Barato ``` Dashboard → Combos → Crear Nuevo Nombre: premium-coding Modelos: 1. cc/claude-opus-4-6 (Suscripción primaria) 2. glm/glm-4.7 (Respaldo barato, $0.6/1M) 3. minimax/MiniMax-M2.1 (Fallback más barato, $0.20/1M) Usa en CLI: premium-coding ``` ### Ejemplo 2: Solo Gratuito (Costo Cero) ``` Nombre: free-combo Modelos: 1. gc/gemini-3-flash-preview (180K gratis/mes) 2. if/kimi-k2-thinking (ilimitado) 3. qw/qwen3-coder-plus (ilimitado) Costo: ¡$0 para siempre! ```
🔧 Integración CLI ### Cursor IDE ``` Configuración → Modelos → Avanzado: OpenAI API Base URL: http://localhost:20128/v1 OpenAI API Key: [del dashboard OmniRoute] Model: cc/claude-opus-4-6 ``` ### Claude Code Usa la página **CLI Tools** en el dashboard para configuración en un clic, o edita `~/.claude/settings.json` manualmente. ### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` ### OpenClaw **Opción 1 — Dashboard (recomendado):** ``` Dashboard → CLI Tools → OpenClaw → Seleccionar Modelo → Aplicar ``` **Opción 2 — Manual:** Edita `~/.openclaw/openclaw.json`: ```json { "models": { "providers": { "omniroute": { "baseUrl": "http://127.0.0.1:20128/v1", "apiKey": "sk_omniroute", "api": "openai-completions" } } } } ``` > **Nota:** OpenClaw solo funciona con OmniRoute local. Usa `127.0.0.1` en lugar de `localhost` para evitar problemas de resolución IPv6. ### Cline / Continue / RooCode ``` Configuración → Configuración de API: Proveedor: OpenAI Compatible Base URL: http://localhost:20128/v1 API Key: [del dashboard OmniRoute] Model: if/kimi-k2-thinking ```
--- ## 🧪 Evaluaciones (Evals) OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard. ### Conjunto Golden Integrado El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren: - Saludos, matemáticas, geografía, generación de código - Conformidad de formato JSON, traducción, markdown - Rechazo de seguridad (contenido dañino), conteo, lógica booleana ### Estrategias de Evaluación | Estrategia | Descripción | Ejemplo | | ---------- | ---------------------------------------------------- | -------------------------------- | | `exact` | La salida debe coincidir exactamente | `"4"` | | `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"` | | `regex` | La salida debe coincidir con el patrón regex | `"1.*2.*3"` | | `custom` | Función JS personalizada retorna true/false | `(output) => output.length > 10` | --- ## 🐛 Solución de Problemas
Haz clic para expandir la guía de solución de problemas **"Language model did not provide messages"** - Cuota del proveedor agotada → Verifica el rastreador de cuota en el dashboard - Solución: Usa combo con fallback o cambia a tier más barato **Rate limiting** - Cuota de suscripción agotada → Fallback a GLM/MiniMax - Agrega combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` **Token OAuth expirado** - Renovado automáticamente por OmniRoute - Si persiste: Dashboard → Proveedor → Reconectar **Costos altos** - Verifica estadísticas de uso en Dashboard → Costos - Cambia modelo primario a GLM/MiniMax - Usa tier gratuito (Gemini CLI, iFlow) para tareas no críticas **Dashboard se abre en el puerto equivocado** - Establece `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128` **Errores de cloud sync** - Verifica que `BASE_URL` apunte a tu instancia en ejecución - Verifica que `CLOUD_URL` apunte a tu endpoint cloud esperado - Mantén los valores `NEXT_PUBLIC_*` alineados con los valores del servidor **Primer login no funciona** - Verifica `INITIAL_PASSWORD` en `.env` - Si no está definido, la contraseña predeterminada es `123456` **Sin logs de solicitud** - Establece `ENABLE_REQUEST_LOGS=true` en `.env` **Prueba de conexión muestra "Invalid" para proveedores compatibles con OpenAI** - Muchos proveedores no exponen el endpoint `/models` - OmniRoute v1.0.6+ incluye validación vía chat completions como fallback - Asegúrate de que la URL base incluya el sufijo `/v1`
--- ## 🛠️ Stack Tecnológico - **Runtime**: Node.js 20+ - **Lenguaje**: TypeScript 5.9 — **100% TypeScript** en `src/` y `open-sse/` (v1.0.6) - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 - **Base de Datos**: LowDB (JSON) + SQLite (estado del dominio + logs de proxy) - **Streaming**: Server-Sent Events (SSE) - **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys - **Testing**: Node.js test runner (368+ tests unitarios) - **CI/CD**: GitHub Actions (publicación automática npm + Docker Hub en release) - **Website**: [omniroute.online](https://omniroute.online) - **Paquete**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) - **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) - **Resiliencia**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS --- ## 📖 Documentación | Documento | Descripción | | ------------------------------------------------ | -------------------------------------------------- | | [Guía del Usuario](docs/USER_GUIDE.md) | Proveedores, combos, integración CLI, deploy | | [Referencia de API](docs/API_REFERENCE.md) | Todos los endpoints con ejemplos | | [Solución de Problemas](docs/TROUBLESHOOTING.md) | Problemas comunes y soluciones | | [Arquitectura](docs/ARCHITECTURE.md) | Arquitectura del sistema e internos | | [Contribuir](CONTRIBUTING.md) | Setup de desarrollo y directrices | | [Spec OpenAPI](docs/openapi.yaml) | Especificación OpenAPI 3.0 | | [Política de Seguridad](SECURITY.md) | Reportar vulnerabilidades y prácticas de seguridad | --- ## 📧 Soporte > 💬 **¡Únete a la comunidad!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtén ayuda, comparte consejos y mantente al día. - **Website**: [omniroute.online](https://omniroute.online) - **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) - **WhatsApp**: [Grupo de la Comunidad](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - **Proyecto Original**: [9router por decolua](https://github.com/decolua/9router) --- ## 👥 Contribuidores [![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) ### Cómo Contribuir 1. Haz fork del repositorio 2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`) 3. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`) 4. Haz push a la rama (`git push origin feature/amazing-feature`) 5. Abre un Pull Request Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para directrices detalladas. ### Lanzar una Nueva Versión ```bash # Crea un release — la publicación en npm ocurre automáticamente gh release create v1.0.6 --title "v1.0.6" --generate-notes ``` --- ## 📊 Historial de Stars Star History Chart --- ## 🙏 Agradecimientos Agradecimiento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — el proyecto original que inspiró este fork. OmniRoute se construye sobre esa increíble base con características adicionales, APIs multi-modal y una reescritura completa en TypeScript. Agradecimiento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — la implementación original en Go que inspiró esta adaptación a JavaScript. --- ## 📄 Licencia Licencia MIT - consulta [LICENSE](LICENSE) para detalles. ---
Hecho con ❤️ para desarrolladores que programan 24/7
omniroute.online