Documentation 2026-07-28 23:57 UTC to 2026-07-29 19:02 UTC

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Gateway di app Claude per Amazon Bedrock, Claude Platform su AWS, Google Cloud e Microsoft Foundry

6 

7> Esegui Claude Code attraverso Amazon Bedrock, Claude Platform su AWS, Google Cloud o Microsoft Foundry dietro un gateway auto-ospitato con accesso SSO, accesso ai modelli per gruppo e telemetria OTLP.

8 

9<Note>

10 Il gateway di app Claude è progettato per le organizzazioni che devono — o preferiscono — instradare l'inferenza attraverso il proprio provider cloud, ad esempio per soddisfare i requisiti di [residenza dei dati](/docs/it/claude-apps-gateway-deploy#compliance-posture). Se non hai questo requisito e desideri accesso ad altre funzionalità come il provisioning SCIM o Claude Code su web e mobile, Claude Enterprise potrebbe essere una scelta migliore. Consulta la pagina di [disponibilità delle funzionalità](/docs/it/feature-availability) per un confronto completo di tutti i metodi di distribuzione.

11</Note>

12 

13Claude apps gateway è un servizio auto-ospitato che si posiziona tra i client Claude Code dei tuoi sviluppatori e il tuo provider di modelli. Gli sviluppatori accedono con il tuo provider di identità aziendale (IdP) invece di detenere chiavi API o credenziali cloud. Il gateway contiene la credenziale upstream, applica l'accesso ai modelli e le [impostazioni gestite](/docs/it/permissions#managed-settings) per gruppo IdP, e trasmette la telemetria di utilizzo al tuo stack di osservabilità.

14 

15È incluso nel binario `claude`, quindi lo stesso eseguibile che esegue Claude Code su un laptop esegue il server gateway con `claude gateway --config gateway.yaml`.

16 

17Questa pagina copre:

18 

