Vai al contenuto principale

​
Prerequisiti

Prima di configurare Claude Code con Bedrock, assicurati di avere:
  • Un account AWS con accesso a Bedrock abilitato
  • Accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6) in Bedrock
  • AWS CLI installato e configurato (facoltativo - necessario solo se non hai un altro meccanismo per ottenere le credenziali)
  • Autorizzazioni IAM appropriate
Se stai distribuendo Claude Code a più utenti, fissa le versioni del tuo modello per evitare interruzioni quando Anthropic rilascia nuovi modelli.

​
Configurazione

​
1. Invia i dettagli del caso d’uso

I nuovi utenti dei modelli Anthropic devono inviare i dettagli del caso d’uso prima di invocare un modello. Questa operazione viene eseguita una sola volta per account.
  1. Assicurati di avere le giuste autorizzazioni IAM (vedi ulteriori informazioni di seguito)
  2. Accedi alla console di Amazon Bedrock
  3. Seleziona Chat/Text playground
  4. Scegli un modello Anthropic qualsiasi e ti verrà chiesto di compilare il modulo del caso d’uso

​
2. Configura le credenziali AWS

Claude Code utilizza la catena di credenziali predefinita di AWS SDK. Configura le tue credenziali utilizzando uno di questi metodi: Opzione A: Configurazione AWS CLI 
aws configure
Opzione B: Variabili di ambiente (chiave di accesso) 
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
Opzione C: Variabili di ambiente (profilo SSO) 
aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name
Opzione D: Credenziali della console di gestione AWS 
aws login
Scopri di più su aws login. Opzione E: Chiavi API Bedrock 
export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key
Le chiavi API Bedrock forniscono un metodo di autenticazione più semplice senza la necessità di credenziali AWS complete. Scopri di più sulle chiavi API Bedrock.

​
Configurazione avanzata delle credenziali

Claude Code supporta l’aggiornamento automatico delle credenziali per AWS SSO e provider di identità aziendali. Aggiungi queste impostazioni al file di impostazioni di Claude Code (vedi Impostazioni per i percorsi dei file). Quando Claude Code rileva che le tue credenziali AWS sono scadute (sia localmente in base al loro timestamp che quando Bedrock restituisce un errore di credenziale), eseguirà automaticamente i tuoi comandi awsAuthRefresh e/o awsCredentialExport configurati per ottenere nuove credenziali prima di riprovare la richiesta.
Configurazione di esempio
{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}
Impostazioni di configurazione spiegate
awsAuthRefresh: Usa questo per i comandi che modificano la directory .aws, come l’aggiornamento delle credenziali, della cache SSO o dei file di configurazione. L’output del comando viene visualizzato all’utente, ma l’input interattivo non è supportato. Funziona bene per i flussi SSO basati su browser in cui la CLI visualizza un URL o un codice e completi l’autenticazione nel browser. awsCredentialExport: Usa questo solo se non puoi modificare .aws e devi restituire direttamente le credenziali. L’output viene acquisito silenziosamente e non mostrato all’utente. Il comando deve restituire JSON in questo formato: 
{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value"
  }
}

​
3. Configura Claude Code

Imposta le seguenti variabili di ambiente per abilitare Bedrock: 
# Abilita integrazione Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # o la tua regione preferita

# Facoltativo: Sovrascrivi la regione per il modello piccolo/veloce (Haiku)
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2
Quando abiliti Bedrock per Claude Code, tieni presente quanto segue:
  • AWS_REGION è una variabile di ambiente obbligatoria. Claude Code non legge dal file di configurazione .aws per questa impostazione.
  • Quando si utilizza Bedrock, i comandi /login e /logout sono disabilitati poiché l’autenticazione viene gestita tramite credenziali AWS.
  • Puoi utilizzare file di impostazioni per variabili di ambiente come AWS_PROFILE che non desideri perdere in altri processi. Vedi Impostazioni per ulteriori informazioni.

​
4. Fissa le versioni del modello

Fissa versioni specifiche del modello per ogni distribuzione. Se utilizzi alias di modello (sonnet, opus, haiku) senza fissare, Claude Code potrebbe tentare di utilizzare una versione di modello più recente che non è disponibile nel tuo account Bedrock, interrompendo gli utenti esistenti quando Anthropic rilascia aggiornamenti.
Imposta queste variabili di ambiente su ID di modello Bedrock specifici: 
export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'
Queste variabili utilizzano ID di profili di inferenza tra regioni (con il prefisso us.). Se utilizzi un prefisso di regione diverso o profili di inferenza dell’applicazione, regola di conseguenza. Per gli ID di modello attuali e legacy, vedi Panoramica dei modelli. Vedi Configurazione del modello per l’elenco completo delle variabili di ambiente. Claude Code utilizza questi modelli predefiniti quando non sono impostate variabili di fissaggio:
Tipo di modelloValore predefinito
Modello primarioglobal.anthropic.claude-sonnet-4-6
Modello piccolo/veloceus.anthropic.claude-haiku-4-5-20251001-v1:0
Per personalizzare ulteriormente i modelli, utilizza uno di questi metodi: 
# Utilizzo dell'ID del profilo di inferenza
export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Utilizzo dell'ARN del profilo di inferenza dell'applicazione
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Facoltativo: Disabilita il caching dei prompt se necessario
export DISABLE_PROMPT_CACHING=1
Prompt caching potrebbe non essere disponibile in tutte le regioni.

​
Mappa ogni versione del modello a un profilo di inferenza

Le variabili di ambiente ANTHROPIC_DEFAULT_*_MODEL configurano un profilo di inferenza per famiglia di modelli. Se la tua organizzazione ha bisogno di esporre diverse versioni della stessa famiglia nel selettore /model, ciascuna instradato al suo ARN del profilo di inferenza dell’applicazione, utilizza invece l’impostazione modelOverrides nel tuo file di impostazioni. Questo esempio mappa tre versioni di Opus a ARN distinti in modo che gli utenti possano passare da uno all’altro senza aggirare i profili di inferenza della tua organizzazione: 
{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",
    "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"
  }
}
Quando un utente seleziona una di queste versioni in /model, Claude Code chiama Bedrock con l’ARN mappato. Le versioni senza un override tornano all’ID del modello Bedrock integrato o a qualsiasi profilo di inferenza corrispondente scoperto all’avvio. Vedi Sovrascrivi ID di modello per versione per i dettagli su come gli override interagiscono con availableModels e altre impostazioni del modello.

​
Configurazione IAM

Crea una policy IAM con le autorizzazioni richieste per Claude Code: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*",
        "arn:aws:bedrock:*:*:foundation-model/*"
      ]
    },
    {
      "Sid": "AllowMarketplaceSubscription",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ViewSubscriptions",
        "aws-marketplace:Subscribe"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:CalledViaLast": "bedrock.amazonaws.com"
        }
      }
    }
  ]
}
Per autorizzazioni più restrittive, puoi limitare la Resource a ARN di profili di inferenza specifici. Per i dettagli, vedi Documentazione IAM di Bedrock.
Crea un account AWS dedicato per Claude Code per semplificare il tracciamento dei costi e il controllo degli accessi.

​
AWS Guardrails

Amazon Bedrock Guardrails ti consente di implementare il filtro dei contenuti per Claude Code. Crea un Guardrail nella console di Amazon Bedrock, pubblica una versione, quindi aggiungi le intestazioni Guardrail al tuo file di impostazioni. Abilita l’inferenza tra regioni sul tuo Guardrail se stai utilizzando profili di inferenza tra regioni. Configurazione di esempio: 
{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"
  }
}

​
Risoluzione dei problemi

Se riscontri problemi di regione:
  • Controlla la disponibilità del modello: aws bedrock list-inference-profiles --region your-region
  • Passa a una regione supportata: export AWS_REGION=us-east-1
  • Considera l’utilizzo di profili di inferenza per l’accesso tra regioni
Se ricevi un errore “on-demand throughput isn’t supported”: Claude Code utilizza l’API Bedrock Invoke e non supporta l’API Converse.

​
Risorse aggiuntive