Claude Code: abbonamento o chiave API?

Quale credenziale sta utilizzando la sessione Claude Code?

Un accesso a Claude Code può avvenire in uno di due modi. È possibile accedere con un account con abbonamento Claude di claude.ai oppure autenticarsi presso un'organizzazione Anthropic Console, che addebita ogni token al saldo API (application programming interface) dell'organizzazione. Esegui /status all'interno di una sessione attiva per verificare quale modalità è in uso: la scheda Status mostra una riga Login method per l'account con cui hai effettuato l'accesso e, quando la credenziale viene fornita da una chiave API, compare anche una riga API key aggiuntiva.

La questione se lo strumento sia incluso nel tuo piano è distinta e trova risposta in se Claude Code è incluso in un abbonamento Claude Pro. Il funzionamento delle chiavi per l'API Claude è descritto in come funziona l'autenticazione dell'API Claude. Questa sezione tratta invece ciò che i due argomenti non coprono: quale credenziale ha scelto effettivamente la sessione e come cambiarla.

Il comportamento descritto di seguito si basa sulla documentazione di Anthropic sull'autenticazione di Claude Code, consultata il 31 August 2026. Claude Code rilascia spesso nuove versioni e alcuni di questi comportamenti richiedono una versione minima. Esegui quindi claude --version prima di concludere che il problema riguardi la tua macchina.

Due account che possono condividere lo stesso indirizzo email

Un account claude.ai e un account Claude Console su platform.claude.com sono account distinti. Possono usare lo stesso indirizzo email e restare comunque accessi separati, con saldi distinti e in organizzazioni diverse. La creazione di uno non crea l'altro. Il pagamento di un piano Max non accredita credito su un'organizzazione Console e la ricarica di un'organizzazione Console non aggiunge nulla al piano.

I saldi differiscono perché differiscono i modelli di fatturazione. Un accesso tramite abbonamento utilizza la quota d'uso del piano, che si azzera in una finestra mobile di cinque ore e in una finestra settimanale; la quota è condivisa con Claude sul web. Una credenziale Console viene fatturata all'organizzazione in base ai token e i dati di riferimento sono disponibili nella pagina dei consumi Console. Le conseguenze di questa differenza sul lavoro reale sono illustrate in pagare in base ai token invece di pagare un abbonamento.

Un tipo di account non può utilizzare affatto il percorso dell'abbonamento. Anthropic indica come modalità di accesso disponibili un abbonamento Pro o Max, una licenza Claude for Teams o Enterprise, un account Claude Console oppure un cloud provider. Un account claude.ai con piano gratuito non compare nell'elenco. Un utente del piano gratuito non dispone quindi di una credenziale di abbonamento con cui effettuare l'accesso e cosa include e cosa non include il livello gratuito di Claude non si estende allo strumento da riga di comando. L'alternativa è un'organizzazione Console con credito API, cioè un account a pagamento di tipo diverso.

Percorso 1: accedere con il proprio abbonamento Claude

Eseguire claude in una directory di progetto. Al primo avvio, il comando apre una finestra del browser per accedere con l’account claude.ai associato al proprio piano.

claude

Su un server, due aspetti si comportano diversamente. Se il browser non si apre, premere c per copiare l’URL di accesso negli appunti e incollarlo in un browser sul proprio computer. Se il browser mostra un codice di accesso invece di riportare alla sessione del terminale, incollare il codice al prompt che lo richiede. Il secondo caso è normale quando si usa SSH (secure shell), WSL2 o un container, perché il browser non può raggiungere il server di callback locale avviato da Claude Code sul computer remoto.

Al termine dell’accesso, verificarne l’esito invece di darlo per scontato. Avviare una sessione ed eseguire /status. La scheda Status indica il metodo di accesso, oltre all’organizzazione e all’indirizzo email salvati. /login ripete il flusso usando un altro account, mentre /logout rimuove le credenziali salvate. Il logout reimposta anche lo stato della configurazione iniziale, quindi il comando claude successivo guida nuovamente attraverso la procedura di onboarding.