19* [Perché Claude apps gateway](#why-claude-apps-gateway), cosa aggiunge rispetto all'esecuzione della tua, e quando qualcos'altro si adatta meglio

20* Una [guida rapida](#quickstart) con [prerequisiti](#prerequisites) che porta un gateway da zero a uno sviluppatore connesso

21* [Connessione degli sviluppatori](#connect-developers), inclusa l'impostazione dell'URL del gateway attraverso le impostazioni gestite

22* [Disponibilità e limitazioni](#availability-and-limitations) che coprono quali funzionalità di Claude Code funzionano attraverso il gateway e cosa supporta il server

23 

24Le pagine complementari approfondiscono. Il [riferimento di configurazione](/docs/it/claude-apps-gateway-config) copre ogni opzione nel file YAML che la guida rapida scrive, e la [guida di distribuzione](/docs/it/claude-apps-gateway-deploy) copre la configurazione per IdP, la distribuzione su Kubernetes e Cloud Run, e le operazioni.

25 

26<h2 id="why-claude-apps-gateway">

27 Perché Claude apps gateway

28</h2>

29 

30La [panoramica del gateway](/docs/it/gateways) copre cosa fa un gateway e perché ne eseguiresti uno. Claude apps gateway è il gateway di Anthropic, integrato nel binario `claude` e testato insieme a ogni rilascio di Claude Code, quindi inoltra le intestazioni e i campi di richiesta che Claude Code invia senza che gli operatori mantengano un elenco di autorizzazioni separato. Una volta distribuito, ti offre:

31 

32* **Credenziali**: la chiave API upstream o la credenziale cloud vive solo nella tua infrastruttura. Gli sviluppatori si autenticano con SSO aziendale e ricevono token bearer di breve durata, quindi l'offboarding avviene nel tuo IdP. Deprovision un utente e il suo accesso al gateway scade entro la durata della sessione, un'ora per impostazione predefinita.

33* **Controllo di accesso**: i tuoi gruppi IdP si mappano agli elenchi di modelli consentiti e alle politiche di [impostazioni gestite](/docs/it/permissions#managed-settings). Il gateway applica l'accesso ai modelli lato server, rifiutando le richieste per modelli non concessi, e seleziona la politica di impostazioni gestite di ogni gruppo, che il CLI applica al [livello di impostazioni gestite](/docs/it/settings#settings-precedence). Diversi team ottengono diversi modelli, strumenti e autorizzazioni, e uno sviluppatore non può ignorare ciò che la sua politica blocca.

34* **Consegna delle impostazioni**: il gateway consegna le impostazioni gestite ai client connessi stesso, prendendo il posto delle [impostazioni gestite dal server](/docs/it/server-managed-settings) dalla console amministratore di claude.ai.

35* **Telemetria**: ogni destinazione configurata, come Datadog, Splunk o ClickHouse, riceve [metriche OpenTelemetry Protocol (OTLP)](/docs/it/monitoring-usage) con conteggi di token, modello, identità dell'utente e latenza per impostazione predefinita, con log e tracce come opt-in per destinazione.

36* **Instradamento upstream**: i client parlano l'API Anthropic Messages al gateway, e il gateway traduce per ogni upstream, sia Bedrock, [Claude Platform su AWS](/docs/it/claude-platform-on-aws), Agent Platform di Google Cloud, Foundry o l'API Anthropic, con failover tra loro. Puoi cambiare regioni, provider o ordine di failover senza che gli sviluppatori se ne accorgano o riconfigurino.

37 

38<Frame>

39 <img src="https://mintcdn.com/claude-code/st9_ZQOFsZa3cKFl/images/claude-gateway-architecture.svg?fit=max&auto=format&n=st9_ZQOFsZa3cKFl&q=85&s=560770d8f49bbd6f1ca7090ed1f13c03" alt="Diagramma che mostra i client Claude Code che si connettono tramite HTTPS con token bearer a un gateway di app Claude auto-ospitato all'interno della tua infrastruttura, che accede gli utenti rispetto al tuo IdP, archivia lo stato di autenticazione in PostgreSQL, trasmette la telemetria al tuo raccoglitore OTLP e inoltra l'inferenza ad Amazon Bedrock, Claude Platform su AWS, Google Cloud, Microsoft Foundry o all'API Anthropic" width="760" height="320" data-path="images/claude-gateway-architecture.svg" />

40</Frame>

41 

42<Note>

43 Il piano dati del gateway stesso non invia nulla all'infrastruttura Anthropic a meno che l'API Anthropic non sia un upstream configurato. Controlli dove vanno la telemetria, i log di audit, le impostazioni gestite e l'identità IdP dei tuoi sviluppatori, e il gateway non li invia ad Anthropic. Per il traffico rimanente che il processo CLI può inviare e come chiuderlo, vedi [Compliance posture](/docs/it/claude-apps-gateway-deploy#compliance-posture).

44</Note>

45 

46Per quali funzionalità di Claude Code funzionano attraverso il gateway e cosa supporta il server stesso, vedi [Disponibilità e limitazioni](#availability-and-limitations) di seguito. Per decisioni come costo, bypass, esecuzione di più gateway e piattaforme serverless, vedi la [guida di distribuzione](/docs/it/claude-apps-gateway-deploy#deployment).

47 

48<h3 id="other-gateway-implementations">

49 Altre implementazioni di gateway

50</h3>

51 

52Se esegui già un gateway LLM o un gateway API che soddisfa le tue esigenze, continua a usarlo; [Altri gateway LLM](/docs/it/llm-gateway) copre la configurazione di Claude Code rispetto ad esso.

53 

54Il [riferimento del protocollo gateway](/docs/it/llm-gateway-protocol) documenta il contratto che Claude Code si aspetta da qualsiasi gateway: gli endpoint che chiama, le intestazioni e i campi del corpo da inoltrare, e cosa smette di funzionare quando vengono rimossi. Un gateway di app Claude in esecuzione serve un superset di quel contratto su `GET /protocol`, aggiungendo gli endpoint specifici del gateway di app Claude per l'accesso SSO, la consegna delle impostazioni gestite e la telemetria. Recuperalo con `curl https://claude-gateway.internal.example.com/protocol` da qualsiasi gateway distribuito, come quello che la [guida rapida](#quickstart) di seguito produce.

55 

56I cambiamenti di rottura del protocollo vengono annunciati in anticipo, ma la compatibilità all'indietro indefinita non è garantita.

57 

58<h2 id="quickstart">

59 Guida rapida

60</h2>

61 

62Questa guida rapida percorre il percorso minimo: registra un client OAuth nel tuo IdP, scrivi un `gateway.yaml`, esegui il gateway insieme a Postgres con Docker Compose, e verifica l'accesso end-to-end. Utilizza un upstream Amazon Bedrock; Claude Platform su AWS, Agent Platform di Google Cloud, Microsoft Foundry e l'API Anthropic sono ugualmente supportati scambiando il blocco `upstreams` come mostrato nel [riferimento di configurazione](/docs/it/claude-apps-gateway-config#upstreams). Alla fine hai un gateway a cui uno sviluppatore può `/login`.

63 

64<Note>

65 **Distribuisci sulla tua rete privata.** Claude Code si connette solo a un gateway il cui indirizzo è privato. Questo è un meccanismo di sicurezza, perché un gateway affidabile può spingere impostazioni che eseguono comandi su macchine sviluppatore. Posiziona il gateway dietro un load balancer interno o una VPN e assegnagli un nome host che si risolve solo in IP privati.

66 

67 Gli endpoint del gateway pubblico gestiti da Anthropic sono l'eccezione: `/login` li accetta su `https://`. Questi sono un piccolo insieme fisso di gateway che Anthropic stesso gestisce; non sono un'opzione di distribuzione che puoi selezionare o configurare. L'elenco è compilato in Claude Code, quindi nessuna configurazione può aggiungere un nome host ad esso e nessun gateway che ospiti si qualifica per l'esenzione. {/* min-version: 2.1.206 */}Prima della v2.1.206, `/login` rifiutava questi endpoint come qualsiasi altro indirizzo pubblico.

68</Note>

69 

70<h3 id="prerequisites">

71 Prerequisiti

72</h3>

73 

74Avere questi in atto prima di iniziare:

75 

76| Hai bisogno | Dettagli |

77| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| Claude Code v2.1.195 o successivo | Il sottocomando `claude gateway` e il flusso di accesso al gateway vengono spediti in v2.1.195. Le build pubbliche precedenti non le includono. Sia la macchina che esegue il server gateway che la macchina di ogni sviluppatore devono essere su v2.1.195 o successivo; esegui `claude update` per ottenere l'ultimo rilascio. {/* min-version: 2.1.198 */}L'[upstream Claude Platform su AWS](/docs/it/claude-apps-gateway-config#claude-platform-on-aws) richiede Claude Code v2.1.198 o successivo sul server gateway. |

79| Provider di identità OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak, o Dex, o qualsiasi altro IdP conforme a OIDC come PingFederate. Il gateway esegue il discovery OIDC standard e il flusso del codice di autorizzazione rispetto ad esso. SAML e LDAP non sono supportati. |

80| PostgreSQL 14 o successivo | Supporta il flusso di accesso del dispositivo, dove il callback del browser scrive e il CLI di polling legge, più contatori di limite di velocità. Qualsiasi Postgres gestito funziona, incluso il livello più piccolo. Senza limiti di spesa configurati, il gateway archivia pochi KB di stato di autenticazione di breve durata; con [limiti di spesa](/docs/it/claude-apps-gateway-spend-limits), contiene anche tabelle di spesa durevole, audit e identità che dovrebbero essere sottoposte a backup. TLS tramite `?sslmode=require` è consigliato. |

81| Upstream del modello | Credenziali Amazon Bedrock, credenziali Claude Platform su AWS, credenziali Google Cloud, una risorsa Microsoft Foundry o una chiave API Anthropic. Sono supportati più upstream con failover. |

82| HTTPS | Il gateway deve essere raggiungibile su `https://` dai laptop degli sviluppatori e da qualsiasi browser utilizzato per l'accesso; il gateway serve la pagina di verifica del dispositivo sullo stesso listener. Fornisci un certificato TLS tramite `listen.tls` o esegui dietro un ingresso che termina TLS e imposta `listen.public_url`. Un'origine `http://` semplice è accettata solo su loopback, per lo sviluppo locale. |

83| Indirizzo di rete privata | Su `/login`, Claude Code richiede che il nome host o l'indirizzo IP del gateway si risolvano solo in indirizzi privati: RFC 1918, CGNAT `100.64.0.0/10`, IPv6 ULA `fc00::/7` o loopback per lo sviluppo locale. Il controllo viene eseguito su ogni IP risolto, quindi se qualsiasi indirizzo a cui il nome si risolve è pubblico, `/login` rifiuta l'URL. Se le macchine degli sviluppatori instradano HTTPS attraverso un proxy aziendale, l'accesso richiede anche che l'host proxy si risolva in indirizzi privati; se non lo fa, aggiungi l'host del gateway a `NO_PROXY` in modo che il CLI si connetta direttamente. {/* min-version: 2.1.206 */}Gli endpoint del gateway gestiti da Anthropic sono esenti dai controlli di indirizzo privato e proxy: `/login` li accetta su `https://` per corrispondenza esatta del nome host, quindi il requisito di rete privata si applica solo a un gateway che ospiti tu stesso. Prima della v2.1.206, `/login` rifiutava un endpoint gestito da Anthropic come qualsiasi altro indirizzo pubblico. |

84| Runtime Linux | Il server gateway viene eseguito solo sul binario Linux nativo. macOS funziona per lo sviluppo locale. Windows non è supportato come piattaforma server. |

85 

86Il server gateway richiede il binario `claude` nativo; scarica un rilascio bloccato come descritto in [Installa Claude Code](/docs/it/setup). Il server utilizza funzionalità di runtime che non sono disponibili quando Claude Code viene eseguito in Node. Se vedi `requires the native binary` all'avvio, passa a uno dei metodi di installazione standalone.

87 

88<h3 id="steps">

89 Passaggi

90</h3>

91 

92<Steps>

93 <Step title="Registra un client OAuth nel tuo IdP">

94 Decidi prima il nome host del gateway, perché l'URI di reindirizzamento deve corrispondere. Crea una nuova applicazione web OIDC e imposta l'URI di reindirizzamento su `https://claude-gateway.<your-domain>/oauth/callback`, dove l'host è lo stesso valore che imposti come [`listen.public_url`](/docs/it/claude-apps-gateway-config#listen) nel passaggio 3. Annota `client_id` e `client_secret`. Le istruzioni per IdP sono in [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup).

95 </Step>

96 

97 <Step title="Provisioning di un database PostgreSQL">

98 Qualsiasi Postgres 14 o successivo funziona, incluso il livello gestito più piccolo. Il gateway esegue le proprie migrazioni dello schema all'avvio, quindi l'utente del database ha bisogno dell'autorizzazione `CREATE TABLE`. Se la tua politica di sicurezza proibisce DDL dai ruoli dell'applicazione, pre-crea lo schema invece; vedi [`store`](/docs/it/claude-apps-gateway-config#store).

99 </Step>

100 

101 <Step title="Scrivi gateway.yaml">

102 I segreti vengono letti tramite l'espansione `${ENV_VAR}` in modo che il file stesso possa vivere nel controllo della versione. Usa un nome host `public_url` che si risolve in un IP privato sulla tua rete, perché `/login` rifiuta gli indirizzi pubblici. La configurazione minima ha cinque sezioni, e ogni altro campo ha un valore predefinito:

103 

104 ```yaml gateway.yaml theme={null}

105 listen:

106 host: 0.0.0.0

107 port: 8080

108 # Obbligatorio dietro qualsiasi proxy che termina TLS. Utilizzato per l'IdP

109 # redirect_uri e il documento di discovery.

110 public_url: https://claude-gateway.internal.example.com

111 

112 oidc:

113 issuer: https://login.example.com # deve servire /.well-known/openid-configuration

114 client_id: 0oa1example2

115 client_secret: ${OIDC_CLIENT_SECRET}

116 allowed_email_domains: [example.com] # rifiuta id_tokens al di fuori della tua organizzazione

117 userinfo_fallback: true # per IdP il cui id_token omette email/groups; innocuo altrimenti

118 

119 session:

120 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32

121 ttl_hours: 1 # limita anche la latenza di revoca su deprovision IdP

122 

123 store:

124 postgres_url: ${GATEWAY_POSTGRES_URL} # aggiungi ?sslmode=require per Postgres gestito

125 

126 upstreams:

127 - provider: bedrock

128 region: us-east-1

129 auth: {} # vuoto: catena di credenziali predefinita AWS

130 # (IRSA, ruolo attività EC2/ECS, variabili env, ~/.aws)

131 

132 # I modelli vengono tradotti per upstream automaticamente. Il catalogo integrato

133 # mappa claude-opus-4-8 a us.anthropic.claude-opus-4-8 e così via per ogni

134 # modello Claude supportato da Bedrock. Imposta false e aggiungi un elenco `models:` per

135 # esporre solo modelli specifici.

136 auto_include_builtin_models: true

137 ```

138 

139 Questa configurazione è sufficiente per un ciclo di accesso funzionante con il catalogo di modelli Bedrock predefinito. Una volta in esecuzione, aggiungi RBAC per gruppo tramite [`managed.policies`](/docs/it/claude-apps-gateway-config#managed), fan-out di telemetria tramite [`telemetry`](/docs/it/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARN di throughput provisioning o regioni non statunitensi tramite [`models`](/docs/it/claude-apps-gateway-config#models).

140 

141 <Note>

142 L'upstream Bedrock ha bisogno di un principale AWS con `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` sia sugli ARN `inference-profile/us.anthropic.*` che sugli ARN `foundation-model/anthropic.*` sottostanti, e l'accesso ai modelli abilitato nella console Bedrock per i modelli Claude che desideri. Fornisci la credenziale con IRSA su EKS, un ruolo attività ECS o un profilo di istanza EC2 piuttosto che chiavi statiche. Il [riferimento `upstreams`](/docs/it/claude-apps-gateway-config#upstreams) ha i dettagli IAM completi, la matrice di credenziali cross-cloud e i blocchi `auth` per gli altri provider.

143 </Note>

144 </Step>

145 

146 <Step title="Eseguilo">

147 Costruisci un'immagine container attorno al binario `claude` che soddisfi i [requisiti dell'immagine](/docs/it/claude-apps-gateway-deploy#container-image), quindi eseguila insieme a Postgres:

148 

149 ```yaml docker-compose.yaml theme={null}

150 services:

151 gateway:

152 image: <your-registry>/claude-gateway:<version>

153 ports: ["8080:8080"]

154 volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]

155 environment:

156 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

157 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

158 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

159 # Credenziali AWS: in produzione, ometti questi e usa un ruolo di istanza

160 # Per il test locale di Compose, passa i tuoi:

161 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

162 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

163 AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}

164 depends_on:

165 postgres:

166 condition: service_healthy

167 postgres:

168 image: postgres:16-alpine

169 environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }

170 healthcheck:

171 test: ["CMD-SHELL", "pg_isready -U gw"]

172 interval: 5s

173 volumes: ["pgdata:/var/lib/postgresql/data"]

174 volumes: { pgdata: }

175 ```

176 

177 Il gateway è un singolo binario Linux che legge la configurazione, esegue il discovery OIDC rispetto al tuo IdP, applica le migrazioni dello schema Postgres, costruisce client upstream e inizia ad ascoltare. L'avvio è fail-closed per la configurazione, la connessione Postgres con un timeout di 5 secondi, il discovery OIDC e la costruzione del client upstream. Se uno di questi è irraggiungibile o non configurato correttamente, il gateway esce con un errore piuttosto che servire il traffico in uno stato degradato.

178 

179 Un avvio riuscito non convalida il percorso di inferenza, perché le credenziali dell'istanza Bedrock e Agent Platform si risolvono sulla prima richiesta, non all'avvio.

180 

181 Guarda stderr per la sequenza di avvio. Le righe di log utilizzano il formato `[gateway] <timestamp> <level> <message>`, gli eventi di audit sono JSON a riga singola con un campo `evt`, e un banner di avvio, omesso di seguito, viene stampato tra la migrazione e le righe di ascolto. Dovresti vedere, in ordine:

182 

183 ```text theme={null}

184 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

185 [gateway] 2026-06-10T17:03:21.408Z info migration 1 applied

186 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

187 ```

188 

189 Se l'avvio esce prima della riga `claude gateway listening on`, l'ultima riga di stderr nomina il problema:

190 

191 * un Postgres irraggiungibile

192 * un ruolo Postgres senza autorizzazione DDL

193 * un documento di discovery OIDC irraggiungibile o non valido

194 * una violazione dello schema di configurazione con il percorso del campo offensivo

195 

196 Correggilo e riavvia.

197 

198 Se hai già un ingresso che termina TLS, salta Compose ed esegui il binario direttamente con `claude gateway --config gateway.yaml`. Imposta `public_url` all'origine dell'ingresso e associa `listen` a un indirizzo loopback o interno al cluster.

199 </Step>

200 

201 <Step title="Verifica la superficie di autenticazione">

202 Tre controlli confermano che il gateway può autenticare un utente reale prima di consegnarlo a uno sviluppatore.

203 

204 Gli esempi utilizzano l'URL pubblico del gateway; per la configurazione locale di Compose senza un ingresso, sostituisci `http://localhost:8080` nei primi due controlli. Il terzo controllo apre `verification_uri_complete`, che è costruito da `public_url`, quindi per Compose locale imposta `public_url: http://localhost:8080` in `gateway.yaml` e aggiungi `http://localhost:8080/oauth/callback` come secondo URI di reindirizzamento sul client OAuth dal passaggio 1, perché il gateway costruisce l'IdP `redirect_uri` da `public_url`. Il link di verifica si apre quindi nel tuo browser locale.

205 

206 In Windows PowerShell, esegui `curl.exe`; il `curl` semplice è un alias per `Invoke-WebRequest` e rifiuta questi flag.

207 

208 Per primo, recupera il documento di discovery, che conferma che il gateway è attivo, la configurazione è valida e tutti i controlli di avvio sono passati:

209 

210 ```bash theme={null}

211 curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

212 ```

213 

214 ```json theme={null}

215 {

216 "issuer": "https://claude-gateway.internal.example.com",

217 "device_authorization_endpoint": "…/oauth/device_authorization",

218 "token_endpoint": "…/oauth/token",

219 "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]

220 }

221 ```

222 

223 La risposta include campi aggiuntivi, come `response_types_supported` e `scopes_supported`.

224 

225 Secondo, richiedi un'autorizzazione del dispositivo, che conferma che il flusso di accesso del dispositivo funziona e Postgres è raggiungibile e scrivibile:

226 

227 ```bash theme={null}

228 curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

229 ```

230 

231 ```json theme={null}

232 {

233 "device_code": "…",

234 "user_code": "WDJB-MJHT",

235 "verification_uri": "https://claude-gateway.internal.example.com/device",

236 "verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",

237 "expires_in": 600,

238 "interval": 5

239 }

240 ```

241 

242 Terzo, testa la parte del browser aprendo `verification_uri_complete` in un browser e confermando il codice. Dovresti essere reindirizzato alla pagina di accesso del tuo IdP e, dopo l'accesso, tornare al gateway con una conferma di accesso.

243 

244 Usa il primo controllo che fallisce per individuare il problema:

245 

246 * **Il primo controllo fallisce**: l'avvio non è stato completato; controlla stderr

247 * **Il secondo controllo fallisce**: Postgres non è raggiungibile dal gateway o il ruolo non può scrivere; controlla la stringa di connessione e le autorizzazioni

248 * **Il terzo controllo non raggiunge l'IdP**: controlla che l'URI di reindirizzamento dell'IdP corrisponda esattamente a `https://<gateway>/oauth/callback`

249 * **Il terzo controllo raggiunge l'IdP ma rimbalza indietro con un errore**: leggi il log di audit del gateway, che registra ogni rifiuto di autenticazione con il motivo, come `email domain not allowed`

250 </Step>

251 

252 <Step title="Accedi a uno sviluppatore">

253 Questo ultimo passaggio avviene su una macchina sviluppatore, non sul server. Imposta `forceLoginMethod` su `"gateway"` e `forceLoginGatewayUrl` su `public_url` del tuo gateway nel [file delle impostazioni gestite](/docs/it/settings#settings-files) di quella macchina, quindi esegui `/login`, premi Invio sulla schermata **Cloud gateway** e completa l'accesso del browser. [Imposta l'URL del gateway](#set-the-gateway-url) di seguito copre la distribuzione di entrambe le chiavi su larga scala.

254 </Step>

255</Steps>

256 

257<h2 id="connect-developers">

258 Connetti gli sviluppatori

259</h2>

260 

261Gli sviluppatori si connettono dai loro laptop con un accesso al browser, utilizzando il loro account di lavoro aziendale. Non hanno bisogno di un account claude.ai, una chiave API o un abbonamento, perché le richieste al modello passano attraverso il gateway utilizzando la credenziale upstream dell'organizzazione. La connessione è guidata dalle [impostazioni gestite lato client](/docs/it/claude-apps-gateway-config#client-side-managed-settings) che spingere tramite MDM, quindi non c'è configurazione manuale sul lato dello sviluppatore; questa sezione copre cosa configura l'amministratore.

262 

263Il CLI impronta digitale il certificato foglia TLS del gateway al primo collegamento e lo blocca per nome host. Pubblica l'impronta digitale SHA-256 prevista insieme all'URL del gateway in modo che gli sviluppatori abbiano qualcosa da confrontare. Ottieni l'impronta digitale dal file del certificato con `openssl x509 -noout -fingerprint -sha256 -in cert.pem`; il prompt `/login` mostra i primi 16 caratteri del digest come esadecimale minuscolo senza separatori.

264 

265Quando il certificato ruota, ogni sviluppatore vede di nuovo il prompt di fiducia, quindi tratta le rotazioni come un evento pianificato e ripubblica l'impronta digitale.

266 

267Una volta connesso, il [selettore di modelli](/docs/it/model-config) mostra i modelli nell'elenco di autorizzazione `availableModels` dello sviluppatore, le impostazioni gestite si applicano all'avvio e si aggiornano ogni ora, e la telemetria si instrada al tuo raccoglitore. Le sessioni si aggiornano silenziosamente prima della scadenza di `ttl_hours` e un aggiornamento non riuscito dopo il deprovision IdP richiede un nuovo accesso.

268 

269<h3 id="set-the-gateway-url">

270 Imposta l'URL del gateway

271</h3>

272 

273Imposta entrambe le chiavi nel file di [impostazioni gestite](/docs/it/settings#settings-files) per OS che distribuisci tramite MDM o direttamente su disco, e `/login` si apre direttamente sulla schermata **Cloud gateway** con l'URL compilato:

274 

275```json theme={null}

276{

277 "forceLoginMethod": "gateway",

278 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"

279}

280```

281 

282Lo sviluppatore preme Invio per connettersi. Il prompt dell'impronta digitale TLS del primo collegamento appare ancora.

283 

284Non c'è opzione gateway nel selettore di accesso per uno sviluppatore da selezionare manualmente, e `forceLoginGatewayUrl` viene ignorato nei file di impostazioni personali di uno sviluppatore. `forceLoginMethod` da solo, senza un URL, lascia lo sviluppatore con un messaggio "Contatta il tuo amministratore IT". Entrambe le chiavi appartengono al file che spingere alle macchine, non al blocco `managed.policies[].cli` del gateway, che raggiunge solo i client già connessi.

285 

286<h3 id="ci-pipelines-and-remote-machines">

287 Pipeline CI e macchine remote

288</h3>

289 

290Non c'è flusso di token di servizio per pipeline non presenziate. L'accesso al gateway esegue sempre il flusso del dispositivo del browser, quindi un lavoro CI senza uno sviluppatore per approvare l'accesso non può autenticarsi; configura quelli direttamente contro il tuo provider.

291 

292Una volta che uno sviluppatore ha effettuato l'accesso, ogni invocazione di Claude Code su quella macchina utilizza la sessione del gateway, incluse le esecuzioni non interattive `claude -p` e le sessioni avviate da Agent SDK, e la [politica del gateway si applica a tutte](/docs/it/claude-apps-gateway-config#managed).

293 

294Il flusso del dispositivo separa il CLI di polling dal browser di approvazione, quindi una scatola di sviluppo remoto senza display funziona ancora: lo sviluppatore esegue `/login` su SSH sulla macchina remota e apre il link di verifica nel browser sul suo laptop.

295 

296<h3 id="what’s-enforced-on-developers">

297 Cosa viene applicato agli sviluppatori

298</h3>

299 

300Queste garanzie si applicano a ogni sessione gateway connessa.

301 

302* **Accesso ai modelli**: le richieste per modelli che la politica non concede restituiscono 400 e il selettore `/model` viene filtrato all'elenco di autorizzazione `availableModels` della politica. Imposta [`enforceAvailableModels: true`](/docs/it/model-config#default-model-behavior) nella politica in modo che l'opzione Predefinita si risolva in un modello all'interno di `availableModels` invece che al valore predefinito integrato di Claude Code; senza di esso, Predefinita rimane selezionabile e viene rifiutata al momento della richiesta se quel modello non è concesso.

303* **Destinazione telemetria**: quando è configurato l'[inoltro di telemetria](/docs/it/claude-apps-gateway-config#telemetry), l'endpoint di esportazione OTLP è bloccato al gateway e la configurazione spinta dal gateway sostituisce le variabili `OTEL_*` impostate localmente.

304* **Credenziali**: il token del gateway è l'unica credenziale della sessione. `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `apiKeyHelper` e qualsiasi accesso precedente a claude.ai vengono ignorati mentre connesso, quindi gli sviluppatori non hanno bisogno di disconnettersi da claude.ai per primo.

305* **Impostazioni gestite**: le chiavi bloccate non possono essere ignorate localmente. Il CLI applica la politica all'avvio e su ogni sondaggio orario.

306* **Avvio**: le sessioni connesse escono all'avvio con un errore dopo circa 10 secondi quando il gateway è irraggiungibile, piuttosto che iniziare senza le loro impostazioni.

307* **Deprovision**: una sessione il cui utente è disabilitato nell'IdP scade entro `ttl_hours` quando il prossimo aggiornamento fallisce.

308 

309<h3 id="what-the-organization-can-see">

310 Cosa può vedere l'organizzazione

311</h3>

312 

313La telemetria di utilizzo porta l'identità dello sviluppatore, i conteggi di token, il modello e la latenza al raccoglitore dell'organizzazione. Il gateway non registra o archivia il contenuto del prompt o del completamento. Se viene raccolta una telemetria più ricca come log e tracce, che può includere comandi e percorsi di file, è la [scelta per destinazione](/docs/it/claude-apps-gateway-config#telemetry) dell'organizzazione.

314 

315<h2 id="availability-and-limitations">

316 Disponibilità e limitazioni

317</h2>

318 

319La tabella copre quali funzionalità di Claude Code funzionano quando gli sviluppatori si connettono attraverso il gateway e cosa supporta il server gateway stesso. Dove qualcosa non è supportato, la colonna Note fornisce l'alternativa.

320 

321Il gateway consegna i valori [`anthropic-beta`](https://platform.claude.com/docs/en/api/beta-headers) che il CLI invia a ogni upstream, quindi gli operatori non mantengono un elenco di autorizzazioni beta. Per Amazon Bedrock, che ignora l'intestazione, il gateway sposta i valori nel campo `anthropic_beta` del corpo della richiesta; gli altri upstream ricevono l'intestazione come inviata.

322 

323L'insieme beta della sessione del gateway del CLI omette i beta solo per la prima parte e il beta della cache estesa, ecco perché quelle righe di seguito mostrano come non disponibili.

324 

325| Funzionalità | Stato | Note |

326| --------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

327| Inoltro di inferenza (Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud, Microsoft Foundry, Anthropic) | Disponibile | Con traduzione del modello per upstream e failover. L'upstream Amazon Bedrock utilizza l'endpoint `bedrock-runtime` e la catena di credenziali predefinita AWS; l'[endpoint Mantle](/docs/it/amazon-bedrock#use-the-mantle-endpoint) di Amazon Bedrock non è un upstream supportato. L'[upstream Claude Platform su AWS](/docs/it/claude-apps-gateway-config#claude-platform-on-aws) richiede Claude Code v2.1.198 o successivo sul server gateway. |

328| Accesso ai modelli e impostazioni gestite per gruppo IdP | Disponibile | L'accesso ai modelli viene applicato lato server; le impostazioni gestite vengono consegnate per gruppo IdP e applicate dal CLI al [livello di impostazioni gestite](/docs/it/settings#settings-precedence) |

329| Fan-out di telemetria (OTLP/HTTP) | Disponibile | Identità-timbrato per esportazione; entrambe le codifiche protobuf e JSON |

330| Provider di identità OIDC | Disponibile | Qualsiasi IdP conforme a OIDC; il gateway esegue il discovery OIDC standard e il flusso del codice di autorizzazione. Vedi [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup) per la configurazione per IdP |

331| Limiti di spesa per utente e per gruppo | Disponibile | Vedi [Limiti di spesa](/docs/it/claude-apps-gateway-spend-limits) |

332| Ricerca web lato server | Non disponibile | Il CLI non può vedere quale provider upstream il gateway instrada, quindi non può verificare il supporto della ricerca web e disabilita WebSearch sulle sessioni del gateway |

333| Caching del prompt standard | Disponibile | I breakpoint `cache_control` vengono inoltrati a ogni upstream |

334| TTL cache di 1 ora | Non disponibile | Il CLI omette il beta della cache estesa sulle sessioni del gateway, perché non ogni upstream a cui il gateway può instradare supporta il TTL di 1 ora, quindi il caching del prompt attraverso il gateway utilizza il TTL di 5 minuti; vedi la nota dell'intestazione beta sopra |

335| Modalità Auto | Disponibile | Segue le [regole del provider di terze parti](/docs/it/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry): solo i modelli idonei sui provider di terze parti possono usarlo. {/* min-version: 2.1.207 */}Prima della v2.1.207, la modalità auto sulle sessioni del gateway richiedeva l'impostazione di `CLAUDE_CODE_ENABLE_AUTO_MODE=1`, consegnabile tramite il blocco `env` della politica gestita |

336| Ottimizzazioni solo per la prima parte come ambito cache globale e strumenti efficienti in termini di token | Non disponibile | Il CLI non le abilita sulle sessioni del gateway; vedi la nota dell'intestazione beta sopra |

337| OTLP/gRPC | Non supportato | OTLP su HTTP solo |

338| SAML, LDAP e altri auth non OIDC | Non supportato | Solo OIDC. Fronte con un ponte OIDC se necessario |

339| Multi-tenant (più emittenti OIDC) | Non supportato | Un emittente per gateway. Esegui istanze separate |

340| Server Windows | Non supportato | Distribuisci su Linux. macOS solo per lo sviluppo locale |

341| Helm chart | Non disponibile | Il gateway viene eseguito come una Deployment stateless standard; vedi la [guida di distribuzione](/docs/it/claude-apps-gateway-deploy#kubernetes) |

342| Interfaccia utente amministratore | Non disponibile | La configurazione è il file YAML; ridistribuisci per cambiarla |

343 

344<h2 id="next-steps">

345 Passaggi successivi

346</h2>

347 

348La guida rapida ti lascia con una configurazione minima in esecuzione sotto Docker Compose. Per andare oltre:

349 

350* Espandi `gateway.yaml` oltre la configurazione minima, ad esempio per aggiungere RBAC per gruppo, failover multi-upstream o destinazioni di telemetria. Il [riferimento di configurazione](/docs/it/claude-apps-gateway-config) copre ogni opzione.

351* Passa da Compose a una distribuzione di produzione su Kubernetes o Cloud Run, configura correttamente il tuo IdP e rivedi il modello di sicurezza. La [guida di distribuzione e operazioni](/docs/it/claude-apps-gateway-deploy) copre la configurazione per IdP, i requisiti dell'immagine container, i probe di salute e la risoluzione dei problemi.

352* Metti limiti di spesa su singoli sviluppatori o gruppi in modo che un carico di lavoro incontrollato non possa consumare il tuo intero impegno. [Limiti di spesa](/docs/it/claude-apps-gateway-spend-limits) copre l'API amministratore e come funziona l'applicazione.

353* Per un esempio completo su Google Cloud, con Cloud Run, Cloud SQL e Secret Manager, vedi [Distribuisci su Google Cloud](/docs/it/claude-apps-gateway-on-gcp).

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Eseguire Claude Code dietro un launcher aziendale

6 

7> Instradare i processi che Claude Code avvia dal suo binario, incluso il servizio in background e ogni sessione di agent view, attraverso un launcher obbligatorio con CLAUDE_CODE_PROCESS_WRAPPER.

8 

9Alcune organizzazioni richiedono che ogni processo su una workstation si avvii attraverso un launcher obbligatorio. Il launcher applica la sandbox, i controlli di rete o l'iniezione di credenziali da cui dipende la postura di sicurezza dell'azienda, e un binario che si avvia senza di esso è una violazione della policy.

10 

11`CLAUDE_CODE_PROCESS_WRAPPER` avvia ogni processo che Claude Code lancia dal suo binario attraverso il vostro launcher: il servizio in background, ogni sessione che ospita in [agent view](/docs/it/agent-view), e i riavvii di Claude Code dopo un aggiornamento. Impostatelo al percorso assoluto del vostro launcher, e Claude Code eseguirà il launcher con il comando di Claude Code come suoi argomenti.

12 

13Un launcher che avvolge il comando `claude` nel vostro `PATH` non può raggiungere questi processi, perché si avviano dal percorso diretto del binario senza consultare `claude`.

14 

15<Note>

16 `CLAUDE_CODE_PROCESS_WRAPPER` richiede Claude Code v2.1.208 o successivo. Le versioni precedenti ignorano la variabile e avviano ogni processo senza wrapper.

17</Note>

18 

19<h2 id="what-the-launcher-covers">

20 Cosa copre il launcher

21</h2>

22 

23Con `CLAUDE_CODE_PROCESS_WRAPPER` impostato, Claude Code avvia ognuno dei seguenti processi attraverso il vostro launcher:

24 

25* Il servizio in background che `claude agents` e le sessioni in background avviano su richiesta.

26* L'host del terminale e la sessione di Claude Code all'interno di ogni riga di agent view, incluse le sessioni di standby caldo che il servizio mantiene pronte.

27* Le sessioni che il servizio riavvia dopo un aggiornamento o un crash.

28* Il riavvio che Claude Code esegue di se stesso per completare l'installazione di un aggiornamento, inclusa l'azione restart-for-update di agent view.

29 

30Su Windows, la variabile viene ignorata: il contratto del launcher dipende da `exec`, che Windows non supporta. Una macchina Windows con la variabile impostata esegue ogni processo senza wrapper e continua a funzionare, e l'unico segnale è un avviso nel [debug log](/docs/it/troubleshooting). Se la vostra policy del launcher copre Windows, la variabile non la soddisfa lì: contate le macchine Windows come senza wrapper quando pianificate il rollout.

31 

32<h3 id="processes-that-start-outside-the-launcher">

33 Processi che si avviano al di fuori del launcher

34</h3>

35 

36Tre processi non si avviano mai attraverso il launcher:

37 

38* Un [servizio in background installato](/docs/it/agent-view#the-supervisor-process): `launchd` o `systemd` avvia quel processo dal suo file di unità. `/status` e `claude daemon status` avvertono quando questo si applica, e le sessioni che il servizio genera si avviano comunque attraverso il launcher una volta che il servizio si riavvia con la variabile nelle sue impostazioni.

39* Una sessione che avviate voi stessi in un terminale, che viene eseguita come l'avete invocata. Per coprire queste sessioni, mettete uno script denominato `claude` in una directory precedente su `PATH` che esegue il vostro launcher con il binario reale; non sostituite il symlink gestito. Gli auto-spawn non consultano `PATH`, quindi i due launcher non si impilano mai.

40* Il primo processo di un deep link `claude-cli://`, che il gestore del protocollo del sistema operativo avvia direttamente. Tutto ciò che quella sessione avvia in background in seguito viene eseguito attraverso il launcher. Per chiudere completamente questo percorso, [impedite la registrazione del gestore](/docs/it/deep-links#registration-and-supported-platforms) con l'impostazione `disableDeepLinkRegistration`.

41 

42<h3 id="helper-process-names-in-process-monitors">

43 Nomi dei processi helper nei monitor dei processi

44</h3>

45 

46Con un launcher configurato, `ps` e Activity Monitor mostrano il nome del binario con versione per i processi helper in background invece delle etichette `claude bg-pty-host` e `claude bg-spare` di Claude Code, perché l'`exec` del launcher ricostruisce l'elenco degli argomenti. La ridenominazione è un effetto collaterale, non un occultamento: i processi sono altrimenti invariati, e Claude Code identifica i suoi processi dal percorso del binario, mai dal nome visualizzato.

47 

48<h2 id="set-up-the-launcher">

49 Configurare il launcher

50</h2>

51 

52<Steps>

53 <Step title="Scrivere lo script del launcher">

54 Create uno script eseguibile in un percorso assoluto, come `/opt/corp/launcher`. Claude Code lo esegue con il comando completo di Claude Code come suoi argomenti, e lo script deve terminare chiamando `exec "$@"` in modo che si sostituisca con Claude Code:

55 

56 ```bash theme={null}

57 #!/bin/sh

58 # La configurazione della vostra organizzazione: entrare nella sandbox, applicare

59 # controlli di rete o iniettare credenziali.

60 exec "$@"

61 ```

62 

63 Rendetelo eseguibile con `chmod +x`. La parte di configurazione è tutto ciò che il vostro launcher deve fare prima che Claude Code venga eseguito; [il contratto del launcher](#the-launcher-contract) di seguito elenca le regole che lo script deve seguire.

64 

65 <Note>

66 Se in precedenza avete sostituito il symlink `~/.local/bin/claude` con il vostro launcher, ripristinate il symlink originale nello stesso cambio. Un symlink sostituito fa sì che la prima sessione avvolta avvii il servizio in background attraverso entrambi i launcher contemporaneamente, e mette l'installazione in uno stato gestito esternamente: `/doctor` lo segnala, l'auto-update lascia il file in posizione, e la pulizia delle versioni precedenti rimane disabilitata finché l'installer non gestisce di nuovo quel percorso.

67 </Note>

68 </Step>

69 

70 <Step title="Impostare CLAUDE_CODE_PROCESS_WRAPPER nelle impostazioni">

71 Impostate la variabile nel blocco `env` di un file di impostazioni in modo che il servizio in background staccato la erediti. Un `export` di shell non è sufficiente: il servizio in background si avvia su richiesta, sopravvive alla vostra shell e non rilegge mai i profili di shell.

72 

73 Per una macchina, aggiungetela a `~/.claude/settings.json`. Per distribuirla a ogni macchina della vostra organizzazione, mettete lo stesso blocco in [managed settings](/docs/it/permissions#managed-settings):

74 

75 ```json theme={null}

76 {

77 "env": {

78 "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"

79 }

80 }

81 ```

82 

83 Quando più di una fonte imposta la variabile, il valore delle managed settings sovrascrive sia `~/.claude/settings.json` che un valore esportato nella shell, quindi gli utenti non possono puntare gli auto-spawn a un launcher diverso.

84 

85 Le impostazioni di progetto e locali non possono impostare questa variabile. Un file sottoposto a commit in un repository non deve essere in grado di mettere un binario davanti a ogni processo di Claude Code sulla macchina, quindi `CLAUDE_CODE_PROCESS_WRAPPER` in `.claude/settings.json` o `.claude/settings.local.json` viene ignorato, con un avviso nel [debug log](/docs/it/troubleshooting).

86 </Step>

87 

88 <Step title="Riavviare il servizio in background e le vostre sessioni">

89 Un servizio in background in esecuzione e qualsiasi sessione `claude` aperta leggono la variabile una volta all'avvio, quindi continuano ad avviare processi senza wrapper finché non vengono riavviati. Eseguite `claude daemon stop --any` per fermare il servizio su richiesta; il comando successivo che ne ha bisogno, come `claude agents`, avvia uno avvolto. Un [servizio installato](/docs/it/agent-view#the-supervisor-process) accetta `claude daemon stop` senza `--any`. Quindi riavviate le vostre sessioni `claude` aperte.

90 

91 Su macchine che non potete riavviare manualmente, la prima sessione avviata dopo il push delle impostazioni ritira automaticamente un servizio su richiesta senza wrapper rimasto. Una macchina dove non si avvia nessuna nuova sessione mantiene il suo servizio senza wrapper finché non lo fa, e un servizio installato ha sempre bisogno del riavvio in questo passaggio.

92 </Step>

93 

94 <Step title="Verificare">

95 Eseguite `/status` in una sessione: la voce Self-exec mostra il comando di avvio risolto e avverte quando il servizio in background in esecuzione non corrisponde. `claude daemon status` stampa le stesse informazioni dalla shell, incluso dopo che avete annullato l'impostazione della variabile, quando `/status` non mostra più la voce.

96 </Step>

97</Steps>

98 

99<h2 id="the-launcher-contract">

100 Il contratto del launcher

101</h2>

102 

103Quando il launcher non può essere eseguito, Claude Code rifiuta di avviare il processo invece di avviarlo senza wrapper. Su Windows, [la variabile viene ignorata](#what-the-launcher-covers) e i processi si avviano senza wrapper. Claude Code tiene lo script a queste regole:

104 

105* **Terminare con `exec "$@"`**. Un launcher che crea un fork di un figlio e esce lascia un processo Claude Code orfano che il servizio in background non può tracciare. Agent view contrassegna tale sessione come non riuscita con un messaggio che nomina il launcher, e il servizio raccoglie ciò che il launcher ha lasciato indietro.

106* **Non riordinare, assorbire o anteporre argomenti.** Il primo argomento è il binario di Claude Code e tutto ciò che segue è il suo argv.

107* **Passare ogni variabile di ambiente ereditata attraverso a `exec`.** Aggiungere variabili, come credenziali iniettate, va bene; eliminare quelle ereditate no.

108 * I token di autenticazione per sessione, la selezione del modello e del provider, e `CLAUDE_CODE_PROCESS_WRAPPER` stesso viaggiano tutti sull'ambiente ereditato, quindi un launcher che lo ricostruisce da un elenco di autorizzazione interrompe le sessioni che avvia, e `/status` segnala una mancata corrispondenza del launcher.

109 * Se il launcher deve entrare in uno spazio dei nomi o in una sandbox che ripristina l'ambiente, ri-esportate l'ambiente ereditato all'interno di esso verbatim.

110* **Raggiungere `exec` entro circa tre secondi ogni volta che il launcher viene eseguito.** Un dispatch in background a freddo esegue il launcher due volte in serie prima del primo byte di output, quindi fate il lavoro lento come uno scambio di single sign-on pigrizia o da una cache.

111 * Un launcher che funziona molto oltre il budget viene trattato come un avvio bloccato e riavviato.

112* **Tollerare di essere invocato da dentro se stesso.** Claude Code applica il launcher a ogni auto-spawn annidato, quindi un launcher che acquisisce una risorsa esclusiva deve rilevare che la detiene già.

113* **Non scrivere nel terminale prima che Claude Code si avvii.** Qualsiasi cosa stampata prima dell'`exec` viene segnalata come causa del crash se la sessione muore prima dell'inizializzazione.

114 

115<h3 id="format-of-the-claude_code_process_wrapper-value">

116 Formato del valore `CLAUDE_CODE_PROCESS_WRAPPER`

117</h3>

118 

119Per la maggior parte dei launcher, il valore è solo il percorso assoluto dello script, come `/opt/corp/launcher`.

120 

121Per passare al vostro launcher argomenti propri, scrivete dopo il percorso. Claude Code analizza il valore come un elenco di argomenti, non un comando di shell:

122 

123* Lo spazio bianco separa i token, e le virgolette doppie raggruppano un token che contiene spazi.

124* Un valore che inizia con `[` viene letto come un array di stringhe JSON, come `["/opt/corp/launcher", "--profile", "cc"]`.

125* La sintassi di shell non funziona: non c'è espansione di variabili o globbing, e un operatore non quotato come `;`, `|`, `&`, o `$(` viene rifiutato come errore di configurazione piuttosto che reinterpretato.

126 

127Quando il valore non può essere utilizzato, Claude Code rifiuta di avviare il processo interessato e [segnala il motivo](/docs/it/errors#claude_code_process_wrapper-launcher-errors).

128 

129<h2 id="relationship-to-claude_code_shell_prefix">

130 Relazione con `CLAUDE_CODE_SHELL_PREFIX`

131</h2>

132 

133`CLAUDE_CODE_PROCESS_WRAPPER` avvolge i processi propri di Claude Code e passa il comando attraverso come token argv separati per il launcher a cui eseguire `exec`. [`CLAUDE_CODE_SHELL_PREFIX`](/docs/it/env-vars) avvolge i comandi di shell che Claude Code esegue per vostro conto, come le chiamate dello strumento Bash, gli hook e i comandi che avviano i server MCP stdio, e passa ognuno come una singola stringa quotata di shell in `$1` per il wrapper da rivalutare. Un launcher scritto per uno non funziona come l'altro.

134 

135<h2 id="related-resources">

136 Risorse correlate

137</h2>

138 

139* [Agent view](/docs/it/agent-view): le sessioni in background e il processo supervisore che il launcher copre

140* [Environment variables](/docs/it/env-vars): la voce di riferimento `CLAUDE_CODE_PROCESS_WRAPPER`

141* [Managed settings](/docs/it/permissions#managed-settings): consegnare il blocco `env` in tutta una flotta

142* [Launcher error reference](/docs/it/errors#claude_code_process_wrapper-launcher-errors): i messaggi di rifiuto e come recuperare

12 12 

13<Warning>13<Warning>

14 Sebbene il dev container fornisca protezioni sostanziali, nessun sistema è completamente immune da tutti gli attacchi.14 Sebbene il dev container fornisca protezioni sostanziali, nessun sistema è completamente immune da tutti gli attacchi.

15 Quando eseguito con `--dangerously-skip-permissions`, i dev container non impediscono a un progetto dannoso di estrarre qualsiasi cosa accessibile all'interno del contenitore, incluse le credenziali di Claude Code archiviate in [`~/.claude`](/it/claude-directory).15 Quando eseguito con `--dangerously-skip-permissions`, i dev container non impediscono a un progetto dannoso di estrarre qualsiasi cosa accessibile all'interno del contenitore, incluse le credenziali di Claude Code archiviate in [`~/.claude`](/docs/it/claude-directory).

16 Utilizza i dev container solo quando sviluppi con repository affidabili e monitora le attività di Claude.16 Utilizza i dev container solo quando sviluppi con repository affidabili e monitora le attività di Claude.

17 Evita di montare segreti host come `~/.ssh` o file di credenziali cloud nel contenitore; preferisci token con ambito repository o di breve durata.17 Evita di montare segreti host come `~/.ssh` o file di credenziali cloud nel contenitore; preferisci token con ambito repository o di breve durata.

18</Warning>18</Warning>

20<Accordion title="Come i dev container funzionano con il tuo editor">20<Accordion title="Come i dev container funzionano con il tuo editor">

21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="Diagramma che mostra un editor sull'host che si connette a un dev container Docker. Claude Code, il terminale e gli strumenti di build vengono eseguiti all'interno del contenitore. Il repository host è bind-montato nel contenitore come workspace." width="640" height="300" data-path="images/devcontainer-architecture.svg" />21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="Diagramma che mostra un editor sull'host che si connette a un dev container Docker. Claude Code, il terminale e gli strumenti di build vengono eseguiti all'interno del contenitore. Il repository host è bind-montato nel contenitore come workspace." width="640" height="300" data-path="images/devcontainer-architecture.svg" />

22 22 

23 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=ef00c8e25b1ea7a3a152895f1488831b" className="hidden dark:block" alt="Diagramma che mostra un editor sull'host che si connette a un dev container Docker. Claude Code, il terminale e gli strumenti di build vengono eseguiti all'interno del contenitore. Il repository host è bind-montato nel contenitore come workspace." width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />23 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=a0a340b1f2afc6a590696102c8acaaca" className="hidden dark:block" alt="Diagramma che mostra un editor sull'host che si connette a un dev container Docker. Claude Code, il terminale e gli strumenti di build vengono eseguiti all'interno del contenitore. Il repository host è bind-montato nel contenitore come workspace." width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />

24 24 

25 Un dev container viene eseguito come contenitore Docker, sia sulla tua macchina che su un host cloud come GitHub Codespaces. Un editor che supporta la specifica Dev Containers, come VS Code, GitHub Codespaces, un IDE JetBrains o Cursor, si connette a quel contenitore: navighi e modifichi i file nell'editor come al solito, ma il terminale integrato, i language server e gli strumenti di build vengono tutti eseguiti all'interno del contenitore piuttosto che sul tuo host. Gli editor senza supporto per dev container, come Vim semplice, non fanno parte di questo flusso di lavoro.25 Un dev container viene eseguito come contenitore Docker, sia sulla tua macchina che su un host cloud come GitHub Codespaces. Un editor che supporta la specifica Dev Containers, come VS Code, GitHub Codespaces, un IDE JetBrains o Cursor, si connette a quel contenitore: navighi e modifichi i file nell'editor come al solito, ma il terminale integrato, i language server e gli strumenti di build vengono tutti eseguiti all'interno del contenitore piuttosto che sul tuo host. Gli editor senza supporto per dev container, come Vim semplice, non fanno parte di questo flusso di lavoro.

26 26 

27 Claude Code viene eseguito all'interno del contenitore, quindi vede gli stessi file, dipendenze e strumenti del resto della toolchain del tuo progetto. In VS Code puoi utilizzare il [pannello dell'estensione Claude Code](/it/vs-code) o eseguire `claude` nel terminale integrato; entrambi vengono eseguiti all'interno del contenitore e condividono la stessa configurazione `~/.claude`.27 Claude Code viene eseguito all'interno del contenitore, quindi vede gli stessi file, dipendenze e strumenti del resto della toolchain del tuo progetto. In VS Code puoi utilizzare il [pannello dell'estensione Claude Code](/docs/it/vs-code) o eseguire `claude` nel terminale integrato; entrambi vengono eseguiti all'interno del contenitore e condividono la stessa configurazione `~/.claude`.

28</Accordion>28</Accordion>

29 29 

30<h2 id="add-claude-code-to-your-dev-container">30<h2 id="add-claude-code-to-your-dev-container">

75Quello che vedi al prompt di autenticazione dipende dal tuo provider:75Quello che vedi al prompt di autenticazione dipende dal tuo provider:

76 76 

77* **Anthropic**: accedi tramite browser con il tuo account Claude o Anthropic Console77* **Anthropic**: accedi tramite browser con il tuo account Claude o Anthropic Console

78* **[Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry](/it/third-party-integrations)**: Claude Code utilizza le tue credenziali del provider cloud, senza prompt del browser78* **[Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry](/docs/it/third-party-integrations)**: Claude Code utilizza le tue credenziali del provider cloud, senza prompt del browser

79 79 

80Per i provider cloud, passa le credenziali nel contenitore come variabili di ambiente tramite `containerEnv`, un segreto di Codespaces, o l'identità del carico di lavoro del tuo cloud piuttosto che montare file di credenziali dall'host. Vedi [Amazon Bedrock](/it/amazon-bedrock), [Google Cloud's Agent Platform](/it/google-vertex-ai), o [Microsoft Foundry](/it/microsoft-foundry) per la catena di credenziali che Claude Code legge.80Per i provider cloud, passa le credenziali nel contenitore come variabili di ambiente tramite `containerEnv`, un segreto di Codespaces, o l'identità del carico di lavoro del tuo cloud piuttosto che montare file di credenziali dall'host. Vedi [Amazon Bedrock](/docs/it/amazon-bedrock), [Google Cloud's Agent Platform](/docs/it/google-vertex-ai), o [Microsoft Foundry](/docs/it/microsoft-foundry) per la catena di credenziali che Claude Code legge.

81 81 

82Vedi [Scegli il tuo provider API](/it/admin-setup#choose-your-api-provider) per decidere quale percorso si adatta alla tua organizzazione.82Vedi [Scegli il tuo provider API](/docs/it/admin-setup#choose-your-api-provider) per decidere quale percorso si adatta alla tua organizzazione.

83 83 

84<Note>84<Note>

85 Se l'accesso al browser si completa ma il callback non raggiunge mai il contenitore, copia il codice mostrato nel browser e incollalo al prompt `Paste code here if prompted` nel terminale. Questo può accadere quando l'inoltro delle porte dell'editor non instrada il callback localhost.85 Se l'accesso al browser si completa ma il callback non raggiunge mai il contenitore, copia il codice mostrato nel browser e incollalo al prompt `Paste code here if prompted` nel terminale. Questo può accadere quando l'inoltro delle porte dell'editor non instrada il callback localhost.

89 Mantieni l'autenticazione e le impostazioni tra i rebuild89 Mantieni l'autenticazione e le impostazioni tra i rebuild

90</h2>90</h2>

91 91 

92Per impostazione predefinita, la directory home del contenitore viene scartata al rebuild, quindi gli ingegneri devono accedere di nuovo ogni volta. Claude Code archivia il suo token di autenticazione, le impostazioni utente e la cronologia della sessione in [`~/.claude`](/it/claude-directory). Monta un volume denominato in quel percorso per mantenere questo stato tra i rebuild.92Per impostazione predefinita, la directory home del contenitore viene scartata al rebuild, quindi gli ingegneri devono accedere di nuovo ogni volta. Claude Code archivia il suo token di autenticazione, le impostazioni utente e la cronologia della sessione in [`~/.claude`](/docs/it/claude-directory). Monta un volume denominato in quel percorso per mantenere questo stato tra i rebuild.

93 93 

94L'esempio seguente monta un volume nella directory home dell'utente `node`:94L'esempio seguente monta un volume nella directory home dell'utente `node`:

95 95 

99]99]

100```100```

101 101 

102Sostituisci `/home/node` con la directory home del `remoteUser` del tuo contenitore. Se monti il volume in un luogo diverso da `~/.claude`, imposta [`CLAUDE_CONFIG_DIR`](/it/env-vars) al percorso di montaggio in modo che Claude Code legga e scriva lì.102Sostituisci `/home/node` con la directory home del `remoteUser` del tuo contenitore. Se monti il volume in un luogo diverso da `~/.claude`, imposta [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars) al percorso di montaggio in modo che Claude Code legga e scriva lì.

103 103 

104Per isolare lo stato per progetto piuttosto che condividere un volume su tutti i repository, includi la variabile `${devcontainerId}` nel nome della sorgente. La [configurazione di riferimento](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) utilizza `source=claude-code-config-${devcontainerId}` per questo scopo.104Per isolare lo stato per progetto piuttosto che condividere un volume su tutti i repository, includi la variabile `${devcontainerId}` nel nome della sorgente. La [configurazione di riferimento](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) utilizza `source=claude-code-config-${devcontainerId}` per questo scopo.

105 105 

106In GitHub Codespaces, `~/.claude` persiste tra l'arresto e l'avvio di un codespace, ma viene comunque cancellato quando ricostruisci il contenitore, quindi il mount del volume sopra si applica anche lì. Per portare l'autenticazione tra i codespace, archivia `ANTHROPIC_API_KEY` o un `CLAUDE_CODE_OAUTH_TOKEN` da [`claude setup-token`](/it/authentication#generate-a-long-lived-token) come [segreto di Codespaces](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces); Codespaces rende i segreti disponibili come variabili di ambiente all'interno del contenitore automaticamente.106In GitHub Codespaces, `~/.claude` persiste tra l'arresto e l'avvio di un codespace, ma viene comunque cancellato quando ricostruisci il contenitore, quindi il mount del volume sopra si applica anche lì. Per portare l'autenticazione tra i codespace, archivia `ANTHROPIC_API_KEY` o un `CLAUDE_CODE_OAUTH_TOKEN` da [`claude setup-token`](/docs/it/authentication#generate-a-long-lived-token) come [segreto di Codespaces](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces); Codespaces rende i segreti disponibili come variabili di ambiente all'interno del contenitore automaticamente.

107 107 

108<h2 id="enforce-organization-policy">108<h2 id="enforce-organization-policy">

109 Applica la politica organizzativa109 Applica la politica organizzativa

111 111 

112Un dev container è un luogo conveniente per applicare la politica organizzativa, perché la stessa immagine e configurazione vengono eseguite sulla macchina di ogni ingegnere.112Un dev container è un luogo conveniente per applicare la politica organizzativa, perché la stessa immagine e configurazione vengono eseguite sulla macchina di ogni ingegnere.

113 113 

114Claude Code legge `/etc/claude-code/managed-settings.json` su Linux e lo applica con la massima precedenza nella [gerarchia delle impostazioni](/it/settings#how-scopes-interact), quindi i valori lì sovrascrivono qualsiasi cosa un ingegnere imposti in `~/.claude` o nella directory `.claude/` del progetto. Copia il file in posizione dal tuo Dockerfile:114Claude Code legge `/etc/claude-code/managed-settings.json` su Linux e lo applica con la massima precedenza nella [gerarchia delle impostazioni](/docs/it/settings#how-scopes-interact), quindi i valori lì sovrascrivono qualsiasi cosa un ingegnere imposti in `~/.claude` o nella directory `.claude/` del progetto. Copia il file in posizione dal tuo Dockerfile:

115 115 

116```dockerfile Dockerfile theme={null}116```dockerfile Dockerfile theme={null}

117RUN mkdir -p /etc/claude-code117RUN mkdir -p /etc/claude-code

118COPY managed-settings.json /etc/claude-code/managed-settings.json118COPY managed-settings.json /etc/claude-code/managed-settings.json

119```119```

120 120 

121Poiché il Dockerfile risiede nel repository, chiunque abbia accesso in scrittura può modificare o rimuovere questo passaggio. Per la politica che gli ingegneri non possono aggirare modificando i file del repository, fornisci le impostazioni gestite tramite [impostazioni gestite dal server](/it/server-managed-settings) o il tuo MDM. Vedi [file di impostazioni gestite](/it/settings#settings-files) per le chiavi disponibili e gli altri percorsi di consegna.121Poiché il Dockerfile risiede nel repository, chiunque abbia accesso in scrittura può modificare o rimuovere questo passaggio. Per la politica che gli ingegneri non possono aggirare modificando i file del repository, fornisci le impostazioni gestite tramite [impostazioni gestite dal server](/docs/it/server-managed-settings) o il tuo MDM. Vedi [file di impostazioni gestite](/docs/it/settings#settings-files) per le chiavi disponibili e gli altri percorsi di consegna.

122 122 

123Per impostare [variabili di ambiente](/it/env-vars) che si applicano a ogni sessione di Claude Code nel contenitore, aggiungile a `containerEnv` nel tuo `devcontainer.json`. L'esempio seguente disattiva la telemetria e la segnalazione degli errori e impedisce a Claude Code di auto-aggiornarsi dopo l'installazione:123Per impostare [variabili di ambiente](/docs/it/env-vars) che si applicano a ogni sessione di Claude Code nel contenitore, aggiungile a `containerEnv` nel tuo `devcontainer.json`. L'esempio seguente disattiva la telemetria e la segnalazione degli errori e impedisce a Claude Code di auto-aggiornarsi dopo l'installazione:

124 124 

125```json devcontainer.json theme={null}125```json devcontainer.json theme={null}

126"containerEnv": {126"containerEnv": {

131 131 

132La Dev Container Feature installa sempre l'ultima versione di Claude Code. Per fissare una versione specifica di Claude Code per build riproducibili, installala dal tuo Dockerfile con `npm install -g @anthropic-ai/claude-code@X.Y.Z` invece di utilizzare la feature, e imposta `DISABLE_AUTOUPDATER` come mostrato sopra.132La Dev Container Feature installa sempre l'ultima versione di Claude Code. Per fissare una versione specifica di Claude Code per build riproducibili, installala dal tuo Dockerfile con `npm install -g @anthropic-ai/claude-code@X.Y.Z` invece di utilizzare la feature, e imposta `DISABLE_AUTOUPDATER` come mostrato sopra.

133 133 

134Per l'elenco completo dei controlli di politica incluse le regole di autorizzazione, le restrizioni degli strumenti e gli allowlist dei server MCP, vedi [Configura Claude Code per la tua organizzazione](/it/admin-setup).134Per l'elenco completo dei controlli di politica incluse le regole di autorizzazione, le restrizioni degli strumenti e gli allowlist dei server MCP, vedi [Configura Claude Code per la tua organizzazione](/docs/it/admin-setup).

135 135 

136Per rendere disponibili i [server MCP](/it/mcp) all'interno del contenitore, definiscili a [ambito di progetto](/it/mcp#mcp-installation-scopes) in un file `.mcp.json` alla radice del repository in modo che siano archiviati insieme alla configurazione del tuo dev container. Installa tutti i binari su cui i server stdio locali dipendono nel tuo Dockerfile, e aggiungi i domini dei server remoti al tuo allowlist di rete.136Per rendere disponibili i [server MCP](/docs/it/mcp) all'interno del contenitore, definiscili a [ambito di progetto](/docs/it/mcp#mcp-installation-scopes) in un file `.mcp.json` alla radice del repository in modo che siano archiviati insieme alla configurazione del tuo dev container. Installa tutti i binari su cui i server stdio locali dipendono nel tuo Dockerfile, e aggiungi i domini dei server remoti al tuo allowlist di rete.

137 137 

138<h2 id="restrict-network-egress">138<h2 id="restrict-network-egress">

139 Limita l'uscita di rete139 Limita l'uscita di rete

140</h2>140</h2>

141 141 

142Puoi limitare il traffico in uscita del contenitore solo ai domini di cui Claude Code ha bisogno. Vedi [Requisiti di accesso alla rete](/it/network-config#network-access-requirements) per i domini di inferenza e autenticazione, e [Servizi di telemetria](/it/data-usage#telemetry-services) per le connessioni opzionali di telemetria e segnalazione degli errori e come disabilitarle.142Puoi limitare il traffico in uscita del contenitore solo ai domini di cui Claude Code ha bisogno. Vedi [Requisiti di accesso alla rete](/docs/it/network-config#network-access-requirements) per i domini di inferenza e autenticazione, e [Servizi di telemetria](/docs/it/data-usage#telemetry-services) per le connessioni opzionali di telemetria e segnalazione degli errori e come disabilitarle.

143 143 

144Il contenitore di riferimento include uno script [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) che blocca tutto il traffico in uscita tranne i domini di cui Claude Code e i tuoi strumenti di sviluppo hanno bisogno. L'esecuzione di un firewall all'interno di un contenitore richiede autorizzazioni extra, quindi il riferimento aggiunge le capacità `NET_ADMIN` e `NET_RAW` tramite `runArgs`. Lo script del firewall e queste capacità non sono richiesti per Claude Code stesso: puoi lasciarli fuori e affidarti ai tuoi controlli di rete.144Il contenitore di riferimento include uno script [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) che blocca tutto il traffico in uscita tranne i domini di cui Claude Code e i tuoi strumenti di sviluppo hanno bisogno. L'esecuzione di un firewall all'interno di un contenitore richiede autorizzazioni extra, quindi il riferimento aggiunge le capacità `NET_ADMIN` e `NET_RAW` tramite `runArgs`. Lo script del firewall e queste capacità non sono richiesti per Claude Code stesso: puoi lasciarli fuori e affidarti ai tuoi controlli di rete.

145 145 

151 151 

152Saltare i prompt di autorizzazione rimuove la tua opportunità di rivedere le chiamate degli strumenti prima che vengano eseguite. Claude può comunque modificare qualsiasi file nel workspace bind-montato, che appare direttamente sul tuo host, e raggiungere qualsiasi cosa la politica di rete del contenitore consente. Abbina questo flag alle [restrizioni di uscita di rete](#restrict-network-egress) sopra per limitare ciò che una sessione bypassata può raggiungere.152Saltare i prompt di autorizzazione rimuove la tua opportunità di rivedere le chiamate degli strumenti prima che vengano eseguite. Claude può comunque modificare qualsiasi file nel workspace bind-montato, che appare direttamente sul tuo host, e raggiungere qualsiasi cosa la politica di rete del contenitore consente. Abbina questo flag alle [restrizioni di uscita di rete](#restrict-network-egress) sopra per limitare ciò che una sessione bypassata può raggiungere.

153 153 

154Se desideri meno prompt senza disabilitare i controlli di sicurezza, considera invece la [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode), che ha un classificatore che rivede le azioni prima che vengano eseguite. Per impedire agli ingegneri di utilizzare `--dangerously-skip-permissions` del tutto, imposta `permissions.disableBypassPermissionsMode` su `"disable"` nelle [impostazioni gestite](/it/settings#permission-settings).154Se desideri meno prompt senza disabilitare i controlli di sicurezza, considera invece la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), che ha un classificatore che rivede le azioni prima che vengano eseguite. Per impedire agli ingegneri di utilizzare `--dangerously-skip-permissions` del tutto, imposta `permissions.disableBypassPermissionsMode` su `"disable"` nelle [impostazioni gestite](/docs/it/settings#permission-settings).

155 155 

156<h2 id="try-the-reference-container">156<h2 id="try-the-reference-container">

157 Prova il contenitore di riferimento157 Prova il contenitore di riferimento

193 193 

194Una volta che Claude Code è in esecuzione nel tuo dev container, le pagine seguenti coprono il resto di un rollout organizzativo: scegliere un percorso di autenticazione, fornire politica gestita al di fuori del repository, monitorare l'utilizzo e comprendere cosa Claude Code archivia e invia.194Una volta che Claude Code è in esecuzione nel tuo dev container, le pagine seguenti coprono il resto di un rollout organizzativo: scegliere un percorso di autenticazione, fornire politica gestita al di fuori del repository, monitorare l'utilizzo e comprendere cosa Claude Code archivia e invia.

195 195 

196* [Configura Claude Code per la tua organizzazione](/it/admin-setup): scegli un provider di autenticazione, decidi come la politica raggiunge i dispositivi e pianifica il rollout196* [Configura Claude Code per la tua organizzazione](/docs/it/admin-setup): scegli un provider di autenticazione, decidi come la politica raggiunge i dispositivi e pianifica il rollout

197* [Impostazioni gestite dal server](/it/server-managed-settings): fornisci politica gestita dalla console admin di Claude.ai in modo che gli ingegneri non possano aggirarla modificando i file del repository197* [Impostazioni gestite dal server](/docs/it/server-managed-settings): fornisci politica gestita dalla console admin di Claude.ai in modo che gli ingegneri non possano aggirarla modificando i file del repository

198* [Monitora l'utilizzo e l'attività di audit](/it/monitoring-usage): esporta metriche OpenTelemetry e rivedi cosa il tuo team sta eseguendo198* [Monitora l'utilizzo e l'attività di audit](/docs/it/monitoring-usage): esporta metriche OpenTelemetry e rivedi cosa il tuo team sta eseguendo

199* [Requisiti di accesso alla rete](/it/network-config#network-access-requirements): l'elenco completo dei domini per proxy e firewall199* [Requisiti di accesso alla rete](/docs/it/network-config#network-access-requirements): l'elenco completo dei domini per proxy e firewall

200* [Servizi di telemetria e opt-out](/it/data-usage#telemetry-services): cosa Claude Code invia per impostazione predefinita e le variabili di ambiente che lo disabilitano200* [Servizi di telemetria e opt-out](/docs/it/data-usage#telemetry-services): cosa Claude Code invia per impostazione predefinita e le variabili di ambiente che lo disabilitano

201* [Esplora la directory `.claude`](/it/claude-directory): cosa contiene il mount del volume, incluse credenziali, impostazioni e cronologia della sessione201* [Esplora la directory `.claude`](/docs/it/claude-directory): cosa contiene il mount del volume, incluse credenziali, impostazioni e cronologia della sessione

202* [Ambienti sandbox](/it/sandbox-environments): confronta i dev container con la sandbox Bash integrata, i container personalizzati e le VM202* [Ambienti sandbox](/docs/it/sandbox-environments): confronta i dev container con la sandbox Bash integrata, i container personalizzati e le VM

203* [Modello di sicurezza](/it/security): come il sistema di autorizzazione di Claude Code, il sandboxing e le protezioni dall'iniezione di prompt si incastrano insieme203* [Modello di sicurezza](/docs/it/security): come il sistema di autorizzazione di Claude Code, il sandboxing e le protezioni dall'iniezione di prompt si incastrano insieme

204* [Modalità di autorizzazione](/it/permission-modes): l'intera gamma dalla modalità piano alla modalità auto al bypass, e quando utilizzare ciascuna204* [Modalità di autorizzazione](/docs/it/permission-modes): l'intera gamma dalla modalità piano alla modalità auto al bypass, e quando utilizzare ciascuna

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Gateway LLM altri

6 

7> Instrada Claude Code attraverso un gateway LLM che la tua organizzazione già esegue. Copre il collegamento di Claude Code a un gateway, il rollout per la tua organizzazione e cosa Claude Code invia a un gateway.

8 

9Questa sezione copre l'utilizzo di un prodotto gateway che la tua organizzazione già esegue, piuttosto che [gateway di app Claude](/docs/it/claude-apps-gateway). Per informazioni su cosa sia un gateway, come si posiziona tra Claude Code e il tuo provider e come scegliere tra gateway di app Claude e un altro prodotto, vedi la [panoramica del gateway](/docs/it/gateways).

10 

11<Note>

12 * Se sei uno sviluppatore che si connette a un gateway esistente: [collega Claude Code al tuo gateway](/docs/it/llm-gateway-connect)

13 * Se sei un amministratore che esegue il rollout di un gateway per la tua organizzazione: [distribuisci e distribuisci un gateway](/docs/it/llm-gateway-rollout)

14 * Se stai configurando un prodotto gateway: il [riferimento del protocollo gateway](/docs/it/llm-gateway-protocol)

15</Note>

16 

17Qualsiasi gateway che espone un [formato API supportato](/docs/it/llm-gateway-protocol#api-formats) funziona. Anthropic non approva, mantiene o controlla i prodotti gateway di terze parti e non supporta l'instradamento di Claude Code a modelli non-Claude attraverso alcun gateway. Distribuisci il gateway seguendo la sua documentazione, quindi completa il lato Claude Code con i [passaggi di rollout di seguito](#roll-out-a-gateway).

18 

19<h2 id="what-a-gateway-provides">

20 Cosa fornisce un gateway

21</h2>

22 

23Un gateway offre alla tua organizzazione un unico posto per gestire:

24 

25* **Credenziali**: la chiave del provider rimane lato server; gli sviluppatori mantengono invece le credenziali del gateway

26* **Tracciamento dell'utilizzo**: attribuisci l'utilizzo per sviluppatore o team, indipendentemente da quale provider serve la richiesta

27* **Controlli dei costi**: applica budget e limiti di velocità in un unico posto

28* **Registrazione di audit**: registra ogni richiesta di modello per la conformità

29* **Cambio di provider**: cambia il provider nella configurazione del gateway, senza toccare le macchine degli sviluppatori

30 

31Tutti questi, tranne il cambio di provider, si applicano sia che l'upstream sia l'API di Anthropic che un [provider cloud](/docs/it/third-party-integrations). Il cambio di provider senza riconfigurare le macchine degli sviluppatori dipende anche dal gateway che espone un singolo [endpoint in formato Anthropic](/docs/it/llm-gateway-protocol#api-formats) indipendentemente dall'upstream; un gateway che espone il formato proprio di un provider lega la configurazione del client a quel provider.

32 

33Il compromesso è che il gateway diventa un'infrastruttura che la tua organizzazione gestisce. Claude Code aggiunge funzionalità con ogni rilascio, e un gateway che non le inoltra interrompe le funzionalità corrispondenti, quindi il prodotto gateway deve essere mantenuto aggiornato man mano che Claude Code evolve. Il [riferimento del protocollo gateway](/docs/it/llm-gateway-protocol) copre cosa inoltrare.

34 

35<h2 id="roll-out-a-gateway">

36 Esegui il rollout di un gateway

37</h2>

38 

39Quando sei pronto a eseguire il rollout di un gateway LLM alla tua organizzazione, la sequenza è la stessa indipendentemente dal prodotto gateway che scegli:

40 

411. Distribuisci il gateway e dagli la tua credenziale del provider, in modo che possa autenticare le richieste che inoltra.

422. Emetti a ogni sviluppatore una credenziale del gateway, in modo che l'utilizzo sia attribuito allo sviluppatore e l'offboarding revoca una credenziale.

433. Distribuisci la configurazione attraverso un [file di impostazioni gestite](/docs/it/settings#settings-files) e il tuo strumento di segreti, in modo che ogni macchina riceva l'URL di base e una credenziale. Quando entrambi sono distribuiti, gli sviluppatori non configurano nulla. Se non hai la distribuzione delle impostazioni in atto, gli sviluppatori seguono la [pagina di connessione](/docs/it/llm-gateway-connect) per impostare le variabili stessi.

444. Fai in modo che ogni sviluppatore [verifichi la configurazione in Claude Code](/docs/it/llm-gateway-connect#check-for-an-existing-configuration), in modo che i problemi di distribuzione emergano prima che dipendano dal gateway.

45 

46[Esegui il rollout di un gateway LLM per la tua organizzazione](/docs/it/llm-gateway-rollout) esamina ogni passaggio e mostra i file di configurazione da distribuire a ogni passaggio. Il gateway è una parte della configurazione dell'organizzazione; per l'applicazione delle politiche, la visibilità dell'utilizzo e le decisioni sulla gestione dei dati, vedi [Configura Claude Code per la tua organizzazione](/docs/it/admin-setup).

47 

48<h2 id="subscriptions-and-gateways">

49 Abbonamenti e gateway

50</h2>

51 

52Mentre una [variabile di credenziale del gateway](/docs/it/llm-gateway-connect#set-the-credential-variable) o `apiKeyHelper` è attiva, l'abbonamento a claude.ai di uno sviluppatore non viene utilizzato: la credenziale sostituisce l'accesso all'abbonamento per quella sessione, e i limiti di utilizzo dell'abbonamento non si applicano. Quel traffico viene fatturato per token a chiunque possieda la credenziale che il gateway inoltra, come l'account Anthropic Console della tua organizzazione, o il tuo account Amazon Bedrock, Google Cloud's Agent Platform, o Microsoft Foundry quando il gateway instrada lì.

53 

54[`ANTHROPIC_BASE_URL`](/docs/it/llm-gateway-connect#set-the-base-url-and-credential) è la variabile che punta Claude Code al gateway. Impostare solo quella variabile, senza una credenziale del gateway, non sostituisce l'abbonamento. Le richieste vengono comunque instradate attraverso il gateway, ma un accesso a claude.ai salvato rimane la credenziale attiva, quindi i suoi limiti di utilizzo e la fatturazione si applicano. I gateway che passano questo traffico ad Anthropic devono inoltrare la capacità OAuth in `anthropic-beta`; vedi il [riferimento delle intestazioni della richiesta](/docs/it/llm-gateway-protocol#request-headers).

55 

56<h2 id="related-pages">

57 Pagine correlate

58</h2>

59 

60* [Panoramica del gateway](/docs/it/gateways): come funziona un gateway e come scegliere tra gateway di app Claude e un altro prodotto

61* [Gateway di app Claude](/docs/it/claude-apps-gateway): il gateway auto-ospitato di Anthropic con accesso SSO e telemetria OTLP

62* [Collega Claude Code a un gateway LLM](/docs/it/llm-gateway-connect): imposta l'URL di base e la credenziale sulla tua macchina, con configurazione per superficie e una tabella di risoluzione dei problemi

63* [Esegui il rollout di un gateway LLM per la tua organizzazione](/docs/it/llm-gateway-rollout): la checklist dell'amministratore per distribuire un gateway, emettere credenziali sviluppatore e distribuire impostazioni gestite

64* [Riferimento del protocollo gateway](/docs/it/llm-gateway-protocol): cosa Claude Code invia a un gateway, per gli operatori che ne configurano uno, coprendo endpoint, intestazioni da inoltrare e pass-through delle funzionalità

20 20 

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22 

23<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=7434a04e08187edd26ec6c3dd332f624" className="hidden dark:block" alt="Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta." width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta." width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24 

25Per ottenere il massimo dall'abbinamento dei prefissi, Claude Code ordina ogni richiesta in modo che il contenuto che cambia raramente tra i turni venga per primo:25Per ottenere il massimo dall'abbinamento dei prefissi, Claude Code ordina ogni richiesta in modo che il contenuto che cambia raramente tra i turni venga per primo:

26 26 

32 32 

33Una modifica al layer della conversazione lascia il prompt di sistema e il contesto del progetto memorizzati nella cache. Una modifica al prompt di sistema invalida tutto, perché tutto il contenuto successivo ora si trova dietro un prefisso diverso. La terza colonna fornisce trigger comuni piuttosto che un elenco esaustivo, e le sezioni seguenti coprono l'insieme completo, incluso contenuto come lo stile di output che è fisso all'inizio della sessione.33Una modifica al layer della conversazione lascia il prompt di sistema e il contesto del progetto memorizzati nella cache. Una modifica al prompt di sistema invalida tutto, perché tutto il contenuto successivo ora si trova dietro un prefisso diverso. La terza colonna fornisce trigger comuni piuttosto che un elenco esaustivo, e le sezioni seguenti coprono l'insieme completo, incluso contenuto come lo stile di output che è fisso all'inizio della sessione.

34 34 

35La regola di abbinamento dei prefissi spiega la maggior parte dei comportamenti in questa pagina. [Plan mode](/it/permission-modes#analyze-before-you-edit-with-plan-mode) e [skill loading](/it/skills), ad esempio, aggiungono le loro istruzioni come messaggi di conversazione, quindi il prefisso memorizzato nella cache rimane intatto.35La regola di abbinamento dei prefissi spiega la maggior parte dei comportamenti in questa pagina. [Plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode) e [skill loading](/docs/it/skills), ad esempio, aggiungono le loro istruzioni come messaggi di conversazione, quindi il prefisso memorizzato nella cache rimane intatto.

36 36 

37Due impostazioni non fanno parte del testo del prompt, quindi non compaiono nella tabella dei layer, ma entrambe fanno parte della chiave della cache:37Due impostazioni non fanno parte del testo del prompt, quindi non compaiono nella tabella dei layer, ma entrambe fanno parte della chiave della cache:

38 38 

49 49 

50Il caching avviene lato server, nell'infrastruttura che serve il tuo modello. Dove si trova dipende da come ti autentichi:50Il caching avviene lato server, nell'infrastruttura che serve il tuo modello. Dove si trova dipende da come ti autentichi:

51 51 

52* **API key, Claude subscription, o [Claude Platform on AWS](/it/claude-platform-on-aws)**: la cache vive nell'infrastruttura di Anthropic, accessibile tramite [Claude API](https://platform.claude.com/docs)52* **API key, Claude subscription, o [Claude Platform on AWS](/docs/it/claude-platform-on-aws)**: la cache vive nell'infrastruttura di Anthropic, accessibile tramite [Claude API](https://platform.claude.com/docs)

53* **Amazon Bedrock o Google Cloud's Agent Platform**: la cache vive nell'infrastruttura di servizio del tuo provider cloud53* **Amazon Bedrock o Google Cloud's Agent Platform**: la cache vive nell'infrastruttura di servizio del tuo provider cloud

54* **Microsoft Foundry**: le richieste vengono instradate all'infrastruttura di Anthropic54* **Microsoft Foundry**: le richieste vengono instradate all'infrastruttura di Anthropic

55* **Custom `ANTHROPIC_BASE_URL` o [LLM gateway](/it/llm-gateway)**: la cache vive dove vengono inoltrate le tue richieste, e se il caching funziona dipende dal gateway55* **Custom `ANTHROPIC_BASE_URL` o [LLM gateway](/docs/it/llm-gateway)**: la cache vive dove vengono inoltrate le tue richieste, e se il caching funziona dipende dal gateway

56 56 

57Per ciò che ogni provider memorizza ed elabora, vedi [data usage](/it/data-usage). Ovunque viva la cache, le voci scadono dopo un periodo di inattività, e [Cache lifetime](#cache-lifetime) di seguito copre il TTL e come estenderlo.57Per ciò che ogni provider memorizza ed elabora, vedi [data usage](/docs/it/data-usage). Ovunque viva la cache, le voci scadono dopo un periodo di inattività, e [Cache lifetime](#cache-lifetime) di seguito copre il TTL e come estenderlo.

58 58 

59<h2 id="actions-that-invalidate-the-cache">59<h2 id="actions-that-invalidate-the-cache">

60 Azioni che invalidano la cache60 Azioni che invalidano la cache

75 Switching models75 Switching models

76</h3>76</h3>

77 77 

78Ogni modello ha la sua cache. Cambiare con [`/model`](/it/model-config#setting-your-model) significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit, anche se il contenuto è identico.78Ogni modello ha la sua cache. Cambiare con [`/model`](/docs/it/model-config#setting-your-model) significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit, anche se il contenuto è identico.

79 79 

80L'impostazione [`opusplan` model](/it/model-config#opusplan-model-setting) si risolve in Opus durante la modalità piano e Sonnet durante l'esecuzione, quindi ogni toggle della modalità piano è un cambio di modello e avvia una cache fresca.80L'impostazione [`opusplan` model](/docs/it/model-config#opusplan-model-setting) si risolve in Opus durante la modalità piano e Sonnet durante l'esecuzione, quindi ogni toggle della modalità piano è un cambio di modello e avvia una cache fresca.

81 81 

82Il [fallback automatico del modello](/it/model-config#automatic-model-fallback) su Fable 5 è anche un cambio di modello. Quando un classificatore di sicurezza contrassegna una richiesta, Claude Code la riesegue sul modello Opus predefinito e la sessione continua lì.82Il [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) su Fable 5 è anche un cambio di modello. Quando un classificatore di sicurezza contrassegna una richiesta, Claude Code la riesegue sul modello Opus predefinito e la sessione continua lì.

83 83 

84<h3 id="changing-effort-level">84<h3 id="changing-effort-level">

85 Changing effort level85 Changing effort level

86</h3>86</h3>

87 87 

88La cache è codificata dal [livello di effort](/it/model-config#adjust-effort-level) così come dal modello, quindi cambiare con `/effort` significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Una volta che una conversazione è iniziata, Claude Code mostra una finestra di dialogo di conferma prima di applicare un cambio di effort che invaliderebbe la cache. Un cambio che si risolve nello stesso livello già in vigore, come impostare esplicitamente il valore predefinito del modello, salta la finestra di dialogo e mantiene la cache.88La cache è codificata dal [livello di effort](/docs/it/model-config#adjust-effort-level) così come dal modello, quindi cambiare con `/effort` significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Una volta che una conversazione è iniziata, Claude Code mostra una finestra di dialogo di conferma prima di applicare un cambio di effort che invaliderebbe la cache. Un cambio che si risolve nello stesso livello già in vigore, come impostare esplicitamente il valore predefinito del modello, salta la finestra di dialogo e mantiene la cache.

89 89 

90<h3 id="turning-on-fast-mode">90<h3 id="turning-on-fast-mode">

91 Turning on fast mode91 Turning on fast mode

92</h3>92</h3>

93 93 

94L'abilitazione della [fast mode](/it/fast-mode) aggiunge un'intestazione di richiesta che fa parte della chiave della cache, quindi la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Quei token di input non memorizzati nella cache vengono fatturati alle [tariffe della fast mode](/it/fast-mode#understand-the-cost-tradeoff), motivo per cui attivarla all'inizio di una sessione costa meno che attivarla in profondità in una sessione lunga. L'abilitazione della fast mode da un modello non-Opus [cambia anche il tuo modello](#switching-models), il che avvia una cache fresca di per sé.94L'abilitazione della [fast mode](/docs/it/fast-mode) aggiunge un'intestazione di richiesta che fa parte della chiave della cache, quindi la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Quei token di input non memorizzati nella cache vengono fatturati alle [tariffe della fast mode](/docs/it/fast-mode#understand-the-cost-tradeoff), motivo per cui attivarla all'inizio di una sessione costa meno che attivarla in profondità in una sessione lunga. L'abilitazione della fast mode da un modello non-Opus [cambia anche il tuo modello](#switching-models), il che avvia una cache fresca di per sé.

95 95 

96Il costo si applica una volta per conversazione. Dopo il primo turno della fast mode, Claude Code continua a inviare l'intestazione e varia solo l'impostazione di velocità della richiesta, che non fa parte della chiave della cache. Disattivare la fast mode, il [fallback automatico alla velocità standard](/it/fast-mode#handle-rate-limits) dopo un limite di velocità, e riattivarla in seguito mantengono tutti la cache. `/clear` e `/compact` ripristinano questo, poiché ricostruiscono la cache in quei punti comunque.96Il costo si applica una volta per conversazione. Dopo il primo turno della fast mode, Claude Code continua a inviare l'intestazione e varia solo l'impostazione di velocità della richiesta, che non fa parte della chiave della cache. Disattivare la fast mode, il [fallback automatico alla velocità standard](/docs/it/fast-mode#handle-rate-limits) dopo un limite di velocità, e riattivarla in seguito mantengono tutti la cache. `/clear` e `/compact` ripristinano questo, poiché ricostruiscono la cache in quei punti comunque.

97 97 

98<h3 id="connecting-or-disconnecting-an-mcp-server">98<h3 id="connecting-or-disconnecting-an-mcp-server">

99 Connecting or disconnecting an MCP server99 Connecting or disconnecting an MCP server

100</h3>100</h3>

101 101 

102Le definizioni degli strumenti si trovano nel layer del prompt di sistema, quindi la cache si invalida quando l'insieme delle definizioni degli strumenti nella richiesta cambia tra i turni. Attivare lo [strumento advisor](/it/advisor) è un'eccezione: la sua definizione si trova dopo il punto di interruzione della cache, quindi abilitare o disabilitare `/advisor` mantiene il prefisso memorizzato nella cache intatto. Se un cambio di [MCP server](/it/mcp) fa questo dipende dal fatto che i suoi strumenti siano rimandati dalla [tool search](/it/mcp#scale-with-mcp-tool-search) o caricati nel prefisso:102Le definizioni degli strumenti si trovano nel layer del prompt di sistema, quindi la cache si invalida quando l'insieme delle definizioni degli strumenti nella richiesta cambia tra i turni. Attivare lo [strumento advisor](/docs/it/advisor) è un'eccezione: la sua definizione si trova dopo il punto di interruzione della cache, quindi abilitare o disabilitare `/advisor` mantiene il prefisso memorizzato nella cache intatto. Se un cambio di [MCP server](/docs/it/mcp) fa questo dipende dal fatto che i suoi strumenti siano rimandati dalla [tool search](/docs/it/mcp#scale-with-mcp-tool-search) o caricati nel prefisso:

103 103 

104* **Strumenti rimandati**, il valore predefinito sui modelli supportati: un server che si connette, disconnette, o cambia il suo elenco di strumenti aggiunge solo nuovo contenuto e non disturba nulla che sia già memorizzato nella cache.104* **Strumenti rimandati**, il valore predefinito sui modelli supportati: un server che si connette, disconnette, o cambia il suo elenco di strumenti aggiunge solo nuovo contenuto e non disturba nulla che sia già memorizzato nella cache.

105* **Strumenti caricati nel prefisso**: qualsiasi cambio ad essi invalida la cache. Questo accade quando [tool search non è disponibile o disabilitato](/it/mcp#configure-tool-search), come su Google Cloud's Agent Platform o con un gateway `ANTHROPIC_BASE_URL` personalizzato. Accade anche per un server o uno strumento contrassegnato [`alwaysLoad`](/it/mcp#exempt-a-server-from-deferral), e per le definizioni mantenute in primo piano dal [caricamento basato su soglia](/it/mcp#configure-tool-search).105* **Strumenti caricati nel prefisso**: qualsiasi cambio ad essi invalida la cache. Questo accade quando [tool search non è disponibile o disabilitato](/docs/it/mcp#configure-tool-search), come su Google Cloud's Agent Platform o con un gateway `ANTHROPIC_BASE_URL` personalizzato. Accade anche per un server o uno strumento contrassegnato [`alwaysLoad`](/docs/it/mcp#exempt-a-server-from-deferral), e per le definizioni mantenute in primo piano dal [caricamento basato su soglia](/docs/it/mcp#configure-tool-search).

106 106 

107Quando gli strumenti si caricano nel prefisso, la causa più comune di un'invalidazione è un server che si connette o disconnette a metà sessione, il che può accadere senza alcuna azione da parte tua: il processo di un server stdio esce, una sessione HTTP scade, o un server [si riconnette automaticamente dopo un errore transitorio](/it/mcp#automatic-reconnection). Un server connesso può anche inviare un [dynamic tool update](/it/mcp#dynamic-tool-updates) che cambia il suo elenco di strumenti.107Quando gli strumenti si caricano nel prefisso, la causa più comune di un'invalidazione è un server che si connette o disconnette a metà sessione, il che può accadere senza alcuna azione da parte tua: il processo di un server stdio esce, una sessione HTTP scade, o un server [si riconnette automaticamente dopo un errore transitorio](/docs/it/mcp#automatic-reconnection). Un server connesso può anche inviare un [dynamic tool update](/docs/it/mcp#dynamic-tool-updates) che cambia il suo elenco di strumenti.

108 108 

109Modificare la tua configurazione MCP non cambia la cache di per sé. La nuova configurazione ha effetto solo dopo un riavvio, che è quando il server si connette o disconnette.109Modificare la tua configurazione MCP non cambia la cache di per sé. La nuova configurazione ha effetto solo dopo un riavvio, che è quando il server si connette o disconnette.

110 110 

112 Enabling or disabling a plugin112 Enabling or disabling a plugin

113</h3>113</h3>

114 114 

115I [plugin](/it/plugins) raggruppano diversi tipi di componenti, e il costo di un cambio dipende da quali componenti il plugin fornisce. Skills, comandi, agenti, hooks, server LSP, monitor e temi non invalidano mai la cache: qualsiasi cosa aggiungano alla richiesta viene aggiunta dopo la conversazione esistente, quindi la richiesta successiva paga per il nuovo contenuto ma legge comunque tutto ciò che lo precede dalla cache.115I [plugin](/docs/it/plugins) raggruppano diversi tipi di componenti, e il costo di un cambio dipende da quali componenti il plugin fornisce. Skills, comandi, agenti, hooks, server LSP, monitor e temi non invalidano mai la cache: qualsiasi cosa aggiungano alla richiesta viene aggiunta dopo la conversazione esistente, quindi la richiesta successiva paga per il nuovo contenuto ma legge comunque tutto ciò che lo precede dalla cache.

116 116 

117L'eccezione è un plugin che fornisce [MCP server](/it/plugins-reference#mcp-servers). Abilitare o disabilitare uno segue le stesse regole di [connessione o disconnessione di un MCP server](#connecting-or-disconnecting-an-mcp-server): la cache sopravvive quando gli strumenti del server sono rimandati, e la richiesta successiva rilegge l'intera conversazione quando si caricano nel prefisso.117L'eccezione è un plugin che fornisce [MCP server](/docs/it/plugins-reference#mcp-servers). Abilitare o disabilitare uno segue le stesse regole di [connessione o disconnessione di un MCP server](#connecting-or-disconnecting-an-mcp-server): la cache sopravvive quando gli strumenti del server sono rimandati, e la richiesta successiva rilegge l'intera conversazione quando si caricano nel prefisso.

118 118 

119I cambiamenti dei plugin si applicano quando esegui [`/reload-plugins`](/it/discover-plugins#apply-plugin-changes-without-restarting) o avvii una nuova sessione. Il costo, sia annunci aggiunti che una rilettura completa, si mostra al primo turno dopo il ricaricamento, non quando esegui `/plugin install`, `/plugin enable`, o `/plugin disable`. {/* min-version: 2.1.163 */}A partire da v2.1.163, quando un ricaricamento attiverebbe la rilettura completa, `/reload-plugins` mostra un avviso e non applica il ricaricamento. Passa `--force` per applicare comunque.119I cambiamenti dei plugin si applicano quando esegui [`/reload-plugins`](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) o avvii una nuova sessione. Il costo, sia annunci aggiunti che una rilettura completa, si mostra al primo turno dopo il ricaricamento, non quando esegui `/plugin install`, `/plugin enable`, o `/plugin disable`. {/* min-version: 2.1.163 */}A partire da v2.1.163, quando un ricaricamento attiverebbe la rilettura completa, `/reload-plugins` mostra un avviso e non applica il ricaricamento. Passa `--force` per applicare comunque.

120 120 

121Disabilitare un plugin che hai abilitato in precedenza nella sessione ripristina la forma di richiesta precedente. Se quel prefisso è ancora entro la sua [durata della cache](#cache-lifetime), la richiesta successiva legge la voce di cache più vecchia invece di ricostruirla.121Disabilitare un plugin che hai abilitato in precedenza nella sessione ripristina la forma di richiesta precedente. Se quel prefisso è ancora entro la sua [durata della cache](#cache-lifetime), la richiesta successiva legge la voce di cache più vecchia invece di ricostruirla.

122 122 

124 Denying an entire tool124 Denying an entire tool

125</h3>125</h3>

126 126 

127Aggiungere un nome di strumento semplice come `Bash` o `WebFetch` come [deny rule](/it/permissions#manage-permissions) rimuove completamente quello strumento dal contesto di Claude. Le definizioni degli strumenti incorporati si caricano nel layer del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache. La modifica ha effetto al turno successivo sia che la aggiungi tramite `/permissions` o [modificando direttamente un file di impostazioni](/it/settings#when-edits-take-effect).127Aggiungere un nome di strumento semplice come `Bash` o `WebFetch` come [deny rule](/docs/it/permissions#manage-permissions) rimuove completamente quello strumento dal contesto di Claude. Le definizioni degli strumenti incorporati si caricano nel layer del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache. La modifica ha effetto al turno successivo sia che la aggiungi tramite `/permissions` o [modificando direttamente un file di impostazioni](/docs/it/settings#when-edits-take-effect).

128 128 

129Solo una deny rule che corrisponde nella posizione del nome dello strumento ha questo effetto: un nome di strumento semplice, la forma equivalente `Bash(*)`, o un [tool-name glob](/it/permissions#tool-name-wildcards) come `"*"`. Un glob che corrisponde solo agli strumenti MCP, come `"mcp__*"`, rimuove quegli strumenti allo stesso modo ma lascia la cache intatta quando gli strumenti corrispondenti sono [rimandati](#connecting-or-disconnecting-an-mcp-server), il valore predefinito, poiché le definizioni rimandate non erano mai nel prefisso memorizzato nella cache. Le deny rule con ambito come `Bash(rm *)`, e tutte le regole di consentimento e richiesta, non cambiano quali strumenti Claude vede. Claude Code le controlla quando Claude tenta una chiamata, lasciando il prefisso intatto.129Solo una deny rule che corrisponde nella posizione del nome dello strumento ha questo effetto: un nome di strumento semplice, la forma equivalente `Bash(*)`, o un [tool-name glob](/docs/it/permissions#tool-name-wildcards) come `"*"`. Un glob che corrisponde solo agli strumenti MCP, come `"mcp__*"`, rimuove quegli strumenti allo stesso modo ma lascia la cache intatta quando gli strumenti corrispondenti sono [rimandati](#connecting-or-disconnecting-an-mcp-server), il valore predefinito, poiché le definizioni rimandate non erano mai nel prefisso memorizzato nella cache. Le deny rule con ambito come `Bash(rm *)`, e tutte le regole di consentimento e richiesta, non cambiano quali strumenti Claude vede. Claude Code le controlla quando Claude tenta una chiamata, lasciando il prefisso intatto.

130 130 

131<h3 id="compacting-the-conversation">131<h3 id="compacting-the-conversation">

132 Compacting the conversation132 Compacting the conversation

133</h3>133</h3>

134 134 

135[Compaction](/it/context-window#what-survives-compaction) sostituisce la tua cronologia dei messaggi con un riepilogo. Per progettazione, questo invalida il layer della conversazione, poiché la richiesta successiva ha una cronologia nuova e più breve che non condivide un prefisso con quella vecchia. Claude Code riutilizza il layer del prompt di sistema e ricarica il contesto del progetto dal disco, che ha cache hit solo se CLAUDE.md e la memoria sono invariati dall'inizio della sessione.135[Compaction](/docs/it/context-window#what-survives-compaction) sostituisce la tua cronologia dei messaggi con un riepilogo. Per progettazione, questo invalida il layer della conversazione, poiché la richiesta successiva ha una cronologia nuova e più breve che non condivide un prefisso con quella vecchia. Claude Code riutilizza il layer del prompt di sistema e ricarica il contesto del progetto dal disco, che ha cache hit solo se CLAUDE.md e la memoria sono invariati dall'inizio della sessione.

136 136 

137Per produrre il riepilogo, Claude Code invia una richiesta una tantum con lo stesso prompt di sistema, strumenti e cronologia della tua conversazione, più un'istruzione di riepilogo aggiunta come messaggio utente finale. Poiché condivide il tuo prefisso, quella richiesta legge la cache esistente piuttosto che rielaborare la cronologia completa. La maggior parte del tempo di compaction va alla generazione del riepilogo, non a una cache miss. Il turno che segue ricostruisce la cache della conversazione solo per il riepilogo molto più breve, quindi il turno post-compaction non è la parte lenta.137Per produrre il riepilogo, Claude Code invia una richiesta una tantum con lo stesso prompt di sistema, strumenti e cronologia della tua conversazione, più un'istruzione di riepilogo aggiunta come messaggio utente finale. Poiché condivide il tuo prefisso, quella richiesta legge la cache esistente piuttosto che rielaborare la cronologia completa. La maggior parte del tempo di compaction va alla generazione del riepilogo, non a una cache miss. Il turno che segue ricostruisce la cache della conversazione solo per il riepilogo molto più breve, quindi il turno post-compaction non è la parte lenta.

138 138 

144 Upgrading Claude Code144 Upgrading Claude Code

145</h3>145</h3>

146 146 

147Una nuova versione di Claude Code in genere aggiorna il prompt di sistema o le definizioni degli strumenti, quindi la prima richiesta dopo un aggiornamento ricostruisce la cache dall'inizio. [Auto-update](/it/setup#auto-updates) scarica le nuove versioni in background ma le applica al prossimo avvio, mai a metà sessione, quindi lo vedi come un primo turno senza cache dopo il riavvio piuttosto che una sorpresa durante una sessione. Imposta `DISABLE_AUTOUPDATER=1` per controllare quando gli aggiornamenti si applicano.147Una nuova versione di Claude Code in genere aggiorna il prompt di sistema o le definizioni degli strumenti, quindi la prima richiesta dopo un aggiornamento ricostruisce la cache dall'inizio. [Auto-update](/docs/it/setup#auto-updates) scarica le nuove versioni in background ma le applica al prossimo avvio, mai a metà sessione, quindi lo vedi come un primo turno senza cache dopo il riavvio piuttosto che una sorpresa durante una sessione. Imposta `DISABLE_AUTOUPDATER=1` per controllare quando gli aggiornamenti si applicano.

148 148 

149<Note>149<Note>

150 [Resuming a session](/it/sessions#resume-a-session) dopo un aggiornamento rielabora l'intera cronologia della conversazione senza cache hit, poiché la cronologia ora si trova dietro un prompt di sistema diverso. Il costo scala con la lunghezza della conversazione ripresa, quindi il primo turno di ritorno in una sessione lunga può essere la richiesta più costosa che invii.150 [Resuming a session](/docs/it/sessions#resume-a-session) dopo un aggiornamento rielabora l'intera cronologia della conversazione senza cache hit, poiché la cronologia ora si trova dietro un prompt di sistema diverso. Il costo scala con la lunghezza della conversazione ripresa, quindi il primo turno di ritorno in una sessione lunga può essere la richiesta più costosa che invii.

151</Note>151</Note>

152 152 

153<h2 id="actions-that-keep-the-cache">153<h2 id="actions-that-keep-the-cache">

177 177 

178I tuoi file CLAUDE.md a livello di radice del progetto e a livello utente vengono letti una sola volta all'inizio della sessione e mantenuti in memoria. Modificarli durante la sessione non invalida la cache, ma la modifica non si applica nemmeno. Claude continua a lavorare con la versione che è stata caricata all'inizio della sessione. Il nuovo contenuto viene caricato al prossimo `/clear`, `/compact` o riavvio.178I tuoi file CLAUDE.md a livello di radice del progetto e a livello utente vengono letti una sola volta all'inizio della sessione e mantenuti in memoria. Modificarli durante la sessione non invalida la cache, ma la modifica non si applica nemmeno. Claude continua a lavorare con la versione che è stata caricata all'inizio della sessione. Il nuovo contenuto viene caricato al prossimo `/clear`, `/compact` o riavvio.

179 179 

180[I file CLAUDE.md annidati nelle sottodirectory](/it/memory) e [le regole con frontmatter `paths:`](/it/memory#path-specific-rules) vengono caricati in seguito, quando Claude legge per la prima volta un file corrispondente. Modificarne uno prima che venga caricato ha effetto. Dopo che viene caricato, il contenuto fa parte della cronologia della conversazione, quindi una modifica durante la sessione non lo cambia retroattivamente.180[I file CLAUDE.md annidati nelle sottodirectory](/docs/it/memory) e [le regole con frontmatter `paths:`](/docs/it/memory#path-specific-rules) vengono caricati in seguito, quando Claude legge per la prima volta un file corrispondente. Modificarne uno prima che venga caricato ha effetto. Dopo che viene caricato, il contenuto fa parte della cronologia della conversazione, quindi una modifica durante la sessione non lo cambia retroattivamente.

181 181 

182<h3 id="changing-output-style">182<h3 id="changing-output-style">

183 Cambio dello stile di output183 Cambio dello stile di output

184</h3>184</h3>

185 185 

186[Lo stile di output](/it/output-styles) fa parte del prompt di sistema, che Claude Code legge una sola volta all'inizio della sessione. Cambiarlo tramite `/config` o l'impostazione `outputStyle` durante la sessione non invalida la cache, ma il cambiamento non si applica nemmeno. Claude continua a usare lo stile che è stato caricato all'inizio della sessione. Il nuovo stile viene caricato al prossimo `/clear` o riavvio.186[Lo stile di output](/docs/it/output-styles) fa parte del prompt di sistema, che Claude Code legge una sola volta all'inizio della sessione. Cambiarlo tramite `/config` o l'impostazione `outputStyle` durante la sessione non invalida la cache, ma il cambiamento non si applica nemmeno. Claude continua a usare lo stile che è stato caricato all'inizio della sessione. Il nuovo stile viene caricato al prossimo `/clear` o riavvio.

187 187 

188<h3 id="changing-permission-mode">188<h3 id="changing-permission-mode">

189 Cambio della modalità di autorizzazione189 Cambio della modalità di autorizzazione

190</h3>190</h3>

191 191 

192Passare tra [modalità di autorizzazione](/it/permission-modes), come da predefinito ad accettare modifiche, non cambia il prompt di sistema o le definizioni degli strumenti, quindi i cambi di modalità sono sicuri per la cache. L'eccezione è la modalità piano con l'impostazione [`opusplan`](/it/model-config#opusplan-model-setting) del modello, che cambia il modello tra Opus e Sonnet quando entri o esci dalla modalità piano. Questo rende il toggle della modalità un [cambio di modello](#switching-models).192Passare tra [modalità di autorizzazione](/docs/it/permission-modes), come da predefinito ad accettare modifiche, non cambia il prompt di sistema o le definizioni degli strumenti, quindi i cambi di modalità sono sicuri per la cache. L'eccezione è la modalità piano con l'impostazione [`opusplan`](/docs/it/model-config#opusplan-model-setting) del modello, che cambia il modello tra Opus e Sonnet quando entri o esci dalla modalità piano. Questo rende il toggle della modalità un [cambio di modello](#switching-models).

193 193 

194<h3 id="invoking-skills-and-commands">194<h3 id="invoking-skills-and-commands">

195 Invocazione di skills e comandi195 Invocazione di skills e comandi

196</h3>196</h3>

197 197 

198[Skills](/it/skills) e [comandi](/it/commands) iniettano le loro istruzioni come messaggi utente nel punto di invocazione. Nulla prima nella conversazione cambia.198[Skills](/docs/it/skills) e [comandi](/docs/it/commands) iniettano le loro istruzioni come messaggi utente nel punto di invocazione. Nulla prima nella conversazione cambia.

199 199 

200<h3 id="running-/recap">200<h3 id="running-/recap">

201 Esecuzione di `/recap`201 Esecuzione di `/recap`

202</h3>202</h3>

203 203 

204[`/recap`](/it/interactive-mode#session-recap) genera un riepilogo per la visualizzazione nel tuo terminale. A differenza di `/compact`, aggiunge il riepilogo come output del comando piuttosto che sostituire la tua cronologia dei messaggi, quindi il prefisso memorizzato nella cache rimane intatto.204[`/recap`](/docs/it/interactive-mode#session-recap) genera un riepilogo per la visualizzazione nel tuo terminale. A differenza di `/compact`, aggiunge il riepilogo come output del comando piuttosto che sostituire la tua cronologia dei messaggi, quindi il prefisso memorizzato nella cache rimane intatto.

205 205 

206<h3 id="rewinding-the-conversation">206<h3 id="rewinding-the-conversation">

207 Riavvolgimento della conversazione207 Riavvolgimento della conversazione

208</h3>208</h3>

209 209 

210[`/rewind`](/it/checkpointing) tronca la tua conversazione a un turno precedente. La cronologia rimanente è lo stesso contenuto da cui la cache è stata costruita in quel momento, e i layer del prompt di sistema e del contesto del progetto sono invariati, quindi la richiesta successiva colpisce la voce della cache precedente. Ogni turno da allora ha letto attraverso quel prefisso, che ha mantenuto la voce calda anche se il turno originale era più tempo fa del TTL.210[`/rewind`](/docs/it/checkpointing) tronca la tua conversazione a un turno precedente. La cronologia rimanente è lo stesso contenuto da cui la cache è stata costruita in quel momento, e i layer del prompt di sistema e del contesto del progetto sono invariati, quindi la richiesta successiva colpisce la voce della cache precedente. Ogni turno da allora ha letto attraverso quel prefisso, che ha mantenuto la voce calda anche se il turno originale era più tempo fa del TTL.

211 211 

212Il ripristino dei checkpoint dei file insieme alla conversazione non ha alcun effetto separato sulla cache. I contenuti dei file entrano nel contesto solo quando Claude li legge, come [modifica dei file nel tuo repository](#editing-files-in-your-repository).212Il ripristino dei checkpoint dei file insieme alla conversazione non ha alcun effetto separato sulla cache. I contenuti dei file entrano nel contesto solo quando Claude li legge, come [modifica dei file nel tuo repository](#editing-files-in-your-repository).

213 213 

239 Override the TTL239 Override the TTL

240</h3>240</h3>

241 241 

242Imposta `FORCE_PROMPT_CACHING_5M=1` per forzare il TTL di cinque minuti indipendentemente dall'autenticazione. Questo è utile quando stai eseguendo il debug del comportamento della cache, confrontando i due TTL, o sovrascrivendo un `ENABLE_PROMPT_CACHING_1H` impostato in [managed settings](/it/settings#settings-files).242Imposta `FORCE_PROMPT_CACHING_5M=1` per forzare il TTL di cinque minuti indipendentemente dall'autenticazione. Questo è utile quando stai eseguendo il debug del comportamento della cache, confrontando i due TTL, o sovrascrivendo un `ENABLE_PROMPT_CACHING_1H` impostato in [managed settings](/docs/it/settings#settings-files).

243 243 

244<h2 id="cache-scope">244<h2 id="cache-scope">

245 Cache scope245 Cache scope

249 249 

250Le sessioni che esegui in parallelo nella stessa directory costruiscono prefissi corrispondenti e leggono la cache l'una dell'altra. Le sessioni sequenziali condividono il prefisso solo quando lo snapshot dello stato git all'avvio corrisponde, poiché il prompt di sistema cattura anche il ramo e i commit recenti.250Le sessioni che esegui in parallelo nella stessa directory costruiscono prefissi corrispondenti e leggono la cache l'una dell'altra. Le sessioni sequenziali condividono il prefisso solo quando lo snapshot dello stato git all'avvio corrisponde, poiché il prompt di sistema cattura anche il ramo e i commit recenti.

251 251 

252La cache API sottostante è più ampia. Le cache sono isolate tra le organizzazioni e, su alcuni provider, [tra i workspace all'interno di un'organizzazione](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#cache-storage-and-sharing). All'interno di questi confini, qualsiasi due richieste con lo stesso modello e prefisso leggono la stessa cache. Per i chiamanti dell'Agent SDK che eseguono flotte di processi automatizzati, vedi [improve prompt caching across users and machines](/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) per sopprimere le sezioni per macchina del prompt di sistema e condividere la cache tra le macchine.252La cache API sottostante è più ampia. Le cache sono isolate tra le organizzazioni e, su alcuni provider, [tra i workspace all'interno di un'organizzazione](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#cache-storage-and-sharing). All'interno di questi confini, qualsiasi due richieste con lo stesso modello e prefisso leggono la stessa cache. Per i chiamanti dell'Agent SDK che eseguono flotte di processi automatizzati, vedi [improve prompt caching across users and machines](/docs/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) per sopprimere le sezioni per macchina del prompt di sistema e condividere la cache tra le macchine.

253 253 

254<h2 id="check-cache-performance">254<h2 id="check-cache-performance">

255 Verificare le prestazioni della cache255 Verificare le prestazioni della cache

256</h2>256</h2>

257 257 

258Le prestazioni della cache si mostrano come due conteggi di token che l'API segnala su ogni risposta. Il modo più diretto per guardarli dal vivo è uno [statusline script](/it/statusline) che legge l'oggetto `current_usage`:258Le prestazioni della cache si mostrano come due conteggi di token che l'API segnala su ogni risposta. Il modo più diretto per guardarli dal vivo è uno [statusline script](/docs/it/statusline) che legge l'oggetto `current_usage`:

259 259 

260| Field | Meaning |260| Field | Meaning |

261| ----------------------------- | ---------------------------------------------------------------------------------------------------- |261| ----------------------------- | ---------------------------------------------------------------------------------------------------- |

264 264 

265Un alto rapporto lettura-creazione significa che il caching funziona bene. Se la creazione rimane alta turno dopo turno, qualcosa sta cambiando nel tuo prefisso. La sezione [actions that invalidate the cache](#actions-that-invalidate-the-cache) elenca le cause usuali.265Un alto rapporto lettura-creazione significa che il caching funziona bene. Se la creazione rimane alta turno dopo turno, qualcosa sta cambiando nel tuo prefisso. La sezione [actions that invalidate the cache](#actions-that-invalidate-the-cache) elenca le cause usuali.

266 266 

267Per la visibilità in un'organizzazione, l'esportatore OpenTelemetry segnala i token di lettura e creazione della cache per utente e sessione. Vedi [Monitor usage](/it/monitoring-usage) per il riferimento degli attributi di metrica e evento.267Per la visibilità in un'organizzazione, l'esportatore OpenTelemetry segnala i token di lettura e creazione della cache per utente e sessione. Vedi [Monitor usage](/docs/it/monitoring-usage) per il riferimento degli attributi di metrica e evento.

268 268 

269<h2 id="subagents-and-the-cache">269<h2 id="subagents-and-the-cache">

270 Subagents and the cache270 Subagents and the cache

271</h2>271</h2>

272 272 

273Un [subagent](/it/sub-agents) avvia la sua propria conversazione con il suo prompt di sistema e set di strumenti, separato da quello del genitore. Costruisce la sua propria cache, iniziando senza cache hit sulla sua prima chiamata e riscaldandosi attraverso i suoi turni. I subagent utilizzano il TTL di cinque minuti anche su una subscription, poiché il TTL di un'ora automatico si applica alla conversazione principale.273Un [subagent](/docs/it/sub-agents) avvia la sua propria conversazione con il suo prompt di sistema e set di strumenti, separato da quello del genitore. Costruisce la sua propria cache, iniziando senza cache hit sulla sua prima chiamata e riscaldandosi attraverso i suoi turni. I subagent utilizzano il TTL di cinque minuti anche su una subscription, poiché il TTL di un'ora automatico si applica alla conversazione principale.

274 274 

275La cache del genitore non è interessata. Dal lato del genitore, la chiamata e il risultato del subagent si aggiungono alla conversazione, lasciando il prefisso del genitore intatto.275La cache del genitore non è interessata. Dal lato del genitore, la chiamata e il risultato del subagent si aggiungono alla conversazione, lasciando il prefisso del genitore intatto.

276 276 

277Un [fork](/it/sub-agents#fork-the-current-conversation), al contrario, eredita il prompt di sistema, gli strumenti e la cronologia della conversazione del genitore esattamente, quindi la sua prima richiesta legge la cache del genitore. La chiamata di riepilogo della compaction descritta in [Compacting the conversation](#compacting-the-conversation) utilizza lo stesso approccio di condivisione dei prefissi.277Un [fork](/docs/it/sub-agents#fork-the-current-conversation), al contrario, eredita il prompt di sistema, gli strumenti e la cronologia della conversazione del genitore esattamente, quindi la sua prima richiesta legge la cache del genitore. La chiamata di riepilogo della compaction descritta in [Compacting the conversation](#compacting-the-conversation) utilizza lo stesso approccio di condivisione dei prefissi.

278 278 

279<h2 id="disable-prompt-caching">279<h2 id="disable-prompt-caching">

280 Disabilita prompt caching280 Disabilita prompt caching

290| `DISABLE_PROMPT_CACHING_OPUS` | Disabilita per Opus solo |290| `DISABLE_PROMPT_CACHING_OPUS` | Disabilita per Opus solo |

291| `DISABLE_PROMPT_CACHING_FABLE` | Disabilita per Fable solo |291| `DISABLE_PROMPT_CACHING_FABLE` | Disabilita per Fable solo |

292 292 

293Per impostare la politica di caching in un'organizzazione, metti una di queste o le [TTL variables](#cache-lifetime) nel blocco `env` di [managed settings](/it/settings#settings-files). Per l'uso normale, lascia il caching abilitato.293Per impostare la politica di caching in un'organizzazione, metti una di queste o le [TTL variables](#cache-lifetime) nel blocco `env` di [managed settings](/docs/it/settings#settings-files). Per l'uso normale, lascia il caching abilitato.

294 294 

295<h2 id="related-resources">295<h2 id="related-resources">

296 Risorse correlate296 Risorse correlate

297</h2>297</h2>

298 298 

299* [Lessons from building Claude Code: Prompt caching is everything](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): la logica di progettazione per la modalità piano, il caricamento differito degli strumenti e la compaction299* [Lessons from building Claude Code: Prompt caching is everything](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): la logica di progettazione per la modalità piano, il caricamento differito degli strumenti e la compaction

300* [Explore the context window](/it/context-window): cosa viene caricato nel contesto e quando300* [Explore the context window](/docs/it/context-window): cosa viene caricato nel contesto e quando

301* [Reduce token usage](/it/costs#reduce-token-usage): strategie oltre il caching per gestire la dimensione del contesto301* [Reduce token usage](/docs/it/costs#reduce-token-usage): strategie oltre il caching per gestire la dimensione del contesto

302* [Track and reduce costs](/it/agent-sdk/cost-tracking): tracciamento dei token della cache e configurazione del TTL per i chiamanti dell'Agent SDK302* [Track and reduce costs](/docs/it/agent-sdk/cost-tracking): tracciamento dei token della cache e configurazione del TTL per i chiamanti dell'Agent SDK

303* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): il meccanismo API sottostante, i breakpoint e i prezzi303* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): il meccanismo API sottostante, i breakpoint e i prezzi