SpyBara
Go Premium

amazon-bedrock.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 143 additions and 81 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Claude Code su Amazon Bedrock

Scopri come configurare Claude Code tramite Amazon Bedrock, inclusa la configurazione, la configurazione IAM e la risoluzione dei problemi.

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.
<a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

Prerequisiti

Prima di configurare Claude Code con Amazon Bedrock, assicurati di avere:

  • Un account AWS con accesso a Amazon Bedrock abilitato
  • Accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6) in Amazon Bedrock
  • AWS CLI installato e configurato (facoltativo - necessario solo se non hai un altro meccanismo per ottenere le credenziali)
  • Autorizzazioni IAM appropriate

Per accedere con le tue credenziali Amazon Bedrock, segui Accedi con Amazon Bedrock di seguito. Per distribuire Claude Code in un team, utilizza i passaggi di configurazione manuale e fissa le versioni del tuo modello prima del rollout.

Accedi con Bedrock

Se disponi di credenziali AWS e desideri iniziare a utilizzare Claude Code tramite Amazon Bedrock, la procedura guidata di accesso ti guida attraverso i passaggi. Completi i prerequisiti lato AWS una volta per account; la procedura guidata gestisce il lato Claude Code.

1

Abilita i modelli Anthropic nel tuo account AWS

Nella console di Amazon Bedrock, apri il catalogo dei modelli, seleziona un modello Anthropic e invia il modulo del caso d'uso. L'accesso viene concesso immediatamente dopo l'invio. Consulta Invia i dettagli del caso d'uso per AWS Organizations e Configurazione IAM per le autorizzazioni di cui il tuo ruolo ha bisogno.

2

Avvia Claude Code e scegli Amazon Bedrock

Esegui claude. Al prompt di accesso, seleziona piattaforma di terze parti, quindi Amazon Bedrock. Se sei già connesso e visualizzi il prompt della chat, esegui /setup-bedrock per aprire la procedura guidata. Finché CLAUDE_CODE_USE_BEDROCK=1 non è impostato, Claude Code nasconde il comando dal menu dei comandi; digitalo per intero.

3

Segui i prompt della procedura guidata

Scegli come autenticarti ad AWS: un profilo AWS rilevato dalla tua directory ~/.aws, una chiave API di Amazon Bedrock, una chiave di accesso e un segreto, o credenziali già presenti nel tuo ambiente. La procedura guidata chiede la tua regione, verifica quali modelli Claude il tuo account può invocare e ti consente di fissarli. Salva il risultato nel blocco env del tuo file di impostazioni utente, quindi non è necessario esportare variabili di ambiente da solo.

Dopo aver effettuato l'accesso, esegui /setup-bedrock in qualsiasi momento per riaprire la procedura guidata e modificare le tue credenziali, regione o pin dei modelli. Il passaggio del pin del modello inizia dai tuoi modelli attualmente fissati. La procedura guidata scrive in ~/.claude/settings.json, o in $CLAUDE_CONFIG_DIR/settings.json quando CLAUDE_CONFIG_DIR è impostato.

Configurazione manuale

Per configurare Amazon Bedrock tramite variabili di ambiente invece della procedura guidata, ad esempio in CI o in un rollout aziendale con script, seguire i passaggi di seguito.

1. Inviare i dettagli del caso d'uso

Prima di invocare un modello Anthropic per la prima volta, inviare i dettagli del caso d'uso. Questa operazione viene eseguita una volta per account AWS.

  1. Assicurarsi di disporre delle autorizzazioni IAM corrette descritte di seguito
  2. Navigare alla console di Amazon Bedrock
  3. Selezionare un modello Anthropic dal Catalogo modelli
  4. Completare il modulo del caso d'uso. L'accesso viene concesso immediatamente dopo l'invio.

Se si utilizza AWS Organizations, è possibile inviare il modulo una volta dall'account di gestione utilizzando l'API PutUseCaseForModelAccess. Questa chiamata richiede l'autorizzazione IAM bedrock:PutUseCaseForModelAccess. L'approvazione si estende automaticamente agli account figlio.