È importante sapere dove viene salvata la credenziale quando si ricrea un server o lo si cede a un altro amministratore:

• Linux: ~/.claude/.credentials.json, con modalità file 0600.
• macOS: nel portachiavi Keychain crittografato. Se Keychain rifiuta la scrittura, come accade quando è bloccato in una sessione SSH, Claude Code utilizza come fallback lo stesso file 0600.
• Windows: %USERPROFILE%\.claude\.credentials.json, con accesso limitato all’utente dai controlli di accesso della directory del profilo.
• Qualsiasi piattaforma con CLAUDE_CONFIG_DIR impostato: il file viene spostato sotto quella directory e la voce del portachiavi Keychain di macOS viene associata a tale directory. Di conseguenza, una sessione avviata con un CLAUDE_CONFIG_DIR diverso legge una credenziale diversa.

Claude Code gestisce questo file tramite /login e /logout. La modifica manuale del file non è un metodo supportato per cambiare account.

Percorso 2: autenticazione tramite un'organizzazione Console

L'accesso a Console inizia con un amministratore. L'amministratore ti invita da Console selezionando Settings, quindi Members e Invite. Assegna anche un ruolo: il ruolo Claude Code può creare soltanto chiavi API Claude Code, mentre il ruolo Developer può creare qualsiasi chiave. In seguito selezioni l'account Anthropic Console al prompt /login.

A partire da Claude Code v2.1.242 sono disponibili due percorsi Console, che memorizzano elementi diversi. Se accedi con l'account Console, il token OAuth (autorizzazione aperta) dell'accesso effettuato dal browser viene mantenuto e memorizzato come profilo Anthropic, senza creare alcuna chiave API. Claude Code aggiorna autonomamente questo accesso. Se l'aggiornamento non riesce, le richieste falliscono finché non effettui di nuovo l'accesso. Se crei una chiave API, che il prompt definisce legacy, viene generata una chiave Console e memorizzata insieme alle altre credenziali. Una chiave statica non viene mai aggiornata. Continua quindi a funzionare finché qualcuno non la revoca. Questo è utile su un build server, ma introduce un rischio su un laptop.

Rimuovi l'impostazione di ANTHROPIC_API_KEY prima di avviare un accesso Console senza chiave. Se la variabile è impostata, Claude Code salta completamente il prompt di accesso e ti chiede invece di approvare la chiave trovata.

La scelta non è sempre disponibile. Claude Code crea una chiave senza chiedere conferma quando la sessione viene eseguita tramite un cloud provider, quando un file di impostazioni imposta forceLoginOrgUUID oppure assegna a forceLoginMethod il valore "claudeai" o "console", oppure quando sulla macchina esiste una sorgente di impostazioni gestite e Claude Code non riesce a leggerla. Si tratta di decisioni dell'amministratore. Se l'opzione senza chiave non viene mai visualizzata, chiedi all'amministratore che gestisce i sistemi. /status stampa inoltre una riga Setting sources con il nome di ogni file di impostazioni caricato dalla sessione e indica la sorgente gestita quando si applica al tuo caso.

La prima volta che autentichi Claude Code tramite un'organizzazione Console, Console crea per essa un workspace denominato "Claude Code". Questo workspace serve a registrare in un unico punto la spesa di Claude Code. Al suo interno non puoi creare chiavi API.

Perché ANTHROPIC_API_KEY ha la precedenza dopo l'accesso

Claude Code non chiede quale credenziale preferisci usare. Controlla le origini in un ordine prestabilito e utilizza la prima disponibile. Come documentato nell'agosto 2026, l'ordine è il seguente:

1. Credenziali del provider cloud, quando sono impostate CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX o CLAUDE_CODE_USE_FOUNDRY.
2. ANTHROPIC_AUTH_TOKEN, inviato come intestazione Authorization: Bearer, per i gateway che usano l'autenticazione con bearer token.
3. ANTHROPIC_API_KEY, inviato come intestazione X-Api-Key.
4. L'output di uno script apiKeyHelper indicato in un file delle impostazioni.
5. CLAUDE_CODE_OAUTH_TOKEN, il token a lunga durata proveniente da claude setup-token.
6. Credenziali del profilo Anthropic e della federazione.
7. La credenziale dell'abbonamento scritta da /login.

