Vai al contenuto principale
Una distribuzione del gateway delle app Claude è configurata da un file YAML, convenzionalmente gateway.yaml. Il file definisce tutto ciò che il gateway fa: dove ascolta, come gli sviluppatori accedono, dove va l’inferenza e quali criteri e telemetria si applicano. Questa pagina è il riferimento per ogni opzione in quel file. Per scrivere il vostro primo file, iniziate dalla guida rapida, che crea una configurazione minima funzionante e la esegue; una volta che avete una configurazione con cui siete soddisfatti, la guida alla distribuzione copre la containerizzazione e l’hosting su Kubernetes, Cloud Run o la vostra piattaforma. Il gateway legge il file una volta, all’avvio, con claude gateway --config /path/to/gateway.yaml. Ogni opzione è convalidata rispetto a uno schema all’avvio, quindi una configurazione malformata non riesce all’inizio con un errore a livello di campo piuttosto che al primo utilizzo. L’esempio completo alla fine di questa pagina esercita ogni sezione.

Struttura del file

Cinque sezioni sono obbligatorie. Ogni altra sezione è facoltativa e una sezione omessa assume i suoi valori predefiniti. Le chiavi sconosciute causano un errore all’avvio, quindi un errore di battitura emerge come errore denominato piuttosto che come impostazione ignorata silenziosamente. Sezioni obbligatorie:
  • listen: indirizzo di binding, URL pubblico, terminazione TLS
  • oidc: il vostro provider di identità (IdP), inclusi emittente, client, mappatura dei claim e chi può accedere
  • session: i token bearer che il gateway conia, con segreto e durata
  • store: PostgreSQL, per le concessioni dei dispositivi e i contatori dei limiti di velocità
  • upstreams: dove va l’inferenza, sia Anthropic, Bedrock, Agent Platform o Foundry
Sezioni facoltative:
  • admin: autenticazione dell’API Admin e conservazione dei limiti di spesa
  • enforcement: comportamento fail-open o fail-closed dei limiti di spesa
  • models e auto_include_builtin_models: elenco di modelli curato dall’amministratore e ID per upstream
  • managed: politiche di impostazioni gestite per gruppo IdP
  • telemetry: inoltro OTLP al vostro stack di osservabilità
  • access_control, limits, timeouts, rate_limits: IP allow/deny, limiti di dimensione delle richieste, time-to-first-byte upstream e limiti di accesso per IP

Espansione dei segreti

Non scrivete segreti come client_secret, jwt_secret o postgres_url direttamente in gateway.yaml. Fate riferimento ad essi con uno dei moduli sottostanti e il gateway risolve il valore all’avvio da una variabile di ambiente o da un file:
ModuloSi risolve inUsare per
${VAR}La variabile di ambiente VAR. L’avvio fallisce se non definita.Variabili di ambiente del contenitore, AWS Secrets Manager tramite iniezione env
${file:/path}Contenuti del file, ritagliatiMontaggi di volumi Kubernetes Secret, Vault Agent, SOPS

Sezioni obbligatorie

listen

Il blocco listen controlla dove il gateway serve: l’indirizzo di binding e la porta, l’origine visibile esternamente e la terminazione TLS facoltativa.
CampoObbligatorioDescrizione
hostNoIndirizzo di binding. Predefinito 0.0.0.0.
portNoPorta di binding. Predefinito 8080.
public_urlDietro un proxyL’origine https:// visibile esternamente, utilizzata per costruire il redirect_uri dell’IdP e i metadati di scoperta. Obbligatorio dietro qualsiasi proxy che termina TLS come un ALB, Ingress o Cloud Run, perché il gateway non si fida degli header X-Forwarded-* quando costruisce la sua stessa origine; sono falsificabili dal client. trusted_proxies di seguito governa solo la risoluzione dell’IP del client. Obbligatorio anche per abilitare la telemetria, perché il gateway costruisce l’endpoint OTLP che spinge ai client da questo URL.
tls.cert / tls.keyNoPercorsi PEM se il gateway termina TLS stesso
trusted_proxiesNoCIDR o IP dei load balancer davanti al gateway. Quando impostato, il gateway si fida di X-Forwarded-For solo da questi peer e registra l’IP client reale per il rate limiting per IP e l’audit. Equivalente a nginx set_real_ip_from.

oidc

