← Torna al blog

Proxy per Gemini CLI e VS Code Code Assist: accesso da regioni senza supporto Google

Guida passo passo per configurare un proxy HTTP/HTTPS per Gemini CLI e l'estensione Gemini Code Assist in VS Code, se la tua regione non è supportata da Google.

📅14 novembre 2026

Se durante il tentativo di autenticarti in Gemini CLI o di utilizzare l'estensione Gemini Code Assist in VS Code vedi un errore come FAILED_PRECONDITION: User location is not supported — il problema non è nel tuo account e nemmeno nel codice. Google AI Studio e Gemini API vengono distribuiti in modo non uniforme tra i paesi, e alcune regioni sono semplicemente escluse dalla lista di supporto. Questo si risolve configurando un proxy con un indirizzo IP proveniente da un paese autorizzato — e di seguito vedremo come farlo correttamente nel terminale, in VS Code e a livello di variabili d'ambiente.

Cos'è Gemini CLI e Gemini Code Assist

Gemini CLI è uno strumento da console di Google che consente di interagire con i modelli Gemini direttamente dal terminale: scrivere codice, generare comandi, analizzare file di progetto e svolgere compiti agenti senza uscire dall'ambiente di lavoro. Si collega all'API sui domini generativelanguage.googleapis.com o tramite Vertex AI, a seconda del metodo di autenticazione che utilizzi — chiave di Google AI Studio o account Google Cloud.

Gemini Code Assist è un'estensione per VS Code (e anche per JetBrains IDE) che integra suggerimenti, completamento automatico e chat con il modello direttamente nell'editor di codice. In sostanza, è la stessa API, ma richiamata dall'IDE tramite l'estensione, e non dalla riga di comando. Entrambi gli strumenti utilizzano lo stesso backend, quindi il problema del blocco regionale si manifesta in modo simile in entrambi i casi: l'estensione semplicemente non riesce a stabilire una sessione o restituisce un errore alla prima richiesta al modello.

Un aspetto importante: entrambi gli strumenti effettuano richieste di rete non solo all'API di generazione, ma anche ai servizi di autorizzazione di Google (OAuth, Identity Toolkit). Se il proxy è configurato solo per un endpoint, l'autenticazione può andare a buon fine, ma la generazione no, o viceversa. Pertanto, il proxy deve essere configurato a livello di variabili d'ambiente di sistema, e non in un singolo punto.

Perché Gemini non è disponibile nella tua regione

Google distribuisce tradizionalmente i nuovi prodotti AI in modo graduale: prima negli Stati Uniti e in parte dell'Europa, poi negli altri paesi. Per Gemini, questo si traduce in limitazioni geografiche a livello di API: il server verifica l'indirizzo IP della richiesta in ingresso (e a volte anche l'indirizzo di fatturazione dell'account Google) e lo confronta con l'elenco delle posizioni autorizzate. Se il paese non è nell'elenco, la richiesta viene interrotta con un errore di precondizione o semplicemente scade senza una spiegazione chiara.

Questo non è un blocco nel senso tradizionale del termine: il provider del tuo paese non sta bloccando nulla, si tratta di un geo-filtro da parte di Google. Di conseguenza, un VPN con un IP condiviso spesso non aiuta: tali indirizzi sono utilizzati da migliaia di persone, Google li contrassegna come sospetti e richiede un captcha, oppure li blocca comunque per geo, se l'intervallo di IP è formalmente registrato in un altro paese. Serve un indirizzo che appaia come un normale IP domestico o mobile da una regione supportata — quindi il compito è esattamente quello che risolvono i proxy residenziali e mobili.

Quale proxy scegliere per lavorare con Gemini API

Per strumenti di sviluppo come Gemini CLI, i parametri chiave del proxy sono la stabilità della sessione (per evitare che la connessione si interrompa durante la generazione di una lunga risposta), la velocità e quanto "pulito" appare l'IP per i sistemi anti-frode di Google. Ecco un confronto tra tre tipi:

Tipo di proxy Velocità Rischio di geo-blocco Quando utilizzare
Proxy data center Alta Medio-alto Test rapidi, richieste singole all'API
Proxy residenziali Media-alta Basso Lavoro quotidiano con Gemini CLI e Code Assist
Proxy mobili Media Minimo Quando l'IP residenziale viene comunque bloccato dal geo-filtro

Nella pratica, per il lavoro quotidiano dello sviluppatore, i proxy residenziali con associazione a un paese specifico e preferibilmente con sessioni sticky di 10-30 minuti sono i più comodi — questo è sufficiente per evitare che l'autenticazione OAuth si interrompa e che la sessione del terminale venga persa durante la generazione del codice. I proxy dei data center sono più economici e veloci, ma alcuni intervalli di Google sono già conosciuti e a volte richiedono una verifica aggiuntiva dell'account quando si accede tramite tale IP. È utile tenere i proxy mobili di riserva — se l'indirizzo residenziale viene in qualche modo inserito nella lista dei sospetti, la rete mobile dell'operatore di solito supera il controllo geo senza problemi.

