Vai al contenuto principale

​
Amazon Bedrock

OpenClaw può usare i modelli Amazon Bedrock tramite il provider di streaming Bedrock Converse di pi‑ai. L’autenticazione Bedrock usa la catena di credenziali predefinita AWS SDK, non una chiave API.

​
Cosa supporta pi-ai

  • Provider: amazon-bedrock
  • API: bedrock-converse-stream
  • Autenticazione: credenziali AWS (variabili d’ambiente, configurazione condivisa o ruolo dell’istanza)
  • Regione: AWS_REGION o AWS_DEFAULT_REGION (predefinita: us-east-1)

​
Rilevamento automatico dei modelli

OpenClaw può rilevare automaticamente i modelli Bedrock che supportano streaming e output testuale. Il rilevamento usa bedrock:ListFoundationModels e bedrock:ListInferenceProfiles, e i risultati vengono memorizzati nella cache (predefinito: 1 ora). Come viene abilitato il provider implicito:
  • Se plugins.entries.amazon-bedrock.config.discovery.enabled è true, OpenClaw proverà il rilevamento anche quando non è presente alcun marker env AWS.
  • Se plugins.entries.amazon-bedrock.config.discovery.enabled non è impostato, OpenClaw aggiunge automaticamente il provider implicito Bedrock solo quando vede uno di questi marker di autenticazione AWS: AWS_BEARER_TOKEN_BEDROCK, AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, o AWS_PROFILE.
  • Il percorso reale di autenticazione Bedrock a runtime usa comunque la catena predefinita AWS SDK, quindi configurazione condivisa, SSO e autenticazione del ruolo istanza IMDS possono funzionare anche quando il rilevamento richiede enabled: true per l’opt-in.
Le opzioni di configurazione si trovano in plugins.entries.amazon-bedrock.config.discovery: 
{
  plugins: {
    entries: {
      "amazon-bedrock": {
        config: {
          discovery: {
            enabled: true,
            region: "us-east-1",
            providerFilter: ["anthropic", "amazon"],
            refreshInterval: 3600,
            defaultContextWindow: 32000,
            defaultMaxTokens: 4096,
          },
        },
      },
    },
  },
}
Note:
  • enabled per impostazione predefinita usa la modalità automatica. In modalità automatica, OpenClaw abilita il provider implicito Bedrock solo quando vede un marker env AWS supportato.
  • region usa per impostazione predefinita AWS_REGION o AWS_DEFAULT_REGION, poi us-east-1.
  • providerFilter corrisponde ai nomi dei provider Bedrock (ad esempio anthropic).
  • refreshInterval è in secondi; impostalo a 0 per disabilitare la cache.
  • defaultContextWindow (predefinito: 32000) e defaultMaxTokens (predefinito: 4096) sono usati per i modelli rilevati (sovrascrivili se conosci i limiti del tuo modello).
  • Per voci esplicite models.providers["amazon-bedrock"], OpenClaw può comunque risolvere anticipatamente l’autenticazione Bedrock tramite marker env da marker env AWS come AWS_BEARER_TOKEN_BEDROCK senza forzare il caricamento completo dell’autenticazione runtime. Il percorso reale di autenticazione delle chiamate al modello usa comunque la catena predefinita AWS SDK.

