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 credenciais AWS
Claude Code suporta dois métodos de autenticação para Claude Platform on AWS. Escolha o método que se adequa à forma como sua equipe gerencia o acesso.
Opção A: Credenciais AWS com SigV4
Claude Code assina solicitações com SigV4 usando a cadeia de credenciais AWS padrão: variáveis de ambiente, credenciais compartilhadas em ~/.aws/credentials, funções IAM, sessões AWS SSO e qualquer outra fonte que o AWS SDK suporte.
Para uso local, faça login com a AWS CLI antes de iniciar Claude Code. O exemplo abaixo usa um perfil SSO, mas qualquer método que produza credenciais nos locais padrão funciona.
AWS_REGION. A cadeia de credenciais pega a função automaticamente.
Se suas credenciais SSO expirarem durante a sessão, configure awsAuthRefresh para que Claude Code execute novamente seu comando de login e tente novamente em vez de falhar. A atualização automática no Claude Platform on AWS requer Claude Code v2.1.198 ou posterior; versões anteriores param com um prompt para executar /login, que não pode atualizar credenciais AWS. Adicione o comando ao seu arquivo de configurações, como ~/.claude/settings.json:
Authentication até que o login seja concluído.
Com awsAuthRefresh configurado, execute /login, selecione plataforma de terceiros, depois selecione Claude Platform on AWS · atualizar credenciais em Usando plataformas de terceiros. Claude Code executa o comando configurado e relê suas credenciais AWS sem uma reinicialização.
Opção B: 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 AWS federadas. Gere uma no Console AWS em Claude Platform on AWS → API keys e defina-a como ANTHROPIC_AWS_API_KEY:
x-api-key e tem precedência sobre SigV4, portanto qualquer credencial AWS em seu ambiente é ignorada. Chaves de API de uma organização Claude Console separada não funcionarão aqui.
Trate chaves de API do workspace como qualquer outra credencial de produção. O bloco env do arquivo de configurações do usuário é uma maneira conveniente de escopar a chave para sua máquina sem exportá-la globalmente.
Os comandos
/login e /logout não o autenticam em uma assinatura Claude.ai para Claude Platform on AWS. A autenticação é executada através de suas credenciais AWS ou chave de API do workspace.
- Configure Claude Code
Defina as variáveis de ambiente que rotearão Claude Code através do Claude Platform on AWS em vez da API Anthropic padrão.
ANTHROPIC_AWS_WORKSPACE_ID é obrigatório. Claude Code o envia em cada solicitação como o cabeçalho anthropic-workspace-id. Substitua o valor de exemplo wrkspc_01ABCDEFGHIJKLMN pelo seu próprio ID de workspace da sua configuração Claude Platform on AWS.
Claude Code calcula a URL base como https://aws-external-anthropic.{region}.api.aws a partir da região AWS, que ele resolve com a mesma precedência que Amazon Bedrock. Para substituir a URL diretamente, defina ANTHROPIC_AWS_BASE_URL.
Claude Platform on AWS é opt-in mesmo quando credenciais AWS estão presentes em seu ambiente. Amazon Bedrock e Microsoft Foundry têm precedência no roteamento de provedores, portanto desdefina CLAUDE_CODE_USE_BEDROCK e CLAUDE_CODE_USE_FOUNDRY se estiverem definidas.
- Fixe versões de modelo
Claude Platform on AWS usa os mesmos IDs de modelo que a API Claude direta.
Os aliases padrão fable, opus, sonnet e haiku resolvem para os padrões integrados do Claude Code para Claude Platform on AWS, que podem ficar atrás da versão mais recente. Sem ANTHROPIC_DEFAULT_OPUS_MODEL, o alias opus resolve para Opus 5.5. Antes da v2.1.280, ele resolvia para Opus 5 a partir da v2.1.219, para Opus 4.8 a partir da v2.1.207 e para Opus 4.7 antes disso.
Se você implantar Claude Code para uma equipe, fixe os IDs de modelo explicitamente para que um novo lançamento não mova todos de uma vez:
ENABLE_PROMPT_CACHING_1H=1. A API cobra gravações de cache de 1 hora a uma taxa mais alta. Consulte preços de prompt caching para as taxas.
Para definir TTLs diferentes para sua conversa principal e para as solicitações que Claude Code faz fora dela, escolha o TTL você mesmo.
- Inicie e verifique
Inicie Claude Code e confirme o roteamento:
Claude Platform on AWS quando o provedor está ativo. Execute /status para verificar os detalhes: a linha API provider lê 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ê definir 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 exportandoCLAUDE_CODE_USE_ANTHROPIC_AWS, ANTHROPIC_AWS_WORKSPACE_ID e ANTHROPIC_AWS_API_KEY ou credenciais AWS antes da chamada.
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, definaANTHROPIC_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.
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.
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:- Visão geral do Claude Platform on AWS: assinatura, configuração de workspace e referência de produto
- Referência de ação IAM: permissões e políticas gerenciadas