2. Configurare le credenziali AWS

Claude Code utilizza la catena di credenziali predefinita dell'SDK AWS. Configurare le 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)

Sostituire your-profile-name con il nome del profilo AWS prima di eseguire questi comandi.

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

export AWS_PROFILE=your-profile-name

Claude Code richiede credenziali di ruolo dalla regione IAM Identity Center denominata da sso_region del profilo, che non deve corrispondere alla regione in cui si esegue Amazon Bedrock. Nella versione 2.1.207, la regione di Amazon Bedrock ha sovrascritto sso_region, quindi un profilo la cui istanza di IAM Identity Center si trova in una regione diversa non è riuscito ad autenticarsi con un errore Session token not found or invalid.

Opzione D: Credenziali della console di gestione AWS

aws login

Ulteriori informazioni su aws login.

Opzione E: Chiavi API di Amazon Bedrock

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Le chiavi API di Amazon Bedrock forniscono un metodo di autenticazione più semplice senza la necessità di credenziali AWS complete. Ulteriori informazioni sulle chiavi API di Amazon Bedrock.

Caching delle credenziali e timeout di risoluzione

Claude Code risolve la catena del provider di credenziali predefinito AWS una volta e mantiene le credenziali risolte in memoria. Le riutilizza fino a cinque minuti prima della scadenza, o per un'ora quando non hanno scadenza, quindi un profilo supportato da SSO richiede credenziali da IAM Identity Center circa una volta per durata della credenziale. Un errore di credenziale dall'API cancella la cache e il nuovo tentativo risolve credenziali aggiornate. Richiede Claude Code v2.1.207 o successiva.

La cache copre tutte le opzioni di credenziale sopra elencate tranne una chiave API di Amazon Bedrock, che non utilizza la catena del provider. Per risolvere la catena su ogni richiesta, impostare CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1.

Ogni risoluzione della catena scade dopo 60 secondi. Se un passaggio della catena si blocca, ad esempio un helper credential_process che attende un input che non può ricevere, la richiesta non riesce con AWS default-chain credential resolve timed out. Se la catena esegue un accesso interattivo che legittimamente ha bisogno di più tempo, come SSO basato su browser con MFA tramite un wrapper come aws-vault, aumentare il limite in millisecondi con CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS. Prima della versione 2.1.207, una risoluzione di credenziale bloccata lasciava la richiesta in attesa indefinitamente.

Configurazione avanzata delle credenziali

Claude Code supporta l'aggiornamento automatico delle credenziali per AWS SSO e provider di identità aziendali. Aggiungere queste impostazioni al file di impostazioni di Claude Code (vedere Settings per i percorsi dei file).

Queste due impostazioni hanno diverse condizioni di attivazione:

  • awsAuthRefresh: viene eseguito solo quando Claude Code rileva che le credenziali AWS sono scadute, localmente in base al loro timestamp o quando l'API restituisce un errore di credenziale, quindi ritenta la richiesta con credenziali aggiornate.
  • awsCredentialExport: viene eseguito all'avvio della sessione e su ogni ricaricamento delle credenziali, anche quando le credenziali nella catena del provider di credenziali predefinito AWS sono ancora valide. Utilizzare questa opzione quando l'account Amazon Bedrock richiede credenziali tra account che differiscono da quelle che la catena del provider predefinito risolverebbe.

Prima di eseguire il comando awsAuthRefresh, Claude Code effettua una chiamata STS GetCallerIdentity per confermare che le credenziali sono effettivamente scadute e ignora il comando quando funzionano ancora. Claude Code invia questo controllo attraverso la configurazione del proxy, rispettando HTTPS_PROXY e NO_PROXY. Prima della versione 2.1.239, Claude Code inviava questo controllo direttamente e si bloccava all'avvio su reti che consentono solo l'uscita attraverso un proxy.

Configurazione di esempio 
{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}
Impostazioni di configurazione spiegate

