Claude Code Router — indirizza Claude Code a qualsiasi modello oppure salta del tutto il router

La maggior parte delle persone che cercano Claude Code Router vuole una di due cose diverse: instradare Claude Code tra più provider di modelli oppure eseguire Claude Code a un prezzo inferiore rispetto al listino di Anthropic. Solo la prima richiede il router. Claude Code legge nativamente ANTHROPIC_BASE_URL, quindi la seconda richiede tre variabili d'ambiente e nessun software aggiuntivo.

Questa guida copre entrambi i percorsi, con i nomi esatti delle variabili, il problema delle credenziali che produce silenziosamente un 401, e un elenco onesto di ciò che smette di funzionare dietro qualsiasi gateway. Se hai letto di recente un'altra guida su CCR, vai prima a Opzione B: il config.json che quegli articoli ti dicono di modificare non è più la configurazione letta dal router.

Quale ti serve davvero?

Il router è un servizio locale: un processo aggiuntivo da eseguire, configurare e mantenere aggiornato; inoltre, dal 2026, è un'app desktop con una propria interfaccia invece di un file da modificare. Il costo è giustificato quando hai davvero bisogno dell'instradamento tra più provider, della contabilità per richiesta o della selezione del modello a livello di subagente. Non lo è quando sarebbe bastato un URL di base.

Opzione A — sostituzione dell'URL di base (nessuna installazione)

Kunavo espone l'Anthropic Messages API nativa all'indirizzo /v1/messages, che è l'endpoint chiamato da Claude Code. Indirizzalo lì:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL indica solo l'origine: Claude Code aggiunge autonomamente /v1/messages, quindi non includere un percorso. Mantieni le righe dei modelli: il modello predefinito integrato di Claude Code e il suo alias opus puntano entrambi all'ultimo Opus e, se Kunavo non offre ancora quel modello, la prima richiesta restituisce 404. L'alias sonnet richiede Sonnet 5.5, che Kunavo non offre; quindi, senza la riga ANTHROPIC_DEFAULT_SONNET_MODEL /model sonnet, la fase di esecuzione di opusplan e qualsiasi subagent impostato su model: sonnet restituiscono 404. L'alias opus è fissato su Opus 5.5 (claude-opus-5-5), che richiede Claude Code v2.1.280 o successivo: esegui claude update se la tua versione è precedente. Ottieni la chiave dal dashboard dopo esserti registrato e aver aggiunto $10; viene mostrata una sola volta.

Quale variabile delle credenziali usare e perché è importante

Claude Code invia le due variabili delle credenziali in header HTTP diversi e una chiave nell'header che il server non legge restituisce 401:

Preferisci ANTHROPIC_AUTH_TOKEN per un motivo concreto: ANTHROPIC_API_KEY richiede un'approvazione una tantum in una sessione interattiva e una chiave rifiutata una volta viene poi ignorata senza alcun prompt, producendo un errore sconcertante in cui la variabile è chiaramente impostata ma chiaramente inutilizzata. Su Kunavo la discovery dei modelli non fa distinzione. La discovery dei modelli del gateway di Claude Code invia solo il bearer token quando è impostato ANTHROPIC_AUTH_TOKEN e ricorre a x-api-key altrimenti; l'endpoint /v1/models di Kunavo legge la chiave da entrambi gli header.

Rendilo permanente

Le esportazioni della shell si applicano solo a quel terminale e a tutto ciò che viene avviato da esso: un editor aperto dal dock non le vedrà, né le vedranno gli agenti in background. Inserisci i valori in un file di impostazioni per applicarli ovunque:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Usa ~/.claude/settings.json per tutti i progetti. Non inserire mai una chiave nel file .claude/settings.json di un progetto: quel file viene sottoposto a commit.

Verifica prima di fidarti

