You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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
Role Normalization — Converts developer → system for non-OpenAI providers; system → user for GLM/ERNIE
Think Tag Extraction — Extracts <think> 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)
🔧 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.
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.
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.
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
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.
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
⚡ Pornire rapidă
1. Instalați la nivel global:
npm install -g omniroute
omniroute
🎉 Tabloul de bord se deschide la http://localhost:20128
Comanda
Descriere
omniroute
Porniți serverul (portul implicit 20128)
omniroute --port 3000
Utilizați portul personalizat
omniroute --no-open
Nu deschideți automat browserul
omniroute --help
Arată ajutor
2. Conectați un furnizor GRATUIT:
Tabloul de bord → Furnizori → Conectare Claude Code sau Antigravity → Conectare OAuth → Gata!
3. Utilizați în instrumentul dvs. CLI:
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
Endpoint: http://localhost:20128/v1
API Key: [copy from dashboard]
Model: if/kimi-k2-thinking
Asta este! Începeți să codați cu modele AI GRATUITE.
Alternativă - rulează de la sursă:
cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
🐳 Docker
OmniRoute este disponibil ca imagine publică Docker pe Docker Hub.
🌐 Offline Mode — Works fully offline with bundled server
npm run electron:dev # Development mode
npm run electron:build # Current platform
npm run electron:build:win # Windows (.exe)
npm run electron:build:mac # macOS (.dmg)
npm run electron:build:linux # Linux (.AppImage)
Funcționează cu orice instrument care acceptă puncte finale personalizate OpenAI
Sanitizarea răspunsului — Elimina câmpurile nestandard pentru compatibilitate strictă cu OpenAI SDK
Normalizarea rolurilor — developer → system pentru non-OpenAI; system → user pentru modelele GLM/ERNIE
Think tag extraction — blocuri <think> → reasoning_content pentru modele de gândire
Ieșire structurată — json_schema → responseMimeType/responseSchema a lui Gemeni
👥 Suport pentru mai multe conturi
Adăugați mai multe conturi pentru fiecare furnizor
Auto round-robin sau rutare bazată pe prioritate
Revenire la următorul cont când cineva atinge cota
🔄 Reîmprospătare automată a simbolului
Tokenurile OAuth se reîmprospătează automat înainte de expirare
Nu este nevoie de re-autentificare manuală
Experiență perfectă pentru toți furnizorii
🎨 Combo personalizate
Creați combinații de modele nelimitate
6 strategii: umplere întâi, round-robin, putere cu două alegeri, aleatoriu, cel mai puțin utilizat, optimizat din punct de vedere al costurilor
Partajați combo-uri pe dispozitive cu Cloud Sync
🏥 Tabloul de bord pentru sănătate
Starea sistemului (timp de funcționare, versiune, utilizare a memoriei)
Stări întrerupătoarelor de circuit pentru fiecare furnizor (Închis/Deschis/Pe jumătate deschis)
Starea limitei ratei și blocajele active
Statistici de cache pentru semnături
Telemetrie latență (p50/p95/p99) + cache prompt
Resetați starea de sănătate cu un singur clic
🔧 Translator Playground
OmniRoute include un puternic Translator Playground încorporat cu 4 moduri pentru depanare, testare și monitorizare a traducerilor API:
Modul
Descriere
💻 Loc de joacă
Traducere directă a formatului — inserați orice corp de solicitare API și vedeți instantaneu cum îl traduce OmniRoute între formatele de furnizor (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Include exemple de șabloane și detecție automată a formatului.
💬 Tester de chat
Trimiteți cereri reale de chat prin OmniRoute și vedeți întregul drum dus-întors: intrarea dvs., solicitarea tradusă, răspunsul furnizorului și răspunsul tradus înapoi. Neprețuit pentru validarea rutei combinate.
🧪 Banc de testare
Mod de testare în loturi — definiți mai multe cazuri de testare cu diferite intrări și rezultate așteptate, rulați-le pe toate simultan și comparați rezultatele între furnizori și modele.
📱 Monitor live
Monitorizare în timp real a cererilor — urmăriți cererile primite în timp ce acestea trec prin OmniRoute, vedeți traducerile formatului care au loc în direct și identificați problemele instantaneu.
Acces: Tabloul de bord → Traducător (bara laterală)
💾 Cloud Sync
Sincronizați furnizorii, combo-urile și setările pe dispozitive
Sincronizare automată în fundal
Stocare securizată criptată
🎯 Cazuri de utilizare
Cazul 1: „Am abonament Claude Pro”
Problemă: Cota expiră neutilizată, limitele ratei în timpul codării grele
Notă: OpenClaw funcționează numai cu OmniRoute local. Utilizați 127.0.0.1 în loc de localhost pentru a evita problemele de rezoluție IPv6.
Cline / Continuare / RooCode
Settings → API Configuration:
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from OmniRoute dashboard]
Model: if/kimi-k2-thinking
🧪 Evaluări (Evaluări)
OmniRoute include un cadru de evaluare încorporat pentru a testa calitatea răspunsului LLM față de un set de aur. Accesați-l prin Analitice → Evaluări în tabloul de bord.
Set de aur încorporat
„Setul de Aur OmniRoute” preîncărcat conține 10 cazuri de testare care acoperă:
Dacă problemele persistă: Dashboard → Provider → Reconnect
Costuri mari
Verificați statisticile de utilizare în Tabloul de bord → Costuri
Comutați modelul principal la GLM/MiniMax
Utilizați nivelul gratuit (Gemini CLI, iFlow) pentru sarcini necritice
Tabloul de bord se deschide pe portul greșit
Setați PORT=20128 și NEXT_PUBLIC_BASE_URL=http://localhost:20128
Erori de sincronizare în cloud
Verificați BASE_URL puncte către instanța dvs. care rulează
Verificați CLOUD_URL puncte către punctul final din cloud așteptat
Păstrați valorile NEXT_PUBLIC_* aliniate cu valorile de pe partea serverului
Prima conectare nu funcționează
Verificați INITIAL_PASSWORD în .env
Dacă nu este setată, parola de rezervă este 123456
Fără jurnal de solicitare
Setați ENABLE_REQUEST_LOGS=true în .env
Testul de conectare arată „Invalid” pentru furnizorii compatibili cu OpenAI
Mulți furnizori nu expun un punct final /models
OmniRoute v1.0.6+ include validarea de rezervă prin finalizarea chatului
Asigurați-vă că adresa URL de bază include sufixul /v1
🔐 OAuth em Servidor Remoto (Configurare OAuth la distanță)
⚠️ IMPORTANT pentru utilizatorii cu OmniRoute în VPS/Docker/servidor remoto
Por que o OAuth do Antigravity / Gemini CLI falha em serveres remotes?
Pentru autentificare, Antigravity și Gemini CLI folosesc Google OAuth 2.0. O Google exige que a redirect_uri utilizat nu fluxo OAuth seja exatamente uma das URIs pre-cadastradas no Google Cloud Console do aplicative.
As credenciais OAuth embutidas no OmniRoute esteo cadastradas apenas for localhost. Când accesați OmniRoute într-un server la distanță (ex: https://omniroute.meuservidor.com), sau Google respinge autentificarea com:
Error 400: redirect_uri_mismatch
Soluție: Configurați propriile acreditări OAuth
Você necesita criar um OAuth 2.0 Client ID nu Google Cloud Console ca URI pentru server.
Faceți clic pe "+ Create Credentials" → "OAuth client ID"
Tip de aplicație: "Aplicație web"
Nume: scolha qualquer nome (ex: OmniRoute Remote)
3. Adăugați ca URI de redirecționare autorizate
No campo „URI-uri de redirecționare autorizate”, adiție:
https://seu-servidor.com/callback
Substitue seu-servidor.com pelo domínio sau IP do seu servidor (inclua a porta se necessário, ex: http://45.33.32.156:20128/callback).
4. Salve și copie ca credenciais
Após criar, o Google afișează o Client ID e o Client Secret.
5. Configurați ca variabile de mediu
Nu ai .env (ai variat de ambient do Docker):
# Para Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
# Para Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
6. Reinicie o OmniRoute
# Se usando npm:
npm run dev
# Se usando Docker:
docker restart omniroute
7. Tente connect novamente
Tabloul de bord → Furnizori → Antigravity (sau Gemini CLI) → OAuth
Agora sau Google redirecționează corect pentru https://seu-servidor.com/callback și funcționează autenticação.
Soluție temporară (sem configurar credenciais proprias)
Nu vă rugăm să vă convingeți acum, dar este posibil să utilizați sau să fluxați manual de URL:
OmniRoute deschide o adresă URL de autorizare Google
Após você autorizar, o Google tentará redirecionar para localhost (que falha no server remote)
Copiați o adresă URL completă da bara de accesare a browserului (mesmo que a page não carregue)
Cole essa URL nu există câmpuri care nu apar modal de conexão pentru OmniRoute
Faceți clic pe „Conectați-vă”
Această soluție de soluționare funcționează deoarece codul de autorizare a URL-ului este valabil independent de redirecționare pentru a încărca sau nu.
🛠️ Tech Stack
Runtime: Node.js 18–22 LTS (⚠️ Node.js 24+ este nu este acceptat - better-sqlite3 binarele native sunt incompatibile)
Limba: TypeScript 5.9 — 100% TypeScript în src/ și open-sse/ (v1.0.6)
Cadru: Next.js 16 + React 19 + Tailwind CSS 4
Bază de date: LowDB (JSON) + SQLite (starea domeniului + jurnalele proxy)
Streaming: evenimente trimise de server (SSE)
Auth: OAuth 2.0 (PKCE) + JWT + chei API
Testare: Runner de testare Node.js (368+ teste unitare)
Mulțumiri speciale pentru 9router de decolua — proiectul original care a inspirat această furcă. OmniRoute se bazează pe această bază incredibilă cu funcții suplimentare, API-uri multimodale și o rescrie completă TypeScript.
Mulțumiri speciale pentru CLIProxyAPI — implementarea Go originală care a inspirat acest port JavaScript.
Cota de abonament expiră neutilizată în fiecare lună
