Claude Code «API Error: 401 authentication_error» con un base URL personalizzato: tutte le cause

Stampa le tre variabili e verifica che il base URL non abbia un percorso

La causa più comune è visibile qui. Il base URL deve essere un’origine, senza /v1 né percorsi finali, perché il client aggiunge da solo l’endpoint. Un base URL che termina con /v1 produce una richiesta a /v1/v1/messages.

env | grep -E '^ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY|MODEL)='

# Right: https://api.kunavo.com
# Wrong: https://api.kunavo.com/v1

Chiama direttamente l’endpoint, in entrambi i modi

/v1/messages di Kunavo accetta la credenziale sia come x-api-key sia come Authorization: Bearer; per questo Claude Code non richiede plugin o proxy intermedi. Se curl riesce e la CLI no, il problema è nell’ambiente della shell, non nel server.

curl -s https://api.kunavo.com/v1/messages   -H "x-api-key: $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-5","max_tokens":8,
       "messages":[{"role":"user","content":"hi"}]}'

# Same call, other header style — both are accepted:
#   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Annulla la variabile che non stai usando

Se sono impostate sia ANTHROPIC_API_KEY sia ANTHROPIC_AUTH_TOKEN, può prevalere quella sbagliata. Annulla ANTHROPIC_API_KEY, avvia una nuova shell e riprova: un export obsoleto nel profilo della shell sopravvive a ogni altra correzione.

Se lo stato è 404, smetti di eseguire il debug della chiave

Un 404 il cui messaggio nomina il modello indica che la credenziale è stata accettata, ma la stringa del modello no. Correggi invece ANTHROPIC_MODEL: la chiave non presenta problemi. In una configurazione nuova, la causa abituale è che nessuno fissa il modello: Claude Code invia quindi il proprio valore predefinito integrato, l'Opus più recente, che Kunavo potrebbe non offrire ancora; inoltre /model sonnet richiede Sonnet 5.5, che Kunavo non offre. Imposta ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL sugli ID restituiti da GET /v1/models.

Perché la mia chiave funziona con curl ma non con Claude Code?

Quasi sempre perché nel profilo della shell è impostata una seconda variabile oppure il base URL contiene un percorso. L’endpoint accetta entrambi gli stili di intestazione, quindi la differenza non è l’header.

ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY?

AUTH_TOKEN per un base URL di terze parti: viene usato immediatamente. API_KEY attiva prima una richiesta di approvazione una tantum, spesso scambiata per un errore.

Un abbonamento Claude copre un base URL personalizzato?

No. Un abbonamento autentica verso l’endpoint del provider; se indirizzi la CLI altrove, devi usare la credenziale di quell’endpoint, che viene fatturata da quest’ultimo.