Configurazione del proxy nel terminale: Linux, macOS, Windows

Gemini CLI, come la maggior parte delle utility da console su Node.js (che è scritto proprio su di esso), rispetta le variabili d'ambiente standard HTTP_PROXY e HTTPS_PROXY. Questo è sufficiente per instradare tutto il traffico CLI attraverso il proxy senza modificare le configurazioni dell'applicazione.

Per macOS e Linux (bash/zsh) aggiungi nella sessione corrente:

export HTTP_PROXY="http://login:password@proxy_host:port"
export HTTPS_PROXY="http://login:password@proxy_host:port"
export NO_PROXY="localhost,127.0.0.1"

gemini --version

Per rendere il proxy permanente, e non solo per la sessione corrente del terminale, aggiungi queste righe in ~/.zshrc o ~/.bashrc e riavvia il terminale con il comando source ~/.zshrc.

Per Windows in PowerShell le variabili si impostano così:

$env:HTTP_PROXY = "http://login:password@proxy_host:port"
$env:HTTPS_PROXY = "http://login:password@proxy_host:port"

gemini --version

Se desideri che le variabili vengano mantenute dopo il riavvio di PowerShell, utilizza [System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://login:password@proxy_host:port", "User") — la variabile verrà registrata nel profilo utente di Windows.

Se il tuo proxy richiede un'autenticazione separata senza login nell'URL (ad esempio, tramite IP whitelist), basta rimuovere il login e la password dalla stringa di connessione e aggiungere l'IP del tuo server o della tua macchina di lavoro nella whitelist sul pannello del fornitore di proxy.

Configurazione del proxy in VS Code per Code Assist

VS Code ha le proprie impostazioni proxy, che non vengono ereditate automaticamente dalle variabili d'ambiente di sistema, a meno che non sia attivata l'opzione corrispondente. Apri settings.json (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)") e aggiungi:

{
  "http.proxy": "http://login:password@proxy_host:port",
  "http.proxyStrictSSL": false,
  "http.proxySupport": "override"
}

Il parametro http.proxySupport: "override" è importante: senza di esso, VS Code potrebbe continuare a utilizzare il proxy di sistema o ignorare completamente l'impostazione per singole estensioni. Dopo aver modificato le impostazioni, riavvia completamente VS Code (non semplicemente riavviare la finestra), poiché l'estensione Gemini Code Assist inizializza il client di rete una sola volta all'avvio dell'applicazione.

Se l'estensione non rileva comunque il proxy, controlla l'impostazione http.proxyAuthorization — in rari casi, le versioni aziendali di VS Code bloccano la trasmissione di login e password nell'URL del proxy per motivi di sicurezza, e in tal caso le credenziali devono essere trasmesse tramite l'intestazione Proxy-Authorization in base64.

Un'altra questione è disattivare temporaneamente le estensioni di diagnostica come i client VPN aziendali e gli antivirus con intercettazione del traffico (ispezione SSL). Spesso sostituiscono il certificato al volo, e Gemini Code Assist, che verifica rigorosamente la catena di certificati di Google, interromperà la connessione con un errore TLS, che può essere facilmente confuso con un problema del proxy stesso.

Configurazione del proxy in Gemini CLI

Oltre alle variabili d'ambiente, in Gemini CLI puoi impostare il proxy tramite il file di configurazione del progetto o delle impostazioni globali dell'utente — questo è comodo se desideri utilizzare proxy diversi per progetti diversi senza toccare le variabili di sistema. La configurazione di solito si trova in ~/.gemini/settings.json o nel file .env all'interno della directory del progetto:

# .env nella radice del progetto
GEMINI_API_KEY=la_tua_chiave
HTTPS_PROXY=http://login:password@proxy_host:port
HTTP_PROXY=http://login:password@proxy_host:port

Se ti autentichi tramite un account Google Cloud (Vertex AI), e non tramite una chiave di AI Studio, è necessario che il proxy venga utilizzato anche dallo strumento gcloud, attraverso il quale passa il flusso OAuth. Per questo, il proxy deve essere impostato separatamente:

gcloud config set proxy/type http
gcloud config set proxy/address proxy_host
gcloud config set proxy/port port
gcloud config set proxy/username login
gcloud config set proxy/password password

Se dopo questo gcloud auth login apre comunque il browser con l'IP reale (non proxy) per confermare l'accesso, tieni presente che la pagina OAuth si apre direttamente nel tuo browser di sistema, e se il browser non è impostato sullo stesso proxy, la sessione finale di autenticazione potrebbe ricevere un token associato al tuo vero IP. Per una completa coerenza, è consigliabile configurare il proxy anche nel browser che utilizzi per confermare l'accesso — ad esempio, tramite un'estensione proxy o le impostazioni di rete di sistema durante l'autenticazione.

Verifica della connessione: curl e Python

Prima di capire perché Gemini CLI non funziona, assicurati che il proxy instradi effettivamente il traffico verso l'API di Google. Il modo più veloce è effettuare una richiesta diretta tramite curl:

curl -x http://login:password@proxy_host:port \
  "https://generativelanguage.googleapis.com/v1beta/models?key=LA_TUA_API_KEY"

Se ricevi in risposta un JSON con l'elenco dei modelli (gemini-1.5-flash, gemini-1.5-pro e così via) — il proxy funziona e la regione è supportata. Se vedi 403 o FAILED_PRECONDITION — il problema è a livello di geo-filtro, è necessario cambiare paese al proxy.

Per una diagnosi più dettagliata, è comodo utilizzare Python specificando esplicitamente il proxy per la sessione:

import requests

proxies = {
    "http": "http://login:password@proxy_host:port",
    "https": "http://login:password@proxy_host:port",
}

url = "https://generativelanguage.googleapis.com/v1beta/models"
params = {"key": "LA_TUA_API_KEY"}

response = requests.get(url, params=params, proxies=proxies, timeout=15)
print(response.status_code)
print(response.text[:500])

Questo script è comodo da tenere a portata di mano come verifica rapida prima di avviare una sessione completa in CLI o IDE — mostra in pochi secondi se il problema è nella rete, nella chiave o nella regione IP stessa.

Errori comuni e loro soluzione

Errore "User location is not supported" anche dopo aver connesso il proxy di solito significa che l'IP del server proxy si trova in un paese non supportato, oppure Google lo ha identificato come data center e ha applicato un controllo aggiuntivo. La soluzione è passare a un IP residenziale o mobile dagli Stati Uniti o da un altro paese con pieno supporto per Gemini.

Timeout durante la generazione di risposte lunghe sono spesso legati a sessioni instabili del proxy — l'IP cambia durante la richiesta e la connessione si interrompe. È necessaria una sessione sticky per un tempo superiore alla richiesta tipica (di solito 10-15 minuti di riserva sono sufficienti anche per generazioni di codice voluminoso).

Errore SSL/TLS handshake failed quasi sempre indica un'intercettazione del traffico da parte di un antivirus, firewall aziendale o una configurazione errata di proxyStrictSSL in VS Code. Controlla se sul computer è installato un software con ispezione SSL e disattivalo temporaneamente per la diagnosi.

CLI funziona, ma l'estensione in VS Code no (o viceversa) significa che le variabili d'ambiente non sono state propagate nel processo di VS Code. Questa è una situazione comune in Linux e macOS, se VS Code è stato avviato non dal terminale in cui sono state esportate le variabili, ma dall'icona nel menu di sistema. In tal caso, le variabili devono essere impostate tramite settings.json, come descritto sopra, e non fare affidamento sull'ereditarietà dalla shell.

Associazione IP alla regione della chiave API e sicurezza

Un aspetto particolare, spesso dimenticato: se la chiave API o il progetto Google Cloud è stato creato con associazione a una specifica regione di fatturazione, il cambio di IP del proxy può portare a una discrepanza tra la posizione attesa e quella effettiva, e Google a volte richiede una nuova verifica tramite SMS o email. Per ridurre la frequenza di tali controlli, cerca di utilizzare proxy con IP costante (non ruotato ad ogni richiesta) dallo stesso paese — questo appare per i sistemi di protezione di Google come un comportamento normale di un utente che vive semplicemente in quel paese, e non come un'attività sospetta.

Se lavori su più progetti o chiavi contemporaneamente e utilizzi un browser anti-detect come Dolphin Anty o AdsPower per isolare i profili (rilevante se stai testando integrazioni Gemini in diversi ambienti browser), associa a ogni profilo un proxy separato con geolocalizzazione fissa — così si riduce il rischio che un progetto "trascini" sospetti a causa di IP misti di un altro.

Inoltre, non utilizzare lo stesso proxy gratuito o condiviso per Gemini e contemporaneamente per altre attività ad alta intensità — un numero elevato di sessioni parallele da un IP aumenta la possibilità di incorrere in rate-limit o blocchi temporanei a livello di Google, il che appare come un problema di regione, anche se la causa è completamente diversa.

Conclusione

La limitazione di Gemini CLI e Gemini Code Assist per regione si risolve a livello di rete: il proxy deve essere configurato contemporaneamente nelle variabili d'ambiente di sistema, nelle impostazioni di VS Code e, se utilizzi Google Cloud, nella configurazione di gcloud — solo allora tutti e tre i punti di ingresso (CLI, estensione IDE e autorizzazione OAuth) funzioneranno attraverso lo stesso IP senza disallineamenti. Prima di iniziare a lavorare, verifica sempre la connessione con una semplice richiesta curl — questo risparmia ore di diagnosi quando il problema non è realmente nel codice, ma nel paese del proxy.

Per un lavoro quotidiano stabile con Gemini CLI, i proxy residenziali con geolocalizzazione fissa e sessioni sticky prolungate sono i più adatti — appaiono come un normale IP domestico e raramente richiedono verifiche aggiuntive da parte di Google. Se l'indirizzo residenziale viene comunque bloccato dal geo-filtro, vale la pena provare i proxy mobili, mentre per test rapidi e singoli dell'API senza una lunga sessione, i proxy dei data center sono più che sufficienti.