​
Pré-requisitos

Antes de configurar Claude Code com Vertex AI, certifique-se de que você tem:
  • Uma conta do Google Cloud Platform (GCP) com faturamento ativado
  • Um projeto GCP com a API Vertex AI ativada
  • Acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4.5)
  • Google Cloud SDK (gcloud) instalado e configurado
  • Cota alocada na região GCP desejada

​
Configuração de Região

Claude Code pode ser usado com endpoints globais e regionais do Vertex AI.
O Vertex AI pode não suportar os modelos padrão do Claude Code em todas as regiões. Você pode precisar mudar para uma região ou modelo suportado.
O Vertex AI pode não suportar os modelos padrão do Claude Code em endpoints globais. Você pode precisar mudar para um endpoint regional ou modelo suportado.

​
Configuração

​
1. Ativar a API Vertex AI

Ative a API Vertex AI em seu projeto GCP: 
# Defina seu ID de projeto
gcloud config set project YOUR-PROJECT-ID

# Ativar API Vertex AI
gcloud services enable aiplatform.googleapis.com

​
2. Solicitar acesso ao modelo

Solicite acesso aos modelos Claude no Vertex AI:
  1. Navegue até o Vertex AI Model Garden
  2. Procure por modelos “Claude”
  3. Solicite acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4.5)
  4. Aguarde a aprovação (pode levar 24-48 horas)

​
3. Configurar credenciais GCP

Claude Code usa autenticação padrão do Google Cloud. Para mais informações, consulte a documentação de autenticação do Google Cloud.
Ao autenticar, Claude Code usará automaticamente o ID do projeto da variável de ambiente ANTHROPIC_VERTEX_PROJECT_ID. Para substituir isso, defina uma destas variáveis de ambiente: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT ou GOOGLE_APPLICATION_CREDENTIALS.

​
4. Configurar Claude Code

Defina as seguintes variáveis de ambiente: 
# Ativar integração Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Desativar cache de prompt se necessário
export DISABLE_PROMPT_CACHING=1

# Quando CLOUD_ML_REGION=global, substituir região para modelos não suportados
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Opcional: Substituir regiões para outros modelos específicos
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
Cache de prompt é automaticamente suportado quando você especifica o sinalizador efêmero cache_control. Para desativá-lo, defina DISABLE_PROMPT_CACHING=1. Para limites de taxa aumentados, entre em contato com o suporte do Google Cloud.
Ao usar Vertex AI, os comandos /login e /logout são desativados, pois a autenticação é tratada através de credenciais do Google Cloud.

​
5. Configuração de modelo

Claude Code usa estes modelos padrão para Vertex AI:
Tipo de modeloValor padrão
Modelo primárioclaude-sonnet-4-5@20250929
Modelo pequeno/rápidoclaude-haiku-4-5@20251001
Para usuários do Vertex AI, Claude Code não será atualizado automaticamente de Haiku 3.5 para Haiku 4.5. Para mudar manualmente para um modelo Haiku mais recente, defina a variável de ambiente ANTHROPIC_DEFAULT_HAIKU_MODEL para o nome completo do modelo (por exemplo, claude-haiku-4-5@20251001).
Para personalizar modelos: 
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
Configuração de IAM

Atribua as permissões de IAM necessárias: A função roles/aiplatform.user inclui as permissões necessárias:
  • aiplatform.endpoints.predict - Necessário para invocação de modelo e contagem de tokens
Para permissões mais restritivas, crie uma função personalizada com apenas as permissões acima. Para detalhes, consulte a documentação de IAM do Vertex.
Recomendamos criar um projeto GCP dedicado para Claude Code para simplificar o rastreamento de custos e controle de acesso.

​
Janela de contexto de 1M de tokens

Claude Sonnet 4 e Sonnet 4.5 suportam a janela de contexto de 1M de tokens no Vertex AI.
A janela de contexto de 1M de tokens está atualmente em beta. Para usar a janela de contexto estendida, inclua o cabeçalho beta context-1m-2025-08-07 em suas solicitações do Vertex AI.

​
Resolução de problemas

Se você encontrar problemas de cota:
  • Verifique as cotas atuais ou solicite um aumento de cota através do Cloud Console
Se você encontrar erros “modelo não encontrado” 404:
  • Confirme que o modelo está Ativado no Model Garden
  • Verifique se você tem acesso à região especificada
  • Se estiver usando CLOUD_ML_REGION=global, verifique se seus modelos suportam endpoints globais no Model Garden em “Recursos suportados”. Para modelos que não suportam endpoints globais, faça um dos seguintes:
    • Especifique um modelo suportado via ANTHROPIC_MODEL ou ANTHROPIC_SMALL_FAST_MODEL, ou
    • Defina um endpoint regional usando variáveis de ambiente VERTEX_REGION_<MODEL_NAME>
Se você encontrar erros 429:
  • Para endpoints regionais, certifique-se de que o modelo primário e o modelo pequeno/rápido são suportados em sua região selecionada
  • Considere mudar para CLOUD_ML_REGION=global para melhor disponibilidade

​
Recursos adicionais