Se hai credenziali Google Cloud e desideri iniziare a utilizzare Claude Code tramite Vertex AI, la procedura guidata di accesso ti guida attraverso i passaggi. Completi i prerequisiti lato GCP una volta per progetto; la procedura guidata gestisce il lato Claude Code.
Esegui claude. Al prompt di accesso, seleziona 3rd-party platform, quindi Google Vertex AI.
3
Segui i prompt della procedura guidata
Scegli come autenticarti a Google Cloud: Application Default Credentials da gcloud, un file di chiave dell'account di servizio, o credenziali già presenti nel tuo ambiente. La procedura guidata rileva il tuo progetto e la tua regione, verifica quali modelli Claude il tuo progetto può invocare, e ti consente di fissarli. Salva il risultato nel blocco env del tuo file di impostazioni utente, quindi non è necessario esportare variabili di ambiente da solo.
Dopo aver effettuato l'accesso, esegui /setup-vertex in qualsiasi momento per riaprire la procedura guidata e modificare le tue credenziali, progetto, regione o fissaggi di modello.
Configurazione della regione
Claude Code supporta endpoint Vertex AI globali, multi-regione e regionali. Imposta CLOUD_ML_REGION su global, una posizione multi-regione come eu o us, o una regione specifica come us-east5. Claude Code seleziona il nome host Vertex AI corretto per ogni modulo, inclusi gli host aiplatform.eu.rep.googleapis.com e aiplatform.us.rep.googleapis.com per le posizioni multi-regione.
Configurazione manuale
Per configurare Vertex AI tramite variabili di ambiente invece della procedura guidata, ad esempio in CI o in un rollout aziendale con script, segui i passaggi di seguito.
1. Abilita Vertex AI API
Abilita Vertex AI API nel tuo progetto GCP:
# Imposta il tuo ID progetto
gcloud config set project YOUR-PROJECT-ID# Abilita Vertex AI API
gcloud services enable aiplatform.googleapis.com
Claude Code v2.1.121 o versioni successive supporta X.509 certificate-based Workload Identity Federation attraverso la stessa catena Application Default Credentials. Imposta GOOGLE_APPLICATION_CREDENTIALS al percorso del tuo file di configurazione delle credenziali.
Configurazione avanzata delle credenziali
Claude Code supporta l'aggiornamento automatico delle credenziali GCP tramite l'impostazione gcpAuthRefresh. Quando Claude Code rileva che le tue credenziali GCP sono scadute o non possono essere caricate, esegue il comando configurato per ottenere nuove credenziali prima di riprovare la richiesta.
L'output del comando viene visualizzato all'utente, ma l'input interattivo non è supportato. Questo funziona bene per i flussi di autenticazione basati su browser in cui la CLI mostra un URL e completi l'autenticazione nel browser. Il comando di aggiornamento scade dopo tre minuti se l'autenticazione non viene completata. Se imposti gcpAuthRefresh nelle impostazioni del progetto come .claude/settings.json, il comando viene eseguito solo dopo che accetti il prompt di fiducia dell'area di lavoro.
4. Configura Claude Code
Imposta le seguenti variabili di ambiente:
# Abilita integrazione Vertex AIexport CLAUDE_CODE_USE_VERTEX=1export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID# Facoltativo: Esegui l'override dell'URL dell'endpoint Vertex per endpoint personalizzati o gateway# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com# Facoltativo: Disabilita prompt caching se necessarioexport DISABLE_PROMPT_CACHING=1# Facoltativo: Richiedi TTL cache prompt di 1 ora invece del valore predefinito di 5 minutiexport ENABLE_PROMPT_CACHING_1H=1# Quando CLOUD_ML_REGION=global, esegui l'override della regione per i modelli che non supportano endpoint globaliexport VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
La maggior parte delle versioni del modello ha una variabile VERTEX_REGION_CLAUDE_* corrispondente. Consulta il riferimento delle variabili di ambiente per l'elenco completo. Controlla Vertex Model Garden per determinare quali modelli supportano endpoint globali rispetto a quelli solo regionali.
Prompt caching è abilitato automaticamente. Per disabilitarlo, imposta DISABLE_PROMPT_CACHING=1. Per richiedere un TTL cache di 1 ora invece del valore predefinito di 5 minuti, imposta ENABLE_PROMPT_CACHING_1H=1; le scritture della cache con TTL di 1 ora vengono fatturate a una tariffa più elevata. Per limiti di velocità aumentati, contatta il supporto di Google Cloud. Quando utilizzi Vertex AI, il comando /logout non è disponibile poiché l'autenticazione è gestita tramite le credenziali di Google Cloud.
Claude Code disabilita MCP tool search per impostazione predefinita su Vertex AI, quindi le definizioni degli strumenti MCP vengono caricate in anticipo. Vertex AI supporta la ricerca degli strumenti per Claude Sonnet 4.5 e versioni successive e Claude Opus 4.5 e versioni successive. Imposta ENABLE_TOOL_SEARCH=true per abilitarla su questi modelli. I modelli precedenti su Vertex AI non accettano l'intestazione beta richiesta e le richieste non riescono se abiliti la ricerca degli strumenti con essi.
5. Fissa le versioni del modello
Imposta queste variabili di ambiente su ID modello Vertex AI specifici.
Senza ANTHROPIC_DEFAULT_OPUS_MODEL, l'alias opus su Vertex si risolve in Opus 4.6. Impostalo sull'ID di Opus 4.8 per utilizzare il modello più recente:
Claude Code utilizza questi modelli predefiniti quando nessuna variabile di fissaggio è impostata:
Tipo di modello
Valore predefinito
Modello primario
claude-sonnet-4-5@20250929
Modello piccolo/veloce
Uguale al modello primario
Le attività in background come la generazione del titolo della sessione utilizzano il modello piccolo/veloce, normalmente un modello della classe Haiku. Su Vertex AI, Claude Code imposta per impostazione predefinita questo al modello primario perché Haiku potrebbe non essere abilitato in ogni progetto o regione. Per utilizzare Haiku per le attività in background, imposta ANTHROPIC_DEFAULT_HAIKU_MODEL su un ID modello disponibile nel tuo progetto.
Quando Claude Code si avvia con Vertex AI configurato, verifica che i modelli che intende utilizzare siano accessibili nel tuo progetto. Questo controllo richiede Claude Code v2.1.98 o versione successiva.
Se hai fissato una versione del modello più vecchia del valore predefinito corrente di Claude Code, e il tuo progetto può invocare la versione più recente, Claude Code ti chiede di aggiornare il fissaggio. Accettare scrive il nuovo ID modello nel tuo file di impostazioni utente e riavvia Claude Code. Rifiutare viene ricordato fino al prossimo cambio di versione predefinita.
Se non hai fissato un modello e il valore predefinito corrente non è disponibile nel tuo progetto, Claude Code ritorna alla versione precedente per la sessione corrente e mostra un avviso. Il ritorno non è persistente. Abilita il modello più recente in Model Garden o fissa una versione per rendere la scelta permanente.
Configurazione IAM
Assegna le autorizzazioni IAM richieste:
Il ruolo roles/aiplatform.user include le autorizzazioni richieste:
aiplatform.endpoints.predict - Richiesto per l'invocazione del modello e il conteggio dei token
Per autorizzazioni più restrittive, crea un ruolo personalizzato con solo le autorizzazioni di cui sopra.
Claude Sonnet 5, Opus 4.6 e versioni successive, e Sonnet 4.6 supportano la finestra di contesto da 1M token su Vertex AI. Sonnet 5 funziona sempre con la finestra da 1M, senza alcuna variante [1m] da selezionare. Per gli altri modelli, Claude Code abilita automaticamente la finestra di contesto estesa quando selezioni una variante di modello 1M.
Controlla le quote attuali o richiedi un aumento della quota tramite Cloud Console
Se riscontri errori "model not found" 404:
Conferma che il modello è abilitato in Model Garden
Verifica che il modello sia disponibile nella posizione che hai specificato. Alcuni modelli sono offerti solo su posizioni global o multi-regione come eu e us, non in regioni specifiche
Se utilizzi CLOUD_ML_REGION=global, controlla che i tuoi modelli supportino endpoint globali in Model Garden in "Supported features". Per i modelli che non supportano endpoint globali, puoi:
Specificare un modello supportato tramite ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_HAIKU_MODEL, oppure
Impostare una regione o una posizione multi-regione utilizzando le variabili di ambiente VERTEX_REGION_<MODEL_NAME>
Se riscontri errori 429:
Per gli endpoint regionali, assicurati che il modello primario e il modello piccolo/veloce siano supportati nella tua regione selezionata
Considera di passare a CLOUD_ML_REGION=global per una migliore disponibilità
290 Finestra di contesto da 1M token290 Finestra di contesto da 1M token
291</h2>291</h2>
292292
293Claude Opus 4.6 e versioni successive, e Sonnet 4.6, supportano la [finestra di contesto da 1M token](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) su Vertex AI. Claude Code abilita automaticamente la finestra di contesto estesa quando selezioni una variante di modello 1M.293Claude Sonnet 5, Opus 4.6 e versioni successive, e Sonnet 4.6 supportano la [finestra di contesto da 1M token](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) su Vertex AI. Sonnet 5 funziona sempre con la finestra da 1M, senza alcuna variante `[1m]` da selezionare. Per gli altri modelli, Claude Code abilita automaticamente la finestra di contesto estesa quando selezioni una variante di modello 1M.
294294
295La [procedura guidata di configurazione](#sign-in-with-vertex-ai) offre un'opzione di contesto 1M quando fissa i modelli. Per abilitarla per un modello fissato manualmente, aggiungi `[1m]` all'ID del modello. Consulta [Fissa i modelli per le distribuzioni di terze parti](/it/model-config#pin-models-for-third-party-deployments) per i dettagli.295La [procedura guidata di configurazione](#sign-in-with-vertex-ai) offre un'opzione di contesto 1M quando fissa i modelli. Per abilitarla per un modello fissato manualmente, aggiungi `[1m]` all'ID del modello. Consulta [Fissa i modelli per le distribuzioni di terze parti](/it/model-config#pin-models-for-third-party-deployments) per i dettagli.
