## 💰 ~1,62 mld di token/mese tramite i livelli gratuiti di terze parti
> **Usa i tuoi account dei provider.** Questa è una stima aggregata dei livelli gratuiti di terze parti per i quali si è idonei separatamente, non un'assegnazione di token da parte di OmniRoute. Registrati, ottieni le credenziali ove richiesto e collega i provider che puoi utilizzare; ciascun provider controlla i propri limiti, la disponibilità e i termini.
>
> Combinare manualmente i livelli gratuiti è complicato: decine di SDK, decine di limiti di frequenza e nessuna idea di quanto sia effettivamente disponibile. OmniRoute cataloga **489 voci di livelli gratuiti distribuite tra 35 chiavi di pool ricorrenti** e calcola il totale di token sulla base dei **17 pool con un budget mensile positivo pubblicato, più cinque limiti Groq per modello**, eliminando i duplicati dovuti ai pool condivisi. Le quote che diventano disponibili solo dopo una verifica regionale dell'identità (attualmente: ModelScope) sono mostrate separatamente, +~6M soggetti a verifica regionale dell'identità, e non vengono mai incluse nel totale principale. Il risultato rimane visibile nella dashboard (`/dashboard/free-tiers`).
> Riepilogo animato della pagina live `/dashboard/free-tiers`. Metodologia completa (deduplicazione dei pool, livelli di credito, termini dei provider): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Queste cifre vengono sottoposte a una nuova verifica ogni due settimane rispetto al catalogo live e **possono variare in entrambe le direzioni**: se un provider termina un livello gratuito, il numero diminuisce; se ne arriva uno nuovo, aumenta. Pubblichiamo ciò che il catalogo calcola effettivamente, mai un caso migliore arrotondato per eccesso.
⭐ Aggiungi una stella al repository se OMNIROUTE ti ha aiutato a risparmiare denaro e a semplificare il tuo lavoro.
[](https://github.com/diegosouzapw/OmniRoute)
[](https://www.star-history.com/diegosouzapw/omniroute)
[](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 Unisciti alla community
**👋 Segui il manutentore per scoprire per primo nuovi provider, versioni e suggerimenti:**
[](https://www.linkedin.com/in/diegosouzapw/)
[](https://github.com/diegosouzapw)
[](https://discord.gg/U47eFqAXCn)
[](https://t.me/omnirouteOficial)
[](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4)
[](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4)
[](https://omniroute.online)
**Domande, suggerimenti sui provider, roadmap e supporto → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Globale](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4) / [🇧🇷 Brasile](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4) / [Portale](https://portal.sthub.com.br/communities/groups/st-hub/channels/Omniroute-World-8kRjmK)**
## 📈 Il Gateway continua a crescere
| | v3.8.50 | **v3.8.51** | `v3.8.52+` |
| ------------------------------------ | :------------------------: | :---------: | :-------------------: |
| 🌐 Provider | 352 | **358** | 372 |
| 🧠 ID univoci dei modelli di chat | 1320 | **1374** | 1443 |
| 🖼️ Ponte tra modalità | 🆕 visione + audio + video | ✓ | ✓ |
| 📡 Catalogo gratuito Radar | 🆕 su adesione | ✓ | ✓ |
| ⚖️ Pianificazione basata sulle quote | 🆕 Quota-Share | ✓ | ✓ |
| 📊 Telemetria delle quote | 🆕 in tempo reale | ✓ | ✓ |
| 🧰 Modalità headless | — | — | 🆕 `serve --headless` |
| 🛤️ Infrastruttura del ramo LTS | — | — | 🆕 canali di rilascio |
**→ [Roadmap](ROADMAP.md) — lungo il percorso verso `v3.9.0 LTS`**
## 🧩 Disponibile
[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](LICENSE)
## 🆓 Installa, connetti un provider, quindi instrada tutto attraverso un unico endpoint
```bash
# Dopo aver connesso un provider, copia la tua chiave OmniRoute da Dashboard → Endpoints:
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_OMNIROUTE_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
`auto` richiede un percorso idoneo. Una nuova installazione potrebbe non avere destinazioni idonee senza chiave e un provider senza chiave potrebbe rifiutare client di terze parti. I provider contrassegnati con `tos: avoid`, inclusi OpenCode Free e Kiro, sono esclusi per impostazione predefinita dall'instradamento automatico; connettere un account non modifica questa impostazione. Consulta la [Guida ai piani gratuiti](docs/getting-started/FREE-TIERS-GUIDE.md) prima di scegliere un provider.📦 Script di avvio rapido da copiare e incollare per **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
# 💥 La promessa
# 🤔 Perché OmniRoute?
## 🤝 Supportato dai nostri Amici Open Source
> **Vuoi unirti come Amico Open Source?** Queste sono le aziende che supportano l'open source e aiutano a mantenere OmniRoute in movimento — e noi dichiariamo pubblicamente dove va ogni token che ci danno. Contattaci: [diegosouza.pw@outlook.com](mailto:diegosouza.pw@outlook.com)
Kimi Moonshot AI
Grazie a Kimi (Moonshot AI), il nostro Amico Fondatore Open Source, per aver supportato questo progetto! Kimi è il laboratorio di IA dietro le famiglie di modelli open-weight K2 e K3 — Kimi K3 offre una finestra di contesto da 1M di token, visione nativa e codifica a livello di frontiera a una frazione dei prezzi dei modelli chiusi, e funziona immediatamente con Claude Code, Codex e ogni strumento di codifica che OmniRoute serve.
Cosa alimenta il supporto di Kimi: I crediti API di Kimi alimentano la pipeline di rilascio convalidata dall'IA di OmniRoute — la fase di validazione della fusione alimentata da Kimi K3 che esamina ogni pull request prima che venga spedita — oltre allo sviluppo quotidiano delle funzionalità. Il supporto di prima classe per Kimi viene fornito su entrambi i binari: l'API Kimi diretta (kimi-k3) e il piano di codifica Kimi Code (OAuth e chiave API). OmniRoute è anche il primo progetto open-source brasiliano nel programma di supporto di Kimi. Ottieni una chiave API Kimi con il 15% di crediti extra →
Cheaper Inference cheaperinference.com
Grazie a Cheaper Inference, un Amico Open Source di OmniRoute, per aver supportato questo progetto! Cheaper Inference è un gateway classificato per costo che rivende 42 modelli all'avanguardia — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok e MiniMax — dietro un unico endpoint compatibile con OpenAI, instradando ogni richiesta al provider idoneo più economico senza mai addebitare un prezzo superiore a quello di listino del creatore del modello.
Supporto di prima classe in OmniRoute: Chat Completions, l'endpoint nativo /v1/responses, visione, tool calling e 3 modelli di immagine (grok-imagine, nano-banana-pro, nano-banana-2, raggiungibili come cheaperinference/<model>). Ottieni una chiave API →
I link taggati aff=omniroute sono link partner. Finanziano il progetto senza costi aggiuntivi per te. 🎟️ Promo Affiliati — coupon di iscrizione gratuiti da provider che non sponsorizziamo (clicca per espandere)Questa sezione è solo per codici di riferimento/coupon. Le partnership sponsorizzate si trovano in 🤝 Supportato dai nostri Amici Open Source sopra. OmniRoute non ha sponsorizzazioni o partnership con i provider elencati qui — questi sono coupon pubblici che chiunque può usare.
AgentRouter agentrouter.org
AgentRouter — iscrizione affiliato · $100 di crediti gratuiti all'iscrizione (server gratuito, aspettati una latenza maggiore — ottimo per test, non per la produzione). Supporto di prima classe in OmniRoute dalla v3.8.50: Chat Completions, il formato wire compatibile con Anthropic e il percorso compatibile con OpenAI. I modelli disponibili includono claude-opus-4-8, claude-opus-5, gpt-5.6-sol e altro. Prendi i tuoi $100 →
⚠️ Link affiliato — OmniRoute non ha sponsorizzazioni o partnership con questo provider.
Conosci un altro provider con un generoso coupon di iscrizione gratuito che beneficia gli utenti di OmniRoute? Apri un'issue e lo aggiungeremo qui.
## 🎯 Combo — La funzionalità di punta
> Un **combo** è una catena di modelli tra i quali OmniRoute instrada le richieste **automaticamente**. Se la quota si esaurisce, un provider non funziona o i costi aumentano improvvisamente, il combo può passare al successivo modello idoneo e operativo. 🛡️
### ⚡ Zero configurazione — usa semplicemente `auto`
Non è necessario creare alcun combo. Imposta il modello su `auto` (o su una sua variante) e OmniRoute crea un combo virtuale utilizzando i provider connessi, valutati in tempo reale:
🧑💻 Pesi che privilegiano la qualità per la generazione di codice
auto/fast
⚡ Prima la latenza più bassa
auto/cheap
💰 Prima il costo per token più basso
auto/offline
🔋 Prima il maggiore margine di quota / limite di frequenza
auto/smart
🔭 Prima la qualità + 10% di esplorazione per individuare modelli migliori
auto/lkgp
📌 Persistenza esplicita sull'ultimo provider valido noto
auto/chaos
🧪 Distribuzione parallela a un gruppo di modelli (uno per provider, 5 per impostazione predefinita), restituisce una sola risposta; una chiamata upstream per ciascun modello del gruppo, non è un'iniezione di errori
##
### 🔀 Oppure creane uno personalizzato — 19 strategie di instradamento
Tutte le **19** strategie — combinale liberamente per ogni passaggio del combo:
#
Strategia
Cosa fa
1
priority
Elenco ordinato con priorità alla prima destinazione — esaurisce ciascuna prima di passare alla successiva 🥇
2
fill-first
Utilizza completamente la quota di ciascuna destinazione prima di passare alla successiva
3
weighted
Selezione casuale ponderata in base al peso di ciascuna destinazione
4
round-robin
Alterna ciclicamente le destinazioni in ordine
5
p2c
Bilanciamento casuale del carico con il metodo delle due scelte
6
least-used
Seleziona la destinazione con il carico corrente più basso
7
random
Selezione casuale uniforme (senza duplicati)
8
strict-random
Selezione casuale senza eliminare le ripetizioni 🎲
9
cost-optimized
Riduce al minimo il costo in $ per richiesta in base ai prezzi aggiornati del catalogo 💸
10
headroom
Seleziona la destinazione con la maggiore quota residua
11
reset-window
Preferisce la destinazione la cui finestra di quota si azzera prima
12
reset-aware
Ordina in base al tempo di azzeramento della quota — prima le finestre brevi 📊
13
context-relay
Trasferisce il contesto tra le destinazioni per le conversazioni lunghe 🧠
14
context-optimized
Seleziona la soluzione più adatta alle dimensioni del contesto corrente
15
cache-optimized
Associa ogni prefisso di prompt riutilizzabile allo stesso account — massimizza i riscontri nella cache dei prompt 🎯
16
lkgp
Last-Known-Good Path — mantiene l'ultimo provider utilizzato con successo, quindi ricorre alle regole in caso di problemi
17
auto
Valutazione in tempo reale basata su 16 fattori per ogni connessione 🤖
18
fusion
Distribuisce la richiesta a un gruppo di modelli + un giudice sintetizza una sola risposta 🧬
19
pipeline
Concatena i passaggi — l'output di ogni destinazione alimenta quella successiva 🔗
Il motore Auto-Combo valuta ogni candidato in base a **16 fattori** (stato operativo, quota, costo, latenza, idoneità all'attività, qualità, disponibilità della sessione…) — consulta [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).
##
### 🧱 La resilienza è integrata (3 livelli indipendenti)
📖 [Motore Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guida alla resilienza](docs/architecture/RESILIENCE_GUIDE.md)
## 🏆 Cosa distingue OmniRoute
📊 Metodologia completa e dettagli per ciascuna funzionalità rispetto a 9router, OpenRouter, CLIProxyAPI e LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
## 💚 Sostieni OmniRoute
OmniRoute è distribuito con licenza MIT e mantenuto apertamente. Se ti fa risparmiare tempo o denaro, ecco come contribuire a mantenerlo indipendente: scegli l'opzione che preferisci. Le sponsorizzazioni non influiscono mai sulla priorità di routing; offrono visibilità, non un posizionamento migliore.
**🇧🇷 PIX** — istantaneo, senza commissioni (Brasile)
Chiave (casuale): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix copia e incolla:
```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```
₿ Criptovalute — BTC · ETH · USDT-TRC20 · USDC-Solana (fai clic per espandere)
₿ BTC
Bitcoin (SegWit)
bc1qh00smz004sy85wyl28v77tenkt3ckl6eaep7fd
Ξ ETH
Ethereum (ERC20)
0x64Cf6B68A6Ff34288e89172950a2d00102337a84
₮ USDT
Tron (TRC20)
TKAF41JpuQrHbKTnsQa9svJE2T192Hvsc2
$ USDC
Solana
2emNNZzVVWQc3FQ2wk9M6qXUQmW8AKdjjL174fXR28Tu
⚠️ Invia ogni valuta esclusivamente sulla rete indicata: l'invio sulla rete sbagliata può comportare la perdita dei fondi.
🐛 Hai trovato un bug o vuoi lasciare un feedback? Apri una [Discussione](https://github.com/diegosouzapw/OmniRoute/discussions).
Note per gli sviluppatori: Il progetto può generare un file locale .env durante npm install/postinstall per agevolare gli sviluppatori. Questo file viene intenzionalmente ignorato tramite .gitignore (consulta .gitignore) e non deve mai essere incluso in un commit; se viene incluso accidentalmente, sostituisci tutti i segreti esposti e rimuovi il file dalla cronologia. Consulta docs/DEVELOPER-ENVIRONMENT.md per indicazioni sulla gestione dei file di ambiente locali e dei segreti.
## 📡 OmniRoute Radar
Il dato principale del piano gratuito rimane **~1,62 miliardi di token/mese**, in base al catalogo documentato
e deduplicato per pool riportato sopra. I crediti temporanei di registrazione dei provider possono incrementare separatamente il primo
mese fino a **~2,22 miliardi**. Radar è un overlay opzionale e firmato del catalogo, destinato a chi desidera
informazioni più aggiornate sulla disponibilità dei modelli gratuiti tra una release di OmniRoute e l'altra; il catalogo della community e tutte le funzionalità gratuite
esistenti rimangono gratuiti.
I sostenitori possono ricevere il catalogo in tempo reale e ulteriori opportunità offerte dai provider. Il relativo limite massimo, separato
e variabile, è **di circa 3 miliardi di token/mese al massimo**, a seconda della disponibilità dei provider.
Tale limite non è garantito: i provider possono modificare quote, requisiti di idoneità, modelli o regioni in
qualsiasi momento.
Radar è facoltativo ed effettua esclusivamente richieste GET. Il client OmniRoute non carica prompt, traffico, configurazioni dei provider,
telemetria sull'utilizzo o lo stato locale relativo alla chiusura degli annunci. Scopri i requisiti di idoneità e
il catalogo attuale su **[radar.omniroute.online/planos](https://radar.omniroute.online/planos)**.
## ✨ Novità
> Principali novità recenti dalla **v3.8.20 alla v3.8.50**. Cronologia completa in [`CHANGELOG.md`](CHANGELOG.md).
- **🎛️ OmniConductor** — delega A2A in ingresso alla tua flotta di agenti, competenze di Conductor nell'Agent Card e un pannello della dashboard con chat vocale push-to-talk di Faro. → [Server A2A](docs/frameworks/A2A-SERVER.md)
- **🛂 Ammissione adattiva e protezione dal sovraccarico** — le richieste di chat più pesanti vengono accodate anziché restituire un errore 503, con lease mobili RPM atomici per connessione. → [Guida alla resilienza](docs/architecture/RESILIENCE_GUIDE.md)
- **🗂️ Ordinamento canonico di `/v1/models`** — un unico blocco contiguo raggruppato per provider per ciascun provider (con le combinazioni fissate all'inizio), stabile in tutte le origini del catalogo. → [Riferimento API](docs/reference/API_REFERENCE.md)
- **🗜️ Rafforzamento della compressione** — protezione dall'inflazione attiva per impostazione predefinita, pacchetti Caveman per DE / FR / JA + cinese (wényán), filtri RTK per Gradle e .NET. → [Compressione](docs/compression/COMPRESSION_ENGINES.md)
- **💸 Costo forfettario veritiero** — i provider con abbonamento / piano di programmazione riportano **$0** nelle analisi dei costi; budget, quota e routing continuano a effettuare stime. → [Riferimento API](docs/reference/API_REFERENCE.md)
- **⚖️ Routing Quota-Share** — suddivide equamente la quota di un account condiviso tra le chiavi raggruppate, preservando l'utilizzo delle risorse tramite la cessione delle porzioni inutilizzate. → [Guida alla resilienza](docs/architecture/RESILIENCE_GUIDE.md)
- **🤖 Configurazione di CLI/agenti con un solo comando** — 13 comandi `setup-*` registrati; `omniroute run` avvia 7 CLI (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` supporta 10 destinazioni con un selettore interattivo di provider e modello e preferiti specifici per contesto. → [Integrazioni CLI](docs/guides/CLI-INTEGRATIONS.md)
- **🛰️ Modalità remota** — controlla un'istanza OmniRoute remota tramite token con ambito limitato (`connect` / `contexts` / `tokens`) e un assistente OAuth `antigravity` per le installazioni VPS. → [Modalità remota](docs/guides/REMOTE-MODE.md)
- **🧭 Routing automatico più intelligente** — combinazioni `auto/:`, **Fusion** (pannello di modelli + giudice), routing sensibile all'attività, sostituzioni per richiesta di modello / modalità / budget in USD. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Compressione modulare** — 12 motori componibili + Compression Studios: LLMLingua-2, Ultra a due livelli, omniglyph, controllo di fedeltà per ogni passaggio, GCF v3.2, editor con riordinamento tramite trascinamento. → [Compressione](docs/compression/COMPRESSION_ENGINES.md)
- **🕵️ Decrittazione MITM trasparente (TPROXY)** — intercetta le CLI che ignorano le variabili d'ambiente del proxy, con una CA per SNI e un programma di installazione per l'archivio attendibilità. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
- **💸 Telemetria dei costi ovunque** — header di costo/utilizzo `X-OmniRoute-*` su ogni endpoint, header dei risparmi da cache HIT, quote di spesa in USD per chiave. → [Riferimento API](docs/reference/API_REFERENCE.md)
- **🧠 Memoria sotto il tuo controllo** — disattivata per impostazione predefinita, quantizzazione vettoriale int8 opzionale + decadimento tipizzato, `x-omniroute-no-memory` per richiesta. → [Memoria](docs/frameworks/MEMORY.md)
- **🛡️ Sicurezza** — protezione dalla prompt injection su ogni route LLM (suite di red teaming), protezione opzionale per il mascheramento delle credenziali (oscura chiavi API/segreti trapelati in entrambe le direzioni), ricerca web gratuita tramite DuckDuckGo come ultima risorsa e un gate di accesso OIDC opzionale per la dashboard (l'accesso tramite password rimane sempre disponibile). → [Misure di protezione](docs/security/GUARDRAILS.md)
- **🖼️ Nuovi endpoint** — `/v1/ocr` (Mistral OCR) e `/v1/audio/translations` (in stile Whisper) completano le funzionalità multimediali. → [Riferimento API](docs/reference/API_REFERENCE.md)
- **🎨 Generazione di immagini / video / audio** — un'unica API per i contenuti multimediali: video xAI Grok Imagine e Novita AI, ComfyUI, Magnific, Adobe Firefly, Segmind e provider vocali come ElevenLabs. → [Riferimento API](docs/reference/API_REFERENCE.md)
- **🌍 Distribuzione e operazioni** — `basePath` per reverse proxy, rilevamento automatico della lingua del browser, monitoraggio dei dispositivi per chiave, attendibilità MITM senza privilegi root, localizzazione zh-TW. → [Ambiente](docs/reference/ENVIRONMENT.md)
- **🤝 Altri provider e agenti** — agenti cloud (Codex Cloud, Cursor, Devin, Jules), Grok Build (xAI) con browser + accesso OAuth, scheda dedicata per Ollama, Claude Opus 5 e Sonnet 5, partnership ufficiale con Kimi (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… e un **catalogo aggiornato di 352 provider**. → [Provider](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Trasparenza del routing** — ogni risposta include un header `X-OmniRoute-Decision` che indica la strategia, il provider e la latenza utilizzati; una nuova strategia di combinazione `cache-optimized` + il fattore `cacheAffinity` di Auto-Combo reindirizzano le richieste ripetute alla connessione che conserva il prefisso nella cache; inoltre, un endpoint di sola lettura `/v1/auto-combo/{channel}/candidates` espone il pool attivo di candidati di un canale `auto/*`. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **⚡ Prestazioni locali e infrastruttura** — Redis locale con un clic, strumenti di distribuzione relay per Cloudflare Workers / Deno Deploy, Bifrost e Mux come servizi incorporati supervisionati. → [Servizi incorporati](docs/frameworks/EMBEDDED-SERVICES.md)
- **🧩 Incluso inoltre** — framework per plugin + marketplace, framework per competenze Omni/Agent/GitHub, integrazione con vault Obsidian (22 strumenti MCP), API Batch e Files compatibili con OpenAI, cache semantica delle risposte, gamification con classifiche, rilevamento degli agenti ACP (15 agenti integrati), esportazione pianificata dei log in BigQuery, fan-out parallelo multi-modello `auto/chaos`, bridge per bot Telegram, gestore delle versioni integrato nell'applicazione e classifiche dei provider gratuiti LMArena-ELO. → [Documentazione](docs/README.md)
## 🤖 CLI e agenti di coding compatibili
> Un'unica configurazione — `http://localhost:20128/v1` — e **qualsiasi** IDE o CLI basato sull'IA funziona con modelli gratuiti e a basso costo.
＋ funziona anche con · Agent Deck · Kiro · Command Code · Antigravity · Windsurf · AMP · qualsiasi strumento compatibile con OpenAI
📖 Configurazione specifica per tutti i 36 strumenti (26 CLI di coding + 10 agenti CLI) → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 Plugin OpenCode → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)
**Avvia qualsiasi CLI supportata tramite OmniRoute con un solo comando** — senza scrivere file di configurazione,
con credenziali iniettate per ogni processo e una home isolata temporanea per Qwen/Gemini:
```bash
omniroute run claude --model openai/gpt-5.4 # Claude Code
omniroute run codex --model glm/glm-5.2 # OpenAI Codex CLI
omniroute run aider --model glm/glm-5.2 -- --message "reply OK"
omniroute run goose --model glm/glm-5.2
omniroute run opencode --model glm/glm-5.2 -- run "reply OK"
omniroute run qwen --model glm/glm-5.2 -- -p "reply OK"
omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p "reply OK"
# Oppure scegli interattivamente provider e modello e scrivi la configurazione dello strumento:
omniroute configure codex # disponibili anche: claude opencode qwen aider goose gemini cline continue kilo
```
Ogni comando rispetta il contesto remoto attivo (`omniroute connect `), `--dry-run`
mostra in anteprima le variabili di ambiente e gli argomenti esatti senza eseguire nulla, mentre `--api-key-env NAME` evita
che i segreti finiscano nella cronologia della shell. → [Integrazioni CLI](docs/guides/CLI-INTEGRATIONS.md)
## 🌐 372 provider di IA — 154 contrassegnati nel catalogo come gratuiti
> **372 provider registrati** nelle raccolte canoniche di chat, contenuti multimediali, ricerca, servizi locali, agenti cloud e sistema, inclusi **154 con metadati di rilevamento `hasFree: true`**. Il registro dei modelli di chat comprende **237 provider / 3.009 coppie provider-modello distinte / 1.443 ID modello non elaborati**; il catalogo separato delle disponibilità gratuite contiene **491 voci per modello**, **35 pool ricorrenti** e **54 provider gratuiti per sempre, ricorrenti o senza chiave**. Questi denominatori sono diversi per scelta progettuale; le definizioni e i calcoli con deduplicazione dei pool sono disponibili nella [Guida di riferimento dei provider](docs/reference/PROVIDER_REFERENCE.md) e nei [Piani gratuiti](docs/reference/FREE_TIERS.md).
### 🏢 Tutti i principali laboratori — tramite un unico endpoint
OpenAI
Anthropic
Gemini
xAI Grok
DeepSeek
Mistral
Qwen
Meta Llama
Groq
NVIDIA
MiniMax
Cohere
Perplexity
HuggingFace
Together
Fireworks
Cloudflare
Baidu
…e oltre 330 altri — ogni icona viene caricata in tempo reale dal catalogo dei provider della dashboard. 📖 [Guida di riferimento dei provider](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Gratis per sempre — $0, nessuna carta richiesta
OpenCode Zen DeepSeek V4, Nemotron 3 Nessun limite di token
Kilo Code Auto-router, Tencent Hy3 Gratis per sempre
Requesty GPT-OSS 120B, Nemotron Gratis per sempre
SiliconFlow DeepSeek V3.2 / R1 Piano gratuito
Z.AI GLM GLM-4.7 / 4.5-Flash Gratis per sempre
Baidu ERNIE ERNIE 4.0 Gratis per sempre
Qoder AI Qwen3-Max, Kimi-K2 GRATIS senza limiti
Pollinations GPT, Llama, Claude Nessuna chiave necessaria
Cloudflare AI Oltre 50 modelli 10.000 neuroni/giorno
NVIDIA NIM GLM, MiniMax ~40 RPM gratis
Cerebras GLM 4.7, GPT-OSS Credito una tantum di $5; carta obbligatoria
> Stessa app, la tua macchina, le tue regole. Da un'installazione globale tramite npm fino al **tuo telefono** tramite Termux.
Piattaforma
Installazione
Caratteristiche principali
📦 npm (globale)
npm install -g omniroute
Un solo comando, qualsiasi sistema operativo
🐳 Docker
docker run … diegosouzapw/omniroute
Multi-arch AMD64 + ARM64
🖥️ Desktop (Electron)
npm run electron:build
Finestra nativa + barra delle applicazioni — Windows / macOS / Linux
🎩 Barra dei menu (OmniRouteTray)
brew install --cask zoispag/tap/omniroute-tray
Supervisiona e aggiorna automaticamente il server — macOS
💪 ARM
arm64 nativo
Raspberry Pi, server ARM, Apple Silicon
📱 Android (Termux)
pkg install nodejs && npx -y omniroute
Funziona sul tuo telefono, 24/7, senza root
📲 PWA
"Aggiungi alla schermata Home"
A schermo intero, offline, installabile dal browser
🧩 Plugin OpenCode
@omniroute/opencode-provider
Integrazione nativa con OpenCode
🤖 VS Code Copilot Chat
installa l'estensione OmniCopilot
Ogni modello OmniRoute nel selettore nativo di Copilot Chat — versione stabile e Insiders
🛠️ Dal codice sorgente
npm install && npm run dev
Modificalo, contribuisci
📖 [Guida a Docker](docs/guides/DOCKER_GUIDE.md) · [Desktop](electron/README.md) · [Icona nella barra dei menu](https://github.com/zoispag/omniroute-tray) · [Termux](docs/guides/TERMUX_GUIDE.md) · [PWA](docs/guides/PWA_GUIDE.md) · [OpenCode](docs/frameworks/OPENCODE.md)
### 🧩 Novità: OmniRoute all'interno del Copilot Chat nativo di VS Code
> Nessuna nuova barra laterale, nessuna nuova interfaccia di chat: ogni modello fornito da OmniRoute appare direttamente nel
> **selettore di modelli di Copilot Chat che già utilizzi**. A partire da VS Code 1.122, i modelli dei provider funzionano
> senza accesso a GitHub o abbonamento a Copilot: modalità agente, chiamate agli strumenti e visione,
> gratuitamente.
Installa l'estensione **[OmniCopilot](https://github.com/diegosouzapw/OmniCopilot)**, collegala
al tuo server OmniRoute (il valore predefinito è `localhost:20128`), quindi apri Copilot Chat → selettore di modelli
→ **Gestisci modelli…** → **OmniRoute**.
Dall'editor: apri la vista **Estensioni**, cerca **"OmniRoute"**, fai clic su **Installa**
— funziona allo stesso modo in entrambi gli store. Il codice sorgente, le segnalazioni e la guida alla pubblicazione si trovano in
[diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot).
📖 [Guida a VS Code Copilot Chat](docs/guides/VSCODE-COPILOT.md) — configurazione, cosa mostra il selettore, dashboard in una scheda, risoluzione dei problemi
### 🎩 Novità: OmniRouteTray — il tuo gateway, nella barra dei menu
> `omniroute serve` dà il meglio di sé quando è sempre attivo. **[OmniRouteTray](https://github.com/zoispag/omniroute-tray)**
> lo trasforma in un'app per la barra dei menu di macOS che puoi configurare e dimenticare: avvia il server, lo mantiene attivo
> dopo i riavvii, lo aggiorna direttamente e rende accessibile il tuo budget di token in tempo reale con un clic — **senza
> lasciare aperta una finestra del terminale e senza dover gestire `npm install -g omniroute`.**
Realizzato con [Tauri v2](https://v2.tauri.app/) (un core Rust dalle dimensioni trascurabili), include
il proprio runtime Node 24 firmato e gestisce un'installazione di OmniRoute appartenente all'app, quindi non entra mai in conflitto con le tue
installazioni globali di `node`/`bun`. **Condivide la configurazione e il database esistenti in `~/.omniroute/`** — quindi è lo
stesso OmniRoute che già utilizzi, semplicemente con un cappello. 🎩
Cosa fa
Come
🟢 Supervisiona il server
Avvia omniroute serve e adotta un'istanza già in esecuzione invece di duplicarla
📊 Utilizzo in tempo reale a colpo d'occhio
Barre delle quote dei provider, limiti di sessione/settimanali di Claude con conto alla rovescia per il ripristino, ripartizione dei costi degli ultimi 30 giorni
🔄 Aggiornamento automatico sul posto
Installazione in più fasi, sostituzione atomica, rollback in caso di errore — sempre aggiornato alla versione più recente
🚀 Avvio all'accesso
Avvio facoltativo all'accesso; solo nella barra dei menu, senza icona nel dock
🩺 Diagnostica e log
Diagnostica con un clic e accesso ai log del server
```sh
brew install --cask zoispag/tap/omniroute-tray
```
Preferisci un download? Scarica l'ultimo .dmgReleases. Il codice sorgente, le segnalazioni e la documentazione
di compilazione si trovano su zoispag/omniroute-tray.
💛 Un progetto della community a cura di @zoispag — non è una versione ufficiale di OmniRoute.
## 🔒 Privato e local-first
📖 [Autorizzazione](docs/architecture/AUTHZ_GUIDE.md) · [Misure di sicurezza](docs/security/GUARDRAILS.md) · [Conformità](docs/security/COMPLIANCE.md)
## 🔌 CLI completa + A2A e MCP
> Oltre al server, OmniRoute è una **console completa da riga di comando** con **oltre 80 comandi**, più protocolli aperti per agenti che consentono a un agente AI di controllarlo **autonomamente**.
### ⌨️ Una vera CLI (non solo `start`)
```bash
omniroute # avvia il gateway + la dashboard (porta 20128)
omniroute chat # client di chat TUI interattivo (comandi slash: /model /combo /skill /memory)
omniroute setup # procedura guidata per il primo avvio
omniroute doctor # diagnostica provider, porte e dipendenze native
```
### 🛰️ Modalità remota — esegui la CLI qui e OmniRoute su un VPS
OmniRoute è su un server? Controllalo dal tuo laptop con la **stessa CLI**. Accedi una volta
con un token di accesso con ambito limitato; da quel momento ogni comando sarà indirizzato al server remoto.
```bash
omniroute connect 192.168.0.15 # password → token con ambito limitato, salvato come contesto
omniroute models # ← viene eseguito sul server REMOTO
omniroute configure codex # ← seleziona un modello remoto e scrive un profilo Codex locale
omniroute tokens create --name ci --scope read # genera token con ambito più ristretto per altre macchine
omniroute contexts use default # ← torna al server locale
```
Gli ambiti dei token sono `read` / `write` / `admin`; le route che avviano processi rimangono accessibili solo tramite loopback.
📖 [Modalità remota](docs/guides/REMOTE-MODE.md)
### 🤝 Collega un agente — e controllerà direttamente OmniRoute
Esponi OmniRoute tramite **MCP**, **A2A**, una **REST API**, **webhook** o una **CLI remota**: qualsiasi agente compatibile (o il tuo codice) otterrà il controllo dell'intero gateway, inclusi routing, provider, combo, cache, compressione e memoria, in modo autonomo. Gli endpoint HTTP seguenti sono disponibili all'indirizzo `http://localhost:20128`.
Interfaccia
Endpoint / comando
Utilizzalo per
🧰 MCP (stdio)
omniroute --mcp
Integrarlo con Claude Desktop, Cursor o qualsiasi client MCP
Compatibile con OpenAI — chat, embedding, immagini, audio, OCR
🔔 Webhook
/api/webhooks
Inviare eventi relativi a richieste / quote a Slack, Discord, Telegram o qualsiasi URL
🛰️ CLI remota
omniroute connect
Controllare un'istanza remota con token di accesso con ambito limitato
```bash
# Fornisci a Claude Code il set completo di strumenti OmniRoute tramite MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
```
📖 [Server MCP](docs/frameworks/MCP-SERVER.md) · [Server A2A](docs/frameworks/A2A-SERVER.md) · [Protocolli per agenti](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)
## 🗜️ Risparmia il 15–95% dei token — Automaticamente
### 📖 Come funziona — pipeline, architettura e calcolo del risparmio
La combinazione predefinita esegue `RTK → Caveman`. Quando entrambi agiscono sullo stesso payload di strumenti/contesto, i risparmi si moltiplicano:
```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
```
I blocchi di codice, gli URL, il JSON e i dati strutturati sono **sempre protetti** dal motore di conservazione.
> **Perché usare molti token quando ne bastano pochi?** Ogni richiesta attraversa la pipeline di compressione di OmniRoute **in modo trasparente** — senza modifiche al client. Ora è una **pila di 12 motori componibili** che vengono eseguiti in sequenza e combinati in base alla configurazione di routing — basandosi sulle idee di [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) e [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 La pila di 12 motori
I motori vengono eseguiti nell'ordine della pipeline; ciascuno può essere attivato o disattivato e configurato indipendentemente per ogni combinazione:
#
Motore
Cosa fa
1
Session-Dedup
Elimina i contenuti ripetuti tra i turni (indirizzati per contenuto, tra turni)
2
CCR
Archivia i blocchi di grandi dimensioni dietro marcatori di recupero, richiamandoli su richiesta
3
Lite
Riduzione degli spazi vuoti e degli URL delle immagini (base a bassa latenza)
4
RTK
Filtraggio intelligente, deduplicazione e troncamento dei risultati degli strumenti (in base al comando)
5
Responses Tool Output
JSON lossless come prima scelta + compressione diagnostica limitata per gli output di shell/patch/ricerca/build (Responses API)
6
Headroom
Compattazione tabellare lossless degli array JSON (~30%) tramite un codec GCF integrato
7
Relevance
Valutazione estrattiva delle frasi rispetto all'ultima richiesta dell'utente
8
Caveman
Compressione del testo basata su regole (~65–75% sull'output)
9
Aggressive
Riepilogo + invecchiamento progressivo dei turni precedenti
10
LLMLingua-2
Potatura semantica ML tramite MobileBERT ONNX — sicura per il codice, asincrona
11
Ultra
Potatura euristica dei token con un livello opzionale basato su un modello di piccole dimensioni (SLM)
12
OmniGlyph
Codifica sperimentale del contesto come immagine per Claude Fable 5, misurata sulla connessione diretta ad Anthropic; i transformer GPT 5.6 mantengono un comportamento fail-closed in attesa delle ricevute del provider. Quattro profili di compressione (aggressivo predefinito, bilanciato, sicuro per il codice, passthrough) (il più aggressivo; attivazione esplicita)
I blocchi di codice, gli URL e i dati strutturati sono **sempre conservati** in modo perfettamente identico a livello di byte. Le **configurazioni predefinite con un clic** combinano i motori:
Modalità
Risparmio
Ideale per
🪶 Lite
~15%
Impostazione predefinita sicura sempre attiva
🪨 Standard (Caveman)
~30%
Programmazione quotidiana
⚡ Aggressive
~50%
Sessioni lunghe con uso intensivo di strumenti
🔥 Ultra
~75%
Massimo risparmio
🧰 RTK
60–90%
Output di shell/test/build/git
🔗 Combinata (RTK → Caveman)
78–95%
Prompt misti + log degli strumenti
**Esempio reale — Modalità Standard:**
> **Prima (69 token):** _"Il motivo per cui il tuo componente React viene nuovamente renderizzato è probabilmente che stai creando un nuovo riferimento a un oggetto a ogni ciclo di rendering. Quando passi un oggetto inline come prop, il confronto superficiale di React lo considera ogni volta un oggetto diverso, attivando così un nuovo rendering. Consiglierei di usare useMemo per memorizzare l'oggetto."_
>
> **Dopo (19 token):** _"Nuovo riferimento all'oggetto a ogni rendering. Prop oggetto inline = nuovo riferimento = nuovo rendering. Usa useMemo."_
>
> **Stessa risposta. 72% di token in meno. Nessuna perdita di accuratezza.** ✅
**Esempio PT-BR — Modalità [Troglodita](https://github.com/leninejunior/troglodita):**
> **Prima (42 token):** _"Il problema è che il componente viene renderizzato nuovamente perché a ogni ciclo di rendering viene creato un nuovo riferimento all'oggetto. Consiglierei di usare useMemo."_
>
> **Dopo (12 token):** _"Re-render: nuovo riferimento a ogni ciclo (oggetto inline ricreato). Usare `useMemo`."_
>
> **Stessa risposta. ~70% di token in meno. Precisione tecnica intatta.** ✅
### 🎚️ Oltre i motori — stili di output, regolazione adattiva e controllo per richiesta
I 12 motori precedenti riducono ciò che **entra**. Altri tre livelli determinano **come**, **quando** e cosa **esce**:
- **🪄 Stili di output** _(controllo dell'asse di output)_ — inseriscono istruzioni deterministiche e compatibili con la cache per modellare le risposte; sono combinabili, ciascuno con intensità `lite` / `full` / `ultra`. Aggiungere uno stile richiede una sola riga nel registro:
- **Prosa concisa** — elimina riempitivi / articoli / formulazioni esitanti; mantiene intatta la sostanza tecnica.
- **Meno codice** — YAGNI da "senior dev pigro": la modifica funzionante più piccola, senza strutture non richieste.
- **Coda di cavallo (senior dev pigro)** — percorre la scala YAGNI, risolve la causa principale, produce il diff funzionante più piccolo.
- **Ho l'ADHD (prima l'azione)** — inizia con l'azione successiva, passaggi numerati, un solo prossimo passo concreto, nessun preambolo.
- **CJK conciso (文言)** — stile ultraconciso in cinese classico (limitato alle impostazioni locali `zh`).
- **🎯 Budget di contesto adattivo** _(la regolazione)_ — invece di un'unica soglia di token attiva/disattiva, incrementa l'uso dei motori più economici e con minore perdita solo quanto necessario per **rientrare nella finestra di contesto del modello**. Criterio: `reserve-output` (predefinito, consapevole del modello) · `percentage` · `absolute`. Modalità: `floor` (garantisce che rientri) · `replace-autotrigger` (prevale la scelta esplicita) · `off` (soglia precedente).
- **🎛️ Dove viene decisa la compressione** _(precedenza, da alta a bassa)_ — header per richiesta `x-omniroute-compression` › override della combinazione di routing › profilo denominato attivo › adattivo / attivazione automatica › valore predefinito del pannello › disattivata. Il piano applicato viene riportato nell'header di risposta `X-OmniRoute-Compression: ; source=`.
Attiva automaticamente in base alla soglia di token, abilita la regolazione adattiva, fissa un profilo denominato, configura un'impostazione una tantum per richiesta oppure assegna una pipeline a ciascuna combinazione di routing: scegli ciò che meglio si adatta al carico di lavoro. Un **harness di valutazione** offline facoltativo (`npm run eval:compression`) valuta fedeltà e risparmio su un corpus fissato prima di promuovere una modifica.
📖 [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)
# ⚡ Avvio rapido
**1) Installa e avvia**
```bash
npm install -g omniroute
omniroute
```
> 💡 Vedi `npm warn ERESOLVE` o avvisi sulle dipendenze peer? [Sono innocui](docs/guides/TROUBLESHOOTING.md#npm-install-warnings-eresolve--peer--deprecated).
> **Usi npm 11 o versioni successive?** npm potrebbe bloccare gli script del ciclo di vita dei pacchetti, a meno che non siano autorizzati. Il `postinstall` di OmniRoute (`node scripts/build/postinstall.mjs`) è necessario per preparare i file del runtime nativo. Durante l'installazione globale, autorizza i pacchetti indicati nell'avviso di npm. Per l'insieme di pacchetti segnalato da OmniRoute 3.8.51:
>
> ```bash
> npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute
> ```
>
> Per riutilizzare questa allowlist nelle future installazioni globali, configurala una volta, quindi esegui normalmente l'installazione:
>
> ```bash
> npm config set allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild --location=user
> npm install -g omniroute
> ```
>
> L'elenco delle dipendenze può cambiare tra le versioni; se npm segnala un elenco diverso, usa i nomi dei pacchetti indicati nell'avviso. Autorizzare un pacchetto consente l'esecuzione dei relativi script di installazione.
> **Usi Gemini Web o un altro provider basato sui cookie web?** Il pacchetto npm include
> Playwright, ma non il relativo binario Chromium. Consulta la nota sulla
> [configurazione di Chromium per Playwright](docs/guides/TROUBLESHOOTING.md#gemini-web-and-playwright-chromium)
> prima di effettuare la prima richiesta al provider web.
Dashboard su `http://localhost:20128` · API su `http://localhost:20128/v1`.
**2) Collega un provider idoneo usando il tuo account**
Dashboard → **Provider** → scegli un provider i cui termini e la cui quota attuali siano adatti al tuo caso d'uso → aggiungi la relativa chiave API o completa il flusso dell'account. I piani gratuiti potrebbero richiedere registrazione, approvazione o un metodo di pagamento. Consulta la [Guida ai piani gratuiti](docs/getting-started/FREE-TIERS-GUIDE.md); la disponibilità senza chiave non è garantita e i provider contrassegnati con `tos: avoid` sono esclusi da `auto` per impostazione predefinita.
**3) Configura il tuo strumento di programmazione**
```txt
URL di base: http://localhost:20128/v1
Chiave API: [copia da Dashboard → Endpoint]
Modello: auto (instrada tra le connessioni idonee — oppure scegli provider/modello)
```
**4) Verifica che funzioni**
```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```
Dovresti vedere elencati i modelli collegati. 🎉 Fatto: inizia a programmare e OmniRoute gestirà automaticamente il routing e il fallback.
Se il client non può inviare header personalizzati, OmniRoute espone anche alias di compatibilità con token:
```txt
Catalogo OpenAI: http://localhost:20128/vscode/YOUR_KEY/
Modelli OpenAI: http://localhost:20128/vscode/YOUR_KEY/models
Chat OpenAI: http://localhost:20128/vscode/YOUR_KEY/chat/completions
Risposte OpenAI: http://localhost:20128/vscode/YOUR_KEY/responses
Chat Ollama: http://localhost:20128/vscode/YOUR_KEY/api/chat
Tag Ollama: http://localhost:20128/vscode/YOUR_KEY/api/tags
```
Usali solo per i client che non possono aggiungere `Authorization: Bearer ...`. L'autenticazione tramite header resta la modalità preferita.
## 📦 Altri metodi di installazione — Docker, sorgenti, pnpm, Arch
**🐳 Docker**
```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
`:latest` segue la versione SemVer stabile **pubblicata** più recente. Non segue il branch git `main`. Usa `:X.Y.Z` per GitOps. Consulta [Canali di rilascio Docker](docs/guides/DOCKER_GUIDE.md#release-channels). L'immagine imposta **`OMNIROUTE_MEMORY_MB=1024`**. È sufficiente per la dashboard e una chat leggera. Gli **agenti di programmazione** (`POST /v1/responses` da Claude Code, Codex, Grok, …) richiedono un heap V8 molto più grande, altrimenti il processo genera un `FATAL ERROR` a circa 12 GiB con due contesti lunghi sovrapposti. Dimensiona il container al di sopra dell'heap (i buffer nativi risiedono al di fuori di V8):
| Carico di lavoro | Heap (`-e OMNIROUTE_MEMORY_MB`) | Container (`--memory`) |
| ------------------------------------- | ----------------------------------------- | ---------------------- |
| Dashboard / chat leggera | `1024` (valore predefinito dell'immagine) | ≥2 g |
| Un agente di programmazione | `8192` | ≥10 g |
| Due `/v1/responses` lunghi simultanei | `10240`–`12288` | ≥12–16 g |
```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
Tabella completa: [Guida Docker — RAM di runtime](docs/guides/DOCKER_GUIDE.md#runtime-ram-for-coding-agents).
> **Canale Docker di pre-release:** `diegosouzapw/omniroute:next` e
> `diegosouzapw/omniroute:next-web` seguono il branch `release/v*` predefinito
> corrente. Questi tag modificabili sono destinati esclusivamente al test di correzioni non ancora rilasciate e
> **non sono supportati in produzione**. Consulta
> [Canali di rilascio Docker](docs/guides/DOCKER_GUIDE.md#release-channels).
**🥟 Bun**
L'installazione standard con `bun install` e quella globale (`bun install -g omniroute`) sono supportate tramite il rilevamento del runtime Bun:
- **`bun:sqlite` integrato**: durante l'esecuzione con Bun, OmniRoute utilizza il driver `bun:sqlite` integrato di Bun, ricorrendo a `better-sqlite3` su Node.js oppure a `sql.js`.
- **Selezione automatica del bundler Webpack in sviluppo**: la modalità di sviluppo (`bun run dev`) rileva automaticamente Bun e disabilita Turbopack a favore di Webpack per evitare incompatibilità con i binding nativi V8. Le build di produzione (`bun run build`) rispettano esattamente `OMNIROUTE_USE_TURBOPACK` come su Node: Turbopack per impostazione predefinita, `OMNIROUTE_USE_TURBOPACK=0` per compilare con Webpack (`Dockerfile.bun` lo espone come `--build-arg`).
- **Dockerfile dedicato a Bun**: `Dockerfile.bun` multi-stage per distribuzioni di produzione native con Bun (`docker build -f Dockerfile.bun -t omniroute:bun .`).
```bash
# Installa ed esegui con Bun
bun install
bun run dev
```
**🛠️ Dai sorgenti**
```bash
cp .env.example .env && npm install
PORT=20128 npm run dev
```
**📦 pnpm**
```bash
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
```
**🐧 Arch Linux (AUR)**
```bash
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
```
**🔧 Nix (Flake)**
```bash
# Utilizzando i flake di Nix
nix develop
npm run dev
# Oppure utilizzando devbox
devbox run npm run dev
```
📖 [Guida Docker](docs/guides/DOCKER_GUIDE.md) — Profili Compose, HTTPS con Caddy, tunnel Cloudflare.
**🦭 Podman**
```bash
# 1. Prepara la directory dei dati montata tramite bind
mkdir -p data
# 2. Solo Linux + Podman rootless locale (mai un client Podman Machine remoto):
podman unshare chown 1000:1000 ./data
# 3. Imposta l'indicazione del runtime, crea l'immagine Compose locale e avvia
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
```
Su macOS o Windows, Podman utilizza una Podman Machine remota: salta `podman unshare` e
segui le [indicazioni sulla directory dei dati specifiche per la topologia](contrib/podman/README.md#data-directory-permissions-by-topology).
📖 [Guida Podman](contrib/podman/README.md) — Build Compose, Podman Machine e
configurazione Quadlet di Linux/systemd.
**⚡ Installazione più veloce / leggera (senza build nativa)**
Il motore SQLite nativo (`better-sqlite3`) è una dipendenza **opzionale**, quindi un'installazione
globale non rimane mai bloccata durante la compilazione dai sorgenti: utilizza un binario precompilato quando ne esiste uno compatibile
con la piattaforma/Node in uso; in caso contrario, passa automaticamente a un motore JavaScript puro
(`node:sqlite` su Node 22+, altrimenti il modulo WASM `sql.js` incluso) — senza richiedere strumenti di compilazione.
Per saltare completamente l'**inizializzazione nativa** successiva all'installazione (CI, sistemi headless o computer lenti).
Nota: questa opzione salta solo il passaggio di inizializzazione di SQLite nativo (`scripts/postinstall.mjs`); l'hook
di copia/riparazione del binario (`scripts/build/postinstall.mjs`) viene comunque eseguito normalmente:
```bash
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # Anche CI=1 lo salta
```
Per installazioni più rapide, preferisci **pnpm** (archivio indirizzato in base al contenuto + hard link — vedi sopra).
Per un runtime headless senza dashboard, utilizza il profilo Docker `base` (sopra) oppure la
[guida Termux](docs/guides/TERMUX_GUIDE.md). La CLI e la dashboard web vengono servite dallo
stesso processo su un'unica porta, quindi attualmente non esiste un pacchetto separato dedicato esclusivamente alla CLI.
OAuth 2.0 (PKCE) + JWT + chiavi API + autenticazione MCP con ambiti · AES-256-GCM per i dati inattivi · DOMPurify
Occultamento
wreq-js — imitazione delle impronte digitali TLS JA3 / JA4, proxy a 3 livelli
Resilienza
Circuit breaker, backoff esponenziale, protezione anti-thundering-herd, autoriparazione tramite auto-combo
Logging
pino — log JSON strutturati con il contesto della richiesta
Test
Test runner di Node.js + Vitest — oltre 39.000 dichiarazioni di test statiche in oltre 5.100 file di test tracciati (unitari, integrazione, E2E, sicurezza, ecosistema)
Strategia di copertura dei test per oltre 39.000 dichiarazioni di test statiche distribuite in oltre 5.100 file di test monitorati
# ⭐ Principali contributori
> OmniRoute è plasmato da un'appassionata comunità open source. Queste persone hanno fornito contributi eccezionali che incidono direttamente sulla qualità, sulla stabilità e sulla portata del progetto. **Grazie.**
### Contributori esterni per pull request unite
Dati congelati in corrispondenza del commit più recente dafb4ae808 del ramo live release/v3.8.50, con merge fino al 2026-08-24 05:26:03 UTC. Il censimento paginato tramite GitHub GraphQL contiene 5,911 PR unificate: 2,707 dal proprietario del repository, 179 da Dependabot e 3,025 PR esterne provenienti da 535 collaboratori distinti. Per «righe modificate» si intende la somma di aggiunte ed eliminazioni di GitHub, inclusi file generati, lockfile, cataloghi, traduzioni e documentazione; è una misura delle modifiche complessive, non delle righe di codice scritte. Le posizioni ex aequo al limite della classifica sono mantenute.
### Commit attribuiti da GitHub
Bob.Hou 🏅 51 commit attribuiti da GitHub · pari merito al 10º posto
Xiangzhe 🏅 51 commit attribuiti da GitHub · pari merito al 10º posto
Ricontrollato il 2026-08-24 alle 06:14:31 UTC: commit attribuiti da GitHub segnalati dall'API Contributors del repository per il ramo predefinito release/v3.8.50. L'API ha restituito 525 identità (415 utenti, 2 bot, 108 anonime); questa tabella esclude il manutentore, i bot e le identità anonime e mantiene i pari merito. È distinta sia dalla classifica delle PR unite riportata sopra sia dal censimento di 639 persone basato sui metadati Git riportato sotto.
> 🙏 Le funzionalità, le correzioni di bug e i miglioramenti all'infrastruttura apportati da questi collaboratori sono una **parte fondamentale** di ciò che rende OmniRoute affidabile e ricco di funzionalità. Ogni pull request, ogni caso di test e ogni file di traduzione i18n è importante. L'open source è costruito da persone come loro.
---
## 💖 Sponsor
Un sentito ringraziamento alle persone che finanziano OmniRoute di tasca propria: ogni contributo mantiene il progetto gratuito, indipendente e in continua evoluzione.
longtao 💛 Sostenitore passato con contributo una tantum
… e altri che preferiscono rimanere anonimi 💛Gli sponsor pubblici di GitHub sono stati riconvalidati il 2026-08-24. Lo stato activeOnly di GitHub determina le etichette relative agli sponsor attivi riportate sopra; i sostenitori pubblici con contributo una tantum già resi noti continuano a essere ringraziati, mentre gli sponsor privati rimangono anonimi.💖 Diventa sponsor → — ogni dollaro contribuisce a mantenere OmniRoute gratuito e indipendente.
## 👥 Oltre 600 contributori
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
Verificato il 2026-08-24 sulla base congelata ac02c5b42f e ricontrollato sulla punta attuale di release/v3.8.50, dafb4ae808: 639 identità Git umane normalizzate — 407 figurano come autori di commit (incluso il manutentore) e 232 compaiono soltanto nei trailer espliciti Co-authored-by. Il censimento normalizza gli handle noreply di GitHub, esclude 26 identità appartenenti a bot, agenti, servizi o segnaposto e non unifica i normali indirizzi email soltanto perché i relativi nomi visualizzati coincidono.
### Come contribuire
1. Crea un fork del repository
2. Crea un branch a partire dalla punta **attiva** di `release/vX.Y.Z` (non da `main`) — consulta [Modello di branching e rilascio](docs/ops/BRANCHING_MODEL.md)
3. Crea il branch per la tua funzionalità (`git checkout -b feat/amazing-feature`)
4. Esegui il commit delle modifiche (`git commit -m 'feat: add amazing feature'`)
5. Esegui il push sul branch (`git push origin feat/amazing-feature`)
6. Apri una Pull Request con **base = quel branch `release/vX.Y.Z`**
Consulta [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida dettagliate.
### Rilasciare una nuova versione
```bash
# Crea un rilascio: npm publish viene eseguito automaticamente
VERSION=x.y.z
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
## 📊 Stelle
## 🌍 StarMapper
## 🙏 Ringraziamenti
OmniRoute si regge sulle spalle di giganti. È nato come fork di **[9router](https://github.com/decolua/9router)** e come porting TypeScript del progetto Go **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** e, da lì, ogni sottosistema riportato di seguito è stato ispirato da un progetto open source che lo aveva realizzato per primo. Ognuno di essi ha plasmato una parte concreta di OmniRoute. Questo è il nostro modo di ringraziarli tutti. 🙏
> ⭐ conteggi delle stelle verificati tramite l'API REST di GitHub il 24 agosto 2026 — date una stella a questi progetti. I conteggi rappresentano un'istantanea esatta riferita a quella data e cambieranno naturalmente.
### 🧬 Origini e gateway
Il gateway di IA il cui dataset pubblico dei prezzi alimenta la nostra sincronizzazione del monitoraggio dei costi e il cui modello di normalizzazione dei provider ha contribuito a definire il nostro sistema di routing.
Codice sorgente MIT adattato nel bridge ChatGPT Web → Codex Responses integrato, inclusi gli adattatori per sessioni del browser, strutturazione delle risposte, utilizzo e ricerca sul web.
Pattern trasferiti nel ripristino degli stream, negli alias senza ragionamento, nella ricerca web di fallback, nei limiti a finestra scorrevole, nell'oscuramento dei log e nei flussi di avvio resi più sicuri.
Valori predefiniti di trasformazione compatibili con Claude Code e comportamento delle intestazioni di fatturazione, generalizzati nel bridge basato sulla configurazione di OmniRoute.
Le mappature dei modelli Grok, il generatore Statsig con TypeError simulato, i valori predefiniti per richieste e dispositivi e il processore di risposte NDJSON sono stati adattati in modo sostanziale nell'esecutore Grok Web di OmniRoute.
La principale fonte indiretta di codice alla base di grok2api-merged; le sue implementazioni di modelli, intestazioni, payload, Statsig e processori sono preservate nella derivazione di Grok Web.
Il codice sorgente MIT sottostante per i valori predefiniti del payload e dei dispositivi Grok, il generatore Statsig e il processore result.response propagato tramite TQZHR e grok2api-merged.
Una fonte indiretta accreditata da grok2api-merged per il suo livello di pool di proxy; OmniRoute ne preserva l'attribuzione nella derivazione, ma non dichiara alcun porting del pool di proxy nel proprio esecutore Grok Web circoscritto.
Il suo proxy Grok autenticato tramite cookie e il pattern di streaming result.response.token hanno contribuito a definire il trasporto Grok Web di OmniRoute.
L'implementazione originale di Grok Web ha preso in esame la sua architettura upstream HTTP/browser; il suo percorso HTTP diretto deriva da GrokProxy, pertanto non viene dichiarato alcun porting indipendente del codice.
Gli schemi Rust ChatOptions e delle buste di risposta hanno contribuito a definire i tipi TypeScript di OmniRoute per le richieste Grok e le risposte in streaming.
### 🗜️ Compressione del contesto e dei token — motori
Il progetto virale «perché usare molti token quando pochi token bastano» — la sua filosofia da uomo delle caverne alimenta la nostra modalità di compressione standard e oltre 30 regole per la rimozione dei riempitivi e la condensazione.
Compressione ad alte prestazioni dell'output dei comandi — ha ispirato il nostro motore RTK, il DSL per i filtri JSON, il recupero dell'output grezzo e la pipeline combinata RTK → Caveman.
Ricerca sulla compressione dei prompt (LLMLingua / LLMLingua-2) — ha ispirato il nostro motore llmlingua asincrono, sicuro per il codice e con comportamento fail-open.
Compressione dei token in portoghese brasiliano — alimenta il nostro pacchetto linguistico pt-BR: riduzione dei pleonasmi e rimozione dei riempitivi ottimizzate per la grammatica del portoghese brasiliano.
La skill virale del «senior dev pigro» basata su YAGNI — ha ispirato il nostro stile di output less-code: orientamento alla modifica funzionante più piccola, che riduce il codice _generato_ (l'equivalente, sull'asse dell'output, della prosa concisa di Caveman).
Il suo stile di risposta orientato all'azione e adatto alle persone con ADHD è stato adattato nello stile di output conciso di OmniRoute in cinque lingue.
### 🧩 Formati compatti, ricerca sui token e strumenti sensibili al codice
Il suo formato compatto per grafi e il design a profilo generico hanno contribuito alla progettazione della compattazione tabulare e del formato codec Headroom di OmniRoute.
Compattazione dell'output Bash + profili MCP — ha ispirato la nostra disciplina di interruzione della compressione e la riduzione dei manifest degli strumenti MCP.
Compressione dell'output sensibile al contenuto e specifica per tipo di file, con interruzione in caso di errore — ha convalidato il nostro dispatch per tipo e il salto in caso di guadagno inferiore alla soglia minima.
JSON colonnare in Rust + recupero con indirizzamento per contenuto + deduplicazione tra messaggi — ha convalidato il design dei nostri motori headroom/ccr/session-dedup e l'invariante «la forma compressa è indipendente dalla posizione», che garantisce la stabilità della cache.
Compressione degli schemi e delle descrizioni degli strumenti MCP — ha contribuito alla nostra riduzione della cardinalità dei manifest degli strumenti MCP.
Classificazione delle mappe dei repository in stile Aider — ha contribuito alla nostra esplorazione delle mappe dei repository e della classificazione per il recupero.
Toolkit per la TypeScript Compiler API — ha ispirato la nostra rimozione dei commenti basata su parser, che preserva i letterali stringa, template e regex.
L'intercettazione/analisi MITM del traffico tra assistente di programmazione e LLM ha contribuito a definire i requisiti iniziali di Traffic Inspector. Quattro moduli derivati in precedenza — unione SSE, normalizzazione delle conversazioni, mascheramento dei segreti e sanificazione degli header — sono stati sostituiti da implementazioni clean-room indipendenti basate su standard di protocollo pubblici. Le due superfici di passthrough dell'host (passthrough.ts e _internal/bypass.cjs) rimangono implementazioni interne di OmniRoute classificate in modo indipendente; non sono state riscritte nell'ambito di tale sostituzione.
Instradamento proxy trasparente per processo — ha ispirato il nostro arresto MITM resistente ai crash, i timeout di inattività dei socket, l'attribuzione dei processi tramite /proc e l'acquisizione TPROXY.
Osservabilità della service mesh Istio — ha ispirato i nostri badge dei circuit breaker e la rappresentazione visiva degli archi di errore nel Routing/Combo Studio.
Un elenco curato di librerie sicure per impostazione predefinita che guida le nostre scelte in materia di sicurezza (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).
Ha ispirato la deduplicazione delle richieste, il fallback di emergenza a costo zero, le strategie Auto-Combo collegabili e la classificazione multilingue degli intenti.
La rimappatura dei modelli basata sull'account, la convalida del percorso dell'eseguibile e il comportamento delle etichette dei piani hanno contribuito a definire il runtime Antigravity di OmniRoute.
Il suo formato compatto per il conto alla rovescia fino al ripristino della quota ha ispirato la corrispondente visualizzazione dei limiti del provider in OmniRoute.
Ha identificato la superficie delle quote di Grok Build; OmniRoute ha quindi verificato e corretto in modo indipendente il formato dei dati trasmessi in tempo reale.
## 📄 Licenza
Licenza MIT - consulta [LICENSE](LICENSE) per i dettagli.
---
**[⬆ Torna all'inizio](#-omniroute)** · Realizzato con ❤️ per la comunità IA open source.
OmniRoute v3.8.52 · Node ≥22.22.2 · Licenza MIT · omniroute.online
> Riepilogo animato della pagina live `/dashboard/free-tiers`. Metodologia completa (deduplicazione dei pool, livelli di credito, termini dei provider): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Queste cifre vengono sottoposte a una nuova verifica ogni due settimane rispetto al catalogo live e **possono variare in entrambe le direzioni**: se un provider termina un livello gratuito, il numero diminuisce; se ne arriva uno nuovo, aumenta. Pubblichiamo ciò che il catalogo calcola effettivamente, mai un caso migliore arrotondato per eccesso.
```bash
# Dopo aver connesso un provider, copia la tua chiave OmniRoute da Dashboard → Endpoints:
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_OMNIROUTE_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
`auto` richiede un percorso idoneo. Una nuova installazione potrebbe non avere destinazioni idonee senza chiave e un provider senza chiave potrebbe rifiutare client di terze parti. I provider contrassegnati con `tos: avoid`, inclusi OpenCode Free e Kiro, sono esclusi per impostazione predefinita dall'instradamento automatico; connettere un account non modifica questa impostazione. Consulta la [Guida ai piani gratuiti](docs/getting-started/FREE-TIERS-GUIDE.md) prima di scegliere un provider.
📦 Script di avvio rapido da copiare e incollare per **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
> Un **combo** è una catena di modelli tra i quali OmniRoute instrada le richieste **automaticamente**. Se la quota si esaurisce, un provider non funziona o i costi aumentano improvvisamente, il combo può passare al successivo modello idoneo e operativo. 🛡️
### ⚡ Zero configurazione — usa semplicemente `auto`
Non è necessario creare alcun combo. Imposta il modello su `auto` (o su una sua variante) e OmniRoute crea un combo virtuale utilizzando i provider connessi, valutati in tempo reale:
📖 [Motore Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guida alla resilienza](docs/architecture/RESILIENCE_GUIDE.md)
📊 Metodologia completa e dettagli per ciascuna funzionalità rispetto a 9router, OpenRouter, CLIProxyAPI e LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
Chiave (casuale): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix copia e incolla:
```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```
📖 [Autorizzazione](docs/architecture/AUTHZ_GUIDE.md) · [Misure di sicurezza](docs/security/GUARDRAILS.md) · [Conformità](docs/security/COMPLIANCE.md)
La combinazione predefinita esegue `RTK → Caveman`. Quando entrambi agiscono sullo stesso payload di strumenti/contesto, i risparmi si moltiplicano:
```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
```
I blocchi di codice, gli URL, il JSON e i dati strutturati sono **sempre protetti** dal motore di conservazione.
> **Perché usare molti token quando ne bastano pochi?** Ogni richiesta attraversa la pipeline di compressione di OmniRoute **in modo trasparente** — senza modifiche al client. Ora è una **pila di 12 motori componibili** che vengono eseguiti in sequenza e combinati in base alla configurazione di routing — basandosi sulle idee di [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) e [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 La pila di 12 motori
I motori vengono eseguiti nell'ordine della pipeline; ciascuno può essere attivato o disattivato e configurato indipendentemente per ogni combinazione:
