Chiave API Claude Code — dove ottenerla, dove inserirla e perché la variabile errata fallisce senza messaggi

Claude Code può autenticarsi in due modi diversi e quello che ti serve determina tutto il resto. Un accesso tramite abbonamento claude.ai copre l'utilizzo incluso nel piano Pro o Max. Una chiave API viene fatturata per token senza limiti del piano. Questa guida spiega dove ottenere una chiave, dove inserirla esattamente, le due variabili delle credenziali e perché scegliere quella sbagliata produce un errore silenzioso, oltre a come mantenere sotto controllo la fattura una volta che tutto funziona.

Hai davvero bisogno di una chiave?

È utile saperlo prima di iniziare: impostare una chiave sospende il tuo abbonamento. Quando una variabile delle credenziali è attiva, Claude Code la usa al posto dell'accesso claude.ai salvato, i limiti del piano smettono di applicarsi e l'utilizzo viene fatturato al titolare della chiave. Rimuovila e Claude Code torna all'abbonamento.

Opzione 1 — una chiave Anthropic di prima parte

1. Accedi a console.anthropic.com (un account separato da claude.ai).
2. Aggiungi credito in Billing. L'API è prepagata e separata da qualsiasi abbonamento: un piano Pro non la finanzia.
3. Crea una chiave in API Keys. Inizia con sk-ant- e viene mostrata una sola volta.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

Nota il secondo passaggio nello snippet. ANTHROPIC_API_KEY viene inviato nell'intestazione x-api-key e richiede un'approvazione interattiva una tantum prima che Claude Code possa utilizzarlo. Se quel prompt è stato rifiutato, la chiave viene ignorata in seguito senza alcun prompt, dando esattamente l'impressione che la variabile non venga letta. Riattivala in /config → Use custom API key.

Opzione 2 — una chiave che costa meno per token

Claude Code legge nativamente ANTHROPIC_BASE_URL, quindi funziona con qualsiasi endpoint che esponga l'Anthropic Messages API: nessun plugin, nessun proxy, nessun binario modificato. Questo è il percorso supportato per i gateway ed è il modo per eseguire gli stessi modelli Claude a una tariffa inferiore:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
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

ANTHROPIC_BASE_URL è solo l'origine: Claude Code aggiunge autonomamente /v1/messages. Mantieni le righe dei modelli: il valore predefinito integrato di Claude Code e il suo alias opus puntano entrambi all'ultimo Opus e, se Kunavo non serve ancora quel modello, la prima richiesta restituisce 404. La riga opus lo fissa su Claude Opus 5.5, che richiede Claude Code v2.1.280 o successivo (esegui claude update su una versione precedente). L'alias sonnet richiede Sonnet 5.5, che Kunavo non serve; quindi, senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase di esecuzione di opusplan e i sub-agenti impostati su sonnet restituiscono tutti 404. Crea la chiave sk-kn- nella dashboard dopo esserti registrato e aver ricaricato $10. Non c'è alcun canone mensile e il saldo non scade.

Sono circa 30% in meno rispetto al prezzo di listino del modello principale. Le tariffe complete sono nella guida ai prezzi dell'API Claude, mentre i prezzi di Claude Code confrontano questo percorso con i costi dei piani Pro e Max; la configurazione completa, inclusi l'instradamento del modello per attività e ciò che cambia dietro un gateway, è nella guida al router di Claude Code. Se la CLI non è ancora installata, inizia da installare Claude Code.

Dove va effettivamente la chiave

Due variabili, due intestazioni HTTP diverse. Una chiave nell'intestazione che il server non legge restituisce 401:

Se non sai quale tipo possiedi, inizia con ANTHROPIC_AUTH_TOKEN, che non richiede una fase di approvazione. Su Kunavo entrambe le variabili consentono a Claude Code di scoprire anche l'elenco dei modelli, perché /v1/models legge la chiave da entrambe le intestazioni.

Esportazione della shell o file delle impostazioni

Un'esportazione della shell si applica solo a quel terminale e ai relativi processi figli. Un editor avviato dal dock non la vedrà, e nemmeno gli agenti in background. Per qualcosa di permanente, usa invece il blocco env di ~/.claude/settings.json: le stesse chiavi si applicano ovunque venga eseguito Claude Code. Non inserire una chiave nel .claude/settings.json di un progetto: quel file viene salvato nel repository e condiviso con chiunque lo cloni.

Esegui /status per confermare quale credenziale è attiva. Una riga Auth token o API key che nomina la tua variabile indica che la chiave è attiva; una riga Login method che nomina un account claude.ai indica che non lo è.

Ruotare le chiavi senza modificare i file

Se la credenziale scade secondo una pianificazione o proviene da un vault, punta apiKeyHelper a un comando che stampa quella corrente:

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

Fai riferimento a essa come "apiKeyHelper": "~/bin/get-key.sh" nel file delle impostazioni. Claude Code memorizza l'output nella cache per cinque minuti e lo riesegue su un 401; regolalo con CLAUDE_CODE_API_KEY_HELPER_TTL_MS. Il valore viene inviato in entrambe le intestazioni, quindi funziona in entrambi i casi.

Mantenere prevedibile la fattura

La programmazione agentica consuma molti token: a ogni passaggio vengono reinviati il prompt di sistema, la cronologia dell'attività e il nuovo contesto dei file. Quattro aspetti contano più di ogni altro:

1. Mantieni la riga di Haiku. Senza ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5, l'alias haiku di Claude Code richiede un ID modello che Kunavo non offre (Haiku 5.5 dalla v2.1.293), quindi /model haiku e i subagenti impostati su haiku restituiscono 404. La stessa riga sposta dal modello principale i riepiloghi e i titoli generati autonomamente da Claude Code; il risparmio aumenta quando il lavoro viene distribuito su più attività, come mostrato in quanto costa un flusso di lavoro con Claude Code.
2. Le stesse due variabili instradano l'Agent SDK. Non dispone di una propria opzione base-URL: avvia questa CLI e passa direttamente il tuo ambiente, quindi un programma Agent SDK viene instradato esattamente dalla configurazione precedente.
3. Avvia nuove attività invece di estenderne una all'infinito. Il contesto viene reinviato a ogni passaggio, quindi una sessione lunga ha un costo quadratico. La scelta del livello da assegnare al modello principale è trattata in Opus vs Sonnet vs Haiku, considerando il costo per attività completata anziché il costo per token.
4. Lascia funzionare la memorizzazione nella cache dei prompt. Gli input memorizzati nella cache vengono fatturati al 10% della tariffa di input e il percorso nativo dell'API Messages passa cache_control senza tradurlo (dettagli).
5. Assegna all'editor una chiave con un limite di spesa dedicato nella dashboard, quindi controlla l'utilizzo dopo una settimana. I limiti per chiave trasformano un ciclo incontrollato in uno con tetto massimo.

Risoluzione dei problemi

Domande frequenti