Pular para o conteúdo principal

​
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 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 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 a flag efêmera 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 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 header beta context-1m-2025-08-07 em suas solicitações do Vertex AI.

​
Resolução de problemas

Se você encontrar problemas de cota:
  • Verifique cotas atuais ou solicite 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