OmniRoute/docs/i18n/it/docs/guides/USER_GUIDE.md

User Guide (Italiano)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Lingue: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Guida completa alla configurazione dei provider, alla creazione delle combinazioni, all'integrazione degli strumenti CLI e alla distribuzione di OmniRoute.

---

Indice

• Prezzi in sintesi
• Casi d'uso
• Configurazione dei provider
• Integrazione con la CLI
• Distribuzione
• Modelli disponibili
• Funzionalità avanzate
• Instradamento automatico (senza configurazione)
• Integrazione MCP e A2A
• Sistema delle skill
• Sistema di memoria
• Webhook
• Agenti cloud
• Gestione programmatica
• CLI interna
• Applicazione desktop (Electron)

---

💰 Prezzi in sintesi

Piano	Provider	Costo	Reimpostazione della quota	Ideale per
💳 ABBONAMENTO	Claude Code (Pro)	$20/mese	5 ore + settimanale	Chi ha già un abbonamento
	Codex (Plus/Pro)	$20-200/mese	5 ore + settimanale	Utenti OpenAI
	GitHub Copilot	$10-19/mese	Mensile	Utenti GitHub
🔑 CHIAVE API	DeepSeek	A consumo	Nessuna	Ragionamento economico
	Groq	A consumo	Nessuna	Inferenza ultrarapida
	xAI (Grok)	A consumo	Nessuna	Ragionamento con Grok 4
	Mistral	A consumo	Nessuna	Modelli ospitati nell'UE
	Perplexity	A consumo	Nessuna	Ricerca integrata
	Together AI	A consumo	Nessuna	Modelli open source
	Fireworks AI	A consumo	Nessuna	Immagini FLUX generate rapidamente
	Cerebras	A consumo	Nessuna	Velocità su scala wafer
	Cohere	A consumo	Nessuna	RAG con Command R+
	NVIDIA NIM	A consumo	Nessuna	Modelli aziendali
	Baidu Qianfan	A consumo	Nessuna	Modelli ERNIE
💰 ECONOMICO	GLM-4.7	$0.6/1M	Ogni giorno alle 10:00	Backup economico
	MiniMax M2.1	$0.2/1M	Finestra mobile di 5 ore	Opzione più economica
	Kimi K2	$9/mese fisso	10M token/mese	Costo prevedibile
🆓 GRATUITO	Qoder	$0	Si applicano i limiti del provider	Verifica del catalogo attuale
	Kiro	$0	~50 crediti/mese	Claude gratuito

---

🎯 Casi d'uso

Caso 1: "Ho un abbonamento Claude Pro"

Problema: la quota scade senza essere utilizzata e si raggiungono i limiti di frequenza durante le sessioni di programmazione più intense

Combinazione: "maximize-claude"
  1. cc/claude-opus-4-7        (utilizza completamente l'abbonamento)
  2. glm/glm-4.7               (backup economico quando la quota è esaurita)
  3. if/qwen3.8-max-preview       (fallback gratuito per le emergenze)

Costo mensile: $20 (abbonamento) + ~$5 (backup) = $25 in totale
invece di $20 + il disagio causato dal raggiungimento dei limiti

Caso 2: "Voglio spendere zero"

Problema: non posso permettermi abbonamenti e ho bisogno di un'IA affidabile per la programmazione

Combinazione: "zero-cost"
  1. if/kimi-k2.7-code          (accesso gratuito indicato; potrebbero essere applicati limiti di frequenza)
  2. kr/qwen3-coder-next        (fallback gratuito di Kiro)

Costo mensile: $0
Qualità: verifica il modello, i limiti, la privacy e lo SLA per il tuo carico di lavoro

Caso 3: "Ho bisogno di programmare 24/7, senza interruzioni"

Problema: ho delle scadenze e non posso permettermi tempi di inattività

Combinazione: "always-on"
  1. cc/claude-opus-4-7        (qualità migliore)
  2. cx/gpt-5.5                (secondo abbonamento)
  3. glm/glm-4.7               (economico, si reimposta ogni giorno)
  4. minimax/MiniMax-M2.1      (il più economico, reimpostazione ogni 5 ore)
  5. if/deepseek-v4-flash       (accesso gratuito indicato; potrebbero essere applicati limiti di frequenza)

Risultato: 5 livelli di fallback aumentano la resilienza; la disponibilità dei servizi upstream non è garantita
Costo mensile: $20-200 (abbonamenti) + $10-20 (backup)

Caso 4: "Voglio un'IA GRATUITA in OpenClaw"

Problema: ho bisogno di un assistente IA nelle app di messaggistica, completamente gratuito

Combinazione: "openclaw-free"
  1. if/qwen3.8-max-preview     (accesso gratuito indicato; potrebbero essere applicati limiti di frequenza)
  2. if/deepseek-v4-flash       (accesso gratuito indicato; potrebbero essere applicati limiti di frequenza)
  3. if/kimi-k2.7-code          (accesso gratuito indicato; potrebbero essere applicati limiti di frequenza)

Costo mensile: $0
Accesso tramite: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Configurazione dei provider

Per aggiungere in blocco connessioni con chiave API da un file CSV o JSON, utilizza Dashboard → Provider → Importa da file. Le colonne sono posizionali (provider,name,apiKey,baseUrl,priority); provider deve esistere già come provider gestito o come nodo compatibile. Consulta Importare provider da un file CSV o JSON.

🔐 Provider in abbonamento

Claude Code (Pro/Max)

Dashboard → Provider → Connetti Claude Code
→ Accesso OAuth → Aggiornamento automatico del token
→ Monitoraggio della quota su 5 ore + settimanale

Modelli:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Suggerimento: utilizza Opus per le attività complesse e Sonnet per la velocità. OmniRoute monitora la quota per ciascun modello!

Le route compatibili con Claude e Claude Code mantengono il livello di ragionamento max per i modelli Opus e Sonnet. I modelli Haiku non accettano il livello di ragionamento max, quindi OmniRoute riduce la richiesta a un budget di ragionamento elevato prima di inviarla al provider upstream.

OpenAI Codex (Plus/Pro)

Dashboard → Provider → Connetti Codex
→ Accesso OAuth (porta 1455)
→ Reimpostazione ogni 5 ore + settimanale

Modelli:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

Dashboard → Provider → Connetti GitHub
→ OAuth tramite GitHub
→ Reimpostazione mensile (il 1° del mese)

Modelli:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

💰 Provider economici

GLM-4.7 (Reimpostazione giornaliera, $0.6/1M)

1. Registrati: Zhipu AI
2. Ottieni la chiave API dal Coding Plan
3. Dashboard → Aggiungi chiave API: Provider: glm, Chiave API: your-key

Utilizzo: glm/glm-4.7 — Suggerimento: il Coding Plan offre una quota 3 volte superiore a 1/7 del costo! Reimpostazione giornaliera alle 10:00.

MiniMax M2.1 (Reimpostazione ogni 5 ore, $0.20/1M)

1. Registrati: MiniMax
2. Ottieni la chiave API → Dashboard → Aggiungi chiave API

Utilizzo: minimax/MiniMax-M2.1 — Suggerimento: l'opzione più economica per contesti lunghi (1M token)!

Kimi K2 ($9/mese a tariffa fissa)

1. Abbonati: Moonshot AI
2. Ottieni la chiave API → Dashboard → Aggiungi chiave API

Utilizzo: kimi/kimi-k2.5 — Suggerimento: $9/mese fissi per 10M token = costo effettivo di $0.90/1M!

Baidu Qianfan / ERNIE

1. Registrati: Baidu AI Cloud Qianfan
2. Crea una chiave API Qianfan → Dashboard → Aggiungi chiave API: Provider: qianfan

Utilizzo: qianfan/ernie-5.1, qianfan/ernie-x1.1 o un altro ID modello Qianfan compatibile con OpenAI.

🆓 Provider GRATUITI

I provider gratuiti senza autenticazione dispongono di un interruttore accanto a Nessuna autenticazione richiesta nella relativa pagina del provider. Disattivandolo, il provider viene disabilitato, rimosso dalle visualizzazioni configurata/compatta dei Provider e i relativi modelli vengono rimossi da /v1/models.

Qoder (9 modelli GRATUITI)

Dashboard → Connetti Qoder → Accesso OAuth → L'accesso è soggetto ai limiti attuali del provider

Modelli: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude GRATUITO)

