Documentazione

Claude Code Router

CCR si interpone tra Claude Code e il servizio che fornisce i modelli, permettendo di instradare classi di richieste diverse verso destinazioni diverse. Aggiungi Kunavo come endpoint personalizzato, poi usa Agent Config per associare ciascun livello Claude a un ID modello.

CCR è ora un'app desktop, non un config.json: aggiungi Kunavo come endpoint API personalizzato, poi lascia che le regole di routing inviino ogni classe di richiesta a un modello diverso.

CCR Desktop

Providers → Add provider
  Preset provider   Other / custom API endpoint
  Name              Kunavo
  API endpoint      https://api.kunavo.com
  API key           sk-kn-...
  Models            claude-sonnet-5, claude-opus-5, claude-haiku-4-5

Agent Config → Add profile → Claude Code
  Model         Kunavo/claude-sonnet-5
  Opus model    Kunavo/claude-opus-5
  Haiku model   Kunavo/claude-haiku-4-5

Modificare manualmente config.json non produce più alcun effetto. CCR mantiene la configurazione runtime in ~/.claude-code-router/config.sqlite e legge config.json, una configurazione legacy, una sola volta come origine per la migrazione, quando non esiste una configurazione SQLite. Dopo il primo avvio, le modifiche al file JSON vengono ignorate senza alcun avviso. La maggior parte delle guide online, comprese le versioni precedenti della nostra, descrive ancora il file JSON.

L’endpoint API è l’origine nuda, https://api.kunavo.com: CCR verifica il protocollo su questo indirizzo e Kunavo risponde nativamente con Anthropic Messages su /v1/messages. Se preferisci che CCR usi il formato compatibile con OpenAI, usa invece https://api.kunavo.com/v1: entrambi gli endpoint sono attivi con la stessa chiave.

Non hai ancora una chiave? Crea un account Kunavo, genera una chiave (inizia con sk-kn-) e aggiungi credito da $10: le chiamate vengono pagate con quel saldo e le chiamate non riuscite non vengono addebitate. La dashboard si apre quindi sulla configurazione Claude Code Router.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
In CCR Desktop, apri Providers → Add provider, scegli il preset Other / custom API endpoint e compila i campi Name, API endpoint e API key.
Aggiungi gli ID dei modelli in Models: usa Search models per caricare il catalogo oppure Custom models per inserire manualmente gli ID.
Esegui Check Connection su due o tre modelli. Verranno inviate richieste effettive, quindi seleziona solo ciò che devi verificare, non l’intero elenco.
Apri Agent Config → Add profile → Claude Code, imposta Model e le sostituzioni per ciascun livello Opus / Sonnet / Haiku, salva e avvia Claude Code da CCR.

Verificato rispetto a la pagina di configurazione dei provider di CCR il 6 settembre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Questa è la versione breve. La guida completa, con scelta del modello, costo di una sessione reale e modalità di errore, è in la guida a Claude Code Router.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in Claude Code Router.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

ID del modello	Kunavo ingresso / uscita	Dove si inserisce in Claude Code Router
`claude-opus-5`	$3.50 / $17.50	il livello Opus, per pianificazione e modifiche complesse
`claude-sonnet-5`	$1.40 / $7.00	il livello Sonnet e il modello predefinito del profilo
`claude-haiku-4-5`	$0.70 / $3.50	il livello Haiku, a cui viene assegnato il carico dei subagenti
`gpt-5-6-terra`	$0.70 / $4.20	un percorso a contesto lungo, accessibile tramite la stessa voce del provider

La fatturazione è per token, usando un saldo prepagato senza canone mensile: vedi billing. In presenza di contesto ripetuto, che costituisce la maggior parte di ciò che invia un editor o un client di chat, prompt caching incide sulla spesa più della scelta del modello.

Perché la mappatura per livello è fondamentale

Claude Code sceglie un modello per ciascun livello, non per ogni richiesta: il ciclo principale usa il livello Sonnet o Opus, mentre le attività in background — subagenti, ricerca, riepiloghi — usano quello più piccolo e veloce. Agent Config di CCR espone questi livelli come campi separati, così il modello costoso gestisce solo le richieste che ne hanno bisogno, mentre il livello ad alto volume viene assegnato a un ID economico. È proprio per questa suddivisione che conviene usare un router davanti a Claude Code, ed è una scelta che non si vede nelle impostazioni di Claude Code.

Domande frequenti

Dove archivia Claude Code Router la sua configurazione?

In un database SQLite: ~/.claude-code-router/config.sqlite su macOS e Linux, %APPDATA%\claude-code-router\config.sqlite su Windows. La configurazione legacy config.json viene letta una sola volta come origine per la migrazione, se non esiste ancora una configurazione SQLite; dopo la migrazione, modificare config.json non ha alcun effetto sulla configurazione in uso. Modifica le impostazioni dall’interfaccia desktop.

Come si aggiunge un endpoint API personalizzato a Claude Code Router?

Apri Providers, fai clic su Add provider e seleziona il preset "Other / custom API endpoint": accetta qualsiasi upstream compatibile con OpenAI, Anthropic o Gemini. Inserisci un Name univoco, l’URL di base dell’endpoint API e la chiave API, poi aggiungi gli ID dei modelli recuperandoli o inserendoli in Custom models. Check Connection invia richieste di prova effettive per verificare che endpoint, chiave, protocollo e ID funzionino insieme.

Claude Code Router può inviare livelli Claude diversi a modelli diversi?

Sì, ed è il motivo principale per usarlo. In Agent Config, un profilo Claude Code ha un Model predefinito e sostituzioni facoltative per Fable, Opus, Sonnet e Haiku. Claude Code richiede un livello, non un ID specifico; assegnando il livello Haiku a un modello economico e quello Opus a uno più potente, i costi vengono suddivisi secondo il comportamento già previsto dell’agente: le attività in background ad alto volume usano l’ID economico, la pianificazione quello costoso.

Claude Code Router funziona con un gateway in formato Anthropic?

Sì. Il preset per endpoint personalizzato verifica il protocollo sull’URL fornito e supporta Anthropic Messages tra i protocolli disponibili, quindi puoi aggiungere direttamente un gateway che espone /v1/messages, usando la sua origine come endpoint API. Puoi aggiungere in entrambi i modi un gateway che espone anche un endpoint compatibile con OpenAI: cambia solo il formato usato da CCR per comunicare con esso.