​
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

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 Vertex AI

Habilite a API Vertex AI em seu projeto GCP:

# Defina seu ID do projeto
gcloud config set project YOUR-PROJECT-ID

# 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 documentação de autenticação do Google Cloud.

​
4. Configurar Claude Code

Defina as seguintes variáveis de ambiente:

# Habilite integração Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Desabilite cache de prompt se não estiver habilitado
export DISABLE_PROMPT_CACHING=1

Para limites de taxa elevados e habilitação de cache de prompt, entre em contato com o suporte do Google Cloud. Uma vez habilitado, remova a configuração DISABLE_PROMPT_CACHING.

​
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@20250514'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
Configuração IAM

Conceda as funções IAM necessárias para o Claude Code.

Para detalhes, consulte 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 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