Dashboard → Connetti Kiro → AWS Builder ID o Google/GitHub → ~50 crediti/mese

Modelli: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

---

🎨 Combinazioni

Puoi riordinare le schede delle combinazioni direttamente in Dashboard → Combinazioni trascinando la maniglia presente su ciascuna scheda. L'ordine viene memorizzato in SQLite e ripristinato al ricaricamento.

Esempio 1: Massimizzare l'abbonamento → Backup economico

Dashboard → Combinazioni → Crea nuova

Nome: premium-coding
Modelli:
  1. cc/claude-opus-4-7 (Abbonamento principale)
  2. glm/glm-4.7 (Backup economico, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Fallback più economico, $0.3/1M)

Utilizzo nella CLI: premium-coding

Esempio 2: Solo gratuiti (costo zero)

Nome: free-combo
Modelli:
  1. if/kimi-k2.7-code (accesso gratuito indicato; potrebbero applicarsi limiti del provider)
  2. kr/qwen3-coder-next (Fallback gratuito di Kiro)

Costo: attualmente indicato come $0; termini e disponibilità possono cambiare

---

🔧 Integrazione con la CLI

Cursor IDE

Utilizzo di Cursor come client OmniRoute (instrada la chat di Cursor tramite OmniRoute):

Impostazioni → Modelli → Avanzate:
  URL di base API OpenAI: http://localhost:20128/v1
  Chiave API OpenAI: [dalla dashboard di OmniRoute]
  Modello: cc/claude-opus-4-7

Utilizzo di OmniRoute come provider Cursor (OmniRoute chiama Cursor a monte): preferisci Dashboard → Provider → Cursor → Accedi con Cursor. In Docker, consulta docs/providers/CURSOR-DOCKER.md.

Claude Code

Modifica ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

Utilizza qui l'endpoint radice compatibile con Claude. Non aggiungere /v1 a ANTHROPIC_BASE_URL.

Codex CLI

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

OpenClaw

Modifica ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

Oppure utilizza la Dashboard: Strumenti CLI → OpenClaw → Configurazione automatica

Cline / Continue / RooCode

Provider: compatibile con OpenAI
URL di base: http://localhost:20128/v1
Chiave API: [dalla dashboard]
Modello: cc/claude-opus-4-7

---

🚀 Distribuzione

Installazione globale tramite npm (consigliata)

npm install -g omniroute

# Crea la directory di configurazione
mkdir -p ~/.omniroute

# Crea il file .env (consulta .env.example)
cp .env.example ~/.omniroute/.env

# Avvia il server
omniroute
# Oppure con una porta personalizzata:
omniroute --port 3000

La CLI carica automaticamente .env da ~/.omniroute/.env o ./.env.

Modalità area di notifica

Avvia OmniRoute nell'area di notifica del sistema:

omniroute serve --tray

Il comando termina dopo che il server e l'icona nell'area di notifica sono pronti.

Il server continua a funzionare senza il terminale.

La modalità area di notifica supporta macOS, Windows e le sessioni Linux grafiche. La modalità area di notifica non apre automaticamente la dashboard.

Utilizza il menu dell'area di notifica per queste azioni:

• Aprire la dashboard.
• Aprire /dashboard/logs.
• Modificare l'avvio automatico.
• Arrestare OmniRoute.

Non combinare --tray con queste opzioni:

• --daemon
• --log
• --no-recovery

Queste modalità richiedono una gestione distinta dei processi.

Abilita l'avvio al successivo accesso al computer:

omniroute autostart enable

L'avvio automatico utilizza la modalità area di notifica su macOS, Windows e nelle sessioni Linux grafiche. Linux headless utilizza il servizio utente systemd esistente.

Disabilita l'avvio all'accesso:

omniroute autostart disable

Disinstallazione

Quando OmniRoute non ti serve più, mettiamo a disposizione due script rapidi per una rimozione pulita:

Comando	Azione
npm run uninstall	Rimuove l'applicazione di sistema, ma mantiene il DB e le configurazioni in ~/.omniroute.
npm run uninstall:full	Rimuove l'applicazione E cancella definitivamente tutte le configurazioni, le chiavi e i database.

Nota: per eseguire questi comandi, accedi alla cartella del progetto OmniRoute (se lo hai clonato) ed eseguili. In alternativa, se è installato globalmente, puoi semplicemente eseguire npm uninstall -g omniroute.

Distribuzione su VPS

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Oppure: pm2 start npm --name omniroute -- start

Distribuzione con PM2 (memoria ridotta)

Per i server con RAM limitata, utilizza l'opzione per il limite di memoria:

# Con un limite di 512MB (valore predefinito)
pm2 start npm --name omniroute -- start

# Oppure con un limite di memoria personalizzato
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Oppure utilizzando ecosystem.config.js
pm2 start ecosystem.config.js

Crea ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# Crea l'immagine (impostazione predefinita = runner-cli con codex/claude/droid preinstallati)
docker build -t omniroute:cli .

# Modalità portabile (consigliata)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Per la modalità integrata con l'host e i binari CLI, consulta la sezione Docker nella documentazione principale.

Void Linux (xbps-src)

Gli utenti di Void Linux possono creare e installare un pacchetto nativo di OmniRoute utilizzando il framework di compilazione incrociata xbps-src. Questo automatizza la build standalone di Node.js insieme ai binding nativi richiesti da better-sqlite3.

Visualizza il template xbps-src

# File template per 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Gateway AI universale con instradamento intelligente per più provider LLM"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Determina l'architettura CPU di destinazione per node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Installa tutte le dipendenze – ignora gli script
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Crea il bundle standalone di Next.js
	npm run build

	# 3) Copia le risorse statiche nel bundle standalone
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Compila il binding nativo di better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Inserisce il binding compilato nel bundle standalone
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Rimuove i bundle di sharp specifici per l'architettura
	rm -rf .next/standalone/node_modules/@img

	# 7) Copia le dipendenze di runtime di pino omesse dall'analisi statica di Next.js:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

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

	# Impedisce che le directory vuote del router dell'app Next.js vengano rimosse dall'hook post-installazione
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

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

post_install() {
	vlicense LICENSE
}

Variabili d'ambiente

Variabile	Valore predefinito	Descrizione
JWT_SECRET	omniroute-default-secret-change-me	Segreto per la firma JWT (da modificare in produzione)
INITIAL_PASSWORD	CHANGEME	Password per il primo accesso
DATA_DIR	~/.omniroute	Directory dei dati (database, utilizzo, log)
PORT	valore predefinito del framework	Porta del servizio (20128 negli esempi)
HOSTNAME	valore predefinito del framework	Host di binding (per Docker il valore predefinito è 0.0.0.0)
NODE_ENV	valore predefinito del runtime	Impostare su production per la distribuzione
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL di base pubblico mostrato nella dashboard ed esposto al server (sostituisce il precedente BASE_URL)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	URL di base dell'endpoint di sincronizzazione cloud (sostituisce il precedente CLOUD_URL)
API_KEY_SECRET	endpoint-proxy-api-key-secret	Segreto HMAC per le chiavi API generate
REQUIRE_API_KEY	false	Impone l'uso di una chiave API Bearer su /v1/*
ALLOW_API_KEY_REVEAL	false	Consente agli utenti autenticati della dashboard di visualizzare su richiesta i valori completi delle chiavi API memorizzate
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Frequenza di aggiornamento lato server dei dati memorizzati nella cache di Provider Limits; i pulsanti dell'interfaccia continuano ad attivare la sincronizzazione manuale
DISABLE_SQLITE_AUTO_BACKUP	false	Disabilita gli snapshot SQLite automatici prima di scrittura/importazione/ripristino; i backup manuali continuano a funzionare
APP_LOG_TO_FILE	true	Abilita la scrittura su disco dei log dell'applicazione e di audit
AUTH_COOKIE_SECURE	false	Forza il cookie di autenticazione Secure (dietro un reverse proxy HTTPS)
CLOUDFLARED_BIN	non impostato	Usa un binario cloudflared esistente invece del download gestito
CLOUDFLARED_PROTOCOL	http2	Trasporto per i Quick Tunnel gestiti (http2, quic o auto)
OMNIROUTE_MEMORY_MB	512	Limite dell'heap di Node.js in MB
PROMPT_CACHE_MAX_SIZE	50	Numero massimo di voci nella cache dei prompt
SEMANTIC_CACHE_MAX_SIZE	100	Numero massimo di voci nella cache semantica

Per il riferimento completo delle variabili d'ambiente, consultare il README.

---

📊 Modelli disponibili

Visualizza tutti i modelli disponibili

L'elenco seguente è stato selezionato da open-sse/config/providerRegistry.ts per la versione v3.8.0. I cataloghi cloud (Gemini, OpenRouter, ecc.) vengono sincronizzati dinamicamente — per il catalogo completo aggiornato, apri Dashboard → Providers → [provider] → Available Models oppure chiama GET /api/models/catalog.

Se l'elenco integrato di un provider non è più aggiornato, usa Import from /models in quella pagina (oppure abilita Auto-Sync) per recuperare il catalogo aggiornato dal servizio upstream. Questa funzionalità è stata verificata nella versione v3.8.50 per LLM7.io (gemini-3.1-flash-lite) e UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); durante la stessa sessione di test, l'accesso anonimo a Pollinations è rimasto soggetto alle limitazioni del servizio upstream.

Claude Code (cc/) — OAuth Pro/Max: cc/claude-opus-4-8, cc/claude-opus-4-7, cc/claude-opus-4-6, cc/claude-opus-4-5-20251101, cc/claude-sonnet-4-6, cc/claude-sonnet-4-5-20250929, cc/claude-haiku-4-5-20251001

Codex (cx/) — OAuth Plus/Pro: cx/gpt-5.5 (+ livelli di elaborazione: gpt-5.5-xhigh, gpt-5.5-high, gpt-5.5-medium, gpt-5.5-low), cx/gpt-5.4, cx/gpt-5.4-mini, cx/gpt-5.3-codex, cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — OAuth: gh/gpt-5.5, gh/gpt-5.4, gh/gpt-5.4-mini, gh/gpt-5-mini, gh/gpt-5.3-codex, gh/claude-opus-4.7, gh/claude-opus-4.6, gh/claude-opus-4-5-20251101, gh/claude-sonnet-4.6, gh/claude-sonnet-4.5, gh/claude-haiku-4.5, gh/gemini-3.1-pro-preview, gh/gemini-3-flash-preview, gh/oswe-vscode-prime