OpenID Connect (OIDC) è il protocollo SSO che il gateway utilizza con il vostro provider di identità; vedere Configurazione del provider di identità per ciò che registrare sul lato IdP. Il blocco oidc connette il gateway al vostro provider di identità e decide chi può accedere. Nomina l’emittente e il client OAuth, mappa i claim che portano email e gruppi e limita l’accesso per dominio email o gruppo.
CampoObbligatorioDescrizione
issuerBase di scoperta OIDC. Deve servire la scoperta su /.well-known/openid-configuration. Usate HTTPS in produzione; il gateway accetta un emittente http://. Un emittente loopback come http://localhost:8081 è rifiutato dalla guardia SSRF a meno che CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 non sia impostato nell’ambiente del gateway.
client_id / client_secretDalla vostra registrazione del client OAuth
allowed_email_domainsNoRifiutate i token id i cui claim email non sono in uno di questi domini, case-insensitive. Difesa in profondità contro la misconfiguration dell’IdP multi-tenant. Indipendentemente da questa impostazione, un id_token il cui claim email_verified è esplicitamente false è sempre rifiutato.
allowed_groupsNoLimitate l’accesso ai membri di questi gruppi IdP, abbinati rispetto a groups_claim. Un utente in un dominio email consentito ma in nessuno di questi gruppi è rifiutato. Richiede che l’IdP emetta il claim dei gruppi.
groups_claimNoQuale claim id_token porta l’appartenenza al gruppo. Predefinito groups. Microsoft Entra emette i ruoli dell’app sotto roles. Accetta una chiave flat o un JSON Pointer RFC 6901 come /resource_access/gateway/roles per i claim annidati.
google_groupsNoCercate i gruppi dell’utente che ha effettuato l’accesso tramite l’API Google Workspace Admin SDK Directory, perché il token id di Google non porta alcun claim di gruppi. Impostate service_account_json_path su un file di chiave dell’account di servizio con delega a livello di dominio sull’ambito https://www.googleapis.com/auth/admin.directory.group.readonly e admin_email su un amministratore di Workspace che l’account di servizio rappresenta; l’API Directory richiede un soggetto amministratore reale. Gli indirizzi email dei gruppi di ogni utente diventano il loro claim di gruppi, quindi allowed_groups e managed.policies.match.groups corrispondono agli indirizzi email dei gruppi.
email_claimNoQuale claim id_token porta l’email dell’utente. Predefinito email. Alcuni IdP, come ADFS ed Entra B2C, emettono upn o preferred_username invece. Accetta una chiave flat, un JSON Pointer o un elenco di chiavi di fallback dove viene utilizzata la prima chiave presente.
scopesNoOverride completo degli ambiti OIDC che il gateway richiede. Predefinito [openid, profile, email, offline_access]. Impostate quando il vostro IdP rifiuta gli ambiti che non riconosce o richiede un ambito personalizzato per emettere gruppi o email. Deve includere openid. Eliminare offline_access disabilita i token di aggiornamento, quindi gli sviluppatori rieseguono l’accesso al browser ogni session.ttl_hours. Vedere Configurazione del provider di identità per ricette di ambito per IdP come il flusso di token di aggiornamento di Google.
extra_auth_paramsNoParametri di query extra aggiunti alla richiesta di autorizzazione dell’IdP, verbatim. Questo è il meccanismo di override per il comportamento specifico dell’IdP, come access_type: offline per i token di aggiornamento di Google, domain_hint per alcuni tenant Entra o acr_values per i flussi step-up. Non può sovrascrivere i parametri del protocollo gestiti dal gateway: state, nonce, redirect_uri, PKCE, scope, response_type, response_mode e client_id.
userinfo_fallbackNoQuando l’id_token omette email o gruppi, recuperateli da /userinfo. Necessario per i token di accesso leggeri di Keycloak, il server org di Okta e i token minimi di ADFS. L’id_token rimane autorevole; userinfo riempie solo i vuoti. Predefinito false.
use_pkceNoInviate una sfida PKCE (S256) sulla richiesta di autorizzazione. Predefinito true. Impostate false solo se il vostro IdP rifiuta PKCE per questo client confidenziale.
clock_skew_secondsNoTollerare la deriva dell’orologio quando si convalidano i claim temporali dell’id_token. Predefinito 0, che è rigoroso. Aumentate se vedete errori “token scaduto / non ancora valido” subito dopo l’accesso a causa della deriva dell’orologio host/IdP.
token_endpoint_auth_methodNoOverride del metodo di autenticazione dell’endpoint del token. Accetta client_secret_basic o client_secret_post. Negoziato automaticamente per impostazione predefinita.
id_token_signed_response_algNoAlgoritmo di firma id_token previsto. Predefinito RS256. Impostate per gli IdP che firmano con ES256, PS256 o EdDSA.
additional_authorized_partiesNoValori azp extra da accettare oltre a client_id, per i flussi di broker e scambio di token di Keycloak
discovery_urlNoRecuperate il documento di scoperta da questo URL invece di derivarlo da issuer, per gli IdP dietro un proxy che riscrive l’host dell’emittente. Il percorso deve contenere /.well-known/.
form_action_originsNoOrigini aggiuntive per la direttiva Content-Security-Policy: form-action della pagina /device. Il gateway consente già 'self' e l’origine dell’authorization_endpoint scoperta, ma Chrome applica form-action all’intera catena di reindirizzamento. Se il vostro IdP reindirizza attraverso un secondo host, come Azure AD federato ad ADFS, Okta hub-spoke o un intercettore SSO aziendale, elencate ogni origine attraverso cui la richiesta di autorizzazione può reindirizzare.
ca_cert_pemNoCertificato CA PEM che sostituisce l’archivio di fiducia del sistema solo per le richieste IdP. Usate per Keycloak o Dex dietro PKI aziendale.

session