Testa prima direttamente l'endpoint, così un errore indicherà la configurazione invece di Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Poi avvia claude dalla stessa shell ed esegui /status. Una riga Anthropic base URL che mostra api.kunavo.com e una riga Auth token che indica la tua variabile confermano che entrambe le parti sono operative.

Imposta un modello personalizzato — scegli esplicitamente lo slug

Kunavo risolve gli slug dei modelli con una corrispondenza esatta e non crea alias per i nomi con suffisso di data, quindi claude-sonnet-4-5-20250929 restituisce 404 mentre claude-sonnet-5 ha esito positivo. Imposta sempre ANTHROPIC_MODEL invece di affidarti al valore predefinito integrato:

Le variabili degli alias permettono di instradare le attività senza alcun router: ANTHROPIC_DEFAULT_OPUS_MODEL è associata all'alias opus e alla modalità plan, ANTHROPIC_DEFAULT_SONNET_MODEL è associata a sonnet e alla fase di esecuzione di opusplan, mentre ANTHROPIC_DEFAULT_HAIKU_MODEL è associata a haiku e alle attività in background di Claude Code, come riepiloghi e titoli. Su Kunavo sono obbligatorie le ultime due: se non vengono fissate, richiedono ID modello che Kunavo non offre (Sonnet 5.5 e Haiku 5.5 dalla v2.1.293). Imposta quella di Haiku su claude-haiku-4-5: in questo modo anche le attività in background vengono spostate dal modello principale. (ANTHROPIC_SMALL_FAST_MODEL è la denominazione obsoleta della stessa impostazione.)

Facoltativo: mostra tutti i modelli nel selettore

Imposta CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) e Claude Code interroga GET /v1/models all'avvio, aggiungendo ciò che trova al selettore /model contrassegnato con From gateway. Kunavo espone quell'endpoint, quindi ogni modello Claude abilitato viene visualizzato e /model diventa un menu aggiornato in tempo reale invece di un elenco da mantenere manualmente. Per questa operazione funziona entrambe le variabili delle credenziali: vedi sopra.

Opzione B — claude-code-router, come funziona realmente ora

Inizia da qui, perché quasi tutto ciò che è stato scritto su CCR descrive una versione che non esiste più. Il router era un tempo un file JSON e un comando ccr code. Ora è un piano di controllo locale con un'app desktop, un'interfaccia di gestione, log delle richieste e un gateway per i modelli: il config.json che ogni tutorial mostra non configura più il router.

CCR conserva la propria configurazione runtime in ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite su Windows). Un config.json legacy viene letto una volta, come fonte per la migrazione, quando non esiste ancora alcuna configurazione SQLite. Dopo il primo avvio, modificarlo non influisce sulla configurazione in esecuzione: senza errori né avvisi. Il blocco Providers che hai incollato con cura semplicemente non è la configurazione.

Questo include questa pagina prima del 2026-09-06: lo snippet JSON che si trovava qui era errato, e di un tipo di errore che può costare un pomeriggio, perché nulla ti dice che è stato ignorato. La configurazione ora avviene nell’interfaccia (oppure, come backup, Settings → Export data — non copiare i file SQLite attivi mentre CCR è in esecuzione).

Installazione e avvio

CCR è disponibile in due modalità: un’app desktop da GitHub Releases (barra delle applicazioni, aggiornamento automatico, integrazioni desktop) e una CLI npm per distribuzioni headless o supervisionate. Entrambe condividono la stessa directory di configurazione.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Aggiungere Kunavo richiede una voce provider — Providers → Add provider, preset Other / custom API endpoint, endpoint https://api.kunavo.com, la tua chiave sk-kn- — e un profilo Agent Config → Add profile → Claude Code. La versione dettagliata campo per campo, inclusi Check Connection e l’individuazione dei modelli, è disponibile nella pagina di integrazione di Claude Code Router. Il resto di questa sezione tratta ciò che quella pagina non copre: credenziali, costi e modalità di errore.

Tre credenziali e a quale si riferisce un 401