Kiro (kr/) — OAuth GRATUITO: usa il catalogo aggiornato mostrato in Dashboard → Providers → Kiro → Available Models. La disponibilità dipende dall'account e dal piano.

Qoder (if/) — OAuth GRATUITO: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — $0.2–0.6/1M: glm/glm-5.1, glm/glm-5, glm/glm-5-turbo, glm/glm-4.7, glm/glm-4.7-flash, glm/glm-4.6, glm/glm-4.6v, glm/glm-4.5, glm/glm-4.5v, glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — $0.2/1M: minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed, minimax/MiniMax-M2.5, minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — $9/mese a tariffa fissa oppure a consumo: kimi/kimi-k2.6, kimi/kimi-k2.5

DeepSeek (ds/) — Chiave API: ds/deepseek-v4-pro, ds/deepseek-v4-flash

Groq (groq/) — Ultraveloce: groq/llama-3.3-70b-versatile, groq/meta-llama/llama-4-maverick-17b-128e-instruct, groq/qwen/qwen3-32b, groq/openai/gpt-oss-120b

xAI (xai/) — Grok nativo: xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — Ospitato nell'UE: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Potenziato dalla ricerca: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Open source: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (gratuito), together/meta-llama/Llama-Vision-Free, together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free, together/deepseek-ai/DeepSeek-R1, together/Qwen/Qwen3-235B-A22B, together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — Inferenza rapida: fireworks/accounts/fireworks/models/kimi-k2p6, fireworks/accounts/fireworks/models/minimax-m2p7, fireworks/accounts/fireworks/models/qwen3p6-plus, fireworks/accounts/fireworks/models/glm-5p1, fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — Su scala wafer: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — Incentrato sulla RAG: cohere/command-a-reasoning-08-2025, cohere/command-a-vision-07-2025, cohere/command-a-03-2025, cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — Aziendale: nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1, qianfan/ernie-5.0-thinking-latest, qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro, ollama-cloud/deepseek-v4-flash, ollama-cloud/kimi-k2.6, ollama-cloud/glm-5.1, ollama-cloud/minimax-m2.7, ollama-cloud/gemma4:31b, ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/): sincronizzato in tempo reale da Google per ogni chiave API — nessun elenco statico. Collega una chiave in Dashboard → Providers, quindi usa Available Models per importare il catalogo corrente (ad es. gemini/gemini-3-pro, gemini/gemini-3-flash).

Altri provider compatibili (selezione): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (tramite aws-bedrock), azure-ai, openrouter (catalogo passthrough), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Ciascuno mantiene il proprio elenco di modelli in providerRegistry.ts e può essere sincronizzato automaticamente quando il provider espone un endpoint /models.

Nota sugli ID dei modelli: OmniRoute utilizza gli ID nativi dei provider (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). Alcuni ID includono versioni con punti perché è il formato previsto dall'API upstream. Se un modello non è elencato sopra, esegui omniroute models --search <term> oppure interroga GET /api/models/catalog per verificarne la disponibilità.

---

🧩 Funzionalità avanzate

Modelli personalizzati

Aggiungi qualsiasi ID modello a qualsiasi provider senza attendere un aggiornamento dell'app:

# Tramite API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# Elenco: curl http://localhost:20128/api/provider-models?provider=openai
# Rimozione: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

Oppure usa la Dashboard: Provider → [Provider] → Modelli personalizzati.

Note:

• OpenRouter e i provider compatibili con OpenAI/Anthropic vengono gestiti esclusivamente da Modelli disponibili. L'aggiunta manuale, l'importazione e la sincronizzazione automatica confluiscono tutti nello stesso elenco di modelli disponibili, quindi per questi provider non esiste una sezione separata dedicata ai Modelli personalizzati.
• La sezione Modelli personalizzati è destinata ai provider che non offrono importazioni gestite dei modelli disponibili.

Concatenamento di peer OmniRoute

Un altro gateway OmniRoute può essere aggiunto come provider personalizzato compatibile con OpenAI. Usa l'URL di base /v1 del peer e una chiave API dedicata, con privilegi minimi, emessa da tale peer.

Per catene reciproche o multi-hop, abilita la protezione dai loop facoltativa su ogni gateway:

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

Solo le richieste inviate a un URL peer esplicitamente incluso nell'elenco consentito ricevono l'header X-OmniRoute-Peer-Trace. Un gateway rifiuta un ID istanza ripetuto o un limite di hop esaurito con HTTP 508 Loop Detected; i normali provider upstream non ricevono metadati sui peer.

Il concatenamento dei peer non equivale alla replica del database o al failover dell'host. Ogni gateway mantiene stati SQLite, cache, contatori dei limiti di frequenza e sessioni indipendenti. Usa un reverse proxy con controlli di integrità o il failover lato client per la disponibilità attiva/passiva o attiva/attiva e non montare mai un singolo database SQLite in più istanze OmniRoute in esecuzione.

Route dedicate ai provider

Instrada le richieste direttamente verso un provider specifico con convalida del modello:

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

Il prefisso del provider viene aggiunto automaticamente se manca. I modelli non corrispondenti restituiscono 400.

Configurazione del proxy di rete

# Imposta il proxy globale
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Proxy per provider
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Verifica il proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

Precedenza: Specifico per chiave → Specifico per combinazione → Specifico per provider → Globale → Ambiente.

API del catalogo dei modelli

curl http://localhost:20128/api/models/catalog

Restituisce i modelli raggruppati per provider con i relativi tipi (chat, embedding, image).

Sincronizzazione cloud

• Sincronizza provider, combinazioni e impostazioni tra dispositivi
• Sincronizzazione automatica in background con timeout e interruzione rapida
• In produzione, prediligi NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL lato server

Cloudflare Quick Tunnel

