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:
- Credenciais da AWS com SigV4: autentique-se como uma entidade principal do IAM, com credenciais da cadeia padrão de credenciais da AWS
- Chave de API do workspace: autentique-se com uma chave de longa duração que você gera no AWS Console
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_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:
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 comoANTHROPIC_AWS_API_KEY:
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.
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.
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:
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 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 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