Questo è il modo più comune in cui una configurazione funzionante sembra non funzionare. CCR ha tre segreti distinti e ciascuno autentica un passaggio diverso:

Anche l’associazione delle porte confonde spesso: la gestione usa per impostazione predefinita 127.0.0.1:3458 e il gateway dei modelli 127.0.0.1:3456. Un URL di base indirizzato a 3458 raggiunge l’interfaccia, non il gateway. (Docker riunisce deliberatamente entrambi dietro un unico endpoint Nginx, motivo per cui le istruzioni per Docker sono diverse.) Un’interfaccia raggiungibile non equivale a un gateway funzionante: verifica /health sull’indirizzo del gateway e conferma che Server mostri Running.

La mappa per livello è il punto centrale

Claude Code non richiede un modello, ma un livello — il ciclo principale usa Sonnet o Opus, mentre il lavoro in background (sottoagenti, ricerca, riepiloghi, titoli delle conversazioni) usa quello piccolo e veloce. Un profilo Claude Code in Agent Config espone questi elementi come campi separati: un Model predefinito, più override opzionali per Fable, Opus, Sonnet e Haiku, ciascuno dei quali accetta un valore Provider/model. Lascia un livello vuoto e Claude Code lo sceglierà autonomamente.

Leggi quella tabella prima di copiare la suddivisione dei livelli di qualcun altro, perché la distinzione più evidente è la prima leva: claude-sonnet-5 costa il 50% in meno di claude-opus-5-5 su Kunavo ($1,40 / $7,00 rispetto a $2,80 / ). La seconda leva è il livello Haiku: a $0,70 / $3,50 costa 2× meno di Sonnet 5 e gestisce un volume che non vedi mai, ovvero ogni subagent, ogni passaggio di selezione dei file e ogni titolo generato. claude-sonnet-4-6 non è più il Sonnet economico: a $2,10 / $10,50 costa il 50% in più di Sonnet 5, motivo per cui gli snippet sopra impostano ANTHROPIC_MODEL=claude-sonnet-5.

Instradamento dei sottoagenti — ciò che la mappa dei livelli non può fare

Gli override dei livelli vincolano tutti i sottoagenti a un unico modello. CCR può essere più preciso: quando una richiesta Claude Code corrisponde al percorso integrato, inserisce l’elenco dei modelli disponibili nella descrizione dello strumento Agent / Task, e Claude Code antepone al prompt di ogni agente generato un tag che indica il modello desiderato:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR rimuove il tag e instrada di conseguenza quella singola richiesta, così un sottoagente di ricerca può essere eseguito su Haiku mentre uno di revisione viene eseguito su Opus, scegliendo per attività invece di vincolare tutto a un modello. L’impostazione è facile da non notare: il meccanismo è disattivato finché almeno un modello non ha una Description nella pagina Models. Senza descrizioni, CCR non inserisce nulla e ogni sottoagente ricade silenziosamente sul modello predefinito del profilo. Scrivi descrizioni basate sull’attività — “ricerca nel codice, selezione dei file, sottoagenti paralleli economici” per Haiku, “analisi dell’architettura, revisione ad alto rischio” per Opus. Quando funziona, i log delle richieste mostrano builtin:claude-code-subagent come motivo dell’instradamento.

Scelta del protocollo e relativo costo in termini di cache

CCR analizza l’endpoint e sceglie un protocollo di comunicazione. Forniscigli l’origine nuda https://api.kunavo.com e comunicherà tramite Anthropic Messages; forniscigli https://api.kunavo.com/v1 e userà il formato OpenAI-compatible. Entrambe le interfacce sono attive sulla stessa chiave e puoi sostituire il rilevamento automatico nelle impostazioni avanzate.

