Claude Code no Bedrock ou Vertex AI: como configurar

O que muda quando o Claude Code é executado na sua própria conta de cloud

Pode executar o Claude Code no Amazon Bedrock ou no Google Vertex AI. Para mudar, são necessárias duas ou três variáveis de ambiente e as credenciais de cloud que a sua equipa já utiliza. Tudo o que é local permanece igual: a CLI, os subagentes, os hooks, as skills, os servidores MCP e os seus ficheiros CLAUDE.md. Apenas a chamada ao modelo muda de local. Com ela, mudam quatro aspetos: a rede por onde o pedido passa, a conta que paga, os modelos Claude que pode invocar e as funcionalidades do lado do servidor que estão disponíveis.

A questão raramente é saber se funciona. Funciona. A questão é qual destes quatro aspetos é mais importante para si.

Os três encaminhamentos e o custo de cada um

Acesso direto à Anthropic com uma subscrição. Inicia sessão com uma conta claude.ai num plano Pro, Max, Team ou Enterprise. Os pedidos são enviados para a API da Anthropic. Paga por lugar, e a utilização é limitada pelos limites do plano, em vez de ser contabilizada por token. Este é o único encaminhamento que permite aceder às interfaces construídas sobre a conta, como o Claude Code na Web, a aplicação móvel, o Desktop e o Remote Control. Para uma equipa, o plano Claude Enterprise acrescenta início de sessão único e definições de políticas geridas.

Acesso direto à Anthropic com uma chave de API. Cria uma chave na Anthropic Console e paga por token. A infraestrutura e as regiões são as mesmas da subscrição, sem pagamento por lugar, e a utilização aparece no dashboard da própria Anthropic. Qual das duas opções é mais barata depende do número de horas por dia em que o agente é realmente executado. Esse é o tema de a comparação de custos entre a API e a subscrição e de quanto custa o Claude Code na prática.

Um endpoint de terceiros no Bedrock ou no Vertex. A sua própria conta AWS ou Google Cloud disponibiliza o modelo. A Anthropic não participa no caminho do pedido durante a inferência. Os tokens são incluídos numa fatura que já recebe, ao abrigo das políticas IAM (gestão de identidades e acessos) e dos logs de auditoria que já utiliza. Existem mais duas opções de terceiros: Microsoft Foundry e Claude Platform on AWS. Seguem o mesmo modelo: uma variável de ambiente seleciona o fornecedor e a conta cloud assume o custo.

Nota sobre a nomenclatura, em agosto de 2026: a Google mudou o nome de Vertex AI para Google Cloud's Agent Platform. A documentação da Anthropic usa o novo nome, mas o pedido de início de sessão do Claude Code ainda diz Google Vertex AI, e as variáveis de ambiente ainda dizem VERTEX.

A residência dos dados é o verdadeiro motivo para as equipas fazerem isto

No Bedrock, o pedido é enviado para um endpoint do Bedrock numa região da AWS escolhida por si, dentro da sua própria conta. Os dados em repouso são encriptados com AES-256 através de chaves geridas pela AWS, e pode fornecer a sua própria chave através do AWS KMS (key management service). No Vertex, o equivalente são chaves de encriptação geridas pela Google, com CMEK (customer-managed encryption keys) disponível. O acesso é controlado pelas funções IAM que já utiliza, e as chamadas aparecem no CloudTrail ou no Cloud Audit Logs como qualquer outra chamada de API. Para uma equipa sujeita a regulamentação, esse é todo o argumento, e é um argumento válido.

Dois detalhes tornam isto menos absoluto do que o marketing sugere.

Um perfil de inferência entre regiões não corresponde a uma única região. No Bedrock, o Claude Code resolve os modelos predefinidos incorporados para IDs de perfis de inferência entre regiões, e o prefixo que prefere vem da região que resolveu: us. numa região us-*, eu. numa região eu-*, apac. numa região ap-* e us-gov. no GovCloud. Um perfil entre regiões pode processar um pedido a partir de outra região dentro dessa área geográfica. Portanto, a garantia obtida é uma área geográfica, não uma cidade. Se o requisito especificar uma região, encaminhe o pedido através de um perfil de inferência de aplicação que controla e defina ANTHROPIC_MODEL para o respetivo ARN.

