Documentation 2026-07-28 23:57 UTC to 2026-07-29 07:01 UTC

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

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