awsAuthRefresh: Utilizzare questa opzione 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 si completa l'autenticazione nel browser.

awsCredentialExport: Utilizzare solo se non è possibile modificare .aws e si devono 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",
    "Expiration": "2026-01-01T00:00:00Z"
  }
}

A partire da Claude Code v2.1.181, l'output flat da aws configure export-credentials --format process è accettato anche, con le stesse chiavi al livello superiore invece di annidate sotto Credentials.

Expiration è facoltativo. A partire da Claude Code v2.1.176, quando il comando restituisce un Expiration ISO 8601 valido, Claude Code memorizza nella cache le credenziali fino a cinque minuti prima di quel momento. Senza di esso, o nelle versioni precedenti, le credenziali vengono memorizzate nella cache per un'ora.

Quando si configura awsCredentialExport senza awsAuthRefresh, Claude Code utilizza le credenziali esportate direttamente e non ri-risolve la catena del provider di credenziali predefinito AWS all'avvio. Richiede Claude Code v2.1.206 o successiva.

3. Configurare Claude Code

Impostare le seguenti variabili di ambiente per abilitare Amazon Bedrock:

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # optional if your AWS profile already sets a region

# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).
# On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL
# or the deprecated ANTHROPIC_SMALL_FAST_MODEL set.
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

Quando si abilita Amazon Bedrock per Claude Code, tenere presente quanto segue:

  • A partire dalla versione 2.1.172, è necessario impostare AWS_REGION solo per sovrascrivere la regione del profilo AWS o quando il profilo non ha una regione. Claude Code risolve la regione in questo ordine:

    • AWS_REGION
    • AWS_DEFAULT_REGION
    • la region impostata sul profilo AWS attivo, letta dal file delle credenziali condivise AWS per primo e poi dal file di configurazione condiviso, corrispondendo alla precedenza dell'SDK AWS
    • us-east-1

    Se un valore da una qualsiasi di queste fonti non ha la forma di un nome di regione, Claude Code lo tratta come non impostato e continua verso il basso nell'ordine. Ad esempio, Claude Code tratta un valore contenente una barra, un punto o uno spazio come non impostato.

    Il profilo attivo è AWS_PROFILE se impostato, altrimenti default. Impostare AWS_SHARED_CREDENTIALS_FILE o AWS_CONFIG_FILE per puntare a percorsi di file non predefiniti.

    Eseguire /status per visualizzare la regione risolta. Quando la regione proviene dai file di configurazione AWS o dal fallback predefinito, Claude Code nota anche la fonte nell'output /status. Nella versione 2.1.171 e precedenti, Claude Code non legge i file di configurazione AWS, quindi impostare AWS_REGION esplicitamente.

  • Quando si utilizza Amazon Bedrock, il comando /logout non è disponibile poiché l'autenticazione viene gestita tramite credenziali AWS.

  • Lo strumento WebSearch non è disponibile su Amazon Bedrock. Vedere Comportamento dello strumento WebSearch.

  • È possibile utilizzare file di impostazioni per variabili di ambiente come AWS_PROFILE che non si desidera perdere in altri processi. Vedere Settings per ulteriori informazioni.

4. Fissare le versioni del modello

Impostare queste variabili di ambiente su ID modello Amazon Bedrock specifici.

Senza ANTHROPIC_DEFAULT_OPUS_MODEL, l'alias opus su Amazon Bedrock si risolve in Opus 5, e senza ANTHROPIC_DEFAULT_SONNET_MODEL, l'alias sonnet si risolve in Sonnet 4.5. Questo esempio fissa ogni alias a una versione specifica:

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
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'

Questi ID utilizzano il prefisso del profilo di inferenza tra regioni us.. Se si utilizza un prefisso di regione diverso o profili di inferenza dell'applicazione, regolare di conseguenza. Nelle regioni AWS GovCloud, utilizzare il prefisso us-gov..

Per mantenere i modelli predefiniti integrati e modificare solo il loro prefisso preferito, impostare ANTHROPIC_BEDROCK_REGION_PREFIX invece di fissare. La differenza si mostra in ciò a cui l'alias opus si risolve:

Si imposta L'alias opus si risolve in
ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8' us.anthropic.claude-opus-4-8, l'ID esatto che hai fissato
ANTHROPIC_BEDROCK_REGION_PREFIX=eu eu.anthropic.claude-opus-5, il valore predefinito integrato con il prefisso preferito

Per gli ID modello attuali e legacy, vedere Panoramica dei modelli. Per l'elenco completo delle variabili di ambiente di fissaggio, vedere Configurazione del modello.

Claude Code utilizza questi modelli predefiniti quando non sono impostate variabili di fissaggio:

Tipo di modello Modello predefinito
Modello primario Opus 5, ad esempio us.anthropic.claude-opus-5 in una regione us-*
Modello piccolo/veloce Sonnet 4.5, ad esempio us.anthropic.claude-sonnet-4-5-20250929-v1:0 in una regione us-*

Le attività in background come la generazione del titolo della sessione utilizzano il modello piccolo/veloce, normalmente un modello di classe Haiku. Su Amazon Bedrock, Claude Code utilizza il modello Sonnet predefinito per le attività in background perché Haiku potrebbe non essere abilitato in ogni account o regione. Due selezioni cambiano quale modello li trasporta:

  • Quando si seleziona un modello primario con --model, ANTHROPIC_MODEL o l'impostazione model, le attività in background utilizzano quel modello. Quando Claude Code avvia la sessione sul modello impostato con ANTHROPIC_DEFAULT_MODEL, le attività in background utilizzano anche quel modello. L'impostazione di ANTHROPIC_DEFAULT_OPUS_MODEL senza ANTHROPIC_DEFAULT_SONNET_MODEL conta anche come una selezione, perché il modello Sonnet integrato potrebbe non essere abilitato in un account che indirizza il proprio Opus.
  • Per utilizzare Haiku per le attività in background, impostare ANTHROPIC_DEFAULT_HAIKU_MODEL su un ID modello disponibile nel proprio account.

Nella versione 2.1.207 fino a 2.1.218, il modello primario su Amazon Bedrock era predefinito su Opus 4.8 e l'alias opus si risolveva in Opus 4.8. Prima della versione 2.1.207, il modello primario era predefinito su Sonnet 4.5, l'alias opus si risolveva in Opus 4.6 e le attività in background utilizzavano sempre il modello primario.

Per personalizzare ulteriormente i modelli, utilizzare uno di questi metodi:

# Using inference profile ID
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Using application inference profile ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Optional: Disable prompt caching if needed
# export DISABLE_PROMPT_CACHING=1

# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default
# export ENABLE_PROMPT_CACHING_1H=1

Il TTL della cache di 1 ora viene fatturato a una tariffa più elevata rispetto al valore predefinito di 5 minuti. Vedere durata della cache. Per impostare TTL diversi per la conversazione principale e per le richieste che Claude Code effettua al di fuori di essa, scegliere il TTL da soli.

Mappare 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 l'organizzazione ha bisogno di esporre diverse versioni della stessa famiglia nel selettore /model, ciascuna indirizzata al proprio ARN del profilo di inferenza dell'applicazione, utilizzare l'impostazione modelOverrides nel file di impostazioni.

Questo esempio mappa quattro versioni di Opus a ARN distinti in modo che gli utenti possano passare tra loro senza aggirare i profili di inferenza dell'organizzazione:

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",
    "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 Amazon Bedrock con l'ARN mappato. La stessa mappatura si applica quando si passa l'ID modello Anthropic direttamente tramite --model o ANTHROPIC_MODEL. Le versioni senza un override ritornano all'ID modello Amazon Bedrock integrato o a qualsiasi profilo di inferenza corrispondente scoperto all'avvio. Prima della versione 2.1.200, i valori --model e ANTHROPIC_MODEL raggiungevano Amazon Bedrock così come erano senza passare attraverso la mappa di override. Vedere Override degli ID modello per versione per i dettagli su come gli override interagiscono con availableModels e altre impostazioni del modello.

Controlli del modello all'avvio

Quando Claude Code si avvia con Amazon Bedrock configurato, verifica che i modelli che intende utilizzare siano accessibili nel vostro account.

Se avete fissato una versione del modello più vecchia rispetto al valore predefinito corrente di Claude Code, e il vostro account può richiamare la versione più recente, Claude Code vi chiede di aggiornare il pin. Accettando si scrive il nuovo ID del modello nel vostro file di impostazioni utente e si riavvia Claude Code. Rifiutando viene ricordato fino al prossimo cambio della versione predefinita. I pin che puntano a un ARN del profilo di inferenza dell'applicazione vengono saltati, poiché sono gestiti dall'amministratore.

Se non avete fissato un modello e il valore predefinito corrente non è disponibile nel vostro account, Claude Code esegue il fallback per la sessione corrente e mostra un avviso. Prova prima le versioni precedenti del modello predefinito e, quando il valore predefinito è un modello Opus e nessuna versione Opus è disponibile, esegue il fallback al modello Sonnet predefinito. Il fallback non viene mantenuto. Abilitate il modello più recente nel vostro account Amazon Bedrock o fissate una versione per rendere permanente la scelta.

Quando avviate la sessione su una versione specifica di Sonnet oppure Opus, ad esempio con --model, ANTHROPIC_MODEL, o l'impostazione model, quella versione agisce come valore predefinito fissato della sessione per l'alias sonnet oppure opus corrispondente. Claude Code salta il controllo di disponibilità per il valore predefinito integrato che il vostro modello sostituisce e si avvia sul modello che avete configurato, senza alcun avviso di fallback.

Gli alias dei modelli come opus non agiscono come pin, e nemmeno un ID del modello che Claude Code non riconosce, come un ARN del profilo di inferenza dell'applicazione.

Prefissi del profilo di inferenza tra regioni

Sull'API Amazon Bedrock Invoke API, Claude Code risolve i suoi modelli predefiniti incorporati agli ID del profilo di inferenza tra regioni; per instradare le versioni dei modelli attraverso i vostri profili di inferenza, consultate Mappare ogni versione del modello a un profilo di inferenza. Questa tabella mostra il prefisso che Claude Code preferisce per ogni regione AWS risolta:

Regione AWS Prefisso
us-gov-* (AWS GovCloud) us-gov.
us-* us.
eu-* eu.
ap-* apac.
Tutte le altre regioni global.

Impostare ANTHROPIC_BEDROCK_REGION_PREFIX per scegliere il prefisso che Claude Code prova per primo; quando Claude Code può verificare la disponibilità del profilo e non trova alcun profilo corrispondente per un modello, esegue il fallback come descritto nell'ordine di risoluzione di seguito. I valori validi sono us, eu, apac, jp, au e global. Ad esempio, impostatelo su global quando il vostro account ha profili global. abilitati ma Claude Code ne deriverebbe uno specifico della geografia dalla vostra regione AWS. Richiede Claude Code v2.1.224 o successivo.

Questo esempio instrada i modelli predefiniti attraverso profili global.:

export ANTHROPIC_BEDROCK_REGION_PREFIX=global
# In a us-* region, the primary model now resolves to
# global.anthropic.claude-opus-5 instead of us.anthropic.claude-opus-5

Il prefisso preferito è una preferenza, non una garanzia, indipendentemente dal fatto che provenga dalla vostra regione o dalla variabile. Il modo in cui Claude Code lo applica dipende dal fatto che possa verificare la disponibilità del profilo nel vostro account:

  • Quando Claude Code può elencare i profili di inferenza nel vostro account, risolve ogni modello in questo ordine:
    1. Il profilo con il vostro prefisso preferito.
    2. Qualsiasi profilo corrispondente, per un modello che non ha un profilo con quel prefisso.
    3. L'ID del modello incorporato con il vostro prefisso preferito, per un modello che non ha alcun profilo corrispondente. Claude Code applica questo ID senza verificare la disponibilità in questo passaggio; i controlli del modello di avvio coprono comunque i modelli predefiniti della sessione.
  • Quando l'individuazione del profilo non è disponibile, Claude Code applica il prefisso senza verificare la disponibilità. Se il vostro account non ha profili di inferenza con quel prefisso abilitati, le richieste non riescono con un errore 400.

Claude Code non riscrive gli ID dei profili di inferenza Amazon Bedrock o gli ARN che configurate voi stessi, o i valori modelOverrides; gli ID dei modelli in formato Anthropic si risolvono attraverso la stessa mappatura del selettore /model. Claude Code ignora inoltre la variabile in due casi:

  • Nelle regioni AWS GovCloud, Claude Code utilizza sempre us-gov., l'unico prefisso che instrada all'interno della partizione GovCloud.
  • Quando impostate un valore che non è uno dei valori validi, Claude Code esegue il fallback al prefisso preferito derivato dalla regione.

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",
        "bedrock:GetInferenceProfile"
      ],
      "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.

bedrock:GetInferenceProfile consente a Claude Code di risolvere un ARN del profilo di inferenza dell'applicazione al suo modello di fondazione di supporto, che viene utilizzato per selezionare la forma di richiesta corretta per quel modello.

Se il token non dispone di questa autorizzazione, Claude Code si recupera automaticamente ritentando una volta con la forma alternativa, quindi le richieste hanno comunque successo ma ogni nuovo modello aggiunge un round-trip aggiuntivo. Concedere l'autorizzazione evita il retry. Questo si applica più spesso alle distribuzioni AWS_BEARER_TOKEN_BEDROCK, dove la policy del token è tipicamente più ristretta di un ruolo IAM completo.

Per i dettagli, vedi Documentazione IAM di Amazon Bedrock.

Finestra di contesto da 1M token

Claude Sonnet 5, Opus 4.6 e versioni successive, e Sonnet 4.6 supportano la finestra di contesto da 1M token su Amazon Bedrock. Sonnet 5 funziona sempre con la finestra da 1M sia sull'API Invoke che sull'endpoint Mantle, senza alcuna variante [1m] da selezionare. Per gli altri modelli sull'API Invoke, Claude Code abilita automaticamente la finestra di contesto estesa quando selezioni una variante di modello da 1M.

La procedura guidata di configurazione offre un'opzione di contesto da 1M quando fissa i modelli. Per abilitarla per un modello fissato manualmente, aggiungi [1m] all'ID del modello. Vedi Fissa i modelli per distribuzioni di terze parti per i dettagli.

Livelli di servizio

I livelli di servizio di Amazon Bedrock ti consentono di scambiare il costo rispetto alla latenza. Imposta ANTHROPIC_BEDROCK_SERVICE_TIER su default, flex o priority:

export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

Claude Code invia questo come intestazione X-Amzn-Bedrock-Service-Tier su ogni richiesta. La disponibilità del livello varia in base al modello e alla regione. La capacità riservata utilizza un ARN di throughput fornito come ID del modello invece di questa impostazione.

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"
  }
}

Se la tua organizzazione fornisce le intestazioni del guardrail attraverso una politica di gateway delle app Claude, contano come impostazioni che richiedono approvazione.

Utilizza l'endpoint Mantle

Mantle è un endpoint di Amazon Bedrock che serve i modelli Claude attraverso la forma API nativa di Anthropic piuttosto che l'API Invoke di Amazon Bedrock. Utilizza le stesse credenziali AWS, autorizzazioni IAM e configurazione awsAuthRefresh descritte in precedenza in questa pagina.

Abilita Mantle

Con le credenziali AWS già configurate, imposta CLAUDE_CODE_USE_MANTLE per instradare le richieste all'endpoint Mantle:

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION=us-east-1

Claude Code costruisce l'URL dell'endpoint dalla regione AWS. A partire da v2.1.172, la regione viene risolta con la stessa precedenza di Amazon Bedrock sopra; le versioni precedenti utilizzano solo AWS_REGION. Per sovrascrivere l'URL per un endpoint personalizzato o gateway, imposta ANTHROPIC_BEDROCK_MANTLE_BASE_URL.

Esegui /status all'interno di Claude Code per confermare. La riga del provider mostra Amazon Bedrock (Mantle) quando Mantle è attivo.

Seleziona un modello Mantle

Mantle utilizza ID di modello con prefisso anthropic. e senza suffisso di versione, ad esempio anthropic.claude-sonnet-5 o anthropic.claude-haiku-4-5. I modelli disponibili per il tuo account dipendono da ciò che la tua organizzazione ha ricevuto; gli ID di modello aggiuntivi sono elencati nei tuoi materiali di onboarding da AWS. Contatta il tuo team di account AWS per richiedere l'accesso ai modelli consentiti.

Imposta il modello con il flag --model o con /model all'interno di Claude Code:

claude --model anthropic.claude-haiku-4-5

Esegui Mantle insieme all'API Invoke

I modelli disponibili per te su Mantle potrebbero non includere ogni modello che utilizzi oggi. Impostare sia CLAUDE_CODE_USE_BEDROCK che CLAUDE_CODE_USE_MANTLE consente a Claude Code di chiamare entrambi gli endpoint dalla stessa sessione. Gli ID di modello che corrispondono al formato Mantle vengono instradati a Mantle, e tutti gli altri ID di modello vanno all'API Invoke di Amazon Bedrock.

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

Per visualizzare un modello Mantle nel selettore /model, elenca il suo ID in availableModels nel tuo file di impostazioni. Questa impostazione limita anche il selettore alle voci elencate. L'elenco di anthropic.claude-haiku-4-5 rimuove l'alias bare haiku dal selettore, quindi elenca anche i prefissi di versione o gli ID completi per le versioni che desideri mantenere selezionabili. L'ID Mantle e l'alias haiku si risolvono nella stessa famiglia di modelli, quindi l'unione mantiene solo la voce più specifica. Vedi Comportamento di unione:

{
  "availableModels": ["opus", "sonnet", "claude-haiku-4-5", "anthropic.claude-haiku-4-5"]
}

Le voci con il prefisso anthropic. vengono aggiunte come opzioni del selettore personalizzato e instradate a Mantle. Sostituisci anthropic.claude-haiku-4-5 con l'ID del modello che il tuo account ha ricevuto. Vedi Limita la selezione del modello per come availableModels interagisce con altre impostazioni del modello.

Quando entrambi i provider sono attivi, /status mostra Amazon Bedrock + Amazon Bedrock (Mantle).

Instrada Mantle attraverso un gateway

Se la tua organizzazione instrada il traffico del modello attraverso un gateway LLM centralizzato che inietta le credenziali AWS lato server, disabilita l'autenticazione lato client in modo che Claude Code invii richieste senza firme SigV4 o intestazioni x-api-key:

export CLAUDE_CODE_USE_MANTLE=1
export CLAUDE_CODE_SKIP_MANTLE_AUTH=1
export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

Variabili di ambiente Mantle

Queste variabili sono specifiche dell'endpoint Mantle. Vedi Variabili di ambiente per l'elenco completo.

Variabile Scopo
CLAUDE_CODE_USE_MANTLE Abilita l'endpoint Mantle. Imposta su 1 o true.
ANTHROPIC_BEDROCK_MANTLE_BASE_URL Sovrascrivi l'URL dell'endpoint Mantle predefinito
CLAUDE_CODE_SKIP_MANTLE_AUTH Salta l'autenticazione lato client per configurazioni proxy
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION Sovrascrivi la regione AWS per il modello della classe Haiku (condiviso con Amazon Bedrock)

Risoluzione dei problemi

Loop di autenticazione con SSO e proxy aziendali

Se le schede del browser si aprono ripetutamente quando si utilizza AWS SSO, rimuovi l'impostazione awsAuthRefresh dal tuo file di impostazioni. Questo può accadere quando le VPN aziendali o i proxy di ispezione TLS interrompono il flusso del browser SSO. Claude Code tratta la connessione interrotta come un errore di autenticazione, riesegue awsAuthRefresh e si ripete indefinitamente.

Se il tuo ambiente di rete interferisce con i flussi SSO automatici basati su browser, utilizza aws sso login manualmente prima di avviare Claude Code invece di affidarti a awsAuthRefresh.

Problemi di regione

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 Amazon Bedrock Invoke e non supporta l'API Converse.

Errori di streaming dietro un gateway o proxy

Amazon Bedrock trasmette le risposte InvokeModelWithResponseStream in un formato binario event-stream con l'intestazione Content-Type: application/vnd.amazon.eventstream. Un gateway o proxy tra Claude Code e Amazon Bedrock deve inoltrare il corpo della risposta e le sue intestazioni, incluso Content-Type, così come Amazon Bedrock le ha inviate.

Se il gateway riscrive Content-Type in un altro valore, Claude Code rifiuta la risposta con un errore che inizia con Bedrock streaming response has content-type, indicando il valore che ha ricevuto. La riscrittura comune è text/event-stream, da un'integrazione che ri-emette il flusso come server-sent events.

Se il gateway elimina o cancella l'intestazione, Claude Code presume che il corpo sia il flusso di eventi di Amazon Bedrock e lo decodifica, quindi un corpo che il gateway ha fatto passare senza modifiche continua a trasmettere.

Se un gateway che elimina l'intestazione ri-emette anche il flusso come server-sent events, Claude Code non può decodificare il corpo e ricade su un percorso più lento senza streaming ad ogni turno: ogni risposta appare solo una volta completata invece di trasmettere. In quel caso, imposta CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT=1 in modo che Claude Code legga il corpo come server-sent events.

Per correggere l'errore o il fallback, configura il gateway per inoltrare il corpo della risposta InvokeModelWithResponseStream e la sua intestazione Content-Type senza modifiche.

Un gateway che converte il flusso in server-sent events non sta più servendo l'API Amazon Bedrock. Se accetta anche richieste dell'API Anthropic Messages, connettiti ad esso come gateway LLM con ANTHROPIC_BASE_URL invece di CLAUDE_CODE_USE_BEDROCK.

Conteggi di token zero in /context

Il comando /context conta i token per ogni gruppo di strumenti inviando gli schemi degli strumenti all'API count-tokens di Amazon Bedrock. Nelle versioni di Claude Code precedenti a v2.1.196, Amazon Bedrock ha rifiutato quella richiesta perché gli schemi contenevano campi che la sua API count-tokens non accetta, quindi ogni gruppo di strumenti mostrava 0 token. Altre righe nella suddivisione, come i messaggi e i file di memoria, non sono interessati.

Aggiorna a v2.1.196 o versione successiva.

Errori dell'endpoint Mantle

Se /status non mostra Amazon Bedrock (Mantle) dopo aver impostato CLAUDE_CODE_USE_MANTLE, la variabile non sta raggiungendo il processo. Conferma che sia esportata nella shell in cui hai lanciato claude, o impostala nel blocco env del tuo file di impostazioni.

Un 403 dall'endpoint Mantle con credenziali valide significa che il tuo account AWS non ha ricevuto l'accesso al modello che hai richiesto. Contatta il tuo team di account AWS per richiedere l'accesso.

Un 400 che nomina l'ID del modello significa che quel modello non è servito su Mantle. Mantle ha il suo proprio lineup di modelli separato dal catalogo Amazon Bedrock standard, quindi gli ID del profilo di inferenza come us.anthropic.claude-sonnet-4-6 non funzioneranno. Utilizza un ID nel formato Mantle, o abilita entrambi gli endpoint in modo che Claude Code instrada ogni richiesta all'endpoint in cui il modello è disponibile.

Risorse aggiuntive