SpyBara
Go Premium

claude-platform-on-aws.md 2026-11-03 23:58 UTC to 2026-11-04 23:59 UTC

No changes for this document in this history range.

2026
Wed 11 22:59

Claude Code no Claude Platform on AWS

Configure Claude Code para usar a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace.

Claude Platform on AWS é a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace. As solicitações chegam diretamente à API da Anthropic, portanto você obtém os mesmos modelos e recursos de API que a Claude API no mesmo cronograma de lançamento. Você se autentica com credenciais AWS ou uma chave de API do workspace, e paga através do AWS Marketplace.

Os recursos do lado do cliente que Claude Code ativa através do serviço de sinalizadores de recursos da Anthropic estão desativados por padrão, e a ferramenta advisor não está disponível. Consulte a matriz de disponibilidade de recursos para obter a lista completa.

Use este guia para apontar Claude Code para um workspace que você já provisionou através do Claude Platform on AWS. Para a assinatura AWS e configuração do workspace que vem antes disso, consulte a documentação do Claude Platform on AWS.

[!NOTE]

Assinar através do AWS Marketplace provisiona uma nova organização Anthropic vinculada à sua conta AWS. Esta organização é separada de qualquer organização que você já tenha com a Anthropic, e as credenciais não são transferidas entre elas. Use o ID do workspace e as chaves de API da organização vinculada ao AWS, não de uma conta Claude Console pré-existente.

Pré-requisitos

Antes de configurar Claude Code, você precisa de:

  • Uma assinatura ativa do Claude Platform on AWS através do AWS Marketplace
  • Um workspace em sua organização Anthropic vinculada ao AWS, com seu ID de workspace
  • Um principal IAM com permissão para invocar o serviço Anthropic, ou uma chave de API com escopo para o workspace
  • Credenciais AWS em seu ambiente, em ~/.aws/credentials, ou de uma função IAM anexada se você quiser autenticação SigV4. A AWS CLI é necessária apenas para o fluxo de login SSO.

Configuração

Configure as credenciais da AWS

O Claude Code oferece suporte a dois métodos de autenticação para o Claude Platform on AWS. Escolha o método que se adapta à forma como sua equipe gerencia o acesso:

Use credenciais da AWS com SigV4

O Claude Code assina as requisições com SigV4 usando a cadeia padrão de credenciais da AWS: variáveis de ambiente, credenciais compartilhadas em ~/.aws/credentials, funções do IAM, sessões do AWS SSO e quaisquer outras fontes compatíveis com o AWS SDK.

Para uso local, faça login com a AWS CLI antes de iniciar o Claude Code. O exemplo abaixo usa um perfil de SSO, mas qualquer método que produza credenciais nos locais padrão funciona.

aws sso login --profile my-profile
export AWS_PROFILE=my-profile

Para CI e automação, atribua ao runner uma função do IAM com permissão para invocar o serviço da Anthropic e defina AWS_REGION. A cadeia de credenciais detecta a função automaticamente.

Se suas credenciais de SSO expirarem no meio da sessão, configure awsAuthRefresh para que o Claude Code execute novamente seu comando de login e tente novamente em vez de falhar. Adicione o comando ao seu arquivo de configurações, como ~/.claude/settings.json:

{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}

O Claude Code também executa esse comando na inicialização quando não consegue validar suas credenciais da AWS existentes, e mostra a saída do comando em um painel Authentication até que o login seja concluído.

Com awsAuthRefresh configurado, execute /login, selecione 3rd-party platform e depois selecione Claude Platform on AWS · refresh credentials em Using 3rd-party platforms. O Claude Code executa o comando configurado e lê novamente suas credenciais da AWS sem reiniciar.

Use uma chave de API do workspace

Uma chave de API do workspace é um segredo de longa duração, útil quando você não quer gerenciar credenciais federadas da AWS. Gere uma no AWS Console em Claude Platform on AWS → API keys e defina-a como ANTHROPIC_AWS_API_KEY:

export ANTHROPIC_AWS_API_KEY=sk-ant-xxxxx

A chave é enviada como x-api-key e tem precedência sobre o SigV4, portanto quaisquer credenciais da AWS no seu ambiente são ignoradas. Chaves de API de uma organização separada do Claude Console não funcionam aqui.

Trate as chaves de API do workspace como qualquer outra credencial de produção. O bloco env do arquivo de configurações do usuário é uma forma conveniente de restringir a chave à sua máquina sem exportá-la globalmente.

[!NOTE]

Os comandos /login e /logout não fazem login em uma assinatura do claude.ai para o Claude Platform on AWS. A autenticação é feita por meio das suas credenciais da AWS ou da chave de API do workspace.

Configure o Claude Code

Defina as variáveis de ambiente que direcionam o Claude Code pelo Claude Platform on AWS em vez da API padrão da Anthropic.

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export AWS_REGION=us-east-1

ANTHROPIC_AWS_WORKSPACE_ID é obrigatório. O Claude Code o envia em cada requisição como o cabeçalho anthropic-workspace-id. Substitua o valor de exemplo wrkspc_01ABCDEFGHIJKLMN pelo ID do seu próprio workspace, obtido na configuração do seu Claude Platform on AWS.

O Claude Code calcula a URL base como https://aws-external-anthropic.{region}.api.aws a partir da região da AWS, que ele resolve com a mesma precedência do Amazon Bedrock. Para sobrescrever a URL diretamente, defina ANTHROPIC_AWS_BASE_URL.