• Disponibile in Dashboard → Endpoint per Docker e altre distribuzioni self-hosted
• Crea un URL temporaneo https://*.trycloudflare.com che inoltra le richieste all'endpoint /v1 compatibile con OpenAI corrente
• Alla prima attivazione installa cloudflared solo quando necessario; i riavvii successivi riutilizzano lo stesso binario gestito
• I Quick Tunnel non vengono ripristinati automaticamente dopo il riavvio di OmniRoute o del container; riabilitali dalla dashboard quando necessario
• Gli URL dei tunnel sono temporanei e cambiano ogni volta che arresti o avvii il tunnel
• I Quick Tunnel gestiti usano per impostazione predefinita il trasporto HTTP/2, per evitare avvisi rumorosi relativi al buffer UDP di QUIC nei container con risorse limitate
• Imposta CLOUDFLARED_PROTOCOL=quic o auto se desideri sostituire la scelta del trasporto gestito
• Imposta CLOUDFLARED_BIN se preferisci usare un binario cloudflared preinstallato anziché il download gestito
• I pannelli Cloudflare Quick Tunnel, Tailscale Funnel e ngrok Tunnel possono essere mostrati o nascosti in Impostazioni → Aspetto. Nascondere un pannello non arresta un tunnel in esecuzione.

Funzionalità intelligenti del gateway LLM (Fase 9)

• Cache semantica — Memorizza automaticamente nella cache le risposte non in streaming con temperature=0 (ignorabile con X-OmniRoute-No-Cache: true)
• Idempotenza delle richieste — Deduplica le richieste entro 5 secondi tramite l'header Idempotency-Key o X-Request-Id
• Monitoraggio dell'avanzamento — Eventi SSE event: progress facoltativi tramite l'header X-OmniRoute-Progress: true

---

Playground del traduttore

Accedi tramite Dashboard → Traduttore. Esegui il debug e visualizza come OmniRoute traduce le richieste API tra provider.

Modalità	Scopo
Playground	Seleziona i formati di origine/destinazione, incolla una richiesta e visualizza immediatamente l'output tradotto
Tester chat	Invia messaggi di chat in tempo reale tramite il proxy e analizza l'intero ciclo di richiesta/risposta
Banco di prova	Esegui test in batch su più combinazioni di formati per verificare la correttezza della traduzione
Monitoraggio in tempo reale	Osserva le traduzioni in tempo reale mentre le richieste attraversano il proxy

Casi d'uso:

• Eseguire il debug del motivo per cui una specifica combinazione client/provider non funziona
• Verificare che i tag di ragionamento, le chiamate agli strumenti e i prompt di sistema vengano tradotti correttamente
• Confrontare le differenze di formato tra i formati OpenAI, Claude, Gemini e Responses API

---

Strategie di routing

Configura tramite Dashboard → Settings → Routing. La dashboard espone le sei strategie più utilizzate; le combo e l'auto-router supportano internamente un insieme più ampio.

Strategie visibili nella dashboard (routing a livello di account):

Strategia	Descrizione
Riempi il primo	Utilizza gli account in ordine di priorità: l'account principale gestisce tutte le richieste finché disponibile
Round Robin	Alterna ciclicamente tutti gli account con un limite di persistenza configurabile (predefinito: 3 chiamate per account)
P2C (Power of Two Choices)	Sceglie 2 account casuali e instrada verso quello più affidabile, bilanciando il carico in base allo stato di integrità
Casuale	Seleziona casualmente un account per ogni richiesta utilizzando l'algoritmo di mescolamento Fisher-Yates
Meno utilizzato	Instrada verso l'account con il timestamp lastUsedAt meno recente, distribuendo il traffico uniformemente
Ottimizzazione dei costi	Instrada verso l'account con il valore di priorità più basso, ottimizzando l'uso dei provider meno costosi