Il blocco session modella i token bearer che il gateway conia dopo l’accesso: il segreto che li firma e quanto a lungo vivono.
CampoObbligatorioDescrizione
jwt_secretAlmeno 32 byte di entropia, ad esempio da openssl rand -base64 32. Firma i token bearer HS256 del gateway. Accetta una singola stringa o un array per la rotazione: l’indice 0 firma e tutte le voci verificano. Per ruotare, antepone un nuovo segreto, attendi ttl_hours, quindi elimina quello vecchio.
ttl_hoursNoDurata del token bearer del gateway. Predefinito 1. La CLI aggiorna silenziosamente prima della scadenza quando l’IdP emette token di aggiornamento. Una durata più breve deprovvede più velocemente; una più lunga fa meno round-trip IdP. Se il vostro IdP non può emettere token di aggiornamento perché offline_access non è disponibile, non c’è aggiornamento silenzioso, quindi aumentate a 8 o 12 per evitare di rimandare gli sviluppatori all’accesso al browser ogni ora.

store

Il blocco store punta il gateway al suo database PostgreSQL, che contiene le concessioni dei dispositivi e i contatori dei limiti di velocità.
CampoObbligatorioDescrizione
postgres_urlURL postgres:// o postgresql://. Obbligatorio: il rendezvous della concessione del dispositivo, dove il callback del browser scrive e la CLI di polling legge, ha bisogno di uno stato cross-replica. Il gateway esegue le sue migrazioni dello schema all’avvio, quindi il ruolo ha bisogno di CREATE TABLE sullo schema di destinazione. Se la vostra politica di sicurezza proibisce DDL dal ruolo dell’applicazione, eseguite le migrazioni con un ruolo admin, inizialmente e di nuovo ogni volta che una nuova versione spedisce migrazioni, e concedete al ruolo dell’app SELECT, INSERT, UPDATE, DELETE sulle tabelle del gateway. Vedere Aggiornamenti e Postgres.
usernameNoSovrascrive l’utente in postgres_url
passwordNoCredenziale del database. Impostatela qui piuttosto che in postgres_url in modo che la credenziale rimanga fuori dall’URL. Accetta qualsiasi carattere e ha la precedenza sulle credenziali dell’URL.
max_connectionsNoDimensione del pool di connessioni Postgres per replica. Predefinito 5, che è conservativo e amichevole ai database condivisi. Con i limiti di spesa abilitati, il percorso caldo esegue alcune operazioni per richiesta di inferenza, quindi aumentatelo per un database dedicato sotto carico e mantenete repliche × questo sotto il max_connections del database.
Per lo sviluppo locale, puntate postgres_url a un contenitore Postgres usa e getta, ad esempio docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

upstreams

upstreams è un elenco ordinato. Il gateway inoltra l’inferenza al primo upstream che risolve il modello richiesto. Su 5xx, 429 o timeout esegue il failover al successivo; altri 4xx no, perché questi errori sono attribuibili alla richiesta piuttosto che all’upstream. Più upstream dello stesso provider devono impostare un name: distinto. I client Bedrock, Agent Platform e Foundry sono costruiti una volta all’avvio e i loro SDK aggiornano le credenziali internamente, quindi la rotazione delle credenziali cloud non richiede un riavvio. Le chiavi API Anthropic statiche e i bearer sono letti all’avvio; vedere API Anthropic.

API Anthropic

L’upstream Anthropic minimo è una chiave API dalla Console Claude:
upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # default; override for a forward proxy
Le due forme di credenziale differiscono nell’header che inviano:
  • api_key: invia x-api-key. Ruotatela nella Console Claude e aggiornate la variabile env.
  • oauth_token: invia Authorization: Bearer. Usate la forma bearer quando la vostra organizzazione emette token a breve durata invece di chiavi API a lunga durata. Il bearer è letto una volta all’avvio, quindi aggiornate rimontando il segreto e riavviando.
Invece di una chiave statica o un bearer, potete usare Workload Identity Federation. Create una regola di federazione seguendo la guida Workload Identity Federation, quindi montate il JWT OIDC del vostro carico di lavoro come file, come un token dell’account di servizio proiettato di Kubernetes o un id-token della piattaforma CI. Il gateway scambia il JWT per un bearer a breve durata e lo aggiorna automaticamente. Il file del token viene riletto ad ogni scambio, quindi i token proiettati ruotati vengono ripresi senza un riavvio.
upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

Amazon Bedrock

Per la distribuzione Bedrock lato client che il gateway sostituisce o fronteggia, vedere Claude Code su Amazon Bedrock. L’upstream lato gateway:
upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
Un blocco auth vuoto usa la catena di credenziali predefinita dell’AWS SDK: variabili env, ~/.aws/credentials, ruolo di attività ECS, metadati dell’istanza EC2 o IRSA su EKS. In produzione, date al pod del gateway un ruolo IAM invece di incorporare chiavi statiche in un’immagine del contenitore.
ConfigurazioneCome
Autorizzazioni IAMConcedete al principale del gateway bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream sia sugli ARN del profilo di inferenza che sugli ARN del modello di fondazione sottostante. Per il catalogo integrato nelle regioni US: arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.* e arn:aws:bedrock:*::foundation-model/anthropic.*.
Accesso al modelloNella console Bedrock, per regione, richiedete e abilitate l’accesso al modello per i modelli Claude che desiderate. I profili di inferenza cross-region (us.anthropic.*) richiedono l’accesso al modello in ogni regione che il profilo copre.
EKS (IRSA)Create un ruolo IAM con la politica sopra e una politica di fiducia per il provider OIDC del vostro cluster limitato all’account di servizio del gateway. Annotate l’account di servizio con eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway. auth: {} lo raccoglie.
ECS / EC2Allegate il ruolo IAM alla definizione dell’attività o al profilo dell’istanza. auth: {} lo raccoglie.
AltrovePassate le credenziali tramite le variabili env AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN, o impostatele esplicitamente in auth: con l’espansione ${VAR}
Regioneregion: è la regione dell’endpoint API. I profili di inferenza cross-region instradano attraverso la geo (US, EU, APAC) indipendentemente da quale scegliete. Per le regioni non-US o gli ARN di throughput provisioned, aggiungete un blocco models: con gli ID per upstream corretti.

Google Cloud Agent Platform

Per la configurazione equivalente lato client, vedere Claude Code su Google Cloud. L’upstream lato gateway:
upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com
Un blocco auth vuoto usa Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS, metadati GCE o GKE Workload Identity. I file di chiave JSON dell’account di servizio sono supportati ma sconsigliati; usate Workload Identity o allegate un account di servizio all’istanza GCE o Cloud Run. Impostate region: global per usare l’endpoint globale di Agent Platform invece di uno regionale. Google quindi instrada ogni richiesta a una regione disponibile, quindi non tracciate la disponibilità del modello per regione. L’impostazione di una regione specifica fissa ogni richiesta ad essa.
ConfigurazioneCome
Autorizzazioni IAMConcedete all’account di servizio del gateway roles/aiplatform.user sul progetto, o un ruolo personalizzato con aiplatform.endpoints.predict. Abilitate l’API Agent Platform (aiplatform.googleapis.com).
Accesso al modelloIn Model Garden, abilitate i modelli Claude per il vostro progetto. Pubblicano in regioni specifiche; controllate la scheda del modello per le regioni supportate.
GKE (Workload Identity)Legate un account di servizio GCP all’account di servizio Kubernetes del gateway e annotate il KSA con iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com. auth: {} lo raccoglie.
Cloud Run / GCEImpostate l’account di servizio del servizio su uno con roles/aiplatform.user. auth: {} lo raccoglie.
Altroveauth: { service_account_json: /secrets/sa.json }, il percorso a un file di chiave JSON montato come segreto. Il campo accetta un percorso di file, non i contenuti della chiave, quindi non è coinvolta alcuna espansione ${file:…}.

Microsoft Foundry

Per la distribuzione Foundry lato client, vedere Claude Code su Microsoft Foundry. L’upstream lato gateway:
upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}
use_azure_ad: true si risolve tramite DefaultAzureCredential: Managed Identity su AKS, ACI o App Service; l’Azure CLI o le credenziali di ambiente. Le chiavi API funzionano ma sono a livello di progetto e non ruotano automaticamente. L’endpoint di Foundry è derivato da resource:; impostate l’base_url facoltativo per sovrascriverlo per cloud sovrani come Azure Government.
ConfigurazioneCome
RBACConcedete all’identità del gateway Azure AI User o Cognitive Services User sulla risorsa Foundry
DistribuzioniFoundry usa nomi di distribuzione scelti dall’amministratore, non ID di modello canonici. Aggiungete un blocco models: che mappa ogni ID canonico al vostro nome di distribuzione.
AKS (workload identity)Federate un’Identità Gestita Assegnata dall’Utente con l’emittente OIDC del cluster e legatela all’account di servizio del gateway. use_azure_ad: true lo raccoglie tramite WorkloadIdentityCredential.
ACI / App ServiceAbilitate l’identità gestita assegnata dal sistema o assegnata dall’utente sulla risorsa. use_azure_ad: true lo raccoglie.
Altroveauth: { api_key: "${FOUNDRY_API_KEY}" }. Quotate ${…} dentro { }.

Più upstream

Lo stesso provider può apparire più di una volta con un name: distinto. Questo copre regioni diverse, account diversi tramite catene di credenziali diverse, throughput provisioned rispetto a on-demand e failover cross-provider. Il gateway prova gli upstream in ordine. 5xx, 429, timeout e endpoint mancante (501) eseguono il failover; altri 4xx no. 429 è capacità per upstream, quindi l’esaurimento del throughput provisioned (PT) esegue il failover a on-demand. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete. Questo esempio instrada un’allocazione Bedrock di throughput provisioned per primo, trabocca a on-demand e un secondo account e ricade all’API Anthropic per ultimo:
upstreams:
  # Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Different account: a separate Bedrock allotment via assumed-role creds.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `name:`; an upstream
# without a `name:` defaults to its provider string (e.g. `bedrock`). Any
# upstream not listed for a model is skipped, which is how you route a model
# to provisioned throughput while everything else stays on-demand.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8
LevaCome
Regioni diverseUn upstream Bedrock per regione, ciascuno con la sua region:. Con auto_include_builtin_models: true i profili di inferenza cross-region instradano automaticamente; per distribuzioni fissate per regione usate un blocco models:.
Account diversiUn upstream Bedrock per account, ciascuno con le sue credenziali in auth:. La catena predefinita (auth: {}) usa l’identità del pod; per un secondo account, impostate credenziali esplicite o un token bearer.
Throughput provisionedMappate il modello all’ARN di throughput provisioned in models: per il nome di quell’upstream. Gli altri upstream mantengono l’ID on-demand, quindi la capacità PT è esaurita prima del failover.
Endpoint VPC / FIPSImpostate base_url: sull’upstream al vostro URL di endpoint VPC o FIPS
Instradamento scoped al modelloOmettete un upstream dalla mappa upstream_model: di un modello e quell’upstream viene saltato per quel modello. Ad esempio, instradare Opus al throughput provisioned e Sonnet e Haiku a on-demand.
Il failover tra provider cloud o all’API Anthropic diretto cambia quale accordo, geografia e altri termini governano la richiesta. La CLI applica lo stesso feature gating ai gateway indipendentemente da quale upstream serve una data richiesta, quindi il failover non invia un campo del corpo che un upstream rifiuterebbe.

Sezioni facoltative

admin

Facoltativo. Abilita /v1/organizations/spend_limits, che rispecchia l’API Admin pubblica di Anthropic, e l’applicazione della spesa per sviluppatore su /v1/messages. Vedere Limiti di spesa per come i cap sono impostati e applicati; questa sezione copre le chiavi gateway.yaml che attivano la funzione e la sintonizzano.
admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits
CampoObbligatorioDescrizione
write_keysNoArray di {id, key}. Un x-api-key che corrisponde a uno di questi può elencare, impostare ed eliminare i limiti di spesa. I valori delle chiavi devono essere almeno 32 caratteri; gli id devono essere univoci tra read_keys e write_keys.
read_keysNoArray di {id, key}. Sola lettura: ogni endpoint GET, incluso l’elenco dei cap, il recupero di uno per ID e la lettura di /effective e /audit.
admin_groupsNoNomi di gruppi IdP. Un gateway JWT il cui claim groups include uno di questi ha accesso admin completo, lettura e scrittura, e audit come oidc:<sub>. Usate questo per gli amministratori umani; usate le chiavi API per le macchine.
blocked_messageNoAggiunto verbatim al 429 billing_error che uno sviluppatore bloccato vede. Scrivete l’intera istruzione, come un URL o un canale Slack. Non impostato, l’errore è spend limit reached.
audit_retention_daysNoPredefinito 365. Le righe admin_audit più vecchie vengono spazzate.
spend_retention_monthsNoPredefinito 13. Le righe del contatore spend più vecchie di questo vengono spazzate. Il predefinito mantiene un anno completo più il mese parziale corrente per il reporting anno su anno.
identity_retention_daysNoPredefinito 90. TTL last-seen per le righe principal_emails, che contengono l’email, il nome visualizzato e i gruppi di ogni sviluppatore (PII). Deliberatamente più breve della conservazione della spesa in modo che un’identità deprovisioned invecchi mentre i suoi contatori di spesa anonimi rimangono.
group_limit_modeNomin (predefinito) o max. Quando uno sviluppatore è in più gruppi con cap, min applica il più restrittivo e max il meno. Usato sia dall’applicazione che da /effective.

enforcement

Il blocco enforcement controlla come i controlli dei limiti di spesa si comportano quando l’archivio non è disponibile.
CampoObbligatorioDescrizione
fail_closed_on_errorNoPredefinito false. L’applicazione della spesa fallisce aperta su un’interruzione di Postgres, quindi l’inferenza rimane attiva. Impostate true per fallire chiuso: gli sviluppatori over-cap sono bloccati, ma lo è anche chiunque altro se l’archivio non è raggiungibile. Non ha effetto senza un blocco admin:.

models

Il blocco models è un elenco di modelli curato dall’amministratore facoltativo, servito su /v1/models e utilizzato per tradurre gli ID dei modelli per upstream. È obbligatorio per le regioni Bedrock non-US, gli ARN di throughput provisioned di Bedrock e i nomi di distribuzione di Foundry.
auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

managed