​
Onboarding

  1. Assicurati che le credenziali AWS siano disponibili sull’host gateway:
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# Facoltativo:
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# Facoltativo (chiave API/bearer token Bedrock):
export AWS_BEARER_TOKEN_BEDROCK="..."
  1. Aggiungi un provider Bedrock e un modello alla tua configurazione (nessun apiKey richiesto):
{
  models: {
    providers: {
      "amazon-bedrock": {
        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
        api: "bedrock-converse-stream",
        auth: "aws-sdk",
        models: [
          {
            id: "us.anthropic.claude-opus-4-6-v1:0",
            name: "Claude Opus 4.6 (Bedrock)",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
    },
  },
}

​
Ruoli di istanza EC2

Quando OpenClaw viene eseguito su un’istanza EC2 con un ruolo IAM associato, AWS SDK può usare il servizio di metadata dell’istanza (IMDS) per l’autenticazione. Per il rilevamento dei modelli Bedrock, OpenClaw abilita automaticamente il provider implicito solo a partire da marker env AWS a meno che tu non imposti esplicitamente plugins.entries.amazon-bedrock.config.discovery.enabled: true. Configurazione consigliata per host supportati da IMDS:
  • Imposta plugins.entries.amazon-bedrock.config.discovery.enabled su true.
  • Imposta plugins.entries.amazon-bedrock.config.discovery.region (oppure esporta AWS_REGION).
  • Non hai bisogno di una chiave API fittizia.
  • Hai bisogno di AWS_PROFILE=default solo se vuoi specificamente un marker env per la modalità automatica o per le superfici di stato.
# Consigliato: abilitazione esplicita del rilevamento + regione
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1

# Facoltativo: aggiungi un marker env se vuoi la modalità automatica senza abilitazione esplicita
export AWS_PROFILE=default
export AWS_REGION=us-east-1
Permessi IAM richiesti per il ruolo di istanza EC2:
  • bedrock:InvokeModel
  • bedrock:InvokeModelWithResponseStream
  • bedrock:ListFoundationModels (per il rilevamento automatico)
  • bedrock:ListInferenceProfiles (per il rilevamento dei profili di inferenza)
Oppure collega la policy gestita AmazonBedrockFullAccess.

​
Configurazione rapida (percorso AWS)

# 1. Crea ruolo IAM e profilo istanza
aws iam create-role --role-name EC2-Bedrock-Access \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy --role-name EC2-Bedrock-Access \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
aws iam add-role-to-instance-profile \
  --instance-profile-name EC2-Bedrock-Access \
  --role-name EC2-Bedrock-Access

# 2. Collega all'istanza EC2
aws ec2 associate-iam-instance-profile \
  --instance-id i-xxxxx \
  --iam-instance-profile Name=EC2-Bedrock-Access

# 3. Sull'istanza EC2, abilita esplicitamente il rilevamento
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1

# 4. Facoltativo: aggiungi un marker env se vuoi la modalità automatica senza abilitazione esplicita
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc

# 5. Verifica che i modelli vengano rilevati
openclaw models list

​
Profili di inferenza

OpenClaw rileva profili di inferenza regionali e globali insieme ai foundation model. Quando un profilo corrisponde a un foundation model noto, il profilo eredita le capability di quel modello (context window, max token, reasoning, visione) e la regione di richiesta Bedrock corretta viene inserita automaticamente. Ciò significa che i profili Claude cross-region funzionano senza override manuali del provider. Gli ID dei profili di inferenza hanno un aspetto come us.anthropic.claude-opus-4-6-v1:0 (regionale) o anthropic.claude-opus-4-6-v1:0 (globale). Se il modello sottostante è già nei risultati del rilevamento, il profilo eredita l’intero set di capability; altrimenti vengono applicati valori predefiniti sicuri. Non è necessaria alcuna configurazione aggiuntiva. Finché il rilevamento è abilitato e il principal IAM ha bedrock:ListInferenceProfiles, i profili appaiono insieme ai foundation model in openclaw models list.

​
Note

  • Bedrock richiede che l’accesso al modello sia abilitato nel tuo account/regione AWS.
  • Il rilevamento automatico richiede i permessi bedrock:ListFoundationModels e bedrock:ListInferenceProfiles.
  • Se ti affidi alla modalità automatica, imposta uno dei marker env di autenticazione AWS supportati sull’ host gateway. Se preferisci autenticazione IMDS/configurazione condivisa senza marker env, imposta plugins.entries.amazon-bedrock.config.discovery.enabled: true.
  • OpenClaw espone l’origine delle credenziali in questo ordine: AWS_BEARER_TOKEN_BEDROCK, poi AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, poi AWS_PROFILE, poi la catena predefinita AWS SDK.
  • Il supporto al reasoning dipende dal modello; controlla la scheda del modello Bedrock per le capability attuali.
  • Se preferisci un flusso con chiave gestita, puoi anche mettere un proxy compatibile con OpenAI davanti a Bedrock e configurarlo invece come provider OpenAI.

​
Guardrails

Puoi applicare Amazon Bedrock Guardrails a tutte le invocazioni di modelli Bedrock aggiungendo un oggetto guardrail alla configurazione del plugin amazon-bedrock. Guardrails consente di applicare filtro dei contenuti, negazione di argomenti, filtri parole, filtri per informazioni sensibili e controlli di contextual grounding. 
{
  plugins: {
    entries: {
      "amazon-bedrock": {
        config: {
          guardrail: {
            guardrailIdentifier: "abc123", // guardrail ID or full ARN
            guardrailVersion: "1", // version number or "DRAFT"
            streamProcessingMode: "sync", // optional: "sync" or "async"
            trace: "enabled", // optional: "enabled", "disabled", or "enabled_full"
          },
        },
      },
    },
  },
}
  • guardrailIdentifier (obbligatorio) accetta un ID guardrail (ad es. abc123) o un ARN completo (ad es. arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123).
  • guardrailVersion (obbligatorio) specifica quale versione pubblicata usare, oppure "DRAFT" per la bozza di lavoro.
  • streamProcessingMode (facoltativo) controlla se la valutazione del guardrail viene eseguita in modo sincrono ("sync") o asincrono ("async") durante lo streaming. Se omesso, Bedrock usa il comportamento predefinito.
  • trace (facoltativo) abilita l’output di trace del guardrail nella risposta API. Impostalo su "enabled" o "enabled_full" per il debug; omettilo o impostalo su "disabled" per la produzione.
Il principal IAM usato dal gateway deve avere il permesso bedrock:ApplyGuardrail oltre ai permessi standard di invocazione. Bedrock può anche fungere da provider di embedding per memory search. Questo viene configurato separatamente dal provider di inferenza: imposta agents.defaults.memorySearch.provider su "bedrock": 
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0", // default
      },
    },
  },
}
Gli embedding Bedrock usano la stessa catena di credenziali AWS SDK dell’inferenza (ruoli istanza, SSO, chiavi di accesso, configurazione condivisa e web identity). Non è necessaria alcuna chiave API. Quando provider è "auto", Bedrock viene rilevato automaticamente se quella catena di credenziali viene risolta correttamente. I modelli di embedding supportati includono Amazon Titan Embed (v1, v2), Amazon Nova Embed, Cohere Embed (v3, v4) e TwelveLabs Marengo. Vedi Riferimento della configurazione memory — Bedrock per l’elenco completo dei modelli e le opzioni di dimensione.