← Voltar ao blog

Proxies para Gemini CLI e VS Code Code Assist: acesso de regiões sem suporte do Google

Instruções passo a passo para configurar um proxy HTTP/HTTPS para o Gemini CLI e a extensão Gemini Code Assist no VS Code, caso sua região não seja suportada pelo Google.

📅14 de novembro de 2026

Se ao tentar se autenticar no Gemini CLI ou usar a extensão Gemini Code Assist no VS Code você vê um erro como FAILED_PRECONDITION: User location is not supported — o problema não está na sua conta nem no código. O Google AI Studio e o Gemini API estão sendo lançados em países de forma desigual, e algumas regiões simplesmente estão excluídas da lista de suportadas. Isso pode ser resolvido configurando um proxy com um endereço IP de um país permitido — e a seguir vamos ver como fazer isso corretamente no terminal, no VS Code e no nível de variáveis de ambiente.

O que é Gemini CLI e Gemini Code Assist

Gemini CLI é uma ferramenta de console do Google que permite interagir com os modelos Gemini diretamente do terminal: escrever código, gerar comandos, analisar arquivos de projeto e executar tarefas de agente sem sair do ambiente de trabalho. Ele se conecta à API nos domínios generativelanguage.googleapis.com ou através do Vertex AI, dependendo de qual método de autenticação você está usando — chave do Google AI Studio ou conta do Google Cloud.

Gemini Code Assist é uma extensão para VS Code (e também para IDEs da JetBrains) que incorpora sugestões, autocompletar e chat com o modelo diretamente no editor de código. Na essência, é a mesma API, mas chamada da IDE através da extensão, e não da linha de comando. Ambas as ferramentas utilizam o mesmo backend, portanto, o problema de bloqueio regional se manifesta da mesma forma em ambos os casos — a extensão simplesmente não consegue estabelecer uma sessão ou retorna um erro na primeira solicitação ao modelo.

Um detalhe importante: ambas as ferramentas fazem solicitações de rede não apenas à própria API de geração, mas também aos serviços de autenticação do Google (OAuth, Identity Toolkit). Se o proxy estiver configurado apenas para um endpoint, a autenticação pode passar, mas a geração não, ou vice-versa. Portanto, o proxy deve ser configurado no nível das variáveis de ambiente do sistema, e não pontualmente em um único lugar.

Por que o Gemini não está disponível na sua região

O Google tradicionalmente lança novos produtos de IA em etapas: primeiro nos EUA e em parte da Europa, depois nos outros países. Para o Gemini, isso se expressa em restrições geográficas no nível da API — o servidor verifica o endereço IP da solicitação de entrada (e às vezes o endereço de cobrança da conta do Google) e compara com a lista de locais permitidos. Se o país não estiver na lista, a solicitação é interrompida com um erro de precondição ou simplesmente expira sem uma explicação clara.

Isso não é um bloqueio no sentido habitual da palavra — o provedor do seu país não está cortando nada, trata-se de um geo-filtro do lado do Google. Assim, um VPN com IP compartilhado muitas vezes não ajuda: esses endereços são usados em massa por milhares de pessoas, o Google os marca como suspeitos e ou exige um captcha, ou ainda assim corta por geo, se o intervalo de IP estiver formalmente registrado em um país diferente. É necessário um endereço que pareça um IP doméstico ou móvel comum de uma região suportada — ou seja, a tarefa é exatamente a mesma que a que os proxies residenciais e móveis resolvem.

Qual proxy escolher para trabalhar com o Gemini API

Para ferramentas de desenvolvimento como o Gemini CLI, os parâmetros chave do proxy são a estabilidade da sessão (para que a conexão não caia no meio da geração de uma resposta longa), a velocidade e quão "limpo" o IP parece para os sistemas anti-bot do Google. Aqui está uma comparação de três tipos:

Tipo de proxy Velocidade Risco de bloqueio geográfico Quando usar
Proxies de data center Alta Médio-alto Testes rápidos, solicitações únicas à API
Proxies residenciais Média-alta Baixo Trabalho diário com Gemini CLI e Code Assist
Proxies móveis Média Mínimo Quando o IP residencial ainda é bloqueado pelo geo-filtro

Na prática, para o trabalho diário do desenvolvedor, os proxies residenciais com vinculação a um país específico e, de preferência, com uma sessão sticky de 10-30 minutos são os mais convenientes — isso é suficiente para que a autenticação OAuth não caia e a sessão do terminal não se perca no meio da geração de código. Proxies de data center são mais baratos e rápidos, mas alguns intervalos de IP já são conhecidos pelo Google e às vezes exigem verificação adicional da conta ao entrar através de tal IP. É bom ter proxies móveis como reserva — se o endereço residencial, por algum motivo, entrar na lista de suspeitos, a rede móvel do operador geralmente passa pela verificação de geo sem problemas.