Il blocco managed definisce le politiche di accesso basate sui ruoli chiave sui gruppi IdP o sul dominio email. Le politiche vengono valutate in ordine; la prima corrispondenza viene selezionata, quindi unita alla base catch-all match: {} descritta di seguito. Vengono servite per utente su GET /managed/settings con caching ETag/304.
managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
Un catch-all match: {}, convenzionalmente elencato per ultimo, è trattato come uno strato di base. Ogni altra politica eredita qualsiasi chiave che non imposta dal catch-all, quindi le voci per ruolo hanno solo bisogno di elencare ciò che differisce dall’impostazione predefinita dell’organizzazione. Le regole di unione dipendono dal tipo di chiave:
  • Allow-list: availableModels e permissions.allow. L’elenco di una politica specifica sostituisce completamente quello della base.
  • Deny-list e array di hook: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces e ogni array di tipo di evento hooks. Questi prendono l’unione di base e politica, quindi un hook di deny o audit a livello di organizzazione non può essere accidentalmente eliminato da un override per ruolo.
  • Chiavi di tipo record: env, modelOverrides e skillOverrides. Questi shallow-merge, quindi un blocco env per ruolo sovrascrive le chiavi che imposta e eredita il resto dalla base.
availableModels è anche applicato lato server su /v1/messages, quindi un modello negato restituisce 400 indipendentemente da ciò che il client invia.
MatcherComportamento
match: {}Corrisponde a ogni utente autenticato. Iniziate con uno di questi e aggiungete politiche scoped al gruppo sopra di esso in seguito.
match: { groups: [a, b] }Corrisponde se il claim groups del JWT contiene uno dei gruppi elencati. Case-sensitive: i gruppi devono corrispondere al casing esatto dell’IdP.
match: { email_domain: example.com }Corrisponde alla parte dopo l’ultimo @ nel claim email del JWT, case-insensitive. Accetta un dominio per politica.
match: { groups: [a], email_domain: example.com }Entrambe le condizioni devono corrispondere
Un utente autenticato che non corrisponde a nessuna politica ottiene i valori predefiniti del gateway, il che significa ogni modello nel catalogo e nessuna impostazione gestita. Aggiungete un catch-all match: {} per ultimo se desiderate una politica predefinita garantita.
Il gateway non mantiene alcuna directory utente propria. Autorizza ogni richiesta dal token IdP dell’utente, leggendo l’appartenenza al gruppo dal claim groups del token e valutando le politiche rispetto ad esso. Non c’è roster da enumerare e nessun account da pre-creare, e quindi nessun endpoint SCIM, perché non c’è nulla per SCIM da sincronizzare.Eseguite la gestione del ciclo di vita dell’utente e del gruppo alla fonte della verità, che è il provisioning SCIM nativo del vostro IdP o una piattaforma di governance dell’identità dedicata. L’appartenenza e il deprovisioning governati lì fluiscono nel gateway automaticamente attraverso il token. Se desiderate il provisioning SCIM degli account Claude stessi, questa è una capacità di Claude for Enterprise.Due orologi di propagazione si applicano:
  • Contenuti della politica: modificare una politica e ridistribuire raggiunge i client connessi al loro prossimo sondaggio di impostazioni gestite, entro un’ora
  • Appartenenza al gruppo: cambiare l’appartenenza al gruppo di un utente cambia quale politica li corrisponde. Questo ha effetto al prossimo re-mint della sessione, il che significa il prossimo aggiornamento silenzioso, limitato da session.ttl_hours.

Cosa va in cli

Ogni valore cli è un documento managed-settings.json completo di Claude Code, lo stesso schema che distribuireste tramite MDM o /etc/claude-code/managed-settings.json, espresso qui come YAML. La CLI applica il documento consegnato al livello gestito, sopra le impostazioni dell’utente e del progetto. Il gateway convalida ogni documento rispetto allo schema delle impostazioni della CLI all’avvio, quindi una chiave di primo livello non riconosciuta o una chiave riconosciuta con un valore malformato fallisce l’avvio con un errore che nomina ogni chiave offensiva. Le parti deliberatamente aperte dello schema accettano ancora valori arbitrari, perché i client più recenti possono riconoscere voci che lo schema del gateway non riconosce. Queste chiavi aperte sono env, pluginConfigs e chiavi annidate sotto permissions. Poiché la convalida utilizza lo schema fornito con la versione installata del gateway, mettere una chiave di impostazioni di primo livello introdotta da una versione più recente di Claude Code nella configurazione gestita richiede l’aggiornamento del gateway per primo. Smoke-test una nuova politica su un client prima di distribuirla. Il riferimento completo della chiave è in Impostazioni di Claude Code. Le chiavi che gli operatori raggiungono per primi:
managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }
ChiaveApplicata daEffetto
availableModelsGateway + CLIAllowlist di modelli. Anche controllato su /v1/messages, quindi un client patchato non può bypassarlo.
permissions.allow / .denyCLIRegole di strumenti e comandi. Vedere Autorizzazioni.
permissions.disableBypassPermissionsModeCLIImpostate su disable per bloccare bypassPermissions, la modalità che auto-approva ogni chiamata di strumento, e il flag --dangerously-skip-permissions
allowManagedPermissionRulesOnlyCLIQuando true, le regole di autorizzazione dell’utente e del progetto vengono ignorate; si applicano solo le regole da questo documento
envCLIVariabili di ambiente unite nel processo CLI. Usate per telemetria, auto-update e override dei nomi dei modelli.
hooksCLIHook a livello di organizzazione
Poiché queste impostazioni arrivano sulla rete, la CLI mostra a ogni sviluppatore una finestra di dialogo di approvazione della sicurezza una tantum prima di applicare qualsiasi cosa che possa eseguire un comando shell o alterare dove va il traffico. La finestra di dialogo copre:
  • hooks
  • Variabili env che non sono nell’elenco sicuro integrato della CLI
  • Impostazioni di esecuzione shell come apiKeyHelper e statusLine
  • Contenuto CLAUDE.md gestito
L’elenco sicuro determina quali variabili env si applicano senza approvazione:
  • Nell’elenco sicuro: variabili di auto-update e nome del modello
  • Non nell’elenco sicuro: variabili proxy, variabili base-URL e OTEL_EXPORTER_OTLP_ENDPOINT
La configurazione della telemetria del gateway spinge OTEL_EXPORTER_OTLP_ENDPOINT, quindi l’impostazione di telemetry.forward_to attiva la finestra di dialogo su ogni client interattivo. Le esecuzioni non interattive con il flag -p saltano la finestra di dialogo e applicano le impostazioni senza approvazione. La finestra di dialogo protegge la macchina dello sviluppatore da un gateway compromesso o ostile, non l’organizzazione dallo sviluppatore, quindi il salto -p è intenzionale piuttosto che un gap. Se uno sviluppatore rifiuta, Claude Code esce piuttosto che applicare la politica. Spingere un nuovo hook o una variabile env non sicura a una politica ampia significa quindi un prompt di approvazione all’avvio successivo di ogni sviluppatore corrispondente. La chiave cli era denominata settings nelle versioni precedenti. Questo spelling è ancora accettato come alias, ma le nuove distribuzioni dovrebbero usare cli.

Precedenza con altre fonti gestite

Se un dispositivo ha anche un managed-settings.json locale o una politica consegnata da MDM, le fonti gestite non si uniscono. La fonte con priorità più alta fornisce tutte le impostazioni della politica, classificate in questo ordine con priorità più alta per primo:
  1. L’helper della politica
  2. Impostazioni consegnate dal gateway
  3. MDM, tramite il registro HKLM su Windows o un plist su macOS
  4. Il file managed-settings.json
  5. Il registro HKCU, solo su Windows
Gli host di incorporamento possono fornire politica tramite l’opzione SDK managedSettings. Viene ignorata per impostazione predefinita e si applica solo quando una fonte gestita acconsente con parentSettingsBehavior: "merge", filtrata in modo che possa stringere la politica ma non allentarla. L’eccezione è un piccolo insieme di chiavi cross-source, onorate quando qualsiasi fonte admin le imposta; il livello HKCU scrivibile dall’utente è escluso:
  • sandbox.network.allowManagedDomainsOnly e sandbox.filesystem.allowManagedReadPathsOnly: quando bloccate, gli allowlist corrispondenti vengono uniti tra le fonti
  • allowAllClaudeAiMcps: override di allow-only per l’allowlist del server MCP claude.ai
  • sandbox.bwrapPath e sandbox.socatPath: percorsi del file system ai binari helper sandbox
Ogni altra chiave, inclusi allowManagedPermissionRulesOnly e disableBypassPermissionsMode, proviene solo dalla fonte con priorità più alta. Vedere Precedenza delle impostazioni per la stessa regola nella pagina delle impostazioni. Le politiche del gateway si applicano a ogni invocazione di Claude Code sulla macchina, incluse le esecuzioni non interattive claude -p e le sessioni generate dall’Agent SDK. Se il gateway non è raggiungibile all’avvio, le sessioni firmate escono con un errore piuttosto che eseguire senza la loro politica.
mcpServers dentro il blocco cli di una politica è rifiutato all’avvio del gateway. La distribuzione MCP per gruppo non è disponibile; distribuire i server MCP tramite il managed-mcp.json basato su file su ogni dispositivo o lasciare che gli sviluppatori li aggiungano localmente.

telemetry

La CLI invia OpenTelemetry Protocol (OTLP) su metriche, log e, quando abilitato, tracce HTTP al gateway, che le inoltra verbatim a ogni destinazione configurata. Vedere Monitoraggio dell’utilizzo per le metriche e gli eventi che la CLI emette. La CLI timbra ogni esportazione con l’identità dell’utente autenticato, letta dal JWT emesso dal gateway: gli attributi user.id, user.email e user.groups. L’attribuzione del costo e dell’utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore.
telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}
Ogni destinazione acconsente a metrics, logs e traces indipendentemente e il predefinito è solo metriche. I segnali differiscono in sensibilità:
  • Metriche: contatori aggregati come conteggi di token, conteggi di richieste e latenza
  • Log e tracce: possono portare comandi bash completi, input di strumenti e percorsi di file, coprendo qualsiasi cosa Claude Code fa sulla macchina di uno sviluppatore
Abilitate log e tracce solo su destinazioni con i controlli di accesso e la politica di conservazione che i dati garantiscono.
La telemetria è disattivata nella CLI per impostazione predefinita. La configurazione di telemetry.forward_to insieme a listen.public_url la attiva. Il gateway spinge cinque variabili env a ogni client connesso tramite /managed/settings:
  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_TRACES_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
