🌐 Languages: 🇺🇸 English · 🇪🇸 es · 🇫🇷 fr · 🇩🇪 de · 🇮🇹 it · 🇷🇺 ru · 🇨🇳 zh-CN · 🇯🇵 ja · 🇰🇷 ko · 🇸🇦 ar · 🇮🇳 hi · 🇮🇳 in · 🇹🇭 th · 🇻🇳 vi · 🇮🇩 id · 🇲🇾 ms · 🇳🇱 nl · 🇵🇱 pl · 🇸🇪 sv · 🇳🇴 no · 🇩🇰 da · 🇫🇮 fi · 🇵🇹 pt · 🇷🇴 ro · 🇭🇺 hu · 🇧🇬 bg · 🇸🇰 sk · 🇺🇦 uk-UA · 🇮🇱 he · 🇵🇭 phi · 🇧🇷 pt-BR · 🇨🇿 cs · 🇹🇷 tr

Never stop coding. Smart routing to FREE & low-cost AI models with automatic fallback.

Il tuo proxy API universale: un endpoint, oltre 60 provider, zero tempi di inattività. Ora conServer MCP (25 strumenti),Protocollo A2A,Sistemi di memoria/competenzeeApp desktop Electron.

Completamenti chat • Incorporamenti • Generazione di immagini • Video • Musica • Audio • Riclassificazione •Ricerca Web• Server MCP • Protocollo A2A • 100% TypeScript---

🌐 Sito web • 🚀 Avvio rapido • 💡 Funzionalità • 📖 Documenti • 💰 Prezzi • 💬 WhatsApp

🖼️ Main Dashboard

📸 Dashboard Preview

Fai clic per visualizzare gli screenshot della dashboard

Pagina	Schermata
Fornitori
Combo
Analisi
Salute
Traduttore
Impostazioni
Strumenti CLI
Registri di utilizzo
Endpoint

🤖 Free AI Provider for your favorite coding agents

Connetti qualsiasi strumento IDE o CLI basato sull'intelligenza artificiale tramite OmniRoute: gateway API gratuito per codifica illimitata.

OpenClaw
_{⭐ 205K}

NanoBot
_{⭐ 20,9K}

PicoClaw
_{⭐ 14,6K}

ZeroClaw
_{⭐ 9,9K}

Artiglio di Ferro
_{⭐ 2,1K}

OpenCode
_{⭐ 106K}

CLI del Codice
_{⭐ 60,8K}

Codice Claude
_{⭐ 67,3K}

CLI Gemini
_{⭐ 94,7K}

Codice chilo
_{⭐ 15,5K}

_{📡 Tutti gli agenti si connettono tramite http://localhost:20128/v1 o http://cloud.omniroute.online/v1: una configurazione, modelli e quote illimitati}---

🤔 Why OmniRoute?

Smetti di sprecare denaro e di superare i limiti:

La quota di abbonamento scade ogni mese inutilizzata
Rate limits stop you mid-coding
API costose ($ 20-50/mese per fornitore)
Passaggio manuale tra fornitori

OmniRoute risolve questo problema:

✅Massimizza gli abbonamenti- Tieni traccia della quota, utilizza ogni bit prima di reimpostarlo
✅Falback automatico- Abbonamento → Chiave API → Economico → Gratuito, zero tempi di inattività
✅Multi-account- Round robin tra account per fornitore
✅Universale- Funziona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualsiasi strumento CLI---

📧 Support

💬Join our community!WhatsApp Group — Get help, share tips, and stay updated.

-Sito web: omniroute.online -GitHub: github.com/diegosouzapw/OmniRoute -Problemi: github.com/diegosouzapw/OmniRoute/issues -WhatsApp: Gruppo della community -Contributing: vedi CONTRIBUTING.md, apri un PR o scegli un "buon primo numero" -Progetto originale: 9router di decolua### 🐛 Reporting a Bug?

Quando apri un problema, esegui il comando system-info e allega il file generato:```bash npm run system-info


Questo genera un `system-info.txt` con la versione di Node.js, la versione di OmniRoute, i dettagli del sistema operativo, gli strumenti CLI installati (qoder, gemini, claude, codex, antigravity, droid, ecc.), lo stato di Docker/PM2 e i pacchetti di sistema: tutto ciò di cui abbiamo bisogno per riprodurre rapidamente il problema. Allega il file direttamente al tuo problema GitHub.---

## 🔄 How It Works

┌─────────────┐ │ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...) │ Tool │ └──────┬──────┘ │ http://localhost:20128/v1 ↓ ┌─────────────────────────────────────────┐ │ OmniRoute (Smart Router) │ │ • Format translation (OpenAI ↔ Claude) │ │ • Quota tracking + Embeddings + Images │ │ • Auto token refresh │ └──────┬──────────────────────────────────┘ │ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI │ ↓ quota exhausted ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc. │ ↓ budget limit ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M) │ ↓ budget limit └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)

Result: Never stop coding, minimal cost


---

## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases

>**Ogni sviluppatore che utilizza strumenti di intelligenza artificiale affronta questi problemi quotidianamente.**OmniRoute è stato creato per risolverli tutti: dai superamenti dei costi ai blocchi regionali, dai flussi OAuth interrotti alle operazioni di protocollo e all'osservabilità aziendale.

<dettagli>
<summary><b>💸 1. "Pago un abbonamento costoso ma vengo comunque interrotto dai limiti"</b></summary>

Gli sviluppatori pagano $ 20-200 al mese per Claude Pro, Codex Pro o GitHub Copilot. Anche pagando, la quota ha un tetto: 5 ore di utilizzo, limiti settimanali o limiti di tariffa al minuto. A metà sessione di codifica, il provider smette di rispondere e lo sviluppatore perde flusso e produttività.

**Come OmniRoute risolve il problema:**

-**Fallback intelligente a 4 livelli**: se la quota dell'abbonamento si esaurisce, reindirizza automaticamente alla chiave API → Economico → Gratuito senza alcun intervento manuale
-**Tracciamento dei limiti del provider**: gli snapshot delle quote memorizzate nella cache si aggiornano in base a una pianificazione lato server (predefinita `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) con aggiornamento manuale disponibile nell'interfaccia utente
-**Supporto multi-account**: più account per fornitore con round robin automatico: quando uno si esaurisce, passa a quello successivo
-**Combo personalizzate**— Catene di fallback personalizzabili con 9 strategie di bilanciamento (priorità, ponderata, riempimento-prima, round-robin, P2C, casuale, meno utilizzata, ottimizzata in termini di costi, strettamente casuale)
-**Quote aziendali Codex**: monitoraggio delle quote dello spazio di lavoro aziendale/team direttamente nella dashboard</details>

<dettagli>
<summary><b>🔌 2. "Devo utilizzare più provider, ma ognuno ha un'API diversa"</b></summary>

OpenAI utilizza un formato, Claude (Anthropic) ne utilizza un altro, Gemini ancora un altro. Se uno sviluppatore desidera testare modelli di fornitori diversi o eseguire il fallback tra di loro, deve riconfigurare gli SDK, modificare gli endpoint e gestire formati incompatibili. I provider personalizzati (FriendLI, NIM) hanno endpoint del modello non standard.

**Come OmniRoute risolve il problema:**

-**Endpoint unificato**: un singolo `http://localhost:20128/v1` funge da proxy per tutti gli oltre 60 provider
-**Format Translation**— Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
-**Sanitizzazione della risposta**: rimuove i campi non standard (`x_groq`, `usage_breakdown`, `service_tier`) che interrompono OpenAI SDK v1.83+
-**Normalizzazione dei ruoli**: converte `developer` → `system` per provider non OpenAI; `sistema` → `utente` per GLM/ERNIE
-**Think Tag Extraction**— Estrae i blocchi "<think>" da modelli come DeepSeek R1 in "reasoning_content" standardizzato
-**Output strutturato per Gemini**— Conversione automatica `json_schema` → `responseMimeType`/`responseSchema`
-**`stream` è impostato su `false`**— Si allinea con le specifiche OpenAI, evitando SSE imprevisti negli SDK Python/Rust/Go</details>

<dettagli>
<summary><b>🌐 3. "Il mio provider di intelligenza artificiale blocca la mia regione/paese"</b></summary>

Provider come OpenAI/Codex bloccano l'accesso da determinate regioni geografiche. Gli utenti ricevono errori come "unsupported_country_region_territory" durante le connessioni OAuth e API. Ciò è particolarmente frustrante per gli sviluppatori dei paesi in via di sviluppo.

**Come OmniRoute risolve il problema:**

-**Configurazione proxy a 3 livelli**: proxy configurabile a 3 livelli: globale (tutto il traffico), per provider (un solo provider) e per connessione/chiave
-**Badge proxy con codice colore**— Indicatori visivi: 🟢 proxy globale, 🟡 proxy provider, 🔵 proxy di connessione, che mostra sempre l'IP
-**Scambio di token OAuth tramite proxy**: anche il flusso OAuth passa attraverso il proxy, risolvendo il problema `unsupported_country_region_territory`
-**Test di connessione tramite proxy**: i test di connessione utilizzano il proxy configurato (non più bypass diretto)
-**Supporto SOCKS5**: supporto completo del proxy SOCKS5 per il routing in uscita
-**TLS Fingerprint Spoofing**: impronta digitale TLS simile a un browser tramite `wreq-js` per bypassare il rilevamento dei bot
-**🔏 Corrispondenza impronta digitale CLI**: riordina le intestazioni e i campi del corpo in modo che corrispondano alle firme binarie native della CLI, riducendo drasticamente il rischio di segnalazione dell'account. L'IP proxy viene preservato: ottieni contemporaneamente il mascheramento IP stealth**e**</details>

<dettagli>
<summary><b>🆓 4. "Voglio usare l'intelligenza artificiale per programmare ma non ho soldi"</b></summary>

Non tutti possono pagare $ 20-200 al mese per gli abbonamenti AI. Studenti, sviluppatori provenienti da paesi emergenti, hobbisti e liberi professionisti hanno bisogno di accedere a modelli di qualità a costo zero.

**Come OmniRoute risolve il problema:**

-**Provider di livello gratuito integrati**: supporto nativo per provider gratuiti al 100%: Qoder (5 modelli illimitati tramite OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 modelli illimitati: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + ID AWS Builder gratuiti), Gemini CLI (180.000 token/mese gratuiti)
-**Ollama Cloud**: modelli Ollama ospitati nel cloud su `api.ollama.com` con livello "Utilizzo leggero" gratuito; utilizzare il prefisso `ollamacloud/<model>`
-**Combo solo gratuiti**— Catena `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $ 0/mese con zero tempi di inattività
-**Accesso gratuito a NVIDIA NIM**: ~40 RPM accesso gratuito per sviluppatori a oltre 70 modelli su build.nvidia.com (passaggio dai crediti ai limiti di velocità puri)
-**Strategia di ottimizzazione dei costi**: strategia di routing che sceglie automaticamente il fornitore più economico disponibile</details>

<dettagli>
<summary><b>🔒 5. "Devo proteggere il mio gateway AI da accessi non autorizzati"</b></summary>

Quando si espone un gateway AI alla rete (LAN, VPS, Docker), chiunque abbia l'indirizzo può consumare i token/la quota dello sviluppatore. Senza protezione, le API sono vulnerabili ad usi impropri, tempestive iniezioni e abusi.

**Come OmniRoute risolve il problema:**

-**Gestione delle chiavi API**: generazione, rotazione e definizione dell'ambito per provider con una pagina `/dashboard/api-manager` dedicata
-**Autorizzazioni a livello di modello**: limita le chiavi API a modelli specifici (`openai/*`, modelli con caratteri jolly), con l'interruttore Consenti tutto/Limita
-**API Endpoint Protection**: richiede una chiave per "/v1/models" e blocca fornitori specifici dall'elenco
-**Auth Guard + Protezione CSRF**: tutti i percorsi del dashboard protetti con middleware `withAuth` + token CSRF
-**Rate Limiter**: limitazione della velocità per IP con finestre configurabili
-**IP Filtering**— Allowlist/blocklist for access control
-**Prompt Injection Guard**: sanificazione contro modelli di prompt dannosi
-**Crittografia AES-256-GCM**: credenziali crittografate a riposo</details>

<dettagli>
<summary><b>🛑 6. "Il mio provider si è interrotto e ho perso il flusso di codifica"</b></summary>

I fornitori di intelligenza artificiale possono diventare instabili, restituire errori 5xx o raggiungere limiti di velocità temporanei. Se uno sviluppatore dipende da un singolo fornitore, viene interrotto. Without circuit breakers, repeated retries can crash the application.

**Come OmniRoute risolve il problema:**

-**Interruttore automatico per modello**: apertura/chiusura automatica con soglie e raffreddamento configurabili (chiuso/aperto/semiaperto), con ambito per modello per evitare blocchi a cascata
-**Backoff esponenziale**: ritardi progressivi tra i tentativi
-**Anti-Thundering Herd**— Mutex + protezione semaforo contro tempeste di tentativi simultanei
-**Catene di fallback combinate**: se il fornitore primario fallisce, cade automaticamente nella catena senza alcun intervento
-**Combo Circuit Breaker**: disabilita automaticamente i provider in errore all'interno di una catena combinata
-**Dashboard integrità**: monitoraggio del tempo di attività, stati degli interruttori automatici, blocchi, statistiche della cache, latenza p50/p95/p99</details>

<dettagli>
<summary><b>🔧 7. "Configurare ogni strumento AI è noioso e ripetitivo"</b></summary>

Gli sviluppatori utilizzano Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Ogni strumento necessita di una configurazione diversa (endpoint API, chiave, modello). La riconfigurazione quando si cambia fornitore o modello è una perdita di tempo.

**Come OmniRoute risolve il problema:**

-**Dashboard degli strumenti CLI**: pagina dedicata con configurazione con un clic per Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
-**Generatore di configurazione di GitHub Copilot**: genera `chatLanguageModels.json` per VS Code con selezione di modelli in blocco
-**Procedura guidata di onboarding**: configurazione guidata in 4 passaggi per gli utenti alle prime armi
-**Un endpoint, tutti i modelli**— Configura `http://localhost:20128/v1` una volta, accedi a oltre 60 provider</details>

<dettagli>
<summary><b>🔑 8. "Gestire token OAuth da più provider è un inferno"</b></summary>

Claude Code, Codex, Gemini CLI, Copilot: utilizzano tutti OAuth 2.0 con token in scadenza. Gli sviluppatori devono autenticarsi nuovamente costantemente, gestire "client_secret is Missing", "redirect_uri_mismatch" e errori sui server remoti. OAuth su LAN/VPS è particolarmente problematico.

**Come OmniRoute risolve il problema:**

-**Aggiornamento automatico dei token**: i token OAuth si aggiornano in background prima della scadenza
-**OAuth 2.0 (PKCE) integrato**: flusso automatico per Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder
-**OAuth multi-account**: account multipli per provider tramite estrazione di token JWT/ID
-**OAuth LAN/Remote Fix**: rilevamento IP privato per `redirect_uri` + modalità URL manuale per server remoti
-**OAuth Behind Nginx**: utilizza `window.location.origin` per la compatibilità con il proxy inverso
-**Guida OAuth remota**: guida passo passo per le credenziali Google Cloud su VPS/Docker</details>

<dettagli>
<summary><b>📊 9. "Non so quanto sto spendendo né dove"</b></summary>

Gli sviluppatori utilizzano più fornitori a pagamento ma non hanno una visione unificata della spesa. Ogni fornitore ha il proprio dashboard di fatturazione, ma non esiste una visualizzazione consolidata. I costi imprevisti possono accumularsi.

**Come OmniRoute risolve il problema:**

-**Dashboard di analisi dei costi**: monitoraggio dei costi per token e gestione del budget per fornitore
-**Limiti di budget per livello**: massimale di spesa per livello che attiva il fallback automatico
-**Configurazione dei prezzi per modello**: prezzi configurabili per modello
-**Statistiche di utilizzo per chiave API**: conteggio delle richieste e timestamp dell'ultimo utilizzo per chiave
-**Dashboard di analisi**: schede statistiche, grafico di utilizzo del modello, tabella dei fornitori con percentuali di successo e latenza</details>

<dettagli>
<summary><b>🐛 10. "Non riesco a diagnosticare errori e problemi nelle chiamate AI"</b></summary>

Quando una chiamata fallisce, lo sviluppatore non sa se si trattava di un limite di velocità, di un token scaduto, di un formato errato o di un errore del provider. Registri frammentati su diversi terminali. Senza osservabilità, il debug è un processo per tentativi ed errori.

**Come OmniRoute risolve il problema:**

-**Dashboard dei registri unificati**: 4 schede: registri delle richieste, registri del proxy, registri di controllo, console
-**Visualizzatore log della console**: visualizzatore in stile terminale in tempo reale con livelli codificati a colori, scorrimento automatico, ricerca, filtro
-**Registri proxy SQLite**: registri persistenti che sopravvivono ai riavvii del server
-**Translator Playground**— 4 modalità di debug: Playground (traduzione del formato), Chat Tester (andata e ritorno), Test Bench (batch), Live Monitor (in tempo reale)
-**Telemetria richiesta**: latenza p50/p95/p99 + traccia X-Request-Id
-**Registrazione basata su file con rotazione**: i registri delle app ruotano in base a dimensioni, giorni di conservazione e numero di archivi; gli artefatti del registro chiamate ruotano in base ai giorni di conservazione e al numero di file
-**Rapporto informazioni di sistema**: `npm run system-info` genera `system-info.txt` con l'ambiente completo (versione del nodo, versione di OmniRoute, sistema operativo, strumenti CLI, stato Docker/PM2). Allegalo quando segnali problemi per il triage immediato.</details>

<dettagli>
<summary><b>🏗️ 11. "L'implementazione e la manutenzione del gateway sono complesse"</b></summary>

L'installazione, la configurazione e la manutenzione di un proxy AI in diversi ambienti (locale, VPS, Docker, cloud) richiedono molto lavoro. Problemi come percorsi hardcoded, "EACCES" nelle directory, conflitti di porte e build multipiattaforma aggiungono attrito.

**Come OmniRoute risolve il problema:**

-**npm global install**— `npm install -g omniroute && omniroute` — fatto
-**Docker multipiattaforma**— AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi)
-**Docker Compose Profiles**— `base` (nessuno strumento CLI) e `cli` (con Claude Code, Codex, OpenClaw)
-**App desktop Electron**: app nativa per Windows/macOS/Linux con barra delle applicazioni, avvio automatico, modalità offline
-**Modalità porta divisa**: API e dashboard su porte separate per scenari avanzati (proxy inverso, rete di contenitori)
-**Cloud Sync**: configura la sincronizzazione tra dispositivi tramite Cloudflare Workers
-**Backup DB**: backup, ripristino, esportazione e importazione automatici di tutte le impostazioni, con `DISABLE_SQLITE_AUTO_BACKUP` per backup gestiti esternamente</details>

<dettagli>
<summary><b>🌍 12. "L'interfaccia è solo in inglese e il mio team non parla inglese"</b></summary>

I team nei paesi non anglofoni, soprattutto in America Latina, Asia ed Europa, hanno difficoltà con le interfacce solo in inglese. Le barriere linguistiche riducono l'adozione e aumentano gli errori di configurazione.

**Come OmniRoute risolve il problema:**

-**Dashboard i18n — 30 lingue**— Tutti gli oltre 500 tasti tradotti tra cui arabo, bulgaro, danese, tedesco, spagnolo, finlandese, francese, ebraico, hindi, ungherese, indonesiano, italiano, giapponese, coreano, malese, olandese, norvegese, polacco, portoghese (PT/BR), rumeno, russo, slovacco, svedese, tailandese, ucraino, vietnamita, cinese, filippino, inglese
-**Supporto RTL**: supporto da destra a sinistra per arabo ed ebraico
-**README multilingue**: 30 traduzioni complete di documentazione
-**Selettore lingua**: icona del globo nell'intestazione per la commutazione in tempo reale</details>

<dettagli>
<summary><b>🔄 13. "Mi serve qualcosa di più della semplice chat: mi servono incorporamenti, immagini e audio"</b></summary>

L'intelligenza artificiale non è solo il completamento della chat. Gli sviluppatori devono generare immagini, trascrivere audio, creare incorporamenti per RAG, riclassificare i documenti e moderare i contenuti. Ogni API ha un endpoint e un formato diversi.

**Come OmniRoute risolve il problema:**

-**Embedding**— `/v1/embeddings` con 6 provider e oltre 9 modelli
-**Generazione di immagini**— `/v1/images/ generations` con 10 provider e oltre 20 modelli (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
-**Trasformazione testo in video**— `/v1/videos/generazioni` — ComfyUI (AnimateDiff, SVD) e SD WebUI
-**Trasformazione testo in musica**— `/v1/music/ generations` — ComfyUI (Stable Audio Open, MusicGen)
-**Trascrizione audio**— `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3
-**Sintesi vocale**— `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3,**Inworld**,**Cartesia**,**PlayHT**, + fornitori esistenti
-**Moderazioni**— `/v1/moderations` — Controlli di sicurezza dei contenuti
-**Riclassificazione**— `/v1/rerank` — Riclassificazione della pertinenza del documento
-**API Response**: supporto completo `/v1/responses` per Codex</details>

<dettagli>
<summary><b>🧪 14. "Non ho modo di testare e confrontare la qualità dei modelli"</b></summary>

Gli sviluppatori vogliono sapere quale modello è il migliore per il loro caso d'uso (codice, traduzione, ragionamento), ma il confronto manuale è lento. Non esistono strumenti di valutazione integrati.

**Come OmniRoute risolve il problema:**

-**Valutazioni LLM**: test Golden Set con 10 casi precaricati che coprono saluti, matematica, geografia, generazione di codice, conformità JSON, traduzione, ribasso, rifiuto di sicurezza
-**4 strategie di corrispondenza**: "esatto", "contiene", "regex", "personalizzato" (funzione JS)
-**Translator Playground Test Bench**: test in batch con input multipli e output previsti, confronto tra provider
-**Chat Tester**: andata e ritorno completo con rendering della risposta visiva
-**Live Monitor**: flusso in tempo reale di tutte le richieste che passano attraverso il proxy</details>

<dettagli>
<summary><b>📈 15. "Ho bisogno di scalare senza perdere prestazioni"</b></summary>

Man mano che il volume delle richieste cresce, senza la memorizzazione nella cache le stesse domande generano costi duplicati. Senza idempotenza, le richieste duplicate sprecano elaborazione. I limiti tariffari per fornitore devono essere rispettati.

**Come OmniRoute risolve il problema:**

-**Cache semantica**: la cache a due livelli (firma + semantica) riduce costi e latenza
-**Idempotenza richiesta**: finestra di deduplicazione di 5 secondi per richieste identiche
-**Rilevamento del limite di velocità**: RPM per provider, gap minimo e monitoraggio simultaneo massimo
-**Limiti di velocità modificabili**: impostazioni predefinite configurabili in Impostazioni → Resilienza con persistenza
-**Cache di convalida della chiave API**: cache a 3 livelli per prestazioni di produzione
-**Dashboard integrità con telemetria**: latenza p50/p95/p99, statistiche cache, tempo di attività</details>

<dettagli>
<summary><b>🤖 16. "Voglio controllare il comportamento del modello a livello globale"</b></summary>

Sviluppatori che desiderano tutte le risposte in una lingua specifica, con un tono specifico o che desiderano limitare i token di ragionamento. Configurarlo in ogni strumento/richiesta non è pratico.

**Come OmniRoute risolve il problema:**

-**Inserimento prompt di sistema**: prompt globale applicato a tutte le richieste
-**Thinking Budget Validation**: controllo dell'allocazione dei token tramite ragionamento per richiesta (passthrough, automatico, personalizzato, adattivo)
-**9 Strategie di routing**: strategie globali che determinano la modalità di distribuzione delle richieste
-**Wildcard Router**— I modelli `provider/*` instradano dinamicamente a qualsiasi provider
-**Abilita/Disabilita combo**: attiva/disattiva le combo direttamente dalla dashboard
-**Attiva/disattiva provider**: attiva/disattiva tutte le connessioni per un provider con un clic
-**Provider bloccati**— Esclude fornitori specifici dall'elenco "/v1/models".</details>

<dettagli>
<summary><b>🧰 17. "Ho bisogno degli strumenti MCP come funzionalità di prodotto di prima classe"</b></summary>

Molti gateway AI espongono MCP solo come dettaglio di implementazione nascosto. I team hanno bisogno di un livello operativo visibile e gestibile.

**Come OmniRoute risolve il problema:**

- MCP viene visualizzato nella navigazione del dashboard e nella scheda del protocollo dell'endpoint
- Pagina di gestione MCP dedicata con processo, strumenti, ambiti e audit
- Avvio rapido integrato per `omniroute --mcp` e onboarding del client</details>

<dettagli>
<summary><b>🧠 18. "Ho bisogno dell'orchestrazione A2A con percorsi di attività di sincronizzazione e streaming"</b></summary>

I flussi di lavoro degli agenti necessitano sia di risposte dirette che di esecuzione in streaming di lunga durata con controllo del ciclo di vita.

**Come OmniRoute risolve il problema:**

- Endpoint A2A JSON-RPC (`POST /a2a`) con "messaggio/invia" e "messaggio/stream"
- Streaming SSE con propagazione dello stato terminale
- API del ciclo di vita delle attività per "tasks/get" e "tasks/cancel".</details>

<dettagli>
<summary><b>🛰️ 19. "Ho bisogno dello stato reale del processo MCP, non di uno stato indovinato"</b></summary>

I team operativi devono sapere se MCP è effettivamente attivo, non solo se un'API è raggiungibile.

**Come OmniRoute risolve il problema:**

- File heartbeat di runtime con PID, timestamp, trasporto, conteggio strumenti e modalità ambito
- API di stato MCP che combina battito cardiaco + attività recente
- Schede di stato dell'interfaccia utente per l'aggiornamento di processo/tempo di attività/battito cardiaco</details>

<dettagli>
<summary><b>📋 20. "Ho bisogno dell'esecuzione verificabile dello strumento MCP"</b></summary>

Quando gli strumenti modificano la configurazione o attivano azioni operative, i team necessitano di tracciabilità forense.

**Come OmniRoute risolve il problema:**

- Registrazione di controllo supportata da SQLite per le chiamate allo strumento MCP
- Filtri per strumento, successo/fallimento, chiave API e impaginazione
- Tabella di controllo della dashboard + endpoint statistici per l'automazione</details>

<dettagli>
<summary><b>🔐 21. "Ho bisogno di autorizzazioni MCP con ambito per integrazione"</b></summary>

Client diversi dovrebbero avere accesso con privilegi minimi alle categorie di strumenti.

**Come OmniRoute risolve il problema:**

- 10 ambiti MCP granulari per l'accesso controllato agli strumenti
- Applicazione dell'ambito e visibilità nell'interfaccia utente di gestione MCP
- Postura predefinita sicura per gli strumenti operativi</details>

<dettagli>
<summary><b>⚙️ 22. "Ho bisogno di controlli operativi senza ridistribuzione"</b></summary>

I team necessitano di rapidi cambiamenti di runtime durante incidenti o eventi di costo.

**Come OmniRoute risolve il problema:**

- Cambia l'attivazione combinata direttamente dalla dashboard MCP
- Applicare profili di resilienza da pacchetti di policy predefiniti
- Ripristinare lo stato dell'interruttore dallo stesso pannello operativo</details>

<dettagli>
<summary><b>🔄 23. "Ho bisogno di visibilità e annullamento del ciclo di vita delle attività A2A in tempo reale"</b></summary>

Senza visibilità del ciclo di vita, gli incidenti relativi alle attività diventano difficili da valutare.

**Come OmniRoute risolve il problema:**

- Elenco/filtro delle attività per stato/competenza con impaginazione
- Esamina i metadati, gli eventi e gli artefatti delle attività
- Endpoint di annullamento dell'attività e azione dell'interfaccia utente con conferma</details>

<dettagli>
<summary><b>🌊 24. "Ho bisogno di metriche di flusso attive per il carico A2A"</b></summary>

I flussi di lavoro in streaming richiedono informazioni operative sulla concorrenza e sulle connessioni live.

**Come OmniRoute risolve il problema:**

- Contatori di flussi attivi integrati nello stato A2A
- Timestamp dell'ultima attività e conteggi per stato
- Schede dashboard A2A per il monitoraggio delle operazioni in tempo reale</details>

<dettagli>
<summary><b>🪪 25. "Ho bisogno del rilevamento degli agenti standard per i clienti"</b></summary>

I client e gli agenti di orchestrazione esterni necessitano di metadati leggibili dal computer per l'onboarding.

**Come OmniRoute risolve il problema:**

- Scheda agente esposta in "/.well-known/agent.json".
- Capacità e competenze mostrate nell'interfaccia utente di gestione
- L'API di stato A2A include metadati di rilevamento per l'automazione</details>

<dettagli>
<summary><b>🧭 26. "Ho bisogno della rilevabilità del protocollo nell'UX del prodotto"</b></summary>

Se gli utenti non riescono a scoprire le superfici del protocollo, l'adozione e la qualità del supporto diminuiscono.

**Come OmniRoute risolve il problema:**

- Pagina**Endpoint**consolidata con schede per endpoint Proxy, MCP, A2A e API
- Commuta lo stato del servizio in linea (online/offline) per MCP e A2A
- Collegamenti dalla panoramica alle schede di gestione dedicate</details>

<dettagli>
<summary><b>🧪 27. "Ho bisogno della convalida del protocollo end-to-end con clienti reali"</b></summary>

I test simulati non sono sufficienti per verificare la compatibilità del protocollo prima del rilascio.

**Come OmniRoute risolve il problema:**

- Suite E2E che avvia l'app e utilizza il trasporto client SDK MCP reale
- Test client A2A per i flussi di rilevamento, invio, streaming, acquisizione e annullamento
- Effettuare un controllo incrociato delle asserzioni con l'audit MCP e le API delle attività A2A</details>

<dettagli>
<summary><b>📡 28. "Ho bisogno di osservabilità unificata su tutte le interfacce"</b></summary>

Suddividere l'osservabilità per protocollo crea punti ciechi e un MTTR più lungo.

**Come OmniRoute risolve il problema:**

- Dashboard/registri/analisi unificati in un unico prodotto
- Salute + audit + richiesta di telemetria su livelli OpenAI, MCP e A2A
- API operative per stato e automazione</details>

<dettagli>
<summary><b>💼 29. "Ho bisogno di un runtime per proxy + strumenti + orchestrazione dell'agente"</b></summary>

L'esecuzione di numerosi servizi separati aumenta i costi operativi e le modalità di guasto.

**Come OmniRoute risolve il problema:**

- Proxy compatibile con OpenAI, server MCP e server A2A in uno stack
- Autenticazione condivisa, resilienza, archivio dati e osservabilità
- Modello politico coerente su tutte le superfici di interazione</details>

<dettagli>
<summary><b>🚀 30. "Ho bisogno di distribuire flussi di lavoro agenti senza l'espansione incontrollata del codice"</b></summary>

I team perdono velocità quando uniscono più servizi e script ad hoc.

**Come OmniRoute risolve il problema:**

- Strategia endpoint unificata per clienti e agenti
- Interfacce utente di gestione del protocollo integrate e percorsi di convalida del fumo
- Fondamenti pronti per la produzione (sicurezza, registrazione, resilienza, backup)</details>

### Example Playbooks (Integrated Use Cases)

**Playbook A: Maximize paid subscription + cheap backup**

```txt
Combo: "maximize-claude"
  1. cc/claude-opus-4-6
  2. glm/glm-4.7
  3. if/kimi-k2-thinking

Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption

Playbook B: stack di codifica a costo zero```txt Combo: "free-forever"

gc/gemini-3-flash
if/kimi-k2-thinking
qw/qwen3-coder-plus

Monthly cost: $0 Outcome: stable free coding workflow


**Playbook C: catena di fallback sempre attiva 24 ore su 24, 7 giorni su 7**```txt
Combo: "always-on"
  1. cc/claude-opus-4-6
  2. cx/gpt-5.2-codex
  3. glm/glm-4.7
  4. minimax/MiniMax-M2.1
  5. if/kimi-k2-thinking

Outcome: deep fallback depth for deadline-critical workloads

Playbook D: operazioni dell'agente con MCP + A2A```txt

Start MCP transport (omniroute --mcp) for tool-driven operations
Run A2A tasks via message/send and message/stream
Observe via /dashboard/endpoint (MCP and A2A tabs)
Toggle services via inline status controls


---

## 🆓 Start Free — Zero Configuration Cost

> Configura la codifica AI in pochi minuti a**$ 0/mese**. Connect these free accounts and use the built-in**Free Stack**combo.

| Passo | Action                                             | Providers Unlocked                                                 |
| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |
| 1| Connect**Kiro**(AWS Builder ID OAuth)            | Claude Sonnet 4.5, Haiku 4.5 —**unlimited**                      |
| 2| Connect**Qoder**(Google OAuth)                   | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... —**unlimited**|
| 3| Connetti**Qwen**(codice dispositivo) | qwen3-coder-plus, qwen3-coder-flash... —**unlimited**            |
| 4| Connect**Gemini CLI**(Google OAuth)              | gemini-3-flash, gemini-2.5-pro —**180K/mo free**                 |
| 5| `/dashboard/combos` →**Free Stack ($0)**template | Round-robin all free providers automatically                       |

**Point any IDE/CLI to:**`http://localhost:20128/v1` · API Key: `any-string` · Done.

>**Copertura extra opzionale (anche gratuita):**Chiave API Groq (30 RPM gratuiti), NVIDIA NIM (40 RPM gratuiti, 70+ modelli), Cerebras (1 milione di tok/giorno), chiave API LongCat (50 milioni di token/giorno!), Cloudflare Workers AI (10.000 neuroni/giorno, 50+ modelli).## Avvio Rapido

### 1) Install and run

```bash
npm install -g omniroute
omniroute

**Utenti pnpm:**esegui pnpm approve-builds -g dopo l'installazione per abilitare gli script di build nativi richiesti da better-sqlite3 e @swc/core:
pnpm install -g omniroute
pnpm approve-builds -g # Seleziona tutti i pacchetti → approva
percorso omnicomprensivo

La dashboard si apre in "http://localhost:20128" e l'URL di base dell'API è "http://localhost:20128/v1".

Comando	Descrizione
`omnipercorso`	Avvia il server (`PORT=20128`, API e dashboard sulla stessa porta)
`omniroute --port 3000`	Imposta la porta canonica/API su 3000
`omniroute --mcp`	Avvia il server MCP (trasporto stdio)
`omniroute --no-open`	Non aprire automaticamente il browser
`omniroute --help`	Mostra aiuto

Modalità porta divisa opzionale:```bash PORT=20128 DASHBOARD_PORT=20129 omniroute

API: http://localhost:20128/v1

Dashboard: http://localhost:20129


### Long-Running Streaming Timeouts

Per la maggior parte delle distribuzioni sono necessari solo:

| Variabile | Predefinito | Scopo |
| ------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `REQUEST_TIMEOUT_MS` | `600000` | Base di riferimento condivisa per recupero upstream, timeout Undici nascosti, richieste di impronte digitali TLS e timeout proxy/richieste bridge API |
| `STREAM_IDLE_TIMEOUT_MS` | eredita `REQUEST_TIMEOUT_MS` | Intervallo massimo tra i blocchi di streaming prima che OmniRoute interrompa il flusso SSE |

La compatibilità con le versioni precedenti è preservata: `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS` esistenti e altre variabili di timeout per livello continuano a funzionare e sovrascrivono la linea di base condivisa.

Se hai bisogno di un controllo più preciso, sono disponibili sostituzioni avanzate:| Variabile | Predefinito | Scopo |
| --------------------------------------- | ----------------------------------- | -------------------------------------------------------------------- |
| `FETCH_TIMEOUT_MS` | eredita `REQUEST_TIMEOUT_MS` | Timeout totale della richiesta upstream utilizzato dal segnale di interruzione del recupero principale |
| `FETCH_HEADERS_TIMEOUT_MS` | eredita `FETCH_TIMEOUT_MS` | Limite temporale Undici per la ricezione delle intestazioni di risposta upstream |
| `FETCH_BODY_TIMEOUT_MS` | eredita `FETCH_TIMEOUT_MS` | Limite di tempo Undici tra i blocchi del corpo upstream (`0` lo disabilita) |
| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Timeout connessione TCP Undici |
| `FETCH_KEEPALIVE_TIMEOUT_MS` | "4000" | Timeout del socket keep-alive inattivo Undici |
| "TLS_CLIENT_TIMEOUT_MS" | eredita `FETCH_TIMEOUT_MS` | Timeout per le richieste di impronte digitali TLS effettuate tramite `wreq-js` |
| "API_BRIDGE_PROXY_TIMEOUT_MS" | eredita `REQUEST_TIMEOUT_MS` o `30000` | Timeout per l'inoltro proxy `/v1` dalla porta API alla porta del dashboard |
| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | "max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)" | Timeout della richiesta in entrata sul server bridge API |
| "API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS" | `60000` | Timeout dell'intestazione in entrata sul server bridge API |
| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Timeout keep-alive sul server bridge API |
| "API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS" | "0" | Timeout di inattività del socket sul server bridge API (`0` lo disabilita) |

Se esegui OmniRoute dietro Nginx, Caddy, Cloudflare o un altro proxy inverso, assicurati che il proxy
i timeout sono anche superiori ai timeout di flusso/recupero di OmniRoute.### 2) Connect providers and create your API key

1. Apri Dashboard → "Provider" e connetti almeno un fornitore (OAuth o chiave API).
2. Apri Dashboard → "Endpoint" e crea una chiave API.
3. (Facoltativo) Apri Dashboard → "Combo" e imposta la catena di fallback.### 3) Point your coding tool to OmniRoute

```txt
Base URL: http://localhost:20128/v1
API Key:  [copy from Endpoint page]
Model:    if/kimi-k2-thinking (or any provider/model prefix)

Funziona con Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode e SDK compatibili con OpenAI.### 4) Enable and validate protocols (v2.0)

MCP (per operazioni guidate da strumenti):```bash omniroute --mcp


Quindi collega il tuo client MCP su "stdio" e testa strumenti come:

- `omniroute_get_health`
- `omniroute_list_combos`

**A2A (per flussi di lavoro da agente ad agente):**```bash
curl http://localhost:20128/.well-known/agent.json

curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'

5) Validate everything end-to-end (recommended)

npm run test:protocols:e2e

This suite validates real MCP and A2A client flows against a running app.

Alternative: run from source

cp .env.example .env
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev

Void Linux (modello `xbps-src`)

Per gli utenti Void Linux, è possibile creare un pacchetto nativo utilizzando "xbps-src". Salva questo blocco come srcpkgs/omniroute/template:```bash

Template file for 'omniroute'

pkgname=omniroute version=3.4.1 revision=1 hostmakedepends="nodejs python3 make" depends="openssl" short_desc="Universal AI gateway with smart routing for multiple LLM providers" maintainer="zenobit zenobit@disroot.org" license="MIT" homepage="https://github.com/diegosouzapw/OmniRoute" distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b system_accounts="_omniroute" omniroute_homedir="/var/lib/omniroute" export NODE_ENV=production export npm_config_engine_strict=false export npm_config_loglevel=error export npm_config_fund=false export npm_config_audit=false

do_build() { # Determine target CPU arch for node-gyp local _gyp_arch case "$XBPS_TARGET_MACHINE" in aarch64*) _gyp_arch=arm64 ;; armv7*|armv6*) _gyp_arch=arm ;; i686*) _gyp_arch=ia32 ;; *) _gyp_arch=x64 ;; esac

# 1) Install all deps – skip scripts (no network in do_build, native modules
#    compiled separately below; better-sqlite3 is serverExternalPackage so
#    Next.js does not execute it during next build)
NODE_ENV=development npm ci --ignore-scripts

# 2) Build the Next.js standalone bundle
npm run build

# 3) Copy static assets into standalone
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true

# 4) Compile better-sqlite3 native binding for the target architecture.
#    Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used
#    without npm altering them.
local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

# 5) Place the compiled binding into the standalone bundle
local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
mkdir -p "$_bs3_release"
cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true
#    so sharp is not used at runtime; x64 .so files would break aarch64 strip
rm -rf .next/standalone/node_modules/@img

# 7) Copy pino runtime deps omitted by Next.js static analysis:
#    pino-abstract-transport – required by pino's worker thread
#    split2 – dep of pino-abstract-transport
#    process-warning – dep of pino itself
for _mod in pino-abstract-transport split2 process-warning; do
	cp -r "node_modules/$_mod" .next/standalone/node_modules/
done

}

do_check() { npm run test:unit }

do_install() { vmkdir usr/lib/omniroute/.next

vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

# Prevent removal of empty Next.js app router dirs by the post-install hook
for _d in \
	.next/standalone/.next/server/app/dashboard \
	.next/standalone/.next/server/app/dashboard/settings \
	.next/standalone/.next/server/app/dashboard/providers; do
	touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
done

cat > "${WRKDIR}/omniroute" <<'EOF'

#!/bin/sh export PORT="${PORT:-20128}" export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" export LOG_TO_FILE="${LOG_TO_FILE:-false}" mkdir -p "${DATA_DIR}" exec node /usr/lib/omniroute/.next/standalone/server.js "$@" EOF vbin "${WRKDIR}/omniroute" }

post_install() { vlicense LICENSE }


</details>

---

## 🐳 Docker

OmniRoute è disponibile come immagine Docker pubblica su [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).

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

Con file di ambiente:```bash

Copy and edit .env first

cp .env.example .env

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


**Utilizzo di Docker Compose:**```bash
# Base profile (no CLI tools)
docker compose --profile base up -d

# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d

Il supporto della dashboard per le distribuzioni Docker ora include unCloudflare Quick Tunnelcon un solo clic su "Dashboard → Endpoint". La prima abilitazione scarica cloudflared solo quando necessario, avvia un tunnel temporaneo verso il tuo attuale endpoint /v1 e mostra l'URL https://*.trycloudflare.com/v1 generato direttamente sotto il normale URL pubblico.

Note:

Gli URL del tunnel rapido sono temporanei e cambiano dopo ogni riavvio.
I tunnel rapidi non vengono ripristinati automaticamente dopo il riavvio di OmniRoute o del contenitore. Riattivarli dalla dashboard quando necessario.
L'installazione gestita attualmente supporta Linux, macOS e Windows su "x64"/"arm64".
I tunnel rapidi gestiti utilizzano per impostazione predefinita il trasporto HTTP/2 per evitare avvisi rumorosi del buffer QUIC UDP in ambienti container vincolati. Imposta CLOUDFLARED_PROTOCOL=quic o auto se desideri un trasporto diverso.
Le immagini Docker raggruppano le root CA del sistema e le passano a "cloudflared" gestito, evitando errori di attendibilità TLS quando il tunnel si avvia all'interno del contenitore.
SQLite funziona in modalità WAL. È necessario consentire il completamento di "docker stop" in modo che OmniRoute possa verificare le ultime modifiche in "storage.sqlite".
I file Compose in bundle impostano già un periodo di tolleranza di 40 secondi. Se esegui l'immagine direttamente, mantieni --stop-timeout 40 (o simile) in modo che gli arresti manuali non interrompano la pulizia dello spegnimento.
Imposta CLOUDFLARED_BIN=/absolute/path/to/cloudflared se desideri che OmniRoute utilizzi un file binario esistente invece di scaricarne uno.

Utilizzo di Docker Compose con Caddy (HTTPS Auto-TLS):

OmniRoute può essere esposto in modo sicuro utilizzando il provisioning SSL automatico di Caddy. Assicurati che il record DNS A del tuo dominio punti all'IP del tuo server.```yaml services: omniroute: image: diegosouzapw/omniroute:latest container_name: omniroute restart: unless-stopped volumes: - omniroute-data:/app/data environment: - PORT=20128 - NEXT_PUBLIC_BASE_URL=https://your-domain.com

caddy: image: caddy:latest container_name: caddy restart: unless-stopped ports: - "80:80" - "443:443" command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128

volumes: omniroute-data:


| Immagine | Etichetta | Taglia | Descrizione |
| ------------------------ | -------- | ------ | --------------------- |
| `diegosouzapw/omniroute` | `ultimo` | ~250 MB | Ultima versione stabile |
| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Versione attuale |---

## 🖥️ Desktop App — Offline & Always-On

> 🆕**NOVITÀ!**OmniRoute è ora disponibile come**applicazione desktop nativa**per Windows, macOS e Linux.

Esegui OmniRoute come app desktop autonoma: nessun terminale, nessun browser, nessuna connessione Internet richiesta per i modelli locali. L'app basata su Electron include:

- 🖥️**Finestra nativa**: finestra dell'app dedicata con integrazione nella barra delle applicazioni
- 🔄**Avvio automatico**: avvia OmniRoute all'accesso al sistema
- 🔔**Notifiche native**: ricevi avvisi in caso di esaurimento della quota o problemi con il provider
- ⚡**Installazione con un clic**: NSIS (Windows), DMG (macOS), AppImage (Linux)
- 🌐**Modalità offline**: funziona completamente offline con il server in bundle### Avvio Rapido

```bash
# Development mode
npm run electron:dev

# Build for your platform
npm run electron:build         # Current platform
npm run electron:build:win     # Windows (.exe)
npm run electron:build:mac     # macOS (.dmg) — x64 & arm64
npm run electron:build:linux   # Linux (.AppImage)

System Tray

Quando ridotto a icona, OmniRoute si trova nella barra delle applicazioni con azioni rapide:

Apri il cruscotto
Cambia la porta del server
Esci dall'applicazione

📖 Documentazione completa: electron/README.md---

💰 Pricing at a Glance

Livello	Fornitore	Costo	Reimpostazione quota	Ideale per
💳 ABBONAMENTO	Codice Claude (Pro)	$20/mese	5 ore + settimanale	Già iscritto
	Codice (Plus/Pro)	$20-200/mese	5 ore + settimanale	Utenti OpenAI
	Gemelli CLI	GRATIS	180K/mese + 1K/giorno	Tutti!
	Copilota GitHub	$ 10-19/mese	Mensile	Utenti GitHub
🔑 CHIAVE API	NVIDIA NIM	GRATUITO(sviluppatore per sempre)	~40 giri al minuto	Oltre 70 modelli aperti
	Cerebri	GRATUITO(1 milione di tok/giorno)	60.000 TPM/30 giri/min	Il più veloce del mondo
	Groq	GRATIS(30 GIRI)	14,4K RPD	Lama/Gemma ultraveloce
	DeepSeek V3.2	`0,27/` 1,10 per 1 milione	Nessuno	Miglior ragionamento prezzo/qualità
	xAI Grok-4 Veloce	`0,20/` 0,50 per 1 milione🆕	Nessuno	Più veloce + chiamata strumento, ultrabassa
	xAI Grok-4 (standard)	`0,20/` 1,50 per 1 milione 🆕	Nessuno	Fiore all'occhiello del ragionamento di xAI
	Maestrale	Prova gratuita + pagamento	Tariffa limitata	IA europea
	OpenRouter	Pagamento in base all'uso	Nessuno	Oltre 100 modelli aggr.
💰 ECONOMICO	GLM-5 (via Z.AI) 🆕	$ 0,5/1 milione	Tutti i giorni 10:00	Uscita 128K, nuova ammiraglia
	GLM-4.7	$ 0,6/1 milione	Tutti i giorni 10:00	Backup del budget
	MiniMax M2.5 🆕	Ingresso di $ 0,3/1 milione	5 ore di rotazione	Ragionamento + compiti agentici
	MiniMax M2.1	$ 0,2/1 milione	5 ore di rotazione	Opzione più economica
	Kimi K2.5 (API Moonshot) 🆕	Pagamento in base all'uso	Nessuno	Accesso diretto all'API Moonshot
	Kimi K2	$ 9/mese fisso	10 milioni di token/mese	Costo prevedibile
🆓 GRATUITO	Qoder	$0	Illimitato	5 modelli illimitati
	Qwen	$0	Illimitato	4 modelli illimitati
	Kiro	$0	Illimitato	Claude Sonetto/Haiku (costruttore AWS)
	LongCat Flash-Lite 🆕	$0(50 milioni di tok/giorno 🔥)	1 RPS	La più grande quota gratuita sulla Terra
	Impollinazioni AI 🆕	$0(nessuna chiave necessaria)	1 richiesta/15s	GPT-5, Claude, DeepSeek, Lama 4
	Cloudflare Workers AI 🆕	$0(10.000 neuroni/giorno)	~150 risposte/giorno	Oltre 50 modelli, vantaggio globale
	Scaleway AI 🆕	$0(totale di 1 milione di token)	Tariffa limitata	UE/GDPR, Qwen3 235B, Llama 70B	> 🆕Nuovi modelli aggiunti (marzo 2026):Famiglia Grok-4 Fast a `0,20/` 0,50/milione (benchmark a 1143 ms — 30% più veloce di Gemini 2.5 Flash), GLM-5 tramite Z.AI con output 128K, ragionamento MiniMax M2.5, prezzo aggiornato DeepSeek V3.2, Kimi K2.5 tramite Moonshot Direct API.

💡 Stack combinato da $ 0: la configurazione gratuita completa:```

🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever

Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥 Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed Qwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key Cloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU) Groq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day


**Costo zero. Non smette mai di scrivere codice.**Configuralo come una combinazione OmniRoute e tutti i fallback verranno eseguiti automaticamente, senza alcun passaggio manuale.---

---

## 🆓 Free Models — What You Actually Get

> Tutti i modelli riportati di seguito sono**gratuiti al 100% e non è richiesta alcuna carta di credito**. OmniRoute esegue automaticamente i percorsi tra di loro quando una quota si esaurisce: combinali tutti per una combinazione indistruttibile a $ 0.### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)

| Modello | Prefisso | Limite | Limite di velocità |
| ------------------- | ------ | ------------- | --------------------- |
| `claude-sonetto-4.5` | `kr/` |**Illimitato**| Nessun limite giornaliero riportato |
| `claude-haiku-4.5` | `kr/` |**Illimitato**| Nessun limite giornaliero segnalato |
| `claude-opus-4.6` | `kr/` |**Illimitato**| Ultima opera tramite Kiro |### 🟢 QODER MODELS (Free PAT via qodercli)

| Modello | Prefisso | Limite | Limite di velocità |
| ------------------ | ------ | ------------- | --------------- |
| `kimi-k2-pensiero` | `se/` |**Illimitato**| Nessun limite riportato |
| `qwen3-coder-plus` | `se/` |**Illimitato**| Nessun limite riportato |
| `deepseek-r1` | `se/` |**Illimitato**| Nessun limite segnalato |
| `minimax-m2.1` | `se/` |**Illimitato**| Nessun limite riportato |
| `kimi-k2` | `se/` |**Illimitato**| Nessun limite segnalato |

> Metodo di connessione consigliato:**Token di accesso personale + `qodercli`**. OAuth del browser lo è
> sperimentale e disabilitato per impostazione predefinita a meno che non siano configurate le variabili di ambiente `QODER_OAUTH_*`.### 🟡 QWEN MODELS (Device Code Auth)

| Modello | Prefisso | Limite | Limite di velocità |
| ------------------- | ------ | ------------- | ------------------- |
| `qwen3-coder-plus` | `qw/` |**Illimitato**| Nessun limite riportato |
| `qwen3-coder-flash` | `qw/` |**Illimitato**| Nessun limite riportato |
| `qwen3-coder-next` | `qw/` |**Illimitato**| Nessun limite riportato |
| `modello-visione` | `qw/` |**Illimitato**| Multimodale (immagini) |### 🟣 GEMINI CLI (Google OAuth)

| Modello | Prefisso | Limite | Limite di velocità |
| ------------------------ | ------ | --------------------- | ------------- |
| `gemini-3-flash-anteprima` | `gc/` |**180K tok/mese**+ 1K/giorno | Reset mensile |
| `gemini-2.5-pro` | `gc/` | 180K/mese (pool condiviso) | Alta qualità |### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)

| Livello | Limite giornaliero | Limite di velocità | Note |
| ---------- | ------------ | ----------- | ------------------------------------------------------ |
| Libero (Sviluppo) | Nessun limite massimo |**~40 giri/min**| Oltre 70 modelli; transizione ai limiti tariffari puri a metà del 2025 |

Modelli gratuiti popolari: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)

| Livello | Limite giornaliero | Limite di velocità | Note |
| ---- | ----------------- | ---------------- | -------------------------------------------------- |
| Gratuito |**1 milione di token/giorno**| 60.000 TPM/30 giri/min | L'inferenza LLM più veloce al mondo; si ripristina quotidianamente |

Disponibili gratuitamente: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`### 🔴 GROQ (Free API Key — console.groq.com)

| Livello | Limite giornaliero | Limite di velocità | Note |
| ---- | ------------- | ---------------- | ----------------------------------------- |
| Gratuito |**14,4K RPD**| 30 giri/min per modello | Nessuna carta di credito; 429 al limite, non addebitato |

Disponibili gratuitamente: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕

| Modello | Prefisso | Quota gratuita giornaliera | Note |
| ----------------------- | ------ | ----------------- | ----------------------- |
| `LongCat-Flash-Lite` | `lc/` |**50 milioni di token**💥 | La quota gratuita più grande di sempre |
| `LongCat-Flash-Chat` | `lc/` | Gettoni da 500.000 | Chat multigiro |
| `LongCat-Flash-Thinking` | `lc/` | Gettoni da 500.000 | Ragionamento/CoT |
| `LongCat-Flash-Thinking-2601` | `lc/` | Gettoni da 500.000 | Versione gennaio 2026 |
| `LongCat-Flash-Omni-2603` | `lc/` | Gettoni da 500.000 | Multimodale |

> 100% gratuito durante la beta pubblica. Iscriviti a [longcat.chat](https://longcat.chat) tramite e-mail o telefono. Si ripristina ogni giorno alle 00:00 UTC.### 🟢 POLLINATIONS AI (No API Key Required) 🆕

| Modello | Prefisso | Limite di velocità | Fornitore dietro |
| ---------- | ------ | ---------- | ------------------ |
| `openai` | `pol/` | 1 richiesta/15s | GPT-5 |
| `claude` | `pol/` | 1 richiesta/15s | Claude antropico |
| `gemelli` | `pol/` | 1 richiesta/15s | Google Gemelli |
| `ricerca profonda` | `pol/` | 1 richiesta/15s | DeepSeek V3 |
| `lama` | `pol/` | 1 richiesta/15s | Meta Lama 4 Esploratore |
| `maestrale` | `pol/` | 1 richiesta/15s | Maestrale AI |

> ✨**Zero attrito:**Nessuna registrazione, nessuna chiave API. Aggiungi il provider Pollinations con un campo chiave vuoto e funzionerà immediatamente.### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕

| Livello | Neuroni giornalieri | Utilizzo equivalente | Note |
| ---- | ------------- | --------------------------------------- | ----------------------- |
| Gratuito |**10.000**| ~150 risposte LLM / 500 audio / 15.000 incorporamenti | Vantaggio globale, oltre 50 modelli |

Modelli gratuiti popolari: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (audio gratuito!), `@cf/qwen/qwen2.5-coder-15b-instruct`

> Richiede token API + ID account da [dash.cloudflare.com](https://dash.cloudflare.com). Memorizza l'ID account nelle impostazioni del provider.### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕

| Livello | Quota libera | Posizione | Note |
| ---- | ------------- | ------------ | ----------------------------------- |
| Gratuito |**1 milione di gettoni**| 🇫🇷 Parigi, UE | Nessuna carta di credito necessaria entro i limiti |

Disponibile gratuitamente: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`

> Conforme all'UE/GDPR. Ottieni la chiave API su [console.scaleway.com](https://console.scaleway.com).

>**💡 Lo stack gratuito definitivo (11 fornitori, $ 0 per sempre):**
>
> ```
> Kiro (kr/) → Claude Sonnet/Haiku ILLIMITATO
> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 ILLIMITATO
> LongCat Lite (lc/) → LongCat-Flash-Lite — 50 milioni di token al giorno 🔥
> Impollinazioni (pol/) → GPT-5, Claude, DeepSeek, Llama 4: nessuna chiave necessaria
> Qwen (qw/) → modelli qwen3-coder ILLIMITATI
> Gemini (gemini/) → Gemini 2.5 Flash — 1.500 richieste/giorno gratis
> Cloudflare AI (cf/) → Oltre 50 modelli: 10.000 neuroni al giorno
> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1 milione di token gratuiti (UE)
> Groq (groq/) → Lama/Gemma — 14.4K richieste/giorno ultraveloci
> NVIDIA NIM (nvidia/) → Oltre 70 modelli aperti: 40 RPM per sempre
> Cerebras (cerebras/) → Lama/Qwen il più veloce al mondo — 1 milione di tok/giorno
> ```## 🎙️ Free Transcription Combo

> Trascrivi qualsiasi audio/video per**$ 0**: Deepgram guida con $ 200 gratuiti, AssemblyAI $ 50 di riserva, Groq Whisper come backup di emergenza illimitato.

| Fornitore | Crediti gratuiti | Miglior modello | Limite di velocità |
| ----------------- | ---------------------- | -------------------------------------------- | ---------------------- |
| 🟢**Deepgram**|**$200 gratuiti**(iscrizione) | `nova-3`: massima precisione, oltre 30 lingue | Nessun limite RPM sui crediti gratuiti |
| 🔵**AssembleaAI**|**$50 gratuiti**(iscrizione) | `universal-3-pro`: capitoli, sentimento, PII | Nessun limite RPM sui crediti gratuiti |
| 🔴**Groq**|**Gratis per sempre**| `sussurro-large-v3` — OpenAI Whisper | 30 giri/min (velocità limitata) |

**Combinazione suggerita in `/dashboard/combos`:**```
Name: free-transcription
Strategy: Priority
Nodes:
  [1] deepgram/nova-3          → uses $200 free first
  [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out
  [3] groq/whisper-large-v3    → free forever, emergency fallback

Quindi in /dashboard/media → schedaTrascrizione: carica qualsiasi file audio o video → seleziona il tuo endpoint combinato → ottieni la trascrizione nei formati supportati.## 💡 Key Features

OmniRoute v2.0 è costruito come piattaforma operativa, non solo come proxy di inoltro.### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)

Caratteristica	Cosa fa
⚡Grok-4 Fast Family	Modelli xAI a 0,20 $/0,50 $/milione: 1.143 ms con benchmark (30% più veloce di Gemini 2.5 Flash)
🧠GLM-5 via Z.AI	Contesto di output da 128.000, $ 0,5/1 milione: il nuovo fiore all'occhiello della famiglia GLM
🔮MiniMax M2.5	Ragionamento + compiti di agente a 0,30 dollari/1 milione: miglioramento significativo rispetto a M2.1
🎯toolCalling Flag per modello	`toolCalling: true/false` per modello nel registro: AutoCombo ignora i modelli non compatibili con lo strumento
🌍Rilevamento dell'intento multilingue	Parole chiave PT/ZH/ES/AR nel punteggio AutoCombo: migliore selezione del modello per contenuti non inglesi
📊Falback basati sul benchmark	La latenza p95 reale dalle richieste in tempo reale alimenta il punteggio combinato: AutoCombo apprende dai dati effettivi
🔁Richiedi deduplicazione	Finestra di deduplicazione basata sull'hash dei contenuti: sicura per più agenti, impedisce addebiti duplicati
🔌Strategia router collegabile	Interfaccia `RouterStrategy` estensibile: aggiungi logica di routing personalizzata come plug-in	### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP

Caratteristica	Cosa fa
🎮Parco giochi modello	Pagina dashboard per testare direttamente qualsiasi modello: selettori provider/modello/endpoint, Monaco Editor, streaming, interruzione, tempistica
🔏Corrispondenza impronta digitale CLI	Ordinamento dell'intestazione/corpo per provider in modo che corrisponda alle firme CLI native: attiva/disattiva per provider in Impostazioni > Sicurezza.Il tuo IP proxy viene preservato
🤝Supporto ACP (protocollo agente client)	Rilevamento agente CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + altri 9), generatore di processi, endpoint `/api/acp/agents`
🤖Dashboard agenti ACP	Debug › Pagina Agenti: griglia di 14 agenti con stato di installazione, versione, modulo agente personalizzato per qualsiasi strumento CLI. Gli utentiOpenCodericevono un pulsante "Scarica opencode.json" che genera automaticamente una configurazione pronta per l'uso con tutti i modelli disponibili.
🔧Instradamento del modello personalizzato `apiFormat`	I modelli personalizzati con `apiFormat: "responses"` ora vengono indirizzati correttamente al traduttore dell'API Responses
🏢Codice Isolamento dello spazio di lavoro	Aree di lavoro Codex multiple per e-mail: OAuth separa correttamente le connessioni in base all'ID dell'area di lavoro
🔄Aggiornamento automatico Electron	L'app desktop verifica la disponibilità di aggiornamenti + installazione automatica al riavvio	### 🤖 Agent & Protocol Operations (v2.0)

Caratteristica	Cosa fa
🔧Server MCP (25 strumenti)	Strumenti IDE/agente tramite 3 trasporti: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memoria + 4 strumenti di abilità
🤝Server A2A (JSON-RPC + SSE)	Esecuzione di attività da agente ad agente con flussi di sincronizzazione e streaming
🧭Pagina Endpoint consolidati	Pagina di gestione a schede con schede Endpoint Proxy, MCP, A2A e Endpoint API
🎚️Abilita/Disabilita servizio	Interruttori ON/OFF per MCP e A2A con persistenza delle impostazioni (default: OFF)
🛰️MCP Runtime Heartbeat	Stato reale del processo (pid, tempo di attività, età dell'heartbeat, trasporto, modalità ambito)
📋Pista di controllo MCP	Registri di controllo filtrabili con successo/fallimento e attribuzione chiave
🔐Applicazione dell'ambito MCP	10 autorizzazioni di ambito granulare per l'accesso controllato agli strumenti
📡Gestione del ciclo di vita delle attività A2A	Elenca/filtra attività, ispeziona eventi/artefatti, annulla attività in esecuzione
📋Scoperta Carta Agente	`/.well-known/agent.json` per il rilevamento automatico del client
🧪Cablaggio di prova protocollo E2E	Il client Real MCP SDK + A2A scorre in `test:protocols:e2e`
⚙️Controlli operativi	Cambia combo, applica profili di resilienza, reimposta gli interruttori da un'unica superficie di controllo	### 🧠 Routing & Intelligence

Caratteristica	Cosa fa
🎯Ripiego intelligente a 4 livelli	Percorso automatico: Abbonamento → Chiave API → Economico → Gratuito
📊Monitoraggio delle quote in tempo reale	Conteggio dei token in tempo reale + reimpostazione del conto alla rovescia per provider
🔄Traduzione del formato	OpenAI ↔ Claude ↔ Gemini ↔ Risposte con conversioni sicure per schema
👥Supporto per più account	Conti multipli per fornitore con selezione intelligente
🔄Aggiornamento automatico token	I token OAuth si aggiornano automaticamente con il nuovo tentativo
🎨Combo personalizzati	9 strategie di bilanciamento + controllo della catena di fallback
🌐Router con caratteri jolly	`provider/*` instradamento dinamico
🧠Pensare al controllo del budget	Limiti di ragionamento passthrough, automatico, personalizzato e adattivo
🔀Alias modello	Aliasing del modello integrato + personalizzato e sicurezza della migrazione
⚡Degradazione dello sfondo	Instradare le attività in background a bassa priorità verso modelli più economici
🧪Routing intelligente basato sulle attività	Seleziona automaticamente il modello per tipo di contenuto (codifica/visione/analisi/riepilogo)
🔄Flussi di lavoro dell'agente A2A	Orchestratore FSM deterministico per esecuzioni di agenti multi-step con stato
🔀Percorso adattivo	Override della strategia dinamica basata sul volume dei token e sulla complessità dei prompt
🎲Diversità dei fornitori	Punteggio entropico di Shannon che bilancia la distribuzione del traffico combinato automatico
💬Iniezione richiesta di sistema	Controlli del comportamento globale applicati in modo coerente
📄Compatibilità API risposte	Supporto completo `/v1/responses` per Codex e flussi di lavoro avanzati con agenti	### 🎵 Multi-Modal APIs

Caratteristica	Cosa fa
🖼️Generazione di immagini	`/v1/images/ generations` con cloud e backend locali
📐Incorporamenti	`/v1/embeddings` per le pipeline di ricerca e RAG
🎤Trascrizione audio	`/v1/audio/transcriptions` — 7 fornitori (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), rilevamento automatico della lingua, supporto MP4/MP3/WAV
🔊Sintesi vocale	`/v1/audio/speech` — 10 fornitori (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) con messaggi di errore corretti
🎬Generazione video	`/v1/videos/generazioni` (flussi di lavoro ComfyUI + SD WebUI)
🎵Generazione musicale	`/v1/music/ generations` (flussi di lavoro ComfyUI)
🛡️Moderazioni	Controlli di sicurezza `/v1/moderazioni`
🔀Riclassifica	`/v1/rerank` per il punteggio di pertinenza
🔍Ricerca sul Web🆕	`/v1/search` — 5 provider (Serper, Brave, Perplexity, Exa, Tavily), oltre 6.500 gratuiti al mese, failover automatico, cache	### 🛡️ Resilience, Security & Governance

Caratteristica	Cosa fa
🔌Interruttori automatici	Scatto/recupero per modello con controlli di soglia
🎯Modelli sensibili agli endpoint	I modelli personalizzati dichiarano gli endpoint supportati + il formato API
🛡️Mandria Antituonante	Mutex + protezioni semaforo su eventi ripetizione/velocità
🧠Semantica + Cache delle firme	Riduzione costi/latenza con due livelli di cache
⚡Richiesta Idempotenza	Finestra di protezione duplicata
🔒Spoofing delle impronte digitali TLS	Impronta digitale TLS simile a un browser:riduce il rilevamento dei bot e la segnalazione degli account
🔏Corrispondenza impronta digitale CLI	Corrisponde alle firme delle richieste CLI native:riduce il rischio di ban preservando l'IP proxy
🌐Filtro IP	Controllo della lista consentita/lista bloccata per le distribuzioni esposte
📊Limiti di velocità modificabili	Limiti globali/a livello di provider configurabili con persistenza
📉Degradazione graziosa	Fallback con funzionalità multilivello che proteggono le operazioni principali del gateway
📜Traccia di controllo della configurazione	Tracciamento delle modifiche basato sulle differenze che impedisce la deriva operativa con semplici rollback
⏳Sincronizzazione integrità fornitore	Monitoraggio proattivo della scadenza dei token che attiva avvisi prima degli errori di autorizzazione
🚪Disabilita automaticamente gli account esclusi	Interruttore automatico che sigilla automaticamente gli account token bloccati in modo permanente
🔑Gestione delle chiavi API e ambito	Emissione/rotazione sicura delle chiavi e controlli del modello/fornitore
👁️Rivelazione chiave API con ambito🆕	Attiva il ripristino delle chiavi API tramite `ALLOW_API_KEY_REVEAL`
🛡️Protetti `/models`	Autenticazione opzionale e nascondiglio del provider per il catalogo dei modelli	### 📊 Observability & Analytics

Caratteristica	Cosa fa
📝Richiesta + Registrazione proxy	Richiesta/risposta completa e registrazione proxy
📉Registri dettagliati in streaming🆕	Ricostruisce in modo pulito i flussi di payload SSE nell'interfaccia utente
📋Dashboard dei registri unificati	Visualizzazioni richieste, proxy, audit e console in un'unica pagina
🔍Richiedi telemetria	latenza p50/p95/p99 e tracciamento delle richieste
🏥Dashboard della salute	Tempo di attività, stati degli interruttori, blocchi, statistiche della cache
💰Monitoraggio dei costi	Budget controls and per-model pricing visibility
📈Visualizzazioni analitiche	Approfondimenti sull'utilizzo del modello/fornitore e visualizzazioni delle tendenze
🧪Quadro di valutazione	Test del set d'oro con strategie di corrispondenza configurabili
📡Diagnostica in tempo reale🆕	Bypass semantico della cache per test live combinati accurati	### ☁️ Deployment & Platform

Caratteristica	Cosa fa
🌐Distribuisci ovunque	Localhost, VPS, Docker, ambienti cloud
🚇Tunnel Cloudflare🆕	Integrazione Quick Tunnel con un clic dalla dashboard
🔑Filtro modello chiave API	Risposta nativa /v1/models filtrata tramite i ruoli di contesto Bearer assegnati
⚡Bypass intelligente della cache	Euristica TTL configurabile e controlli di recupero forzato
🔄Backup/Ripristino	Flussi di import/export e disaster recovery
🧙Procedura guidata di inserimento	Configurazione guidata al primo avvio
🔧Dashboard degli strumenti CLI	Configurazione con un clic per gli strumenti di codifica più diffusi
🎮Parco giochi modello	Testa qualsiasi provider/modello/endpoint dalla dashboard
🔏Attiva/disattiva impronta digitale CLI	Corrispondenza dell'impronta digitale per provider in Impostazioni > Sicurezza
🌐i18n (30 lingue)	Full dashboard + docs language support with RTL coverage
🧹Cancella tutti i modelli	Cancellazione dell'elenco dei modelli con un clic nei dettagli del fornitore
👁️Controlli della barra laterale🆕	Nascondi componenti e integrazioni da Impostazioni aspetto
📋Modelli di problemi	Modelli GitHub standardizzati per bug e funzionalità
📂Directory dati personalizzata	Sostituzione di `DATA_DIR` per la posizione di archiviazione	### Feature Deep Dive

Smart fallback with practical cost control

Combo: "my-coding-stack"
  1. cc/claude-opus-4-6
  2. nvidia/llama-3.3-70b
  3. glm/glm-4.7
  4. if/kimi-k2-thinking

Quando la quota, la tariffa o l'integrità vengono meno, OmniRoute passa automaticamente al candidato successivo senza passaggio manuale.#### Protocol management that is visible and operable

MCP + A2A sono rilevabili nell'interfaccia utente e nei documenti (non nascosti)
Le API di stato del protocollo espongono dati operativi in tempo reale (/api/mcp/*, /api/a2a/*)
I dashboard includono azioni per le operazioni del secondo giorno (attivazioni/disattivazione combo, ripristino degli interruttori, annullamento delle attività)#### Translator + validation workflow

L'area Traduttore comprende:

-Parco giochi: richiedi controlli di trasformazione -Chat Tester: richiesta/risposta completa andata e ritorno -Banco di prova: più casi in un'unica esecuzione -Live Monitor: visualizzazione del traffico in tempo reale

Inoltre convalida del protocollo con client reali tramite npm run test:protocols:e2e.

📖README del server MCP: riferimenti allo strumento, configurazioni IDE ed esempi di client

📖README del server A2A: competenze, metodi JSON-RPC, streaming e ciclo di vita delle attività## 🧪 Evaluations (Evals)

OmniRoute include un framework di valutazione integrato per testare la qualità della risposta LLM rispetto a un golden set. Access it viaAnalytics → Evalsin the dashboard.### Built-in Golden Set

L'"OmniRoute Golden Set" precaricato contiene casi di test per:

Saluti, matematica, geografia, generazione di codici
Conformità al formato JSON, traduzione, generazione di markdown
Rifiuto di sicurezza (contenuto dannoso), conteggio, logica booleana### Evaluation Strategies

Strategia	Descrizione	Esempio
`esatto`	L'output deve corrispondere esattamente a	`"4"`
`contains`	L'output deve contenere una sottostringa (senza distinzione tra maiuscole e minuscole)	`"Parigi"`
`regex`	L'output deve corrispondere al modello regex	`"1.2.3"`
"personalizzato"	La funzione JS personalizzata restituisce vero/falso	`(output) => output.lunghezza > 10`	---

📖 Setup Guide

Protocol Setup (MCP + A2A)

🧩 Configurazione MCP (Model Context Protocol)

Avvia il trasporto MCP in modalità stdio:```bash omniroute --mcp


Flusso di convalida consigliato:

1. Connetti il tuo client MCP su stdio.
2. Esegui `omniroute_get_health`.
3. Esegui `omniroute_list_combos`.
4. Apri "/dashboard/mcp" per confermare battito cardiaco, attività e controllo.

API utili per l'automazione:

- "OTTIENI /api/mcp/status".
- `OTTIENI /api/mcp/tools`
- "OTTIENI /api/mcp/audit".
- "OTTIENI /api/mcp/audit/stats".</details>

<dettagli>
<summary><b>🤝 Configurazione A2A (Agent2Agent)</b></summary>

Scopri l'agente:```bash
curl http://localhost:20128/.well-known/agent.json

Invia un'attività:```bash curl -X POST http://localhost:20128/a2a
-H 'content-type: application/json'
-d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'


Gestisci il ciclo di vita:

- "OTTIENI /api/a2a/status".
- "OTTIENI /api/a2a/tasks".
- `GET /api/a2a/tasks/:id`
- `POST /api/a2a/tasks/:id/cancel`

Interfaccia utente operativa:

- "/dashboard/a2a" per l'osservabilità di attività/stato/flusso e azioni di fumo</details>

<dettagli>
<summary><b>🧪 Convalida del protocollo end-to-end</b></summary>

Convalida entrambi i protocolli con client reali:```bash
npm run test:protocols:e2e

This verifies:

Connessione/elenco/chiamata del client SDK MCP
Rilevamento/invio/streaming/acquisizione/annullamento A2A
Controllo incrociato dei dati nell'audit MCP e nelle API di gestione delle attività A2A

💳 Fornitori di abbonamenti

### Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-6
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001

**Suggerimento professionale:**usa Opus per attività complesse, Sonnet per la velocità. OmniRoute tiene traccia della quota per modello!### OpenAI Codex (Plus/Pro)

Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max

Codex Account Limit Management (5h + Weekly)

Ogni account Codex ora dispone di opzioni di attivazione/disattivazione delle policy in Dashboard -> Provider:

"5h" (ON/OFF): applica la politica di soglia della finestra di 5 ore.
"Settimanale" (ON/OFF): applica la politica di soglia della finestra settimanale.
Comportamento soglia: quando una finestra abilitata raggiunge un utilizzo >=90%, quell'account viene saltato.
Comportamento di rotazione: OmniRoute instrada automaticamente al successivo account Codex idoneo.
Comportamento di ripristino: allo scadere del tempo "resetAt" del provider, l'account diventa nuovamente idoneo automaticamente.

Scenari:

5h ON + Weekly ON: l'account viene saltato quando una delle finestre raggiunge la soglia.
5h OFF + Weekly ON: solo l'utilizzo settimanale può bloccare l'account.
5h ON + Weekly OFF: solo un utilizzo di 5 ore può bloccare l'account.
resetAt superato: l'account rientra automaticamente nella rotazione (nessuna riattivazione manuale).### Gemini CLI (FREE 180K/month!)

Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day

Models:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro

**Miglior rapporto qualità-prezzo:**Enorme livello gratuito! Utilizzalo prima dei livelli a pagamento.### GitHub Copilot

Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3.1-pro-preview

🔑 Provider di chiavi API

### NVIDIA NIM (FREE developer access — 70+ models)

Iscriviti: build.nvidia.com
Ottieni la chiave API gratuita (1000 crediti di inferenza inclusi)
Dashboard → Aggiungi fornitore → NVIDIA NIM:
- Chiave API: nvapi-your-key

Modelli:nvidia/llama-3.3-70b-instruct, nvidia/mistral-7b-instruct e oltre 50 altri

**Suggerimento professionale:**API compatibile con OpenAI: funziona perfettamente con la traduzione del formato di OmniRoute!### DeepSeek

Iscriviti: platform.deepseek.com
Ottieni la chiave API
Dashboard → Aggiungi fornitore → DeepSeek

Modelli:deepseek/deepseek-chat, deepseek/deepseek-coder### Groq (Free Tier Available!)

Iscriviti: console.groq.com
Ottieni la chiave API (livello gratuito incluso)
Dashboard → Aggiungi fornitore → Groq

Modelli:groq/llama-3.3-70b, groq/mixtral-8x7b

**Suggerimento da professionista:**Inferenza ultraveloce: ideale per la codifica in tempo reale!### OpenRouter (100+ Models)

Iscriviti: openrouter.ai
Ottieni la chiave API
Dashboard → Aggiungi provider → OpenRouter

**Modelli:**accedi a oltre 100 modelli di tutti i principali fornitori tramite un'unica chiave API.

Comportamento della dashboard:i modelli OpenRouter sono gestiti daModelli disponibili. L'aggiunta manuale, l'importazione e la sincronizzazione automatica aggiornano tutti lo stesso elenco.

💰 Fornitori economici (backup)

### GLM-4.7 (Daily reset, $0.6/1M)

Iscriviti: Zhipu AI
Ottieni la chiave API dal piano di codifica
Dashboard → Aggiungi chiave API:
- Fornitore: glm
- Chiave API: "la tua chiave".

Utilizzare:glm/glm-4.7

**Suggerimento professionale:**Il piano di codifica offre una quota 3× a un costo di 1/7! Resetta ogni giorno alle 10:00.### MiniMax M2.1 (5h reset, $0.20/1M)

Iscriviti: MiniMax
Ottieni la chiave API
Dashboard → Aggiungi chiave API

Utilizzo:minimax/MiniMax-M2.1

**Suggerimento professionale:**Opzione più economica per contesti lunghi (token da 1 milione)!### Kimi K2 ($9/month flat)

Iscriviti: Moonshot AI
Ottieni la chiave API
Dashboard → Aggiungi chiave API

Utilizzare:kimi/kimi-latest

**Suggerimento da professionista:**Risolti 9$ al mese per 10 milioni di token = 0,90$/1 milione di costi effettivi!

🆓 Provider GRATUITI (backup di emergenza)

### Qoder (5 FREE models via OAuth)

Dashboard → Connect Qoder
→ Qoder OAuth login
→ Unlimited usage

Models:
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1

Qwen (4 FREE models via Device Code)

Dashboard → Connect Qwen
→ Device code authorization
→ Unlimited usage

Models:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash

Kiro (Claude FREE)

Dashboard → Connect Kiro
→ AWS Builder ID or Google/GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5

🎨Crea combo

### Example 1: Maximize Subscription → Cheap Backup

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-6 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding

Example 2: Free-Only (Zero Cost)

Name: free-combo
Models:
  1. gc/gemini-3-flash-preview (180K free/month)
  2. if/kimi-k2-thinking (unlimited)
  3. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!

🔧Integrazione CLI

### Cursor IDE

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from OmniRoute dashboard]
  Model: cc/claude-opus-4-6

Claude Code

Utilizza la paginaStrumenti CLInel dashboard per la configurazione con un clic o modifica manualmente ~/.claude/settings.json.### Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"

codex "your prompt"

OpenClaw

Opzione 1: Dashboard (consigliata):``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply


**Opzione 2 — Manuale:**Modifica `~/.openclaw/openclaw.json`:```json
{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}

**Nota:**OpenClaw funziona solo con OmniRoute locale. Utilizza "127.0.0.1" invece di "localhost" per evitare problemi di risoluzione IPv6.### Cline / Continue / RooCode

Settings → API Configuration:
  Provider: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  API Key: [from OmniRoute dashboard]
  Model: if/kimi-k2-thinking

OpenCode

**Passaggio 1:**aggiungi OmniRoute come provider personalizzato:```bash opencode /connect

Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key


**Passaggio 2:**Crea/modifica `opencode.json` nella root del tuo progetto:```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
      }
    }
  }
}

**Passaggio 3:**Seleziona il modello in OpenCode:```bash /models

Select any OmniRoute model from the list


>**Suggerimento:**aggiungi qualsiasi modello disponibile nel tuo endpoint OmniRoute `/v1/models` alla sezione `models`. Utilizza il formato "provider/id-modello" dal dashboard OmniRoute.</details>

---

## Risoluzione dei Problemi

<dettagli>
<summary><b>Fai clic per espandere la guida alla risoluzione dei problemi</b></summary>

**"Il modello linguistico non ha fornito messaggi"**

- Provider quota exhausted → Check dashboard quota tracker
- Soluzione: utilizzare il fallback combinato o passare al livello più economico

**Limitazione della velocità**

- Quota di abbonamento esaurita → Fallback su GLM/MiniMax
- Aggiungi combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`

**Token OAuth scaduto**

- Aggiornato automaticamente da OmniRoute
- Se i problemi persistono: Dashboard → Provider → Riconnetti

**Costi elevati**

- Controlla le statistiche di utilizzo in Dashboard → Costi
- Passa dal modello principale a GLM/MiniMax
- Utilizza il livello gratuito (Gemini CLI, Qoder) per attività non critiche

**Le porte dashboard/API sono sbagliate**

- "PORT" è la porta base canonica (e la porta API per impostazione predefinita)
- "API_PORT" sovrascrive solo il listener API compatibile con OpenAI
- `DASHBOARD_PORT` sovrascrive solo la dashboard/il listener Next.js
- Imposta "NEXT_PUBLIC_BASE_URL" sul tuo dashboard/URL pubblico (per callback OAuth)

**Errori di sincronizzazione cloud**

- Verifica che `BASE_URL` punti alla tua istanza in esecuzione
- Verifica che "CLOUD_URL" punti all'endpoint cloud previsto
- Mantieni i valori `NEXT_PUBLIC_*` allineati con i valori lato server

**Primo accesso non funzionante**

- Controlla "INITIAL_PASSWORD" in ".env".
- Se non impostata, la password di fallback è "123456".

**Nessun registro delle richieste**

- Gli elementi della richiesta vengono scritti in "DATA_DIR/call_logs/" come un file JSON per richiesta
- Abilita l'acquisizione della pipeline da Dashboard → Log → Richiedi log se hai bisogno di payload dettagliati per fase
- Imposta `APP_LOG_TO_FILE=true` se desideri anche i log della console dell'applicazione in `logs/application/app.log`
- Modifica `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES` e `CALL_LOG_MAX_ENTRIES` secondo necessità

**Il test di connessione mostra "Non valido" per i provider compatibili con OpenAI**

- Molti provider non espongono un endpoint `/models`
- OmniRoute v1.0.6+ include la convalida di fallback tramite completamenti di chat
- Assicurati che l'URL di base includa il suffisso "/v1".### 🔐 OAuth on a Remote Server

<a name="oauth-on-a-remote-server"></a>
<a name="oauth-em-servidor-remoto"></a>

>**⚠️ Importante per gli utenti che utilizzano OmniRoute su un VPS, Docker o qualsiasi server remoto**#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?

I provider**Antigravity**e**Gemini CLI**utilizzano**Google OAuth 2.0**. Google richiede che "redirect_uri" nel flusso OAuth corrisponda esattamente a uno degli URI preregistrati nella Google Cloud Console dell'app.

Le credenziali OAuth incluse in OmniRoute sono registrate**solo per `localhost`**. Quando accedi a OmniRoute su un server remoto (ad esempio `https://omniroute.myserver.com`), Google rifiuta l'autenticazione con:```
Error 400: redirect_uri_mismatch

Solution: Configure your own OAuth credentials

Devi creare unID client OAuth 2.0in Google Cloud Console con l'URI del tuo server.#### Step-by-step

1. Apri Google Cloud Console

Vai a: https://console.cloud.google.com/apis/credentials

2. Crea un nuovo ID client OAuth 2.0

Fai clic su**"+ Crea credenziali"→"ID client OAuth"**
Tipo di applicazione:"Applicazione Web"
Nome: qualsiasi cosa tu voglia (ad esempio "OmniRoute Remote")

3. Aggiungi URI di reindirizzamento autorizzati

Nel campo**"URI di reindirizzamento autorizzati"**, aggiungi:``` https://your-server.com/callback


> Sostituisci `your-server.com` con il dominio o l'IP del tuo server (includi la porta se necessario, ad esempio `http://45.33.32.156:20128/callback`).

**4. Salva e copia le credenziali**

Dopo la creazione, Google mostrerà l'**ID cliente**e il**Segreto cliente**.

**5. Imposta variabili di ambiente**

Nel tuo `.env` (o variabili di ambiente Docker):```bash
# For Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

# For Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

6. Riavvia OmniRoute```bash

npm:

npm run dev

Docker:

docker restart omniroute


**7. Prova a connetterti di nuovo**

Dashboard → Provider → Antigravity (o Gemini CLI) → OAuth

Google ora reindirizzerà correttamente a "https://your-server.com/callback".---

#### Temporary workaround (without custom credentials)

Se non desideri impostare le tue credenziali adesso, puoi comunque utilizzare il**flusso URL manuale**:

1. OmniRoute apre l'URL di autorizzazione di Google
2. Dopo l'autorizzazione, Google tenta di reindirizzare a "localhost" (che fallisce sul server remoto)
3.**Copia l'URL completo**dalla barra degli indirizzi del browser (anche se la pagina non viene caricata)
4. Incolla l'URL nel campo mostrato nella modalità di connessione OmniRoute
5. Fai clic su**"Connetti"**

> Funziona perché il codice di autorizzazione nell'URL è valido indipendentemente dal fatto che la pagina di reindirizzamento sia stata caricata.---

<dettagli>
<summary><b>🇧🇷 Versione in portoghese</b></summary>#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?

I fornitori**Antigravity**e**Gemini CLI**utilizzano**Google OAuth 2.0**per l'autenticazione. Google richiede che `redirect_uri` utilizzato nel flusso OAuth sia**esattamente**uno degli URI predefiniti nell'applicazione Google Cloud Console.

Le credenziali OAuth supportate su OmniRoute sono cadastrada**solo per `localhost`**. Quando accedi a OmniRoute su un server remoto (es: `https://omniroute.meuservidor.com`), Google rifiuta l'autenticazione come:```
Error 400: redirect_uri_mismatch

Solução: Configure suas próprias credenciais OAuth

È necessario creare unOAuth 2.0 Client IDsu Google Cloud Console come URI del proprio server.#### Passo a passo

1. Accesso a Google Cloud Console

Abra: https://console.cloud.google.com/apis/credentials

2. Crea un nuovo ID client OAuth 2.0

Fare clic su**"+ Crea credenziali"→"ID client OAuth"**
Tipo di applicazione:"Applicazione Web"
Nome: escolha qualquer nome (es: OmniRoute Remote)

3. Aggiunta come URI di reindirizzamento autorizzati

Nessun campo**"URI di reindirizzamento autorizzati"**, aggiunta:``` https://seu-servidor.com/callback


> Sostituisci `seu-servidor.com` con il tuo dominio o IP con il tuo server (inclusa la porta se necessaria, ad esempio: `http://45.33.32.156:20128/callback`).

**4. Salva e copia come credenziale**

Dopo aver creato, Google mostrerà il**Client ID**e il**Client Secret**.

**5. Configura come variáveis de ambiente**

No seu `.env` (o nelle varie impostazioni dell'ambiente Docker):```bash
# 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. Riavvio di OmniRoute```bash

Se usando npm:

npm run dev

Se usando Docker:

docker restart omniroute


**7. Tenete collegato novamente**

Dashboard → Provider → Antigravity (o Gemini CLI) → OAuth

Ora Google verrà reindirizzato correttamente a `https://seu-servidor.com/callback` e l'autenticazione funzionerà.---

#### Workaround temporário (sem configurar credenciais próprias)

Se non vuoi creare credenziali proprie adesso, puoi anche usare il flusso**manuale dell'URL**:

1. OmniRoute aprirà l'URL di autorizzazione di Google
2. Dopo aver autorizzato Google tenterà di reindirizzare a "localhost" (che non funziona sul server remoto)
3.**Copiare l'URL completo**dalla barra degli indirizzi del browser (anche se la pagina non viene caricata)
4. Inserire questo URL nel campo visualizzato nella modalità di connessione di OmniRoute
5. Fare clic su**"Connetti"**

> Questa soluzione alternativa funziona perché il codice di autorizzazione sull'URL è valido indipendentemente dal reindirizzamento caricato o meno.</details>

---

</details>

## 🛠️ Tech Stack

<dettagli>
<summary><b>Fai clic per espandere i dettagli dello stack tecnologico</b></summary>

-**Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ è**non supportato**— i file binari nativi `better-sqlite3` sono incompatibili)
-**Lingua**: TypeScript 5.9 —**100% TypeScript**su `src/` e `open-sse/` (zero `any` nei moduli principali dalla v2.0)
-**Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-**Database**: LowDB (JSON) + SQLite (stato del dominio + log proxy + audit MCP + decisioni di routing)
-**Schemi**: Zod (convalida I/O dello strumento MCP, contratti API)
-**Protocolli**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
-**Streaming**: eventi inviati dal server (SSE)
-**Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
-**Test**: test runner Node.js + Vitest (oltre 900 test inclusi unità, integrazione, E2E)
-**CI/CD**: Azioni GitHub (pubblicazione npm automatica + Docker Hub al rilascio)
-**Sito web**: [omniroute.online](https://omniroute.online)
-**Pacchetto**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-**Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-**Resilienza**: interruttore automatico, backoff esponenziale, mandria anti-tuono, spoofing TLS, autoriparazione automatica combo</details>

---

## Documentazione

| Documento | Descrizione |
| ----------------------------------------------------- | --------------------------------------------------- |
| [Guida per l'utente](docs/USER_GUIDE.md) | Provider, combinazioni, integrazione CLI, distribuzione |
| [Riferimento API](docs/API_REFERENCE.md) | Tutti gli endpoint con esempi |
| [Server MCP](open-sse/mcp-server/README.md) | 16 strumenti MCP, configurazioni IDE, client Python/TS/Go |
| [Server A2A](src/lib/a2a/README.md) | Protocollo JSON-RPC 2.0, competenze, streaming, gestione delle attività |
| [Motore Auto-Combo](docs/auto-combo.md) | Punteggio a 6 fattori, pacchetti modalità, autoriparazione |
| [Risoluzione dei problemi](docs/TROUBLESHOOTING.md) | Problemi comuni e soluzioni |
| [Architettura](docs/ARCHITECTURE.md) | Architettura del sistema e componenti interni |
| [Contribuire](CONTRIBUTING.md) | Impostazione e linee guida per lo sviluppo |
| [Specifiche OpenAPI](docs/openapi.yaml) | Specifica OpenAPI 3.0 |
| [Politica di sicurezza](SECURITY.md) | Segnalazione delle vulnerabilità e pratiche di sicurezza |
| [Distribuzione VM](docs/VM_DEPLOYMENT_GUIDE.md) | Guida completa: configurazione VM + nginx + Cloudflare |
| [Galleria delle funzionalità](docs/FEATURES.md) | Tour visivo della dashboard con screenshot |
| [Elenco di controllo del rilascio](docs/RELEASE_CHECKLIST.md) | Passaggi di convalida prima del rilascio |---

## 🗺️ Roadmap

OmniRoute ha**oltre 210 funzionalità pianificate**in più fasi di sviluppo. Ecco le aree chiave:

| Categoria | Planned Features | In evidenza |
| ----------------------- | ---------------- | -------------------------------------------------------------------------------------- |
| 🧠**Routing e intelligenza**| 25+ | Routing a latenza più bassa, routing basato su tag, verifica preliminare delle quote, selezione dell'account P2C |
| 🔒**Sicurezza e conformità**| 20+ | Rafforzamento SSRF, cloaking delle credenziali, limite di velocità per endpoint, ambito delle chiavi di gestione |
| 📊**Osservabilità**| 15+ | Integrazione OpenTelemetry, monitoraggio delle quote in tempo reale, monitoraggio dei costi per modello |
| 🔄**Integrazioni del provider**| 20+ | Registro dei modelli dinamici, tempi di recupero dei provider, Codex multi-account, analisi delle quote Copilot |
| ⚡**Prestazioni**| 15+ | Doppio livello di cache, cache dei prompt, cache delle risposte, streaming keepalive, API batch |
| 🌐**Ecosistema**| 10+ | API WebSocket, ricarica a caldo della configurazione, archivio di configurazione distribuito, modalità commerciale |### 🔜 Coming Soon

- 🔗**Integrazione OpenCode**: supporto nativo del provider per l'IDE di codifica AI OpenCode
- 🔗**Integrazione TRAE**: supporto completo per il framework di sviluppo AI TRAE
- 📦**API Batch**: elaborazione batch asincrona per richieste collettive
- 🎯**Routing basato su tag**: instrada le richieste in base a tag e metadati personalizzati
- 💰**Strategia a costo più basso**: seleziona automaticamente il fornitore più economico disponibile

> 📝 Specifiche complete delle funzionalità disponibili in [`docs/new-features/`](docs/new-features/) (217 specifiche dettagliate)---

## 👥 Contributors

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)

### How to Contribute

1. Effettuare il fork del repository
2. Crea il ramo della tua funzionalità ("git checkout -b feature/amazing-feature")
3. Applica le tue modifiche (`git commit -m 'Aggiungi funzionalità straordinarie'`)
4. Spingi sul ramo ("git push origin feature/amazing-feature")
5. Aprire una richiesta di pull

Consulta [CONTRIBUTING.md](CONTRIBUTING.md) per linee guida dettagliate.### Releasing a New Version

```bash
# Create a release — npm publish happens automatically
gh release create v2.0.0 --title "v2.0.0" --generate-notes

📊 Star History

Stargazers over time

🙏 Acknowledgments

Un ringraziamento speciale a**9routerdidecolua**— il progetto originale che ha ispirato questo fork. OmniRoute si basa su queste incredibili fondamenta con funzionalità aggiuntive, API multimodali e una riscrittura completa di TypeScript.

Un ringraziamento speciale a**CLIProxyAPI**: l'implementazione originale di Go che ha ispirato questo port di JavaScript.---

Licenza

Licenza MIT: per i dettagli vedere LICENZA.---

_{Built with ❤️ for developers who code 24/7}
_{omniroute.online}

README.md Unescape Escape

🚀 OmniRoute — The Free AI Gateway (Italiano)

Never stop coding. Smart routing to FREE & low-cost AI models with automatic fallback.

🖼️ Main Dashboard

📸 Dashboard Preview

🤖 Free AI Provider for your favorite coding agents

🤔 Why OmniRoute?

📧 Support

API: http://localhost:20128/v1

Dashboard: http://localhost:20129

5) Validate everything end-to-end (recommended)

Alternative: run from source

Template file for 'omniroute'

Copy and edit .env first

System Tray

💰 Pricing at a Glance

🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever

Smart fallback with practical cost control

📖 Setup Guide

Protocol Setup (MCP + A2A)

Codex Account Limit Management (5h + Weekly)

Qwen (4 FREE models via Device Code)

Kiro (Claude FREE)

Example 2: Free-Only (Zero Cost)

Claude Code

OpenClaw

OpenCode

Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key

Select any OmniRoute model from the list

Solution: Configure your own OAuth credentials

npm:

Docker:

Solução: Configure suas próprias credenciais OAuth

Se usando npm:

Se usando Docker:

📊 Star History

Stargazers over time

🙏 Acknowledgments

Licenza

README.md