Documentazione

ANTHROPIC_BASE_URL

La variabile d'ambiente che indirizza Claude Code e gli SDK Anthropic a un endpoint diverso da api.anthropic.com: il riferimento completo alle variabili, la configurazione per client e le due insidie che causano quasi tutti gli errori.

ANTHROPIC_BASE_URL indica agli SDK di Anthropic e a Claude Code a quale host inviare le richieste API, sostituendo quello predefinito https://api.anthropic.com. Impostala su un'origine senza percorso — il client aggiunge autonomamente /v1/messages — e abbinala a ANTHROPIC_AUTH_TOKEN, che diventa l'intestazione Authorization: Bearer.

~/.zshrc

# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

Dopo, apri un nuovo terminale: Claude Code e gli SDK leggono queste variabili all'avvio del processo, quindi una sessione già in esecuzione continua a usare il vecchio endpoint.

Non inserire /v1 in ANTHROPIC_BASE_URL. I client di Anthropic aggiungono autonomamente il percorso, quindi https://api.kunavo.com/v1 genera richieste a /v1/v1/messages e ogni chiamata restituisce 404. L'SDK di OpenAI usa la convenzione opposta e richiede effettivamente /v1 nel proprio base_url — questa differenza è l'errore di configurazione in assoluto più comune in questo contesto.

Tutte le variabili e la loro funzione

L'elenco completo delle variabili lette da Claude Code è disponibile nel riferimento alle variabili d'ambiente di Anthropic. Queste sono quelle importanti quando reindirizzi l'endpoint.