L’endpoint spinto è costruito dall’URL pubblico, quindi le metriche e i log non hanno bisogno di alcuna configurazione OTEL da sviluppatori o politiche. La configurazione spinta viene applicata al livello gestito, sovrascrivendo le variabili OTEL_* che uno sviluppatore imposta localmente. Le tracce richiedono inoltre CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 su ogni client. Il gateway non spinge quella variabile, quindi impostatela tramite il blocco env di una politica gestita. Non è nell’elenco sicuro della CLI, quindi consegnarla tramite una politica è coperto dalla stessa finestra di dialogo di approvazione della sicurezza che l’endpoint OTLP spinto già attiva. Sia le codifiche OTLP protobuf che JSON vengono inoltrate e qualsiasi backend compatibile con OpenTelemetry funziona come destinazione.

Sintonizzazione HTTP

Quattro blocchi facoltativi di primo livello, access_control, limits, timeouts e rate_limits, sintonizzano la superficie HTTP. I valori predefiniti si adattano alla maggior parte delle distribuzioni.
BloccoChiavePredefinitoDescrizione
access_controlallow_cidrs / deny_cidrsvuotoInbound IP allow/deny per indirizzo client, dopo la risoluzione di trusted_proxies. deny_cidrs viene controllato per primo; un client che corrisponde è rifiutato anche se allow_cidrs corrisponde anche. Se allow_cidrs è non vuoto il gateway è default-deny. /healthz e /readyz sono esenti da allow_cidrs.
limitsmax_request_bytes32 MiBCorpo della richiesta in entrata massimo; le richieste di dimensioni eccessive ottengono 413 prima che il corpo sia bufferizzato. Aumentate per richieste di file o immagini di grandi dimensioni.
limitsmax_request_header_bytesnon impostatoQuando impostato, gli header di dimensioni eccessive restituiscono 431
limitsmax_url_lengthnon impostatoQuando impostato, un URL troppo lungo restituisce 414
timeoutsupstream_ttfb_ms120000Attesa massima per gli header di risposta dell’upstream (time to first byte). Il corpo della risposta quindi scorre senza un cap di wall-clock. Si applica al percorso upstream Anthropic diretto; Bedrock, Agent Platform e Foundry sono limitati dal timeout proprio dell’SDK del provider.
rate_limitsdevice_authorization.max / .window_seconds30 / 600Limite di velocità per IP sull’endpoint di autorizzazione del dispositivo non autenticato. Aumentate per una grande organizzazione dietro un IP di uscita condiviso o NAT. Questi limiti si applicano solo al flusso di accesso della concessione del dispositivo, non all’inferenza /v1/messages. Vedere Resistenza al brute-force del codice utente.
rate_limitsdevice_verify.max / .window_seconds10 / 600Limite di velocità per IP sui invii di user_code su /device

Esempio completo

Questo config di riferimento completo esercita ogni sezione principale; i blocchi di sintonizzazione HTTP mantengono i loro valori predefiniti. Copiatelo, eliminate ciò che non vi serve e riempite i vostri valori. La configurazione nella Guida rapida è una versione minima di questa.
gateway.yaml
# Run with:
#   claude gateway --config gateway.yaml
#
# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
# environment variable (info | warn | error; default info). It does not
# affect audit events, which are always emitted.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omit the tls block when running behind a TLS-terminating ingress.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Required when the issuer is the Okta org server, whose id_tokens
  # can omit email and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emits groups only when the `groups` scope is requested and the
  # app's groups claim filter allows them. The contractors policy below
  # matches on groups, so the scope is requested here.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra app roles: use `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5

# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
# and per-developer spend enforcement on /v1/messages. Omit to disable.
# Caps themselves are set via the admin API, not here.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # Constrain the Default picker option to availableModels instead of
        # the tier default, so contractors don't get a 400 on the default.
        enforceAvailableModels: true
        # allow auto-approves these tools; it does not block the rest.
        # Add deny rules to restrict tools.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Impostazioni gestite lato client

Tutto quanto sopra configura il server del gateway. Puntare le macchine degli sviluppatori ad esso è configurato separatamente, su ogni dispositivo, tramite le impostazioni gestite di Claude Code. Il gateway non può spingere queste chiavi stesso, perché sono ciò che dice al client dove si trova il gateway. Per la CLI, impostate entrambe le chiavi nel managed-settings.json per OS:
{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}
Distribuire quel file a ogni dispositivo, tipicamente tramite la vostra piattaforma MDM. Il percorso del file differisce per piattaforma:
PiattaformaPercorso
macOS/Library/Application Support/ClaudeCode/managed-settings.json, o il dominio delle preferenze gestite com.anthropic.claudecode
Linux e WSL/etc/claude-code/managed-settings.json
WindowsC:\Program Files\ClaudeCode\managed-settings.json, o Group Policy tramite il registro HKLM
forceLoginGatewayUrl e il valore "gateway" di forceLoginMethod sono onorati solo dal livello gestito controllato dall’amministratore. Uno sviluppatore che li imposta nel suo ~/.claude/settings.json non ha effetto.