> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Claude Code su Google Vertex AI > Scopri come configurare Claude Code tramite Google Vertex AI, inclusa la configurazione, la configurazione IAM e la risoluzione dei problemi. export const ContactSalesCard = ({surface}) => { const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`; const iconArrowRight = (size = 13) => ; const STYLES = ` .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } } `; return
Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.
View plans Contact sales {iconArrowRight()}
; };

Prerequisiti

Prima di configurare Claude Code con Vertex AI, assicurati di avere: * Un account Google Cloud Platform (GCP) con fatturazione abilitata * Un progetto GCP con Vertex AI API abilitata * Accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6) * Google Cloud SDK (`gcloud`) installato e configurato * Quota allocata nella regione GCP desiderata Per accedere con le tue credenziali Vertex AI, segui [Accedi con Vertex AI](#sign-in-with-vertex-ai) di seguito. Per distribuire Claude Code in un team, utilizza i passaggi di [configurazione manuale](#set-up-manually) e [fissa le versioni del tuo modello](#5-pin-model-versions) prima del rollout.

Accedi con Vertex AI

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. La procedura guidata di configurazione di Vertex AI richiede Claude Code v2.1.98 o versione successiva. Esegui `claude --version` per verificare. [Abilita Vertex AI API](#1-enable-vertex-ai-api) per il tuo progetto, quindi richiedi accesso ai modelli Claude che desideri in [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden). Consulta [Configurazione IAM](#iam-configuration) per le autorizzazioni di cui il tuo account ha bisogno. Esegui `claude`. Al prompt di accesso, seleziona **3rd-party platform**, quindi **Google Vertex AI**. 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](/it/settings), 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](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai), 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. Vertex AI potrebbe non supportare i modelli predefiniti di Claude Code su ogni tipo di endpoint. La disponibilità del modello varia tra [regioni specifiche](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), posizioni multi-regione e [endpoint globali](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). Potrebbe essere necessario passare a una posizione supportata o specificare un modello supportato.

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: ```bash theme={null} # Imposta il tuo ID progetto gcloud config set project YOUR-PROJECT-ID # Abilita Vertex AI API gcloud services enable aiplatform.googleapis.com ```

2. Richiedi accesso al modello

Richiedi accesso ai modelli Claude in Vertex AI: 1. Accedi a [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 2. Cerca i modelli "Claude" 3. Richiedi accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6) 4. Attendi l'approvazione (potrebbe richiedere 24-48 ore)

3) Configura le credenziali GCP

Claude Code utilizza l'autenticazione standard di Google Cloud. Per ulteriori informazioni, consulta la [documentazione di autenticazione di Google Cloud](https://cloud.google.com/docs/authentication). Claude Code v2.1.121 o versioni successive supporta [X.509 certificate-based Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) attraverso la stessa catena Application Default Credentials. Imposta `GOOGLE_APPLICATION_CREDENTIALS` al percorso del tuo file di configurazione delle credenziali. Claude Code utilizza `ANTHROPIC_VERTEX_PROJECT_ID` come ID progetto per le richieste Vertex AI. Le variabili di ambiente `GCLOUD_PROJECT` e `GOOGLE_CLOUD_PROJECT` e il file di credenziali a cui fa riferimento `GOOGLE_APPLICATION_CREDENTIALS` hanno la precedenza su di esso. Se nessuno di questi è impostato, l'ID progetto viene risolto dalla tua configurazione `gcloud` o dall'account di servizio collegato.

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. ```json theme={null} { "gcpAuthRefresh": "gcloud auth application-default login", "env": { "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id" } } ``` 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: ```bash theme={null} # Abilita integrazione Vertex AI export CLAUDE_CODE_USE_VERTEX=1 export 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 necessario export DISABLE_PROMPT_CACHING=1 # Facoltativo: Richiedi TTL cache prompt di 1 ora invece del valore predefinito di 5 minuti export ENABLE_PROMPT_CACHING_1H=1 # Quando CLOUD_ML_REGION=global, esegui l'override della regione per i modelli che non supportano endpoint globali export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5 export 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](/it/env-vars) per l'elenco completo. Controlla [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) per determinare quali modelli supportano endpoint globali rispetto a quelli solo regionali. [Prompt caching](/it/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](/it/mcp#scale-with-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

Fissa versioni specifiche del modello quando distribuisci a più utenti. Senza fissaggio, gli alias di modello come `sonnet` e `opus` si risolvono nel valore predefinito integrato di Claude Code per Vertex AI, che può essere in ritardo rispetto alla versione più recente e potrebbe non essere ancora abilitato nel tuo progetto. Claude Code [ritorna](#startup-model-checks) alla versione precedente all'avvio quando il valore predefinito non è disponibile, ma il fissaggio ti consente di controllare quando i tuoi utenti passano a un nuovo 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: ```bash theme={null} export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8' export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5' export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001' ``` Per gli ID modello attuali e legacy, consulta [Panoramica dei modelli](https://platform.claude.com/docs/en/about-claude/models/overview). Consulta [Configurazione del modello](/it/model-config#pin-models-for-third-party-deployments) per l'elenco completo delle variabili di ambiente. 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. Per personalizzare ulteriormente i modelli: ```bash theme={null} export ANTHROPIC_MODEL='claude-opus-4-8' export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001' ```

Controlli del modello all'avvio

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](/it/settings) 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](https://console.cloud.google.com/vertex-ai/model-garden) o [fissa una versione](#5-pin-model-versions) 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. Per i dettagli, consulta la [documentazione IAM di Vertex](https://cloud.google.com/vertex-ai/docs/general/access-control). Crea un progetto GCP dedicato per Claude Code per semplificare il tracciamento dei costi e il controllo degli accessi.

Finestra di contesto da 1M token

Claude 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. La [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.

Risoluzione dei problemi

Se riscontri errori "Could not load the default credentials": * Esegui `gcloud auth application-default login` per configurare le credenziali predefinite dell'applicazione * Imposta `GOOGLE_APPLICATION_CREDENTIALS` su un percorso di file della chiave dell'account di servizio * Vedi [Configure GCP credentials](#3-configure-gcp-credentials) per tutte le opzioni Se riscontri problemi di quota: * Controlla le quote attuali o richiedi un aumento della quota tramite [Cloud Console](https://cloud.google.com/docs/quotas/view-manage) Se riscontri errori "model not found" 404: * Conferma che il modello è abilitato in [Model Garden](https://console.cloud.google.com/vertex-ai/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](https://console.cloud.google.com/vertex-ai/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_` 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à

Risorse aggiuntive

* [Documentazione di Vertex AI](https://cloud.google.com/vertex-ai/docs) * [Prezzi di Vertex AI](https://cloud.google.com/vertex-ai/pricing) * [Quote e limiti di Vertex AI](https://cloud.google.com/vertex-ai/docs/quotas)