Variabile	Valore	Cosa controlla
`ANTHROPIC_BASE_URL`	`https://api.kunavo.com`	L'origine verso cui vengono inviate tutte le richieste. Nessun percorso e nessuna barra finale.
`ANTHROPIC_AUTH_TOKEN`	`sk-kn-…`	Credenziale inviata come Authorization: Bearer. È quella richiesta da un gateway.
`ANTHROPIC_API_KEY`	`sk-ant-…`	Credenziale inviata nell'intestazione x-api-key, il formato previsto da api.anthropic.com. Imposta questa oppure il token qui sopra, non entrambe.
`ANTHROPIC_MODEL`	`claude-sonnet-5`	Il modello principale usato da Claude Code per la conversazione.
`ANTHROPIC_DEFAULT_OPUS_MODEL`	`claude-opus-5-5`	Il modello utilizzato dall’alias opus (/model opus). Il valore predefinito di Claude Code è l’Opus più recente, quindi fissalo su un modello servito dall’endpoint. Opus 5.5 richiede Claude Code v2.1.280 o successivo.
`ANTHROPIC_DEFAULT_SONNET_MODEL`	`claude-sonnet-5`	Il modello utilizzato dall’alias sonnet (/model sonnet). Per impostazione predefinita, l’alias richiede Sonnet 5.5, quindi fissalo su un modello Sonnet servito dall’endpoint.
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claude-haiku-4-5`	Il modello associato all'alias haiku (/model haiku e subagenti impostati su haiku), che Claude Code usa anche per le proprie chiamate in background. Dalla v2.1.293, l'alias richiede Haiku 5.5: fissalo su un modello Haiku offerto dall'endpoint.

I nomi dei modelli devono corrispondere a quelli effettivamente offerti dall'endpoint. Indicare un gateway lasciando un ID modello che non supporta è la seconda causa di errore più comune e genera 404 model_not_found, non un errore di autenticazione. Gli ID dei modelli Kunavo sono elencati nella pagina dei modelli e restituiti in tempo reale da GET /v1/models.

Configurazione per client

Claude Code

Inserisci le esportazioni nel profilo della shell da cui viene avviato Claude Code, quindi apri un nuovo terminale. L'installazione e il flusso di lavoro non cambiano.

~/.zshrc

# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
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

Esegui /status in Claude Code per verificare quale endpoint sta usando la sessione corrente. Istruzioni dettagliate, incluso dove generare la chiave: impostare una chiave API in Claude Code.

SDK Anthropic (Python / TypeScript)

Gli SDK leggono le stesse variabili d'ambiente; entrambe le impostazioni possono anche essere passate al costruttore, utile quando un processo comunica con più endpoint.

anthropic_sdk.py

from anthropic import Anthropic

# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
    base_url="https://api.kunavo.com",
    auth_token="sk-kn-...",          # sets the Authorization: Bearer header
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)

SDK OpenAI: l'altra convenzione

Se il tuo codice usa già OpenAI, non hai affatto bisogno di ANTHROPIC_BASE_URL. Imposta base_url sul percorso compatibile con OpenAI, questa volta con /v1, e chiama gli stessi modelli Claude tramite /v1/chat/completions.

openai_sdk.py

from openai import OpenAI

# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)

Cline, Roo Code, Kilo Code, Cursor

Gli agenti degli editor espongono perlopiù le stesse due impostazioni nella propria interfaccia, invece che tramite l'ambiente: un campo «URL di base» o «endpoint personalizzato» e un campo per la chiave API. Le regole non cambiano: origine senza /v1 per un provider in stile Anthropic e chiave nel campo della chiave API. Guide specifiche per client: Cline, Roo Code, Kilo Code.

Verifica che funzioni

Una richiesta curl verifica contemporaneamente l'URL di base e la credenziale. Una risposta 200 con un corpo JSON significa che entrambi sono corretti.

# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

# In Claude Code, /status shows the endpoint the session is actually using.

Se non funziona

Sintomo	Causa	Correzione
404 per ogni richiesta	`/v1` aggiunto alla fine di `ANTHROPIC_BASE_URL`	Imposta solo l'origine. Il client aggiunge /v1/messages.
401 / x-api-key non valida	Credenziale impostata come `ANTHROPIC_API_KEY` mentre l'endpoint autentica tramite token bearer	Usa invece `ANTHROPIC_AUTH_TOKEN`: la differenza spiegata nel dettaglio
Le richieste raggiungono ancora api.anthropic.com	Variabili esportate dopo l'avvio della sessione o impostate in un profilo che la shell non legge	Apri un nuovo terminale; conferma con echo $ANTHROPIC_BASE_URL nella stessa shell che avvia il client.
404 model_not_found	ID di un modello non offerto dall'endpoint	Imposta `ANTHROPIC_MODEL` su un ID di `GET /v1/models`
Claude Code segnala che il saldo dei crediti è troppo basso	Le richieste raggiungono l'endpoint e vengono addebitate alla chiave, non all'abbonamento	Comportamento previsto: ricarica il saldo oppure rimuovi il token per tornare al piano. Vedi credito insufficiente

Effetti su un abbonamento Pro o Max

Quando è impostata una variabile per le credenziali, Claude Code addebita i costi alla chiave anziché all'abbonamento con cui hai effettuato l'accesso: i limiti del piano non si applicano più e l'utilizzo viene addebitato al titolare della chiave. L'abbonamento rimane invariato: rimuovi la variabile e apri un nuovo terminale, e Claude Code tornerà a usare il piano. Le due modalità non si combinano mai; il confronto dei costi è disponibile in Prezzi di Claude Code.

Avanti

Domande frequenti

Che cos'è ANTHROPIC_BASE_URL?

ANTHROPIC_BASE_URL è la variabile d'ambiente che indica agli SDK Anthropic e a Claude Code a quale host inviare le richieste API, al posto dell'host predefinito https://api.anthropic.com. Impostala su un'origine senza percorso: il client aggiunge autonomamente /v1/messages; abbinala ad ANTHROPIC_AUTH_TOKEN, che diventa l'intestazione Authorization: Bearer. Funziona qualsiasi endpoint compatibile con Anthropic; su Kunavo il valore è https://api.kunavo.com.

ANTHROPIC_BASE_URL deve includere /v1?

No. ANTHROPIC_BASE_URL deve contenere solo l'origine: https://api.kunavo.com, non https://api.kunavo.com/v1, perché gli SDK Anthropic e Claude Code aggiungono autonomamente il percorso /v1/messages. Includere /v1 genera richieste a /v1/v1/messages, che restituiscono 404. L'SDK OpenAI segue la convenzione opposta e richiede /v1 in base_url: ecco perché lo stesso gateway si scrive in due modi diversi a seconda del client che lo chiama.

Qual è la differenza tra ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY?

ANTHROPIC_AUTH_TOKEN invia la credenziale nell'intestazione Authorization: Bearer, mentre ANTHROPIC_API_KEY la invia nell'intestazione x-api-key, richiesta da api.anthropic.com. Un gateway che autentica tramite token bearer richiede ANTHROPIC_AUTH_TOKEN; impostare invece ANTHROPIC_API_KEY è la causa più comune di un errore 401 dopo aver modificato ANTHROPIC_BASE_URL. Impostane una sola, non entrambe: se sono presenti entrambe, il comportamento dipende dalla versione del client.

Come si imposta un URL di base personalizzato in Claude Code?

Esporta ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN nel profilo della shell da cui viene avviato Claude Code (~/.zshrc o ~/.bashrc), quindi apri un nuovo terminale affinché erediti le variabili. Claude Code le legge all'avvio, quindi una sessione già in esecuzione continua a usare il vecchio endpoint. Esegui /status in Claude Code per verificare quale endpoint sta usando la sessione corrente.

Impostare ANTHROPIC_BASE_URL disattiva il mio abbonamento Claude Pro o Max?

Quando è impostata una variabile per le credenziali, come ANTHROPIC_AUTH_TOKEN, Claude Code addebita i costi alla chiave anziché all'abbonamento con cui hai effettuato l'accesso. I limiti dei piani Pro e Max non si applicano più e l'utilizzo viene addebitato al titolare della chiave. L'abbonamento non viene modificato né annullato: rimuovi la variabile e apri un nuovo terminale, e Claude Code tornerà a usare il piano.