Algum tráfego continua a chegar à Anthropic, mas nenhum desse tráfego contém o seu código. A telemetria, os relatórios de erros e o comando /feedback estão desativados por predefinição tanto no Bedrock como no Vertex, e /feedback grava um arquivo em ~/.claude/feedback-bundles/ na sua própria máquina, em vez de carregar qualquer conteúdo. Duas exceções são executadas em todos os fornecedores. Antes de obter um URL, a ferramenta WebFetch envia o nome do host, e apenas o nome do host, para api.anthropic.com, para verificar uma lista de bloqueio de segurança. Os inquéritos sobre a qualidade das sessões também continuam a aparecer. Desative o primeiro com skipWebFetchPreflight no ficheiro de definições e o segundo com CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1, ou desative todo o tráfego não essencial de uma vez com CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.

Quanto ao treino: nos termos comerciais, a Anthropic não treina modelos com o código ou os prompts enviados através do Claude Code, e a utilização de plataformas de terceiros é comercial. O Development Partner Program, a opção que permite o treino mediante adesão, não é disponibilizado aos utilizadores do Bedrock ou do Vertex. A retenção zero de dados nestes endpoints depende do seu acordo com a AWS ou com a Google.

Indicar o Claude Code para o Amazon Bedrock

Há duas ações que ocorrem uma vez por conta AWS antes de qualquer configuração do cliente. Abra a consola do Amazon Bedrock, selecione um modelo Anthropic no catálogo de modelos e envie o formulário do caso de utilização: o acesso é concedido imediatamente após o envio. Em seguida, associe uma política IAM que permita as chamadas efetuadas pelo Claude Code.

• bedrock:InvokeModel
• bedrock:InvokeModelWithResponseStream
• bedrock:ListInferenceProfiles
• bedrock:GetInferenceProfile

ListInferenceProfiles permite que o Claude Code verifique, no arranque, quais os modelos que a sua conta pode realmente invocar. GetInferenceProfile permite resolver o ARN de um perfil de inferência de aplicação para identificar o modelo fundacional correspondente, para que possa escolher o formato de pedido correto. Sem essa permissão, os pedidos continuam a funcionar, porque o Claude Code tenta novamente uma vez usando o outro formato. O sintoma é uma viagem de ida e volta adicional por cada modelo novo, não um erro.

O caminho mais rápido no cliente é o assistente. Execute claude, escolha plataforma de terceiros e, em seguida, Amazon Bedrock, ou introduza /setup-bedrock numa sessão que já tenha sessão iniciada. O assistente lê os perfis no diretório ~/.aws, verifica quais os modelos que pode invocar e grava o resultado no bloco env de ~/.claude/settings.json, para que nada dependa do perfil da sua shell.

Para uma implementação com script, defina as variáveis manualmente.

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

As credenciais são obtidas através da cadeia padrão de credenciais do AWS SDK. Portanto, tudo o que já funciona para o CLI aws também funciona aqui: aws configure, um perfil SSO, uma função assumida ou uma chave de API do Bedrock.

aws sso login --profile=your-profile-name
export AWS_PROFILE=your-profile-name

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

O token bearer é a opção mais simples e a que exige mais cuidado, porque é um segredo de longa duração armazenado numa variável de ambiente. Num servidor de compilação partilhado, prefira uma função com expiração. O mesmo princípio aplica-se a todas as outras credenciais que o agente possa ler. Esse é o tema de manter os segredos fora do alcance de um agente de IA.

O problema da região. O Claude Code resolve a região pela seguinte ordem: AWS_REGION, depois AWS_DEFAULT_REGION, em seguida region no seu perfil AWS ativo e, por fim, us-east-1. Esta última etapa é um valor predefinido, não um erro. Por isso, uma equipa que não definiu a região em nenhum local e assumiu o encaminhamento europeu envia os pedidos para uma região dos EUA sem qualquer aviso. Execute /status dentro do Claude Code para ver a região resolvida e a origem desse valor. Para confirmar o que a sua conta pode invocar numa região, execute aws bedrock list-inference-profiles --region your-region.

Executar Claude Code no Google Vertex AI

Ative a API e obtenha as credenciais.

gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com
gcloud auth application-default login

Solicite acesso aos modelos Claude de que precisa no Model Garden. A aprovação não é imediata, por isso aguarde 24 a 48 horas. Conceda roles/aiplatform.user, que inclui a permissão aiplatform.endpoints.predict, usada tanto para invocar modelos como para contar tokens.

Em seguida, selecione o fornecedor.

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

CLOUD_ML_REGION aceita global, uma localização multirregional como eu ou us, ou uma região única. O endpoint global oferece a melhor disponibilidade, mas dá menos controlo sobre o local onde um pedido é processado. Por isso, um requisito de residência de dados normalmente implica especificar uma localização. A cobertura de modelos varia entre estas três opções. Quando um modelo necessário não estiver disponível no endpoint global, fixe apenas esse modelo numa localização com a variável VERTEX_REGION_CLAUDE_* e mantenha todos os restantes no âmbito global. Consulte a página atual de localizações do Vertex AI, em vez de confiar numa lista desatualizada.

A armadilha do projeto. ANTHROPIC_VERTEX_PROJECT_ID é a fonte de menor prioridade para o ID do projeto. GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT e o ficheiro de credenciais indicado por GOOGLE_APPLICATION_CREDENTIALS têm precedência sobre ele. Numa máquina onde uma dessas opções já esteja exportada, os custos são atribuídos a esse outro projeto, sem que nada na sessão o indique.

Verifique o resultado depois de qualquer alteração do fornecedor. Execute /status: a linha API provider mostra Google Vertex AI, e as linhas GCP project, Default region e Model mostram o que o Claude Code resolveu efetivamente. Se a linha do fornecedor estiver ausente, as variáveis não estão a chegar ao processo porque foram exportadas numa shell diferente daquela que iniciou claude. Coloque-as no bloco env do ficheiro de definições. Esta é também a forma de impedir que um valor como AWS_PROFILE seja herdado por todos os outros processos que iniciar.

Quais modelos obtém e com que atraso ficam disponíveis

Aliases como sonnet e opus não significam os modelos mais recentes. Num endpoint de terceiros, resolvem para o modelo predefinido integrado no Claude Code para esse fornecedor. Esse modelo pode estar atrasado em relação à versão atual e pode nem estar ativado na sua conta. Quando o modelo predefinido não está disponível, o Claude Code recorre a um modelo anterior ou de nível inferior nessa sessão e apresenta um aviso. O fallback não é guardado. Por isso, a sessão seguinte tenta novamente e apresenta o aviso outra vez.

Para uma implementação numa equipa, fixe as versões.

# Copy the exact IDs from your provider's own model catalog.
export ANTHROPIC_DEFAULT_OPUS_MODEL='<provider model id>'
export ANTHROPIC_DEFAULT_SONNET_MODEL='<provider model id>'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='<provider model id>'

Obtenha os IDs na visão geral dos modelos e no catálogo do seu fornecedor. O formato varia entre fornecedores: o Bedrock espera um ID de perfil de inferência ou um ARN; o Vertex espera um nome de modelo simples. Não copie os IDs de um artigo, incluindo este. Fixar versões também permite controlar os custos, porque o modelo primário predefinido pertence à classe Opus e o Opus custa mais por token do que o Sonnet. Por isso, uma implementação sem versões fixas é faturada à taxa mais elevada. Para definir apenas um modelo como predefinição da sessão, atribua ANTHROPIC_MODEL ao respetivo ID completo.

A disponibilidade do modelo é o compromisso mais evidente nesta comparação. Na API da Anthropic, um modelo funciona no dia em que é lançado. No Bedrock e no Vertex, funciona depois de o fornecedor de cloud o ativar na sua região e de conceder acesso à sua conta. Isso acontece, na melhor das hipóteses, alguns dias depois e, por vezes, muito mais tarde. Se algum trabalho tiver de ser executado no modelo mais recente, mantenha um encaminhamento que consiga aceder-lhe. Esse é o caso prático para encaminhar modelos diferentes para tarefas diferentes.

O que fica indisponível no Bedrock e no Vertex

Tudo o que é local funciona em todos os provedores: subagentes, hooks, comandos slash, skills, plugins, checkpoints, sandboxing, o ficheiro de definições gerido e métricas do OpenTelemetry. As limitações estão todas no lado do servidor.

Indisponível nos dois endpoints: modo rápido, Advisor, Channels, mensagens entre sessões, o dashboard de analytics e definições geridas pelo servidor. Também fica indisponível tudo o que exige uma conta claude.ai, incluindo o Claude Code na web, a aplicação móvel, Desktop, Remote Control, rotinas e artifacts.

Apenas no Bedrock: a ferramenta WebSearch não existe nesse serviço, pelo que o Claude não pode executar uma pesquisa a partir de uma sessão encaminhada para o Bedrock. Ainda pode ler uma página com WebFetch quando lhe fornece um URL. No Vertex, a pesquisa na web funciona para os modelos de geração Claude 4 e posteriores.

Parcial nos dois: o modo automático funciona apenas num conjunto restrito de modelos mais recentes, e /loop exige um intervalo explícito porque não consegue escolher um por si. Consulte a página de disponibilidade de funcionalidades da Anthropic antes de prometer uma funcionalidade à sua equipa, porque esta lista muda.

Em que conta isso aparece

Uma assinatura e um endpoint de terceiros são compras separadas. Nenhuma substitui a outra.

Vale a pena deixar isso claro, porque o erro passa despercebido. Configure CLAUDE_CODE_USE_BEDROCK=1 numa máquina em que também iniciou sessão com uma licença Max, e a AWS contabilizará cada token segundo as tarifas do Bedrock. A licença continua a ser cobrada mensalmente, mas não paga por nenhum desse tráfego. Também não existe uma visão consolidada: os custos aparecem no AWS Cost Explorer ou no Google Cloud Billing, e o painel de análise da Anthropic não está disponível em nenhum dos dois provedores. O comando /logout também deixa de existir, porque não há uma sessão da Anthropic para terminar. A credencial é a credencial da cloud.

As tarifas estão na página do próprio provedor e podem mudar. Consulte preços do Amazon Bedrock ou preços do Vertex AI, e não os valores apresentados num artigo. Um ponto estrutural não muda: nestes endpoints, paga-se pela inferência por token. Assim, um agente deixado em execução durante todo o dia custa o valor correspondente ao uso, sem um limite de plano que o impeça.

Os limites de utilização e as quotas funcionam de forma diferente em cada encaminhamento

Numa subscrição, os limites pertencem à conta, são repostos segundo um calendário e, quando um é atingido, é necessário esperar. Esse comportamento é explicado em como funcionam os limites de utilização.

Numa chave da Anthropic API, os limites pertencem à organização, são expressos em pedidos e tokens por minuto e aumentam com o seu nível de utilização.

No Bedrock e no Vertex, os limites são quotas da cloud, definidas por conta ou projeto, modelo e região, sem qualquer relação com um plano da Anthropic. Um erro 429 significa que a conta atingiu a quota desse modelo nessa região. A correção deve ser feita na consola do fornecedor: peça um aumento ou mude para uma localização com capacidade disponível. O Bedrock contabiliza a quota segundo uma regra de token burndown, em vez de uma contagem fixa de pedidos, e a capacidade reservada é adquirida como débito provisionado. No Vertex, os erros 429 significam frequentemente que o endpoint numa única região não fornece tanto o modelo principal como o modelo pequeno e rápido. Por isso, CLOUD_ML_REGION=global é o ponto de partida documentado. A página de quotas da Google explica como pedir um aumento.

Modos de falha e as mensagens que verá

Could not load the default credentials, no Vertex. As Application Default Credentials estão ausentes ou expiraram. Execute gcloud auth application-default login ou aponte GOOGLE_APPLICATION_CREDENTIALS para um ficheiro de chave de uma service account.

Um 404 que identifica o modelo, no Vertex. O modelo não está ativado no Model Garden para esse projeto ou não é disponibilizado na localização definida. Alguns modelos são disponibilizados apenas no endpoint global ou numa localização multirregional, como eu, e nunca numa região específica.

on-demand throughput isn't supported, no Bedrock. Foi passado um ID simples de foundation model para um modelo que só é disponibilizado através de um inference profile. Use o ID do inference profile.

AWS default-chain credential resolve timed out. Um passo da cadeia de credenciais da AWS ficou bloqueado, normalmente um helper credential_process à espera de uma entrada que nunca pode receber. Cada resolução da cadeia termina por timeout ao fim de 60 segundos. Se a cadeia precisar realmente de mais tempo, por exemplo num fluxo de SSO num browser com MFA (autenticação multifator) executado através de um wrapper, aumente o limite em milissegundos com CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

Um erro ao iniciar Bedrock streaming response has content-type. Algo entre o Claude Code e o Bedrock está a reescrever o stream. O Bedrock envia streams num formato binário de event-stream com o tipo de conteúdo application/vnd.amazon.eventstream. Por isso, um gateway que o reenvia como server-sent events devolve um corpo que o Claude Code não consegue descodificar. Corrija o gateway para transmitir o corpo da resposta e o respetivo cabeçalho Content-Type sem alterações.

Separadores do browser a abrir em ciclo durante o AWS SSO. Uma VPN empresarial ou um proxy que inspeciona TLS interrompe o início de sessão. O Claude Code interpreta a ligação interrompida como uma falha de autenticação, executa novamente o comando awsAuthRefresh e repete o processo indefinidamente. Remova awsAuthRefresh do ficheiro de definições e execute aws sso login manualmente antes de iniciar o Claude Code.

Escolher um encaminhamento

Escolha Anthropic direto quando quiser modelos novos no dia do lançamento e o conjunto completo de funcionalidades. Escolha uma chave de API quando quiser faturação por token sem comprar lugares. Escolha Bedrock ou Vertex quando for obrigatório que a inferência ocorra dentro de uma conta de cloud que já administra e aceitar um pipeline de modelos mais lento e uma lista de funcionalidades mais curta como consequência. Vale a pena guardar as páginas de configuração da própria Anthropic para o Amazon Bedrock e para o Google Vertex AI, juntamente com a lista da AWS de modelos por região.

Nenhuma das três opções altera o local onde o próprio agente é executado. O Claude Code é um processo local que lê os seus ficheiros e executa os seus comandos, independentemente do endpoint que lhe responde. Por isso, as equipas que querem executá-lo noutro local que não seja um portátil colocam o agente de programação num VPS e exportam essas mesmas variáveis nesse local.

FAQ

A minha subscrição Claude paga o Claude Code no Bedrock ou no Vertex?

Não. Uma licença Pro, Max, Team ou Enterprise e um endpoint de terceiros são compras separadas, e nenhuma cobre a outra. Com CLAUDE_CODE_USE_BEDROCK=1 ou CLAUDE_CODE_USE_VERTEX=1 definido, cada token é contabilizado pela AWS ou pelo Google Cloud às respetivas tarifas e aparece na fatura dessa cloud, enquanto a licença continua a ser cobrada mensalmente pelas interfaces que abrange. O acompanhamento dos custos também muda para o AWS Cost Explorer ou para o Google Cloud Billing, porque o painel de análise da Anthropic não está disponível em nenhum dos dois fornecedores.

Para que região o Claude Code envia os meus pedidos no Amazon Bedrock?

Para a região que foi resolvida, que /status lhe mostra. O Claude Code verifica AWS_REGION, depois AWS_DEFAULT_REGION, depois o region no seu perfil AWS ativo e usa us-east-1 quando nenhum desses valores está definido. Os modelos predefinidos integrados resolvem então para perfis de inferência entre regiões cujo prefixo segue essa região, como us. ou eu., e um perfil entre regiões pode processar um pedido a partir de outra região dentro da mesma área geográfica. Quando uma região específica é um requisito obrigatório, use um perfil de inferência de aplicação que controle e defina ANTHROPIC_MODEL com o respetivo ARN.

Porque falta o modelo Claude mais recente na minha conta Bedrock ou Vertex?

Porque cada fornecedor de cloud disponibiliza os modelos segundo o seu próprio calendário e, além disso, é necessário conceder acesso à sua conta. No Vertex, peça acesso no Model Garden. A aprovação pode demorar 24 a 48 horas. Até lá, aliases como sonnet e opus resolvem para o modelo predefinido integrado do Claude Code para esse fornecedor. Quando esse modelo predefinido não está disponível na sua conta, o Claude Code usa um modelo anterior ou de nível inferior durante a sessão e apresenta um aviso. Fixe ANTHROPIC_DEFAULT_SONNET_MODEL e os respetivos equivalentes em IDs que confirmou estarem ativados.

A pesquisa na Web está disponível no Claude Code no Amazon Bedrock?

Não. A ferramenta WebSearch não está disponível no Bedrock, pelo que o Claude não pode executar uma pesquisa numa sessão encaminhada para esse serviço. Ainda pode ler uma página específica com WebFetch quando fornece o URL. No Google Vertex AI, a pesquisa na Web funciona para modelos de geração Claude 4 e posteriores. Esta é uma das poucas diferenças de capacidade a favor do Vertex.

Preciso de uma conta Anthropic para executar o Claude Code no Bedrock ou no Vertex?

Não. A autenticação usa as suas credenciais AWS ou Google Cloud. Por isso, /logout não está disponível em nenhum dos dois fornecedores. Independentemente do fornecedor utilizado, existe uma ligação à Anthropic: antes de obter um URL, a ferramenta WebFetch envia o nome do host, e apenas o nome do host, para api.anthropic.com, para verificar se está numa lista de bloqueio de segurança. Defina skipWebFetchPreflight no seu ficheiro de definições para desativar essa verificação e combine-o com regras de permissões do WebFetch se ainda quiser limitar os domínios que o Claude pode consultar.