Documentazione

Claude Code

Claude Code tratta qualsiasi endpoint in formato Anthropic come un gateway. Bastano due variabili per indirizzarlo a Kunavo e altre tre per fissare i modelli offerti da Kunavo. L’installazione resta invariata e ogni sessione viene fatturata per token dal tuo saldo, anziché tramite abbonamento.

Due variabili d'ambiente — ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN — portano Claude Code su un modello pay-as-you-go senza modificare l'installazione.

# One terminal session
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # origin, no /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves. Claude Code's default and its opus/sonnet aliases
# follow Anthropic's newest models; the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, /model sonnet 404s.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

claude

ANTHROPIC_BASE_URL è l’origine. Claude Code aggiunge autonomamente /v1/messages — lo snippet di verifica ufficiale di Anthropic è curl "$ANTHROPIC_BASE_URL/v1/messages" — quindi un valore che termina con /v1 genera richieste a /v1/v1/messages e restituisce 404. È l’errore di configurazione più comune; la pagina su ANTHROPIC_BASE_URL illustra gli altri.

Fissa i modelli. Il valore predefinito integrato di Claude Code è l'Opus più recente (Opus 5.5 a settembre 2026, secondo la documentazione di Anthropic sulla configurazione dei modelli) e un modello che Kunavo non offre ancora restituisce 404 alla prima richiesta. L'alias sonnet richiede Sonnet 5.5 e l'alias haiku Haiku 5.5 (dalla v2.1.293); Kunavo non offre nessuno dei due, quindi /model sonnet, /model haiku e i subagenti impostati su questi alias restituiscono 404 se non vengono fissati a un modello. ANTHROPIC_MODEL imposta il modello della sessione; ANTHROPIC_DEFAULT_OPUS_MODEL si applica a /model opus (Opus 5.5 richiede Claude Code v2.1.280 o successive), ANTHROPIC_DEFAULT_SONNET_MODEL si applica a /model sonnet e ANTHROPIC_DEFAULT_HAIKU_MODEL si applica a /model haiku oltre che alle chiamate in background. È valido qualsiasi ID restituito da GET /v1/models.

Usa ANTHROPIC_AUTH_TOKEN, non ANTHROPIC_API_KEY. Le due variabili selezionano un’intestazione: AUTH_TOKEN invia Authorization: Bearer, API_KEY invia x-api-key. Kunavo accetta entrambi, ma API_KEY richiede una richiesta di approvazione una tantum in una sessione interattiva prima di diventare effettiva, mentre AUTH_TOKEN no.

Preferisci non modificare manualmente le variabili d’ambiente? CC Switch può salvare Kunavo come provider Claude Code: usa la stessa radice del servizio e la stessa chiave bearer indicate sopra. La configurazione campo per campo è nella pagina di CC Switch.

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.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Esporta le variabili indicate sopra per la sessione oppure rendile permanenti nel blocco env di ~/.claude/settings.json: {"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"}}. La documentazione di Anthropic specifica chiaramente che la credenziale non va inserita nel file .claude/settings.json di un progetto, perché quel file viene incluso nei commit.
Esegui claude e apri la scheda Status. Una riga che indica Auth token conferma che la credenziale del gateway è attiva; una riga Login method che indica un account claude.ai significa che la variabile non è stata rilevata.
Per l’estensione VS Code, le variabili vanno in claudeCode.environmentVariables nelle impostazioni utente di VS Code: l’estensione verifica le credenziali prima di avviare Claude Code, quindi ~/.claude/settings.json raggiunge il processo avviato ma non quella verifica.

Verificato rispetto a “Collegare Claude Code a un gateway LLM” di Anthropic il 3 ottobre 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 alle chiavi API di Claude Code.

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.

# 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
`claude-sonnet-5`	$1.40 / $7.00	il modello di lavoro predefinito, impostato con /model o ANTHROPIC_MODEL
`claude-opus-5-5`	$2.80 / $14.00	pianificazione e modifiche a livello architetturale
`claude-haiku-4-5`	$0.70 / $3.50	l'alias haiku e le chiamate in background avviate da Claude Code: fissalo con ANTHROPIC_DEFAULT_HAIKU_MODEL
`claude-fable-5`	$7.00 / $35.00	il livello all’avanguardia, per i piani che giustificano la sua tariffa

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.

Domande frequenti

Come si usa Claude Code senza un abbonamento Claude?

Imposta ANTHROPIC_BASE_URL su un endpoint in formato Anthropic, ANTHROPIC_AUTH_TOKEN sulla chiave di quell’endpoint e ANTHROPIC_MODEL su un modello offerto dall’endpoint: il valore predefinito integrato in Claude Code potrebbe non essere disponibile. Claude Code autentica quindi le richieste presso l’endpoint anziché claude.ai; chi possiede la credenziale addebita l’uso per token, senza applicarlo a un piano di abbonamento. Anthropic documenta questa modalità come modalità gateway: la sessione claude.ai salvata resta sul disco ma inutilizzata, e torna in uso non appena rimuovi le variabili.

ANTHROPIC_BASE_URL deve includere /v1?

No. Claude Code aggiunge autonomamente il percorso, quindi la variabile deve contenere l’origine: https://api.kunavo.com, non https://api.kunavo.com/v1. Il comando di verifica ufficiale di Anthropic è curl "$ANTHROPIC_BASE_URL/v1/messages", che mostra chiaramente la concatenazione. Un URL di base che termina già con /v1 invia le richieste a /v1/v1/messages e restituisce 404.

Qual è la differenza tra ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY?

Inseriscono la credenziale in intestazioni HTTP diverse: ANTHROPIC_AUTH_TOKEN invia Authorization: Bearer, mentre ANTHROPIC_API_KEY invia x-api-key. Se usi la variabile sbagliata, la chiave raggiunge l’endpoint in un’intestazione che non viene letta e la richiesta fallisce con 401. Se la documentazione di un gateway parla di "bearer token", usa ANTHROPIC_AUTH_TOKEN; se parla di "API key" o "x-api-key", usa ANTHROPIC_API_KEY.

Quali funzionalità di Claude Code smettono di funzionare con un URL di base personalizzato?

Remote Control e la dettatura vocale richiedono entrambe un’identità claude.ai e non sono disponibili quando è impostata una credenziale del gateway. Remote Control viene inoltre disattivato ogni volta che ANTHROPIC_BASE_URL punta a un host non Anthropic. Anche la verifica della disponibilità della modalità veloce contatta direttamente api.anthropic.com, senza seguire l’URL di base. Tutto ciò che rientra nel ciclo principale — agente, strumenti, subagenti e server MCP — funziona tramite l’API Messages e non ne risente.