La credenziale dell'abbonamento viene controllata per ultima. Pertanto, un ANTHROPIC_API_KEY esportato in qualsiasi punto dell'ambiente del processo ha la precedenza sull'account con cui hai effettuato l'accesso, e la sessione addebita i costi a un'organizzazione Console mentre ritieni di usare il tuo piano. Non c'è alcun malfunzionamento. L'ordine si comporta esattamente come documentato, per questo non viene mostrato alcun avviso.

Due dettagli rendono il problema difficile da individuare. In una sessione interattiva, Claude Code chiede una volta se deve usare la chiave trovata e memorizza la risposta. Pertanto, una scelta effettuata un mese fa può essere ancora applicata oggi. In modalità non interattiva con -p, non viene mostrato alcun prompt e la chiave viene sempre utilizzata quando è presente. -p è la modalità usata da un cron job o da un passaggio di CI (continuous integration), quindi è proprio nei processi non presidiati che una credenziale errata può rimanere inosservata più a lungo.

Nella sessione è disponibile un controllo visivo rapido. Quando ANTHROPIC_API_KEY è impostato, /config mostra un'opzione "Use custom API key". L'opzione è presente soltanto mentre la variabile è impostata, quindi la sua assenza indica che l'ambiente è pulito.

Individuare la chiave residua su un server

Una chiave esportata può rimanere in più posizioni, non solo nel profilo della shell:

• ~/.bashrc, ~/.bash_profile, ~/.profile o ~/.zshrc, letti da ogni nuova shell di login.
• Un'unità systemd, tramite Environment= o EnvironmentFile=, per qualsiasi processo eseguito come servizio.
• Il server tmux, che conserva una copia dell'ambiente con cui è stato avviato. Un pannello aperto oggi può ereditare una variabile eliminata dal profilo la settimana scorsa, perché il server era già in esecuzione prima della modifica.
• Un'immagine di container o la definizione di un job CI, dove la variabile è impostata al di fuori di qualsiasi file leggibile dall'interno della shell.
• Il blocco env di un file di impostazioni di Claude Code, che è una normale chiave di configurazione e segue la normale precedenza delle impostazioni.

Controllali prima di eseguire altre operazioni:

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

Il secondo comando passa volutamente attraverso cut, così stampa i nomi delle variabili senza visualizzare i valori segreti su uno schermo che potresti condividere o registrare. Il primo comando fornisce la risposta: se indica che la variabile è impostata, il prossimo claude avviato da questa shell utilizza quella chiave. Se tutti e cinque i controlli non producono output, non esiste alcuna credenziale nell'ambiente e una sessione avviata da qui utilizza la credenziale /login.

Aggiungi systemctl cat your-unit.service | grep -i environment per qualsiasi servizio che esegue Claude Code, perché un file di unità definisce il proprio ambiente e non legge mai il profilo della shell.

Passaggio da una credenziale all’altra

Per tornare al proprio abbonamento:

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

Attendere clear, quindi eseguire /status nella nuova sessione e verificare che la riga API key non sia più presente. Annullare l’impostazione della variabile nella shell non modifica un processo Claude Code già in esecuzione, perché un processo conserva l’ambiente con cui è stato avviato. Riavviare la sessione.

Eliminare quindi l’export dal file che lo impostava; in caso contrario, la shell di login successiva lo reimposterà. All’interno di tmux, tmux set-environment -u ANTHROPIC_API_KEY lo rimuove dai pane aperti dopo quel momento nella sessione, mentre i pane già aperti conservano la propria copia.

Per eseguire il passaggio inverso, impostare ANTHROPIC_API_KEY nell’ambiente oppure eseguire /login e selezionare l’account Console. Per cancellare completamente un login memorizzato, eseguire /logout. Dopo un accesso Console senza chiave, /logout rimuove e revoca la credenziale creata da quell’accesso.