Preferisci il formato Anthropic Messages. Mantiene cache_control nel traffico, così la cache dei prompt raggiunge il modello e gli input memorizzati nella cache vengono fatturati al 10% della tariffa di input (come funziona) — in un ciclo agente che reinvia un prefisso stabile a ogni passaggio, è il maggior risparmio singolo disponibile. La precisazione importante è che un router nel percorso modifica comunque le richieste: CCR rimuove il messaggio di sistema con l’intestazione di fatturazione inserito da Claude Code e aggiunge l’elenco dei modelli alle descrizioni degli strumenti quando l’instradamento dei sottoagenti è attivo. Entrambi precedono i punti di interruzione della cache, quindi ogni modifica a quel contenuto comporta un cache miss mentre il nuovo prefisso si riscalda. Dopodiché resta stabile — ma è un motivo concreto per cui l’Opzione A ottiene una cache leggermente migliore dell’Opzione B, oltre a richiedere meno gestione.

Anche nel formato compatibile con OpenAI, però, la cache dei prompt raggiunge il modello. Con un prompt lungo, Kunavo imposta da sé i punti di interruzione della cache su quella route: sul prompt di sistema, sulle definizioni degli strumenti e sull’ultimo messaggio non appena la conversazione contiene un turno dell’assistente. Un cache_control che arriva su un messaggio o sulla definizione di uno strumento viene mantenuto.

Fallback: nuovo tentativo o failover

Vale la pena impostare Default on failure nella pagina Routing prima di averne bisogno. Retry reinvia la richiesta allo stesso modello in caso di 408, 409, 429 e 5xx, rispettando Retry-After e, in assenza di tale valore, applicando un backoff esponenziale da 1s fino a un limite di 30s. Fallback targets percorre un elenco ordinato di modelli di riserva e si attiva per qualsiasi 4xx o 5xx, considerando che l’assenza del modello o il rifiuto di un provider potrebbero riguardare solo la destinazione corrente. Le singole regole possono sovrascrivere l’impostazione globale. Quando viene eseguito un fallback, la risposta include x-ccr-fallback-attempts e x-ccr-fallback-model, così puoi capirlo a posteriori.

Verifica che sia effettivamente nel percorso

Avvia Claude Code dal profilo, invia un messaggio, quindi apri Request logs in CCR. La riga mostra request model (ciò che Claude Code ha richiesto), resolved provider e resolved model (dove è stato inviato) — questa terna è la prova. Nella CLI, /model elenca i modelli esposti da CCR. Se Claude Code risponde ma non compare alcuna riga nei log, lo hai avviato autonomamente invece che tramite CCR e l’ambito del profilo è Only opened from CCR.

Quanto costa una sessione di programmazione

Claude Code reinvia il prompt di sistema, la conversazione e il nuovo contesto dei file a ogni passaggio, quindi la tariffa per token si accumula rapidamente. Alle tariffe Kunavo su claude-sonnet-5:

Si tratta di circa il 30% in meno sul modello principale, prima della cache dei prompt. Le tariffe complete sono nella guida ai prezzi dell’API Claude e il calcolatore dei costi usa i tuoi conteggi di token.

Cosa continua a funzionare e cosa no

Indirizzare Claude Code verso un gateway modifica alcuni aspetti. L’elenco è breve, ma vale la pena conoscerlo prima di impegnarti:

Per l’ultima riga: il conteggio dei token è l’unico endpoint che la specifica del gateway proprietario di Anthropic indica come facoltativo e Claude Code stima localmente l’utilizzo del contesto quando è assente. Attualmente Kunavo non fornisce /v1/messages/count_tokens, quindi il valore /context è una stima e non un conteggio esatto. Oltre a questo numero nulla si degrada: la compattazione automatica e la sessione stessa non sono interessate.

Risoluzione dei problemi

Il percorso dell’URL di base

…e quando il router si trova nel percorso

Le correzioni specifiche per ogni errore dell’API sono disponibili nelle pagine di risoluzione dei problemi relative a invalid API key e rate limit.

Domande frequenti