Configurazione del gateway delle app Claude

Riferimento per ogni opzione di gateway.yaml: listener e TLS, OIDC, sessione, archivio Postgres, upstream Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud e Microsoft Foundry, routing dei modelli, criteri gestiti e telemetria.

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 dei file

Cinque sezioni sono obbligatorie. Ogni altra sezione è facoltativa, e una sezione omessa assume i suoi valori predefiniti. Le chiavi sconosciute causano un errore di 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 delle attestazioni e chi può accedere
session: i bearer token che il gateway emette, con segreto e durata
store: PostgreSQL, per le concessioni dei dispositivi e i contatori dei limiti di velocità
upstreams: dove va l'inferenza, sia che si tratti di Anthropic, Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud, o Microsoft 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
pricing: tariffe contrattuali e un moltiplicatore per il misuratore di spesa e per le cifre di costo che gli sviluppatori vedono
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, tempo di primo byte upstream e limiti di accesso per IP
load_test_mode: test di carico del gateway senza chiamare un provider di modelli

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:

Modulo	Si risolve in	Usare 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 al percorso assoluto specificato, ritagliati. Il riferimento deve essere l'intero valore del campo: a differenza di `${VAR}`, non viene espanso all'interno di una stringa più lunga, quindi per una password del database impostare `store.password` piuttosto che incorporarla in `postgres_url`.	Montaggi 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.

Campo	Obbligatorio	Descrizione
`host`	No	Indirizzo di binding. Predefinito `0.0.0.0`.
`port`	No	Porta di binding. Predefinito `8080`.
`public_url`	A meno che `host` non sia loopback	L'origine `https://` visibile esternamente, utilizzata per costruire il `redirect_uri` dell'IdP e i metadati di scoperta. Obbligatorio ogni volta che `host` non è un indirizzo loopback, sia che TLS termini a un proxy come un ALB, Ingress o Cloud Run o al gateway stesso tramite `tls`, perché il gateway non deriva mai la sua stessa origine dagli header `X-Forwarded-*`; sono falsificabili dal client. L'avvio fallisce senza di esso. `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.key`	No	Percorsi PEM se il gateway termina TLS stesso
`trusted_proxies`	No	CIDR 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`. Le voci `X-Forwarded-For` scritte come `ipv4:port` o `[ipv6]:port`, come fanno alcuni load balancer, vengono lette con la porta eliminata. Un indirizzo IPv6 con una porta aggiunta e senza parentesi può essere letto come un indirizzo diverso o non letto affatto, quindi disattiva l'opzione della porta su qualsiasi proxy che scrive quella forma.

`oidc`

Il blocco oidc connette il gateway al tuo 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.

OpenID Connect (OIDC) è il protocollo SSO che il gateway utilizza con il tuo provider di identità; consulta Configurazione del provider di identità per ciò che registrare sul lato IdP.

Campo	Obbligatorio	Descrizione
`issuer`	Sì	Base di scoperta OIDC. Deve servire la scoperta su `/.well-known/openid-configuration`. Usa 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_secret`	Sì	Dalla tua registrazione del client OAuth
`allowed_email_domains`	No	Rifiuta gli id_token il cui claim `email` non è in uno di questi domini, senza distinzione tra maiuscole e minuscole. Difesa in profondità contro la configurazione errata dell'IdP multi-tenant. Indipendentemente da questa impostazione, un id_token il cui claim `email_verified` è esplicitamente `false` è sempre rifiutato.
`allowed_groups`	No	Limita 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. L'abbinamento è un confronto di stringhe esatto e case-sensitive rispetto ai valori in quel claim, e il gateway non espande i gruppi annidati: per ammettere i membri di un sottogruppo, elenca il sottogruppo qui o configura l'IdP per emettere l'appartenenza appiattita.
`groups_claim`	No	Quale claim dell'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_groups`	No	Cerca i gruppi dell'utente che ha effettuato l'accesso tramite la Directory API del Google Workspace Admin SDK, perché l'id_token di Google non porta alcun claim di gruppi. Imposta `service_account_json_path` su un file di chiave dell'account di servizio con delega a livello di dominio sullo scope `https://www.googleapis.com/auth/admin.directory.group.readonly` e `admin_email` su un amministratore di Workspace che l'account di servizio impersona; la Directory API richiede un soggetto amministratore reale. Gli indirizzi email dei gruppi di ogni utente diventano il suo claim di gruppi, quindi `allowed_groups` e `managed.policies.match.groups` corrispondono agli indirizzi email dei gruppi.
`email_claim`	No	Quale claim dell'id_token porta l'email dell'utente. Predefinito `email`. Alcuni IdP, come ADFS ed Entra B2C, emettono invece `upn` o `preferred_username`. Accetta una chiave flat, un JSON Pointer o un elenco di chiavi di fallback dove viene utilizzata la prima chiave presente.
`scopes`	No	Override completo degli scope OIDC che il gateway richiede. Predefinito `[openid, profile, email, offline_access]`. Impostalo quando il tuo IdP rifiuta gli scope che non riconosce o richiede uno scope personalizzato per emettere gruppi o email. Deve includere `openid`. Eliminare `offline_access` disabilita i token di aggiornamento, quindi gli sviluppatori rieseguono l'accesso nel browser ogni `session.ttl_hours`. Consulta Configurazione del provider di identità per ricette di scope per IdP come il flusso dei token di aggiornamento di Google.
`scope_on_refresh`	No	Invia anche `scope`, con lo stesso elenco della richiesta di accesso, quando il gateway scambia un token di aggiornamento. Predefinito `false`: la richiesta di aggiornamento omette `scope`. La maggior parte degli IdP restituisce un id_token ad ogni aggiornamento e non ne ha bisogno. Imposta `true` quando il tuo IdP restituisce un id_token all'aggiornamento solo se gli viene richiesto di nuovo `openid`, cosa che Okta documenta per il suo grant di aggiornamento. Senza un id_token, ogni aggiornamento dipende dal fatto che l'endpoint userinfo dell'IdP accetti il token di accesso aggiornato. Se limiti l'accesso o abbini le policy in base ai gruppi e l'id_token dell'IdP al momento dell'aggiornamento li omette, imposta anche `userinfo_fallback: true` in modo che il gateway li recuperi dall'endpoint userinfo. Un IdP che ha concesso meno scope di quelli richiesti può rifiutare l'aggiornamento con `invalid_scope`, anche per le sessioni esistenti se aggiungi voci a `scopes` mentre questa opzione è attiva. Rimuovi la chiave se gli aggiornamenti iniziano a fallire su `token_endpoint` dopo averla impostata. Richiede Claude Code v2.1.260 o successivo sul server del gateway.
`extra_auth_params`	No	Parametri di query extra aggiunti alla richiesta di autorizzazione dell'IdP, testualmente. 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_fallback`	No	Quando l'id_token omette email o gruppi, recuperali 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_pkce`	No	Invia una sfida PKCE (S256) sulla richiesta di autorizzazione. Predefinito `true`. Imposta `false` solo se il tuo IdP rifiuta PKCE per questo client confidenziale.
`clock_skew_seconds`	No	Tollera la deriva dell'orologio quando si convalidano i claim temporali dell'id_token. Predefinito `0`, che è rigoroso. Aumentalo se vedi errori "token scaduto / non ancora valido" subito dopo l'accesso a causa della deriva dell'orologio tra host e IdP.
`token_endpoint_auth_method`	No	Override 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_alg`	No	Algoritmo di firma dell'id_token previsto. Predefinito `RS256`. Impostalo per gli IdP che firmano con ES256, PS256 o EdDSA.
`additional_authorized_parties`	No	Valori `azp` extra da accettare oltre a `client_id`, per i flussi di broker e scambio di token di Keycloak
`discovery_url`	No	Recupera 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/`.
`use_proxy`	No	Invia le richieste IdP del gateway stesso attraverso il forward proxy in `HTTPS_PROXY` o `HTTP_PROXY`, rispettando `NO_PROXY`. `false` mantiene quelle richieste dirette. Richiede v2.1.227 o successivo; consulta Richieste IdP attraverso un forward proxy di seguito.
`form_action_origins`	No	Origini 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 tuo IdP reindirizza attraverso un secondo host, come Azure AD federato ad ADFS, Okta hub-spoke o un intercettore SSO aziendale, elenca ogni origine attraverso cui la richiesta di autorizzazione può essere reindirizzata.
`ca_cert_pem`	No	Il certificato CA codificato in PEM stesso, non un percorso a un file. Sostituisce l'archivio di attendibilità del sistema solo per le richieste IdP. Per caricare un file montato, scrivi `${file:/etc/gateway/idp-ca.pem}`. Usalo per Keycloak o Dex dietro una PKI aziendale.

Richieste IdP attraverso un forward proxy

Gli upstream di inferenza rispettano HTTPS_PROXY e HTTP_PROXY in ogni versione. Le richieste del gateway stesso all'IdP (scoperta, JWKS, token e userinfo) vanno dirette a meno che non imposti oidc.use_proxy: true, che richiede v2.1.227 o successivo. Quando una variabile proxy è impostata, use_proxy non è impostato e l'emittente non è coperto da NO_PROXY, il gateway mantiene quelle richieste dirette e registra un avviso all'avvio chiedendoti di scegliere; use_proxy: false le mantiene dirette e silenzia l'avviso.

Con use_proxy: true, il pod risolve da sé il nome host di ogni endpoint IdP e chiede al proxy di eseguire CONNECT verso l'indirizzo IP risolto, quindi il proxy deve accettare CONNECT verso l'indirizzo IP di ogni host indicato dal documento di scoperta, non solo dell'emittente. Usa un URL proxy http://. ca_cert_pem e la guardia SSRF si applicano anche sul percorso tramite proxy.

L'egress solo tramite proxy cambia entrambi questi aspetti: mentre è attivo, le richieste IdP passano per il proxy a meno che tu non imposti use_proxy: false, e il gateway consegna al proxy ogni nome host IdP senza risolverlo prima.

Egress solo tramite proxy

Imposta CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 nell'ambiente del gateway, accanto a HTTPS_PROXY, quando il pod raggiunge altri host solo attraverso quel forward proxy e non può risolvere da sé i nomi DNS pubblici, o quando il proxy rifiuta CONNECT verso un indirizzo IP. Richiede v2.1.277 o successivo. È una variabile d'ambiente anziché una chiave di gateway.yaml in modo che nulla nel file di configurazione possa allentare il controllo degli indirizzi del gateway.

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

Il gateway registra una riga network: all'avvio mentre l'egress solo tramite proxy è attivo.

Ogni riga di seguito è una classe di richiesta in uscita su un gateway con HTTPS_PROXY impostato, per impostazione predefinita e mentre l'egress solo tramite proxy è attivo.

Richiesta in uscita	Predefinito	Egress solo tramite proxy attivo
Upstream `provider: anthropic`, scambio di token Workload Identity Federation, esportazioni `telemetry.forward_to`	Risolto e controllato localmente, quindi `CONNECT` verso l'indirizzo IP controllato attraverso il proxy. Un collettore di telemetria elencato in `NO_PROXY` viene invece raggiunto direttamente	Nome host consegnato al proxy
Scoperta IdP, JWKS, token e userinfo	Diretto a meno che `oidc.use_proxy: true`, quindi `CONNECT` verso l'indirizzo IP controllato	Nome host consegnato al proxy, a meno che `oidc.use_proxy: false` non mantenga diretto un IdP interno
Upstream Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud e Microsoft Foundry; ricerche di gruppi Google	Nome host consegnato al proxy	Invariato

L'egress solo tramite proxy rimane disattivato a meno che l'ambiente del gateway non soddisfi tutte e tre queste condizioni:

HTTPS_PROXY o HTTP_PROXY è impostato.
NO_PROXY e no_proxy sono vuoti. Se la tua piattaforma inietta una delle due nei pod, imposta entrambe a un valore vuoto sul container del gateway. Elencare un collettore di telemetria in NO_PROXY mantiene disattivato l'egress solo tramite proxy.
CLAUDE_GATEWAY_ALLOW_LOOPBACK non è attivato. Un collettore o un IdP sul loopback del pod stesso non può essere combinato con l'egress solo tramite proxy, perché un indirizzo loopback consegnato al proxy sarebbe quello dell'host del proxy, quindi assegna invece a quei servizi un indirizzo che il proxy può raggiungere. Per lo stesso motivo il gateway rifiuta del tutto i nomi di tipo localhost mentre l'egress solo tramite proxy è attivo.

Quando una di queste condizioni non è soddisfatta, il gateway registra un avviso all'avvio indicando la variabile che l'ha impedito e mantiene il comportamento predefinito.

Una volta attivo l'egress solo tramite proxy, consenti nel proxy ogni destinazione, incluso un collettore interno e qualsiasi host configurato per indirizzo IP. Puoi comunque mantenere diretto un IdP interno con oidc.use_proxy: false.

`session`

Il blocco session definisce i token bearer che il gateway emette dopo l'accesso: il segreto che li firma e per quanto tempo restano validi.

Campo	Obbligatorio	Descrizione
`jwt_secret`	Sì	Almeno 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, anteponi un nuovo segreto, attendi `ttl_hours`, quindi elimina quello vecchio.
`ttl_hours`	No	Durata 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 revoca l'accesso più velocemente; una più lunga richiede meno round-trip verso l'IdP. Se il tuo IdP non può emettere token di aggiornamento perché `offline_access` non è disponibile, non c'è aggiornamento silenzioso, quindi aumentalo a `8` o `12` per evitare di rimandare gli sviluppatori all'accesso nel browser ogni ora.

`store`

Il blocco store punta il gateway al suo database PostgreSQL, che contiene le concessioni dei dispositivi e i contatori dei rate limit.

Campo	Obbligatorio	Descrizione
`postgres_url`	Sì	URL `postgres://` o `postgresql://`. Obbligatorio: il punto d'incontro della concessione del dispositivo, dove il callback del browser scrive e la CLI in polling legge, richiede uno stato condiviso tra repliche. Il gateway esegue le proprie migrazioni dello schema all'avvio e all'aggiornamento, quindi il ruolo ha bisogno dei diritti per creare e modificare tabelle sullo schema di destinazione. Consulta Aggiornamenti e Postgres.
`username`	No	Sovrascrive l'utente in `postgres_url`
`password`	No	Credenziale del database. Impostala qui anziché in `postgres_url` in modo che la credenziale rimanga fuori dall'URL. Accetta qualsiasi carattere e ha la precedenza sulle credenziali dell'URL.
`max_connections`	No	Dimensione del pool di connessioni Postgres per replica. Predefinito `5`, che è conservativo e adatto ai database condivisi. Con i limiti di spesa abilitati, il percorso critico esegue alcune operazioni per richiesta di inferenza, quindi aumentalo per un database dedicato sotto carico e mantieni repliche × questo valore al di sotto del `max_connections` del database.
`connect_timeout_seconds`	No	Secondi che il gateway attende quando apre una connessione Postgres. Un numero intero da `1` a `60`, predefinito `5`. Aumentalo se i tentativi di connessione vanno in timeout quando si avvia una nuova istanza del gateway. Richiede Claude Code v2.1.274 o successivo sul server del gateway. Le versioni precedenti si rifiutano di avviarsi quando la chiave è impostata.
`readiness_grace_seconds`	No	Per quanti secondi `/readyz` continua a segnalare lo stato di pronto dopo che Postgres smette di rispondere. Un numero intero da `0` a `3600`, predefinito `0`. Consulta Comportamento in caso di interruzione per come scegliere un valore. Richiede Claude Code v2.1.282 o successivo sul server del gateway. Le versioni precedenti si rifiutano di avviarsi quando la chiave è impostata.

Per lo sviluppo locale, punta postgres_url a un container 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, 401, 403, 404 o timeout il gateway esegue il failover all'upstream successivo; sugli altri 4xx no, perché questi errori sono attribuibili alla richiesta anziché all'upstream. Un 401 o 403 significa che la credenziale usata dal gateway verso quell'upstream non ha funzionato. Un 404 significa che quell'upstream non serve il modello richiesto, quindi un upstream successivo nell'elenco può ancora servirlo.

Se imposti forward_user_identity: true su un upstream, un 429 che questo restituisce a una richiesta che portava l'email dello sviluppatore non esegue il failover. Consulta come un rifiuto per limite per utente raggiunge lo sviluppatore.

Il failover su 404 richiede il gateway v2.1.198 o successivo. Le versioni precedenti restituivano il primo 404 al client anche quando un upstream successivo nell'elenco serviva il modello.

Più upstream dello stesso provider devono impostare un name: distinto.

I client Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud e Microsoft Foundry vengono creati 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 vengono letti all'avvio; consulta API Anthropic.

Messaggi di errore dell'upstream

Il gateway restituisce la risposta di errore di un upstream o il proprio 502, a seconda di come hanno risposto gli upstream:

Un upstream ha restituito uno stato su cui il gateway non esegue il failover: la risposta di quell'upstream. Il gateway non prova altri upstream.
Ogni upstream provato dal gateway ha fallito in un modo su cui esegue il failover: l'ultimo 429. Quando nessuno ha restituito un 429, il gateway preferisce, nell'ordine, l'ultimo 401 o 403, l'ultimo 404 e l'ultimo 501. Quando nessuno ha restituito nessuno di questi, il 502 del gateway stesso, all upstreams failed (N attempted), dove N conta ogni voce in upstreams, incluse le voci che il gateway ha saltato perché non servono il modello richiesto.

Quando il gateway restituisce la risposta di un upstream, mantiene il codice di stato dell'upstream. Se mantenga anche il messaggio dell'upstream dipende dal provider. Il corpo di errore di un upstream API Anthropic raggiunge lo sviluppatore invariato.

Gli upstream Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud e Microsoft Foundry possono indicare i tuoi ID account, ARN di ruolo e ID progetto nel loro testo di errore. Il gateway registra quel testo completo nel log operativo. Ciò che lo sviluppatore vede da questi upstream dipende dal rifiuto:

400 o 413 nell'envelope di errore standard di Anthropic: il messaggio dell'upstream stesso, come prompt is too long. Claude Platform on AWS, Agent Platform e Microsoft Foundry restituiscono questo envelope per i rifiuti dell'API del modello.
400 o 413 nel formato proprio del provider: un token capability_rejected:. Quando il gateway non riesce a classificare il rifiuto, upstream rejected the request su un 400 o request too large for this upstream su un 413.
Qualsiasi altro stato: un testo generico per stato, come upstream rate limit exceeded su un 429.

Ad esempio, il gateway sostituisce Input is too long for requested model. di Amazon Bedrock con capability_rejected: prompt_too_long. Claude Code compatta automaticamente su quel token, come fa su prompt is too long.

Mantenere il messaggio 400 o 413 di un upstream cloud, o sostituirlo con un token capability_rejected:, richiede il gateway v2.1.233 o successivo.

API Anthropic

L'upstream Anthropic minimo è una chiave API dalla Claude Console:

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. Ruotala nella Claude Console e aggiorna la variabile d'ambiente.
oauth_token: invia Authorization: Bearer. Usa la forma bearer quando la tua organizzazione emette token a breve durata invece di chiavi API a lunga durata. Il bearer viene letto una volta all'avvio, quindi aggiornalo rimontando il segreto e riavviando.

Invece di una chiave statica o di un bearer, puoi usare Workload Identity Federation. Crea una regola di federazione seguendo la guida a Workload Identity Federation, quindi monta come file il JWT OIDC del tuo workload, ad esempio un token dell'account di servizio proiettato di Kubernetes o l'id-token di una piattaforma CI. Il gateway scambia il JWT con un bearer a breve durata e lo aggiorna automaticamente. Il file del token viene riletto a ogni scambio, quindi i token proiettati ruotati vengono acquisiti 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

Header di identità per utente per un proxy che gestisci

Puoi puntare il base_url di un upstream provider: anthropic a un proxy che gestisci invece che all'API Anthropic. Per indicare a quel proxy quale sviluppatore ha inviato ogni richiesta, imposta forward_user_identity: true su quell'upstream. Il proxy può quindi attribuire la spesa per sviluppatore. Richiede un gateway che esegue Claude Code v2.1.233 o successivo.

Ad esempio, per un proxy su upstream-gateway.internal.example.com:

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # default false

Il gateway aggiunge questi header a ogni richiesta che inoltra a quell'upstream.

Header	Valore
`x-litellm-end-user-id`	L'email dello sviluppatore, quando l'IdP l'ha fornita.
`x-claude-gateway-user-id`	Il soggetto IdP dello sviluppatore, dal claim `sub` del token.
`x-claude-gateway-user-email`	L'email dello sviluppatore, quando l'IdP l'ha fornita.

Quando il token IdP non contiene un'email, il gateway invia solo x-claude-gateway-user-id e omette i due header email. Se il tuo IdP inserisce l'email in un claim diverso, imposta oidc.email_claim su quel claim.

Quando il tuo proxy risponde 429 a una richiesta che portava l'email dello sviluppatore, il gateway restituisce quella risposta allo sviluppatore così com'è invece di eseguire il failover all'upstream successivo, in modo che il budget per utente o il rate limit del tuo proxy vengano rispettati. Le altre risposte del proxy seguono le normali regole di failover. Se il token IdP di uno sviluppatore non contiene un'email, il gateway inoltra le sue richieste senza gli header email, quindi un 429 a una di quelle richieste conta come capacità dell'upstream ed esegue il failover. Prima della v2.1.267 sul server del gateway, ogni 429 eseguiva il failover.

Imposta forward_user_identity solo su un upstream il cui base_url è un proxy che gestisci. Il gateway invia le email degli sviluppatori a qualunque server indicato da quel base_url. Se il base_url è l'API Anthropic, che è il valore predefinito, il gateway si rifiuta di avviarsi.

Amazon Bedrock

Per la distribuzione di Amazon Bedrock lato client che il gateway sostituisce o a cui fa da front-end, consulta 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 d'ambiente, ~/.aws/credentials, ruolo di attività ECS, metadati dell'istanza EC2 o IRSA su EKS. In produzione, assegna al pod del gateway un ruolo IAM invece di incorporare chiavi statiche in un'immagine del container.

Le credenziali esplicite devono essere complete: il gateway fallisce all'avvio quando aws_access_key_id e aws_secret_access_key non sono impostati insieme, o quando aws_session_token è impostato senza di loro. Prima della v2.1.207, un blocco auth: parziale superava la convalida.

Configurazione	Come
Permessi IAM	Concedi al principal del gateway `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` sia sugli ARN dei profili di inferenza sia sugli ARN dei modelli di fondazione sottostanti. Per il catalogo integrato nelle regioni US: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.` e `arn:aws:bedrock:::foundation-model/anthropic.*`. Concedi anche `bedrock:CountTokens` sugli ARN dei modelli di fondazione. Il gateway lo usa, senza costi, per contare i token di input di una richiesta abbandonata dal client, in modo che i limiti di spesa rimangano accurati. Senza di esso il gateway usa come fallback una richiesta Bedrock da un token per quel conteggio.
Accesso al modello	Amazon Bedrock abilita l'accesso ai modelli per impostazione predefinita nelle regioni commerciali. L'unico vincolo rimanente a livello di account è il modulo una tantum di Anthropic sul caso d'uso: se nessuno nel tuo account AWS l'ha inviato, apri la console di Amazon Bedrock, seleziona un modello Anthropic dal catalogo dei modelli e completa il modulo. Consulta Inviare i dettagli del caso d'uso per il modulo di AWS Organizations e i permessi di cui ha bisogno chi lo invia.
EKS (IRSA)	Crea un ruolo IAM con la policy sopra e una trust policy per il provider OIDC del tuo cluster limitata all'account di servizio del gateway. Annota l'account di servizio con `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` lo rileva.
ECS / EC2	Associa il ruolo IAM alla definizione dell'attività o al profilo dell'istanza. `auth: {}` lo rileva.
Altrove	Passa le credenziali tramite le variabili d'ambiente `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, oppure impostale esplicitamente in `auth:` con l'espansione `${VAR}`
Regione	`region:` è la regione dell'endpoint API. I profili di inferenza cross-region instradano all'interno dell'area geografica (US, EU, APAC) indipendentemente da quale scegli. Per le regioni non US o gli ARN di throughput provisioned, aggiungi un blocco `models:` con gli ID per upstream corretti.

Applicare un guardrail di Amazon Bedrock

Per applicare un guardrail di Amazon Bedrock a ogni richiesta di inferenza che il gateway invia tramite un upstream Bedrock, aggiungi un blocco guardrail a quell'upstream. Richiede Claude Code v2.1.281 o successivo sul server del gateway.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # guardrail ID or full ARN
      version: "1"                     # a published version number, or DRAFT
 # keep the quotes: a bare 1 fails at boot

Concedi anche bedrock:ApplyGuardrail sul guardrail al principal che firma le richieste di questo upstream: il principal AWS del gateway oppure, con assume_role, il ruolo indicato in role_arn.

Imposta guardrail su ogni upstream bedrock o su nessuno. Il gateway si rifiuta di avviarsi con una configurazione mista, perché altrimenti il failover potrebbe inviare una richiesta a un upstream Bedrock privo di guardrail.

Il guardrail copre solo gli upstream Bedrock. Se elenchi un altro provider in upstreams, il gateway invia le richieste a quel provider senza il guardrail.

Quando una richiesta /v1/messages il cui corpo contiene un campo amazon-bedrock-*, come amazon-bedrock-guardrailConfig, raggiunge un upstream Bedrock con guardrail impostato, il gateway risponde 400 invece di inoltrarla.

Bedrock in un altro account AWS

Imposta assume_role su un upstream Bedrock e il gateway userà la propria identità AWS solo per chiamare sts:AssumeRole su un ruolo che indichi, che può trovarsi in un account AWS diverso da quello del gateway. Ogni richiesta Bedrock da quell'upstream viene firmata con le credenziali di un'ora restituite da STS, quindi nessuna chiave di accesso a lunga durata attraversa gli account.

Richiede un gateway che esegue Claude Code v2.1.281 o successivo. Un gateway precedente si rifiuta di avviarsi quando trova la chiave.

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # when the role's trust policy requires one

Il blocco assume_role accetta tre chiavi:

Chiave	Significato
`role_arn`	Il ruolo IAM che il gateway assume, come ARN `arn:aws:iam::` o `arn:aws-us-gov:iam::`. Assegnagli i permessi Bedrock di cui questo upstream ha bisogno, `bedrock:CountTokens` incluso, più `bedrock:ApplyGuardrail` quando l'upstream imposta `guardrail`.
`external_id`	Facoltativo. Inviato come external ID in ogni chiamata `sts:AssumeRole`. Impostalo quando la trust policy del ruolo lo richiede, e mettilo tra virgolette se è composto solo da cifre.
`session_name`	Facoltativo. `email` o `sub` assegna a ogni sviluppatore la propria sessione: consulta Attribuzione dei costi AWS per sviluppatore. Se non impostato, ogni richiesta usa un'unica sessione denominata `claude-apps-gateway`.

La trust policy del ruolo indica il principal del gateway stesso, come il suo ruolo IRSA o il ruolo di attività ECS. Quel principal ha bisogno di sts:AssumeRole sul ruolo e di nessun permesso Bedrock proprio. Elimina la Condition se non imposti external_id.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

Se STS rifiuta o non è raggiungibile, il gateway non invia la richiesta con le credenziali proprie dell'upstream. Registra l'errore STS con ciò che occorre verificare, quindi prova l'upstream successivo che hai elencato. Messaggi di errore dell'upstream descrive ciò che riceve il client quando nessun upstream ha successo. Un upstream successivo senza assume_role servirebbe la richiesta con le proprie credenziali, quindi elencane uno solo se è ciò che desideri.
Il gateway chiama l'endpoint STS regionale sts.<region>.amazonaws.com, che la sua rete deve poter raggiungere. Per l'endpoint FIPS, imposta AWS_USE_FIPS_ENDPOINT=true nell'ambiente del gateway anziché use_fips_endpoint in un file di configurazione AWS.
assume_role si applica solo a provider: bedrock e richiede credenziali di origine SigV4: il gateway si rifiuta di avviarsi quando è impostato insieme a aws_bearer_token.
Ogni sviluppatore ammesso dal gateway può usare questo upstream; managed stabilisce quali sviluppatori possono usare quali modelli. Per evitare che un modello servito tramite il ruolo venga servito anche da un altro account, assegnagli un id personalizzato la cui mappa upstream_model contenga solo il nome di questo upstream. Per un id di questo tipo il gateway salta ogni altro upstream, quindi né la richiesta né il conteggio dei token per una richiesta interrotta possono eseguire il failover su un altro account. I nomi dei modelli integrati vengono comunque provati su ogni upstream in ordine, questo incluso, e una richiesta che lo raggiunge viene firmata con lo stesso ruolo, quindi elenca questo upstream per ultimo a meno che anche il suo account non debba servirli.

Questo esempio assegna a un modello un id personalizzato che solo l'upstream isolato serve:

models:
  - id: claude-opus-restricted          # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

Attribuzione dei costi AWS per sviluppatore

Per impostazione predefinita il gateway firma ogni richiesta Bedrock con un'unica credenziale, quindi AWS vede le richieste di tutti gli sviluppatori sotto un unico principal IAM. Aggiungi session_name: email ad assume_role e il gateway chiamerà sts:AssumeRole una volta per sviluppatore ogni ora, con il nome della sessione impostato sull'email di quello sviluppatore, e firmerà le sue richieste con le credenziali restituite, in modo che le richieste di ogni sviluppatore raggiungano AWS sotto la propria sessione di ruolo assunto. Il ruolo può trovarsi nell'account stesso del gateway.

Richiede un gateway che esegue Claude Code v2.1.281 o successivo. Attribuzione dei costi su AWS descrive il ruolo IAM e dove la fatturazione AWS mostra le sessioni.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # or sub

session_name seleziona quale claim verificato diventa il RoleSessionName di AWS: email o sub. Il gateway scrive qualsiasi carattere diverso da lettere ASCII, cifre e _+,.@- come =XX esadecimale per ogni byte UTF-8, e abbrevia un risultato più lungo di 64 caratteri in un prefisso più un hash, in modo che il nome della sessione di ogni sviluppatore rimanga valido e univoco. Una richiesta da uno sviluppatore il cui token non contiene il claim non viene inviata tramite questo upstream, e il log operativo indica di passare a sub o di impostare oidc.email_claim.

Uno sviluppatore attivo costa una chiamata STS all'ora per replica del gateway, e le prime richieste simultanee condividono un'unica chiamata.

Il gateway effettua anche una chiamata propria su questo ruolo: il conteggio dei token per una richiesta abbandonata dal client, in modo che i limiti di spesa rimangano accurati. Quel conteggio e la relativa richiesta di fallback da un token sono firmati dalla sessione condivisa claude-apps-gateway, quindi AWS attribuisce il fallback a claude-apps-gateway anziché allo sviluppatore.

Per un'attribuzione rigorosa per sviluppatore, imposta assume_role con session_name su ogni upstream Bedrock che elenchi. Un upstream senza di esso firma le richieste che serve con le proprie credenziali.

Claude Platform on AWS

Claude Platform on AWS serve l'API Anthropic di prima parte su infrastruttura AWS all'indirizzo aws-external-anthropic.<region>.api.aws. Utilizza ID modello di prima parte, rispetta gli header anthropic-beta così come inviati e serve count_tokens, quindi non si applica nessuna delle traduzioni specifiche di Bedrock. Il provider anthropicAws richiede Claude Code v2.1.198 o successivo; le versioni precedenti del gateway lo rifiutano all'avvio.

Per la distribuzione lato client della stessa piattaforma, consulta Claude Code su Claude Platform on AWS. L'upstream lato gateway:

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

La piattaforma viene eseguita in un account AWS separato da Amazon Bedrock e firma le richieste SigV4 per il proprio nome di servizio, aws-external-anthropic, quindi un ruolo IAM limitato a Bedrock non la autorizza. Una chiave API in auth.api_key ha la precedenza quando sono impostate anche le credenziali SigV4. Un blocco auth vuoto usa la catena di credenziali predefinita dell'AWS SDK, la stessa catena usata dall'upstream Amazon Bedrock.

Campo	Obbligatorio	Descrizione
`region`	Sì	Regione AWS, lettere minuscole, cifre e trattini. Il gateway ne deriva l'endpoint come `https://aws-external-anthropic.<region>.api.aws`.
`workspace_id`	Sì	Inviato come header in ogni richiesta; la piattaforma lo richiede
`auth.api_key`	No	Chiave API per la piattaforma, inviata come `x-api-key`. Non è un token bearer: le due modalità di autenticazione sono una chiave API o SigV4.
`auth.aws_access_key_id` / `auth.aws_secret_access_key`	No	Credenziali SigV4 esplicite. Impostarne una senza l'altra causa un errore all'avvio. `auth.aws_session_token` è accettato insieme a esse.
`base_url`	No	Override dell'endpoint derivato

Poiché la piattaforma risolve ID modello di prima parte, il catalogo integrato la instrada senza un blocco models:. Quando curi un elenco models:, usa come chiave della voce anthropicAws: con l'ID di prima parte.

Google Cloud Agent Platform

Per la configurazione equivalente lato client, consulta 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 le 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; usa Workload Identity o associa un account di servizio all'istanza GCE o Cloud Run.

Imposta region: global per usare l'endpoint globale di Agent Platform di Google Cloud invece di uno regionale. Google instrada quindi ogni richiesta a una regione disponibile, così non devi tenere traccia della disponibilità dei modelli per regione. Impostare una regione specifica vincola ogni richiesta a quella regione.

Configurazione	Come
Permessi IAM	Concedi all'account di servizio del gateway `roles/aiplatform.user` sul progetto, o un ruolo personalizzato con `aiplatform.endpoints.predict`. Abilita l'API di Agent Platform di Google Cloud (`aiplatform.googleapis.com`).
Accesso al modello	In Model Garden, abilita i modelli Claude per il tuo progetto. Vengono pubblicati in regioni specifiche; controlla la scheda del modello per le regioni supportate.
GKE (Workload Identity)	Associa un account di servizio GCP all'account di servizio Kubernetes del gateway e annota il KSA con `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` lo rileva.
Cloud Run / GCE	Imposta come account di servizio del servizio uno con `roles/aiplatform.user`. `auth: {}` lo rileva.
Altrove	`auth: { service_account_json: /secrets/sa.json }`, il percorso di un file di chiave JSON montato come segreto. Il campo accetta un percorso di file, non il contenuto della chiave, quindi non è coinvolta alcuna espansione `${file:…}`.

Microsoft Foundry

Per la distribuzione di Microsoft Foundry lato client, consulta 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; la Azure CLI; o le credenziali d'ambiente. Le chiavi API funzionano ma valgono per l'intero progetto e non ruotano automaticamente. L'endpoint di Microsoft Foundry è derivato da resource:; imposta il base_url facoltativo per sovrascriverlo per cloud sovrani come Azure Government.

Configurazione	Come
RBAC	Concedi all'identità del gateway `Azure AI User` o `Cognitive Services User` sulla risorsa Microsoft Foundry
Deployment	Microsoft Foundry usa nomi di deployment scelti dall'amministratore, non ID modello canonici. Aggiungi un blocco `models:` che mappa ogni ID canonico al nome del tuo deployment.
AKS (workload identity)	Federa una User-Assigned Managed Identity con l'emittente OIDC del cluster e associala all'account di servizio del gateway. `use_azure_ad: true` la rileva tramite `WorkloadIdentityCredential`.
ACI / App Service	Abilita l'identità gestita assegnata dal sistema o dall'utente sulla risorsa. `use_azure_ad: true` la rileva.
Altrove	`auth: { api_key: "${FOUNDRY_API_KEY}" }`. Metti tra virgolette `${…}` dentro `{ }`.

Header statici sulle richieste upstream

Per aggiungere header fissi alle richieste che il gateway invia a un upstream, imposta headers: su quell'upstream. Usalo quando un proxy che gestisci davanti al provider instrada o attribuisce il traffico in base a un header.

headers: richiede Claude Code v2.1.277 o successivo sul server del gateway. Un gateway precedente si rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere la chiave e rimuovi la chiave prima di eseguire il rollback a una versione precedente.

Gli header vanno al server indicato da base_url, o all'endpoint proprio del provider quando base_url non è impostato. Anche il provider li riceve, a meno che il tuo proxy non li rimuova.

Questo esempio raggiunge un upstream provider: vertex attraverso un proxy su upstream-proxy.internal.example.com. Imposta l'header x-source letto dal proxy e invia un token dalla variabile d'ambiente PROXY_TOKEN come x-proxy-token:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

I valori sono testo ASCII stampabile senza spazi all'inizio o alla fine. Metti tra virgolette un numero, true o false in modo che YAML lo legga come testo.

Per tenere un segreto fuori dal file di configurazione, usa l'espansione dei segreti per caricare il valore da una variabile d'ambiente con ${VAR} o da un file con ${file:/path}. Un ${VAR} che si risolve in un valore vuoto impedisce l'avvio del gateway.

headers: funziona su ogni provider e ogni upstream invia solo i propri.

Non tutte le richieste che il gateway invia a un upstream li includono:

Richiesta che il gateway invia a questo upstream	Include `headers:`
`/v1/messages`, in streaming o meno, e `/v1/messages/count_tokens`	Sì
Una richiesta che ha eseguito il failover da un altro upstream	Sì, solo gli `headers:` di questo upstream
La chiamata `CountTokens` di Amazon Bedrock per una richiesta abbandonata dal client	No
Lo scambio di token Workload Identity Federation	No

Su un upstream Amazon Bedrock o Claude Platform on AWS che firma le richieste con AWS SigV4, questi header fanno parte della firma, quindi il tuo proxy deve inoltrarli invariati.

Se usi un nome riservato dal gateway, questo si rifiuta di avviarsi e l'errore di avvio indica l'header. I nomi riservati includono:

authorization e x-api-key
host, content-type e user-agent
Qualsiasi nome che inizia con anthropic-, x-goog-, x-amz- o x-amzn-

Più upstream

Lo stesso provider può comparire 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 fallback tra provider.

Il gateway prova gli upstream in ordine. 5xx, 429, 401, 403, 404, timeout ed endpoint mancante (501) eseguono il failover; gli altri 4xx no.

429 indica la capacità del singolo upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover su on-demand. Se imposti forward_user_identity: true su un upstream, un 429 a una richiesta che portava l'email dello sviluppatore è invece un rifiuto per utente e non esegue il failover.

Ogni richiesta inizia dal primo upstream. Una richiesta raggiunge un upstream successivo solo quando ogni upstream che lo precede ha fallito o non serve il modello richiesto.

Il gateway non tiene traccia degli upstream falliti, quindi mentre un upstream non è disponibile, ogni richiesta che lo raggiunge lo prova comunque e attende che fallisca prima di passare al successivo.

Per un upstream API Anthropic, timeouts.upstream_ttfb_ms limita l'attesa su un upstream non disponibile. Questa impostazione non si applica agli altri provider, dove il gateway attende fino a un'ora che un upstream inizi a rispondere.

404 indica la disponibilità del modello sul singolo upstream, quindi un upstream che non ha abilitato un modello non blocca un upstream successivo che lo serve. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete.

Questo esempio instrada prima un'allocazione di throughput provisioned di Amazon Bedrock, passa in overflow a on-demand e a un secondo account e usa l'API Anthropic come ultimo fallback:

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 static keys.
  - 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:`.
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

Leva	Come
Regioni diverse	Un upstream Amazon Bedrock per regione, ciascuno con la propria `region:`. Con `auto_include_builtin_models: true` i profili di inferenza cross-region instradano automaticamente; per i deployment vincolati a una regione usa un blocco `models:`.
Account diversi	Un upstream Amazon Bedrock per account. La catena predefinita (`auth: {}`) usa l'identità del pod; per un secondo account, aggiungi `assume_role` per raggiungerlo con credenziali a breve durata, oppure imposta credenziali esplicite o un token bearer in `auth:`.
Throughput provisioned	Mappa 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 viene esaurita prima del failover.
Endpoint VPC / FIPS	Imposta `base_url:` sull'upstream all'URL del tuo endpoint VPC o FIPS
Instradamento limitato al modello	Solo un `id` di modello personalizzato, cioè non un modello Claude integrato, salta gli upstream assenti dalla sua mappa `upstream_model:`. Il gateway prova i modelli integrati su ogni upstream in ordine e usa l'ID predefinito del provider dove la mappa non ha una voce, quindi per i modelli integrati la mappa cambia quale ID riceve un upstream anziché se venga provato; un upstream che rifiuta l'ID segue le stesse regole di failover di qualsiasi altro errore dell'upstream.

Il failover tra provider cloud, o verso l'API Anthropic diretta, cambia quale accordo, area geografica e altri termini regolano 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 di limiti di spesa per sviluppatore su /v1/messages. Vedi Limiti di spesa per come vengono impostati e applicati i cap; questa sezione copre le chiavi gateway.yaml che attivano la funzione e la regolano.

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

Campo	Obbligatorio	Descrizione
`write_keys`	No	Array 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_keys`	No	Array 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_groups`	No	Nomi dei gruppi IdP. Un JWT del gateway il cui claim `groups` include uno di questi ha accesso da amministratore completo, in lettura e scrittura, e viene registrato nell'audit come `oidc:<sub>`. Usa questo per gli amministratori umani; usa le chiavi API per le macchine. Una voce vuota in questo elenco arresta il gateway all'avvio. Vedi Valori dei matcher che arrestano il gateway all'avvio.
`blocked_message`	No	Aggiunto alla lettera al `429 billing_error` che uno sviluppatore bloccato vede. Scrivi l'intera istruzione, come un URL o un canale Slack. Se non impostato, il gateway invia solo il messaggio predefinito. Vedi Come funziona l'applicazione.
`audit_retention_days`	No	Predefinito `365`. Le righe `admin_audit` più vecchie vengono eliminate.
`spend_retention_months`	No	Predefinito `13`. Le righe del contatore `spend` più vecchie di questo vengono eliminate. Il valore predefinito mantiene un anno completo più il mese parziale corrente per i rapporti anno su anno.
`identity_retention_days`	No	Predefinito `90`. TTL dall'ultimo accesso 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à rimossa scada mentre i suoi contatori di spesa anonimi rimangono.
`group_limit_mode`	No	`min` (predefinito) o `max`. Quando uno sviluppatore è in diversi gruppi con cap, `min` applica il più restrittivo e `max` il meno restrittivo. Utilizzato sia dall'applicazione che da `/effective`.

`enforcement`

Il blocco enforcement controlla il comportamento dei controlli dei limiti di spesa quando l'archivio non è disponibile.

Campo	Obbligatorio	Descrizione
`fail_closed_on_error`	No	Predefinito `false`. L'applicazione della spesa fallisce aperta in caso di interruzione di Postgres, quindi l'inferenza rimane attiva. Imposta `true` per fallire chiuso: gli sviluppatori oltre il cap vengono bloccati, ma lo è anche chiunque altro se l'archivio non è raggiungibile. Richiede un blocco `admin:`: l'applicazione della spesa viene eseguita solo quando `admin` è configurato, e il gateway rifiuta di avviarsi se imposti questo a `true` senza di esso.

`pricing`

Il blocco pricing dice al misuratore di spesa cosa addebitare invece del prezzo di listino USD, in modo che i cap e /effective riflettano le tue tariffe contrattuali. Gli importi rimangono in USD e rimangono una stima, non una fattura. Due prerequisiti:

Claude Code v2.1.227 o successivo sul server del gateway. Le versioni precedenti rifiutano la chiave sconosciuta all'avvio.
Un blocco admin: o, in v2.1.268 o successivo, un blocco managed: con almeno una policy. Il gateway rifiuta di avviarsi con pricing impostato e nessuno dei due blocchi, perché nulla lo leggerebbe.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

Campo	Obbligatorio	Descrizione
`multiplier`	No	Predefinito `1`. Il misuratore moltiplica ogni importo misurato per questo, sia che sia a prezzo di listino che sovrascritto, quindi `0.85` addebita l'85% del prezzo. Deve essere maggiore di 0 e al massimo 10, e un valore superiore a 1 è un markup.
`overrides`	No	Righe di `{upstream, model, input, output, cache_read, cache_write}` in USD per milione di token. Tutte e quattro le tariffe sono obbligatorie. Ognuna deve essere maggiore di 0 e al massimo 10000.

Come il misuratore abbina una riga di override:

Una riga sostituisce il prezzo di listino per le richieste che upstream, un upstreams[].name, serve per model. Questo include la tariffa più alta della modalità veloce, quindi le richieste veloci e standard vengono misurate alle stesse quattro tariffe.
Un ID incorporato come claude-sonnet-4-6, abbinato come models[].id, copre ogni forma datata, forma regionale di Amazon Bedrock o forma di Agent Platform di Google Cloud che il misuratore prezza come quel modello. Qualsiasi altra stringa, come un alias o un ARN del profilo di inferenza, corrisponde all'ID che il client ha inviato o alla stringa inviata upstream, senza distinzione tra maiuscole e minuscole.
Dove le righe si sovrappongono, il misuratore sceglie la riga più specifica piuttosto che la prima riga: una riga il cui model è la stringa di modello esatta inviata upstream, quindi una riga che corrisponde all'ID esatto che il client ha inviato, quindi una riga che nomina il modello incorporato.
Un nome upstream sconosciuto fa fallire l'avvio, così come due righe per uno stesso upstream che nominano lo stesso modello, incluse due grafie di un modello incorporato. Il gateway avverte all'avvio di una riga che nessun modello richiedibile può utilizzare.
Le richieste di ricerca web rimangono al prezzo di listino di $0.01; il moltiplicatore si applica comunque a loro.

Per tariffe per regione, dai a ogni regione il suo upstream denominato e una riga per upstream.

Aumenta i prezzi

Con v2.1.271 o successivo sul server del gateway, puoi impostare multiplier sopra 1, fino a 10, per misurare più di quanto il provider addebita, ad esempio una tariffa di chargeback interna. Questo esempio misura ogni richiesta al 120% del prezzo:

pricing:
  multiplier: 1.2

Con un blocco admin:, il markup si applica anche ai limiti di spesa. Il misuratore conta il 120% del prezzo, quindi gli sviluppatori raggiungono i loro cap più velocemente. Il gateway registra un avviso all'avvio che lo segnala.

Il moltiplicatore non cambia quello che il provider upstream addebita per le richieste.

Se il gateway inoltre invia le tariffe ai client che hanno effettuato l'accesso, gli sviluppatori hanno bisogno di Claude Code v2.1.271 o successivo per vedere il markup. I client precedenti ignorano un multiplier superiore a 1 e mostrano i costi senza di esso.

Un server gateway precedente a v2.1.271 rifiuta di avviarsi se imposti un multiplier superiore a 1.

Invia le tariffe ai client che hanno effettuato l'accesso

Con v2.1.268 o successivo sul server del gateway, il gateway mette anche le tariffe da pricing nelle policy managed che serve, come l'impostazione gestita modelPricing. Gli sviluppatori abbinati da una policy vedono quindi le tariffe pricing per il primo upstream che serve ogni ID modello in /usage, nella riga di stato e in OpenTelemetry. Uno sviluppatore che non corrisponde a nessuna policy non riceve impostazioni gestite, quindi le sue cifre rimangono al prezzo di listino. I client applicano l'impostazione in Claude Code v2.1.242 o successivo.

Cosa aggiunge il gateway: a meno che il blocco cli di una policy non imposti già modelPricing, il gateway aggiunge il multiplier e, per ogni ID modello che un client può richiedere, la riga di override del primo upstream che serve quell'ID. Una tariffa che solo un upstream di failover addebita rimane sul gateway.
Escludi una policy: imposta modelPricing a {} nel blocco cli di quella policy, e i suoi sviluppatori rimangono al prezzo di listino.
Mantieni le tariffe proprie di una policy: una policy il cui blocco cli imposta modelPricing con il suo multiplier o overrides mantiene quel modelPricing intero, e il gateway non vi aggiunge tariffe proprie.

`models`

Il blocco models è un elenco di modelli facoltativo curato dall'amministratore, servito su /v1/models e utilizzato per tradurre gli ID modello per upstream. È obbligatorio per le regioni non statunitensi di Amazon Bedrock, gli ARN di throughput con provisioning di Amazon Bedrock e i nomi di deploy di Microsoft 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

Ogni chiave sotto upstream_model deve corrispondere al name di un upstream configurato, che per impostazione predefinita è il nome del provider. Una chiave che non corrisponde a nessun upstream fa fallire l'avvio, quindi ometti le righe per i provider che non usi.

`managed`

Il blocco managed definisce policy di accesso basate sui ruoli, associate a gruppi IdP o al dominio email. Le policy vengono valutate in ordine; viene selezionata la prima corrispondenza, su cui viene poi eseguito il merge con la base catch-all match: {}. 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, viene trattato come un livello base. Ogni altra policy eredita dal catch-all qualsiasi chiave che non imposta, quindi le voci per ruolo devono solo elencare ciò che differisce dal valore predefinito dell'organizzazione. Le regole di merge dipendono dal tipo di chiave:

Allowlist: availableModels e permissions.allow. L'elenco di una policy specifica sostituisce completamente quello della base.
Elenchi di negazione e array di hook: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces e ogni array di tipo evento hooks. Questi prendono l'unione di base e policy, quindi un deny a livello di organizzazione o un hook di audit non può essere accidentalmente eliminato da un override per ruolo.
Chiavi di tipo record: env, modelOverrides e skillOverrides. Per queste si esegue un merge superficiale, quindi un blocco env per ruolo sovrascrive le chiavi che imposta ed eredita il resto dalla base.

availableModels viene anche applicato lato server su /v1/messages, quindi un modello negato restituisce 400 indipendentemente da quello che il client invia.

Il gateway convalida il valore model stesso prima di inoltrare una richiesta, quindi un valore malformato non raggiunge mai un upstream. Rifiuta la richiesta con un 400 in due casi:

Quando il valore è mancante o vuoto, il gateway rifiuta la richiesta con il messaggio model is required. Questo controllo richiede un gateway che esegue Claude Code v2.1.228 o successivo.
Quando il valore è presente ma non è una stringa, il gateway rifiuta la richiesta con il messaggio model must be a string. Richiede un gateway che esegue Claude Code v2.1.221 o successivo.

Matcher	Comportamento
`match: {}`	Corrisponde a ogni utente autenticato. Inizia con uno di questi e aggiungi in seguito policy con ambito di gruppo sopra di esso.
`match: { groups: [a, b] }`	Corrisponde se il claim `groups` del JWT contiene uno dei gruppi elencati. Sensibile alle maiuscole: i gruppi devono corrispondere esattamente alle maiuscole e minuscole dell'IdP.
`match: { email_domain: example.com }`	Corrisponde alla parte dopo l'ultimo `@` nel claim `email` del JWT, senza distinzione tra maiuscole e minuscole. Accetta un dominio per policy.
`match: { groups: [a], email_domain: example.com }`	Entrambe le condizioni devono corrispondere

Un utente autenticato che non corrisponde a nessuna policy ottiene i valori predefiniti del gateway, il che significa ogni modello nel catalogo e nessuna impostazione gestita. Aggiungi un catch-all match: {} per ultimo se vuoi una policy predefinita garantita.

Note

Il gateway non mantiene una propria directory utente. Autorizza ogni richiesta dal token IdP dell'utente, leggendo l'appartenenza ai gruppi dal claim groups del token e valutando le policy rispetto ad esso. Non c'è un elenco da enumerare e nessun account da pre-creare, e quindi nessun endpoint SCIM, perché non c'è nulla in cui SCIM possa sincronizzare.

Esegui la gestione del ciclo di vita di utenti e gruppi alla fonte di verità, che è il provisioning SCIM nativo del tuo IdP o una piattaforma dedicata di governance delle identità. L'appartenenza e il deprovisioning gestiti lì fluiscono nel gateway automaticamente attraverso il token. Se vuoi il provisioning SCIM degli account Claude stessi, questa è una funzionalità di Claude for Enterprise.

Si applicano due tempi di propagazione:

Contenuti della policy: modificare una policy e rifare il deploy raggiunge i client connessi al loro prossimo polling delle impostazioni gestite, entro un'ora, a parte le modifiche che si applicano solo al prossimo avvio
Appartenenza ai gruppi: cambiare l'appartenenza ai gruppi di un utente cambia quale policy gli corrisponde. Questo ha effetto alla prossima riemissione della sessione, cioè al prossimo aggiornamento silenzioso, limitato da session.ttl_hours.

Valori dei matcher che arrestano il gateway all'avvio

All'avvio, il gateway controlla il blocco match di ogni policy e l'elenco admin_groups. Uno qualsiasi di questi valori arresta il gateway con un errore che nomina il campo:

Un elenco groups vuoto
Una voce vuota in groups o in admin_groups
Un email_domain vuoto
Un email_domain che contiene @, spazi bianchi o una virgola. Il gateway rimuove gli spazi dal valore e toglie un @ iniziale prima di questo controllo. Scrivi un solo dominio semplice, come example.com.

Prima di v2.1.232, il gateway si avviava con questi valori. Ogni valore aveva questo effetto:

Un email_domain vuoto: il gateway saltava il controllo del dominio, quindi una policy con un email_domain vuoto e nessun elenco groups corrispondeva a ogni utente autenticato
Un elenco groups vuoto: la policy non corrispondeva a nessuno
Un email_domain contenente @, spazi bianchi o una virgola: la policy non corrispondeva a nessuno
Una voce vuota in groups o in admin_groups: la voce corrispondeva a un utente solo quando anche il claim groups dell'IdP di quell'utente conteneva una voce vuota. In admin_groups, quella corrispondenza concedeva l'accesso da amministratore. Se il tuo elenco admin_groups non ha mai contenuto una voce vuota, nessuno ha ottenuto l'accesso da amministratore in questo modo.

Cosa va in `cli`

Ogni valore cli è un documento managed-settings.json completo di Claude Code, lo stesso schema che distribuiresti 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 di utente e progetto, al posto delle impostazioni gestite dal server. Ignora quindi le impostazioni limitate alle fonti di policy a livello di sistema operativo, come policyHelper e wslInheritsWindowsSettings.

Il gateway convalida ogni documento rispetto allo schema delle impostazioni della CLI all'avvio, quindi una chiave di primo livello non riconosciuta fa fallire l'avvio con un errore che nomina ogni chiave problematica. Le parti deliberatamente aperte dello schema accettano comunque valori arbitrari, perché i client più recenti potrebbero riconoscere voci che lo schema del gateway non riconosce. Queste chiavi aperte includono env, pluginConfigs e le chiavi annidate sotto permissions.

Poiché la convalida utilizza lo schema incluso nella versione installata del gateway, inserire nella configurazione gestita una chiave di impostazioni di primo livello introdotta da una versione più recente di Claude Code richiede prima l'aggiornamento del gateway. Esegui uno smoke test di una nuova policy su un client prima di distribuirla.

Il riferimento completo delle chiavi è in Impostazioni di Claude Code. Le chiavi che gli operatori usano per prime:

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 }

Chiave	Applicato da	Effetto
`availableModels`	Gateway + CLI	Allowlist dei modelli. Controllata anche su `/v1/messages`, quindi un client modificato non può aggirarla.
`permissions.allow` / `.deny`	CLI	Regole per strumenti e comandi. Vedi Permessi.
`permissions.disableBypassPermissionsMode`	CLI	Imposta su `disable` per bloccare `bypassPermissions`, la modalità che salta le richieste di permesso, e il flag `--dangerously-skip-permissions`
`allowManagedPermissionRulesOnly`	CLI	Quando `true`, le impostazioni gestite diventano l'unica fonte di impostazioni per le regole di permesso. La voce `allowManagedPermissionRulesOnly` elenca ogni fonte che Claude Code ignora in quel caso.
`env`	CLI	Variabili d'ambiente sottoposte a merge nel processo CLI. Da usare per telemetria, aggiornamento automatico e override dei nomi dei modelli.
`hooks`	CLI	Hook a livello di organizzazione
`managedMcpServers`	CLI	Server MCP remoti forniti a ogni sviluppatore corrispondente insieme ai server che aggiungono loro stessi, solo `http` e `sse`. Vedi Server MCP in una policy. Richiede Claude Code v2.1.259 o successivo sul server del gateway e sui client. I client precedenti ignorano la chiave.

Poiché queste impostazioni arrivano dalla rete, la CLI mostra a ogni sviluppatore una finestra di dialogo di approvazione di sicurezza prima di applicare le impostazioni elencate di seguito:

hooks
variabili env che richiedono l'approvazione dello sviluppatore, come le variabili di proxy e di base URL
impostazioni di esecuzione della shell come apiKeyHelper e statusLine
le impostazioni dei binari della sandbox sandbox.bwrapPath, sandbox.socatPath e sandbox.ripgrep
Impostazioni della sandbox che intercettano il traffico, iniettano credenziali o indeboliscono l'isolamento, come sandbox.network.tlsTerminate e le impostazioni della porta del proxy. Finestre di dialogo di approvazione di sicurezza le elenca tutte.

Memoria delle approvazioni spiega quanto dura un'approvazione e quando la finestra di dialogo appare di nuovo.

Claude Code applica alcune variabili env consegnate senza mostrare allo sviluppatore la finestra di dialogo di approvazione, come le impostazioni di selezione del modello e i limiti numerici. Altre variabili consegnate possono richiedere l'approvazione dello sviluppatore prima di avere effetto; un valore non vuoto di proxy, base URL o OTEL_EXPORTER_OTLP_ENDPOINT la richiede sempre. Quando una variabile consegnata ha bisogno di approvazione, la finestra di dialogo la nomina.

Variabili d'ambiente e la finestra di dialogo di approvazione contiene i dettagli, inclusi quattro interruttori di privacy il cui valore consegnato decide se hanno bisogno di approvazione. Prima di v2.1.218, Claude Code applicava meno variabili senza chiedere allo sviluppatore, quindi più variabili consegnate attivavano la finestra di dialogo.

La configurazione di telemetria del gateway invia OTEL_EXPORTER_OTLP_ENDPOINT, quindi impostare telemetry.forward_to attiva la finestra di dialogo su ogni client interattivo. La finestra di dialogo protegge la macchina dello sviluppatore da un gateway compromesso o ostile, non l'organizzazione dallo sviluppatore.

Un'esecuzione non interattiva, come claude -p o una sessione dell'Agent SDK, non può mostrare la finestra di dialogo. Applica le impostazioni inviate solo per quell'esecuzione e non le registra come approvate, quindi la prossima sessione interattiva dello sviluppatore mostra comunque la finestra di dialogo. Prima di v2.1.207, un'esecuzione non interattiva salvava le impostazioni come approvate e nessuna sessione interattiva successiva mostrava la finestra di dialogo per esse.

Se uno sviluppatore rifiuta, Claude Code esce da quella sessione anziché applicare la policy. Quando invii un nuovo hook, o qualsiasi variabile env che attiva la finestra di dialogo, a una policy ampia, ogni sviluppatore corrispondente vede quindi la finestra di dialogo nelle proprie sessioni interattive. Una sessione interattiva in esecuzione la mostra al prossimo polling orario, altrimenti appare al successivo avvio interattivo dello sviluppatore.

La chiave cli era denominata settings nelle versioni precedenti. Questa grafia è ancora accettata come alias, ma i nuovi deploy dovrebbero usare cli.

Finestra di contesto nelle sessioni da terminale

Le sessioni da terminale con accesso effettuato tramite /login usano la finestra di contesto da 1M per Opus 4.7 e successivi, Sonnet 5 e successivi, e i modelli Fable. L'ID del modello non ha bisogno del suffisso [1m], e le sessioni si compattano a circa 967K token. Prima di Claude Code v2.1.287 sulla macchina dello sviluppatore, Claude Code trattava i modelli Opus e Fable come dotati di una finestra da 200K a meno che l'ID del modello non terminasse con [1m].

Per far sì che le sessioni da terminale si compattino invece al limite dei 200K, imposta la finestra di compattazione automatica nell'env della policy:

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

Claude Code applica questa variabile senza mostrare allo sviluppatore la finestra di dialogo di approvazione. La variabile si applica a ogni modello, inclusi gli ID modello che terminano con [1m].

Per disattivare invece il contesto 1M, imposta CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" nello stesso blocco env. Claude Code tratta quindi ogni modello come dotato di una finestra da 200K. Nelle sessioni interattive, ogni sviluppatore approva questa variabile nella finestra di dialogo di approvazione prima che abbia effetto.

Server MCP in una policy

Per fornire server MCP ai client Claude Code a cui corrisponde una policy, imposta managedMcpServers nel blocco cli di quella policy. Hai bisogno di Claude Code v2.1.259 o successivo sul server del gateway e sui client.

Il gateway controlla ogni voce all'avvio con le stesse regole che Claude Code applica sul client, e se una voce non supera un controllo, il gateway rifiuta di avviarsi e nomina la voce.

Se scrivi un riferimento ${VAR} in gateway.yaml, il gateway lo risolve dal suo ambiente all'avvio tramite l'espansione dei segreti prima di eseguire i controlli sulle voci, quindi ogni client corrispondente riceve il valore letterale e può leggerlo. Le indicazioni sulle intestazioni per i server forniti si applicano al valore espanso.

Il gateway rifiuta la grafia mcpServers di .mcp.json in un blocco cli, e il suo errore di avvio indica managedMcpServers come chiave da usare. Prima di v2.1.259, il gateway rifiutava qualsiasi definizione di server MCP in un blocco cli.

Overlay di Claude Desktop

Se la tua organizzazione distribuisce anche Claude Desktop, lo stesso gateway serve entrambi i client. Punta bootstrapUrl, nella configurazione gestita di Claude Desktop, a <listen.public_url>/user/bootstrap. Claude Desktop deriva l'emittente OAuth da quell'URL, esegue lo stesso accesso con codice dispositivo su questo gateway e recupera la sua configurazione dalla risposta.

Il gateway deriva gran parte della risposta dal blocco cli della policy corrispondente e dalla configurazione di primo livello del gateway:

L'elenco dei modelli, da availableModels. Contesto esteso in Claude Desktop tratta l'opzione di contesto 1M di ciascun modello
Gli strumenti disabilitati, dalle voci permissions.deny con il solo nome dello strumento. Se imposti disabledBuiltinTools nel blocco desktop della policy, il gateway serve l'unione del tuo valore e dell'elenco derivato, quindi puoi disabilitare più strumenti in questo modo ma non puoi riabilitarne uno che hai disabilitato tramite permissions.deny
L'allowlist di uscita, da sandbox.network.allowedDomains. Se imposti coworkEgressAllowedHosts nel blocco desktop della policy, il gateway usa quel valore invece dell'elenco derivato
Un endpoint OTLP che punta al gateway stesso, e gli attributi di identità dell'utente che ha effettuato l'accesso. Il gateway inoltra le esportazioni che riceve su quell'endpoint alle tue destinazioni forward_to. Include l'endpoint e gli attributi quando imposti sia telemetry.forward_to che listen.public_url.

Claude Desktop esporta ogni segnale con un'unica codifica: http/protobuf, oppure http/json quando imposti OTEL_EXPORTER_OTLP_PROTOCOL o una delle sue varianti per segnale a http/json nell'env della policy. Prima di Claude Code v2.1.261 sul server del gateway, la risposta impostava comunque http/json, quindi un collettore che accetta solo protobuf rifiutava le esportazioni di Claude Desktop

Per impostare disabledBuiltinTools, coworkEgressAllowedHosts o l'impostazione managedMcpServers propria di Claude Desktop nel blocco desktop di una policy, hai bisogno di Claude Code v2.1.232 o successivo sul server del gateway. L'impostazione managedMcpServers di Claude Desktop accetta un valore array anziché un oggetto.

Il gateway omette dalla risposta di bootstrap le chiavi senza equivalente in Claude Desktop, come hooks e le regole di permesso con ambito come Bash(npm *).

Aggiungi il blocco facoltativo desktop insieme a cli per impostare direttamente le impostazioni di Claude Desktop. Scrivi le impostazioni del riferimento della configurazione gestita di Claude Desktop come nomi di chiave piatti. Escludi le chiavi che Claude Desktop legge solo da MDM o da file locali, come bootstrapUrl; il gateway le rifiuta all'avvio. Prima di v2.1.232, il gateway accettava un elenco fisso di 11 chiavi di feature gate, come chatTabEnabled e disableAutoUpdates, e rifiutava ogni altra chiave all'avvio. Prima di v2.1.227, il gateway rifiutava all'avvio anche chatTabEnabled e chatAdvancedFileAnalysisEnabled.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

Ogni chiave è facoltativa; Claude Desktop applica il proprio valore predefinito per qualsiasi chiave che ometti. Il gateway convalida ogni blocco desktop all'avvio rispetto allo schema di configurazione che Claude Desktop stesso usa, quindi un errore emerge all'avvio del gateway come un errore che nomina la chiave anziché raggiungere ogni desktop connesso. Il gateway fallisce all'avvio quando un blocco contiene:

Una chiave sconosciuta
Una chiave riconosciuta il cui valore Claude Desktop rifiuterebbe o scarterebbe silenziosamente, come un valore vuoto o una sotto-chiave scritta in modo errato all'interno di una voce annidata. Prima di v2.1.260, il gateway scartava silenziosamente un campo scritto in modo errato all'interno di un oggetto annidato di una voce managedMcpServers o orgPluginSettings invece di fallire all'avvio.
Una chiave che il gateway calcola da solo: la connessione di inferenza, l'elenco dei modelli e l'inoltro OTLP. Configurali tramite upstreams, models e il forward_to della sezione telemetry.
Un alias legacy di una chiave attuale. Nell'errore di avvio, il gateway nomina la chiave canonica da scrivere.

Se usi un valore o una forma di voce deprecati, come una voce managedMcpServers senza transport, il gateway si avvia e registra un avviso che nomina la sostituzione.

Il gateway convalida un blocco desktop rispetto allo schema incluso nella sua versione installata, come fa con il blocco cli. Per consegnare un'impostazione introdotta da una versione più recente di Claude Desktop, aggiorna prima il gateway. Ad esempio, userPluginMarketplacesEnabled e userPluginUploadsEnabled hanno bisogno di Claude Code v2.1.260 o successivo sul server del gateway e di Claude Desktop 1.37937.0 o successivo sulle macchine dei membri.

blockReadsOutsideWorkingDirectories, disableBypassPermissionsMode, configRecheckIntervalMinutes e sshClientPath hanno bisogno di Claude Code v2.1.281 o successivo sul server del gateway. Lo stesso vale per il valore required di microsoftAuthBroker e per il campo continuousAccessEvaluation di una voce managedMcpServers di Microsoft 365. Le versioni di Claude Desktop precedenti al valore required lo leggono come disabled, quindi imposta required solo dopo che il Claude Desktop di ogni membro lo supporta. Il riferimento della configurazione gestita di Claude Desktop elenca la versione che per prima legge ciascuna chiave.

Se imposti orgPluginSettings nel blocco desktop di una policy, il gateway lo serve nella forma di array che Claude Desktop 1.15200.0 e successivi leggono. I desktop più vecchi ignorano l'array e non applicano alcuna policy sugli strumenti dei plugin, quindi aggiorna i membri a 1.15200.0 o successivo prima di farvi affidamento.

Il gateway completa le chiavi che il blocco desktop di una policy non imposta con quelle del blocco desktop del catch-all match: {}, nello stesso modo in cui completa il blocco cli di una policy dalla base. Se imposti disabledBuiltinTools o builtinToolPolicy sia nella base che in una policy per ruolo, il gateway mantiene la restrizione della base:

disabledBuiltinTools: il gateway usa l'unione dell'elenco della base e dell'elenco della policy
builtinToolPolicy: se imposti uno strumento a un valore diverso da allow nella base, il gateway mantiene quel valore anche se imposti allow per lo stesso strumento in una policy per ruolo

Per ogni altra chiave, se la imposti nella policy per ruolo, il gateway usa il valore della policy per ruolo. Il gateway sostituisce per intero un array o un oggetto annidato come banner, quindi se imposti banner.text in una policy per ruolo, il gateway elimina il banner.backgroundColor della base.

Se non distribuisci Claude Desktop, lascia desktop completamente fuori dalle tue policy; il gateway restituisce quindi 404 da /user/bootstrap per ogni utente.

Contesto esteso in Claude Desktop

Se servi Claude Desktop dal gateway, il suo selettore di modelli offre un'opzione di contesto 1M per ogni modello elencato che può essere eseguito con una finestra di contesto da 1M. Tra questi ci sono Claude Opus 4.6 e successivi, Claude Sonnet 4.6 e successivi, e i modelli Fable. L'opzione è la variante [1m] del modello, descritta in Contesto esteso. Hai bisogno di Claude Code v2.1.284 o successivo sul server del gateway.

Una voce models non ottiene l'opzione 1M quando:

Un upstream che può servire la voce la mappa a un modello senza supporto 1M, incluso un upstream che il gateway raggiunge solo in caso di failover
Né il suo id né alcuno dei suoi valori upstream_model nomina un modello Claude, come un alias personalizzato instradato verso l'ARN di un profilo di inferenza dell'applicazione

Per cambiare ciò che offre il selettore, usa uno di questi metodi:

Avvia gli utenti sull'opzione 1M: imposta modelPrefer1mContext: true nel blocco desktop della policy. Gli utenti che non hanno ancora scelto un modello iniziano con l'opzione 1M quando il primo modello elencato ne ha una. Gli utenti che hanno già scelto un modello mantengono la loro scelta.
Offri l'opzione manualmente: fallo se il server del gateway esegue una versione precedente a v2.1.284, o se una voce non nomina alcun modello Claude. Elenca il modello due volte in models, una volta con il suo ID semplice e una volta con [1m] aggiunto, entrambe con la stessa mappa upstream_model. Claude Desktop mostra la coppia come un unico modello con un'opzione 1M. Il gateway serve una voce [1m] senza controllarla, quindi aggiungine una solo per un modello che i tuoi upstream servono a 1M.

Questo esempio offre l'opzione manualmente per un alias personalizzato instradato verso un profilo di inferenza dell'applicazione, e avvia i nuovi utenti su di essa:

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

Rimuovi l'opzione 1M

Per rimuovere l'opzione dal selettore, imposta CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" nel blocco env sotto la chiave cli della policy. Se hai anche elencato una voce il cui id termina con [1m], il gateway la serve comunque, quindi elimina anche quella voce.

La variabile raggiunge anche le sessioni da terminale degli sviluppatori a cui la policy corrisponde. Per ciò che cambia lì, vedi Contesto esteso.

Precedenza rispetto ad altre fonti gestite

Se un dispositivo ha anche una policy consegnata tramite MDM o un managed-settings.json locale, le impostazioni consegnate dal gateway hanno la precedenza. Precedenza all'interno del livello gestito nella pagina delle impostazioni gestite indica quando si applicano le fonti locali, e riporta le chiavi che Claude Code legge da ogni fonte di amministrazione indipendentemente dalla fonte selezionata, come le chiavi di blocco della sandbox, forceRemoteSettingsRefresh e il merge di env per variabile. Un policyHelper configurato in un profilo MDM o nel file delle impostazioni gestite viene eseguito solo quando il gateway non consegna impostazioni; la voce indica cosa sostituisce il suo output.

Gli host di incorporamento come Claude Desktop possono fornire policy tramite l'opzione SDK managedSettings. Impostazioni padre dagli host di incorporamento indica quando Claude Code le applica, e Limitare le impostazioni padre elenca quali impostazioni in direzione di autorizzazione si applicano comunque senza i blocchi allowManaged*Only.

Le policy del gateway si applicano a ogni invocazione di Claude Code sulla macchina, incluse le esecuzioni non interattive claude -p e le sessioni avviate dall'Agent SDK. Se il gateway non è raggiungibile all'avvio, le sessioni con accesso effettuato escono con un errore anziché essere eseguite senza la loro policy.

`telemetry`

La CLI invia metriche, log e, quando abilitate, tracce al gateway, che le inoltra alla lettera a ogni destinazione configurata. Le esportazioni utilizzano OpenTelemetry Protocol (OTLP) su HTTP. Per saltare l'inoltro e far esportare le sessioni direttamente al tuo collettore, nomina il collettore in una policy. Vedi Monitoraggio dell'utilizzo per le metriche e gli eventi che la CLI emette.

Nelle sessioni con accesso effettuato tramite /login, la CLI contrassegna 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 di costi e utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore.

Le sessioni di Claude Desktop e Cowork con accesso effettuato tramite il gateway contrassegnano la loro telemetria con user.email e user.groups insieme a enduser.id, quindi puoi coprire l'utilizzo da terminale, Desktop e Cowork con un'unica query su user.email o user.groups. user.groups è l'elenco dei gruppi IdP separati da virgole.

La telemetria di Desktop e Cowork contiene anche enduser.sub, il claim sub che il tuo provider di identità emette per l'utente, che rimane lo stesso quando l'email di un utente cambia. Le sessioni da terminale riportano lo stesso valore sotto user.id, quindi una query che confronta enduser.sub con user.id del terminale copre insieme l'utilizzo da terminale, Desktop e Cowork di un utente. Nelle esportazioni di Desktop e Cowork, user.id è un identificatore anonimo, non il soggetto.

Come tutti i dati OpenTelemetry di Claude Code, questi attributi vanno solo alle destinazioni che la tua organizzazione configura, mai ad Anthropic.

Se l'elenco dei gruppi di un utente supera i 255 caratteri una volta codificato in percentuale, o un nome di gruppo contiene una virgola o un segno di uguale, il gateway omette user.groups dalla telemetria Desktop e Cowork di quell'utente anziché troncarlo. Le sessioni da terminale di quell'utente riportano comunque l'elenco completo.

Il gateway omette enduser.sub quando il soggetto supera i 255 caratteri una volta codificato in percentuale, o contiene uno spazio, un carattere al di fuori dell'ASCII stampabile, o uno tra , ; = \ " %. La telemetria Desktop e Cowork di quell'utente mantiene i suoi altri attributi.

Hai bisogno di Claude Code v2.1.265 o successivo sul server del gateway per user.email e user.groups nella telemetria di Desktop e Cowork, e di Claude Desktop 1.24012 o successivo sulla macchina di ogni sviluppatore per user.groups.

Hai bisogno di Claude Code v2.1.274 o successivo sul server del gateway per enduser.sub.

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 URL forward_to deve usare https://, con un'eccezione per un collettore sull'interfaccia loopback del gateway stesso:

http://localhost:<port> supera la convalida della configurazione, ma la protezione SSRF blocca ogni esportazione con ECONNREFUSED_SSRF a meno che non imposti CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 nell'ambiente del gateway
http://127.0.0.1:<port> o http://[::1]:<port> fa fallire l'avvio a meno che quella variabile non sia impostata

Per un collettore interno al cluster, esponilo su HTTPS al suo indirizzo interno, o eseguilo come sidecar con la variabile impostata.

Quando HTTPS_PROXY è impostato, il gateway invia le esportazioni attraverso quel proxy.

Per raggiungere direttamente un collettore interno, aggiungilo a NO_PROXY per nome host o per un dominio con un punto iniziale come .internal.example.com, il che richiede Claude Code v2.1.277 o successivo sul server del gateway. Assicurati che il gateway possa raggiungere il collettore senza il proxy. Una voce senza punto iniziale corrisponde solo a quel nome esatto, non ai nomi sotto di esso. Gli intervalli CIDR non corrispondono.

Con l'uscita solo tramite proxy attivata, consenti invece il collettore nel proxy, poiché qualsiasi voce NO_PROXY mantiene disattivata l'uscita solo tramite proxy.

La telemetria è disattivata nella CLI per impostazione predefinita. Quando imposti sia telemetry.forward_to che listen.public_url, il gateway la attiva per i client connessi inviando sei variabili d'ambiente tramite /managed/settings:

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER e OTEL_TRACES_EXPORTER, ognuna impostata a otlp se almeno una destinazione forward_to abilita quel segnale e a none altrimenti
OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Quando aggiungi le tue etichette, il gateway invia anche OTEL_RESOURCE_ATTRIBUTES.

Prima di Claude Code v2.1.265 sul server del gateway, il gateway inviava tutti e tre i selettori di esportazione come otlp, anche per i segnali che nessuna destinazione aveva abilitato.

L'endpoint inviato è costruito dall'URL pubblico, quindi metriche e log non hanno bisogno di configurazione OTEL da parte di sviluppatori o policy.

Gli sviluppatori che hanno effettuato l'accesso tramite /login non possono reindirizzare le esportazioni con la propria configurazione OTEL:

Variabili impostate localmente: Claude Code applica le variabili inviate al livello gestito, quindi ognuna sovrascrive il valore che uno sviluppatore imposta localmente per essa.
Endpoint configurati localmente: con l'esportazione OTLP/HTTP abilitata, la CLI ignora qualsiasi endpoint configurato localmente, indipendentemente dal fatto che il gateway abbia inviato le variabili di telemetria. Le sue esportazioni vanno al gateway a meno che una policy non nomini il tuo collettore come endpoint.

Senza una destinazione forward_to per un segnale, il gateway lo accetta e lo scarta. Se gli sviluppatori esportano già la telemetria di Claude Code a uno dei tuoi collettori, aggiungilo come destinazione forward_to, con log o tracce abilitati se esportano anche quelli, in modo che continui a ricevere i loro dati dopo che hanno effettuato l'accesso. Per saltare invece l'inoltro, nomina il collettore in una policy.

Le tracce richiedono anche CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 su ogni client. Impostala nel blocco env di una policy gestita, poiché il gateway non la invia. Gli sviluppatori la approvano nella stessa finestra di dialogo di approvazione di sicurezza che l'endpoint inviato già attiva.

Impostala a 1 solo nelle policy i cui gruppi vuoi tracciare. Una policy che non la imposta eredita il valore dalla tua policy catch-all match: {} se quella policy ne imposta uno, secondo le regole di merge. Per impedire ai client di un gruppo di inviare tracce anche quando uno sviluppatore imposta la variabile localmente, impostala a 0 nella policy di quel gruppo.

Vengono inoltrate sia la codifica OTLP protobuf che quella JSON, e qualsiasi backend compatibile con OpenTelemetry funziona come destinazione.

Aggiungi le tue etichette

Per applicare etichette fisse come service.namespace o deployment.environment.name alla telemetria delle sessioni con accesso effettuato tramite il gateway, imposta telemetry.resource_attributes. Ogni etichetta è un attributo di risorsa OpenTelemetry, e ogni destinazione riceve le stesse etichette.

Le sessioni ottengono le etichette solo quando imposti anche telemetry.forward_to e listen.public_url. Questo esempio aggiunge due etichette:

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

Il gateway rifiuta di avviarsi quando un'etichetta viola una di queste regole, e l'errore di avvio nomina l'etichetta:

I nomi usano solo lettere, cifre, ., _ e -
I nomi non sono riservati. Confrontati senza distinzione tra maiuscole e minuscole, i nomi riservati sono tutti quelli che iniziano con user., enduser. o identity., più service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version e wsl.version
I valori sono ASCII stampabile non vuoto, senza spazi e senza nessuno tra , ; = \ " %
I valori sono lunghi al massimo 255 caratteri secondo il conteggio del gateway dopo la codifica in percentuale, quindi /, : e @ contano ciascuno come tre
I valori sono testo, quindi metti tra virgolette un numero, true o false

Hai bisogno di Claude Code v2.1.281 o successivo sul server del gateway per impostare telemetry.resource_attributes. Un gateway precedente rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere la chiave, e rimuovi la chiave prima di eseguire il rollback a una versione precedente.

Le sessioni da terminale con accesso effettuato tramite /login ricevono le etichette come OTEL_RESOURCE_ATTRIBUTES, inviata insieme alle altre variabili di telemetria. Se imposti OTEL_RESOURCE_ATTRIBUTES nel blocco env di una policy, le sessioni da terminale a cui quella policy corrisponde ottengono quel valore invece delle etichette. Claude Desktop riceve le etichette dal gateway insieme a user.email e agli altri attributi di identità.

Claude Code copia anche ogni etichetta su ogni punto dati delle metriche, quindi puoi filtrare le metriche in base a essa in un backend che non indicizza gli attributi di risorsa. Per disattivare quella copia, vedi Controllo della cardinalità delle metriche.

Esporta direttamente al tuo collettore

Per far sì che le sessioni con accesso effettuato tramite /login inviino la telemetria direttamente al tuo collettore anziché attraverso l'inoltro, imposta OTEL_EXPORTER_OTLP_ENDPOINT sull'URL base https:// del collettore nel blocco env di una policy gestita. Claude Code aggiunge /v1/metrics, /v1/logs o /v1/traces all'URL che imposti, come https://otel-collector.example.com:4318, ed esporta lì ogni segnale su OTLP/HTTP. Richiede Claude Code v2.1.265 o successivo sulla macchina di ogni sviluppatore. I client precedenti esportano attraverso l'inoltro.

Per autenticarti al collettore, imposta OTEL_EXPORTER_OTLP_HEADERS nello stesso blocco env. Le sessioni non inviano mai il token di sessione del gateway dello sviluppatore a un collettore nominato in questo modo.

Quando aggiungi o modifichi questo endpoint in una policy, Claude Code chiede a ogni sviluppatore di approvarlo nella finestra di dialogo di approvazione di sicurezza prima di applicarlo in una sessione interattiva.

Claude Code controlla l'endpoint prima di esportare direttamente un segnale, e mantiene quel segnale sull'inoltro quando un controllo fallisce. I controlli includono:

L'endpoint proviene dal gateway stesso. Se imposti la stessa variabile in un profilo MDM o in un managed-settings.json locale, le esportazioni rimangono sull'inoltro.
L'URL usa https://, oppure http:// verso un indirizzo loopback
L'URL si risolve in un percorso che termina con /v1/<signal>, senza query né frammento. Claude Code costruisce da solo quel percorso a partire dalla variabile generica. Usa una variabile per segnale come OTEL_EXPORTER_OTLP_METRICS_ENDPOINT così come è scritta, quindi lì includi il percorso completo.
L'URL non è l'host del gateway stesso. Un endpoint indirizzato al gateway mantiene il percorso di inoltro e il suo token di sessione.
Né tu né lo sviluppatore avete configurato otelHeadersHelper in alcuna fonte di impostazioni. Con un helper configurato, ogni segnale rimane sull'inoltro.

L'endpoint che nomini cambia solo la destinazione delle esportazioni. Scegli comunque quali segnali esportare con i selettori OTEL_*_EXPORTER.

L'endpoint da solo non attiva l'esportazione, quindi imposta anche le variabili che lo fanno, a meno che il gateway non le invii già:

Se il gateway invia già le variabili di telemetria, queste coprono l'abilitazione, i selettori e il protocollo, e il tuo endpoint esplicito sovrascrive il valore <public_url> inviato. Imposta tu stesso un selettore OTEL_*_EXPORTER a otlp solo per un segnale che nessuna destinazione forward_to abilita.
Se non lo fa, imposta anche CLAUDE_CODE_ENABLE_TELEMETRY=1, i selettori OTEL_*_EXPORTER e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Quando lo sviluppatore esce, o accede a un gateway diverso, le esportazioni al collettore si interrompono e Claude Code scarta ogni batch rimanente anziché inviarlo.

Quando una destinazione fallisce

Il gateway non bufferizza, non riprova e non archivia la telemetria, quindi scarta un'esportazione che non raggiunge una destinazione anziché consegnarla in ritardo. Ogni destinazione riesce o fallisce per conto proprio, e il client che esporta riceve comunque una risposta di successo, quindi una consegna fallita appare solo nel log del gateway.

Dopo cinque consegne consecutive fallite a una destinazione, il gateway sospende l'inoltro verso di essa per intervalli di 30 secondi, registrando ogni pausa, finché una consegna non riesce. Qualsiasi risposta di errore, timeout o errore di connessione conta come consegna fallita, tranne 400, 413, 415, 422 e 431, che indicano che il collettore ha rifiutato il payload di quell'esportazione perché malformato o troppo grande.

Un payload rifiutato non fa avanzare né azzera il conteggio dei fallimenti: il gateway continua a inoltrare alla destinazione e registra un avviso che la nomina insieme allo stato, al primo rifiuto della destinazione e poi ogni cento.

Ottimizzazione HTTP

Quattro blocchi facoltativi di primo livello, access_control, limits, timeouts e rate_limits, regolano la superficie HTTP. I valori predefiniti sono adatti alla maggior parte dei deploy.

Blocco	Chiave	Predefinito	Descrizione
`access_control`	`allow_cidrs` / `deny_cidrs`	vuoto	Consenso/negazione degli IP in entrata per indirizzo client, dopo la risoluzione di `trusted_proxies`. `deny_cidrs` viene controllato per primo; un client a cui corrisponde viene rifiutato anche se corrisponde anche `allow_cidrs`. Se `allow_cidrs` non è vuoto, il gateway nega per impostazione predefinita. `/healthz` e `/readyz` sono esenti da `allow_cidrs`. Quando un proxy attendibile invia una voce `X-Forwarded-For` che non è un indirizzo IP, il client reale è sconosciuto e il gateway registra una sola volta un avviso che indica cosa controllare. Dove uno dei due elenchi si applica alla richiesta, la rifiuta con `403` e motivo di audit `xff_unparseable`. Dove nessuno dei due si applica, serve la richiesta e usa l'indirizzo del proxy stesso come IP del client per i rate limit per IP e per l'audit.
`limits`	`max_request_bytes`	32 MiB	Dimensione massima del corpo della richiesta in entrata; le richieste troppo grandi ottengono `413` prima che il corpo venga bufferizzato. Aumentalo per richieste con file o immagini di grandi dimensioni.
`limits`	`max_request_header_bytes`	non impostato	Quando impostato, le intestazioni troppo grandi restituiscono `431`
`limits`	`max_url_length`	non impostato	Quando impostato, un URL troppo lungo restituisce `414`
`timeouts`	`upstream_ttfb_ms`	120000	Attesa massima per le intestazioni di risposta dell'upstream (tempo al primo byte). Il corpo della risposta viene poi trasmesso in streaming senza limite di tempo complessivo. Si applica al percorso upstream diretto di Anthropic; con ogni altro provider il gateway attende fino a un'ora che la risposta inizi.
`rate_limits`	`device_authorization.max` / `.window_seconds`	30 / 600	Rate limit per IP sull'endpoint non autenticato di autorizzazione del dispositivo. Aumentalo per una grande organizzazione dietro un IP di uscita condiviso o NAT. Distribuzioni su larga scala mostra come dimensionarlo. Questi limiti si applicano solo al flusso di accesso con concessione del dispositivo, non all'inferenza su `/v1/messages`. Vedi Resistenza al brute force dei codici utente.
`rate_limits`	`device_verify.max` / `.window_seconds`	10 / 600	Rate limit per IP sugli invii di `user_code` su `/device`. È ciò che impedisce a qualcuno di indovinare il codice di un altro sviluppatore. Distribuzioni su larga scala mostra di quanto aumentarlo.

Se lasci vuoti entrambi gli elenchi access_control, che è il valore predefinito, il gateway serve qualsiasi indirizzo client, quindi solo la tua rete limita chi può raggiungerlo. Questo è importante perché un gateway può inviare impostazioni gestite che eseguono comandi sulle macchine degli sviluppatori.

Mentre allow_cidrs è vuoto, il gateway avverte in due punti, senza cambiare il modo in cui risponde alle richieste:

All'avvio: un avviso nel log operativo consiglia di consentire solo gli intervalli privati 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128 e fc00::/7, più qualsiasi altro intervallo interno da cui si connettono i tuoi sviluppatori. Se associ il gateway a un indirizzo loopback e non imposti né trusted_proxies né public_url, come nello sviluppo locale, l'avviso non appare.
In fase di esecuzione: la prima volta che una richiesta arriva da un indirizzo al di fuori di quegli intervalli privati, il gateway registra un avviso ed emette un evento di audit access.public_client contenente l'IP del client. Entrambi si attivano una volta per processo. Gli indirizzi link-local, 169.254.0.0/16 e fe80::/10, non contano come pubblici. Il gateway risponde a /healthz e /readyz prima che questo controllo venga eseguito, quindi i probe di salute da intervalli pubblici non lo attivano.

Entrambi i segnali usano l'indirizzo del client così come il gateway lo risolve. Se un load balancer, un port-forward o un tunnel inoltra il traffico e non è elencato in listen.trusted_proxies, il gateway vede l'indirizzo dell'intermediario, che di solito è privato, quindi né l'avviso in fase di esecuzione né un'allowlist privata intercettano il traffico inoltrato attraverso di esso.

Dietro un front end di questo tipo, imposta prima listen.trusted_proxies in modo che il gateway veda gli indirizzi reali dei client, e in ogni caso mantieni il gateway e tutto ciò che si trova davanti a esso irraggiungibili dalla rete internet pubblica.

`load_test_mode`

Il blocco load_test_mode ti consente di eseguire un test di carico su un gateway senza chiamare un provider di modelli. Mentre è attivo, il gateway costruisce e firma ogni richiesta al provider come di consueto, la scarta invece di inviarla e trasmette in streaming una risposta preconfezionata attraverso il suo normale percorso di risposta. La risposta è testo di riempimento che inizia con una frase che dichiara che è preconfezionata.

Richiede Claude Code v2.1.282 o successivo sul server del gateway. Un gateway precedente rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere il blocco, e rimuovi il blocco prima di eseguire il rollback.

L'esempio seguente attiva la modalità con i valori predefiniti, una risposta di circa 750 token di testo trasmessa in streaming in circa 10 secondi:

load_test_mode:
  enabled: true
  reply_tokens: 750     # roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    # how long a streamed reply takes

Campo	Obbligatorio	Descrizione
`enabled`	Sì	`true` attiva la modalità. `false` mantiene i tuoi valori nel file con la modalità disattivata. Il gateway rifiuta di avviarsi se il blocco è presente senza di esso.
`reply_tokens`	No	Predefinito `750`. Circa quanti token di testo contiene ogni risposta preconfezionata, un numero intero da 1 a 100000.
`reply_seconds`	No	Predefinito `9.5`. Quanto dura una risposta in streaming, da 0 a 600. `0` invia l'intera risposta in una volta. La risposta a una richiesta non in streaming torna sempre in una volta.

Un test di carico in questa modalità copre il gateway, il tuo Postgres e tutto ciò che si trova davanti al gateway. Non copre i limiti, la velocità o il percorso di rete del provider.

Nessuna richiesta di modello viene inviata al provider, quindi la CPU per richiesta di una replica è una stima e risulta inferiore a quella di produzione, dove la replica cifra anche il traffico verso il provider. Conferma il numero di repliche con un piccolo pilota sul provider reale. Prima di v2.1.283, la stima risulta molto più bassa.

Mentre la modalità è attiva, una richiesta può contenere un'intestazione x-load-test-user con un numero intero di al massimo sette cifre. Il gateway conta ogni numero come uno sviluppatore separato, con l'email e i gruppi dello sviluppatore il cui token accompagnava la richiesta.

Assegna al deploy del test di carico un database vuoto dedicato, perché il gateway rifiuta di avviarsi con la modalità attiva su un database in cui uno sviluppatore abbia già speso qualcosa.

Esempio completo

Questo config di riferimento completo esercita ogni sezione principale; i blocchi di sintonizzazione HTTP mantengono i loro valori predefiniti. Copialo, elimina ciò che non ti serve e inserisci i tuoi valori. La configurazione nella Guida rapida è una versione minima di questa.

# Run with:
#   claude gateway --config gateway.yaml
#
# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
# environment variable (debug | info | warn | error; default info). debug
# also logs the claim names in each id_token, for groups_claim diagnosis.
# 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
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # keep passing the readiness check through a database failover

# 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

# Load test this deployment without calling a model provider. Never on a
# gateway that developers use: every request gets a canned reply.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# Meter at contracted rates instead of USD list price. Requires admin: or a
# managed: policy. With managed:, the same rates also go to signed-in clients.
# Rates below are placeholders, not real contract prices.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

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

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

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - 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
      # anthropicAws: 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 gateway. Punta le macchine degli sviluppatori al gateway separatamente, su ogni dispositivo, attraverso le impostazioni gestite di Claude Code. Il gateway non può inviare da solo le chiavi di accesso, perché sono proprio loro a indicare al client dove si trova il gateway.

Per la CLI, imposta queste chiavi nel file managed-settings.json di ogni sistema operativo. Le due chiavi di accesso instradano il /login di ogni sviluppatore al tuo gateway:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge" mantiene funzionante la consegna dell'allowlist di egress da parte di Claude Desktop alle sue sessioni Claude Code incorporate; Deliver policy to Claude Desktop sessions spiega il meccanismo e dove deve trovarsi l'opt-in.

Per impedire agli sviluppatori di aggirare il gateway con una variabile di un provider cloud o con un proprio ANTHROPIC_BASE_URL, aggiungi "allowedProviders": ["gateway"] allo stesso file. Claude Code rifiuta quindi ogni sessione sulla macchina che non sia configurata per un Cloud gateway, e ammette un gateway solo quando è quello indicato da forceLoginGatewayUrl oppure uno il cui URL è impostato come ANTHROPIC_BASE_URL nel blocco env del file. claude gateway si rifiuta di essere eseguito su una macchina che imposta l'elenco, quindi non inserire la chiave sull'host del gateway. Consulta la voce allowedProviders nel riferimento delle impostazioni. Richiede Claude Code v2.1.285 o successivo.

Distribuisci il file managed-settings.json a ogni dispositivo, tipicamente tramite la tua piattaforma MDM. Il percorso del file differisce per piattaforma. Consulta dove ogni meccanismo memorizza la policy.

Per impostazione predefinita, una policy del registro su Windows o un plist di preferenze gestite su macOS sostituisce il file managed-settings.json anziché farne il merge, ad eccezione delle chiavi di eccezione e dei controlli tra fonti descritti sopra. Tutte e tre le chiavi in questo frammento seguono la regola della fonte con priorità più alta, quindi le flotte che distribuiscono la policy tramite Group Policy o profili di configurazione devono inserirle tutte e tre in quel meccanismo.

Per Claude Desktop, imposta la chiave bootstrapUrl nella configurazione gestita di Claude Desktop su <listen.public_url>/user/bootstrap. Il flusso di accesso e la policy per gruppo corrispondono quindi a quelli della CLI una volta che una policy si attiva lato server con una chiave desktop; senza l'opt-in, /user/bootstrap restituisce 404. Consulta Claude Desktop overlay per la metà lato server.

Claude Code rispetta forceLoginGatewayUrl, gatewayInternalNetworks e il valore "gateway" di forceLoginMethod solo da una fonte gestita sulla macchina: managed-settings.json, il plist macOS o il registro HKLM di Windows, oppure un policy helper. Impostarli nel ~/.claude/settings.json personale di uno sviluppatore o nel payload del gateway non configura l'accesso tramite gateway.

Lascia forceLoginMethod e forceLoginOrgUUID fuori dal payload. Claude Code legge comunque entrambe le chiavi dal payload per il controllo delle credenziali all'avvio, quindi uno sviluppatore che mantiene sulla macchina una credenziale emessa da Anthropic incorre nell'uscita all'avvio descritta in La policy dell'amministratore richiede un accesso tramite Cloud gateway anche dopo aver effettuato l'accesso.

Panoramica del gateway delle app Claude: guida rapida e connessione dello sviluppatore
Guida alla distribuzione: configurazione IdP, immagine del contenitore, Kubernetes e Cloud Run e operazioni
Limiti di spesa: cap per sviluppatore e API Admin

claude-apps-gateway-config.md +494 −309

64| - | - | - |64| - | - | - |

65| `host` | No | Indirizzo di binding. Predefinito `0.0.0.0`. |65| `host` | No | Indirizzo di binding. Predefinito `0.0.0.0`. |

66| `port` | No | Porta di binding. Predefinito `8080`. |66| `port` | No | Porta di binding. Predefinito `8080`. |

67| `public_url` | Se non è loopback | L'origine `https://` visibile esternamente, utilizzata per costruire il `redirect_uri` dell'IdP e i metadati di scoperta. Obbligatorio ogni volta che `host` non è un indirizzo loopback, sia che TLS termini a un proxy come un ALB, Ingress o Cloud Run o al gateway stesso tramite `tls`, perché il gateway non deriva mai la sua stessa origine dagli header `X-Forwarded-*`; sono falsificabili dal client. L'avvio fallisce senza di esso. `trusted_proxies` di seguito governa solo la risoluzione dell'IP del client. Obbligatorio anche per abilitare la [telemetria](#telemetry), perché il gateway costruisce l'endpoint OTLP che spinge ai client da questo URL. |67| `public_url` | A meno che `host` non sia loopback | L'origine `https://` visibile esternamente, utilizzata per costruire il `redirect_uri` dell'IdP e i metadati di scoperta. Obbligatorio ogni volta che `host` non è un indirizzo loopback, sia che TLS termini a un proxy come un ALB, Ingress o Cloud Run o al gateway stesso tramite `tls`, perché il gateway non deriva mai la sua stessa origine dagli header `X-Forwarded-*`; sono falsificabili dal client. L'avvio fallisce senza di esso. `trusted_proxies` di seguito governa solo la risoluzione dell'IP del client. Obbligatorio anche per abilitare la [telemetria](#telemetry), perché il gateway costruisce l'endpoint OTLP che spinge ai client da questo URL. |

68| `tls.cert` / `tls.key` | No | Percorsi PEM se il gateway termina TLS stesso |68| `tls.cert` / `tls.key` | No | Percorsi PEM se il gateway termina TLS stesso |

69| `trusted_proxies` | No | CIDR 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`. Le voci `X-Forwarded-For` scritte come `ipv4:port` o `[ipv6]:port`, come fanno alcuni load balancer, vengono lette con la porta eliminata. Un indirizzo IPv6 con una porta aggiunta e senza parentesi può essere letto come un indirizzo diverso o non letto affatto, quindi disattivate l'opzione della porta su qualsiasi proxy che scrive quella forma. |69| `trusted_proxies` | No | CIDR 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`. Le voci `X-Forwarded-For` scritte come `ipv4:port` o `[ipv6]:port`, come fanno alcuni load balancer, vengono lette con la porta eliminata. Un indirizzo IPv6 con una porta aggiunta e senza parentesi può essere letto come un indirizzo diverso o non letto affatto, quindi disattiva l'opzione della porta su qualsiasi proxy che scrive quella forma. |

70 70

71<h3 id="oidc">71<h3 id="oidc">

72 `oidc`72 `oidc`

73</h3>73</h3>

74 74

75Il 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.75Il blocco `oidc` connette il gateway al tuo 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.

76 76

77OpenID Connect (OIDC) è il protocollo SSO che il gateway utilizza con il vostro provider di identità; vedere [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup) per ciò che registrare sul lato IdP.77OpenID Connect (OIDC) è il protocollo SSO che il gateway utilizza con il tuo provider di identità; consulta [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup) per ciò che registrare sul lato IdP.

78 78

80| - | - | - |80| - | - | - |

81| `issuer` | Sì | Base 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](/docs/it/claude-apps-gateway-deploy#threat-model-summary) a meno che `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` non sia impostato nell'ambiente del gateway. |81| `issuer` | Sì | Base di scoperta OIDC. Deve servire la scoperta su `/.well-known/openid-configuration`. Usa HTTPS in produzione; il gateway accetta un emittente `http://`. Un emittente loopback come `http://localhost:8081` è rifiutato dalla [guardia SSRF](/docs/it/claude-apps-gateway-deploy#threat-model-summary) a meno che `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` non sia impostato nell'ambiente del gateway. |

~~82| `client_id` / `client_secret` | Sì | Dalla vostra registrazione del client OAuth |~~82| `client_id` / `client_secret` | Sì | Dalla tua registrazione del client OAuth |

83| `allowed_email_domains` | No | Rifiutate 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. |83| `allowed_email_domains` | No | Rifiuta gli id\_token il cui claim `email` non è in uno di questi domini, senza distinzione tra maiuscole e minuscole. Difesa in profondità contro la configurazione errata dell'IdP multi-tenant. Indipendentemente da questa impostazione, un id\_token il cui claim `email_verified` è esplicitamente `false` è sempre rifiutato. |

84| `allowed_groups` | No | Limitate 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. L'abbinamento è un confronto di stringhe esatto e case-sensitive rispetto ai valori in quel claim, e il gateway non espande i gruppi annidati: per ammettere i membri di un sottogruppo, elencate il sottogruppo qui o configurate l'IdP per emettere l'appartenenza appiattita. |84| `allowed_groups` | No | Limita 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. L'abbinamento è un confronto di stringhe esatto e case-sensitive rispetto ai valori in quel claim, e il gateway non espande i gruppi annidati: per ammettere i membri di un sottogruppo, elenca il sottogruppo qui o configura l'IdP per emettere l'appartenenza appiattita. |

85| `groups_claim` | No | Quale 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. |85| `groups_claim` | No | Quale claim dell'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. |

86| `google_groups` | No | Cercate 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. |86| `google_groups` | No | Cerca i gruppi dell'utente che ha effettuato l'accesso tramite la Directory API del Google Workspace Admin SDK, perché l'id\_token di Google non porta alcun claim di gruppi. Imposta `service_account_json_path` su un file di chiave dell'account di servizio con delega a livello di dominio sullo scope `https://www.googleapis.com/auth/admin.directory.group.readonly` e `admin_email` su un amministratore di Workspace che l'account di servizio impersona; la Directory API richiede un soggetto amministratore reale. Gli indirizzi email dei gruppi di ogni utente diventano il suo claim di gruppi, quindi `allowed_groups` e `managed.policies.match.groups` corrispondono agli indirizzi email dei gruppi. |

87| `email_claim` | No | Quale 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. |87| `email_claim` | No | Quale claim dell'id\_token porta l'email dell'utente. Predefinito `email`. Alcuni IdP, come ADFS ed Entra B2C, emettono invece `upn` o `preferred_username`. Accetta una chiave flat, un JSON Pointer o un elenco di chiavi di fallback dove viene utilizzata la prima chiave presente. |

88| `scopes` | No | Override 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à](/docs/it/claude-apps-gateway-deploy#identity-provider-setup) per ricette di ambito per IdP come il flusso di token di aggiornamento di Google. |88| `scopes` | No | Override completo degli scope OIDC che il gateway richiede. Predefinito `[openid, profile, email, offline_access]`. Impostalo quando il tuo IdP rifiuta gli scope che non riconosce o richiede uno scope personalizzato per emettere gruppi o email. Deve includere `openid`. Eliminare `offline_access` disabilita i token di aggiornamento, quindi gli sviluppatori rieseguono l'accesso nel browser ogni `session.ttl_hours`. Consulta [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup) per ricette di scope per IdP come il flusso dei token di aggiornamento di Google. |

89| `scope_on_refresh` | No | Inviate anche `scope`, con lo stesso elenco della richiesta di accesso, quando il gateway scambia un token di aggiornamento. Predefinito `false`: la richiesta di aggiornamento omette `scope`. La maggior parte degli IdP restituisce un id\_token ad ogni aggiornamento e non ha bisogno di questo. Impostate `true` quando il vostro IdP restituisce un id\_token al momento dell'aggiornamento solo se richiesto di nuovo `openid`, che Okta documenta per il suo grant di aggiornamento. Senza un id\_token, ogni aggiornamento dipende dall'endpoint userinfo dell'IdP che accetta il token di accesso aggiornato. Se controllate l'accesso o abbinate le politiche sui gruppi e l'id\_token dell'IdP al momento dell'aggiornamento li omette, impostate anche `userinfo_fallback: true` in modo che il gateway li riempia dall'endpoint userinfo. Un IdP che ha concesso meno ambiti di quelli richiesti può rifiutare l'aggiornamento con `invalid_scope`, incluso per le sessioni esistenti se aggiungete voci a `scopes` mentre questo è attivo. Deselezionate la chiave se gli aggiornamenti iniziano a fallire su `token_endpoint` dopo averla impostata. Richiede Claude Code v2.1.260 o successivo sul server del gateway. |89| `scope_on_refresh` | No | Invia anche `scope`, con lo stesso elenco della richiesta di accesso, quando il gateway scambia un token di aggiornamento. Predefinito `false`: la richiesta di aggiornamento omette `scope`. La maggior parte degli IdP restituisce un id\_token ad ogni aggiornamento e non ne ha bisogno. Imposta `true` quando il tuo IdP restituisce un id\_token all'aggiornamento solo se gli viene richiesto di nuovo `openid`, cosa che Okta documenta per il suo grant di aggiornamento. Senza un id\_token, ogni aggiornamento dipende dal fatto che l'endpoint userinfo dell'IdP accetti il token di accesso aggiornato. Se limiti l'accesso o abbini le policy in base ai gruppi e l'id\_token dell'IdP al momento dell'aggiornamento li omette, imposta anche `userinfo_fallback: true` in modo che il gateway li recuperi dall'endpoint userinfo. Un IdP che ha concesso meno scope di quelli richiesti può rifiutare l'aggiornamento con `invalid_scope`, anche per le sessioni esistenti se aggiungi voci a `scopes` mentre questa opzione è attiva. Rimuovi la chiave se gli aggiornamenti iniziano a fallire su `token_endpoint` dopo averla impostata. Richiede Claude Code v2.1.260 o successivo sul server del gateway. |

90| `extra_auth_params` | No | Parametri 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`. |90| `extra_auth_params` | No | Parametri di query extra aggiunti alla richiesta di autorizzazione dell'IdP, testualmente. 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`. |

91| `userinfo_fallback` | No | Quando 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`. |91| `userinfo_fallback` | No | Quando l'id\_token omette email o gruppi, recuperali 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`. |

~~92| `use_pkce` | No | Inviate una sfida PKCE (S256) sulla richiesta di autorizzazione. Predefinito `true`. Impostate `false` solo se il vostro IdP rifiuta PKCE per questo client confidenziale. |~~92| `use_pkce` | No | Invia una sfida PKCE (S256) sulla richiesta di autorizzazione. Predefinito `true`. Imposta `false` solo se il tuo IdP rifiuta PKCE per questo client confidenziale. |

93| `clock_skew_seconds` | No | Tollerare 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. |93| `clock_skew_seconds` | No | Tollera la deriva dell'orologio quando si convalidano i claim temporali dell'id\_token. Predefinito `0`, che è rigoroso. Aumentalo se vedi errori "token scaduto / non ancora valido" subito dopo l'accesso a causa della deriva dell'orologio tra host e IdP. |

94| `token_endpoint_auth_method` | No | Override del metodo di autenticazione dell'endpoint del token. Accetta `client_secret_basic` o `client_secret_post`. Negoziato automaticamente per impostazione predefinita. |94| `token_endpoint_auth_method` | No | Override del metodo di autenticazione dell'endpoint del token. Accetta `client_secret_basic` o `client_secret_post`. Negoziato automaticamente per impostazione predefinita. |

~~95| `id_token_signed_response_alg` | No | Algoritmo di firma id\_token previsto. Predefinito `RS256`. Impostate per gli IdP che firmano con ES256, PS256 o EdDSA. |~~95| `id_token_signed_response_alg` | No | Algoritmo di firma dell'id\_token previsto. Predefinito `RS256`. Impostalo per gli IdP che firmano con ES256, PS256 o EdDSA. |

96| `additional_authorized_parties` | No | Valori `azp` extra da accettare oltre a `client_id`, per i flussi di broker e scambio di token di Keycloak |96| `additional_authorized_parties` | No | Valori `azp` extra da accettare oltre a `client_id`, per i flussi di broker e scambio di token di Keycloak |

97| `discovery_url` | No | Recuperate 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/`. |97| `discovery_url` | No | Recupera 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/`. |

98| `use_proxy` | No | Inviate le richieste IdP del gateway stesso attraverso il proxy forward in `HTTPS_PROXY` o `HTTP_PROXY`, onorando `NO_PROXY`. `false` mantiene quelle richieste dirette. Richiede v2.1.227 o successivo; vedere [Richieste IdP attraverso un proxy forward](#idp-requests-through-a-forward-proxy) di seguito. |98| `use_proxy` | No | Invia le richieste IdP del gateway stesso attraverso il forward proxy in `HTTPS_PROXY` o `HTTP_PROXY`, rispettando `NO_PROXY`. `false` mantiene quelle richieste dirette. Richiede v2.1.227 o successivo; consulta [Richieste IdP attraverso un forward proxy](#idp-requests-through-a-forward-proxy) di seguito. |

99| `form_action_origins` | No | Origini 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. |99| `form_action_origins` | No | Origini 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 tuo IdP reindirizza attraverso un secondo host, come Azure AD federato ad ADFS, Okta hub-spoke o un intercettore SSO aziendale, elenca ogni origine attraverso cui la richiesta di autorizzazione può essere reindirizzata. |

100| `ca_cert_pem` | No | Il certificato CA PEM stesso, non un percorso a un file. Sostituisce l'archivio di fiducia del sistema solo per le richieste IdP. Per caricare un file montato, scrivete `${file:/etc/gateway/idp-ca.pem}`. Usate per Keycloak o Dex dietro PKI aziendale. |100| `ca_cert_pem` | No | Il certificato CA codificato in PEM stesso, non un percorso a un file. Sostituisce l'archivio di attendibilità del sistema solo per le richieste IdP. Per caricare un file montato, scrivi `${file:/etc/gateway/idp-ca.pem}`. Usalo per Keycloak o Dex dietro una PKI aziendale. |

101 101

102<h4 id="idp-requests-through-a-forward-proxy">102<h4 id="idp-requests-through-a-forward-proxy">

103 Richieste IdP attraverso un proxy forward103 Richieste IdP attraverso un forward proxy

104</h4>104</h4>

105 105

106Gli upstream di inferenza onorare `HTTPS_PROXY` e `HTTP_PROXY` su ogni versione. Le richieste del gateway stesso all'IdP, scoperta, JWKS, token e userinfo, vanno dirette a meno che non impostiate `oidc.use_proxy: true`, che richiede v2.1.227 o successivo. Quando una variabile proxy è impostata, `use_proxy` non è impostato e l'emittente non è coperto da `NO_PROXY`, il gateway mantiene quelle richieste dirette e registra un avviso all'avvio chiedendovi di scegliere; `use_proxy: false` le mantiene dirette e silenzia l'avviso.106Gli upstream di inferenza rispettano `HTTPS_PROXY` e `HTTP_PROXY` in ogni versione. Le richieste del gateway stesso all'IdP (scoperta, JWKS, token e userinfo) vanno dirette a meno che non imposti `oidc.use_proxy: true`, che richiede v2.1.227 o successivo. Quando una variabile proxy è impostata, `use_proxy` non è impostato e l'emittente non è coperto da `NO_PROXY`, il gateway mantiene quelle richieste dirette e registra un avviso all'avvio chiedendoti di scegliere; `use_proxy: false` le mantiene dirette e silenzia l'avviso.

107 107

108Con `use_proxy: true`, il pod risolve il nome host di ogni endpoint IdP stesso e chiede al proxy di `CONNECT` all'indirizzo IP risolto, quindi il proxy deve accettare `CONNECT` all'indirizzo IP di ogni host che il documento di scoperta nomina, non solo l'emittente. Usate un URL proxy `http://`. `ca_cert_pem` e la [guardia SSRF](/docs/it/claude-apps-gateway-deploy#threat-model-summary) si applicano anche sul percorso proxato.108Con `use_proxy: true`, il pod risolve da sé il nome host di ogni endpoint IdP e chiede al proxy di eseguire `CONNECT` verso l'indirizzo IP risolto, quindi il proxy deve accettare `CONNECT` verso l'indirizzo IP di ogni host indicato dal documento di scoperta, non solo dell'emittente. Usa un URL proxy `http://`. `ca_cert_pem` e la [guardia SSRF](/docs/it/claude-apps-gateway-deploy#threat-model-summary) si applicano anche sul percorso tramite proxy.

109 109

110[Egress solo proxy](#proxy-only-egress) cambia entrambi questi: mentre è attivo, le richieste IdP seguono il proxy a meno che non impostiate `use_proxy: false`, e il gateway consegna al proxy ogni nome host IdP senza risolverlo prima.110L'[egress solo tramite proxy](#proxy-only-egress) cambia entrambi questi aspetti: mentre è attivo, le richieste IdP passano per il proxy a meno che tu non imposti `use_proxy: false`, e il gateway consegna al proxy ogni nome host IdP senza risolverlo prima.

111 111

112<h4 id="proxy-only-egress">112<h4 id="proxy-only-egress">

113 Egress solo proxy113 Egress solo tramite proxy

114</h4>114</h4>

115 115

116Impostate `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` nell'ambiente del gateway, accanto a `HTTPS_PROXY`, quando il pod raggiunge altri host solo attraverso quel proxy forward e non può risolvere i nomi DNS pubblici stesso, o quando il proxy rifiuta `CONNECT` a un indirizzo IP. Richiede v2.1.277 o successivo. È una variabile di ambiente piuttosto che una chiave `gateway.yaml` in modo che nulla nel file di configurazione possa rilassare il controllo dell'indirizzo del gateway.116Imposta `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` nell'ambiente del gateway, accanto a `HTTPS_PROXY`, quando il pod raggiunge altri host solo attraverso quel forward proxy e non può risolvere da sé i nomi DNS pubblici, o quando il proxy rifiuta `CONNECT` verso un indirizzo IP. Richiede v2.1.277 o successivo. È una variabile d'ambiente anziché una chiave di `gateway.yaml` in modo che nulla nel file di configurazione possa allentare il controllo degli indirizzi del gateway.

117 117

118```bash theme={null}118```bash theme={null}

119export HTTPS_PROXY=http://proxy.corp.example.com:3128119export HTTPS_PROXY=http://proxy.corp.example.com:3128

122export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1122export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

123```123```

124 124

125Il gateway registra una riga `network:` all'avvio mentre l'egress solo proxy è attivo.125Il gateway registra una riga `network:` all'avvio mentre l'egress solo tramite proxy è attivo.

126 126

127Ogni riga di seguito è una classe di richiesta in uscita su un gateway con `HTTPS_PROXY` impostato, per impostazione predefinita e mentre l'egress solo proxy è attivo.127Ogni riga di seguito è una classe di richiesta in uscita su un gateway con `HTTPS_PROXY` impostato, per impostazione predefinita e mentre l'egress solo tramite proxy è attivo.

128 128

130| - | - | - |130| - | - | - |

131| `provider: anthropic` upstream, scambio di token Workload Identity Federation, esportazioni `telemetry.forward_to` | Risolto e controllato localmente, quindi `CONNECT` all'indirizzo IP controllato attraverso il proxy. Un collettore di telemetria elencato in `NO_PROXY` viene raggiunto direttamente invece | Nome host consegnato al proxy |131| Upstream `provider: anthropic`, scambio di token Workload Identity Federation, esportazioni `telemetry.forward_to` | Risolto e controllato localmente, quindi `CONNECT` verso l'indirizzo IP controllato attraverso il proxy. Un collettore di telemetria elencato in `NO_PROXY` viene invece raggiunto direttamente | Nome host consegnato al proxy |

132| Scoperta IdP, JWKS, token e userinfo | Diretto a meno che [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy), quindi `CONNECT` all'indirizzo IP controllato | Nome host consegnato al proxy, a meno che `oidc.use_proxy: false` non mantenga un IdP interno diretto |132| Scoperta IdP, JWKS, token e userinfo | Diretto a meno che [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy), quindi `CONNECT` verso l'indirizzo IP controllato | Nome host consegnato al proxy, a meno che `oidc.use_proxy: false` non mantenga diretto un IdP interno |

134 134

135L'egress solo proxy rimane disattivato a meno che l'ambiente del gateway non soddisfi tutti e tre questi condizioni:135L'egress solo tramite proxy rimane disattivato a meno che l'ambiente del gateway non soddisfi tutte e tre queste condizioni:

136 136

137* `HTTPS_PROXY` o `HTTP_PROXY` è impostato.137* `HTTPS_PROXY` o `HTTP_PROXY` è impostato.

138* `NO_PROXY` e `no_proxy` sono vuoti. Se la vostra piattaforma inietta uno di questi nei pod, impostate entrambi a un valore vuoto sul contenitore del gateway. Elencando un collettore di telemetria in `NO_PROXY` mantiene l'egress solo proxy disattivato.138* `NO_PROXY` e `no_proxy` sono vuoti. Se la tua piattaforma inietta una delle due nei pod, imposta entrambe a un valore vuoto sul container del gateway. Elencare un collettore di telemetria in `NO_PROXY` mantiene disattivato l'egress solo tramite proxy.

139* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` non è attivato. Un collettore o IdP sul loopback proprio del pod non può essere combinato con l'egress solo proxy, perché un indirizzo loopback consegnato al proxy sarebbe il proprio dell'host proxy, quindi date a quei servizi un indirizzo che il proxy può raggiungere invece. Per lo stesso motivo il gateway rifiuta i nomi di stile `localhost` completamente mentre l'egress solo proxy è attivo.139* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` non è attivato. Un collettore o un IdP sul loopback del pod stesso non può essere combinato con l'egress solo tramite proxy, perché un indirizzo loopback consegnato al proxy sarebbe quello dell'host del proxy, quindi assegna invece a quei servizi un indirizzo che il proxy può raggiungere. Per lo stesso motivo il gateway rifiuta del tutto i nomi di tipo `localhost` mentre l'egress solo tramite proxy è attivo.

140 140

141Quando una di queste condizioni non è soddisfatta, il gateway registra un avviso all'avvio nominando la variabile che l'ha fermato e mantiene il comportamento predefinito.141Quando una di queste condizioni non è soddisfatta, il gateway registra un avviso all'avvio indicando la variabile che l'ha impedito e mantiene il comportamento predefinito.

142 142

143Una volta che l'egress solo proxy è attivo, consentite ogni destinazione nel proxy, incluso un collettore interno e qualsiasi host configurato per indirizzo IP. Potete ancora mantenere un IdP interno diretto con [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy).143Una volta attivo l'egress solo tramite proxy, consenti nel proxy ogni destinazione, incluso un collettore interno e qualsiasi host configurato per indirizzo IP. Puoi comunque mantenere diretto un IdP interno con [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy).

144 144

145<Warning>145<Warning>

146 Attivate questo solo quando l'allowlist del proxy è almeno altrettanto rigoroso del controllo del gateway stesso. Il proxy deve rifiutare gli endpoint dei metadati cloud come `169.254.169.254` e `metadata.google.internal`, gli indirizzi link-local e il loopback dell'host proxy stesso, e deve rifiutarli per l'indirizzo a cui un nome si risolve, non solo per nome, perché il gateway non cattura più un nome host che si risolve a uno di essi. Un proxy che si connette ovunque gli viene chiesto rimuove la [guardia SSRF](/docs/it/claude-apps-gateway-deploy#threat-model-summary) del gateway per queste richieste.146 Attiva questa opzione solo quando l'allowlist del proxy è rigorosa almeno quanto il controllo del gateway stesso. Il proxy deve rifiutare gli endpoint dei metadati cloud come `169.254.169.254` e `metadata.google.internal`, gli indirizzi link-local e il loopback dell'host del proxy stesso, e deve rifiutarli in base all'indirizzo in cui un nome si risolve, non solo in base al nome, perché il gateway non intercetta più un nome host che si risolve in uno di essi. Un proxy che si connette ovunque gli venga chiesto rimuove la [guardia SSRF](/docs/it/claude-apps-gateway-deploy#threat-model-summary) del gateway per queste richieste.

147</Warning>147</Warning>

148 148

149<h3 id="session">149<h3 id="session">

150 `session`150 `session`

151</h3>151</h3>

152 152

153Il blocco `session` modella i token bearer che il gateway conia dopo l'accesso: il segreto che li firma e quanto a lungo vivono.153Il blocco `session` definisce i token bearer che il gateway emette dopo l'accesso: il segreto che li firma e per quanto tempo restano validi.

154 154

156| - | - | - |156| - | - | - |

157| `jwt_secret` | Sì | Almeno 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. |157| `jwt_secret` | Sì | Almeno 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, anteponi un nuovo segreto, attendi `ttl_hours`, quindi elimina quello vecchio. |

158| `ttl_hours` | No | Durata 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. |158| `ttl_hours` | No | Durata 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 revoca l'accesso più velocemente; una più lunga richiede meno round-trip verso l'IdP. Se il tuo IdP non può emettere token di aggiornamento perché `offline_access` non è disponibile, non c'è aggiornamento silenzioso, quindi aumentalo a `8` o `12` per evitare di rimandare gli sviluppatori all'accesso nel browser ogni ora. |

159 159

160<h3 id="store">160<h3 id="store">

161 `store`161 `store`

162</h3>162</h3>

163 163

164Il blocco `store` punta il gateway al suo database PostgreSQL, che contiene le concessioni dei dispositivi e i contatori dei limiti di velocità.164Il blocco `store` punta il gateway al suo database PostgreSQL, che contiene le concessioni dei dispositivi e i contatori dei rate limit.

165 165

167| - | - | - |167| - | - | - |

168| `postgres_url` | Sì | URL `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 e all'aggiornamento, quindi il ruolo ha bisogno di diritti per creare e alterare le tabelle sullo schema di destinazione. Vedere [Aggiornamenti](/docs/it/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/it/claude-apps-gateway-deploy#postgres). |168| `postgres_url` | Sì | URL `postgres://` o `postgresql://`. Obbligatorio: il punto d'incontro della concessione del dispositivo, dove il callback del browser scrive e la CLI in polling legge, richiede uno stato condiviso tra repliche. Il gateway esegue le proprie migrazioni dello schema all'avvio e all'aggiornamento, quindi il ruolo ha bisogno dei diritti per creare e modificare tabelle sullo schema di destinazione. Consulta [Aggiornamenti](/docs/it/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/it/claude-apps-gateway-deploy#postgres). |

169| `username` | No | Sovrascrive l'utente in `postgres_url` |169| `username` | No | Sovrascrive l'utente in `postgres_url` |

170| `password` | No | Credenziale 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. |170| `password` | No | Credenziale del database. Impostala qui anziché in `postgres_url` in modo che la credenziale rimanga fuori dall'URL. Accetta qualsiasi carattere e ha la precedenza sulle credenziali dell'URL. |

171| `max_connections` | No | Dimensione del pool di connessioni Postgres per replica. Predefinito `5`, che è conservativo e amichevole ai database condivisi. Con i [limiti di spesa](#admin) 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. |171| `max_connections` | No | Dimensione del pool di connessioni Postgres per replica. Predefinito `5`, che è conservativo e adatto ai database condivisi. Con i [limiti di spesa](#admin) abilitati, il percorso critico esegue alcune operazioni per richiesta di inferenza, quindi aumentalo per un database dedicato sotto carico e mantieni repliche × questo valore al di sotto del `max_connections` del database. |

172| `connect_timeout_seconds` | No | Secondi che il gateway attende quando apre una connessione Postgres. Un numero intero da `1` a `60`, predefinito `5`. Aumentatelo se i tentativi di connessione scadono quando una nuova istanza del gateway si avvia. Richiede Claude Code v2.1.274 o successivo sul server del gateway. Le versioni precedenti si rifiutano di avviarsi quando la chiave è impostata. |172| `connect_timeout_seconds` | No | Secondi che il gateway attende quando apre una connessione Postgres. Un numero intero da `1` a `60`, predefinito `5`. Aumentalo se i tentativi di connessione vanno in timeout quando si avvia una nuova istanza del gateway. Richiede Claude Code v2.1.274 o successivo sul server del gateway. Le versioni precedenti si rifiutano di avviarsi quando la chiave è impostata. |

173| `readiness_grace_seconds` | No | Per quanti secondi `/readyz` continua a segnalare lo stato di pronto dopo che Postgres smette di rispondere. Un numero intero da `0` a `3600`, predefinito `0`. Consulta [Comportamento in caso di interruzione](/docs/it/claude-apps-gateway-deploy#outage-behavior) per come scegliere un valore. Richiede Claude Code v2.1.282 o successivo sul server del gateway. Le versioni precedenti si rifiutano di avviarsi quando la chiave è impostata. |

173 174

174Per 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`.175Per lo sviluppo locale, punta `postgres_url` a un container Postgres usa e getta, ad esempio `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.

175 176

176<h3 id="upstreams">177<h3 id="upstreams">

177 `upstreams`178 `upstreams`

179 180

180`upstreams` è un elenco ordinato. Il gateway inoltra l'inferenza al primo upstream che risolve il modello richiesto.181`upstreams` è un elenco ordinato. Il gateway inoltra l'inferenza al primo upstream che risolve il modello richiesto.

181 182

182Su `5xx`, `429`, `401`, `403`, `404` o timeout il gateway esegue il failover al successivo; altri `4xx` no, perché questi errori sono attribuibili alla richiesta piuttosto che all'upstream. Un `401` o `403` significa che la credenziale del gateway stesso non ha funzionato contro quell'upstream. Un `404` significa che quell'upstream non serve il modello richiesto, quindi un upstream successivo nell'elenco può ancora servirlo.183Su `5xx`, `429`, `401`, `403`, `404` o timeout il gateway esegue il failover all'upstream successivo; sugli altri `4xx` no, perché questi errori sono attribuibili alla richiesta anziché all'upstream. Un `401` o `403` significa che la credenziale usata dal gateway verso quell'upstream non ha funzionato. Un `404` significa che quell'upstream non serve il modello richiesto, quindi un upstream successivo nell'elenco può ancora servirlo.

183 184

184Se impostate `forward_user_identity: true` su un upstream, un `429` che restituisce a una richiesta che portava l'email dello sviluppatore non esegue il failover. Vedere [come un rifiuto di limite per utente raggiunge lo sviluppatore](#per-user-identity-headers-for-a-proxy-you-run).185Se imposti `forward_user_identity: true` su un upstream, un `429` che questo restituisce a una richiesta che portava l'email dello sviluppatore non esegue il failover. Consulta [come un rifiuto per limite per utente raggiunge lo sviluppatore](#per-user-identity-headers-for-a-proxy-you-run).

185 186

186Il failover su `404` richiede gateway v2.1.198 o successivo. Le versioni precedenti hanno restituito il primo `404` al client anche quando un upstream successivo nell'elenco serviva il modello.187Il failover su `404` richiede il gateway v2.1.198 o successivo. Le versioni precedenti restituivano il primo `404` al client anche quando un upstream successivo nell'elenco serviva il modello.

187 188

188Più upstream dello stesso provider devono impostare un `name:` distinto.189Più upstream dello stesso provider devono impostare un `name:` distinto.

189 190

190I client Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform e Microsoft 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](#anthropic-api).191I client Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud e Microsoft Foundry vengono creati 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 vengono letti all'avvio; consulta [API Anthropic](#anthropic-api).

191 192

192<h4 id="upstream-error-messages">193<h4 id="upstream-error-messages">

193 Messaggi di errore dell'upstream194 Messaggi di errore dell'upstream

194</h4>195</h4>

195 196

196Il gateway restituisce la risposta di errore di un upstream o il suo proprio `502`, a seconda di come gli upstream hanno risposto:197Il gateway restituisce la risposta di errore di un upstream o il proprio `502`, a seconda di come hanno risposto gli upstream:

197 198

198* **Un upstream ha restituito uno stato su cui il gateway non [esegue il failover](#multiple-upstreams)**: quella risposta dell'upstream. Il gateway non prova ulteriori upstream.199* **Un upstream ha restituito uno stato su cui il gateway non [esegue il failover](#multiple-upstreams)**: la risposta di quell'upstream. Il gateway non prova altri upstream.

199* **Ogni upstream che il gateway ha provato ha fallito in un modo su cui [esegue il failover](#multiple-upstreams)**: l'ultimo `429`. Quando nessuno ha restituito un `429`, il gateway preferisce, in ordine, l'ultimo `401` o `403`, l'ultimo `404` e l'ultimo `501`. Quando nessuno ha restituito nessuno di quelli, il proprio `502` del gateway, `all upstreams failed (N attempted)`, dove N conta ogni voce in [`upstreams`](#upstreams), incluse le voci che il gateway ha saltato perché non servono il modello richiesto.200* **Ogni upstream provato dal gateway ha fallito in un modo su cui [esegue il failover](#multiple-upstreams)**: l'ultimo `429`. Quando nessuno ha restituito un `429`, il gateway preferisce, nell'ordine, l'ultimo `401` o `403`, l'ultimo `404` e l'ultimo `501`. Quando nessuno ha restituito nessuno di questi, il `502` del gateway stesso, `all upstreams failed (N attempted)`, dove N conta ogni voce in [`upstreams`](#upstreams), incluse le voci che il gateway ha saltato perché non servono il modello richiesto.

200 201

201Quando il gateway restituisce la risposta di un upstream, mantiene il codice di stato dell'upstream. Se mantiene il messaggio dell'upstream dipende dal provider. Il corpo di errore di un upstream API Anthropic raggiunge lo sviluppatore invariato.202Quando il gateway restituisce la risposta di un upstream, mantiene il codice di stato dell'upstream. Se mantenga anche il messaggio dell'upstream dipende dal provider. Il corpo di errore di un upstream API Anthropic raggiunge lo sviluppatore invariato.

202 203

203Gli upstream Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform e Microsoft Foundry possono nominare i vostri ID account, ARN di ruolo e ID di progetto nel loro testo di errore. Il gateway registra quel testo completo nel [log operativo](/docs/it/claude-apps-gateway-deploy#logs). Ciò che lo sviluppatore vede da questi upstream dipende dal rifiuto:204Gli upstream Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud e Microsoft Foundry possono indicare i tuoi ID account, ARN di ruolo e ID progetto nel loro testo di errore. Il gateway registra quel testo completo nel [log operativo](/docs/it/claude-apps-gateway-deploy#logs). Ciò che lo sviluppatore vede da questi upstream dipende dal rifiuto:

204 205

205* `400` o `413` nell'envelope di errore standard di Anthropic: il messaggio dell'upstream stesso, come `prompt is too long`. Claude Platform on AWS, Agent Platform e Microsoft Foundry restituiscono questo envelope per i rifiuti dell'API del modello.206* `400` o `413` nell'envelope di errore standard di Anthropic: il messaggio dell'upstream stesso, come `prompt is too long`. Claude Platform on AWS, Agent Platform e Microsoft Foundry restituiscono questo envelope per i rifiuti dell'API del modello.

206* `400` o `413` nella forma propria del provider: un token `capability_rejected:`. Quando il gateway non può classificare il rifiuto, `upstream rejected the request` su un `400` o `request too large for this upstream` su un `413`.207* `400` o `413` nel formato proprio del provider: un token `capability_rejected:`. Quando il gateway non riesce a classificare il rifiuto, `upstream rejected the request` su un `400` o `request too large for this upstream` su un `413`.

207* Qualsiasi altro stato: copia generica per stato, come `upstream rate limit exceeded` su un `429`.208* Qualsiasi altro stato: un testo generico per stato, come `upstream rate limit exceeded` su un `429`.

208 209

209Ad esempio, il gateway sostituisce `Input is too long for requested model.` di Amazon Bedrock con `capability_rejected: prompt_too_long`. Claude Code [compatta automaticamente](/docs/it/errors#prompt-is-too-long) su quel token, come fa su `prompt is too long`.210Ad esempio, il gateway sostituisce `Input is too long for requested model.` di Amazon Bedrock con `capability_rejected: prompt_too_long`. Claude Code [compatta automaticamente](/docs/it/errors#prompt-is-too-long) su quel token, come fa su `prompt is too long`.

210 211

211Mantenere il messaggio `400` o `413` di un upstream cloud o sostituirlo con un token `capability_rejected:` richiede gateway v2.1.233 o successivo.212Mantenere il messaggio `400` o `413` di un upstream cloud, o sostituirlo con un token `capability_rejected:`, richiede il gateway v2.1.233 o successivo.

212 213

213<h4 id="anthropic-api">214<h4 id="anthropic-api">

214 API Anthropic215 API Anthropic

215</h4>216</h4>

216 217

217L'upstream Anthropic minimo è una chiave API dalla [Console Claude](https://platform.claude.com):218L'upstream Anthropic minimo è una chiave API dalla [Claude Console](https://platform.claude.com):

218 219

219```yaml theme={null}220```yaml theme={null}

220upstreams:221upstreams:

228 229

229Le due forme di credenziale differiscono nell'header che inviano:230Le due forme di credenziale differiscono nell'header che inviano:

230 231

231* **`api_key`**: invia `x-api-key`. Ruotatela nella Console Claude e aggiornate la variabile env.232* **`api_key`**: invia `x-api-key`. Ruotala nella Claude Console e aggiorna la variabile d'ambiente.

232* **`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.233* **`oauth_token`**: invia `Authorization: Bearer`. Usa la forma bearer quando la tua organizzazione emette token a breve durata invece di chiavi API a lunga durata. Il bearer viene letto una volta all'avvio, quindi aggiornalo rimontando il segreto e riavviando.

233 234

234Invece di una chiave statica o un bearer, potete usare Workload Identity Federation. Create una regola di federazione seguendo la [guida Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/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.235Invece di una chiave statica o di un bearer, puoi usare Workload Identity Federation. Crea una regola di federazione seguendo la [guida a Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation), quindi monta come file il JWT OIDC del tuo workload, ad esempio un token dell'account di servizio proiettato di Kubernetes o l'id-token di una piattaforma CI. Il gateway scambia il JWT con un bearer a breve durata e lo aggiorna automaticamente. Il file del token viene riletto a ogni scambio, quindi i token proiettati ruotati vengono acquisiti senza un riavvio.

235 236

236```yaml theme={null}237```yaml theme={null}

237upstreams:238upstreams:

247<a id="per-user-identity-headers-for-a-proxy-you-run" />248<a id="per-user-identity-headers-for-a-proxy-you-run" />

248 249

249<h5 id="per-user-identity-headers-for-a-proxy-you-run">250<h5 id="per-user-identity-headers-for-a-proxy-you-run">

250 Intestazioni di identità per utente per un proxy che gestite251 Header di identità per utente per un proxy che gestisci

251</h5>252</h5>

252 253

253Potete puntare l'`base_url` di un upstream `provider: anthropic` a un proxy che gestite invece che all'API Anthropic. Per dire a quel proxy quale sviluppatore ha inviato ogni richiesta, impostate `forward_user_identity: true` su quell'upstream. Il proxy può quindi attribuire la spesa per sviluppatore. Richiede un gateway che esegue Claude Code v2.1.233 o successivo.254Puoi puntare il `base_url` di un upstream `provider: anthropic` a un proxy che gestisci invece che all'API Anthropic. Per indicare a quel proxy quale sviluppatore ha inviato ogni richiesta, imposta `forward_user_identity: true` su quell'upstream. Il proxy può quindi attribuire la spesa per sviluppatore. Richiede un gateway che esegue Claude Code v2.1.233 o successivo.

254 255

255Ad esempio, per un proxy su `upstream-gateway.internal.example.com`:256Ad esempio, per un proxy su `upstream-gateway.internal.example.com`:

256 257

263 forward_user_identity: true # default false264 forward_user_identity: true # default false

264```265```

265 266

266Il gateway aggiunge questi intestazioni a ogni richiesta che inoltra a quell'upstream.267Il gateway aggiunge questi header a ogni richiesta che inoltra a quell'upstream.

267 268

268| Intestazione | Valore |269| Header | Valore |

269| - | - |270| - | - |

273 274

274Quando il token IdP non porta email, il gateway invia solo `x-claude-gateway-user-id` e omette i due intestazioni email. Se il vostro IdP mette l'email in un claim diverso, impostate [`oidc.email_claim`](#oidc) a quel claim.275Quando il token IdP non contiene un'email, il gateway invia solo `x-claude-gateway-user-id` e omette i due header email. Se il tuo IdP inserisce l'email in un claim diverso, imposta [`oidc.email_claim`](#oidc) su quel claim.

275 276

276Quando il vostro proxy risponde `429` a una richiesta che portava l'email dello sviluppatore, il gateway restituisce quella risposta allo sviluppatore così com'è invece di eseguire il failover al successivo upstream, quindi il vostro budget per utente del proxy o il limite di velocità tiene. Le altre risposte del proxy seguono le [regole di failover](#upstreams) ordinarie. Se il token IdP di uno sviluppatore non porta email, il gateway inoltra le sue richieste senza gli intestazioni email, quindi un `429` a una di quelle richieste conta come capacità upstream e esegue il failover. Prima della v2.1.267 sul server del gateway, ogni `429` eseguiva il failover.277Quando il tuo proxy risponde `429` a una richiesta che portava l'email dello sviluppatore, il gateway restituisce quella risposta allo sviluppatore così com'è invece di eseguire il failover all'upstream successivo, in modo che il budget per utente o il rate limit del tuo proxy vengano rispettati. Le altre risposte del proxy seguono le normali [regole di failover](#upstreams). Se il token IdP di uno sviluppatore non contiene un'email, il gateway inoltra le sue richieste senza gli header email, quindi un `429` a una di quelle richieste conta come capacità dell'upstream ed esegue il failover. Prima della v2.1.267 sul server del gateway, ogni `429` eseguiva il failover.

277 278

278Impostate `forward_user_identity` solo su un upstream il cui `base_url` è un proxy che gestite. Il gateway invia email degli sviluppatori a qualsiasi server che `base_url` nomina. Se `base_url` è l'API Anthropic, che è il predefinito, il gateway si rifiuta di avviarsi.279Imposta `forward_user_identity` solo su un upstream il cui `base_url` è un proxy che gestisci. Il gateway invia le email degli sviluppatori a qualunque server indicato da quel `base_url`. Se il `base_url` è l'API Anthropic, che è il valore predefinito, il gateway si rifiuta di avviarsi.

279 280

280<h4 id="amazon-bedrock">281<h4 id="amazon-bedrock">

281 Amazon Bedrock282 Amazon Bedrock

282</h4>283</h4>

283 284

284Per la distribuzione Bedrock lato client che il gateway sostituisce o fronteggia, vedere [Claude Code su Amazon Bedrock](/docs/it/amazon-bedrock). L'upstream lato gateway:285Per la distribuzione di Amazon Bedrock lato client che il gateway sostituisce o a cui fa da front-end, consulta [Claude Code su Amazon Bedrock](/docs/it/amazon-bedrock). L'upstream lato gateway:

285 286

286```yaml theme={null}287```yaml theme={null}

287upstreams:288upstreams:

300 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com301 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

301```302```

302 303

303Un 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.304Un blocco `auth` vuoto usa la catena di credenziali predefinita dell'AWS SDK: variabili d'ambiente, `~/.aws/credentials`, ruolo di attività ECS, metadati dell'istanza EC2 o IRSA su EKS. In produzione, assegna al pod del gateway un ruolo IAM invece di incorporare chiavi statiche in un'immagine del container.

304 305

305Le credenziali esplicite devono essere complete: il gateway non riesce all'avvio quando `aws_access_key_id` e `aws_secret_access_key` non sono impostati insieme, o quando `aws_session_token` è impostato senza di loro. Prima della v2.1.207, un blocco `auth:` parziale ha superato la convalida.306Le credenziali esplicite devono essere complete: il gateway fallisce all'avvio quando `aws_access_key_id` e `aws_secret_access_key` non sono impostati insieme, o quando `aws_session_token` è impostato senza di loro. Prima della v2.1.207, un blocco `auth:` parziale superava la convalida.

306 307

307| Configurazione | Come |308| Configurazione | Come |

308| - | - |309| - | - |

309| Autorizzazioni IAM | Concedete 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.*`. Concedete anche `bedrock:CountTokens` sugli ARN del modello di fondazione. Il gateway lo usa, senza costi, per contare i token di input di una richiesta che il client ha abbandonato, quindi i [limiti di spesa](#admin) rimangono accurati. Senza di esso il gateway ricade a una richiesta Bedrock di un token per quel conteggio. |310| Permessi IAM | Concedi al principal del gateway `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` sia sugli ARN dei profili di inferenza sia sugli ARN dei modelli di fondazione sottostanti. Per il catalogo integrato nelle regioni US: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` e `arn:aws:bedrock:*::foundation-model/anthropic.*`. Concedi anche `bedrock:CountTokens` sugli ARN dei modelli di fondazione. Il gateway lo usa, senza costi, per contare i token di input di una richiesta abbandonata dal client, in modo che i [limiti di spesa](#admin) rimangano accurati. Senza di esso il gateway usa come fallback una richiesta Bedrock da un token per quel conteggio. |

310| Accesso al modello | Amazon Bedrock abilita l'accesso al modello per impostazione predefinita nelle regioni commerciali. Il gate a livello di account rimanente è quello di Anthropic: se nessuno nel vostro account AWS l'ha inviato, aprite la console Amazon Bedrock, selezionate un modello Anthropic dal catalogo dei modelli e completate il modulo. Vedere [Inviare i dettagli del caso d'uso](/docs/it/amazon-bedrock#1-submit-use-case-details) per il modulo AWS Organizations e le autorizzazioni di cui il mittente ha bisogno. |311| Accesso al modello | Amazon Bedrock abilita l'accesso ai modelli per impostazione predefinita nelle regioni commerciali. L'unico vincolo rimanente a livello di account è il modulo una tantum di Anthropic sul caso d'uso: se nessuno nel tuo account AWS l'ha inviato, apri la console di Amazon Bedrock, seleziona un modello Anthropic dal catalogo dei modelli e completa il modulo. Consulta [Inviare i dettagli del caso d'uso](/docs/it/amazon-bedrock#1-submit-use-case-details) per il modulo di AWS Organizations e i permessi di cui ha bisogno chi lo invia. |

311| 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. |312| EKS (IRSA) | Crea un ruolo IAM con la policy sopra e una trust policy per il provider OIDC del tuo cluster limitata all'account di servizio del gateway. Annota l'account di servizio con `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` lo rileva. |

312| ECS / EC2 | Allegate il ruolo IAM alla definizione dell'attività o al profilo dell'istanza. `auth: {}` lo raccoglie. |313| ECS / EC2 | Associa il ruolo IAM alla definizione dell'attività o al profilo dell'istanza. `auth: {}` lo rileva. |

313| Altrove | Passate 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}` |314| Altrove | Passa le credenziali tramite le variabili d'ambiente `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, oppure impostale esplicitamente in `auth:` con l'espansione `${VAR}` |

314| Regione | `region:` è 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:`](#models) con gli ID per upstream corretti. |315| Regione | `region:` è la regione dell'endpoint API. I profili di inferenza cross-region instradano all'interno dell'area geografica (US, EU, APAC) indipendentemente da quale scegli. Per le regioni non US o gli ARN di throughput provisioned, aggiungi un blocco [`models:`](#models) con gli ID per upstream corretti. |

316

317<h5 id="apply-an-amazon-bedrock-guardrail">

318 Applicare un guardrail di Amazon Bedrock

319</h5>

320

321Per applicare un guardrail di Amazon Bedrock a ogni richiesta di inferenza che il gateway invia tramite un upstream Bedrock, aggiungi un blocco `guardrail` a quell'upstream. Richiede Claude Code v2.1.281 o successivo sul server del gateway.

322

323```yaml theme={null}

324upstreams:

325 - provider: bedrock

326 region: us-east-1

327 auth: {}

328 guardrail:

329 id: gr-abc123 # guardrail ID or full ARN

330 version: "1" # a published version number, or DRAFT

331 # keep the quotes: a bare 1 fails at boot

332```

333

334<Warning>

335 Il gateway non supporta i tag di input dei guardrail. Non aggiunge tag di contenuto guard ai prompt, quindi un filtro del guardrail che Amazon Bedrock applica solo all'input con tag non viene eseguito sul traffico che passa per il gateway. Per sapere quali filtri dipendono dai tag di input, consulta [input tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) nella documentazione di Amazon Bedrock.

336</Warning>

337

338Concedi anche `bedrock:ApplyGuardrail` sul guardrail al principal che firma le richieste di questo upstream: il principal AWS del gateway oppure, con [`assume_role`](#bedrock-in-another-aws-account), il ruolo indicato in `role_arn`.

339

340Imposta `guardrail` su ogni upstream `bedrock` o su nessuno. Il gateway si rifiuta di avviarsi con una configurazione mista, perché altrimenti il [failover](#multiple-upstreams) potrebbe inviare una richiesta a un upstream Bedrock privo di guardrail.

341

342Il guardrail copre solo gli upstream Bedrock. Se elenchi un altro provider in `upstreams`, il gateway invia le richieste a quel provider senza il guardrail.

343

344Quando una richiesta `/v1/messages` il cui corpo contiene un campo `amazon-bedrock-*`, come `amazon-bedrock-guardrailConfig`, raggiunge un upstream Bedrock con `guardrail` impostato, il gateway risponde 400 invece di inoltrarla.

345

346<a id="bedrock-in-another-aws-account" />

347

348<h5 id="bedrock-in-another-aws-account">

349 Bedrock in un altro account AWS

350</h5>

351

352Imposta `assume_role` su un upstream Bedrock e il gateway userà la propria identità AWS solo per chiamare `sts:AssumeRole` su un ruolo che indichi, che può trovarsi in un account AWS diverso da quello del gateway. Ogni richiesta Bedrock da quell'upstream viene firmata con le credenziali di un'ora restituite da STS, quindi nessuna chiave di accesso a lunga durata attraversa gli account.

353

354Richiede un gateway che esegue Claude Code v2.1.281 o successivo. Un gateway precedente si rifiuta di avviarsi quando trova la chiave.

355

356```yaml theme={null}

357upstreams:

358 - name: bedrock-isolated

359 provider: bedrock

360 region: us-east-1

361 auth: {} # the gateway's own role: it only calls STS

362 assume_role:

363 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock

364 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # when the role's trust policy requires one

365```

366

367Il blocco `assume_role` accetta tre chiavi:

368

369| Chiave | Significato |

370| - | - |

371| `role_arn` | Il ruolo IAM che il gateway assume, come ARN `arn:aws:iam::` o `arn:aws-us-gov:iam::`. Assegnagli i [permessi Bedrock](#amazon-bedrock) di cui questo upstream ha bisogno, `bedrock:CountTokens` incluso, più `bedrock:ApplyGuardrail` quando l'upstream imposta `guardrail`. |

372| `external_id` | Facoltativo. Inviato come external ID in ogni chiamata `sts:AssumeRole`. Impostalo quando la trust policy del ruolo lo richiede, e mettilo tra virgolette se è composto solo da cifre. |

373| `session_name` | Facoltativo. `email` o `sub` assegna a ogni sviluppatore la propria sessione: consulta [Attribuzione dei costi AWS per sviluppatore](#per-developer-aws-cost-attribution). Se non impostato, ogni richiesta usa un'unica sessione denominata `claude-apps-gateway`. |

374

375La trust policy del ruolo indica il principal del gateway stesso, come il suo ruolo IRSA o il ruolo di attività ECS. Quel principal ha bisogno di `sts:AssumeRole` sul ruolo e di nessun permesso Bedrock proprio. Elimina la `Condition` se non imposti `external_id`.

376

377```json theme={null}

378{

379 "Version": "2012-10-17",

380 "Statement": [{

381 "Effect": "Allow",

382 "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },

383 "Action": "sts:AssumeRole",

384 "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }

385 }]

386}

387```

388

389* Se STS rifiuta o non è raggiungibile, il gateway non invia la richiesta con le credenziali proprie dell'upstream. Registra l'errore STS con ciò che occorre verificare, quindi prova l'upstream successivo che hai elencato. [Messaggi di errore dell'upstream](#upstream-error-messages) descrive ciò che riceve il client quando nessun upstream ha successo. Un upstream successivo senza `assume_role` servirebbe la richiesta con le proprie credenziali, quindi elencane uno solo se è ciò che desideri.

390* Il gateway chiama l'endpoint STS regionale `sts.<region>.amazonaws.com`, che la sua rete deve poter raggiungere. Per l'endpoint FIPS, imposta `AWS_USE_FIPS_ENDPOINT=true` nell'ambiente del gateway anziché `use_fips_endpoint` in un file di configurazione AWS.

391* `assume_role` si applica solo a `provider: bedrock` e richiede credenziali di origine SigV4: il gateway si rifiuta di avviarsi quando è impostato insieme a `aws_bearer_token`.

392* Ogni sviluppatore ammesso dal gateway può usare questo upstream; [`managed`](#managed) stabilisce quali sviluppatori possono usare quali modelli. Per evitare che un modello servito tramite il ruolo venga servito anche da un altro account, assegnagli un id personalizzato la cui mappa `upstream_model` contenga solo il nome di questo upstream. Per un id di questo tipo il gateway salta ogni altro upstream, quindi né la richiesta né il conteggio dei token per una richiesta interrotta possono eseguire il failover su un altro account. I nomi dei modelli integrati vengono comunque provati su ogni upstream in ordine, questo incluso, e una richiesta che lo raggiunge viene firmata con lo stesso ruolo, quindi elenca questo upstream per ultimo a meno che anche il suo account non debba servirli.

393

394Questo esempio assegna a un modello un id personalizzato che solo l'upstream isolato serve:

395

396```yaml theme={null}

397models:

398 - id: claude-opus-restricted # a custom id, not a built-in model name

399 upstream_model:

400 bedrock-isolated: us.anthropic.claude-opus-4-8 # the only upstream that serves it

401```

402

403<a id="per-developer-aws-cost-attribution" />

404

405<h5 id="per-developer-aws-cost-attribution">

406 Attribuzione dei costi AWS per sviluppatore

407</h5>

408

409Per impostazione predefinita il gateway firma ogni richiesta Bedrock con un'unica credenziale, quindi AWS vede le richieste di tutti gli sviluppatori sotto un unico principal IAM. Aggiungi `session_name: email` ad [`assume_role`](#bedrock-in-another-aws-account) e il gateway chiamerà `sts:AssumeRole` una volta per sviluppatore ogni ora, con il nome della sessione impostato sull'email di quello sviluppatore, e firmerà le sue richieste con le credenziali restituite, in modo che le richieste di ogni sviluppatore raggiungano AWS sotto la propria sessione di ruolo assunto. Il ruolo può trovarsi nell'account stesso del gateway.

410

411Richiede un gateway che esegue Claude Code v2.1.281 o successivo. [Attribuzione dei costi su AWS](/docs/it/claude-apps-gateway-on-aws#cost-attribution) descrive il ruolo IAM e dove la fatturazione AWS mostra le sessioni.

412

413```yaml theme={null}

414upstreams:

415 - provider: bedrock

416 region: us-east-1

417 auth: {} # the gateway's own role: it only calls STS

418 assume_role:

419 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user

420 session_name: email # or sub

421```

422

423`session_name` seleziona quale claim verificato diventa il `RoleSessionName` di AWS: `email` o `sub`. Il gateway scrive qualsiasi carattere diverso da lettere ASCII, cifre e `_+,.@-` come `=XX` esadecimale per ogni byte UTF-8, e abbrevia un risultato più lungo di 64 caratteri in un prefisso più un hash, in modo che il nome della sessione di ogni sviluppatore rimanga valido e univoco. Una richiesta da uno sviluppatore il cui token non contiene il claim non viene inviata tramite questo upstream, e il log operativo indica di passare a `sub` o di impostare [`oidc.email_claim`](#oidc).

424

425Uno sviluppatore attivo costa una chiamata STS all'ora per replica del gateway, e le prime richieste simultanee condividono un'unica chiamata.

426

427Il gateway effettua anche una chiamata propria su questo ruolo: il conteggio dei token per una richiesta abbandonata dal client, in modo che i [limiti di spesa](/docs/it/claude-apps-gateway-spend-limits) rimangano accurati. Quel conteggio e la relativa [richiesta di fallback da un token](#amazon-bedrock) sono firmati dalla sessione condivisa `claude-apps-gateway`, quindi AWS attribuisce il fallback a `claude-apps-gateway` anziché allo sviluppatore.

428

429Per un'attribuzione rigorosa per sviluppatore, imposta `assume_role` con `session_name` su ogni upstream Bedrock che elenchi. Un upstream senza di esso firma le richieste che serve con le proprie credenziali.

315 430

316<h4 id="claude-platform-on-aws">431<h4 id="claude-platform-on-aws">

317 Claude Platform on AWS432 Claude Platform on AWS

318</h4>433</h4>

319 434

320Claude Platform on AWS serve l'API Anthropic di prima parte su infrastruttura AWS su `aws-external-anthropic.<region>.api.aws`. Utilizza ID modello di prima parte, onora gli header `anthropic-beta` come inviati e serve `count_tokens`, quindi nessuna della traduzione specifica di Bedrock si applica. Il provider `anthropicAws` richiede Claude Code v2.1.198 o successivo; le versioni precedenti del gateway lo rifiutano all'avvio.435Claude Platform on AWS serve l'API Anthropic di prima parte su infrastruttura AWS all'indirizzo `aws-external-anthropic.<region>.api.aws`. Utilizza ID modello di prima parte, rispetta gli header `anthropic-beta` così come inviati e serve `count_tokens`, quindi non si applica nessuna delle traduzioni specifiche di Bedrock. Il provider `anthropicAws` richiede Claude Code v2.1.198 o successivo; le versioni precedenti del gateway lo rifiutano all'avvio.

321 436

322Per la distribuzione lato client della stessa piattaforma, vedere [Claude Code su Claude Platform on AWS](/docs/it/claude-platform-on-aws). L'upstream lato gateway:437Per la distribuzione lato client della stessa piattaforma, consulta [Claude Code su Claude Platform on AWS](/docs/it/claude-platform-on-aws). L'upstream lato gateway:

323 438

324```yaml theme={null}439```yaml theme={null}

325upstreams:440upstreams:

338 # base_url: https://aws-external-anthropic.us-east-1.api.aws453 # base_url: https://aws-external-anthropic.us-east-1.api.aws

339```454```

340 455

341La piattaforma viene eseguita in un account AWS separato da Amazon Bedrock e firma le richieste SigV4 per il suo nome di servizio, `aws-external-anthropic`, quindi un ruolo IAM limitato a Bedrock non lo autorizza. Una chiave API in `auth.api_key` ha la precedenza quando le credenziali SigV4 sono anche impostate. Un blocco `auth` vuoto usa la catena di credenziali predefinita dell'AWS SDK, la stessa catena che l'upstream [Amazon Bedrock](#amazon-bedrock) utilizza.456La piattaforma viene eseguita in un account AWS separato da Amazon Bedrock e firma le richieste SigV4 per il proprio nome di servizio, `aws-external-anthropic`, quindi un ruolo IAM limitato a Bedrock non la autorizza. Una chiave API in `auth.api_key` ha la precedenza quando sono impostate anche le credenziali SigV4. Un blocco `auth` vuoto usa la catena di credenziali predefinita dell'AWS SDK, la stessa catena usata dall'upstream [Amazon Bedrock](#amazon-bedrock).

342 457

344| - | - | - |459| - | - | - |

345| `region` | Sì | Regione AWS, lettere minuscole, cifre e trattini. Il gateway deriva l'endpoint da essa come `https://aws-external-anthropic.<region>.api.aws`. |460| `region` | Sì | Regione AWS, lettere minuscole, cifre e trattini. Il gateway ne deriva l'endpoint come `https://aws-external-anthropic.<region>.api.aws`. |

346| `workspace_id` | Sì | Inviato come header su ogni richiesta; la piattaforma lo richiede |461| `workspace_id` | Sì | Inviato come header in ogni richiesta; la piattaforma lo richiede |

347| `auth.api_key` | No | Chiave API per la piattaforma, inviata come `x-api-key`. Non un token bearer: le due modalità di autenticazione sono una chiave API o SigV4. |462| `auth.api_key` | No | Chiave API per la piattaforma, inviata come `x-api-key`. Non è un token bearer: le due modalità di autenticazione sono una chiave API o SigV4. |

348| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | No | Credenziali SigV4 esplicite. L'impostazione di una senza l'altra non riesce all'avvio. `auth.aws_session_token` è accettato insieme a loro. |463| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | No | Credenziali SigV4 esplicite. Impostarne una senza l'altra causa un errore all'avvio. `auth.aws_session_token` è accettato insieme a esse. |

349| `base_url` | No | Override dell'endpoint derivato |464| `base_url` | No | Override dell'endpoint derivato |

350 465

351Poiché la piattaforma risolve ID modello di prima parte, il catalogo integrato instrada ad essa senza un blocco [`models:`](#models). Quando curate un elenco `models:`, chiave l'entry `anthropicAws:` con l'ID di prima parte.466Poiché la piattaforma risolve ID modello di prima parte, il catalogo integrato la instrada senza un blocco [`models:`](#models). Quando curi un elenco `models:`, usa come chiave della voce `anthropicAws:` con l'ID di prima parte.

352 467

353<h4 id="google-cloud-agent-platform">468<h4 id="google-cloud-agent-platform">

354 Google Cloud Agent Platform469 Google Cloud Agent Platform

355</h4>470</h4>

356 471

357Per la configurazione equivalente lato client, vedere [Claude Code su Google Cloud](/docs/it/google-vertex-ai). L'upstream lato gateway:472Per la configurazione equivalente lato client, consulta [Claude Code su Google Cloud](/docs/it/google-vertex-ai). L'upstream lato gateway:

358 473

359```yaml theme={null}474```yaml theme={null}

360upstreams:475upstreams:

368 # base_url: https://us-east5-aiplatform.p.googleapis.com483 # base_url: https://us-east5-aiplatform.p.googleapis.com

369```484```

370 485

371Un 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.486Un blocco `auth` vuoto usa le 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; usa Workload Identity o associa un account di servizio all'istanza GCE o Cloud Run.

372 487

373Impostate `region: global` per usare l'[endpoint globale di Agent Platform](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) 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.488Imposta `region: global` per usare l'[endpoint globale di Agent Platform di Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) invece di uno regionale. Google instrada quindi ogni richiesta a una regione disponibile, così non devi tenere traccia della disponibilità dei modelli per regione. Impostare una regione specifica vincola ogni richiesta a quella regione.

374 489

375| Configurazione | Come |490| Configurazione | Come |

376| - | - |491| - | - |

377| Autorizzazioni IAM | Concedete 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`). |492| Permessi IAM | Concedi all'account di servizio del gateway `roles/aiplatform.user` sul progetto, o un ruolo personalizzato con `aiplatform.endpoints.predict`. Abilita l'API di Agent Platform di Google Cloud (`aiplatform.googleapis.com`). |

378| Accesso al modello | In Model Garden, abilitate i modelli Claude per il vostro progetto. Pubblicano in regioni specifiche; controllate la scheda del modello per le regioni supportate. |493| Accesso al modello | In Model Garden, abilita i modelli Claude per il tuo progetto. Vengono pubblicati in regioni specifiche; controlla la scheda del modello per le regioni supportate. |

379| 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. |494| GKE (Workload Identity) | Associa un account di servizio GCP all'account di servizio Kubernetes del gateway e annota il KSA con `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` lo rileva. |

380| Cloud Run / GCE | Impostate l'account di servizio del servizio su uno con `roles/aiplatform.user`. `auth: {}` lo raccoglie. |495| Cloud Run / GCE | Imposta come account di servizio del servizio uno con `roles/aiplatform.user`. `auth: {}` lo rileva. |

381| Altrove | `auth: { 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:…}`. |496| Altrove | `auth: { service_account_json: /secrets/sa.json }`, il percorso di un file di chiave JSON montato come segreto. Il campo accetta un percorso di file, non il contenuto della chiave, quindi non è coinvolta alcuna espansione `${file:…}`. |

382 497

383<h4 id="microsoft-foundry">498<h4 id="microsoft-foundry">

384 Microsoft Foundry499 Microsoft Foundry

385</h4>500</h4>

386 501

387Per la distribuzione Foundry lato client, vedere [Claude Code su Microsoft Foundry](/docs/it/microsoft-foundry). L'upstream lato gateway:502Per la distribuzione di Microsoft Foundry lato client, consulta [Claude Code su Microsoft Foundry](/docs/it/microsoft-foundry). L'upstream lato gateway:

388 503

389```yaml theme={null}504```yaml theme={null}

390upstreams:505upstreams:

396 # api_key: ${FOUNDRY_API_KEY}511 # api_key: ${FOUNDRY_API_KEY}

397```512```

398 513

399`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.514`use_azure_ad: true` si risolve tramite `DefaultAzureCredential`: Managed Identity su AKS, ACI o App Service; la Azure CLI; o le credenziali d'ambiente. Le chiavi API funzionano ma valgono per l'intero progetto e non ruotano automaticamente. L'endpoint di Microsoft Foundry è derivato da `resource:`; imposta il `base_url` facoltativo per sovrascriverlo per cloud sovrani come Azure Government.

400 515

401| Configurazione | Come |516| Configurazione | Come |

402| - | - |517| - | - |

404| Distribuzioni | Foundry usa nomi di distribuzione scelti dall'amministratore, non ID di modello canonici. Aggiungete un blocco [`models:`](#models) che mappa ogni ID canonico al vostro nome di distribuzione. |519| Deployment | Microsoft Foundry usa nomi di deployment scelti dall'amministratore, non ID modello canonici. Aggiungi un blocco [`models:`](#models) che mappa ogni ID canonico al nome del tuo deployment. |

405| 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`. |520| AKS (workload identity) | Federa una User-Assigned Managed Identity con l'emittente OIDC del cluster e associala all'account di servizio del gateway. `use_azure_ad: true` la rileva tramite `WorkloadIdentityCredential`. |

406| ACI / App Service | Abilitate l'identità gestita assegnata dal sistema o assegnata dall'utente sulla risorsa. `use_azure_ad: true` lo raccoglie. |521| ACI / App Service | Abilita l'identità gestita assegnata dal sistema o dall'utente sulla risorsa. `use_azure_ad: true` la rileva. |

407| Altrove | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Quotate `${…}` dentro `{ }`. |522| Altrove | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Metti tra virgolette `${…}` dentro `{ }`. |

408 523

409<h4 id="static-headers-on-upstream-requests">524<h4 id="static-headers-on-upstream-requests">

410 Intestazioni statiche sulle richieste upstream525 Header statici sulle richieste upstream

411</h4>526</h4>

412 527

413Per aggiungere intestazioni fisse alle richieste che il gateway invia a un upstream, impostate `headers:` su quell'upstream. Usatelo quando un proxy che gestite davanti al provider instrada o attribuisce il traffico per un intestazione.528Per aggiungere header fissi alle richieste che il gateway invia a un upstream, imposta `headers:` su quell'upstream. Usalo quando un proxy che gestisci davanti al provider instrada o attribuisce il traffico in base a un header.

414 529

415`headers:` richiede Claude Code v2.1.277 o successivo sul server del gateway. Un gateway precedente si rifiuta di avviarsi quando trova la chiave. Aggiornate ogni replica prima di aggiungere la chiave e rimuovete la chiave prima di eseguire il rollback a una versione precedente.530`headers:` richiede Claude Code v2.1.277 o successivo sul server del gateway. Un gateway precedente si rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere la chiave e rimuovi la chiave prima di eseguire il rollback a una versione precedente.

416 531

417Gli intestazioni vanno al server che `base_url` nomina, o all'endpoint proprio del provider quando `base_url` non è impostato. Il provider li riceve anche a meno che il vostro proxy non li rimuova.532Gli header vanno al server indicato da `base_url`, o all'endpoint proprio del provider quando `base_url` non è impostato. Anche il provider li riceve, a meno che il tuo proxy non li rimuova.

418 533

419Questo esempio raggiunge un upstream `provider: vertex` attraverso un proxy su `upstream-proxy.internal.example.com`. Imposta l'intestazione `x-source` che il proxy legge e invia un token dalla variabile di ambiente `PROXY_TOKEN` come `x-proxy-token`:534Questo esempio raggiunge un upstream `provider: vertex` attraverso un proxy su `upstream-proxy.internal.example.com`. Imposta l'header `x-source` letto dal proxy e invia un token dalla variabile d'ambiente `PROXY_TOKEN` come `x-proxy-token`:

420 535

421```yaml theme={null}536```yaml theme={null}

422upstreams:537upstreams:

430 x-proxy-token: ${PROXY_TOKEN}545 x-proxy-token: ${PROXY_TOKEN}

431```546```

432 547

433I valori sono testo ASCII stampabile senza spazio a nessuno dei due lati. Quotate un numero, `true` o `false` in modo che YAML lo legga come testo.548I valori sono testo ASCII stampabile senza spazi all'inizio o alla fine. Metti tra virgolette un numero, `true` o `false` in modo che YAML lo legga come testo.

434 549

435Per mantenere un segreto fuori dal file di configurazione, usate l'[espansione del segreto](#secret-expansion) per caricare il valore da una variabile di ambiente con `${VAR}` o da un file con `${file:/path}`. Un `${VAR}` che si risolve a un valore vuoto ferma il gateway dall'avviarsi.550Per tenere un segreto fuori dal file di configurazione, usa l'[espansione dei segreti](#secret-expansion) per caricare il valore da una variabile d'ambiente con `${VAR}` o da un file con `${file:/path}`. Un `${VAR}` che si risolve in un valore vuoto impedisce l'avvio del gateway.

436 551

437`headers:` funziona su ogni provider e ogni upstream invia solo il suo.552`headers:` funziona su ogni provider e ogni upstream invia solo i propri.

438 553

439Non ogni richiesta che il gateway invia a un upstream li porta:554Non tutte le richieste che il gateway invia a un upstream li includono:

440 555

442| - | - |557| - | - |

443| `/v1/messages`, streaming o no, e `/v1/messages/count_tokens` | Sì |558| `/v1/messages`, in streaming o meno, e `/v1/messages/count_tokens` | Sì |

445| Chiamata `CountTokens` di Amazon Bedrock per una richiesta che il client ha abbandonato | No |560| La chiamata `CountTokens` di Amazon Bedrock per una richiesta abbandonata dal client | No |

446| Lo scambio di token Workload Identity Federation | No |561| Lo scambio di token Workload Identity Federation | No |

447 562

448Su un upstream Amazon Bedrock o Claude Platform on AWS che firma le richieste con AWS SigV4, questi intestazioni fanno parte della firma, quindi il vostro proxy deve passarli attraverso invariati.563Su un upstream Amazon Bedrock o Claude Platform on AWS che firma le richieste con AWS SigV4, questi header fanno parte della firma, quindi il tuo proxy deve inoltrarli invariati.

449 564

450Se usate un nome che il gateway riserva, si rifiuta di avviarsi e l'errore di avvio nomina l'intestazione. I nomi riservati includono:565Se usi un nome riservato dal gateway, questo si rifiuta di avviarsi e l'errore di avvio indica l'header. I nomi riservati includono:

451 566

452* `authorization` e `x-api-key`567* `authorization` e `x-api-key`

453* `host`, `content-type` e `user-agent`568* `host`, `content-type` e `user-agent`

457 Più upstream572 Più upstream

458</h4>573</h4>

459 574

460Lo 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.575Lo stesso provider può comparire 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 fallback tra provider.

461 576

462Il gateway prova gli upstream in ordine. `5xx`, `429`, `401`, `403`, `404`, timeout e endpoint mancante (`501`) eseguono il failover; altri `4xx` no.577Il gateway prova gli upstream in ordine. `5xx`, `429`, `401`, `403`, `404`, timeout ed endpoint mancante (`501`) eseguono il failover; gli altri `4xx` no.

463 578

464`429` è capacità per upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover a on-demand. Se impostate [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) su un upstream, un `429` a una richiesta che portava l'email dello sviluppatore è un rifiuto per utente invece e non esegue il failover.579`429` indica la capacità del singolo upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover su on-demand. Se imposti [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) su un upstream, un `429` a una richiesta che portava l'email dello sviluppatore è invece un rifiuto per utente e non esegue il failover.

465 580

466Ogni richiesta inizia al primo upstream. Una richiesta raggiunge un upstream successivo solo quando ogni upstream davanti ad esso ha fallito o non serve il modello richiesto.581Ogni richiesta inizia dal primo upstream. Una richiesta raggiunge un upstream successivo solo quando ogni upstream che lo precede ha fallito o non serve il modello richiesto.

467 582

468Il gateway non mantiene alcun record di upstream falliti, quindi mentre un upstream è inattivo, ogni richiesta che lo raggiunge lo prova ancora e attende che fallisca prima di passare al successivo.583Il gateway non tiene traccia degli upstream falliti, quindi mentre un upstream non è disponibile, ogni richiesta che lo raggiunge lo prova comunque e attende che fallisca prima di passare al successivo.

469 584

470Per un upstream API Anthropic, [`timeouts.upstream_ttfb_ms`](#http-tuning) limita l'attesa su un upstream inattivo. Questa impostazione non si applica agli altri provider, dove il gateway attende fino a un'ora che un upstream inizi a rispondere.585Per un upstream API Anthropic, [`timeouts.upstream_ttfb_ms`](#http-tuning) limita l'attesa su un upstream non disponibile. Questa impostazione non si applica agli altri provider, dove il gateway attende fino a un'ora che un upstream inizi a rispondere.

471 586

472`404` è disponibilità del modello per upstream, quindi un upstream che non ha abilitato un modello non blocca un upstream successivo che lo serve. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete.587`404` indica la disponibilità del modello sul singolo upstream, quindi un upstream che non ha abilitato un modello non blocca un upstream successivo che lo serve. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete.

473 588

474Questo 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:589Questo esempio instrada prima un'allocazione di throughput provisioned di Amazon Bedrock, passa in overflow a on-demand e a un secondo account e usa l'API Anthropic come ultimo fallback:

475 590

476```yaml theme={null}591```yaml theme={null}

477upstreams:592upstreams:

485 provider: bedrock600 provider: bedrock

486 region: us-west-2601 region: us-west-2

487 auth: {}602 auth: {}

488 # Different account: a separate Bedrock allotment via assumed-role creds.603 # Different account: a separate Bedrock allotment via static keys.

489 - name: bedrock-acct2604 - name: bedrock-acct2

490 provider: bedrock605 provider: bedrock

491 region: us-east-1606 region: us-east-1

511 626

512| Leva | Come |627| Leva | Come |

513| - | - |628| - | - |

514| Regioni diverse | Un upstream Bedrock per regione, ciascuno con la sua `region:`. Con [`auto_include_builtin_models: true`](#models) i profili di inferenza cross-region instradano automaticamente; per distribuzioni fissate per regione usate un blocco `models:`. |629| Regioni diverse | Un upstream Amazon Bedrock per regione, ciascuno con la propria `region:`. Con [`auto_include_builtin_models: true`](#models) i profili di inferenza cross-region instradano automaticamente; per i deployment vincolati a una regione usa un blocco `models:`. |

515| Account diversi | Un 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. |630| Account diversi | Un upstream Amazon Bedrock per account. La catena predefinita (`auth: {}`) usa l'identità del pod; per un secondo account, aggiungi [`assume_role`](#bedrock-in-another-aws-account) per raggiungerlo con credenziali a breve durata, oppure imposta credenziali esplicite o un token bearer in `auth:`. |

516| Throughput provisioned | Mappate 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. |631| Throughput provisioned | Mappa 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 viene esaurita prima del failover. |

518| Instradamento scoped al modello | Solo un modello `id` personalizzato, uno che non è un modello Claude integrato, salta gli upstream assenti dalla sua mappa `upstream_model:`. Il gateway prova i modelli integrati su ogni upstream in ordine e usa l'ID predefinito del provider dove la mappa non ha voce, quindi per i modelli integrati la mappa cambia quale ID un upstream riceve piuttosto che se viene provato; un upstream che rifiuta l'ID segue le stesse [regole di failover](#upstreams) di qualsiasi altro errore dell'upstream. |633| Instradamento limitato al modello | Solo un `id` di modello personalizzato, cioè non un modello Claude integrato, salta gli upstream assenti dalla sua mappa `upstream_model:`. Il gateway prova i modelli integrati su ogni upstream in ordine e usa l'ID predefinito del provider dove la mappa non ha una voce, quindi per i modelli integrati la mappa cambia quale ID riceve un upstream anziché se venga provato; un upstream che rifiuta l'ID segue le stesse [regole di failover](#upstreams) di qualsiasi altro errore dell'upstream. |

519 634

520Il failover tra provider cloud o all'API Anthropic diretto cambia quale accordo, geografia e altri termini governano la richiesta.635Il failover tra provider cloud, o verso l'API Anthropic diretta, cambia quale accordo, area geografica e altri termini regolano la richiesta.

521 636

522La 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.637La 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.

523 638

529 `admin`644 `admin`

530</h3>645</h3>

531 646

532Facoltativo. Abilita `/v1/organizations/spend_limits`, che rispecchia l'API Admin pubblica di Anthropic, e l'applicazione di limiti di spesa per sviluppatore su `/v1/messages`. Vedi [Spend limits](/docs/it/claude-apps-gateway-spend-limits) per come vengono impostati e applicati i cap; questa sezione copre le chiavi `gateway.yaml` che attivano la funzione e la sintonizzano.647Facoltativo. Abilita `/v1/organizations/spend_limits`, che rispecchia l'API Admin pubblica di Anthropic, e l'applicazione di limiti di spesa per sviluppatore su `/v1/messages`. Vedi [Limiti di spesa](/docs/it/claude-apps-gateway-spend-limits) per come vengono impostati e applicati i cap; questa sezione copre le chiavi `gateway.yaml` che attivano la funzione e la regolano.

533 648

534```yaml theme={null}649```yaml theme={null}

535admin:650admin:

551| - | - | - |666| - | - | - |

552| `write_keys` | No | Array 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`. |667| `write_keys` | No | Array 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`. |

553| `read_keys` | No | Array di `{id, key}`. Sola lettura: ogni endpoint `GET`, incluso l'elenco dei cap, il recupero di uno per ID e la lettura di [`/effective`](/docs/it/claude-apps-gateway-spend-limits#%2Feffective) e [`/audit`](/docs/it/claude-apps-gateway-spend-limits#%2Faudit). |668| `read_keys` | No | Array di `{id, key}`. Sola lettura: ogni endpoint `GET`, incluso l'elenco dei cap, il recupero di uno per ID e la lettura di [`/effective`](/docs/it/claude-apps-gateway-spend-limits#%2Feffective) e [`/audit`](/docs/it/claude-apps-gateway-spend-limits#%2Faudit). |

554| `admin_groups` | No | Nomi dei gruppi IdP. Un JWT del gateway il cui claim `groups` include uno di questi ha accesso admin completo, lettura e scrittura, e controlla come `oidc:<sub>`. Usa questo per gli admin umani; usa le chiavi API per le macchine. Una voce vuota in questo elenco arresta il gateway all'avvio. Vedi [Matcher values that stop the gateway at boot](#matcher-values-that-stop-the-gateway-at-boot). |669| `admin_groups` | No | Nomi dei gruppi IdP. Un JWT del gateway il cui claim `groups` include uno di questi ha accesso da amministratore completo, in lettura e scrittura, e viene registrato nell'audit come `oidc:<sub>`. Usa questo per gli amministratori umani; usa le chiavi API per le macchine. Una voce vuota in questo elenco arresta il gateway all'avvio. Vedi [Valori dei matcher che arrestano il gateway all'avvio](#matcher-values-that-stop-the-gateway-at-boot). |

555| `blocked_message` | No | Aggiunto verbatim al `429 billing_error` che uno sviluppatore bloccato vede. Scrivi l'intera istruzione, come un URL o un canale Slack. Se non impostato, il gateway invia solo il messaggio predefinito. Vedi [How enforcement works](/docs/it/claude-apps-gateway-spend-limits#how-enforcement-works). |670| `blocked_message` | No | Aggiunto alla lettera al `429 billing_error` che uno sviluppatore bloccato vede. Scrivi l'intera istruzione, come un URL o un canale Slack. Se non impostato, il gateway invia solo il messaggio predefinito. Vedi [Come funziona l'applicazione](/docs/it/claude-apps-gateway-spend-limits#how-enforcement-works). |

556| `audit_retention_days` | No | Predefinito `365`. Le righe `admin_audit` più vecchie vengono eliminate. |671| `audit_retention_days` | No | Predefinito `365`. Le righe `admin_audit` più vecchie vengono eliminate. |

557| `spend_retention_months` | No | Predefinito `13`. Le righe del contatore `spend` più vecchie di questo vengono eliminate. Il valore predefinito mantiene un anno completo più il mese parziale corrente per i rapporti anno su anno. |672| `spend_retention_months` | No | Predefinito `13`. Le righe del contatore `spend` più vecchie di questo vengono eliminate. Il valore predefinito mantiene un anno completo più il mese parziale corrente per i rapporti anno su anno. |

558| `identity_retention_days` | No | Predefinito `90`. TTL dell'ultimo accesso 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à deprovisioning invecchi mentre i suoi contatori di spesa anonimi rimangono. |673| `identity_retention_days` | No | Predefinito `90`. TTL dall'ultimo accesso 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à rimossa scada mentre i suoi contatori di spesa anonimi rimangono. |

559| `group_limit_mode` | No | `min` (predefinito) o `max`. Quando uno sviluppatore è in diversi gruppi con cap, `min` applica il più restrittivo e `max` il meno restrittivo. Utilizzato sia dall'applicazione che da `/effective`. |674| `group_limit_mode` | No | `min` (predefinito) o `max`. Quando uno sviluppatore è in diversi gruppi con cap, `min` applica il più restrittivo e `max` il meno restrittivo. Utilizzato sia dall'applicazione che da `/effective`. |

560 675

561<h3 id="enforcement">676<h3 id="enforcement">

566 681

568| - | - | - |683| - | - | - |

569| `fail_closed_on_error` | No | Predefinito `false`. L'applicazione della spesa fallisce aperta in caso di interruzione di Postgres, quindi l'inferenza rimane attiva. Imposta `true` per fallire chiuso: gli sviluppatori oltre il cap vengono bloccati, ma lo è anche chiunque altro se l'archivio non è raggiungibile. Richiede un blocco [`admin:`](#admin): l'applicazione della spesa viene eseguita solo quando `admin` è configurato, e il gateway rifiuta di avviarsi se imposti questo `true` senza uno. |684| `fail_closed_on_error` | No | Predefinito `false`. L'applicazione della spesa fallisce aperta in caso di interruzione di Postgres, quindi l'inferenza rimane attiva. Imposta `true` per fallire chiuso: gli sviluppatori oltre il cap vengono bloccati, ma lo è anche chiunque altro se l'archivio non è raggiungibile. Richiede un blocco [`admin:`](#admin): l'applicazione della spesa viene eseguita solo quando `admin` è configurato, e il gateway rifiuta di avviarsi se imposti questo a `true` senza di esso. |

570 685

571<h3 id="pricing">686<h3 id="pricing">

572 `pricing`687 `pricing`

593| - | - | - |708| - | - | - |

594| `multiplier` | No | Predefinito `1`. Il misuratore moltiplica ogni importo misurato per questo, sia che sia a prezzo di listino che sovrascritto, quindi `0.85` addebita l'85% del prezzo. Deve essere maggiore di 0 e al massimo 10, e un valore superiore a 1 è un [markup](#mark-prices-up). |709| `multiplier` | No | Predefinito `1`. Il misuratore moltiplica ogni importo misurato per questo, sia che sia a prezzo di listino che sovrascritto, quindi `0.85` addebita l'85% del prezzo. Deve essere maggiore di 0 e al massimo 10, e un valore superiore a 1 è un [markup](#mark-prices-up). |

595| `overrides` | No | Righe di `{upstream, model, input, output, cache_read, cache_write}` in USD per milione di token. Tutti e quattro i tassi sono obbligatori. Ognuno deve essere maggiore di 0 e al massimo 10000. |710| `overrides` | No | Righe di `{upstream, model, input, output, cache_read, cache_write}` in USD per milione di token. Tutte e quattro le tariffe sono obbligatorie. Ognuna deve essere maggiore di 0 e al massimo 10000. |

596 711

597Come il misuratore abbina una riga di override:712Come il misuratore abbina una riga di override:

598 713

599* Una riga sostituisce il prezzo di listino per le richieste che `upstream`, un [`upstreams[].name`](#upstreams), serve per `model`. Questo include il tasso [fast mode](/docs/it/fast-mode#understand-the-cost-tradeoff) più alto, quindi le richieste fast e standard vengono misurate agli stessi quattro tassi.714* Una riga sostituisce il prezzo di listino per le richieste che `upstream`, un [`upstreams[].name`](#upstreams), serve per `model`. Questo include la tariffa più alta della [modalità veloce](/docs/it/fast-mode#understand-the-cost-tradeoff), quindi le richieste veloci e standard vengono misurate alle stesse quattro tariffe.

600* Un ID incorporato come `claude-sonnet-4-6`, abbinato come [`models[].id`](#models), copre ogni forma datata, forma regionale di Amazon Bedrock, o forma di Google Cloud's Agent Platform che il misuratore prezza come quel modello. Qualsiasi altra stringa, come un alias o un ARN del profilo di inferenza, abbina l'ID che il client ha inviato o la stringa inviata upstream, senza distinzione tra maiuscole e minuscole.715* Un ID incorporato come `claude-sonnet-4-6`, abbinato come [`models[].id`](#models), copre ogni forma datata, forma regionale di Amazon Bedrock o forma di Agent Platform di Google Cloud che il misuratore prezza come quel modello. Qualsiasi altra stringa, come un alias o un ARN del profilo di inferenza, corrisponde all'ID che il client ha inviato o alla stringa inviata upstream, senza distinzione tra maiuscole e minuscole.

601* Dove le righe si sovrappongono, il misuratore sceglie la riga più specifica piuttosto che la prima riga: una riga il cui `model` è la stringa di modello esatta inviata upstream, quindi una riga che corrisponde all'ID esatto che il client ha inviato, quindi una riga che nomina il modello incorporato.716* Dove le righe si sovrappongono, il misuratore sceglie la riga più specifica piuttosto che la prima riga: una riga il cui `model` è la stringa di modello esatta inviata upstream, quindi una riga che corrisponde all'ID esatto che il client ha inviato, quindi una riga che nomina il modello incorporato.

602* Un nome upstream sconosciuto fallisce all'avvio, così come due righe per uno upstream che nominano lo stesso modello, incluse due ortografie di un modello incorporato. Il gateway avverte all'avvio di una riga che nessun modello richiedibile può utilizzare.717* Un nome upstream sconosciuto fa fallire l'avvio, così come due righe per uno stesso upstream che nominano lo stesso modello, incluse due grafie di un modello incorporato. Il gateway avverte all'avvio di una riga che nessun modello richiedibile può utilizzare.

603* Le richieste di ricerca web rimangono al prezzo di listino \$0.01; il moltiplicatore si applica comunque a loro.718* Le richieste di ricerca web rimangono al prezzo di listino di \$0.01; il moltiplicatore si applica comunque a loro.

604 719

605Per tariffe per regione, dai a ogni regione il suo upstream denominato e una riga per upstream.720Per tariffe per regione, dai a ogni regione il suo upstream denominato e una riga per upstream.

606 721

608 Aumenta i prezzi723 Aumenta i prezzi

609</h4>724</h4>

610 725

611Con v2.1.271 o successivo sul server del gateway, puoi impostare `multiplier` sopra 1, fino a 10, per misurare più di quanto il provider addebita, ad esempio un tasso di chargeback interno. Questo esempio misura ogni richiesta al 120% del prezzo:726Con v2.1.271 o successivo sul server del gateway, puoi impostare `multiplier` sopra 1, fino a 10, per misurare più di quanto il provider addebita, ad esempio una tariffa di chargeback interna. Questo esempio misura ogni richiesta al 120% del prezzo:

612 727

613```yaml theme={null}728```yaml theme={null}

614pricing:729pricing:

615 multiplier: 1.2730 multiplier: 1.2

616```731```

617 732

618Con un blocco [`admin:`](#admin), il markup si applica anche ai limiti di spesa. Il misuratore conta il 120% del prezzo, quindi gli sviluppatori raggiungono i loro cap più velocemente. Il gateway registra un avviso all'avvio che lo dice.733Con un blocco [`admin:`](#admin), il markup si applica anche ai limiti di spesa. Il misuratore conta il 120% del prezzo, quindi gli sviluppatori raggiungono i loro cap più velocemente. Il gateway registra un avviso all'avvio che lo segnala.

619 734

620Il moltiplicatore non cambia quello che il provider upstream addebita per le richieste.735Il moltiplicatore non cambia quello che il provider upstream addebita per le richieste.

621 736

622Se il gateway inoltre [invia le tariffe ai client firmati](#send-the-rates-to-signed-in-clients), gli sviluppatori hanno bisogno di Claude Code v2.1.271 o successivo per vedere il markup. I client precedenti ignorano un `multiplier` superiore a 1 e mostrano i costi senza di esso.737Se il gateway inoltre [invia le tariffe ai client che hanno effettuato l'accesso](#send-the-rates-to-signed-in-clients), gli sviluppatori hanno bisogno di Claude Code v2.1.271 o successivo per vedere il markup. I client precedenti ignorano un `multiplier` superiore a 1 e mostrano i costi senza di esso.

623 738

624Un server gateway precedente a v2.1.271 rifiuta di avviarsi se imposti un `multiplier` superiore a 1.739Un server gateway precedente a v2.1.271 rifiuta di avviarsi se imposti un `multiplier` superiore a 1.

625 740

626<h4 id="send-the-rates-to-signed-in-clients">741<h4 id="send-the-rates-to-signed-in-clients">

627 Inviare le tariffe ai client firmati742 Invia le tariffe ai client che hanno effettuato l'accesso

628</h4>743</h4>

629 744

630Con v2.1.268 o successivo sul server del gateway, il gateway mette anche le tariffe da `pricing` nelle policy [`managed`](#managed) che serve, come l'impostazione gestita [`modelPricing`](/docs/it/settings-reference#modelpricing). Gli sviluppatori abbinati da una policy vedono quindi le tariffe `pricing` per il primo upstream che serve ogni ID modello in `/usage`, la riga di stato e OpenTelemetry. Uno sviluppatore che non corrisponde a nessuna policy non riceve impostazioni gestite, quindi le sue cifre rimangono al prezzo di listino. I client applicano l'impostazione in Claude Code v2.1.242 o successivo.745Con v2.1.268 o successivo sul server del gateway, il gateway mette anche le tariffe da `pricing` nelle policy [`managed`](#managed) che serve, come l'impostazione gestita [`modelPricing`](/docs/it/settings-reference#modelpricing). Gli sviluppatori abbinati da una policy vedono quindi le tariffe `pricing` per il primo upstream che serve ogni ID modello in `/usage`, nella riga di stato e in OpenTelemetry. Uno sviluppatore che non corrisponde a nessuna policy non riceve impostazioni gestite, quindi le sue cifre rimangono al prezzo di listino. I client applicano l'impostazione in Claude Code v2.1.242 o successivo.

631 746

632* Cosa aggiunge il gateway: a meno che il blocco `cli` di una policy non imposti già `modelPricing`, il gateway aggiunge il `multiplier` e, per ogni ID modello che un client può richiedere, la riga di override del primo upstream che serve quell'ID. Un tasso che solo un upstream di failover addebita rimane sul gateway.747* Cosa aggiunge il gateway: a meno che il blocco `cli` di una policy non imposti già `modelPricing`, il gateway aggiunge il `multiplier` e, per ogni ID modello che un client può richiedere, la riga di override del primo upstream che serve quell'ID. Una tariffa che solo un upstream di failover addebita rimane sul gateway.

633* Escludi una policy: imposta `modelPricing` a `{}` nel blocco `cli` di quella policy, e i suoi sviluppatori rimangono al prezzo di listino.748* Escludi una policy: imposta `modelPricing` a `{}` nel blocco `cli` di quella policy, e i suoi sviluppatori rimangono al prezzo di listino.

634* Mantieni le tariffe proprie di una policy: una policy il cui blocco `cli` imposta `modelPricing` con il suo `multiplier` o `overrides` mantiene quel `modelPricing` intero, e il gateway non aggiunge tariffe proprie a esso.749* Mantieni le tariffe proprie di una policy: una policy il cui blocco `cli` imposta `modelPricing` con il suo `multiplier` o `overrides` mantiene quel `modelPricing` intero, e il gateway non vi aggiunge tariffe proprie.

635 750

636<h3 id="models">751<h3 id="models">

637 `models`752 `models`

638</h3>753</h3>

639 754

640Il blocco `models` è un elenco di modelli curato da admin facoltativo, servito su `/v1/models` e utilizzato per tradurre gli ID modello per upstream. È obbligatorio per le regioni non statunitensi di Amazon Bedrock, gli ARN di throughput con provisioning di Amazon Bedrock e i nomi di distribuzione di Microsoft Foundry.755Il blocco `models` è un elenco di modelli facoltativo curato dall'amministratore, servito su `/v1/models` e utilizzato per tradurre gli ID modello per upstream. È obbligatorio per le regioni non statunitensi di Amazon Bedrock, gli ARN di throughput con provisioning di Amazon Bedrock e i nomi di deploy di Microsoft Foundry.

641 756

642```yaml theme={null}757```yaml theme={null}

643auto_include_builtin_models: true # false: expose only the list below758auto_include_builtin_models: true # false: expose only the list below

651 foundry: your-opus-deployment-name766 foundry: your-opus-deployment-name

652```767```

653 768

654Ogni chiave sotto `upstream_model` deve corrispondere al `name` di un upstream configurato, che per impostazione predefinita è il nome del provider. Una chiave che non corrisponde a nessun upstream fallisce all'avvio, quindi ometti le righe per i provider che non usi.769Ogni chiave sotto `upstream_model` deve corrispondere al `name` di un upstream configurato, che per impostazione predefinita è il nome del provider. Una chiave che non corrisponde a nessun upstream fa fallire l'avvio, quindi ometti le righe per i provider che non usi.

655 770

656<h3 id="managed">771<h3 id="managed">

657 `managed`772 `managed`

658</h3>773</h3>

659 774

660Il blocco `managed` definisce policy di accesso basate su ruoli basate su gruppi IdP o dominio di posta elettronica. Le policy vengono valutate in ordine; la prima corrispondenza viene selezionata, quindi unita alla base catch-all `match: {}`. Vengono servite per utente su `GET /managed/settings` con caching ETag/304.775Il blocco `managed` definisce policy di accesso basate sui ruoli, associate a gruppi IdP o al dominio email. Le policy vengono valutate in ordine; viene selezionata la prima corrispondenza, su cui viene poi eseguito il merge con la base catch-all `match: {}`. Vengono servite per utente su `GET /managed/settings` con caching ETag/304.

661 776

662```yaml theme={null}777```yaml theme={null}

663managed:778managed:

673 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]788 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

674```789```

675 790

676Un catch-all `match: {}`, convenzionalmente elencato per ultimo, viene trattato come un livello base. Ogni altra policy eredita qualsiasi chiave che non imposta dalla catch-all, quindi le voci per ruolo devono solo elencare ciò che differisce dal valore predefinito dell'organizzazione. Le regole di unione dipendono dal tipo di chiave:791Un catch-all `match: {}`, convenzionalmente elencato per ultimo, viene trattato come un livello base. Ogni altra policy eredita dal catch-all qualsiasi chiave che non imposta, quindi le voci per ruolo devono solo elencare ciò che differisce dal valore predefinito dell'organizzazione. Le regole di merge dipendono dal tipo di chiave:

677 792

678* **Allow-lists**: `availableModels` e `permissions.allow`. L'elenco di una policy specifica sostituisce completamente quello della base.793* **Allowlist**: `availableModels` e `permissions.allow`. L'elenco di una policy specifica sostituisce completamente quello della base.

679* **Deny-lists e hook arrays**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` e ogni array di tipo evento `hooks`. Questi prendono l'unione di base e policy, quindi un deny a livello di organizzazione o un hook di audit non può essere accidentalmente eliminato da un override per ruolo.794* **Elenchi di negazione e array di hook**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` e ogni array di tipo evento `hooks`. Questi prendono l'unione di base e policy, quindi un deny a livello di organizzazione o un hook di audit non può essere accidentalmente eliminato da un override per ruolo.

680* **Record-typed keys**: `env`, `modelOverrides` e `skillOverrides`. Questi si uniscono superficialmente, quindi un blocco `env` per ruolo sostituisce le chiavi che imposta e eredita il resto dalla base.795* **Chiavi di tipo record**: `env`, `modelOverrides` e `skillOverrides`. Per queste si esegue un merge superficiale, quindi un blocco `env` per ruolo sovrascrive le chiavi che imposta ed eredita il resto dalla base.

681 796

682`availableModels` viene anche applicato lato server su `/v1/messages`, quindi un modello negato restituisce `400` indipendentemente da quello che il client invia.797`availableModels` viene anche applicato lato server su `/v1/messages`, quindi un modello negato restituisce `400` indipendentemente da quello che il client invia.

683 798

688 803

689| Matcher | Comportamento |804| Matcher | Comportamento |

690| - | - |805| - | - |

691| `match: {}` | Corrisponde a ogni utente autenticato. Inizia con uno di questi e aggiungi policy con ambito di gruppo sopra di esso in seguito. |806| `match: {}` | Corrisponde a ogni utente autenticato. Inizia con uno di questi e aggiungi in seguito policy con ambito di gruppo sopra di esso. |

692| `match: { groups: [a, b] }` | Corrisponde se il claim `groups` del JWT contiene uno dei gruppi elencati. Sensibile alle maiuscole: i gruppi devono corrispondere alle maiuscole esatte dell'IdP. |807| `match: { groups: [a, b] }` | Corrisponde se il claim `groups` del JWT contiene uno dei gruppi elencati. Sensibile alle maiuscole: i gruppi devono corrispondere esattamente alle maiuscole e minuscole dell'IdP. |

693| `match: { email_domain: example.com }` | Corrisponde alla parte dopo l'ultimo `@` nel claim `email` del JWT, senza distinzione tra maiuscole e minuscole. Accetta un dominio per policy. |808| `match: { email_domain: example.com }` | Corrisponde alla parte dopo l'ultimo `@` nel claim `email` del JWT, senza distinzione tra maiuscole e minuscole. Accetta un dominio per policy. |

694| `match: { groups: [a], email_domain: example.com }` | Entrambe le condizioni devono corrispondere |809| `match: { groups: [a], email_domain: example.com }` | Entrambe le condizioni devono corrispondere |

695 810

696Un utente autenticato che non corrisponde a nessuna policy ottiene i valori predefiniti del gateway, il che significa ogni modello nel catalogo e nessuna impostazione gestita. Aggiungi un catch-all `match: {}` per ultimo se vuoi una policy predefinita garantita.811Un utente autenticato che non corrisponde a nessuna policy ottiene i valori predefiniti del gateway, il che significa ogni modello nel catalogo e nessuna impostazione gestita. Aggiungi un catch-all `match: {}` per ultimo se vuoi una policy predefinita garantita.

697 812

698<Note>813<Note>

699 Il gateway non mantiene una propria directory utente. Autorizza ogni richiesta dal token IdP dell'utente, leggendo l'appartenenza al gruppo dal claim `groups` del token e valutando le policy 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.814 Il gateway non mantiene una propria directory utente. Autorizza ogni richiesta dal token IdP dell'utente, leggendo l'appartenenza ai gruppi dal claim `groups` del token e valutando le policy rispetto ad esso. Non c'è un elenco da enumerare e nessun account da pre-creare, e quindi nessun endpoint SCIM, perché non c'è nulla in cui SCIM possa sincronizzare.

700 815

701 Esegui la gestione del ciclo di vita di utenti e gruppi alla fonte della verità, che è il provisioning SCIM nativo del tuo IdP o una piattaforma dedicata di governance dell'identità. L'appartenenza e il deprovisioning governati lì fluiscono nel gateway automaticamente attraverso il token. Se vuoi il provisioning SCIM degli account Claude stessi, questa è una capacità di [Claude for Enterprise](/docs/it/admin-setup).816 Esegui la gestione del ciclo di vita di utenti e gruppi alla fonte di verità, che è il provisioning SCIM nativo del tuo IdP o una piattaforma dedicata di governance delle identità. L'appartenenza e il deprovisioning gestiti lì fluiscono nel gateway automaticamente attraverso il token. Se vuoi il provisioning SCIM degli account Claude stessi, questa è una funzionalità di [Claude for Enterprise](/docs/it/admin-setup).

702 817

703 Si applicano due orologi di propagazione:818 Si applicano due tempi di propagazione:

704 819

705 * **Contenuti della policy**: modificare una policy e ridistribuire raggiunge i client connessi al loro prossimo sondaggio di impostazioni gestite, entro un'ora, a parte i [cambiamenti che si applicano solo al prossimo avvio](/docs/it/server-managed-settings#fetch-and-caching-behavior)820 * **Contenuti della policy**: modificare una policy e rifare il deploy raggiunge i client connessi al loro prossimo polling delle impostazioni gestite, entro un'ora, a parte le [modifiche che si applicano solo al prossimo avvio](/docs/it/server-managed-settings#fetch-and-caching-behavior)

706 * **Appartenenza al gruppo**: cambiare l'appartenenza al gruppo di un utente cambia quale policy lo corrisponde. Questo ha effetto al prossimo rinnovo della sessione, il che significa il prossimo aggiornamento silenzioso, limitato da `session.ttl_hours`.821 * **Appartenenza ai gruppi**: cambiare l'appartenenza ai gruppi di un utente cambia quale policy gli corrisponde. Questo ha effetto alla prossima riemissione della sessione, cioè al prossimo aggiornamento silenzioso, limitato da `session.ttl_hours`.

707</Note>822</Note>

708 823

709<h4 id="matcher-values-that-stop-the-gateway-at-boot">824<h4 id="matcher-values-that-stop-the-gateway-at-boot">

710 Matcher values that stop the gateway at boot825 Valori dei matcher che arrestano il gateway all'avvio

711</h4>826</h4>

712 827

713All'avvio, il gateway controlla il blocco `match` di ogni policy e l'elenco [`admin_groups`](#admin). Uno qualsiasi di questi valori arresta il gateway con un errore che nomina il campo:828All'avvio, il gateway controlla il blocco `match` di ogni policy e l'elenco [`admin_groups`](#admin). Uno qualsiasi di questi valori arresta il gateway con un errore che nomina il campo:

715* Un elenco `groups` vuoto830* Un elenco `groups` vuoto

716* Una voce vuota in `groups` o in `admin_groups`831* Una voce vuota in `groups` o in `admin_groups`

717* Un `email_domain` vuoto832* Un `email_domain` vuoto

718* Un `email_domain` che contiene `@`, spazi bianchi o una virgola. Il gateway taglia il valore e rimuove un `@` iniziale prima di questo controllo. Scrivi un dominio nudo, come `example.com`.833* Un `email_domain` che contiene `@`, spazi bianchi o una virgola. Il gateway rimuove gli spazi dal valore e toglie un `@` iniziale prima di questo controllo. Scrivi un solo dominio semplice, come `example.com`.

719 834

720Prima di v2.1.232, il gateway si avviava con questi valori. Ogni valore aveva questo effetto:835Prima di v2.1.232, il gateway si avviava con questi valori. Ogni valore aveva questo effetto:

721 836

722* Un `email_domain` vuoto: il gateway ha saltato il controllo del dominio, quindi una policy con un `email_domain` vuoto e nessun elenco `groups` corrisponde a ogni utente autenticato837* Un `email_domain` vuoto: il gateway saltava il controllo del dominio, quindi una policy con un `email_domain` vuoto e nessun elenco `groups` corrispondeva a ogni utente autenticato

723* Un elenco `groups` vuoto: la policy non corrisponde a nessuno838* Un elenco `groups` vuoto: la policy non corrispondeva a nessuno

724* Un `email_domain` contenente `@`, spazi bianchi o una virgola: la policy non corrisponde a nessuno839* Un `email_domain` contenente `@`, spazi bianchi o una virgola: la policy non corrispondeva a nessuno

725* Una voce vuota in `groups` o in `admin_groups`: la voce corrisponde a un utente solo quando il claim `groups` dell'IdP di quell'utente conteneva anche una voce vuota. In `admin_groups`, quella corrispondenza ha concesso l'accesso admin. Se il tuo elenco `admin_groups` non ha mai contenuto una voce vuota, nessuno ha ottenuto l'accesso admin in questo modo.840* Una voce vuota in `groups` o in `admin_groups`: la voce corrispondeva a un utente solo quando anche il claim `groups` dell'IdP di quell'utente conteneva una voce vuota. In `admin_groups`, quella corrispondenza concedeva l'accesso da amministratore. Se il tuo elenco `admin_groups` non ha mai contenuto una voce vuota, nessuno ha ottenuto l'accesso da amministratore in questo modo.

726 841

727<h4 id="what-goes-in-cli">842<h4 id="what-goes-in-cli">

728 What goes in `cli`843 Cosa va in `cli`

729</h4>844</h4>

730 845

731Ogni valore `cli` è un documento completo di `managed-settings.json` di Claude Code, lo stesso schema che distribuiresti 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 di utente e progetto, al posto delle impostazioni gestite dal server. Ignora quindi le impostazioni [ristrette alle fonti di policy a livello di sistema operativo](/docs/it/server-managed-settings#current-limitations), come `policyHelper` e `wslInheritsWindowsSettings`.846Ogni valore `cli` è un documento `managed-settings.json` completo di Claude Code, lo stesso schema che distribuiresti 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 di utente e progetto, al posto delle impostazioni gestite dal server. Ignora quindi le impostazioni [limitate alle fonti di policy a livello di sistema operativo](/docs/it/server-managed-settings#current-limitations), come `policyHelper` e `wslInheritsWindowsSettings`.

732 847

733Il gateway convalida ogni documento rispetto allo schema delle impostazioni della CLI all'avvio, quindi una chiave di primo livello non riconosciuta fallisce all'avvio con un errore che nomina ogni chiave offensiva. Le parti deliberatamente aperte dello schema accettano ancora valori arbitrari, perché i client più recenti potrebbero riconoscere voci che lo schema del gateway non riconosce. Queste chiavi aperte includono `env`, `pluginConfigs` e chiavi annidate sotto `permissions`.848Il gateway convalida ogni documento rispetto allo schema delle impostazioni della CLI all'avvio, quindi una chiave di primo livello non riconosciuta fa fallire l'avvio con un errore che nomina ogni chiave problematica. Le parti deliberatamente aperte dello schema accettano comunque valori arbitrari, perché i client più recenti potrebbero riconoscere voci che lo schema del gateway non riconosce. Queste chiavi aperte includono `env`, `pluginConfigs` e le chiavi annidate sotto `permissions`.

734 849

735Poiché 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 prima l'aggiornamento del gateway. Smoke-test una nuova policy su un client prima di distribuirla.850Poiché la convalida utilizza lo schema incluso nella versione installata del gateway, inserire nella configurazione gestita una chiave di impostazioni di primo livello introdotta da una versione più recente di Claude Code richiede prima l'aggiornamento del gateway. Esegui uno smoke test di una nuova policy su un client prima di distribuirla.

736 851

737Il riferimento completo della chiave è in [Claude Code settings](/docs/it/settings-reference#all-settings). Le chiavi che gli operatori raggiungono per prime:852Il riferimento completo delle chiavi è in [Impostazioni di Claude Code](/docs/it/settings-reference#all-settings). Le chiavi che gli operatori usano per prime:

738 853

739```yaml theme={null}854```yaml theme={null}

740managed:855managed:

770 885

772| - | - | - |887| - | - | - |

774| `permissions.allow` / `.deny` | CLI | Regole di strumenti e comandi. Vedi [Permissions](/docs/it/permissions). |889| `permissions.allow` / `.deny` | CLI | Regole per strumenti e comandi. Vedi [Permessi](/docs/it/permissions). |

775| `permissions.disableBypassPermissionsMode` | CLI | Imposta su `disable` per bloccare [`bypassPermissions`](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode), la modalità che salta i prompt di autorizzazione, e il flag `--dangerously-skip-permissions` |890| `permissions.disableBypassPermissionsMode` | CLI | Imposta su `disable` per bloccare [`bypassPermissions`](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode), la modalità che salta le richieste di permesso, e il flag `--dangerously-skip-permissions` |

776| `allowManagedPermissionRulesOnly` | CLI | Quando `true`, le impostazioni gestite diventano l'unica fonte di impostazioni delle regole di autorizzazione. La voce [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) elenca ogni fonte che Claude Code ignora. |891| `allowManagedPermissionRulesOnly` | CLI | Quando `true`, le impostazioni gestite diventano l'unica fonte di impostazioni per le regole di permesso. La voce [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) elenca ogni fonte che Claude Code ignora in quel caso. |

777| `env` | CLI | Variabili di ambiente unite nel processo CLI. Usa per telemetria, auto-aggiornamento e override dei nomi dei modelli. |892| `env` | CLI | Variabili d'ambiente sottoposte a merge nel processo CLI. Da usare per telemetria, aggiornamento automatico e override dei nomi dei modelli. |

778| `hooks` | CLI | [hooks](/docs/it/hooks) a livello di organizzazione |893| `hooks` | CLI | [Hook](/docs/it/hooks) a livello di organizzazione |

779| `managedMcpServers` | CLI | Server MCP remoti [forniti a ogni sviluppatore corrispondente](/docs/it/managed-mcp#provide-servers-through-managed-settings) insieme ai server che aggiungono loro stessi, `http` e `sse` solo. Vedi [MCP servers in a policy](#mcp-servers-in-a-policy). Richiede Claude Code v2.1.259 o successivo sul server del gateway e sui client. I client precedenti ignorano la chiave. |894| `managedMcpServers` | CLI | Server MCP remoti [forniti a ogni sviluppatore corrispondente](/docs/it/managed-mcp#provide-servers-through-managed-settings) insieme ai server che aggiungono loro stessi, solo `http` e `sse`. Vedi [Server MCP in una policy](#mcp-servers-in-a-policy). Richiede Claude Code v2.1.259 o successivo sul server del gateway e sui client. I client precedenti ignorano la chiave. |

780 895

781Poiché queste impostazioni arrivano sulla rete, la CLI mostra a ogni sviluppatore una finestra di dialogo di approvazione della sicurezza prima di applicare le impostazioni elencate di seguito:896Poiché queste impostazioni arrivano dalla rete, la CLI mostra a ogni sviluppatore una finestra di dialogo di approvazione di sicurezza prima di applicare le impostazioni elencate di seguito:

782 897

783* `hooks`898* `hooks`

784* Variabili `env` che richiedono l'approvazione dello sviluppatore, come variabili proxy e base-URL899* variabili `env` che richiedono l'approvazione dello sviluppatore, come le variabili di proxy e di base URL

785* impostazioni di esecuzione della shell come `apiKeyHelper` e `statusLine`900* impostazioni di esecuzione della shell come `apiKeyHelper` e `statusLine`

786* le impostazioni binarie della sandbox `sandbox.bwrapPath`, `sandbox.socatPath` e `sandbox.ripgrep`901* le impostazioni dei binari della sandbox `sandbox.bwrapPath`, `sandbox.socatPath` e `sandbox.ripgrep`

787* Impostazioni della sandbox che intercettano il traffico, iniettano credenziali o indeboliscono l'isolamento, come `sandbox.network.tlsTerminate` e le impostazioni della porta proxy. [Security approval dialogs](/docs/it/server-managed-settings#security-approval-dialogs) le elenca tutte.902* Impostazioni della sandbox che intercettano il traffico, iniettano credenziali o indeboliscono l'isolamento, come `sandbox.network.tlsTerminate` e le impostazioni della porta del proxy. [Finestre di dialogo di approvazione di sicurezza](/docs/it/server-managed-settings#security-approval-dialogs) le elenca tutte.

903

904[Memoria delle approvazioni](/docs/it/server-managed-settings#approval-memory) spiega quanto dura un'approvazione e quando la finestra di dialogo appare di nuovo.

788 905

789[Approval memory](/docs/it/server-managed-settings#approval-memory) copre quanto dura un'approvazione e quando la finestra di dialogo appare di nuovo.906Claude Code applica alcune variabili `env` consegnate senza mostrare allo sviluppatore la finestra di dialogo di approvazione, come le impostazioni di selezione del modello e i limiti numerici. Altre variabili consegnate possono richiedere l'approvazione dello sviluppatore prima di avere effetto; un valore non vuoto di proxy, base URL o `OTEL_EXPORTER_OTLP_ENDPOINT` la richiede sempre. Quando una variabile consegnata ha bisogno di approvazione, la finestra di dialogo la nomina.

790 907

791Claude Code applica alcune variabili `env` consegnate senza mostrare allo sviluppatore la finestra di dialogo di approvazione, come le impostazioni di selezione del modello e i limiti numerici. Altre variabili consegnate possono richiedere l'approvazione dello sviluppatore prima di avere effetto; un valore proxy, base-URL o `OTEL_EXPORTER_OTLP_ENDPOINT` non vuoto lo fa sempre. Quando una variabile consegnata ha bisogno di approvazione, la finestra di dialogo la nomina.908[Variabili d'ambiente e la finestra di dialogo di approvazione](/docs/it/server-managed-settings#environment-variables-and-the-approval-dialog) contiene i dettagli, inclusi quattro interruttori di privacy il cui valore consegnato decide se hanno bisogno di approvazione. Prima di v2.1.218, Claude Code applicava meno variabili senza chiedere allo sviluppatore, quindi più variabili consegnate attivavano la finestra di dialogo.

792 909

793[Environment variables and the approval dialog](/docs/it/server-managed-settings#environment-variables-and-the-approval-dialog) ha i dettagli, inclusi quattro interruttori di privacy il cui valore consegnato decide se hanno bisogno di approvazione. Prima di v2.1.218, Claude Code applicava meno variabili senza chiedere allo sviluppatore, quindi più variabili consegnate attivavano la finestra di dialogo.910La configurazione di [telemetria](#telemetry) del gateway invia `OTEL_EXPORTER_OTLP_ENDPOINT`, quindi impostare `telemetry.forward_to` attiva la finestra di dialogo su ogni client interattivo. La finestra di dialogo protegge la macchina dello sviluppatore da un gateway compromesso o ostile, non l'organizzazione dallo sviluppatore.

794 911

795La configurazione [telemetry](#telemetry) del gateway spinge `OTEL_EXPORTER_OTLP_ENDPOINT`, quindi impostare `telemetry.forward_to` attiva la finestra di dialogo su ogni client interattivo. La finestra di dialogo protegge la macchina dello sviluppatore da un gateway compromesso o ostile, non l'organizzazione dallo sviluppatore.912Un'[esecuzione non interattiva](/docs/it/server-managed-settings#security-approval-dialogs), come `claude -p` o una sessione dell'Agent SDK, non può mostrare la finestra di dialogo. Applica le impostazioni inviate solo per quell'esecuzione e non le registra come approvate, quindi la prossima sessione interattiva dello sviluppatore mostra comunque la finestra di dialogo. Prima di v2.1.207, un'esecuzione non interattiva salvava le impostazioni come approvate e nessuna sessione interattiva successiva mostrava la finestra di dialogo per esse.

796 913

797Un'esecuzione non interattiva con il flag `-p` non può mostrare la finestra di dialogo. Applica le impostazioni spinte per quella sola esecuzione e non le registra come approvate, quindi la prossima sessione interattiva dello sviluppatore mostra comunque la finestra di dialogo per loro. Prima di v2.1.207, un'esecuzione non interattiva salvava le impostazioni come approvate e nessuna sessione interattiva successiva mostrava la finestra di dialogo per loro.914Se uno sviluppatore rifiuta, Claude Code esce da quella sessione anziché applicare la policy. Quando invii un nuovo hook, o qualsiasi variabile env che attiva la finestra di dialogo, a una policy ampia, ogni sviluppatore corrispondente vede quindi la finestra di dialogo nelle proprie sessioni interattive. Una sessione interattiva in esecuzione la mostra al prossimo polling orario, altrimenti appare al successivo avvio interattivo dello sviluppatore.

915

916La chiave `cli` era denominata `settings` nelle versioni precedenti. Questa grafia è ancora accettata come alias, ma i nuovi deploy dovrebbero usare `cli`.

917

918<h4 id="context-window-in-terminal-sessions">

919 Finestra di contesto nelle sessioni da terminale

920</h4>

798 921

799Se uno sviluppatore rifiuta, Claude Code esce da quella sessione piuttosto che applicare la policy. Quando spingi un nuovo hook, o qualsiasi variabile env che attiva la finestra di dialogo, a una policy ampia, Claude Code mostra quindi la finestra di dialogo a ogni sviluppatore corrispondente. Mostra la finestra di dialogo in una sessione in esecuzione al prossimo sondaggio orario, e altrimenti all'avvio successivo dello sviluppatore.922Le sessioni da terminale con accesso effettuato tramite `/login` usano la finestra di contesto da 1M per Opus 4.7 e successivi, Sonnet 5 e successivi, e i modelli Fable. L'ID del modello non ha bisogno del suffisso `[1m]`, e le sessioni si compattano a circa 967K token. Prima di Claude Code v2.1.287 sulla macchina dello sviluppatore, Claude Code trattava i modelli Opus e Fable come dotati di una finestra da 200K a meno che l'ID del modello non terminasse con `[1m]`.

800 923

801La chiave `cli` era denominata `settings` nelle versioni precedenti. Questo spelling è ancora accettato come alias, ma le nuove distribuzioni dovrebbero usare `cli`.924Per far sì che le sessioni da terminale si compattino invece al limite dei 200K, imposta la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) nell'`env` della policy:

925

926```yaml theme={null}

927managed:

928 policies:

929 - match: {}

930 cli:

931 env:

932 CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

933```

934

935Claude Code applica questa variabile senza mostrare allo sviluppatore la finestra di dialogo di approvazione. La variabile si applica a ogni modello, inclusi gli ID modello che terminano con `[1m]`.

936

937Per disattivare invece il contesto 1M, imposta [`CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`](/docs/it/model-config#extended-context) nello stesso blocco `env`. Claude Code tratta quindi ogni modello come dotato di una finestra da 200K. Nelle sessioni interattive, ogni sviluppatore approva questa variabile nella [finestra di dialogo di approvazione](#what-goes-in-cli) prima che abbia effetto.

802 938

803<h4 id="mcp-servers-in-a-policy">939<h4 id="mcp-servers-in-a-policy">

804 MCP servers in a policy940 Server MCP in una policy

805</h4>941</h4>

806 942

807Per fornire server MCP ai client Claude Code che una policy corrisponde, imposta [`managedMcpServers`](/docs/it/managed-mcp#provide-servers-through-managed-settings) nel blocco `cli` di quella policy. Hai bisogno di Claude Code v2.1.259 o successivo sul server del gateway e sui client.943Per fornire server MCP ai client Claude Code a cui corrisponde una policy, imposta [`managedMcpServers`](/docs/it/managed-mcp#provide-servers-through-managed-settings) nel blocco `cli` di quella policy. Hai bisogno di Claude Code v2.1.259 o successivo sul server del gateway e sui client.

808 944

809Il gateway controlla ogni voce all'avvio con [le stesse regole che Claude Code applica sul client](/docs/it/managed-mcp#what-an-entry-can-contain), e se una voce fallisce un controllo, il gateway rifiuta di avviarsi e nomina la voce.945Il gateway controlla ogni voce all'avvio con [le stesse regole che Claude Code applica sul client](/docs/it/managed-mcp#what-an-entry-can-contain), e se una voce non supera un controllo, il gateway rifiuta di avviarsi e nomina la voce.

810 946

811Se scrivi un riferimento `${VAR}` in `gateway.yaml`, il gateway lo risolve dal suo ambiente all'avvio attraverso [secret expansion](#secret-expansion) prima di eseguire i controlli della voce, quindi ogni client corrispondente riceve il valore letterale e può leggerlo. La [header guidance for provided servers](/docs/it/managed-mcp#provide-servers-through-managed-settings) si applica al valore espanso.947Se scrivi un riferimento `${VAR}` in `gateway.yaml`, il gateway lo risolve dal suo ambiente all'avvio tramite l'[espansione dei segreti](#secret-expansion) prima di eseguire i controlli sulle voci, quindi ogni client corrispondente riceve il valore letterale e può leggerlo. Le [indicazioni sulle intestazioni per i server forniti](/docs/it/managed-mcp#provide-servers-through-managed-settings) si applicano al valore espanso.

812 948

813Il gateway rifiuta lo spelling `.mcp.json` `mcpServers` in un blocco `cli`, e il suo errore di avvio nomina `managedMcpServers` come la chiave da usare. Prima di v2.1.259, il gateway rifiutava qualsiasi definizione di server MCP in un blocco `cli`.949Il gateway rifiuta la grafia `mcpServers` di `.mcp.json` in un blocco `cli`, e il suo errore di avvio indica `managedMcpServers` come chiave da usare. Prima di v2.1.259, il gateway rifiutava qualsiasi definizione di server MCP in un blocco `cli`.

814 950

815<h4 id="claude-desktop-overlay">951<h4 id="claude-desktop-overlay">

816 Claude Desktop overlay952 Overlay di Claude Desktop

817</h4>953</h4>

818 954

819Se la tua organizzazione distribuisce anche [Claude Desktop](/docs/it/desktop), lo stesso gateway serve entrambi i client. Punta `bootstrapUrl`, nella [managed configuration](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop, a `<listen.public_url>/user/bootstrap`. Claude Desktop deriva l'emittente OAuth da quell'URL, esegue lo stesso accesso con codice dispositivo rispetto a questo gateway e recupera la sua configurazione dalla risposta.955Se la tua organizzazione distribuisce anche [Claude Desktop](/docs/it/desktop), lo stesso gateway serve entrambi i client. Punta `bootstrapUrl`, nella [configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop, a `<listen.public_url>/user/bootstrap`. Claude Desktop deriva l'emittente OAuth da quell'URL, esegue lo stesso accesso con codice dispositivo su questo gateway e recupera la sua configurazione dalla risposta.

820 956

821<Note>957<Note>

822 Richiede Claude Code v2.1.203 o successivo sul server del gateway e un opt-in esplicito: `/user/bootstrap` restituisce 404 a meno che la policy che corrisponde all'utente non porti una chiave `desktop`. Un `desktop: {}` vuoto opta una policy, e una chiave `desktop` sul livello base `match: {}` opta in ogni policy che la eredita. Il registro di audit registra ogni richiesta come `desktop_bootstrap.serve` o `desktop_bootstrap.denied`.958 Richiede Claude Code v2.1.203 o successivo sul server del gateway e un opt-in esplicito: `/user/bootstrap` restituisce 404 a meno che la policy che corrisponde all'utente non contenga una chiave `desktop`. Un `desktop: {}` vuoto abilita una policy, e una chiave `desktop` sul livello base `match: {}` abilita ogni policy che la eredita. Il log di audit registra ogni richiesta come `desktop_bootstrap.serve` o `desktop_bootstrap.denied`.

823</Note>959</Note>

824 960

825Il gateway deriva gran parte della risposta dal blocco `cli` della policy corrispondente e dalla configurazione del gateway di primo livello:961Il gateway deriva gran parte della risposta dal blocco `cli` della policy corrispondente e dalla configurazione di primo livello del gateway:

826 962

827* L'elenco dei modelli, da `availableModels`963* L'elenco dei modelli, da `availableModels`. [Contesto esteso in Claude Desktop](#extended-context-in-claude-desktop) tratta l'opzione di contesto 1M di ciascun modello

828* Strumenti disabilitati, da voci `permissions.deny` con nome di strumento nudo. Se imposti `disabledBuiltinTools` nel blocco `desktop` della policy, il gateway serve l'unione del tuo valore e dell'elenco derivato, quindi puoi disabilitare più strumenti in questo modo ma non puoi riabilitarne uno che hai disabilitato tramite `permissions.deny`964* Gli strumenti disabilitati, dalle voci `permissions.deny` con il solo nome dello strumento. Se imposti `disabledBuiltinTools` nel blocco `desktop` della policy, il gateway serve l'unione del tuo valore e dell'elenco derivato, quindi puoi disabilitare più strumenti in questo modo ma non puoi riabilitarne uno che hai disabilitato tramite `permissions.deny`

829* L'allowlist di uscita, da `sandbox.network.allowedDomains`. Se imposti `coworkEgressAllowedHosts` nel blocco `desktop` della policy, il gateway usa quel valore invece dell'elenco derivato965* L'allowlist di uscita, da `sandbox.network.allowedDomains`. Se imposti `coworkEgressAllowedHosts` nel blocco `desktop` della policy, il gateway usa quel valore invece dell'elenco derivato

830* Un endpoint OTLP che punta al gateway stesso, e gli attributi di identità dell'utente firmato. Il gateway inoltra le esportazioni che riceve a quell'endpoint alle tue destinazioni `forward_to`. Include l'endpoint e gli attributi quando imposti sia [`telemetry.forward_to`](#telemetry) che `listen.public_url`.966* Un endpoint OTLP che punta al gateway stesso, e gli attributi di identità dell'utente che ha effettuato l'accesso. Il gateway inoltra le esportazioni che riceve su quell'endpoint alle tue destinazioni `forward_to`. Include l'endpoint e gli attributi quando imposti sia [`telemetry.forward_to`](#telemetry) che `listen.public_url`.

831 967

832 Claude Desktop esporta ogni segnale con una codifica: `http/protobuf`, o `http/json` quando imposti `OTEL_EXPORTER_OTLP_PROTOCOL` o uno dei suoi varianti per segnale a `http/json` nel `env` della policy. Prima di Claude Code v2.1.261 sul server del gateway, la risposta impostava `http/json` indipendentemente, quindi un collettore che accetta solo protobuf rifiutava le esportazioni di Claude Desktop968 Claude Desktop esporta ogni segnale con un'unica codifica: `http/protobuf`, oppure `http/json` quando imposti `OTEL_EXPORTER_OTLP_PROTOCOL` o una delle sue varianti per segnale a `http/json` nell'`env` della policy. Prima di Claude Code v2.1.261 sul server del gateway, la risposta impostava comunque `http/json`, quindi un collettore che accetta solo protobuf rifiutava le esportazioni di Claude Desktop

833 969

834Per impostare `disabledBuiltinTools`, `coworkEgressAllowedHosts` o l'impostazione `managedMcpServers` di Claude Desktop stesso nel blocco `desktop` di una policy, hai bisogno di Claude Code v2.1.232 o successivo sul server del gateway. L'impostazione `managedMcpServers` di Claude Desktop accetta un valore di array piuttosto che un oggetto.970Per impostare `disabledBuiltinTools`, `coworkEgressAllowedHosts` o l'impostazione `managedMcpServers` propria di Claude Desktop nel blocco `desktop` di una policy, hai bisogno di Claude Code v2.1.232 o successivo sul server del gateway. L'impostazione `managedMcpServers` di Claude Desktop accetta un valore array anziché un oggetto.

835 971

836Il gateway omette le chiavi senza equivalente di Claude Desktop, come `hooks` e regole di autorizzazione con ambito come `Bash(npm *)`, dalla risposta di bootstrap.972Il gateway omette dalla risposta di bootstrap le chiavi senza equivalente in Claude Desktop, come `hooks` e le regole di permesso con ambito come `Bash(npm *)`.

837 973

838Aggiungi il blocco `desktop` facoltativo insieme a `cli` per impostare le impostazioni di Claude Desktop direttamente. Scrivi le impostazioni dal [managed configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop come nomi di chiave piatti. Lascia fuori le chiavi che Claude Desktop legge solo da MDM o file locali, come `bootstrapUrl`; il gateway le rifiuta all'avvio. Prima di v2.1.232, il gateway accettava un elenco fisso di 11 chiavi di feature-gate, come `chatTabEnabled` e `disableAutoUpdates`, e rifiutava ogni altra chiave all'avvio. Prima di v2.1.227, il gateway rifiutava anche `chatTabEnabled` e `chatAdvancedFileAnalysisEnabled` all'avvio.974Aggiungi il blocco facoltativo `desktop` insieme a `cli` per impostare direttamente le impostazioni di Claude Desktop. Scrivi le impostazioni del [riferimento della configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop come nomi di chiave piatti. Escludi le chiavi che Claude Desktop legge solo da MDM o da file locali, come `bootstrapUrl`; il gateway le rifiuta all'avvio. Prima di v2.1.232, il gateway accettava un elenco fisso di 11 chiavi di feature gate, come `chatTabEnabled` e `disableAutoUpdates`, e rifiutava ogni altra chiave all'avvio. Prima di v2.1.227, il gateway rifiutava all'avvio anche `chatTabEnabled` e `chatAdvancedFileAnalysisEnabled`.

839 975

840```yaml theme={null}976```yaml theme={null}

841managed:977managed:

849 banner: { text: "Contractor build: internal use only" }985 banner: { text: "Contractor build: internal use only" }

850```986```

851 987

852Ogni chiave è facoltativa; Claude Desktop applica il suo valore predefinito per qualsiasi chiave che ometti. Il gateway convalida ogni blocco `desktop` all'avvio rispetto allo schema di configurazione che Claude Desktop stesso usa, quindi un errore emerge all'avvio del gateway come un errore che nomina la chiave piuttosto che raggiungere ogni desktop connesso. Il gateway fallisce all'avvio quando un blocco contiene:988Ogni chiave è facoltativa; Claude Desktop applica il proprio valore predefinito per qualsiasi chiave che ometti. Il gateway convalida ogni blocco `desktop` all'avvio rispetto allo schema di configurazione che Claude Desktop stesso usa, quindi un errore emerge all'avvio del gateway come un errore che nomina la chiave anziché raggiungere ogni desktop connesso. Il gateway fallisce all'avvio quando un blocco contiene:

853 989

854* Una chiave sconosciuta990* Una chiave sconosciuta

855* Una chiave riconosciuta il cui valore Claude Desktop rifiuterebbe o lascerebbe cadere silenziosamente, come un valore vuoto o un nome di sub-chiave errato all'interno di una voce annidata. Prima di v2.1.260, il gateway lasciava cadere silenziosamente un campo errato all'interno di un oggetto annidato di una voce `managedMcpServers` o `orgPluginSettings` invece di fallire all'avvio.991* Una chiave riconosciuta il cui valore Claude Desktop rifiuterebbe o scarterebbe silenziosamente, come un valore vuoto o una sotto-chiave scritta in modo errato all'interno di una voce annidata. Prima di v2.1.260, il gateway scartava silenziosamente un campo scritto in modo errato all'interno di un oggetto annidato di una voce `managedMcpServers` o `orgPluginSettings` invece di fallire all'avvio.

856* Una chiave che il gateway calcola da solo: la connessione di inferenza, l'elenco dei modelli e l'inoltro OTLP. Configura quelli attraverso [`upstreams`](#upstreams), [`models`](#models) e la sezione [`telemetry`](#telemetry) `forward_to`.992* Una chiave che il gateway calcola da solo: la connessione di inferenza, l'elenco dei modelli e l'inoltro OTLP. Configurali tramite [`upstreams`](#upstreams), [`models`](#models) e il `forward_to` della sezione [`telemetry`](#telemetry).

857* Un alias legacy di una chiave attuale. Nell'errore di avvio, il gateway nomina la chiave canonica da scrivere.993* Un alias legacy di una chiave attuale. Nell'errore di avvio, il gateway nomina la chiave canonica da scrivere.

858 994

859Se usi un valore o una forma di voce deprecata, come una voce `managedMcpServers` senza `transport`, il gateway si avvia e registra un avviso che nomina la sostituzione.995Se usi un valore o una forma di voce deprecati, come una voce `managedMcpServers` senza `transport`, il gateway si avvia e registra un avviso che nomina la sostituzione.

996

997Il gateway convalida un blocco `desktop` rispetto allo schema incluso nella sua versione installata, come fa con il blocco `cli`. Per consegnare un'impostazione introdotta da una versione più recente di Claude Desktop, aggiorna prima il gateway. Ad esempio, `userPluginMarketplacesEnabled` e `userPluginUploadsEnabled` hanno bisogno di Claude Code v2.1.260 o successivo sul server del gateway e di Claude Desktop 1.37937.0 o successivo sulle macchine dei membri.

860 998

861Il gateway convalida un blocco `desktop` rispetto allo schema fornito con la sua versione installata, come fa con il blocco `cli`. Per consegnare un'impostazione introdotta da una versione più recente di Claude Desktop, aggiorna il gateway prima. Ad esempio, `userPluginMarketplacesEnabled` e `userPluginUploadsEnabled` hanno bisogno di Claude Code v2.1.260 o successivo sul server del gateway e Claude Desktop 1.37937.0 o successivo sulle macchine dei membri.999`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` e `sshClientPath` hanno bisogno di Claude Code v2.1.281 o successivo sul server del gateway. Lo stesso vale per il valore `required` di `microsoftAuthBroker` e per il campo `continuousAccessEvaluation` di una voce `managedMcpServers` di Microsoft 365. Le versioni di Claude Desktop precedenti al valore `required` lo leggono come `disabled`, quindi imposta `required` solo dopo che il Claude Desktop di ogni membro lo supporta. Il [riferimento della configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop elenca la versione che per prima legge ciascuna chiave.

862 1000

863Se imposti `orgPluginSettings` nel blocco `desktop` di una policy, il gateway lo serve nella forma di array che Claude Desktop 1.15200.0 e successivo legge. I desktop più vecchi ignorano l'array e non applicano alcuna policy di strumento plugin, quindi aggiorna i membri a 1.15200.0 o successivo prima di fare affidamento su di esso.1001Se imposti `orgPluginSettings` nel blocco `desktop` di una policy, il gateway lo serve nella forma di array che Claude Desktop 1.15200.0 e successivi leggono. I desktop più vecchi ignorano l'array e non applicano alcuna policy sugli strumenti dei plugin, quindi aggiorna i membri a 1.15200.0 o successivo prima di farvi affidamento.

864 1002

865Il gateway riempie le chiavi che il blocco `desktop` di una policy non imposta dal blocco `desktop` della catch-all `match: {}`, nello stesso modo in cui riempie il blocco `cli` di una policy dalla base. Se imposti `disabledBuiltinTools` o `builtinToolPolicy` sia nella base che in una policy per ruolo, il gateway mantiene la restrizione della base:1003Il gateway completa le chiavi che il blocco `desktop` di una policy non imposta con quelle del blocco `desktop` del catch-all `match: {}`, nello stesso modo in cui completa il blocco `cli` di una policy dalla base. Se imposti `disabledBuiltinTools` o `builtinToolPolicy` sia nella base che in una policy per ruolo, il gateway mantiene la restrizione della base:

866 1004

867* `disabledBuiltinTools`: il gateway usa l'unione dell'elenco della base e dell'elenco della policy1005* `disabledBuiltinTools`: il gateway usa l'unione dell'elenco della base e dell'elenco della policy

868* `builtinToolPolicy`: se imposti uno strumento a un valore diverso da `allow` nella base, il gateway mantiene quel valore anche se imposti `allow` per lo stesso strumento in una policy per ruolo1006* `builtinToolPolicy`: se imposti uno strumento a un valore diverso da `allow` nella base, il gateway mantiene quel valore anche se imposti `allow` per lo stesso strumento in una policy per ruolo

869 1007

870Per ogni altra chiave, se la imposti nella policy per ruolo, il gateway usa il valore della policy per ruolo. Il gateway sostituisce un array o un oggetto annidato come `banner` interamente, quindi se imposti `banner.text` in una policy per ruolo, il gateway elimina il `banner.backgroundColor` della base.1008Per ogni altra chiave, se la imposti nella policy per ruolo, il gateway usa il valore della policy per ruolo. Il gateway sostituisce per intero un array o un oggetto annidato come `banner`, quindi se imposti `banner.text` in una policy per ruolo, il gateway elimina il `banner.backgroundColor` della base.

871 1009

872Se non distribuisci Claude Desktop, lascia `desktop` completamente fuori dalle tue policy; il gateway restituisce quindi 404 da `/user/bootstrap` per ogni utente.1010Se non distribuisci Claude Desktop, lascia `desktop` completamente fuori dalle tue policy; il gateway restituisce quindi 404 da `/user/bootstrap` per ogni utente.

873 1011

1012<h4 id="extended-context-in-claude-desktop">

1013 Contesto esteso in Claude Desktop

1014</h4>

1015

1016Se servi [Claude Desktop](#claude-desktop-overlay) dal gateway, il suo selettore di modelli offre un'opzione di contesto 1M per ogni modello elencato che può essere eseguito con una finestra di contesto da 1M. Tra questi ci sono Claude Opus 4.6 e successivi, Claude Sonnet 4.6 e successivi, e i modelli Fable. L'opzione è la variante `[1m]` del modello, descritta in [Contesto esteso](/docs/it/model-config#extended-context). Hai bisogno di Claude Code v2.1.284 o successivo sul server del gateway.

1017

1018Una voce [`models`](#models) non ottiene l'opzione 1M quando:

1019

1020* Un upstream che può servire la voce la mappa a un modello senza supporto 1M, incluso un upstream che il gateway raggiunge solo in caso di failover

1021* Né il suo `id` né alcuno dei suoi valori `upstream_model` nomina un modello Claude, come un alias personalizzato instradato verso l'ARN di un profilo di inferenza dell'applicazione

1022

1023Per cambiare ciò che offre il selettore, usa uno di questi metodi:

1024

1025* **Avvia gli utenti sull'opzione 1M**: imposta `modelPrefer1mContext: true` nel blocco `desktop` della policy. Gli utenti che non hanno ancora scelto un modello iniziano con l'opzione 1M quando il primo modello elencato ne ha una. Gli utenti che hanno già scelto un modello mantengono la loro scelta.

1026* **Offri l'opzione manualmente**: fallo se il server del gateway esegue una versione precedente a v2.1.284, o se una voce non nomina alcun modello Claude. Elenca il modello due volte in `models`, una volta con il suo ID semplice e una volta con `[1m]` aggiunto, entrambe con la stessa mappa `upstream_model`. Claude Desktop mostra la coppia come un unico modello con un'opzione 1M. Il gateway serve una voce `[1m]` senza controllarla, quindi aggiungine una solo per un modello che i tuoi upstream servono a 1M.

1027

1028Questo esempio offre l'opzione manualmente per un alias personalizzato instradato verso un profilo di inferenza dell'applicazione, e avvia i nuovi utenti su di essa:

1029

1030```yaml theme={null}

1031models:

1032 - id: corp-sonnet

1033 upstream_model:

1034 bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

1035 - id: corp-sonnet[1m]

1036 upstream_model:

1037 bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

1038

1039managed:

1040 policies:

1041 - match: {}

1042 desktop:

1043 modelPrefer1mContext: true

1044```

1045

1046<h5 id="remove-the-1m-option">

1047 Rimuovi l'opzione 1M

1048</h5>

1049

1050Per rimuovere l'opzione dal selettore, imposta `CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"` nel blocco `env` sotto la chiave `cli` della policy. Se hai anche elencato una voce il cui `id` termina con `[1m]`, il gateway la serve comunque, quindi elimina anche quella voce.

1051

1052La variabile raggiunge anche le sessioni da terminale degli sviluppatori a cui la policy corrisponde. Per ciò che cambia lì, vedi [Contesto esteso](/docs/it/model-config#extended-context).

1053

874<h4 id="precedence-with-other-managed-sources">1054<h4 id="precedence-with-other-managed-sources">

875 Precedence with other managed sources1055 Precedenza rispetto ad altre fonti gestite

876</h4>1056</h4>

877 1057

878Se un dispositivo ha anche una policy consegnata da MDM o un `managed-settings.json` locale, le impostazioni consegnate dal gateway hanno la priorità. [Precedence within the managed tier](/docs/it/managed-settings#precedence-within-the-managed-tier) sulla pagina delle impostazioni gestite dice quando si applicano le fonti locali, e ha le [chiavi che Claude Code legge da ogni fonte admin](/docs/it/managed-settings#keys-read-from-every-admin-source) indipendentemente da quale fonte ha selezionato, come le chiavi di blocco della sandbox, `forceRemoteSettingsRefresh` e il `env` per variabile. Un [`policyHelper`](/docs/it/settings-reference#policyhelper) configurato in un profilo MDM o nel file delle impostazioni gestite viene eseguito solo quando il gateway non consegna impostazioni; la voce dice cosa sostituisce il suo output.1058Se un dispositivo ha anche una policy consegnata tramite MDM o un `managed-settings.json` locale, le impostazioni consegnate dal gateway hanno la precedenza. [Precedenza all'interno del livello gestito](/docs/it/managed-settings#precedence-within-the-managed-tier) nella pagina delle impostazioni gestite indica quando si applicano le fonti locali, e riporta le [chiavi che Claude Code legge da ogni fonte di amministrazione](/docs/it/managed-settings#keys-read-from-every-admin-source) indipendentemente dalla fonte selezionata, come le chiavi di blocco della sandbox, `forceRemoteSettingsRefresh` e il merge di `env` per variabile. Un [`policyHelper`](/docs/it/settings-reference#policyhelper) configurato in un profilo MDM o nel file delle impostazioni gestite viene eseguito solo quando il gateway non consegna impostazioni; la voce indica cosa sostituisce il suo output.

879 1059

880Gli host di incorporamento come [Claude Desktop](/docs/it/desktop) possono fornire policy attraverso l'opzione SDK `managedSettings`. [Parent settings from embedding hosts](/docs/it/managed-settings#parent-settings-from-embedding-hosts) dice quando Claude Code lo applica, e [Restrict parent settings](/docs/it/claude-apps-gateway#restrict-parent-settings) elenca quali impostazioni di direzione di autorizzazione si applicano ancora senza i blocchi `allowManaged*Only`.1060Gli host di incorporamento come [Claude Desktop](/docs/it/desktop) possono fornire policy tramite l'opzione SDK `managedSettings`. [Impostazioni padre dagli host di incorporamento](/docs/it/managed-settings#parent-settings-from-embedding-hosts) indica quando Claude Code le applica, e [Limitare le impostazioni padre](/docs/it/claude-apps-gateway#restrict-parent-settings) elenca quali impostazioni in direzione di autorizzazione si applicano comunque senza i blocchi `allowManaged*Only`.

881 1061

882Le policy 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 policy.1062Le policy del gateway si applicano a ogni invocazione di Claude Code sulla macchina, incluse le esecuzioni non interattive `claude -p` e le sessioni avviate dall'Agent SDK. Se il gateway non è raggiungibile all'avvio, le sessioni con accesso effettuato escono con un errore anziché essere eseguite senza la loro policy.

883 1063

884<h3 id="telemetry">1064<h3 id="telemetry">

885 `telemetry`1065 `telemetry`

886</h3>1066</h3>

887 1067

888La CLI invia metriche, log e, quando abilitato, tracce al gateway, che le inoltra verbatim a ogni destinazione configurata. Le esportazioni utilizzano OpenTelemetry Protocol (OTLP) su HTTP. Per saltare l'inoltro e avere sessioni esportate direttamente al tuo collettore, [nomina il collettore in una policy](#export-directly-to-your-collector). Vedi [Monitoring usage](/docs/it/monitoring-usage) per le metriche e gli eventi che la CLI emette.1068La CLI invia metriche, log e, quando abilitate, tracce al gateway, che le inoltra alla lettera a ogni destinazione configurata. Le esportazioni utilizzano OpenTelemetry Protocol (OTLP) su HTTP. Per saltare l'inoltro e far esportare le sessioni direttamente al tuo collettore, [nomina il collettore in una policy](#export-directly-to-your-collector). Vedi [Monitoraggio dell'utilizzo](/docs/it/monitoring-usage) per le metriche e gli eventi che la CLI emette.

889 1069

890La 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 di costo e utilizzo per sviluppatore funziona quindi senza configurazione lato sviluppatore.1070Nelle sessioni con accesso effettuato tramite `/login`, la CLI contrassegna 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 di costi e utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore.

891 1071

892[Claude Desktop](#claude-desktop-overlay) e le sessioni Cowork firmate attraverso il gateway timbrano la loro telemetria con `user.email` e `user.groups` insieme a `enduser.id`, quindi puoi coprire l'utilizzo di terminale, Desktop e Cowork con una query su `user.email` o `user.groups`. `user.groups` è l'elenco di gruppi IdP separato da virgole.1072Le sessioni di [Claude Desktop](#claude-desktop-overlay) e Cowork con accesso effettuato tramite il gateway contrassegnano la loro telemetria con `user.email` e `user.groups` insieme a `enduser.id`, quindi puoi coprire l'utilizzo da terminale, Desktop e Cowork con un'unica query su `user.email` o `user.groups`. `user.groups` è l'elenco dei gruppi IdP separati da virgole.

893 1073

894Desktop e Cowork telemetry portano anche `enduser.sub`, il claim `sub` che il tuo provider di identità emette per l'utente, che rimane lo stesso quando l'email di un utente cambia. Le sessioni di terminale timbrano lo stesso valore sotto `user.id`, quindi una query che corrisponde a `enduser.sub` rispetto al terminale `user.id` copre l'utilizzo di terminale, Desktop e Cowork di un utente insieme. Sulle esportazioni Desktop e Cowork, `user.id` è un identificatore anonimo, non il soggetto.1074La telemetria di Desktop e Cowork contiene anche `enduser.sub`, il claim `sub` che il tuo provider di identità emette per l'utente, che rimane lo stesso quando l'email di un utente cambia. Le sessioni da terminale riportano lo stesso valore sotto `user.id`, quindi una query che confronta `enduser.sub` con `user.id` del terminale copre insieme l'utilizzo da terminale, Desktop e Cowork di un utente. Nelle esportazioni di Desktop e Cowork, `user.id` è un identificatore anonimo, non il soggetto.

895 1075

896Come tutti i dati OpenTelemetry da Claude Code, questi attributi vanno solo alle destinazioni che la tua organizzazione configura, mai ad Anthropic.1076Come tutti i dati OpenTelemetry di Claude Code, questi attributi vanno solo alle destinazioni che la tua organizzazione configura, mai ad Anthropic.

897 1077

898Se l'elenco di gruppi di un utente è più lungo di 255 caratteri una volta codificato in percentuale, o un nome di gruppo contiene una virgola o un segno di uguale, il gateway lascia `user.groups` fuori dalla telemetria Desktop e Cowork di quell'utente piuttosto che troncarla. Le sessioni di terminale di quell'utente portano comunque l'elenco completo.1078Se l'elenco dei gruppi di un utente supera i 255 caratteri una volta codificato in percentuale, o un nome di gruppo contiene una virgola o un segno di uguale, il gateway omette `user.groups` dalla telemetria Desktop e Cowork di quell'utente anziché troncarlo. Le sessioni da terminale di quell'utente riportano comunque l'elenco completo.

899 1079

900Il gateway lascia `enduser.sub` fuori quando il soggetto è più lungo di 255 caratteri una volta codificato in percentuale, o contiene uno spazio, un carattere al di fuori dell'ASCII stampabile, o uno di `,` `;` `=` `\` `"` `%`. La telemetria Desktop e Cowork di quell'utente mantiene i suoi altri attributi.1080Il gateway omette `enduser.sub` quando il soggetto supera i 255 caratteri una volta codificato in percentuale, o contiene uno spazio, un carattere al di fuori dell'ASCII stampabile, o uno tra `,` `;` `=` `\` `"` `%`. La telemetria Desktop e Cowork di quell'utente mantiene i suoi altri attributi.

901 1081

902Hai bisogno di Claude Code v2.1.265 o successivo sul server del gateway per `user.email` e `user.groups` sulla telemetria Desktop e Cowork, e Claude Desktop 1.24012 o successivo su ogni macchina dello sviluppatore per `user.groups`.1082Hai bisogno di Claude Code v2.1.265 o successivo sul server del gateway per `user.email` e `user.groups` nella telemetria di Desktop e Cowork, e di Claude Desktop 1.24012 o successivo sulla macchina di ogni sviluppatore per `user.groups`.

903 1083

904Hai bisogno di Claude Code v2.1.274 o successivo sul server del gateway per `enduser.sub`.1084Hai bisogno di Claude Code v2.1.274 o successivo sul server del gateway per `enduser.sub`.

905 1085

919```1099```

920 1100

921<Warning>1101<Warning>

922 Ogni destinazione opta in `metrics`, `logs` e `traces` indipendentemente, e il valore predefinito è solo metriche. I segnali differiscono in sensibilità:1102 Ogni destinazione abilita `metrics`, `logs` e `traces` in modo indipendente, e il valore predefinito è solo le metriche. I segnali differiscono per sensibilità:

923 1103

924 * **Metrics**: contatori aggregati come conteggi di token, conteggi di richieste e latenza1104 * **Metriche**: contatori aggregati come conteggi di token, conteggi di richieste e latenza

925 * **Logs and traces**: possono portare comandi bash completi, input di strumenti e percorsi di file, coprendo tutto ciò che Claude Code fa sulla macchina di uno sviluppatore1105 * **Log e tracce**: possono contenere comandi Bash completi, input degli strumenti e percorsi di file, coprendo tutto ciò che Claude Code fa sulla macchina di uno sviluppatore

926 1106

927 Abilita log e tracce solo su destinazioni con i controlli di accesso e la policy di conservazione che i dati garantiscono.1107 Abilita log e tracce solo su destinazioni con i controlli di accesso e la policy di conservazione che quei dati richiedono.

928</Warning>1108</Warning>

929 1109

930Ogni URL `forward_to` deve usare `https://`, con un'eccezione per un collettore sull'interfaccia loopback del gateway stesso:1110Ogni URL `forward_to` deve usare `https://`, con un'eccezione per un collettore sull'interfaccia loopback del gateway stesso:

931 1111

932* `http://localhost:<port>` passa la convalida della configurazione, ma la [SSRF guard](/docs/it/claude-apps-gateway-deploy#threat-model-summary) blocca ogni esportazione con `ECONNREFUSED_SSRF` a meno che non imposti `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` nell'ambiente del gateway1112* `http://localhost:<port>` supera la convalida della configurazione, ma la [protezione SSRF](/docs/it/claude-apps-gateway-deploy#threat-model-summary) blocca ogni esportazione con `ECONNREFUSED_SSRF` a meno che non imposti `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` nell'ambiente del gateway

933* `http://127.0.0.1:<port>` o `http://[::1]:<port>` fallisce all'avvio a meno che quella variabile non sia impostata1113* `http://127.0.0.1:<port>` o `http://[::1]:<port>` fa fallire l'avvio a meno che quella variabile non sia impostata

934 1114

935Per un collettore in-cluster, esponilo su HTTPS al suo indirizzo interno, o eseguilo come sidecar con la variabile impostata.1115Per un collettore interno al cluster, esponilo su HTTPS al suo indirizzo interno, o eseguilo come sidecar con la variabile impostata.

936 1116

937Quando `HTTPS_PROXY` è impostato, il gateway invia le esportazioni attraverso quel proxy.1117Quando `HTTPS_PROXY` è impostato, il gateway invia le esportazioni attraverso quel proxy.

938 1118

939Per raggiungere un collettore interno direttamente, aggiungilo a `NO_PROXY` per nome host o per un dominio con un punto iniziale come `.internal.example.com`, che richiede Claude Code v2.1.277 o successivo sul server del gateway. Assicurati che il gateway possa raggiungere il collettore senza il proxy. Una voce senza un punto iniziale corrisponde solo a quel nome esatto, non ai nomi sotto di esso. Gli intervalli CIDR non corrispondono.1119Per raggiungere direttamente un collettore interno, aggiungilo a `NO_PROXY` per nome host o per un dominio con un punto iniziale come `.internal.example.com`, il che richiede Claude Code v2.1.277 o successivo sul server del gateway. Assicurati che il gateway possa raggiungere il collettore senza il proxy. Una voce senza punto iniziale corrisponde solo a quel nome esatto, non ai nomi sotto di esso. Gli intervalli CIDR non corrispondono.

940 1120

941Con [proxy-only egress](#proxy-only-egress) attivato, consenti il collettore nel proxy invece, poiché qualsiasi voce `NO_PROXY` mantiene l'uscita solo proxy disattivata.1121Con l'[uscita solo tramite proxy](#proxy-only-egress) attivata, consenti invece il collettore nel proxy, poiché qualsiasi voce `NO_PROXY` mantiene disattivata l'uscita solo tramite proxy.

942 1122

943La telemetria è disattivata nella CLI per impostazione predefinita. Quando imposti sia `telemetry.forward_to` che `listen.public_url`, il gateway la attiva per i client connessi spingendo sei variabili di ambiente attraverso `/managed/settings`:1123La telemetria è disattivata nella CLI per impostazione predefinita. Quando imposti sia `telemetry.forward_to` che `listen.public_url`, il gateway la attiva per i client connessi inviando sei variabili d'ambiente tramite `/managed/settings`:

944 1124

945* `CLAUDE_CODE_ENABLE_TELEMETRY=1`1125* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

946* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` e `OTEL_TRACES_EXPORTER`, ognuno impostato a `otlp` se almeno una destinazione `forward_to` abilita quel segnale e a `none` altrimenti1126* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` e `OTEL_TRACES_EXPORTER`, ognuna impostata a `otlp` se almeno una destinazione `forward_to` abilita quel segnale e a `none` altrimenti

947* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`1127* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

948* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`1128* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

949 1129

950Quando aggiungi le tue etichette personalizzate]\(#add-your-own-labels), il gateway spinge anche `OTEL_RESOURCE_ATTRIBUTES`.1130Quando [aggiungi le tue etichette](#add-your-own-labels), il gateway invia anche `OTEL_RESOURCE_ATTRIBUTES`.

951 1131

952Prima di Claude Code v2.1.265 sul server del gateway, il gateway spingeva tutti e tre i selettori di esportazione come `otlp`, incluso per i segnali che nessuna destinazione ha optato.1132Prima di Claude Code v2.1.265 sul server del gateway, il gateway inviava tutti e tre i selettori di esportazione come `otlp`, anche per i segnali che nessuna destinazione aveva abilitato.

953 1133

954L'endpoint spinto è costruito dall'URL pubblico, quindi metriche e log non hanno bisogno di configurazione OTEL da sviluppatori o policy.1134L'endpoint inviato è costruito dall'URL pubblico, quindi metriche e log non hanno bisogno di configurazione OTEL da parte di sviluppatori o policy.

955 1135

956Gli sviluppatori firmati attraverso `/login` non possono reindirizzare le esportazioni con la loro configurazione OTEL:1136Gli sviluppatori che hanno effettuato l'accesso tramite `/login` non possono reindirizzare le esportazioni con la propria configurazione OTEL:

957 1137

958* **Variabili impostate localmente**: Claude Code applica le variabili spinte al livello gestito, quindi ognuna sostituisce il valore che uno sviluppatore imposta per essa localmente.1138* **Variabili impostate localmente**: Claude Code applica le variabili inviate al livello gestito, quindi ognuna sovrascrive il valore che uno sviluppatore imposta localmente per essa.

959* **Endpoint configurati localmente**: con l'esportazione OTLP/HTTP abilitata, la CLI ignora qualsiasi endpoint configurato localmente, indipendentemente dal fatto che il gateway abbia spinto le variabili di telemetria. Le sue esportazioni vanno al gateway a meno che una policy non [nomini il tuo collettore come endpoint](#export-directly-to-your-collector).1139* **Endpoint configurati localmente**: con l'esportazione OTLP/HTTP abilitata, la CLI ignora qualsiasi endpoint configurato localmente, indipendentemente dal fatto che il gateway abbia inviato le variabili di telemetria. Le sue esportazioni vanno al gateway a meno che una policy non [nomini il tuo collettore come endpoint](#export-directly-to-your-collector).

960 1140

961Senza una destinazione `forward_to` per un segnale, il gateway lo accetta e lo scarta. Se gli sviluppatori già esportano telemetria di Claude Code a uno dei tuoi collettori, aggiungilo come destinazione `forward_to`, con log o tracce abilitate se esportano quelli, in modo che continui a ricevere i loro dati dopo che si firmano. Per saltare l'inoltro invece, [nomina il collettore in una policy](#export-directly-to-your-collector).1141Senza una destinazione `forward_to` per un segnale, il gateway lo accetta e lo scarta. Se gli sviluppatori esportano già la telemetria di Claude Code a uno dei tuoi collettori, aggiungilo come destinazione `forward_to`, con log o tracce abilitati se esportano anche quelli, in modo che continui a ricevere i loro dati dopo che hanno effettuato l'accesso. Per saltare invece l'inoltro, [nomina il collettore in una policy](#export-directly-to-your-collector).

962 1142

963[Traces](/docs/it/monitoring-usage#traces-beta) richiedono anche `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` su ogni client. Impostalo nel blocco `env` di una policy gestita, poiché il gateway non lo spinge. Gli sviluppatori lo approvano nella stessa [security approval dialog](#managed) che l'endpoint spinto già attiva.1143Le [tracce](/docs/it/monitoring-usage#traces-beta) richiedono anche `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` su ogni client. Impostala nel blocco `env` di una policy gestita, poiché il gateway non la invia. Gli sviluppatori la approvano nella stessa [finestra di dialogo di approvazione di sicurezza](#managed) che l'endpoint inviato già attiva.

964 1144

965Impostalo a `1` solo nelle policy i cui gruppi vuoi tracciati. Una policy che non lo imposta eredita il valore dalla tua policy catch-all `match: {}` se quella policy ne imposta uno, per le [merge rules](#managed). Per impedire ai client di un gruppo di inviare tracce anche quando uno sviluppatore imposta la variabile localmente, impostala a `0` nella policy di quel gruppo.1145Impostala a `1` solo nelle policy i cui gruppi vuoi tracciare. Una policy che non la imposta eredita il valore dalla tua policy catch-all `match: {}` se quella policy ne imposta uno, secondo le [regole di merge](#managed). Per impedire ai client di un gruppo di inviare tracce anche quando uno sviluppatore imposta la variabile localmente, impostala a `0` nella policy di quel gruppo.

966 1146

967Sia la codifica protobuf che JSON OTLP vengono inoltrate, e qualsiasi backend compatibile con OpenTelemetry funziona come destinazione.1147Vengono inoltrate sia la codifica OTLP protobuf che quella JSON, e qualsiasi backend compatibile con OpenTelemetry funziona come destinazione.

968 1148

969<h4 id="add-your-own-labels">1149<h4 id="add-your-own-labels">

970 Add your own labels1150 Aggiungi le tue etichette

971</h4>1151</h4>

972 1152

973Per mettere etichette fisse come `service.namespace` o `deployment.environment.name` sulla telemetria delle sessioni firmate attraverso il gateway, imposta `telemetry.resource_attributes`. Ogni etichetta è un attributo di risorsa OpenTelemetry, e ogni destinazione riceve le stesse etichette.1153Per applicare etichette fisse come `service.namespace` o `deployment.environment.name` alla telemetria delle sessioni con accesso effettuato tramite il gateway, imposta `telemetry.resource_attributes`. Ogni etichetta è un attributo di risorsa OpenTelemetry, e ogni destinazione riceve le stesse etichette.

974 1154

975Le sessioni ottengono le etichette solo quando imposti anche `telemetry.forward_to` e `listen.public_url`. Questo esempio aggiunge due etichette:1155Le sessioni ottengono le etichette solo quando imposti anche `telemetry.forward_to` e `listen.public_url`. Questo esempio aggiunge due etichette:

976 1156

983 deployment.environment.name: prod1163 deployment.environment.name: prod

984```1164```

985 1165

986Il gateway rifiuta di avviarsi quando un'etichetta infrange una di queste regole, e l'errore di avvio nomina l'etichetta:1166Il gateway rifiuta di avviarsi quando un'etichetta viola una di queste regole, e l'errore di avvio nomina l'etichetta:

987 1167

988* I nomi usano solo lettere, cifre, `.`, `_` e `-`1168* I nomi usano solo lettere, cifre, `.`, `_` e `-`

989* I nomi non sono riservati. Confrontati in qualsiasi maiuscola, i nomi riservati sono tutto ciò che inizia con `user.`, `enduser.` o `identity.`, più `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version` e `wsl.version`1169* I nomi non sono riservati. Confrontati senza distinzione tra maiuscole e minuscole, i nomi riservati sono tutti quelli che iniziano con `user.`, `enduser.` o `identity.`, più `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version` e `wsl.version`

990* I valori sono ASCII stampabile non vuoto senza spazio e nessuno di `, ; = \ " %`1170* I valori sono ASCII stampabile non vuoto, senza spazi e senza nessuno tra `, ; = \ " %`

991* I valori sono al massimo 255 caratteri come il gateway li conta dopo la codifica percentuale, quindi `/`, `:` e `@` contano ciascuno come tre1171* I valori sono lunghi al massimo 255 caratteri secondo il conteggio del gateway dopo la codifica in percentuale, quindi `/`, `:` e `@` contano ciascuno come tre

992* I valori sono testo, quindi cita un numero, `true` o `false`1172* I valori sono testo, quindi metti tra virgolette un numero, `true` o `false`

993 1173

994Hai bisogno di Claude Code v2.1.281 o successivo sul server del gateway per impostare `telemetry.resource_attributes`. Un gateway precedente rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere la chiave, e rimuovi la chiave prima di eseguire il rollback a una versione precedente.1174Hai bisogno di Claude Code v2.1.281 o successivo sul server del gateway per impostare `telemetry.resource_attributes`. Un gateway precedente rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere la chiave, e rimuovi la chiave prima di eseguire il rollback a una versione precedente.

995 1175

996Le sessioni di terminale firmate attraverso `/login` ricevono le etichette come `OTEL_RESOURCE_ATTRIBUTES`, spinte con le altre [telemetry variables](#telemetry). Se imposti `OTEL_RESOURCE_ATTRIBUTES` nel blocco `env` di una policy, le sessioni di terminale che quella policy corrisponde ottengono quel valore invece delle etichette. Claude Desktop riceve le etichette dal gateway insieme a `user.email` e agli altri attributi di identità.1176Le sessioni da terminale con accesso effettuato tramite `/login` ricevono le etichette come `OTEL_RESOURCE_ATTRIBUTES`, inviata insieme alle altre [variabili di telemetria](#telemetry). Se imposti `OTEL_RESOURCE_ATTRIBUTES` nel blocco `env` di una policy, le sessioni da terminale a cui quella policy corrisponde ottengono quel valore invece delle etichette. Claude Desktop riceve le etichette dal gateway insieme a `user.email` e agli altri attributi di identità.

997 1177

998Claude Code copia anche ogni etichetta su ogni punto dati metrico, quindi puoi filtrare le metriche per essa in un backend che non indicizza gli attributi di risorsa. Per disattivare quella copia, vedi [Metrics cardinality control](/docs/it/monitoring-usage#metrics-cardinality-control).1178Claude Code copia anche ogni etichetta su ogni punto dati delle metriche, quindi puoi filtrare le metriche in base a essa in un backend che non indicizza gli attributi di risorsa. Per disattivare quella copia, vedi [Controllo della cardinalità delle metriche](/docs/it/monitoring-usage#metrics-cardinality-control).

999 1179

1000<h4 id="export-directly-to-your-collector">1180<h4 id="export-directly-to-your-collector">

1001 Export directly to your collector1181 Esporta direttamente al tuo collettore

1002</h4>1182</h4>

1003 1183

1004Per avere sessioni firmate attraverso `/login` inviare telemetria direttamente al tuo collettore invece che attraverso l'inoltro, imposta `OTEL_EXPORTER_OTLP_ENDPOINT` all'URL base `https://` del collettore nel blocco `env` di una [managed policy](#managed). Claude Code aggiunge `/v1/metrics`, `/v1/logs` o `/v1/traces` all'URL che imposti, come `https://otel-collector.example.com:4318`, ed esporta ogni segnale lì su OTLP/HTTP. Richiede Claude Code v2.1.265 o successivo su ogni macchina dello sviluppatore. I client precedenti esportano attraverso l'inoltro.1184Per far sì che le sessioni con accesso effettuato tramite `/login` inviino la telemetria direttamente al tuo collettore anziché attraverso l'inoltro, imposta `OTEL_EXPORTER_OTLP_ENDPOINT` sull'URL base `https://` del collettore nel blocco `env` di una [policy gestita](#managed). Claude Code aggiunge `/v1/metrics`, `/v1/logs` o `/v1/traces` all'URL che imposti, come `https://otel-collector.example.com:4318`, ed esporta lì ogni segnale su OTLP/HTTP. Richiede Claude Code v2.1.265 o successivo sulla macchina di ogni sviluppatore. I client precedenti esportano attraverso l'inoltro.

1005 1185

1006Per autenticarti al collettore, imposta `OTEL_EXPORTER_OTLP_HEADERS` nello stesso blocco `env`. Le sessioni non inviano mai il token di sessione del gateway dello sviluppatore a un collettore nominato in questo modo.1186Per autenticarti al collettore, imposta `OTEL_EXPORTER_OTLP_HEADERS` nello stesso blocco `env`. Le sessioni non inviano mai il token di sessione del gateway dello sviluppatore a un collettore nominato in questo modo.

1007 1187

1008Quando aggiungi o cambi questo endpoint in una policy, Claude Code chiede a ogni sviluppatore di approvarlo nella [security approval dialog](#managed) prima di applicarlo in una sessione interattiva.1188Quando aggiungi o modifichi questo endpoint in una policy, Claude Code chiede a ogni sviluppatore di approvarlo nella [finestra di dialogo di approvazione di sicurezza](#managed) prima di applicarlo in una sessione interattiva.

1009 1189

1010Claude Code controlla l'endpoint prima di esportare un segnale direttamente, e mantiene quel segnale sull'inoltro quando un controllo fallisce. I controlli includono:1190Claude Code controlla l'endpoint prima di esportare direttamente un segnale, e mantiene quel segnale sull'inoltro quando un controllo fallisce. I controlli includono:

1011 1191

1012* L'endpoint viene dal gateway stesso. Se imposti la stessa variabile in un profilo MDM o in un `managed-settings.json` locale, le esportazioni rimangono sull'inoltro.1192* L'endpoint proviene dal gateway stesso. Se imposti la stessa variabile in un profilo MDM o in un `managed-settings.json` locale, le esportazioni rimangono sull'inoltro.

1013* L'URL usa `https://`, o `http://` a un indirizzo loopback1193* L'URL usa `https://`, oppure `http://` verso un indirizzo loopback

1014* L'URL si risolve in un percorso che termina in `/v1/<signal>`, senza query o frammento. Claude Code costruisce quel percorso da solo dalla variabile generica. Usa una variabile per segnale come `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` come scritto, quindi includi il percorso completo lì.1194* L'URL si risolve in un percorso che termina con `/v1/<signal>`, senza query né frammento. Claude Code costruisce da solo quel percorso a partire dalla variabile generica. Usa una variabile per segnale come `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` così come è scritta, quindi lì includi il percorso completo.

1015* L'URL non è l'host del gateway stesso. Un endpoint indirizzato al gateway mantiene il percorso di inoltro e il suo token di sessione.1195* L'URL non è l'host del gateway stesso. Un endpoint indirizzato al gateway mantiene il percorso di inoltro e il suo token di sessione.

1016* Né tu né lo sviluppatore avete configurato [`otelHeadersHelper`](/docs/it/settings-reference#otelheadershelper) in nessuna fonte di impostazioni. Con un helper configurato, ogni segnale rimane sull'inoltro.1196* Né tu né lo sviluppatore avete configurato [`otelHeadersHelper`](/docs/it/settings-reference#otelheadershelper) in alcuna fonte di impostazioni. Con un helper configurato, ogni segnale rimane sull'inoltro.

1017 1197

1018L'endpoint che nomini cambia solo dove vanno le esportazioni. Scegli comunque quali segnali esportare affatto con i selettori `OTEL_*_EXPORTER`.1198L'endpoint che nomini cambia solo la destinazione delle esportazioni. Scegli comunque quali segnali esportare con i selettori `OTEL_*_EXPORTER`.

1019 1199

1020L'endpoint da solo non attiva l'esportazione, quindi imposta anche le variabili che lo fanno, a meno che il gateway non le spinga già:1200L'endpoint da solo non attiva l'esportazione, quindi imposta anche le variabili che lo fanno, a meno che il gateway non le invii già:

1021 1201

1022* Se il gateway già [spinge le variabili di telemetria](#telemetry), coprono l'abilitazione, i selettori e il protocollo, e il tuo endpoint esplicito sostituisce il valore `<public_url>` spinto. Imposta un selettore `OTEL_*_EXPORTER` a `otlp` tu stesso solo per un segnale che nessuna destinazione `forward_to` abilita.1202* Se il gateway [invia già le variabili di telemetria](#telemetry), queste coprono l'abilitazione, i selettori e il protocollo, e il tuo endpoint esplicito sovrascrive il valore `<public_url>` inviato. Imposta tu stesso un selettore `OTEL_*_EXPORTER` a `otlp` solo per un segnale che nessuna destinazione `forward_to` abilita.

1023* Se non lo fa, imposta anche `CLAUDE_CODE_ENABLE_TELEMETRY=1`, i selettori `OTEL_*_EXPORTER` e `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.1203* Se non lo fa, imposta anche `CLAUDE_CODE_ENABLE_TELEMETRY=1`, i selettori `OTEL_*_EXPORTER` e `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.

1024 1204

1025Quando lo sviluppatore si firma, o si firma a un gateway diverso, le esportazioni al collettore si fermano e Claude Code elimina ogni batch rimanente piuttosto che inviarlo.1205Quando lo sviluppatore esce, o accede a un gateway diverso, le esportazioni al collettore si interrompono e Claude Code scarta ogni batch rimanente anziché inviarlo.

1026 1206

1027<h4 id="when-a-destination-fails">1207<h4 id="when-a-destination-fails">

1028 When a destination fails1208 Quando una destinazione fallisce

1029</h4>1209</h4>

1030 1210

1031Il gateway non bufferizza, ritenta o archivia telemetria, quindi elimina un'esportazione che non raggiunge una destinazione piuttosto che consegnarla in ritardo. Ogni destinazione ha successo o fallisce da sola, e il client che esporta riceve una risposta di successo comunque, quindi una consegna fallita appare solo nel log del gateway.1211Il gateway non bufferizza, non riprova e non archivia la telemetria, quindi scarta un'esportazione che non raggiunge una destinazione anziché consegnarla in ritardo. Ogni destinazione riesce o fallisce per conto proprio, e il client che esporta riceve comunque una risposta di successo, quindi una consegna fallita appare solo nel log del gateway.

1032 1212

1033Dopo cinque consegne consecutive fallite a una destinazione, il gateway pausa l'inoltro a essa in tratti di 30 secondi, registrando ogni pausa, fino a quando una consegna ha successo. Qualsiasi risposta di errore, timeout o errore di connessione conta come una consegna fallita, tranne `400`, `413`, `415`, `422` e `431`, che significano che il collettore ha rifiutato il payload di quell'esportazione come malformato o troppo grande.1213Dopo cinque consegne consecutive fallite a una destinazione, il gateway sospende l'inoltro verso di essa per intervalli di 30 secondi, registrando ogni pausa, finché una consegna non riesce. Qualsiasi risposta di errore, timeout o errore di connessione conta come consegna fallita, tranne `400`, `413`, `415`, `422` e `431`, che indicano che il collettore ha rifiutato il payload di quell'esportazione perché malformato o troppo grande.

1034 1214

1035Un payload rifiutato non avanza né ripristina il conteggio dei fallimenti: il gateway continua a inoltrare alla destinazione e registra un avviso che la nomina e lo stato, al primo rifiuto della destinazione e ogni centesimo dopo.1215Un payload rifiutato non fa avanzare né azzera il conteggio dei fallimenti: il gateway continua a inoltrare alla destinazione e registra un avviso che la nomina insieme allo stato, al primo rifiuto della destinazione e poi ogni cento.

1036 1216

1037<h3 id="http-tuning">1217<h3 id="http-tuning">

1038 HTTP tuning1218 Ottimizzazione HTTP

1039</h3>1219</h3>

1040 1220

1041Quattro 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.1221Quattro blocchi facoltativi di primo livello, `access_control`, `limits`, `timeouts` e `rate_limits`, regolano la superficie HTTP. I valori predefiniti sono adatti alla maggior parte dei deploy.

1042 1222

1044| - | - | - | - |1224| - | - | - | - |

1045| `access_control` | `allow_cidrs` / `deny_cidrs` | vuoto | Inbound IP allow/deny per indirizzo client, dopo la risoluzione di `trusted_proxies`. `deny_cidrs` viene controllato per primo; un client che corrisponde viene rifiutato anche se `allow_cidrs` corrisponde anche. Se `allow_cidrs` è non vuoto il gateway è default-deny. `/healthz` e `/readyz` sono esenti da `allow_cidrs`. Quando un proxy attendibile invia una voce `X-Forwarded-For` che non è un indirizzo IP, il client reale è sconosciuto e il gateway registra un avviso una volta nominando cosa controllare. Dove uno dei due elenchi si applica alla richiesta, la rifiuta con `403` e motivo di audit `xff_unparseable`. Dove nessuno dei due lo fa, serve la richiesta e usa l'indirizzo del proxy stesso come IP client per i limiti di velocità per IP e audit. |1225| `access_control` | `allow_cidrs` / `deny_cidrs` | vuoto | Consenso/negazione degli IP in entrata per indirizzo client, dopo la risoluzione di `trusted_proxies`. `deny_cidrs` viene controllato per primo; un client a cui corrisponde viene rifiutato anche se corrisponde anche `allow_cidrs`. Se `allow_cidrs` non è vuoto, il gateway nega per impostazione predefinita. `/healthz` e `/readyz` sono esenti da `allow_cidrs`. Quando un proxy attendibile invia una voce `X-Forwarded-For` che non è un indirizzo IP, il client reale è sconosciuto e il gateway registra una sola volta un avviso che indica cosa controllare. Dove uno dei due elenchi si applica alla richiesta, la rifiuta con `403` e motivo di audit `xff_unparseable`. Dove nessuno dei due si applica, serve la richiesta e usa l'indirizzo del proxy stesso come IP del client per i rate limit per IP e per l'audit. |

1046| `limits` | `max_request_bytes` | 32 MiB | Max corpo della richiesta in entrata; le richieste di dimensioni eccessive ottengono `413` prima che il corpo sia bufferizzato. Aumenta per richieste di file o immagini di grandi dimensioni. |1226| `limits` | `max_request_bytes` | 32 MiB | Dimensione massima del corpo della richiesta in entrata; le richieste troppo grandi ottengono `413` prima che il corpo venga bufferizzato. Aumentalo per richieste con file o immagini di grandi dimensioni. |

1049| `timeouts` | `upstream_ttfb_ms` | 120000 | Max attesa per le intestazioni di risposta dell'upstream (tempo al primo byte). Il corpo della risposta quindi scorre senza cap di wall-clock. Si applica al percorso upstream diretto di Anthropic; su ogni altro provider il gateway attende fino a un'ora affinché la risposta inizi. |1229| `timeouts` | `upstream_ttfb_ms` | 120000 | Attesa massima per le intestazioni di risposta dell'upstream (tempo al primo byte). Il corpo della risposta viene poi trasmesso in streaming senza limite di tempo complessivo. Si applica al percorso upstream diretto di Anthropic; con ogni altro provider il gateway attende fino a un'ora che la risposta inizi. |

1050| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite di velocità per IP sull'endpoint di autorizzazione del dispositivo non autenticato. Aumenta per una grande organizzazione dietro un IP di uscita condiviso o NAT. [Large rollouts](/docs/it/claude-apps-gateway-deploy#large-rollouts) mostra come dimensionarlo. Questi limiti si applicano solo al flusso di accesso con concessione del dispositivo, non all'inferenza `/v1/messages`. Vedi [User-code brute-force resistance](/docs/it/claude-apps-gateway-deploy#user-code-brute-force-resistance). |1230| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Rate limit per IP sull'endpoint non autenticato di autorizzazione del dispositivo. Aumentalo per una grande organizzazione dietro un IP di uscita condiviso o NAT. [Distribuzioni su larga scala](/docs/it/claude-apps-gateway-deploy#large-rollouts) mostra come dimensionarlo. Questi limiti si applicano solo al flusso di accesso con concessione del dispositivo, non all'inferenza su `/v1/messages`. Vedi [Resistenza al brute force dei codici utente](/docs/it/claude-apps-gateway-deploy#user-code-brute-force-resistance). |

1051| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Limite di velocità per IP su invii di `user_code` su `/device`. È quello che impedisce a qualcuno di indovinare il codice di un altro sviluppatore. [Large rollouts](/docs/it/claude-apps-gateway-deploy#large-rollouts) mostra quanto aumentarlo. |1231| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Rate limit per IP sugli invii di `user_code` su `/device`. È ciò che impedisce a qualcuno di indovinare il codice di un altro sviluppatore. [Distribuzioni su larga scala](/docs/it/claude-apps-gateway-deploy#large-rollouts) mostra di quanto aumentarlo. |

1052 1232

1053Se lasci entrambi gli elenchi `access_control` vuoti, che è il valore predefinito, il gateway serve qualsiasi indirizzo client, quindi solo la tua rete limita chi può raggiungerlo. Questo è importante perché un gateway può spingere [impostazioni gestite](#managed) che eseguono comandi sulle macchine degli sviluppatori.1233Se lasci vuoti entrambi gli elenchi `access_control`, che è il valore predefinito, il gateway serve qualsiasi indirizzo client, quindi solo la tua rete limita chi può raggiungerlo. Questo è importante perché un gateway può inviare [impostazioni gestite](#managed) che eseguono comandi sulle macchine degli sviluppatori.

1054 1234

1055Mentre `allow_cidrs` è vuoto, il gateway avverte in due posti, senza cambiare come risponde a nessuna richiesta:1235Mentre `allow_cidrs` è vuoto, il gateway avverte in due punti, senza cambiare il modo in cui risponde alle richieste:

1056 1236

1057* **All'avvio**: un avviso nel log operativo consiglia di consentire solo gli intervalli privati `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` e `fc00::/7`, più qualsiasi altro intervallo interno da cui i tuoi sviluppatori si connettono. Se leghi il gateway a un indirizzo loopback e non imposti né `trusted_proxies` né `public_url`, come nello sviluppo locale, l'avviso non appare.1237* **All'avvio**: un avviso nel log operativo consiglia di consentire solo gli intervalli privati `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` e `fc00::/7`, più qualsiasi altro intervallo interno da cui si connettono i tuoi sviluppatori. Se associ il gateway a un indirizzo loopback e non imposti né `trusted_proxies` né `public_url`, come nello sviluppo locale, l'avviso non appare.

1058* **A runtime**: la prima volta che una richiesta arriva da un indirizzo al di fuori di quegli intervalli privati, il gateway registra un avviso e emette un evento di audit [`access.public_client`](/docs/it/claude-apps-gateway-deploy#logs) che porta l'IP client. Entrambi si attivano una volta per processo. Gli indirizzi link-local, `169.254.0.0/16` e `fe80::/10`, non contano come pubblici. Il gateway risponde a `/healthz` e `/readyz` prima che questo controllo venga eseguito, quindi i probe di salute da intervalli pubblici non lo attivano.1238* **In fase di esecuzione**: la prima volta che una richiesta arriva da un indirizzo al di fuori di quegli intervalli privati, il gateway registra un avviso ed emette un [evento di audit `access.public_client`](/docs/it/claude-apps-gateway-deploy#logs) contenente l'IP del client. Entrambi si attivano una volta per processo. Gli indirizzi link-local, `169.254.0.0/16` e `fe80::/10`, non contano come pubblici. Il gateway risponde a `/healthz` e `/readyz` prima che questo controllo venga eseguito, quindi i probe di salute da intervalli pubblici non lo attivano.

1059 1239

1060Entrambi i segnali usano l'indirizzo client come il gateway lo risolve. Se un load balancer, port-forward o tunnel inoltra il traffico e non è elencato in `listen.trusted_proxies`, il gateway vede l'indirizzo del relay, che di solito è privato, quindi né l'avviso a runtime né un elenco di autorizzazione privato lo cattura.1240Entrambi i segnali usano l'indirizzo del client così come il gateway lo risolve. Se un load balancer, un port-forward o un tunnel inoltra il traffico e non è elencato in `listen.trusted_proxies`, il gateway vede l'indirizzo dell'intermediario, che di solito è privato, quindi né l'avviso in fase di esecuzione né un'allowlist privata intercettano il traffico inoltrato attraverso di esso.

1061 1241

1062Dietro un tale front end, imposta [`listen.trusted_proxies`](#listen) per primo in modo che il gateway veda gli indirizzi client reali, e mantieni il gateway e tutto davanti ad esso irraggiungibile da internet pubblico indipendentemente.1242Dietro un front end di questo tipo, imposta prima [`listen.trusted_proxies`](#listen) in modo che il gateway veda gli indirizzi reali dei client, e in ogni caso mantieni il gateway e tutto ciò che si trova davanti a esso irraggiungibili dalla rete internet pubblica.

1063 1243

1064<h3 id="load_test_mode">1244<h3 id="load_test_mode">

1065 `load_test_mode`1245 `load_test_mode`

1066</h3>1246</h3>

1067 1247

1068Il blocco `load_test_mode` ti consente di testare il carico di un gateway senza chiamare un provider di modelli. Mentre è attivo, il gateway costruisce e firma ogni richiesta del provider come al solito, la scarta invece di inviarla, e trasmette una risposta in scatola attraverso il suo percorso di risposta normale. La risposta è testo di riempimento che inizia con una frase che dice che è in scatola.1248Il blocco `load_test_mode` ti consente di eseguire un test di carico su un gateway senza chiamare un provider di modelli. Mentre è attivo, il gateway costruisce e firma ogni richiesta al provider come di consueto, la scarta invece di inviarla e trasmette in streaming una risposta preconfezionata attraverso il suo normale percorso di risposta. La risposta è testo di riempimento che inizia con una frase che dichiara che è preconfezionata.

1069 1249

1070Richiede Claude Code v2.1.282 o successivo sul server del gateway. Una versione precedente rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere il blocco, e rimuovi il blocco prima di eseguire il rollback.1250Richiede Claude Code v2.1.282 o successivo sul server del gateway. Un gateway precedente rifiuta di avviarsi quando trova la chiave. Aggiorna ogni replica prima di aggiungere il blocco, e rimuovi il blocco prima di eseguire il rollback.

1071 1251

1072L'esempio seguente attiva la modalità con i valori predefiniti, una risposta di circa 750 token di testo trasmessi in circa 10 secondi:1252L'esempio seguente attiva la modalità con i valori predefiniti, una risposta di circa 750 token di testo trasmessa in streaming in circa 10 secondi:

1073 1253

1074```yaml theme={null}1254```yaml theme={null}

1075load_test_mode:1255load_test_mode:

1080 1260

1082| - | - | - |1262| - | - | - |

1083| `enabled` | Sì | `true` attiva la modalità. `false` mantiene i tuoi numeri nel file con la modalità disattivata. Il gateway rifiuta di avviarsi se il blocco è presente senza di esso. |1263| `enabled` | Sì | `true` attiva la modalità. `false` mantiene i tuoi valori nel file con la modalità disattivata. Il gateway rifiuta di avviarsi se il blocco è presente senza di esso. |

1084| `reply_tokens` | No | Predefinito `750`. Approssimativamente quanti token di testo ogni risposta in scatola porta, un numero intero da 1 a 100000. |1264| `reply_tokens` | No | Predefinito `750`. Circa quanti token di testo contiene ogni risposta preconfezionata, un numero intero da 1 a 100000. |

1085| `reply_seconds` | No | Predefinito `9.5`. Quanto tempo impiega una risposta trasmessa, da 0 a 600. `0` invia l'intera risposta in una volta. Una risposta a una richiesta non trasmessa torna sempre in una volta. |1265| `reply_seconds` | No | Predefinito `9.5`. Quanto dura una risposta in streaming, da 0 a 600. `0` invia l'intera risposta in una volta. La risposta a una richiesta non in streaming torna sempre in una volta. |

1086 1266

1087Un test di carico in questa modalità copre il gateway, il tuo Postgres e tutto davanti al gateway. Non copre i limiti, la velocità o il percorso di rete del provider.1267Un test di carico in questa modalità copre il gateway, il tuo Postgres e tutto ciò che si trova davanti al gateway. Non copre i limiti, la velocità o il percorso di rete del provider.

1088 1268

1089Nessuna richiesta di modello viene inviata al provider, quindi la CPU di una replica per richiesta è una stima e legge inferiore alla produzione, che crittografa anche il suo traffico al provider. Conferma un conteggio di replica con un piccolo pilota rispetto al provider reale. Prima di v2.1.283, la stima legge molto più bassa.1269Nessuna richiesta di modello viene inviata al provider, quindi la CPU per richiesta di una replica è una stima e risulta inferiore a quella di produzione, dove la replica cifra anche il traffico verso il provider. Conferma il numero di repliche con un piccolo pilota sul provider reale. Prima di v2.1.283, la stima risulta molto più bassa.

1090 1270

1091Mentre la modalità è attiva, una richiesta può portare un header `x-load-test-user` che contiene un numero intero di fino a sette cifre. Il gateway conta ogni numero come uno sviluppatore separato, con l'email e i gruppi dello sviluppatore il cui token è venuto con la richiesta.1271Mentre la modalità è attiva, una richiesta può contenere un'intestazione `x-load-test-user` con un numero intero di al massimo sette cifre. Il gateway conta ogni numero come uno sviluppatore separato, con l'email e i gruppi dello sviluppatore il cui token accompagnava la richiesta.

1092 1272

1093Dai alla distribuzione del test di carico il suo database vuoto, perché il gateway rifiuta di avviarsi con la modalità attiva rispetto a un database in cui uno sviluppatore ha già speso qualcosa.1273Assegna al deploy del test di carico un database vuoto dedicato, perché il gateway rifiuta di avviarsi con la modalità attiva su un database in cui uno sviluppatore abbia già speso qualcosa.

1094 1274

1095<Warning>1275<Warning>

1096 Non attivare mai questo per un gateway che gli sviluppatori usano. Ogni richiesta ottiene la risposta in scatola e nessun modello viene chiamato. Il gateway registra un avviso `load_test_mode is on` all'avvio e contrassegna ogni evento di audit [`inference`](/docs/it/claude-apps-gateway-deploy#logs) con `load_test: true` mentre la modalità è attiva.1276 Non attivarla mai su un gateway usato dagli sviluppatori. Ogni richiesta ottiene la risposta preconfezionata e nessun modello viene chiamato. Il gateway registra un avviso `load_test_mode is on` all'avvio e contrassegna ogni [evento di audit](/docs/it/claude-apps-gateway-deploy#logs) `inference` con `load_test: true` mentre la modalità è attiva.

1097</Warning>1277</Warning>

1098 1278

1099<h2 id="complete-example">1279<h2 id="complete-example">

1100 Esempio completo1280 Esempio completo

1101</h2>1281</h2>

1102 1282

1103Questo config di riferimento completo esercita ogni sezione principale; i blocchi di [sintonizzazione HTTP](#http-tuning) mantengono i loro valori predefiniti. Copiatelo, eliminate ciò che non vi serve e riempite i vostri valori. La configurazione nella [Guida rapida](/docs/it/claude-apps-gateway#quickstart) è una versione minima di questa.1283Questo config di riferimento completo esercita ogni sezione principale; i blocchi di [sintonizzazione HTTP](#http-tuning) mantengono i loro valori predefiniti. Copialo, elimina ciò che non ti serve e inserisci i tuoi valori. La configurazione nella [Guida rapida](/docs/it/claude-apps-gateway#quickstart) è una versione minima di questa.

1104 1284

1105```yaml gateway.yaml theme={null}1285```yaml gateway.yaml theme={null}

1106# Run with:1286# Run with:

1148 postgres_url: ${GATEWAY_POSTGRES_URL}1328 postgres_url: ${GATEWAY_POSTGRES_URL}

1149 # max_connections: 51329 # max_connections: 5

1150 # connect_timeout_seconds: 51330 # connect_timeout_seconds: 5

1331 # readiness_grace_seconds: 300 # keep passing the readiness check through a database failover

1151 1332

1152# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)1333# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)

1153# and per-developer spend enforcement on /v1/messages. Omit to disable.1334# and per-developer spend enforcement on /v1/messages. Omit to disable.

1255 Impostazioni gestite lato client1436 Impostazioni gestite lato client

1256</h2>1437</h2>

1257 1438

1258Tutto quanto sopra configura il server gateway. Puntate le macchine degli sviluppatori al gateway separatamente, su ogni dispositivo, attraverso le [impostazioni gestite](/docs/it/managed-settings) di Claude Code. Il gateway non può inviare le chiavi di accesso stesso, perché sono loro che indicano al client dove si trova il gateway.1439Tutto quanto sopra configura il server gateway. Punta le macchine degli sviluppatori al gateway separatamente, su ogni dispositivo, attraverso le [impostazioni gestite](/docs/it/managed-settings) di Claude Code. Il gateway non può inviare da solo le chiavi di accesso, perché sono proprio loro a indicare al client dove si trova il gateway.

1259 1440

1260Per la CLI, impostate queste chiavi nel file `managed-settings.json` per ogni sistema operativo. Le due chiavi di accesso instradano il `/login` di ogni sviluppatore al vostro gateway:1441Per la CLI, imposta queste chiavi nel file `managed-settings.json` di ogni sistema operativo. Le due chiavi di accesso instradano il `/login` di ogni sviluppatore al tuo gateway:

1261 1442

1262```json theme={null}1443```json theme={null}

1263{1444{

1267}1448}

1268```1449```

1269 1450

1270`parentSettingsBehavior: "merge"` mantiene il funzionamento della consegna della lista di egress di Claude Desktop alle sue sessioni Claude Code incorporate; [Deliver policy to Claude Desktop sessions](/docs/it/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) spiega il meccanismo e dove deve trovarsi l'opt-in.1451`parentSettingsBehavior: "merge"` mantiene funzionante la consegna dell'allowlist di egress da parte di Claude Desktop alle sue sessioni Claude Code incorporate; [Deliver policy to Claude Desktop sessions](/docs/it/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) spiega il meccanismo e dove deve trovarsi l'opt-in.

1452

1453Per impedire agli sviluppatori di aggirare il gateway con una variabile di un provider cloud o con un proprio `ANTHROPIC_BASE_URL`, aggiungi `"allowedProviders": ["gateway"]` allo stesso file. Claude Code rifiuta quindi ogni sessione sulla macchina che non sia configurata per un Cloud gateway, e ammette un gateway solo quando è quello indicato da `forceLoginGatewayUrl` oppure uno il cui URL è impostato come `ANTHROPIC_BASE_URL` nel blocco `env` del file. `claude gateway` si rifiuta di essere eseguito su una macchina che imposta l'elenco, quindi non inserire la chiave sull'host del gateway. Consulta la voce [`allowedProviders`](/docs/it/settings-reference#allowedproviders) nel riferimento delle impostazioni. Richiede Claude Code v2.1.285 o successivo.

1454

1455Distribuisci il file `managed-settings.json` a ogni dispositivo, tipicamente tramite la tua piattaforma MDM. Il percorso del file differisce per piattaforma. Consulta [dove ogni meccanismo memorizza la policy](/docs/it/managed-settings#where-each-mechanism-stores-the-policy).

1271 1456

1272Distribuite il file `managed-settings.json` a ogni dispositivo, tipicamente tramite la vostra piattaforma MDM. Il percorso del file differisce per piattaforma. Consultate [dove ogni meccanismo memorizza la policy](/docs/it/managed-settings#where-each-mechanism-stores-the-policy).1457Per impostazione predefinita, una policy del registro su Windows o un plist di preferenze gestite su macOS sostituisce il file `managed-settings.json` anziché farne il merge, ad eccezione delle [chiavi di eccezione e dei controlli tra fonti descritti sopra](#precedence-with-other-managed-sources). Tutte e tre le chiavi in questo frammento seguono la regola della fonte con priorità più alta, quindi le flotte che distribuiscono la policy tramite Group Policy o profili di configurazione devono inserirle tutte e tre in quel meccanismo.

1273 1458

1274Per impostazione predefinita, una policy del registro su Windows o un plist di preferenze gestite su macOS sostituisce il file `managed-settings.json` piuttosto che unirsi ad esso, ad eccezione delle [chiavi di eccezione e dei controlli tra fonti sopra](#precedence-with-other-managed-sources). Tutte e tre le chiavi in questo frammento seguono la regola della fonte con priorità più alta, quindi i fleet che distribuiscono la policy tramite Group Policy o profili di configurazione devono inserire tutte e tre in quel meccanismo invece.1459Per Claude Desktop, imposta la chiave `bootstrapUrl` nella [configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop su `<listen.public_url>/user/bootstrap`. Il flusso di accesso e la policy per gruppo corrispondono quindi a quelli della CLI una volta che una policy si attiva lato server con una chiave `desktop`; senza l'opt-in, `/user/bootstrap` restituisce 404. Consulta [Claude Desktop overlay](#claude-desktop-overlay) per la metà lato server.

1275 1460

1276Per Claude Desktop, impostate la chiave `bootstrapUrl` nella propria [configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop su `<listen.public_url>/user/bootstrap`. Il flusso di accesso e la policy per gruppo corrispondono quindi a quelli della CLI una volta che una policy si attiva lato server con una chiave `desktop`; senza l'opt-in, `/user/bootstrap` restituisce 404. Consultate [Claude Desktop overlay](#claude-desktop-overlay) per la metà lato server.1461Claude Code rispetta [`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/it/settings-reference#gatewayinternalnetworks) e il valore `"gateway"` di [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) solo da una fonte gestita sulla macchina: `managed-settings.json`, il plist macOS o il registro HKLM di Windows, oppure un policy helper. Impostarli nel `~/.claude/settings.json` personale di uno sviluppatore o nel payload del gateway non configura l'accesso tramite gateway.

1277 1462

1278Claude Code rispetta [`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/it/settings-reference#gatewayinternalnetworks), e il valore `"gateway"` di [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) solo da una fonte gestita sulla macchina: `managed-settings.json`, il plist macOS o il registro HKLM di Windows, o un policy helper. Uno sviluppatore che li imposta nel proprio `~/.claude/settings.json` non ha alcun effetto, e nemmeno impostarli nel payload del gateway.1463Lascia `forceLoginMethod` e `forceLoginOrgUUID` fuori dal payload. Claude Code legge comunque entrambe le chiavi dal payload per il controllo delle credenziali all'avvio, quindi uno sviluppatore che mantiene sulla macchina una credenziale emessa da Anthropic incorre nell'uscita all'avvio descritta in [La policy dell'amministratore richiede un accesso tramite Cloud gateway](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in) anche dopo aver effettuato l'accesso.

1279 1464

1280<h2 id="related">1465<h2 id="related">

1281 Correlati1466 Correlati

claude-apps-gateway-config.md 2026-10-01 23:59 UTC to 2026-10-02 20:57 UTC

Configurazione del gateway delle app Claude

Struttura dei file

Espansione dei segreti

Sezioni obbligatorie

`listen`

`oidc`

Richieste IdP attraverso un forward proxy

Egress solo tramite proxy

`session`

`store`

`upstreams`

Messaggi di errore dell'upstream

API Anthropic

Header di identità per utente per un proxy che gestisci

Amazon Bedrock

Applicare un guardrail di Amazon Bedrock

Bedrock in un altro account AWS

Attribuzione dei costi AWS per sviluppatore

Claude Platform on AWS

Google Cloud Agent Platform

Microsoft Foundry

Header statici sulle richieste upstream

Più upstream

Sezioni facoltative

`admin`

`enforcement`

`pricing`

Aumenta i prezzi

Invia le tariffe ai client che hanno effettuato l'accesso

`models`

`managed`

Valori dei matcher che arrestano il gateway all'avvio

Cosa va in `cli`

Finestra di contesto nelle sessioni da terminale

Server MCP in una policy

Overlay di Claude Desktop

Contesto esteso in Claude Desktop

Rimuovi l'opzione 1M

Precedenza rispetto ad altre fonti gestite

`telemetry`

Aggiungi le tue etichette

Esporta direttamente al tuo collettore

Quando una destinazione fallisce

Ottimizzazione HTTP

`load_test_mode`

Esempio completo

Impostazioni gestite lato client

Correlati