Configuração do proxy no terminal: Linux, macOS, Windows

O Gemini CLI, assim como a maioria das utilidades de console em Node.js (e ele é escrito exatamente nele), respeita as variáveis de ambiente padrão HTTP_PROXY e HTTPS_PROXY. Isso é suficiente para redirecionar todo o tráfego do CLI através do proxy sem precisar editar as configurações do aplicativo.

Para macOS e Linux (bash/zsh), adicione à sessão atual:

export HTTP_PROXY="http://login:senha@proxy_host:porta"
export HTTPS_PROXY="http://login:senha@proxy_host:porta"
export NO_PROXY="localhost,127.0.0.1"

gemini --version

Para que o proxy seja aplicado de forma permanente, e não apenas na sessão atual do terminal, adicione essas mesmas linhas ao ~/.zshrc ou ~/.bashrc e reinicie o terminal com o comando source ~/.zshrc.

Para Windows no PowerShell, as variáveis são definidas assim:

$env:HTTP_PROXY = "http://login:senha@proxy_host:porta"
$env:HTTPS_PROXY = "http://login:senha@proxy_host:porta"

gemini --version

Se você quiser que as variáveis sejam mantidas após reiniciar o PowerShell, use [System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://login:senha@proxy_host:porta", "User") — a variável será gravada no perfil do usuário do Windows.

Se o seu proxy exigir autenticação separada sem login na URL (por exemplo, por whitelist de IP), basta remover o login e a senha da string de conexão e adicionar o IP do seu servidor ou máquina de trabalho na whitelist do painel do provedor de proxy.

Configuração do proxy no VS Code para Code Assist

O VS Code possui suas próprias configurações de proxy, que não são herdadas automaticamente das variáveis de ambiente do sistema, a menos que a opção correspondente esteja ativada. Abra settings.json (Ctrl+Shift+P → "Preferências: Abrir Configurações do Usuário (JSON)") e adicione:

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

O parâmetro http.proxySupport: "override" é importante: sem ele, o VS Code pode continuar a usar o proxy do sistema ou ignorar a configuração para extensões específicas. Após editar as configurações, reinicie completamente o VS Code (não apenas reinicie a janela), pois a extensão Gemini Code Assist inicializa o cliente de rede uma vez ao iniciar o aplicativo.

Se a extensão ainda não reconhecer o proxy, verifique a configuração http.proxyAuthorization — em raros casos, versões corporativas do VS Code bloqueiam a transmissão de login e senha na URL do proxy por motivos de segurança, e então as credenciais precisam ser passadas através do cabeçalho Proxy-Authorization em base64.

Um ponto separado — desative temporariamente diagnósticos de extensões como clientes VPN corporativos e antivírus com interceptação de tráfego (inspeção SSL). Eles frequentemente substituem o certificado em tempo real, e o Gemini Code Assist, que verifica rigorosamente a cadeia de certificados do Google, pode interromper a conexão com um erro de TLS, que pode ser confundido com um problema no próprio proxy.

Configuração do proxy no próprio Gemini CLI

Além das variáveis de ambiente, no Gemini CLI você pode definir o proxy através do arquivo de configuração do projeto ou das configurações globais do usuário — isso é conveniente se você quiser usar proxies diferentes para projetos diferentes, sem tocar nas variáveis do sistema. A configuração geralmente é armazenada em ~/.gemini/settings.json ou em um arquivo .env dentro do diretório do projeto:

# .env na raiz do projeto
GEMINI_API_KEY=seu_token
HTTPS_PROXY=http://login:senha@proxy_host:porta
HTTP_PROXY=http://login:senha@proxy_host:porta

Se você se autentica através de uma conta do Google Cloud (Vertex AI), e não através da chave do AI Studio, será necessário que o proxy seja usado também pela ferramenta gcloud, pela qual passa o fluxo OAuth. Para isso, o proxy é definido separadamente:

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

Se após isso gcloud auth login ainda abrir o navegador com o IP real (não proxy) para confirmação de login, tenha em mente que a própria página de OAuth é aberta diretamente no seu navegador do sistema, e se o navegador não estiver configurado para o mesmo proxy, a sessão final de autenticação pode obter um token vinculado ao seu verdadeiro IP. Para total consistência, é recomendável configurar o proxy também no navegador que você usa para confirmar o login — por exemplo, através de uma extensão de proxy ou configurações de rede do sistema durante a autenticação.

Verificação da conexão: curl e Python

Antes de investigar por que o Gemini CLI não está funcionando, verifique se o proxy, em geral, está passando o tráfego para a API do Google. A maneira mais rápida é fazer uma solicitação direta através do curl:

curl -x http://login:senha@proxy_host:porta \
  "https://generativelanguage.googleapis.com/v1beta/models?key=SEU_API_KEY"

Se a resposta retornar um JSON com a lista de modelos (gemini-1.5-flash, gemini-1.5-pro e assim por diante) — o proxy está funcionando e a região é suportada. Se você ver 403 ou FAILED_PRECONDITION — o problema está no nível do filtro geo, é necessário mudar o país do proxy.

Para um diagnóstico mais detalhado, é conveniente usar Python com a especificação explícita do proxy para a sessão:

import requests

proxies = {
    "http": "http://login:senha@proxy_host:porta",
    "https": "http://login:senha@proxy_host:porta",
}

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

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

Esse script é conveniente para ter à mão como uma verificação rápida antes de iniciar uma sessão completa no CLI ou na IDE — ele mostra em poucos segundos se o problema é a rede, a chave ou a própria região do IP.

Erros comuns e suas soluções

Erro "User location is not supported" mesmo após conectar o proxy geralmente significa que o IP do servidor proxy está em um país não suportado ou que o Google o identificou como um IP de data center e aplicou uma verificação adicional. A solução é mudar para um IP residencial ou móvel dos EUA ou de outro país com suporte total ao Gemini.

Timeouts ao gerar respostas longas estão frequentemente relacionados a uma sessão de proxy instável — o IP muda no meio da solicitação, e a conexão é interrompida. É necessária uma sessão sticky por um tempo que exceda a solicitação típica (geralmente 10-15 minutos com uma margem é suficiente mesmo para gerações de código volumosas).

Erro SSL/TLS handshake failed quase sempre indica interceptação de tráfego por um antivírus, firewall corporativo ou configuração incorreta de proxyStrictSSL no VS Code. Verifique se não há software com inspeção SSL na máquina e desative-o temporariamente para diagnóstico.

CLI funciona, mas a extensão no VS Code não (ou vice-versa) significa que as variáveis de ambiente não foram passadas para o processo do VS Code. Essa é uma situação comum no Linux e macOS, se o VS Code foi iniciado de um terminal diferente de onde as variáveis foram exportadas, e sim a partir do ícone no menu do sistema. Nesse caso, as variáveis precisam ser definidas através do settings.json, como descrito acima, e não contar com a herança do shell.

Vinculação de IP à região da chave API e segurança

Um detalhe separado, que muitas vezes é esquecido: se a chave API ou o projeto do Google Cloud foi criado com vinculação a uma região de cobrança específica, mudar o IP do proxy pode levar à discrepância entre a localização esperada e a real, e o Google às vezes exige reautenticação via SMS ou email. Para reduzir a frequência dessas verificações, tente usar proxies com um IP fixo (não rotacionado a cada solicitação) de um mesmo país — isso parece para os sistemas de proteção do Google como um comportamento normal de um usuário que simplesmente vive nesse país, e não como uma atividade suspeita.

Se você está trabalhando com vários projetos ou chaves ao mesmo tempo e usa um navegador anti-detect como Dolphin Anty ou AdsPower para isolar perfis (relevante se você está testando integrações do Gemini em diferentes ambientes de navegador), vincule a cada perfil um proxy separado com geolocalização fixa — assim há menos risco de que um projeto "puxe" suspeitas devido a IPs misturados de outro.

Além disso, não é aconselhável usar o mesmo proxy gratuito ou compartilhado para Gemini e ao mesmo tempo para outras tarefas de alta carga — um grande número de sessões paralelas de um único IP aumenta a chance de ser colocado sob rate-limit ou bloqueio temporário no nível do Google, o que parece também um problema de região, embora a causa seja completamente diferente.

Conclusão

A limitação do Gemini CLI e Gemini Code Assist por região é resolvida no nível da rede: o proxy deve ser configurado simultaneamente nas variáveis de ambiente do sistema, nas configurações do VS Code e, ao usar o Google Cloud, na configuração do gcloud — somente então todos os três pontos de entrada (CLI, extensão IDE e autenticação OAuth) funcionarão através do mesmo IP sem desincronização. Antes de começar a trabalhar de forma completa, sempre verifique a conexão com uma simples solicitação curl — isso economiza horas de diagnóstico quando o problema na verdade não está no código, mas no país do proxy.

Para um trabalho diário estável com o Gemini CLI, os proxies residenciais com geolocalização fixa e uma longa sessão sticky são os mais adequados — eles parecem um IP doméstico comum e raramente provocam verificações adicionais do Google. Se o endereço residencial ainda assim for bloqueado pelo geo-filtro, vale a pena tentar proxies móveis, e para testes rápidos e únicos da API sem uma longa sessão, os proxies de data center são mais do que suficientes.