Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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.6)
  • Google Cloud SDK (gcloud) instalado e configurado
  • Cota alocada na região GCP desejada
Para entrar com suas próprias credenciais do Vertex AI, siga Entrar com Vertex AI abaixo. Para implantar Claude Code em toda uma equipe, use as etapas de configuração manual e fixe suas versões de modelo antes de fazer o lançamento.

​
Entrar com Vertex AI

Se você tem credenciais do Google Cloud e deseja começar a usar Claude Code através do Vertex AI, o assistente de login o guia através disso. Você completa os pré-requisitos do lado do GCP uma vez por projeto; o assistente cuida do lado do Claude Code.
O assistente de configuração do Vertex AI requer Claude Code v2.1.98 ou posterior. Execute claude --version para verificar.
1

Ativar modelos Claude no seu projeto GCP

Ative a API Vertex AI para seu projeto, depois solicite acesso aos modelos Claude que você deseja no Vertex AI Model Garden. Veja Configuração de IAM para as permissões que sua conta precisa.
2

Inicie Claude Code e escolha Vertex AI

Execute claude. No prompt de login, selecione plataforma de terceiros, depois Google Vertex AI.
3

Siga os prompts do assistente

Escolha como você se autentica no Google Cloud: Application Default Credentials do gcloud, um arquivo de chave de conta de serviço, ou credenciais já em seu ambiente. O assistente detecta seu projeto e região, verifica quais modelos Claude seu projeto pode invocar, e permite que você os fixe. Ele salva o resultado no bloco env do seu arquivo de configurações do usuário, para que você não precise exportar variáveis de ambiente você mesmo.
Depois de entrar, execute /setup-vertex a qualquer momento para reabrir o assistente e alterar suas credenciais, projeto, região ou fixações de modelo.

​
Configuração de região

Claude Code suporta endpoints globais, multi-região e regionais do Vertex AI. Defina CLOUD_ML_REGION como global, um local multi-região como eu ou us, ou uma região específica como us-east5. Claude Code seleciona o nome de host correto do Vertex AI para cada formulário, incluindo os hosts aiplatform.eu.rep.googleapis.com e aiplatform.us.rep.googleapis.com para locais multi-região.
Vertex AI pode não suportar os modelos padrão do Claude Code em todos os tipos de endpoint. A disponibilidade de modelos varia entre regiões específicas, locais multi-região e endpoints globais. Você pode precisar mudar para um local suportado ou especificar um modelo suportado.

​
Configurar manualmente

Para configurar Vertex AI através de variáveis de ambiente em vez do assistente, por exemplo em CI ou um lançamento empresarial com script, siga as etapas abaixo.

​
1. Ativar a API Vertex AI

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

# Ativar 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. Procure por modelos “Claude”
  3. Solicite acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4.6)
  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. Claude Code v2.1.121 ou posterior suporta Federação de Identidade de Carga de Trabalho baseada em certificado X.509 através da mesma cadeia de Credenciais Padrão da Aplicação. Defina GOOGLE_APPLICATION_CREDENTIALS para o caminho do seu arquivo de configuração de credenciais.
Claude Code usa ANTHROPIC_VERTEX_PROJECT_ID como o ID do projeto para solicitações Vertex AI. As variáveis de ambiente GCLOUD_PROJECT e GOOGLE_CLOUD_PROJECT e o arquivo de credenciais referenciado por GOOGLE_APPLICATION_CREDENTIALS têm precedência sobre ele. Se nenhum destes estiver definido, o ID do projeto é resolvido a partir da sua configuração gcloud ou da conta de serviço anexada.

​
Configuração avançada de credenciais

Claude Code suporta atualização automática de credenciais para GCP através da configuração gcpAuthRefresh. Quando Claude Code detecta que suas credenciais GCP expiraram ou não podem ser carregadas, ele executa o comando configurado para obter novas credenciais antes de tentar novamente a solicitação. 
{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}
A saída do comando é exibida ao usuário, mas entrada interativa não é suportada. Isso funciona bem para fluxos de autenticação baseados em navegador onde a CLI mostra uma URL e você completa a autenticação no navegador. O comando de atualização expira após três minutos se a autenticação não for concluída. Se você definir gcpAuthRefresh em configurações de projeto como .claude/settings.json, o comando é executado apenas após você aceitar o prompt de confiança do workspace.

​
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: Substituir a URL do endpoint Vertex para endpoints personalizados ou gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

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

# Opcional: Solicitar TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos
export ENABLE_PROMPT_CACHING_1H=1

# Quando CLOUD_ML_REGION=global, substituir região para modelos que não suportam endpoints globais
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
A maioria das versões de modelo tem uma variável VERTEX_REGION_CLAUDE_* correspondente. Veja a referência de variáveis de ambiente para a lista completa. Verifique o Vertex Model Garden para determinar quais modelos suportam endpoints globais versus apenas regionais. Prompt caching é ativado automaticamente. Para desativá-lo, defina DISABLE_PROMPT_CACHING=1. Para solicitar um TTL de cache de 1 hora em vez do padrão de 5 minutos, defina ENABLE_PROMPT_CACHING_1H=1; gravações de cache com TTL de 1 hora são cobradas a uma taxa mais alta. 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 das credenciais do Google Cloud. Claude Code desativa MCP tool search por padrão no Vertex AI, portanto as definições de ferramenta MCP são carregadas antecipadamente. Vertex AI suporta busca de ferramentas para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior. Defina ENABLE_TOOL_SEARCH=true para ativá-lo nesses modelos. Modelos anteriores no Vertex AI não aceitam o cabeçalho beta necessário, e as solicitações falham se você ativar a busca de ferramentas com eles.

​
5. Fixar versões de modelo

Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como sonnet e opus resolvem para a versão mais recente, que pode ainda não estar ativada no seu projeto Vertex AI quando Anthropic lançar uma atualização. Claude Code volta para a versão anterior na inicialização quando a mais recente não está disponível, mas fixar permite que você controle quando seus usuários se movem para um novo modelo.
Defina estas variáveis de ambiente para IDs de modelo Vertex AI específicos. Sem ANTHROPIC_DEFAULT_OPUS_MODEL, o alias opus no Vertex resolve para Opus 4.6. Defina-o para o ID do Opus 4.7 para usar o modelo mais recente: 
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
Para IDs de modelo atuais e legados, veja Visão geral de modelos. Veja Configuração de modelo para a lista completa de variáveis de ambiente. Claude Code usa estes modelos padrão quando nenhuma variável de fixação está definida:
Tipo de modeloValor padrão
Modelo primárioclaude-sonnet-4-5@20250929
Modelo pequeno/rápidoMesmo que o modelo primário
Tarefas em segundo plano, como geração de título de sessão, usam o modelo pequeno/rápido, normalmente um modelo da classe Haiku. No Vertex AI, Claude Code usa como padrão o modelo primário porque Haiku pode não estar ativado em todos os projetos ou regiões. Para usar Haiku para tarefas em segundo plano, defina ANTHROPIC_DEFAULT_HAIKU_MODEL para um ID de modelo que esteja disponível no seu projeto. Para personalizar modelos ainda mais: 
export ANTHROPIC_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

​
Verificações de modelo na inicialização

Quando Claude Code inicia com Vertex AI configurado, ele verifica que os modelos que pretende usar estão acessíveis no seu projeto. Esta verificação requer Claude Code v2.1.98 ou posterior. Se você fixou uma versão de modelo que é mais antiga que o padrão atual do Claude Code, e seu projeto pode invocar a versão mais recente, Claude Code o solicita a atualizar a fixação. Aceitar escreve o novo ID de modelo no seu arquivo de configurações do usuário e reinicia Claude Code. Recusar é lembrado até a próxima mudança de versão padrão. Se você não fixou um modelo e o padrão atual não está disponível no seu projeto, Claude Code volta para a versão anterior para a sessão atual e mostra um aviso. O fallback não é persistido. Ative o modelo mais recente no Model Garden ou fixe uma versão para tornar a escolha permanente.

​
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, veja a documentação de IAM do Vertex.
Crie 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 Opus 4.7, Opus 4.6 e Sonnet 4.6 suportam a janela de contexto de 1M de tokens no Vertex AI. Claude Code ativa automaticamente a janela de contexto estendida quando você seleciona uma variante de modelo 1M. O assistente de configuração oferece uma opção de contexto 1M quando fixa modelos. Para ativá-lo para um modelo fixado manualmente em vez disso, acrescente [1m] ao ID do modelo. Veja Fixar modelos para implantações de terceiros para detalhes.

​
Resolução de problemas

Se você encontrar erros “Não foi possível carregar as credenciais padrão”:
  • Execute gcloud auth application-default login para configurar Credenciais Padrão da Aplicação
  • Defina GOOGLE_APPLICATION_CREDENTIALS para um caminho de arquivo de chave de conta de serviço
  • Consulte Configurar credenciais do GCP para todas as opções
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 o modelo está disponível no local que você especificou. Alguns modelos são oferecidos apenas em locais global ou multi-região como eu e us, não em regiões específicas
  • 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_DEFAULT_HAIKU_MODEL, ou
    • Defina uma região ou local multi-região 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