126 126
127Consulta [dove ogni meccanismo memorizza la policy](/docs/it/managed-settings#where-each-mechanism-stores-the-policy) per i percorsi dei file, e [Impostazioni gestite lato client](/docs/it/claude-apps-gateway-config#client-side-managed-settings) per l'equivalente `bootstrapUrl` di Claude Desktop.127Consulta [dove ogni meccanismo memorizza la policy](/docs/it/managed-settings#where-each-mechanism-stores-the-policy) per i percorsi dei file, e [Impostazioni gestite lato client](/docs/it/claude-apps-gateway-config#client-side-managed-settings) per l'equivalente `bootstrapUrl` di Claude Desktop.
128 128
129<h3 id="large-rollouts">
130 Rollout su larga scala
131</h3>
132
133L'accesso è limitato per indirizzo IP client, e i valori predefiniti si adattano a un piccolo team. Ogni indirizzo ottiene 30 avvii di accesso e 10 invii di codice ogni 10 minuti. Un rollout a migliaia di sviluppatori può raggiungere questi limiti la prima mattina, per uno di due motivi:
134
135* **Il gateway non può vedere oltre il tuo load balancer.** Senza [`listen.trusted_proxies`](/docs/it/claude-apps-gateway-config#listen), ogni sviluppatore sembra provenire dall'indirizzo del load balancer e condivide un limite. Impostalo prima di qualsiasi altra cosa. Il gateway registra un avviso la prima volta che ignora un'intestazione `X-Forwarded-For`.
136* **Molti sviluppatori condividono pochi indirizzi di uscita NAT o VPN.** Condividono i limiti di quegli indirizzi anche quando `trusted_proxies` è corretto. Aumenta [`rate_limits`](/docs/it/claude-apps-gateway-config#http-tuning) per adattarsi.
137
138Per dimensionare `max`, dividi gli sviluppatori per gli indirizzi di uscita che condividono. Stima quanti di loro accedono entro un periodo `window_seconds`, che è 10 minuti per impostazione predefinita. Quindi raddoppialo per coprire i tentativi e gli sviluppatori che accedono sia a Claude Code che a Claude Desktop.
139
140Ad esempio, 10.000 sviluppatori dietro 4 indirizzi di uscita accedono uniformemente in un'ora. Cioè 2.500 sviluppatori per indirizzo e circa 420 di loro in ogni 10 minuti, che raddoppi e arrotondi a 1.000. L'esempio seguente imposta entrambi i limiti a 1.000:
141
142```yaml theme={null}
143rate_limits:
144 device_authorization: { max: 1000, window_seconds: 600 }
145 device_verify: { max: 1000, window_seconds: 600 }
146```
147
148`device_verify` è quello che impedisce a qualcuno di indovinare il codice di accesso di un altro sviluppatore, quindi aumentalo solo quanto la tua stima ha bisogno. Anche a questi limiti, un codice è 8 caratteri da un alfabeto di 20 caratteri e scade dopo 10 minuti, quindi indovinare rimane impraticabile; consulta [Resistenza al brute-force del codice utente](#user-code-brute-force-resistance).
149
150Quando il tuo IdP emette token di aggiornamento, Claude Code rinnova le sessioni silenziosamente, quindi puoi rimettere il limite dopo il rollout. Senza token di aggiornamento, gli sviluppatori accedono di nuovo ogni [`session.ttl_hours`](/docs/it/claude-apps-gateway-config#session). Dimensiona entrambi i limiti anche per quel tasso costante e lasciali aumentati.
151
152Quando un limite viene raggiunto, Claude Code v2.1.274 o successivo mostra `The gateway is limiting sign-in attempts right now`. Un gateway su v2.1.274 o successivo mostra `Too many attempts came from your network address` sulla pagina di verifica, con le impostazioni da controllare. Scrive anche una riga di log `sign-in refused` che nomina l'impostazione da modificare.
153
129<h2 id="operations">154<h2 id="operations">
130 Operazioni155 Operazioni
131</h2>156</h2>
160 185
161Il documento di scoperta OAuth in `/.well-known/oauth-authorization-server` restituisce anche `200` solo dopo il caricamento della configurazione, la scoperta OIDC, la costruzione del client upstream e la migrazione di Postgres, quindi funge anche da controllo di avvio end-to-end.186Il documento di scoperta OAuth in `/.well-known/oauth-authorization-server` restituisce anche `200` solo dopo il caricamento della configurazione, la scoperta OIDC, la costruzione del client upstream e la migrazione di Postgres, quindi funge anche da controllo di avvio end-to-end.
162 187
188<h3 id="concurrent-upstream-requests">
189 Richieste upstream concorrenti
190</h3>
191
192Per impostazione predefinita, ogni replica del gateway invia al massimo 256 richieste upstream contemporaneamente. Una risposta in streaming conta rispetto al limite fino al termine dello stream.
193
194Una richiesta che arriva mentre una replica è al limite attende all'interno del gateway per uno slot libero. Lo sviluppatore vede una risposta che è lenta a iniziare o sembra bloccarsi. Su un upstream `provider: anthropic`, una richiesta che attende più a lungo di [`timeouts.upstream_ttfb_ms`](/docs/it/claude-apps-gateway-config#http-tuning) rinuncia a quell'upstream e fallisce con un 502 quando nessun upstream successivo lo serve.
195
196La riga di log di avvio che contiene `upstream requests:` mostra il limite in vigore. Mentre una replica ha più richieste aperte rispetto al limite, registra anche un avvertimento che contiene `client requests are open`, al massimo una volta al minuto.
197
198Per servire più richieste contemporaneamente, hai due opzioni:
199
200* Aggiungi repliche.
201* Aumenta il limite su ogni replica. Imposta la variabile di ambiente `BUN_CONFIG_MAX_HTTP_REQUESTS` sul contenitore del gateway su un numero intero da 1 a 65535, quindi riavvia il contenitore.
202
203Una replica riempie il suo limite a una velocità di richiesta di circa il limite diviso per il numero medio di secondi che una richiesta rimane aperta. Ad esempio, se le richieste rimangono aperte per 10 secondi in media, una replica al limite predefinito di 256 lo riempie a circa 26 richieste al secondo.
204
205Se autoscali su CPU, una replica al limite mette in coda le richieste senza attivare uno scale-out, quindi imposta l'obiettivo al di sotto del livello di CPU che le tue repliche mostrano quando registrano l'avvertimento `client requests are open`.
206
207<Warning>
208 Ogni richiesta aperta contiene memoria nel processo del gateway mentre esegue lo streaming e mentre attende uno slot. Se mantieni il limite a 256, la memoria su una replica sovraccarica continua a crescere, perché le richieste in attesa mantengono i loro corpi di richiesta. Dimensiona la memoria del contenitore per il numero di richieste aperte al picco e osserva la memoria quando cambi il limite. Una replica che esaurisce la memoria viene uccisa e interrompe ogni stream che contiene.
209</Warning>
210
163<h3 id="outage-behavior">211<h3 id="outage-behavior">
164 Comportamento in caso di interruzione212 Comportamento in caso di interruzione
165</h3>213</h3>
207 Aggiornamenti255 Aggiornamenti
208</h3>256</h3>
209 257
210258Le repliche sono senza stato, quindi un riavvio rolling è sicuro in qualsiasi momento. Il gateway esegue migrazioni dello schema all'avvio, il che significa che distribuire il nuovo binario auto-migra il database. Le repliche concorrenti si serializzano su un lock consigliato di Postgres, quindi solo una applica ogni migrazione.Le repliche sono senza stato, quindi un riavvio rolling non perde alcuno stato del gateway. Il gateway esegue migrazioni dello schema all'avvio, il che significa che distribuire il nuovo binario auto-migra il database. Le repliche concorrenti si serializzano su un lock consigliato di Postgres, quindi solo una applica ogni migrazione.
259
260Quando il tuo orchestrator arresta una replica con `SIGTERM`, come in un riavvio rolling o uno scale-in, il gateway smette di accettare nuove connessioni e lascia che le richieste e gli stream già in volo finiscano prima di uscire. Attende fino a 25 secondi, chiamato la finestra di drenaggio, quindi chiude tutto ciò che è ancora aperto. Un `SIGINT`, come Ctrl+C in un terminale, avvia lo stesso drenaggio, e un secondo segnale durante il drenaggio chiude le richieste aperte ed esce subito. Il drenaggio richiede gateway v2.1.274 o successivo.
261
262Le generazioni lunghe possono eseguire lo streaming per minuti. Su Kubernetes e Amazon ECS, aumenta entrambi questi insieme per dare a quegli stream più tempo:
263
264* **La finestra di drenaggio**: imposta la variabile di ambiente `CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS` sul contenitore del gateway su un numero intero positivo di millisecondi, come `120000`. Il gateway ignora un valore in qualsiasi altra forma, come `120s`, e mantiene il predefinito di 25 secondi
265* **Il periodo di grazia del tuo orchestrator**: `terminationGracePeriodSeconds` su Kubernetes, o `stopTimeout` su Amazon ECS
266
267Il periodo di grazia predefinito è 30 secondi su entrambe le piattaforme. Mantienilo almeno 5 secondi più lungo della finestra di drenaggio, o l'orchestrator uccide il gateway prima che il drenaggio finisca. Su Kubernetes, aggiungi anche la durata di qualsiasi hook `preStop`, perché il periodo di grazia inizia a contare prima che l'hook venga eseguito piuttosto che quando il gateway riceve `SIGTERM`.
268
269La tua piattaforma potrebbe anche limitare quanto a lungo il drenaggio può eseguire:
270
271* **Amazon ECS su Fargate**: `stopTimeout` consente al massimo 120 secondi
272* **Cloud Run**: arresta un'istanza 10 secondi dopo `SIGTERM`, quindi gli stream aperti ottengono al massimo 10 secondi lì, qualunque sia la finestra di drenaggio
273
274Quando la finestra di drenaggio termina con richieste ancora aperte, il gateway registra un avvertimento che contiene `drain window over after`, conta le richieste che ha tagliato e nomina entrambe le impostazioni da aumentare.
211 275
212Le migrazioni sono append-only, quindi il rollback a un binario precedente che conosce meno migrazioni è sicuro; ignora le righe extra. Il rollback ri-convalida anche il YAML rispetto allo schema del binario più vecchio, quindi una configurazione che ha adottato una chiave introdotta dalla versione più recente fallisce l'avvio su quella più vecchia. Rimuovi la nuova chiave prima di eseguire il rollback.276Le migrazioni sono append-only, quindi il rollback a un binario precedente che conosce meno migrazioni è sicuro; ignora le righe extra. Il rollback ri-convalida anche il YAML rispetto allo schema del binario più vecchio, quindi una configurazione che ha adottato una chiave introdotta dalla versione più recente fallisce l'avvio su quella più vecchia. Rimuovi la nuova chiave prima di eseguire il rollback.
213 277
239 303
240* Gli sviluppatori detengono JWT di breve durata invece di chiavi upstream grezze. La gamba CLI-to-gateway utilizza la concessione del dispositivo RFC 8628, e lo scambio di autorizzazione del gateway con l'IdP esegue PKCE nella configurazione predefinita, quindi un codice di autorizzazione IdP intercettato è inutile.304* Gli sviluppatori detengono JWT di breve durata invece di chiavi upstream grezze. La gamba CLI-to-gateway utilizza la concessione del dispositivo RFC 8628, e lo scambio di autorizzazione del gateway con l'IdP esegue PKCE nella configurazione predefinita, quindi un codice di autorizzazione IdP intercettato è inutile.
241* La pagina di verifica del dispositivo applica POST della stessa origine e un limite di velocità per IP per RFC 8628 §5.1. Consulta [Resistenza al brute-force del codice utente](#user-code-brute-force-resistance).305* La pagina di verifica del dispositivo applica POST della stessa origine e un limite di velocità per IP per RFC 8628 §5.1. Consulta [Resistenza al brute-force del codice utente](#user-code-brute-force-resistance).
242306* Le richieste in uscita passano attraverso una guardia SSRF (Server-Side Request Forgery) che risolve DNS, blocca gli indirizzi link-local e cloud-metadata più loopback per impostazione predefinita, e fissa la connessione all'IP risolto, quindi gli URL influenzati dall'operatore come l'IdP e le destinazioni OTLP non possono essere reindirizzati agli endpoint dei metadati cloud. Gli intervalli privati RFC 1918 sono deliberatamente consentiti, perché gli IdP e i collettori OTLP comunemente vivono su IP privati. Imposta `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` nell'ambiente del gateway solo quando qualcosa che il gateway deve raggiungere legittimamente vive su loopback, come un IdP di sviluppo locale o un collettore OTLP sidecar su `localhost`. La variabile rilassa il blocco loopback per ogni URL configurato dall'operatore e salta anche l'avviso al momento dell'avvio che controlla se il pod può raggiungere l'endpoint dei metadati cloud, quindi preferisci dare al collettore il suo indirizzo interno.* Le richieste del gateway al tuo IdP, ai tuoi collettori OTLP e agli upstream `provider: anthropic` passano attraverso una guardia SSRF (Server-Side Request Forgery) che risolve DNS, blocca gli indirizzi link-local e cloud-metadata più loopback per impostazione predefinita, e fissa la connessione all'IP risolto, quindi gli URL influenzati dall'operatore non possono essere reindirizzati agli endpoint dei metadati cloud. Gli intervalli privati RFC 1918 sono deliberatamente consentiti, perché gli IdP e i collettori OTLP comunemente vivono su IP privati. Per gli altri provider, il gateway rifiuta un `base_url` che nomina uno di quegli indirizzi o un nome host di metadati quando carica la configurazione, e l'SDK del provider si connette quindi senza il controllo DNS.
307
308 Se attivi [egress solo proxy](/docs/it/claude-apps-gateway-config#proxy-only-egress), quel controllo di indirizzo si sposta al tuo proxy in avanti: il gateway consegna i nomi host e la lista di consentiti del proxy deve rifiutare quelle destinazioni.
309
310 Imposta `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` nell'ambiente del gateway solo quando qualcosa che il gateway deve raggiungere legittimamente vive su loopback, come un IdP di sviluppo locale o un collettore OTLP sidecar su `localhost`. La variabile rilassa il blocco loopback per ogni URL configurato dall'operatore e salta anche l'avviso al momento dell'avvio che controlla se il pod può raggiungere l'endpoint dei metadati cloud, quindi preferisci dare al collettore il suo indirizzo interno.
243 311
244Se aggiungi i tuoi controlli di uscita, il gateway deve raggiungere il server dei metadati ogni volta che utilizza credenziali di metadati dell'istanza come workload identity.312Se aggiungi i tuoi controlli di uscita, il gateway deve raggiungere il server dei metadati ogni volta che utilizza credenziali di metadati dell'istanza come workload identity.
245 313
254 322
255Il `user_code` che uno sviluppatore digita nella pagina di verifica `/device` è di 8 caratteri tratti da un alfabeto di 20 caratteri, che produce 20⁸ o circa 2,56×10¹⁰ combinazioni, e scade dopo 10 minuti.323Il `user_code` che uno sviluppatore digita nella pagina di verifica `/device` è di 8 caratteri tratti da un alfabeto di 20 caratteri, che produce 20⁸ o circa 2,56×10¹⁰ combinazioni, e scade dopo 10 minuti.
256 324
257325Il gateway applica limiti di velocità per IP sugli endpoint di concessione del dispositivo, configurabili tramite [`rate_limits`](/docs/it/claude-apps-gateway-config#http-tuning). Aumenta i limiti se molti sviluppatori accedono da un singolo indirizzo NAT aziendale condiviso. I limiti si applicano solo al flusso di accesso, non all'inferenza.Il gateway applica limiti di velocità per IP sugli endpoint di concessione del dispositivo, configurabili tramite [`rate_limits`](/docs/it/claude-apps-gateway-config#http-tuning). Aumenta i limiti se molti sviluppatori accedono da un singolo indirizzo NAT aziendale condiviso. [I rollout su larga scala](#large-rollouts) mostra come dimensionarli. I limiti si applicano solo al flusso di accesso, non all'inferenza.
258 326
259<h3 id="compliance-posture">327<h3 id="compliance-posture">
260 Postura di conformità328 Postura di conformità
284Lo stderr del gateway include il flusso di eventi di audit, il log di audit registra le identità degli sviluppatori e il file di debug registra l'output di hook e MCP server dalla macchina dello sviluppatore. Rivedi e oscura questi elementi prima di pubblicare su un problema pubblico.352Lo stderr del gateway include il flusso di eventi di audit, il log di audit registra le identità degli sviluppatori e il file di debug registra l'output di hook e MCP server dalla macchina dello sviluppatore. Rivedi e oscura questi elementi prima di pubblicare su un problema pubblico.
285 353
286| Sintomo | Causa | Soluzione |354| Sintomo | Causa | Soluzione |
287355| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
288| La `/login` di uno sviluppatore mostra il selettore di account standard invece della schermata **Cloud gateway** | `forceLoginMethod` o `forceLoginGatewayUrl` non è impostato nelle impostazioni gestite su quella macchina | Distribuisci il [file delle impostazioni gestite](/docs/it/claude-apps-gateway#set-the-gateway-url) al dispositivo; `/login` legge l'URL del gateway da lì |356| La `/login` di uno sviluppatore mostra il selettore di account standard invece della schermata **Cloud gateway** | `forceLoginMethod` o `forceLoginGatewayUrl` non è impostato nelle impostazioni gestite su quella macchina | Distribuisci il [file delle impostazioni gestite](/docs/it/claude-apps-gateway#set-the-gateway-url) al dispositivo; `/login` legge l'URL del gateway da lì |
289| Le richieste di uno sviluppatore falliscono con `Not signed in to the Cloud gateway — run /login.` | Le impostazioni gestite della macchina impostano `forceLoginMethod: "gateway"` o `forceLoginGatewayUrl`, e la sessione non ha un accesso al gateway. Un accesso a claude.ai residuo non soddisfa il requisito. | Chiedi allo sviluppatore di eseguire `/login` e completare l'accesso al gateway. Vedi anche [Administrator policy requires a Cloud gateway sign-in](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |357| Le richieste di uno sviluppatore falliscono con `Not signed in to the Cloud gateway — run /login.` | Le impostazioni gestite della macchina impostano `forceLoginMethod: "gateway"` o `forceLoginGatewayUrl`, e la sessione non ha un accesso al gateway. Un accesso a claude.ai residuo non soddisfa il requisito. | Chiedi allo sviluppatore di eseguire `/login` e completare l'accesso al gateway. Vedi anche [Administrator policy requires a Cloud gateway sign-in](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |
290| Claude Desktop segnala che la sua configurazione di bootstrap non poteva essere recuperata | `/user/bootstrap` ha restituito 404: il criterio che corrisponde all'utente non contiene una chiave `desktop`, oppure nessun criterio corrisponde. Il log di audit del gateway registra ogni rifiuto come `desktop_bootstrap.denied` con il motivo. | Aggiungi un blocco `desktop` al criterio che corrisponde all'utente, oppure al livello base `match: {}`; un `desktop: {}` vuoto è sufficiente. Vedi [Claude Desktop overlay](/docs/it/claude-apps-gateway-config#claude-desktop-overlay). |358| Claude Desktop segnala che la sua configurazione di bootstrap non poteva essere recuperata | `/user/bootstrap` ha restituito 404: il criterio che corrisponde all'utente non contiene una chiave `desktop`, oppure nessun criterio corrisponde. Il log di audit del gateway registra ogni rifiuto come `desktop_bootstrap.denied` con il motivo. | Aggiungi un blocco `desktop` al criterio che corrisponde all'utente, oppure al livello base `match: {}`; un `desktop: {}` vuoto è sufficiente. Vedi [Claude Desktop overlay](/docs/it/claude-apps-gateway-config#claude-desktop-overlay). |
291| L'avvio mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | La build di Claude Code installata precede il supporto del gateway | Chiedi allo sviluppatore di aggiornare Claude Code a una versione che include il supporto Cloud gateway |359| L'avvio mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | La build di Claude Code installata precede il supporto del gateway | Chiedi allo sviluppatore di aggiornare Claude Code a una versione che include il supporto Cloud gateway |
292| L'avvio esce con `Administrator policy requires a Cloud gateway sign-in on this machine` | L'ambiente dello sviluppatore imposta `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN`, le loro impostazioni configurano un [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper), oppure una chiave API da un accesso precedente a Claude Console è ancora salvata | Chiedi allo sviluppatore di cancellare ciascuno che si applica: annulla l'impostazione della variabile, rimuovi la voce `apiKeyHelper`, oppure esegui `claude auth logout` per rimuovere la chiave salvata. Quindi chiedigli di avviare `claude` e accedere con `/login`. Vedi anche [Administrator policy requires a Cloud gateway sign-in](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |360| L'avvio esce con `Administrator policy requires a Cloud gateway sign-in on this machine` | L'ambiente dello sviluppatore imposta `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN`, le loro impostazioni configurano un [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper), oppure una chiave API da un accesso precedente a Claude Console è ancora salvata | Chiedi allo sviluppatore di cancellare ciascuno che si applica: annulla l'impostazione della variabile, rimuovi la voce `apiKeyHelper`, oppure esegui `claude auth logout` per rimuovere la chiave salvata. Quindi chiedigli di avviare `claude` e accedere con `/login`. Vedi anche [Administrator policy requires a Cloud gateway sign-in](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |
293| L'avvio o `/login` segnala `Claude Code may not be enabled for your organization` dopo un 403 al caricamento delle impostazioni gestite | Il gateway, o qualcosa davanti ad esso, ha risposto alla richiesta `/managed/settings` con 403. La rotta delle impostazioni del gateway stesso non risponde mai con 403. Lo stato proviene dai controlli IP [`access_control`](/docs/it/claude-apps-gateway-config#http-tuning) o da un proxy o WAF davanti al gateway. Il log di audit registra un rifiuto del controllo IP come `access.denied` con il motivo. Lo sviluppatore rimane connesso. | Controlla il log di audit per `access.denied` al momento dell'errore e correggi gli elenchi `access_control` o il front end, quindi chiedi allo sviluppatore di avviare `claude` di nuovo |361| L'avvio o `/login` segnala `Claude Code may not be enabled for your organization` dopo un 403 al caricamento delle impostazioni gestite | Il gateway, o qualcosa davanti ad esso, ha risposto alla richiesta `/managed/settings` con 403. La rotta delle impostazioni del gateway stesso non risponde mai con 403. Lo stato proviene dai controlli IP [`access_control`](/docs/it/claude-apps-gateway-config#http-tuning) o da un proxy o WAF davanti al gateway. Il log di audit registra un rifiuto del controllo IP come `access.denied` con il motivo. Lo sviluppatore rimane connesso. | Controlla il log di audit per `access.denied` al momento dell'errore e correggi gli elenchi `access_control` o il front end, quindi chiedi allo sviluppatore di avviare `claude` di nuovo |
362| CLI `/login`: `The gateway is limiting sign-in attempts right now`, oppure `Request failed with status code 429` nelle versioni precedenti. La pagina `/device` potrebbe mostrare `Too many attempts` agli sviluppatori che non hanno mai provato prima | È stato raggiunto il limite di velocità di accesso per IP. O `listen.trusted_proxies` non copre il bilanciatore di carico, quindi ogni sviluppatore condivide il suo indirizzo, oppure molti sviluppatori condividono un indirizzo di uscita NAT o VPN. Gli eventi di audit con `result: rate_limited` mostrano lo stesso uno o pochi valori `client_ip`. | Imposta prima `listen.trusted_proxies` agli intervalli di origine del bilanciatore di carico, quindi aumenta `rate_limits` se gli sviluppatori condividono ancora indirizzi. Vedi [Large rollouts](#large-rollouts). |
294| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Il nome host del gateway si risolve in almeno un indirizzo IP pubblico. Claude Code controlla ogni indirizzo risolto e richiede che tutti siano privati. Una causa comune è un nome dual-stack in cui una famiglia si risolve in un indirizzo pubblico, inclusi i bilanciatori di carico dual-stack interni di AWS, che restituiscono indirizzi AAAA in intervallo pubblico. | Fai in modo che il nome del gateway si risolva solo in indirizzi privati sulle macchine degli sviluppatori. Per un nome dual-stack, elimina il record in intervallo pubblico o servi un nome DNS solo interno separato. Vedi il [prerequisito di rete privata](/docs/it/claude-apps-gateway#prerequisites). Se l'indirizzo è spazio pubblico che la tua organizzazione possiede e utilizza internamente, [dichiara quel blocco](/docs/it/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) invece. |363| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Il nome host del gateway si risolve in almeno un indirizzo IP pubblico. Claude Code controlla ogni indirizzo risolto e richiede che tutti siano privati. Una causa comune è un nome dual-stack in cui una famiglia si risolve in un indirizzo pubblico, inclusi i bilanciatori di carico dual-stack interni di AWS, che restituiscono indirizzi AAAA in intervallo pubblico. | Fai in modo che il nome del gateway si risolva solo in indirizzi privati sulle macchine degli sviluppatori. Per un nome dual-stack, elimina il record in intervallo pubblico o servi un nome DNS solo interno separato. Vedi il [prerequisito di rete privata](/docs/it/claude-apps-gateway#prerequisites). Se l'indirizzo è spazio pubblico che la tua organizzazione possiede e utilizza internamente, [dichiara quel blocco](/docs/it/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) invece. |
295| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | Un `HTTPS_PROXY` o `HTTP_PROXY` si applica all'host del gateway e il nome host del proxy si risolve in un indirizzo pubblico. Un proxy il cui host si risolve solo in indirizzi privati è consentito e non attiva questo errore | Aggiungi l'host del gateway a `NO_PROXY` sulla macchina dello sviluppatore in modo che la connessione sia diretta, oppure utilizza un proxy il cui nome host si risolve in indirizzi privati. Il messaggio nomina la voce esatta `NO_PROXY` da aggiungere |364| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | Un `HTTPS_PROXY` o `HTTP_PROXY` si applica all'host del gateway e il nome host del proxy si risolve in un indirizzo pubblico. Un proxy il cui host si risolve solo in indirizzi privati è consentito e non attiva questo errore | Aggiungi l'host del gateway a `NO_PROXY` sulla macchina dello sviluppatore in modo che la connessione sia diretta, oppure utilizza un proxy il cui nome host si risolve in indirizzi privati. Il messaggio nomina la voce esatta `NO_PROXY` da aggiungere |
296| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | Il gateway è su un blocco dichiarato in [`gatewayInternalNetworks`](/docs/it/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own), e la macchina dello sviluppatore l'ha raggiunto da un indirizzo al di fuori di quel blocco: un pool di indirizzi VPN, un segmento NAT di container o WSL2, oppure una rete che non è la tua | Chiedi allo sviluppatore di eseguire `/login` dal sistema operativo host sulla tua rete. Se l'indirizzo mostrato è anche lo spazio pubblico della tua organizzazione, sostituisci la voce del gateway con un blocco che copra entrambi, fino a `/8`; una seconda voce sovrapposta è rifiutata |365| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | Il gateway è su un blocco dichiarato in [`gatewayInternalNetworks`](/docs/it/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own), e la macchina dello sviluppatore l'ha raggiunto da un indirizzo al di fuori di quel blocco: un pool di indirizzi VPN, un segmento NAT di container o WSL2, oppure una rete che non è la tua | Chiedi allo sviluppatore di eseguire `/login` dal sistema operativo host sulla tua rete. Se l'indirizzo mostrato è anche lo spazio pubblico della tua organizzazione, sostituisci la voce del gateway con un blocco che copra entrambi, fino a `/8`; una seconda voce sovrapposta è rifiutata |
301| CLI `/login`: `Could not resolve gateway host <host>` | La macchina non può risolvere il nome DNS interno del gateway, tipicamente perché non è sulla rete aziendale | Chiedi allo sviluppatore di connettersi alla tua rete o VPN, quindi riprova `/login` |370| CLI `/login`: `Could not resolve gateway host <host>` | La macchina non può risolvere il nome DNS interno del gateway, tipicamente perché non è sulla rete aziendale | Chiedi allo sviluppatore di connettersi alla tua rete o VPN, quindi riprova `/login` |
302| L'avvio esce con un errore di convalida della configurazione che nomina `store.postgres_url` | Nessun Postgres configurato; il gateway richiede Postgres | Imposta `store.postgres_url`. Per lo sviluppo locale, utilizza un container usa e getta: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |371| L'avvio esce con un errore di convalida della configurazione che nomina `store.postgres_url` | Nessun Postgres configurato; il gateway richiede Postgres | Imposta `store.postgres_url`. Per lo sviluppo locale, utilizza un container usa e getta: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |
303| L'avvio esce: `requires the native binary` | In esecuzione sotto Node invece del binario nativo | Installa Claude Code con uno dei [metodi di installazione standalone](/docs/it/setup) |372| L'avvio esce: `requires the native binary` | In esecuzione sotto Node invece del binario nativo | Installa Claude Code con uno dei [metodi di installazione standalone](/docs/it/setup) |
304373| L'avvio esce con un errore di scoperta OIDC dopo `config.load` | `oidc.issuer` non raggiungibile, oppure la catena TLS non è attendibile | Controlla che l'emittente sia raggiungibile dal pod e serva `/.well-known/openid-configuration`. Imposta `ca_cert_pem` per PKI privata. Se il pod raggiunge l'IdP solo attraverso un proxy forward, imposta [`oidc.use_proxy: true`](/docs/it/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); nelle versioni precedenti a v2.1.227, fornisci al pod una rotta diretta a ciascuno degli endpoint dell'IdP invece. || L'avvio esce con un errore di scoperta OIDC dopo `config.load` | `oidc.issuer` non raggiungibile, oppure la catena TLS non è attendibile | Controlla che l'emittente sia raggiungibile dal pod e serva `/.well-known/openid-configuration`. Imposta `ca_cert_pem` per PKI privata. Se il pod raggiunge l'IdP solo attraverso un proxy forward, imposta [`oidc.use_proxy: true`](/docs/it/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); nelle versioni precedenti a v2.1.227, fornisci al pod una rotta diretta a ciascuno degli endpoint dell'IdP invece. Se il pod inoltre non può risolvere il nome host dell'IdP, oppure il proxy rifiuta `CONNECT` a un indirizzo IP, vedi [Proxy-only egress](/docs/it/claude-apps-gateway-config#proxy-only-egress), che richiede v2.1.277 o successivo. |
305| L'avvio esce con un errore di autorizzazione Postgres | Il ruolo del database manca dei diritti DDL sul suo schema | Concedi al ruolo `CREATE` sullo schema del gateway in modo che possa creare e alterare le sue tabelle all'avvio |374| L'avvio esce con un errore di autorizzazione Postgres | Il ruolo del database manca dei diritti DDL sul suo schema | Concedi al ruolo `CREATE` sullo schema del gateway in modo che possa creare e alterare le sue tabelle all'avvio |
375| Log: `could not connect to Postgres at boot, attempt 1 of 3` | Il database non era raggiungibile quando il gateway è stato avviato, ad esempio su un'istanza fredda la cui rete è ancora in fase di avvio | Se il gateway finisce di avviarsi, non è necessaria alcuna azione. Quando il database non è raggiungibile, il gateway tenta la connessione tre volte, due secondi di distanza, prima di uscire. Se esce con `could not connect to Postgres`, controlla `store.postgres_url` e il percorso di rete al database. Se i tentativi scadono piuttosto che essere rifiutati, aumenta [`store.connect_timeout_seconds`](/docs/it/claude-apps-gateway-config#store) per dare a ciascuno più tempo. |
306| `/oauth/callback` mostra "Sign-in could not be completed" | Dominio email rifiutato, convalida id\_token non riuscita, oppure `email_verified` è esplicitamente `false`, che il gateway rifiuta sempre senza override | Controlla `allowed_email_domains` e che l'IdP restituisca un'attestazione `email` verificata. Per `email_verified: false`, correggi la verifica lato IdP. Se il tuo IdP emette email con un nome di attestazione diverso, imposta `oidc.email_claim`. |376| `/oauth/callback` mostra "Sign-in could not be completed" | Dominio email rifiutato, convalida id\_token non riuscita, oppure `email_verified` è esplicitamente `false`, che il gateway rifiuta sempre senza override | Controlla `allowed_email_domains` e che l'IdP restituisca un'attestazione `email` verificata. Per `email_verified: false`, correggi la verifica lato IdP. Se il tuo IdP emette email con un nome di attestazione diverso, imposta `oidc.email_claim`. |
307| Log: `token exchange failed request_id=<id>: id_token missing email claim` | L'IdP non include `email` nell'id\_token per impostazione predefinita. Questo rifiuto si attiva solo quando `allowed_email_domains` è impostato; senza di esso, un'email mancante conia una sessione senza email | Configura l'IdP per emettere `email` nell'id\_token. Okta: aggiungi `email` alle attestazioni del token ID di un server di autorizzazione personalizzato. Entra: aggiungi `email` come attestazione facoltativa sulla registrazione dell'app. PingFederate: abilita una Politica OpenID Connect che emette `email`. Se l'IdP serve `email` dall'endpoint userinfo ma non lo includerà nell'id\_token, come il server di autorizzazione dell'organizzazione Okta, imposta `oidc.userinfo_fallback: true`. |377| Log: `token exchange failed request_id=<id>: id_token missing email claim` | L'IdP non include `email` nell'id\_token per impostazione predefinita. Questo rifiuto si attiva solo quando `allowed_email_domains` è impostato; senza di esso, un'email mancante conia una sessione senza email | Configura l'IdP per emettere `email` nell'id\_token. Okta: aggiungi `email` alle attestazioni del token ID di un server di autorizzazione personalizzato. Entra: aggiungi `email` come attestazione facoltativa sulla registrazione dell'app. PingFederate: abilita una Politica OpenID Connect che emette `email`. Se l'IdP serve `email` dall'endpoint userinfo ma non lo includerà nell'id\_token, come il server di autorizzazione dell'organizzazione Okta, imposta `oidc.userinfo_fallback: true`. |
308| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e gli sviluppatori vedono `Cloud gateway session expired` ogni `session.ttl_hours` | L'IdP ha accettato il token di aggiornamento ma non ha restituito alcun id\_token con esso, quindi il gateway ha chiesto all'endpoint userinfo dell'IdP le attestazioni dell'utente. L'IdP ha rifiutato il token di accesso aggiornato lì. Il gateway risponde `temporarily_unavailable`, quindi Claude Code mantiene il token di aggiornamento ma non può rinnovare la sessione. Le versioni del gateway precedenti a v2.1.260 registrano la stessa riga senza il dettaglio `(at …)`. | Imposta [`oidc.scope_on_refresh: true`](/docs/it/claude-apps-gateway-config#oidc), disponibile nel gateway v2.1.260 o successivo, in modo che la richiesta di aggiornamento chieda di nuovo `openid`. Alcuni IdP, come Okta, restituiscono un id\_token all'aggiornamento solo quando richiesto. Su PingFederate, abilita **Return ID Token On Refresh Grant** in **Applications > OAuth > OpenID Connect Policy Management** invece. La chiave non cambia il comportamento di PingFederate. Per altri IdP che ancora lo omettono, controlla se l'endpoint userinfo accetta token di accesso emessi da un aggiornamento. Come misura temporanea, aumenta [`session.ttl_hours`](/docs/it/claude-apps-gateway-config#session). Vedi [Identity provider setup](#identity-provider-setup) per il compromesso di deprovisioning. |378| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e gli sviluppatori vedono `Cloud gateway session expired` ogni `session.ttl_hours` | L'IdP ha accettato il token di aggiornamento ma non ha restituito alcun id\_token con esso, quindi il gateway ha chiesto all'endpoint userinfo dell'IdP le attestazioni dell'utente. L'IdP ha rifiutato il token di accesso aggiornato lì. Il gateway risponde `temporarily_unavailable`, quindi Claude Code mantiene il token di aggiornamento ma non può rinnovare la sessione. Le versioni del gateway precedenti a v2.1.260 registrano la stessa riga senza il dettaglio `(at …)`. | Imposta [`oidc.scope_on_refresh: true`](/docs/it/claude-apps-gateway-config#oidc), disponibile nel gateway v2.1.260 o successivo, in modo che la richiesta di aggiornamento chieda di nuovo `openid`. Alcuni IdP, come Okta, restituiscono un id\_token all'aggiornamento solo quando richiesto. Su PingFederate, abilita **Return ID Token On Refresh Grant** in **Applications > OAuth > OpenID Connect Policy Management** invece. La chiave non cambia il comportamento di PingFederate. Per altri IdP che ancora lo omettono, controlla se l'endpoint userinfo accetta token di accesso emessi da un aggiornamento. Come misura temporanea, aumenta [`session.ttl_hours`](/docs/it/claude-apps-gateway-config#session). Vedi [Identity provider setup](#identity-provider-setup) per il compromesso di deprovisioning. |
309| Ogni richiesta Amazon Bedrock restituisce 502; il log mostra `Could not load credentials from any providers` | Su EC2, il limite di hop predefinito di IMDSv2 di 1 blocca la richiesta di metadati dell'istanza dall'interno del container. L'avvio e `/readyz` passano comunque perché l'AWS SDK risolve le credenziali dell'istanza sulla prima richiesta, non alla costruzione del client | Aumenta il limite di hop con `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, oppure impostalo nel modello di lancio. La modifica si applica a ogni container sull'istanza. Preferisci i ruoli delle attività ECS dove disponibili, che leggono le credenziali dall'endpoint delle credenziali del container ECS ed evitano completamente la modifica, oppure applica la modifica su un'istanza del gateway dedicata per limitare l'esposizione. |379| Ogni richiesta Amazon Bedrock restituisce 502; il log mostra `Could not load credentials from any providers` | Su EC2, il limite di hop predefinito di IMDSv2 di 1 blocca la richiesta di metadati dell'istanza dall'interno del container. L'avvio e `/readyz` passano comunque perché l'AWS SDK risolve le credenziali dell'istanza sulla prima richiesta, non alla costruzione del client | Aumenta il limite di hop con `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, oppure impostalo nel modello di lancio. La modifica si applica a ogni container sull'istanza. Preferisci i ruoli delle attività ECS dove disponibili, che leggono le credenziali dall'endpoint delle credenziali del container ECS ed evitano completamente la modifica, oppure applica la modifica su un'istanza del gateway dedicata per limitare l'esposizione. |
380| Al carico di picco, le risposte sono lente a iniziare o sembrano bloccarsi, oppure falliscono con un 502 `all upstreams failed` mentre l'upstream è integro | Una replica ha più richieste aperte di quante ne invia upstream contemporaneamente, quindi le richieste extra attendono all'interno del gateway. Su un upstream `provider: anthropic`, una richiesta che attende più a lungo di `timeouts.upstream_ttfb_ms` rinuncia a quel upstream, che produce il 502 quando nessun upstream successivo lo serve. Il log mostra un avviso che contiene `client requests are open`. | Aggiungi repliche, oppure aumenta il limite su ogni replica. Vedi [Concurrent upstream requests](#concurrent-upstream-requests). |
310| Errore IdP: unknown or unsupported scope | L'IdP rifiuta gli ambiti che non riconosce | Imposta `oidc.scopes` esattamente all'elenco che il tuo IdP accetta; deve includere `openid`. L'impostazione predefinita è `openid profile email offline_access`. |381| Errore IdP: unknown or unsupported scope | L'IdP rifiuta gli ambiti che non riconosce | Imposta `oidc.scopes` esattamente all'elenco che il tuo IdP accetta; deve includere `openid`. L'impostazione predefinita è `openid profile email offline_access`. |
311| Le sessioni non si rinnovano silenziosamente dopo l'impostazione di `oidc.scopes` | `offline_access` è stato eliminato dall'override | Aggiungi di nuovo `offline_access` se il tuo IdP lo supporta. Senza un token di aggiornamento, gli sviluppatori rieseguono l'accesso del browser ogni `session.ttl_hours`. |382| Le sessioni non si rinnovano silenziosamente dopo l'impostazione di `oidc.scopes` | `offline_access` è stato eliminato dall'override | Aggiungi di nuovo `offline_access` se il tuo IdP lo supporta. Senza un token di aggiornamento, gli sviluppatori rieseguono l'accesso del browser ogni `session.ttl_hours`. |
312| Il browser mostra "This request came from another site and was blocked" | POST di modulo cross-site, bloccato come protezione CSRF. Previsto per pagine incorporate o proxy | Apri il collegamento di verifica direttamente |383| Il browser mostra "This request came from another site and was blocked" | POST di modulo cross-site, bloccato come protezione CSRF. Previsto per pagine incorporate o proxy | Apri il collegamento di verifica direttamente |