omniroute 0.8.5 → 0.9.0

package/README.it.md

@@ -0,0 +1,995 @@
+<div align="center">
+  <img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
+  
+  # 🚀 OmniRoute — Il Gateway IA Gratuito
+
+### Non smettere mai di programmare. Routing intelligente verso **modelli IA GRATUITI e economici** con fallback automatico.
+
+_Il tuo proxy API universale — un endpoint, 36+ provider, zero downtime._
+
+**Chat Completions • Embeddings • Generazione Immagini • Audio • Reranking • 100% TypeScript**
+
+---
+
+### 🤖 Provider IA gratuito per i tuoi agenti di programmazione preferiti
+
+_Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API gratuito per programmazione illimitata._
+
+  <table>
+    <tr>
+      <td align="center" width="110">
+        <a href="https://github.com/cline/cline">
+          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
+          <b>OpenClaw</b>
+        </a><br/>
+        <sub>⭐ 205K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/HKUDS/nanobot">
+          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
+          <b>NanoBot</b>
+        </a><br/>
+        <sub>⭐ 20.9K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/sipeed/picoclaw">
+          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
+          <b>PicoClaw</b>
+        </a><br/>
+        <sub>⭐ 14.6K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/zeroclaw-labs/zeroclaw">
+          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
+          <b>ZeroClaw</b>
+        </a><br/>
+        <sub>⭐ 9.9K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/nearai/ironclaw">
+          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
+          <b>IronClaw</b>
+        </a><br/>
+        <sub>⭐ 2.1K</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="110">
+        <a href="https://github.com/anomalyco/opencode">
+          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
+          <b>OpenCode</b>
+        </a><br/>
+        <sub>⭐ 106K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/openai/codex">
+          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
+          <b>Codex CLI</b>
+        </a><br/>
+        <sub>⭐ 60.8K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/anthropics/claude-code">
+          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
+          <b>Claude Code</b>
+        </a><br/>
+        <sub>⭐ 67.3K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/google-gemini/gemini-cli">
+          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
+          <b>Gemini CLI</b>
+        </a><br/>
+        <sub>⭐ 94.7K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/Kilo-Org/kilocode">
+          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
+          <b>Kilo Code</b>
+        </a><br/>
+        <sub>⭐ 15.5K</sub>
+      </td>
+    </tr>
+  </table>
+
+<sub>📡 Tutti gli agenti si connettono via <code>http://localhost:20128/v1</code> o <code>http://cloud.omniroute.online/v1</code> — una configurazione, modelli e quota illimitati</sub>
+
+---
+
+[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
+[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
+[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
+
+[🌐 Sito Web](https://omniroute.online) • [🚀 Avvio Rapido](#-avvio-rapido) • [💡 Funzionalità](#-funzionalità-principali) • [📖 Docs](#-documentazione) • [💰 Prezzi](#-panoramica-prezzi)
+
+🌐 **Disponibile in:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+
+</div>
+
+---
+
+## 🤔 Perché OmniRoute?
+
+**Smetti di sprecare soldi e di sbattere contro i limiti:**
+
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> La quota dell'abbonamento scade inutilizzata ogni mese
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> I limiti di rate ti fermano nel mezzo della programmazione
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> API costose ($20-50/mese per provider)
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Cambio manuale tra provider
+
+**OmniRoute risolve tutto questo:**
+
+- ✅ **Massimizza gli abbonamenti** — Traccia le quote, usa tutto prima del reset
+- ✅ **Fallback automatico** — Abbonamento → API Key → Economico → Gratuito, zero downtime
+- ✅ **Multi-account** — Round-robin tra account per provider
+- ✅ **Universale** — Funziona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualsiasi strumento CLI
+
+---
+
+## 🔄 Come Funziona
+
+```
+┌─────────────┐
+│  Il tuo CLI │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────┐
+│         OmniRoute (Router Intelligente)  │
+│  • Traduzione formato (OpenAI ↔ Claude) │
+│  • Tracciamento quote + Embeddings + Immagini │
+│  • Rinnovo automatico dei token         │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [Tier 1: ABBONAMENTO] Claude Code, Codex, Gemini CLI
+       │   ↓ quota esaurita
+       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, ecc.
+       │   ↓ limite budget
+       ├─→ [Tier 3: ECONOMICO] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ limite budget
+       └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (illimitato)
+
+Risultato: Non smettere mai di programmare, costo minimo
+```
+
+---
+
+## ⚡ Avvio Rapido
+
+**1. Installa globalmente:**
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+🎉 La Dashboard si apre su `http://localhost:20128`
+
+| Comando                 | Descrizione                                 |
+| ----------------------- | ------------------------------------------- |
+| `omniroute`             | Avviare il server (porta predefinita 20128) |
+| `omniroute --port 3000` | Usare una porta personalizzata              |
+| `omniroute --no-open`   | Non aprire il browser automaticamente       |
+| `omniroute --help`      | Mostrare l'aiuto                            |
+
+**2. Connetti un provider GRATUITO:**
+
+Dashboard → Provider → Connetti **Claude Code** o **Antigravity** → Login OAuth → Fatto!
+
+**3. Usa nel tuo strumento CLI:**
+
+```
+Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Impostazioni:
+  Endpoint: http://localhost:20128/v1
+  API Key: [copia dalla dashboard]
+  Model: if/kimi-k2-thinking
+```
+
+**Tutto qui!** Inizia a programmare con modelli IA GRATUITI.
+
+**Alternativa — eseguire dal codice sorgente:**
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+---
+
+## 🐳 Docker
+
+OmniRoute è disponibile come immagine Docker pubblica su [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+
+**Avvio rapido:**
+
+```bash
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+**Con file di ambiente:**
+
+```bash
+# Copia e modifica il .env prima
+cp .env.example .env
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file .env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+**Con Docker Compose:**
+
+```bash
+# Profilo base (senza strumenti CLI)
+docker compose --profile base up -d
+
+# Profilo CLI (Claude Code, Codex, OpenClaw integrati)
+docker compose --profile cli up -d
+```
+
+| Immagine                 | Tag      | Dimensione | Descrizione             |
+| ------------------------ | -------- | ---------- | ----------------------- |
+| `diegosouzapw/omniroute` | `latest` | ~250MB     | Ultima versione stabile |
+| `diegosouzapw/omniroute` | `0.9.0`  | ~250MB     | Versione attuale        |
+
+---
+
+## 💰 Panoramica Prezzi
+
+| Tier               | Provider          | Costo                        | Reset Quota           | Ideale Per                      |
+| ------------------ | ----------------- | ---------------------------- | --------------------- | ------------------------------- |
+| **💳 ABBONAMENTO** | Claude Code (Pro) | $20/mese                     | 5h + settimanale      | Già abbonato                    |
+|                    | Codex (Plus/Pro)  | $20-200/mese                 | 5h + settimanale      | Utenti OpenAI                   |
+|                    | Gemini CLI        | **GRATUITO**                 | 180K/mese + 1K/giorno | Tutti!                          |
+|                    | GitHub Copilot    | $10-19/mese                  | Mensile               | Utenti GitHub                   |
+| **🔑 API KEY**     | NVIDIA NIM        | **GRATUITO** (1000 crediti)  | Una tantum            | Test gratuiti                   |
+|                    | DeepSeek          | A consumo                    | Nessuno               | Miglior rapporto qualità-prezzo |
+|                    | Groq              | Livello gratis + a pagamento | Limitato              | Inferenza ultra-veloce          |
+|                    | xAI (Grok)        | A consumo                    | Nessuno               | Modelli Grok                    |
+|                    | Mistral           | Livello gratis + a pagamento | Limitato              | IA Europea                      |
+|                    | OpenRouter        | A consumo                    | Nessuno               | 100+ modelli                    |
+| **💰 ECONOMICO**   | GLM-4.7           | $0.6/1M                      | Giornaliero 10h       | Backup economico                |
+|                    | MiniMax M2.1      | $0.2/1M                      | Rotativo 5h           | Opzione più economica           |
+|                    | Kimi K2           | $9/mese fisso                | 10M token/mese        | Costo prevedibile               |
+| **🆓 GRATUITO**    | iFlow             | $0                           | Illimitato            | 8 modelli gratuiti              |
+|                    | Qwen              | $0                           | Illimitato            | 3 modelli gratuiti              |
+|                    | Kiro              | $0                           | Illimitato            | Claude gratuito                 |
+
+**💡 Consiglio Pro:** Inizia con Gemini CLI (180K gratis/mese) + iFlow (illimitato gratis) = $0 di costo!
+
+---
+
+## 🎯 Casi d'Uso
+
+### Caso 1: "Ho un abbonamento Claude Pro"
+
+**Problema:** La quota scade inutilizzata, limiti di rate durante la programmazione intensa
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        (usa l'abbonamento al massimo)
+  2. glm/glm-4.7               (backup economico quando la quota è esaurita)
+  3. if/kimi-k2-thinking       (fallback d'emergenza gratuito)
+
+Costo mensile: $20 (abbonamento) + ~$5 (backup) = $25 totale
+vs. $20 + sbattere contro i limiti = frustrazione
+```
+
+### Caso 2: "Voglio costo zero"
+
+**Problema:** Non può permettersi abbonamenti, ha bisogno di IA affidabile per programmare
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         (180K gratis/mese)
+  2. if/kimi-k2-thinking       (illimitato gratis)
+  3. qw/qwen3-coder-plus       (illimitato gratis)
+
+Costo mensile: $0
+Qualità: Modelli pronti per la produzione
+```
+
+### Caso 3: "Devo programmare 24/7, senza interruzioni"
+
+**Problema:** Scadenze strette, non può permettersi downtime
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        (migliore qualità)
+  2. cx/gpt-5.2-codex          (secondo abbonamento)
+  3. glm/glm-4.7               (economico, reset giornaliero)
+  4. minimax/MiniMax-M2.1      (più economico, reset 5h)
+  5. if/kimi-k2-thinking       (gratuito illimitato)
+
+Risultato: 5 livelli di fallback = zero downtime
+```
+
+### Caso 4: "Voglio IA GRATUITA in OpenClaw"
+
+**Problema:** Ha bisogno di assistente IA nelle app di messaggistica, completamente gratuito
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                (illimitato gratis)
+  2. if/minimax-m2.1           (illimitato gratis)
+  3. if/kimi-k2-thinking       (illimitato gratis)
+
+Costo mensile: $0
+Accesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
+```
+
+---
+
+## 💡 Funzionalità Principali
+
+### 🧠 Routing & Intelligenza
+
+| Funzionalità                             | Cosa Fa                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| 🎯 **Fallback intelligente 4 livelli**   | Auto-routing: Abbonamento → API Key → Economico → Gratuito                    |
+| 📊 **Tracciamento quote in tempo reale** | Conteggio token live + countdown reset per provider                           |
+| 🔄 **Traduzione di formato**             | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro trasparente                          |
+| 👥 **Supporto multi-account**            | Account multipli per provider con selezione intelligente                      |
+| 🔄 **Rinnovo automatico dei token**      | I token OAuth si rinnovano automaticamente con retry                          |
+| 🎨 **Combo personalizzati**              | 6 strategie: fill-first, round-robin, p2c, random, least-used, cost-optimized |
+| 🧩 **Modelli personalizzati**            | Aggiungi qualsiasi ID modello a qualsiasi provider                            |
+| 🌐 **Router wildcard**                   | Instrada pattern `provider/*` verso qualsiasi provider dinamicamente          |
+| 🧠 **Budget di ragionamento**            | Modalità passthrough, auto, custom e adaptive per modelli di ragionamento     |
+| 💬 **Iniezione System Prompt**           | System prompt globale applicato a tutte le richieste                          |
+| 📄 **API Responses**                     | Supporto completo per OpenAI Responses API (`/v1/responses`) per Codex        |
+
+### 🎵 API Multi-modali
+
+| Funzionalità                | Cosa Fa                                              |
+| --------------------------- | ---------------------------------------------------- |
+| 🖼️ **Generazione immagini** | `/v1/images/generations` — 4 provider, 9+ modelli    |
+| 📐 **Embeddings**           | `/v1/embeddings` — 6 provider, 9+ modelli            |
+| 🎤 **Trascrizione audio**   | `/v1/audio/transcriptions` — Compatibile Whisper     |
+| 🔊 **Testo a voce**         | `/v1/audio/speech` — Sintesi audio multi-provider    |
+| 🛡️ **Moderazioni**          | `/v1/moderations` — Controlli di sicurezza           |
+| 🔀 **Reranking**            | `/v1/rerank` — Riclassificazione rilevanza documenti |
+
+### 🛡️ Resilienza & Sicurezza
+
+| Funzionalità                    | Cosa Fa                                                        |
+| ------------------------------- | -------------------------------------------------------------- |
+| 🔌 **Circuit Breaker**          | Apertura/chiusura auto per provider con soglie configurabili   |
+| 🛡️ **Anti-Thundering Herd**     | Mutex + semaforo rate-limit per provider con API key           |
+| 🧠 **Cache semantica**          | Cache a due livelli (firma + semantica) riduce costi e latenza |
+| ⚡ **Idempotenza richieste**    | Finestra dedup 5s per richieste duplicate                      |
+| 🔒 **Spoofing TLS Fingerprint** | Bypass rilevamento bot tramite wreq-js                         |
+| 🌐 **Filtro IP**                | Allowlist/blocklist per controllo accesso API                  |
+| 📊 **Rate limit modificabili**  | RPM, gap minimo e concorrenza massima configurabili            |
+
+### 📊 Osservabilità & Analytics
+
+| Funzionalità                  | Cosa Fa                                                      |
+| ----------------------------- | ------------------------------------------------------------ |
+| 📝 **Log richieste**          | Modalità debug con log completi richiesta/risposta           |
+| 💾 **Log SQLite**             | Log proxy persistenti che sopravvivono ai riavvii            |
+| 📊 **Dashboard analytics**    | Recharts: card statistiche, grafico uso, tabella provider    |
+| 📈 **Tracciamento progresso** | Eventi SSE di progresso opt-in per lo streaming              |
+| 🧪 **Valutazioni LLM**        | Test con golden set e 4 strategie di corrispondenza          |
+| 🔍 **Telemetria richieste**   | Aggregazione latenza p50/p95/p99 + tracciamento X-Request-Id |
+| 📋 **Log + Quote**            | Pagine dedicate per navigazione log e tracciamento quote     |
+| 🏥 **Dashboard salute**       | Uptime, stati circuit breaker, lockout, statistiche cache    |
+| 💰 **Tracciamento costi**     | Gestione budget + configurazione prezzi per modello          |
+
+### ☁️ Deploy & Sincronizzazione
+
+| Funzionalità                     | Cosa Fa                                                                          |
+| -------------------------------- | -------------------------------------------------------------------------------- |
+| 💾 **Cloud Sync**                | Sincronizza impostazioni tra dispositivi via Cloudflare Workers                  |
+| 🌐 **Deploy ovunque**            | Localhost, VPS, Docker, Cloudflare Workers                                       |
+| 🔑 **Gestione API Key**          | Genera, ruota e limita API key per provider                                      |
+| 🧙 **Assistente configurazione** | Setup guidato in 4 passaggi per nuovi utenti                                     |
+| 🔧 **Dashboard CLI Tools**       | Configurazione con un clic per Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
+| 🔄 **Backup DB**                 | Backup e ripristino automatici di tutte le impostazioni                          |
+
+<details>
+<summary><b>📖 Dettagli funzionalità</b></summary>
+
+### 🎯 Fallback intelligente 4 livelli
+
+Crea combo con fallback automatico:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (il tuo abbonamento)
+  2. nvidia/llama-3.3-70b      (API NVIDIA gratuita)
+  3. glm/glm-4.7               (backup economico, $0.6/1M)
+  4. if/kimi-k2-thinking       (fallback gratuito)
+
+→ Cambia automaticamente quando la quota si esaurisce o si verificano errori
+```
+
+### 📊 Tracciamento quote in tempo reale
+
+- Consumo token per provider
+- Countdown reset (5 ore, giornaliero, settimanale)
+- Stima dei costi per livelli a pagamento
+- Report spese mensili
+
+### 🔄 Traduzione di formato
+
+Traduzione trasparente tra formati:
+
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- Il tuo CLI invia in formato OpenAI → OmniRoute traduce → Il provider riceve il formato nativo
+- Funziona con qualsiasi strumento che supporti endpoint OpenAI personalizzati
+
+### 👥 Supporto multi-account
+
+- Aggiungi account multipli per provider
+- Round-robin automatico o routing per priorità
+- Fallback all'account successivo quando la quota viene raggiunta
+
+### 🔄 Rinnovo automatico dei token
+
+- I token OAuth si rinnovano automaticamente prima della scadenza
+- Nessuna necessità di ri-autenticazione manuale
+- Esperienza trasparente su tutti i provider
+
+### 🎨 Combo personalizzati
+
+- Crea combinazioni di modelli illimitate
+- 6 strategie: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
+- Condividi combo tra dispositivi con Cloud Sync
+
+### 🏥 Dashboard salute
+
+- Stato del sistema (uptime, versione, utilizzo memoria)
+- Stati circuit breaker per provider (Closed/Open/Half-Open)
+- Stato rate limit e lockout attivi
+- Statistiche cache firme
+- Telemetria latenza (p50/p95/p99) + cache prompt
+- Reset salute con un clic
+
+### 🔧 Playground del traduttore
+
+- Debug, test e visualizzazione delle traduzioni di formato API
+- Invia richieste e vedi come OmniRoute traduce tra formati dei provider
+- Inestimabile per risolvere problemi di integrazione
+
+### 💾 Cloud Sync
+
+- Sincronizza provider, combo e impostazioni tra dispositivi
+- Sincronizzazione in background automatica
+- Archiviazione criptata sicura
+
+</details>
+
+---
+
+## 📖 Guida alla Configurazione
+
+<details>
+<summary><b>💳 Provider per abbonamento</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+Dashboard → Provider → Connetti Claude Code
+→ Login OAuth → Rinnovo automatico token
+→ Tracciamento quota 5h + settimanale
+
+Modelli:
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**Consiglio Pro:** Usa Opus per compiti complessi, Sonnet per velocità. OmniRoute traccia la quota per modello!
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+Dashboard → Provider → Connetti Codex
+→ Login OAuth (porta 1455)
+→ Reset 5h + settimanale
+
+Modelli:
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI (GRATUITO 180K/mese!)
+
+```bash
+Dashboard → Provider → Connetti Gemini CLI
+→ Google OAuth
+→ 180K completions/mese + 1K/giorno
+
+Modelli:
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**Miglior valore:** Livello gratuito enorme! Usa prima dei livelli a pagamento.
+
+### GitHub Copilot
+
+```bash
+Dashboard → Provider → Connetti GitHub
+→ OAuth via GitHub
+→ Reset mensile (1° del mese)
+
+Modelli:
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>🔑 Provider per API Key</b></summary>
+
+### NVIDIA NIM (GRATUITO 1000 crediti!)
+
+1. Registrati: [build.nvidia.com](https://build.nvidia.com)
+2. Ottieni una API key gratuita (1000 crediti di inferenza inclusi)
+3. Dashboard → Aggiungi Provider → NVIDIA NIM:
+   - API Key: `nvapi-your-key`
+
+**Modelli:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` e 50+ altri
+
+**Consiglio Pro:** API compatibile OpenAI — funziona perfettamente con la traduzione di formato di OmniRoute!
+
+### DeepSeek
+
+1. Registrati: [platform.deepseek.com](https://platform.deepseek.com)
+2. Ottieni una API key
+3. Dashboard → Aggiungi Provider → DeepSeek
+
+**Modelli:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
+
+### Groq (Livello gratuito disponibile!)
+
+1. Registrati: [console.groq.com](https://console.groq.com)
+2. Ottieni una API key (livello gratuito incluso)
+3. Dashboard → Aggiungi Provider → Groq
+
+**Modelli:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
+
+**Consiglio Pro:** Inferenza ultra-veloce — ideale per programmazione in tempo reale!
+
+### OpenRouter (100+ modelli)
+
+1. Registrati: [openrouter.ai](https://openrouter.ai)
+2. Ottieni una API key
+3. Dashboard → Aggiungi Provider → OpenRouter
+
+**Modelli:** Accesso a 100+ modelli da tutti i principali provider tramite una singola API key.
+
+</details>
+
+<details>
+<summary><b>💰 Provider economici (Backup)</b></summary>
+
+### GLM-4.7 (Reset giornaliero, $0.6/1M)
+
+1. Registrati: [Zhipu AI](https://open.bigmodel.cn/)
+2. Ottieni la API key dal Coding Plan
+3. Dashboard → Aggiungi API Key:
+   - Provider: `glm`
+   - API Key: `your-key`
+
+**Usa:** `glm/glm-4.7`
+
+**Consiglio Pro:** Il Coding Plan offre 3× quota a 1/7 del costo! Reset giornaliero alle 10:00.
+
+### MiniMax M2.1 (Reset 5h, $0.20/1M)
+
+1. Registrati: [MiniMax](https://www.minimax.io/)
+2. Ottieni una API key
+3. Dashboard → Aggiungi API Key
+
+**Usa:** `minimax/MiniMax-M2.1`
+
+**Consiglio Pro:** L'opzione più economica per contesto lungo (1M token)!
+
+### Kimi K2 ($9/mese fisso)
+
+1. Abbonati: [Moonshot AI](https://platform.moonshot.ai/)
+2. Ottieni una API key
+3. Dashboard → Aggiungi API Key
+
+**Usa:** `kimi/kimi-latest`
+
+**Consiglio Pro:** $9/mese fisso per 10M token = $0.90/1M di costo effettivo!
+
+</details>
+
+<details>
+<summary><b>🆓 Provider GRATUITI (Backup d'emergenza)</b></summary>
+
+### iFlow (8 modelli GRATUITI)
+
+```bash
+Dashboard → Connetti iFlow
+→ Login OAuth iFlow
+→ Utilizzo illimitato
+
+Modelli:
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen (3 modelli GRATUITI)
+
+```bash
+Dashboard → Connetti Qwen
+→ Autorizzazione con codice dispositivo
+→ Utilizzo illimitato
+
+Modelli:
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro (Claude GRATUITO)
+
+```bash
+Dashboard → Connetti Kiro
+→ AWS Builder ID o Google/GitHub
+→ Utilizzo illimitato
+
+Modelli:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 Creare combo</b></summary>
+
+### Esempio 1: Massimizzare abbonamento → Backup economico
+
+```
+Dashboard → Combo → Crea nuovo
+
+Nome: premium-coding
+Modelli:
+  1. cc/claude-opus-4-6 (Abbonamento principale)
+  2. glm/glm-4.7 (Backup economico, $0.6/1M)
+  3. minimax/MiniMax-M2.1 (Fallback più economico, $0.20/1M)
+
+Usa nel CLI: premium-coding
+```
+
+### Esempio 2: Solo gratuiti (Costo zero)
+
+```
+Nome: free-combo
+Modelli:
+  1. gc/gemini-3-flash-preview (180K gratis/mese)
+  2. if/kimi-k2-thinking (illimitato)
+  3. qw/qwen3-coder-plus (illimitato)
+
+Costo: $0 per sempre!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 Integrazione CLI</b></summary>
+
+### Cursor IDE
+
+```
+Impostazioni → Modelli → Avanzato:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [dalla dashboard OmniRoute]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+Usa la pagina **CLI Tools** nella dashboard per la configurazione con un clic, o modifica `~/.claude/settings.json` manualmente.
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**Opzione 1 — Dashboard (consigliato):**
+
+```
+Dashboard → CLI Tools → OpenClaw → Seleziona Modello → Applica
+```
+
+**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. Usa `127.0.0.1` invece di `localhost` per evitare problemi di risoluzione IPv6.
+
+### Cline / Continue / RooCode
+
+```
+Impostazioni → Configurazione API:
+  Provider: OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  API Key: [dalla dashboard OmniRoute]
+  Model: if/kimi-k2-thinking
+```
+
+</details>
+
+---
+
+## 📊 Modelli Disponibili
+
+<details>
+<summary><b>Vedi tutti i modelli disponibili</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - GRATUITO:
+
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+
+- `gh/gpt-5`
+- `gh/claude-4.5-sonnet`
+
+**NVIDIA NIM (`nvidia/`)** - Crediti GRATUITI:
+
+- `nvidia/llama-3.3-70b-instruct`
+- `nvidia/mistral-7b-instruct`
+- 50+ modelli su [build.nvidia.com](https://build.nvidia.com)
+
+**GLM (`glm/`)** - $0.6/1M:
+
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+
+- `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - GRATUITO:
+
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+- `if/glm-4.7`
+- `if/minimax-m2`
+
+**Qwen (`qw/`)** - GRATUITO:
+
+- `qw/qwen3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - GRATUITO:
+
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+**OpenRouter (`or/`)** - 100+ modelli:
+
+- `or/anthropic/claude-4-sonnet`
+- `or/google/gemini-2.5-pro`
+- Qualsiasi modello da [openrouter.ai/models](https://openrouter.ai/models)
+
+</details>
+
+---
+
+## 🧪 Valutazioni (Evals)
+
+OmniRoute include un framework di valutazione integrato per testare la qualità delle risposte LLM contro un golden set. Accesso via **Analytics → Evals** nella dashboard.
+
+### Golden Set integrato
+
+Il "OmniRoute Golden Set" precaricato contiene 10 casi di test:
+
+- Saluti, matematica, geografia, generazione codice
+- Conformità formato JSON, traduzione, markdown
+- Rifiuto sicurezza (contenuto nocivo), conteggio, logica booleana
+
+### Strategie di valutazione
+
+| Strategia  | Descrizione                                                | Esempio                          |
+| ---------- | ---------------------------------------------------------- | -------------------------------- |
+| `exact`    | L'output deve corrispondere esattamente                    | `"4"`                            |
+| `contains` | L'output deve contenere la sottostringa (case-insensitive) | `"Paris"`                        |
+| `regex`    | L'output deve corrispondere al pattern regex               | `"1.*2.*3"`                      |
+| `custom`   | Funzione JS personalizzata restituisce true/false          | `(output) => output.length > 10` |
+
+---
+
+## 🐛 Risoluzione Problemi
+
+<details>
+<summary><b>Clicca per espandere la guida alla risoluzione problemi</b></summary>
+
+**"Language model did not provide messages"**
+
+- Quota del provider esaurita → Controlla il tracker quote nella dashboard
+- Soluzione: Usa un combo con fallback o passa a un livello più economico
+
+**Rate limiting**
+
+- Quota abbonamento esaurita → Fallback a GLM/MiniMax
+- Aggiungi combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**Token OAuth scaduto**
+
+- Rinnovato automaticamente da OmniRoute
+- Se il problema persiste: Dashboard → Provider → Riconnetti
+
+**Costi elevati**
+
+- Controlla le statistiche di utilizzo in Dashboard → Costi
+- Cambia il modello principale a GLM/MiniMax
+- Usa il livello gratuito (Gemini CLI, iFlow) per compiti non critici
+
+**La dashboard si apre sulla porta sbagliata**
+
+- Imposta `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**Errori cloud sync**
+
+- 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 del server
+
+**Il primo login non funziona**
+
+- Controlla `INITIAL_PASSWORD` nel `.env`
+- Se non impostata, la password predefinita è `123456`
+
+**Nessun log delle richieste**
+
+- Imposta `ENABLE_REQUEST_LOGS=true` nel `.env`
+
+**Il test di connessione mostra "Invalid" per provider compatibili OpenAI**
+
+- Molti provider non espongono l'endpoint `/models`
+- OmniRoute v0.9.0+ include validazione fallback tramite chat completions
+- Assicurati che la URL base includa il suffisso `/v1`
+
+</details>
+
+---
+
+## 🛠️ Stack Tecnologico
+
+- **Runtime**: Node.js 20+
+- **Linguaggio**: TypeScript 5.9 — **100% TypeScript** in `src/` e `open-sse/` (v0.9.0)
+- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
+- **Database**: LowDB (JSON) + SQLite (stato dominio + log proxy)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+- **Testing**: Node.js test runner (368+ test unitari)
+- **CI/CD**: GitHub Actions (pubblicazione automatica npm + 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**: Circuit breaker, backoff esponenziale, anti-thundering herd, TLS spoofing
+
+---
+
+## 📖 Documentazione
+
+| Documento                                       | Descrizione                                        |
+| ----------------------------------------------- | -------------------------------------------------- |
+| [Guida Utente](docs/USER_GUIDE.md)              | Provider, combo, integrazione CLI, deploy          |
+| [Riferimento API](docs/API_REFERENCE.md)        | Tutti gli endpoint con esempi                      |
+| [Risoluzione Problemi](docs/TROUBLESHOOTING.md) | Problemi comuni e soluzioni                        |
+| [Architettura](docs/ARCHITECTURE.md)            | Architettura del sistema e dettagli interni        |
+| [Come Contribuire](CONTRIBUTING.md)             | Setup di sviluppo e linee guida                    |
+| [Spec OpenAPI](docs/openapi.yaml)               | Specifica OpenAPI 3.0                              |
+| [Politica di Sicurezza](SECURITY.md)            | Segnalazione vulnerabilità e pratiche di sicurezza |
+
+---
+
+## 📧 Supporto
+
+- **Sito Web**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Progetto Originale**: [9router di decolua](https://github.com/decolua/9router)
+
+---
+
+## 👥 Contributori
+
+[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+
+### Come Contribuire
+
+1. Fai il fork del repository
+2. Crea il tuo branch di funzionalità (`git checkout -b feature/amazing-feature`)
+3. Fai il commit delle modifiche (`git commit -m 'Add amazing feature'`)
+4. Fai il push al branch (`git push origin feature/amazing-feature`)
+5. Apri una Pull Request
+
+Consulta [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida dettagliate.
+
+### Rilasciare una nuova versione
+
+```bash
+# Crea un rilascio — la pubblicazione npm avviene automaticamente
+gh release create v0.9.0 --title "v0.9.0" --generate-notes
+```
+
+---
+
+## 📊 Cronologia Stelle
+
+<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
+ </picture>
+</a>
+
+---
+
+## 🙏 Ringraziamenti
+
+Un ringraziamento speciale a **[9router](https://github.com/decolua/9router)** di **[decolua](https://github.com/decolua)** — il progetto originale che ha ispirato questo fork. OmniRoute si costruisce su quell'incredibile base con funzionalità aggiuntive, API multi-modali e una riscrittura completa in TypeScript.
+
+Un ringraziamento speciale a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — l'implementazione originale in Go che ha ispirato questo porting in JavaScript.
+
+---
+
+## 📄 Licenza
+
+Licenza MIT — vedi [LICENSE](LICENSE) per i dettagli.
+
+---
+
+<div align="center">
+  <sub>Fatto con ❤️ per gli sviluppatori che programmano 24/7</sub>
+  <br/>
+  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
+</div>