Se /status continua a non corrispondere a quanto previsto, eseguire claude doctor. Elenca le voci delle impostazioni rifiutate da Claude Code. In questo modo è possibile individuare un file di impostazioni che non è stato analizzato correttamente e le cui impostazioni non sono mai state applicate.

Autenticazione quando non è disponibile un browser

claude setup-token apre lo stesso flusso di autorizzazione del browser di /login e stampa nel terminale un token OAuth valido per un anno.

claude setup-token

Il token non viene salvato in alcun punto, quindi copialo quando viene visualizzato. Impostalo come CLAUDE_CODE_OAUTH_TOKEN sul computer che ne ha bisogno. Il token esegue l'autenticazione con il tuo abbonamento, quindi richiede un piano Pro, Max, Team o Enterprise e può effettuare solo richieste ai modelli. La modalità bare non lo legge, quindi uno script che passa --bare richiede ANTHROPIC_API_KEY oppure un apiKeyHelper.

Anche in questo caso la precedenza è importante. Se CLAUDE_CODE_OAUTH_TOKEN si trova in un profilo della shell, l'esecuzione di /login imposta la sessione corrente sul nuovo accesso e ogni nuova sessione legge di nuovo la variabile finché non la rimuovi.

Se la tua organizzazione esegue l'inferenza tramite Amazon Bedrock, Google Cloud o Microsoft Foundry, quelle credenziali hanno la precedenza e non viene eseguito alcun accesso tramite browser. La relativa configurazione è un'attività separata, descritta in eseguire Claude Code tramite Bedrock o Vertex.

Una sessione di lunga durata su un VPS (virtual private server) è il contesto in cui questi problemi si concentrano maggiormente, perché la shell che l'ha avviata potrebbe essere stata configurata mesi prima e non essere mai stata riavviata. Eseguire Claude Code su un VPS all'interno di tmux descrive la gestione della sessione in questa configurazione.

Verificare cosa ha effettivamente consumato ogni credenziale

Con un accesso tramite abbonamento, /usage mostra le barre relative all'utilizzo del piano e il dettaglio di ciò che le ha consumate. La cifra in dollari nel blocco Session viene calcolata localmente a partire dal numero di token e dal prezzo di listino. Considerala quindi una stima destinata agli utenti API, non una fattura. Gli abbonati devono consultare le barre, non gli importi in dollari.

Con una credenziale Console, i dati rilevanti si trovano nella Console: la pagina dell'utilizzo per la spesa e il dashboard Claude Code per i dati relativi ai singoli membri. Nessun dato visualizzato nel terminale è autorevole ai fini della fatturazione.

Se le barre del piano non cambiano mentre lavori, una credenziale dell'ambiente sta avendo la precedenza. Questo singolo sintomo è l'indicatore più affidabile del fatto che sia attiva la credenziale errata, e monitorare quanto consuma una sessione Claude Code spiega come misurarlo in modo più approfondito. Se invece le barre avanzano e poi si fermano, hai raggiunto il limite del piano; come funzionano i limiti di utilizzo di Claude e le finestre di ripristino lo spiega in dettaglio.

Modalità di errore e controlli da eseguire

Tutto funziona, ma l'utilizzo previsto dal piano non cambia mai. È attiva una credenziale dell'ambiente. /status mostra una riga API key e il controllo della shell precedente mostra la variabile.

Le richieste falliscono anche se l'abbonamento è attivo. Una chiave appartenente a un'organizzazione della Console disabilitata o scaduta ha la precedenza sul login. Esegui unset ANTHROPIC_API_KEY, avvia una nuova sessione e controlla nuovamente /status. Se l'errore indica una chiave API non valida, correggere l'errore di chiave API non valida di Claude Code descrive in dettaglio questo caso, incluso il motivo per cui eseguire nuovamente /login non lo risolve.

