Claude Code no Amazon Bedrock

Aprenda sobre como configurar o Claude Code através do Amazon Bedrock, incluindo configuração, configuração do IAM e solução de problemas.

Pré-requisitos

Antes de configurar o Claude Code com Bedrock, certifique-se de ter:

• Uma conta AWS com acesso ao Bedrock habilitado
• Acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4) no Bedrock
• AWS CLI instalado e configurado (opcional - necessário apenas se você não tiver outro mecanismo para obter credenciais)
• Permissões IAM apropriadas

Configuração

1. Habilitar acesso ao modelo

Primeiro, certifique-se de ter acesso aos modelos Claude necessários em sua conta AWS:

1. Navegue até o console do Amazon Bedrock
2. Vá para Acesso ao modelo na navegação à esquerda
3. Solicite acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4)
4. Aguarde a aprovação (geralmente instantânea para a maioria das regiões)

2. Configurar credenciais AWS

O Claude Code usa a cadeia de credenciais padrão do AWS SDK. Configure suas credenciais usando um destes métodos:

Opção A: Configuração do AWS CLI

aws configure

Opção B: Variáveis de ambiente (chave de acesso)

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

Opção C: Variáveis de ambiente (perfil SSO)

aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name

Opção D: Chaves de API do Bedrock

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

As chaves de API do Bedrock fornecem um método de autenticação mais simples sem precisar de credenciais AWS completas. Saiba mais sobre chaves de API do Bedrock.

Configuração avançada de credenciais

O Claude Code suporta atualização automática de credenciais para AWS SSO e provedores de identidade corporativos. Adicione essas configurações ao seu arquivo de configurações do Claude Code (veja Configurações para localizações de arquivos).

Quando o Claude Code detecta que suas credenciais AWS expiraram (seja localmente com base em seu timestamp ou quando o Bedrock retorna um erro de credencial), ele executará automaticamente seus comandos awsAuthRefresh e/ou awsCredentialExport configurados para obter novas credenciais antes de tentar novamente a solicitação.

Exemplo de configuração

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

Configurações explicadas

awsAuthRefresh: Use isso para comandos que modificam o diretório .aws (por exemplo, atualizando credenciais, cache SSO ou arquivos de configuração). A saída é mostrada ao usuário (mas entrada do usuário não é suportada), tornando-o adequado para fluxos de autenticação baseados em navegador onde o CLI exibe um código para inserir no navegador.

awsCredentialExport: Use isso apenas se você não puder modificar .aws e deve retornar credenciais diretamente. A saída é capturada silenciosamente (não mostrada ao usuário). O comando deve produzir JSON neste formato:

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

3. Configurar Claude Code

Defina as seguintes variáveis de ambiente para habilitar o Bedrock:

# Habilitar integração com Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # ou sua região preferida

# Opcional: Substituir a região para o modelo pequeno/rápido (Haiku)
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

Ao habilitar o Bedrock para o Claude Code, tenha em mente o seguinte:

• AWS_REGION é uma variável de ambiente obrigatória. O Claude Code não lê do arquivo de configuração .aws para esta configuração.
• Ao usar o Bedrock, os comandos /login e /logout são desabilitados, pois a autenticação é tratada através das credenciais AWS.
• Você pode usar arquivos de configurações para variáveis de ambiente como AWS_PROFILE que você não quer vazar para outros processos. Veja Configurações para mais informações.

4. Configuração do modelo

O Claude Code usa estes modelos padrão para o Bedrock:

Tipo de modelo	Valor padrão
Modelo principal	us.anthropic.claude-3-7-sonnet-20250219-v1:0
Modelo pequeno/rápido	us.anthropic.claude-3-5-haiku-20241022-v1:0

Para personalizar modelos, use um destes métodos:

# Usando ID do perfil de inferência
export ANTHROPIC_MODEL='us.anthropic.claude-opus-4-1-20250805-v1:0'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-v1:0'

# Usando ARN do perfil de inferência da aplicação
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Opcional: Desabilitar cache de prompt se necessário
export DISABLE_PROMPT_CACHING=1

Cache de prompt pode não estar disponível em todas as regiões

5. Configuração de tokens de saída

Ao usar o Claude Code com Amazon Bedrock, recomendamos as seguintes configurações de tokens:

# Configurações recomendadas de tokens de saída para Bedrock
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
export MAX_THINKING_TOKENS=1024

Por que esses valores:

• CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096: A lógica de throttling burndown do Bedrock define um mínimo de 4096 tokens como penalidade de max_token. Definir isso mais baixo não reduzirá custos, mas pode cortar usos longos de ferramentas, causando falha persistente no loop do agente Claude Code. O Claude Code normalmente usa menos de 4096 tokens de saída sem pensamento estendido, mas pode precisar dessa margem para tarefas envolvendo criação significativa de arquivos ou uso da ferramenta Write.

• MAX_THINKING_TOKENS=1024: Isso fornece espaço para pensamento estendido sem cortar respostas de uso de ferramentas, enquanto ainda mantém cadeias de raciocínio focadas. Esse equilíbrio ajuda a prevenir mudanças de trajetória que nem sempre são úteis para tarefas de codificação especificamente.

Configuração do IAM

Crie uma política IAM com as permissões necessárias para o Claude Code:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*"
      ]
    }
  ]
}

Para permissões mais restritivas, você pode limitar o Resource a ARNs específicos de perfis de inferência.

Para detalhes, veja documentação do IAM do Bedrock.

Recomendamos criar uma conta AWS dedicada para o Claude Code para simplificar o rastreamento de custos e controle de acesso.

Solução de problemas

Se você encontrar problemas de região:

• Verifique a disponibilidade do modelo: aws bedrock list-inference-profiles --region your-region
• Mude para uma região suportada: export AWS_REGION=us-east-1
• Considere usar perfis de inferência para acesso entre regiões

Se você receber um erro “on-demand throughput isn’t supported”:

• Especifique o modelo como um ID de perfil de inferência

O Claude Code usa a API Invoke do Bedrock e não suporta a API Converse.

Recursos adicionais

• Documentação do Bedrock
• Preços do Bedrock
• Perfis de inferência do Bedrock
• Claude Code no Amazon Bedrock: Guia de Configuração Rápida