​
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 do 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

O Vertex AI pode não suportar os modelos padrão do Claude Code em regiões que não sejam us-east5. Certifique-se de estar usando us-east5 e ter cota alocada, ou mude para modelos suportados.

​
Configuração

​
1. Habilitar API do Vertex AI

Habilite a API do Vertex AI em seu projeto GCP:

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

# Habilite a API do 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 substituir 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 com Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=SEU-ID-DO-PROJETO

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

# Opcional: Substituir regiões para modelos específicos
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
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-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4

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 principalclaude-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:

A função roles/aiplatform.user inclui as permissões necessárias:

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

Para permissões mais restritivas, crie uma função personalizada 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.

​
Solução de problemas

Se você encontrar problemas de cota:

  • Verifique as cotas atuais ou solicite aumento de cota através do Cloud Console

Se você encontrar erros 404 de “modelo não encontrado”:

  • Verifique se você tem acesso à região especificada
  • Confirme se o modelo está Habilitado no Model Garden

Se você encontrar erros 429:

  • Certifique-se de que o modelo principal e o modelo pequeno/rápido são suportados em sua região selecionada

​
Recursos adicionais