​
Pré-requisitos

Antes de configurar o Claude Code com Vertex AI, certifique-se de ter:

  • Uma conta do Google Cloud Platform (GCP) com faturamento habilitado
  • Um projeto GCP com API Vertex AI habilitada
  • Acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4)
  • Google Cloud SDK (gcloud) instalado e configurado
  • Cota alocada na região GCP desejada

​
Configuração de Região

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. Habilitar API Vertex AI

Habilite a API Vertex AI no seu projeto GCP:

# Defina seu ID do projeto
gcloud config set project SEU-ID-DO-PROJETO

# Habilite a 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. Pesquise por modelos “Claude”
  3. Solicite acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4)
  4. Aguarde aprovação (pode levar 24-48 horas)

​
3. Configurar credenciais GCP

O 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, o Claude Code usará automaticamente o ID do projeto da variável de ambiente ANTHROPIC_VERTEX_PROJECT_ID. Para sobrescrever isso, defina uma dessas variáveis de ambiente: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, ou GOOGLE_APPLICATION_CREDENTIALS.

​
4. Configurar Claude Code

Defina as seguintes variáveis de ambiente:

# Habilitar integração Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=SEU-ID-DO-PROJETO

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

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

# Opcional: Sobrescrever 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 desabilitá-lo, defina DISABLE_PROMPT_CACHING=1. Para limites de taxa elevados, entre em contato com o suporte do Google Cloud.

Ao usar Vertex AI, os comandos /login e /logout são desabilitados, pois a autenticação é tratada através das credenciais do Google Cloud.

​
5. Configuração do modelo

O Claude Code usa estes modelos padrão para Vertex AI:

Tipo de modeloValor padrão
Modelo primárioclaude-sonnet-4@20250514
Modelo pequeno/rápidoclaude-3-5-haiku@20241022

Para personalizar modelos:

export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
Configuração IAM

Atribua as permissões IAM necessárias:

O papel roles/aiplatform.user inclui as permissões necessárias:

  • aiplatform.endpoints.predict - Necessário para invocação do modelo
  • aiplatform.endpoints.computeTokens - Necessário para contagem de tokens

Para permissões mais restritivas, crie um papel personalizado apenas com as permissões acima.

Para detalhes, consulte a documentação IAM do Vertex.

Recomendamos criar um projeto GCP dedicado para o Claude Code para simplificar o rastreamento de custos e controle de acesso.

​
Janela de contexto de 1M tokens

O Claude Sonnet 4 suporta a janela de contexto de 1M tokens no Vertex AI.

A janela de contexto de 1M tokens está atualmente em beta. Para usar a janela de contexto estendida, inclua o cabeçalho beta context-1m-2025-08-07 nas suas solicitações Vertex AI.

​
Soluçã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 404 de “modelo não encontrado”:

  • Confirme que o modelo está Habilitado no Model Garden
  • Verifique se você tem acesso à região especificada
  • Se usando CLOUD_ML_REGION=global, verifique se seus modelos suportam endpoints globais no Model Garden sob “Recursos suportados”. Para modelos que não suportam endpoints globais, ou:
    • Especifique um modelo suportado via ANTHROPIC_MODEL ou ANTHROPIC_SMALL_FAST_MODEL, ou
    • Defina um endpoint regional usando variáveis de ambiente VERTEX_REGION_<NOME_DO_MODELO>

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 na sua região selecionada
  • Considere mudar para CLOUD_ML_REGION=global para melhor disponibilidade

​
Recursos adicionais