Strategie avanzate per combo e auto-routing (configurabili per ciascuna combo o tramite i prefissi auto/* — consulta AUTO-COMBO.md):

• priority — ordine rigoroso, senza mai applicare il round-robin
• weighted — suddivisione proporzionale del traffico in base ai pesi per modello
• fill-first — utilizza il primo modello fino al raggiungimento dei limiti
• round-robin / strict-random / random
• p2c (Power of Two Choices)
• least-used e cost-optimized
• auto — selezione basata sul punteggio tra tutti i candidati
• lkgp (Last Known Good Provider) — mantiene l'ultimo provider che ha risposto correttamente, quindi ricorre alle regole
• context-optimized — sceglie il modello con la finestra di contesto libera più ampia
• context-relay — concatena modelli con contesto esteso per i turni successivi

Header esterno per sessioni persistenti

Per l'affinità di sessione esterna (ad esempio, agenti Claude Code/Codex dietro reverse proxy), invia:

X-Session-Id: your-session-key

OmniRoute accetta anche x_session_id e restituisce la chiave di sessione effettiva in X-OmniRoute-Session-Id.

Se utilizzi Nginx e invii header contenenti caratteri di sottolineatura, abilita:

underscores_in_headers on;

Alias di modelli con caratteri jolly

Crea pattern con caratteri jolly per rimappare i nomi dei modelli:

Pattern: claude-sonnet-*     →  Destinazione: cc/claude-sonnet-4-6
Pattern: gpt-*               →  Destinazione: gh/gpt-5.3-codex

I caratteri jolly supportano * (qualsiasi sequenza di caratteri) e ? (un singolo carattere).

Catene di fallback

Definisci catene di fallback globali da applicare a tutte le richieste:

Catena: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

---

Resilienza e circuit breaker

Configura tramite Dashboard → Settings → Resilience.

OmniRoute implementa la resilienza a livello di provider mediante cinque componenti:

1. Coda e regolazione delle richieste — Gestione delle richieste a livello di sistema:

   • Richieste al minuto (RPM) — Numero massimo di richieste al minuto per account
   • Tempo minimo tra le richieste — Intervallo minimo in millisecondi tra le richieste
   • Numero massimo di richieste simultanee — Numero massimo di richieste simultanee per account

2. Cooldown della connessione — Configurazione per tipo di autenticazione relativa a una singola connessione dopo errori che consentono un nuovo tentativo:

   • Cooldown di base — Intervallo di cooldown predefinito per gli errori upstream che consentono un nuovo tentativo
   • Utilizza le indicazioni di nuovo tentativo dell'upstream — Rispetta le indicazioni autorevoli Retry-After o di reset, se fornite
   • Numero massimo di passaggi di backoff — Livello massimo di backoff esponenziale per errori ripetuti

3. Circuit breaker del provider — Monitora gli errori end-to-end del provider, contrassegna un provider come degradato al raggiungimento della soglia di avviso configurata e apre il circuit breaker quando viene raggiunta la soglia di errore configurata:

   • Soglia di degradazione — Numero di errori consecutivi del provider prima di entrare nello stato DEGRADED
   • Soglia di errore — Numero di errori consecutivi del provider prima di entrare nello stato OPEN
   • Timeout di reset — Intervallo di tempo prima che il provider venga testato nuovamente
   • CLOSED (Integro) — Le richieste vengono elaborate normalmente
   • DEGRADED — Le richieste continuano a essere elaborate mentre vengono monitorati gli errori più frequenti
   • OPEN — Il provider viene temporaneamente bloccato dopo errori ripetuti
   • HALF_OPEN — Verifica se il provider è stato ripristinato

   I limiti di frequenza 429 relativi alla connessione rimangono nel Cooldown della connessione e non vengono conteggiati dal circuit breaker del provider.

   Lo stato di runtime del circuit breaker del provider viene visualizzato solo in Dashboard → Health.

4. Attendi il cooldown — Se tutte le connessioni candidate sono già in cooldown, OmniRoute può attendere la scadenza del primo cooldown e riprovare automaticamente la stessa richiesta del client.

5. Rilevamento automatico dei limiti di frequenza — Quando i provider upstream restituiscono intervalli di attesa espliciti, tali indicazioni sostituiscono il cooldown locale della connessione, se l'impostazione è abilitata.

Suggerimento: utilizza la pagina Health per esaminare e reimpostare i circuit breaker attivi dei provider dopo un'interruzione. La pagina Resilience modifica solo la configurazione.

---

Esportazione/importazione del database

Gestisci i backup del database in Dashboard → Settings → System & Storage.

Azione	Descrizione
Esporta database	Scarica il database SQLite corrente come file .sqlite
Esporta tutto (.tar.gz)	Scarica un archivio di backup completo che include: database, impostazioni, combo, connessioni ai provider (senza credenziali), metadati delle chiavi API
Importa database	Carica un file .sqlite per sostituire il database corrente. Viene creato automaticamente un backup prima dell'importazione, a meno che DISABLE_SQLITE_AUTO_BACKUP=true

# API: esporta il database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: esporta tutto (archivio completo)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: importa il database
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

Convalida dell'importazione: L'integrità del file importato viene verificata (controllo pragma di SQLite), insieme alla presenza delle tabelle richieste (provider_connections, provider_nodes, combos, api_keys) e alle dimensioni (massimo 100 MB).

Casi d'uso:

• Migrare OmniRoute tra macchine
• Creare backup esterni per il ripristino di emergenza
• Condividere le configurazioni tra i membri del team (esporta tutto → condividi l'archivio)

---

Dashboard delle impostazioni

La pagina delle impostazioni è organizzata in 7 schede per facilitare la navigazione:

Scheda	Contenuti
Generale	Strumenti di archiviazione del sistema, comportamento predefinito, visibilità dei tunnel degli endpoint
Aspetto	Controlli del tema (chiaro/scuro/sistema), visibilità della barra laterale, opzioni dei pannelli per le schede dei tunnel Cloudflare/Tailscale/ngrok
IA	Budget di ragionamento (inoltro invariato / rimozione automatica / personalizzato / adattivo — consulta THINKING_BUDGET.md), prompt di sistema globale, statistiche della cache dei prompt
Sicurezza	Impostazioni di accesso/password, controllo degli accessi IP, autenticazione API per /models, blocco dei provider, protezione dalle prompt injection
Instradamento	Strategia di instradamento globale (riempi prima / round robin / P2C / casuale / meno usato / ottimizzato per i costi), alias dei modelli con caratteri jolly, catene di fallback, valori predefiniti delle combo
Resilienza	Coda delle richieste, tempo di attesa delle connessioni, configurazione del circuit breaker dei provider e comportamento di attesa del cooldown
Avanzate	Configurazione globale del proxy (HTTP/SOCKS5), sostituzioni del proxy per singolo provider

La scheda Generale non duplica più le note di sola lettura relative alla registrazione e alla cache. Le impostazioni di conservazione e ottimizzazione del database vengono mantenute tramite /api/settings/database; la cancellazione manuale della cache utilizza DELETE /api/cache. I limiti delle righe dei registri delle chiamate e del proxy sono controllati da CALL_LOGS_TABLE_MAX_ROWS e PROXY_LOGS_TABLE_MAX_ROWS.

---

Gestione dei costi e del budget

Accessibile tramite Dashboard → Costi.

Scheda	Scopo
Budget	Imposta limiti di spesa per ogni chiave API con budget giornalieri/settimanali/mensili e monitoraggio in tempo reale
Prezzi	Visualizza e modifica le voci dei prezzi dei modelli — costo per 1.000 token di input/output per provider

# API: imposta un budget
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: ottieni lo stato attuale del budget
curl http://localhost:20128/api/usage/budget

Monitoraggio dei costi: Ogni richiesta registra l'utilizzo dei token e calcola il costo utilizzando la tabella dei prezzi. Visualizza i dettagli in Dashboard → Utilizzo per provider, modello e chiave API.

---

Trascrizione audio

OmniRoute supporta la trascrizione audio tramite l'endpoint compatibile con OpenAI:

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# Esempio con curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

deepgram/nova-3 è la route nativa di Deepgram e richiede una chiave API Deepgram. Se è configurato solo OpenRouter, utilizza openrouter/deepgram/nova-3.

Provider per la conversione da voce a testo (trascrizione):

• openai/ (compatibile con Whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (famiglia Nova)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (varianti di Whisper)
• qwen/

Provider per la conversione da testo a voce (POST /v1/audio/speech):

• openai/ (tts-1, tts-1-hd)
• hyperbolic/
• deepgram/ (Aura)
• nvidia/ (Magpie TTS)
• elevenlabs/
• huggingface/
• inworld/
• cartesia/
• playht/
• kie/
• aws-polly/
• xiaomi-mimo/
• coqui/, tortoise/
• qwen/

Formati audio supportati per la trascrizione: mp3, wav, m4a, flac, ogg, webm. I formati di output TTS dipendono dal provider (mp3, wav, opus, pcm, mulaw).

---

Strategie di bilanciamento delle combo

Configura il bilanciamento per ogni combo in Dashboard → Combo → Crea/Modifica → Strategia.

Strategia	Descrizione
Round-Robin	Ruota sequenzialmente tra i modelli
Priorità	Prova sempre il primo modello; passa a quello successivo solo in caso di errore
Casuale	Seleziona un modello casuale dalla combinazione per ogni richiesta
Ponderata	Instrada proporzionalmente in base ai pesi assegnati a ciascun modello
Meno utilizzato	Instrada verso il modello con il minor numero di richieste recenti (usa le metriche della combinazione)
Ottimizzata per i costi	Instrada verso il modello disponibile più economico (usa la tabella dei prezzi)

Le impostazioni predefinite globali delle combinazioni possono essere configurate in Dashboard → Settings → Routing → Combo Defaults. Per impostazione predefinita, i timeout delle destinazioni della combinazione ereditano il timeout della richiesta corrente. Usa Target timeout (seconds) nelle impostazioni predefinite delle combinazioni o in una singola combinazione solo quando un limite più breve per ciascuna destinazione deve attivare più rapidamente il passaggio alla destinazione successiva.

Le ottimizzazioni delle combinazioni a latenza zero sono facoltative. Lascia Zero-latency optimizations disabilitato per evitare che queste funzionalità di latenza mettano in competizione le destinazioni di fallback, ignorino destinazioni in base alla cronologia TTFT o comprimano le richieste di fallback; abilitarlo consente l'hedging configurato, i salti predittivi basati sul TTFT e la compressione proattiva del fallback, sacrificando la fedeltà dell'instradamento e delle richieste in favore di una minore latenza di coda.

Disabilita Reasoning token buffer quando i provider upstream richiedono limiti max_tokens / maxOutputTokens rigorosi. Quando è abilitato, l'instradamento delle combinazioni aggiunge margine per i modelli di ragionamento solo ai modelli con un limite di output noto e lascia invariato il limite di token del client quando il valore sicuro con buffer supererebbe tale limite. Se il limite del client è già superiore a un limite noto, OmniRoute lo riduce a tale limite prima di inviare la richiesta upstream.

---

Dashboard di integrità

Accessibile tramite Dashboard → Health. Panoramica in tempo reale dell'integrità del sistema con 6 schede:

Scheda	Cosa mostra
Stato del sistema	Tempo di attività, versione, utilizzo della memoria, directory dei dati
Integrità dei provider	Stato di runtime globale del circuit breaker dei provider
Limiti di frequenza	Cooldown delle connessioni attive per account con tempo rimanente
Blocchi attivi	Blocchi attivi specifici per modello ed esclusioni temporanee
Cache delle firme	Statistiche della cache di deduplicazione (chiavi attive, percentuale di hit)
Telemetria della latenza	Aggregazione della latenza p50/p95/p99 per provider

Suggerimento: la pagina Health si aggiorna automaticamente ogni 10 secondi. Usa la scheda del circuit breaker per identificare i provider che stanno riscontrando problemi.

---

🤖 Instradamento automatico (configurazione zero)

OmniRoute include un router automatico basato su punteggi che seleziona il modello migliore per ogni richiesta tra tutti i provider connessi, senza alcuna combinazione da gestire. Basta inviare la richiesta con uno dei prefissi auto/* e OmniRoute creerà al volo una combinazione virtuale, assegnando punteggi ai candidati in base a latenza, costo, tasso di successo, compatibilità con il contesto, idoneità del modello per l'attività, errori recenti, quota e stato del circuit breaker.

Prefisso	Ottimizza per
auto	Impostazione predefinita bilanciata (latenza × costo × tasso di successo)
auto/coding	Attività di programmazione: preferisce Claude, GPT-5, GLM, Kimi, Qwen Coder e i modelli di programmazione DeepSeek
auto/cheap	Costo per token più basso, accetta una latenza maggiore
auto/fast	Latenza più bassa, ignora il costo
auto/offline	Solo provider locali (Ollama, vLLM, llama.cpp), utile per configurazioni isolate dalla rete
auto/smart	Priorità alla qualità del ragionamento (Opus, GPT-5 xhigh, R1, ragionamento GLM 5.1)
auto/lkgp	"Ultimo provider noto funzionante": mantiene l'ultimo provider che ha avuto successo, quindi ricorre alle regole

Esempio:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Esegui il refactoring di questa funzione Python" }],
    "stream": true
  }'

Il router automatico è descritto in dettaglio in AUTO-COMBO.md, incluse le modalità per regolare i pesi dei punteggi, aggiungere provider alla lista nera e ispezionare le decisioni di instradamento in Dashboard → Auto Combo.

---

🔌 Integrazione MCP e A2A

OmniRoute è sia un server MCP (Model Context Protocol) sia un server A2A (JSON-RPC 2.0 da agente ad agente). Qualsiasi IDE o host per agenti compatibile con MCP può chiamare direttamente gli strumenti di OmniRoute, senza richiedere wrapper aggiuntivi.

Trasporti MCP

• SSE: http://localhost:20128/api/mcp/sse
• HTTP con streaming: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (per i plugin IDE che preferiscono stdio)

Connettere Claude Desktop

Modificare ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o il file equivalente su Windows/Linux:

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

Connettere Cursor / Continue / VS Code MCP

Utilizzare l'URL SSE http://localhost:20128/api/mcp/sse e una chiave API Bearer generata in Dashboard → API Keys.

Ambiti

MCP definisce attualmente 32 ambiti denominati. Ogni chiave Bearer può essere limitata ad ambiti specifici; consultare MCP-SERVER.md per l'elenco ufficiale degli ambiti e degli strumenti e A2A-SERVER.md per lo schema JSON-RPC.

---

🧠 Sistema di skill

OmniRoute offre un framework di skill estensibile (src/lib/skills/) che consente agli agenti e all'endpoint A2A di eseguire routine specifiche per dominio (ad es. code-review, summarize, extract-facts, web-research).

• Interfaccia del marketplace — Sfoglia e installa le skill da Dashboard → Skills
• Ambiti per chiave — Limita le skill che ciascuna chiave API può richiamare
• Skill personalizzate — Inserisci un file TypeScript in src/lib/a2a/skills/, registralo e diventerà immediatamente richiamabile tramite A2A

Documentazione completa: SKILLS.md.

---

💾 Sistema di memoria

OmniRoute conserva una memoria conversazionale a lungo termine con recupero ibrido:

• SQLite FTS5 per la ricerca per parole chiave nelle interazioni passate
• Archivio vettoriale Qdrant (opzionale) per il recupero semantico
• Estrazione automatica dei fatti — entità, preferenze e decisioni vengono riepilogate dopo ogni sessione e archiviate nella tabella memory_facts
• Le memorie sono isolate per chiave API e per sessione

Gestisci le memorie da Dashboard → Memory (ricerca, modifica, esportazione, eliminazione). L'interfaccia HTTP (/api/memory/*) consente agli agenti di inviare e interrogare i fatti a livello di codice — consulta MEMORY.md.

---

🔔 Webhook

Sottoscrivi gli eventi di OmniRoute per il monitoraggio e l'automazione in tempo reale.

• Crea un webhook in Dashboard → Webhooks specificando l'URL di destinazione e il segreto di firma HMAC
• Eventi disponibili: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
• Ogni payload include X-OmniRoute-Signature (HMAC-SHA256) per la verifica
• Tentativi: 3 tentativi con backoff esponenziale, quindi inserimento nella coda dei messaggi non recapitabili

Schema completo in WEBHOOKS.md.

---

☁️ Agenti cloud

OmniRoute si integra con agenti di programmazione cloud (OpenAI Codex Cloud, Devin, Jules, Antigravity), consentendoti di assegnare attività di lunga durata dalla stessa dashboard utilizzata per gestire l'instradamento locale.

• Crea attività in Dashboard → Cloud Agents o tramite POST /api/v1/agents/tasks
• Monitora stato, log e artefatti per ciascuna attività
• Usa la tua chiave API per ogni provider — le credenziali non lasciano mai l'istanza OmniRoute

Documentazione completa: CLOUD_AGENT.md.

---

🛠️ Gestione programmatica

Puoi gestire tutte le risorse di OmniRoute (provider, combinazioni, chiavi, impostazioni) tramite HTTP utilizzando una chiave Bearer con l'ambito manage.

Genera la chiave in Dashboard → API Keys → New Key → Scope: manage, quindi:

# Elenca i provider
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Aggiungi una connessione a un provider
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# Crea una combinazione
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# Elenca/crea chiavi API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

Consulta API_REFERENCE.md per il catalogo completo degli endpoint e gli schemi di richiesta/risposta.

---

💻 CLI interna

OmniRoute include una CLI interna (omniroute …) per la configurazione, la diagnostica e il controllo in fase di esecuzione. Questa è separata dalla pagina "Strumenti CLI" della dashboard, che configura CLI di terze parti (Claude Code, Cursor, Codex, Cline, …) affinché possano comunicare con OmniRoute.

omniroute setup                    # Procedura guidata interattiva (password, provider, combinazioni)
omniroute setup --non-interactive  # Adatto alla CI
omniroute doctor                   # Diagnostica dello stato (directory dati, DB, provider, porte)
omniroute providers available      # Elenca i provider supportati
omniroute providers list           # Elenca le connessioni configurate
omniroute providers test <id>      # Testa in tempo reale una connessione a un provider
omniroute combos list              # Elenca le combinazioni
omniroute combos switch <name>     # Imposta la combinazione predefinita
omniroute models                   # Elenca i modelli disponibili (--json, --search)
omniroute keys add | list | remove # Gestisce le chiavi API dal terminale
omniroute backup                   # Crea uno snapshot della configurazione e del DB
omniroute restore [<timestamp>]    # Ripristina da uno snapshot
omniroute health                   # Stato dettagliato (circuit breaker, cache, memoria)
omniroute quota                    # Utilizzo delle quote dei provider
omniroute mcp status               # Stato del server MCP
omniroute a2a status               # Stato del server A2A
omniroute tunnel list|create|stop  # Tunnel Cloudflare/Tailscale/ngrok
omniroute reset-password           # Reimposta la password di amministrazione
omniroute --mcp                    # Avvia il server MCP tramite stdio
omniroute --port 3000              # Avvia il server su una porta personalizzata

Suggerimento: abbina omniroute doctor --json al tuo strumento di monitoraggio per ricevere avvisi sulle connessioni non funzionanti ai provider.

---

🖥️ Applicazione desktop (Electron)

OmniRoute è disponibile come applicazione desktop nativa per Windows, macOS e Linux.

Installazione

# Dalla directory electron:
cd electron
npm install

# Modalità di sviluppo (si connette al server di sviluppo Next.js in esecuzione):
npm run dev

# Modalità di produzione (utilizza la build standalone):
npm start

Creazione dei programmi di installazione

cd electron
npm run build          # Piattaforma corrente
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universale)
npm run build:linux    # Linux (.AppImage)

Output → electron/dist-electron/

Funzionalità principali

Funzionalità	Descrizione
Disponibilità del server	Interroga il server prima di mostrare la finestra (nessuna schermata vuota)
Area di notifica	Riduce a icona nell'area di notifica, cambia porta e consente di uscire dal relativo menu
Gestione della porta	Cambia la porta del server dall'area di notifica (riavvia automaticamente il server)
Content Security Policy	CSP restrittiva tramite header di sessione
Istanza singola	Può essere eseguita una sola istanza dell'app alla volta
Modalità offline	Il server Next.js incluso funziona senza connessione Internet

Variabili di ambiente

Variabile	Valore predefinito	Descrizione
OMNIROUTE_PORT	20128	Porta del server
OMNIROUTE_MEMORY_MB	512	Limite heap di Node.js (64–16384 MB)

📖 Documentazione completa: electron/README.md