All'avvio viene visualizzato un avviso che indica la scadenza imminente del login. Le versioni recenti mostrano un avviso quando una credenziale /login scadrà entro tre giorni. /status mostra quindi la riga del login come scaduta, insieme all'organizzazione e all'indirizzo email salvati. Esegui /login per rinnovarla. L'avviso non blocca mai una richiesta. Per questo è facile ignorarlo finché una sessione non interattiva smette di avanzare.

Un apiKeyHelper è lento o non funziona. Per impostazione predefinita, Claude Code esegue nuovamente l'helper ogni cinque minuti. L'intervallo è configurabile con CLAUDE_CODE_API_KEY_HELPER_TTL_MS. Quando un'esecuzione richiede più di dieci secondi, viene visualizzato un avviso nella barra del prompt. Un helper che non restituisce alcuna chiave, a causa di un errore o di un timeout, provoca il fallimento delle richieste entro tre tentativi.

La credenziale è corretta, ma l'organizzazione è errata. Un unico indirizzo email può appartenere a due organizzazioni. /status indica l'organizzazione usata per l'autenticazione. Leggi quindi quella riga invece di presumere quale organizzazione sia stata selezionata.

FAQ

Come posso verificare quale account sta usando Claude Code?

Esegui /status nella sessione. La scheda Status mostra una riga Login method per l’account con cui hai effettuato l’accesso e aggiunge una riga API key quando la credenziale viene fornita da una API key. Una riga Profile sostituisce quella del login quando viene selezionato un profilo Anthropic o una credenziale di federazione. Al di fuori della sessione, verificare se ANTHROPIC_API_KEY è impostata nella shell permette di capire se esiste una credenziale d’ambiente che avrebbe la precedenza sul login.

Perché il mio abbonamento Claude Pro o Max viene ignorato?

Perché una credenziale d’ambiente ha la precedenza. Claude Code usa la prima credenziale disponibile in un ordine fisso e la credenziale dell’abbonamento /login è all’ultimo posto, dopo le variabili del cloud provider, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper e CLAUDE_CODE_OAUTH_TOKEN. Esegui unset ANTHROPIC_API_KEY, avvia una nuova sessione e verifica con /status. Rimuovi quindi l’export dal profilo della shell, dall’unità systemd, dall’ambiente tmux o dalla definizione del container che lo imposta. In caso contrario, ricomparirà nella shell di login successiva.

Posso usare Claude Code con un account Claude gratuito?

No. Per il login, Anthropic indica i seguenti tipi di account: un abbonamento Pro o Max, un’utenza Claude for Teams o Enterprise, un account Claude Console oppure un cloud provider. Un account gratuito claude.ai non rientra tra questi. Di conseguenza, non esiste una credenziale di abbonamento da memorizzare. L’alternativa a pagamento all’abbonamento è un’organizzazione Claude Console con credito API, fatturato per token. Si tratta di un account separato, anche quando usa lo stesso indirizzo email.

L’account claude.ai e l’account Console condividono lo stesso saldo?

No. Sono account separati, con fatturazione distinta, anche quando usano lo stesso indirizzo email. L’utilizzo dell’abbonamento attinge alla quota del piano, condivisa con Claude sul web, e si reimposta su una finestra mobile di cinque ore e su una finestra settimanale. L’utilizzo di Console viene fatturato per token all’organizzazione e compare nella pagina dell’utilizzo di Console. Aggiungere credito a uno dei due account non ha alcun effetto sull’altro.

Come posso autenticare Claude Code su un server headless?

Hai due opzioni. Esegui claude tramite SSH e completa il login nel browser dal tuo computer: premi c per copiare l’URL, effettua l’accesso e incolla nuovamente il codice nel terminale se il browser ne mostra uno invece di eseguire il redirect. In alternativa, esegui claude setup-token su una macchina dotata di browser, copia il token con validità di un anno che viene visualizzato e impostalo come CLAUDE_CODE_OAUTH_TOKEN sul server. Questo token richiede un piano Pro, Max, Team o Enterprise e può eseguire soltanto richieste ai modelli. Uno script che usa --bare richiede quindi una API key oppure un apiKeyHelper.