O Claude Platform on AWS é opcional mesmo quando há credenciais da AWS presentes no seu ambiente. O Amazon Bedrock e o Microsoft Foundry têm precedência no roteamento de provedores, portanto remova CLAUDE_CODE_USE_BEDROCK e CLAUDE_CODE_USE_FOUNDRY caso estejam definidas.

Fixe as versões dos modelos

O Claude Platform on AWS usa os mesmos IDs de modelo da Claude API direta.

Os aliases padrão fable, opus, sonnet e haiku são resolvidos para os padrões integrados do Claude Code para o Claude Platform on AWS, que podem ficar atrás da versão mais recente. Sem ANTHROPIC_DEFAULT_OPUS_MODEL, o alias opus é resolvido para o Opus 5.5. Antes da v2.1.280, ele era resolvido para o Opus 5 a partir da v2.1.219.

Se você implanta o Claude Code para uma equipe, fixe os IDs de modelo explicitamente para que uma nova versão não mude todos de uma só vez:

export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Para a lista completa de IDs de modelo e aliases, consulte Visão geral dos modelos. Para outras variáveis relacionadas a modelos, consulte Configuração de modelos.

O cache de prompt é ativado automaticamente. Para solicitar um TTL de cache de 1 hora em vez do padrão de 5 minutos, defina ENABLE_PROMPT_CACHING_1H=1. A API cobra gravações de cache de 1 hora a uma taxa mais alta. Consulte preços do cache de prompt para ver as taxas.

Para definir TTLs diferentes para sua conversa principal e para as requisições que o Claude Code faz fora dela, escolha o TTL você mesmo.

Inicie e verifique

Inicie o Claude Code e confirme o roteamento:

claude

O banner de inicialização mostra Claude Platform on AWS quando o provedor está ativo. Execute /status para verificar os detalhes: a linha API provider exibe Claude Platform on AWS, e a saída inclui seu Workspace ID, a AWS region e a Claude Platform on AWS base URL se você definiu uma substituição.

Use o Agent SDK

O Agent SDK lê as mesmas variáveis de ambiente que a CLI, portanto qualquer programa que gere o subprocesso Claude Code pode direcionar Claude Platform on AWS exportando CLAUDE_CODE_USE_ANTHROPIC_AWS, ANTHROPIC_AWS_WORKSPACE_ID e ANTHROPIC_AWS_API_KEY ou credenciais AWS antes da chamada.

import { query } from "@anthropic-ai/claude-agent-sdk";

process.env.CLAUDE_CODE_USE_ANTHROPIC_AWS = "1";
process.env.ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN";
process.env.AWS_REGION = "us-east-1";

for await (const msg of query({ prompt: "What's in this repo?" })) {
  console.log(msg);
}

Este exemplo depende da cadeia de credenciais AWS ambiente para SigV4. Para autenticar com uma chave de API do workspace em vez disso, defina ANTHROPIC_AWS_API_KEY da mesma forma. Para a superfície mais ampla do Agent SDK, consulte Visão geral do Agent SDK.

Rotear através de um proxy corporativo

Para rotear tráfego através de um proxy ou gateway LLM, defina ANTHROPIC_AWS_BASE_URL para o endereço do proxy. Claude Code envia solicitações para essa URL com os mesmos cabeçalhos de workspace e autenticação, portanto qualquer gateway que os encaminhe inalterados funciona.

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com

Se seu gateway assina solicitações em si, defina CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1 para que Claude Code envie solicitações não assinadas e deixe o gateway adicionar cabeçalhos SigV4 antes de encaminhar para AWS. Se o gateway requer seu próprio token, defina-o em ANTHROPIC_AUTH_TOKEN.

export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export ANTHROPIC_AWS_BASE_URL=https://anthropic-proxy.example.com

Troubleshooting

Execute /status para ver o provedor resolvido e qualquer ID de workspace, região, substituição de URL base e configuração de salto de autenticação explicitamente configurados. Esta é a maneira mais rápida de confirmar que Claude Code está direcionando Claude Platform on AWS.

403 Forbidden ou AccessDenied em cada solicitação

O principal IAM que Claude Code resolveu provavelmente não tem permissão para invocar o serviço Anthropic em seu workspace. Verifique a função anexada ao seu perfil AWS ou ao executor que iniciou Claude Code, e verifique se ela tem as ações aws-external-anthropic documentadas na referência de ação IAM.

Se você definir ANTHROPIC_AWS_API_KEY, a chave tem precedência sobre SigV4 e uma chave obsoleta produz o mesmo erro. Regenere a chave no Console AWS em Claude Platform on AWS → API keys ou desdefina a variável para voltar às suas credenciais AWS.

Solicitações falham com um erro de workspace ausente

ANTHROPIC_AWS_WORKSPACE_ID provavelmente está desdefido ou vazio. Cada solicitação do Claude Platform on AWS deve incluir o ID do workspace. Não é implícito por suas credenciais AWS. Encontre o ID em sua configuração do Claude Platform on AWS e exporte-o antes de iniciar Claude Code.

Solicitações ainda vão para api.anthropic.com

CLAUDE_CODE_USE_ANTHROPIC_AWS provavelmente está desdefido ou definido para um valor que não é analisado como verdadeiro. Defina-o como 1 e execute /status para confirmar o provedor resolvido. Se CLAUDE_CODE_USE_BEDROCK ou CLAUDE_CODE_USE_FOUNDRY também estiver definido, esses têm precedência sobre Claude Platform on AWS.

Recursos adicionais

A assinatura do Claude Platform on AWS, configuração de workspace e IAM que vem antes de configurar Claude Code é coberta na documentação da plataforma: