Documentation — Spybara

admin-setup.md +8 −1

Details

110| [Disable agent view](/docs/it/agent-view#how-background-sessions-are-hosted) | Disattivare `claude agents`, `--bg`, `/background` e il supervisore on-demand | `disableAgentView` |110| [Disable agent view](/docs/it/agent-view#how-background-sessions-are-hosted) | Disattivare `claude agents`, `--bg`, `/background` e il supervisore on-demand | `disableAgentView` |

111| [Configure the corporate launcher](/docs/it/corporate-launcher) | Anteponi il [supervisore dell'agente di background](/docs/it/agent-view#how-background-sessions-are-hosted), i suoi worker e gli [altri processi di background coperti](/docs/it/corporate-launcher#what-the-launcher-covers) con un launcher aziendale richiesto invece di disattivare la visualizzazione dell'agente | `processWrapper` |111| [Configure the corporate launcher](/docs/it/corporate-launcher) | Anteponi il [supervisore dell'agente di background](/docs/it/agent-view#how-background-sessions-are-hosted), i suoi worker e gli [altri processi di background coperti](/docs/it/corporate-launcher#what-the-launcher-covers) con un launcher aziendale richiesto invece di disattivare la visualizzazione dell'agente | `processWrapper` |

112| [Model restrictions](/docs/it/model-config#restrict-model-selection) | `availableModels` filtra quali modelli appaiono nel selettore. L'aggiunta di `enforceAvailableModels` vincola anche il modello predefinito selezionato automaticamente. Consulta [surface coverage](/docs/it/model-config#surface-coverage) per come questa impostazione raggiunge la CLI, il web e l'IDE | `availableModels`, `enforceAvailableModels` |112| [Model restrictions](/docs/it/model-config#restrict-model-selection) | `availableModels` filtra quali modelli appaiono nel selettore. L'aggiunta di `enforceAvailableModels` vincola anche il modello predefinito selezionato automaticamente. Consulta [surface coverage](/docs/it/model-config#surface-coverage) per come questa impostazione raggiunge la CLI, il web e l'IDE | `availableModels`, `enforceAvailableModels` |

113| [Effort cap](/docs/it/settings-reference#maxeffortlevel) | Limitare il [livello di sforzo](/docs/it/model-config#adjust-effort-level) per ogni modello o per modello, su ogni provider | `maxEffortLevel` |

113| [Version floor](/docs/it/settings-reference#minimumversion) | Impedire all'aggiornamento automatico di installare al di sotto di un minimo a livello di organizzazione | `minimumVersion` |114| [Version floor](/docs/it/settings-reference#minimumversion) | Impedire all'aggiornamento automatico di installare al di sotto di un minimo a livello di organizzazione | `minimumVersion` |

114| [Required version range](/docs/it/settings-reference#requiredminimumversion) | Rifiutare di avviarsi completamente quando la versione in esecuzione è al di fuori di un intervallo approvato dall'organizzazione. Più forte di `minimumVersion`, che blocca solo i downgrade | `requiredMinimumVersion`, `requiredMaximumVersion` |115| [Required version range](/docs/it/settings-reference#requiredminimumversion) | Rifiutare di avviarsi completamente quando la versione in esecuzione è al di fuori di un intervallo approvato dall'organizzazione. Più forte di `minimumVersion`, che blocca solo i downgrade | `requiredMinimumVersion`, `requiredMaximumVersion` |

115| [Telemetry opt-out](/docs/it/data-usage#telemetry-services) | Disattivare le metriche di utilizzo associate ad Anthropic, i rapporti di errore e i sondaggi su ogni dispositivo | `env` con `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` impostato su `1`; la sezione collegata elenca le variabili per categoria |116| [Telemetry opt-out](/docs/it/data-usage#telemetry-services) | Disattivare le metriche di utilizzo associate ad Anthropic, i rapporti di errore e i sondaggi su ogni dispositivo | `env` con `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` impostato su `1`; la sezione collegata elenca le variabili per categoria |

116 117

117Le organizzazioni i cui membri si autenticano tramite claude.ai o l'API Anthropic possono anche governare i modelli senza distribuire impostazioni: le [restrizioni del modello dell'organizzazione](/docs/it/model-config#organization-model-restrictions) disabilitano i singoli modelli, un [modello predefinito dell'organizzazione](/docs/it/model-config#organization-default-model) imposta quale modello le nuove sessioni iniziano, e i [limiti di sforzo dell'organizzazione](/docs/it/model-config#organization-effort-limits) limitano i livelli di sforzo per ruolo. Tutti e tre i controlli richiedono un piano Claude Enterprise. Le restrizioni dei modelli e i limiti di sforzo sono applicati lato server; il modello predefinito è un punto di partenza che gli utenti possono modificare, a meno che l'organizzazione non lo applichi. L'applicazione è disponibile per un set limitato di organizzazioni; chiedi al tuo team di account Anthropic sulla disponibilità. Nessuno di questi controlli raggiunge le sessioni su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o [Claude Platform on AWS](/docs/it/claude-platform-on-aws); su questi provider, utilizza `availableModels` sopra per le restrizioni e la chiave `model` nelle impostazioni gestite per un valore predefinito.118Se i tuoi membri si autenticano tramite claude.ai o l'API Anthropic e sei su un piano Claude Enterprise, puoi anche governare i modelli dalle impostazioni di amministrazione della tua organizzazione senza distribuire nulla:

119

120* [Organization model restrictions](/docs/it/model-config#organization-model-restrictions): disabilita i singoli modelli. Applicato lato server.

121* [Organization default model](/docs/it/model-config#organization-default-model): imposta quale modello le nuove sessioni iniziano. Gli utenti possono modificarlo a meno che la tua organizzazione non applichi il valore predefinito, che è disponibile per un set limitato di organizzazioni; chiedi al tuo team di account Anthropic.

122* [Organization effort limits](/docs/it/model-config#organization-effort-limits): limita i livelli di sforzo per ruolo. Applicato lato server.

123

124Nessuno di questi controlli raggiunge le sessioni su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o [Claude Platform on AWS](/docs/it/claude-platform-on-aws). Su questi provider, utilizza le impostazioni gestite invece: `availableModels` per le restrizioni, `model` per un valore predefinito, e [`maxEffortLevel`](/docs/it/settings-reference#maxeffortlevel) per un limite di sforzo.

118 125

119[Claude Code on the web](/docs/it/claude-code-on-the-web) ha la sua propria superficie di amministrazione: nella pagina degli ambienti cloud nelle impostazioni di amministrazione, i proprietari creano [ambienti condivisi dall'organizzazione](/docs/it/cloud-environments#organization-shared-environments) che impostano il [livello di accesso alla rete](/docs/it/cloud-environments#network-access), le variabili di ambiente e lo script di configurazione per le sessioni cloud dei membri. I proprietari scelgono l'ambiente predefinito dell'organizzazione separatamente, su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code).126[Claude Code on the web](/docs/it/claude-code-on-the-web) ha la sua propria superficie di amministrazione: nella pagina degli ambienti cloud nelle impostazioni di amministrazione, i proprietari creano [ambienti condivisi dall'organizzazione](/docs/it/cloud-environments#organization-shared-environments) che impostano il [livello di accesso alla rete](/docs/it/cloud-environments#network-access), le variabili di ambiente e lo script di configurazione per le sessioni cloud dei membri. I proprietari scelgono l'ambiente predefinito dell'organizzazione separatamente, su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code).

120 127

advisor.md +17 −6

Details

48/advisor opus48/advisor opus

49```49```

50 50

~~51Il comando conferma con `Advisor set to` seguito dal nome del modello advisor. La tua selezione viene salvata in `advisorModel` nelle impostazioni utente e persiste tra le sessioni.~~51Il comando conferma con `Advisor set to` seguito dal nome del modello advisor. La tua selezione viene salvata in `advisorModel` nelle impostazioni utente e persiste tra le sessioni, eccetto nei casi che la voce [`advisorModel`](/docs/it/settings-reference#advisormodel) elenca come applicabili solo alla sessione corrente.

53Il comando funziona anche dove non c'è un selettore di terminale: in [modalità non interattiva](/docs/it/headless) con `-p`, nell'Agent SDK, nell'app desktop e su [Remote Control](/docs/it/remote-control). Questo richiede Claude Code v2.1.260 o successivo. Su quelle superfici:

55* Esegui `/advisor` senza argomento per stampare il modello advisor corrente e gli alias che accetta.

56* Esegui `/advisor` con un modello, come `/advisor opus`, per impostarlo.

57* Esegui `/advisor off` per disattivarlo.

52 58

53Claude Code non invoca un advisor salvato che l'allowlist [`availableModels`](/docs/it/model-config#restrict-model-selection) della tua organizzazione esclude. Per usare l'advisor, scegli un modello consentito con `/advisor`. Claude Code salva comunque un advisor che il tuo modello principale attuale non supporta. Quell'advisor si attiva dopo che passi a un modello principale [compatibile](#choose-an-advisor-model) con [`/model`](/docs/it/model-config#setting-your-model).59Claude Code non invoca un advisor salvato che l'allowlist [`availableModels`](/docs/it/model-config#restrict-model-selection) della tua organizzazione esclude. Per usare l'advisor, scegli un modello consentito con `/advisor`. Claude Code salva comunque un advisor che il tuo modello principale attuale non supporta. Quell'advisor si attiva dopo che passi a un modello principale [compatibile](#choose-an-advisor-model) con [`/model`](/docs/it/model-config#setting-your-model).

54 60

92L'advisor deve essere almeno altrettanto capace del modello principale. Gli advisor accettati per ogni modello principale sono:98L'advisor deve essere almeno altrettanto capace del modello principale. Gli advisor accettati per ogni modello principale sono:

93 99

95| --------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |101| --------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

97| Sonnet 4.6 | Fable, Opus, Sonnet | |103| Sonnet 4.6 | Fable, Opus, Sonnet | |

100| Opus 4.7 o successivo | Fable, e Opus 4.7 o successivo | Opus 4.7 e i modelli Opus successivi sono classificati come ugualmente capaci, quindi uno qualsiasi di essi accetta un altro come advisor. Un Opus 4.7 principale con un advisor Opus 4.6 o Sonnet 5 viene rifiutato |106| Opus 4.7 o successivo | Fable, e Opus 4.7 o successivo | Opus 4.7 e i modelli Opus successivi sono classificati come ugualmente capaci, quindi uno qualsiasi di essi accetta un altro come advisor. Un Opus 4.7 principale con un advisor Opus 4.6 o Sonnet 5 viene rifiutato |

102 108

103Fable 5.1 richiede Claude Code v2.1.257 o successivo, e Fable 5 richiede v2.1.170 o successivo. Entrambi richiedono [accesso a Fable](/docs/it/model-config#work-with-fable).109Fable 5.1 richiede Claude Code v2.1.257 o successivo. Entrambi i modelli Fable richiedono [accesso a Fable](/docs/it/model-config#work-with-fable).

104 110

105Imposta l'advisor come `fable`, `opus`, o `sonnet`. Questi alias si risolvono nella versione predefinita integrata di Claude Code per ogni famiglia di modelli, che avanza con le nuove versioni di Claude Code. Puoi anche passare un ID modello completo come `claude-opus-5`.111Imposta l'advisor come `fable`, `opus`, o `sonnet`. Questi alias si risolvono nella versione predefinita integrata di Claude Code per ogni famiglia di modelli, che avanza con le nuove versioni di Claude Code. Puoi anche passare un ID modello completo come `claude-opus-5`.

106 112

161 Costo167 Costo

162</h2>168</h2>

163 169

164Quando Claude chiama l'advisor, il modello advisor legge la conversazione, quindi ogni chiamata consuma token alle tariffe del modello advisor in aggiunta all'utilizzo del tuo modello principale. Con la fatturazione API, paghi le tariffe di input e output del modello advisor per i token dell'advisor. Sui piani di abbonamento, l'utilizzo dell'advisor conta verso i limiti di utilizzo del tuo piano, ad eccezione del fatto che un advisor Fable viene fatturato ai [crediti di utilizzo](/docs/it/model-config#fable-and-usage-credits) sui piani in cui l'utilizzo di Fable lo fa. Se il tuo account richiede il consenso ai crediti di utilizzo, un advisor Fable non viene fatturato finché non lo dai, perché Claude Code [non applica la selezione](#fable-advisor-and-usage-credits) fino ad allora.170Quando Claude chiama l'advisor, il modello advisor legge la conversazione, quindi ogni chiamata consuma token alle tariffe del modello advisor in aggiunta all'utilizzo del tuo modello principale. Come questi token dell'advisor vengono fatturati dipende da come paghi:

171

172* **Fatturazione API**: paghi le tariffe di input e output del modello advisor per i token dell'advisor

173* **Piani di abbonamento**: l'utilizzo dell'advisor conta verso i limiti di utilizzo del tuo piano, ad eccezione del fatto che un advisor Fable viene fatturato ai [crediti di utilizzo](/docs/it/model-config#fable-and-usage-credits) sui piani in cui l'utilizzo di Fable lo fa

174

175Se il tuo account richiede il consenso ai crediti di utilizzo, un advisor Fable non viene fatturato finché non lo dai, perché Claude Code [non applica la selezione](#fable-advisor-and-usage-credits) fino ad allora.

165 176

166Claude chiama l'advisor nei punti decisionali piuttosto che ad ogni turno, quindi l'accoppiamento di un modello principale più veloce con un advisor più potente in genere costa meno che eseguire il modello più potente in tutto. L'utilizzo dell'advisor conta verso i totali della sessione mostrati da [`/usage`](/docs/it/costs#track-your-costs).177Claude chiama l'advisor nei punti decisionali piuttosto che ad ogni turno, quindi l'accoppiamento di un modello principale più veloce con un advisor più potente in genere costa meno che eseguire il modello più potente in tutto. L'utilizzo dell'advisor conta verso i totali della sessione mostrati da [`/usage`](/docs/it/costs#track-your-costs).

167 178

189 Disattiva l'advisor200 Disattiva l'advisor

190</h2>201</h2>

191 202

192Per smettere di usare l'advisor e cancellare il tuo `advisorModel` salvato, esegui `/advisor off` o scegli **No advisor** nel selettore `/advisor`:203Per smettere di usare l'advisor, esegui `/advisor off` o scegli **No advisor** nel selettore `/advisor`:

193 204

194```205```

195/advisor off206/advisor off

agent-sdk/agent-loop.md +21 −9

Details

23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-loop-diagram-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=afe723c52a324d3c61fa72fb02432ab6" className="hidden dark:block" alt="Diagram of the agent loop: your prompt enters the agentic loop, where Claude evaluates and either requests tool calls, whose results feed back into another evaluation, or returns the final answer" width="720" height="212" data-path="images/agent-loop-diagram-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-loop-diagram-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=afe723c52a324d3c61fa72fb02432ab6" className="hidden dark:block" alt="Diagram of the agent loop: your prompt enters the agentic loop, where Claude evaluates and either requests tool calls, whose results feed back into another evaluation, or returns the final answer" width="720" height="212" data-path="images/agent-loop-diagram-dark.svg" />

24 24

251. **Ricevere il prompt.** Claude riceve il vostro prompt, insieme al prompt di sistema, alle definizioni degli strumenti e alla cronologia della conversazione. L'SDK produce un [`SystemMessage`](#message-types) con sottotipo `"init"` contenente i metadati della sessione.251. **Ricevere il prompt.** Claude riceve il vostro prompt, insieme al prompt di sistema, alle definizioni degli strumenti e alla cronologia della conversazione. L'SDK produce un [`SystemMessage`](#message-types) con sottotipo `"init"` contenente i metadati della sessione.

262. **Valutare e rispondere.** Claude valuta lo stato attuale e determina come procedere. Può rispondere con testo, richiedere una o più chiamate di strumenti, o entrambi. L'SDK produce un [`AssistantMessage`](#message-types) contenente il testo e le richieste di chiamate di strumenti.262. **Valutare e rispondere.** Claude valuta lo stato attuale e determina come procedere. Può rispondere con testo, richiedere una o più chiamate di strumenti, o entrambi. L'SDK produce uno o più oggetti [`AssistantMessage`](#message-types), uno per ogni blocco di contenuto, come un blocco di testo o una richiesta di chiamata di strumento.

273. **Eseguire gli strumenti.** L'SDK esegue ogni strumento richiesto e raccoglie i risultati. Ogni set di risultati degli strumenti viene restituito a Claude per la decisione successiva. Potete utilizzare [hooks](/docs/it/agent-sdk/hooks) per intercettare, modificare o bloccare le chiamate di strumenti prima che vengano eseguite.273. **Eseguire gli strumenti.** L'SDK esegue ogni strumento richiesto e raccoglie i risultati. Ogni set di risultati degli strumenti viene restituito a Claude per la decisione successiva. Potete utilizzare [hooks](/docs/it/agent-sdk/hooks) per intercettare, modificare o bloccare le chiamate di strumenti prima che vengano eseguite.

284. **Ripetere.** I passaggi 2 e 3 si ripetono come un ciclo. Ogni ciclo completo è un turno. Claude continua a chiamare gli strumenti ed elaborare i risultati fino a quando non produce una risposta senza chiamate di strumenti.284. **Ripetere.** I passaggi 2 e 3 si ripetono come un ciclo. Ogni ciclo completo è un turno. Claude continua a chiamare gli strumenti ed elaborare i risultati fino a quando non produce una risposta senza chiamate di strumenti.

295. **Restituire il risultato.** L'SDK produce un [`AssistantMessage`](#message-types) finale con la risposta di testo (senza chiamate di strumenti), seguito da un [`ResultMessage`](#message-types) con il testo finale, l'utilizzo dei token, il costo e l'ID della sessione.295. **Restituire il risultato.** L'SDK produce un [`AssistantMessage`](#message-types) finale con la risposta di testo (senza chiamate di strumenti), seguito da un [`ResultMessage`](#message-types) con il testo finale, l'utilizzo dei token, il costo e l'ID della sessione.

41Per prima cosa, l'SDK invia il vostro prompt a Claude e produce un [`SystemMessage`](#message-types) con i metadati della sessione. Poi il ciclo inizia:41Per prima cosa, l'SDK invia il vostro prompt a Claude e produce un [`SystemMessage`](#message-types) con i metadati della sessione. Poi il ciclo inizia:

42 42

431. **Turno 1:** Claude chiama `Bash` per eseguire `npm test`. L'SDK produce un [`AssistantMessage`](#message-types) con la chiamata dello strumento, esegue il comando, poi produce un [`UserMessage`](#message-types) con l'output (tre errori).431. **Turno 1:** Claude chiama `Bash` per eseguire `npm test`. L'SDK produce un [`AssistantMessage`](#message-types) con la chiamata dello strumento, esegue il comando, poi produce un [`UserMessage`](#message-types) con l'output (tre errori).

~~442. **Turno 2:** Claude chiama `Read` su `auth.ts` e `auth.test.ts`. L'SDK restituisce il contenuto dei file e produce un `AssistantMessage`.~~442. **Turno 2:** Claude chiama `Read` su `auth.ts` e `auth.test.ts`. L'SDK produce un `AssistantMessage` per ogni chiamata e restituisce il contenuto dei file.

~~453. **Turno 3:** Claude chiama `Edit` per correggere `auth.ts`, poi chiama `Bash` per rieseguire `npm test`. Tutti e tre i test passano. L'SDK produce un `AssistantMessage`.~~453. **Turno 3:** Claude chiama `Edit` per correggere `auth.ts`, poi chiama `Bash` per rieseguire `npm test`. Tutti e tre i test passano. L'SDK produce un `AssistantMessage` per ogni chiamata.

464. **Turno finale:** Claude produce una risposta solo di testo senza chiamate di strumenti: "Corretto il bug di autenticazione, tutti e tre i test passano ora." L'SDK produce un `AssistantMessage` finale con questo testo, poi un [`ResultMessage`](#message-types) con lo stesso testo più costo e utilizzo.464. **Turno finale:** Claude produce una risposta solo di testo senza chiamate di strumenti: "Corretto il bug di autenticazione, tutti e tre i test passano ora." L'SDK produce un `AssistantMessage` finale con questo testo, poi un [`ResultMessage`](#message-types) con lo stesso testo più costo e utilizzo.

47 47

48Erano quattro turni: tre con chiamate di strumenti, uno con risposta solo di testo finale.48Erano quattro turni: tre con chiamate di strumenti, uno con risposta solo di testo finale.

65 * `"worker_shutting_down"`: il ciclo terminerà dopo il turno corrente perché l'host sta uscendo o Remote Control si è disconnesso65 * `"worker_shutting_down"`: il ciclo terminerà dopo il turno corrente perché l'host sta uscendo o Remote Control si è disconnesso

66 66

67 In TypeScript, ogni sottotipo diverso da `"init"` è il suo proprio tipo nell'unione [`SDKMessage`](/docs/it/agent-sdk/typescript#sdkmessage) piuttosto che un sottotipo di `SDKSystemMessage`.67 In TypeScript, ogni sottotipo diverso da `"init"` è il suo proprio tipo nell'unione [`SDKMessage`](/docs/it/agent-sdk/typescript#sdkmessage) piuttosto che un sottotipo di `SDKSystemMessage`.

~~68* **`AssistantMessage`:** emesso dopo ogni risposta di Claude, inclusa quella finale solo di testo. Contiene blocchi di contenuto di testo e blocchi di chiamate di strumenti da quel turno.~~68* **`AssistantMessage`:** emesso per ogni blocco di contenuto nelle risposte di Claude, incluso quello finale solo di testo. Ogni messaggio contiene un singolo blocco di contenuto, come testo o una chiamata di strumento, e i messaggi da una risposta condividono un ID messaggio.

69* **`UserMessage`:** emesso dopo ogni esecuzione di strumento con il risultato dello strumento inviato di nuovo a Claude. Emesso anche per qualsiasi input dell'utente che trasmettete a metà ciclo.69* **`UserMessage`:** emesso dopo ogni esecuzione di strumento con il risultato dello strumento inviato di nuovo a Claude. Emesso anche per qualsiasi input dell'utente che trasmettete a metà ciclo.

70* **`StreamEvent`:** emesso solo quando i messaggi parziali sono abilitati. Contiene eventi di streaming API grezzi (delta di testo, chunk di input dello strumento). Vedere [Stream responses](/docs/it/agent-sdk/streaming-output).70* **`StreamEvent`:** emesso solo quando i messaggi parziali sono abilitati. Contiene eventi di streaming API grezzi (delta di testo, chunk di input dello strumento). Vedere [Stream responses](/docs/it/agent-sdk/streaming-output).

71* **`ResultMessage`:** segna la fine del ciclo dell'agente. Contiene il risultato di testo finale, l'utilizzo dei token, il costo e l'ID della sessione. Controllate il campo `subtype` per determinare se l'attività ha avuto successo o ha raggiunto un limite. Un piccolo numero di eventi di sistema finali, come `prompt_suggestion`, può arrivare dopo di esso, quindi iterate il flusso fino al completamento piuttosto che interrompere al risultato. Vedere [Gestire il risultato](#handle-the-result).71* **`ResultMessage`:** segna la fine del ciclo dell'agente. Contiene il risultato di testo finale, l'utilizzo dei token, il costo e l'ID della sessione. Controllate il campo `subtype` per determinare se l'attività ha avuto successo o ha raggiunto un limite. Un piccolo numero di eventi di sistema finali, come `prompt_suggestion`, può arrivare dopo di esso, quindi iterate il flusso fino al completamento piuttosto che interrompere al risultato. Vedere [Gestire il risultato](#handle-the-result).

91 <CodeGroup>91 <CodeGroup>

92 ```python Python theme={null}92 ```python Python theme={null}

93 import asyncio93 import asyncio

~~94 from claude_agent_sdk import query, AssistantMessage, ResultMessage~~94 from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock

95 95

96 96

97 async def main():97 async def main():

98 try:98 try:

99 async for message in query(prompt="Summarize this project"):99 async for message in query(prompt="Summarize this project"):

100 if isinstance(message, AssistantMessage):100 if isinstance(message, AssistantMessage):

101 print(f"Turn completed: {len(message.content)} content blocks")101 # Each AssistantMessage carries one content block

102 for block in message.content:

103 if isinstance(block, TextBlock):

104 print(f"Claude: {block.text}")

105 elif isinstance(block, ToolUseBlock):

106 print(f"Tool call: {block.name}")

102 if isinstance(message, ResultMessage):107 if isinstance(message, ResultMessage):

103 if message.subtype == "success":108 if message.subtype == "success":

104 print(message.result)109 print(message.result)

120 try {125 try {

121 for await (const message of query({ prompt: "Summarize this project" })) {126 for await (const message of query({ prompt: "Summarize this project" })) {

122 if (message.type === "assistant") {127 if (message.type === "assistant") {

123 console.log(`Turn completed: ${message.message.content.length} content blocks`);128 // Each assistant message carries one content block

129 for (const block of message.message.content) {

130 if (block.type === "text") {

131 console.log(`Claude: ${block.text}`);

132 } else if (block.type === "tool_use") {

133 console.log(`Tool call: ${block.name}`);

134 }

135 }

124 }136 }

125 if (message.type === "result") {137 if (message.type === "result") {

126 if (message.subtype === "success") {138 if (message.subtype === "success") {

175 187

176Claude determina quali strumenti chiamare in base all'attività, ma voi controllate se quelle chiamate sono autorizzate a essere eseguite. Potete approvare automaticamente strumenti specifici, bloccare altri completamente, o richiedere l'approvazione per tutto. Tre opzioni lavorano insieme per determinare cosa viene eseguito:188Claude determina quali strumenti chiamare in base all'attività, ma voi controllate se quelle chiamate sono autorizzate a essere eseguite. Potete approvare automaticamente strumenti specifici, bloccare altri completamente, o richiedere l'approvazione per tutto. Tre opzioni lavorano insieme per determinare cosa viene eseguito:

177 189

178* **`allowed_tools` / `allowedTools`** approva automaticamente gli strumenti elencati. Un agente di sola lettura con `["Read", "Glob", "Grep"]` nel suo elenco di strumenti consentiti esegue quegli strumenti senza chiedere. Gli strumenti non elencati sono ancora disponibili ma richiedono autorizzazione.190* **`allowed_tools` / `allowedTools`** approva automaticamente gli strumenti elencati. Un agente di sola lettura con `["Read", "Glob", "Grep"]` nel suo elenco di strumenti consentiti esegue quegli strumenti senza chiedere. Gli strumenti non elencati sono ancora disponibili, e le chiamate a essi che necessitano di approvazione ricadono nella modalità di autorizzazione e in `canUseTool`.

179* **`disallowed_tools` / `disallowedTools`** blocca gli strumenti elencati, indipendentemente da altre impostazioni. Vedere [Autorizzazioni](/docs/it/agent-sdk/permissions) per l'ordine in cui le regole vengono controllate prima che uno strumento venga eseguito.191* **`disallowed_tools` / `disallowedTools`** blocca gli strumenti elencati, indipendentemente da altre impostazioni. Vedere [Autorizzazioni](/docs/it/agent-sdk/permissions) per l'ordine in cui le regole vengono controllate prima che uno strumento venga eseguito.

180* **`permission_mode` / `permissionMode`** controlla quanto controllo umano desiderate. L'SDK valuta la modalità attiva insieme alle vostre regole di consentimento e negazione in un ordine fisso, descritto in [Come vengono valutate le autorizzazioni](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated). Vedere [Modalità di autorizzazione](#permission-mode) per le modalità disponibili.192* **`permission_mode` / `permissionMode`** controlla quanto controllo umano desiderate. L'SDK valuta la modalità attiva insieme alle vostre regole di consentimento e negazione in un ordine fisso, descritto in [Come vengono valutate le autorizzazioni](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated). Vedere [Modalità di autorizzazione](#permission-mode) per le modalità disponibili.

181 193

245| `"default"` | Gli strumenti non coperti da regole di consentimento attivano il vostro callback `canUseTool`; nessun callback significa negare | Applicazioni interattive con un callback di approvazione personalizzato |257| `"default"` | Gli strumenti non coperti da regole di consentimento attivano il vostro callback `canUseTool`; nessun callback significa negare | Applicazioni interattive con un callback di approvazione personalizzato |

246| `"acceptEdits"` | Approva automaticamente le modifiche ai file e i comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.); altri comandi Bash seguono le regole predefinite | Fidate delle modifiche di Claude e volete un'iterazione più veloce, ad esempio durante la prototipazione o quando lavorate in una directory isolata |258| `"acceptEdits"` | Approva automaticamente le modifiche ai file e i comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.); altri comandi Bash seguono le regole predefinite | Fidate delle modifiche di Claude e volete un'iterazione più veloce, ad esempio durante la prototipazione o quando lavorate in una directory isolata |

247| `"plan"` | Claude esplora e pianifica senza modificare i vostri file sorgente; le modifiche ai file non vengono mai approvate automaticamente e vengono richieste tramite il vostro callback `canUseTool` | Volete che Claude proponga modifiche senza eseguirle, ad esempio durante la revisione del codice o quando dovete approvare le modifiche prima che vengano apportate |259| `"plan"` | Claude esplora e pianifica senza modificare i vostri file sorgente; le modifiche ai file non vengono mai approvate automaticamente e vengono richieste tramite il vostro callback `canUseTool` | Volete che Claude proponga modifiche senza eseguirle, ad esempio durante la revisione del codice o quando dovete approvare le modifiche prima che vengano apportate |

248| `"dontAsk"` | Non chiede mai. Gli strumenti pre-approvati da [regole di autorizzazione](/docs/it/settings-reference#permission-settings) vengono eseguiti; tutto il resto viene negato. `AskUserQuestion`, strumenti connettore [impostati dalla vostra organizzazione su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) e strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) vengono negati anche se li avete consentiti | Volete una superficie di strumenti fissa ed esplicita per un agente headless e preferite un rifiuto esplicito rispetto a un affidamento silenzioso all'assenza di `canUseTool` |260| `"dontAsk"` | Non chiede mai. Gli strumenti pre-approvati da [regole di autorizzazione](/docs/it/settings-reference#permission-settings) vengono eseguiti, e così anche le chiamate che non richiedono approvazione in modalità `default`, come le letture di file all'interno delle vostre directory di lavoro; ogni chiamata che altrimenti richiederebbe un prompt viene negata. `AskUserQuestion`, strumenti connettore [impostati dalla vostra organizzazione su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) e strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) vengono negati anche se li avete consentiti | Volete una superficie di strumenti fissa ed esplicita per un agente headless e preferite un rifiuto esplicito rispetto a un affidamento silenzioso all'assenza di `canUseTool` |

249| `"auto"` | Utilizza un classificatore di modello per approvare o negare i prompt di autorizzazione. Vedere [Modalità Auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per disponibilità e comportamento | Agenti autonomi che desiderano ancora protezioni di sicurezza sull'utilizzo degli strumenti |261| `"auto"` | Utilizza un classificatore di modello per approvare o negare i prompt di autorizzazione. Vedere [Modalità Auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per disponibilità e comportamento | Agenti autonomi che desiderano ancora protezioni di sicurezza sull'utilizzo degli strumenti |

250| `"bypassPermissions"` | Esegue tutti gli strumenti consentiti senza chiedere, tranne gli strumenti corrispondenti a una regola [`ask`](/docs/it/settings-reference#permission-settings) esplicita, strumenti connettore [impostati dalla vostra organizzazione su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) e strumenti che richiedono l'interazione dell'utente. Le [protezioni di messaggistica tra sessioni](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode) si applicano ancora. Vedere [Come vengono valutate le autorizzazioni](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) per l'ordine di precedenza. In TypeScript SDK, richiede anche `allowDangerouslySkipPermissions: true` in `options`. Non può essere utilizzato quando si esegue come root su Unix. Utilizzare solo in ambienti isolati dove le azioni dell'agente non possono influenzare i sistemi che vi interessano | CI, container o altri ambienti isolati |262| `"bypassPermissions"` | Esegue tutti gli strumenti consentiti senza chiedere, tranne gli strumenti corrispondenti a una regola [`ask`](/docs/it/settings-reference#permission-settings) esplicita, strumenti connettore [impostati dalla vostra organizzazione su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) e strumenti che richiedono l'interazione dell'utente. Le [protezioni di messaggistica tra sessioni](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode) si applicano ancora. Vedere [Come vengono valutate le autorizzazioni](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) per l'ordine di precedenza. In TypeScript SDK, richiede anche `allowDangerouslySkipPermissions: true` in `options`. Non può essere utilizzato quando si esegue come root su Unix. Utilizzare solo in ambienti isolati dove le azioni dell'agente non possono influenzare i sistemi che vi interessano | CI, container o altri ambienti isolati |

251 263

agent-sdk/cost-tracking.md +127 −59

Details

6 6

7> Scopri come tracciare l'utilizzo dei token, stimare i costi e configurare la memorizzazione nella cache dei prompt con Claude Agent SDK.7> Scopri come tracciare l'utilizzo dei token, stimare i costi e configurare la memorizzazione nella cache dei prompt con Claude Agent SDK.

8 8

9Claude Agent SDK fornisce informazioni dettagliate sull'utilizzo dei token per ogni interazione con Claude. Questa guida spiega come tracciare correttamente l'utilizzo e comprendere la segnalazione dei costi, soprattutto quando si affrontano utilizzi di strumenti paralleli e conversazioni multi-step.9Claude Agent SDK fornisce informazioni dettagliate sull'utilizzo dei token per ogni interazione con Claude. Questa guida spiega come tracciare correttamente l'utilizzo e comprendere la segnalazione dei costi, soprattutto quando si affrontano usi paralleli di strumenti e conversazioni multi-step.

10 10

~~11Per la documentazione API completa, consulta il [riferimento TypeScript SDK](/it/agent-sdk/typescript) e il [riferimento Python SDK](/it/agent-sdk/python).~~11Per la documentazione API completa, consulta il [riferimento TypeScript SDK](/docs/it/agent-sdk/typescript) e il [riferimento Python SDK](/docs/it/agent-sdk/python).

12 12

13<Warning>13<Warning>

14 I campi `total_cost_usd` e `costUSD` sono stime lato client, non dati di fatturazione autorevoli. L'SDK li calcola localmente da una tabella dei prezzi inclusa al momento della compilazione, quindi possono divergere da ciò che viene effettivamente fatturato quando:14 I campi `total_cost_usd` e `costUSD` sono stime lato client, non dati di fatturazione autorevoli. L'SDK li calcola localmente da una tabella dei prezzi inclusa al momento della compilazione, a meno che non sia in vigore una tabella [`modelPricing`](/docs/it/settings-reference#modelpricing). Possono divergere da ciò che viene effettivamente fatturato quando:

15 15

16 * i prezzi cambiano16 * i prezzi cambiano

17 * la versione dell'SDK installata non riconosce un modello17 * la versione dell'SDK installata non riconosce un modello

18 * si applicano regole di fatturazione che il client non può modellare18 * si applicano regole di fatturazione che il client non può modellare

19 19

20 Utilizza questi campi per approfondimenti di sviluppo e budget approssimativi. Per la fatturazione autorevole, utilizza l'[API di utilizzo e costi](https://platform.claude.com/docs/en/build-with-claude/usage-cost-api) o la pagina Utilizzo nella [Console Claude](https://platform.claude.com/usage). Non fatturare gli utenti finali o attivare decisioni finanziarie da questi campi.20 Una regola di fatturazione che l'SDK modella è la [determinazione dei prezzi per la residenza dei dati](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing). Quando la `usage` di una risposta segnala `inference_geo: "us"`, l'SDK moltiplica il prezzo di listino dei token di quella risposta per 1,1. Le tariffe per richiesta come la ricerca web non vengono moltiplicate. Richiede TypeScript Agent SDK v0.3.239 o successivo, oppure Python Agent SDK v0.2.144 o successivo.

22 Utilizza questi campi per approfondimenti di sviluppo e budget approssimativi. Per la fatturazione autorevole, utilizza l'[API di utilizzo e costi](https://platform.claude.com/docs/en/build-with-claude/usage-cost-api) o la pagina Utilizzo nella [Claude Console](https://platform.claude.com/usage). Non fatturare gli utenti finali o attivare decisioni finanziarie da questi campi.

21</Warning>23</Warning>

22 24

23<h2 id="understand-token-usage">25<h2 id="understand-token-usage">

26 28

27Gli SDK TypeScript e Python espongono gli stessi dati di utilizzo con nomi di campi diversi:29Gli SDK TypeScript e Python espongono gli stessi dati di utilizzo con nomi di campi diversi:

28 30

29* **TypeScript** fornisce scomposizioni di token per step su ogni messaggio dell'assistente (`message.message.id`, `message.message.usage`), costi per modello tramite `modelUsage` sul messaggio risultato e un totale cumulativo sul messaggio risultato.31* **TypeScript** fornisce suddivisioni dei token per fase su ogni messaggio dell'assistente (`message.message.id`, `message.message.usage`), costo per modello tramite `modelUsage` sul messaggio risultato, e un totale cumulativo sul messaggio risultato.

30* **Python** fornisce scomposizioni di token per step su ogni messaggio dell'assistente (`message.usage`, `message.message_id`), costi per modello tramite `model_usage` sul messaggio risultato e il totale accumulato sul messaggio risultato (`total_cost_usd` e dizionario `usage`).32* **Python** fornisce suddivisioni dei token per fase su ogni messaggio dell'assistente come `message.usage` e `message.message_id`, costo per modello tramite `model_usage` sul messaggio risultato, e il totale cumulativo sul messaggio risultato come `total_cost_usd`.

31 33

32Entrambi gli SDK utilizzano lo stesso modello di costo sottostante ed espongono la stessa granularità. La differenza è nella denominazione dei campi e nel punto in cui l'utilizzo per step è annidato.34Entrambi gli SDK utilizzano lo stesso modello di costo sottostante ed espongono la stessa granularità. La differenza è nella denominazione dei campi e nel modo in cui l'utilizzo per fase è annidato.

33 35

34Il tracciamento dei costi dipende dalla comprensione di come l'SDK delimita i dati di utilizzo:36Il tracciamento dei costi dipende dalla comprensione di come l'SDK delimita i dati di utilizzo:

35 37

36* **Chiamata `query()`:** una singola invocazione della funzione `query()` dell'SDK. Una singola chiamata può coinvolgere più step (Claude risponde, utilizza strumenti, ottiene risultati, risponde di nuovo). Ogni chiamata produce un messaggio [`result`](/it/agent-sdk/typescript#sdkresultmessage) alla fine.38* **Chiamata `query()`:** una singola invocazione della funzione `query()` dell'SDK. Una singola chiamata può coinvolgere più fasi: Claude risponde, utilizza strumenti, ottiene risultati e risponde di nuovo. Ogni chiamata produce un messaggio [`result`](/docs/it/agent-sdk/typescript#sdkresultmessage) alla fine, tranne in [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), dove una chiamata `query()` comporta più turni dell'utente e ogni turno emette il proprio messaggio `result`.

~~37* **Step:** un singolo ciclo di richiesta/risposta all'interno di una chiamata `query()`. Ogni step produce messaggi dell'assistente con utilizzo dei token.~~39* **Fase:** un singolo ciclo richiesta/risposta all'interno di una chiamata `query()`. Ogni fase produce messaggi dell'assistente con utilizzo dei token.

38* **Sessione:** una serie di chiamate `query()` collegate da un ID di sessione (utilizzando l'opzione `resume`). Ogni chiamata `query()` all'interno di una sessione segnala il proprio costo in modo indipendente.40* **Sessione:** una serie di chiamate `query()` collegate da un ID di sessione (utilizzando l'opzione `resume`). Ogni chiamata `query()` all'interno di una sessione segnala il proprio costo in modo indipendente.

39 41

~~40Il diagramma seguente mostra il flusso di messaggi da una singola chiamata `query()`, con utilizzo dei token segnalato ad ogni step e la stima cumulativa alla fine:~~42Il diagramma seguente mostra il flusso di messaggi da una singola chiamata `query()`, con l'utilizzo dei token segnalato ad ogni fase e la stima cumulativa alla fine:

44<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=68497aee338e01cc745323af7aea378e" className="dark:hidden" alt="Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows the estimated total_cost_usd." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />

41 45

42<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=68497aee338e01cc745323af7aea378e" alt="Diagramma che mostra una query che produce due step di messaggi. Lo Step 1 ha quattro messaggi dell'assistente che condividono lo stesso ID e utilizzo (contare una volta), lo Step 2 ha un messaggio dell'assistente con un nuovo ID e il messaggio risultato finale mostra il total_cost_usd stimato." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />46<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-sdk/message-usage-flow-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=8ea95085abc0a6b7f55ecef498bd4d14" className="hidden dark:block" alt="Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows the estimated total_cost_usd." width="760" height="520" data-path="images/agent-sdk/message-usage-flow-dark.svg" />

43 47

44<Steps>48<Steps>

~~45 <Step title="Ogni step produce messaggi dell'assistente">~~49 <Step title="Ogni fase produce messaggi dell'assistente">

46 Quando Claude risponde, invia uno o più messaggi dell'assistente. In TypeScript, ogni messaggio dell'assistente contiene un `BetaMessage` annidato (accessibile tramite `message.message`) con un `id` e un oggetto [`usage`](https://platform.claude.com/docs/en/api/messages) con conteggi di token (`input_tokens`, `output_tokens`). In Python, la classe dataclass `AssistantMessage` espone gli stessi dati direttamente tramite `message.usage` e `message.message_id`. Quando Claude utilizza più strumenti in un turno, tutti i messaggi in quel turno condividono lo stesso ID, quindi deduplicare per ID per evitare il doppio conteggio.50 Quando Claude risponde, invia uno o più messaggi dell'assistente. In TypeScript, ogni messaggio dell'assistente contiene un `BetaMessage` annidato (accessibile tramite `message.message`) con un `id` e un oggetto [`usage`](https://platform.claude.com/docs/en/api/messages) con conteggi dei token (`input_tokens`, `output_tokens`). In Python, la dataclass `AssistantMessage` espone gli stessi dati direttamente tramite `message.usage` e `message.message_id`. Quando Claude utilizza più strumenti in un turno, tutti i messaggi in quel turno condividono lo stesso ID, quindi deduplicare per ID per evitare il doppio conteggio.

47 </Step>51 </Step>

48 52

49 <Step title="Il messaggio risultato fornisce la stima cumulativa">53 <Step title="Il messaggio risultato fornisce la stima cumulativa">

50 Quando la chiamata `query()` si completa, l'SDK emette un messaggio risultato con `total_cost_usd` e `usage` cumulativo. Questo è disponibile sia in TypeScript ([`SDKResultMessage`](/it/agent-sdk/typescript#sdkresultmessage)) che in Python ([`ResultMessage`](/it/agent-sdk/python#resultmessage)). Se effettui più chiamate `query()` (ad esempio, in una sessione multi-turno), ogni risultato riflette solo il costo di quella singola chiamata. Se hai bisogno solo della stima totale, puoi ignorare l'utilizzo per step e leggere questo singolo valore.54 Quando la chiamata `query()` si completa, l'SDK emette un messaggio risultato con `total_cost_usd` e `usage` cumulativo, tipizzato come [`SDKResultMessage`](/docs/it/agent-sdk/typescript#sdkresultmessage) in TypeScript e [`ResultMessage`](/docs/it/agent-sdk/python#resultmessage) in Python. Se si effettuano più chiamate `query()`, ad esempio in una sessione multi-turno, ogni risultato riflette solo il costo di quella singola chiamata. Se è necessario solo il totale stimato, è possibile ignorare l'utilizzo per fase e leggere questo singolo valore.

56 In modalità input streaming, ogni turno emette il proprio messaggio risultato. Vedere [Tracciare i costi in modalità input streaming](#track-costs-in-streaming-input-mode) per come leggere i totali delle chiamate in quella modalità.

51 </Step>57 </Step>

52</Steps>58</Steps>

53 59

60<h2 id="track-costs-in-streaming-input-mode">

61 Tracciare i costi in modalità di input in streaming

62</h2>

64In [modalità di input in streaming](/docs/it/agent-sdk/streaming-vs-single-mode), una singola chiamata `query()` contiene più turni utente e ogni turno emette il proprio messaggio di risultato. I campi del risultato differiscono in ambito:

66* **`usage`**: copre solo quel turno, e all'interno di esso solo il ciclo principale dell'agente, non eventuali subagenti che ha eseguito.

67* **`total_cost_usd` e `modelUsage`, o `model_usage` in Python**: portano il totale cumulativo per l'intera chiamata fino a quel momento.

69In una chiamata in cui la vostra app non invia mai `/clear`, `/reset`, o `/new`, leggete il risultato più recente per i totali della chiamata piuttosto che sommare i risultati.

71I totali cumulativi ricominciamo ogni volta che la vostra app invia uno di questi tre comandi, e all'interno di una chiamata `query()` nient'altro li ripristina. Tre risultati sono importanti per la vostra contabilità:

73* **Il risultato del turno `/clear`**: copre solo ciò che è stato eseguito dal ripristino, e porta un nuovo `session_id`.

74* **Ogni risultato successivo**: continua a contare da quel ripristino.

75* **L'ultimo risultato prima di ogni `/clear`**: contiene il totale per i turni dal ripristino precedente.

77Per totalizzare l'intera chiamata, aggiungete l'ultimo risultato prima di ogni `/clear` al risultato finale della chiamata. Ogni altro risultato, incluso quello del turno `/clear`, è sostituito da uno successivo.

79In TypeScript, l'SDK emette anche un [`SDKConversationResetMessage`](/docs/it/agent-sdk/typescript#sdkconversationresetmessage) ad ogni ripristino, quindi potete rilevare i ripristini dal flusso. In Python, l'SDK emette analogamente un `ConversationResetMessage`. Prima della versione Python SDK v0.2.137, l'iteratore Python ha eliminato quel messaggio, quindi su quelle versioni contate i ripristini voi stessi dai turni `/clear` che la vostra app invia.

81`maxBudgetUsd`, o `max_budget_usd` in Python, viene confrontato con lo stesso totale cumulativo, quindi un `/clear` avvia anche il budget da capo.

54<h2 id="get-the-total-cost-of-a-query">83<h2 id="get-the-total-cost-of-a-query">

55 Ottenere il costo totale di una query84 Ottenere il costo totale di una query

56</h2>85</h2>

57 86

58Il messaggio risultato ([TypeScript](/it/agent-sdk/typescript#sdkresultmessage), [Python](/it/agent-sdk/python#resultmessage)) segna la fine del ciclo dell'agente per una chiamata `query()`. Include `total_cost_usd`, il costo stimato cumulativo su tutti gli step in quella chiamata. Questo funziona sia per risultati di successo che di errore. Se utilizzi sessioni per effettuare più chiamate `query()`, ogni risultato riflette solo il costo di quella singola chiamata.87Il messaggio di risultato, tipizzato come [`SDKResultMessage`](/docs/it/agent-sdk/typescript#sdkresultmessage) in TypeScript e [`ResultMessage`](/docs/it/agent-sdk/python#resultmessage) in Python, segna la fine del ciclo dell'agente per una chiamata `query()`. Include `total_cost_usd`, il costo stimato cumulativo su tutti i passaggi in quella chiamata. In Python il campo è tipizzato come opzionale, quindi verificate che non sia `None` prima di leggerlo. I risultati di successo e di errore lo portano entrambi, anche se il risultato finale di un [crash della sessione](#recover-totals-after-a-session-crash) potrebbe portarlo azzerato.

89Se utilizzate sessioni per effettuare più chiamate `query()`, ogni risultato riflette solo il costo di quella singola chiamata. In modalità di input in streaming, leggete i totali delle chiamate come descritto in [Track costs in streaming input mode](#track-costs-in-streaming-input-mode).

59 90

60I tre campi a livello di risultato differiscono in ciò che contano quando l'agente genera [subagenti](/it/agent-sdk/subagents). Utilizza `modelUsage`, o `model_usage` in Python, per la contabilità dei token dell'intero albero; il campo `usage` sottoconta non appena si verifica l'annidamento.91I tre campi a livello di risultato differiscono in ciò che contano quando l'agente genera [subagenti](/docs/it/agent-sdk/subagents). Utilizzate `modelUsage`, o `model_usage` in Python, per la contabilità dei token dell'intero albero; il campo `usage` sottoconta non appena si verifica l'annidamento.

61 92

~~62| Campo | Attività subagente |~~93| Campo | Attività del subagente |

63| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |94| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |

64| `usage` | Escluso. Conta solo il ciclo dell'agente di primo livello, quindi i token consumati all'interno dei subagenti non vengono aggiunti |95| `usage` | Escluso. Conta solo il ciclo dell'agente di primo livello, quindi i token consumati all'interno dei subagenti non vengono aggiunti |

65| `total_cost_usd` | Incluso. Conta le richieste dei subagenti insieme al ciclo di primo livello |96| `total_cost_usd` | Incluso. Conta le richieste dei subagenti insieme al ciclo di primo livello |

66| `modelUsage` / `model_usage` | Incluso. Conta le richieste dei subagenti insieme al ciclo di primo livello, suddiviso per modello |97| `modelUsage` / `model_usage` | Incluso. Conta le richieste dei subagenti insieme al ciclo di primo livello, suddiviso per modello |

67 98

~~68Gli esempi seguenti iterano sul flusso di messaggi da una chiamata `query()` e stampano il costo totale quando arriva il messaggio `result`:~~99In [modalità di input a messaggio singolo](/docs/it/agent-sdk/streaming-vs-single-mode#single-message-input), quando i subagenti in background sono ancora in esecuzione alla fine del turno finale, Claude Code li attende, fino al limite descritto in [background tasks at exit](/docs/it/headless#background-tasks-at-exit), prima di emettere il risultato. Il `total_cost_usd`, `duration_api_ms` e `modelUsage` del risultato, o `model_usage` in Python, includono il lavoro svolto durante l'attesa.

100

101I seguenti esempi iterano sul flusso di messaggi da una chiamata `query()` e stampano il costo totale quando arriva il messaggio `result`:

69 102

70<CodeGroup>103<CodeGroup>

71 ```typescript TypeScript theme={null}104 ```typescript TypeScript theme={null}

98 print(f"Total cost: ${message.total_cost_usd or 0}")131 print(f"Total cost: ${message.total_cost_usd or 0}")

99 except Exception as error:132 except Exception as error:

100 # A single-shot query() raises after yielding an error result. If the133 # A single-shot query() raises after yielding an error result. If the

101 # failure was an error result, it still carried total_cost_usd and the134 # failure was an error result, the branch above has already run;

102 # branch above has already run; connection or process failures yield135 # connection or process failures yield no result message.

103 # no result message.

104 print(f"Session ended with an error: {error}")136 print(f"Session ended with an error: {error}")

105 137

106 138

108 ```140 ```

109</CodeGroup>141</CodeGroup>

110 142

143Per limitare quanto i subagenti possono aggiungere a `total_cost_usd`, impostate i [limiti di profondità, concorrenza e spesa](/docs/it/agent-sdk/subagents#cap-subagent-depth-concurrency-and-spend) sulla query.

144

111<h2 id="track-per-step-and-per-model-usage">145<h2 id="track-per-step-and-per-model-usage">

112 Tracciare l'utilizzo per step e per modello146 Tracciare l'utilizzo per step e per modello

113</h2>147</h2>

114 148

115Gli esempi in questa sezione utilizzano nomi di campi TypeScript. In Python, i campi equivalenti sono [`AssistantMessage.usage`](/it/agent-sdk/python#assistantmessage) e `AssistantMessage.message_id` per l'utilizzo per step, e [`ResultMessage.model_usage`](/it/agent-sdk/python#resultmessage) per le scomposizioni per modello.149Gli esempi in questa sezione utilizzano nomi di campi TypeScript. In Python, i campi equivalenti sono [`AssistantMessage.usage`](/docs/it/agent-sdk/python#assistantmessage) e `AssistantMessage.message_id` per l'utilizzo per step, e [`ResultMessage.model_usage`](/docs/it/agent-sdk/python#resultmessage) per i dettagli per modello.

116 150

117<h3 id="track-per-step-usage">151<h3 id="track-per-step-usage">

118 Tracciare l'utilizzo per step152 Tracciare l'utilizzo per step

119</h3>153</h3>

120 154

121Ogni messaggio dell'assistente contiene un `BetaMessage` annidato (accessibile tramite `message.message`) con un `id` e un oggetto `usage` con conteggi di token. Quando Claude utilizza strumenti in parallelo, più messaggi condividono lo stesso `id` con dati di utilizzo identici. Traccia quali ID hai già contato e salta i duplicati per evitare totali gonfiati.155Ogni messaggio dell'assistente contiene un `BetaMessage` annidato (accessibile tramite `message.message`) con un `id` e un oggetto `usage` con i conteggi dei token. Quando Claude utilizza gli strumenti in parallelo, più messaggi condividono lo stesso `id` con dati di utilizzo identici. Tenere traccia degli ID che hai già contato e saltare i duplicati per evitare totali gonfiati.

122 156

123<Warning>157<Warning>

124 Le chiamate di strumenti paralleli producono più messaggi dell'assistente il cui `BetaMessage` annidato condivide lo stesso `id` e utilizzo identico. Deduplicare sempre per ID per ottenere conteggi di token per step accurati.158 I valori per step deduplicati sono accurati per i token di input e cache. L'`output_tokens` per step è un placeholder, quindi [leggi i token di output dal messaggio di risultato](#read-output-tokens-from-the-result-message).

125</Warning>159</Warning>

126 160

127L'esempio seguente accumula token di input e output su tutti gli step, contando ogni ID di messaggio univoco una sola volta:161L'esempio seguente accumula i token di input in tutti gli step, contando ogni ID di messaggio del loop principale univoco una sola volta e saltando i messaggi dei subagent, e legge il totale di output dal messaggio di risultato, che copre il loop principale:

128 162

129```typescript theme={null}163```typescript theme={null}

130import { query } from "@anthropic-ai/claude-agent-sdk";164import { query } from "@anthropic-ai/claude-agent-sdk";

131 165

132const seenIds = new Set<string>();166const seenIds = new Set<string>();

133let totalInputTokens = 0;167let totalInputTokens = 0;

134let totalOutputTokens = 0;168let resultOutputTokens = 0;

135 169

136try {170try {

137 for await (const message of query({ prompt: "Summarize this project" })) {171 for await (const message of query({ prompt: "Summarize this project" })) {

138 if (message.type === "assistant") {172 if (message.type === "assistant" && !message.parent_tool_use_id) {

139 const msgId = message.message.id;173 const msgId = message.message.id;

140 174

141 // Parallel tool calls share the same ID, only count once175 // Parallel tool calls share the same ID, only count once

142 if (!seenIds.has(msgId)) {176 if (!seenIds.has(msgId)) {

143 seenIds.add(msgId);177 seenIds.add(msgId);

144 totalInputTokens += message.message.usage.input_tokens;178 totalInputTokens += message.message.usage.input_tokens;

145 totalOutputTokens += message.message.usage.output_tokens;

146 }179 }

147 }180 }

181 if (message.type === "result") {

182 // Per-step output_tokens is a placeholder; the result message

183 // carries the accumulated output total.

184 resultOutputTokens = message.usage.output_tokens;

185 }

148 }186 }

149} catch (error) {187} catch (error) {

150 // A single-shot query() throws after yielding an error result, so the188 // A single-shot query() throws after yielding an error result, so the

151 // totals below still reflect the steps that ran before the failure.189 // input total below still reflects the steps that ran before the failure.

152 console.error(`Session ended with an error: ${error}`);190 console.error(`Session ended with an error: ${error}`);

153}191}

154 192

155console.log(`Steps: ${seenIds.size}`);193console.log(`Steps: ${seenIds.size}`);

156console.log(`Input tokens: ${totalInputTokens}`);194console.log(`Input tokens: ${totalInputTokens}`);

157console.log(`Output tokens: ${totalOutputTokens}`);195console.log(`Output tokens: ${resultOutputTokens}`);

158```196```

159 197

160<h3 id="break-down-usage-per-model">198<h3 id="break-down-usage-per-model">

161 Scomporre l'utilizzo per modello199 Dettagliare l'utilizzo per modello

162</h3>200</h3>

163 201

164Il messaggio risultato include [`modelUsage`](/it/agent-sdk/typescript#modelusage), una mappa del nome del modello ai conteggi di token e costi per modello. Questo è utile quando esegui più modelli (ad esempio, Haiku per subagenti e Opus per l'agente principale) e vuoi vedere dove vanno i token.202Il messaggio di risultato include [`modelUsage`](/docs/it/agent-sdk/typescript#modelusage), una mappa del nome del modello ai conteggi dei token per modello e al costo. Questo è utile quando esegui più modelli (ad esempio, Haiku per i subagent e Opus per l'agente principale) e desideri vedere dove vanno i token.

165 203

166L'esempio seguente esegue una query e stampa il costo e la scomposizione dei token per ogni modello utilizzato:204Il `costBasis` di ogni voce indica quale tabella dei prezzi ha determinato il prezzo della richiesta più recente di quel modello: `list` per il prezzo di listino, `managed` per una tabella [`modelPricing`](/docs/it/settings-reference#modelpricing), o `unknown` quando nessuno dei due corrisponde all'ID del modello. Il campo richiede Claude Code v2.1.246 o successivo.

205

206L'esempio seguente esegue una query e stampa il costo e il dettaglio dei token per ogni modello utilizzato:

167 207

168```typescript theme={null}208```typescript theme={null}

169import { query } from "@anthropic-ai/claude-agent-sdk";209import { query } from "@anthropic-ai/claude-agent-sdk";

189```229```

190 230

191<h2 id="accumulate-costs-across-multiple-calls">231<h2 id="accumulate-costs-across-multiple-calls">

192 Accumulare costi su più chiamate232 Accumulare i costi su più chiamate

193</h2>233</h2>

194 234

195Ogni chiamata `query()` restituisce il suo `total_cost_usd`. L'SDK non fornisce un totale a livello di sessione, quindi se la tua applicazione effettua più chiamate `query()` (ad esempio, in una sessione multi-turno o tra diversi utenti), accumula i totali tu stesso.235Ogni chiamata `query()` restituisce il suo `total_cost_usd`. L'SDK non fornisce un totale a livello di sessione, quindi se la vostra applicazione effettua più chiamate `query()`, ad esempio in una sessione multi-turno o tra diversi utenti, accumulate i totali voi stessi. In modalità input streaming, leggete il totale di ogni chiamata come descritto in [Track costs in streaming input mode](#track-costs-in-streaming-input-mode). Per una chiamata che si è conclusa con un crash, vedere [Recover totals after a session crash](#recover-totals-after-a-session-crash).

196 236

197Gli esempi seguenti eseguono due chiamate `query()` in sequenza, aggiungono il `total_cost_usd` di ogni chiamata a un totale in esecuzione e stampano sia il costo per chiamata che quello combinato:237I seguenti esempi eseguono due chiamate `query()` in sequenza, aggiungono il `total_cost_usd` di ogni chiamata a un totale progressivo e stampano sia il costo per singola chiamata che il costo combinato:

198 238

199<CodeGroup>239<CodeGroup>

200 ```typescript TypeScript theme={null}240 ```typescript TypeScript theme={null}

263 ```303 ```

264</CodeGroup>304</CodeGroup>

265 305

266<h2 id="handle-errors-caching-and-token-discrepancies">306<h2 id="handle-errors-caching-and-output-token-counts">

267 Gestire errori, caching e discrepanze di token307 Gestire errori, caching e conteggi dei token di output

268</h2>308</h2>

269 309

270Per un tracciamento accurato dei costi, tieni conto di conversazioni non riuscite, prezzi dei token in cache e occasionali incoerenze di segnalazione.310Per un tracciamento accurato dei costi, tenere conto del conteggio di output segnaposto sui messaggi dell'assistente, dei token che una conversazione non riuscita ha consumato e dei prezzi dei token della cache.

271 311

272<h3 id="resolve-output-token-discrepancies">312<h3 id="read-output-tokens-from-the-result-message">

273 Risolvere discrepanze di token di output313 Leggere i token di output dal messaggio di risultato

274</h3>314</h3>

275 315

276In rari casi, potresti osservare valori `output_tokens` diversi per messaggi con lo stesso ID. Quando ciò accade:316Claude Code costruisce ogni messaggio dell'assistente dall'utilizzo che l'API ha segnalato quando la risposta è iniziata, quindi il `output_tokens` del messaggio è solo il conteggio che l'API aveva segnalato a `message_start`, prima che la risposta fosse generata. Una risposta API può produrre diversi messaggi dell'assistente, e ognuno di essi porta lo stesso segnaposto.

317

318L'API segnala il conteggio di output reale alla fine della risposta, e Claude Code lo aggiunge al messaggio di risultato. Leggere i token di output dal `usage` del risultato, o da `modelUsage` per una suddivisione per modello.

277 319

2781. **Utilizza il valore più alto:** il messaggio finale in un gruppo contiene in genere il totale accurato.320Per osservare il conteggio di output di una risposta crescere mentre viene trasmesso in streaming, impostare `includePartialMessages`, o `include_partial_messages` in Python, e leggere `usage` da ogni evento di flusso `message_delta`, tipizzato come [`SDKPartialAssistantMessage`](/docs/it/agent-sdk/typescript#sdkpartialassistantmessage) in TypeScript e [`StreamEvent`](/docs/it/agent-sdk/python#streamevent) in Python.

2792. **Preferisci il messaggio risultato:** il `total_cost_usd` nel messaggio risultato riflette la stima accumulata dell'SDK su tutti gli step, quindi è più affidabile che sommare i valori per step tu stesso. È comunque una stima e può differire dalla tua fattura effettiva.

2803. **Segnala incoerenze:** archivia i problemi nel [repository GitHub Claude Code](https://github.com/anthropics/claude-code/issues).

281 321

282<h3 id="track-costs-on-failed-conversations">322<h3 id="track-costs-on-failed-conversations">

283 Tracciare i costi su conversazioni non riuscite323 Tracciare i costi su conversazioni non riuscite

284</h3>324</h3>

285 325

286Sia i messaggi risultato di successo che di errore includono `usage` e `total_cost_usd`. Se una conversazione fallisce a metà, hai comunque consumato token fino al punto di errore. Leggi sempre i dati di costo dal messaggio risultato indipendentemente dal suo `subtype`.326Sia i messaggi di risultato di successo che di errore includono `usage` e `total_cost_usd`; in Python entrambi i campi sono tipizzati come opzionali, quindi verificare che non siano `None` prima di leggerli.

327

328Se una conversazione non riesce a metà strada, hai comunque consumato token fino al punto del fallimento. Leggere i dati di costo da ogni messaggio di risultato, indipendentemente dal fatto che il suo `subtype` sia `success` o uno dei sottotipi di errore. Su alcuni risultati di errore, `usage` segnala meno di quanto la chiamata ha speso:

329

330* **`error_during_execution` dopo un [arresto anomalo della sessione](#recover-totals-after-a-session-crash)**: ogni campo di costo può essere azzerato.

331* **`error_max_budget_usd`**: `usage` omette la risposta che ha superato il budget, mentre `total_cost_usd` e `modelUsage` la includono.

332

333Dove hai la scelta, contabilizzare da `total_cost_usd` o `modelUsage` piuttosto che da `usage`.

334

335<h3 id="recover-totals-after-a-session-crash">

336 Recuperare i totali dopo un arresto anomalo della sessione

337</h3>

338

339Quando il processo Claude Code si arresta in modo anomalo, emette un risultato `error_during_execution` finale e esce, sia in modalità input single-shot che in streaming. Quel risultato può portare `usage`, `total_cost_usd` e `modelUsage` azzerati, quindi recuperare i totali della chiamata da ciò che è arrivato prima. Il passaggio 1 recupera i totali completi ogni volta che esiste un risultato precedente; il fallback nel passaggio 2 recupera solo i token di input e cache del ciclo principale.

340

3411. Utilizzare il risultato del turno prima dell'arresto anomalo. In modalità input streaming, contiene il totale in esecuzione dall'inizio della chiamata o dall'ultimo [`/clear`](#track-costs-in-streaming-input-mode). Passare al passaggio 2 invece quando quel risultato non può aiutarti:

342 * La chiamata era single-shot, quindi non esiste alcun risultato precedente.

343 * L'arresto anomalo è avvenuto al primo turno.

344 * Il turno prima dell'arresto anomalo era il `/clear` stesso, quindi il suo risultato copre solo il ripristino.

3452. Sommare invece il `usage` sui messaggi dell'assistente, contando ogni risposta API una volta, come fa l'esempio [Track per-step usage](#track-per-step-usage). In modalità single-shot, sommare tutti; in modalità input streaming, sommare quelli arrivati dopo l'ultimo risultato. Questo ti dà i token di input e cache del ciclo principale. L'utilizzo dei subagent non è recuperabile in questo modo, e nemmeno i token di output o il costo in USD, perché [il `output_tokens` per passaggio è un segnaposto](#read-output-tokens-from-the-result-message).

287 346

288<h3 id="track-cache-tokens">347<h3 id="track-cache-tokens">

289 Tracciare i token in cache348 Tracciare i token della cache

290</h3>349</h3>

291 350

292Agent SDK utilizza automaticamente la [memorizzazione nella cache dei prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) per ridurre i costi su contenuti ripetuti. Non è necessario configurare il caching tu stesso. L'oggetto di utilizzo include due campi aggiuntivi per il tracciamento della cache:351L'Agent SDK utilizza automaticamente [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) per ridurre i costi su contenuti ripetuti. Non è necessario configurare il caching da soli. L'oggetto usage include due campi aggiuntivi per il tracciamento della cache:

293 352

294* `cache_creation_input_tokens`: token utilizzati per creare nuove voci di cache (addebitati a una tariffa più alta rispetto ai token di input standard).353* `cache_creation_input_tokens`: token utilizzati per creare nuove voci della cache (addebitati a una tariffa più alta rispetto ai token di input standard).

295* `cache_read_input_tokens`: token letti da voci di cache esistenti (addebitati a una tariffa ridotta).354* `cache_read_input_tokens`: token letti da voci della cache esistenti (addebitati a una tariffa ridotta).

296 355

297Traccia questi separatamente da `input_tokens` per comprendere i risparmi di caching. In TypeScript, questi campi sono tipizzati sull'oggetto [`Usage`](/it/agent-sdk/typescript#usage). In Python, appaiono come chiavi nel dizionario [`ResultMessage.usage`](/it/agent-sdk/python#resultmessage) (ad esempio, `message.usage.get("cache_read_input_tokens", 0)`).356Tracciare questi separatamente da `input_tokens` per comprendere i risparmi della cache. In TypeScript, questi campi sono tipizzati sull'oggetto [`Usage`](/docs/it/agent-sdk/typescript#usage). In Python, appaiono come chiavi nel dizionario [`ResultMessage.usage`](/docs/it/agent-sdk/python#resultmessage) (ad esempio, `message.usage.get("cache_read_input_tokens", 0)`).

298 357

299<h3 id="extend-the-prompt-cache-ttl-to-one-hour">358<h3 id="extend-the-prompt-cache-ttl-to-one-hour">

300 Estendere il TTL della cache dei prompt a un'ora359 Estendere il TTL della cache del prompt a un'ora

301</h3>360</h3>

302 361

303Le voci di cache scritte dall'SDK utilizzano un TTL di 5 minuti per impostazione predefinita quando ti autentichi con una chiave API o esegui su Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry. Se il tuo carico di lavoro esegue molte sessioni brevi rispetto allo stesso prompt di sistema e contesto con gap più lunghi di 5 minuti tra loro, la cache scade tra le sessioni e ogni nuova sessione paga il prezzo di input completo.362I tuoi turni rientrano nel [bucket TTL della conversazione principale](/docs/it/prompt-caching#which-ttl-each-request-gets), insieme ai helper che Claude Code esegue inline con essi. Le richieste che Claude Code effettua al di fuori di quella conversazione, come i [subagent](/docs/it/agent-sdk/subagents), hanno un [controllo TTL separato](/docs/it/prompt-caching#choose-the-ttl-yourself).

363

364Le voci della cache per i tuoi turni utilizzano un TTL di 5 minuti per impostazione predefinita quando ti autentichi con una chiave API o esegui su Amazon Bedrock, Agent Platform di Google Cloud, Microsoft Foundry, o [Claude Platform on AWS](/docs/it/claude-platform-on-aws). Se il tuo carico di lavoro esegue molte sessioni brevi rispetto allo stesso prompt di sistema e contesto con gap più lunghi di 5 minuti tra di essi, la cache scade tra le sessioni e ogni nuova sessione paga il prezzo di input completo.

304 365

305Per richiedere un TTL di 1 ora sulle scritture della cache, imposta la variabile di ambiente [`ENABLE_PROMPT_CACHING_1H`](/it/env-vars). Puoi esportarla nel tuo ambiente shell o container, oppure passarla tramite `options.env`.366Per richiedere un TTL di 1 ora sulle scritture della cache, impostare la variabile di ambiente [`ENABLE_PROMPT_CACHING_1H`](/docs/it/env-vars). Puoi esportarla nel tuo ambiente shell o container, o passarla attraverso `options.env`.

306 367

307L'esempio seguente abilita il TTL di 1 ora per un agente in esecuzione su Amazon Bedrock:368L'esempio seguente abilita il TTL di 1 ora per un agente in esecuzione su Amazon Bedrock. Poiché imposta `CLAUDE_CODE_USE_BEDROCK`, richiede credenziali AWS funzionanti per [Amazon Bedrock](/docs/it/amazon-bedrock); senza di esse la query non riesce.

308 369

309<CodeGroup>370<CodeGroup>

310 ```python Python theme={null}371 ```python Python theme={null}

344 ```405 ```

345</CodeGroup>406</CodeGroup>

346 407

347Le scritture della cache con un TTL di 1 ora sono fatturate a una tariffa più alta rispetto alle scritture di 5 minuti, quindi abilitare questa opzione scambia un costo di scrittura più elevato per più letture della cache. Consulta i [prezzi della memorizzazione nella cache dei prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) per i dettagli. Gli utenti con abbonamento Claude ricevono già automaticamente il TTL di 1 ora e non hanno bisogno di impostare questa variabile.408Le scritture della cache con un TTL di 1 ora sono fatturate a una tariffa più alta rispetto alle scritture di 5 minuti, quindi abilitare questo scambia un costo di scrittura più elevato per più letture della cache. Vedi [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) per i dettagli. Su un abbonamento Claude all'interno dell'utilizzo incluso nel tuo piano, ottieni il TTL di 1 ora sui tuoi turni, e su alcune delle richieste helper che Claude Code effettua accanto a essi, senza impostare questa variabile, e Claude Code riduce quei turni al TTL di 5 minuti una volta che stai attingendo ai [crediti di utilizzo](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans).

409

410`ENABLE_PROMPT_CACHING_1H` richiede il TTL di 1 ora su ogni richiesta in entrambi i bucket. Per scegliere un TTL per ogni bucket separatamente, utilizza invece questi controlli. Ognuno accetta `5m` o `1h` e ha la precedenza su `ENABLE_PROMPT_CACHING_1H`:

411

412* Conversazione principale: la variabile di ambiente [`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/it/env-vars), o l'impostazione [`promptCacheTtl`](/docs/it/settings-reference#promptcachettl)

413* Tutto il resto: la variabile di ambiente `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, o l'impostazione [`subagentPromptCacheTtl`](/docs/it/settings-reference#subagentpromptcachettl)

414

415Impostare `promptCacheTtl` a `1h` mantiene la cache di 1 ora sulla conversazione principale mentre stai attingendo ai crediti di utilizzo. Per l'ordine di precedenza completo, vedi [choose the TTL yourself](/docs/it/prompt-caching#choose-the-ttl-yourself).

348 416

349<h2 id="related-documentation">417<h2 id="related-documentation">

350 Documentazione correlata418 Documentazione correlata

351</h2>419</h2>

352 420

353* [Riferimento TypeScript SDK](/it/agent-sdk/typescript) - Documentazione API completa421* [Riferimento TypeScript SDK](/docs/it/agent-sdk/typescript) - Documentazione API completa

354* [Panoramica SDK](/it/agent-sdk/overview) - Introduzione all'SDK422* [Panoramica SDK](/docs/it/agent-sdk/overview) - Introduzione all'SDK

355* [Autorizzazioni SDK](/it/agent-sdk/permissions) - Gestione delle autorizzazioni degli strumenti423* [Autorizzazioni SDK](/docs/it/agent-sdk/permissions) - Gestione delle autorizzazioni degli strumenti

agent-sdk/custom-tools.md +2 −2

Details

338L'opzione `tools` e gli elenchi consentiti/non consentiti influiscono su due livelli: la disponibilità, che controlla se un tool appare nel contesto di Claude, e il permesso, che controlla se una chiamata viene approvata una volta che Claude la tenta. `tools` e le voci `disallowedTools` con nome semplice modificano la disponibilità. `allowedTools` e le regole `disallowedTools` con ambito modificano il permesso. Se si nomina uno dei [tool di tracciamento delle attività](/docs/it/agent-sdk/todo-tracking#model-availability) in `allowedTools`, Claude Code opta anche la sessione.338L'opzione `tools` e gli elenchi consentiti/non consentiti influiscono su due livelli: la disponibilità, che controlla se un tool appare nel contesto di Claude, e il permesso, che controlla se una chiamata viene approvata una volta che Claude la tenta. `tools` e le voci `disallowedTools` con nome semplice modificano la disponibilità. `allowedTools` e le regole `disallowedTools` con ambito modificano il permesso. Se si nomina uno dei [tool di tracciamento delle attività](/docs/it/agent-sdk/todo-tracking#model-availability) in `allowedTools`, Claude Code opta anche la sessione.

339 339

341| :------------------------ | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |341| :------------------------ | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

342| `tools: ["Read", "Grep"]` | Disponibilità | Solo i tool integrati elencati sono nel contesto di Claude. I tool integrati non elencati vengono rimossi. I tool MCP non sono interessati. |342| `tools: ["Read", "Grep"]` | Disponibilità | Solo i tool integrati elencati sono nel contesto di Claude. I tool integrati non elencati vengono rimossi. I tool MCP non sono interessati. |

344| tool consentiti | Permesso | I tool elencati vengono eseguiti senza un prompt di permesso. Gli altri tool non elencati rimangono disponibili; le chiamate passano attraverso il [flusso di permesso](/docs/it/agent-sdk/permissions). |344| tool consentiti | Permesso | I tool elencati vengono eseguiti senza un prompt di permesso. Gli altri tool non elencati rimangono disponibili; le chiamate passano attraverso il [flusso di permesso](/docs/it/agent-sdk/permissions). |

345| tool non consentiti | Entrambi | Un nome di tool semplice come `"Bash"` rimuove il tool dal contesto di Claude, come se lo ometteste da `tools`. Una regola con ambito come `"Bash(rm *)"` lascia il tool nel contesto e nega solo le chiamate corrispondenti. |345| tool non consentiti | Entrambi | Un nome di tool semplice come `"Bash"` rimuove il tool dal contesto di Claude, come se lo ometteste da `tools`. Una regola con ambito come `"Bash(rm *)"` lascia il tool nel contesto e nega solo le chiamate corrispondenti [come scritto](/docs/it/permissions#bash-rule-limits). |

346 346

347Per rimuovere completamente un tool integrato, omettetelo da `tools` o elencate il suo nome semplice in `disallowedTools` (Python: `disallowed_tools`); entrambi mantengono il tool fuori dal contesto in modo che Claude non lo tenti mai. Una regola `disallowedTools` con ambito blocca le chiamate corrispondenti ma lascia il tool visibile, quindi Claude potrebbe sprecare un turno tentandolo. Vedere [Configurare i permessi](/docs/it/agent-sdk/permissions) per l'ordine di valutazione completo.347Per rimuovere completamente un tool integrato, omettetelo da `tools` o elencate il suo nome semplice in `disallowedTools` (Python: `disallowed_tools`); entrambi mantengono il tool fuori dal contesto in modo che Claude non lo tenti mai. Una regola `disallowedTools` con ambito blocca le chiamate corrispondenti ma lascia il tool visibile, quindi Claude potrebbe sprecare un turno tentandolo. Vedere [Configurare i permessi](/docs/it/agent-sdk/permissions) per l'ordine di valutazione completo.

348 348

agent-sdk/examples.md +33 −0 created

Details

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.

5# Esempi

7> Trova un progetto Agent SDK completo e eseguibile o una ricetta guidata nel Claude Cookbook che corrisponda a ciò che desideri costruire.

9Questa pagina ti indirizza verso progetti Agent SDK completi ed eseguibili e ricette guidate del Claude Cookbook. Le applicazioni TypeScript si trovano nel repository [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos), e le ricette Python si trovano nel [Claude Cookbook](https://platform.claude.com/cookbook).

11<h2 id="run-a-minimal-agent-first">

12 Esegui prima un agente minimalista

13</h2>

15Se non hai ancora costruito nulla con l'SDK, inizia con uno di questi prima di un'applicazione completa:

17* [Agent SDK quickstart](/docs/it/agent-sdk/quickstart): costruisci il tuo primo agente funzionante in TypeScript o Python, con i passaggi di configurazione inclusi. L'agente trova e corregge i bug in un file di esempio.

19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world): un progetto TypeScript minimalista da clonare quando desideri iniziare dal codice del repository

21<h2 id="explore-a-typescript-application">

22 Esplora un'applicazione TypeScript

23</h2>

25Le applicazioni TypeScript in [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) sono demo per lo sviluppo locale, da un client di posta elettronica a un sistema di ricerca multi-agente. Clona la demo la cui struttura corrisponde a ciò che stai costruendo.

27<h2 id="work-through-a-python-recipe">

28 Lavora attraverso una ricetta Python

29</h2>

31La serie Agent SDK del Claude Cookbook è una sequenza di ricette, ognuna un notebook Python, che progredisce da un semplice agente di ricerca a sofisticati sistemi multi-agente. Ogni notebook si basa sul precedente, introducendo nuovi concetti e capacità. Inizia con [l'agente di ricerca one-liner](https://platform.claude.com/cookbook/claude-agent-sdk-00-the-one-liner-research-agent) e procedi in avanti.

33Per ricette su prodotti Claude, consulta il [Claude Cookbook](https://platform.claude.com/cookbook) completo.

agent-sdk/mcp.md +3 −1

Details

924 Tool output exceeds maximum allowed tokens924 Tool output exceeds maximum allowed tokens

925</h3>925</h3>

926 926

927L'SDK applica lo stesso limite di output MCP di Claude Code. Quando il risultato di uno strumento è più grande di 25.000 token, l'output completo viene salvato in un file e il risultato dello strumento viene sostituito con un messaggio di errore che nomina il percorso del file, in modo che l'agente possa leggere l'output in porzioni. Aumentare il limite con la variabile di ambiente [`MAX_MCP_OUTPUT_TOKENS`](/docs/it/env-vars). Vedere [MCP output limits and warnings](/docs/it/mcp#mcp-output-limits-and-warnings) per il comportamento completo, incluso il modo in cui un server può dichiarare un limite per strumento più elevato con l'annotazione `anthropic/maxResultSizeChars`.927L'SDK applica lo stesso limite di output MCP di Claude Code. Quando il risultato di uno strumento senza contenuto di immagine è più grande di 25.000 token, Claude Code salva l'output in un file e sostituisce il risultato dello strumento con un messaggio di errore che nomina il percorso del file, in modo che l'agente possa leggere l'output in porzioni.

928

929Aumentare il limite con la variabile di ambiente [`MAX_MCP_OUTPUT_TOKENS`](/docs/it/env-vars). Vedere [MCP output limits and warnings](/docs/it/mcp#mcp-output-limits-and-warnings) per il comportamento completo, incluso il modo in cui un server può dichiarare un limite per strumento più elevato con l'annotazione `anthropic/maxResultSizeChars`.

928 930

929<h2 id="related-resources">931<h2 id="related-resources">

930 Risorse correlate932 Risorse correlate

agent-sdk/modifying-system-prompts.md +12 −2

Details

44 Personalizzare il comportamento dell'agente44 Personalizzare il comportamento dell'agente

45</h2>45</h2>

46 46

47Gli stili di output, `append`, e una stringa di prompt personalizzata modificano direttamente il system prompt. CLAUDE.md segue un percorso diverso: l'SDK lo legge e inietta il suo contenuto nella conversazione come contesto del progetto, non nel system prompt, quindi modella il comportamento insieme a qualsiasi system prompt Lei scelga. [Skills](/docs/it/agent-sdk/skills), [hooks](/docs/it/agent-sdk/hooks), e [permissions](/docs/it/agent-sdk/permissions) modellano anche il comportamento al di fuori del system prompt e sono trattati in pagine separate.47`append` e una stringa di prompt personalizzata modificano direttamente il system prompt, e uno stile di output cambia le istruzioni che Claude Code fornisce a Claude per ogni risposta. CLAUDE.md segue un percorso diverso: l'SDK lo legge e inietta il suo contenuto nella conversazione come contesto del progetto, quindi modella il comportamento insieme a qualsiasi system prompt Lei scelga. [Skills](/docs/it/agent-sdk/skills), [hooks](/docs/it/agent-sdk/hooks), e [permissions](/docs/it/agent-sdk/permissions) modellano anche il comportamento al di fuori del system prompt e sono trattati in pagine separate.

48 48

49<h3 id="claude-md-files-for-project-level-instructions">49<h3 id="claude-md-files-for-project-level-instructions">

50 File CLAUDE.md per istruzioni a livello di progetto50 File CLAUDE.md per istruzioni a livello di progetto

118 Stili di output per configurazioni persistenti118 Stili di output per configurazioni persistenti

119</h3>119</h3>

120 120

121Gli stili di output sono configurazioni salvate che modificano il system prompt di Claude. Vengono archiviati come file markdown e possono essere riutilizzati in sessioni e progetti diversi.121Gli stili di output sono configurazioni salvate che modificano il ruolo, il tono e il formato di output di Claude. Vengono archiviati come file markdown e possono essere riutilizzati in sessioni e progetti diversi.

122 122

123<h4 id="create-an-output-style">123<h4 id="create-an-output-style">

124 Creare uno stile di output124 Creare uno stile di output

387* Se includete il marcatore più di una volta, il primo è la divisione e l'SDK rimuove gli altri.387* Se includete il marcatore più di una volta, il primo è la divisione e l'SDK rimuove gli altri.

388* Se lasciate fuori il marcatore, l'SDK unisce tutte le stringhe in un blocco, lo stesso che passare una stringa.388* Se lasciate fuori il marcatore, l'SDK unisce tutte le stringhe in un blocco, lo stesso che passare una stringa.

389 389

390<h3 id="change-the-prompt-of-an-existing-session">

391 Cambiare il prompt di una sessione esistente

392</h3>

393

394Per impostazione predefinita, Claude Code costruisce il system prompt una volta, alla prima richiesta di una sessione, con il vostro testo `append` o prompt personalizzato incluso, e lo registra nella sessione. Fino a quando la sessione non viene compattata, ogni richiesta successiva utilizza quel prompt registrato, incluso dopo che tornate alla sessione con `resume` o `continue`. Se passate un `append` o prompt personalizzato diverso su quella chiamata successiva, ha effetto una volta che la sessione viene compattata o in una nuova sessione.

395

396Se avviate Claude Code in [bare mode](/docs/it/headless#start-faster-with-bare-mode) passando `--bare` tramite `extraArgs` o impostando `CLAUDE_CODE_SIMPLE=1`, la registrazione rimane disattivata a meno che non impostiate `snapshot: true` sulla forma dell'oggetto di `systemPrompt`. La registrazione di un `append` o prompt personalizzato per impostazione predefinita richiede Claude Code v2.1.265 o successivo, che l'Agent SDK TypeScript raggruppa dalla v0.3.265. Prima di Claude Code v2.1.268, le sessioni che non [recuperano i flag delle funzionalità](/docs/it/env-vars#features-that-need-feature-flag-fetching), incluse le sessioni su Amazon Bedrock, Google Cloud's Agent Platform, e Microsoft Foundry, ricostruivano il prompt su ogni richiesta e `snapshot` non aveva effetto.

397

398Per ricostruire il prompt su ogni richiesta invece, impostate `snapshot: false` sulla forma dell'oggetto di `systemPrompt` nell'SDK TypeScript: `{ type: "preset", preset: "claude_code", append, snapshot: false }` o `{ type: "custom", prompt, snapshot: false }`. Usate questa forma mentre iterate sulla formulazione del prompt, o quando la vostra applicazione cambia `append` tra le chiamate che riprendono la stessa sessione. Il campo `snapshot` richiede `@anthropic-ai/claude-agent-sdk` v0.3.257 o successivo.

399

390<h2 id="compare-the-four-approaches">400<h2 id="compare-the-four-approaches">

391 Confronto dei quattro approcci401 Confronto dei quattro approcci

392</h2>402</h2>

agent-sdk/permissions.md +14 −12

Details

41 </Step>41 </Step>

42 42

43 <Step title="Regole di consentimento">43 <Step title="Regole di consentimento">

44 Controlla le regole `allow` (da `allowed_tools` e settings.json). Se una regola corrisponde, lo strumento viene approvato. Le rimozioni `rm` e `rmdir` che prendono di mira un [percorso critico](/docs/it/permission-modes#critical-paths) non vengono mai approvate da una regola di consentimento: raggiungono il tuo callback nelle modalità che richiedono conferma, vanno al [classificatore](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) in modalità `auto` su Claude Code v2.1.218 o successivo, e vengono negate in modalità `dontAsk`.44 Controlla le regole `allow` (da `allowed_tools` e settings.json). Se una regola corrisponde, lo strumento viene approvato. Una chiamata che lo strumento approva da solo viene risolta in questo passaggio anche, senza alcuna regola necessaria: ad esempio una lettura di file all'interno delle tue directory di lavoro o un [comando Bash di sola lettura](/docs/it/permissions#read-only-commands). Le rimozioni `rm` e `rmdir` che prendono di mira un [percorso critico](/docs/it/permission-modes#critical-paths) non vengono mai approvate da una regola di consentimento: raggiungono il tuo callback nelle modalità che richiedono conferma, vanno al [classificatore](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) in modalità `auto` su Claude Code v2.1.218 o successivo, e vengono negate in modalità `dontAsk`.

45 </Step>45 </Step>

46 46

47 <Step title="Callback canUseTool">47 <Step title="Callback canUseTool">

73 Regole di consentimento e negazione73 Regole di consentimento e negazione

74</h2>74</h2>

75 75

76`allowed_tools` e `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) aggiungono voci agli elenchi di regole di consentimento e negazione nel flusso di valutazione sopra. Se nominate uno dei [task-tracking tools](/docs/it/agent-sdk/todo-tracking#model-availability) in `allowed_tools`, Claude Code opta anche la sessione. Qualsiasi altro strumento non elencato in `allowed_tools` è ancora disponibile per Claude e passa alla modalità di permesso. Le regole di negazione si comportano diversamente a seconda che denominino uno strumento o limitino un modello all'interno di uno.76`allowed_tools` e `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) aggiungono voci agli elenchi di regole di consentimento e negazione nel flusso di valutazione sopra. Se nominate uno dei [task-tracking tools](/docs/it/agent-sdk/todo-tracking#model-availability) in `allowed_tools`, Claude Code opta anche la sessione. Qualsiasi altro strumento non elencato in `allowed_tools` è ancora disponibile per Claude e una chiamata ad esso che necessita approvazione passa alla modalità di permesso. Le regole di negazione si comportano diversamente a seconda che denominino uno strumento o limitino un modello all'interno di uno.

77 77

78| Opzione | Effetto |78| Opzione | Effetto |

79| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |79| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

80| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` vengono approvati automaticamente. Gli strumenti non elencati qui esistono ancora e passano alla modalità di permesso e `canUseTool`. |80| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` vengono approvati automaticamente. Gli altri strumenti non elencati qui esistono ancora e le chiamate ad essi che necessitano approvazione passano alla modalità di permesso e `canUseTool`. |

81| `disallowed_tools=["Bash"]` | La definizione dello strumento `Bash` viene rimossa dalla richiesta. Claude non vede lo strumento e non può tentarlo. |81| `disallowed_tools=["Bash"]` | La definizione dello strumento `Bash` viene rimossa dalla richiesta. Claude non vede lo strumento e non può tentarlo. |

82| `disallowed_tools=["Bash(rm *)"]` | `Bash` rimane disponibile. Le chiamate corrispondenti a `rm *` vengono negate in ogni modalità di permesso, inclusa `bypassPermissions`. Altre chiamate `Bash` passano alla modalità di permesso. |82| `disallowed_tools=["Bash(rm *)"]` | `Bash` rimane disponibile. Le chiamate corrispondenti a `rm *` [come scritto](/docs/it/permissions#bash-rule-limits) vengono negate in ogni modalità di permesso, inclusa `bypassPermissions`. Altre chiamate `Bash`, incluso `/bin/rm`, passano alla modalità di permesso. |

83| `disallowed_tools=["*"]` | Ogni definizione di strumento viene rimossa dalla richiesta. I glob dei nomi degli strumenti sono supportati nelle regole di negazione: `"*"` corrisponde a ogni strumento e `"mcp__*"` corrisponde a ogni strumento MCP su tutti i server. |83| `disallowed_tools=["*"]` | Ogni definizione di strumento viene rimossa dalla richiesta. I glob dei nomi degli strumenti sono supportati nelle regole di negazione: `"*"` corrisponde a ogni strumento e `"mcp__*"` corrisponde a ogni strumento MCP su tutti i server. |

84 84

85Le regole di consentimento accettano glob dei nomi degli strumenti solo dopo un prefisso letterale `mcp__<server>__`. Il segmento del server deve essere privo di glob in modo che la regola nomini un server specifico che hai configurato: `mcp__puppeteer__*` corrisponde a ogni strumento dal server `puppeteer` e `mcp__github__get_*` corrisponde ai suoi strumenti `get_`. Una voce non ancorata come `allowed_tools=["*"]` o `allowed_tools=["mcp__*"]` viene ignorata con un avviso di avvio e non approva automaticamente nulla.85Le regole di consentimento accettano glob dei nomi degli strumenti solo dopo un prefisso letterale `mcp__<server>__`. Il segmento del server deve essere privo di glob in modo che la regola nomini un server specifico che hai configurato: `mcp__puppeteer__*` corrisponde a ogni strumento dal server `puppeteer` e `mcp__github__get_*` corrisponde ai suoi strumenti `get_`. Una voce non ancorata come `allowed_tools=["*"]` o `allowed_tools=["mcp__*"]` viene ignorata con un avviso di avvio e non approva automaticamente nulla.

91<Warning>91<Warning>

92 **Gli strumenti approvati automaticamente non raggiungono mai `canUseTool`.** Una chiamata a uno strumento approvata in qualsiasi fase precedente, da `acceptEdits` o `bypassPermissions`, o da una regola di consentimento, salta il tuo callback `canUseTool`, quindi i controlli di permesso che inserisci lì vengono silenziosamente ignorati per quello strumento. `AskUserQuestion`, gli strumenti MCP contrassegnati [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool), gli strumenti connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), e le rimozioni `rm` e `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths) raggiungono comunque il callback, anche quando una regola di consentimento corrisponde. In modalità `auto`, le rimozioni di percorsi critici vanno al [classificatore](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) invece del callback, mentre le altre chiamate elencate qui lo raggiungono ancora; il routing del classificatore richiede Claude Code v2.1.218 o successivo. In modalità `dontAsk` queste chiamate vengono invece negate, senza invocare il callback.92 **Gli strumenti approvati automaticamente non raggiungono mai `canUseTool`.** Una chiamata a uno strumento approvata in qualsiasi fase precedente, da `acceptEdits` o `bypassPermissions`, o da una regola di consentimento, salta il tuo callback `canUseTool`, quindi i controlli di permesso che inserisci lì vengono silenziosamente ignorati per quello strumento. `AskUserQuestion`, gli strumenti MCP contrassegnati [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool), gli strumenti connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), e le rimozioni `rm` e `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths) raggiungono comunque il callback, anche quando una regola di consentimento corrisponde. In modalità `auto`, le rimozioni di percorsi critici vanno al [classificatore](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) invece del callback, mentre le altre chiamate elencate qui lo raggiungono ancora; il routing del classificatore richiede Claude Code v2.1.218 o successivo. In modalità `dontAsk` queste chiamate vengono invece negate, senza invocare il callback.

93 93

94 La copertura dipende dalla forma della voce: un nome semplice come `Read` o `mcp__github__get_issue` approva automaticamente ogni chiamata a quello strumento a parte le eccezioni sopra, mentre una regola limitata come `Bash(ls *)` approva automaticamente solo le chiamate corrispondenti e altre chiamate `Bash` passano comunque al callback. Per i controlli che devono essere eseguiti su ogni chiamata a uno strumento, utilizza un hook [`PreToolUse`](/docs/it/agent-sdk/hooks): gli hook vengono eseguiti prima di ogni altro passaggio e un hook di negazione si applica anche in modalità `bypassPermissions`.94 La copertura dipende dalla forma della voce: un nome semplice come `Read` o `mcp__github__get_issue` approva automaticamente ogni chiamata a quello strumento a parte le eccezioni sopra, mentre una regola limitata come `Bash(npm test *)` approva automaticamente solo le chiamate corrispondenti e altre chiamate `Bash` che necessitano approvazione passano comunque al callback. Per i controlli che devono essere eseguiti su ogni chiamata a uno strumento, utilizza un hook [`PreToolUse`](/docs/it/agent-sdk/hooks): gli hook vengono eseguiti prima di ogni altro passaggio e un hook di negazione si applica anche in modalità `bypassPermissions`.

95</Warning>95</Warning>

96 96

97Per un agente bloccato, abbina `allowedTools` con `permissionMode: "dontAsk"`. Gli strumenti elencati vengono approvati, a parte gli strumenti sempre-prompt nella Avvertenza sopra; tutto il resto viene negato completamente invece di richiedere:97Per un agente bloccato, abbina `allowedTools` con `permissionMode: "dontAsk"`:

98 98

99```typescript theme={null}99```typescript theme={null}

100const options = {100const options = {

103};103};

104```104```

105 105

106Gli strumenti elencati vengono approvati, a parte le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves), e ogni altra chiamata che comporterebbe una richiesta viene invece negata. Le chiamate che non necessitano approvazione in modalità `default` vengono eseguite indipendentemente dal fatto che le elenchi, come i [comandi Bash di sola lettura](/docs/it/permissions#read-only-commands), strumenti come `Agent` che non chiedono prima di eseguire, e letture di file all'interno delle tue directory di lavoro. Per mettere uno strumento completamente fuori dalla portata di Claude, aggiungi il suo nome semplice a `disallowedTools`.

107

106<Warning>108<Warning>

107 **`allowed_tools` non vincola `bypassPermissions`.** `allowed_tools` pre-approva gli strumenti che elenchi. Gli strumenti non elencati non vengono abbinati da alcuna regola di consentimento e passano alla modalità di permesso, dove `bypassPermissions` li approva. Impostare `allowed_tools=["Read"]` insieme a `permission_mode="bypassPermissions"` approva comunque ogni strumento, inclusi `Bash`, `Write` e `Edit`. Se hai bisogno di `bypassPermissions` ma vuoi bloccare strumenti specifici, usa `disallowed_tools`.109 **`allowed_tools` non vincola `bypassPermissions`.** `allowed_tools` pre-approva gli strumenti che elenchi. Gli strumenti non elencati non vengono abbinati da alcuna regola di consentimento e passano alla modalità di permesso, dove `bypassPermissions` li approva. Impostare `allowed_tools=["Read"]` insieme a `permission_mode="bypassPermissions"` approva comunque ogni strumento, inclusi `Bash`, `Write` e `Edit`. Se hai bisogno di `bypassPermissions` ma vuoi bloccare strumenti specifici, usa `disallowed_tools`.

108</Warning>110</Warning>

122L'SDK supporta queste modalità di permesso:124L'SDK supporta queste modalità di permesso:

123 125

125| :------------------ | :------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |127| :------------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

126| `default` | Comportamento di permesso standard | Nessuna approvazione automatica; gli strumenti non abbinati attivano il tuo callback `canUseTool` |128| `default` | Comportamento di permesso standard | Nessuna approvazione automatica basata sulla modalità; le chiamate che necessitano di approvazione e non corrispondono a nessuna regola di consentimento attivano il tuo callback `canUseTool` |

127| `dontAsk` | Nega invece di richiedere | Qualsiasi cosa non pre-approvata da `allowed_tools` o regole viene negata; gli strumenti del connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) e gli strumenti che richiedono l'interazione dell'utente vengono negati anche se li hai pre-approvati, così come le rimozioni `rm` e `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths). `canUseTool` non viene mai chiamato |129| `dontAsk` | Nega invece di richiedere | Qualsiasi chiamata che altrimenti richiederebbe viene negata. Le chiamate approvate da `allowed_tools` o regole vengono eseguite, così come le chiamate che non necessitano di approvazione in modalità `default`; gli strumenti del connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) e gli strumenti che richiedono l'interazione dell'utente vengono negati anche se li hai pre-approvati, così come le rimozioni `rm` e `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths). `canUseTool` non viene mai chiamato |

128| `acceptEdits` | Accetta automaticamente le modifiche ai file | Le modifiche ai file e le [operazioni del filesystem](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, ecc.) vengono approvate automaticamente |130| `acceptEdits` | Accetta automaticamente le modifiche ai file | Le modifiche ai file e le [operazioni del filesystem](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, ecc.) vengono approvate automaticamente |

129| `bypassPermissions` | Ignora i controlli di permesso | Gli strumenti vengono eseguiti senza richieste di permesso, ad eccezione delle [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves). Usare con cautela |131| `bypassPermissions` | Ignora i controlli di permesso | Gli strumenti vengono eseguiti senza richieste di permesso, ad eccezione delle [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves). Usare con cautela |

130| `plan` | Modalità di pianificazione | Claude esplora e pianifica senza modificare i tuoi file sorgente; le modifiche ai file non vengono mai approvate automaticamente e richiedono il tuo callback `canUseTool` |132| `plan` | Modalità di pianificazione | Claude esplora e pianifica senza modificare i tuoi file sorgente; le modifiche ai file non vengono mai approvate automaticamente e richiedono il tuo callback `canUseTool` |

131| `auto` | Approvazioni classificate dal modello | Un classificatore di modello approva o nega le richieste di permesso. Vedi [Auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per la disponibilità |133| `auto` | Approvazioni classificate dal modello | Un classificatore di modello approva o nega le richieste di permesso. Vedi [Auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per la disponibilità |

132 134

133<Warning>135<Warning>

134 **Eredità del subagente:** I subagenti ereditano la modalità di permesso della sessione genitore. Un [`AgentDefinition`'s `permissionMode`](/docs/it/agent-sdk/typescript#agentdefinition) può sovrascriverlo, tranne quando il genitore utilizza `bypassPermissions`, `acceptEdits` o `auto`: quelle modalità si applicano a ogni subagente e non possono essere sovrascritte per subagente. Claude Code ignora anche il `permissionMode: "bypassPermissions"` di una definizione quando la modalità bypass è disabilitata da [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings), in modo che il subagente venga eseguito con la modalità della sessione genitore.136 **Eredità del subagente:** Un subagente viene eseguito nella modalità di permesso della sessione genitore a meno che tu non imposti `permissionMode` sulla sua [`AgentDefinition`](/docs/it/agent-sdk/typescript#agentdefinition) e la sessione genitore sia in modalità `default`, `dontAsk` o `plan`. Anche in questo caso, Claude Code non applica mai un valore `"bypassPermissions"`. Un subagente viene eseguito in modalità `bypassPermissions` solo quando la sessione genitore stessa lo fa. L'eccezione `bypassPermissions` richiede Claude Code v2.1.267 o successivo.

135 137

136 I subagenti possono avere prompt di sistema diversi e comportamento meno vincolato rispetto al tuo agente principale, quindi ereditare `bypassPermissions` concede loro accesso completo e autonomo al sistema. Le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque.138 I subagenti possono avere prompt di sistema diversi e comportamento meno vincolato rispetto al tuo agente principale, quindi ereditare `bypassPermissions` concede loro accesso completo e autonomo al sistema. Le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque.

137</Warning>139</Warning>

271 Modalità non chiedere (`dontAsk`)273 Modalità non chiedere (`dontAsk`)

272</h4>274</h4>

273 275

274Converte qualsiasi richiesta di permesso in una negazione. Gli strumenti pre-approvati da `allowed_tools`, regole di consentimento di `settings.json` o un hook vengono eseguiti normalmente. Gli strumenti del connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), gli strumenti che richiedono l'interazione dell'utente e le rimozioni `rm` e `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths) vengono negati anche quando una regola di consentimento corrisponde. Un'autorizzazione di hook `PreToolUse` non cancella nemmeno una rimozione di percorso critico. Tutto il resto viene negato senza chiamare `canUseTool`.276Converte qualsiasi richiesta di permesso in una negazione, senza chiamare `canUseTool`. Gli strumenti pre-approvati da `allowed_tools`, regole di consentimento di `settings.json` o un hook vengono eseguiti normalmente, così come le chiamate che non necessitano di approvazione in modalità `default`, come le letture di file all'interno delle tue directory di lavoro e le chiamate a `Agent`. Gli strumenti del connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), gli strumenti che richiedono l'interazione dell'utente e le rimozioni `rm` e `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths) vengono negati anche quando una regola di consentimento corrisponde. Un'autorizzazione di hook `PreToolUse` non cancella nemmeno una rimozione di percorso critico.

275 277

276**Usare quando:** desideri una superficie di strumenti fissa ed esplicita per un agente headless e preferisci una negazione definitiva rispetto a un affidamento silenzioso su `canUseTool` assente.278**Usare quando:** desideri una superficie di strumenti fissa ed esplicita per un agente headless e preferisci una negazione definitiva rispetto a un affidamento silenzioso su `canUseTool` assente.

277 279

agent-sdk/python.md +4 −6

Details

906| `session_id` | `str \| None` | `None` | Usa un ID di sessione specifico invece di uno generato automaticamente. Deve essere un UUID valido. Non può essere combinato con `continue_conversation` o `resume` a meno che `fork_session` non sia anche impostato |906| `session_id` | `str \| None` | `None` | Usa un ID di sessione specifico invece di uno generato automaticamente. Deve essere un UUID valido. Non può essere combinato con `continue_conversation` o `resume` a meno che `fork_session` non sia anche impostato |

908| `max_budget_usd` | `float \| None` | `None` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per avvertenze di accuratezza |908| `max_budget_usd` | `float \| None` | `None` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per avvertenze di accuratezza |

909| `disallowed_tools` | `list[str]` | `[]` | Strumenti da negare. Un nome semplice come `"Bash"` rimuove lo strumento dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia lo strumento disponibile e nega le chiamate corrispondenti in ogni modalità di autorizzazione, incluso `bypassPermissions`. Vedi [Autorizzazioni](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |909| `disallowed_tools` | `list[str]` | `[]` | Strumenti da negare. Un nome semplice come `"Bash"` rimuove lo strumento dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia lo strumento disponibile e nega le chiamate corrispondenti in ogni modalità di autorizzazione, incluso `bypassPermissions`, per il comando [come scritto](/docs/it/permissions#bash-rule-limits). Vedi [Autorizzazioni](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |

1181| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |1181| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |

1182| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |1182| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |

1183| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero. Vedi [`EffortLevel`](#effortlevel) |1183| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero. Vedi [`EffortLevel`](#effortlevel) |

1184| `permissionMode` | No | Modalità di autorizzazione per l'esecuzione dello strumento all'interno di questo agente. Vedi [`PermissionMode`](#permissionmode) |1184| `permissionMode` | No | Modalità di autorizzazione per l'esecuzione dello strumento all'interno di questo agente. Le [regole di eredità del subagente](/docs/it/agent-sdk/permissions#available-modes) decidono quando si applica. Vedi [`PermissionMode`](#permissionmode) |

1185 1185

1186<Note>1186<Note>

1187 I nomi dei campi `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa Python snake\_case per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.1187 I nomi dei campi `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa Python snake\_case per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.

2699 "run_in_background": bool | None, # Gli agenti vengono eseguiti in background per impostazione predefinita; impostare su False per eseguire in modo sincrono2699 "run_in_background": bool | None, # Gli agenti vengono eseguiti in background per impostazione predefinita; impostare su False per eseguire in modo sincrono

2700 "name": str | None, # Nome per l'agente generato2700 "name": str | None, # Nome per l'agente generato

2701 "team_name": str | None, # Deprecato; ignorato2701 "team_name": str | None, # Deprecato; ignorato

2703 "isolation": "worktree" | "remote" | None, # Modalità di isolamento per le modifiche dell'agente2703 "isolation": "worktree" | "remote" | None, # Modalità di isolamento per le modifiche dell'agente

2704}2704}

2705```2705```

2884 2884

2885**Nome dello strumento:** `Monitor`2885**Nome dello strumento:** `Monitor`

2886 2886

2887Esegue uno script in background e fornisce ogni evento a Claude in modo che possa reagire senza polling: `command` esegue uno script e emette un evento per riga stdout, e `ws` apre un WebSocket ed emette un evento per frame di testo. Fornire esattamente uno tra `command` o `ws`.2887Esegue una sorgente in background e fornisce ogni evento a Claude in modo che possa reagire senza polling: `command` esegue uno script e emette un evento per riga stdout, e `ws` apre un WebSocket ed emette un evento per frame di testo. Fornire esattamente uno tra `command` o `ws`.

2888 2888

2889Quando Monitor esegue un comando, segue le stesse regole di autorizzazione di Bash; un monitoraggio WebSocket richiede l'approvazione separatamente. L'origine `ws` richiede Claude Code v2.1.195 o successivo. Vedi il [riferimento dello strumento Monitor](/docs/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider.2889Quando Monitor esegue un comando, segue le stesse regole di autorizzazione di Bash; un monitoraggio WebSocket richiede l'approvazione separatamente. L'origine `ws` richiede Claude Code v2.1.195 o successivo. Vedi il [riferimento dello strumento Monitor](/docs/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider.

2890 2890

3164**Nome dello strumento:** `TodoWrite`3164**Nome dello strumento:** `TodoWrite`

3165 3165

3166<Note>3166<Note>

3167 Su Python Agent SDK 0.2.139 e successivi, si applica la seguente restrizione.

~~3168~~

3169 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:3167 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

3170 3168

3171 * `TodoWrite`3169 * `TodoWrite`

agent-sdk/streaming-output.md +8 −4

Details

6 6

7> Ricevere risposte in tempo reale dall'Agent SDK mentre il testo e le chiamate di strumenti vengono trasmessi7> Ricevere risposte in tempo reale dall'Agent SDK mentre il testo e le chiamate di strumenti vengono trasmessi

8 8

9Per impostazione predefinita, l'Agent SDK restituisce oggetti `AssistantMessage` completi dopo che Claude ha terminato di generare ogni risposta. Per ricevere aggiornamenti incrementali mentre il testo e le chiamate di strumenti vengono generati, abilita lo streaming di messaggi parziali.9Per impostazione predefinita, l'Agent SDK restituisce un `AssistantMessage` completo per ogni blocco di contenuto non vuoto, come un blocco di testo o una chiamata di strumento, dopo che Claude ha terminato di generare quel blocco. Per ricevere aggiornamenti incrementali mentre il testo e le chiamate di strumenti vengono generati, abilita lo streaming di messaggi parziali.

10 10

11<Tip>11<Tip>

12 Questa pagina copre lo streaming di output (ricezione di token in tempo reale). Per le modalità di input (come invii messaggi), vedi [Inviare messaggi agli agenti](/docs/it/agent-sdk/streaming-vs-single-mode). Puoi anche [trasmettere risposte utilizzando l'Agent SDK tramite la CLI](/docs/it/headless).12 Questa pagina copre lo streaming di output (ricezione di token in tempo reale). Per le modalità di input (come invii messaggi), vedi [Inviare messaggi agli agenti](/docs/it/agent-sdk/streaming-vs-single-mode). Puoi anche [trasmettere risposte utilizzando l'Agent SDK tramite la CLI](/docs/it/headless).

102 uuid: UUID;102 uuid: UUID;

103 session_id: string;103 session_id: string;

104 ttft_ms?: number; // Time to first token in ms, present only on message_start events104 ttft_ms?: number; // Time to first token in ms, present only on message_start events

105 user_message_uuid?: string;

105 };106 };

106 ```107 ```

107</CodeGroup>108</CodeGroup>

108 109

109Il campo `parent_tool_use_id` è sempre `None` in Python e `null` in TypeScript. Gli eventi di streaming vengono emessi solo per la sessione principale; i delta a livello di token dai subagent non vengono inoltrati. Per attribuire l'output a un subagent, utilizza messaggi completi, che contengono `parent_tool_use_id`. Vedi [Rilevare l'invocazione di subagent](/docs/it/agent-sdk/subagents#detect-subagent-invocation).110Il campo `parent_tool_use_id` è sempre `None` in Python e `null` in TypeScript. Gli eventi di streaming vengono emessi solo per la sessione principale; i delta a livello di token dai subagent non vengono inoltrati. Per attribuire l'output a un subagent, utilizza messaggi completi, che contengono `parent_tool_use_id`. Vedi [Rilevare l'invocazione di subagent](/docs/it/agent-sdk/subagents#detect-subagent-invocation).

110 111

112Claude Code imposta `user_message_uuid` sul primo evento di streaming non-ping del turno, e di nuovo quando il messaggio a cui il turno sta rispondendo cambia, secondo le condizioni in [`user_message_uuid`](/docs/it/agent-sdk/typescript#user_message_uuid). Il `StreamEvent` Python non espone questo campo.

113

111Il campo `event` contiene l'evento di streaming grezzo dall'[API Claude](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). I tipi di evento comuni includono:114Il campo `event` contiene l'evento di streaming grezzo dall'[API Claude](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). I tipi di evento comuni includono:

112 115

113| Tipo di evento | Descrizione |116| Tipo di evento | Descrizione |

123 Flusso dei messaggi126 Flusso dei messaggi

124</h2>127</h2>

125 128

126Con i messaggi parziali abilitati, ricevete i messaggi in questo ordine:129Claude Code emette un `AssistantMessage` quando ogni blocco di contenuto non vuoto si completa, quindi una risposta con un blocco di testo e una chiamata a uno strumento produce due oggetti `AssistantMessage`. Ognuno contiene solo il proprio blocco di contenuto, e entrambi condividono lo stesso ID messaggio, che leggete come `message.message.id` in TypeScript e `message.message_id` in Python. Con i messaggi parziali abilitati, ogni `AssistantMessage` arriva prima dell'evento `content_block_stop` di quel blocco, e ricevete i messaggi in questo ordine:

127 130

128```text theme={null}131```text theme={null}

129StreamEvent (message_start)132StreamEvent (message_start)

130StreamEvent (content_block_start) - text block133StreamEvent (content_block_start) - text block

131StreamEvent (content_block_delta) - text chunks...134StreamEvent (content_block_delta) - text chunks...

135AssistantMessage - complete text block

132StreamEvent (content_block_stop)136StreamEvent (content_block_stop)

133StreamEvent (content_block_start) - tool_use block137StreamEvent (content_block_start) - tool_use block

134StreamEvent (content_block_delta) - tool input chunks...138StreamEvent (content_block_delta) - tool input chunks...

139AssistantMessage - complete tool_use block

135StreamEvent (content_block_stop)140StreamEvent (content_block_stop)

136StreamEvent (message_delta)141StreamEvent (message_delta)

137StreamEvent (message_stop)142StreamEvent (message_stop)

138AssistantMessage - complete message with all content

139... tool executes ...143... tool executes ...

140... more streaming events for next turn ...144... more streaming events for next turn ...

141ResultMessage - final result145ResultMessage - final result

142```146```

143 147

144Senza i messaggi parziali abilitati, ricevete tutti i tipi di messaggio tranne `StreamEvent`. I tipi comuni includono `SystemMessage` (inizializzazione della sessione), `AssistantMessage` (risposte complete), `ResultMessage` (risultato finale) e un messaggio di confine compatto che indica quando la cronologia della conversazione è stata compattata (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` con sottotipo `"compact_boundary"` in Python).148Senza i messaggi parziali abilitati, ricevete tutti i tipi di messaggio tranne `StreamEvent`. I tipi comuni includono `SystemMessage` (inizializzazione della sessione), `AssistantMessage` (blocchi di contenuto completi), `ResultMessage` (risultato finale) e un messaggio di confine compatto che indica quando la cronologia della conversazione è stata compattata (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` con sottotipo `"compact_boundary"` in Python).

145 149

146<h2 id="stream-tool-calls">150<h2 id="stream-tool-calls">

147 Trasmettere chiamate di strumenti151 Trasmettere chiamate di strumenti

agent-sdk/subagents.md +1 −1

Details

166| `maxTurns` | `number` | No | Numero massimo di turni agentici prima che l'agente si fermi. Quando l'agente raggiunge il limite, Claude Code restituisce il suo output contrassegnato come parziale, e puoi [riprendere l'agente](#resume-subagents) per continuare. Il contrassegno parziale richiede Claude Code v2.1.246 o successivo |166| `maxTurns` | `number` | No | Numero massimo di turni agentici prima che l'agente si fermi. Quando l'agente raggiunge il limite, Claude Code restituisce il suo output contrassegnato come parziale, e puoi [riprendere l'agente](#resume-subagents) per continuare. Il contrassegno parziale richiede Claude Code v2.1.246 o successivo |

170 170

171In Python SDK, i nomi di campo con più parole come `disallowedTools` e `mcpServers` mantengono la loro ortografia camelCase per corrispondere al formato wire piuttosto che seguire la convenzione snake\_case di Python. Vedi il riferimento [`AgentDefinition`](/docs/it/agent-sdk/python#agentdefinition) per i dettagli.171In Python SDK, i nomi di campo con più parole come `disallowedTools` e `mcpServers` mantengono la loro ortografia camelCase per corrispondere al formato wire piuttosto che seguire la convenzione snake\_case di Python. Vedi il riferimento [`AgentDefinition`](/docs/it/agent-sdk/python#agentdefinition) per i dettagli.

172 172

agent-sdk/todo-tracking.md +2 −4

Details

6 6

7> Traccia i todo nelle sessioni di Agent SDK e visualizza i progressi di Claude nella tua applicazione da chiamate di strumenti strutturate7> Traccia i todo nelle sessioni di Agent SDK e visualizza i progressi di Claude nella tua applicazione da chiamate di strumenti strutturate

8 8

9Sui modelli elencati in [Disponibilità del modello](#model-availability), Claude traccia il lavoro multi-step senza un elenco todo scritto, e Claude Code esclude i [task-tracking tools](/docs/it/tools-reference#task-tool-availability) dalle sessioni per impostazione predefinita. Non hai bisogno di nulla in questa pagina affinché Claude lavori attraverso attività multi-step su questi modelli.9Claude Code fornisce i [task-tracking tools](/docs/it/tools-reference#task-tool-availability) per impostazione predefinita solo sui modelli elencati in [Disponibilità del modello](#model-availability). I modelli più recenti traccia il lavoro multi-step senza un elenco todo scritto, quindi su quelli non hai bisogno di nulla in questa pagina affinché Claude lavori attraverso attività multi-step.

10 10

11In una sessione che ha i task-tracking tools, Claude mantiene un elenco todo scritto, aggiornando lo stato di ogni elemento mentre lavora. Vedi ogni cambiamento nel flusso dei messaggi come una chiamata di strumento strutturata. Abilita una sessione solo quando la tua applicazione legge quelle chiamate di strumento, sia per registrare l'attività delle attività che per renderizzare il proprio display di progresso.11In una sessione che ha i task-tracking tools, Claude mantiene un elenco todo scritto, aggiornando lo stato di ogni elemento mentre lavora. Vedi ogni cambiamento nel flusso dei messaggi come una chiamata di strumento strutturata. Abilita una sessione solo quando la tua applicazione legge quelle chiamate di strumento, sia per registrare l'attività delle attività che per renderizzare il proprio display di progresso.

12 12

15</h2>15</h2>

16 16

17<Note>17<Note>

~~18 Su TypeScript Agent SDK 0.3.233 e successivi, o Python Agent SDK 0.2.139 e successivi, si applica la seguente restrizione.~~

20 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:18 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

21 19

22 * `TodoWrite`20 * `TodoWrite`

30 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.28 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.

31</Note>29</Note>

32 30

33Sui modelli elencati, a meno che non abiliti una sessione, non vedi blocchi `tool_use` per gli strumenti nel flusso dei messaggi. L'Agent SDK applica questi valori predefiniti attraverso il binario Claude Code che raggruppa. Se punti `pathToClaudeCodeExecutable` (TypeScript) o `cli_path` (Python) alla tua installazione di Claude Code, ottieni gli strumenti che quella installazione fornisce, secondo i suoi valori predefiniti. Per vedere l'insieme esatto in una sessione in esecuzione, [controlla quali strumenti sono disponibili](/docs/it/tools-reference#check-which-tools-are-available). Per abilitare una sessione, fai uno dei seguenti:31Su un modello che non dispone degli strumenti per impostazione predefinita, a meno che non abiliti una sessione, non vedrai blocchi `tool_use` per loro nel flusso dei messaggi. L'Agent SDK applica questi valori predefiniti attraverso il binario Claude Code che raggruppa. Se punti `pathToClaudeCodeExecutable` (TypeScript) o `cli_path` (Python) alla tua installazione di Claude Code, otterrai gli strumenti che quella installazione fornisce, secondo i suoi valori predefiniti. Per vedere l'insieme esatto in una sessione in esecuzione, [controlla quali strumenti sono disponibili](/docs/it/tools-reference#check-which-tools-are-available). Per abilitare una sessione, fai uno dei seguenti:

34 32

35* Nomina uno degli strumenti nell'opzione [`allowedTools`](/docs/it/agent-sdk/permissions#allow-and-deny-rules) (TypeScript) o `allowed_tools` (Python)33* Nomina uno degli strumenti nell'opzione [`allowedTools`](/docs/it/agent-sdk/permissions#allow-and-deny-rules) (TypeScript) o `allowed_tools` (Python)

36* Elenca gli strumenti nell'opzione `tools`, che limita gli strumenti integrati della sessione a quelli che nomina. Includi gli strumenti che desideri insieme agli altri strumenti integrati che utilizzi34* Elenca gli strumenti nell'opzione `tools`, che limita gli strumenti integrati della sessione a quelli che nomina. Includi gli strumenti che desideri insieme agli altri strumenti integrati che utilizzi

agent-sdk/troubleshooting.md +161 −0 created

Details

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.

5# Risolvere i problemi dell'Agent SDK

7> Correggi gli errori dell'Agent SDK in base al messaggio esatto che vedi, con la causa e la soluzione per ogni errore negli SDK TypeScript e Python.

9Le voci in questa pagina sono organizzate in base all'errore che vedi. Ognuna indica la causa e cosa fare.

11<h2 id="cli-startup">

12 Avvio CLI

13</h2>

15<h3 id="clinotfounderror-claude-code-not-found">

16 CLINotFoundError: Claude Code not found

17</h3>

19L'SDK Python avvia il CLI di Claude Code come un sottoprocesso. Quando non riesce a trovare un eseguibile `claude`, la connessione non riesce con un `CLINotFoundError`:

21```

22Claude Code not found at: /your/configured/path

23```

25Il messaggio include il percorso configurato quando imposti `ClaudeAgentOptions(cli_path=...)` e punta a un file mancante. Senza `cli_path`, l'SDK cerca nel tuo `PATH` e nelle posizioni di installazione comuni, e il messaggio include le istruzioni di installazione per la tua piattaforma.

27Per correggerlo:

29* Installa Claude Code se non è installato. Vedi [Install Claude Code](/docs/it/setup#install-claude-code) per il comando sulla tua piattaforma.

30* Se hai impostato `cli_path`, conferma che il file esiste ed è l'eseguibile `claude`.

31* Se dipendi dalla risoluzione di `PATH`, conferma che `claude --version` funziona nello stesso ambiente in cui viene eseguita la tua applicazione. I processi che avvii al di fuori della tua shell, ad esempio da un IDE o da un gestore di servizi, spesso vengono eseguiti con un `PATH` diverso.

33L'SDK TypeScript cerca il CLI nel suo pacchetto di piattaforma in bundle e nel percorso che imposti in `pathToClaudeCodeExecutable`. Abbina il messaggio che vedi:

35* `Native CLI binary for <platform>-<arch> not found`: il pacchetto di piattaforma in bundle è mancante, il più delle volte perché l'installazione ha saltato le dipendenze opzionali. Reinstalla `@anthropic-ai/claude-agent-sdk` senza saltare le dipendenze opzionali, oppure punta `pathToClaudeCodeExecutable` a un'[installazione nativa](/docs/it/setup#install-claude-code). In un eseguibile a file singolo creato con `bun build --compile`, lo stesso messaggio ha una causa e una soluzione diverse. Vedi [Compile to a single executable](/docs/it/agent-sdk/typescript#compile-to-a-single-executable).

36* `Claude Code native binary not found at <path>` o `Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?`: il file nel percorso risolto è mancante, oppure il processo non può accedervi. Conferma che il file esiste in quel percorso e che il processo può accedervi.

38<h3 id="cliconnectionerror-refusing-to-execute-batch-script">

39 CLIConnectionError: Refusing to execute batch script

40</h3>

42Su Windows, la connessione non riesce con un `CLIConnectionError` quando il percorso CLI che l'SDK Python utilizza è uno script batch `.bat` o `.cmd`, incluso lo shim `claude.cmd` che un'installazione npm crea:

44```

45Refusing to execute batch script 'C:\\Users\\you\\AppData\\Roaming\\npm\\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).

46```

48Il rifiuto è un indurimento della sicurezza deliberato, non un'installazione interrotta. Windows esegue gli script batch riscrivendo lo spawn in un'invocazione `cmd.exe /c`, e `cmd.exe` ripete l'analisi dell'intera riga di comando al momento dell'esecuzione, quindi un valore di argomento può eseguire comandi iniettati.

50La maggior parte delle installazioni Windows non raggiunge mai questo errore. La wheel x64 di Windows di `claude-agent-sdk` include un `claude.exe`, e l'SDK preferisce il CLI in bundle, quindi qualsiasi `claude.exe` nativo che riesce a scoprire, prima di ricorrere a uno shim batch. Vedi il rifiuto in due casi:

52* Hai impostato `ClaudeAgentOptions(cli_path=...)` su un file `.bat` o `.cmd`, come lo shim `claude.cmd` di npm.

53* La tua installazione non ha un `claude.exe` in bundle o nativo, ad esempio un'installazione da sorgente su ARM64 Windows dove l'unico `claude` nel tuo `PATH` è lo shim npm.

55Per correggerlo, dai all'SDK un eseguibile nativo invece di uno script batch:

57* Se hai impostato `ClaudeAgentOptions(cli_path=...)`, puntalo a un `claude.exe` o rimuovi l'opzione. L'SDK salta la scoperta mentre `cli_path` è impostato, quindi un'installazione nativa da sola non può avere effetto.

58* Installa Claude Code nativamente in PowerShell: `irm https://claude.ai/install.ps1 | iex`

59* Su Windows x64, installa la wheel `claude-agent-sdk`, che include `claude.exe`.

61Prima di `claude-agent-sdk` 0.2.124, l'SDK Python generava script batch tramite `cmd.exe` senza questo controllo.

63<h3 id="cliconnectionerror-failed-to-start-claude-code">

64 CLIConnectionError: Failed to start Claude Code

65</h3>

67L'SDK ha trovato un file nel percorso risolto ma non ha potuto avviarlo. Python genera questi errori come un `CLIConnectionError`. TypeScript rifiuta l'iterazione del messaggio con un errore che non porta alcuna classe SDK. La tabella seguente mappa ogni messaggio a ciò che ti dice. Abbina il messaggio che vedi:

69| Messaggio | SDK | Cosa ti dice |

70| ----------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |

71| `Failed to start Claude Code: <detail>` | Python | Il resto del messaggio è l'errore del sistema operativo stesso |

72| `Claude Code executable at <path> exists but failed to launch` | TypeScript | Lo script nel percorso configurato non può essere eseguito |

73| `Claude Code native binary at <path> exists but failed to launch` | TypeScript | Il binario non può essere eseguito, con un suggerimento libc aggiunto al messaggio |

74| `Failed to spawn Claude Code process: <detail>` | TypeScript | Qualsiasi altro errore di avvio |

76In entrambi gli SDK, la causa più comune è un percorso risolto che punta a qualcosa che non può essere eseguito, come un file di testo, una directory o un file senza permesso di esecuzione. Leggi il suggerimento libc del messaggio del binario nativo come una possibile causa.

78Per correggerlo in uno qualsiasi degli SDK:

80* Conferma che il percorso configurato punta all'eseguibile `claude` stesso e che il file ha il permesso di esecuzione.

81* Se non hai bisogno di un percorso personalizzato, rimuovi `cli_path` in Python o `pathToClaudeCodeExecutable` in TypeScript in modo che l'SDK trovi un CLI da solo, preferendo la sua copia in bundle.

82* Quando il binario che non funziona è la copia in bundle dell'SDK in un'immagine contenitore, reinstalla l'SDK durante la compilazione dell'immagine in modo che il binario in bundle corrisponda alla piattaforma del contenitore, oppure ricompila l'immagine per l'architettura su cui viene eseguita. La causa più comune è un binario che non corrisponde all'architettura o alla libc del contenitore, oppure uno che ha perso il suo permesso di esecuzione nella compilazione dell'immagine.

84<h3 id="cliconnectionerror-not-connected">

85 CLIConnectionError: Not connected

86</h3>

88Chiamare un metodo `ClaudeSDKClient` in Python prima che il client si sia connesso, o dopo che si sia disconnesso, genera un `CLIConnectionError` con questo messaggio:

90```

91Not connected. Call connect() first.

92```

94Fai quello che dice il messaggio. Chiama `await client.connect()` prima di qualsiasi altro metodo client, oppure apri il client con `async with ClaudeSDKClient() as client:`, che si connette all'ingresso.

96<h2 id="cli-process-exit">

97 Uscita del processo CLI

98</h2>

100Le voci in questa sezione significano che il processo Claude Code è terminato mentre la tua applicazione lo stava utilizzando. Quale errore vedi dipende dal linguaggio SDK e dal fatto che il CLI abbia segnalato un risultato di errore prima di uscire.

101

102<h3 id="processerror-command-failed-with-exit-code">

103 ProcessError: Command failed with exit code

104</h3>

105

106L'SDK Python genera un `ProcessError` quando il processo Claude Code esce con un codice diverso da zero:

107

108```

109Command failed with exit code 1 (exit code: 1)

110Error output: Check stderr output for details

111```

112

113Il messaggio indica il codice di uscita due volte, e la riga `Error output` è testo fisso piuttosto che l'output di errore del tuo processo. Lo stesso testo fisso riempie l'attributo `stderr` dell'eccezione. L'attributo `exit_code` dell'eccezione porta il codice. Per acquisire ciò che il CLI ha effettivamente scritto su stderr, passa un callback `stderr` in `ClaudeAgentOptions` e registra ciò che riceve.

114

115Un `ProcessError` nudo significa che il CLI è uscito senza segnalare un risultato di errore. Quando il CLI ha segnalato uno, l'SDK genera [`ResultError`](/docs/it/agent-sdk/python#resulterror) invece, coperto in [Claude Code returned an error result](#claude-code-returned-an-error-result). `ResultError` è una sottoclasse di `ProcessError`, quindi `except ProcessError` cattura entrambi. Per gestirli diversamente, metti la clausola `except ResultError` per prima.

116

117Prima di `claude-agent-sdk` 0.2.140, l'SDK Python generava uscite di risultato di errore come una semplice `Exception` piuttosto che un `ResultError`.

118

119<h3 id="claude-code-process-exited-with-code-n">

120 Claude Code process exited with code N

121</h3>

122

123I wrapper IDE stampano anche questo messaggio, e il [riferimento agli errori](/docs/it/errors#claude-code-process-exited-with-code-n) lo copre per VS Code e altri launcher. Questa voce copre ciò che il tuo codice SDK TypeScript riceve. L'SDK presenta un'uscita CLI con codice diverso da zero come un semplice `Error` che rifiuta il ciclo `for await` sui messaggi di `query()`. Non c'è alcuna classe di errore SDK da catturare, quindi avvolgi il ciclo in `try`/`catch` e abbina il messaggio:

124

125```

126Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

127```

128

129Quando il CLI ha scritto su stderr, il messaggio termina con la coda di esso. Per acquisire il flusso completo, passa un callback `stderr` nelle opzioni di query. Un processo ucciso da un segnale segnala `Claude Code process terminated by signal <name>` nella stessa forma.

130

131<h3 id="claude-code-returned-an-error-result">

132 Claude Code returned an error result

133</h3>

134

135Entrambi gli SDK sostituiscono l'errore di uscita del processo con questo messaggio quando il CLI ha segnalato un risultato di errore prima di uscire:

136

137```

138Claude Code returned an error result: <the CLI's own error report>

139```

140

141Il testo dopo i due punti è il rapporto del CLI su ciò che è andato storto, quindi inizia da lì piuttosto che dall'uscita stessa. Python genera questo come un [`ResultError`](/docs/it/agent-sdk/python#resulterror), il cui attributo `data` porta il risultato di errore completo. TypeScript rifiuta il ciclo dei messaggi con un semplice `Error` che porta la stessa forma di messaggio.

142

143<h2 id="structured-outputs">

144 Output strutturati

145</h2>

146

147<h3 id="structured_output-is-none-but-the-result-says-success">

148 structured\_output is None but the result says success

149</h3>

150

151Un messaggio di risultato può terminare con `subtype: "success"` mentre `structured_output` è `None` in Python o `undefined` in TypeScript. L'esecuzione si completa, ma non esiste un output convalidato. Un modo per raggiungere questo è uno schema che nessun output può soddisfare, ad esempio vincoli di lunghezza in conflitto. L'esecuzione termina senza un errore di convalida, e l'unico segnale è il `structured_output` mancante.

152

153Tratta questo risultato come un errore nel codice dell'applicazione. Controlla sia che `subtype` sia `success` che che `structured_output` sia presente prima di utilizzarlo. La sezione [Error handling](/docs/it/agent-sdk/structured-outputs#error-handling) mostra questo modello per entrambi gli SDK.

154

155Se accade ripetutamente con uno schema che ritieni sia corretto, verifica che lo schema sia soddisfacibile, quindi semplificalo finché gli output non si convalidano, e reintroduci i vincoli uno alla volta.

156

157<h2 id="report-a-new-issue">

158 Segnala un nuovo problema

159</h2>

160

161Se il tuo errore non è coperto qui, controlla i problemi aperti o apri un nuovo problema nei repository SDK: [claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript/issues) o [claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python/issues). Includi il testo di errore completo e la tua versione SDK.

agent-teams.md +6 −6

Details

1633. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/it/model-config#environment-variables), quando è impostato su qualsiasi cosa diversa da `inherit`.1633. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/it/model-config#environment-variables), quando è impostato su qualsiasi cosa diversa da `inherit`.

1644. Il modello attuale del lead.1644. Il modello attuale del lead.

165 165

166[`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/it/sub-agents#run-every-subagent-on-one-model) si applica ai compagni di team così come ai subagent.166Se impostate [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/it/sub-agents#run-every-subagent-on-one-model), le prime due fonti non si applicano. Claude Code sceglie il modello di ogni compagno di team da `CLAUDE_CODE_SUBAGENT_MODEL` quando è impostato su qualsiasi cosa diversa da `inherit`, e dal modello attuale del lead altrimenti. Richiede Claude Code versione 2.1.257 o successiva.

167 167

168Prima della versione 2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` veniva per primo in questo ordine.168Prima della versione 2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` veniva per primo in questo ordine.

169 169

252 Come Claude avvia i team di agenti252 Come Claude avvia i team di agenti

253</h3>253</h3>

254 254

255Per avviare un team, chiedete a Claude dei compagni di team. Claude avvia un compagno di team quando chiama lo [strumento Agent](/docs/it/tools-reference) con un [`name`](/docs/it/sub-agents#subagent-names) mentre i team di agenti sono abilitati, e Claude Code non vi chiede di confermare. Claude nomina anche i subagent ordinari autonomamente in modo da poterli messaggiare in seguito, e mentre i team di agenti sono abilitati, un subagent denominato si avvia come compagno di team, quindi i team possono formarsi anche quando non lo avete richiesto.255Per avviare un team, chiedete a Claude dei compagni di team. Claude avvia un compagno di team quando chiama lo [strumento Agent](/docs/it/tools-reference) con un [`name`](/docs/it/sub-agents#subagent-names) mentre i team di agenti sono abilitati, a meno che la chiamata non sia un [fork](/docs/it/sub-agents#fork-the-current-conversation) o passi `isolation` sulla chiamata stessa. Claude Code non vi chiede di confermare l'avvio.

256 256

257Se preferite subagent, [disabilitate i team di agenti](#claude-spawns-teammates-instead-of-subagents).257Claude nomina anche i subagent ordinari autonomamente in modo da poterli messaggiare in seguito. Queste chiamate seguono la stessa regola, quindi i team possono formarsi anche quando non lo avete richiesto. Se preferite subagent, [disabilitate i team di agenti](#claude-spawns-teammates-instead-of-subagents).

258 258

259<h3 id="architecture">259<h3 id="architecture">

260 Architettura260 Architettura

294 Utilizzare definizioni di subagent per i compagni di team294 Utilizzare definizioni di subagent per i compagni di team

295</h3>295</h3>

296 296

297Quando generate un compagno di team, potete fare riferimento a un tipo di [subagent](/docs/it/sub-agents) da qualsiasi [ambito di subagent](/docs/it/sub-agents#choose-the-subagent-scope): progetto, utente, plugin o definito da CLI. Questo vi permette di definire un ruolo una volta, come un security-reviewer o test-runner, e riutilizzarlo sia come subagent delegato che come compagno di team di un team di agenti.297Quando generate un compagno di team in una qualsiasi modalità di visualizzazione, potete fare riferimento a un tipo di [subagent](/docs/it/sub-agents) dal progetto, dall'utente o dall'[ambito di subagent](/docs/it/sub-agents#choose-the-subagent-scope) gestito. Questo vi permette di definire un ruolo una volta, come un security-reviewer o test-runner, e riutilizzarlo sia come subagent delegato che come compagno di team di un team di agenti.

298 298

299Per utilizzare una definizione di subagent, menzionatela per nome quando chiedete a Claude di generare il compagno di team:299Per utilizzare una definizione di subagent, menzionatela per nome quando chiedete a Claude di generare il compagno di team:

300 300

314 Permessi314 Permessi

315</h3>315</h3>

316 316

317I compagni di team iniziano con le impostazioni di permesso del lead. Se il lead viene eseguito con `--dangerously-skip-permissions`, lo fanno anche tutti i compagni di team. Dopo la generazione, potete cambiare le modalità dei singoli compagni di team, ma non potete impostare modalità per compagno di team al momento della generazione.317I compagni di team iniziano con la modalità di permesso del lead, eccetto la modalità [`dontAsk`](/docs/it/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), che non ereditano. Se il lead viene eseguito con `--dangerously-skip-permissions`, lo fanno anche tutti i compagni di team. Dopo la generazione, potete cambiare la modalità di permesso di un singolo compagno di team, ma non potete impostare modalità di permesso per compagno di team al momento della generazione.

318 318

319I prompt di permesso dei compagni di team risalgono alla sessione lead, quindi approvate voi stessi lì. [Approvazione del piano](#have-teammates-plan-before-implementing) è l'eccezione progettata: la sessione lead concede le approvazioni del piano dei compagni di team senza un prompt separato per voi.319I prompt di permesso dei compagni di team risalgono alla sessione lead, quindi approvate voi stessi lì. [Approvazione del piano](#have-teammates-plan-before-implementing) è l'eccezione progettata: la sessione lead concede le approvazioni del piano dei compagni di team senza un prompt separato per voi.

320 320

547* **Nessun team annidato**: i compagni di team non possono generare i loro propri compagni di team. Solo il lead può gestire il team.547* **Nessun team annidato**: i compagni di team non possono generare i loro propri compagni di team. Solo il lead può gestire il team.

548* **Nessun subagent in background da compagni di team in-process**: i propri subagent di un compagno di team in-process vengono eseguiti in primo piano, perché il lavoro in background di un compagno di team non può sopravvivere al processo del lead. Claude Code restituisce un errore quando un compagno di team genera un subagent la cui definizione imposta `background: true`. Una richiesta `run_in_background: true` di un compagno di team fallisce anche, con un errore o eseguendosi silenziosamente in primo piano, come descritto in [come Claude Code sceglie il primo piano o lo sfondo](/docs/it/sub-agents#run-subagents-in-foreground-or-background). I subagent lanciati dalla conversazione principale seguono il [default in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background).548* **Nessun subagent in background da compagni di team in-process**: i propri subagent di un compagno di team in-process vengono eseguiti in primo piano, perché il lavoro in background di un compagno di team non può sopravvivere al processo del lead. Claude Code restituisce un errore quando un compagno di team genera un subagent la cui definizione imposta `background: true`. Una richiesta `run_in_background: true` di un compagno di team fallisce anche, con un errore o eseguendosi silenziosamente in primo piano, come descritto in [come Claude Code sceglie il primo piano o lo sfondo](/docs/it/sub-agents#run-subagents-in-foreground-or-background). I subagent lanciati dalla conversazione principale seguono il [default in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background).

549* **Il lead è fisso**: la sessione principale è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.549* **Il lead è fisso**: la sessione principale è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.

550* **Permessi impostati al momento della generazione**: tutti i compagni di team iniziano con la modalità di permesso del lead. Potete cambiare le modalità dei singoli compagni di team dopo la generazione, ma non potete impostare modalità per compagno di team al momento della generazione.550* **Permessi impostati al momento della generazione**: i compagni di team iniziano con la modalità di permesso descritta in [Permessi](#permissions). Potete cambiare la modalità di permesso di un singolo compagno di team dopo la generazione, ma non potete impostare modalità di permesso per compagno di team al momento della generazione.

551* **Split panes richiedono tmux o iTerm2**: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.551* **Split panes richiedono tmux o iTerm2**: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.

552 552

553<h2 id="next-steps">553<h2 id="next-steps">

agents.md +1 −1

Details

19 19

20Tre ulteriori strumenti supportano questo lavoro senza essere un modo per eseguire agenti stessi:20Tre ulteriori strumenti supportano questo lavoro senza essere un modo per eseguire agenti stessi:

21 21

22* [Worktrees](/docs/it/worktrees) danno a ogni sessione un checkout git separato, così le sessioni parallele non modificano mai gli stessi file. Usateli per le sessioni che eseguite voi stessi. La visualizzazione agenti sposta automaticamente ogni sessione inviata nel suo proprio worktree, e i subagenti che generate possono ottenerne uno anche loro.22* [Worktrees](/docs/it/worktrees) danno a ogni sessione un checkout git separato, così le sessioni parallele non modificano mai gli stessi file. Usateli per le sessioni che eseguite voi stessi. Una sessione che inviate da visualizzazione agenti [si sposta nel suo proprio worktree prima di modificare i file](/docs/it/agent-view#how-file-edits-are-isolated), e i subagenti che generate possono ottenerne uno anche loro.

23* [Messaggistica tra sessioni](/docs/it/cross-session-messaging) consente a Claude di elencare e inviare messaggi alle Vostre altre sessioni Claude Code su questa macchina, su un'altra macchina, o su [Claude Code sul web](/docs/it/claude-code-on-the-web), così le sessioni che eseguite voi stessi possono passare risultati e stato tra di loro.23* [Messaggistica tra sessioni](/docs/it/cross-session-messaging) consente a Claude di elencare e inviare messaggi alle Vostre altre sessioni Claude Code su questa macchina, su un'altra macchina, o su [Claude Code sul web](/docs/it/claude-code-on-the-web), così le sessioni che eseguite voi stessi possono passare risultati e stato tra di loro.

24* [`/batch`](/docs/it/commands) è una [skill](/docs/it/skills) che ha Claude dividere un grande cambiamento in 5 a 30 subagenti isolati da worktree che ciascuno apre una pull request. È un uso confezionato di subagenti e worktrees, non uno stile di coordinamento separato.24* [`/batch`](/docs/it/commands) è una [skill](/docs/it/skills) che ha Claude dividere un grande cambiamento in 5 a 30 subagenti isolati da worktree che ciascuno apre una pull request. È un uso confezionato di subagenti e worktrees, non uno stile di coordinamento separato.

25 25

amazon-bedrock.md +23 −4

Details

186 186

187Claude Code risolve la catena del provider di credenziali predefinito AWS una volta e mantiene le credenziali risolte in memoria. Le riutilizza fino a cinque minuti prima della scadenza, o per un'ora quando non hanno scadenza, quindi un profilo supportato da SSO richiede credenziali da IAM Identity Center circa una volta per durata della credenziale. Un errore di credenziale dall'API cancella la cache e il nuovo tentativo risolve credenziali aggiornate. Richiede Claude Code v2.1.207 o successiva.187Claude Code risolve la catena del provider di credenziali predefinito AWS una volta e mantiene le credenziali risolte in memoria. Le riutilizza fino a cinque minuti prima della scadenza, o per un'ora quando non hanno scadenza, quindi un profilo supportato da SSO richiede credenziali da IAM Identity Center circa una volta per durata della credenziale. Un errore di credenziale dall'API cancella la cache e il nuovo tentativo risolve credenziali aggiornate. Richiede Claude Code v2.1.207 o successiva.

188 188

189La cache copre tutte le opzioni di credenziale sopra elencate tranne una chiave API di Amazon Bedrock, che non utilizza la catena del provider. Per risolvere la catena su ogni richiesta, impostare [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/it/env-vars).189La cache copre tutte le opzioni di credenziale sopra elencate tranne una chiave API di Amazon Bedrock, che non utilizza la catena del provider. Per risolvere la catena su ogni richiesta invece, impostare [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/it/env-vars).

190 190

191Ogni risoluzione della catena scade dopo 60 secondi. Se un passaggio della catena si blocca, ad esempio un helper `credential_process` che attende un input che non può ricevere, la richiesta non riesce con [`AWS default-chain credential resolve timed out`](/docs/it/errors#aws-default-chain-credential-resolve-timed-out). Se la catena esegue un accesso interattivo che legittimamente ha bisogno di più tempo, come SSO basato su browser con MFA tramite un wrapper come `aws-vault`, aumentare il limite in millisecondi con [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/it/env-vars). Prima della versione 2.1.207, una risoluzione di credenziale bloccata lasciava la richiesta in attesa indefinitamente.191Ogni risoluzione della catena scade dopo 60 secondi. Se un passaggio della catena si blocca, ad esempio un helper `credential_process` che attende un input che non può ricevere, la richiesta non riesce con [`AWS default-chain credential resolve timed out`](/docs/it/errors#aws-default-chain-credential-resolve-timed-out). Se la catena esegue un accesso interattivo che legittimamente ha bisogno di più tempo, come SSO basato su browser con MFA tramite un wrapper come `aws-vault`, aumentare il limite in millisecondi con [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/it/env-vars). Prima della versione 2.1.207, una risoluzione di credenziale bloccata lasciava la richiesta in attesa indefinitamente.

192 192

193Tranne quando si esegue l'autenticazione con una chiave API di Amazon Bedrock, la [procedura guidata di configurazione](#sign-in-with-bedrock) applica lo stesso limite a ogni chiamata AWS che effettua durante la verifica delle credenziali, e alla ricerca delle credenziali prima di ogni controllo del modello. Durante la verifica delle credenziali, un controllo che lo supera non riesce con [`Timed out after 60s waiting for AWS`](/docs/it/errors#bedrock-setup-verification-timed-out-waiting-for-aws).

194

193<h4 id="advanced-credential-configuration">195<h4 id="advanced-credential-configuration">

194 Configurazione avanzata delle credenziali196 Configurazione avanzata delle credenziali

195</h4>197</h4>

263 265

264Quando si abilita Amazon Bedrock per Claude Code, tenere presente quanto segue:266Quando si abilita Amazon Bedrock per Claude Code, tenere presente quanto segue:

265 267

266* A partire dalla versione 2.1.172, è necessario impostare `AWS_REGION` solo per sovrascrivere la regione del profilo AWS o quando il profilo non ha una regione. Claude Code risolve la regione in questo ordine:268* È necessario impostare `AWS_REGION` solo per sovrascrivere la regione del profilo AWS o quando il profilo non ha una regione. Claude Code risolve la regione in questo ordine:

267 269

268 * `AWS_REGION`270 * `AWS_REGION`

269 * `AWS_DEFAULT_REGION`271 * `AWS_DEFAULT_REGION`

274 276

275 Il profilo attivo è `AWS_PROFILE` se impostato, altrimenti `default`. Impostare `AWS_SHARED_CREDENTIALS_FILE` o `AWS_CONFIG_FILE` per puntare a percorsi di file non predefiniti.277 Il profilo attivo è `AWS_PROFILE` se impostato, altrimenti `default`. Impostare `AWS_SHARED_CREDENTIALS_FILE` o `AWS_CONFIG_FILE` per puntare a percorsi di file non predefiniti.

276 278

277 Eseguire `/status` per visualizzare la regione risolta. Quando la regione proviene dai file di configurazione AWS o dal fallback predefinito, Claude Code nota anche la fonte nell'output `/status`. Nella versione 2.1.171 e precedenti, Claude Code non legge i file di configurazione AWS, quindi impostare `AWS_REGION` esplicitamente.279 Eseguire `/status` per visualizzare la regione risolta. Quando la regione proviene dai file di configurazione AWS o dal fallback predefinito, Claude Code nota anche la fonte nell'output `/status`.

278* Quando si utilizza Amazon Bedrock, il comando `/logout` non è disponibile poiché l'autenticazione viene gestita tramite credenziali AWS.280* Quando si utilizza Amazon Bedrock, il comando `/logout` non è disponibile poiché l'autenticazione viene gestita tramite credenziali AWS.

279* Lo strumento WebSearch non è disponibile su Amazon Bedrock. Vedere [Comportamento dello strumento WebSearch](/docs/it/tools-reference#websearch-tool-behavior).281* Lo strumento WebSearch non è disponibile su Amazon Bedrock. Vedere [Comportamento dello strumento WebSearch](/docs/it/tools-reference#websearch-tool-behavior).

280* È possibile utilizzare file di impostazioni per variabili di ambiente come `AWS_PROFILE` che non si desidera perdere in altri processi. Vedere [Settings](/docs/it/settings) per ulteriori informazioni.282* È possibile utilizzare file di impostazioni per variabili di ambiente come `AWS_PROFILE` che non si desidera perdere in altri processi. Vedere [Settings](/docs/it/settings) per ulteriori informazioni.

529export AWS_REGION=us-east-1531export AWS_REGION=us-east-1

530```532```

531 533

532Claude Code costruisce l'URL dell'endpoint dalla regione AWS. A partire da v2.1.172, la regione viene risolta con la stessa precedenza di [Amazon Bedrock sopra](#3-configure-claude-code); le versioni precedenti utilizzano solo `AWS_REGION`. Per sovrascrivere l'URL per un endpoint personalizzato o gateway, imposta `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`.534Claude Code costruisce l'URL dell'endpoint dalla regione AWS, risolta con la stessa precedenza di [Amazon Bedrock sopra](#3-configure-claude-code). Per sovrascrivere l'URL per un endpoint personalizzato o gateway, imposta `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`.

533 535

534Esegui `/status` all'interno di Claude Code per confermare. La riga del provider mostra `Amazon Bedrock (Mantle)` quando Mantle è attivo.536Esegui `/status` all'interno di Claude Code per confermare. La riga del provider mostra `Amazon Bedrock (Mantle)` quando Mantle è attivo.

535 537

605 607

606Se il tuo ambiente di rete interferisce con i flussi SSO automatici basati su browser, utilizza `aws sso login` manualmente prima di avviare Claude Code invece di affidarti a `awsAuthRefresh`.608Se il tuo ambiente di rete interferisce con i flussi SSO automatici basati su browser, utilizza `aws sso login` manualmente prima di avviare Claude Code invece di affidarti a `awsAuthRefresh`.

607 609

610<h3 id="certificate-errors-behind-a-tls-inspecting-proxy">

611 Errori di certificato dietro un proxy che ispeziona TLS

612</h3>

613

614Claude Code applica la configurazione del tuo [archivio di certificati CA](/docs/it/network-config#ca-certificate-store) alle sue richieste ad AWS, incluse:

615

616* Scoperta del modello

617* Conteggio dei token

618* Le chiamate del ruolo di credenziale STS e SSO che risolvono le tue credenziali AWS

619* La verifica delle credenziali e i controlli del modello della [procedura guidata di configurazione](#sign-in-with-bedrock)

620

621Per queste richieste, un certificato radice aziendale nel tuo archivio di attendibilità del sistema operativo o nel bundle `NODE_EXTRA_CA_CERTS` non necessita di alcuna configurazione specifica di Amazon Bedrock.

622

623Prima della v2.1.260, Claude Code applicava la tua configurazione CA a queste richieste solo quando passavano attraverso un proxy configurato, e su una connessione diretta si fidavano solo dell'archivio di certificati predefinito del runtime.

624

625Prima della v2.1.261, la ricerca delle credenziali dietro i controlli del modello della procedura guidata di configurazione con l'opzione **Usa credenziali già nel mio ambiente** si fidava ancora solo dell'archivio di certificati predefinito del runtime. Dietro un proxy che ispeziona TLS il cui certificato radice è solo nell'archivio del sistema operativo, le richieste interessate non riuscivano con `unable to get local issuer certificate`, oppure la procedura guidata mostrava i modelli come `unreachable`, mentre le richieste di inferenza avevano successo. Aggiorna a v2.1.261 o versione successiva.

626

608<h3 id="region-issues">627<h3 id="region-issues">

609 Problemi di regione628 Problemi di regione

610</h3>629</h3>

analytics.md +5 −11

Details

26* **Leaderboard**: i principali contributori classificati per utilizzo di Claude Code26* **Leaderboard**: i principali contributori classificati per utilizzo di Claude Code

27* **Esportazione dati**: scarica i dati di contributo come CSV per report personalizzati27* **Esportazione dati**: scarica i dati di contributo come CSV per report personalizzati

28 28

29Per i conteggi dei token per utente e le stime dei costi, configura [esportazione OpenTelemetry](/it/monitoring-usage), oppure esporta il [report di spesa](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans) dalle impostazioni di analittica della tua organizzazione, che elenca l'utilizzo dei token e la spesa stimata in crediti di utilizzo per utente e per modello.29Per i conteggi dei token per utente e le stime dei costi, configura [esportazione OpenTelemetry](/docs/it/monitoring-usage), oppure esporta il [report di spesa](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans) dalle impostazioni di analittica della tua organizzazione, che elenca l'utilizzo dei token e la spesa stimata in crediti di utilizzo per utente e per modello.

30 30

31<h3 id="enable-contribution-metrics">31<h3 id="enable-contribution-metrics">

32 Enable contribution metrics32 Enable contribution metrics

41Hai bisogno del ruolo di proprietario per configurare le impostazioni di analittica. Un amministratore GitHub deve installare l'app GitHub.41Hai bisogno del ruolo di proprietario per configurare le impostazioni di analittica. Un amministratore GitHub deve installare l'app GitHub.

42 42

43<Warning>43<Warning>

44 Le metriche di contributo non sono disponibili per le organizzazioni con [Zero Data Retention](/it/zero-data-retention) abilitato. Il dashboard di analittica mostrerà solo le metriche di utilizzo.44 Le metriche di contributo non sono disponibili per le organizzazioni con [Zero Data Retention](/docs/it/zero-data-retention) abilitato. Il dashboard di analittica mostrerà solo le metriche di utilizzo.

45</Warning>45</Warning>

46 46

47<Steps>47<Steps>

139 139

140Quando le metriche di contributo sono abilitate, Claude Code analizza le pull request unite per determinare quale codice è stato scritto con assistenza di Claude Code. Questo viene fatto abbinando l'attività della sessione di Claude Code al codice in ogni PR.140Quando le metriche di contributo sono abilitate, Claude Code analizza le pull request unite per determinare quale codice è stato scritto con assistenza di Claude Code. Questo viene fatto abbinando l'attività della sessione di Claude Code al codice in ogni PR.

141 141

142<h4 id="tagging-criteria">

143 Tagging criteria

144</h4>

~~145~~

146I PR sono etichettati come "with Claude Code" se contengono almeno una riga di codice scritta durante una sessione di Claude Code. Il sistema utilizza un abbinamento conservativo: solo il codice dove c'è un'alta confidenza nel coinvolgimento di Claude Code viene conteggiato come assistito.

~~147~~

148<h4 id="attribution-process">142<h4 id="attribution-process">

149 Attribution process143 Attribution process

150</h4>144</h4>

267 Risorse correlate261 Risorse correlate

268</h2>262</h2>

269 263

270* [Monitoring with OpenTelemetry](/it/monitoring-usage): esporta metriche e eventi in tempo reale al tuo stack di osservabilità264* [Monitoring with OpenTelemetry](/docs/it/monitoring-usage): esporta metriche e eventi in tempo reale al tuo stack di osservabilità

271* [Manage costs effectively](/it/costs): imposta limiti di spesa e ottimizza l'utilizzo dei token265* [Manage costs effectively](/docs/it/costs): imposta limiti di spesa e ottimizza l'utilizzo dei token

272* [Permissions](/it/permissions): configura ruoli e autorizzazioni266* [Permissions](/docs/it/permissions): configura ruoli e autorizzazioni

authentication.md +5 −1

Details

235 235

236Una sessione del [gateway delle app Claude](/docs/it/claude-apps-gateway) autenticata si trova al di fuori di questo elenco: è una selezione di provider come Amazon Bedrock o Google Cloud's Agent Platform, e ha la precedenza su di essi. Quando esiste una sessione gateway, la CLI si autentica con il token gateway anche se `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, o `CLAUDE_CODE_USE_FOUNDRY` è impostato, e le fonti di credenziali sopra come il bearer token, la chiave API, `apiKeyHelper`, e i profili non vengono utilizzati.236Una sessione del [gateway delle app Claude](/docs/it/claude-apps-gateway) autenticata si trova al di fuori di questo elenco: è una selezione di provider come Amazon Bedrock o Google Cloud's Agent Platform, e ha la precedenza su di essi. Quando esiste una sessione gateway, la CLI si autentica con il token gateway anche se `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, o `CLAUDE_CODE_USE_FOUNDRY` è impostato, e le fonti di credenziali sopra come il bearer token, la chiave API, `apiKeyHelper`, e i profili non vengono utilizzati.

237 237

238Se avete una sottoscrizione Claude attiva ma avete anche `ANTHROPIC_API_KEY` impostato nel Vostro ambiente, la chiave API ha la precedenza una volta approvata. Questo può causare errori di autenticazione se la chiave appartiene a un'organizzazione disabilitata o scaduta. Eseguite `unset ANTHROPIC_API_KEY` per tornare alla Vostra sottoscrizione, e controllate `/status` per confermare quale metodo è attivo. La riga `Login method` mostra il Vostro account di sottoscrizione, e una riga `API key` appare quando una chiave API è in uso.238Se le [impostazioni gestite](/docs/it/managed-settings) della Vostra macchina impostano [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) a `"gateway"` o impostano [`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl), e non selezionate un provider cloud attraverso una variabile come `CLAUDE_CODE_USE_BEDROCK` o `CLAUDE_CODE_USE_VERTEX`, la Vostra sessione utilizza solo l'accesso gateway. Claude Code salta le altre fonti di credenziali e vi chiede di accedere con `/login`. Consultate [Administrator policy requires a Cloud gateway sign-in](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in) per quello che vedete con ogni credenziale residua. Prima della v2.1.261, o prima della v2.1.265 su una macchina che imposta solo `forceLoginGatewayUrl`, Claude Code utilizzava un accesso salvato residuo su queste macchine fino a quando non avete effettuato l'accesso al gateway.

239

240Se avete una sottoscrizione Claude attiva ma avete anche `ANTHROPIC_API_KEY` impostato nel Vostro ambiente, Claude Code utilizza la chiave API una volta che l'approvate. Questo può causare errori di autenticazione se la chiave appartiene a un'organizzazione disabilitata o scaduta.

241

242Eseguite `unset ANTHROPIC_API_KEY` per tornare alla Vostra sottoscrizione, e controllate `/status` per confermare quale metodo è attivo. Quando un accesso e una chiave API sono entrambi configurati, `/status` contrassegna la credenziale che non è in uso.

239 243

240[Claude Code sul Web](/docs/it/claude-code-on-the-web) utilizza sempre le Vostre credenziali di sottoscrizione. Se impostate `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` nell'ambiente sandbox, non sovrascrivono le Vostre credenziali di sottoscrizione.244[Claude Code sul Web](/docs/it/claude-code-on-the-web) utilizza sempre le Vostre credenziali di sottoscrizione. Se impostate `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` nell'ambiente sandbox, non sovrascrivono le Vostre credenziali di sottoscrizione.

241 245

auto-mode-config.md +7 −5

Details

36 36

37<Info>Prima di v2.1.211, il classificatore consentiva push solo al tuo ramo di lavoro, ai rami creati da Claude e ai push di routine al ramo predefinito.</Info>37<Info>Prima di v2.1.211, il classificatore consentiva push solo al tuo ramo di lavoro, ai rami creati da Claude e ai push di routine al ramo predefinito.</Info>

38 38

39Se desideri un checkpoint umano prima di ogni push o pull request, aggiungi regole di autorizzazione: le [ricette di seguito](#add-a-human-checkpoint) mantengono la modalità auto attiva per tutto il resto.39Se desideri un checkpoint umano prima dei comandi push e pull request di Claude, aggiungi regole di autorizzazione: le [ricette di seguito](#add-a-human-checkpoint) mantengono la modalità auto attiva per tutto il resto.

40 40

41<h3 id="add-a-human-checkpoint">41<h3 id="add-a-human-checkpoint">

42 Aggiungere un checkpoint umano42 Aggiungere un checkpoint umano

55}55}

56```56```

57 57

58Questi regole corrispondono ai comandi che iniziano con `git push` o `gh pr create`. Un push che Claude scrive in un altro modo, come `git -C <dir> push` o `git -c <key>=<value> push`, [non corrisponde alla regola](/docs/it/permissions#bash-rule-limits), quindi non viene sottoposto a checkpoint. Per un checkpoint che ispeziona il testo completo del comando, aggiungi un [hook PreToolUse](/docs/it/hooks#pretooluse).

58Scegli il meccanismo che corrisponde a quanto ferma deve essere la limitazione:60Scegli il meccanismo che corrisponde a quanto ferma deve essere la limitazione:

59 61

61| :------------------------------------- | :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |63| :------------------------------------- | :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

62| Richiedi prima dell'azione | `permissions.ask` | Sempre richiede per le regole con ambito di contenuto come la ricetta di cui sopra. Il classificatore non può approvare automaticamente un'azione corrispondente. |64| Richiedi prima dell'azione | `permissions.ask` | Sempre richiede per un comando che corrisponde a una regola con ambito di contenuto come la ricetta di cui sopra. Il classificatore non può approvare automaticamente un'azione corrispondente. |

64| Confine una tantum per questa sessione | Dichiaralo nella conversazione, come "non fare push finché non rivedo" | Il classificatore blocca le azioni corrispondenti, ma il confine può andare perso se la [compattazione del contesto](/docs/it/costs#reduce-token-usage) rimuove il messaggio che lo ha dichiarato. Utilizza una regola di richiesta o negazione per una garanzia duratura. |66| Confine una tantum per questa sessione | Dichiaralo nella conversazione, come "non fare push finché non rivedo" | Il classificatore blocca le azioni corrispondenti, ma il confine può andare perso se la [compattazione del contesto](/docs/it/costs#reduce-token-usage) rimuove il messaggio che lo ha dichiarato. Utilizza una regola di richiesta o negazione per una garanzia duratura. |

65 67

393 395

394Per vedere cosa ha bloccato il classificatore, trova la chiamata di strumento nella conversazione. Se la chiamata appare accorciata o ripiegata in una riga di riepilogo come `Ran 3 shell commands`, premi `Ctrl+O` per aprire il [transcript viewer](/docs/it/interactive-mode#transcript-viewer), che l'espande.396Per vedere cosa ha bloccato il classificatore, trova la chiamata di strumento nella conversazione. Se la chiamata appare accorciata o ripiegata in una riga di riepilogo come `Ran 3 shell commands`, premi `Ctrl+O` per aprire il [transcript viewer](/docs/it/interactive-mode#transcript-viewer), che l'espande.

395 397

396Due altri posti sullo schermo che segnalano i rifiuti omettono il comando o l'URL: l'avviso vicino alla casella di input, come `bash denied by auto mode · Blocked by classifier · /permissions`, fornisce lo strumento e il motivo, e la scheda **Recently denied** elenca un comando shell dalla descrizione che Claude ha scritto per esso. Per acquisire l'input esatto di questi rifiuti a livello di programmazione, aggiungi un [hook `PermissionDenied`](/docs/it/hooks#permissiondenied), che lo riceve come `tool_input`.398Due altri posti sullo schermo che segnalano i rifiuti omettono il comando o l'URL: l'avviso vicino alla casella di input, come `bash denied by auto mode · [Data Exfiltration] · /permissions`, fornisce lo strumento e il motivo, e la scheda **Recently denied** elenca un comando shell dalla descrizione che Claude ha scritto per esso. Per acquisire l'input esatto di questi rifiuti a livello di programmazione, aggiungi un [hook `PermissionDenied`](/docs/it/hooks#permissiondenied), che lo riceve come `tool_input`.

397 399

398Il testo sotto la chiamata ti dice se c'è qualcosa da correggere. Il testo che segnala un problema con il classificatore stesso, come un modello che `is temporarily unavailable` o un errore del classificatore, significa che Claude Code ha bloccato la chiamata senza un verdetto finale dal classificatore; vedi [Auto mode cannot determine the safety of an action](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action) per cosa fare. Altrimenti, una riga che legge `Denied by auto mode classifier` con un motivo come `Blocked by classifier` significa che il classificatore ha giudicato la chiamata non sicura, quindi scegli la correzione da ciò che la chiamata stava cercando di raggiungere o fare:400Il testo sotto la chiamata ti dice se c'è qualcosa da correggere. Il testo che segnala un problema con il classificatore stesso, come un modello che `is temporarily unavailable` o un errore del classificatore, significa che Claude Code ha bloccato la chiamata senza un verdetto finale dal classificatore; vedi [Auto mode cannot determine the safety of an action](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action) per cosa fare. Altrimenti, una riga che legge `Denied by auto mode classifier` con un motivo come `[Production Deploy]` o `Blocked by classifier` significa che il classificatore ha giudicato la chiamata non sicura, quindi scegli la correzione da ciò che la chiamata stava cercando di raggiungere o fare:

399 401

400* Una destinazione che Claude ha bisogno durante l'intero compito, come un registro di pacchetti, un dominio interno o un host di repository: aggiungilo a `autoMode.environment`.402* Una destinazione che Claude ha bisogno durante l'intero compito, come un registro di pacchetti, un dominio interno o un host di repository: aggiungilo a `autoMode.environment`.

401* Un comando che desideri eseguire senza revisione da ora in poi: aggiungi una regola `allow`.403* Un comando che desideri eseguire senza revisione da ora in poi: aggiungi una regola `allow`.

403 405

404Puoi aggiungere la voce di ambiente o la regola `allow` dalla scheda [**Auto mode**](#edit-rules-from-permissions) della finestra di dialogo `/permissions`.406Puoi aggiungere la voce di ambiente o la regola `allow` dalla scheda [**Auto mode**](#edit-rules-from-permissions) della finestra di dialogo `/permissions`.

405 407

406Il motivo mostrato con la chiamata è il testo fisso `Blocked by classifier` nella maggior parte delle sessioni, in Claude Code v2.1.208 e successivo: il classificatore assegna un punteggio a ogni azione su una scala di gravità interna piuttosto che scrivere una spiegazione. Alcune sessioni eseguono un modello di classificatore che scrive una breve spiegazione, in v2.1.193 e successivo; quando uno appare, trattalo come un suggerimento su quale destinazione o intento il classificatore stava perdendo. Claude Code seleziona il modello di classificatore, quindi quale motivo vedi non è qualcosa che configuri.408Nella maggior parte delle sessioni il nome del motivo nomina la regola che il classificatore ha abbinato, tra parentesi quadre, come `[Data Exfiltration]` o `[Production Deploy]`, e alcune sessioni eseguono un modello di classificatore che aggiunge una breve spiegazione. Claude Code seleziona il modello di classificatore, quindi quale forma vedi non è qualcosa che configuri.

407 409

408<h3 id="fix-repeated-denials">410<h3 id="fix-repeated-denials">

409 Correggere i rifiuti ripetuti411 Correggere i rifiuti ripetuti

best-practices.md +1 −1

Details

452</h3>452</h3>

453 453

454<Tip>454<Tip>

455 Ogni prompt che inviate crea un checkpoint. Potete ripristinare la conversazione, il codice o entrambi a qualsiasi checkpoint precedente.455 Ogni prompt che inviate che avvia un turno crea un checkpoint. Potete ripristinare la conversazione, il codice o entrambi a qualsiasi checkpoint precedente.

456</Tip>456</Tip>

457 457

458Claude crea automaticamente snapshot dei file prima di ogni modifica in modo che un checkpoint possa ripristinarli. Premete il doppio tasto Escape o eseguite `/rewind` per aprire il menu di rewind. Potete ripristinare solo la conversazione, ripristinare solo il codice, ripristinare entrambi o riassumere da un messaggio selezionato. Consultate [Checkpointing](/docs/it/checkpointing) per i dettagli.458Claude crea automaticamente snapshot dei file prima di ogni modifica in modo che un checkpoint possa ripristinarli. Premete il doppio tasto Escape o eseguite `/rewind` per aprire il menu di rewind. Potete ripristinare solo la conversazione, ripristinare solo il codice, ripristinare entrambi o riassumere da un messaggio selezionato. Consultate [Checkpointing](/docs/it/checkpointing) per i dettagli.

channels.md +2 −2

Details

47 * `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.47 * `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

48 * Il plugin è [non trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.48 * Il plugin è [non trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.

49 49

50 Quando l'installazione chiede un ambito di installazione, scegli l'opzione di ambito utente in modo che il plugin sia disponibile in tutti i tuoi progetti. Controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, esegui quel comando per attivare il comando di configurazione del plugin.50 Quando l'installazione chiede un ambito di installazione, scegli l'opzione di ambito utente in modo che il plugin sia disponibile in tutti i tuoi progetti. Controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, vedi [Applica le modifiche del plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) per rendere disponibile il comando di configurazione del plugin.

51 </Step>51 </Step>

52 52

53 <Step title="Configura il tuo token">53 <Step title="Configura il tuo token">

125 * `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.125 * `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

126 * Il plugin è [non trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.126 * Il plugin è [non trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.

127 127

128 Quando l'installazione chiede un ambito di installazione, scegli l'opzione di ambito utente in modo che il plugin sia disponibile in tutti i tuoi progetti. Controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, esegui quel comando per attivare il comando di configurazione del plugin.128 Quando l'installazione chiede un ambito di installazione, scegli l'opzione di ambito utente in modo che il plugin sia disponibile in tutti i tuoi progetti. Controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, vedi [Applica le modifiche del plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) per rendere disponibile il comando di configurazione del plugin.

129 </Step>129 </Step>

130 130

131 <Step title="Configura il tuo token">131 <Step title="Configura il tuo token">

channels-reference.md +1 −1

Details

170 170

171 Se l'evento non arriva, la diagnosi dipende da ciò che `curl` ha restituito:171 Se l'evento non arriva, la diagnosi dipende da ciò che `curl` ha restituito:

172 172

173 * **`curl` ha successo ma nulla raggiunge Claude**: esegui `/mcp` nella tua sessione per controllare lo stato del server. Uno stato `failed` di solito significa un errore di dipendenza o importazione nel tuo file server; controlla il log di debug in `~/.claude/debug/<session-id>.txt` per la traccia stderr.173 * **`curl` ha successo ma nulla raggiunge Claude**: esegui `/mcp` nella tua sessione per controllare lo stato del server. Uno stato `failed` di solito significa un errore di dipendenza o importazione nel tuo file server. Per vedere la traccia stderr, riavvia con `claude --debug --dangerously-load-development-channels server:webhook` e controlla il log di debug in `~/.claude/debug/<session-id>.txt`.

174 * **`curl` fallisce con "connessione rifiutata"**: la porta non è ancora associata o un processo stantio da un'esecuzione precedente la sta mantenendo. `lsof -i :<port>` mostra cosa sta ascoltando; `kill` il processo stantio prima di riavviare la tua sessione.174 * **`curl` fallisce con "connessione rifiutata"**: la porta non è ancora associata o un processo stantio da un'esecuzione precedente la sta mantenendo. `lsof -i :<port>` mostra cosa sta ascoltando; `kill` il processo stantio prima di riavviare la tua sessione.

175 </Step>175 </Step>

176</Steps>176</Steps>

checkpointing.md +12 −4

Details

12 Come funziona il checkpointing12 Come funziona il checkpointing

13</h2>13</h2>

14 14

~~15Mentre lavori con Claude, il checkpointing cattura automaticamente lo stato del tuo codice prima di ogni prompt dell'utente.~~15Mentre lavori con Claude, il checkpointing cattura automaticamente lo stato del tuo codice prima di ogni prompt che invii e che avvia un turno.

16 16

17<h3 id="automatic-tracking">17<h3 id="automatic-tracking">

18 Tracciamento automatico18 Tracciamento automatico

20 20

21Claude Code traccia tutti i cambiamenti effettuati dai suoi strumenti di modifica dei file:21Claude Code traccia tutti i cambiamenti effettuati dai suoi strumenti di modifica dei file:

22 22

~~23* Ogni prompt dell'utente crea un nuovo checkpoint~~23* Ogni prompt che invii e che avvia un turno crea un nuovo checkpoint

24* Claude Code mantiene snapshot dei file per i 100 checkpoint più recenti in una sessione. L'eliminazione di un checkpoint più vecchio cancella i file snapshot che nessun checkpoint rimanente referenzia, ad eccezione del primo snapshot di ogni file, che l'estensione VS Code utilizza come baseline per i suoi diff di sessione.24* Claude Code mantiene snapshot dei file per i 100 checkpoint più recenti in una sessione. L'eliminazione di un checkpoint più vecchio cancella i file snapshot che nessun checkpoint rimanente referenzia, ad eccezione del primo snapshot di ogni file, che l'estensione VS Code utilizza come baseline per i suoi diff di sessione.

25* Claude Code salva i checkpoint con la conversazione, quindi puoi comunque eseguire `/rewind` dopo aver ripreso una sessione25* Claude Code salva i checkpoint con la conversazione, quindi puoi comunque eseguire `/rewind` dopo aver ripreso una sessione

26* Claude Code elimina gli snapshot dei file di una sessione nella [retention sweep](/docs/it/claude-directory#cleaned-up-automatically), per impostazione predefinita circa 30 giorni dopo l'ultimo salvataggio della sessione. Il riavvolgimento a un checkpoint i cui snapshot sono scomparsi può fallire con [`No files were restored`](/docs/it/errors#no-files-were-restored). Per mantenere gli snapshot più a lungo, imposta [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays).26* Claude Code elimina gli snapshot dei file di una sessione nella [retention sweep](/docs/it/claude-directory#cleaned-up-automatically), per impostazione predefinita circa 30 giorni dopo l'ultimo salvataggio della sessione. Il riavvolgimento a un checkpoint i cui snapshot sono scomparsi può fallire con [`No files were restored`](/docs/it/errors#no-files-were-restored). Per mantenere gli snapshot più a lungo, imposta [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays).

35 Se il campo di input del prompt contiene testo, doppio `Esc` lo cancella invece di aprire il menu. Il testo cancellato viene salvato nella cronologia di input, quindi premi `Su` per richiamarlo dopo aver terminato nel menu di riavvolgimento.35 Se il campo di input del prompt contiene testo, doppio `Esc` lo cancella invece di aprire il menu. Il testo cancellato viene salvato nella cronologia di input, quindi premi `Su` per richiamarlo dopo aver terminato nel menu di riavvolgimento.

36</Note>36</Note>

37 37

~~38Il menu di riavvolgimento elenca ogni prompt che hai inviato durante la sessione. Seleziona il punto su cui desideri agire, quindi scegli un'azione:~~38Il menu di riavvolgimento elenca ogni prompt che hai inviato durante la sessione, ad eccezione dei [messaggi che si sono uniti a un turno in corso](#messages-sent-mid-turn-not-checkpointed). Seleziona il punto su cui desideri agire, quindi scegli un'azione:

39 39

40* **Ripristina codice e conversazione**: ripristina sia il codice che la conversazione a quel punto40* **Ripristina codice e conversazione**: ripristina sia il codice che la conversazione a quel punto

41* **Ripristina conversazione**: riavvolgi al messaggio mantenendo il codice attuale41* **Ripristina conversazione**: riavvolgi al messaggio mantenendo il codice attuale

93cp source.txt dest.txt93cp source.txt dest.txt

94```94```

95 95

96Queste modifiche ai file non possono essere annullate tramite riavvolgimento. Solo le modifiche dirette ai file effettuate attraverso gli strumenti di modifica dei file di Claude vengono tracciate.96Queste modifiche ai file non possono essere annullate tramite rewind. Solo le modifiche dirette ai file effettuate attraverso gli strumenti di modifica dei file di Claude vengono tracciate.

97 97

98<h3 id="subagent-edits-not-restored">98<h3 id="subagent-edits-not-restored">

99 Le modifiche dei subagent non vengono ripristinate99 Le modifiche dei subagent non vengono ripristinate

110 110

111Il checkpointing traccia solo i file che sono stati modificati nella sessione corrente. Le modifiche manuali che effettui ai file al di fuori di Claude Code e le modifiche da altre sessioni concorrenti normalmente non vengono acquisite, a meno che non modifichino gli stessi file della sessione corrente.111Il checkpointing traccia solo i file che sono stati modificati nella sessione corrente. Le modifiche manuali che effettui ai file al di fuori di Claude Code e le modifiche da altre sessioni concorrenti normalmente non vengono acquisite, a meno che non modifichino gli stessi file della sessione corrente.

112 112

113<h3 id="messages-sent-mid-turn-not-checkpointed">

114 I messaggi inviati a metà turno non vengono sottoposti a checkpoint

115</h3>

116

117Quando un messaggio che [metti in coda mentre Claude lavora](/docs/it/interactive-mode#queue-messages-while-claude-works) raggiunge Claude durante il turno in esecuzione, si unisce a quel turno invece di iniziarne uno nuovo. Il messaggio appare nella conversazione, ma Claude Code non crea un checkpoint per esso, e il menu di rewind non lo elenca. Un messaggio in coda che Claude Code invia come suo proprio turno riceve un checkpoint come al solito.

118

119Per rimuovere tale messaggio, o annullare le modifiche che Claude ha apportato dopo di esso, riavvolgi al prompt che ha avviato il turno. Questo riavvolge l'intero turno, incluso il lavoro che Claude ha svolto prima dell'arrivo del tuo messaggio.

120

113<h3 id="symlinked-and-hard-linked-paths-not-restored">121<h3 id="symlinked-and-hard-linked-paths-not-restored">

114 I percorsi symlink e hard-link non vengono ripristinati122 I percorsi symlink e hard-link non vengono ripristinati

115</h3>123</h3>

claude-apps-gateway.md +11 −6

Details

135 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).135 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).

136 136

137 <Note>137 <Note>

138 L'upstream Amazon 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 il modulo di caso d'uso una tantum di Anthropic inviato per l'account dalla console Bedrock Model catalog. 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.138 L'upstream Amazon 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. Ha anche bisogno del modulo di caso d'uso una tantum di Anthropic inviato per l'account dalla console Bedrock Model catalog. 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.

139 </Note>139 </Note>

140 </Step>140 </Step>

141 141

287}287}

288```288```

289 289

290Lo sviluppatore preme Invio per connettersi. Il [prompt dell'impronta digitale TLS del primo collegamento](#connect-developers) appare ancora.290Lo sviluppatore preme Invio per connettersi. Il [prompt dell'impronta digitale TLS del primo collegamento](#connect-developers) appare ancora. Una volta che il file è su una macchina, uno sviluppatore che non ha completato l'accesso al gateway vede uno dei messaggi descritti in [La politica dell'amministratore richiede un accesso al Cloud gateway](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in). Gli sviluppatori che selezionano un provider cloud attraverso una variabile di ambiente come `CLAUDE_CODE_USE_BEDROCK` non hanno bisogno dell'accesso al gateway.

291 291

292Uno sviluppatore non può configurare questo manualmente. Il selettore di accesso non ha opzione gateway 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". Le chiavi di accesso appartengono al file che spingere alle macchine, non al blocco `managed.policies[].cli` del gateway, che raggiunge solo i client già connessi.292Uno sviluppatore non può configurare questo manualmente. Il selettore di accesso non ha opzione gateway 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". Le chiavi di accesso appartengono al file che spingere alle macchine, non al blocco `managed.policies[].cli` del gateway, che raggiunge solo i client già connessi.

293 293

423Queste garanzie si applicano a ogni sessione connessa tramite `/login`. Le sessioni incorporate che Claude Desktop avvia ottengono la loro politica come descritto in [Consegna la politica alle sessioni di Claude Desktop](#deliver-policy-to-claude-desktop-sessions) e il punto di telemetria dice dove vanno le loro esportazioni.423Queste garanzie si applicano a ogni sessione connessa tramite `/login`. Le sessioni incorporate che Claude Desktop avvia ottengono la loro politica come descritto in [Consegna la politica alle sessioni di Claude Desktop](#deliver-policy-to-claude-desktop-sessions) e il punto di telemetria dice dove vanno le loro esportazioni.

424 424

425* **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.425* **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.

426* **Destinazione telemetria**: nelle sessioni connesse tramite `/login`, il CLI invia le sue esportazioni OTLP/HTTP al gateway indipendentemente da qualsiasi `OTEL_EXPORTER_OTLP_ENDPOINT` impostato localmente e il gateway le inoltra alle destinazioni in [`telemetry.forward_to`](/docs/it/claude-apps-gateway-config#telemetry). Nelle sessioni incorporate che [Claude Desktop avvia](#connect-claude-desktop), il CLI invia le sue esportazioni all'`OTEL_EXPORTER_OTLP_ENDPOINT` configurato. Il CLI allega il token di sessione del gateway a quelle esportazioni solo quando quell'endpoint punta al gateway stesso. Senza una destinazione configurata per un segnale, il gateway lo accetta e lo scarta, quindi se raccogli già la telemetria di Claude Code direttamente, aggiungi il tuo raccoglitore come destinazione `forward_to`.426* **Destinazione telemetria**: nelle sessioni connesse tramite `/login`, il CLI invia le sue esportazioni OTLP/HTTP al gateway piuttosto che a un `OTEL_EXPORTER_OTLP_ENDPOINT` impostato localmente, a meno che una politica non [nomini il tuo raccoglitore come endpoint](/docs/it/claude-apps-gateway-config#export-directly-to-your-collector). Il gateway inoltra le esportazioni che riceve alle destinazioni in [`telemetry.forward_to`](/docs/it/claude-apps-gateway-config#telemetry).

427* **Credenziali**: il token del gateway è l'unica credenziale della sessione. `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `apiKeyHelper`, [profili Anthropic](/docs/it/authentication#anthropic-profiles-and-federation-credentials) e qualsiasi accesso precedente a claude.ai vengono ignorati mentre connesso, quindi gli sviluppatori non hanno bisogno di disconnettersi da claude.ai per primo.427 * Nelle sessioni incorporate che [Claude Desktop avvia](#connect-claude-desktop), il CLI invia le sue esportazioni all'`OTEL_EXPORTER_OTLP_ENDPOINT` configurato. Il CLI allega il token di sessione del gateway a quelle esportazioni solo quando quell'endpoint punta al gateway stesso.

428 * Senza una destinazione configurata per un segnale, il gateway lo accetta e lo scarta.

429 * Se raccogli già la telemetria di Claude Code direttamente, aggiungi il tuo raccoglitore come destinazione `forward_to` o nominalo in una politica per saltare il relay.

430* **Credenziali**: il token del gateway è l'unica credenziale della sessione. [Profili Anthropic](/docs/it/authentication#anthropic-profiles-and-federation-credentials) e qualsiasi accesso precedente a claude.ai vengono ignorati mentre connesso, quindi gli sviluppatori non hanno bisogno di disconnettersi da claude.ai per primo. Per una credenziale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` o `apiKeyHelper` configurata, vedi [La politica dell'amministratore richiede un accesso al Cloud gateway](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in).

428* **Impostazioni gestite**: le chiavi bloccate non possono essere ignorate localmente. Il CLI applica la politica all'avvio e applica le modifiche su ogni sondaggio orario, a parte le [modifiche che si applicano solo al prossimo avvio](/docs/it/server-managed-settings#fetch-and-caching-behavior).431* **Impostazioni gestite**: le chiavi bloccate non possono essere ignorate localmente. Il CLI applica la politica all'avvio e applica le modifiche su ogni sondaggio orario, a parte le [modifiche che si applicano solo al prossimo avvio](/docs/it/server-managed-settings#fetch-and-caching-behavior).

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

430* **Avvio dopo che il gateway termina la sessione**: vedi [Applica fail-closed startup](/docs/it/server-managed-settings#enforce-fail-closed-startup) per quali avvii si aprono disconnessi dal gateway e quali escono quando il gateway risponde con un `401`.433* **Avvio dopo che il gateway termina la sessione**: vedi [Applica fail-closed startup](/docs/it/server-managed-settings#enforce-fail-closed-startup) per i lanci che si aprono disconnessi dal gateway e quelli che escono quando il gateway risponde con un `401`.

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

432 435

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

455| 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 |458| 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 |

456| [Remote Control](/docs/it/remote-control) | Non disponibile | Il CLI mostra [un errore che nomina il gateway](/docs/it/errors#remote-control-requires-the-anthropic-api) |459| [Remote Control](/docs/it/remote-control) | Non disponibile | Il CLI mostra [un errore che nomina il gateway](/docs/it/errors#remote-control-requires-the-anthropic-api) |

457| Caching del prompt standard | Disponibile | Il gateway inoltri i breakpoint `cache_control` a ogni upstream, e il CLI contrassegna il [contesto di sistema che aggiunge a metà conversazione](/docs/it/prompt-caching#where-the-cache-lives) per il caching sulle sessioni del gateway, come fa su ogni altro provider e connessione. |460| [`/design-sync`](/docs/it/commands#all-commands) e `/design-login` | Non disponibile | Entrambi hanno bisogno di claude.ai, che il CLI non contatta sulle sessioni del gateway, quindi nessuno dei due comandi appare lì |

461| Funzionalità che necessitano di recupero dei flag di funzionalità, come `/import` e `claude import` | Non disponibile | Il CLI salta il recupero dei flag sulle sessioni del gateway. [Funzionalità che necessitano di recupero dei flag di funzionalità](/docs/it/env-vars#features-that-need-feature-flag-fetching) elenca cosa questo disattiva |

462| Caching del prompt standard | Disponibile | Il gateway inoltri i breakpoint `cache_control` a ogni upstream. [Dove risiede la cache](/docs/it/prompt-caching#where-the-cache-lives) copre quali blocchi il CLI contrassegna, incluso il contesto di sistema che aggiunge a metà conversazione |

458| 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 |463| 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 |

459| 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. 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 |464| 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. 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 |

460| 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 |465| 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 |

claude-apps-gateway-config.md +93 −26

Details

32 32

33* [`admin`](#admin): autenticazione dell'API Admin e conservazione dei limiti di spesa33* [`admin`](#admin): autenticazione dell'API Admin e conservazione dei limiti di spesa

34* [`enforcement`](#enforcement): comportamento fail-open o fail-closed dei limiti di spesa34* [`enforcement`](#enforcement): comportamento fail-open o fail-closed dei limiti di spesa

~~35* [`pricing`](#pricing): tariffe contrattuali e un moltiplicatore di sconto per il misuratore di spesa~~35* [`pricing`](#pricing): tariffe contrattuali e un moltiplicatore di sconto per il misuratore di spesa e per le cifre di costo che gli sviluppatori vedono

36* [`models`](#models) e `auto_include_builtin_models`: elenco di modelli curato dall'amministratore e ID per upstream36* [`models`](#models) e `auto_include_builtin_models`: elenco di modelli curato dall'amministratore e ID per upstream

37* [`managed`](#managed): politiche di impostazioni gestite per gruppo IdP37* [`managed`](#managed): politiche di impostazioni gestite per gruppo IdP

38* [`telemetry`](#telemetry): inoltro OTLP al vostro stack di osservabilità38* [`telemetry`](#telemetry): inoltro OTLP al vostro stack di osservabilità

136 `upstreams`136 `upstreams`

137</h3>137</h3>

138 138

139`upstreams` è un elenco ordinato. Il gateway inoltra l'inferenza al primo upstream che risolve il modello richiesto. Su `5xx`, `429`, `401`, `403`, `404` o timeout esegue il failover al successivo; altri `4xx` no, perché questi errori sono attribuibili alla richiesta piuttosto che all'upstream. Un `401` o `403` significa che la credenziale del gateway stesso non ha funzionato contro quell'upstream, e un `404` significa che quell'upstream non serve il modello richiesto, quindi un upstream successivo nell'elenco può ancora servirlo.139`upstreams` è un elenco ordinato. Il gateway inoltra l'inferenza al primo upstream che risolve il modello richiesto.

140

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

142

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

140 144

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

142 146

228 232

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

230 234

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

236

231Impostate `forward_user_identity` solo su un upstream il cui `base_url` è un proxy che gestite. Il gateway invia email degli sviluppatori a qualsiasi server che `base_url` nomina. Se `base_url` è l'API Anthropic, che è il predefinito, il gateway si rifiuta di avviarsi.237Impostate `forward_user_identity` solo su un upstream il cui `base_url` è un proxy che gestite. Il gateway invia email degli sviluppatori a qualsiasi server che `base_url` nomina. Se `base_url` è l'API Anthropic, che è il predefinito, il gateway si rifiuta di avviarsi.

232 238

233<h4 id="amazon-bedrock">239<h4 id="amazon-bedrock">

367 373

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

369 375

370`429` è capacità per upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover a on-demand. `404` è disponibilità del modello per upstream, quindi un upstream che non ha abilitato un modello non blocca un upstream successivo che lo serve. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete.376`429` è capacità per upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover a on-demand. Se impostate [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) su un upstream, un `429` a una richiesta che portava l'email dello sviluppatore è un rifiuto per utente invece e non esegue il failover.

377

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

371 379

372Questo esempio instrada un'allocazione Bedrock di throughput provisioned per primo, trabocca a on-demand e un secondo account e ricade all'API Anthropic per ultimo:380Questo esempio instrada un'allocazione Bedrock di throughput provisioned per primo, trabocca a on-demand e un secondo account e ricade all'API Anthropic per ultimo:

373 381

473Il blocco `pricing` dice al misuratore di spesa cosa addebitare invece del prezzo di listino USD, quindi i cap e [`/effective`](/docs/it/claude-apps-gateway-spend-limits#%2Feffective) riflettono le vostre tariffe contrattuali. Gli importi rimangono in USD e rimangono una stima, non una fattura. Due prerequisiti:481Il blocco `pricing` dice al misuratore di spesa cosa addebitare invece del prezzo di listino USD, quindi i cap e [`/effective`](/docs/it/claude-apps-gateway-spend-limits#%2Feffective) riflettono le vostre tariffe contrattuali. Gli importi rimangono in USD e rimangono una stima, non una fattura. Due prerequisiti:

474 482

475* Claude Code v2.1.227 o successivo sul server gateway. Le versioni precedenti rifiutano la chiave sconosciuta all'avvio.483* Claude Code v2.1.227 o successivo sul server gateway. Le versioni precedenti rifiutano la chiave sconosciuta all'avvio.

476* Un blocco [`admin:`](#admin), perché solo il misuratore di spesa legge `pricing`. Il gateway rifiuta di avviarsi con `pricing` impostato e nessun `admin`.484* Un blocco [`admin:`](#admin) o, in v2.1.268 o successivo, un blocco [`managed:`](#managed) con almeno una politica. Il gateway rifiuta di avviarsi con `pricing` impostato e nessuno dei due blocchi, perché nulla lo leggerebbe.

477 485

478```yaml theme={null}486```yaml theme={null}

479pricing:487pricing:

491| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |499| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

492| `multiplier` | No | Predefinito `1`. Il misuratore moltiplica ogni importo misurato per questo, sia che sia a prezzo di listino che sovrascritto, quindi `0.85` addebita l'85% del prezzo. Deve essere maggiore di 0 e al massimo 1. |500| `multiplier` | No | Predefinito `1`. Il misuratore moltiplica ogni importo misurato per questo, sia che sia a prezzo di listino che sovrascritto, quindi `0.85` addebita l'85% del prezzo. Deve essere maggiore di 0 e al massimo 1. |

493| `overrides` | No | Righe di `{upstream, model, input, output, cache_read, cache_write}` in USD per milione di token. Tutti e quattro i tassi sono obbligatori e devono essere positivi. |501| `overrides` | No | Righe di `{upstream, model, input, output, cache_read, cache_write}` in USD per milione di token. Tutti e quattro i tassi sono obbligatori. Ognuno deve essere maggiore di 0 e al massimo 10000. |

494 502

495Come il misuratore corrisponde a una riga di override:503Come il misuratore corrisponde a una riga di override:

496 504

502 510

503Per tariffe per regione, date a ogni regione il suo upstream denominato e una riga per upstream.511Per tariffe per regione, date a ogni regione il suo upstream denominato e una riga per upstream.

504 512

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

514 Inviare le tariffe ai client firmati

515</h4>

516

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

518

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

520* Escludere una politica: impostate `modelPricing` a `{}` nel blocco `cli` di quella politica, e i suoi sviluppatori rimangono al prezzo di listino.

521* Mantenere le tariffe proprie di una politica: una politica il cui blocco `cli` imposta `modelPricing` con il suo proprio `multiplier` o `overrides` mantiene quel `modelPricing` intero, e il gateway non aggiunge tariffe proprie ad esso.

522

505<h3 id="models">523<h3 id="models">

506 `models`524 `models`

507</h3>525</h3>

696* L'elenco dei modelli, da `availableModels`714* L'elenco dei modelli, da `availableModels`

697* Strumenti disabilitati, da voci `permissions.deny` di nome di strumento nudo. Se impostate `disabledBuiltinTools` nel blocco `desktop` della politica, il gateway serve l'unione del vostro valore e dell'elenco derivato, quindi potete disabilitare più strumenti in questo modo ma non potete ri-abilitarne uno che avete disabilitato tramite `permissions.deny`715* Strumenti disabilitati, da voci `permissions.deny` di nome di strumento nudo. Se impostate `disabledBuiltinTools` nel blocco `desktop` della politica, il gateway serve l'unione del vostro valore e dell'elenco derivato, quindi potete disabilitare più strumenti in questo modo ma non potete ri-abilitarne uno che avete disabilitato tramite `permissions.deny`

698* L'allowlist di uscita, da `sandbox.network.allowedDomains`. Se impostate `coworkEgressAllowedHosts` nel blocco `desktop` della politica, il gateway usa quel valore invece dell'elenco derivato716* L'allowlist di uscita, da `sandbox.network.allowedDomains`. Se impostate `coworkEgressAllowedHosts` nel blocco `desktop` della politica, il gateway usa quel valore invece dell'elenco derivato

699* Un endpoint OTLP che punta al gateway stesso, che si diffonde alle vostre destinazioni, incluso quando l'inoltro di [`telemetry`](#telemetry) è configurato.717* Un endpoint OTLP che punta al gateway stesso, e gli attributi di identità dell'utente firmato. Il gateway inoltra le esportazioni che riceve a quell'endpoint alle vostre destinazioni `forward_to`. Include l'endpoint e gli attributi quando impostate sia [`telemetry.forward_to`](#telemetry) che `listen.public_url`.

700 718

701 Claude Desktop esporta ogni segnale con una codifica: `http/protobuf`, o `http/json` quando impostate `OTEL_EXPORTER_OTLP_PROTOCOL` o uno dei suoi varianti per segnale a `http/json` nel `env` della politica. Prima di Claude Code v2.1.261 sul server gateway, la risposta impostava `http/json` indipendentemente, quindi un collettore che accetta solo protobuf rifiutava le esportazioni di Claude Desktop719 Claude Desktop esporta ogni segnale con una codifica: `http/protobuf`, o `http/json` quando impostate `OTEL_EXPORTER_OTLP_PROTOCOL` o uno dei suoi varianti per segnale a `http/json` nel `env` della politica. Prima di Claude Code v2.1.261 sul server gateway, la risposta impostava `http/json` indipendentemente, quindi un collettore che accetta solo protobuf rifiutava le esportazioni di Claude Desktop

702 720

754 `telemetry`772 `telemetry`

755</h3>773</h3>

756 774

757La CLI invia OpenTelemetry Protocol (OTLP) su metriche HTTP, log e, quando abilitato, tracce al gateway, che le inoltra verbatim a ogni destinazione configurata. Vedere [Monitoraggio dell'utilizzo](/docs/it/monitoring-usage) per le metriche e gli eventi che la CLI emette.775La CLI invia metriche, log e, quando abilitato, tracce al gateway, che le inoltra verbatim a ogni destinazione configurata. Le esportazioni utilizzano OpenTelemetry Protocol (OTLP) su HTTP. Per saltare il relè e avere sessioni esportate direttamente al vostro collettore, [nominate il collettore in una politica](#export-directly-to-your-collector). Vedere [Monitoraggio dell'utilizzo](/docs/it/monitoring-usage) per le metriche e gli eventi che la CLI emette.

758 776

759La CLI timbra ogni esportazione con l'identità dell'utente autenticato, letta dal JWT emesso dal gateway: gli attributi `user.id`, `user.email` e `user.groups`. L'attribuzione del costo e dell'utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore.777La CLI timbra ogni esportazione con l'identità dell'utente autenticato, letta dal JWT emesso dal gateway: gli attributi `user.id`, `user.email` e `user.groups`. L'attribuzione del costo e dell'utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore.

760 778

779[Claude Desktop](#claude-desktop-overlay) e le sessioni Cowork firmate tramite il gateway timbrano la loro telemetria con `user.email` e `user.groups` insieme a `enduser.id`, quindi potete coprire l'utilizzo di terminale, Desktop e Cowork con una query su `user.email` o `user.groups`. `user.groups` è l'elenco di gruppi IdP separato da virgole.

780

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

782

783Se l'elenco di gruppi di un utente è più lungo di 255 caratteri una volta percent-encoded, o un nome di gruppo contiene una virgola o un segno di uguale, il gateway lascia `user.groups` fuori dalla telemetria Desktop e Cowork di quell'utente piuttosto che troncarla. Le sessioni di terminale di quell'utente portano comunque l'elenco completo.

784

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

786

761```yaml theme={null}787```yaml theme={null}

762telemetry:788telemetry:

763 forward_to:789 forward_to:

789 815

790Per un collettore in-cluster, esponetelo su HTTPS al suo indirizzo interno, o eseguitelo come sidecar con la variabile impostata.816Per un collettore in-cluster, esponetelo su HTTPS al suo indirizzo interno, o eseguitelo come sidecar con la variabile impostata.

791 817

792La telemetria è disattivata nella CLI per impostazione predefinita. La configurazione di `telemetry.forward_to` insieme a `listen.public_url` la attiva. Il gateway spinge sei variabili env a ogni client connesso tramite `/managed/settings`:818La telemetria è disattivata nella CLI per impostazione predefinita. Quando impostate sia `telemetry.forward_to` che `listen.public_url`, il gateway la attiva per i client connessi spingendo sei variabili di ambiente tramite `/managed/settings`:

793 819

794* `CLAUDE_CODE_ENABLE_TELEMETRY=1`820* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

795* `OTEL_METRICS_EXPORTER=otlp`821* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` e `OTEL_TRACES_EXPORTER`, ognuno impostato a `otlp` se almeno una destinazione `forward_to` abilita quel segnale e a `none` altrimenti

796* `OTEL_LOGS_EXPORTER=otlp`

797* `OTEL_TRACES_EXPORTER=otlp`

798* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`822* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

799* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`823* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

800 824

801L'endpoint spinto è costruito dall'URL pubblico, quindi le metriche e i log non hanno bisogno di alcuna configurazione OTEL da sviluppatori o politiche. La configurazione spinta viene applicata al livello gestito, sovrascrivendo le variabili `OTEL_*` che uno sviluppatore imposta localmente. Indipendentemente dal fatto che il gateway spinga queste variabili, una CLI firmata tramite `/login` che ha l'esportazione OTLP/HTTP abilitata invia le sue esportazioni al gateway piuttosto che a un endpoint configurato localmente, e senza una destinazione `forward_to` per un segnale il gateway accetta e scarta; se raccogliete già la telemetria di Claude Code direttamente, aggiungete il vostro collettore come destinazione `forward_to`.825Prima di Claude Code v2.1.265 sul server gateway, il gateway spingeva tutti e tre i selettori di esportazione come `otlp`, incluso per i segnali che nessuna destinazione ha abilitato.

826

827L'endpoint spinto è costruito dall'URL pubblico, quindi le metriche e i log non hanno bisogno di alcuna configurazione OTEL da sviluppatori o politiche.

828

829Gli sviluppatori firmati tramite `/login` non possono reindirizzare le esportazioni con la loro propria configurazione OTEL:

830

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

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

833

834Senza una destinazione `forward_to` per un segnale, il gateway accetta e scarta. Se gli sviluppatori già esportano la telemetria di Claude Code a uno dei vostri collettori, aggiungete come destinazione `forward_to`, con log o tracce abilitate se esportano quelli, quindi continua a ricevere i loro dati dopo che si firmano. Per saltare il relè invece, [nominate il collettore in una politica](#export-directly-to-your-collector).

835

836[Le tracce](/docs/it/monitoring-usage#traces-beta) richiedono inoltre `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` su ogni client. Impostatela nel blocco `env` di una politica gestita, poiché il gateway non la spinge. Gli sviluppatori l'approvano nella stessa [finestra di dialogo di approvazione della sicurezza](#managed) che l'endpoint OTLP spinto già attiva.

802 837

803Le [tracce](/docs/it/monitoring-usage#traces-beta) richiedono inoltre `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` su ogni client. Il gateway non spinge quella variabile, quindi impostatela tramite il blocco `env` di una politica gestita. Non è tra le variabili che Claude Code applica senza l'approvazione dello sviluppatore, quindi consegnarla tramite una politica è coperto dalla stessa [finestra di dialogo di approvazione della sicurezza](#managed) che l'endpoint OTLP spinto già attiva.838Impostatela a `1` solo nelle politiche i cui gruppi desiderate tracciati. Una politica che non la imposta eredita il valore dal vostro `match: {}` politica catch-all se quella politica ne imposta uno, per le [regole di unione](#managed). Per impedire ai client di un gruppo di inviare tracce anche quando uno sviluppatore imposta la variabile localmente, impostatela a `0` nella politica di quel gruppo.

804 839

805Sia le codifiche OTLP protobuf che JSON vengono inoltrate, e qualsiasi backend compatibile con OpenTelemetry funziona come destinazione.840Sia le codifiche OTLP protobuf che JSON vengono inoltrate, e qualsiasi backend compatibile con OpenTelemetry funziona come destinazione.

806 841

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

843 Esportare direttamente al vostro collettore

844</h4>

845

846Per avere sessioni firmate tramite `/login` inviare telemetria direttamente al vostro collettore invece che tramite il relè, impostate `OTEL_EXPORTER_OTLP_ENDPOINT` all'URL di base `https://` del collettore nel blocco `env` di una [politica gestita](#managed). Claude Code aggiunge `/v1/metrics`, `/v1/logs` o `/v1/traces` all'URL che impostate, come `https://otel-collector.example.com:4318`, ed esporta ogni segnale lì su OTLP/HTTP. Richiede Claude Code v2.1.265 o successivo su ogni macchina dello sviluppatore. I client precedenti esportano tramite il relè.

847

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

849

850Quando aggiungete o cambiate questo endpoint in una politica, Claude Code chiede a ogni sviluppatore di approvarlo nella [finestra di dialogo di approvazione della sicurezza](#managed) prima di applicarlo in una sessione interattiva.

851

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

853

854* L'endpoint viene dal gateway stesso. Se impostate la stessa variabile in un profilo MDM o un `managed-settings.json` locale, le esportazioni rimangono sul relè.

855* L'URL usa `https://`, o `http://` a un indirizzo loopback

856* L'URL si risolve a un percorso che termina in `/v1/<signal>`, senza query o frammento. Claude Code costruisce quel percorso stesso dalla variabile generica. Usa una variabile per segnale come `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` come scritto, quindi includi il percorso completo lì.

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

858* Né voi né lo sviluppatore avete configurato [`otelHeadersHelper`](/docs/it/settings-reference#otelheadershelper) in alcuna fonte di impostazioni. Con un helper configurato, ogni segnale rimane sul relè.

859

860L'endpoint che nominate cambia solo dove vanno le esportazioni. Scegliete comunque quali segnali esportano affatto con i selettori `OTEL_*_EXPORTER`.

861

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

863

864* Se il gateway già [spinge le variabili di telemetria](#telemetry), coprono l'abilitazione, i selettori e il protocollo, e il vostro endpoint esplicito sovrascrive il valore `<public_url>` spinto. Impostate un selettore `OTEL_*_EXPORTER` a `otlp` voi stessi solo per un segnale che nessuna destinazione `forward_to` abilita.

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

866

867Quando lo sviluppatore si firma, o si firma a un gateway diverso, le esportazioni al collettore si fermano e Claude Code scarta ogni batch rimanente piuttosto che inviarlo.

868

869<h4 id="when-a-destination-fails">

870 Quando una destinazione fallisce

871</h4>

872

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

874

875Dopo cinque consegne consecutive fallite a una destinazione, il gateway pausa l'inoltro ad essa in tratti di 30 secondi, registrando ogni pausa, finché una consegna ha successo. Qualsiasi risposta di errore, timeout o errore di connessione conta come una consegna fallita, eccetto `400`, `413`, `415`, `422` e `431`, che significano che il collettore ha rifiutato il payload di quell'esportazione come malformato o troppo grande.

876

877Un payload rifiutato non avanza né ripristina il conteggio dei fallimenti: il gateway continua a inoltrare alla destinazione e registra un avviso che la nomina e lo stato, al primo rifiuto della destinazione e ogni centesimo dopo.

878

807<h3 id="http-tuning">879<h3 id="http-tuning">

808 Sintonizzazione HTTP880 Sintonizzazione HTTP

809</h3>881</h3>

891# fail_closed_on_error: false963# fail_closed_on_error: false

892 964

893# Meter at contracted rates instead of USD list price. Requires admin:.965# Meter at contracted rates instead of USD list price. Requires admin:.

966# With managed:, the same rates also go to signed-in clients.

894# Rates below are placeholders, not real contract prices.967# Rates below are placeholders, not real contract prices.

895# pricing:968# pricing:

896# multiplier: 0.85969# multiplier: 0.85

970 Impostazioni gestite lato client1043 Impostazioni gestite lato client

971</h2>1044</h2>

972 1045

973Tutto quanto sopra configura il server del gateway. Puntare le macchine degli sviluppatori al gateway è configurato separatamente, su ogni dispositivo, tramite le [impostazioni gestite](/docs/it/managed-settings) di Claude Code. Il gateway non può spingere le chiavi di accesso stesso, perché sono ciò che dice al client dove si trova il gateway.1046Tutto quanto sopra configura il server gateway. Puntate le macchine degli sviluppatori al gateway separatamente, su ogni dispositivo, attraverso le [impostazioni gestite](/docs/it/managed-settings) di Claude Code. Il gateway non può inviare le chiavi di accesso stesso, perché sono loro che indicano al client dove si trova il gateway.

974 1047

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

976 1049

977```json theme={null}1050```json theme={null}

978{1051{

982}1055}

983```1056```

984 1057

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

~~986~~

987Distribuire il file `managed-settings.json` a ogni dispositivo, tipicamente tramite la vostra piattaforma MDM. Il percorso del file differisce per piattaforma:

988 1059

989| Piattaforma | Percorso |1060Distribuite il file `managed-settings.json` a ogni dispositivo, tipicamente tramite la vostra piattaforma MDM. Il percorso del file differisce per piattaforma. Consultate [dove ogni meccanismo memorizza la policy](/docs/it/managed-settings#where-each-mechanism-stores-the-policy).

990| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |

991| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json`, o il dominio delle preferenze gestite `com.anthropic.claudecode` |

992| Linux e WSL | `/etc/claude-code/managed-settings.json` |

993| Windows | `C:\Program Files\ClaudeCode\managed-settings.json`, o Group Policy tramite il registro HKLM |

994 1061

995Per impostazione predefinita, una politica del registro su Windows o un plist delle preferenze gestite su macOS sostituisce il file `managed-settings.json` piuttosto che unirsi ad esso, a parte le [chiavi di eccezione e i controlli tra fonti sopra](#precedence-with-other-managed-sources). Tutte e tre le chiavi in questo frammento seguono la regola della fonte con priorità più alta, quindi le flotte che consegnano la politica tramite Group Policy o profili di configurazione devono inserire tutte e tre in quel meccanismo.1062Per impostazione predefinita, una policy del registro su Windows o un plist di preferenze gestite su macOS sostituisce il file `managed-settings.json` piuttosto che unirsi ad esso, ad eccezione delle [chiavi di eccezione e dei controlli tra fonti sopra](#precedence-with-other-managed-sources). Tutte e tre le chiavi in questo frammento seguono la regola della fonte con priorità più alta, quindi i fleet che distribuiscono la policy tramite Group Policy o profili di configurazione devono inserire tutte e tre in quel meccanismo invece.

996 1063

997Per Claude Desktop, impostate la chiave `bootstrapUrl` nella propria [configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop su `<listen.public_url>/user/bootstrap`. Il flusso di accesso e la politica per gruppo corrispondono quindi a quelli della CLI una volta che una politica si attiva lato server con una chiave `desktop`; senza l'opt-in, `/user/bootstrap` restituisce 404. Vedere [Claude Desktop overlay](#claude-desktop-overlay) per la metà lato server.1064Per Claude Desktop, impostate la chiave `bootstrapUrl` nella propria [configurazione gestita](https://claude.com/docs/third-party/claude-desktop/configuration) di Claude Desktop su `<listen.public_url>/user/bootstrap`. Il flusso di accesso e la policy per gruppo corrispondono quindi a quelli della CLI una volta che una policy si attiva lato server con una chiave `desktop`; senza l'opt-in, `/user/bootstrap` restituisce 404. Consultate [Claude Desktop overlay](#claude-desktop-overlay) per la metà lato server.

998 1065

999[`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl) e il valore `"gateway"` di [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) sono onorati solo da una fonte gestita sulla macchina: `managed-settings.json`, il plist macOS o il registro HKLM di Windows, o un helper di politica. Uno sviluppatore che li imposta nel suo `~/.claude/settings.json` non ha effetto, e nemmeno impostarli nel payload del gateway.1066[`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl) e il valore `"gateway"` di [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) sono rispettati solo da una fonte gestita sulla macchina: `managed-settings.json`, il plist macOS o il registro HKLM di Windows, o un policy helper. Uno sviluppatore che li imposta nel proprio `~/.claude/settings.json` non ha alcun effetto, e nemmeno impostarli nel payload del gateway.

1000 1067

1001<h2 id="related">1068<h2 id="related">

1002 Correlati1069 Correlati

claude-apps-gateway-deploy.md +14 −5

Details

62 62

63Ogni topologia di produzione qui mette un proxy L7, come un Ingress, il front-end di Cloud Run, o un ALB, davanti alle repliche HTTP semplici. Imposta [`listen.trusted_proxies`](/docs/it/claude-apps-gateway-config#listen) agli intervalli di origine del proxy in modo che il gateway legga gli IP client da `X-Forwarded-For`. Il gateway onora l'intestazione solo quando il peer TCP è affidabile. Gli [esempi elaborati di Google Cloud](/docs/it/claude-apps-gateway-on-gcp) e [AWS](/docs/it/claude-apps-gateway-on-aws) hanno valori concreti per topologia. Senza proxy affidabili, ogni richiesta sembra provenire dall'IP del proxy, il che comprime i limiti di velocità per IP in un bucket condiviso e registra l'IP del proxy negli eventi di audit.63Ogni topologia di produzione qui mette un proxy L7, come un Ingress, il front-end di Cloud Run, o un ALB, davanti alle repliche HTTP semplici. Imposta [`listen.trusted_proxies`](/docs/it/claude-apps-gateway-config#listen) agli intervalli di origine del proxy in modo che il gateway legga gli IP client da `X-Forwarded-For`. Il gateway onora l'intestazione solo quando il peer TCP è affidabile. Gli [esempi elaborati di Google Cloud](/docs/it/claude-apps-gateway-on-gcp) e [AWS](/docs/it/claude-apps-gateway-on-aws) hanno valori concreti per topologia. Senza proxy affidabili, ogni richiesta sembra provenire dall'IP del proxy, il che comprime i limiti di velocità per IP in un bucket condiviso e registra l'IP del proxy negli eventi di audit.

64 64

65Non reindirizzare le richieste agli endpoint di autorizzazione del dispositivo e token del gateway. Claude Code non segue i reindirizzamenti su quelle richieste, quindi una regola di ingress che le reindirizza, come una riscrittura HTTP-to-HTTPS o di canonicalizzazione dell'host, interrompe l'accesso e l'aggiornamento del token.65Non reindirizzare le richieste agli endpoint di autorizzazione del dispositivo e token del gateway, ad esempio con una riscrittura HTTP-to-HTTPS o di canonicalizzazione dell'host all'ingress. Claude Code non segue i reindirizzamenti su quelle richieste, quindi una regola di ingress che le reindirizza interrompe l'accesso e l'aggiornamento del token.

66 66

67Dai al proxy un timeout di inattività più lungo dell'intervallo di keepalive del gateway, che dipende dall'upstream:67Dai al proxy un timeout di inattività più lungo dell'intervallo di keepalive del gateway, che dipende dall'upstream:

68 68

120 Invia l'URL del gateway alle macchine degli sviluppatori120 Invia l'URL del gateway alle macchine degli sviluppatori

121</h3>121</h3>

122 122

123Una volta che il gateway è in servizio, invia `forceLoginMethod`, `forceLoginGatewayUrl` e `parentSettingsBehavior: "merge"` a ogni macchina dello sviluppatore tramite impostazioni gestite, tramite MDM o scrivendo direttamente il `managed-settings.json` per OS. Senza questo, `/login` mostra il selettore di account standard senza opzione gateway. Consulta [Impostazioni gestite lato client](/docs/it/claude-apps-gateway-config#client-side-managed-settings) per i percorsi dei file e l'equivalente `bootstrapUrl` di Claude Desktop.123Una volta che il gateway è in servizio, invia `forceLoginMethod`, `forceLoginGatewayUrl` e `parentSettingsBehavior: "merge"` a ogni macchina dello sviluppatore tramite impostazioni gestite, tramite MDM o scrivendo direttamente il `managed-settings.json` per OS. Senza questo, `/login` mostra il selettore di account standard senza opzione gateway.

124

125Una volta che distribuisci le chiavi, Claude Code smette di utilizzare una chiave API rimasta o un accesso a claude.ai sulla macchina, quindi pianifica il push insieme alle tue istruzioni di accesso. [La policy dell'amministratore richiede un accesso al gateway Cloud](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in) descrive i messaggi che gli sviluppatori vedono.

126

127Consulta [dove ogni meccanismo memorizza la policy](/docs/it/managed-settings#where-each-mechanism-stores-the-policy) per i percorsi dei file, e [Impostazioni gestite lato client](/docs/it/claude-apps-gateway-config#client-side-managed-settings) per l'equivalente `bootstrapUrl` di Claude Desktop.

124 128

125<h2 id="operations">129<h2 id="operations">

126 Operazioni130 Operazioni

136 140

137* **Eventi di audit**: JSON a riga singola per evento rilevante per la sicurezza. Invia stderr al tuo aggregatore di log. Gli eventi emessi includono `config.load`, `session.mint`, `session.refresh`, `device.authorize`, `device.verify`, `device.callback`, `auth.denied`, `access.denied`, `inference`, `managed.serve`, `desktop_bootstrap.serve`, `desktop_bootstrap.denied`, `spend.blocked`, `admin.denied`, `admin.limit.upsert`, e `admin.limit.delete`. I campi variano per evento:141* **Eventi di audit**: JSON a riga singola per evento rilevante per la sicurezza. Invia stderr al tuo aggregatore di log. Gli eventi emessi includono `config.load`, `session.mint`, `session.refresh`, `device.authorize`, `device.verify`, `device.callback`, `auth.denied`, `access.denied`, `inference`, `managed.serve`, `desktop_bootstrap.serve`, `desktop_bootstrap.denied`, `spend.blocked`, `admin.denied`, `admin.limit.upsert`, e `admin.limit.delete`. I campi variano per evento:

138 * Gli eventi di mint e refresh riusciti portano `sub`, `email`, `client_ip`, e il risultato142 * Gli eventi di mint e refresh riusciti portano `sub`, `email`, `client_ip`, e il risultato

139 * `auth.denied` e `access.denied` portano il motivo e l'IP client, più il percorso della richiesta per `auth.denied`, poiché nessuna identità utente esiste in quelle negazioni143 * `auth.denied` e `access.denied` portano il motivo e l'IP client, più il percorso della richiesta per `auth.denied`, poiché nessuna identità utente esiste in quelle negazioni. Due motivi di `access.denied` cambiano quello che l'evento porta:

144 * `xff_unparseable`: l'evento porta anche la voce `X-Forwarded-For` che non poteva essere letta

145 * `client_ip_unknown`: l'evento non porta alcun IP client, perché la connessione non aveva un indirizzo peer mentre era impostato un elenco `access_control`

140 * `inference` registra quale upstream ha servito la richiesta e lo stato della risposta146 * `inference` registra quale upstream ha servito la richiesta e lo stato della risposta

141 * `desktop_bootstrap.denied` registra un fetch di bootstrap di Claude Desktop rifiutato con il motivo (`not_configured`, `policy_not_opted_in`, o `no_policy_matched`) e l'identità dell'utente147 * `desktop_bootstrap.denied` registra un fetch di bootstrap di Claude Desktop rifiutato con il motivo (`not_configured`, `policy_not_opted_in`, o `no_policy_matched`) e l'identità dell'utente

142 * `admin.denied` registra un tentativo di autenticazione dell'API admin rifiutato con l'IP client, il metodo, il percorso e un motivo, senza il materiale della chiave presentato: `invalid_key` quando è stato presentato un `x-api-key` ma non ha corrisposto a nessuna chiave configurata, `bearer_rejected` quando è stato presentato solo un header `Authorization` e non si è verificato come una sessione gateway in `admin.admin_groups`, o `no_credentials` quando nessun header è stato presentato148 * `admin.denied` registra un tentativo di autenticazione dell'API admin rifiutato con l'IP client, il metodo, il percorso e un motivo, senza il materiale della chiave presentato: `invalid_key` quando è stato presentato un `x-api-key` ma non ha corrisposto a nessuna chiave configurata, `bearer_rejected` quando è stato presentato solo un header `Authorization` e non si è verificato come una sessione gateway in `admin.admin_groups`, o `no_credentials` quando nessun header è stato presentato

274Lo stderr del gateway include il flusso di eventi di audit, il log di audit registra le identità degli sviluppatori e il file di debug registra l'output di hook e MCP server dalla macchina dello sviluppatore. Rivedere e oscurare questi elementi prima di pubblicare in un problema pubblico.280Lo stderr del gateway include il flusso di eventi di audit, il log di audit registra le identità degli sviluppatori e il file di debug registra l'output di hook e MCP server dalla macchina dello sviluppatore. Rivedere e oscurare questi elementi prima di pubblicare in un problema pubblico.

275 281

277| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |283| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

278| Lo `/login` di uno sviluppatore mostra il selettore di account standard invece della schermata **Cloud gateway** | `forceLoginMethod` o `forceLoginGatewayUrl` non è impostato nelle impostazioni gestite su quella macchina | Distribuisci il [file di impostazioni gestite](/docs/it/claude-apps-gateway#set-the-gateway-url) al dispositivo; `/login` legge l'URL del gateway da lì |284| Lo `/login` di uno sviluppatore mostra il selettore di account standard invece della schermata **Cloud gateway** | `forceLoginMethod` o `forceLoginGatewayUrl` non è impostato nelle impostazioni gestite su quella macchina | Distribuisci il [file di impostazioni gestite](/docs/it/claude-apps-gateway#set-the-gateway-url) al dispositivo; `/login` legge l'URL del gateway da lì |

285| Le richieste di uno sviluppatore falliscono con `Not signed in to the Cloud gateway — run /login.` | Le impostazioni gestite della macchina impostano `forceLoginMethod: "gateway"` o `forceLoginGatewayUrl`, e la sessione non ha un accesso al gateway. Un accesso a claude.ai residuo non soddisfa il requisito. | Fai eseguire `/login` allo sviluppatore e completa l'accesso al gateway. Vedi anche [Administrator policy requires a Cloud gateway sign-in](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in). |

279| Claude Desktop segnala che la sua configurazione di bootstrap non poteva essere recuperata | `/user/bootstrap` ha restituito 404: il criterio che corrisponde all'utente non contiene una chiave `desktop`, o nessun criterio corrisponde. Il log di audit del gateway registra ogni rifiuto come `desktop_bootstrap.denied` con il motivo. | Aggiungi un blocco `desktop` al criterio che corrisponde all'utente, o al livello base `match: {}`; un `desktop: {}` vuoto è sufficiente. Consulta [Claude Desktop overlay](/docs/it/claude-apps-gateway-config#claude-desktop-overlay). |286| Claude Desktop segnala che la sua configurazione di bootstrap non poteva essere recuperata | `/user/bootstrap` ha restituito 404: il criterio che corrisponde all'utente non contiene una chiave `desktop`, o nessun criterio corrisponde. Il log di audit del gateway registra ogni rifiuto come `desktop_bootstrap.denied` con il motivo. | Aggiungi un blocco `desktop` al criterio che corrisponde all'utente, o al livello base `match: {}`; un `desktop: {}` vuoto è sufficiente. Consulta [Claude Desktop overlay](/docs/it/claude-apps-gateway-config#claude-desktop-overlay). |

280| L'avvio mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | La build di Claude Code installata precede il supporto del gateway | Fai aggiornare lo sviluppatore a Claude Code a una versione che include il supporto del gateway cloud |287| L'avvio mostra `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | La build di Claude Code installata precede il supporto del gateway | Fai aggiornare lo sviluppatore a Claude Code a una versione che include il supporto del gateway cloud |

288| L'avvio o `/login` segnala `Claude Code may not be enabled for your organization` dopo un 403 al caricamento delle impostazioni gestite | Il gateway, o qualcosa davanti ad esso, ha risposto alla richiesta `/managed/settings` con 403. La rotta delle impostazioni del gateway stesso non risponde mai con 403. Lo stato proviene dai controlli IP [`access_control`](/docs/it/claude-apps-gateway-config#http-tuning) o da un proxy o WAF davanti al gateway. Il log di audit registra un rifiuto del controllo IP come `access.denied` con il motivo. Lo sviluppatore rimane connesso. | Controlla il log di audit per `access.denied` al momento dell'errore e correggi gli elenchi `access_control` o il front end, quindi fai avviare di nuovo `claude` allo sviluppatore |

281| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Il nome host del gateway si risolve in almeno un indirizzo IP pubblico. Claude Code controlla ogni indirizzo risolto e richiede che ogni uno sia privato. Una causa comune è un nome dual-stack dove una famiglia si risolve in un indirizzo pubblico, inclusi i load balancer dual-stack interni AWS, che restituiscono indirizzi AAAA di intervallo pubblico. | Fai risolvere il nome del gateway solo in indirizzi privati sulle macchine degli sviluppatori. Per un nome dual-stack, elimina il record di intervallo pubblico o servi un nome DNS solo interno separato. Consulta il [prerequisito di rete privata](/docs/it/claude-apps-gateway#prerequisites). |289| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Il nome host del gateway si risolve in almeno un indirizzo IP pubblico. Claude Code controlla ogni indirizzo risolto e richiede che ogni uno sia privato. Una causa comune è un nome dual-stack dove una famiglia si risolve in un indirizzo pubblico, inclusi i load balancer dual-stack interni AWS, che restituiscono indirizzi AAAA di intervallo pubblico. | Fai risolvere il nome del gateway solo in indirizzi privati sulle macchine degli sviluppatori. Per un nome dual-stack, elimina il record di intervallo pubblico o servi un nome DNS solo interno separato. Consulta il [prerequisito di rete privata](/docs/it/claude-apps-gateway#prerequisites). |

282| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | Un `HTTPS_PROXY` o `HTTP_PROXY` si applica all'host del gateway e il nome host del proxy si risolve in un indirizzo pubblico. Un proxy il cui host si risolve solo in indirizzi privati è consentito e non attiva questo errore | Aggiungi l'host del gateway a `NO_PROXY` sulla macchina dello sviluppatore in modo che la connessione sia diretta, o usa un proxy il cui nome host si risolve in indirizzi privati. Il messaggio nomina la voce esatta `NO_PROXY` da aggiungere |290| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | Un `HTTPS_PROXY` o `HTTP_PROXY` si applica all'host del gateway e il nome host del proxy si risolve in un indirizzo pubblico. Un proxy il cui host si risolve solo in indirizzi privati è consentito e non attiva questo errore | Aggiungi l'host del gateway a `NO_PROXY` sulla macchina dello sviluppatore in modo che la connessione sia diretta, o usa un proxy il cui nome host si risolve in indirizzi privati. Il messaggio nomina la voce esatta `NO_PROXY` da aggiungere |

283| CLI `/login`: `Could not resolve the configured HTTP proxy` | Il nome host in `HTTPS_PROXY` o `HTTP_PROXY` non si risolve dalla macchina dello sviluppatore, tipicamente perché non è connessa alla rete aziendale | Fai connettere lo sviluppatore alla tua rete o VPN e riprova, o correggi l'URL del proxy |291| CLI `/login`: `Could not resolve the configured HTTP proxy` | Il nome host in `HTTPS_PROXY` o `HTTP_PROXY` non si risolve dalla macchina dello sviluppatore, tipicamente perché non è connessa alla rete aziendale | Fai connettere lo sviluppatore alla tua rete o VPN e riprova, o correggi l'URL del proxy |

288| L'avvio esce con un errore di permesso di Postgres | Il ruolo del database manca dei diritti DDL sul suo schema | Concedi al ruolo `CREATE` sullo schema del gateway in modo che possa creare e alterare le sue tabelle all'avvio |296| L'avvio esce con un errore di permesso di Postgres | Il ruolo del database manca dei diritti DDL sul suo schema | Concedi al ruolo `CREATE` sullo schema del gateway in modo che possa creare e alterare le sue tabelle all'avvio |

289| `/oauth/callback` mostra "Sign-in could not be completed" | Dominio email rifiutato, convalida id\_token fallita, o `email_verified` è esplicitamente `false`, che il gateway rifiuta sempre senza override | Controlla `allowed_email_domains` e che l'IdP restituisca un claim `email` verificato. Per `email_verified: false`, correggi la verifica lato IdP. Se il tuo IdP emette email sotto un nome di claim diverso, imposta `oidc.email_claim`. |297| `/oauth/callback` mostra "Sign-in could not be completed" | Dominio email rifiutato, convalida id\_token fallita, o `email_verified` è esplicitamente `false`, che il gateway rifiuta sempre senza override | Controlla `allowed_email_domains` e che l'IdP restituisca un claim `email` verificato. Per `email_verified: false`, correggi la verifica lato IdP. Se il tuo IdP emette email sotto un nome di claim diverso, imposta `oidc.email_claim`. |

290| Log: `token exchange failed request_id=<id>: id_token missing email claim` | L'IdP non include `email` nell'id\_token per impostazione predefinita. Questo rifiuto si attiva solo quando `allowed_email_domains` è impostato; senza di esso, un'email mancante conia una sessione senza email | Configura l'IdP per emettere `email` nell'id\_token. Okta: aggiungi `email` ai claim id\_token di un server di autorizzazione personalizzato. Entra: aggiungi `email` come claim facoltativo sulla registrazione dell'app. PingFederate: abilita una Policy OpenID Connect che emette `email`. Se l'IdP serve `email` dall'endpoint userinfo ma non lo includerà nell'id\_token, come il server di autorizzazione dell'organizzazione Okta, imposta `oidc.userinfo_fallback: true`. |298| Log: `token exchange failed request_id=<id>: id_token missing email claim` | L'IdP non include `email` nell'id\_token per impostazione predefinita. Questo rifiuto si attiva solo quando `allowed_email_domains` è impostato; senza di esso, un'email mancante conia una sessione senza email | Configura l'IdP per emettere `email` nell'id\_token. Okta: aggiungi `email` ai claim id\_token di un server di autorizzazione personalizzato. Entra: aggiungi `email` come claim facoltativo sulla registrazione dell'app. PingFederate: abilita una Policy OpenID Connect che emette `email`. Se l'IdP serve `email` dall'endpoint userinfo ma non lo includerà nell'id\_token, come il server di autorizzazione dell'organizzazione Okta, imposta `oidc.userinfo_fallback: true`. |

299| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e gli sviluppatori vedono `Cloud gateway session expired` ogni `session.ttl_hours` | L'IdP ha accettato il token di aggiornamento ma non ha restituito alcun id\_token con esso, quindi il gateway ha chiesto all'endpoint userinfo dell'IdP i claim dell'utente. L'IdP ha rifiutato il token di accesso aggiornato lì. Il gateway risponde `temporarily_unavailable`, quindi Claude Code mantiene il token di aggiornamento ma non può rinnovare la sessione. Le versioni del gateway precedenti a v2.1.260 registrano la stessa riga senza il dettaglio `(at …)`. | Imposta [`oidc.scope_on_refresh: true`](/docs/it/claude-apps-gateway-config#oidc), disponibile nel gateway v2.1.260 o successivo, in modo che la richiesta di aggiornamento chieda di nuovo `openid`. Alcuni IdP, come Okta, restituiscono un id\_token al refresh solo quando richiesto. Su PingFederate, abilita **Return ID Token On Refresh Grant** sotto **Applications > OAuth > OpenID Connect Policy Management**. La chiave non cambia il comportamento di PingFederate. Per altri IdP che ancora lo omettono, controlla se l'endpoint userinfo accetta token di accesso emessi da un aggiornamento. Come misura temporanea, aumenta [`session.ttl_hours`](/docs/it/claude-apps-gateway-config#session). Vedi [Identity provider setup](#identity-provider-setup) per il compromesso di deprovisioning. |

291| Ogni richiesta Amazon Bedrock restituisce 502; il log mostra `Could not load credentials from any providers` | Su EC2, il limite di hop predefinito di IMDSv2 di 1 blocca la richiesta di metadati dell'istanza dall'interno del container. L'avvio e `/readyz` passano comunque perché l'AWS SDK risolve le credenziali dell'istanza alla prima richiesta, non alla costruzione del client | Aumenta il limite di hop con `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, o impostalo nel modello di lancio. Il cambiamento si applica a ogni container sull'istanza. Preferisci i ruoli delle attività ECS dove disponibili, che leggono le credenziali dall'endpoint delle credenziali del container ECS e evitano completamente il cambiamento, o applica il cambiamento su un'istanza del gateway dedicata per limitare l'esposizione. |300| Ogni richiesta Amazon Bedrock restituisce 502; il log mostra `Could not load credentials from any providers` | Su EC2, il limite di hop predefinito di IMDSv2 di 1 blocca la richiesta di metadati dell'istanza dall'interno del container. L'avvio e `/readyz` passano comunque perché l'AWS SDK risolve le credenziali dell'istanza alla prima richiesta, non alla costruzione del client | Aumenta il limite di hop con `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, o impostalo nel modello di lancio. Il cambiamento si applica a ogni container sull'istanza. Preferisci i ruoli delle attività ECS dove disponibili, che leggono le credenziali dall'endpoint delle credenziali del container ECS e evitano completamente il cambiamento, o applica il cambiamento su un'istanza del gateway dedicata per limitare l'esposizione. |

292| Errore IdP: unknown or unsupported scope | L'IdP rifiuta gli scope che non riconosce | Imposta `oidc.scopes` esattamente all'elenco che il tuo IdP accetta; deve includere `openid`. Il predefinito è `openid profile email offline_access`. |301| Errore IdP: unknown or unsupported scope | L'IdP rifiuta gli scope che non riconosce | Imposta `oidc.scopes` esattamente all'elenco che il tuo IdP accetta; deve includere `openid`. Il predefinito è `openid profile email offline_access`. |

293| Le sessioni non si rinnovano silenziosamente dopo aver impostato `oidc.scopes` | `offline_access` è stato eliminato dall'override | Aggiungi `offline_access` di nuovo se il tuo IdP lo supporta. Senza un token di aggiornamento, gli sviluppatori rieseguono l'accesso al browser ogni `session.ttl_hours`. |302| Le sessioni non si rinnovano silenziosamente dopo aver impostato `oidc.scopes` | `offline_access` è stato eliminato dall'override | Aggiungi `offline_access` di nuovo se il tuo IdP lo supporta. Senza un token di aggiornamento, gli sviluppatori rieseguono l'accesso al browser ogni `session.ttl_hours`. |

300| CLI `/login` completa l'accesso al browser, quindi la sessione termina con `Cloud gateway sign-in was not completed` e una mancata corrispondenza del certificato TLS | Alla prima richiesta dopo l'accesso, il gateway ha presentato un certificato che non corrisponde all'impronta digitale che Claude Code ha bloccato, quindi Claude Code non ha mantenuto alcuna credenziale del gateway. Le cause comuni sono repliche dietro un indirizzo che servono certificati diversi, o qualcosa sul percorso di rete che intercetta TLS. | Servi un certificato per il nome host, ad esempio terminando TLS una volta all'ingress, quindi fai eseguire di nuovo `/login` allo sviluppatore. Se quel certificato differisce da quello bloccato, Claude Code mostra di nuovo il [prompt di fiducia](/docs/it/claude-apps-gateway#connect-developers) con un avviso che il certificato è cambiato. |309| CLI `/login` completa l'accesso al browser, quindi la sessione termina con `Cloud gateway sign-in was not completed` e una mancata corrispondenza del certificato TLS | Alla prima richiesta dopo l'accesso, il gateway ha presentato un certificato che non corrisponde all'impronta digitale che Claude Code ha bloccato, quindi Claude Code non ha mantenuto alcuna credenziale del gateway. Le cause comuni sono repliche dietro un indirizzo che servono certificati diversi, o qualcosa sul percorso di rete che intercetta TLS. | Servi un certificato per il nome host, ad esempio terminando TLS una volta all'ingress, quindi fai eseguire di nuovo `/login` allo sviluppatore. Se quel certificato differisce da quello bloccato, Claude Code mostra di nuovo il [prompt di fiducia](/docs/it/claude-apps-gateway#connect-developers) con un avviso che il certificato è cambiato. |

301| CLI `/login` si ferma con `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` | Una richiesta di accesso ha raggiunto un server il cui certificato non corrisponde a quello che lo sviluppatore ha accettato quando `/login` è iniziato: repliche dietro un indirizzo che servono certificati diversi, intercettazione TLS sul percorso, o una rotazione del certificato mentre l'accesso era in corso. | Servi un certificato per il nome host, quindi fai iniziare di nuovo l'accesso allo sviluppatore e rivedi il nuovo certificato al [prompt di fiducia](/docs/it/claude-apps-gateway#connect-developers). |310| CLI `/login` si ferma con `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` | Una richiesta di accesso ha raggiunto un server il cui certificato non corrisponde a quello che lo sviluppatore ha accettato quando `/login` è iniziato: repliche dietro un indirizzo che servono certificati diversi, intercettazione TLS sul percorso, o una rotazione del certificato mentre l'accesso era in corso. | Servi un certificato per il nome host, quindi fai iniziare di nuovo l'accesso allo sviluppatore e rivedi il nuovo certificato al [prompt di fiducia](/docs/it/claude-apps-gateway#connect-developers). |

302 311

303Il messaggio `Cloud gateway sign-in was not completed` nomina il nome host del gateway e, quando Claude Code ha entrambe le impronte digitali, i primi 16 caratteri di quella bloccata e quella presentata.312Il messaggio `Cloud gateway sign-in was not completed` nomina il nome host del gateway. Quando Claude Code ha entrambe le impronte digitali bloccata e presentata, il messaggio mostra anche i primi 16 caratteri di ciascuna.

304 313

305Se Claude Code segnala `couldn't load your organization's managed settings` dopo un accesso al gateway, Claude Code nomina il motivo, si riavvia sul posto e riprende la conversazione. Se Claude Code non può riavviarsi, ad esempio in una sessione in background, Claude Code termina la sessione e mantiene l'accesso.314Se Claude Code segnala `couldn't load your organization's managed settings` dopo un accesso al gateway, Claude Code nomina il motivo, si riavvia sul posto e riprende la conversazione. Se Claude Code non può riavviarsi, ad esempio in una sessione in background, Claude Code termina la sessione e mantiene l'accesso.

306 315

claude-apps-gateway-on-aws.md +554 −0 created

Details

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.

5# Distribuire il gateway delle app Claude su AWS

7> Un esempio pratico di esecuzione del gateway delle app Claude su AWS: ECS Fargate o EKS, Amazon RDS per PostgreSQL, AWS Secrets Manager e autenticazione basata su ruoli IAM ad Amazon Bedrock.

9<Note>

10 Questa pagina illustra un modo per eseguire il gateway delle app Claude su AWS. La configurazione è un esempio funzionante per infrastrutture gestite dal cliente piuttosto che una distribuzione di produzione supportata; utilizzatela per vedere come i componenti si incastrano insieme prima di adattarla al vostro ambiente. Per i requisiti indipendenti dalla piattaforma, consultate la [guida alla distribuzione](/docs/it/claude-apps-gateway-deploy).

11</Note>

13Questo esempio esegue il provisioning del gateway delle app Claude su AWS con Amazon Bedrock come upstream del modello, utilizzando [Amazon ECS](https://aws.amazon.com/ecs/) su [AWS Fargate](https://aws.amazon.com/fargate/) o [Amazon EKS](https://aws.amazon.com/eks/) per il calcolo. [Okta](https://www.okta.com/) è il provider di identità (IdP) di esempio, ma qualsiasi IdP conforme a OpenID Connect (OIDC) funziona; consultate [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup) per i dettagli specifici di ogni IdP.

15<Note>

16 Bedrock non è l'unico upstream Claude su AWS. Il gateway supporta anche Claude Platform su AWS, l'API Claude gestita da Anthropic con autenticazione AWS e fatturazione AWS Marketplace, al posto di Bedrock o insieme ad esso. La sua voce upstream, le credenziali e i permessi IAM differiscono da quelli specifici di Bedrock in questa pagina; il [riferimento upstream Claude Platform su AWS](/docs/it/claude-apps-gateway-config#claude-platform-on-aws) copre cosa cambia, e il resto di questa pagina si applica invariato.

17</Note>

19<h2 id="architecture">

20 Architettura

21</h2>

23<Frame caption="L'architettura di esempio, con Amazon Bedrock come upstream del modello. Un upstream Claude Platform su AWS occupa la stessa posizione.">

24 <img src="https://mintcdn.com/claude-code/PHweeRmDUYEKff49/images/claude-gateway-aws-architecture.svg?fit=max&auto=format&n=PHweeRmDUYEKff49&q=85&s=8599cc34aa28522cde208ee831439bb4" alt="Diagramma del gateway delle app Claude su AWS: i client Claude Code si connettono tramite HTTPS a un Application Load Balancer interno che sta davanti al gateway (ECS Fargate o EKS), che viene eseguito in subnet private insieme a un'istanza Amazon RDS per PostgreSQL per lo stato della sessione. Il gateway accede gli utenti tramite OIDC rispetto all'IdP aziendale, legge i segreti da AWS Secrets Manager, inoltra le richieste del modello ad Amazon Bedrock utilizzando il suo ruolo IAM e estrae la sua immagine da Amazon ECR al momento della distribuzione." width="820" height="430" data-path="images/claude-gateway-aws-architecture.svg" />

25</Frame>

27Il gateway viene eseguito come endpoint HTTPS privato sulla vostra rete a cui gli sviluppatori accedono tramite il vostro IdP. Le loro sessioni Claude Code raggiungono i modelli Claude su Amazon Bedrock attraverso il ruolo IAM del gateway, quindi nessuna credenziale del modello finisce sulle macchine degli sviluppatori. La configurazione di riferimento esegue il provisioning di:

29* Servizio **Amazon ECS su AWS Fargate** o **Amazon EKS** Deployment che esegue il contenitore del gateway

30* Repository **Amazon ECR** per l'immagine del gateway

31* Istanza **Amazon RDS per PostgreSQL** in subnet private, non accessibile pubblicamente, per lo [store](/docs/it/claude-apps-gateway-config#store) del gateway

32* Segreti **AWS Secrets Manager** per la chiave di firma JWT, il segreto del client OIDC e l'URL di Postgres

33* **Ruolo IAM** con `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream` e `bedrock:CountTokens`, allegato come ruolo di attività ECS o associato tramite IAM Roles for Service Accounts (IRSA) su EKS

34* **Application Load Balancer interno** per HTTPS

36<h2 id="prerequisites">

37 Prerequisiti

38</h2>

40La procedura dettagliata crea le risorse proprie del gateway, ma si basa su infrastrutture di rete e identità che già possedete. Prima di iniziare, avete bisogno di:

42* Un account AWS con autorizzazione per creare le [risorse sopra](#architecture)

43* [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installata e [autenticata](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html), e [Docker](https://docs.docker.com/get-started/get-docker/) installato localmente

44* Un [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) con almeno due [subnet private](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html) in diverse zone di disponibilità, con accesso a Internet in uscita tramite un [gateway NAT](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html); il load balancer interno ha bisogno di subnet in due AZ e il gateway ha bisogno di uscita verso Bedrock e il vostro IdP

45* Un'applicazione web OIDC Okta con URI di reindirizzamento `https://<gateway-host>/oauth/callback`; consultate [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup)

46* Un nome host TLS per il gateway, tipicamente un nome DNS interno in una [zona ospitata privata Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html) che punta al load balancer, con un [certificato ACM](https://docs.aws.amazon.com/acm/latest/userguide/gs.html) per quel nome, importato o emesso da [AWS Private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html)

48<h3 id="set-your-environment-variables">

49 Impostare le variabili di ambiente

50</h3>

52Ogni comando in questa pagina legge quattro valori dalla vostra shell: `AWS_REGION`, `ACCOUNT_ID`, `VPC_ID` e `PRIVATE_SUBNETS`.

54Scegliete una regione US dove Bedrock serve i modelli Claude di cui avete bisogno. La procedura dettagliata si basa sul catalogo dei modelli integrato del gateway, che si risolve in profili di inferenza `us.anthropic.*`, e la politica IAM concede quegli ARN. In una regione non-US, aggiungete un [blocco `models:`](/docs/it/claude-apps-gateway-config#models) con gli ID del profilo di inferenza di quella geo e cambiate il prefisso ARN della politica IAM per corrispondere.

56Se non avete l'ID VPC a portata di mano, elencate i vostri VPC con `aws ec2 describe-vpcs`, quindi elencate le subnet di quel VPC per trovare due private in diverse zone di disponibilità:

58```bash theme={null}

59aws ec2 describe-subnets --filters "Name=vpc-id,Values=<your-vpc-id>" \

60 --query 'Subnets[].{ID:SubnetId,AZ:AvailabilityZone,CIDR:CidrBlock}' --output table

61```

63Esportate tutti e quattro prima di continuare:

65```bash theme={null}

66export AWS_REGION=us-east-1 # una regione US dove Bedrock serve i modelli Claude di cui avete bisogno

67export ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"

68export VPC_ID=<your-vpc-id>

69export PRIVATE_SUBNETS="<subnet-id-a> <subnet-id-b>"

70```

72<h2 id="deploy-the-gateway">

73 Distribuire il gateway

74</h2>

76I passaggi seguenti eseguono il provisioning della distribuzione completa con comandi `aws`.

78<Steps>

79 <Step title="Creare i gruppi di sicurezza">

80 Tre gruppi di sicurezza concatenano il percorso del traffico: la vostra rete aziendale raggiunge il load balancer sulla porta 443, il load balancer raggiunge il gateway sulla porta 8080 e il gateway raggiunge Postgres sulla porta 5432. Nient'altro è raggiungibile. Come li collegate dipende dal percorso di calcolo:

82 * Su ECS Fargate, il passaggio di distribuzione allega `$ALB_SG` al load balancer e `$GW_SG` al servizio.

83 * Su EKS, AWS Load Balancer Controller crea il proprio gruppo di sicurezza frontend per l'ALB, quindi `$ALB_SG` e `$GW_SG` non vengono utilizzati: l'annotazione `inbound-cidrs` del passaggio di distribuzione limita il listener alla vostra rete aziendale e il gruppo di sicurezza del database ammette il gruppo di sicurezza del cluster al posto di `$GW_SG`.

85 ```bash theme={null}

86 ALB_SG="$(aws ec2 create-security-group --group-name claude-gateway-alb \

87 --description "Claude gateway ALB" --vpc-id "$VPC_ID" \

88 --query GroupId --output text)"

89 GW_SG="$(aws ec2 create-security-group --group-name claude-gateway-svc \

90 --description "Claude gateway service" --vpc-id "$VPC_ID" \

91 --query GroupId --output text)"

92 DB_SG="$(aws ec2 create-security-group --group-name claude-gateway-db \

93 --description "Claude gateway Postgres" --vpc-id "$VPC_ID" \

94 --query GroupId --output text)"

96 aws ec2 authorize-security-group-ingress --group-id "$ALB_SG" \

97 --protocol tcp --port 443 --cidr <your-corporate-cidr>

98 aws ec2 authorize-security-group-ingress --group-id "$GW_SG" \

99 --protocol tcp --port 8080 --source-group "$ALB_SG"

100 aws ec2 authorize-security-group-ingress --group-id "$DB_SG" \

101 --protocol tcp --port 5432 --source-group "$GW_SG"

102 ```

103 </Step>

104

105 <Step title="Creare i ruoli IAM e inviare il modulo del caso d'uso">

106 Il gateway viene eseguito con un ruolo di attività dedicato la cui unica autorizzazione è invocare i modelli Claude su Bedrock. Secondo il [riferimento upstream Bedrock](/docs/it/claude-apps-gateway-config#amazon-bedrock), la politica deve coprire sia gli ARN del profilo di inferenza cross-region che gli ARN del modello di base sottostante:

107

108 ```bash theme={null}

109 cat > bedrock-invoke.json <<EOF

110 {

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

112 "Statement": [{

113 "Effect": "Allow",

114 "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream", "bedrock:CountTokens"],

115 "Resource": [

116 "arn:aws:bedrock:${AWS_REGION}:${ACCOUNT_ID}:inference-profile/us.anthropic.*",

117 "arn:aws:bedrock:*::foundation-model/anthropic.*"

118 ]

119 }]

120 }

121 EOF

122 cat > ecs-trust.json <<'EOF'

123 {

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

125 "Statement": [{

126 "Effect": "Allow",

127 "Principal": { "Service": "ecs-tasks.amazonaws.com" },

128 "Action": "sts:AssumeRole"

129 }]

130 }

131 EOF

132

133 aws iam create-role --role-name claude-gateway-task \

134 --assume-role-policy-document file://ecs-trust.json

135 aws iam put-role-policy --role-name claude-gateway-task \

136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

137 ```

138

139 ECS ha anche bisogno di un ruolo di esecuzione, che l'agente ECS stesso utilizza per estrarre l'immagine da ECR e iniettare i valori di Secrets Manager creati in seguito. È separato dal ruolo di attività che l'AWS SDK del gateway utilizza in fase di esecuzione:

140

141 ```bash theme={null}

142 aws iam create-role --role-name claude-gateway-execution \

143 --assume-role-policy-document file://ecs-trust.json

144 aws iam attach-role-policy --role-name claude-gateway-execution \

145 --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

146 cat > secrets-read.json <<EOF

147 {

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

149 "Statement": [{

150 "Effect": "Allow",

151 "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],

152 "Resource": [

153 "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-jwt-secret-??????",

154 "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-oidc-client-secret-??????",

155 "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-postgres-url-??????"

156 ]

157 }]

158 }

159 EOF

160 aws iam put-role-policy --role-name claude-gateway-execution \

161 --policy-name read-gateway-secrets --policy-document file://secrets-read.json

162 ```

163

164 I nomi della politica specificano un ARN per segreto piuttosto che un wildcard semplice `gateway-*`, che in un account condiviso corrisponderebbe anche a segreti non correlati; il suffisso finale `-??????` corrisponde esattamente al suffisso di sei caratteri casuale che Secrets Manager aggiunge all'ARN di ogni segreto. Un `-*` finale sarebbe un glob di prefisso semplice e corrisponderebbe anche a nomi più lunghi come `gateway-postgres-url-prod`.

165

166 La politica IAM concede al gateway il permesso di chiamare Bedrock, e Bedrock abilita l'accesso al modello per impostazione predefinita nelle regioni commerciali. Il gate rimanente a livello di account è il modulo del caso d'uso una tantum di Anthropic: se nessuno nel vostro account lo ha inviato, aprite la [console Amazon Bedrock](https://console.aws.amazon.com/bedrock/), selezionate un modello Anthropic dal catalogo dei modelli e completate il modulo. L'accesso viene concesso immediatamente dopo l'invio; consultate [Claude Code su Amazon Bedrock](/docs/it/amazon-bedrock#1-submit-use-case-details) per il modulo AWS Organizations e i permessi IAM di cui il mittente ha bisogno.

167

168 Il percorso EKS riutilizza entrambi i documenti della politica su un ruolo IRSA al posto dei due ruoli ECS; consultate il passaggio di distribuzione.

169 </Step>

170

171 <Step title="Eseguire il provisioning di Amazon RDS per PostgreSQL">

172 L'istanza viene eseguita nelle subnet private senza indirizzo pubblico e con crittografia dell'archiviazione attivata. La versione del motore è fissata a Postgres 16, che soddisfa il limite supportato del gateway di PostgreSQL 14 e garantisce che la famiglia del gruppo di parametri sottostante corrisponda all'istanza.

173

174 Per prima cosa, create il gruppo di subnet che posiziona il database nelle subnet private e un gruppo di parametri con `rds.force_ssl=1` in modo che il server rifiuti le connessioni in testo semplice. La versione del motore è fissata una volta perché la famiglia del gruppo di parametri deve corrispondere alla versione principale del motore che l'istanza esegue:

175

176 ```bash theme={null}

177 aws rds create-db-subnet-group --db-subnet-group-name claude-gateway-db \

178 --db-subnet-group-description "Claude gateway" --subnet-ids $PRIVATE_SUBNETS

179

180 PG_VERSION=16

181 PG_FAMILY="postgres${PG_VERSION}"

182 aws rds create-db-parameter-group --db-parameter-group-name claude-gateway-db \

183 --db-parameter-group-family "$PG_FAMILY" \

184 --description "Claude gateway - require TLS on every connection"

185 aws rds modify-db-parameter-group --db-parameter-group-name claude-gateway-db \

186 --parameters "ParameterName=rds.force_ssl,ParameterValue=1,ApplyMethod=immediate"

187 ```

188

189 Quindi create l'istanza con una password principale generata:

190

191 ```bash theme={null}

192 PGPASS="$(openssl rand -hex 24)"

193 aws rds create-db-instance --db-instance-identifier claude-gateway-db \

194 --engine postgres --engine-version "$PG_VERSION" \

195 --db-instance-class db.t4g.micro \

196 --allocated-storage 20 --db-name claude_gateway \

197 --master-username gateway --master-user-password "$PGPASS" \

198 --db-subnet-group-name claude-gateway-db \

199 --db-parameter-group-name claude-gateway-db \

200 --vpc-security-group-ids "$DB_SG" \

201 --no-publicly-accessible --storage-encrypted

202 ```

203

204 L'argomento letterale `--master-user-password` è visibile nella tabella dei processi e nei log di audit/EDR mentre il comando viene eseguito, la stessa esposizione che la nota del passaggio dei segreti copre. Su un host condiviso o monitorato, passate la password tramite `--cli-input-json` da un file `0600` al posto, il modo in cui `setup.sh` del bundle lo fa.

205

206 Attendete che l'istanza si avvii, il che può richiedere diversi minuti, quindi leggete il suo endpoint privato e assemblate la stringa di connessione che il gateway utilizzerà:

207

208 ```bash theme={null}

209 aws rds wait db-instance-available --db-instance-identifier claude-gateway-db

210 DB_HOST="$(aws rds describe-db-instances --db-instance-identifier claude-gateway-db \

211 --query 'DBInstances[0].Endpoint.Address' --output text)"

212 GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${DB_HOST}:5432/claude_gateway?sslmode=verify-full"

213 ```

214

215 `sslmode=verify-full` fa sì che il gateway verifichi la catena del certificato del server RDS e il nome host, non solo crittografare. L'ancora di fiducia è il [bundle di certificati AWS RDS](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem), che il passaggio di compilazione dell'immagine sottostante copia in `/etc/claude/rds-global-bundle.pem` e affida tramite `NODE_EXTRA_CA_CERTS`. Non aggiungete un parametro `sslrootcert=` in stile libpq all'URL: il driver del gateway legge solo `sslmode` dalla stringa di query e inoltrerebbe `sslrootcert` a Postgres come parametro di avvio, che il server rifiuta.

216

217 Il servizio ECS o i pod EKS devono essere eseguiti in questo VPC in modo che possano raggiungere l'endpoint privato dell'istanza, e il gruppo di sicurezza `claude-gateway-db` ammette solo il gruppo di sicurezza del gateway.

218 </Step>

219

220 <Step title="Scrivere gateway.yaml">

221 Il blocco `upstreams` punta a Bedrock con `auth: {}`, quindi il gateway si autentica tramite la catena di credenziali predefinita di AWS dal ruolo di attività su ECS o dal ruolo IRSA su EKS. Consultate il [riferimento di configurazione](/docs/it/claude-apps-gateway-config) per ogni campo.

222

223 Due campi `listen` descrivono cosa sta davanti al gateway:

224

225 * `public_url`: l'origine esterna `https://`, obbligatoria per qualsiasi bind non-loopback; consultate il [riferimento `listen`](/docs/it/claude-apps-gateway-config#listen). Il gateway costruisce l'`redirect_uri` dell'IdP e il suo documento di scoperta solo da questo valore, mai da intestazioni `X-Forwarded-*`.

226 * `trusted_proxies`: gli intervalli di origine del front end. Il gateway onora `X-Forwarded-For` solo quando il peer TCP è in questo elenco, quindi cammina nella catena oltre i hop affidabili, in modo che i limiti di velocità di accesso per IP e gli eventi di audit registrino gli IP degli sviluppatori al posto di quello del load balancer.

227

228 Su entrambi i percorsi il front end è un ALB interno, creato direttamente o da AWS Load Balancer Controller, e i nodi di un ALB prendono indirizzi dalle subnet a cui è collegato, quindi impostate `trusted_proxies` ai CIDR di quelle subnet. Questo affida ogni host in quelle subnet come proxy. Evitate che l'origine di ingresso dell'ALB, il vostro CIDR aziendale, si sovrapponga ad essi, e non condividete le subnet con carichi di lavoro non affidabili che potrebbero falsificare gli IP dei client tramite `X-Forwarded-For`.

229

230 L'attributo di conservazione del client port dell'ALB, `routing.http.xff_client_port.enabled`, può rimanere a entrambe le impostazioni: con esso attivato, l'ALB scrive il client come `203.0.113.7:54321` o `[2001:db8::1]:54321`, e il gateway legge entrambi con la porta eliminata.

231

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

233 listen:

234 host: 0.0.0.0

235 port: 8080

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

237 trusted_proxies: [<your-alb-subnet-cidrs>]

238

239 oidc:

240 issuer: https://example.okta.com

241 client_id: 0oa1example2

242 client_secret: ${OIDC_CLIENT_SECRET} # EKS: ${file:/secrets/oidc-client-secret}

243 allowed_email_domains: [example.com]

244 # Il server di autorizzazione dell'organizzazione Okta restituisce un id_token sottile che omette

245 # email e gruppi; il gateway li riempie da /userinfo.

246 userinfo_fallback: true

247 # Okta emette gruppi solo quando viene richiesto lo scope `groups` e il

248 # filtro della rivendicazione dei gruppi dell'app lo consente.

249 scopes: [openid, profile, email, offline_access, groups]

250

251 session:

252 jwt_secret: ${GATEWAY_JWT_SECRET} # EKS: ${file:/secrets/jwt-secret}

253 ttl_hours: 8 # limita la latenza di deprovisioning; abbassate

254 # verso 1 per una revoca più stretta

255

256 store:

257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

258

259 upstreams:

260 - provider: bedrock

261 region: <your-region> # corrispondere a $AWS_REGION in modo che gli ARN della politica IAM

262 # lo coprano

263 auth: {} # catena di credenziali predefinita di AWS:

264 # ruolo di attività ECS, o IRSA su EKS

265 ```

266

267 <Note>

268 Solo il blocco `oidc` è specifico di Okta. Per utilizzare Microsoft Entra ID al posto, impostate `issuer` su `https://login.microsoftonline.com/<tenant-id>/v2.0`, eliminate `userinfo_fallback` e lo scope `groups`, e notate che Entra emette Object ID dei gruppi piuttosto che nomi, quindi [`managed.policies`](/docs/it/claude-apps-gateway-config#managed) deve corrispondere ai GUID, o su App Roles con `oidc.groups_claim: roles`. Consultate [Configurazione del provider di identità](/docs/it/claude-apps-gateway-deploy#identity-provider-setup).

269 </Note>

270 </Step>

271

272 <Step title="Archiviare i segreti in AWS Secrets Manager">

273 Create tre segreti; il ruolo di esecuzione dal passaggio IAM può già leggerli:

274

275 ```bash theme={null}

276 aws secretsmanager create-secret --name gateway-jwt-secret \

277 --secret-string "$(openssl rand -base64 32)"

278 aws secretsmanager create-secret --name gateway-oidc-client-secret \

279 --secret-string '<your-okta-client-secret>'

280 aws secretsmanager create-secret --name gateway-postgres-url \

281 --secret-string "$GATEWAY_POSTGRES_URL"

282 ```

283

284 Notate l'ARN che ogni chiamata stampa; la definizione di attività ECS fa riferimento ai segreti per ARN.

285

286 <Note>

287 Gli argomenti letterali `--secret-string` sono visibili nella tabella dei processi e nei log di audit/EDR mentre ogni comando viene eseguito. Su un host condiviso o monitorato, mettete il valore in un file `0600` e passate `--secret-string file://<path>` al posto. `setup.sh` del bundle mantiene i valori dei segreti fuori da argv del processo allo stesso modo, passando file temporanei `0600` a `--cli-input-json`.

288 </Note>

289

290 A differenza dei segreti, `gateway.yaml` stesso non contiene valori segreti, perché ogni credenziale si risolve all'avvio tramite l'espansione [`${VAR}` o `${file:...}`](/docs/it/claude-apps-gateway-config#secret-expansion). Come tutto raggiunge il contenitore differisce per percorso:

291

292 * Su ECS, il passaggio di compilazione successivo copia `gateway.yaml` nell'immagine a `/etc/claude/gateway.yaml`, e la definizione di attività inietta i tre segreti come variabili di ambiente tramite il suo campo `secrets`, quindi lo YAML fa riferimento a `${GATEWAY_JWT_SECRET}`, `${OIDC_CLIENT_SECRET}` e `${GATEWAY_POSTGRES_URL}`.

293 * Su EKS, montate `gateway.yaml` da una ConfigMap e i segreti come file a `/secrets`, referenziati come `${file:/secrets/...}`. Originare i Kubernetes Secrets da Secrets Manager con External Secrets Operator o il provider AWS del driver CSI Secrets Store, o crearli direttamente con `kubectl`.

294 </Step>

295

296 <Step title="Compilare e spingere l'immagine ad Amazon ECR">

297 Compilate l'immagine secondo i [requisiti dell'immagine del contenitore](/docs/it/claude-apps-gateway-deploy#container-image), posizionando il binario glibc `linux-x64` a `./claude` nel contesto di compilazione. Scrivete il vostro Dockerfile secondo questi requisiti o iniziate dal [`Dockerfile`](https://github.com/anthropics/claude-code/blob/main/examples/gateway/aws/Dockerfile) del bundle, che copia il `gateway.yaml` compilato dai passaggi precedenti nell'immagine a `/etc/claude/gateway.yaml`. Su ECS quella copia incorporata è come la configurazione raggiunge il contenitore, motivo per cui la compilazione viene dopo che il file è stato scritto. Il percorso EKS al posto monta `gateway.yaml` da una ConfigMap al momento della distribuzione, quindi la copia incorporata non viene utilizzata lì.

298

299 L'immagine porta anche il bundle di certificati AWS RDS come ancora di fiducia per la stringa di connessione `sslmode=verify-full`, quindi scaricatelo nel contesto di compilazione per primo. AWS ruota il bundle (nuove CA regionali vengono aggiunte), quindi scaricatelo per compilazione piuttosto che fissare un checksum o impegnarlo:

300

301 ```bash theme={null}

302 curl -fL --proto '=https' -o rds-global-bundle.pem \

303 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

304 ```

305

306 I requisiti dell'immagine del contenitore non coprono il bundle, quindi se scrivete il vostro Dockerfile, aggiungete le due righe che lo copiano e lo affidano; il `Dockerfile` del bundle include già entrambi:

307

308 ```dockerfile theme={null}

309 COPY rds-global-bundle.pem /etc/claude/rds-global-bundle.pem

310 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

311 ```

312

313 Create il repository ECR e accedete Docker ad esso. I tag immutabili significano che il tag `<version>` che il passaggio di distribuzione fissa non può essere successivamente reindirizzato silenziosamente a un'immagine diversa:

314

315 ```bash theme={null}

316 aws ecr create-repository --repository-name claude-gateway \

317 --image-tag-mutability IMMUTABLE \

318 --image-scanning-configuration scanOnPush=true

319 aws ecr get-login-password --region "$AWS_REGION" \

320 | docker login --username AWS --password-stdin \

321 "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

322 ```

323

324 Compilate e spingete l'immagine. La definizione di attività sottostante esegue `linux/amd64`, quindi la piattaforma deve corrispondere qui; per Fargate su ARM64 (Graviton), compilate `linux/arm64` con il binario `linux-arm64` e impostate `cpuArchitecture` su `ARM64` al posto:

325

326 ```bash theme={null}

327 docker build --platform=linux/amd64 \

328 -t "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/claude-gateway:<version>" .

329 docker push "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/claude-gateway:<version>"

330 ```

331 </Step>

332

333 <Step title="Distribuire">

334 <Tabs>

335 <Tab title="ECS Fargate">

336 Create il cluster e un gruppo di log per stderr del gateway, che porta sia i suoi eventi di audit che i log operazionali. La conservazione è una chiamata separata, e senza una CloudWatch mantiene i log per sempre; allineate i 90 giorni con la vostra politica di conservazione dell'audit:

337

338 ```bash theme={null}

339 aws ecs create-cluster --cluster-name claude-gateway

340 aws logs create-log-group --log-group-name /ecs/claude-gateway

341 aws logs put-retention-policy --log-group-name /ecs/claude-gateway \

342 --retention-in-days 90

343 ```

344

345 Scrivete la definizione di attività. Il ruolo di attività porta il permesso Bedrock e il ruolo di esecuzione inietta i segreti; utilizzate gli ARN dei segreti dal passaggio Secrets Manager:

346

347 ```json claude-gateway-task.json theme={null}

348 {

349 "family": "claude-gateway",

350 "networkMode": "awsvpc",

351 "requiresCompatibilities": ["FARGATE"],

352 "cpu": "1024",

353 "memory": "2048",

354 "runtimePlatform": { "cpuArchitecture": "X86_64", "operatingSystemFamily": "LINUX" },

355 "executionRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-execution",

356 "taskRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-task",

357 "containerDefinitions": [

358 {

359 "name": "gateway",

360 "image": "<account-id>.dkr.ecr.<region>.amazonaws.com/claude-gateway:<version>",

361 "portMappings": [{ "containerPort": 8080 }],

362 "secrets": [

363 { "name": "GATEWAY_JWT_SECRET", "valueFrom": "<gateway-jwt-secret ARN>" },

364 { "name": "OIDC_CLIENT_SECRET", "valueFrom": "<gateway-oidc-client-secret ARN>" },

365 { "name": "GATEWAY_POSTGRES_URL", "valueFrom": "<gateway-postgres-url ARN>" }

366 ],

367 "logConfiguration": {

368 "logDriver": "awslogs",

369 "options": {

370 "awslogs-group": "/ecs/claude-gateway",

371 "awslogs-region": "<region>",

372 "awslogs-stream-prefix": "gateway"

373 }

374 }

375 }

376 ]

377 }

378 ```

379

380 Registratela:

381

382 ```bash theme={null}

383 aws ecs register-task-definition --cli-input-json file://claude-gateway-task.json

384 ```

385

386 Mettete un ALB interno davanti con un gruppo di destinazione che verifica lo stato del gateway. `--ip-address-type ipv4` è importante: un ALB interno dual-stack pubblica record AAAA di intervallo pubblico, che il controllo della rete privata `/login` rifiuta:

387

388 ```bash theme={null}

389 ALB_ARN="$(aws elbv2 create-load-balancer --name claude-gateway \

390 --scheme internal --type application --ip-address-type ipv4 \

391 --subnets $PRIVATE_SUBNETS --security-groups "$ALB_SG" \

392 --query 'LoadBalancers[0].LoadBalancerArn' --output text)"

393

394 TG_ARN="$(aws elbv2 create-target-group --name claude-gateway \

395 --protocol HTTP --port 8080 --vpc-id "$VPC_ID" --target-type ip \

396 --health-check-path /readyz \

397 --query 'TargetGroups[0].TargetGroupArn' --output text)"

398 ```

399

400 Aggiungete il listener HTTPS. `--ssl-policy` fissa un limite TLS moderno, poiché ometterlo ricade nella politica predefinita legacy `ELBSecurityPolicy-2016-08`, che ancora accetta TLS 1.0/1.1.

401

402 L'ALB chiude una connessione dopo 60 secondi senza dati per impostazione predefinita. I ping di keepalive del gateway mantengono i flussi entro quel default, quindi aumentare il timeout aggiunge margine sopra la cadenza del ping; la riga [Troubleshooting](#troubleshooting) sui flussi interrotti copre il meccanismo e i gateway più vecchi. I comandi sottostanti aggiungono il listener e aumentano il timeout:

403

404 ```bash theme={null}

405 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

406 --protocol HTTPS --port 443 \

407 --ssl-policy ELBSecurityPolicy-TLS13-1-2-2021-06 \

408 --certificates CertificateArn=<your-acm-certificate-arn> \

409 --default-actions Type=forward,TargetGroupArn="$TG_ARN"

410

411 aws elbv2 modify-load-balancer-attributes --load-balancer-arn "$ALB_ARN" \

412 --attributes Key=idle_timeout.timeout_seconds,Value=3600

413 ```

414

415 Create il servizio. Il circuito di distribuzione del deployment fa rotolare una distribuzione le cui attività continuano a fallire, da un'immagine cattiva o una configurazione non avviabile, indietro allo stato stabile precedente al posto di rilanciare attività fallite per sempre:

416

417 ```bash theme={null}

418 aws ecs create-service --cluster claude-gateway --service-name claude-gateway \

419 --task-definition claude-gateway --desired-count 1 --launch-type FARGATE \

420 --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true}" \

421 --health-check-grace-period-seconds 60 \

422 --network-configuration "awsvpcConfiguration={subnets=[$(echo $PRIVATE_SUBNETS | tr ' ' ',')],securityGroups=[$GW_SG],assignPublicIp=DISABLED}" \

423 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

424 ```

425

426 Il periodo di grazia di 60 secondi dà a un'attività fredda il tempo di estrarre l'immagine, connettersi allo store e rispondere al suo primo controllo di stato prima che ECS inizi a contare i fallimenti rispetto alla distribuzione. Il controllo di stato del gruppo di destinazione su `GET /readyz` verifica che lo store sia raggiungibile, quindi un'attività che non può raggiungere Postgres non entra mai in rotazione; consultate [Comportamento di interruzione](/docs/it/claude-apps-gateway-deploy#outage-behavior) per il compromesso e l'alternativa `/healthz`.

427

428 Le attività vengono eseguite in subnet private senza IP pubblico, quindi tutto l'egresso (verso Bedrock, il vostro IdP, Secrets Manager, ECR e CloudWatch Logs) passa attraverso il gateway NAT. Per mantenere il traffico Bedrock fuori dal percorso pubblico, create un endpoint VPC dell'interfaccia `bedrock-runtime` e puntate l'`base_url` dell'upstream ad esso, come mostrato nel [riferimento upstream Bedrock](/docs/it/claude-apps-gateway-config#amazon-bedrock); l'IdP ha ancora bisogno di uscita a Internet.

429

430 Finite dando agli sviluppatori un nome host risolvibile privatamente: in una zona ospitata privata Route 53, alias il nome DNS interno del gateway all'ALB, e impostate `listen.public_url` a quel nome host. Il nome `*.elb.amazonaws.com` dell'ALB stesso si risolve in indirizzi privati su un ALB interno, ma non può portare il vostro certificato ACM, quindi utilizzate il vostro nome.

431

432 Aggiornate l'URI di reindirizzamento autorizzato del client OAuth a `<public_url>/oauth/callback` prima del primo accesso. Dopo aver cambiato `public_url`, ricompilate e spingete l'immagine sotto un nuovo tag, registrate una nuova revisione della definizione di attività e ridistribuite. Su ECS l'impostazione vive nel `gateway.yaml` incorporato dell'immagine, e il gateway costruisce la sua origine pubblica solo da quell'impostazione, ignorando `X-Forwarded-Host` e `X-Forwarded-Proto`. `X-Forwarded-For` è onorato per gli IP dei client solo quando `listen.trusted_proxies` è impostato.

433 </Tab>

434

435 <Tab title="EKS">

436 Questo percorso ha bisogno di `kubectl` e `eksctl` installati localmente, e di un cluster EKS esistente con un provider OIDC IAM e AWS Load Balancer Controller installato. Il cluster deve essere su `$VPC_ID` in modo che i pod possano raggiungere l'endpoint privato RDS, e il gruppo di sicurezza `claude-gateway-db` deve ammettere il gruppo di sicurezza del pod o del nodo del cluster al posto di `$GW_SG`.

437

438 Su EKS il gateway ottiene le sue credenziali Bedrock tramite IRSA piuttosto che i ruoli ECS. La politica di fiducia `ecs-tasks.amazonaws.com` dal passaggio IAM non si applica qui; IRSA ha bisogno di un ruolo la cui politica di fiducia si federi sul provider OIDC del cluster, scoped a `system:serviceaccount:claude-gateway:gateway`. `eksctl create iamserviceaccount` crea quel ruolo, allega le politiche e annota l'account di servizio Kubernetes con l'ARN del ruolo in un passaggio. Trasformate i due documenti della politica dal passaggio IAM in politiche gestite che può allegare:

439

440 ```bash theme={null}

441 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

442 --policy-document file://bedrock-invoke.json --query Policy.Arn --output text)"

443 SECRETS_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-secrets-read \

444 --policy-document file://secrets-read.json --query Policy.Arn --output text)"

445

446 kubectl create namespace claude-gateway

447 eksctl create iamserviceaccount --cluster <your-cluster> --region "$AWS_REGION" \

448 --namespace claude-gateway --name gateway --role-name claude-gateway \

449 --attach-policy-arn "$BEDROCK_POLICY_ARN" \

450 --attach-policy-arn "$SECRETS_POLICY_ARN" \

451 --approve

452 ```

453

454 La politica dei segreti è necessaria solo quando i pod leggono Secrets Manager stessi, come fa il provider AWS del driver CSI Secrets Store utilizzando l'account di servizio del pod di montaggio; eliminatela se create i Kubernetes Secrets in un altro modo. Il provider ha bisogno di entrambe le azioni della politica: chiama `DescribeSecret` quando riconcilia i segreti ruotati, quindi una concessione `GetSecretValue`-only monta sulla prima distribuzione ma smette di raccogliere rotazioni.

455

456 Distribuite il gateway come Deployment standard più un Service e un Ingress, come descritto in [Distribuzione Kubernetes](/docs/it/claude-apps-gateway-deploy#kubernetes), con:

457

458 * `serviceAccountName: gateway`

459 * `gateway.yaml` montato da una ConfigMap e i segreti montati a `/secrets`

460 * il probe di prontezza puntato a `GET /readyz`

461

462 Per il front end, un Ingress gestito da AWS Load Balancer Controller esegue il provisioning dell'ALB interno. Annotatelo con:

463

464 * `alb.ingress.kubernetes.io/scheme: internal` e `alb.ingress.kubernetes.io/target-type: ip`

465 * `alb.ingress.kubernetes.io/ip-address-type: ipv4`, in modo che nessun record AAAA di intervallo pubblico venga pubblicato per il controllo della rete privata `/login` [private-network check](/docs/it/claude-apps-gateway#prerequisites) da rifiutare

466 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`, in modo che il gruppo di sicurezza gestito dal controller ammetta solo la vostra rete aziendale al posto del suo default `0.0.0.0/0`

467 * `alb.ingress.kubernetes.io/certificate-arn` con il certificato ACM

468 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`, in modo che il listener non ricada nella politica predefinita legacy che accetta TLS 1.0 e 1.1

469 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`, un margine sopra il keepalive di streaming del gateway; consultate [Troubleshooting](#troubleshooting)

470

471 Con IRSA, l'AWS SDK legge un token dell'account di servizio proiettato e lo scambia con AWS STS, quindi il pod non ha mai bisogno del servizio di metadati dell'istanza EC2; una NetworkPolicy di egresso può bloccare `169.254.169.254` per i pod del gateway. Il problema del limite di hop del nodo in [Troubleshooting](#troubleshooting) sottostante si applica solo ai cluster che saltano IRSA e si affidano ai ruoli dell'istanza del nodo.

472 </Tab>

473 </Tabs>

474 </Step>

475

476 <Step title="Spingere l'URL del gateway alle macchine degli sviluppatori">

477 Il gateway è ora in esecuzione, ma gli sviluppatori non possono raggiungerlo da `/login` fino a quando l'URL del gateway non è sulle loro macchine. Impostate `forceLoginMethod` e `forceLoginGatewayUrl` nel [file delle impostazioni gestite](/docs/it/claude-apps-gateway#set-the-gateway-url) che distribuite a ogni dispositivo tramite MDM. Non c'è opzione di gateway nel selettore di accesso per uno sviluppatore da selezionare manualmente.

478 </Step>

479</Steps>

480

481<h2 id="terraform-reference">

482 Riferimento Terraform

483</h2>

484

485Il bundle complementare a [`examples/gateway/aws`](https://github.com/anthropics/claude-code/tree/main/examples/gateway/aws) pacchetti questa pagina come codice:

486

487* **`setup.sh`** script la procedura dettagliata di provisioning sopra con gli stessi comandi `aws`, sul percorso ECS Fargate. È idempotente: le risorse esistenti vengono rilevate e saltate, quindi rieseguirlo è sicuro, e qualsiasi default può essere sovrascritto tramite variabile di ambiente. Voi create comunque il segreto del client OIDC Okta e il certificato ACM voi stessi: un'esecuzione senza di essi salta la distribuzione ECS/ALB, nomina gli input mancanti e stampa il comando `create-secret`; create entrambi e rieseguite. Il modulo del caso d'uso Bedrock e l'alias Route 53 vengono stampati come passaggi successivi piuttosto che eseguiti automaticamente, e il push MDM del client rimane un passaggio manuale da questa pagina.

488* **`gateway.yaml.example`** è il modello di configurazione dal passaggio gateway.yaml, con le chiavi opzionali incluse commentate. Copiatelo in `gateway.yaml` e sostituite ogni `REPLACE_ME` prima di compilare.

489* **`Dockerfile`** compila l'immagine di runtime dal binario precompilato `linux-x64` e copia il vostro `gateway.yaml` compilato a `/etc/claude/gateway.yaml`, più il bundle di certificati AWS RDS che ancora la connessione `sslmode=verify-full` dello store. `setup.sh` scarica il bundle solo quando non è già nel contesto di compilazione; eliminate il file e ricompilate sotto un nuovo tag per raccogliere una rotazione CA di AWS. Il file di configurazione non contiene valori segreti, poiché ogni credenziale si risolve all'avvio tramite l'espansione `${VAR}`. Una modifica della configurazione quindi significa una ricompilazione sotto un nuovo tag; `setup.sh` automatizza questo taggando le immagini con un hash del file.

490* **`terraform/`** esegue il provisioning dello stesso ambito ECS Fargate in modo dichiarativo: i gruppi di sicurezza, i ruoli IAM, il repository ECR, l'istanza RDS, i segreti di Secrets Manager e il servizio ECS dietro l'ALB interno. Il VPC e le subnet private rimangono prerequisiti, passati come variabili. Terraform crea il repository ECR ma non compila l'immagine, e la definizione del servizio fa riferimento all'immagine, quindi l'apply è due passaggi: un apply mirato per il repository, quindi la compilazione e il push, quindi l'apply completo. Il `terraform/README.md` del bundle copre le variabili, lo stato remoto e lo smantellamento.

491

492Come questa pagina, il bundle è un esempio funzionante per infrastrutture gestite dal cliente piuttosto che una distribuzione di produzione supportata; esaminate e adattate al vostro ambiente prima di affidarvi ad esso.

493

494<h2 id="troubleshooting">

495 Troubleshooting

496</h2>

497

498Per gli errori di avvio del gateway e di accesso, consultate la tabella di [troubleshooting](/docs/it/claude-apps-gateway-deploy#troubleshooting) indipendente dalla piattaforma. Le voci sottostanti sono specifiche di AWS.

499

500| Sintomo | Causa | Correzione |

501| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

502| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | Il nome del gateway si risolve in almeno un indirizzo pubblico. Un ALB interno dual-stack pubblica record AAAA di intervallo pubblico, e il [controllo della rete privata](/docs/it/claude-apps-gateway#prerequisites) richiede che ogni indirizzo risolto sia privato | Create l'ALB con `--ip-address-type ipv4`, o servite un nome DNS interno separato solo con nessun record AAAA pubblico |

503| Ogni richiesta Bedrock restituisce 502; il log mostra `Could not load credentials from any providers` | L'attività viene eseguita sul tipo di lancio ECS EC2 senza un ruolo di attività, o il pod viene eseguito su un nodo EKS senza IRSA, quindi le credenziali provengono dai metadati dell'istanza, che il limite di hop predefinito di IMDSv2 di 1 ferma dentro un contenitore. Nessuno dei due percorsi in questa pagina è interessato: i ruoli di attività Fargate e IRSA non utilizzano i metadati dell'istanza | Preferite i ruoli di attività e IRSA. Dove le credenziali dell'istanza sono inevitabili, aumentate il limite di hop con `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`; la [tabella indipendente dalla piattaforma](/docs/it/claude-apps-gateway-deploy#troubleshooting) copre i compromessi |

504| Le richieste Bedrock restituiscono `403 AccessDeniedException` | L'account non ha inviato il modulo del caso d'uso una tantum di Anthropic, l'iscrizione automatica AWS Marketplace che inizia al primo invoke dell'account non ha ancora finito, o la politica del ruolo di attività manca gli ARN del profilo di inferenza o del modello di base | Inviate il modulo del caso d'uso dalla catalogo dei modelli della console Bedrock; se è stato appena inviato o questo è il primo invoke dell'account, riprovate dopo alcuni minuti. Concedete `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` su entrambe le famiglie di ARN. |

505| Bedrock restituisce una `ValidationException` dicendo che la velocità effettiva on-demand non è supportata | Una voce `models:` personalizzata mappa a un ID del modello di base semplice che la regione serve solo tramite profili di inferenza | Mappate il modello all'ID del profilo di inferenza cross-region (`us.anthropic.*`) al posto; il catalogo integrato lo fa già |

506| L'attività ECS si ferma con `ResourceInitializationError` prima che il gateway registri qualcosa | Il ruolo di esecuzione non può leggere i segreti di Secrets Manager, o le subnet private non hanno percorso verso Secrets Manager o ECR | Concedete `secretsmanager:GetSecretValue` sui tre ARN dei segreti `gateway-` al ruolo di esecuzione, e fornite uscita tramite il gateway NAT, o, senza uno, endpoint dell'interfaccia per Secrets Manager, ECR e CloudWatch Logs, che il driver `awslogs` ha bisogno nella stessa fase, più un endpoint del gateway S3 |

507| L'avvio del gateway esce con un errore di timeout della connessione Postgres | Il gruppo di sicurezza del database non ammette il gruppo di sicurezza del gateway sulla porta 5432, o il servizio viene eseguito al di fuori del VPC del database; lo store smette di aspettare dopo 5 secondi | Consentite 5432 dal gruppo di sicurezza del gateway su quello del database, ed eseguite il servizio nello stesso VPC del gruppo di subnet del DB |

508| L'avvio del gateway esce con un errore di verifica del certificato TLS di Postgres | La stringa di connessione imposta `sslmode=verify-full` ma l'immagine non affida il bundle CA di RDS: il bundle non è stato copiato nell'immagine, o `NODE_EXTRA_CA_CERTS` non punta ad esso | Aggiungete le due righe del Dockerfile del passaggio di compilazione che copiano il bundle e impostano `NODE_EXTRA_CA_CERTS`, quindi ricompilate, spingete sotto un nuovo tag e ridistribuite |

509| Le risposte di streaming si interrompono a metà flusso dopo un periodo tranquillo | Un gateway più vecchio di v2.1.229 su un upstream Bedrock o Claude Platform su AWS non invia nulla mentre l'upstream è tranquillo, ad esempio durante il pensiero esteso senza output trasmesso. L'ALB chiude una connessione dopo 60 secondi senza dati per impostazione predefinita, quindi taglia il flusso a quel gap. I gateway v2.1.229 e successivi mantengono un flusso tranquillo sotto quel timeout: su quegli upstream il gateway emette un evento SSE `ping` una volta che circa 15 secondi passano senza dati di flusso, e su un upstream API Anthropic rilancia i ping propri dell'API | Aggiornate il gateway a v2.1.229 o successivo, o impostate l'attributo `idle_timeout.timeout_seconds` su `3600`, tramite `modify-load-balancer-attributes` o l'annotazione `load-balancer-attributes` Ingress su EKS |

510

511<h2 id="telemetry">

512 Telemetria

513</h2>

514

515Il gateway vi fornisce metriche di utilizzo per sviluppatore senza alcuna configurazione OTEL per macchina. Claude Code emette metriche, log e tracce OpenTelemetry (OTLP) opt-in; [Monitoraggio dell'utilizzo](/docs/it/monitoring-usage) copre tutto ciò che il CLI segnala. Sulle sessioni del gateway il CLI marca ogni esportazione con gli attributi di identità IdP autenticati `user.id`, `user.email` e `user.groups`, quindi l'utilizzo si accumula per sviluppatore senza alcun plumbing `OTEL_RESOURCE_ATTRIBUTES`.

516

517Il gateway stesso è un relè OTLP autenticato. Impostate [`telemetry.forward_to`](/docs/it/claude-apps-gateway-config#telemetry) insieme a `listen.public_url`, e spinge le impostazioni dell'esportatore OTEL a ogni client connesso e inoltra il loro traffico OTLP verbatim a ogni destinazione che elencate. Ogni destinazione opta per metriche, log e tracce indipendentemente, e l'impostazione predefinita è solo metriche; consultate il [riferimento `telemetry`](/docs/it/claude-apps-gateway-config#telemetry) per i campi per segnale e i loro compromessi di sensibilità. Il gateway non memorizza nel buffer, aggrega o archivia la telemetria, quindi dove i dati finiscono è interamente la configurazione dell'esportatore del collettore.

518

519La telemetria del client è disattivata per impostazione predefinita; configurare `telemetry.forward_to` è ciò che la attiva per gli sviluppatori connessi, e ogni client interattivo mostra una finestra di dialogo di approvazione della sicurezza una tantum per le impostazioni spinte, come descritto nel [riferimento di configurazione](/docs/it/claude-apps-gateway-config#telemetry). Su AWS, ogni segnale mappa a una destinazione come segue.

520

521<h3 id="client-metrics-logs-and-traces">

522 Metriche, log e tracce del client

523</h3>

524

525Puntate `telemetry.forward_to` a un collettore OpenTelemetry, come il [collettore AWS Distro for OpenTelemetry (ADOT)](https://aws-otel.github.io/), ed esportate da lì ad Amazon CloudWatch, Amazon Managed Service for Prometheus, o qualsiasi backend OTLP.

526

527Eseguite il collettore come suo proprio servizio interno raggiungibile su `https://`; il [riferimento `telemetry`](/docs/it/claude-apps-gateway-config#telemetry) copre l'eccezione di loopback e `CLAUDE_GATEWAY_ALLOW_LOOPBACK`.

528

529<h3 id="gateway-logs">

530 Log del gateway

531</h3>

532

533Su ECS Fargate, nessuna configurazione extra: il driver `awslogs` consegna stderr del gateway, che porta i suoi eventi di audit e log operazionali, al gruppo di log `/ecs/claude-gateway` creato sopra. Su EKS, i log dei pod non raggiungono CloudWatch per impostazione predefinita, quindi la traccia di audit viene persa fino a quando non installate la raccolta dei log: il componente aggiuntivo Amazon CloudWatch Observability con acquisizione dei log del contenitore abilitata, o un DaemonSet Fluent Bit. Su entrambi i percorsi, interrogate i log con CloudWatch Logs Insights e guidate gli allarmi dai filtri delle metriche.

534

535<h3 id="container-metrics">

536 Metriche del contenitore

537</h3>

538

539Abilitate Container Insights sul cluster con `aws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled` per CPU, memoria e rete per attività. Su EKS, installate il componente aggiuntivo Amazon CloudWatch Observability.

540

541<h3 id="spend">

542 Spesa

543</h3>

544

545La telemetria mostra l'utilizzo dopo il fatto; i [limiti di spesa](/docs/it/claude-apps-gateway-spend-limits) sono la vista live del gateway per sviluppatore e l'applicazione sulla credenziale upstream condivisa.

546

547<h2 id="next-steps">

548 Passaggi successivi

549</h2>

550

551* [Riferimento di configurazione](/docs/it/claude-apps-gateway-config): ogni opzione `gateway.yaml`, inclusi `managed.policies` e `telemetry`

552* [Distribuzione e operazioni](/docs/it/claude-apps-gateway-deploy): configurazione IdP, controlli di stato, rotazione della chiave segreta JWT, aggiornamenti e il modello di sicurezza

553* [Panoramica del gateway delle app Claude](/docs/it/claude-apps-gateway): quickstart e connessione degli sviluppatori

554* [Esempi AWS per il gateway delle app Claude](https://github.com/aws-samples/anthropic-on-aws/tree/main/claude-apps-gateway): esempi di distribuzione mantenuti da AWS che coprono una gamma di ambienti dei clienti

claude-code-on-the-web.md +18 −18

Details

42 42

43Le sessioni cloud hanno bisogno di accesso ai tuoi repository GitHub per clonare il codice e inviare i rami. Puoi concedere l'accesso in due modi:43Le sessioni cloud hanno bisogno di accesso ai tuoi repository GitHub per clonare il codice e inviare i rami. Puoi concedere l'accesso in due modi:

44 44

46| :--------------- | :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |46| :--------------- | :--------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |

47| **GitHub App** | Autorizza l'app Claude GitHub durante l'[onboarding web](/docs/it/web-quickstart). | Onboarding del browser; team che desiderano [Auto-fix](#auto-fix-pull-requests) |47| **GitHub App** | Autorizza l'app Claude GitHub durante l'[onboarding web](/docs/it/web-quickstart) | Qualsiasi repository pubblico e repository privati su cui è installata l'app Claude GitHub | Onboarding del browser; team che desiderano [Auto-fix](#auto-fix-pull-requests) |

48| **`/web-setup`** | Esegui `/web-setup` nel tuo terminale per sincronizzare il tuo token CLI `gh` locale al tuo account Claude. | Sviluppatori individuali che già usano `gh` |48| **`/web-setup`** | Esegui `/web-setup` nel tuo terminale per inviare il tuo token CLI `gh` locale al tuo account Claude | Qualsiasi repository a cui il tuo token `gh` può accedere, indipendentemente dal fatto che l'app sia installata o meno | Sviluppatori individuali che già usano `gh` |

49 49

~~50<Note>~~50L'installazione dell'app Claude GitHub su un repository abilita anche [Auto-fix](#auto-fix-pull-requests) per le pull request in esso.

51 Con entrambi i metodi, una sessione cloud può accedere a qualsiasi repository che l'account GitHub connesso può vedere, non solo ai repository su cui è installata l'app Claude GitHub. L'installazione dell'app abilita i webhook PR per [Auto-fix](#auto-fix-pull-requests); non è un controllo di accesso a livello di sessione. Per limitare quali repository il tuo team può raggiungere dalle sessioni cloud, limita l'accesso su GitHub stesso, ad esempio limitando l'appartenenza al team o al repository per gli account GitHub connessi.

~~52</Note>~~

53 51

54Entrambi i metodi funzionano. Per come `/schedule` verifica l'accesso prima di creare una routine, vedi [Repository e autorizzazioni di ramo](/docs/it/routines#repositories-and-branch-permissions). Vedi [Connetti dal tuo terminale](/docs/it/web-quickstart#connect-from-your-terminal) per la procedura dettagliata di `/web-setup`.52Per come `/schedule` verifica l'accesso al repository prima di creare una routine, vedi [Repository e autorizzazioni di ramo](/docs/it/routines#repositories-and-branch-permissions). Vedi [Connetti dal tuo terminale](/docs/it/web-quickstart#connect-from-your-terminal) per la procedura dettagliata di `/web-setup`, incluso ciò che `/web-setup` memorizza e come rimuoverlo.

55 53

56La configurazione rapida del web è un'impostazione dell'organizzazione che consente ai membri di connettere GitHub con `/web-setup`, salta il prompt di installazione dell'app Claude GitHub durante l'onboarding del browser e fa sì che l'onboarding del browser crei l'[ambiente **Default**](/docs/it/cloud-environments#the-default-environment) per loro invece di mostrare il modulo dell'ambiente. Nei piani Team ed Enterprise è disabilitato per impostazione predefinita, il che nasconde `/web-setup`. Un [Proprietario](/docs/it/server-managed-settings#access-control) lo attiva con l'interruttore **Quick web setup** su [**Impostazioni di amministrazione > Claude Code**](https://claude.ai/admin-settings/claude-code).54La configurazione rapida del web è un'impostazione dell'organizzazione che consente ai membri di connettere GitHub con `/web-setup`, salta il prompt di installazione dell'app Claude GitHub durante l'onboarding del browser e fa sì che l'onboarding del browser crei l'[ambiente **Default**](/docs/it/cloud-environments#the-default-environment) per loro invece di mostrare il modulo dell'ambiente. Nei piani Team ed Enterprise è disabilitato per impostazione predefinita, il che nasconde `/web-setup`. Un [Proprietario](/docs/it/server-managed-settings#access-control) lo attiva con l'interruttore **Quick web setup** su [**Impostazioni di amministrazione > Claude Code**](https://claude.ai/admin-settings/claude-code).

57 55

79claude --cloud "Fix the authentication bug in src/auth/login.ts"77claude --cloud "Fix the authentication bug in src/auth/login.ts"

80```78```

81 79

82Questo crea una nuova sessione cloud su claude.ai. La VM cloud clona il remoto GitHub della tua directory attuale al tuo ramo attuale, non il tuo checkout locale, quindi esegui il push prima se hai commit locali. `--cloud` funziona con un singolo repository alla volta. L'attività viene eseguita nel cloud mentre continui a lavorare localmente. L'ortografia più vecchia `--remote` funziona ancora come alias deprecato per `--cloud`.80Questo crea una nuova sessione cloud su claude.ai. La VM cloud clona il remoto GitHub della tua directory attuale al tuo ramo attuale, non il tuo checkout locale, quindi esegui il push prima se hai commit locali. Vedi [Invia repository locali senza GitHub](#send-local-repositories-without-github) per i casi in cui Claude Code carica il tuo repository locale invece di clonare.

82`--cloud` funziona con un singolo repository alla volta. L'attività viene eseguita nel cloud mentre continui a lavorare localmente. L'ortografia più vecchia `--remote` funziona ancora come alias deprecato per `--cloud`.

83 83

84Mentre il contenitore cloud si avvia, la CLI mostra un elenco di controllo in tempo reale dei passaggi di configurazione, come la clonazione del repository e l'esecuzione dello [script di configurazione](/docs/it/cloud-environments#setup-scripts). Accoda i messaggi che digiti durante il provisioning e li invia una volta che la sessione è pronta.84Mentre il contenitore cloud si avvia, la CLI mostra un elenco di controllo in tempo reale dei passaggi di configurazione, come la clonazione del repository e l'esecuzione dello [script di configurazione](/docs/it/cloud-environments#setup-scripts). Accoda i messaggi che digiti durante il provisioning e li invia una volta che la sessione è pronta.

85 85

121 Invia repository locali senza GitHub121 Invia repository locali senza GitHub

122</h4>122</h4>

123 123

124Quando esegui `claude --cloud` da un repository che non è connesso a GitHub, Claude Code raggruppa il tuo repository locale e lo carica direttamente nella sessione cloud. Il bundle include la tua cronologia completa del repository su tutti i rami, più eventuali modifiche non sottoposte a commit ai file tracciati.124Quando esegui `claude --cloud` da un repository che non ha un remoto git, o da un repository github.com su cui l'app GitHub di Claude non è installata, Claude Code raggruppa il tuo repository locale e lo carica direttamente nella sessione cloud. Questo si applica anche se hai connesso GitHub con `/web-setup`. Il bundle include la tua cronologia completa del repository su tutti i rami, più eventuali modifiche non sottoposte a commit ai file tracciati.

125 125

126Su macOS, Linux e WSL, Claude Code lascia fuori dall'upload le modifiche non sottoposte a commit ai file denominati come credenziali o chiavi e nomina i file che ha lasciato fuori. Questo copre i file `.env`, i file Terraform `*.tfvars` e i file di chiave come `id_rsa` e `*.pem`. La sessione inizia con la versione sottoposta a commit di ognuno, o senza il file se nessuno è sottoposto a commit. In un worktree collegato, submodulo o layout simile, Claude Code carica queste modifiche con il resto e nomina i file che carica.126Su macOS, Linux e WSL, Claude Code lascia fuori dall'upload le modifiche non sottoposte a commit ai file denominati come credenziali o chiavi e nomina i file che ha lasciato fuori. Questo copre i file `.env`, i file Terraform `*.tfvars` e i file di chiave come `id_rsa` e `*.pem`. La sessione inizia con la versione sottoposta a commit di ognuno, o senza il file se nessuno è sottoposto a commit. In un worktree collegato, submodulo o layout simile, Claude Code carica queste modifiche con il resto e nomina i file che carica.

127 127

128Questo fallback si attiva automaticamente quando l'accesso a GitHub non è disponibile. Per forzarlo anche quando GitHub è connesso, imposta `CCR_FORCE_BUNDLE=1`:128Per caricare un bundle anche quando Claude Code altrimenti clonerebbe dal remoto, imposta `CCR_FORCE_BUNDLE=1`:

129 129

130```bash theme={null}130```bash theme={null}

131CCR_FORCE_BUNDLE=1 claude --cloud "Run the test suite and fix any failures"131CCR_FORCE_BUNDLE=1 claude --cloud "Run the test suite and fix any failures"

136* La directory deve essere un repository git con almeno un commit136* La directory deve essere un repository git con almeno un commit

137* Il repository raggruppato deve essere inferiore a 100 MB. I repository più grandi ricadono nel raggruppamento solo del ramo attuale, quindi in uno snapshot squashed singolo dell'albero di lavoro e falliscono solo se lo snapshot è ancora troppo grande137* Il repository raggruppato deve essere inferiore a 100 MB. I repository più grandi ricadono nel raggruppamento solo del ramo attuale, quindi in uno snapshot squashed singolo dell'albero di lavoro e falliscono solo se lo snapshot è ancora troppo grande

138* I file non tracciati non sono inclusi; esegui `git add` sui file che desideri che la sessione cloud veda138* I file non tracciati non sono inclusi; esegui `git add` sui file che desideri che la sessione cloud veda

139* Le sessioni create da un bundle non possono eseguire il push di nuovo a un remoto a meno che tu non abbia anche [autenticazione GitHub](#github-authentication-options) configurata139* Le sessioni create da un bundle possono eseguire il push di nuovo a un remoto GitHub solo quando la tua [connessione GitHub](#github-authentication-options) ha accesso push a quel repository

140 140

141<h3 id="send-follow-ups-from-the-cli">141<h3 id="send-follow-ups-from-the-cli">

142 Invia follow-up dalla CLI142 Invia follow-up dalla CLI

261 261

262Ogni sessione mostra un indicatore di diff con righe aggiunte e rimosse, come `+42 -18`. Selezionarlo per aprire la visualizzazione diff, lasciare commenti in linea su righe specifiche e inviarli a Claude con il messaggio successivo.262Ogni sessione mostra un indicatore di diff con righe aggiunte e rimosse, come `+42 -18`. Selezionarlo per aprire la visualizzazione diff, lasciare commenti in linea su righe specifiche e inviarli a Claude con il messaggio successivo.

263 263

264Claude Code calcola questi diff, inclusi i diff per file mostrati mentre Claude modifica, dal contenuto grezzo del blob git, quindi i driver diff e i filtri `textconv` configurati nel repository non si applicano.264Claude Code calcola questi diff, inclusi i diff per file mostrati mentre Claude modifica, dal contenuto grezzo del blob git, quindi i driver diff e i filtri `textconv` configurati nel repository non si applicano. Per un file in un repository che non è uno dei checkout della sessione stessa, come uno clonato all'interno dell'area di lavoro durante la sessione, il diff per file mostra la modifica di Claude stessa piuttosto che un confronto git.

265 265

266Vedere [Rivedere e iterare](/docs/it/web-quickstart#review-and-iterate) per la procedura dettagliata completa inclusa la creazione di PR. Per fare in modo che Claude monitori automaticamente la PR per errori CI e commenti di revisione, vedere [Correzione automatica delle pull request](#auto-fix-pull-requests).266Vedere [Rivedere e iterare](/docs/it/web-quickstart#review-and-iterate) per la procedura dettagliata completa inclusa la creazione di PR. Per fare in modo che Claude monitori automaticamente la PR per errori CI e commenti di revisione, vedere [Correzione automatica delle pull request](#auto-fix-pull-requests).

267 267

352Ogni sessione cloud è separata dalla tua macchina e dalle altre sessioni attraverso diversi livelli:352Ogni sessione cloud è separata dalla tua macchina e dalle altre sessioni attraverso diversi livelli:

353 353

354* **Macchine virtuali isolate**: ogni sessione viene eseguita in una VM isolata gestita da Anthropic. Le sessioni che la tua organizzazione instrada a un [ambiente self-hosted](/docs/it/self-hosted-environments) vengono eseguite sulla tua infrastruttura, dove l'isolamento è responsabilità della tua distribuzione354* **Macchine virtuali isolate**: ogni sessione viene eseguita in una VM isolata gestita da Anthropic. Le sessioni che la tua organizzazione instrada a un [ambiente self-hosted](/docs/it/self-hosted-environments) vengono eseguite sulla tua infrastruttura, dove l'isolamento è responsabilità della tua distribuzione

355* **Controlli di accesso alla rete**: negli ambienti ospitati da Anthropic, l'accesso alla rete è limitato per impostazione predefinita e può essere disabilitato. In un ambiente self-hosted, limiti l'uscita della sessione al tuo confine di rete. Quando viene eseguito con l'accesso alla rete disabilitato, Claude Code può comunque comunicare con l'API Anthropic, che potrebbe consentire ai dati di uscire dalla VM.355* <span id="default-allowed-domains" />**Controlli di accesso alla rete**: negli ambienti ospitati da Anthropic, l'accesso alla rete è limitato per impostazione predefinita e può essere disabilitato. Vedi [Accesso alla rete](/docs/it/cloud-environments#network-access) per i livelli di accesso, i [domini consentiti per impostazione predefinita](/docs/it/cloud-environments#default-allowed-domains) e il traffico che non passa attraverso l'allowlist. In un ambiente self-hosted, limiti l'uscita della sessione al tuo confine di rete. Quando viene eseguito con l'accesso alla rete disabilitato, Claude Code può comunque comunicare con l'API Anthropic, che potrebbe consentire ai dati di uscire dalla VM.

356* **Protezione delle credenziali**: negli ambienti ospitati da Anthropic, le credenziali git e le chiavi di firma rimangono al di fuori della sandbox e un proxy autentica per conto della sessione con credenziali con ambito. In un ambiente self-hosted, la tua distribuzione fornisce credenziali git; vedi [Configura git](/docs/it/self-hosted-environments-deploy#configure-git)356* **Protezione delle credenziali**: negli ambienti ospitati da Anthropic, le credenziali git e le chiavi di firma rimangono al di fuori della sandbox e un proxy autentica per conto della sessione con credenziali con ambito. In un ambiente self-hosted, la tua distribuzione fornisce credenziali git; vedi [Configura git](/docs/it/self-hosted-environments-deploy#configure-git)

357* **Credenziali API**: negli ambienti ospitati da Anthropic nei piani Pro e Max, le chiavi che [aggiungi a un ambiente cloud](/docs/it/cloud-environments#add-api-credentials) rimangono al di fuori della sandbox allo stesso modo, allegate alle richieste corrispondenti dopo che lasciano la sessione. Un ambiente self-hosted non ha credenziali API e i piani Team ed Enterprise non le hanno ancora357* **Credenziali API**: negli ambienti ospitati da Anthropic nei piani Pro e Max, le chiavi che [aggiungi a un ambiente cloud](/docs/it/cloud-environments#add-api-credentials) rimangono al di fuori della sandbox allo stesso modo, allegate alle richieste corrispondenti dopo che lasciano la sessione. Un ambiente self-hosted non ha credenziali API e i piani Team ed Enterprise non le hanno ancora

358* **Analisi sicura**: il codice viene analizzato e modificato all'interno dell'ambiente isolato della sessione prima di creare PR358* **Analisi sicura**: il codice viene analizzato e modificato all'interno dell'ambiente isolato della sessione prima di creare PR

371 371

372* Controlla [status.claude.com](https://status.claude.com) per gli incidenti delle sessioni cloud372* Controlla [status.claude.com](https://status.claude.com) per gli incidenti delle sessioni cloud

373* Riprova dopo un minuto, poiché la capacità viene fornita su richiesta373* Riprova dopo un minuto, poiché la capacità viene fornita su richiesta

374* Conferma che il tuo repository sia raggiungibile. L'account GitHub che si connette deve avere accesso al repository su GitHub, tramite l'autorizzazione dell'app GitHub di Claude o un token `gh` sincronizzato tramite `/web-setup`. L'installazione dell'app sul repository non è richiesta. Vedi [Opzioni di autenticazione GitHub](#github-authentication-options).374* Conferma che la tua connessione GitHub possa raggiungere il repository seguendo [Nessun repository appare dopo la connessione di GitHub](/docs/it/web-quickstart#no-repositories-appear-after-connecting-github)

375 375

376<h3 id="unable-to-get-organization-uuid">376<h3 id="unable-to-get-organization-uuid">

377 Impossibile ottenere l'UUID dell'organizzazione377 Impossibile ottenere l'UUID dell'organizzazione

395 Ambiente scaduto395 Ambiente scaduto

396</h3>396</h3>

397 397

398Le sessioni cloud si fermano dopo un periodo di inattività e la VM della sessione viene recuperata. Sul web, la sessione è contrassegnata come scaduta nell'elenco delle sessioni.398Le sessioni cloud si fermano dopo un periodo di inattività e la VM della sessione viene recuperata. Una sessione conta come inattiva mentre attende che tu approvi una chiamata dello strumento [MCP connector](/docs/it/cloud-environments#network-access) o che tu acceda a un server MCP, e può scadere durante quell'attesa. Sul web, la sessione è contrassegnata come scaduta nell'elenco delle sessioni.

399 399

400Riapri la sessione da [claude.ai/code](https://claude.ai/code) per fornire una VM fresca con la cronologia della conversazione ripristinata. Il lavoro in background che era ancora in esecuzione quando la VM è stata recuperata, come subagent e comandi shell, non viene ripristinato.400Riapri la sessione da [claude.ai/code](https://claude.ai/code) per fornire una VM fresca con la cronologia della conversazione ripristinata. Il lavoro in background che era ancora in esecuzione quando la VM è stata recuperata, come subagent e comandi shell, non viene ripristinato.

401 401

407 407

408* **Limiti di velocità**: Claude Code sul web condivide i limiti di velocità con tutti gli altri utilizzi di Claude e Claude Code all'interno del tuo account. L'esecuzione di più attività in parallelo consuma più limiti di velocità proporzionalmente. Non esiste alcun addebito di calcolo separato per la VM cloud.408* **Limiti di velocità**: Claude Code sul web condivide i limiti di velocità con tutti gli altri utilizzi di Claude e Claude Code all'interno del tuo account. L'esecuzione di più attività in parallelo consuma più limiti di velocità proporzionalmente. Non esiste alcun addebito di calcolo separato per la VM cloud.

409* **Autenticazione del repository**: puoi spostare le sessioni da web a locale solo quando sei autenticato allo stesso account409* **Autenticazione del repository**: puoi spostare le sessioni da web a locale solo quando sei autenticato allo stesso account

410* **Restrizioni della piattaforma**: il clonaggio del repository e la creazione di pull request richiedono GitHub. Le istanze self-hosted di [GitHub Enterprise Server](/docs/it/github-enterprise-server) sono supportate per i piani Team ed Enterprise. GitLab, Bitbucket e altri repository non GitHub possono essere inviati alle sessioni cloud come [bundle locale](#send-local-repositories-without-github), ma la sessione non può eseguire il push dei risultati di nuovo al remoto410* **Restrizioni della piattaforma**: il clonaggio del repository e la creazione di pull request richiedono GitHub. Le istanze self-hosted di [GitHub Enterprise Server](/docs/it/github-enterprise-server) sono supportate per i piani Team ed Enterprise. Puoi inviare un repository GitLab, Bitbucket o altro non-GitHub a una sessione cloud come [bundle locale](#send-local-repositories-without-github) impostando `CCR_FORCE_BUNDLE=1`, ma la sessione non può eseguire il push dei risultati di nuovo a quel remoto

411* **Elenco IP consentiti dell'organizzazione**: le sessioni cloud chiamano l'API Anthropic dall'infrastruttura gestita da Anthropic, non dalla tua rete, mentre le sessioni in un [ambiente self-hosted](/docs/it/self-hosted-environments) la chiamano dalla tua rete. Se la tua organizzazione ha [IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting) abilitato, ogni sessione cloud ospitata da Anthropic fallisce con un errore di autenticazione. Lo stesso vale per [Code Review](/docs/it/code-review) e per [Routine](/docs/it/routines) che vengono eseguite su ambienti ospitati da Anthropic; una routine instradata a un ambiente self-hosted chiama l'API dalla tua rete. Contatta il [supporto Anthropic](https://support.claude.com/) per esentare i servizi ospitati da Anthropic dall'elenco IP consentiti della tua organizzazione.411* **Elenco IP consentiti dell'organizzazione**: le sessioni cloud chiamano l'API Anthropic dall'infrastruttura gestita da Anthropic, non dalla tua rete, mentre le sessioni in un [ambiente self-hosted](/docs/it/self-hosted-environments) la chiamano dalla tua rete. Se la tua organizzazione ha [IP allowlisting](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting) abilitato, ogni sessione cloud ospitata da Anthropic fallisce con un errore di autenticazione. Lo stesso vale per [Code Review](/docs/it/code-review) e per [routine](/docs/it/routines) che vengono eseguite su ambienti ospitati da Anthropic; una routine instradata a un ambiente self-hosted chiama l'API dalla tua rete. Contatta il [supporto Anthropic](https://support.claude.com/) per esentare i servizi ospitati da Anthropic dall'elenco IP consentiti della tua organizzazione.

412 412

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

414 Risorse correlate414 Risorse correlate

claude-security.md +171 −0 created

Details

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.

5# Scansiona il tuo codebase per le vulnerabilità

7> Installa il plugin Claude Security per scansionare il tuo codebase alla ricerca di vulnerabilità in una sessione Claude Code e trasforma i risultati in patch che esamini e applichi.

9Il plugin Claude Security esegue una scansione multi-agente delle vulnerabilità del tuo codebase all'interno di una sessione Claude Code. Un team di agenti Claude mappa la tua architettura, costruisce un modello di minaccia, ricerca le vulnerabilità e esamina indipendentemente ogni risultato prima di scrivere il rapporto. Utilizza il plugin per scansionare un intero repository o [solo un set di modifiche](#scan-only-your-changes), come il diff di un branch, il diff di una pull request o un singolo commit, quindi trasforma i risultati che scegli in patch che esamini e applichi tu stesso.

11Il plugin viene eseguito localmente nella tua sessione, utilizza i modelli a cui hai accesso in Claude Code, e ogni scansione conta rispetto ai limiti di utilizzo del tuo piano. Se desideri un servizio gestito che monitori i tuoi repository, o desideri eseguire scansioni su [Claude Mythos 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5), consulta il prodotto [Claude Security](https://claude.com/product/claude-security), disponibile nel piano Enterprise. Il plugin raggiunge il codice che il prodotto gestito non può raggiungere, come i repository ospitati su GitLab o Bitbucket, o su reti che non consentono connessioni in entrata.

13Il plugin è anche distinto dagli strumenti di revisione già presenti in Claude Code: il [plugin security guidance](/docs/it/security-guidance) esamina il codice mentre Claude lo scrive, [`/security-review`](/docs/it/commands#all-commands) esegue un singolo passaggio sul tuo branch, e [Code Review](/docs/it/code-review) esamina le pull request. Per capire come i livelli si sovrappongono, consulta [Come il plugin si integra con altri strumenti di sicurezza](#how-the-plugin-fits-with-other-security-tools).

15<h2 id="prerequisites">

16 Prerequisiti

17</h2>

19Per eseguire il plugin, hai bisogno di:

21* Un piano a pagamento, per i [dynamic workflows](/docs/it/workflows) che la scansione utilizza per orchestrare i suoi agenti. Su Pro, attivali dalla riga Dynamic workflows in `/config`.

22* Python 3.9 o successivo disponibile nel tuo `PATH` come `python3`. Verifica con `python3 --version`. Gli strumenti del plugin utilizzano solo la libreria standard di Python, quindi non viene installato nulla.

23* Linux, macOS o Windows.

24* Git, per le scansioni di modifiche e per trasformare i risultati in patch; questi lavori non supportano altri sistemi di controllo versione. Una scansione completa funziona in qualsiasi directory, con o senza controllo versione.

26<h2 id="install-the-plugin">

27 Installa il plugin

28</h2>

30In una sessione Claude Code, installa dal [marketplace ufficiale Anthropic](/docs/it/discover-plugins#official-anthropic-marketplace):

32```text theme={null}

33/plugin install claude-security@claude-plugins-official

34```

36Il comando apre i dettagli del plugin, dove scegli un [ambito di installazione](/docs/it/discover-plugins#install-plugins) per avviare l'installazione.

38Se l'installazione non riesce, la soluzione dipende dal messaggio che Claude Code segnala:

40* Se segnala `Marketplace "claude-plugins-official" not found`, aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

41* Se segnala che non riesce a [trovare il plugin nel marketplace](/docs/it/discover-plugins#install-plugins), controlla il nome del plugin per eventuali errori di digitazione.

43Controlla il riepilogo dell'installazione. Se segnala `Run /reload-plugins to activate.`, consulta [Applica le modifiche del plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) per attivare il plugin nella tua sessione corrente.

45Una volta che il plugin è attivo, sei pronto a [scansionare e correggere il tuo codebase](#scan-and-fix-your-codebase).

47<h3 id="uninstall-the-plugin">

48 Disinstalla il plugin

49</h3>

51Per rimuovere il plugin, disinstallalo dal menu `/plugin`, oppure esegui `claude plugin uninstall claude-security` nel tuo terminale.

53<h2 id="scan-and-fix-your-codebase">

54 Scansiona e correggi il tuo codebase

55</h2>

57Il plugin aggiunge un comando, `/claude-security`, che apre un menu dei suoi tre lavori: scansionare il codebase, scansionare un set di modifiche e suggerire patch. Il percorso felice esegue una scansione completa, quindi trasforma i suoi risultati in patch:

59<Steps>

60 <Step title="Apri il menu Claude Security">

61 Esegui `/claude-security` e scegli **Scan codebase**.

62 </Step>

64 <Step title="Scegli cosa scansionare">

65 Il plugin legge prima il tuo repository, quindi offre l'intero repository o un'area focalizzata, con il conteggio dei file e il costo relativo di ogni opzione indicati. Scegli l'intero repository, oppure rispondi "I don't know" e il plugin sceglie un valore predefinito sensato per la dimensione del tuo repository.

66 </Step>

68 <Step title="Conferma l'esecuzione">

69 Una scansione può richiedere un po' di tempo, può utilizzare un numero significativo di token e richiede che Claude Code rimanga aperto mentre si completa. Nulla viene eseguito finché non confermi.

70 </Step>

72 <Step title="Leggi il rapporto">

73 Mentre la scansione viene eseguita, segnala ogni fase mentre inizia, con i dettagli disponibili in [`/workflows`](/docs/it/workflows). I risultati si trovano in una directory con timestamp nel tuo repository, descritta in [Leggi i risultati della scansione](#read-the-scan-results).

74 </Step>

76 <Step title="Trasforma i risultati in patch">

77 Esegui `/claude-security` di nuovo e scegli **Suggest patches**, quindi scegli quali risultati affrontare. Le patch esaminate si trovano nella cartella `patches/` del rapporto; [Correggi i risultati](#fix-findings) spiega come ogni patch viene costruita ed esaminata.

78 </Step>

80 <Step title="Applica le patch che accetti">

81 Applica ogni patch dalla tua shell con `git apply`, nella sua stessa pull request. Le patch non vengono mai applicate automaticamente.

82 </Step>

83</Steps>

85Non devi iniziare dal menu: chiedi un lavoro direttamente, come argomenti del comando, come `/claude-security scan my branch`, o in linguaggio naturale, come "scan commit abc1234". Il plugin funziona meglio in [auto mode](/docs/it/permission-modes), che consente agli agenti della scansione di procedere senza un prompt di autorizzazione ad ogni passaggio.

87<h3 id="scan-only-your-changes">

88 Scansiona solo le tue modifiche

89</h3>

91Quando il tuo branch ha commit che la base non ha, il menu `/claude-security` offre di scansionare solo quel diff, così puoi controllare un branch prima di unirlo. Puoi anche scansionare una delle tue pull request aperte, o un singolo commit chiedendolo, come "scan commit abc1234". Vengono scansionate solo le modifiche committate: esegui prima il commit o lo stash delle modifiche in corso, oppure esegui una scansione completa, che legge l'albero di lavoro.

93Le scansioni di modifiche richiedono un repository git; le scansioni complete di una directory senza versione funzionano comunque. Trovare le tue pull request aperte è l'unico passaggio che raggiunge la rete, ed è offerto solo quando la tua sessione ha già il permesso di eseguire la CLI di GitHub e `gh` è connesso.

95<h3 id="scope-large-repositories">

96 Delimita i repository di grandi dimensioni

97</h3>

99Su un repository di grandi dimensioni, scansiona un'area alla volta invece dell'intero albero. Scegli uno degli ambiti focalizzati che il plugin offre, come il tuo livello API o il tuo codice di autenticazione, e l'esecuzione si dimensiona in base a quello che scegli. La sezione di copertura del rapporto indica cosa è stato e non è stato esaminato. Esegui un'altra scansione su un'area diversa in qualsiasi momento.

100

101<h3 id="read-the-scan-results">

102 Leggi i risultati della scansione

103</h3>

104

105Ogni scansione scrive i suoi risultati in una directory `CLAUDE-SECURITY-<timestamp>/` con timestamp nel tuo repository:

106

107* **`CLAUDE-SECURITY-RESULTS.md`**: il rapporto, con l'ID di ogni risultato, come `F1`, più il suo impatto, lo scenario di exploit, la gravità, la confidenza e la raccomandazione

108* **`CLAUDE-SECURITY-RESULTS.jsonl`**: gli stessi risultati in forma leggibile da macchina, un oggetto JSON per riga

109* **`CLAUDE-SECURITY-RESULTS.sarif`**: gli stessi risultati come un log [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) per la scansione del codice GitHub e qualsiasi altro strumento che legge lo standard. La scansione classifica i risultati secondo le loro categorie di debolezza [CWE](https://cwe.mitre.org/)

110* **`CLAUDE-SECURITY-REVISION-<commit>.json`**: il timbro di revisione, che registra quale commit è stato scansionato, con quale sforzo, se le modifiche non sottoposte a commit facevano parte dell'albero scansionato e quanto accuratamente l'esecuzione è stata verificata, così un rapporto è sempre legato al codice che descrive. Una scansione al di fuori del controllo versione timbra `UNVERSIONED` al posto del commit

111

112Quella directory è l'unica modifica che una scansione apporta al tuo checkout, e ha il suo `.gitignore`, così un `git add` casuale non spazza mai un rapporto in un commit. Per mantenere un rapporto nella cronologia per un audit trail, elimina quel singolo file `.gitignore` e esegui il commit della directory come qualsiasi altro.

113

114I risultati appaiono nel rapporto solo dopo che gli agenti verificatori indipendenti li analizzano, il che mantiene i rapporti brevi e degni di lettura. Le scansioni sono non deterministiche: due scansioni dello stesso codice possono far emergere risultati diversi. Esegui scansioni regolarmente e utilizza i timbri di revisione per attribuire ogni rapporto al codice esatto e alle impostazioni che ha coperto.

115

116<h2 id="fix-findings">

117 Correggi i risultati

118</h2>

119

120Avvia il flusso di correzione scegliendo **Suggest patches** dal menu `/claude-security`, o chiedi in linguaggio naturale, come "fix finding F3", quindi scegli quali risultati dal rapporto affrontare. Le patch vengono costruite rispetto al codice sottoposto a commit, e il rapporto deve ancora descrivere il codice che hai: i risultati il cui codice è cambiato nel frattempo vengono saltati con una nota, e il plugin offre una scansione fresca invece di applicare patch da un rapporto obsoleto. Ogni patch viene redatta in una copia scratch del tuo repository, così i tuoi file sorgente rimangono intatti finché non applichi una patch tu stesso.

121

122Prima della consegna, ogni patch viene esaminata da un agente indipendente da quello che l'ha scritta, che esegue i test del tuo progetto rispetto alla modifica quando il codice li ha e legge il diff per conto suo per qualsiasi cosa nuova che potrebbe introdurre. Una patch viene scritta solo quando quella revisione può garantire che la modifica affronta il risultato, non introduce alcuna nuova vulnerabilità e lascia il comportamento altrimenti invariato. Quando non può garantire tutti e tre, ricevi una breve nota che spiega il motivo invece di una patch.

123

124<h3 id="patches-are-never-applied-automatically">

125 Le patch non vengono mai applicate automaticamente

126</h3>

127

128Applicare una patch è sempre una tua decisione. Le patch si trovano nella cartella `patches/` del rapporto, una `F<n>.patch` per risultato con una nota accanto che spiega la modifica. Applica una dalla tua shell, o chiedi a Claude di applicarla e aprire una pull request:

129

130```bash theme={null}

131git apply CLAUDE-SECURITY-<timestamp>/patches/F1.patch

132```

133

134Quando il codice con patch non ha test, la nota della patch lo dice, così sai che la sua revisione è stata eseguita senza un passaggio di test. Applica ogni patch nella sua stessa pull request così può essere esaminata e testata per conto suo.

135

136<h2 id="how-the-plugin-fits-with-other-security-tools">

137 Come il plugin si integra con altri strumenti di sicurezza

138</h2>

139

140Il plugin Claude Security è il livello di scansione profonda su richiesta in uno stack di difesa in profondità, insieme al [plugin security guidance](/docs/it/security-guidance), [`/security-review`](/docs/it/commands#all-commands), [Code Review](/docs/it/code-review), al prodotto gestito [Claude Security](https://claude.com/product/claude-security) e ai tuoi scanner esistenti:

141

142| Fase | Strumento | Cosa copre |

143| :------------------------------- | :------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------ |

144| In sessione | [Plugin security guidance](/docs/it/security-guidance) | Vulnerabilità comuni nel codice che Claude scrive, corrette nella stessa sessione |

145| Su richiesta, singolo passaggio | [`/security-review`](/docs/it/commands#all-commands) | Un passaggio di sicurezza una tantum sul branch corrente |

146| Su richiesta, scansione profonda | Plugin Claude Security | Scansione multi-agente di un repository o diff, con risultati e patch esaminati indipendentemente |

147| Su pull request | [Code Review](/docs/it/code-review), piani Team e Enterprise | Revisione multi-agente di correttezza e sicurezza con contesto completo del codebase |

148| Gestito | [Claude Security](https://claude.com/product/claude-security), piano Enterprise | Scansione ospitata che monitora i repository connessi |

149| In CI | I tuoi scanner di analisi statica e dipendenze esistenti | Regole specifiche del linguaggio, controlli della catena di approvvigionamento e applicazione delle politiche |

150

151Il plugin non sostituisce i tuoi strumenti di sicurezza del codice sorgente esistenti. Eseguilo insieme all'analisi statica, alla scansione delle dipendenze e alla revisione del codice: ragiona sul tuo codice nel modo in cui farebbe un ricercatore di sicurezza umano, il che completa i controlli deterministici che questi strumenti forniscono.

152

153<h2 id="troubleshooting">

154 Risoluzione dei problemi

155</h2>

156

157**Il menu `/claude-security` si apre con un avviso Python.** Il plugin ha bisogno di `python3` 3.9 o successivo nel tuo `PATH`. Quando non riesce a trovare `python3` affatto, il menu avverte che Claude Security non funzionerà finché uno non viene installato; quando il primo `python3` nel tuo `PATH` è più vecchio, l'avviso nomina la versione che ha trovato. Installa Python 3, o metti un `python3` più recente per primo nel tuo `PATH`, quindi avvia una nuova sessione.

158

159**Potresti vedere un avviso "safeguards flagged this message" quando esegui la scansione su un modello Fable.** Il messaggio nomina il modello, ad esempio "I safeguards di Fable 5.1 hanno contrassegnato questo messaggio". I classificatori di sicurezza della cibersicurezza di Fable contrassegnano determinate richieste, e Claude Code riesegue una richiesta contrassegnata su un modello Opus attraverso il [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback). Questo è previsto, e la scansione dovrebbe comunque completarsi con successo.

160

161<h2 id="related-resources">

162 Risorse correlate

163</h2>

164

165Per approfondire i pezzi che questa pagina tocca:

166

167* [Plugin security guidance](/docs/it/security-guidance): cattura i problemi nel codice mentre Claude lo scrive, nella stessa sessione

168* [Code Review](/docs/it/code-review): configura la revisione multi-agente al momento della PR

169* [Claude Security](https://claude.com/product/claude-security): il servizio gestito che monitora i repository connessi

170* [Sicurezza di Claude Code](/docs/it/security): come Claude Code affronta la fiducia, i permessi e i salvaguardie

171* [Scopri e installa plugin](/docs/it/discover-plugins#official-anthropic-marketplace): sfoglia altri plugin ufficiali

claude-tag.md +11 −0 created

Details

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.

5# Claude Tag

7> Porta Claude nei canali Slack del tuo team con Claude Tag e trova la documentazione di configurazione e utilizzo su claude.com.

9[Claude Tag](https://claude.com/product/tag) è un'integrazione Slack che esegue `@Claude` nei canali del tuo team come identità condivisa dell'organizzazione con accesso configurato dall'amministratore. Chiunque in un canale può taggare `@Claude` in un thread e assegnargli un'attività. Leggi la [documentazione di Claude Tag](https://claude.com/docs/claude-tag/overview) su claude.com per configurarlo e iniziare a utilizzarlo.

11Claude Tag è disponibile sui piani Team ed Enterprise ed è distinto dal precedente [Claude Code in Slack](/docs/it/slack), che esegue ogni sessione con l'account di un singolo utente. Sui piani Pro e Max, dove Claude Tag non è disponibile, Claude Code in Slack rimane il percorso di configurazione.

cli-reference.md +24 −12

Details

13Puoi avviare sessioni, inviare contenuti tramite pipe, riprendere conversazioni e gestire gli aggiornamenti con questi comandi:13Puoi avviare sessioni, inviare contenuti tramite pipe, riprendere conversazioni e gestire gli aggiornamenti con questi comandi:

14 14

16| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |16| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |

34| `claude daemon status` | Stampa lo stato del [supervisore](/docs/it/agent-view#the-supervisor-process) della sessione in background, versione, directory socket e numero di worker per la diagnostica. Esce con 1 se il supervisore non è in esecuzione | `claude daemon status` |34| `claude daemon status` | Stampa lo stato del [supervisore](/docs/it/agent-view#the-supervisor-process) della sessione in background, versione, directory socket e numero di worker per la diagnostica. Esce con 1 se il supervisore non è in esecuzione | `claude daemon status` |

35| `claude daemon stop --any` | Interrompi il [supervisore](/docs/it/agent-view#the-supervisor-process) della sessione in background e le sessioni che ospita. Passa `--keep-workers` per lasciare le sessioni in background in esecuzione in modo che il supervisore successivo si riconnetta ad esse. `--any` conferma l'interruzione di un supervisore su richiesta, che è l'impostazione predefinita. Usa questo per recuperare da un [supervisore che non risponde](/docs/it/agent-view#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` |35| `claude daemon stop --any` | Interrompi il [supervisore](/docs/it/agent-view#the-supervisor-process) della sessione in background e le sessioni che ospita. Passa `--keep-workers` per lasciare le sessioni in background in esecuzione in modo che il supervisore successivo si riconnetta ad esse. `--any` conferma l'interruzione di un supervisore su richiesta, che è l'impostazione predefinita. Usa questo per recuperare da un [supervisore che non risponde](/docs/it/agent-view#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` |

36| `claude doctor` | Stampa diagnostica di installazione e impostazioni di sola lettura dal terminale senza avviare una sessione, inclusa la salute dell'installazione, errori di convalida del file di impostazioni e idoneità al Controllo Remoto. Per il controllo di configurazione in-sessione che può anche applicare correzioni, esegui [`/doctor`](/docs/it/commands#all-commands) | `claude doctor` |36| `claude doctor` | Stampa diagnostica di installazione e impostazioni di sola lettura dal terminale senza avviare una sessione, inclusa la salute dell'installazione, errori di convalida del file di impostazioni e idoneità al Controllo Remoto. Per il controllo di configurazione in-sessione che può anche applicare correzioni, esegui [`/doctor`](/docs/it/commands#all-commands) | `claude doctor` |

37| `claude import [codex\|gemini]` | Avvia una sessione interattiva che esegue [`/import`](/docs/it/commands#all-commands) per portare la configurazione da altri agenti di codifica in Claude Code. Accetta le stesse opzioni `--dry-run` e `--yes` del comando. Non disponibile su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry o Claude Platform su AWS. Anche non disponibile quando disattivi il [recupero dei feature flag](/docs/it/env-vars#features-that-need-feature-flag-fetching). Richiede Claude Code v2.1.213 o successivo | `claude import codex --dry-run` |37| `claude import [source]` | Avvia una sessione interattiva che esegue [`/import`](/docs/it/commands#all-commands) per portare la configurazione da altri agenti di codifica in Claude Code. Accetta le stesse opzioni `--dry-run` e `--yes` del comando. Non disponibile su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry o Claude Platform su AWS. Anche non disponibile quando disattivi il [recupero dei feature flag](/docs/it/env-vars#features-that-need-feature-flag-fetching). Richiede Claude Code v2.1.213 o successivo | `claude import codex --dry-run` |

40| `claude mcp login <name>` | Esegui il flusso OAuth di un server MCP configurato senza aprire il pannello interattivo `/mcp`. Funziona per server HTTP, SSE e connettori claude.ai. Aggiungi `--no-browser` su SSH per stampare l'URL di autorizzazione invece di aprire un browser, quindi incolla l'URL di reindirizzamento al prompt. Richiede Claude Code v2.1.186 o successivo. Vedi [Autentica dalla riga di comando](/docs/it/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |40| `claude mcp login <name>` | Esegui il flusso OAuth di un server MCP configurato senza aprire il pannello interattivo `/mcp`. Funziona per server HTTP, SSE e connettori claude.ai. Aggiungi `--no-browser` su SSH per stampare l'URL di autorizzazione invece di aprire un browser, quindi incolla l'URL di reindirizzamento al prompt. Richiede Claude Code v2.1.186 o successivo. Vedi [Autentica dalla riga di comando](/docs/it/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

43| `claude project purge [path]` | Elimina tutto lo stato locale di Claude Code per un progetto: trascrizioni, elenchi di attività, log di debug, cronologia delle modifiche ai file, righe della cronologia dei prompt e la voce del progetto in `~/.claude.json`. Ometti `[path]` per scegliere da un elenco interattivo. Flag: `--dry-run` per visualizzare un'anteprima, `-y`/`--yes` per saltare la conferma, `-i`/`--interactive` per confermare ogni elemento, `--all` per ogni progetto. Vedi [Cancella dati locali](/docs/it/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |43| `claude project purge [path]` | Elimina tutto lo stato locale di Claude Code per un progetto: trascrizioni, elenchi di attività, log di debug, cronologia delle modifiche ai file, righe della cronologia dei prompt e la voce del progetto in `~/.claude.json`. Ometti `[path]` per scegliere da un elenco interattivo. Flag: `--dry-run` per visualizzare un'anteprima, `-y`/`--yes` per saltare la conferma, `-i`/`--interactive` per confermare ogni elemento, `--all` per ogni progetto. Vedi [Cancella dati locali](/docs/it/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |

44| `claude remote-control` | Avvia un server [Remote Control](/docs/it/remote-control) per controllare Claude Code da Claude.ai o dall'app Claude. Viene eseguito in modalità server (nessuna sessione interattiva locale). Vedi [Flag modalità server](/docs/it/remote-control#start-a-remote-control-session). Dopo aver interrotto il server, puoi ripristinare le sessioni che stava servendo. Vedi [Riprendi sessioni dopo aver interrotto il server](/docs/it/remote-control#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |44| `claude remote-control` | Avvia un server [Remote Control](/docs/it/remote-control) per controllare Claude Code da Claude.ai o dall'app Claude. Viene eseguito in modalità server (nessuna sessione interattiva locale). Vedi [Flag modalità server](/docs/it/remote-control#start-a-remote-control-session). Dopo aver interrotto il server, puoi ripristinare le sessioni che stava servendo. Vedi [Riprendi sessioni dopo aver interrotto il server](/docs/it/remote-control#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |

45| `claude respawn <id>` | Riavvia una [sessione in background](/docs/it/agent-view#manage-sessions-from-the-shell), in esecuzione o interrotta, mantenendo la sua conversazione intatta. Usa `--all` per riavviare ogni sessione in esecuzione, ad esempio per raccogliere un binario Claude Code aggiornato | `claude respawn 7c5dcf5d` |45| `claude respawn <id>` | Riavvia una [sessione in background](/docs/it/agent-view#manage-sessions-from-the-shell), in esecuzione o interrotta, mantenendo la sua conversazione intatta. Usa `--all` per riavviare ogni sessione in esecuzione, ad esempio per raccogliere un binario Claude Code aggiornato | `claude respawn 7c5dcf5d` |

46| `claude rm <id>` | Rimuovi una [sessione in background](/docs/it/agent-view#manage-sessions-from-the-shell) dall'elenco. La trascrizione della conversazione rimane sul tuo computer locale, disponibile tramite `claude --resume` | `claude rm 7c5dcf5d` |46| `claude rm <id>` | Rimuovi una [sessione in background](/docs/it/agent-view#manage-sessions-from-the-shell) dall'elenco. Quando la rimozione viene [rifiutata sul worktree della sessione](/docs/it/agent-view#what-deleting-a-session-removes) e un secondo `claude rm` può risolverlo, il rifiuto stampa il flag esatto e il valore da passare: `--discard-unpushed <commit>@<worktree-id>` scarta un worktree che ha commit non inviati insieme a quei commit, e `--force-remove-worktree <worktree-id>` elimina una directory worktree che git o l'hook `WorktreeRemove` non potevano rimuovere. `--discard-unpushed` richiede Claude Code v2.1.260 o successivo, e `--force-remove-worktree` richiede v2.1.268 o successivo. La trascrizione della conversazione rimane sul tuo computer locale, disponibile tramite `claude --resume` | `claude rm 7c5dcf5d` |

47| `claude self-hosted-runner` | Avvia un processo runner che registra questa macchina o contenitore con un [ambiente auto-ospitato](/docs/it/self-hosted-environments) e ospita sessioni cloud di Claude Code sulla tua infrastruttura. Esegui `claude self-hosted-runner setup` per una procedura guidata dell'operatore, `claude self-hosted-runner doctor` per [diagnosticare un runner distribuito](/docs/it/self-hosted-environments-deploy#troubleshooting) e `claude self-hosted-runner orchestrator` per generare [runner su richiesta](/docs/it/self-hosted-environments-configuration#on-demand-runners). Richiede Claude Code v2.1.224 o successivo | `claude self-hosted-runner setup` |47| `claude self-hosted-runner` | Avvia un processo runner che registra questa macchina o contenitore con un [ambiente auto-ospitato](/docs/it/self-hosted-environments) e ospita sessioni cloud di Claude Code sulla tua infrastruttura. Esegui `claude self-hosted-runner setup` per una procedura guidata dell'operatore, `claude self-hosted-runner doctor` per [diagnosticare un runner distribuito](/docs/it/self-hosted-environments-deploy#troubleshooting) e `claude self-hosted-runner orchestrator` per generare [runner su richiesta](/docs/it/self-hosted-environments-configuration#on-demand-runners). Richiede Claude Code v2.1.224 o successivo | `claude self-hosted-runner setup` |

48| `claude setup-token` | Genera un token OAuth di lunga durata per CI e script. Stampa il token nel terminale senza salvarlo. Richiede un abbonamento Claude. Vedi [Genera un token di lunga durata](/docs/it/authentication#generate-a-long-lived-token) | `claude setup-token` |48| `claude setup-token` | Genera un token OAuth di lunga durata per CI e script. Stampa il token nel terminale senza salvarlo. Richiede un abbonamento Claude. Vedi [Genera un token di lunga durata](/docs/it/authentication#generate-a-long-lived-token) | `claude setup-token` |

85| `--debug` | Abilita la modalità debug con filtro di categoria opzionale, come `--debug='mcp,startup'` o `--debug='!1p'`. Il filtro si lega solo nella forma `=`; un filtro separato da spazi abilita la modalità debug senza filtrare | `claude --debug='mcp,startup'` |85| `--debug` | Abilita la modalità debug con filtro di categoria opzionale, come `--debug='mcp,startup'` o `--debug='!1p'`. Il filtro si lega solo nella forma `=`; un filtro separato da spazi abilita la modalità debug senza filtrare | `claude --debug='mcp,startup'` |

86| `--debug-file <path>` | Scrivi i log di debug in un percorso file specifico. Abilita implicitamente la modalità debug. Ha la precedenza su `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |86| `--debug-file <path>` | Scrivi i log di debug in un percorso file specifico. Abilita implicitamente la modalità debug. Ha la precedenza su `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |

88| `--disallowedTools`, `--disallowed-tools` | Regole di negazione. Un nome di strumento nudo rimuove gli strumenti corrispondenti dal contesto di Claude: `"Edit"` rimuove Edit, `"*"` rimuove ogni strumento e `"mcp__*"` rimuove ogni strumento MCP. Una regola con ambito come `Bash(rm *)` lascia lo strumento disponibile e nega solo le chiamate corrispondenti. Una regola che nomina [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior) non può rimuoverlo mentre rimane qualsiasi altro strumento | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |88| `--disallowedTools`, `--disallowed-tools` | Regole di negazione. Un nome di strumento nudo rimuove gli strumenti corrispondenti dal contesto di Claude: `"Edit"` rimuove Edit, `"*"` rimuove ogni strumento e `"mcp__*"` rimuove ogni strumento MCP. Una regola con ambito come `Bash(rm *)` lascia lo strumento disponibile e nega solo le chiamate corrispondenti come scritto]\(/it/permissions#bash-rule-limits). Una regola che nomina [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior) non può rimuoverlo mentre rimane qualsiasi altro strumento | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

89| `--effort` | Imposta il [livello di sforzo](/docs/it/model-config#adjust-effort-level) per la sessione corrente. Opzioni: `low`, `medium`, `high`, `xhigh`, `max`, o `ultracode`. I livelli disponibili dipendono dal modello. `ultracode` avvia la sessione a livello di sforzo `xhigh` con [ultracode](/docs/it/workflows#let-claude-decide-with-ultracode) attivato e richiede Claude Code v2.1.203 o successivo. Sostituisce le impostazioni [`modelSettings`](/docs/it/settings-reference#modelsettings) e [`effortLevel`](/docs/it/settings-reference#effortlevel) per questa sessione e non persiste | `claude --effort high` |89| `--effort` | Imposta il [livello di sforzo](/docs/it/model-config#adjust-effort-level) per la sessione corrente. Opzioni: `low`, `medium`, `high`, `xhigh`, `max`, o `ultracode`. I livelli disponibili dipendono dal modello. `ultracode` richiede `xhigh` effort con [ultracode](/docs/it/workflows#let-claude-decide-with-ultracode) attivato e richiede Claude Code v2.1.203 o successivo. Sostituisce le impostazioni [`modelSettings`](/docs/it/settings-reference#modelsettings) e [`effortLevel`](/docs/it/settings-reference#effortlevel) per questa sessione e non persiste | `claude --effort high` |

90| `--enable-auto-mode` | Rimosso in v2.1.111. Auto mode è ora nel ciclo `Shift+Tab` per impostazione predefinita; usa `--permission-mode auto` per iniziare in esso | `claude --permission-mode auto` |90| `--enable-auto-mode` | Rimosso in v2.1.111. Auto mode è ora nel ciclo `Shift+Tab` per impostazione predefinita; usa `--permission-mode auto` per iniziare in esso | `claude --permission-mode auto` |

91| `--environment <environment-id>` | Crea una nuova sessione cloud che viene eseguita sull'[ambiente self-hosted](/docs/it/self-hosted-environments) con l'ID fornito. Gli ID ambiente iniziano con `ccpool_`. Vedi il [comportamento di dispatch di `--environment`](/docs/it/self-hosted-environments-testing#environment-dispatch-behavior) per il comportamento di dispatch e le combinazioni di flag che rifiuta. Richiede Claude Code v2.1.224 o successivo | `claude -p "Fix the login bug" --environment ccpool_abc123` |91| `--environment <environment-id>` | Crea una nuova sessione cloud che viene eseguita sull'[ambiente self-hosted](/docs/it/self-hosted-environments) con l'ID fornito. Gli ID ambiente iniziano con `ccpool_`. Vedi il [comportamento di dispatch di `--environment`](/docs/it/self-hosted-environments-testing#environment-dispatch-behavior) per il comportamento di dispatch e le combinazioni di flag che rifiuta. Richiede Claude Code v2.1.224 o successivo | `claude -p "Fix the login bug" --environment ccpool_abc123` |

92| `--exclude-dynamic-system-prompt-sections` | Sposta le sezioni per macchina dal prompt di sistema (directory di lavoro, informazioni sull'ambiente, percorsi di memoria, flag git-repo) nel primo messaggio dell'utente. Migliora il riutilizzo della prompt-cache tra diversi utenti e macchine che eseguono lo stesso compito. Si applica solo con il prompt di sistema predefinito; ignorato quando `--system-prompt` o `--system-prompt-file` è impostato. Usa con `-p` per carichi di lavoro con script e multi-utente | `claude -p --exclude-dynamic-system-prompt-sections "query"` |92| `--exclude-dynamic-system-prompt-sections` | Sposta le sezioni per macchina dal prompt di sistema (directory di lavoro, informazioni sull'ambiente, percorsi di memoria, flag git-repo) nel primo messaggio dell'utente. Migliora il riutilizzo della prompt-cache tra diversi utenti e macchine che eseguono lo stesso compito. Si applica solo con il prompt di sistema predefinito; ignorato quando `--system-prompt` o `--system-prompt-file` è impostato. Usa con `-p` per carichi di lavoro con script e multi-utente | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

93| `--exec` | Esegui un comando shell come un job in background supportato da PTY invece di avviare una sessione Claude. Usa con `--bg` per avviare dalla shell | `claude --bg --exec 'pytest -x'` |93| `--exec` | Esegui un comando shell come un job in background supportato da PTY invece di avviare una sessione Claude. Usa con `--bg` per avviare dalla shell | `claude --bg --exec 'pytest -x'` |

94| `--fallback-model` | Abilita il fallback automatico al modello specificato quando il modello primario è sovraccarico o non disponibile, ad esempio un modello ritirato. Accetta un elenco separato da virgole provato in ordine. Vedi [Catene di modelli di fallback](/docs/it/model-config#fallback-model-chains). Per persistere una catena tra le sessioni, usa l'impostazione [`fallbackModel`](/docs/it/settings-reference#fallbackmodel), che questo flag sostituisce | `claude --fallback-model sonnet,haiku` |94| `--fallback-model` | Abilita il fallback automatico al modello specificato quando il modello primario è sovraccarico o non disponibile, ad esempio un modello ritirato. Accetta un elenco separato da virgole provato in ordine. Vedi [Catene di modelli di fallback](/docs/it/model-config#fallback-model-chains). Per persistere una catena tra le sessioni, usa l'impostazione [`fallbackModel`](/docs/it/settings-reference#fallbackmodel), che questo flag sostituisce | `claude --fallback-model sonnet,haiku` |

95| `--fork-session` | Quando riprendi, crea un nuovo ID di sessione invece di riutilizzare l'originale (usa con `--resume` o `--continue`) | `claude --resume abc123 --fork-session` |95| `--fork-session` | Quando riprendi, crea un nuovo ID di sessione invece di riutilizzare l'originale (usa con `--resume` o `--continue`) | `claude --resume abc123 --fork-session` |

96| `--forward-subagent-text` | Emetti blocchi di testo e thinking dei [subagents](/docs/it/sub-agents) nel flusso di output come messaggi `assistant` e `user` con `parent_tool_use_id` impostato, in modo da poter ricostruire la trascrizione di ogni subagent. Senza questo flag, Claude Code emette solo blocchi `tool_use` e `tool_result` dei subagents. Richiede `--print` e `--output-format stream-json`. Claude Code inoltra anche i messaggi dai [subagents annidati](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents), impostando `parent_tool_use_id` all'ID della chiamata dello strumento Agent che ha generato ognuno; questo richiede Claude Code v2.1.219 o successivo. La variabile di ambiente [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/it/env-vars) abilita lo stesso comportamento. Richiede Claude Code v2.1.211 o successivo | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |96| `--forward-subagent-text` | Emetti blocchi di testo e thinking dei [subagents](/docs/it/sub-agents) nel flusso di output come messaggi `assistant` e `user` con `parent_tool_use_id` impostato, in modo da poter ricostruire la trascrizione di ogni subagent. Senza questo flag, Claude Code omette il testo e i blocchi di thinking di un subagent che viene eseguito in [foreground](/docs/it/sub-agents#run-subagents-in-foreground-or-background). Richiede `--print` e `--output-format stream-json`. Claude Code inoltra anche i messaggi dai [subagents annidati](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents), impostando `parent_tool_use_id` all'ID della chiamata dello strumento Agent che ha generato ognuno; questo richiede Claude Code v2.1.219 o successivo. La variabile di ambiente [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/it/env-vars) abilita lo stesso comportamento. Richiede Claude Code v2.1.211 o successivo | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |

97| `--from-pr` | Apri il selettore di sessione filtrato alle sessioni collegate a una specifica pull request. Accetta un numero di PR, un URL di GitHub o GitHub Enterprise PR, un URL di merge request di GitLab o un URL di pull request di Bitbucket. Le sessioni vengono collegate automaticamente quando Claude crea la pull request | `claude --from-pr 123` |97| `--from-pr` | Apri il selettore di sessione filtrato alle sessioni collegate a una specifica pull request. Accetta un numero di PR, un URL di GitHub o GitHub Enterprise PR, un URL di merge request di GitLab o un URL di pull request di Bitbucket. Le sessioni vengono collegate automaticamente quando Claude crea la pull request | `claude --from-pr 123` |

98| `--ide` | Connettiti automaticamente all'IDE all'avvio se esattamente un IDE valido è disponibile | `claude --ide` |98| `--ide` | Connettiti automaticamente all'IDE all'avvio se esattamente un IDE valido è disponibile | `claude --ide` |

114| `--permission-mode` | Inizia in una [modalità di autorizzazione](/docs/it/permission-modes) specificata. Accetta `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`, o `manual` come alias per `default`. L'alias `manual` seleziona la modalità di autorizzazione che l'interfaccia utente etichetta come Manual e richiede Claude Code v2.1.200 o successivo; `claude --help` la elenca al posto di `default` e entrambi i valori funzionano. Sostituisce `defaultMode` dai file di impostazioni. Senza questo flag o `--dangerously-skip-permissions`, una nuova sessione inizia nella modalità di autorizzazione descritta in [quale modalità di autorizzazione una sessione inizia in](/docs/it/permission-modes#which-mode-a-session-starts-in). Per `-p`, è `default` quando nulla è configurato | `claude --permission-mode plan` |114| `--permission-mode` | Inizia in una [modalità di autorizzazione](/docs/it/permission-modes) specificata. Accetta `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`, o `manual` come alias per `default`. L'alias `manual` seleziona la modalità di autorizzazione che l'interfaccia utente etichetta come Manual e richiede Claude Code v2.1.200 o successivo; `claude --help` la elenca al posto di `default` e entrambi i valori funzionano. Sostituisce `defaultMode` dai file di impostazioni. Senza questo flag o `--dangerously-skip-permissions`, una nuova sessione inizia nella modalità di autorizzazione descritta in [quale modalità di autorizzazione una sessione inizia in](/docs/it/permission-modes#which-mode-a-session-starts-in). Per `-p`, è `default` quando nulla è configurato | `claude --permission-mode plan` |

115| `--permission-prompt-tool` | Specifica uno strumento MCP per gestire i prompt di autorizzazione in modalità non interattiva. Claude Code attende che il server MCP di quello strumento si connetta prima di eseguire il primo turno, fino al timeout di avvio [`MCP_TIMEOUT`](/docs/it/env-vars), 30 secondi per impostazione predefinita. <br /><br />Lo strumento di prompt non può approvare uno strumento MCP contrassegnato come [richiedente interazione dell'utente](/docs/it/mcp#require-approval-for-a-specific-tool): Claude Code converte un risultato `allow` per uno in un deny. Questa restrizione richiede Claude Code v2.1.199 o successivo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |115| `--permission-prompt-tool` | Specifica uno strumento MCP per gestire i prompt di autorizzazione in modalità non interattiva. Claude Code attende che il server MCP di quello strumento si connetta prima di eseguire il primo turno, fino al timeout di avvio [`MCP_TIMEOUT`](/docs/it/env-vars), 30 secondi per impostazione predefinita. <br /><br />Lo strumento di prompt non può approvare uno strumento MCP contrassegnato come [richiedente interazione dell'utente](/docs/it/mcp#require-approval-for-a-specific-tool): Claude Code converte un risultato `allow` per uno in un deny. Questa restrizione richiede Claude Code v2.1.199 o successivo | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

116| `--permission-prompts` | Imposta chi risponde ai prompt di autorizzazione in modalità print. Con il valore predefinito `host`, Claude Code li invia all'host dell'Agent SDK o allo strumento `--permission-prompt-tool`. Passa `none` quando nessuno può rispondere, e Claude Code li nega invece. Vedi [Disattiva i prompt di autorizzazione nelle esecuzioni incustodite](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs). Richiede Claude Code v2.1.259 o successivo | `claude -p --permission-prompts none "query"` |116| `--permission-prompts` | Imposta chi risponde ai prompt di autorizzazione in modalità print. Con il valore predefinito `host`, Claude Code li invia all'host dell'Agent SDK o allo strumento `--permission-prompt-tool`. Passa `none` quando nessuno può rispondere, e Claude Code li nega invece. Vedi [Disattiva i prompt di autorizzazione nelle esecuzioni incustodite](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs). Richiede Claude Code v2.1.259 o successivo | `claude -p --permission-prompts none "query"` |

117| `--plugin-dir` | Carica un plugin da una directory o da un archivio `.zip` per questa sessione solo. Ogni flag accetta un percorso. Ripeti il flag per più plugin: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |117| `--plugin-dir` | Carica un plugin da una directory o da un archivio `.zip`, o diversi da una [cartella di plugins](/docs/it/plugins#test-your-plugins-locally), per questa sessione solo. Ogni flag accetta un percorso. Ripeti il flag per più percorsi: `--plugin-dir A --plugin-dir B.zip`. Passare una cartella di plugins richiede Claude Code v2.1.265 o successivo | `claude --plugin-dir ./my-plugin` |

118| `--plugin-url` | Recupera un archivio plugin `.zip` da un URL per questa sessione solo. Ripeti il flag per più plugin, o passa URL separati da spazi in un singolo valore tra virgolette | `claude --plugin-url https://example.com/plugin.zip` |118| `--plugin-url` | Recupera un archivio plugin `.zip` da un URL per questa sessione solo. Ripeti il flag per più plugins, o passa URL separati da spazi in un singolo valore tra virgolette | `claude --plugin-url https://example.com/plugin.zip` |

119| `--print`, `-p` | Stampa la risposta senza modalità interattiva (vedi [documentazione Agent SDK](/docs/it/agent-sdk/overview) per i dettagli di utilizzo programmatico) | `claude -p "query"` |119| `--print`, `-p` | Stampa la risposta senza modalità interattiva (vedi [documentazione Agent SDK](/docs/it/agent-sdk/overview) per i dettagli di utilizzo programmatico) | `claude -p "query"` |

120| `--prompt-suggestions` | Emetti un messaggio `prompt_suggestion` con un prompt utente successivo previsto dopo ogni turno che ne genera uno; le conversazioni molto brevi possono non produrne alcuno. Richiede `--print`, `--output-format stream-json` e `--verbose`. Vedi [Suggerimenti di prompt](/docs/it/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |120| `--prompt-suggestions` | Emetti un messaggio `prompt_suggestion` con un prompt utente successivo previsto dopo ogni turno che ne genera uno; le conversazioni molto brevi possono non produrne alcuno. Richiede `--print`, `--output-format stream-json` e `--verbose`. Vedi [Suggerimenti di prompt](/docs/it/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

121| `--ref <branch>` | Con `--environment`, basa il checkout della nuova sessione su un ref denominato invece di `HEAD` locale | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |121| `--ref <branch>` | Con `--environment`, basa il checkout della nuova sessione su un ref denominato invece di `HEAD` locale | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |

132| `--strict-mcp-config` | Usa solo server MCP da `--mcp-config`, ignorando tutte le altre configurazioni MCP. Vedi [Controllo esclusivo con managed-mcp.json](/docs/it/managed-mcp#exclusive-control-with-managed-mcp-json) per quello che il flag fa sotto un file MCP gestito | `claude --strict-mcp-config --mcp-config ./mcp.json` |132| `--strict-mcp-config` | Usa solo server MCP da `--mcp-config`, ignorando tutte le altre configurazioni MCP. Vedi [Controllo esclusivo con managed-mcp.json](/docs/it/managed-mcp#exclusive-control-with-managed-mcp-json) per quello che il flag fa sotto un file MCP gestito | `claude --strict-mcp-config --mcp-config ./mcp.json` |

135| `--system-prompt-snapshot` | Passa `off` per ricostruire il prompt di sistema su ogni richiesta invece di riutilizzare il prompt [registrato sulla prima richiesta della conversazione](#system-prompt-flags-in-resumed-conversations), ad esempio mentre iteri sul testo `--append-system-prompt` tra esecuzioni `--continue`. Richiede Claude Code v2.1.257 o successivo | `claude --system-prompt-snapshot off` |

136| `--teammate-mode` | Imposta come i compagni di squadra del [team di agent](/docs/it/agent-teams) vengono visualizzati: `in-process` (predefinito), `auto`, `tmux`, o `iterm2` (aggiunto in v2.1.186). Sostituisce l'impostazione [`teammateMode`](/docs/it/settings-reference#teammatemode) per questa sessione. Vedi [Scegli una modalità di visualizzazione](/docs/it/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |137| `--teammate-mode` | Imposta come i compagni di squadra del [team di agent](/docs/it/agent-teams) vengono visualizzati: `in-process` (predefinito), `auto`, `tmux`, o `iterm2` (aggiunto in v2.1.186). Sostituisce l'impostazione [`teammateMode`](/docs/it/settings-reference#teammatemode) per questa sessione. Vedi [Scegli una modalità di visualizzazione](/docs/it/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |

137| `--tmux` | Crea una sessione tmux per il worktree. Richiede `--worktree`. Utilizza i riquadri nativi di iTerm2 quando disponibili; passa `--tmux=classic` per tmux tradizionale | `claude -w feature-auth --tmux` |138| `--tmux` | Crea una sessione tmux per il worktree. Richiede `--worktree`. Utilizza i riquadri nativi di iTerm2 quando disponibili; passa `--tmux=classic` per tmux tradizionale | `claude -w feature-auth --tmux` |

138| `--tools` | Limita quali strumenti integrati Claude può utilizzare. Usa `""` per disabilitare tutti, `"default"` per tutti, o nomi di strumenti come `"Bash,Edit,Read"`. Se nomini uno dei [task-tracking tools](/docs/it/tools-reference#task-tool-availability) qui, Claude Code opta anche la sessione in. Il flag non influisce sugli strumenti MCP; per negarli anche, usa `--disallowedTools "mcp__*"`. Un elenco che omette [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior) non lo rimuove; `""` lo rimuove solo quando nessuno strumento MCP rimane | `claude --tools "Bash,Edit,Read"` |139| `--tools` | Limita quali strumenti integrati Claude può utilizzare. Usa `""` per disabilitare tutti, `"default"` per il set predefinito, o nomi di strumenti come `"Bash,Edit,Read"`. Su macOS, Linux e WSL, il set predefinito esclude `Glob` e `Grep`, come descritto in [Comportamento dello strumento Glob](/docs/it/tools-reference#glob-tool-behavior). Se nomini uno dei [task-tracking tools](/docs/it/tools-reference#task-tool-availability) qui, Claude Code opta anche la sessione in. Il flag non influisce sugli strumenti MCP; per negarli anche, usa `--disallowedTools "mcp__*"`. Un elenco che omette [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior) non lo rimuove; `""` lo rimuove solo quando nessuno strumento MCP rimane | `claude --tools "Bash,Edit,Read"` |

139| `--verbose` | Abilita la registrazione dettagliata, mostra l'output completo turno per turno. Sostituisce l'impostazione [`viewMode`](/docs/it/settings-reference#viewmode) per questa sessione | `claude --verbose` |140| `--verbose` | Abilita la registrazione dettagliata, mostra l'output completo turno per turno. Sostituisce l'impostazione [`viewMode`](/docs/it/settings-reference#viewmode) per questa sessione | `claude --verbose` |

141| `--worktree`, `-w` | Avvia Claude in un [git worktree](/docs/it/worktrees) isolato in `<repo>/.claude/worktrees/<name>`. Se non viene fornito alcun nome, Claude Code ne genera uno. Passa `#<number>`, un URL di pull request di GitHub o un URL di merge request di GitLab per [recuperare quella PR o MR da `origin` e creare un branch del worktree da essa](/docs/it/worktrees#branch-from-a-pull-request). Il branching da una merge request di GitLab richiede Claude Code v2.1.233 o successivo | `claude -w feature-auth` |142| `--worktree`, `-w` | Avvia Claude in un [git worktree](/docs/it/worktrees) isolato in `<repo>/.claude/worktrees/<name>`. Se non viene fornito alcun nome, Claude Code ne genera uno. Passa `#<number>`, un URL di pull request di GitHub o un URL di merge request di GitLab per [recuperare quella PR o MR da `origin` e creare un branch del worktree da essa](/docs/it/worktrees#branch-from-a-pull-request). Il branching da una merge request di GitLab richiede Claude Code v2.1.233 o successivo | `claude -w feature-auth` |

144 Flag del prompt di sistema145 Flag del prompt di sistema

145</h3>146</h3>

146 147

147Claude Code fornisce quattro flag per personalizzare il prompt di sistema. Tutti e quattro funzionano sia in modalità interattiva che non interattiva.148Claude Code fornisce cinque flag per personalizzare il prompt di sistema. Quattro impostano il suo testo, e con `--system-prompt-snapshot` controlli se una conversazione mantiene il testo con cui ha iniziato. Tutti e cinque funzionano sia in modalità interattiva che non interattiva.

148 149

150| :---------------------------- | :--------------------------------------------------- | :------------------------------------------------------ |151| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------- |

156| `--system-prompt-snapshot` | Con `off`, ricostruisce il prompt su ogni richiesta. Con `on`, il valore predefinito, riutilizza un prompt registrato dove [la registrazione si applica](#system-prompt-flags-in-resumed-conversations) | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |

155 157

156`--system-prompt` e `--system-prompt-file` si escludono a vicenda. I flag di aggiunta possono essere combinati con uno qualsiasi dei flag di sostituzione.158`--system-prompt` e `--system-prompt-file` si escludono a vicenda. I flag di aggiunta possono essere combinati con uno qualsiasi dei flag di sostituzione.

157 159

158Scegli in base al fatto che l'identità predefinita di Claude Code si adatti ancora al tuo compito. Usa un flag di aggiunta quando Claude dovrebbe rimanere un assistente di codifica che segue anche le tue regole aggiuntive: istruzioni per invocazione, formattazione dell'output o contesto di dominio per uno script `-p`. L'aggiunta preserva la guida predefinita degli strumenti, le istruzioni di sicurezza e le convenzioni di codifica, quindi fornisci solo ciò che differisce. Usa un flag di sostituzione quando la superficie, l'identità o il modello di autorizzazione differisce da quello di Claude Code, come un agent non di codifica in una pipeline che nessun umano osserva. La sostituzione elimina l'intero prompt predefinito, inclusa la guida degli strumenti e le istruzioni di sicurezza, quindi assumi la responsabilità di qualunque cosa il tuo compito abbia ancora bisogno.160Scegli in base al fatto che l'identità predefinita di Claude Code si adatti ancora al tuo compito. Usa un flag di aggiunta quando Claude dovrebbe rimanere un assistente di codifica che segue anche le tue regole aggiuntive: istruzioni per invocazione, formattazione dell'output o contesto di dominio per uno script `-p`. L'aggiunta preserva la guida predefinita degli strumenti, le istruzioni di sicurezza e le convenzioni di codifica, quindi fornisci solo ciò che differisce. Usa un flag di sostituzione quando la superficie, l'identità o il modello di autorizzazione differisce da quello di Claude Code, come un agent non di codifica in una pipeline che nessun umano osserva. La sostituzione elimina l'intero prompt predefinito, inclusa la guida degli strumenti e le istruzioni di sicurezza, quindi assumi la responsabilità di qualunque cosa il tuo compito abbia ancora bisogno.

159 161

160Questi flag si applicano solo all'invocazione corrente. Per persone persistenti che puoi alternare e condividere in un progetto, usa [output styles](/docs/it/output-styles). Per convenzioni di progetto che Claude dovrebbe sempre seguire, usa [CLAUDE.md](/docs/it/memory). La [guida Agent SDK sui prompt di sistema](/docs/it/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) copre la stessa decisione in maggiore profondità.162Per persone persistenti che puoi alternare e condividere in un progetto, usa [output styles](/docs/it/output-styles). Per convenzioni di progetto che Claude dovrebbe sempre seguire, usa [CLAUDE.md](/docs/it/memory). La [guida Agent SDK sui prompt di sistema](/docs/it/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) copre la stessa decisione in maggiore profondità.

163

164<h4 id="system-prompt-flags-in-resumed-conversations">

165 Flag del prompt di sistema nelle conversazioni riprese

166</h4>

167

168Per impostazione predefinita, Claude Code costruisce il prompt di sistema una volta, sulla prima richiesta di una conversazione, con il testo da qualsiasi flag di prompt di sistema applicato, e lo registra nella sessione. Fino a quando la conversazione non viene compattata, ogni richiesta successiva utilizza quel prompt registrato, incluso dopo che torni alla conversazione con `--resume` o `--continue`. Se passi testo di flag di prompt di sistema diverso, o nessuno, su quel lancio successivo, ha effetto una volta che la conversazione viene compattata o quando inizi una nuova conversazione.

169

170Se avvii Claude Code in [modalità bare](/docs/it/headless#start-faster-with-bare-mode), passando `--bare` o impostando `CLAUDE_CODE_SIMPLE=1`, la registrazione rimane disattivata a meno che tu non passi `--system-prompt-snapshot on`. Prima di v2.1.268, le sessioni che non [recuperano flag di funzionalità](/docs/it/env-vars#features-that-need-feature-flag-fetching), incluse le sessioni su Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry, ricostruivano il prompt su ogni richiesta e `--system-prompt-snapshot` non aveva effetto.

171

172Per ricostruire il prompt su ogni richiesta invece, ad esempio mentre itteri sulla sua formulazione tra esecuzioni `--continue`, passa `--system-prompt-snapshot off`. Prima di v2.1.265, passare uno qualsiasi dei flag di prompt di sistema disattivava anche la registrazione a meno che tu non passassi `--system-prompt-snapshot on`.

161 173

162<h2 id="see-also">174<h2 id="see-also">

163 Vedi anche175 Vedi anche

cloud-environments.md +806 −0 created

Details

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.

5# Configurare ambienti cloud

7> Configurare ambienti cloud per le sessioni cloud di Claude Code: livelli di accesso di rete, variabili di ambiente, script di configurazione e caching dell'ambiente.

9<Note>

10 Gli ambienti cloud richiedono [Claude Code sul web](/docs/it/claude-code-on-the-web), che è in anteprima di ricerca per gli utenti Pro, Max e Team, e per gli utenti Enterprise con [posti premium o posti Chat + Claude Code](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan).

11</Note>

13Ogni [sessione cloud](/docs/it/claude-code-on-the-web) viene eseguita in un ambiente cloud. È possibile configurare un ambiente per consentire o negare l'[accesso di rete](#access-levels), [impostare variabili di ambiente](#set-environment-variables) per la sessione, sui piani Pro e Max memorizzare [credenziali API](#add-api-credentials) che le sessioni utilizzano senza vederle, ed eseguire uno [script di configurazione](#setup-scripts) prima che Claude inizi a lavorare.

15Gli stessi ambienti si applicano ovunque avviate una sessione cloud: [Claude Code sul web](/docs/it/claude-code-on-the-web), il terminale con [`claude --cloud`](/docs/it/claude-code-on-the-web#from-terminal-to-web), [Claude Tag](https://claude.com/docs/claude-tag/overview), [routine](/docs/it/routines), l'[app mobile Claude](/docs/it/mobile) e l'[app Desktop](/docs/it/desktop). Ognuna di queste superfici può anche instradare a un [ambiente self-hosted](/docs/it/self-hosted-environments). [Disponibilità e limitazioni](/docs/it/self-hosted-environments#availability-and-limitations) copre cosa Claude non può ancora utilizzare quando una sessione Claude Tag viene eseguita in uno.

17<Info>

18 Le sessioni di [Remote Control](/docs/it/remote-control) collegano le interfacce web e mobile a una sessione sulla vostra macchina, che utilizza la rete e i file della vostra macchina, non un ambiente cloud. Le sessioni del canale Claude Tag utilizzano solo ambienti a livello di organizzazione, sia [ambienti condivisi](#organization-shared-environments) che [ambienti self-hosted](/docs/it/self-hosted-environments).

19</Info>

21<h2 id="the-default-environment">

22 L'ambiente Default

23</h2>

25Se non avete ancora un ambiente, l'onboarding configura l'ambiente **Default** per voi. Come dipende da dove eseguite l'onboarding:

27* **Flussi CLI come `/web-setup`**: creano **Default** per voi

28* **Onboarding web su Pro e Max**: crea **Default** per voi

29* **Onboarding web su Team ed Enterprise**: mostra un modulo **Create your first cloud environment** a meno che un Owner non abbia attivato [Quick web setup](/docs/it/claude-code-on-the-web#github-authentication-options); mantenete i valori predefiniti del modulo e fate clic su **Create & finish** per ottenere lo stesso ambiente **Default**

31**Default** non ha alcuna configurazione propria:

33* [Accesso di rete **Trusted**](#access-levels): le sessioni raggiungono i registri dei pacchetti e altri [domini consentiti](#default-allowed-domains), e nient'altro attraverso la rete della sessione.

34* Nessun'altra configurazione: **Default** non definisce variabili di ambiente o script di configurazione, quindi le sessioni iniziano con solo gli [strumenti preinstallati](#installed-tools).

36Con solo **Default** disponibile, ogni sessione viene eseguita in esso. Quando si dispone di più di un ambiente, le sessioni ne scelgono uno per superficie:

38* Sul web, l'app Desktop e l'app mobile, le sessioni utilizzano l'ambiente mostrato nel [selettore](#configure-your-environment). Un [default dell'organizzazione](#organization-shared-environments) impostato da un Owner riempie la selezione quando non ne avete scelto uno.

39* Dalla CLI, Claude Code utilizza la vostra scelta [`/remote-env`](#select-an-environment-from-the-cli), o ricade nell'ambiente ospitato da Anthropic quando il vostro elenco ne ha uno, e altrimenti nel primo ambiente nel vostro elenco che non è un ambiente bridge, una voce [Remote Control](/docs/it/remote-control) che registra per rappresentare la vostra macchina piuttosto che un ambiente cloud. Per un [ambiente self-hosted](/docs/it/self-hosted-environments), passare `--environment <environment-id>` con il suo ID `ccpool_` [quando inviate una sessione](/docs/it/self-hosted-environments-testing#run-the-test-loop) sostituisce la scelta `/remote-env` e il fallback per quella invocazione. Claude Code rifiuta gli ID `env_` ospitati da Anthropic passati al flag, quindi utilizzate `/remote-env` per indirizzare quelli. Il flag richiede Claude Code v2.1.224 o successiva.

41Configurate un ambiente quando il default non è sufficiente: quando Claude ha bisogno di raggiungere domini al di fuori della [lista di consentiti predefinita](#default-allowed-domains), ha bisogno di variabili di ambiente impostate per le sue sessioni, o ha bisogno di dipendenze installate prima di iniziare a lavorare.

43<h2 id="configure-your-environment">

44 Configurare il vostro ambiente

45</h2>

47Create, modificate e archiviate gli ambienti dal selettore di ambiente, che raggiungete su [claude.ai/code](https://claude.ai/code) dopo l'[onboarding web](/docs/it/web-quickstart), oppure dalla casella di messaggio nell'[app Desktop](/docs/it/desktop#cloud-sessions). Gli ambienti che create sono personali al vostro account; gli [ambienti condivisi](#organization-shared-environments) creati da un Owner appaiono nello stesso selettore. Consultate [Strumenti installati](#installed-tools) per vedere cosa è disponibile senza alcuna configurazione.

49<Steps>

50 <Step title="Aprire il selettore di ambiente">

51 Su [claude.ai/code](https://claude.ai/code), selezionate l'icona cloud che mostra il nome dell'ambiente corrente, nella riga sopra la casella di messaggio. Non c'è una pagina di impostazioni o un URL diretto per il selettore.

53 <Frame>

54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="Il selettore di ambiente aperto sopra la casella di messaggio su claude.ai/code. Il pulsante cloud che mostra il nome dell'ambiente Default si trova nella riga sopra la casella di messaggio. Il menu aperto elenca una riga Local con etichette Download e Desktop only, una sezione Cloud dove l'ambiente Default è selezionato con un segno di spunta e mostra un'icona di ingranaggio delle impostazioni al passaggio del mouse, un'opzione Add cloud environment e una sezione Remote Control con istruzioni di configurazione." width="1672" height="682" data-path="images/cloud-environment-selector.png" />

55 </Frame>

56 </Step>

58 <Step title="Aggiungere o modificare un ambiente">

59 Selezionate **Add cloud environment**, oppure passate il mouse su un ambiente esistente e selezionate l'icona delle impostazioni che appare a destra. La finestra di dialogo include il nome, il livello di accesso di rete, le variabili di ambiente e lo script di configurazione. Quando modificate un ambiente cloud esistente su un piano Pro o Max, la finestra di dialogo include anche [credenziali API](#add-api-credentials).

61 <Frame>

62 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="La finestra di dialogo New cloud environment. Un campo Name con il testo segnaposto Default, un selettore Network access impostato su Trusted con link alla politica di rete e ai livelli di accesso, una casella Environment variables che mostra il testo segnaposto in formato .env con una nota che i valori sono visibili a chiunque utilizzi l'ambiente, una casella Setup script descritta come uno script Bash che viene eseguito quando inizia una nuova sessione prima che Claude Code si avvii, e pulsanti Cancel e Create environment." width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

63 </Frame>

64 </Step>

65</Steps>

67<h3 id="set-environment-variables">

68 Impostare le variabili di ambiente

69</h3>

71Le variabili di ambiente utilizzano il formato `.env`, una coppia `KEY=value` per riga. I valori semplici non hanno bisogno di virgolette, e se quotate un valore con una coppia corrispondente, le virgolette non diventano parte del valore. Quotate un valore che si estende su più righe o contiene un `#`: in un valore non quotato, `#` inizia un commento e il resto della riga viene eliminato.

73L'esempio seguente definisce tre variabili.

75```text theme={null}

76NODE_ENV=development

77LOG_LEVEL=debug

78DATABASE_URL=postgres://localhost:5432/myapp

79```

81Ogni sessione copia i valori dell'ambiente una volta, all'avvio, in variabili di ambiente ordinarie che qualsiasi comando eseguito da Claude può leggere. Poiché le sessioni in esecuzione non rileggono la configurazione, la modifica o l'aggiunta di variabili influisce sulle sessioni che avviate in seguito; le sessioni già in esecuzione mantengono i valori con cui sono state avviate.

83Claude Code sul web imposta anche alcune variabili da solo quando avvia una sessione. Per [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/it/claude-code-on-the-web#manage-context), il valore che Claude Code sul web imposta sostituisce uno che aggiungete qui, quindi aggiungere quella chiave qui non ha effetto.

85Chiunque utilizzi l'ambiente può leggere i valori. Sui piani Pro e Max, utilizzate una [credenziale API](#add-api-credentials) invece per una chiave che il proxy dell'agente può allegare a una richiesta. Le [richieste che non ricevono mai una credenziale](#requests-that-never-get-the-credential) sono elencate lì.

87<h3 id="add-api-credentials">

88 Aggiungere credenziali API

89</h3>

91Una credenziale API è una chiave API o un token che memorizzate in un ambiente cloud in modo che Claude possa chiamare quell'API da qualsiasi sessione nell'ambiente senza vedere la chiave. Il proxy dell'agente di Anthropic aggiunge la chiave alle richieste per gli host che elencate, dopo che ogni richiesta esce dalla VM della sessione. La chiave non raggiunge mai Claude, i comandi che esegue, o le variabili di ambiente della sessione.

93Le credenziali API sono disponibili sui piani Pro e Max. Non sono ancora disponibili sui piani Team o Enterprise, quindi la sezione **API credentials** non appare nella finestra di dialogo dell'ambiente su quei piani.

95<h4 id="requirements">

96 Requisiti

97</h4>

99Due di questi decidono se potete aggiungere una credenziale, e due decidono se il proxy dell'agente può utilizzarla una volta aggiunta:

100

101* **Ruolo**: un ruolo di amministratore dell'organizzazione nella vostra organizzazione claude.ai

102 * Su Team ed Enterprise, gli Owner lo detengono e gli Admin no

103 * Su Pro e Max, lo detenete nella vostra organizzazione personale

104 * Senza di esso, vedete una nota invece dell'elenco delle credenziali, anche sui vostri ambienti personali. Chiedete a un Owner di aggiungere la credenziale a un ambiente condiviso ed eseguite le vostre sessioni lì

105* **Tipo di ambiente**: un ambiente cloud ospitato da Anthropic che già esiste. Un [ambiente self-hosted](/docs/it/self-hosted-environments) non ha credenziali API

106* **Raggiungibilità API**: l'API accetta connessioni da internet, perché le richieste escono dalla rete di Anthropic

107* **Chiavi di crittografia**: se la vostra organizzazione utilizza chiavi di crittografia gestite dal cliente, non potete salvare credenziali

108

109<h4 id="add-a-credential">

110 Aggiungere una credenziale

111</h4>

112

113Aggiungete le credenziali una alla volta dall'editor di un ambiente che già esiste. La finestra di dialogo per un nuovo ambiente non le offre. Non c'è nemmeno modifica. Per modificare gli host o il valore di una credenziale, cancellatela e aggiungetela di nuovo.

114

115<Steps>

116 <Step title="Aprire le credenziali API dell'ambiente">

117 [Aprite l'ambiente per la modifica](#configure-your-environment) su [claude.ai/code](https://claude.ai/code). Nella finestra di dialogo **Update cloud environment**, trovate **API credentials** sotto **Environment variables**. Vedete le credenziali già sull'ambiente, ognuna con gli host a cui si applica.

118 </Step>

119

120 <Step title="Aggiungere la credenziale">

121 Selezionate **Add credential** e compilate il modulo. Mantenete il **Credential type** predefinito, **Bearer**, per una chiave API che viaggia in un'intestazione di richiesta, e compilate questi campi:

122

123 * **Name**: un'etichetta per la credenziale, come `Internal billing API`

124 * **Allowed websites**: gli host dell'API, come `api.example.com`. Un `*.` iniziale corrisponde a ogni sottodominio

125 * **Custom headers**: una riga per l'intestazione che trasporta la chiave. La riga inizia con `Authorization` come **Name** dell'intestazione e `Bearer` come suo **Prefix**; incollate la chiave stessa come **Value**. Per un'intestazione come `X-Api-Key` che accetta il valore nudo, cambiate il nome e cancellate il prefisso

126

127 Per un'API che si autentica in un altro modo, scegliete un **Credential type** diverso. L'elenco è lo stesso che [Claude Tag](https://claude.com/docs/claude-tag/overview), l'integrazione Slack per i piani Team ed Enterprise, offre per le [connessioni](https://claude.com/docs/claude-tag/admins/add-connections).

128 </Step>

129

130 <Step title="Salvare la credenziale">

131 Selezionate **Connect**. La credenziale appare nell'elenco con i suoi host, salvata senza il pulsante **Save changes** della finestra di dialogo. Non potete visualizzare il valore di nuovo dopo il salvataggio.

132 </Step>

133</Steps>

134

135Per confermare che la credenziale funziona, avviate una sessione nell'ambiente e chiedete a Claude di chiamare l'API, ad esempio con `curl`. L'API risponde come se la chiave fosse nella richiesta, e la chiave non appare nelle variabili di ambiente della sessione o in nessun file. Se l'elenco contrassegna una credenziale **Not sent**, la nota sotto di essa dice perché e cosa fare. Due credenziali i cui host si sovrappongono senza corrispondere esattamente non ricevono alcun marcatore, e il proxy dell'agente ne invia solo una.

136

137<h4 id="which-requests-get-the-credential">

138 Quali richieste ricevono la credenziale

139</h4>

140

141Il proxy dell'agente allega una credenziale a una richiesta quando l'host della richiesta corrisponde a uno che avete elencato su quella credenziale. Le sessioni possono raggiungere quegli host anche quando il [livello di accesso di rete](#access-levels) dell'ambiente non lo permetterebbe altrimenti, tranne gli [host che non ricevono mai la credenziale](#requests-that-never-get-the-credential). La credenziale si applica in ogni sessione che viene eseguita nell'ambiente, chiunque l'abbia avviata, finché non la cancellate.

142

143<h4 id="requests-that-never-get-the-credential">

144 Richieste che non ricevono mai la credenziale

145</h4>

146

147Il proxy dell'agente non allega mai una credenziale che aggiungete a queste richieste:

148

149* **GitHub**: il [proxy GitHub](#github-proxy) autentica le richieste a GitHub invece, quindi non avete bisogno di una credenziale API per esso

150* **L'API Anthropic e i registri di pacchetti pubblici**: `api.anthropic.com`, `registry.npmjs.org`, `jsr.io`, `npm.jsr.io`, `pypi.org`, `files.pythonhosted.org`, `index.crates.io` e `proxy.golang.org`

151* **Richieste dello script di configurazione**: Claude Code si connette al proxy dell'agente quando si avvia, dopo che lo [script di configurazione](#setup-scripts) è stato eseguito

152

153<h3 id="select-an-environment-from-the-cli">

154 Selezionare un ambiente dalla CLI

155</h3>

156

157Eseguite `/remote-env` nel vostro terminale per scegliere l'ambiente predefinito per le sessioni cloud che create dalla CLI, come [`claude --cloud`](/docs/it/claude-code-on-the-web#from-terminal-to-web). Il comando apre un selettore dei vostri ambienti esistenti e salva la vostra scelta nella chiave `remote.defaultEnvironmentId` nelle vostre [impostazioni utente](/docs/it/settings#where-settings-live), quindi si applica in ogni progetto sulla vostra macchina fino a quando non la cambiate, a meno che la stessa chiave non sia impostata a un [livello di impostazioni](/docs/it/settings#settings-precedence) di precedenza più alta, come le impostazioni del progetto di un repository.

158

159Un ID di [ambiente self-hosted](/docs/it/self-hosted-environments), che ha la forma `ccpool_...`, segue una regola di origine più ristretta. Consultate [`remote.defaultEnvironmentId`](/docs/it/settings-reference#remote-defaultenvironmentid) per i livelli di impostazioni che Claude Code onora da esso.

160

161`/remote-env` imposta solo il default: non avvia una sessione e non può aggiungere o modificare ambienti. Gestite gli ambienti dal [selettore di ambiente](#configure-your-environment).

162

163<h3 id="archive-an-environment">

164 Archiviare un ambiente

165</h3>

166

167Per archiviare un ambiente, apritelo per la modifica e selezionate **Archive**. Non potete eliminare un ambiente, solo archiviarlo.

168

169L'archiviazione influisce sulle nuove sessioni, non su quelle in esecuzione:

170

171* Le sessioni già in esecuzione nell'ambiente continuano a funzionare.

172* L'ambiente scompare dal selettore e da `/remote-env`, quindi non potete sceglierlo per le nuove sessioni.

173* Le credenziali API sull'ambiente rimangono allegate nelle sue sessioni in esecuzione. Cancellate quelle che non desiderate più prima di archiviare.

174* Nessuna nuova sessione può iniziare in un ambiente archiviato, su nessuna superficie. Se l'ambiente era il vostro [default CLI](#select-an-environment-from-the-cli) salvato, Claude Code avvia le sessioni cloud CLI nell'ambiente ospitato da Anthropic quando il vostro elenco ne ha uno, e altrimenti nel primo ambiente nel vostro elenco che non è un [ambiente bridge Remote Control](#the-default-environment). Qualsiasi cosa configurata con l'ambiente esplicitamente, come una [routine](/docs/it/routines#environments-and-network-access), non può avviare nuove sessioni in esso. Puntate a un altro ambiente.

175

176<h3 id="organization-shared-environments">

177 Ambienti condivisi dell'organizzazione

178</h3>

179

180Sui piani Team ed Enterprise, un Owner può creare ambienti cloud che sono condivisi con ogni membro dell'organizzazione. Lo stesso ruolo gestisce tutto il resto sulla pagina **Cloud environments** dell'amministrazione, inclusi gli [ambienti self-hosted](/docs/it/self-hosted-environments); il ruolo Admin non può aprire la pagina. L'elenco completo dei ruoli che possono aprirla è quello per [gestire le impostazioni gestite dal server](/docs/it/server-managed-settings#access-control). Gli ambienti condivisi appaiono nel selettore di ambiente di ogni membro insieme ai loro ambienti personali, quindi un team può standardizzare su una configurazione invece di farla ricreare a ogni membro.

181

182Create, modificate e archiviate gli ambienti condivisi dalla pagina **Cloud environments** nelle [impostazioni di amministrazione](https://claude.ai/admin-settings). Un ambiente condiviso si apre anche dal [selettore di ambiente](#configure-your-environment) su [claude.ai/code](https://claude.ai/code): un Owner può modificarlo lì. Gli altri membri lo vedono in sola lettura. Ogni ambiente condiviso ha un nome, un [livello di accesso di rete](#access-levels), [variabili di ambiente](#set-environment-variables) in formato `.env` e uno [script di configurazione](#setup-scripts). Gli Owner scelgono l'[ambiente predefinito](#the-default-environment) dell'organizzazione separatamente, su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code).

183

184Le sessioni di ogni membro in un ambiente condiviso leggono le sue variabili, quindi non includete segreti in esse. Le [credenziali API](#add-api-credentials), che danno alle sessioni una chiave che non possono leggere, non sono ancora disponibili sui piani Team o Enterprise.

185

186<h3 id="set-the-environment-a-claude-tag-channel-uses">

187 Impostare l'ambiente che un canale Claude Tag utilizza

188</h3>

189

190Nei canali [Claude Tag](https://claude.com/docs/claude-tag/overview), Claude lavora come identità condivisa della vostra organizzazione, non come nessun membro, quindi le sessioni dei canali utilizzano solo ambienti a livello di organizzazione, sia ambienti condivisi che [ambienti self-hosted](/docs/it/self-hosted-environments). Per dare a un canale un toolchain che non è [preinstallato](#installed-tools), come .NET, un Owner può creare un [ambiente condiviso](#organization-shared-environments) dalla pagina **Cloud environments** dell'amministrazione con uno [script di configurazione](#setup-scripts) che lo installa. Puntate il canale a un ambiente in uno di due modi:

191

192* Impostate un ambiente condiviso o self-hosted come l'[ambiente predefinito](#the-default-environment) dell'organizzazione su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code).

193* [Fissate uno a un canale](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one) nelle impostazioni di amministrazione di Claude Tag.

194

195<h2 id="network-access">

196 Accesso di rete

197</h2>

198

199Ogni ambiente imposta un livello di accesso di rete, che controlla le connessioni in uscita che le sue sessioni possono effettuare. Il livello predefinito, **Trusted**, consente i registri dei pacchetti e altri [domini consentiti](#default-allowed-domains); **Custom** accetta il vostro elenco di domini.

200

201Per modificare l'accesso di rete di un ambiente, [apritelo per la modifica](#configure-your-environment) e utilizzate il selettore **Network access** nella finestra di dialogo. L'icona cloud che apre il selettore appare sulle superfici dell'app elencate sotto [L'ambiente Default](#the-default-environment) e nell'[editor di routine](/docs/it/routines#environments-and-network-access); gli ambienti personali non hanno una pagina separata nelle impostazioni del vostro account claude.ai.

202

203<Note>

204 I connettori MCP che abilitate su una sessione o routine funzionano senza aggiungere i loro host ai **Allowed domains**, perché il traffico del connettore viaggia attraverso i server di Anthropic piuttosto che attraverso la rete della sessione. Configurate i connettori per sessione o per routine; rimuovete quelli che non vi servono per limitare quali strumenti Claude può raggiungere. Questo si basa sullo stesso canale legato ad Anthropic notato sotto [Sicurezza e isolamento](/docs/it/claude-code-on-the-web#security-and-isolation).

205</Note>

206

207<h3 id="access-levels">

208 Livelli di accesso

209</h3>

210

211Il campo **Network access** nella [finestra di dialogo dell'ambiente](#configure-your-environment) accetta uno di quattro livelli:

212

213| Livello | Connessioni in uscita |

214| :---------- | :-------------------------------------------------------------------------------------------- |

215| **None** | Nessun accesso di rete in uscita attraverso la rete della sessione |

216| **Trusted** | [Domini consentiti](#default-allowed-domains) solo: registri dei pacchetti, GitHub, cloud SDK |

217| **Full** | Qualsiasi dominio |

218| **Custom** | Il vostro elenco di consentiti, opzionalmente includendo i default |

219

220Qualunque livello scegliate, le sessioni possono ancora raggiungere questi, perché ognuno prende un percorso che non passa attraverso l'elenco di consentiti di rete della sessione:

221

222* GitHub, attraverso il suo [proxy separato](#github-proxy)

223* I [connettori MCP](#network-access) che abilitate, il cui traffico viaggia attraverso i server di Anthropic

224* Gli host che avete elencato sulle [credenziali API](#add-api-credentials) dell'ambiente, tranne gli [host che non ricevono mai la credenziale](#requests-that-never-get-the-credential)

225* L'API Anthropic, per le richieste di Claude Code stesso, anche a **None**, come notato sotto [Sicurezza e isolamento](/docs/it/claude-code-on-the-web#security-and-isolation)

226

227<h3 id="allow-specific-domains">

228 Consentire domini specifici

229</h3>

230

231Per consentire domini che non sono nella lista Trusted, selezionate **Custom** nelle impostazioni di accesso di rete dell'ambiente, quindi elencate un dominio per riga nel campo **Allowed domains**. Questo esempio consente tre host che un progetto interno potrebbe necessitare.

232

233```text theme={null}

234api.example.com

235*.internal.example.com

236registry.example.com

237```

238

239Le sessioni in questo ambiente possono ora raggiungere `api.example.com`, qualsiasi sottodominio di `internal.example.com` e `registry.example.com`, e nessun altro dominio attraverso la rete della sessione. Il [traffico GitHub](#github-proxy), il [traffico del connettore MCP](#network-access) e le richieste agli host delle [credenziali API](#add-api-credentials) dell'ambiente, diversi dagli [host che non ricevono mai la credenziale](#requests-that-never-get-the-credential), non passano attraverso questo elenco di consentiti. Un `*.` iniziale corrisponde a ogni sottodominio. Per mantenere anche i [domini Trusted](#default-allowed-domains), selezionate **Also include default list of common package managers**; lasciatelo deselezionato per consentire solo quello che elencate.

240

241Se la vostra organizzazione utilizza gli [artifact](/docs/it/artifacts#availability), non avete bisogno di `*.frame.claudeusercontent.com` nell'elenco affinché le sessioni li leggano. Quando l'elenco lascia fuori quell'host, Claude Code legge il contenuto dell'artifact attraverso la connessione della sessione ad Anthropic invece. Mantenete l'host in un elenco di consentiti in due situazioni:

242

243* **Le sessioni in questo ambiente aprono gli artifact pubblici di un'altra organizzazione**: Claude Code li recupera dall'host direttamente, quindi aggiungetelo a questo elenco.

244* **State configurando la CLI locale o un runner self-hosted**: mantenete l'host in quell'elenco di consentiti. Consultate i [requisiti di accesso di rete](/docs/it/network-config#network-access-requirements) e i [requisiti di rete](/docs/it/self-hosted-environments-deploy#network-requirements) self-hosted.

245

246Ogni ambiente ha il suo elenco di domini consentiti; non c'è un elenco di consentiti a livello di organizzazione che gli amministratori possono spingere agli ambienti di ogni membro. Le [impostazioni gestite dal server](/docs/it/server-managed-settings) si applicano ancora all'interno delle sessioni cloud, ma nessuna di esse aggiunge domini all'elenco di consentiti di rete dell'ambiente.

247

248<h3 id="github-proxy">

249 Proxy GitHub

250</h3>

251

252Negli ambienti ospitati da Anthropic, tutte le operazioni GitHub passano attraverso un proxy dedicato che mantiene le vostre credenziali GitHub reali al di fuori della VM della sessione, indipendentemente dal [livello di accesso](#access-levels) dell'ambiente. Le sessioni in un ambiente self-hosted si autenticano con le operazioni git con le credenziali che la vostra distribuzione fornisce; [Configurare git](/docs/it/self-hosted-environments-deploy#configure-git) copre le opzioni, incluse le credenziali coniate per sessione e un opt-in a questo stesso proxy. Il proxy fornisce:

253

254* **Credenziali Git**: il client git all'interno della VM utilizza una credenziale con ambito, che il proxy verifica e scambia con il vostro token GitHub effettivo.

255* **Richieste API**: le richieste dagli strumenti GitHub integrati e da `gh` sotto il [segnaposto `proxy-injected`](#work-with-github-issues-and-pull-requests), vengono inviate con le vostre credenziali reali sostituite.

256* **Protezione push**: `git push` funziona solo contro il ramo di lavoro corrente della sessione; la clonazione, il recupero e le operazioni PR funzionano normalmente.

257* **Ambito del repository**: le richieste API GitHub e di asset di rilascio raggiungono solo i repository collegati alla sessione, quindi uno script di configurazione che scarica asset di rilascio da un repository non collegato riceve un 403.

258* **Restrizioni GraphQL**: il proxy serve solo un set fisso di operazioni GraphQL per i flussi di lavoro delle pull request. Il proxy rifiuta tutto il resto sull'endpoint GraphQL con un 403 che dice `This GraphQL query is not enabled for this session` e nomina il fallback REST, `gh api repos/{owner}/{repo}/...`. La restrizione si applica a ogni richiesta attraverso il proxy indipendentemente dalle credenziali che fornite, quindi un `GH_TOKEN` che impostate riceve lo stesso 403. Claude non può raggiungere le API GitHub che esistono solo in GraphQL, come Projects v2, attraverso il proxy.

259

260I file sottoposti a commit dai repository pubblici arrivano tramite `raw.githubusercontent.com`, che il [proxy di sicurezza](#security-proxy) gestisce invece. Quel dominio è nella lista [Trusted](#default-allowed-domains) predefinita, quindi quei file rimangono raggiungibili a meno che il [livello di accesso](#access-levels) dell'ambiente non lo escluda.

261

262<h3 id="security-proxy">

263 Proxy di sicurezza

264</h3>

265

266Le sessioni cloud negli ambienti ospitati da Anthropic vengono eseguite dietro un proxy di rete HTTP/HTTPS per scopi di sicurezza e prevenzione degli abusi; in un [ambiente self-hosted](/docs/it/self-hosted-environments-deploy#default-deny-egress), il traffico in uscita esce attraverso il vostro confine di rete invece. Tutto il traffico internet in uscita da una sessione ospitata da Anthropic passa attraverso questo proxy, che fornisce:

267

268* Protezione contro richieste dannose

269* Limitazione della velocità e prevenzione degli abusi

270* Filtro dei contenuti per una sicurezza migliorata

271* Un audit trail a livello DNS dei nomi host richiesti

272

273<h2 id="what’s-available-in-cloud-sessions">

274 Cosa è disponibile nelle sessioni cloud

275</h2>

276

277Negli ambienti ospitati da Anthropic, ogni sessione ottiene una macchina virtuale (VM) fresca che esegue Ubuntu 24.04 su x86\_64, indipendentemente dal vostro sistema operativo e dall'architettura della CPU, con il vostro repository clonato e i toolchain comuni preinstallati. Quando una dipendenza fornisce binari precompilati, come gem Ruby con estensioni native o wheel Python precostruiti, utilizzate la sua build Linux x86\_64 per corrispondere alla VM. Questa sezione copre i default ospitati da Anthropic, gli strumenti GitHub integrati, come [eseguire test e servizi](#run-tests-start-services-and-add-packages), e i [limiti di risorse](#resource-limits) che ogni VM ottiene.

278

279<Note>

280 Le sessioni che la vostra organizzazione instrada a un [ambiente self-hosted](/docs/it/self-hosted-environments) vengono eseguite sui vostri runner invece, con gli strumenti che la vostra immagine runner fornisce.

281</Note>

282

283<h3 id="what-carries-over-from-your-setup">

284 Cosa viene trasferito dalla vostra configurazione

285</h3>

286

287Le sessioni cloud iniziano da un clone fresco del vostro repository. Qualsiasi cosa che sottoponete a commit nel repository è disponibile. Qualsiasi cosa che avete installato o configurato solo sulla vostra macchina non è disponibile nella sessione. La politica della vostra organizzazione arriva separatamente attraverso le [impostazioni gestite dal server](/docs/it/server-managed-settings).

288

289| | Disponibile nelle sessioni cloud | Perché |

290| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

291| Il vostro `CLAUDE.md` del repository | Sì | Parte del clone |

292| I vostri hook `.claude/settings.json` del repository | Sì | Parte del clone |

293| I vostri server MCP `.mcp.json` del repository | Sì | Parte del clone |

294| Il vostro `.claude/rules/` del repository | Sì | Parte del clone |

295| Il vostro `.claude/skills/`, `.claude/agents/`, `.claude/commands/` del repository | Sì | Parte del clone |

296| Plugin dichiarati in `.claude/settings.json` | Sì | Installati all'avvio della sessione dal [marketplace](/docs/it/plugin-marketplaces) che avete dichiarato. Richiede accesso di rete per raggiungere la fonte del marketplace |

297| Le [impostazioni gestite dal server](/docs/it/server-managed-settings) della vostra organizzazione | Sì | Recuperate dai server di Anthropic quando la sessione inizia. Consultate [Copertura della superficie](/docs/it/model-config#surface-coverage) per come `availableModels` viene applicato nelle sessioni cloud. Le impostazioni distribuite al vostro dispositivo tramite MDM o file di impostazioni gestite non si applicano, perché la sessione viene eseguita su una VM gestita da Anthropic; in un [ambiente self-hosted](/docs/it/self-hosted-environments), le sessioni leggono anche il file di impostazioni gestite nell'immagine runner, per [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) |

298| Il vostro `~/.claude/CLAUDE.md` utente | No | Vive sulla vostra macchina, non nel repository |

299| Il vostro `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` utente | No | Vivono sulla vostra macchina, non nel repository. Sottoponete a commit nel directory `.claude/` del repository. Le sessioni cloud caricano automaticamente le skill che abilitate su claude.ai |

300| Plugin abilitati solo nelle vostre impostazioni utente | No | L'`enabledPlugins` con ambito utente vive in `~/.claude/settings.json`. Dichiarateli nel `.claude/settings.json` del repository, o abilitateli per il vostro account claude.ai in modo che Claude Code li carichi come [plugin sincronizzati](/docs/it/plugins-reference#synced-plugins) |

301| Server MCP che avete aggiunto con `claude mcp add` all'ambito locale predefinito o all'ambito utente | No | Quelli scrivono su `~/.claude.json` sulla vostra macchina, non nel repository. Aggiungete il server con `claude mcp add --scope project`, che scrive il [`.mcp.json`](/docs/it/mcp#project-scope) del repository, e sottoponete a commit quel file |

302| Variabili di trasporto nel vostro blocco `env` di `.claude/settings.json` del repository, come `NODE_EXTRA_CA_CERTS` e le [variabili del certificato client mTLS](/docs/it/network-config#mtls-authentication) | No | L'ambiente di hosting gestisce la connessione API della sessione, quindi Claude Code ignora queste chiavi e annota ogni chiave ignorata nel log di debug della sessione |

303| Chiavi API e token per i servizi che Claude chiama | Sui piani Pro e Max, come [credenziali API](#add-api-credentials) | Aggiungete la chiave una volta sull'ambiente e il proxy dell'agente la allega alle richieste per gli host che elencate. Una chiave che il proxy dell'agente [non può allegare](#requests-that-never-get-the-credential), o qualsiasi chiave su un piano Team o Enterprise, rimane in una variabile di ambiente |

304| Auth interattivo come AWS SSO | No | Non supportato. SSO richiede un login basato su browser che non può essere eseguito in una sessione cloud |

305

306Per rendere disponibile la vostra configurazione nelle sessioni cloud, sottoponete a commit nel repository.

307

308Chiunque utilizzi l'ambiente può leggere le sue variabili di ambiente e lo script di configurazione. La nota della finestra di dialogo sotto **Environment variables** lo dice e avverte contro l'aggiunta di segreti lì. Sui piani Pro e Max, memorizzate una chiave che il proxy dell'agente può allegare come [credenziale API](#add-api-credentials) invece.

309

310<h3 id="installed-tools">

311 Strumenti installati

312</h3>

313

314Le sessioni cloud vengono fornite con runtime di linguaggio comuni, strumenti di build e database preinstallati. La tabella seguente riassume cosa è incluso per categoria.

315

316| Categoria | Incluso |

317| :----------- | :--------------------------------------------------------------------- |

318| **Python** | Python 3.x con pip, poetry, uv, black, mypy, pytest, ruff |

319| **Node.js** | 20, 21 e 22, con npm, yarn, pnpm, bun¹, eslint, prettier, chromedriver |

320| **Ruby** | 3.1, 3.2, 3.3 con gem, bundler, rbenv |

321| **PHP** | 8.3 con Composer |

322| **Java** | OpenJDK 21 con Maven e Gradle |

323| **Go** | Go con supporto dei moduli |

324| **Rust** | rustc e cargo |

325| **C/C++** | GCC, Clang, cmake, ninja, conan |

326| **Docker** | docker, dockerd, docker compose |

327| **Database** | PostgreSQL 16, Redis 7.0 |

328| **Utilità** | git, gh, jq, yq, ripgrep, tmux, vim, nano |

329

330¹ Bun è installato ma ha [problemi di compatibilità](#install-dependencies-with-a-sessionstart-hook) noti con il proxy per il recupero dei pacchetti.

331

332Per ottenere le versioni della maggior parte degli strumenti in questa tabella, chiedete a Claude di eseguire `check-tools` in una sessione cloud. È un comando shell installato sulla VM della sessione, non un comando slash; chiedete a Claude perché [Claude esegue tutti i comandi della VM per voi](#run-tests-start-services-and-add-packages). Per uno strumento che non segnala, come Ruby, PHP, bun, PostgreSQL o Redis, chiedete a Claude di eseguire il comando di versione dello strumento stesso, ad esempio `psql --version`.

333

334Le versioni di Node.js sono installate su `/opt/node20`, `/opt/node21` e `/opt/node22`, con 22 su `PATH` per impostazione predefinita. Per lavorare con una versione diversa, chiedete a Claude di anteporre la directory `bin` di quella versione, come `/opt/node20/bin`, a `PATH`.

335

336I toolchain al di fuori di questo elenco, come .NET SDK, non sono preinstallati anche quando i loro registri di pacchetti sono sulla [lista di consentiti predefinita](#default-allowed-domains). Installateli con uno [script di configurazione](#setup-scripts).

337

338<h3 id="work-with-github-issues-and-pull-requests">

339 Lavorare con i problemi e le pull request di GitHub

340</h3>

341

342Le sessioni cloud includono strumenti GitHub integrati che consentono a Claude di leggere i problemi, elencare le pull request, recuperare i diff e pubblicare commenti senza alcuna configurazione. Questi strumenti si autenticano attraverso il [proxy GitHub](#github-proxy) utilizzando il metodo che avete configurato sotto [Opzioni di autenticazione GitHub](/docs/it/claude-code-on-the-web#github-authentication-options), quindi il vostro token non entra mai nel contenitore.

343

344Potete impostare `GH_TOKEN` o `GITHUB_TOKEN` voi stessi nelle [impostazioni di ambiente](#set-environment-variables), o lasciare entrambi non impostati e lasciare che il [proxy GitHub](#github-proxy) si autentichi per voi:

345

346* Se impostate un token, passa attraverso al contenitore invariato, quindi i vostri script e il [`gh` CLI](https://cli.github.com) di GitHub lo utilizzano direttamente.

347* Se non impostate nessuno e il [proxy GitHub](#github-proxy) sta gestendo l'autenticazione per la vostra sessione, entrambe le variabili leggono come la stringa segnaposto `proxy-injected` nei comandi che Claude esegue, e il proxy sostituisce le vostre credenziali reali sulle richieste GitHub in uscita. `gh` funziona senza un token vostro, ma uno script che legge `GITHUB_TOKEN` direttamente ottiene il segnaposto, non un token utilizzabile.

348

349Un token che impostate è una variabile di ambiente ordinaria, quindi chiunque utilizzi l'ambiente può leggerlo; il percorso del proxy mantiene la credenziale fuori dalla configurazione dell'ambiente e dalla VM della sessione.

350

351Per verificare quale caso si applica alla vostra sessione, chiedete a Claude di eseguire `echo $GH_TOKEN`.

352

353Il [`gh` CLI](https://cli.github.com) di GitHub è preinstallato. Se avete bisogno di un comando `gh` che gli strumenti integrati non coprono, come `gh release` o `gh workflow run`, chiedete a Claude di eseguirlo. `gh` legge `GH_TOKEN` automaticamente, quindi non avete bisogno di eseguire `gh auth login`.

354

355<h3 id="link-output-back-to-the-session">

356 Collegare l'output di nuovo alla sessione

357</h3>

358

359Ogni sessione cloud ha un URL di trascrizione su claude.ai, e la sessione può leggere il suo ID dalla variabile di ambiente `CLAUDE_CODE_REMOTE_SESSION_ID`. Utilizzate questo per mettere un link tracciabile nei corpi PR, nei messaggi di commit, nei post Slack o nei report generati in modo che un revisore possa aprire l'esecuzione che li ha prodotti.

360

361I commit che Claude crea in una sessione cloud includono un trailer git `Claude-Session: <url>`, e i corpi PR includono l'URL della sessione su una riga propria. Questo richiede v2.1.179 o successiva. Per omettere il trailer e il link nel corpo PR, impostate [`attribution.sessionUrl`](/docs/it/settings-reference#attribution-sessionurl) su `false`. L'impostazione richiede v2.1.182 o successiva.

362

363Per includere il link della sessione in qualcosa di diverso da un commit o PR, come un messaggio Slack che Claude pubblica o un file di report che scrive, chiedete a Claude di eseguire il comando seguente e utilizzate il suo output. Il comando converte il prefisso `cse_` nel valore della variabile di ambiente al prefisso `session_` che l'URL della trascrizione si aspetta:

364

365```bash theme={null}

366echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

367```

368

369<h3 id="run-tests-start-services-and-add-packages">

370 Eseguire test, avviare servizi e aggiungere pacchetti

371</h3>

372

373Non avete una shell nella VM della sessione. Claude esegue ogni comando per voi, quindi formulate i compiti in questa sezione come richieste nel vostro prompt.

374

375<h4 id="run-tests">

376 Eseguire test

377</h4>

378

379Claude esegue i test come parte del lavoro su un compito. Chiedete nel vostro prompt, come "fix the failing tests in `tests/`" o "run pytest after each change." I test runner che vengono con i [toolchain preinstallati](#installed-tools), come pytest e cargo test, funzionano senza configurazione aggiuntiva. Un runner che il vostro progetto dichiara come dipendenza, come jest, si installa con le vostre dipendenze.

380

381<h4 id="start-services">

382 Avviare servizi

383</h4>

384

385PostgreSQL e Redis sono preinstallati ma non in esecuzione per impostazione predefinita. Chiedete a Claude di avviare quello di cui avete bisogno; i comandi che esegue sono:

386

387```bash theme={null}

388service postgresql start

389```

390

391```bash theme={null}

392service redis-server start

393```

394

395Docker è disponibile per l'esecuzione di servizi containerizzati. Chiedete a Claude di eseguire `docker compose up` per avviare i servizi del vostro progetto. L'accesso di rete per il pull delle immagini segue il [livello di accesso](#access-levels) del vostro ambiente, e i [default Trusted](#default-allowed-domains) includono Docker Hub e altri registri comuni.

396

397Se le vostre immagini sono grandi o lente da estrarre, aggiungete `docker compose pull` o `docker compose build` al vostro [script di configurazione](#setup-scripts). La [cache dell'ambiente](#environment-caching) mantiene le immagini estratte, quindi ogni nuova sessione le ha su disco. La cache memorizza solo file, non processi in esecuzione, quindi Claude avvia comunque i contenitori ogni sessione.

398

399<h4 id="add-packages">

400 Aggiungere pacchetti

401</h4>

402

403Per aggiungere pacchetti che non sono preinstallati, utilizzate uno [script di configurazione](#setup-scripts). La [cache dell'ambiente](#environment-caching) mantiene quello che lo script installa, quindi i pacchetti che installate lì sono disponibili all'inizio di ogni sessione senza reinstallare ogni volta. Potete anche chiedere a Claude di installare pacchetti a metà sessione, ma quelle installazioni non si trasferiscono ad altre sessioni.

404

405<h3 id="resource-limits">

406 Limiti di risorse

407</h3>

408

409Le sessioni cloud negli ambienti ospitati da Anthropic vengono eseguite con limiti di risorse approssimativi che possono cambiare nel tempo:

410

411* 4 vCPU

412* 16 GB di RAM

413* 30 GB di disco

414

415La VM può interrompere i compiti che necessitano di significativamente più memoria, come grandi lavori di build o test ad alta intensità di memoria. Per carichi di lavoro oltre questi limiti, utilizzate [Remote Control](/docs/it/remote-control) per eseguire Claude Code sul vostro hardware, o eseguite le sessioni cloud in un [ambiente self-hosted](/docs/it/self-hosted-environments) su compute che la vostra organizzazione gestisce.

416

417<h2 id="setup-scripts">

418 Script di configurazione

419</h2>

420

421Uno script di configurazione è uno script Bash che viene eseguito quando inizia una nuova sessione cloud, prima che Claude Code si avvii. Utilizzate gli script di configurazione per installare dipendenze, configurare strumenti o recuperare qualsiasi cosa la sessione necessiti che non sia preinstallata.

422

423Gli script vengono eseguiti come root su Ubuntu 24.04, quindi `apt install` e la maggior parte dei gestori di pacchetti di linguaggio funzionano.

424

425Per aggiungere uno script di configurazione, aprite la finestra di dialogo delle impostazioni dell'ambiente e inserite il vostro script nel campo **Setup script**.

426

427Questo esempio installa [ShellCheck](https://www.shellcheck.net/), che non è preinstallato.

428

429```bash theme={null}

430#!/bin/bash

431apt update && apt install -y shellcheck

432```

433

434<h3 id="script-requirements">

435 Requisiti dello script

436</h3>

437

438Uno script di configurazione ha tre vincoli da considerare:

439

440* **Exit zero**: se lo script esce con non-zero, la sessione non riesce ad avviarsi. Aggiungete `|| true` ai comandi non critici in modo che un fallimento di installazione intermittente non blocchi la sessione.

441* **Finire entro cinque minuti**: mantenete il runtime totale dello script sotto circa cinque minuti in modo che la [cache dell'ambiente](#environment-caching) possa essere costruita. Eseguite le installazioni indipendenti in parallelo con `&` e `wait`, e spostate qualsiasi singolo download che non si adatta in un [hook SessionStart](#setup-scripts-vs-sessionstart-hooks) che lo avvia in background.

442* **Accesso di rete per le installazioni**: le installazioni di pacchetti devono raggiungere i registri. Il livello **Trusted** predefinito copre i [registri di pacchetti comuni](#default-allowed-domains) inclusi npm, PyPI, RubyGems e crates.io; con accesso di rete **None**, le installazioni falliscono.

443

444<h3 id="environment-caching">

445 Caching dell'ambiente

446</h3>

447

448Lo script di configurazione viene eseguito la prima volta che avviate una sessione in un ambiente. Dopo il completamento, Anthropic crea uno snapshot del filesystem e riutilizza quello snapshot come punto di partenza per le sessioni successive. Le nuove sessioni iniziano con le vostre dipendenze, strumenti e immagini Docker già su disco, e saltano il passaggio dello script di configurazione. Questo mantiene l'avvio veloce anche quando lo script installa grandi toolchain o estrae immagini di contenitori.

449

450La cache è uno snapshot del filesystem, quindi mantiene quello che lo script di configurazione scrive su disco e perde qualsiasi cosa che era solo in esecuzione. I pacchetti che installate, le immagini Docker che estraete e i file che scrivete si trasferiscono tutti. Un database che lo script ha avviato, uno stack `docker compose up` o qualsiasi altro processo in background no; avviate quelli per sessione chiedendo a Claude o con un [hook SessionStart](#setup-scripts-vs-sessionstart-hooks).

451

452Lo script di configurazione viene eseguito di nuovo per ricostruire la cache quando cambiate lo script di configurazione dell'ambiente o gli host di rete consentiti, e quando la cache raggiunge la sua scadenza dopo circa sette giorni. Riprendere una sessione esistente non riesegue mai lo script di configurazione.

453

454Non avete bisogno di abilitare il caching o gestire gli snapshot voi stessi.

455

456<h3 id="setup-scripts-vs-sessionstart-hooks">

457 Script di configurazione vs. hook SessionStart

458</h3>

459

460Utilizzate uno script di configurazione per fornire la VM stessa: toolchain e strumenti CLI che non sono [preinstallati](#installed-tools). Utilizzate un [hook SessionStart](/docs/it/hooks#sessionstart) per la configurazione del progetto che dovrebbe essere eseguita ovunque, cloud e locale, come `npm install`.

461

462Gli script di configurazione e gli hook SessionStart vengono eseguiti in un ordine fisso quando inizia una sessione cloud. La tabella confronta dove li configurate, quando vengono eseguiti e dove vengono eseguiti.

463

464| | Script di configurazione | Hook SessionStart |

465| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

466| **Dove li configurate** | La finestra di dialogo dell'ambiente su [claude.ai/code](https://claude.ai/code), più la pagina **Cloud environments** dell'amministrazione per gli [ambienti condivisi](#organization-shared-environments) | Un [file di impostazioni](/docs/it/settings#where-settings-live) come il vostro `.claude/settings.json` del repository; consultate [Cosa viene trasferito dalla vostra configurazione](#what-carries-over-from-your-setup) per quali file raggiungono una sessione cloud |

467| **Quando vengono eseguiti** | Prima che Claude Code si avvii, saltati quando esiste un [ambiente cache](#environment-caching) | Dopo che Claude Code si avvia, su ogni sessione inclusa la ripresa |

468| **Dove vengono eseguiti** | Solo sessioni cloud | Sessioni locali e cloud |

469

470Se avete hook SessionStart nel vostro `~/.claude/settings.json` a livello di utente, non aspettatevi che siano nel cloud: le impostazioni a livello di utente rimangono sulla vostra macchina. Quali altri hook vengono eseguiti dipende da dove viene eseguita la sessione:

471

472* **Ambiente ospitato da Anthropic**: Claude Code esegue gli hook dal repository e dalle [impostazioni gestite dal server](/docs/it/server-managed-settings) della vostra organizzazione.

473* **[Ambiente self-hosted](/docs/it/self-hosted-environments-configuration#permissions-and-tool-approval)**: Claude Code esegue anche gli hook che l'operatore ha seminato da `~/.claude/` dell'host runner, e gli hook nel file di impostazioni gestite dell'immagine runner quando quel file è una delle [fonti gestite che Claude Code applica](/docs/it/managed-settings#how-claude-code-combines-managed-sources).

474

475<h3 id="install-dependencies-with-a-sessionstart-hook">

476 Installare dipendenze con un hook SessionStart

477</h3>

478

479Per installare dipendenze solo nelle sessioni cloud, abbinate un hook SessionStart con uno script che verifica dove è in esecuzione.

480

481Per primo, aggiungete un hook SessionStart al vostro `.claude/settings.json` del repository. Questa configurazione dice a Claude Code di eseguire `scripts/install_pkgs.sh` dal vostro repository ogni volta che una sessione inizia o riprende:

482

483```json theme={null}

484{

485 "hooks": {

486 "SessionStart": [

487 {

488 "matcher": "startup|resume",

489 "hooks": [

490 {

491 "type": "command",

492 "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"

493 }

494 ]

495 }

496 ]

497 }

498}

499```

500

501Il `matcher` limita l'hook agli eventi `startup` e `resume`, e `$CLAUDE_PROJECT_DIR` si risolve nella radice del repository, quindi l'hook trova lo script indipendentemente dalla directory di lavoro della sessione.

502

503Successivamente, create lo script su `scripts/install_pkgs.sh`. Esce immediatamente al di fuori del cloud, quindi installa le vostre dipendenze:

504

505```bash theme={null}

506#!/bin/bash

507

508if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then

509 exit 0

510fi

511

512npm install

513pip install -r requirements.txt

514exit 0

515```

516

517Il controllo `CLAUDE_CODE_REMOTE` è quello che limita l'installazione alle sessioni cloud: la VM della sessione porta quella variabile come `true`, non è mai `true` localmente, quindi sul vostro laptop lo script esce prima di installare qualsiasi cosa.

518

519Insieme, i due file danno a ogni sessione cloud un `npm install` e `pip install` fresco all'avvio mentre lasciano le sessioni locali intatte.

520

521<h4 id="limitations-in-cloud-sessions">

522 Limitazioni nelle sessioni cloud

523</h4>

524

525Gli hook SessionStart si comportano allo stesso modo nel cloud che localmente, con questi avvertimenti:

526

527* **Nessun ambito solo cloud**: gli hook vengono eseguiti sia nelle sessioni locali che cloud. Per saltare l'esecuzione locale, controllate la variabile di ambiente `CLAUDE_CODE_REMOTE` come mostrato sopra.

528* **Richiede accesso di rete**: i comandi di installazione devono raggiungere i registri dei pacchetti. Se il vostro ambiente utilizza accesso di rete **None**, questi hook falliscono. L'[elenco di consentiti predefinito](#default-allowed-domains) sotto **Trusted** copre npm, PyPI, RubyGems e crates.io.

529* **Compatibilità del proxy**: negli ambienti ospitati da Anthropic, tutto il traffico in uscita passa attraverso un [proxy di sicurezza](#security-proxy), e alcuni gestori di pacchetti non funzionano correttamente con esso; Bun è un esempio noto. In un [ambiente self-hosted](/docs/it/self-hosted-environments-deploy#default-deny-egress), il traffico in uscita va attraverso il vostro confine di rete invece.

530* **Aggiunge latenza di avvio**: gli hook vengono eseguiti ogni volta che una sessione inizia o riprende, a differenza degli script di configurazione che beneficiano della [cache dell'ambiente](#environment-caching). Mantenete gli script di installazione veloci controllando se le dipendenze sono già presenti prima di reinstallare.

531

532Per personalizzare l'immagine di base, utilizzate uno script di configurazione per installare quello di cui avete bisogno sopra l'[immagine fornita](#installed-tools), o eseguite la vostra immagine come contenitore insieme a Claude con `docker compose`. La sostituzione completa dell'immagine di base non è ancora supportata.

533

534<h2 id="default-allowed-domains">

535 Domini consentiti predefiniti

536</h2>

537

538Con accesso di rete **Trusted**, le sessioni possono raggiungere i seguenti domini per impostazione predefinita. I domini contrassegnati con `*` indicano la corrispondenza del sottodominio con carattere jolly, quindi `*.gcr.io` consente qualsiasi sottodominio di `gcr.io`.

539

540<AccordionGroup>

541 <Accordion title="Servizi Anthropic">

542 * api.anthropic.com

543 * statsig.anthropic.com

544 * docs.claude.com

545 * platform.claude.com

546 * code.claude.com

547 * claude.ai

548 </Accordion>

549

550 <Accordion title="Controllo versione">

551 * github.com

552 * [www.github.com](http://www.github.com)

553 * api.github.com

554 * npm.pkg.github.com

555 * raw\.githubusercontent.com

556 * pkg-npm.githubusercontent.com

557 * objects.githubusercontent.com

558 * release-assets.githubusercontent.com

559 * codeload.github.com

560 * avatars.githubusercontent.com

561 * camo.githubusercontent.com

562 * gist.github.com

563 * gitlab.com

564 * [www.gitlab.com](http://www.gitlab.com)

565 * registry.gitlab.com

566 * bitbucket.org

567 * [www.bitbucket.org](http://www.bitbucket.org)

568 * api.bitbucket.org

569 </Accordion>

570

571 <Accordion title="Registri di contenitori">

572 * registry-1.docker.io

573 * auth.docker.io

574 * index.docker.io

575 * hub.docker.com

576 * [www.docker.com](http://www.docker.com)

577 * production.cloudflare.docker.com

578 * download.docker.com

579 * gcr.io

580 * \*.gcr.io

581 * ghcr.io

582 * mcr.microsoft.com

583 * \*.data.mcr.microsoft.com

584 * public.ecr.aws

585 </Accordion>

586

587 <Accordion title="Piattaforme cloud">

588 * cloud.google.com

589 * accounts.google.com

590 * gcloud.google.com

591 * \*.googleapis.com

592 * storage.googleapis.com

593 * compute.googleapis.com

594 * container.googleapis.com

595 * azure.com

596 * portal.azure.com

597 * microsoft.com

598 * [www.microsoft.com](http://www.microsoft.com)

599 * \*.microsoftonline.com

600 * packages.microsoft.com

601 * dotnet.microsoft.com

602 * dot.net

603 * visualstudio.com

604 * dev.azure.com

605 * \*.amazonaws.com

606 * \*.api.aws

607 * oracle.com

608 * [www.oracle.com](http://www.oracle.com)

609 * java.com

610 * [www.java.com](http://www.java.com)

611 * java.net

612 * [www.java.net](http://www.java.net)

613 * download.oracle.com

614 * yum.oracle.com

615 </Accordion>

616

617 <Accordion title="Gestori di pacchetti JavaScript e Node">

618 * registry.npmjs.org

619 * [www.npmjs.com](http://www.npmjs.com)

620 * [www.npmjs.org](http://www.npmjs.org)

621 * npmjs.com

622 * npmjs.org

623 * yarnpkg.com

624 * registry.yarnpkg.com

625 </Accordion>

626

627 <Accordion title="Gestori di pacchetti Python">

628 * pypi.org

629 * [www.pypi.org](http://www.pypi.org)

630 * files.pythonhosted.org

631 * pythonhosted.org

632 * test.pypi.org

633 * pypi.python.org

634 * pypa.io

635 * [www.pypa.io](http://www.pypa.io)

636 </Accordion>

637

638 <Accordion title="Gestori di pacchetti Ruby">

639 * rubygems.org

640 * [www.rubygems.org](http://www.rubygems.org)

641 * api.rubygems.org

642 * index.rubygems.org

643 * ruby-lang.org

644 * [www.ruby-lang.org](http://www.ruby-lang.org)

645 * rubyforge.org

646 * [www.rubyforge.org](http://www.rubyforge.org)

647 * rubyonrails.org

648 * [www.rubyonrails.org](http://www.rubyonrails.org)

649 * rvm.io

650 * get.rvm.io

651 </Accordion>

652

653 <Accordion title="Gestori di pacchetti Rust">

654 * crates.io

655 * [www.crates.io](http://www.crates.io)

656 * index.crates.io

657 * static.crates.io

658 * rustup.rs

659 * static.rust-lang.org

660 * [www.rust-lang.org](http://www.rust-lang.org)

661 </Accordion>

662

663 <Accordion title="Gestori di pacchetti Go">

664 * proxy.golang.org

665 * sum.golang.org

666 * index.golang.org

667 * golang.org

668 * [www.golang.org](http://www.golang.org)

669 * goproxy.io

670 * pkg.go.dev

671 </Accordion>

672

673 <Accordion title="Gestori di pacchetti JVM">

674 * maven.org

675 * repo.maven.org

676 * central.maven.org

677 * repo1.maven.org

678 * repo.maven.apache.org

679 * jcenter.bintray.com

680 * gradle.org

681 * [www.gradle.org](http://www.gradle.org)

682 * services.gradle.org

683 * plugins.gradle.org

684 * kotlinlang.org

685 * [www.kotlinlang.org](http://www.kotlinlang.org)

686 * spring.io

687 * repo.spring.io

688 </Accordion>

689

690 <Accordion title="Altri gestori di pacchetti">

691 * packagist.org (PHP Composer)

692 * [www.packagist.org](http://www.packagist.org)

693 * repo.packagist.org

694 * nuget.org (.NET NuGet)

695 * [www.nuget.org](http://www.nuget.org)

696 * api.nuget.org

697 * pub.dev (Dart/Flutter)

698 * api.pub.dev

699 * hex.pm (Elixir/Erlang)

700 * [www.hex.pm](http://www.hex.pm)

701 * cpan.org (Perl CPAN)

702 * [www.cpan.org](http://www.cpan.org)

703 * metacpan.org

704 * [www.metacpan.org](http://www.metacpan.org)

705 * api.metacpan.org

706 * cocoapods.org (iOS/macOS)

707 * [www.cocoapods.org](http://www.cocoapods.org)

708 * cdn.cocoapods.org

709 * haskell.org

710 * [www.haskell.org](http://www.haskell.org)

711 * hackage.haskell.org

712 * swift.org

713 * [www.swift.org](http://www.swift.org)

714 </Accordion>

715

716 <Accordion title="Distribuzioni Linux">

717 * archive.ubuntu.com

718 * security.ubuntu.com

719 * ubuntu.com

720 * [www.ubuntu.com](http://www.ubuntu.com)

721 * \*.ubuntu.com

722 * ppa.launchpad.net

723 * launchpad.net

724 * [www.launchpad.net](http://www.launchpad.net)

725 * \*.nixos.org

726 </Accordion>

727

728 <Accordion title="Strumenti di sviluppo e piattaforme">

729 * dl.k8s.io (Kubernetes)

730 * pkgs.k8s.io

731 * k8s.io

732 * [www.k8s.io](http://www.k8s.io)

733 * releases.hashicorp.com (HashiCorp)

734 * apt.releases.hashicorp.com

735 * rpm.releases.hashicorp.com

736 * archive.releases.hashicorp.com

737 * hashicorp.com

738 * [www.hashicorp.com](http://www.hashicorp.com)

739 * repo.anaconda.com (Anaconda/Conda)

740 * conda.anaconda.org

741 * anaconda.org

742 * [www.anaconda.com](http://www.anaconda.com)

743 * anaconda.com

744 * continuum.io

745 * apache.org (Apache)

746 * [www.apache.org](http://www.apache.org)

747 * archive.apache.org

748 * downloads.apache.org

749 * eclipse.org (Eclipse)

750 * [www.eclipse.org](http://www.eclipse.org)

751 * download.eclipse.org

752 * nodejs.org (Node.js)

753 * [www.nodejs.org](http://www.nodejs.org)

754 * developer.apple.com

755 * developer.android.com

756 * pkg.stainless.com

757 * binaries.prisma.sh

758 </Accordion>

759

760 <Accordion title="Servizi cloud e monitoraggio">

761 * statsig.com

762 * [www.statsig.com](http://www.statsig.com)

763 * api.statsig.com

764 * sentry.io

765 * \*.sentry.io

766 * downloads.sentry-cdn.com

767 * http-intake.logs.datadoghq.com

768 * browser-intake-us5-datadoghq.com

769 * \*.datadoghq.com

770 * \*.datadoghq.eu

771 * api.honeycomb.io

772 </Accordion>

773

774 <Accordion title="Distribuzione di contenuti e mirror">

775 * sourceforge.net

776 * \*.sourceforge.net

777 * packagecloud.io

778 * \*.packagecloud.io

779 * fonts.googleapis.com

780 * fonts.gstatic.com

781 </Accordion>

782

783 <Accordion title="Schema e configurazione">

784 * json-schema.org

785 * [www.json-schema.org](http://www.json-schema.org)

786 * json.schemastore.org

787 * [www.schemastore.org](http://www.schemastore.org)

788 </Accordion>

789

790 <Accordion title="Model Context Protocol">

791 * \*.modelcontextprotocol.io

792 </Accordion>

793</AccordionGroup>

794

795<h2 id="related-resources">

796 Risorse correlate

797</h2>

798

799* [Claude Code sul web](/docs/it/claude-code-on-the-web): avviare, gestire e condividere sessioni cloud

800* [Guida rapida web](/docs/it/web-quickstart): connettere GitHub e avviare la vostra prima sessione cloud

801* [Claude Tag](https://claude.com/docs/claude-tag/overview): le sessioni che Claude avvia da Slack vengono eseguite negli stessi ambienti

802* [Routine](/docs/it/routines): le esecuzioni programmate utilizzano gli stessi ambienti e livelli di accesso di rete

803* [Remote Control](/docs/it/remote-control): eseguire sessioni sulla rete e sui file della vostra macchina invece

804* [Ambienti self-hosted](/docs/it/self-hosted-environments): eseguire sessioni cloud sull'infrastruttura propria della vostra organizzazione

805* [Hook SessionStart](/docs/it/hooks#sessionstart): configurazione sottoposta a commit nel repository che viene eseguita nelle sessioni locali e cloud

806* [Impostazioni gestite dal server](/docs/it/server-managed-settings): politica dell'organizzazione che raggiunge le sessioni cloud

commands.md +4 −4

Details

55| :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |55| :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

56| `/add-dir <path>` | Aggiungere una directory di lavoro per l'accesso ai file durante la sessione corrente. Digitate un percorso parziale per vedere i suggerimenti di directory corrispondenti; premete `Tab` per accettarne uno. La maggior parte della configurazione `.claude/` [non viene scoperta](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) dalla directory aggiunta. Non potete aggiungere la maggior parte dei [percorsi di rete](/docs/it/errors#working-directory-is-a-network-path), come `\\server\share`. Dopo un'aggiunta riuscita, i vostri [hook `DirectoryAdded`](/docs/it/hooks#directoryadded) vengono eseguiti. Quando lo eseguite mentre Claude sta rispondendo, Claude Code vi chiede di confermare la directory subito, e una volta confermata, la prossima chiamata di strumento di Claude nello stesso turno può accedervi. Prima della v2.1.234, Claude Code metteva in coda il comando fino al termine del turno |56| `/add-dir <path>` | Aggiungere una directory di lavoro per l'accesso ai file durante la sessione corrente. Digitate un percorso parziale per vedere i suggerimenti di directory corrispondenti; premete `Tab` per accettarne uno. La maggior parte della configurazione `.claude/` [non viene scoperta](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) dalla directory aggiunta. Non potete aggiungere la maggior parte dei [percorsi di rete](/docs/it/errors#working-directory-is-a-network-path), come `\\server\share`. Dopo un'aggiunta riuscita, i vostri [hook `DirectoryAdded`](/docs/it/hooks#directoryadded) vengono eseguiti. Quando lo eseguite mentre Claude sta rispondendo, Claude Code vi chiede di confermare la directory subito, e una volta confermata, la prossima chiamata di strumento di Claude nello stesso turno può accedervi. Prima della v2.1.234, Claude Code metteva in coda il comando fino al termine del turno |

57| `/advisor [model\|off]` | Abilitare o disabilitare lo [strumento advisor](/docs/it/advisor), che consulta un secondo modello per una guida nei momenti chiave durante un'attività. Accetta `fable`, `opus`, `sonnet`, o un ID modello completo. `fable` richiede l'[accesso a Fable](/docs/it/advisor#choose-an-advisor-model). Senza un argomento, apre un selettore |57| `/advisor [model\|off]` | Abilitare o disabilitare lo [strumento advisor](/docs/it/advisor), che consulta un secondo modello per una guida nei momenti chiave durante un'attività. Accetta `fable`, `opus`, `sonnet`, o un ID modello completo. `fable` richiede l'[accesso a Fable](/docs/it/advisor#choose-an-advisor-model). Senza un argomento, apre un selettore. In una sessione senza un terminale interattivo, o su [Remote Control](/docs/it/remote-control#limitations), passate il modello o `off` come argomento; senza argomento lì, il comando stampa l'advisor corrente come testo. Questi moduli richiedono Claude Code v2.1.260 o successivo |

58| `/agents` | A partire dalla v2.1.198, l'esecuzione di `/agents` stampa un promemoria per chiedere a Claude di creare o gestire [subagent](/docs/it/sub-agents), o di modificare direttamente `.claude/agents/` o `~/.claude/agents/`. Nella v2.1.197 e precedenti, apre un'interfaccia interattiva per creare e gestire le configurazioni dei subagent |58| `/agents` | A partire dalla v2.1.198, l'esecuzione di `/agents` stampa un promemoria per chiedere a Claude di creare o gestire [subagent](/docs/it/sub-agents), o di modificare direttamente `.claude/agents/` o `~/.claude/agents/`. Nella v2.1.197 e precedenti, apre un'interfaccia interattiva per creare e gestire le configurazioni dei subagent |

59| `/artifacts` | Elencare gli [artifact](/docs/it/artifacts#find-an-artifact-again) che possedete o che sono condivisi con voi, quindi allegarne uno alla sessione, aprirlo nel vostro browser, o copiarne il collegamento. Disponibile dove gli [artifact](/docs/it/artifacts#availability) sono disponibili. Richiede Claude Code v2.1.208 o successivo; l'allegamento con `Enter` richiede v2.1.216 |59| `/artifacts` | Elencare gli [artifact](/docs/it/artifacts#find-an-artifact-again) che possedete o che sono condivisi con voi, quindi allegarne uno alla sessione, aprirlo nel vostro browser, o copiarne il collegamento. Disponibile dove gli [artifact](/docs/it/artifacts#availability) sono disponibili. Richiede Claude Code v2.1.208 o successivo; l'allegamento con `Enter` richiede v2.1.216 |

60| `/auto-mode-setup` | [Bozza di voci `autoMode.environment`](/docs/it/auto-mode-config#generate-environment-entries) dal vostro progetto e dalle sessioni recenti, quindi rivedete la bozza e salvatela nelle impostazioni utente. Richiede un piano Pro, Max o Team e Claude Code v2.1.228 o successivo. Su Windows nativo, richiede v2.1.233 o successivo |60| `/auto-mode-setup` | [Bozza di voci `autoMode.environment`](/docs/it/auto-mode-config#generate-environment-entries) dal vostro progetto e dalle sessioni recenti, quindi rivedete la bozza e salvatela nelle impostazioni utente. Richiede un piano Pro, Max o Team e Claude Code v2.1.228 o successivo. Su Windows nativo, richiede v2.1.233 o successivo |

81| `/deep-research <question>` | **[Workflow](/docs/it/workflows#bundled-workflows).** Distribuire ricerche web su una domanda, recuperare e controllare incrociato le fonti e sintetizzare un rapporto citato |81| `/deep-research <question>` | **[Workflow](/docs/it/workflows#bundled-workflows).** Distribuire ricerche web su una domanda, recuperare e controllare incrociato le fonti e sintetizzare un rapporto citato |

82| `/design [brief]` | **[Skill](/docs/it/skills#bundled-skills).** Bozza di mockup UI, flussi di schermata, pagine di destinazione o poster come tavole su una tela, pubblicati come [artifact](/docs/it/artifacts#draft-a-design-canvas) che esegue un'anteprima di ricerca dell'editor Claude Design, ad esempio `/design a settings screen for a mobile banking app`. Dove il salvataggio è abilitato per il vostro account, modificate le tavole sulla tela e salvate per pubblicare una nuova versione; altrimenti visualizzate la bozza e esportatela come PNG o PDF. Richiede una sessione dove gli [artifact sono disponibili](/docs/it/artifacts#availability) e Claude Code v2.1.234 o successivo. Disponibile sull'API Anthropic. Su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform su AWS, gli artifact non sono disponibili, quindi il comando non è disponibile lì |82| `/design [brief]` | **[Skill](/docs/it/skills#bundled-skills).** Bozza di mockup UI, flussi di schermata, pagine di destinazione o poster come tavole su una tela, pubblicati come [artifact](/docs/it/artifacts#draft-a-design-canvas) che esegue un'anteprima di ricerca dell'editor Claude Design, ad esempio `/design a settings screen for a mobile banking app`. Dove il salvataggio è abilitato per il vostro account, modificate le tavole sulla tela e salvate per pubblicare una nuova versione; altrimenti visualizzate la bozza e esportatela come PNG o PDF. Richiede una sessione dove gli [artifact sono disponibili](/docs/it/artifacts#availability) e Claude Code v2.1.234 o successivo. Disponibile sull'API Anthropic. Su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform su AWS, gli artifact non sono disponibili, quindi il comando non è disponibile lì |

84| `/design-sync [hint]` | **[Skill](/docs/it/skills#bundled-skills).** Convertire il sistema di progettazione React del vostro repo e caricarlo su [Claude Design](https://claude.ai/design), in modo che i progetti che produce utilizzino i vostri componenti reali. Facoltativamente nominate il sistema di progettazione, ad esempio `/design-sync Acme DS`. Una sincronizzazione per la prima volta verifica ogni componente e può richiedere alcune ore su un grande repo. Disponibile sull'API Anthropic; su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform su AWS lo strumento sottostante non può raggiungere claude.ai, quindi il comando non è disponibile |84| `/design-sync [hint]` | **[Skill](/docs/it/skills#bundled-skills).** Convertire il sistema di progettazione React del vostro repo e caricarlo su [Claude Design](https://claude.ai/design), in modo che i progetti che produce utilizzino i vostri componenti reali. Facoltativamente nominate il sistema di progettazione, ad esempio `/design-sync Acme DS`. Una sincronizzazione per la prima volta verifica ogni componente e può richiedere alcune ore su un grande repo. Disponibile sull'API Anthropic. Ha bisogno di claude.ai, che la CLI non contatta su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o Claude Platform su AWS, o attraverso un [gateway di app Claude](/docs/it/claude-apps-gateway#availability-and-limitations), quindi il comando non è disponibile lì |

85| `/desktop` | Continuare la sessione corrente nell'app Claude Code Desktop. Richiede macOS o Windows x64 e un abbonamento Claude. Alias: `/app` |85| `/desktop` | Continuare la sessione corrente nell'app Claude Code Desktop. Richiede macOS o Windows x64 e un abbonamento Claude. Alias: `/app` |

86| `/diff` | Rivedere le modifiche nel vostro albero di lavoro, inclusi i modifica che Claude ha fatto finora. Consultate [Rivedere le modifiche con /diff](/docs/it/interactive-mode#review-changes-with-%2Fdiff) |86| `/diff` | Rivedere le modifiche nel vostro albero di lavoro, inclusi i modifica che Claude ha fatto finora. Consultate [Rivedere le modifiche con /diff](/docs/it/interactive-mode#review-changes-with-%2Fdiff) |

87| `/doctor` | **[Skill](/docs/it/skills#bundled-skills).** Eseguire un controllo di configurazione che diagnostica i problemi e può risolverli. Controlla la salute dell'installazione, incluse installazioni duplicate o rimaste, problemi di `PATH` e file di impostazioni non analizzabili. Trova skill inutilizzate, server MCP e plugin rispetto al loro costo di contesto, contrassegna [hook](/docs/it/hooks) lenti e controlla una versione più recente sul vostro [canale di rilascio](/docs/it/setup#configure-release-channel). Deduplica i file `CLAUDE.md` locali rispetto a quelli archiviati, taglia i file [`CLAUDE.md`](/docs/it/memory#my-claude-md-is-too-large) archiviati tagliando il contenuto che Claude potrebbe derivare dal codebase, e migra la guida sempre caricata che rimane in [skill](/docs/it/skills) e file `CLAUDE.md` annidati che si caricano su richiesta. Offre anche di rendere [auto mode](/docs/it/permissions#permission-modes) il vostro predefinito e di [pre-approvare](/docs/it/permissions) comandi di sola lettura frequentemente negati. Segnala i risultati per primo e chiede conferma prima di cambiare qualsiasi cosa. Dal terminale, `claude doctor` stampa diagnostica di installazione di sola lettura senza avviare una sessione. Alias: `/checkup`. Il controllo di ridimensionamento `CLAUDE.md` richiede Claude Code v2.1.206 o successivo. Prima della v2.1.205, `/doctor` apriva una schermata di diagnostica di sola lettura e premere `f` inviava il rapporto a Claude |87| `/doctor` | **[Skill](/docs/it/skills#bundled-skills).** Eseguire un controllo di configurazione che diagnostica i problemi e può risolverli. Controlla la salute dell'installazione, incluse installazioni duplicate o rimaste, problemi di `PATH` e file di impostazioni non analizzabili. Trova skill inutilizzate, server MCP e plugin rispetto al loro costo di contesto, contrassegna [hook](/docs/it/hooks) lenti e controlla una versione più recente sul vostro [canale di rilascio](/docs/it/setup#configure-release-channel). Deduplica i file `CLAUDE.md` locali rispetto a quelli archiviati, taglia i file [`CLAUDE.md`](/docs/it/memory#my-claude-md-is-too-large) archiviati tagliando il contenuto che Claude potrebbe derivare dal codebase, e migra la guida sempre caricata che rimane in [skill](/docs/it/skills) e file `CLAUDE.md` annidati che si caricano su richiesta. Offre anche di rendere [auto mode](/docs/it/permissions#permission-modes) il vostro predefinito e di [pre-approvare](/docs/it/permissions) comandi di sola lettura frequentemente negati. Segnala i risultati per primo e chiede conferma prima di cambiare qualsiasi cosa. Dal terminale, `claude doctor` stampa diagnostica di installazione di sola lettura senza avviare una sessione. Alias: `/checkup`. Il controllo di ridimensionamento `CLAUDE.md` richiede Claude Code v2.1.206 o successivo. Prima della v2.1.205, `/doctor` apriva una schermata di diagnostica di sola lettura e premere `f` inviava il rapporto a Claude |

100| `/ide` | Gestire le integrazioni IDE e mostrare lo stato |100| `/ide` | Gestire le integrazioni IDE e mostrare lo stato |

101| `/import [codex\|gemini] [--dry-run] [--yes]` | Portare la configurazione da altri agenti di codifica sulla vostra macchina, attualmente OpenAI Codex e Google Gemini CLI, in Claude Code, inclusi file di istruzioni, server MCP, comandi, subagent e skill. In [modalità non interattiva](/docs/it/headless) con `-p`, `/import` elenca quello che ha trovato e vi dà il comando che conferma l'importazione. Aggiungete `--dry-run` per visualizzare in anteprima senza scrivere nulla, o `--yes` per saltare il selettore interattivo. Non disponibile su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o Claude Platform su AWS. Anche non disponibile quando disattivate il [recupero di flag di funzionalità](/docs/it/env-vars#features-that-need-feature-flag-fetching). Richiede Claude Code v2.1.213 o successivo |101| `/import [codex\|gemini\|cursor] [--dry-run] [--yes]` | Portare la configurazione da OpenAI Codex, Google Gemini CLI, o Cursor sulla vostra macchina in Claude Code, inclusi file di istruzioni, server MCP, comandi, subagent e skill. In [modalità non interattiva](/docs/it/headless) con `-p`, `/import` elenca quello che ha trovato e vi dà il comando che conferma l'importazione. Aggiungete `--dry-run` per visualizzare in anteprima senza scrivere nulla, o `--yes` per saltare il selettore interattivo. Non disponibile su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o Claude Platform su AWS, o attraverso un [gateway di app Claude](/docs/it/claude-apps-gateway#availability-and-limitations). Anche non disponibile quando disattivate il [recupero di flag di funzionalità](/docs/it/env-vars#features-that-need-feature-flag-fetching). Richiede Claude Code v2.1.213 o successivo. L'importazione da Cursor richiede v2.1.265 o successivo |

102| `/init` | Inizializzare il progetto con una guida `CLAUDE.md`. Impostare `CLAUDE_CODE_NEW_INIT=1` per un flusso interattivo che guida anche attraverso skill, hook e file di memoria personale. Se `/init` trova la configurazione da un agente di codifica che `/import` supporta, offre di trasferirla con `/import` |102| `/init` | Inizializzare il progetto con una guida `CLAUDE.md`. Impostare `CLAUDE_CODE_NEW_INIT=1` per un flusso interattivo che guida anche attraverso skill, hook e file di memoria personale. Se `/init` trova la configurazione da OpenAI Codex o Google Gemini CLI, offre di trasferirla con `/import` |

103| `/insights` | Generare un rapporto HTML che analizza le vostre sessioni recenti su questa macchina: quali progetti in cui lavorate, come usate Claude Code, dove le cose vanno male e funzionalità da provare. Non disponibile in [sessioni cloud](/docs/it/claude-code-on-the-web). Consultate [Analizzare i vostri modelli di utilizzo](/docs/it/costs#analyze-your-usage-patterns) per la posizione del rapporto, la conservazione e il costo |103| `/insights` | Generare un rapporto HTML che analizza le vostre sessioni recenti su questa macchina: quali progetti in cui lavorate, come usate Claude Code, dove le cose vanno male e funzionalità da provare. Non disponibile in [sessioni cloud](/docs/it/claude-code-on-the-web). Consultate [Analizzare i vostri modelli di utilizzo](/docs/it/costs#analyze-your-usage-patterns) per la posizione del rapporto, la conservazione e il costo |

104| `/install-github-app` | Installare l'app Claude GitHub per un repository, con un passaggio facoltativo per configurare i flussi di lavoro [GitHub Actions](/docs/it/github-actions) e i segreti. Vi guida attraverso la selezione di un repo e la configurazione dell'integrazione. Funziona solo con repository github.com. Quando il git remote del vostro repository è su gitlab.com o bitbucket.org, il comando stampa un avviso ed esce invece di avviare la configurazione. Per eseguire Claude Code dalle pipeline GitLab, consultate [GitLab CI/CD](/docs/it/gitlab-ci-cd) |104| `/install-github-app` | Installare l'app Claude GitHub per un repository, con un passaggio facoltativo per configurare i flussi di lavoro [GitHub Actions](/docs/it/github-actions) e i segreti. Vi guida attraverso la selezione di un repo e la configurazione dell'integrazione. Funziona solo con repository github.com. Quando il git remote del vostro repository è su gitlab.com o bitbucket.org, il comando stampa un avviso ed esce invece di avviare la configurazione. Per eseguire Claude Code dalle pipeline GitLab, consultate [GitLab CI/CD](/docs/it/gitlab-ci-cd) |

context-window.md +2 −2

Details

1588 1588

1589La sessione illustra un flusso realistico con conteggi di token rappresentativi:1589La sessione illustra un flusso realistico con conteggi di token rappresentativi:

1590 1590

1591* **Prima di digitare qualcosa**: CLAUDE.md, memoria automatica, nomi degli strumenti MCP e descrizioni delle skill si caricano tutti nel contesto. La tua configurazione personale potrebbe aggiungere altro qui, come uno [stile di output](/docs/it/output-styles) o testo da [`--append-system-prompt`](/docs/it/cli-reference), che entrambi vanno nel prompt di sistema allo stesso modo.1591* **Prima di digitare qualcosa**: CLAUDE.md, memoria automatica, nomi degli strumenti MCP e descrizioni delle skill si caricano tutti nel contesto. La tua configurazione personale potrebbe aggiungere altro qui, come uno [stile di output](/docs/it/output-styles) o testo da [`--append-system-prompt`](/docs/it/cli-reference).

1592* **Mentre Claude lavora**: ogni lettura di file si aggiunge al contesto, le [regole con ambito di percorso](/docs/it/memory#path-specific-rules) si caricano automaticamente insieme ai file corrispondenti e un [hook PostToolUse](/docs/it/hooks-guide) si attiva dopo ogni modifica.1592* **Mentre Claude lavora**: ogni lettura di file si aggiunge al contesto, le [regole con ambito di percorso](/docs/it/memory#path-specific-rules) si caricano automaticamente insieme ai file corrispondenti e un [hook PostToolUse](/docs/it/hooks-guide) si attiva dopo ogni modifica.

1593* **Il prompt di follow-up**: un [subagent](/docs/it/sub-agents) gestisce la ricerca nella sua propria finestra di contesto separata, quindi le letture di file di grandi dimensioni rimangono fuori dalla tua. Solo il riepilogo e un piccolo trailer di metadati tornano indietro.1593* **Il prompt di follow-up**: un [subagent](/docs/it/sub-agents) gestisce la ricerca nella sua propria finestra di contesto separata, quindi le letture di file di grandi dimensioni rimangono fuori dalla tua. Solo il riepilogo e un piccolo trailer di metadati tornano indietro.

1594* **Alla fine**: `/compact` sostituisce la conversazione con un riepilogo strutturato. La maggior parte del contenuto di avvio si ricarica automaticamente; la tabella sottostante mostra cosa accade a ogni meccanismo.1594* **Alla fine**: `/compact` sostituisce la conversazione con un riepilogo strutturato. La maggior parte del contenuto di avvio si ricarica automaticamente; la tabella sottostante mostra cosa accade a ogni meccanismo.

1601 1601

1602| Meccanismo | Dopo la compattazione |1602| Meccanismo | Dopo la compattazione |

1603| :----------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |1603| :----------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |

1604| Prompt di sistema e stile di output | Invariato; non fa parte della cronologia dei messaggi |1604| Prompt di sistema e stile di output | Entrambi continuano ad applicarsi |

1605| CLAUDE.md nella radice del progetto e regole senza ambito | Reinizializzato dal disco |1605| CLAUDE.md nella radice del progetto e regole senza ambito | Reinizializzato dal disco |

1606| Memoria automatica | Reinizializzato dal disco |1606| Memoria automatica | Reinizializzato dal disco |

1607| Il piano che Claude ha scritto in [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode) | Reinizializzato dal disco |1607| Il piano che Claude ha scritto in [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode) | Reinizializzato dal disco |

corporate-launcher.md +1 −1

Details

49 Nomi dei processi helper nei monitor dei processi49 Nomi dei processi helper nei monitor dei processi

50</h3>50</h3>

51 51

52Con 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.52Con un launcher configurato, `ps` e Activity Monitor non mostrano più le etichette `claude bg-pty-host` e `claude bg-spare` di Claude Code per i processi helper in background, perché l'`exec` del launcher ricostruisce l'elenco degli argomenti. La perdita delle etichette è 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.

53 53

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

55 Configurare il launcher55 Configurare il launcher

cross-session-messaging.md +405 −0 created

Details

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.

5# Messaggi tra le tue altre sessioni di Claude Code

7> Consenti a Claude di elencare e inviare messaggi alle tue altre sessioni di Claude Code su questa macchina, e raggiungi le tue sessioni su altre macchine o sul web.

9<Note>

10 La messaggistica tra sessioni richiede Claude Code v2.1.224 o successivo su macOS e Linux, incluso Linux all'interno di WSL 2. Su Windows nativo, richiede Claude Code v2.1.234 o successivo. Quando una sessione soddisfa i requisiti, la messaggistica è attiva senza nulla da abilitare. Vedi [Disponibilità](#availability) per i requisiti del provider e come confermare che una sessione lo supporta.

11</Note>

13La messaggistica tra sessioni consente a Claude di consegnare un messaggio da una delle tue sessioni di Claude Code a un'altra. Quando una modifica in una sessione interrompe ciò su cui un'altra sta lavorando, Claude può avvertire quella sessione prima che tu te ne accorga. Quando una sessione risolve una domanda su cui un'altra è bloccata, Claude può inviare la risposta attraverso.

15Un messaggio è un pezzo di testo che un Claude scrive a un altro, mai la cronologia della conversazione del mittente o i file. Per spostare un'intera conversazione o il suo contesto, [riprendi la sessione](/docs/it/sessions#resume-a-session) invece.

17Claude utilizza due strumenti per questo: `ListAgents` per scoprire quali agenti può raggiungere, e `SendMessage` per consegnare un messaggio a uno di essi per nome. Con lo stesso strumento `SendMessage`, Claude può anche inviare messaggi a [subagenti](/docs/it/sub-agents#resume-subagents) e ai compagni di [team di agenti](/docs/it/agent-teams) all'interno di una singola sessione o team. Questa pagina copre i messaggi tra le tue sessioni indipendenti.

19<h2 id="when-to-use-cross-session-messaging">

20 Quando utilizzare la messaggistica tra sessioni

21</h2>

23Utilizza la messaggistica quando una delle tue sessioni ha qualcosa che un'altra sessione ha bisogno a metà compito. Claude può inviare un messaggio da solo quando vede la necessità, ad esempio dopo aver apportato una modifica che influisce sul lavoro che un'altra sessione sta svolgendo, oppure puoi chiedergli di inviarne uno. I casi comuni sono:

25* **Consegna un risultato**: quando una sessione scopre un cambiamento che interrompe il funzionamento o prende una decisione, Claude lo riassume per la sessione che lavora sull'area interessata, invece di doverlo rispiegare lì.

26* **Coordina worktree paralleli**: quando le sessioni lavorano lo stesso repository in [worktree](/docs/it/worktrees) separati, Claude può dire alle altre sessioni cosa è stato implementato.

27* **Ottieni lo stato dal lavoro a lunga esecuzione**: fai in modo che una migrazione o un'esecuzione di test riferisca alla sessione che stai osservando, oppure chiedilo tu stesso da lì. Se quella sessione è su questa macchina, Claude può anche [chiederle un avviso quando successivamente diventa inattiva o esce](#get-a-notice-when-another-session-goes-idle).

28* **Messaggi tra macchine**: raggiungi una delle tue sessioni su un'altra macchina o sul web.

30Utilizza la messaggistica tra sessioni indipendenti che avvii e dirigi tu stesso. Claude Code ha una funzione dedicata per ognuno degli altri modi di eseguire o raggiungere più sessioni, quindi utilizza quella costruita per quello che stai facendo:

32* Per continuare una conversazione in un altro terminale, o condividere il suo contesto con una nuova sessione, [riprendi la sessione](/docs/it/sessions#resume-a-session)

33* Per un team coordinato di sessioni che Claude genera e supervisiona, utilizza [team di agenti](/docs/it/agent-teams)

34* Per osservare e dirigere molte sessioni da un unico posto, utilizza [agent view](/docs/it/agent-view)

35* Per dirigere una sessione tu stesso dal tuo telefono o da un altro dispositivo, piuttosto che far inviare messaggi alle sessioni l'una all'altra, utilizza [Remote Control](/docs/it/remote-control)

36* Per spingere eventi esterni, come risultati CI o messaggi di chat, in una sessione, utilizza [channels](/docs/it/channels)

38<h2 id="message-another-session">

39 Invia un messaggio a un'altra sessione

40</h2>

42Quando una delle tue sessioni apprende qualcosa che un'altra sessione ha bisogno, come un risultato, uno stato o una decisione, Claude lo passa invece di farti copiare e incollare tra i terminali. Claude scopre il target con `ListAgents` e invia con `SendMessage`, quindi non chiami mai nessuno dei due strumenti tu stesso. Claude può decidere di inviare un messaggio senza essere chiesto, e puoi anche richiederne uno.

44Per richiederne uno tu stesso, dì a Claude cosa vuoi che l'altra sessione sappia o faccia. Questo esempio è un prompt che digiti, non un messaggio che Claude invia:

46```text wrap theme={null}

47Chiedi alla sessione in esecuzione nel mio altro terminale se la migrazione è terminata

48```

50Claude scrive il messaggio vero e proprio, quindi il tuo prompt può lasciare il contenuto a Claude. Questo prompt chiede un riassunto senza dettarne la formulazione, e quello che Claude invia varia:

52```text wrap theme={null}

53Spiega quello che abbiamo appena fatto alla sessione che lavora sull'API dei pagamenti

54```

56Per nominare il target tu stesso, menziona la sessione nel tuo prompt: digita `@` seguito dalle prime lettere del nome della sessione e scegli la sessione dal typeahead, nello stesso modo in cui [@-menzioni un subagente](/docs/it/sub-agents#invoke-subagents-explicitly). Richiede Claude Code v2.1.232 o successiva. Claude Code inserisce la menzione, come `@api-worker`, e dice a Claude quale sessione nomina, quindi Claude può inviare un messaggio a quella sessione senza elencare prima le tue sessioni. Questo prompt nomina il target con una menzione:

58```text wrap theme={null}

59Fai sapere a @api-worker che la migrazione dello schema è terminata

60```

62Il typeahead elenca le tue altre sessioni live su questa macchina. Due casi richiedono più delle prime lettere di un nome:

64* **Una sessione oltre questa macchina**: una sessione cloud o Remote Control appare nel typeahead solo dopo che Claude ha elencato o inviato messaggi alle tue sessioni oltre questa macchina, quindi chiedi a Claude di elencarle prima.

65* **Un nome con uno spazio o altri caratteri al di fuori di lettere, cifre, trattini e sottolineature**: digitalo tra virgolette doppie, come `@"release notes"`. Quando scegli la sessione dal typeahead, Claude Code inserisce le virgolette per te.

67Puoi anche digitare la menzione senza il picker. Quando più di una sessione live risponde al nome menzionato, Claude ti chiede quale intendi prima di inviare.

69Per come appare il messaggio che Claude scrive quando arriva, incluso un esempio di uno, vedi [come appare un messaggio](#what-a-message-looks-like).

71<h3 id="message-delivery">

72 Consegna del messaggio

73</h3>

75Il Claude ricevente legge il messaggio tra le chiamate di strumenti durante un turno attivo, quindi uno strumento in esecuzione non viene mai interrotto. Quando la sessione ricevente è inattiva, Claude Code avvia un nuovo turno con il messaggio.

77Un messaggio da un'altra sessione arriva come testo semplice. Se menziona un file o una [risorsa MCP](/docs/it/mcp#use-mcp-resources) con `@`, Claude vede la menzione come scritta e Claude Code non allega nulla, indipendentemente dal fatto che il messaggio avvii un nuovo turno o arrivi durante uno. Claude può comunque aprire un percorso menzionato sulla macchina ricevente con i suoi strumenti, soggetto alle autorizzazioni di quella sessione. Prima della v2.1.251, una menzione `@` in un messaggio che ha avviato un nuovo turno ha allegato il file o la risorsa MCP sul lato ricevente.

79Claude Code rifiuta un messaggio nei seguenti casi:

81* Il messaggio è [oltre il limite di dimensione](#limitations). Claude Code lo rifiuta nella sessione di invio, prima che parta.

82* Un rapido burst a una sessione su questa macchina ha raggiunto [quello che la posta in arrivo di quella sessione accetta](#limitations). Claude Code rifiuta ulteriori messaggi a quella sessione.

83* Il target di risposta su questa macchina non supera un controllo di sicurezza, come un target con collegamento simbolico o un endpoint che non è il processo previsto. [Rifiuto di inviare un messaggio tra sessioni](/docs/it/errors#refusing-to-send-a-cross-session-message) elenca questi controlli.

84* Claude indirizza il messaggio al nome della sessione stessa, come descritto in [Vedi quali sessioni Claude può raggiungere](#see-which-sessions-claude-can-reach).

86La sessione ricevente controlla ogni messaggio in arrivo rispetto ai suoi [controlli in entrata](#control-inbound-messages), e il controllo termina in uno di tre risultati:

88* **Consegnato**: Claude Code passa il messaggio al Claude ricevente.

89* **Trattenuto**: Claude Code mette da parte il messaggio non consegnato. Un messaggio trattenuto raggiunge Claude solo quando lo approvi o un cambio di modalità o impostazioni successivo lo consente.

90* **Rifiutato**: Claude Code elimina il messaggio senza consegnarlo.

92Una volta consegnato, il messaggio conta verso [l'utilizzo](/docs/it/costs) come un prompt che digiti, e il Claude ricevente può rispondere al mittente nello stesso modo, tranne nel [caso cross-machine unidirezionale](#message-sessions-on-other-machines).

94I confini delle autorizzazioni rimangono per sessione. Claude è istruito a non chiedere mai a un'altra sessione un'azione che è stata negata o bloccata nella sua stessa sessione, o che le sue stesse impostazioni di autorizzazione bloccherebbero, e a instradare quel lavoro di nuovo a te. Sul lato ricevente, i [prompt di autorizzazione e le regole della sessione ricevente stessa si applicano ancora](#how-a-session-treats-an-incoming-message) a qualsiasi cosa il messaggio chieda.

96<h3 id="get-a-notice-when-another-session-goes-idle">

97 Ricevi un avviso quando un'altra sessione diventa inattiva

98</h3>

100Claude può chiedere a una delle tue sessioni su questa macchina di inviare indietro un avviso quando quella sessione successivamente diventa inattiva o esce. Inattivo qui significa che la sessione ha terminato un turno senza nulla in coda. Utilizzalo quando stai aspettando un compito lungo in un'altra sessione e vuoi sapere quando è fatto invece di controllare. Richiede Claude Code v2.1.236 o successiva in entrambe le sessioni.

101

102<h4 id="ask-for-a-notice">

103 Chiedi un avviso

104</h4>

105

106Dì a Claude cosa stai aspettando. Questo prompt chiede un avviso dalla sessione di migrazione:

107

108```text wrap theme={null}

109Dimmi quando la sessione di migrazione finisce quello su cui sta lavorando

110```

111

112Claude si iscrive con l'input `notify_when_idle` dello strumento `SendMessage`, allegato a un messaggio che sta inviando comunque o da solo. Da solo, Claude Code si iscrive senza avviare un turno o spendere token nella sessione osservata, e invia l'avviso subito se quella sessione è già inattiva. Allegato a un messaggio, Claude Code consegna prima il messaggio e invia l'avviso dopo.

113

114<h4 id="what-each-session-shows">

115 Cosa mostra ogni sessione

116</h4>

117

118La sessione osservata mostra una riga che dice che un altro processo ha chiesto di essere avvertito quando la sessione è successivamente inattiva. La sessione che chiede mostra l'avviso come una riga che nomina la sessione osservata. La riga può includere l'ora in cui il turno di quella sessione è terminato e uno stato di una riga da quel turno. Se la sessione che chiede è inattiva, Claude Code avvia un nuovo turno con l'avviso.

119

120<h4 id="limits">

121 Limiti

122</h4>

123

124L'avviso è una tantum: Claude Code lo invia una volta dalla sessione osservata, e nessuna delle due sessioni esegue il polling dell'altra. Se nessun avviso arriva entro 12 ore, Claude Code elimina l'iscrizione e lo dice a Claude, quindi non continua ad aspettare.

125

126I [controlli in entrata](#control-inbound-messages) di ogni lato si applicano a un avviso come un messaggio:

127

128* **`refuse` su entrambi i lati**: nulla arriva. La sessione osservata elimina la richiesta senza registrarla o rispondere, quindi l'iscrizione scade senza risposta dopo 12 ore, e una sessione che chiede con `refuse` non si iscrive mai.

129* **`hold` su entrambi i lati**: l'avviso arriva con meno. La sessione osservata lascia fuori lo stato di una riga, e la sessione che chiede mostra l'avviso nella tua trascrizione senza consegnarlo a Claude.

130

131Solo il Claude nella tua conversazione principale può iscriversi, e solo alle tue sessioni su questa macchina. Quando un subagente o un collega del team di agenti imposta `notify_when_idle`, Claude Code non effettua alcuna iscrizione e glielo dice. Quando Claude chiede un avviso da qualsiasi altro agente, come un collega, un subagente o una sessione oltre questa macchina, Claude Code rifiuta l'intera chiamata, incluso qualsiasi messaggio allegato, e segnala il rifiuto a Claude in modo che possa rinviare il messaggio senza la richiesta.

132

133<h3 id="see-which-sessions-claude-can-reach">

134 Vedi quali sessioni Claude può raggiungere

135</h3>

136

137Claude trova il target di un messaggio da solo, quindi non hai bisogno di eseguire nulla prima di chiedergli di inviare. Per vedere tu stesso quali sessioni Claude può raggiungere, esegui il comando `/list-agents`. La prima riga, quando presente, è il nome della sessione stessa, quello che le tue altre sessioni usano per inviarle messaggi. Le righe sottostanti sono le sessioni che Claude può raggiungere:

138

139* **Subagenti**: agenti in esecuzione all'interno della sessione corrente.

140* **Colleghi**: i colleghi del [team di agenti](/docs/it/agent-teams) della sessione stessa. Prima della v2.1.239, i colleghi non apparivano nell'elenco, anche se Claude poteva già inviar loro messaggi per nome.

141* **Le tue altre sessioni locali**: sessioni Claude Code in esecuzione sulla stessa macchina, incluse [sessioni in background](/docs/it/agent-view). Una sessione appare solo quando associa un [socket della posta in arrivo](#the-sessions-inbox-socket).

142* **Le tue sessioni cloud**: le tue sessioni [Claude Code sul web](/docs/it/claude-code-on-the-web), mostrate mentre questa sessione è connessa a [Remote Control](/docs/it/remote-control). Claude Code le etichetta `cloud` nell'elenco.

143* **Le tue sessioni Remote Control su altre macchine**: mostrate mentre questa sessione è connessa a [Remote Control](/docs/it/remote-control), ed etichettate `Remote Control`. Claude Code mostra `offline` come lo stato di una sessione la cui connessione Remote Control è caduta.

144

145Questa sessione non è una delle righe. Se Claude indirizza un messaggio al nome della sessione stessa, Claude Code lo rifiuta e dice a Claude che il target è la sessione corrente. Prima della v2.1.239, l'elenco non mostrava il nome di questa sessione, e Claude Code segnalava un messaggio inviato a essa come un agente che non poteva trovare.

146

147Mentre questa sessione è connessa a [Remote Control](/docs/it/remote-control), Claude Code trattiene alcuni dettagli delle tue sessioni locali dall'output `/list-agents`, senza cambiare quello che Claude stesso vede quando cerca una sessione a cui inviare messaggi:

148

149* **Directory di lavoro**: lascia fuori la directory di lavoro di ogni sessione locale.

150* **Nomi delle sessioni**: lascia fuori qualsiasi nome di sessione che non può attribuire a una persona, quindi una riga rimasta senza nome legge `(unnamed session)`.

151* **La prima riga**: lascia fuori la riga con il nome della sessione stessa a meno che tu non abbia digitato quel nome a questo terminale, con `--name` o con `/rename` e il nome, da quando hai avviato o ripreso l'ultima volta la sessione.

152

153Quando l'output elenca qualcosa, termina con una nota che dice che i dettagli sono stati trattenuti. Eseguire `/rename` seguito da un nome inutilizzato al terminale di una sessione propria dà a quella sessione un nome che appare nell'output.

154

155Claude Code legge i tuoi elenchi di sessioni cloud e Remote Control dal più recente al più vecchio e si ferma dopo un numero limitato di pagine per ognuno. Se il tuo account ha più di quelle sessioni di quante si adattino, Claude Code non elenca le più vecchie, e Claude non può inviar loro messaggi per nome. Quando ciò accade, Claude Code lo dice nell'elenco, e Claude vede la stessa nota quando invia un messaggio.

156

157Claude indirizza una sessione oltre questa macchina per nome, nello stesso modo di una sessione locale. Vedi [Invia messaggi a sessioni su altre macchine](#message-sessions-on-other-machines) per come quei messaggi viaggiano.

158

159Una sessione risponde al nome che imposti con il comando [`/rename`](/docs/it/commands) o il flag [`--name`](/docs/it/cli-reference#cli-flags). Quando non ne imposti uno, Claude Code nomina la sessione stessa. Per una sessione interattiva, questo è il nome mostrato negli [elenchi delle sessioni in esecuzione](/docs/it/sessions#name-your-sessions).

160

161Quando rinomini una sessione, Claude Code aggiorna anche il record condiviso che le tue altre sessioni usano per cercare il nome della sessione. Se non può aggiornare quel record, ti avverte nell'output `/rename` che altre sessioni potrebbero ancora mostrare il nome vecchio. Esegui la sessione con [`--debug`](/docs/it/cli-reference#cli-flags), e Claude Code registra la causa dell'aggiornamento fallito.

162

163Quando rinomini una sessione, o avvii o riprendi una sessione interattiva, con un nome che un'altra sessione live su questa macchina già usa, Claude Code lascia il nome con la sessione che lo ha già e [rinomina il tuo a una variante](/docs/it/sessions#name-your-sessions). Le sessioni possono comunque condividere un nome, ad esempio quando una di esse esegue una versione precedente di Claude Code o il nome condiviso è uno che Claude Code ha generato. A meno che questa sessione non sia connessa a Remote Control, Claude Code mostra la directory di lavoro di ogni sessione locale nell'output `/list-agents`, quindi puoi distinguere le sessioni con lo stesso nome quando vengono eseguite in directory diverse. Claude indirizza il messaggio in uno di due modi, a seconda di quante sessioni live rispondono al nome:

164

165* **Una sessione risponde al nome**: Claude Code consegna il messaggio solo sul nome.

166* **Diverse sessioni condividono il nome, o Claude Code non potrebbe controllare ovunque vengono eseguite le tue sessioni**: Claude aggiunge un breve identificatore a ogni riga del suo elenco e utilizza l'identificatore nell'indirizzo.

167

168<h3 id="message-sessions-on-other-machines">

169 Invia messaggi a sessioni su altre macchine

170</h3>

171

172Come un messaggio viaggia, e se passa attraverso i server Anthropic, dipende da dove viene eseguita la sessione target:

173

174| Dove viene eseguita l'altra sessione | Come il messaggio viaggia |

175| :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |

176| Su questa macchina | Su un socket per sessione su macOS e Linux, o una named pipe per sessione su Windows nativo, mai attraverso i server Anthropic |

177| Su un'altra delle tue macchine | Attraverso i server Anthropic, arrivando sulla connessione [Remote Control](/docs/it/remote-control) di quella macchina |

178| Su [Claude Code sul web](/docs/it/claude-code-on-the-web) | Attraverso i server Anthropic, direttamente alla sessione cloud |

179

180Avviare una conversazione con una sessione su un'altra delle tue macchine richiede Claude Code v2.1.225 o successiva e un target che [appare nell'elenco](#see-which-sessions-claude-can-reach). Prima della v2.1.225, Claude poteva solo rispondere a un messaggio che arrivava da uno.

181

182Puoi inviare un messaggio a una sessione mostrata come `offline` nell'[elenco](#see-which-sessions-claude-can-reach), una la cui connessione Remote Control è caduta. L'invio va a buon fine, ma il messaggio arriva solo dopo che la macchina di quella sessione si riconnette. Claude viene informato di ciò quando invia.

183

184La consegna sulla stessa macchina funziona ovunque la funzione sia abilitata. Ogni sessione si registra in file su disco. Quando Claude elenca o invia messaggi alle tue sessioni locali, Claude Code legge quei file per trovare le sessioni, quindi due sessioni possono raggiungersi solo quando possono vedere gli stessi file.

185

186Un contenitore ha il suo filesystem, quindi una sessione all'interno e una sessione sull'host non possono raggiungersi. Due sessioni all'interno dello stesso contenitore possono comunque inviarsi messaggi, incluso su un [runner self-hosted](/docs/it/self-hosted-environments). Una sessione all'interno di WSL 2 e una sessione Windows nativa sullo stesso computer non possono raggiungersi neanche, perché si registrano in directory home diverse e ascoltano su tipi di socket diversi.

187

188Mentre questa sessione è connessa a Remote Control, quando invii un messaggio a una sessione su un'altra delle tue macchine, Claude Code mostra il messaggio nella conversazione di quella sessione sotto il nome Remote Control di questa sessione. Il Claude su quella macchina può rispondere a quel nome. Ad esempio, quando questa sessione è connessa a Remote Control come `laptop-graceful-unicorn` e invii un messaggio al tuo desktop, vedi il messaggio nella sessione desktop sotto `laptop-graceful-unicorn`.

189

190Se questa sessione non è connessa a Remote Control quando Claude invia a una sessione oltre questa macchina, il messaggio comunque va a buon fine, ma senza un [indirizzo di risposta](#what-a-message-looks-like), quindi il Claude ricevente non può rispondere. Claude viene informato di ciò quando invia.

191

192Per richiedere la tua approvazione prima che qualsiasi messaggio vada oltre questa macchina, imposta [`isolatePeerMachines`](#require-approval-for-cross-machine-messages).

193

194<h2 id="how-a-session-treats-an-incoming-message">

195 Come una sessione tratta un messaggio in arrivo

196</h2>

197

198Quando la sessione A invia un messaggio alla sessione B, Claude Code dice al Claude di B che il messaggio è venuto da un'altra sessione, non da te, e limita quello che il messaggio può fare:

199

200* **Non può approvare nulla**: un messaggio da un'altra sessione non conta mai come il tuo consenso, quindi non può rispondere a un prompt di autorizzazione in sospeso per tuo conto.

201* **Non può cambiare la configurazione**: Claude Code istruisce il Claude ricevente a non cambiare mai le impostazioni di autorizzazione, `CLAUDE.md` o altre configurazioni perché un'altra sessione lo ha chiesto.

202* **I comandi non vengono eseguiti**: un comando nel testo del messaggio, come `/compact`, arriva come testo semplice. Claude Code non lo esegue mai.

203* **I prompt di autorizzazione si attivano comunque**: se agire sul messaggio richiede un'autorizzazione che la sessione ricevente non ha, vedi lo stesso prompt che vedresti per qualsiasi altro lavoro.

204

205<h3 id="what-a-message-looks-like">

206 Come appare un messaggio

207</h3>

208

209Quando un messaggio arriva, Claude Code lo mostra nella conversazione come un'anteprima di una riga attenuata, e la riga di anteprima rimane nella conversazione dopo. L'anteprima porta il nome del mittente e la prima riga del messaggio, tagliata con `…` quando è lunga, come `› Message from @api-worker: Schema migration finished (ctrl+o to expand)`. Prima della v2.1.247, Claude Code mostrava il messaggio in arrivo per intero invece di un'anteprima.

210

211Uno di questi mostra il testo completo:

212

213* Premi `Ctrl+O` per aprire il [visualizzatore di trascrizioni](/docs/it/interactive-mode#transcript-viewer) e leggi il testo completo sotto il nome della sessione del mittente.

214* In una sessione avviata con [`--verbose`](/docs/it/cli-reference#cli-flags), Claude Code mostra il testo completo invece dell'anteprima.

215

216L'anteprima accorcia solo quello che vedi. Che tu lo espanda o no, Claude legge il messaggio completo.

217

218Claude riceve il messaggio con il nome del mittente e un indirizzo di risposta, tranne per un [messaggio cross-machine unidirezionale](#message-sessions-on-other-machines), che non porta alcun indirizzo di risposta. Oltre al nome e all'indirizzo di risposta, il Claude ricevente ottiene il testo del messaggio, mai la cronologia della conversazione o i file del mittente. [Consegna del messaggio](#message-delivery) copre le menzioni `@` nel testo.

219

220Un messaggio che un [subagente](/docs/it/sub-agents) ha scritto arriva sotto il nome della sessione di invio, con il subagente identificato nel testo del messaggio. Una risposta ad esso raggiunge la conversazione principale di quella sessione, non il subagente.

221

222Questo esempio è un messaggio che un Claude ha scritto a un altro, come il suo testo completo legge quando lo espandi:

223

224```text wrap theme={null}

225Schema migration finished

226The new column is tenant_id, and rebasing on main is safe now.

227```

228

229<h3 id="control-inbound-messages">

230 Controlla i messaggi in entrata

231</h3>

232

233Imposta [`crossSessionInbound`](/docs/it/settings-reference#crosssessioninbound) per scegliere cosa una sessione fa con i messaggi in arrivo dalle tue altre sessioni:

234

235| Valore | Comportamento |

236| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

237| `accept` | Claude Code consegna ogni messaggio a Claude |

238| `hold` | Claude Code mostra un avviso per ogni messaggio e non lo consegna. Se un `accept` successivamente si applica, secondo le [regole di precedenza](/docs/it/settings-reference#crosssessioninbound), Claude Code rilascia i messaggi trattenuti |

239| `refuse` | Claude Code elimina ogni messaggio senza consegnarlo |

240

241Oltre a modificare un file di impostazioni, puoi selezionare il valore nella riga `/config` **Messages from your other sessions**. Claude Code scrive il valore che selezioni nelle tue impostazioni utente. La riga richiede Claude Code v2.1.232 o successiva e non appare mentre le impostazioni gestite o il flag `--settings` imposta la chiave, poiché un valore di impostazioni utente non si applicherebbe allora. Claude Code rifiuta la scorciatoia `/config crossSessionInbound=value` per questa chiave.

242

243Per vedere quale valore si applica, segui le regole di precedenza `crossSessionInbound` nel [riferimento delle impostazioni](/docs/it/settings-reference#crosssessioninbound). Quando nessun valore si applica, Claude Code decide per messaggio dalle modalità di autorizzazione delle due sessioni. Raggruppa le sessioni che [bypassano i prompt di autorizzazione](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode) in una classe, e ogni altra sessione nell'altra. La modalità Plan conta come bypassare nelle sessioni con autorizzazioni di bypass disponibili, e [auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), `acceptEdits` e `dontAsk` contano come prompt:

244

245* **La sessione ricevente richiede autorizzazioni**: Claude Code consegna ogni messaggio. Trattiene uno per la tua approvazione solo quando la sessione di invio si identifica come bypassando i prompt di autorizzazione.

246* **La sessione ricevente bypassa i prompt di autorizzazione**: Claude Code trattiene ogni messaggio per la tua approvazione. Consegna uno solo quando la sessione di invio si identifica come bypassando anche.

247

248Quando il default trattiene un messaggio, Claude Code apre una finestra di dialogo di approvazione nella sessione ricevente. La finestra di dialogo mostra il mittente e un'anteprima:

249

250* **Approve** consegna quel messaggio a Claude.

251* **Deny**, o chiudere la finestra di dialogo, lo elimina.

252* Quando la finestra di dialogo rimane senza risposta oltre la scadenza [`dialogExpiry`](/docs/it/settings-reference#dialogexpiry), Claude Code la chiude e elimina il messaggio. La scadenza predefinita è cinque minuti.

253* Mentre nessun terminale è collegato a una [sessione in background](/docs/it/agent-view), Claude Code lascia la finestra di dialogo aperta oltre la scadenza. Dopo che colleghi, se la finestra di dialogo rimane senza risposta per un intero periodo di scadenza, Claude Code la chiude e elimina il messaggio.

254* Se la classe di modalità di autorizzazione di questa sessione cambia mentre i messaggi sono trattenuti, Claude Code riapplica le regole in entrata, consegna i messaggi che ora accetta, e mostra un avviso.

255* Se un cambio di impostazioni fa applicare `refuse` mentre i messaggi sono trattenuti, Claude Code elimina ogni messaggio trattenuto e segnala un rifiuto a ogni mittente che può raggiungere.

256

257Quando il mittente è una sessione interattiva sulla stessa macchina, Claude Code mostra un avviso lì quando il ricevente trattiene il messaggio, e un follow-up quando il ricevente successivamente consegna, nega o lo fa scadere. Se il ricevente lo rifiuta, Claude Code mostra un avviso lì che il ricevente non sta accettando messaggi tra sessioni e dice al Claude del mittente di non aspettare o rinviare.

258

259Claude Code trattiene al massimo 100 messaggi, separatamente dalla coda di consegna, e oltre quello elimina i più vecchi.

260

261<h3 id="non-interactive-sessions">

262 Sessioni non interattive

263</h3>

264

265Claude Code associa un socket della posta in arrivo per una sessione [`claude -p`](/docs/it/headless) come una interattiva, quindi un worker `-p` a lunga esecuzione può ricevere messaggi e appare nell'elenco. Quando avvii una sessione in [modalità bare](/docs/it/headless#start-faster-with-bare-mode), Claude Code non associa il socket, quindi quella sessione non può ricevere messaggi e non appare nell'elenco degli agenti.

266

267Una sessione `-p` non può mostrare la finestra di dialogo di approvazione. Quando il [default in entrata](#control-inbound-messages) trattiene un messaggio lì, Claude Code lo mantiene per la stessa scadenza [`dialogExpiry`](/docs/it/settings-reference#dialogexpiry) che la finestra di dialogo usa, cinque minuti per impostazione predefinita:

268

269* **Prima della scadenza**: se una modalità o un cambio di impostazioni consente il messaggio, Claude Code lo consegna.

270* **Oltre la scadenza**: Claude Code elimina il messaggio e lo segnala come scaduto a un mittente che può raggiungere.

271

272Imposta `dialogExpiry` su `"never"` per mantenere i messaggi trattenuti dal default fino alla fine della sessione. Un messaggio trattenuto da un'impostazione `hold` esplicita non scade; Claude Code lo consegna solo quando un `accept` successivamente si applica.

273

274Quando la sessione termina con messaggi ancora trattenuti, Claude Code li segnala come scaduti a ogni mittente che può raggiungere. Prima della v2.1.225, nessuna scadenza si applicava in una sessione `-p`: un messaggio trattenuto rimaneva trattenuto a meno che un cambio di modalità di autorizzazione durante l'esecuzione lo consegnasse, e una sessione che terminava con messaggi trattenuti non segnalava nulla ai loro mittenti.

275

276Per far sì che un worker `-p` accetti messaggi incustodito, avvialo con `crossSessionInbound` impostato su `accept` nel suo valore `--settings`. Un `accept` nelle tue impostazioni utente funziona anche ma si applica a ogni sessione che esegui.

277

278<h3 id="the-sessions-inbox-socket">

279 Il socket della posta in arrivo della sessione

280</h3>

281

282Leggi questa sezione quando una sessione che ti aspetti non è nell'elenco degli agenti, quando vuoi che uno script o un hook pubblichi in una sessione, o quando un comando in sandbox non può raggiungere il socket.

283

284Claude Code associa un socket della posta in arrivo per ogni sessione con la messaggistica tra sessioni abilitata, dove altre sessioni sulla macchina consegnano messaggi. Il socket è un socket di dominio Unix su macOS e Linux, incluso Linux all'interno di WSL 2, e una named pipe su Windows nativo. Per quali tipi di sessione associano uno, vedi [Sessioni non interattive](#non-interactive-sessions).

285

286Puoi trovare il percorso del socket in due posti:

287

288* `/status` lo mostra nella riga `Peer address`. Il percorso è prefissato con `uds:`.

289* Claude Code lo esporta a [hooks](/docs/it/hooks) e comandi Bash come la variabile di ambiente [`CLAUDE_CODE_MESSAGING_SOCKET`](/docs/it/env-vars#variables):

290 * In una sessione che inizia con la messaggistica attiva, Claude Code esporta la variabile prima che qualsiasi hook venga eseguito, incluso `SessionStart`.

291 * Ogni sessione esporta il suo socket, mai uno ereditato da una sessione genitore.

292

293Su macOS e Linux, Claude Code limita il socket al tuo utente del sistema operativo. Su Windows nativo, richiede invece a ogni connessione di autenticarsi prima con una chiave che solo il tuo utente del sistema operativo può leggere. In entrambi i casi, su una macchina condivisa le sessioni di un altro utente non possono consegnare ad esso.

294

295Su macOS e Linux, Claude Code rifiuta anche di creare il socket in una directory che non può accettare, ad esempio una di proprietà di un altro utente, e utilizza invece una directory privata per utente, `/tmp/cc-socks-<uid>`. Quando non può accettare alcuna directory, la sessione viene eseguita senza una posta in arrivo: Claude Code mostra un avviso, `/status` mostra `unavailable` e il motivo nella sua riga `Peer address`, e il log [`--debug`](/docs/it/cli-reference#cli-flags) registra il rifiuto completo.

296

297Insieme al percorso del socket, Claude Code esporta un token per sessione come [`CLAUDE_CODE_MESSAGING_TOKEN`](/docs/it/env-vars#variables). Uno script che pubblica nel socket della sua stessa sessione può inviare `{"type":"auth","token":"<token>"}` come la prima riga della sua connessione, dove `<token>` è il valore di `CLAUDE_CODE_MESSAGING_TOKEN`. Se Claude Code richiede la riga dipende dalla piattaforma:

298

299* **macOS e Linux, incluso WSL 2**: la riga è facoltativa. Claude Code accetta una connessione con o senza di essa.

300* **Windows nativo**: la riga è obbligatoria. Claude Code chiude qualsiasi connessione la cui prima riga non è una riga di autenticazione valida e non consegna nulla da quella connessione.

301

302Apri la connessione solo quando il messaggio che stai pubblicando è pronto. Claude Code chiude una connessione che non ha inviato una riga completa entro 30 secondi, quindi cattura prima l'output di un comando lento e poi apri la connessione per inviarlo.

303

304I [messaggi propri-figli](#own-child-messages) sottostanti dicono quando Claude Code consulta il token e come tratta un messaggio che non può verificare.

305

306<span id="own-child-messages" />Claude Code esegue i messaggi in arrivo sul socket attraverso gli stessi [controlli in entrata](#control-inbound-messages) di qualsiasi altro messaggio peer, con un'eccezione e un prerequisito:

307

308* **Messaggi propri-figli**: quando nessun valore `crossSessionInbound` si applica, Claude Code consegna un messaggio che verifica è venuto dai processi figli della sessione stessa, come un hook o un comando Bash che pubblica di nuovo nel socket della posta in arrivo della sua stessa sessione.

309 * Su Linux, incluso all'interno di WSL 2, Claude Code può verificare per evidenza di processo anche per un figlio che è già uscito. Su macOS può verificare in quel modo solo mentre il processo di pubblicazione è ancora in esecuzione, e in un contenitore dove Claude Code viene eseguito come ID processo 1 non ha alcuna evidenza di processo. Su Windows nativo non ne ha nemmeno.

310 * Su macOS dopo che il processo di pubblicazione è uscito e in contenitori dove Claude Code viene eseguito come ID processo 1, quella evidenza di processo manca, e Claude Code verifica invece un figlio che ha inviato il [`CLAUDE_CODE_MESSAGING_TOKEN`](/docs/it/env-vars#variables) esportato della sessione nella riga di autenticazione che ha aperto la sua connessione. Su Windows nativo, quel token è l'unico modo in cui Claude Code verifica un messaggio proprio-figlio.

311 * Quando Claude Code non può verificare in nessun modo, tratta il messaggio come qualsiasi altro che non asserisce alcuna classe di autorizzazione, quindi una sessione che bypassa i prompt di autorizzazione lo trattiene per la tua approvazione.

312* **Sessioni in sandbox**: controlla se un comando Bash può raggiungere il socket dall'interno della [sandbox](/docs/it/sandboxing) con le impostazioni del socket Unix della sandbox, [`sandbox.network.allowAllUnixSockets` e `sandbox.network.allowUnixSockets`](/docs/it/settings-reference#sandbox-settings).

313

314<h2 id="restrict-cross-session-messaging">

315 Limitare la messaggistica tra sessioni

316</h2>

317

318Oltre alle impostazioni predefinite per messaggio, è possibile limitare la messaggistica in due modi. Richiedere l'approvazione prima che qualsiasi messaggio lasci la macchina, oppure disattivare la messaggistica per una sessione o un'organizzazione.

319

320<h3 id="require-approval-for-cross-machine-messages">

321 Richiedere approvazione per i messaggi tra macchine

322</h3>

323

324Impostare [`isolatePeerMachines`](/docs/it/settings-reference#isolatepeermachines) su `true` per richiedere l'approvazione esplicita prima che qualsiasi `SendMessage` raggiunga una sessione al di là di questa macchina:

325

326```json theme={null}

327{

328 "isolatePeerMachines": true

329}

330```

331

332Con questa impostazione, Claude Code richiede l'approvazione prima che il messaggio di Claude a una sessione al di là di questa macchina venga inviato, anche in modalità `bypassPermissions`, che ignora i normali prompt di autorizzazione. Un valore `true` da qualsiasi ambito di impostazioni si applica, quindi un file di progetto archiviato può attivare il requisito ma non disattivarlo. Claude Code non richiede l'approvazione per i messaggi tra sessioni sulla stessa macchina.

333

334<h3 id="turn-off-cross-session-messaging">

335 Disattivare la messaggistica tra sessioni

336</h3>

337

338La ricezione e l'invio sono controlli separati, quindi disattivare la direzione di cui hai bisogno, o entrambe. Utilizzare `crossSessionInbound` per i messaggi in arrivo e le regole di autorizzazione per ciò che Claude qui può inviare o elencare:

339

340* **Interrompere la ricezione**: impostare `crossSessionInbound` su `refuse`, e Claude Code elimina i messaggi peer in arrivo senza consegnarli. Dalle impostazioni di progetto o locali, `refuse` si applica su ogni altra fonte, e dalle impostazioni utente si applica a meno che le impostazioni gestite o il flag `--settings` impostino un valore.

341* **Interrompere l'invio e l'elenco**: aggiungere [regole di negazione delle autorizzazioni](/docs/it/permissions#tool-specific-permission-rules) che denominano `SendMessage` e `ListAgents`. Entrambi accettano il nome dello strumento senza specificatore.

342

343Gli amministratori possono disattivare entrambi i lati per un'organizzazione nelle [impostazioni gestite](/docs/it/managed-settings), combinando le regole di negazione con `refuse`:

344

345```json theme={null}

346{

347 "permissions": {

348 "deny": ["SendMessage", "ListAgents"]

349 },

350 "crossSessionInbound": "refuse"

351}

352```

353

354Con questa impostazione in vigore, Claude Code associa comunque il socket della posta in arrivo di ogni sessione, ma elimina ogni messaggio che arriva su di esso senza consegnare nulla a Claude. Negare `SendMessage` rimuove anche la messaggistica ai subagent e ai compagni di squadra dell'agente, poiché lo stesso strumento serve entrambi. Una sessione che rifiuta non mostra alcun cambiamento visibile, nel suo `/status` o negli elenchi di altre sessioni sulla stessa macchina, quindi per confermarlo, controllare i file di impostazioni che si applicano a quella sessione piuttosto che il suo stato.

355

356<h2 id="availability">

357 Disponibilità

358</h2>

359

360La messaggistica tra sessioni richiede Claude Code v2.1.224 o successiva su macOS, Linux e WSL 2, e v2.1.234 o successiva su Windows nativo. La disponibilità, e quali sessioni Claude può inviare messaggi, dipendono anche dal tuo sistema operativo, provider e configurazione:

361

362* **Sistema operativo**: disponibile su macOS, Windows e Linux, incluso Linux all'interno di WSL 2.

363

364* **Sessioni su questa macchina**: disponibile su ogni provider, inclusi Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud e Microsoft Foundry, e in sessioni che vengono eseguite con [fetching dei flag di funzionalità](/docs/it/env-vars#features-that-need-feature-flag-fetching) disattivato. Su quei provider, e con il fetching dei flag disattivato, la messaggistica sulla stessa macchina richiede Claude Code v2.1.248 o successiva. Claude Code consegna questi messaggi su un [socket per sessione sulla tua macchina](#the-sessions-inbox-socket), mai attraverso i server Anthropic.

365

366 Per impedire a una sessione di riceverli, imposta [`crossSessionInbound`](#turn-off-cross-session-messaging) su `refuse`.

367

368* **Sessioni oltre questa macchina**: Claude trova le tue sessioni [Claude Code sul web](/docs/it/claude-code-on-the-web) e le tue sessioni su altre macchine da una sessione che è connessa a Remote Control, che ha bisogno di un accesso claude.ai come autenticazione attiva di questa sessione e degli altri [requisiti di Remote Control](/docs/it/remote-control#requirements). Claude non può trovare quelle sessioni con una chiave API o su Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud e Microsoft Foundry.

369

370Per controllare una sessione, digita `/list-agents`, disponibile anche come `/peers`. Il risultato separa una sessione che non ha la funzione da una sessione dove qualcosa di più stretto ha bloccato un messaggio, come uno strumento `SendMessage` mancante o un invio rifiutato:

371

372* **`/list-agents` non è riconosciuto**: la sessione non ha messaggistica tra sessioni. Lavora attraverso i requisiti sopra, iniziando con `claude --version` per il requisito di versione.

373* **`/list-agents` funziona ma un invio non è arrivato**: la messaggistica è attiva, e qualcosa di più stretto si applica:

374 * **Regole di negazione**: una [regola di autorizzazione di negazione](#turn-off-cross-session-messaging) rimuove gli strumenti `SendMessage` e `ListAgents`.

375 * **Controlli in entrata**: i [controlli in entrata della sessione ricevente](#control-inbound-messages) possono trattenere o eliminare quello che invii.

376 * **Sessione cloud mancante**: una sessione cloud appare solo mentre questa sessione è connessa a [Remote Control](/docs/it/remote-control).

377 * **Sessione su un'altra macchina mancante**: una sessione su un'altra delle tue macchine appare solo quando viene eseguita con [Remote Control](/docs/it/remote-control) e questa sessione è connessa anche.

378 * **Sessione su un'altra macchina `offline`**: un messaggio a una sessione elencata come `offline` va a buon fine, ma [arriva solo dopo che la macchina di quella sessione si riconnette](#message-sessions-on-other-machines).

379 * **Sessione cloud o su un'altra macchina più vecchia mancante**: Claude Code [legge quegli elenchi di sessioni dal più recente al più vecchio e si ferma dopo un numero limitato di pagine](#see-which-sessions-claude-can-reach), quindi Claude non può inviare un messaggio a una sessione che è caduta oltre di loro per nome.

380 * **Avvio di una conversazione**: [Invia messaggi a sessioni su altre macchine](#message-sessions-on-other-machines) copre l'avvio di una conversazione con una sessione oltre questa macchina.

381

382In una sessione con messaggistica, `/status` mostra anche una riga `Peer address` con l'indirizzo della posta in arrivo della sessione stessa, o `unavailable` e il motivo quando Claude Code [non poteva impostare una posta in arrivo](#the-sessions-inbox-socket).

383

384<h2 id="limitations">

385 Limitazioni

386</h2>

387

388I limiti qui sono proprietà del canale di messaggistica stesso e si applicano ovunque la funzione viene eseguita. Per i gap di piattaforma e provider, vedi [Disponibilità](#availability) invece.

389

390* **Solo testo semplice**: Claude invia solo testo semplice tra sessioni. I messaggi del protocollo [team di agenti](/docs/it/agent-teams) strutturati rimangono all'interno di un team.

391* **La dimensione del messaggio sulla stessa macchina è limitata**: Claude Code rifiuta un messaggio a una sessione su questa macchina una volta che la sua forma serializzata supera circa un milione di caratteri. Il rifiuto [nomina le dimensioni esatte](/docs/it/errors#message-too-large-for-cross-session-delivery). Nulla raggiunge la sessione ricevente.

392* **I burst rapidi a una sessione vengono rifiutati al mittente**: una volta che un burst rapido di messaggi a una sessione su questa macchina raggiunge quello che la posta in arrivo di quella sessione accetta, Claude Code rifiuta ulteriori invii nella sessione di invio. Il [rifiuto nomina il burst](/docs/it/errors#too-many-messages-to-this-session-just-now) e dice a Claude di raggruppare il resto in un messaggio o aspettare. Prima della v2.1.236, Claude Code segnalava quegli invii come inviati mentre la sessione ricevente li eliminava.

393* **I loop di messaggi sono limitati**: nella sessione ricevente, Claude Code limita la velocità dei messaggi ripetuti per mittente, elimina i ripetuti identici che arrivano entro una breve finestra, e mette in coda al massimo 50 messaggi accettati per Claude da leggere. Un loop di messaggi tra due sessioni quindi si ferma da solo. Quando il limite di velocità, il controllo di ripetizione o il limite di coda elimina un messaggio da una sessione interattiva su questa macchina, Claude Code dice a quella sessione quale lo ha eliminato e dice al suo Claude di non rinviare subito.

394

395<h2 id="related-resources">

396 Risorse correlate

397</h2>

398

399* [Subagenti](/docs/it/sub-agents#resume-subagents) e [team di agenti](/docs/it/agent-teams#messages-between-agents): messaggistica all'interno di una singola sessione o team

400* [Agenti in background](/docs/it/agent-view): invia e monitora le sessioni parallele che potresti inviare messaggi

401* [Remote Control](/docs/it/remote-control): connetti questa sessione per raggiungere le tue sessioni su altre macchine

402* [Impostazioni](/docs/it/settings-reference#all-settings): `crossSessionInbound`, `isolatePeerMachines` e `dialogExpiry`

403* [Modalità di autorizzazione](/docs/it/permission-modes): le modalità dietro il default in entrata delle due classi

404* [Riferimento degli strumenti](/docs/it/tools-reference): le righe `ListAgents` e `SendMessage` nella tabella degli strumenti

405* [Esegui agenti in parallelo](/docs/it/agents): confronta i modi in cui Claude Code esegue più agenti

debug-your-config.md +1 −1

Details

122| Server MCP del progetto aggiunto ma non appare | Il prompt di approvazione una tantum è stato chiuso | I server con ambito di progetto richiedono approvazione. Esegui `/mcp` per vedere lo stato e approvare. |122| Server MCP del progetto aggiunto ma non appare | Il prompt di approvazione una tantum è stato chiuso | I server con ambito di progetto richiedono approvazione. Esegui `/mcp` per vedere lo stato e approvare. |

123| Il server MCP non riesce ad avviarsi da alcune directory | `command` o `args` utilizza un percorso di file relativo | Usa percorsi assoluti per gli script locali. Gli eseguibili sul tuo `PATH` come `npx` o `uvx` funzionano così come sono. |123| Il server MCP non riesce ad avviarsi da alcune directory | `command` o `args` utilizza un percorso di file relativo | Usa percorsi assoluti per gli script locali. Gli eseguibili sul tuo `PATH` come `npx` o `uvx` funzionano così come sono. |

124| Il server MCP si avvia senza le variabili di ambiente previste | La voce di configurazione del server non le imposta, e non si trovano nell'ambiente che Claude Code passa ai server stdio: il suo ambiente, meno le [variabili che rimuove dai sottoprocessi](/docs/it/monitoring-usage#administrator-configuration) | Imposta per-server `env` all'interno della voce `.mcp.json` del server, che non dipende dall'ambiente di lancio o dalla fiducia dell'area di lavoro. |124| Il server MCP si avvia senza le variabili di ambiente previste | La voce di configurazione del server non le imposta, e non si trovano nell'ambiente che Claude Code passa ai server stdio: il suo ambiente, meno le [variabili che rimuove dai sottoprocessi](/docs/it/monitoring-usage#administrator-configuration) | Imposta per-server `env` all'interno della voce `.mcp.json` del server, che non dipende dall'ambiente di lancio o dalla fiducia dell'area di lavoro. |

125| La regola di negazione `Bash(rm *)` non blocca `/bin/rm` o `find -delete` | Le regole di prefisso corrispondono alla stringa di comando letterale, non all'eseguibile sottostante | Aggiungi modelli espliciti per ogni variante, o usa un [PreToolUse hook](/docs/it/hooks-guide) o la [sandbox](/docs/it/sandboxing) per una garanzia difficile. |125| La regola di negazione `Bash(rm *)` non blocca `/bin/rm` o `find -delete` | Le regole Bash corrispondono alla stringa di comando letterale, non all'eseguibile sottostante; vedi [cosa una regola Bash non corrisponde](/docs/it/permissions#bash-rule-limits) | Usa un [PreToolUse hook](/docs/it/hooks-guide) o la [sandbox](/docs/it/sandboxing) per una garanzia difficile. |

126 126

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

128 Risorse correlate128 Risorse correlate

desktop.md +13 −8

Details

9L'app Claude Desktop ha tre schede: **Chat** per le conversazioni, **Cowork** per [Dispatch e lavoro agentico più lungo](https://claude.com/product/cowork), e **Code** per lo sviluppo software. Questa pagina è il riferimento per la scheda Code.9L'app Claude Desktop ha tre schede: **Chat** per le conversazioni, **Cowork** per [Dispatch e lavoro agentico più lungo](https://claude.com/product/cowork), e **Code** per lo sviluppo software. Questa pagina è il riferimento per la scheda Code.

10 10

11<CardGroup cols={3}>11<CardGroup cols={3}>

~~12 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">~~12 <Card title="Scarica per macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

~~13 Universal build for Intel and Apple Silicon~~13 Build universale per Intel e Apple Silicon

14 </Card>14 </Card>

15 15

~~16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">~~16 <Card title="Scarica per Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">

~~17 For x64 processors~~17 Per processori x64

18 </Card>18 </Card>

19 19

~~20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">~~20 <Card title="Ottieni Claude per Linux (beta)" icon="linux" href="/docs/it/desktop-linux">

~~21 apt or .deb for Ubuntu and Debian~~21 apt o .deb per Ubuntu e Debian

22 </Card>22 </Card>

23</CardGroup>23</CardGroup>

24 24

25For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/desktop-linux).25Per Windows ARM64, scarica l'[installer ARM64](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). Su Linux, installa con apt; vedi [Claude Desktop su Linux](/docs/it/desktop-linux).

26 26

27Dopo l'installazione, avvia Claude, accedi e fai clic sulla scheda **Code**. La prima volta che lo apri su Windows, hai bisogno di [Git for Windows](https://git-scm.com/downloads/win) installato; riavvia l'app dopo averlo installato. Per una procedura dettagliata della tua prima sessione, consulta la [guida introduttiva](/docs/it/desktop-quickstart).27Dopo l'installazione, avvia Claude, accedi e fai clic sulla scheda **Code**. La prima volta che lo apri su Windows, hai bisogno di [Git for Windows](https://git-scm.com/downloads/win) installato; riavvia l'app dopo averlo installato. Per una procedura dettagliata della tua prima sessione, consulta la [guida introduttiva](/docs/it/desktop-quickstart).

28 28

743 743

744Le sessioni cloud continuano in background anche se chiudi l'app. L'utilizzo conta verso i limiti del tuo [piano di abbonamento](/docs/it/costs) senza costi di calcolo separati.744Le sessioni cloud continuano in background anche se chiudi l'app. L'utilizzo conta verso i limiti del tuo [piano di abbonamento](/docs/it/costs) senza costi di calcolo separati.

745 745

746Puoi creare ambienti cloud personalizzati con diversi livelli di accesso alla rete e variabili di ambiente. Seleziona il menu a discesa dell'ambiente quando avvii una sessione cloud e scegli **Add cloud environment**. Vedi [Configure cloud environments](/docs/it/cloud-environments) per i dettagli sulla configurazione dell'accesso alla rete e delle variabili di ambiente.746Puoi creare ambienti cloud personalizzati con diversi livelli di accesso alla rete e variabili di ambiente. Quando avvii una sessione cloud, apri il menu a discesa dell'ambiente nella casella del prompt per gestirli:

747

748* **Add an environment**: seleziona **Add cloud environment**

749* **Edit or archive one of your own environments**: passa il mouse su di esso e fai clic sull'icona dell'ingranaggio

750

751Vedi [Configure cloud environments](/docs/it/cloud-environments) per i dettagli sulla configurazione dell'accesso alla rete e delle variabili di ambiente.

747 752

748<h3 id="ssh-sessions">753<h3 id="ssh-sessions">

749 SSH sessions754 SSH sessions

desktop-ios-simulator.md +176 −0 created

Details

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.

5# Testare app iOS nel simulatore

7> Claude Code Desktop apre la tua app nel riquadro iOS Simulator quando Claude la compila, esegue o la verifica, con un simulatore separato per ogni sessione.

9<Note>

10 Il riquadro iOS Simulator è in beta pubblica in Claude Code Desktop su macOS. È disponibile nei piani Pro, Max, Team ed Enterprise, tranne nelle organizzazioni Enterprise che hanno una configurazione HIPAA abilitata.

11</Note>

13Il riquadro iOS Simulator mostra la tua app in esecuzione nell'iOS Simulator di Apple accanto alla tua conversazione in Claude Code Desktop. Quando Claude compila, installa, avvia o verifica la tua app in un simulatore, il riquadro si apre automaticamente e trasmette lo schermo del dispositivo in diretta. Usalo per osservare Claude mentre esegue e testa la tua app, oppure per navigare tu stesso nell'app mentre Claude continua a lavorare.

15Il riquadro del simulatore controlla il simulatore direttamente, quindi non ha bisogno di [computer use](/docs/it/desktop#let-claude-use-your-computer) e non prende mai il controllo dello schermo o nasconde le altre finestre. Dalla CLI, Claude raggiunge l'iOS Simulator attraverso [computer use](/docs/it/computer-use#test-a-simulator-flow), che controlla il simulatore sullo schermo nello stesso modo in cui lo faresti con un mouse.

17<h2 id="requirements">

18 Requisiti

19</h2>

21Il riquadro del simulatore utilizza gli strumenti del simulatore di Apple, che l'app desktop non include. Prima di avviare una sessione, assicurati di avere:

23* Claude Desktop v1.24012.0 o successivo

24* Un Mac, poiché l'iOS Simulator di Apple funziona solo su macOS

25* [Xcode](https://developer.apple.com/xcode/) con la piattaforma iOS installata, che fornisce i dispositivi simulatore. Se Xcode non elenca ancora simulatori, vedi [Il riquadro del simulatore dice che non sono stati trovati simulatori](#the-simulator-pane-says-no-simulators-were-found)

26 * Usa Xcode 26.x. Il riquadro non funziona ancora con Xcode 27, che sostituisce l'app Simulator con Device Hub. Se `xcode-select` punta a Xcode 27 sul tuo Mac, vedi [Il riquadro del simulatore non funziona con Xcode 27](#the-simulator-pane-fails-with-xcode-27)

28<Note>

29 In questa pagina, "dispositivo" si riferisce a un iPhone o iPad simulato, uno degli stessi dispositivi simulatore che gestisci in Xcode in **Window → Devices and Simulators**, non a hardware fisico.

30</Note>

32Il riquadro del simulatore è disponibile solo nelle sessioni locali. Nelle sessioni [cloud](/docs/it/desktop#run-long-running-tasks-remotely) e [SSH](/docs/it/desktop#ssh-sessions), Claude viene eseguito su una macchina che non può raggiungere i simulatori sul tuo Mac.

34<h2 id="run-your-app-in-the-simulator">

35 Esegui la tua app nel simulatore

36</h2>

38Non hai bisogno di un comando o di un'impostazione per aprire il riquadro del simulatore. Claude lo apre quando esegue la tua app in un simulatore.

40<Steps>

41 <Step title="Apri il tuo progetto iOS">

42 In Claude Code Desktop, apri la scheda **Code** e avvia una sessione con la cartella del progetto della tua app come [cartella del progetto](/docs/it/desktop#start-a-session). Qualsiasi progetto che compila un'app per l'iOS Simulator funziona.

43 </Step>

45 <Step title="Chiedi a Claude di eseguire o testare l'app">

46 Esprimi l'attività intorno all'esecuzione o alla verifica dell'app. Ad esempio:

48 ```text theme={null}

49 Build the app and run it in the simulator to check the onboarding flow.

50 ```

51 </Step>

53 <Step title="Guarda l'app nel riquadro del simulatore">

54 Quando l'app viene avviata in un simulatore, il riquadro iOS Simulator si apre accanto alla conversazione. La prima volta che Claude utilizza un dispositivo, l'app desktop ti chiede di consentirlo; vedi [Concedi a Claude l'accesso a un dispositivo](#grant-claude-access-to-a-device). Claude installa l'app, la naviga, e legge lo schermo per verificare i propri cambiamenti mentre tu osservi.

55 </Step>

56</Steps>

58Il riquadro del simulatore si apre ogni volta che Claude avvia l'app in un simulatore, in qualsiasi momento della sessione. Quando la tua richiesta riguarda la visualizzazione dell'app, ad esempio "il nuovo schermo sembra giusto?", Claude avvia un simulatore prima di iniziare il lavoro. Dopo che Claude corregge un bug o cambia uno schermo, chiedigli di verificare il cambiamento: riavviare l'app riaprirà il riquadro se non è aperto.

60Il riquadro del simulatore mostra il dispositivo in cui l'app è effettivamente stata avviata. Per testare su un dispositivo specifico, nominalo nella tua richiesta, ad esempio "eseguilo sul simulatore iPhone SE", e Claude indirizza quel dispositivo quando compila e avvia.

62Un dispositivo che Claude avvia appare anche nell'app Simulator di Apple, e Claude può installare l'app su un dispositivo che hai già avviato.

64Puoi anche aprire il riquadro del simulatore tu stesso. Una volta che la sessione ha un simulatore collegato o ha modificato file Swift, il menu **Views** nella barra degli strumenti della sessione mostra una voce **iOS Simulator**. Se il riquadro non sta ancora mostrando un dispositivo, fai clic su **Attach simulator**, oppure scegli un dispositivo specifico dal menu dei dispositivi accanto ad esso; scegliere un dispositivo spento lo avvia. Se Xcode o i suoi simulatori mancano, il riquadro mostra invece i passaggi di configurazione e li spunta man mano che li completi.

66<h2 id="control-the-simulator-yourself">

67 Controlla il simulatore tu stesso

68</h2>

70Il riquadro del simulatore è interattivo, non solo un visualizzatore. Mentre Claude lavora, o tra i compiti, puoi:

72* Toccare e scorrere facendo clic e trascinando sullo schermo del dispositivo

73* Premere i pulsanti hardware con le stesse scorciatoie da tastiera dell'app Simulator di Apple: **Cmd+Shift+H** per Home, **Cmd+L** per bloccare, **Cmd+Up Arrow** e **Cmd+Down Arrow** per il volume

74* Ruotare il dispositivo di un quarto di giro in senso orario con il pulsante di rotazione o **Cmd+Right Arrow**

75* Cambiare quale dispositivo il riquadro mostra dal menu dei dispositivi, che elenca la versione del sistema operativo di ogni simulatore e se è avviato

76* Salvare uno screenshot con **Cmd+S** o una registrazione dello schermo con **Cmd+R**, utilizzando i pulsanti di acquisizione del riquadro o le scorciatoie da tastiera; i file vengono salvati sul tuo Desktop

77* Interrompere lo streaming di un dispositivo senza spegnerlo facendo clic su **Detach simulator**, che riporta il riquadro allo stato **Attach simulator**

79La riga sotto il nome del dispositivo regola il flusso video dal simulatore. Abbassa **Frame rate** o **Resolution** se il riquadro affatica il tuo Mac, cambia **Encoding** tra H.264 e JPEG, oppure seleziona **FPS** per visualizzare la frequenza dei fotogrammi che il riquadro sta ricevendo. Queste impostazioni cambiano il modo in cui il riquadro visualizza il dispositivo, non il modo in cui l'app viene eseguita.

81Tu e Claude controllate lo stesso dispositivo, quindi i tuoi tocchi cambiano lo stato dell'app che Claude vede. Per fare in modo che Claude verifichi uno schermo specifico, navigaci toccando, quindi chiedi. Mentre Claude controlla il dispositivo, il riquadro mostra un badge **Claude is using this device** sopra lo schermo; aspetta che il badge scompaia prima di toccare, in modo che il risultato rifletta l'app piuttosto che il tuo input.

83<h2 id="how-sessions-manage-devices">

84 Come le sessioni gestiscono i dispositivi

85</h2>

87Ogni dispositivo appartiene alla sessione che lo ha avviato, quindi le [sessioni parallele](/docs/it/desktop#work-in-parallel-with-sessions) non condividono un dispositivo: quello che vedi nel riquadro di una sessione riflette il lavoro di quella sessione, non di un'altra. Cambiare sessioni nella barra laterale cambia la visualizzazione del simulatore insieme alla conversazione, e tornare indietro riprende lo stesso dispositivo da dove era rimasto. Se Claude lavora con più di un dispositivo, ognuno apre il proprio riquadro, fino a 4 per sessione.

89Claude Code Desktop spegne i simulatori che ha avviato una volta che non sono più in uso: quando esci dall'app, quando archivi la sessione, o 10 minuti dopo aver scollegato un dispositivo dal suo riquadro. I dispositivi che avvii tu stesso, sia dal riquadro che dall'app Simulator di Apple, non vengono mai spenti automaticamente. Per spegnere il dispositivo collegato subito, usa il pulsante di spegnimento nel riquadro.

91<h2 id="grant-claude-access-to-a-device">

92 Concedi a Claude l'accesso a un dispositivo

93</h2>

95Claude chiede il tuo consenso prima di controllare un dispositivo, mentre compilare l'app o aprire un URL su di esso segue la modalità di autorizzazione della tua sessione. Tu o la tua organizzazione potete anche disattivare completamente l'accesso di Claude.

97<h3 id="allow-a-device-the-first-time">

98 Consenti un dispositivo la prima volta

99</h3>

100

101La prima volta che Claude utilizza un simulatore, l'app desktop ti chiede di consentirlo. Il consenso copre il controllo di quel dispositivo e l'acquisizione di screenshot, e lo dai una volta per dispositivo piuttosto che una volta per sessione. Gli screenshot di Claude del dispositivo vengono inviati ad Anthropic e conservati secondo le tue normali impostazioni di conservazione della conversazione, quindi non accedere ad account reali su un dispositivo che Claude utilizza.

102

103Dopo aver consentito un dispositivo, le azioni di Claude su di esso, come toccare, digitare, avviare l'app e acquisire screenshot, vengono eseguite senza ulteriori prompt. Hanno la stessa fiducia di quando fai clic nel riquadro, e toccano solo il dispositivo simulato, quindi il riquadro non ha bisogno delle autorizzazioni macOS Accessibility e Screen Recording che il computer use richiede.

104

105Se rifiuti, il dispositivo viene comunque avviato e il riquadro funziona ancora per i tuoi tocchi; solo l'accesso di Claude rimane disattivato. Per cambiare idea in seguito, fai clic su **Let Claude use it** nel riquadro.

106

107<h3 id="actions-that-follow-your-permission-mode">

108 Azioni che seguono la tua modalità di autorizzazione

109</h3>

110

111Due azioni seguono la [modalità di autorizzazione](/docs/it/permissions#permission-modes) della tua sessione invece del consenso una tantum:

112

113* Aprire un URL sul dispositivo, ad esempio per testare un deep link o caricare una pagina nel Safari del dispositivo, perché un URL può portare dati fuori dal dispositivo.

114* Compilare l'app, perché `xcodebuild` esegue gli script di compilazione del tuo progetto sul tuo Mac. Controllare una compilazione già in corso non genera un prompt.

115

116<h3 id="turn-off-simulator-access">

117 Disattiva l'accesso al simulatore

118</h3>

119

120Puoi disattivare l'accesso al simulatore di Claude nelle impostazioni dell'app desktop. Le organizzazioni hanno due modi per disattivarlo per tutti:

121

122* L'[impostazione gestita](/docs/it/desktop#managed-settings) `disableMobileSimulatorTools` blocca gli strumenti del simulatore di Claude. Il riquadro del simulatore rimane utilizzabile per i tuoi tocchi, e l'impostazione non può essere ignorata dall'interno dell'app.

123* La chiave della politica `requireCoworkFullVmSandbox`, che esegue gli strumenti di Claude all'interno di una macchina virtuale isolata invece che sul tuo Mac, disabilita il riquadro del simulatore e gli strumenti del simulatore di Claude interamente, quindi il riquadro non può collegare un dispositivo mentre è impostato.

124

125Claude ti avvisa quando uno di questi si applica.

126

127<h2 id="limitations">

128 Limitazioni

129</h2>

130

131Claude controlla solo dispositivi simulati e non può controllare un iPhone o iPad fisico. Per testare su uno, esegui l'app su di esso da Xcode tu stesso, quindi descrivi quello che vedi o allega uno screenshot alla conversazione affinché Claude possa lavorarci.

132

133<h2 id="troubleshooting">

134 Troubleshooting

135</h2>

136

137<h3 id="the-simulator-pane-doesn’t-open-when-claude-runs-the-app">

138 Il riquadro del simulatore non si apre quando Claude esegue l'app

139</h3>

140

141Claude potrebbe non aver riconosciuto che volevi eseguire o testare l'app, oppure gli strumenti del simulatore potrebbero mancare. Controlla quanto segue:

142

143* Dichiara l'obiettivo esplicitamente, ad esempio "esegui l'app nell'iOS Simulator e naviga attraverso il flusso di iscrizione".

144* Conferma che Xcode e i simulatori iOS siano installati e che la tua versione di Xcode soddisfi i [requisiti](#requirements).

145* Se la tua organizzazione gestisce Claude Code, gli [strumenti del simulatore potrebbero essere disabilitati dalla politica](#turn-off-simulator-access).

146* Se sei in un'organizzazione Enterprise che ha una configurazione HIPAA abilitata, il riquadro del simulatore non è disponibile per te.

147* Il riquadro del simulatore richiede Claude Desktop v1.24012.0 o successivo. Apri **Claude → Check for Updates**, quindi riavvia l'app.

148

149<h3 id="the-simulator-pane-says-no-simulators-were-found">

150 Il riquadro del simulatore dice che non sono stati trovati simulatori

151</h3>

152

153Se `xcode-select` punta a Xcode 27, il riquadro può segnalare che non sono stati trovati simulatori anche se i dispositivi esistono; vedi [Il riquadro del simulatore non funziona con Xcode 27](#the-simulator-pane-fails-with-xcode-27). Altrimenti, Xcode è installato ma non ha simulatori iOS da elencare. Il riquadro del simulatore mostra i passaggi di configurazione da seguire e li spunta man mano che ognuno si completa. Per installare il pezzo mancante manualmente, scarica il runtime del simulatore iOS dalle impostazioni di Xcode, oppure esegui `xcodebuild -downloadPlatform iOS`.

154

155<h3 id="the-simulator-pane-fails-with-xcode-27">

156 Il riquadro del simulatore non funziona con Xcode 27

157</h3>

158

159Il riquadro non funziona ancora con Xcode 27, che sostituisce l'app Simulator con Device Hub. Con Xcode 27 selezionato, il collegamento di un dispositivo non riesce, oppure il riquadro segnala che non sono stati trovati simulatori anche se i dispositivi esistono.

160

161Il riquadro utilizza qualunque Xcode `xcode-select` punti. Se Xcode 27 è la tua unica installazione, installa prima Xcode 26.x insieme ad esso. Quindi seleziona l'installazione 26.x dal suo percorso. Ad esempio, se è installato come `/Applications/Xcode-26.4.app`:

162

163```bash theme={null}

164sudo xcode-select -s /Applications/Xcode-26.4.app

165```

166

167Esegui `xcode-select -p` per controllare quale installazione è selezionata.

168

169<h2 id="see-also">

170 Vedi anche

171</h2>

172

173* [Computer use in Desktop](/docs/it/desktop#let-claude-use-your-computer): controllo dello schermo per app senza un riquadro dedicato

174* [Computer use from the CLI](/docs/it/computer-use): come la CLI raggiunge l'iOS Simulator

175* [Work in parallel with sessions](/docs/it/desktop#work-in-parallel-with-sessions): come le sessioni isolano i cambiamenti

176* [Get started with Claude Code Desktop](/docs/it/desktop-quickstart)

desktop-quickstart.md +7 −7

Details

9L'app desktop ti offre Claude Code con un'interfaccia grafica costruita per eseguire più sessioni affiancate: una barra laterale per gestire il lavoro parallelo, un layout con trascinamento della selezione con terminale integrato e editor di file, revisione visiva dei diff, anteprima live dell'app, monitoraggio dei PR di GitHub con merge automatico e attività pianificate. Non è richiesto alcun terminale.9L'app desktop ti offre Claude Code con un'interfaccia grafica costruita per eseguire più sessioni affiancate: una barra laterale per gestire il lavoro parallelo, un layout con trascinamento della selezione con terminale integrato e editor di file, revisione visiva dei diff, anteprima live dell'app, monitoraggio dei PR di GitHub con merge automatico e attività pianificate. Non è richiesto alcun terminale.

10 10

11<CardGroup cols={3}>11<CardGroup cols={3}>

~~13 Universal build for Intel and Apple Silicon~~13 Build universale per Intel e Apple Silicon

14 </Card>14 </Card>

15 15

~~17 For x64 processors~~17 Per processori x64

18 </Card>18 </Card>

19 19

~~20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">~~20 <Card title="Ottieni Claude per Linux (beta)" icon="linux" href="/docs/it/desktop-linux">

~~21 apt or .deb for Ubuntu and Debian~~21 apt o .deb per Ubuntu e Debian

22 </Card>22 </Card>

23</CardGroup>23</CardGroup>

24 24

26 26

27<Note>27<Note>

28 Claude Code richiede un [abbonamento Pro, Max, Team o Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing).28 Claude Code richiede un [abbonamento Pro, Max, Team o Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing).

desktop-scheduled-tasks.md +14 −14

Details

14 Confronta le opzioni di pianificazione14 Confronta le opzioni di pianificazione

15</h2>15</h2>

16 16

~~17Claude Code offers three ways to schedule recurring or one-off work:~~17Claude Code offre tre modi per pianificare lavori ricorrenti o una tantum:

18 18

~~20| :------------------------- | :---------------------------------- | :------------------------------------- | :------------------------------------------------------------------------- |~~20| :------------------------------ | :------------------------------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------- |

~~22| Requires machine on | No | Yes | Yes |~~22| Richiede macchina accesa | No | Sì | Sì |

~~23| Requires open session | No | No | Yes |~~23| Richiede sessione aperta | No | No | Sì |

~~24| Persistent across restarts | Yes | Yes | Restored on `--resume`, with [exceptions](/docs/en/scheduled-tasks#limitations) |~~24| Persistente tra i riavvii | Sì | Sì | Ripristinato su `--resume`, con [eccezioni](/docs/it/scheduled-tasks#limitations) |

~~25| Access to local files | No (fresh clone) | Yes | Yes |~~25| Accesso ai file locali | No (clone fresco) | Sì | Sì |

~~28| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |~~28| Pianificazione personalizzabile | Via `/schedule` nella CLI | Sì | Sì |

30 30

31<Tip>31<Tip>

~~32 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.~~32 Utilizzate **attività cloud** per lavori che devono essere eseguiti in modo affidabile senza la vostra macchina. Utilizzate **attività Desktop** quando avete bisogno di accesso ai file e agli strumenti locali. Utilizzate **`/loop`** per il polling rapido durante una sessione.

33</Tip>33</Tip>

34 34

35<Note>35<Note>

discover-plugins.md +12 −9

Details

207 </Step>207 </Step>

208 208

209 <Step title="Utilizzare il vostro nuovo plugin">209 <Step title="Utilizzare il vostro nuovo plugin">

210 Controllate il riepilogo dell'installazione: se riporta `Run /reload-plugins to activate.`, eseguite `/reload-plugins`, e se questo avverte che il ricaricamento rileggerà la conversazione, rieseguitelo come `/reload-plugins --force`.210 Se il riepilogo dell'installazione riporta `Run /reload-plugins to activate.`, Claude Code esegue quindi quel ricaricamento per voi. Se il ricaricamento avverte che il vostro prossimo messaggio rileggerebbe la conversazione, eseguite `/reload-plugins --force` per attivare il plugin.

211 211

212 Le skills dei plugin sono nello spazio dei nomi del nome del plugin, quindi **commit-commands** fornisce skills come `/commit-commands:commit`.212 Le skills dei plugin sono nello spazio dei nomi del nome del plugin, quindi **commit-commands** fornisce skills come `/commit-commands:commit`.

213 213

311```311```

312 312

313<Note>313<Note>

314 I marketplace basati su URL hanno alcune limitazioni rispetto ai marketplace basati su Git. Se riscontrate errori "path not found" durante l'installazione di plugin, consultate [Risoluzione dei problemi](/docs/it/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).314 I marketplace basati su URL hanno alcune limitazioni rispetto ai marketplace basati su Git. Se riscontrate errori durante l'installazione di plugin da un marketplace basato su URL, consultate [Risoluzione dei problemi](/docs/it/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).

315</Note>315</Note>

316 316

317<h2 id="install-plugins">317<h2 id="install-plugins">

349Quando installate dall'interfaccia `/plugin`, il riepilogo dell'installazione vi dice se il plugin è attivo nella vostra sessione corrente:349Quando installate dall'interfaccia `/plugin`, il riepilogo dell'installazione vi dice se il plugin è attivo nella vostra sessione corrente:

350 350

351* `Plugin is now active.`: Claude Code ha attivato il plugin come parte dell'installazione.351* `Plugin is now active.`: Claude Code ha attivato il plugin come parte dell'installazione.

352* `Run /reload-plugins to activate.`: il plugin non è ancora attivo, perché attivarlo [invaliderebbe la cache del prompt](/docs/it/prompt-caching#enabling-or-disabling-a-plugin) o perché il tentativo di attivazione non è riuscito. Eseguite il comando per attivare il plugin.352* `Run /reload-plugins to activate.`: il plugin non è ancora attivo, perché attivarlo [invaliderebbe la cache del prompt](/docs/it/prompt-caching#enabling-or-disabling-a-plugin) o perché il tentativo di attivazione non è riuscito. Claude Code quindi esegue `/reload-plugins` per voi. Se quel ricaricamento avverte sulla cache del prompt, eseguite `/reload-plugins --force` per [attivare il plugin comunque](#apply-plugin-changes-without-restarting).

353* Se il plugin non riesce a caricarsi, il riepilogo segnala l'errore e la scheda **Errors** di `/plugin` mostra il dettaglio.353* Se il plugin non riesce a caricarsi, il riepilogo segnala l'errore e la scheda **Errors** di `/plugin` mostra il dettaglio.

354 354

355Prima della v2.1.221, nessuna installazione aveva effetto nella sessione corrente finché non eseguivate `/reload-plugins` o riavviavate.355Prima della v2.1.221, nessuna installazione aveva effetto nella sessione corrente finché non eseguivate `/reload-plugins` o riavviavate.

393 393

394Potete anche gestire i plugin con comandi diretti:394Potete anche gestire i plugin con comandi diretti:

395 395

396* Quando eseguite `/plugin disable`, `/plugin enable` o `/plugin uninstall`, Claude Code apre il pannello dei plugin per applicare la modifica e lo lascia aperto. Premete **Esc** per chiudere il pannello prima di digitare un altro comando.396* Quando eseguite `/plugin disable`, `/plugin enable` o `/plugin uninstall`, Claude Code apre il pannello dei plugin per applicare la modifica e lo lascia aperto. Premete **Esc** per chiudere il pannello prima di digitare un altro comando. [Applicare le modifiche dei plugin senza riavviare](#apply-plugin-changes-without-restarting) descrive quando la modifica ha effetto nella vostra sessione.

397* Per gli script, utilizzate invece i comandi shell `claude plugin`, che non aprono il pannello.397* Per gli script, utilizzate invece i comandi shell `claude plugin`, che non aprono il pannello.

398 398

399Elencate i plugin installati senza aprire il menu:399Elencate i plugin installati senza aprire il menu:

437 Applicare le modifiche dei plugin senza riavviare437 Applicare le modifiche dei plugin senza riavviare

438</h3>438</h3>

439 439

440Quando il [riepilogo dell'installazione](#install-plugins) segnala `Plugin is now active.`, Claude Code ha già attivato il plugin e potete saltare questo passaggio. Per tutto il resto, i plugin che avete abilitato o disabilitato durante la sessione e le installazioni il cui riepilogo segnala `Run /reload-plugins to activate.`, applicate tutte le modifiche senza riavviare:440Quando chiudete il menu `/plugin`, Claude Code esegue `/reload-plugins` per voi per applicare le modifiche che avete apportato, come l'installazione, l'abilitazione, la disabilitazione e la disinstallazione dei plugin. Se il ricaricamento invaliderebbe la [cache del prompt](/docs/it/prompt-caching#enabling-or-disabling-a-plugin), avvisa e lascia le modifiche in sospeso; eseguite `/reload-plugins --force` per applicarle comunque. Se Claude sta ancora rispondendo quando chiudete il menu, il ricaricamento viene eseguito dopo che la risposta è terminata.

441 441

442```shell theme={null}442Per le modifiche dei plugin che avvengono al di fuori del menu, eseguite `/reload-plugins` voi stessi. Queste modifiche includono:

443/reload-plugins443

444```444* Un comando `claude plugin` che avete eseguito in un altro terminale

445* Modifiche a un plugin che avete caricato con [`--plugin-dir`](/docs/it/plugins#test-your-plugins-locally) mentre lo sviluppate

446* Un [aggiornamento automatico](#configure-auto-updates) di un plugin la cui notifica vi chiede di ricaricare

447* Una modifica in una cartella [`--plugin-dir`](/docs/it/plugins#test-your-plugins-locally) che Claude Code ha mantenuto perché applicarla invaliderebbe la cache del prompt

445 448

446Quando il ricaricamento invaliderebbe la cache del prompt, il comando avvisa e salta fino a quando non lo eseguite di nuovo con `--force`.449Prima di v2.1.268, i plugin che avete abilitato, disabilitato o disinstallato nel menu, e le installazioni che non si sono attivate durante l'installazione, rimanevano in sospeso fino a quando non eseguivate `/reload-plugins`.

447 450

448`/reload-plugins` viene eseguito anche in sessioni senza un terminale interattivo, come l'app desktop, l'Agent SDK e la [modalità non interattiva](/docs/it/headless) con `-p`. Richiede Claude Code v2.1.260 o versioni successive. Due limiti si applicano in quelle sessioni:451`/reload-plugins` viene eseguito anche in sessioni senza un terminale interattivo, come l'app desktop, l'Agent SDK e la [modalità non interattiva](/docs/it/headless) con `-p`. Richiede Claude Code v2.1.260 o versioni successive. Due limiti si applicano in quelle sessioni:

449 452

errors.md +3409 −562

Details

6 6

7> Consulta i messaggi di errore di runtime di Claude Code con il significato di ciascuno e come risolverli.7> Consulta i messaggi di errore di runtime di Claude Code con il significato di ciascuno e come risolverli.

8 8

9Questa pagina elenca gli errori di runtime che Claude Code visualizza e come recuperare da ciascuno, oltre a cosa controllare quando le risposte sembrano non corrette senza un errore. Per gli errori di installazione come `command not found` o errori TLS durante la configurazione, vedi [Troubleshooting installation and login](/docs/it/troubleshoot-install).9Questa pagina elenca gli errori di runtime che Claude Code visualizza e come recuperare da ciascuno, più cosa controllare quando le risposte sembrano non corrette senza un errore. Per gli errori di installazione come `command not found` o errori TLS durante la configurazione, vedi [Risoluzione dei problemi di installazione e accesso](/docs/it/troubleshoot-install).

10 10

11Questi errori e i comandi di recupero si applicano su CLI, l'[app Desktop](/docs/it/desktop) e [Claude Code sul web](/docs/it/claude-code-on-the-web), poiché tutti e tre avvolgono lo stesso Claude Code CLI. Per problemi specifici della superficie, vedi la sezione troubleshooting nella pagina di quella superficie.11Ad eccezione degli [errori di Wrapper e IDE](#wrapper-and-ide-errors), che il programma di avvio stampa piuttosto che Claude Code stesso, questi errori e i comandi di recupero si applicano su CLI, l'[app Desktop](/docs/it/desktop) e [Claude Code sul web](/docs/it/claude-code-on-the-web), poiché tutti e tre avvolgono lo stesso CLI di Claude Code. Per altri problemi specifici della superficie, vedi la sezione di risoluzione dei problemi nella pagina di quella superficie.

12 12

13<Note>13<Note>

14 Claude Code chiama l'API Claude per le risposte del modello, quindi la maggior parte degli errori di runtime si mappano a un codice di errore API sottostante. Questa pagina copre cosa significa ogni errore all'interno di Claude Code e come recuperare. Per le definizioni del codice di stato HTTP grezzo, vedi il [riferimento degli errori della piattaforma Claude](https://platform.claude.com/docs/en/api/errors).14 Claude Code chiama l'API Claude per le risposte del modello, quindi la maggior parte degli errori di runtime si mappano a un codice di errore API sottostante. Questa pagina copre cosa significa ogni errore all'interno di Claude Code e come recuperare. Per le definizioni del codice di stato HTTP grezzo, vedi il [riferimento degli errori della piattaforma Claude](https://platform.claude.com/docs/en/api/errors).

15</Note>15</Note>

16 16

17<h2 id="find-your-error">17<h2 id="find-your-error">

~~18 Trova il tuo errore~~18 Trovare il vostro errore

19</h2>19</h2>

20 20

~~21Abbina il messaggio che vedi nel tuo terminale a una sezione sottostante.~~21Abbinate il messaggio che vedete a una sezione qui sotto.

22 22

23| Messaggio | Sezione |23| Messaggio | Sezione |

24| :------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |24| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |

27| `Request timed out` | [Errori del server](#request-timed-out), o [Rete](#unable-to-connect-to-api) se il messaggio menziona la tua connessione internet |27| `Request timed out` | [Errori del server](#request-timed-out), oppure [Rete](#unable-to-connect-to-api) se il messaggio menziona la vostra connessione internet |

28| `API Error: No response from API` | [Errori del server](#no-response-from-api) |

28| `Server error mid-response. The response above may be incomplete.` | [Errori del server](#the-response-above-may-be-incomplete) |29| `Server error mid-response. The response above may be incomplete.` | [Errori del server](#the-response-above-may-be-incomplete) |

30| `Connection lost mid-response` / `Your computer went to sleep mid-response` / `The response stopped arriving` | [Errori del server](#the-response-above-may-be-incomplete) |

29| `Connection closed mid-response` / `Response stalled mid-stream` | [Errori del server](#the-response-above-may-be-incomplete) |31| `Connection closed mid-response` / `Response stalled mid-stream` | [Errori del server](#the-response-above-may-be-incomplete) |

32| `Connection lost before a response was produced` / `Your computer went to sleep before a response was produced` / `The response stalled before a response was produced` | [Tentativi automatici](#automatic-retries) |

33| `Connection closed while thinking` / `Response stalled while thinking` | [Tentativi automatici](#automatic-retries) |

34| `Connection lost while your computer was asleep` | [Tentativi automatici](#automatic-retries) |

30| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |35| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

31| `Auto mode could not evaluate this action and is blocking it for safety` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |36| `Auto mode could not evaluate this action and is blocking it for safety` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

32| `Auto mode classifier transcript exceeded context window` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |37| `Auto mode classifier transcript exceeded context window` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

38| `Agent aborted: auto mode classifier request refused by the safety safeguard` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

34| `You've hit your session limit` / `You've hit your weekly limit` | [Limiti di utilizzo](#youve-hit-your-session-limit) |40| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [Limiti di utilizzo](#youve-hit-your-session-limit) |

42| `the prompt to confirm went unanswered — nothing was sent` | [Limiti di utilizzo](#the-prompt-to-confirm-went-unanswered) |

46| `Could not update your spend limit` | [Limiti di utilizzo](#could-not-update-your-spend-limit) |

47| `spend limit reached` / `spend limit unavailable` | [Limiti di utilizzo](#spend-limit-reached) |

52| `Invalid auth token · Fix external auth token` | [Autenticazione](#invalid-request-header-value) |

53| `Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable` | [Autenticazione](#invalid-request-header-value) |

54| `Invalid request header from the environment · Fix the environment variable` | [Autenticazione](#invalid-request-header-value) |

44| `Your organization has disabled API key authentication` | [Autenticazione](#your-organization-has-disabled-api-key-authentication) |56| `Your organization has disabled API key authentication` | [Autenticazione](#your-organization-has-disabled-api-key-authentication) |

45| `Your organization has disabled Claude subscription access` | [Autenticazione](#your-organization-has-disabled-claude-subscription-access) |57| `Your organization has disabled Claude subscription access` | [Autenticazione](#your-organization-has-disabled-claude-subscription-access) |

46| `Routines are disabled by your organization's policy` | [Autenticazione](#routines-are-disabled-by-your-organizations-policy) |58| `Routines are disabled by your organization's policy` | [Autenticazione](#routines-are-disabled-by-your-organizations-policy) |

47| `Remote Control is only available when using Claude via api.anthropic.com` | [Autenticazione](#remote-control-requires-the-anthropic-api) |59| `Remote Control is only available when using Claude via api.anthropic.com` | [Autenticazione](#remote-control-requires-the-anthropic-api) |

60| `OAuth token refresh failed — run /login to re-authenticate` | [Autenticazione](#remote-control-couldnt-refresh-your-login) |

61| `JWT refresh failed: no OAuth token — run /login` | [Autenticazione](#remote-control-couldnt-refresh-your-login) |

62| `Claude.ai login expired` | [Autenticazione](#remote-control-couldnt-refresh-your-login) |

63| `Claude.ai login was rejected — run /login, then /remote-control` | [Autenticazione](#remote-control-couldnt-refresh-your-login) |

64| `OAuth token unavailable — run /login to restore Remote Control` | [Autenticazione](#remote-control-couldnt-refresh-your-login) |

65| `Signed out of Claude — run /login, then /remote-control` | [Autenticazione](#remote-control-couldnt-refresh-your-login) |

66| `signed-in claude.ai account or organization changed on this machine` | [Autenticazione](#remote-control-stopped-because-the-signed-in-account-changed) |

67| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [Autenticazione](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

68| `Remote Control stopped — the app running this session is signed out of Claude` | [Autenticazione](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

70| `API Error: 401 Invalid authentication credentials` | [Autenticazione](#api-error-401-invalid-authentication-credentials) |

72| `Not signed in to the Cloud gateway — run /login.` | [Autenticazione](#administrator-policy-requires-a-cloud-gateway-sign-in) |

73| `Administrator policy requires a Cloud gateway sign-in on this machine` | [Autenticazione](#administrator-policy-requires-a-cloud-gateway-sign-in) |

75| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [Autenticazione](#your-account-is-on-hold) |

76| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [Autenticazione](#your-account-is-on-hold) |

77| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [Autenticazione](#anthropic-profile-login-expired) |

78| `Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile` | [Autenticazione](#anthropic-profile-login-expired) |

80| `claude.ai rejected the session token` / `session token rejected` | [Autenticazione](#claude-ai-rejected-the-session-token) |

81| `Issuer mismatch in authorization response (RFC 9207)` | [Autenticazione](#issuer-mismatch-in-authorization-response) |

82| `Cloud gateway session expired — run /login to reconnect.` | [Autenticazione](#cloud-gateway-session-expired) |

83| `Cloud gateway <url> no longer accepts this session` | [Autenticazione](#cloud-gateway-session-expired) |

86| `Could not load AWS credentials` / `Could not load Google Cloud credentials` | [Autenticazione](#could-not-load-aws-or-google-cloud-credentials) |

88| `Timed out after 60s waiting for AWS` | [Autenticazione](#bedrock-setup-verification-timed-out-waiting-for-aws) |

89| `A request to AWS timed out. Check your network and proxy settings, then try again.` | [Autenticazione](#bedrock-setup-verification-timed-out-waiting-for-aws) |

90| `Could not load the default credentials` on Google Cloud's Agent Platform | [Autenticazione](#could-not-load-aws-or-google-cloud-credentials) |

56| `Waiting for API response · will retry in` | [Tentativi automatici](#automatic-retries), o [Rete](#unable-to-connect-to-api) se persiste |92| `Connection refused —` / `Can't reach the API server —` / `No internet route —` / `Couldn't connect through your proxy` / `Connection dropped`, each ending with an error code in parentheses | [Rete](#unable-to-connect-to-api) |

93| `Unable to connect to Anthropic services` during setup | [Rete](#unable-to-connect-to-anthropic-services) |

94| `Socket is closed` | [Rete](#socket-is-closed) |

95| `Waiting for API response · will retry in` | [Tentativi automatici](#automatic-retries), oppure [Rete](#unable-to-connect-to-api) se persiste |

96| `API returned an empty or malformed response` | [Rete](#api-returned-an-empty-or-malformed-response) |

97| `Streaming response ended before any complete data was received` | [Rete](#streaming-response-ended-before-any-complete-data-was-received) |

57| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [Rete](#bedrock-streaming-response-has-an-unexpected-content-type) |98| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [Rete](#bedrock-streaming-response-has-an-unexpected-content-type) |

101| `unable to get local issuer certificate` | [Rete](#ssl-certificate-errors) |

103| `proxy refused the connection` | [Rete](#the-proxy-refused-the-connection) |

104| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/it/cloud-environments#github-proxy) |

105| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [Rete](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

108| `Couldn't share the transcript.` | [Rete](#couldnt-share-the-transcript) |

109| `Prompt is too long` / `Input is too long for requested model` | [Errori di richiesta](#prompt-is-too-long) |

110| `Prompt is too long · automatic compaction failed:` | [Errori di richiesta](#prompt-is-too-long) |

111| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [Errori di richiesta](#prompt-is-too-long) |

112| `Context limit reached · /compact or /clear to continue` | [Errori di richiesta](#prompt-is-too-long) |

113| `Context limit reached · /clear to continue` | [Errori di richiesta](#prompt-is-too-long) |

114| `capability_rejected: prompt_too_long` on a Claude apps gateway session | [Errori di richiesta](#prompt-is-too-long) |

115| `upstream rejected the request` / `request too large for this upstream` on a Claude apps gateway session | [Messaggi di errore upstream](/docs/it/claude-apps-gateway-config#upstream-error-messages) |

116| `upstream rate limit exceeded` on a Claude apps gateway session | [Messaggi di errore upstream](/docs/it/claude-apps-gateway-config#upstream-error-messages) |

117| `all upstreams failed (N attempted)` on a Claude apps gateway session | [Messaggi di errore upstream](/docs/it/claude-apps-gateway-config#upstream-error-messages) |

118| `Claude Code may not be enabled for your organization` after a Claude apps gateway sign-in | [Risoluzione dei problemi del gateway delle app Claude](/docs/it/claude-apps-gateway-deploy#troubleshooting) |

119| `Context exceeds the ...-token limit by ... tokens` in `/context` output | [Errori di richiesta](#context-exceeds-the-token-limit) |

122| `Request too large for the API's 32MB request limit` | [Errori di richiesta](#request-too-large) |

127| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [Errori di richiesta](#tool-input-schema-is-invalid) |

130| `Model ... not found` | [Errori di richiesta](#model-not-found) |

71| `Claude Opus is not available with the Claude Pro plan` | [Errori di richiesta](#claude-opus-is-not-available-with-the-claude-pro-plan) |131| `Claude Opus is not available with the Claude Pro plan` | [Errori di richiesta](#claude-opus-is-not-available-with-the-claude-pro-plan) |

132| `Claude Code ... does not support this model; version ... or newer is required` | [Errori di richiesta](#claude-code-does-not-support-this-model) |

133| `Claude Code ... is older than the minimum version required by your organization's policy` | [Errori di richiesta](#claude-code-does-not-support-this-model) |

72| `Model ... is restricted by your organization's settings` | [Errori di richiesta](#model-is-restricted-by-your-organizations-settings) |134| `Model ... is restricted by your organization's settings` | [Errori di richiesta](#model-is-restricted-by-your-organizations-settings) |

135| `Model switch ... blocked by a PreModelSwitch hook` | [Errori di richiesta](#model-switch-was-blocked-by-a-premodelswitch-hook) |

136| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [Errori di richiesta](#couldnt-save-it-as-your-default) |

73| `thinking.type.enabled is not supported for this model` | [Errori di richiesta](#thinking-type-enabled-is-not-supported-for-this-model) |137| `thinking.type.enabled is not supported for this model` | [Errori di richiesta](#thinking-type-enabled-is-not-supported-for-this-model) |

138| `Effort '<level>' isn't available with thinking turned off on this model` | [Errori di richiesta](#effort-isnt-available-with-thinking-turned-off) |

139| `effort '<level>' is not supported when thinking is disabled` | [Errori di richiesta](#effort-isnt-available-with-thinking-turned-off) |

142| `[Unsupported tool content removed]` | [Errori di richiesta](#unsupported-tool-content-removed) |

143| `server_tool_use.name: Input should be` on every turn of a resumed session | [Errori di richiesta](#unsupported-tool-content-removed) |

144| `<model> can't help with this. Start a new session to continue` | [Errori di richiesta](#usage-policy-refusal) |

76| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Errori di richiesta](#usage-policy-refusal) |145| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Errori di richiesta](#usage-policy-refusal) |

146| `<model>'s safeguards flagged this message` | [Errori di richiesta](#safety-measures-flagged-a-cybersecurity-topic) |

77| `<model> has safety measures that flagged this message for a cybersecurity topic` | [Errori di richiesta](#safety-measures-flagged-a-cybersecurity-topic) |147| `<model> has safety measures that flagged this message for a cybersecurity topic` | [Errori di richiesta](#safety-measures-flagged-a-cybersecurity-topic) |

78| `Installation was killed before it could finish (exit code 137)` | [Errori di installazione](#installation-was-killed-before-it-could-finish) |148| `Installation was killed before it could finish (exit code 137)` | [Errori di installazione](#installation-was-killed-before-it-could-finish) |

79| `The connection dropped while downloading the update` | [Errori di installazione](#the-connection-dropped-while-downloading-the-update) |149| `The connection dropped while downloading the update` | [Errori di installazione](#the-connection-dropped-while-downloading-the-update) |

80| `Download timed out: exceeded the total deadline` | [Errori di installazione](#the-connection-dropped-while-downloading-the-update) |150| `Download timed out: exceeded the total deadline` | [Errori di installazione](#the-connection-dropped-while-downloading-the-update) |

152| `Cloud sessions cannot be created from a --restricted session` | [Errori della riga di comando](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

154| `Error: Invalid --agents configuration:` | [Errori della riga di comando](#invalid-agents-configuration) |

155| `Error: Settings file exceeds the 2MiB limit` | [Errori della riga di comando](#settings-file-exceeds-the-2mib-limit) |

156| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [Errori della riga di comando](#the-current-directory-no-longer-exists) |

157| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [Errori della riga di comando](#directory-couldnt-be-resolved-to-a-real-location) |

158| `Error: Workspace not trusted` when starting Remote Control | [Errori della riga di comando](#workspace-not-trusted-when-starting-remote-control) |

159| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [Errori della riga di comando](#not-carried-over-to-the-sessions-remote-control-starts) |

160| `` `claude import` is not yet available in this build `` | [Errori della riga di comando](#claude-import-is-not-yet-available-in-this-build) |

161| `Could not read Claude Code config` | [Errori della riga di comando](#could-not-read-claude-code-config) |

163| `Cannot add MCP server to scope: managed` | [Errori della riga di comando](#cannot-add-mcp-server-to-the-managed-scope) |

164| `is Anthropic-hosted and doesn't support local OAuth` | [Errori della riga di comando](#anthropic-hosted-and-doesnt-support-local-oauth) |

165| `Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes` | [Errori della riga di comando](#cant-read-mcp-json) |

166| `Server rejected the Authorization header minted by the configured headersHelper` | [Errori della riga di comando](#server-rejected-the-authorization-header-minted-by-the-configured-headershelper) |

84| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [Errori della riga di comando](#mcp-permission-prompt-tool-not-found) |167| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [Errori della riga di comando](#mcp-permission-prompt-tool-not-found) |

168| `OAuth callback port <port> is already in use — another process may be holding it` | [Errori della riga di comando](#oauth-callback-port-is-already-in-use) |

169| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [Errori della riga di comando](#security-review-fails-without-origin-head) |

170| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [Errori della riga di comando](#security-review-fails-without-origin-head) |

171| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [Errori della riga di comando](#security-review-fails-without-origin-head) |

172| `Input must be provided either through stdin or as a prompt argument when using --print` | [Errori della riga di comando](#input-must-be-provided-when-using-print) |

173| `Error: Input contained only whitespace` | [Errori della riga di comando](#input-contained-only-whitespace) |

174| `Blank prompt — the message was only whitespace, so nothing was sent to the model.` | [Errori della riga di comando](#input-contained-only-whitespace) |

175| `Error: stream-json input carried over 256M characters with no newline` | [Errori della riga di comando](#stream-json-input-carried-over-256m-characters-with-no-newline) |

176| `Unknown command: /<name>`, with or without a `Did you mean` suggestion | [Errori della riga di comando](#unknown-command) |

177| `Diff is too large for ultrareview` / `PR #<N> is too large for ultrareview` | [Errori della riga di comando](#diff-is-too-large-for-ultrareview) |

178| `Could not find merge-base with <branch>` | [Errori della riga di comando](#could-not-find-merge-base-with-the-base-branch) |

179| `Your checkout has no branches (detached HEAD only)` | [Errori della riga di comando](#your-checkout-has-no-branches) |

180| `Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected` | [Errori della riga di comando](#no-github-account-is-connected-to-your-claude-account) |

181| `Your connected GitHub account can't see <owner>/<repo>` | [Errori della riga di comando](#your-connected-github-account-cant-see-the-repository) |

182| `The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead` | [Errori della riga di comando](#the-github-app-preflight-failed-transiently) |

183| `Failed to resume the conversation` | [Errori della riga di comando](#failed-to-resume-the-conversation) |

184| `No conversation found with session ID: <session-id>` | [Errori della riga di comando](#no-conversation-found-with-the-session-id) |

185| `Cannot switch renderers in this session` | [Errori della riga di comando](#cannot-switch-renderers-in-this-session) |

186| `Cannot switch renderers while work is running in the background` | [Errori della riga di comando](#cannot-switch-renderers-in-this-session) |

187| `Couldn't read your Zed keymap` / `Couldn't back up your Zed keymap` / `Couldn't update your Zed keymap` | [Errori della riga di comando](#terminal-setup-left-your-zed-keymap-unchanged) |

188| `Your Zed keymap isn't a readable list of keybindings` | [Errori della riga di comando](#terminal-setup-left-your-zed-keymap-unchanged) |

189| `Skill usage reports are not available on this connection.` | [Errori della riga di comando](#skill-usage-reports-are-not-available-on-this-connection) |

190| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Errori dei plugin](#plugin-eval-is-currently-in-early-access) |

85| `Marketplace "<name>" is registered from an untrusted source` | [Errori dei plugin](#marketplace-is-registered-from-an-untrusted-source) |191| `Marketplace "<name>" is registered from an untrusted source` | [Errori dei plugin](#marketplace-is-registered-from-an-untrusted-source) |

86| `references ${user_config.*} in a shell-form command` | [Errori dei plugin](#plugin-command-references-user-config) |192| `references ${user_config.*} in a shell-form command` | [Errori dei plugin](#plugin-command-references-user-config) |

87| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Errori dei plugin](#plugin-command-references-user-config) |193| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Errori dei plugin](#plugin-command-references-user-config) |

88| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Errori dei plugin](#plugin-command-references-user-config) |194| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Errori dei plugin](#plugin-command-references-user-config) |

195| `Plugin archive integrity check failed` | [Errori dei plugin](#plugin-archive-integrity-check-failed) |

196| `path escapes plugin directory` | [Errori dei plugin](#path-escapes-plugin-directory) |

197| `path could not be checked` | [Errori dei plugin](#path-could-not-be-checked) |

198| `its marketplace entry path does not stay inside the marketplace directory` | [Errori dei plugin](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

199| `Plugin source path refused` | [Errori dei plugin](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

200| `Failed to load marketplace configuration` | [Errori dei plugin](#failed-to-load-marketplace-configuration) |

201| `Marketplace configuration file is corrupted` | [Errori dei plugin](#failed-to-load-marketplace-configuration) |

90| `File is covered by a Read deny rule in your permission settings` | [Errori degli strumenti](#file-is-covered-by-a-read-deny-rule) |203| `File is covered by a Read deny rule in your permission settings` | [Errori degli strumenti](#file-is-covered-by-a-read-deny-rule) |

204| `subagent_type is required: the general-purpose agent is not available in this session` | [Errori degli strumenti](#subagent-type-is-required) |

205| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [Errori degli strumenti](#memory-index-is-over-its-read-limit) |

206| `pkill: refusing to run` | [Errori degli strumenti](#pkill-pattern-matches-the-claude-code-process) |

207| `Failed to write to <name>'s inbox — nothing was sent` | [Errori degli strumenti](#failed-to-write-to-a-teammate-inbox) |

208| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [Errori degli strumenti](#failed-to-write-to-a-teammate-inbox) |

209| `Message too large for cross-session delivery` | [Errori degli strumenti](#message-too-large-for-cross-session-delivery) |

210| `Too many messages to this session just now` | [Errori degli strumenti](#too-many-messages-to-this-session-just-now) |

211| `Refusing to send: reply target is a symlink` / `Refusing to send: cannot vet reply target` | [Errori degli strumenti](#refusing-to-send-a-cross-session-message) |

212| `Refusing to send: connected endpoint is not the expected process` / `Refusing to send: connected endpoint identity could not be read` | [Errori degli strumenti](#refusing-to-send-a-cross-session-message) |

213| `Refusing to send: connected endpoint is not owned by this user` / `Refusing to send: connected endpoint owner could not be read` | [Errori degli strumenti](#refusing-to-send-a-cross-session-message) |

214| `Refusing to send: connected endpoint is a different process with the expected pid` | [Errori degli strumenti](#refusing-to-send-a-cross-session-message) |

215| `Refusing to read <path>: its symlink resolution changed after permission was checked` / `Refusing to search <path>: its symlink resolution changed after permission was checked` | [Errori degli strumenti](#refusing-after-a-symlink-changed) |

216| `Refusing to write <path>: its parent-directory symlink resolution changed after permission was checked` / `Refusing to write <path>: it is a symbolic link. Write to the link's target path instead` | [Errori degli strumenti](#refusing-after-a-symlink-changed) |

217| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [Errori degli strumenti](#refusing-after-a-symlink-changed) |

218| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [Errori degli strumenti](#refusing-after-a-symlink-changed) |

219| `task output swap refused (tasks dir moved or linked)` | [Errori degli strumenti](#task-output-swap-refused) |

220| `Command killed: its output file was replaced or could no longer be verified` | [Errori degli strumenti](#task-output-swap-refused) |

221| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Errori degli strumenti](#the-source-file-is-not-valid-utf-8-text) |

222| `the source file has the replacement character U+FFFD` | [Errori degli strumenti](#the-source-file-is-not-valid-utf-8-text) |

223| `Can't open MCP settings while no terminal is attached to this background session` | [Errori della sessione in background](#commands-refused-in-a-background-session) |

91| `Can't open MCP settings in a background session` | [Errori della sessione in background](#commands-refused-in-a-background-session) |224| `Can't open MCP settings in a background session` | [Errori della sessione in background](#commands-refused-in-a-background-session) |

225| `blocked because the path is spelled in a form that cannot be safely resolved` | [Errori della sessione in background](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |

226| `blocked because the path is network-shaped` | [Errori della sessione in background](#write-or-command-blocked-because-the-path-names-a-network-location) |

227| `This session has no saved transcript` | [Errori della sessione in background](#this-session-has-no-saved-transcript) |

228| `Can't open — this session is running in another terminal` | [Errori della sessione in background](#this-session-is-running-in-another-terminal) |

229| `This conversation is already open in another running Claude session` | [Errori della sessione in background](#this-session-is-running-in-another-terminal) |

230| `This session's saved conversation is no longer on disk` | [Errori della sessione in background](#this-sessions-saved-conversation-is-no-longer-on-disk) |

231| `kept <id> — <n> unpushed commits on <branch>` | [Errori della sessione in background](#worktree-has-commits-that-are-not-pushed-anywhere) |

232| `kept <id> — worktree has commits that are not pushed anywhere` | [Errori della sessione in background](#worktree-has-commits-that-are-not-pushed-anywhere) |

233| `terminal host process died — press Enter to restart` / `This session's terminal host process died` | [Errori della sessione in background](#terminal-host-process-died) |

234| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [Errori della sessione in background](#session-isnt-responding) |

235| `Session <id> was stopped while the respawn was in flight` | [Errori della sessione in background](#session-was-stopped-while-the-respawn-was-in-flight) |

236| `This session was running agent '<name>', which is no longer available` | [Errori della sessione in background](#session-agent-no-longer-available) |

92| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Errori della sessione in background](#claude_code_process_wrapper-launcher-errors) |237| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Errori della sessione in background](#claude_code_process_wrapper-launcher-errors) |

238| `EUNKNOWN: unknown error, uv_spawn` | [Errori della sessione in background](#eunknown-when-starting-a-background-session) |

239| `EACCES: permission denied, posix_spawn` | [Errori della sessione in background](#eacces-when-starting-a-background-session) |

240| `exited before it became reachable` | [Errori della sessione in background](#background-service-exited-before-it-became-reachable) |

241| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [Errori della sessione in background](#working-directory-no-longer-exists-when-starting-a-background-session) |

242| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [Errori della sessione in background](#eacces-when-starting-a-background-session) |

243| `Claude Code process exited with code N` | [Errori del wrapper e dell'IDE](#claude-code-process-exited-with-code-n) |

244| `Could not locate the Claude CLI on PATH` | [Errori del wrapper e dell'IDE](#could-not-locate-the-claude-cli-on-path) |

245| `Restored the code, but skipped N files` | [Avvisi e errori di Rewind](#restored-the-code-but-skipped-files) |

246| `No files were restored: N files failed (backup missing, or the file could not be updated)` | [Avvisi e errori di Rewind](#no-files-were-restored) |

247| `Transcript writes are failing (...)` | [Avvisi di salvataggio della sessione](#transcript-writes-are-failing) |

248| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [Avvisi di salvataggio della sessione](#transcript-saving-is-off-skip-prompt-history) |

249| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [Avvisi di salvataggio della sessione](#transcript-saving-is-off-child-session-marker) |

250| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [Avvisi di configurazione](#fullscreen-failed-start-notice) |

251| `Claude Code exited after an unrecoverable interface error (...)` | [Avvisi di configurazione](#exited-after-an-unrecoverable-interface-error) |

252| `Agent descriptions are over the 15.0k-token limit` | [Avvisi di configurazione](#agent-descriptions-are-over-the-15000-token-limit) |

93| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Avvisi di configurazione](#workspace-has-not-been-trusted) |253| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Avvisi di configurazione](#workspace-has-not-been-trusted) |

255| `Remote managed settings failed to load (<cause>)` | [Avvisi di configurazione](#remote-managed-settings-failed-to-load) |

256| `Managed settings were not approved; exiting without applying them.` | [Avvisi di configurazione](#managed-settings-were-not-approved) |

257| `MCP server <name> is blocked by enterprise managed policy` | [Avvisi di configurazione](#mcp-server-is-blocked-by-enterprise-managed-policy) |

258| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [Avvisi di configurazione](#managed-settings-document-could-not-be-parsed) |

259| `Managed settings drop-in directory could not be read` | [Avvisi di configurazione](#managed-settings-document-could-not-be-parsed) |

260| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [Avvisi di configurazione](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

261| `headersHelper not run — this workspace has no persisted trust` | [Avvisi di configurazione](#headershelper-not-run) |

262| `Invalid permission rule "..." was skipped: Malformed Tool(content) rule` | [Avvisi di configurazione](#malformed-tool-content-rule) |

263| `... is not matched by file permission checks` | [Avvisi di configurazione](#is-not-matched-by-file-permission-checks) |

264| `... has a wildcard before the rest of the command` | [Avvisi di configurazione](#has-a-wildcard-before-the-rest-of-the-command) |

265| `CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced` | [Avvisi di configurazione](#the-200k-limit-isnt-enforced) |

266| `[claude-code:unrecognized_model]` | [Avvisi di configurazione](#unrecognized-model-id-on-a-request) |

267| `Stale sandbox mask files left by a killed session` | [Avvisi di configurazione](#stale-sandbox-mask-files-left-by-a-killed-session) |

268| Le risposte sembrano di qualità inferiore al solito | [Qualità della risposta](#responses-seem-lower-quality-than-usual) |

95 269

96<h2 id="automatic-retries">270<h2 id="automatic-retries">

97 Tentativi automatici271 Tentativi automatici

98</h2>272</h2>

99 273

100Claude Code ritenta i guasti transitori prima di mostrarti un errore. Gli errori del server, le risposte sovraccariche, i timeout delle richieste, i throttle 429 temporanei e le connessioni interrotte vengono tutti ritentati fino a 10 volte con backoff esponenziale. A partire da v2.1.198, questo copre le connessioni che si interrompono nel mezzo di una risposta prima che qualsiasi output visibile sia stato trasmesso: Claude Code ri-emette la richiesta con lo stesso backoff e il turno continua invece di fermarsi con un errore di connessione. A partire da v2.1.199, i throttle 429 temporanei che non portano le intestazioni di quota del tuo piano vengono anche ritentati quando sei connesso con un abbonamento claude.ai; le versioni precedenti li ritentavano solo per le chiavi API e gli accessi Enterprise.274Claude Code ritenta i guasti transitori fino a 10 volte con backoff esponenziale prima di mostrarti un errore. Non sempre ritenta un guasto che arriva a metà della risposta di Claude. Quando vedi uno degli errori in questa pagina, Claude Code ha già effettuato i tentativi che si applicano a quel guasto; gli elenchi sottostanti indicano quali guasti ottengono il budget completo, quali ne ottengono uno più piccolo e quali non ne ottengono nessuno.

101 275

102Alcune classi di guasti non vengono ritentate, perché un tentativo non può avere successo:276Claude Code ritenta questi guasti:

103 277

104* A partire da v2.1.199, un guasto di convalida del certificato TLS, come un proxy che ispeziona TLS, un bundle `NODE_EXTRA_CA_CERTS` mancante, o un certificato scaduto, fallisce al primo tentativo in modo che la correzione appaia immediatamente invece che dopo il budget di tentativo completo. Vedi [Errori del certificato SSL](#ssl-certificate-errors). Le condizioni TLS transitorie come un timeout di handshake continuano a ritentare.278* Errori del server, risposte sovraccariche e timeout delle richieste che arrivano prima che una qualsiasi risposta di Claude sia stata trasmessa.

105* A partire da v2.1.199, un errore del server che arriva dopo che Claude ha già trasmesso output visibile mantiene la risposta parziale e aggiunge un [avviso di risposta incompleta](#the-response-above-may-be-incomplete) invece di ritentare, poiché ri-eseguire la richiesta potrebbe eseguire gli stessi strumenti due volte. Le versioni precedenti scartavano l'output parziale e segnalano il turno come un errore.279* Connessioni interrotte. Quando una connessione si interrompe a metà di una richiesta prima che Claude abbia completato una qualsiasi parte della sua risposta, incluso il suo thinking, Claude Code invia nuovamente la richiesta con lo stesso backoff e il turno continua, anche se del testo aveva già iniziato a essere trasmesso. Quando si interrompe dopo che Claude ha finito di pensare ma prima di aver iniziato un testo o una chiamata di strumento, Claude Code invece invia nuovamente la richiesta fino a due volte in rapida successione, e termina il turno con `Connection lost before a response was produced` se la connessione continua a interrompersi a quel punto.

106* Una [risposta di streaming Amazon Bedrock con un content-type inaspettato](#bedrock-streaming-response-has-an-unexpected-content-type) fallisce al primo tentativo, perché il gateway o il proxy che riscrive la risposta riscriverebbero il tentativo nello stesso modo. Richiede Claude Code v2.1.208 o successivo.280* Una connessione che Claude Code rileva è stata interrotta dal tuo computer che si è addormentato a metà di una richiesta. Claude Code la conta come una connessione interrotta secondo le regole sopra; una volta che l'etichetta di riprovazione nomina il motivo specifico, legge `Connection lost while your computer was asleep`, e se il turno termina dopo che Claude ha finito di pensare ma prima di un testo o di una chiamata di strumento, il messaggio legge `Your computer went to sleep before a response was produced`.

281* Un flusso di risposta bloccato, quando le intestazioni di risposta sono arrivate ma nessuna risposta di Claude è arrivata, o quando Claude ha finito di pensare ma non ha iniziato un testo o una chiamata di strumento: Claude Code interrompe la connessione bloccata e invia nuovamente la richiesta al massimo una volta, al di fuori del budget di 10 tentativi sopra. Se la risposta si blocca una seconda volta dopo che Claude ha finito di pensare ma prima di un testo o di una chiamata di strumento, Claude Code termina il turno con `The response stalled before a response was produced`.

282* Una richiesta di streaming a cui l'API non risponde mai con intestazioni di risposta, su una connessione dove il [first-byte deadline runs](/docs/it/network-config#streaming-idle-watchdogs): Claude Code la interrompe alla scadenza e la invia nuovamente al massimo una volta per richiesta di modello, entro il budget di riprovazione, quindi termina il turno con [No response from API](#no-response-from-api) se anche quel tentativo rimane senza risposta. Su altre connessioni, la richiesta attende `API_TIMEOUT_MS`. Quando imposti `CLAUDE_CODE_RETRY_WATCHDOG`, il limite di un tentativo non si applica.

283* Throttle 429 temporanei, ma non il `429` del limite di spesa di un gateway, che non è un throttle; vedi [Spend limit reached](#spend-limit-reached).

284 * Quando sei connesso con un abbonamento claude.ai, questo include throttle 429 che non portano le intestazioni di quota del tuo piano. Prima della v2.1.199, Claude Code ritentava questi throttle solo per le chiavi API e gli accessi Enterprise.

285* Una richiesta rifiutata perché l'input più `max_tokens` supera il limite di contesto. Inviarla nuovamente invariata fallirebbe allo stesso modo, quindi Claude Code ritenta con un `max_tokens` ridotto, e smette di ritentare e compatta invece in due casi:

286 * Quando nessuna riduzione può adattarsi, ad esempio quando la conversazione stessa riempie quasi la finestra di contesto.

287 * Quando un tentativo non può ridurre ulteriormente `max_tokens`. Prima della v2.1.218, Claude Code poteva inviare nuovamente una richiesta ridotta che ancora non si adattava, ad esempio quando il budget di thinking esteso superava il contesto rimanente, fino a quando il budget di riprovazione non si esauriva.

288* Una credenziale Google Cloud scaduta o mancante su [Google Cloud's Agent Platform](/docs/it/google-vertex-ai), o credenziali AWS che non riescono a caricarsi sulla tua macchina. Claude Code scarta le sue credenziali memorizzate nella cache e ritenta fino a due volte, quindi segnala l'errore in modo che tu possa autenticarti di nuovo subito, come descritto in [Could not load AWS or Google Cloud credentials](#could-not-load-aws-or-google-cloud-credentials). Prima della v2.1.228, Claude Code ritentava una credenziale Google Cloud non riuscita attraverso il budget di riprovazione completo prima di mostrare l'errore.

289* Un `401` o `403` dall'API Anthropic, direttamente o attraverso un [LLM gateway](/docs/it/llm-gateway), mentre uno script [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper) fornisce la credenziale. Claude Code esegue nuovamente lo script e ritenta con il suo output aggiornato, entro il budget di riprovazione completo. Quando lo script stesso fallisce al nuovo tentativo, Claude Code mostra [Your apiKeyHelper script is failing](#your-apikeyhelper-script-is-failing) invece.

107 290

108Durante il tentativo, lo spinner mostra un countdown `Retrying in Ns · attempt x/y` dopo un'etichetta di errore. L'etichetta nomina il motivo specifico dal primo tentativo per i guasti su cui puoi agire subito: la rete è inattiva, un handshake TLS non è riuscito, o hai raggiunto un limite di velocità. Per altri errori legge `API error` all'inizio. A partire da v2.1.198 passa al motivo specifico dal terzo tentativo, o al tentativo finale quando `CLAUDE_CODE_MAX_RETRIES` consente meno di tre; le versioni precedenti passano solo al tentativo finale.291Prima della v2.1.227, `Connection lost before a response was produced` leggeva `Connection closed while thinking, before producing a response` e `The response stalled before a response was produced` leggeva `Response stalled while thinking, before producing a response`.

109 292

110A partire da v2.1.198, il suggerimento dello spinner usuale è soppresso durante i tentativi. Una volta rivelato il motivo dell'errore, se il guasto è un sovraccarico 529 la riga sotto il countdown nomina anche dove controllare lo stato del servizio: `status.claude.com` sull'API Anthropic, o l'host del provider o gateway indicato nel messaggio su altre configurazioni.293Claude Code non ritenta questi guasti:

111 294

112Se nessun dato arriva sul flusso di risposta per 20 secondi mentre una richiesta è ancora in sospeso, lo spinner mostra `Waiting for API response · will retry in … · check your network` prima che qualsiasi tentativo sia iniziato. La richiesta non è ancora fallita: il countdown viene eseguito fino al punto in cui Claude Code interrompe la connessione bloccata e ritenta, quindi il banner si cancella da solo una volta che i dati riprendono o il tentativo ha successo. A partire da v2.1.185 la soglia è di 20 secondi; le versioni precedenti mostrano il banner dopo 10 secondi con una formulazione diversa. Se riappare ad ogni tentativo, trattalo come un [problema di rete](#unable-to-connect-to-api).295* Un errore di convalida del certificato TLS, come un proxy che ispeziona TLS, un bundle `NODE_EXTRA_CA_CERTS` mancante, o un certificato scaduto. Claude Code segnala l'errore al primo tentativo, in modo che tu possa correggere subito la configurazione del certificato; vedi [SSL certificate errors](#ssl-certificate-errors). Claude Code ritenta comunque condizioni TLS transitorie come un timeout di handshake. Prima della v2.1.199, Claude Code ritentava i guasti dei certificati attraverso il budget di riprovazione completo prima di mostrare l'errore.

296* Un errore del server, una connessione interrotta, o un flusso bloccato che arriva dopo che Claude ha completato un blocco di testo o una chiamata di strumento, o ne ha iniziato uno dopo aver finito il suo thinking, ma prima di finire la risposta. Claude Code non esegue nuovamente la richiesta, perché ciò potrebbe eseguire le stesse chiamate di strumento due volte. Mantiene ciò che Claude ha completato, esegue le chiamate di strumento che Claude ha finito, e continua il turno dai loro risultati. Per ciò che vedi in una sessione interattiva e in una non interattiva, leggi [The response above may be incomplete](#the-response-above-may-be-incomplete). Prima della v2.1.199, Claude Code scartava l'output parziale e segnalava l'intero turno come un errore quando un errore del server arrivava a metà del flusso.

297* Un guasto che arriva dopo che Claude ha finito la risposta: non c'è nulla da ritentare, quindi Claude Code mantiene la risposta completa e termina il turno normalmente.

298* Una [Amazon Bedrock streaming response with an unexpected content-type](#bedrock-streaming-response-has-an-unexpected-content-type), perché il gateway o il proxy che riscrive la risposta riscriverebbero il tentativo allo stesso modo. Richiede Claude Code v2.1.208 o successivo.

299* Un tentativo non in streaming di una richiesta in streaming non riuscita che ottiene uno stato di successo ma [no Claude API message in the body](#api-returned-an-empty-or-malformed-response). Claude Code termina il turno con quell'errore.

300* Una richiesta che il controllo della politica della tua organizzazione ha negato, che emerge come una riga `API Error:` che porta il messaggio di negazione. Gli amministratori della tua organizzazione hanno configurato il controllo con [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks), una funzione Claude Enterprise, e il messaggio termina con le istruzioni che hanno configurato, o per impostazione predefinita ti dice di contattarli. Claude Code non invia nuovamente la richiesta negata allo stesso modello o a un [fallback model](/docs/it/model-config#fallback-model-chains), perché il diniego riguarda il contenuto della richiesta piuttosto che il modello. Prima della v2.1.239, Claude Code poteva inviare nuovamente una richiesta negata, senza streaming o su un fallback model configurato, prima di mostrarti il diniego.

113 301

114Quando vedi uno degli errori in questa pagina, quei tentativi sono già stati esauriti, a meno che non appartenga a una classe che non viene ritentata, come un guasto di convalida del certificato. Puoi regolare il comportamento con queste variabili di ambiente:302<h3 id="what-you-see-while-claude-code-retries-or-waits">

303 Cosa vedi mentre Claude Code ritenta o attende

304</h3>

305

306Durante il tentativo, lo spinner mostra un countdown `Retrying in Ns · attempt x/y` dopo un'etichetta di errore. L'etichetta nomina il motivo specifico dal primo tentativo per i guasti su cui puoi agire subito: la rete è inattiva, un handshake TLS non è riuscito, o hai raggiunto un limite di velocità. Per altri errori legge `API error` all'inizio. A partire dalla v2.1.198 passa al motivo specifico dal terzo tentativo, o al tentativo finale quando `CLAUDE_CODE_MAX_RETRIES` consente meno di tre; le versioni precedenti passano solo al tentativo finale.

307

308A partire dalla v2.1.198, il suggerimento dello spinner usuale è soppresso durante i tentativi. Una volta rivelato il motivo dell'errore, se il guasto è un sovraccarico 529 la riga sotto il countdown nomina anche dove controllare lo stato del servizio: `status.claude.com` sull'API Anthropic, o l'host del provider o del gateway nominato nel messaggio su altre configurazioni.

309

310Se nessun dato arriva sul flusso di risposta per 20 secondi mentre una richiesta è ancora in sospeso, lo spinner mostra `Waiting for API response · will retry in … · check your network` prima che sia iniziato un tentativo. La richiesta non è ancora fallita: il countdown corre fino al punto in cui Claude Code interrompe la connessione bloccata. Dopo l'interruzione, ciò che vedi dipende da quanto lontano era arrivata la risposta:

311

312* Prima che Claude abbia completato un blocco di testo o una chiamata di strumento, o ne abbia iniziato uno dopo aver finito il suo thinking, Claude Code ritenta la richiesta o termina il turno con un errore. [Automatic retries](#automatic-retries) dice quali blocchi ritenta e quante volte.

313* Dopo che Claude ha completato un blocco di testo o una chiamata di strumento, o ne ha iniziato uno dopo aver finito il suo thinking, ma prima che Claude abbia finito la risposta, Claude Code mantiene ciò che Claude ha completato, continua il turno da qualsiasi chiamata di strumento che Claude ha finito, e mostra [The response above may be incomplete](#the-response-above-may-be-incomplete). In una sessione non interattiva, e per la risposta di un subagent in qualsiasi sessione, Claude Code potrebbe prima chiedere a Claude di continuare la risposta; quella voce dice quando lo fa e quando vedi ancora l'avviso lì.

314* Dopo che Claude ha finito la risposta, Claude Code termina il turno normalmente.

315

316Il banner si cancella da solo una volta che i dati riprendono o un tentativo ha successo. Se riappare ad ogni tentativo, trattalo come un [network issue](#unable-to-connect-to-api). Prima della v2.1.185, il banner appariva dopo 10 secondi con una formulazione diversa.

317

318Mentre Claude sta consultando l'[advisor](/docs/it/advisor), il banner appare dopo 90 secondi senza dati invece di 20, perché una lunga revisione dell'advisor può non inviare nulla per ben oltre 20 secondi. Prima della v2.1.214, la soglia di 20 secondi si applicava anche durante le chiamate dell'advisor, quindi il banner appariva durante le revisioni dell'advisor anche quando non c'era nulla di sbagliato.

319

320<h3 id="tune-retry-behavior">

321 Sintonizza il comportamento dei tentativi

322</h3>

323

324Puoi sintonizzare il comportamento dei tentativi con queste variabili di ambiente:

115 325

117| :------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |327| :---------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

118| [`CLAUDE_CODE_MAX_RETRIES`](/docs/it/env-vars) | 10 | Numero di tentativi di ripetizione. Limitato a 15 a partire da v2.1.186; a partire da v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` aumenta il valore predefinito e rimuove il limite. Abbassalo per far emergere i guasti più velocemente negli script. |328| [`CLAUDE_CODE_MAX_RETRIES`](/docs/it/env-vars) | 10 | Numero di tentativi di riprovazione. Limitato a 15 a partire dalla v2.1.186; a partire dalla v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` aumenta il valore predefinito e rimuove il limite. Abbassalo per far emergere i guasti più velocemente negli script. |

119| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/it/env-vars) | non impostato | Impostalo su `1` in sessioni incustodite come i job CI per ritentare gli errori di capacità `429` e `529` indefinitamente invece di fallire dopo i tentativi di `CLAUDE_CODE_MAX_RETRIES`. A partire da v2.1.199 aumenta anche il conteggio di tentativi predefinito per altri errori transitori, come errori del server, timeout e connessioni interrotte, a 300, approssimativamente tre ore di backoff, e rimuove il limite di 15 su `CLAUDE_CODE_MAX_RETRIES` se imposti esplicitamente quella variabile. |329| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/it/env-vars) | unset | Imposta su `1` in sessioni non presenziate come i lavori CI per ritentare gli errori di capacità `429` e `529` indefinitamente invece di fallire dopo `CLAUDE_CODE_MAX_RETRIES` tentativi. Claude Code fallisce immediatamente su un `429` che segnala un limite di spesa o crediti di utilizzo esauriti, anche uno da un [gateway spend cap](#spend-limit-reached) che si ripristina secondo una pianificazione. Prima della v2.1.239, il watchdog ritentava questi indefinitamente. Sulla v2.1.199 o successivo aumenta anche il conteggio dei tentativi predefinito per altri errori transitori, come errori del server, timeout e connessioni interrotte, a 300, approssimativamente tre ore di backoff, e rimuove il limite di 15 su `CLAUDE_CODE_MAX_RETRIES` se imposti esplicitamente quella variabile. |

120| [`API_TIMEOUT_MS`](/docs/it/env-vars) | 600000 | Timeout per richiesta in millisecondi. Aumentalo per reti lente o proxy. |330| [`API_TIMEOUT_MS`](/docs/it/env-vars) | 600000 | Timeout per richiesta in millisecondi. Aumentalo per reti lente o proxy. Limita anche quanto a lungo Claude Code attende le intestazioni di risposta, descritto in [No response from API](#no-response-from-api). |

331| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/it/env-vars) | unset | Scadenza in millisecondi per il primo byte di risposta di una richiesta di streaming. Richiede Claude Code v2.1.242 o successivo. Per come Claude Code sceglie la scadenza quando questo non è impostato, vedi [No response from API](#no-response-from-api). |

121 332

122<h2 id="server-errors">333<h2 id="server-errors">

123 Errori del server334 Errori del server

124</h2>335</h2>

125 336

126Questi errori provengono dal provider di inferenza piuttosto che dal vostro account o dalla vostra richiesta. Sull'API Anthropic significa l'infrastruttura Anthropic. Su Amazon Bedrock, Agent Platform di Google Cloud, Microsoft Foundry o un gateway personalizzato significa l'infrastruttura di quel provider.337La maggior parte di questi errori proviene dal provider di inferenza: il servizio Anthropic su Anthropic API e il servizio dietro l'endpoint di quel provider su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry o un gateway personalizzato. [Auto mode cannot determine the safety of an action](#auto-mode-cannot-determine-the-safety-of-an-action) e [Agent terminated early due to an API error](#agent-terminated-early-due-to-an-api-error) coprono anche cause dal vostro lato, come un account Amazon Bedrock che non può invocare il modello di classificazione o un subagent che ha raggiunto un limite di utilizzo.

127 338

128<h3 id="api-error-500-internal-server-error">339<h3 id="api-error-500-internal-server-error">

129 API Error: 500 Internal server error340 API Error: 500 Internal server error

130</h3>341</h3>

131 342

132Claude Code mostra il codice di stato e il messaggio di errore dell'API per qualsiasi risposta 5xx. L'esempio seguente mostra una risposta 500 sull'API Anthropic:343Claude Code mostra il codice di stato e il messaggio di errore dell'API per qualsiasi risposta 5xx. L'esempio seguente mostra una risposta 500 su Anthropic API:

133 344

134```text theme={null}345```text theme={null}

135API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.346API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

136```347```

137 348

138La frase finale indica dove controllare lo stato del servizio e varia in base al provider. Le configurazioni di Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry indicano lo stato del servizio di quel provider. Un `ANTHROPIC_BASE_URL` personalizzato indica l'host del gateway.349La frase finale indica dove controllare lo stato del servizio e varia in base al provider. Le configurazioni di Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry indicano lo stato del servizio di quel provider. Un `ANTHROPIC_BASE_URL` personalizzato indica l'host del gateway.

139 350

140Questo indica un errore imprevisto all'interno dell'API. Non è causato dal vostro prompt, dalle impostazioni o dall'account.351Questo indica un errore imprevisto all'interno dell'API. Non è causato dal vostro prompt, dalle impostazioni o dall'account.

141 352

142**Cosa fare:**353**Cosa fare:**

143 354

144* Controllate [status.claude.com](https://status.claude.com), o la pagina di stato del provider indicata nel messaggio, per gli incidenti attivi355* Controllate [status.claude.com](https://status.claude.com) o la pagina di stato del provider indicata nel messaggio per gli incidenti attivi

145* Aspettate un minuto, quindi inviate di nuovo il vostro messaggio. Il vostro messaggio originale è ancora nella conversazione, quindi per un prompt lungo potete digitare `try again` invece di incollare l'intera cosa.356* Aspettate un minuto, quindi inviate di nuovo il vostro messaggio. Il vostro messaggio originale è ancora nella conversazione, quindi per un prompt lungo potete digitare `try again` invece di incollare l'intera cosa.

146* Se l'errore persiste senza alcun incidente segnalato, eseguite `/feedback` in modo che Anthropic possa investigare con i dettagli della vostra richiesta. Consultate [Report an error](#report-an-error) se `/feedback` non è disponibile nel vostro ambiente.357* Se l'errore persiste senza alcun incidente pubblicato, eseguite `/feedback` in modo che Anthropic possa investigare con i dettagli della vostra richiesta. Vedete [Report an error](#report-an-error) se `/feedback` non è disponibile nel vostro ambiente.

147 358

148<h3 id="api-error-repeated-529-overloaded-errors">359<h3 id="api-error-repeated-529-overloaded-errors">

149 API Error: Repeated 529 Overloaded errors360 API Error: Repeated 529 Overloaded errors

150</h3>361</h3>

151 362

152L'API è temporaneamente al massimo della capacità per tutti gli utenti. Claude Code ha già ritentato più volte prima di mostrare questo messaggio:363L'API è temporaneamente al massimo della capacità per tutti gli utenti. Claude Code ha già riprovato più volte prima di mostrare questo messaggio:

153 364

154```text theme={null}365```text theme={null}

155API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.366API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

161 372

162**Cosa fare:**373**Cosa fare:**

163 374

164* Controllate [status.claude.com](https://status.claude.com), o la pagina di stato del provider indicata nel messaggio, per gli avvisi di capacità375* Controllate [status.claude.com](https://status.claude.com) o la pagina di stato del provider indicata nel messaggio per gli avvisi di capacità

165* Ritentate tra pochi minuti376* Riprovate tra pochi minuti

166* Eseguite `/model` e passate a un modello diverso per continuare a lavorare, poiché la capacità è tracciata per modello. Claude Code vi chiede di farlo quando un modello è sotto un carico particolarmente elevato, ad esempio `Opus is experiencing high load, please use /model to switch to Sonnet`.377* Eseguite `/model` e passate a un modello diverso per continuare a lavorare, poiché la capacità è tracciata per modello. Claude Code vi chiede di farlo quando un modello è sotto un carico particolarmente elevato, ad esempio `Opus is experiencing high load, please use /model to switch to Sonnet`.

167 378

168<h3 id="request-timed-out">379<h3 id="request-timed-out">

179 390

180**Cosa fare:**391**Cosa fare:**

181 392

182* Ritentate la richiesta393* Riprovate la richiesta

183* Per attività di lunga durata, suddividete il lavoro in prompt più piccoli394* Per attività di lunga durata, suddividete il lavoro in prompt più piccoli

184* Se la causa è una rete lenta o un proxy, aumentate `API_TIMEOUT_MS` come descritto in [Automatic retries](#automatic-retries)395* Se la causa è una rete lenta o un proxy, aumentate `API_TIMEOUT_MS` come descritto in [Automatic retries](#automatic-retries)

185* Se i timeout sono frequenti e la vostra rete è altrimenti sana, consultate [Network and connection errors](#network-and-connection-errors) di seguito396* Se i timeout sono frequenti e la vostra rete è altrimenti sana, vedete [Network and connection errors](#network-and-connection-errors) di seguito

397

398<h3 id="no-response-from-api">

399 No response from API

400</h3>

401

402Claude Code ha inviato una richiesta di streaming e l'API non ha restituito intestazioni di risposta entro la scadenza per il primo byte, quindi Claude Code ha interrotto la richiesta invece di aspettare il timeout di richiesta completo `API_TIMEOUT_MS`, 10 minuti per impostazione predefinita. Claude Code invia di nuovo la richiesta al massimo una volta, se il [retry budget](#tune-retry-behavior) lo consente. Quando il nuovo tentativo rimane senza risposta, il turno termina con questo messaggio, che mostra quanto tempo ha aspettato ogni tentativo. Quando impostate [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/it/env-vars), il limite di un nuovo tentativo non si applica e Claude Code riprova secondo il budget descritto in [Tune retry behavior](#tune-retry-behavior).

403

404```text theme={null}

405API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

406```

407

408Claude Code imposta l'attesa per le intestazioni di risposta del primo tentativo e l'attesa del nuovo tentativo separatamente:

409

410* **First attempt**: [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/it/env-vars) quando lo impostate su 1 o più, limitato tra 10 secondi e 30 minuti. Altrimenti Claude Code utilizza il timeout del watchdog a livello di byte elencato in [Streaming idle watchdogs](/docs/it/network-config#streaming-idle-watchdogs), quindi le variabili che cambiano quel timeout cambiano anche questa attesa. In entrambi i casi, Claude Code aggiunge un secondo per ogni 32KB del corpo della richiesta.

411* **Retry**: un secondo in meno di `API_TIMEOUT_MS`, poco meno di 10 minuti per impostazione predefinita, in modo che il nuovo tentativo possa durare più a lungo di un proxy o gateway che tiene la risposta fino al completamento della generazione. Su Amazon Bedrock, il nuovo tentativo utilizza la stessa scadenza del primo tentativo e il messaggio mostra una durata invece di due.

412

413Nessuna attesa supera un secondo in meno di un `API_TIMEOUT_MS` positivo, e un `API_TIMEOUT_MS` positivo inferiore a 11 secondi disattiva la scadenza. Il watchdog a livello di byte inizia solo una volta che le intestazioni di risposta arrivano, quindi una risposta che smette di inviare byte dopo quello segue le [stalled-stream rules](#automatic-retries) invece di questa scadenza.

414

415**Cosa fare:**

416

417* Inviate di nuovo il vostro messaggio. Il vostro messaggio originale è ancora nella conversazione, quindi per un prompt lungo potete digitare `try again` invece di incollare l'intera cosa.

418* Se si ripete, trattarlo come un [network or proxy problem](#unable-to-connect-to-api). Un proxy che accetta la connessione e non invia mai la richiesta produce questo errore ad ogni tentativo.

419* Se un proxy o gateway sulla vostra rete tiene le risposte fino al completamento, aumentate `API_TIMEOUT_MS` in modo che il nuovo tentativo aspetti più a lungo. Su Amazon Bedrock, aumentate anche `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`.

420* Se il primo tentativo continua a scadere e il nuovo tentativo ha successo, aumentate `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` in modo che il primo tentativo aspetti abbastanza a lungo.

421

422Prima della v2.1.242, Claude Code aspettava il timeout di richiesta completo `API_TIMEOUT_MS`, 10 minuti per impostazione predefinita, prima di fallire una richiesta di streaming senza risposta. Prima della v2.1.261, il nuovo tentativo aspettava la stessa scadenza del primo tentativo e il messaggio non mostrava durate.

186 423

187<h3 id="the-response-above-may-be-incomplete">424<h3 id="the-response-above-may-be-incomplete">

188 The response above may be incomplete425 The response above may be incomplete

189</h3>426</h3>

190 427

191Una risposta in streaming non è riuscita dopo che Claude aveva già prodotto un output visibile. L'invio nuovamente della richiesta potrebbe eseguire le stesse chiamate di strumento due volte, quindi Claude Code mantiene ciò che è già stato trasmesso e aggiunge questo avviso invece di scartare il turno. La variante che vedete indica la causa:428Una richiesta di streaming non è riuscita mentre la risposta era ancora in corso, dopo che Claude aveva completato un blocco di testo o una chiamata di strumento, o ne aveva iniziato uno dopo aver terminato il suo pensiero. L'invio di nuovo della richiesta potrebbe eseguire le stesse chiamate di strumento due volte, quindi Claude Code mantiene l'output che Claude ha completato e aggiunge questo avviso invece di scartare il turno. Quale variante vedete indica la causa:

192 429

193```text theme={null}430```text theme={null}

194API Error: Server error mid-response. The response above may be incomplete.431API Error: Server error mid-response. The response above may be incomplete.

195API Error: Connection closed mid-response. The response above may be incomplete.432API Error: Connection lost mid-response. The response above may be incomplete.

196API Error: Response stalled mid-stream. The response above may be incomplete.433API Error: Your computer went to sleep mid-response. The response above may be incomplete.

434API Error: The response stopped arriving. The response above may be incomplete.

197```435```

198 436

199* `Server error mid-response`: un errore di server sovraccarico o 5xx a metà flusso. Questa variante richiede Claude Code v2.1.199 o successivo; prima di allora quel caso scartava l'output parziale e segnalava l'intero turno come errore.437* `Server error mid-response`: un errore del server di sovraccarico o 5xx a metà flusso. Questa variante richiede Claude Code v2.1.199 o successivo; prima di allora quel caso scartava l'output parziale e segnalava l'intero turno come errore.

200* `Connection closed mid-response`: la connessione è stata interrotta.438* `Connection lost mid-response`: la connessione è stata interrotta.

201* `Response stalled mid-stream`: il flusso ha smesso di inviare dati.439* `Your computer went to sleep mid-response`: Claude Code ha rilevato che il vostro computer si è addormentato mentre la risposta era in streaming. Una volta che il vostro computer si sveglia, Claude Code tratta la connessione come interrotta e smette di leggerla.

440* `The response stopped arriving`: la connessione è rimasta aperta ma ha smesso di consegnare dati, quindi il watchdog di inattività dello streaming l'ha interrotta. Prima della v2.1.222, Claude Code poteva anche segnalare questo errore su connessioni [gateway](/docs/it/gateways) raggiunte tramite `ANTHROPIC_BASE_URL` o `ANTHROPIC_AWS_BASE_URL` mentre i ping keep-alive del server stavano ancora arrivando, perché contava solo gli eventi di risposta analizzati lì; l'aggiornamento interrompe quei timeout spuri su quelle rotte. I gateway raggiunti tramite un URL di base del provider come `ANTHROPIC_BEDROCK_BASE_URL` non sono avvolti dal watchdog di byte; vedete [Streaming idle watchdogs](/docs/it/network-config#streaming-idle-watchdogs).

441

442Prima della v2.1.227, `Connection lost mid-response` leggeva `Connection closed mid-response` e `The response stopped arriving` leggeva `Response stalled mid-stream`.

443

444In quattro casi, Claude Code gestisce l'errore senza mostrare questo avviso subito:

445

446* Più in alto nella risposta, Claude Code riprova l'errore o termina il turno con un errore diverso. Vedete [Automatic retries](#automatic-retries).

447* Quando uno di questi errori arriva dopo che Claude ha terminato la risposta, Claude Code mantiene la risposta completa e termina il turno normalmente, senza questo avviso. Prima della v2.1.222, Claude Code mostrava questo avviso quando la connessione veniva interrotta o si bloccava dopo il completamento della risposta e segnalava il turno come errore anche se la risposta era completa.

448* In una [non-interactive session](/docs/it/headless), come una esecuzione `-p`, un'esecuzione [Agent SDK](/docs/it/agent-sdk/overview) o una [cloud session](/docs/it/claude-code-on-the-web), non dovete inviare `continue` voi stessi quando la risposta tagliata è nella conversazione principale e contiene testo ma nessuna chiamata di strumento: Claude Code mantiene l'output parziale e chiede a Claude di continuare da dove si è fermato, fino a tre volte di seguito. Vedete questo avviso per tale risposta solo una volta che Claude Code ha esaurito quelle continuazioni. Prima della v2.1.246, Claude Code terminava un turno non interattivo con questo avviso al primo taglio.

449* In un [subagent](/docs/it/sub-agents#api-errors-in-subagents), indipendentemente dal fatto che la sessione sia interattiva o meno: quando la sua risposta tagliata contiene testo ma nessuna chiamata di strumento, Claude Code chiede al subagent di continuare. L'avviso diventa l'ultimo messaggio del subagent solo una volta che quelle continuazioni sono esaurite. Prima della v2.1.257, un subagent mostrava questo avviso al primo taglio.

202 450

203**Cosa fare:**451**Cosa fare:**

204 452

205* Leggete la risposta che è stata trasmessa. Nulla è stato perso, ma le frasi finali o le chiamate di strumento potrebbero mancare.453* In una sessione interattiva, leggete la risposta che rimane sullo schermo: Claude Code mantiene ogni blocco che Claude ha completato prima dell'errore, ma scarta un blocco finale interrotto quando il turno termina, quindi le frasi o le chiamate di strumento finali potrebbero mancare. Rispondete con `continue` per far riprendere a Claude dal suo ultimo blocco completato.

206* Rispondete con `continue` per fare in modo che Claude riprenda da dove si era fermato454* In [non-interactive mode](/docs/it/headless) (`-p`):

207* Se lo stesso errore appare prima di qualsiasi output visibile, Claude Code ritenta la richiesta invece di finalizzarla. Consultate [Automatic retries](#automatic-retries).455 * Con l'output di testo predefinito, Claude Code stampa l'ultimo blocco di testo completato che ancora mantiene da prima nel turno, seguito da questo messaggio. Quando non ne mantiene nessuno, Claude Code stampa solo questo messaggio, ad esempio perché Claude Code ha compattato la conversazione a metà turno e ha cancellato quel testo. Prima della v2.1.219, Claude Code stampava solo questo messaggio nell'output di testo `-p` e scartava la risposta che aveva già prodotto.

456 * Con `--output-format json` o `stream-json`, Claude Code segnala questo messaggio nel campo `result`.

457 * Per continuare il turno una volta che la connessione è stabile, riprendete la sessione e inviate `continue` come descritto in [Continue conversations](/docs/it/headless#continue-conversations).

208 458

209<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">459<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

210 Auto mode cannot determine the safety of an action460 Auto mode cannot determine the safety of an action

211</h3>461</h3>

212 462

213Il modello che [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) utilizza per classificare le azioni non ha potuto produrre una decisione, quindi auto mode non ha approvato l'azione automaticamente. Il messaggio che vedete dipende dal motivo per cui il classificatore non è riuscito.463Il modello che [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) utilizza per classificare le azioni non poteva produrre una decisione, quindi auto mode non ha approvato l'azione automaticamente. Il messaggio che vedete dipende da come il classificatore non è riuscito.

214 464

215Le letture, le ricerche e le modifiche all'interno della vostra directory di lavoro saltano il classificatore, quindi continuano a funzionare in tutti questi casi.465Le letture, le ricerche e le modifiche all'interno della vostra directory di lavoro saltano il classificatore, quindi continuano a funzionare in tutti questi casi.

216 466

217Quando il modello classificatore è sovraccarico:467Quando il modello di classificazione non è disponibile:

218 468

219```text theme={null}469```text theme={null}

220<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.470<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

221```471```

222 472

473Quando Claude Code può determinare la categoria di errore, la nomina tra parentesi dopo `temporarily unavailable`, ad esempio `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`. Le categorie sono `(rate-limited)`, `(overloaded)`, `(server error)`, `(timed out)` e `(connection failed)`. I limiti di velocità, il sovraccarico e gli errori del server sono transitori e il nuovo tentativo funziona. Se `(timed out)` o `(connection failed)` si ripete, controllate la vostra connessione; vedete [Unable to connect to API](#unable-to-connect-to-api). Prima della v2.1.229, il messaggio non nominava mai una categoria e leggeva `Wait briefly and then try this action again`.

474

475Quando nessuna categoria si adatta, il messaggio appare senza categoria tra parentesi; più di un errore produce quella forma. Su [Amazon Bedrock](/docs/it/amazon-bedrock), incluso l'[Mantle endpoint](/docs/it/amazon-bedrock#use-the-mantle-endpoint), appare anche quando il vostro account AWS non può invocare il modello indicato nel messaggio e quel fallimento si ripete ad ogni nuovo tentativo fino a quando al vostro account non viene concesso l'accesso al modello.

476

223**Cosa fare:**477**Cosa fare:**

224 478

225* Ritentate dopo pochi secondi; Claude vede lo stesso messaggio e di solito ritenta da solo479* Riprovate dopo pochi secondi; Claude vede lo stesso messaggio e di solito riprova da solo. Un errore transitorio non è correlato all'[auto mode eligibility](/docs/it/permission-modes#eliminate-prompts-with-auto-mode); non dovete cambiare le impostazioni

226* Se i tentativi continuano a fallire, continuate con attività di sola lettura e tornate all'azione bloccata in seguito480* Se i nuovi tentativi continuano a fallire, continuate con attività di sola lettura e tornate all'azione bloccata in seguito

227* Questo è transitorio e non correlato all'[idoneità di auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode); non è necessario modificare le impostazioni481* Su Amazon Bedrock, se il messaggio ritorna ad ogni nuovo tentativo, controllate che il vostro account possa invocare il modello che nomina: per i modelli Amazon Bedrock standard, confermate che la vostra [IAM policy](/docs/it/amazon-bedrock#iam-configuration) consente di invocarlo; per gli ID modello Mantle, [contattate il vostro team di account AWS](/docs/it/amazon-bedrock#mantle-endpoint-errors)

482

483Quando una richiesta di classificazione non riesce perché il vostro token OAuth è scaduto o è stato ruotato da un'altra sessione, Claude Code aggiorna il token e riprova la richiesta una volta, quindi una scadenza di token di routine non emerge come questo messaggio. Prima della v2.1.216, un token scaduto o ruotato non riusciva ad ogni richiesta di classificazione e auto mode negava ogni azione controllata con questo messaggio fino a quando il token non veniva aggiornato.

228 484

229Quando il classificatore ha restituito una risposta non analizzabile:485Quando il classificatore ha restituito una risposta non analizzabile:

230 486

234 490

235**Cosa fare:**491**Cosa fare:**

236 492

237* Ritentate l'azione; di solito ha successo al tentativo successivo493* Riprovate l'azione; questo di solito ha successo al tentativo successivo

238* Eseguite `claude --debug` e ripetete l'azione per vedere la risposta del classificatore sottostante nel log di debug494* Eseguite `claude --debug` e ripetete l'azione per vedere la risposta del classificatore sottostante nel registro di debug

239 495

240Quando un controllo di sicurezza API separato ha bloccato la richiesta del classificatore a causa del contenuto della conversazione precedente:496Quando un controllo di sicurezza API separato ha bloccato la richiesta del classificatore a causa del contenuto della conversazione precedente:

241 497

243Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details499Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

244```500```

245 501

502Claude Code nega l'azione ma dice a Claude che questo non è un giudizio che l'azione sia pericolosa e di continuare con altri compiti piuttosto che riprovare. Questi rifiuti non contano verso le [auto mode's pause thresholds](/docs/it/permission-modes#when-auto-mode-falls-back). In un'esecuzione `-p` [non-interactive](/docs/it/headless), Claude Code non interrompe l'esecuzione. Quello che Claude riceve dipende da dove ha richiesto l'azione:

503

504* A un [background subagent](/docs/it/sub-agents#run-subagents-in-foreground-or-background) in un'esecuzione `-p` senza `--input-format stream-json`, Claude Code restituisce un risultato di errore contenente `Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode`

505* Ovunque, incluse le sessioni interattive e la conversazione principale di un'esecuzione `-p`, Claude Code restituisce quel rifiuto a Claude

506

507Prima della v2.1.225, Claude Code contava questi rifiuti verso le soglie di pausa e restituiva lo stesso messaggio di rifiuto di un blocco di classificatore genuino.

508

246**Cosa fare:**509**Cosa fare:**

247 510

248* Questa non è una decisione sulla vostra azione. Il contenuto già nella vostra conversazione ha attivato un filtro di sicurezza sull'API quando auto mode ha inviato la conversazione al classificatore511* Questo non è un giudizio sulla vostra azione. Il contenuto già nella vostra conversazione ha attivato un filtro di sicurezza sull'API quando auto mode ha inviato la conversazione al classificatore

249* Ritentare non aiuterà; lo stesso contenuto della conversazione attiverà di nuovo il filtro512* Riprovare non aiuterà; lo stesso contenuto della conversazione attiverà di nuovo il filtro

250* Passate a una [modalità di autorizzazione](/docs/it/permission-modes) diversa in modo da poter approvare l'azione quando richiesto, o iniziate una conversazione nuova senza il contenuto che attiva il filtro513* In una sessione interattiva, passate a una [permission mode](/docs/it/permission-modes) diversa in modo da poter approvare l'azione quando richiesto

514* Iniziate una conversazione nuova senza il contenuto che attiva

251 515

252Quando la conversazione è cresciuta oltre la finestra di contesto del classificatore:516Quando la conversazione è cresciuta più grande della finestra di contesto del classificatore:

253 517

254```text theme={null}518```text theme={null}

255Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)519Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

256```520```

257 521

258In una sessione interattiva, auto mode ritorna a un normale prompt di autorizzazione per quell'azione in modo da poter approvare o negare manualmente. In [modalità non interattiva](/docs/it/headless) l'esecuzione si interrompe perché la trascrizione cresce solo e ritentare non può avere successo.522Quello che accade all'azione dipende da dove Claude l'ha richiesta:

523

524* In una sessione interattiva, auto mode torna a un normale prompt di autorizzazione per quell'azione in modo da poter approvarla o negarla manualmente

525* A un [background subagent](/docs/it/sub-agents#run-subagents-in-foreground-or-background) in un'esecuzione `-p` [non-interactive](/docs/it/headless) senza `--input-format stream-json`, Claude Code restituisce un risultato di errore contenente `Agent aborted: auto mode classifier transcript exceeded context window in headless mode` e l'esecuzione continua

526* Altrove in un'esecuzione `-p` senza un [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags), non c'è alcun prompt a cui tornare, quindi l'azione non viene eseguita e l'esecuzione continua

259 527

260**Cosa fare:**528**Cosa fare:**

261 529

262* Approvate o negate l'azione nel prompt che appare530* In una sessione interattiva, approvate o negate l'azione nel prompt che appare

263* Eseguite `/compact` per ridurre la dimensione della conversazione in modo che le azioni successive si adattino di nuovo alla finestra del classificatore531* In una sessione interattiva, eseguite `/compact` per ridurre la dimensione della conversazione in modo che le azioni successive si adattino di nuovo alla finestra del classificatore

264 532

265<h3 id="agent-terminated-early-due-to-an-api-error">533<h3 id="agent-terminated-early-due-to-an-api-error">

266 Agent terminated early due to an API error534 Agent terminated early due to an API error

267</h3>535</h3>

268 536

269La richiesta API di un [subagent](/docs/it/sub-agents) non è riuscita in modo terminale, ad esempio perché è stato raggiunto un limite di utilizzo o i tentativi per un errore del server si sono esauriti, quindi il subagent si è fermato prima di completare il suo compito. Questo messaggio richiede Claude Code v2.1.199 o successivo; prima di allora il testo di errore dell'API è stato restituito a Claude come se fosse il risultato del subagent.537Una richiesta API di un [subagent](/docs/it/sub-agents) non è riuscita in modo terminale, ad esempio perché è stato raggiunto un limite di utilizzo o i nuovi tentativi per un errore del server sono esauriti, quindi il subagent si è fermato prima di completare il suo compito. Questo messaggio richiede Claude Code v2.1.199 o successivo; prima di allora il testo di errore dell'API veniva restituito a Claude come se fosse il risultato del subagent.

270 538

271```text theme={null}539```text theme={null}

272Agent terminated early due to an API error: <error detail>540Agent terminated early due to an API error: <error detail>

275**Cosa fare:**543**Cosa fare:**

276 544

277* Abbinate il dettaglio dell'errore dopo i due punti alla sua sezione su questa pagina, come [Usage limits](#usage-limits) o [Server errors](#server-errors), e seguite i passaggi di quella sezione545* Abbinate il dettaglio dell'errore dopo i due punti alla sua sezione su questa pagina, come [Usage limits](#usage-limits) o [Server errors](#server-errors), e seguite i passaggi di quella sezione

278* Una volta che l'errore sottostante si risolve, chiedete a Claude di ritentare il compito o [riprendere il subagent](/docs/it/sub-agents#resume-subagents)546* Una volta che l'errore sottostante si risolve, chiedete a Claude di riprovare il compito o di [resume the subagent](/docs/it/sub-agents#resume-subagents)

279 547

280Quando un limite di velocità, un sovraccarico o un errore del server interrompe un subagent in primo piano che ha già prodotto un output di testo, Claude riceve quell'output parziale contrassegnato come incompleto invece di questo errore. Un subagent il cui unico output era chiamate di strumento riceve anche questo errore; nella v2.1.199 quella forma ha restituito un risultato parziale vuoto. Consultate [API errors in subagents](/docs/it/sub-agents#api-errors-in-subagents).548Quando un limite di velocità, sovraccarico o errore del server interrompe un subagent in primo piano che ha già prodotto output di testo, Claude riceve quell'output parziale contrassegnato come incompleto invece di questo errore. Un subagent il cui unico output era chiamate di strumento riceve anche questo errore; nella v2.1.199 quella forma restituiva un risultato parziale vuoto. Vedete [API errors in subagents](/docs/it/sub-agents#api-errors-in-subagents).

281 549

282<h2 id="usage-limits">550<h2 id="usage-limits">

283 Limiti di utilizzo551 Limiti di utilizzo

284</h2>552</h2>

285 553

286Questi errori significano che è stata raggiunta una quota associata al vostro account o piano. Sono distinti dagli [errori del server](#server-errors), che interessano tutti.554La maggior parte degli errori in questa sezione significa che è stata raggiunta una quota associata al tuo account o al tuo piano. Tre funzionano diversamente: [`Server is temporarily limiting requests`](#server-is-temporarily-limiting-requests) è una limitazione lato server non correlata alla quota del tuo piano, [`Usage credits required for 1M context`](#usage-credits-required-for-1m-context) è un controllo di diritto piuttosto che una quota esaurita, e [`The prompt to confirm went unanswered`](#the-prompt-to-confirm-went-unanswered) significa che un prompt di consenso per i crediti di utilizzo è stato chiuso senza risposta, indipendentemente dal fatto che sia stata raggiunta una quota.

287 555

288<h3 id="youve-hit-your-session-limit">556<h3 id="youve-hit-your-session-limit">

289 Avete raggiunto il vostro limite di sessione557 You've hit your session limit

290</h3>558</h3>

291 559

292I piani di abbonamento includono un'indennità di utilizzo mobile. Quando si esaurisce, vedete uno di questi messaggi:560I piani di abbonamento includono un'indennità di utilizzo mobile. Quando si esaurisce, vedrai uno di questi messaggi:

293 561

294```text theme={null}562```text theme={null}

295You've hit your session limit · resets 3:45pm563You've hit your session limit · resets 3:45pm

296You've hit your weekly limit · resets Mon 12:00am564You've hit your weekly limit · resets Mon 12:00am

297You've hit your Opus limit · resets 3:45pm565You've hit your Opus limit · resets 3:45pm

566You've hit your Sonnet limit · resets 3:45pm

298```567```

299 568

300Claude Code blocca ulteriori richieste fino all'ora di ripristino mostrata nel messaggio. I limiti di sessione e settimanali sono condivisi tra tutti i modelli, quindi il cambio di modello non ripristina l'accesso. Il limite di Opus si applica solo alle richieste di Opus, quindi il passaggio a un altro modello con `/model` vi permette di continuare a lavorare.569Claude Code blocca ulteriori richieste fino all'ora di ripristino mostrata nel messaggio. I limiti di sessione e settimanali sono condivisi tra tutti i modelli, quindi il cambio di modelli non ripristina l'accesso. I limiti Opus e Sonnet si applicano ciascuno solo alle richieste a quella famiglia di modelli, quindi il passaggio a un modello al di fuori della famiglia con `/model` ti mantiene al lavoro.

570

571In una sessione interattiva con accesso tramite abbonamento claude.ai, Claude Code può anche attendere nella sessione aperta e continuare l'attività interrotta poco dopo il ripristino. Mentre attende, una riga in fondo alla sessione legge `Usage limit reached · continuing automatically at 3:45pm · esc to cancel`. Premi `Esc` a un prompt vuoto per annullare l'attesa. Vedi [Wait for a usage limit to reset](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) per quello che vedi, come avviare o annullare un'attesa e come disattivare la continuazione automatica. Prima della v2.1.234, Claude Code non offriva questa attesa.

301 572

302L'utilizzo conta contemporaneamente sulle indennità di sessione e settimanali. Un singolo picco di attività intensa, come un ampio fanout di flusso di lavoro, può esaurire l'indennità settimanale prima che la finestra di sessione si ripristini.573L'utilizzo conta sia per le indennità di sessione che settimanali contemporaneamente. Un singolo picco di attività intensa, come un grande fanout di flusso di lavoro, può esaurire l'indennità settimanale prima che la finestra di sessione si ripristini.

303 574

304**Cosa fare:**575**Cosa fare:**

305 576

306* Attendete l'ora di ripristino mostrata nell'errore577* Attendi l'ora di ripristino mostrata nell'errore

307* Per il limite di Opus, eseguite `/model` e passate a un altro modello per continuare a lavorare578* Nella scheda Code dell'[app Desktop](/docs/it/desktop), la scheda session-limit offre una casella di controllo **Auto-continue when limits reset**. La scheda weekly-limit non lo fa. Quando è selezionata, l'app Desktop ritenta il turno interrotto dopo il ripristino e mostra l'ora del nuovo tentativo sulla scheda. La casella di controllo Desktop e l'impostazione **Continue automatically at usage limit** della CLI in `/config` sono separate, quindi disattiva ciascuna per conto proprio.

308* Eseguite `/usage` per vedere i vostri limiti di piano e quando si ripristinano579* Per il limite Opus o Sonnet, esegui `/model` e passa a un modello al di fuori di quella famiglia per continuare a lavorare. Ogni modello ha la propria cache di prompt, quindi la richiesta successiva rilegge l'intera conversazione senza hit della cache; vedi [Switching models](/docs/it/prompt-caching#switching-models)

309* Eseguite `/usage-credits` per acquistare utilizzo aggiuntivo su Pro e Max, o per richiederlo al vostro amministratore su Team ed Enterprise. Consultate [usage credits per piani a pagamento](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) per informazioni su come viene fatturato.580* Esegui `/usage` per vedere i limiti del tuo piano e quando si ripristinano

310* Per aggiornare il vostro piano per limiti di base più elevati, consultate [claude.com/pricing](https://claude.com/pricing)581* Esegui `/usage-credits` per acquistare utilizzo aggiuntivo su Pro e Max, o per richiederlo al tuo amministratore su Team ed Enterprise. Vedi [usage credits for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) per come viene fatturato.

582* Per aggiornare il tuo piano per limiti di base più elevati, vedi [claude.com/pricing](https://claude.com/pricing)

311 583

312Per monitorare l'indennità rimanente prima di raggiungere il limite, aggiungete i campi `rate_limits` a una [riga di stato personalizzata](/docs/it/statusline#rate-limit-usage), oppure nell'app Desktop fate clic sull'[anello di utilizzo](/docs/it/desktop#check-usage) accanto al selettore di modello.584Per monitorare l'indennità rimanente prima di raggiungere il limite, aggiungi i campi `rate_limits` a una [riga di stato personalizzata](/docs/it/statusline#rate-limit-usage), oppure nell'app Desktop fai clic sull'[anello di utilizzo](/docs/it/desktop#check-usage) accanto al selettore di modelli.

313 585

314<h3 id="usage-credits-required-for-1m-context">586<h3 id="usage-credits-required-for-1m-context">

315 Crediti di utilizzo richiesti per il contesto 1M587 Usage credits required for 1M context

316</h3>588</h3>

317 589

318Il modello selezionato utilizza la finestra di contesto estesa da 1M token, e il vostro piano lo include solo tramite crediti di utilizzo.590Il modello selezionato utilizza la finestra di contesto estesa da 1M token e il tuo piano lo include solo tramite crediti di utilizzo.

319 591

320```text theme={null}592```text theme={null}

321API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context593API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

322```594```

323 595

324Questo è un controllo di diritto, non un esaurimento della quota. Si attiva anche quando le vostre indennità di sessione e settimanali hanno capacità rimanente. Consultate [Extended context](/docs/it/model-config#extended-context) per sapere quali piani includono il contesto 1M direttamente e quali richiedono crediti di utilizzo.596Questo è un controllo di diritto, non un esaurimento della quota. Si attiva anche quando le tue indennità di sessione e settimanali hanno capacità rimanente. Vedi [Extended context](/docs/it/model-config#extended-context) per quali piani includono il contesto 1M direttamente e quali richiedono crediti di utilizzo. Claude Code esegue questo controllo quando scegli il modello con `/model`, e solo su una connessione diretta all'API Anthropic; se punti `ANTHROPIC_BASE_URL` a un [gateway LLM](/docs/it/llm-gateway), `/model` consente la selezione `[1m]` e il gateway decide se la richiesta ha successo.

597

598Quando questo errore appare a metà conversazione perché il contesto è cresciuto oltre 200K token, Claude Code compatta automaticamente la conversazione al di sotto del limite di contesto standard e mantiene la sessione a quel limite in seguito, quindi non è necessaria alcuna azione. Nelle versioni precedenti alla v2.1.172, l'errore si ripeteva su ogni richiesta successiva incluso `/compact`; esegui `/clear` su quelle versioni per recuperare. I passaggi seguenti si applicano quando hai esplicitamente selezionato un modello `[1m]`.

599

600**Cosa fare:**

601

602* Esegui `/model` e seleziona la variante senza il suffisso `[1m]` per tornare alla finestra di contesto standard

603* Dove il messaggio nomina `/usage-credits`, eseguilo per attivare la fatturazione a consumo per la variante 1M su Pro e Max, o per richiedere crediti di utilizzo al tuo amministratore su Team ed Enterprise

604* Se l'errore persiste dopo `/model`, un ID modello 1M potrebbe essere impostato altrove. Vedi [Setting your model](/docs/it/model-config#setting-your-model) per i percorsi di configurazione da controllare in ordine di priorità.

605* Per rimuovere completamente le varianti 1M dal selettore di modelli, imposta [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/it/env-vars)

606

607<h3 id="the-prompt-to-confirm-went-unanswered">

608 The prompt to confirm went unanswered

609</h3>

610

611Se il tuo account richiede il [consenso per i crediti di utilizzo Fable](/docs/it/model-config#fable-and-usage-credits), Claude Code ti chiede di confermare prima che una richiesta Fable fatturi i crediti di utilizzo. Quando nessuno risponde a quel prompt di consenso in una sessione che potrebbe non avere nessuno al suo terminale, Claude Code chiude il prompt e termina il turno con uno di questi messaggi:

612

613```text theme={null}

614Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

615Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

616```

617

618I messaggi nominano il modello Fable della sessione, quindi su Fable 5 leggono `continuing on Fable 5` e `Fable 5 now uses usage credits`. Prima della v2.1.257, il primo messaggio iniziava `Fable 5 limit reached`.

325 619

326Quando questo errore appare a metà conversazione perché il contesto è cresciuto oltre i 200K token, Claude Code compatta automaticamente la conversazione al di sotto del limite di contesto standard e mantiene la sessione a quel limite in seguito, quindi non è necessaria alcuna azione. Nelle versioni precedenti a v2.1.172, l'errore si ripeteva su ogni richiesta successiva incluso `/compact`; eseguite `/clear` su quelle versioni per recuperare. I passaggi seguenti si applicano quando avete esplicitamente selezionato un modello `[1m]`.620Questo accade nelle sessioni [Remote Control](/docs/it/remote-control), [sessioni in background](/docs/it/agent-view) e sessioni compagni [team agente](/docs/it/agent-teams). Claude Code mostra il prompt di consenso solo nella vista interattiva della sessione: il terminale dove viene eseguito, o, per una sessione in background, la [vista agenti](/docs/it/agent-view) una volta che ti colleghi. Un client Remote Control non può visualizzarlo. Claude Code chiude il prompt alla scadenza [`dialogExpiry`](/docs/it/settings-reference#dialogexpiry), cinque minuti per impostazione predefinita, o non appena arriva un nuovo prompt mentre nessuno ha digitato a quel terminale, come un prompt inviato da un client Remote Control. Digitare al terminale dove viene eseguita la sessione annulla la scadenza, e Claude Code attende la tua risposta. Nella vista allegata di una sessione in background, digitare non annulla la scadenza, e un nuovo prompt chiude comunque il prompt di consenso, quindi rispondi prima che accada uno dei due. Claude Code non invia nulla e mantiene il tuo modello, quindi quando invii il tuo prossimo prompt, Claude Code mostra di nuovo il prompt di consenso.

327 621

328**Cosa fare:**622**Cosa fare:**

329 623

330* Eseguite `/model` e selezionate la variante senza il suffisso `[1m]` per tornare alla finestra di contesto standard624* Al terminale dove viene eseguita la sessione, invia un altro prompt e rispondi al prompt di consenso quando riappare. Per una sessione in background, collegati prima dalla [vista agenti](/docs/it/agent-view). Reinviare da un client Remote Control mostra di nuovo questo messaggio, perché il client non può visualizzare il prompt.

331* Eseguite `/usage-credits` per attivare la fatturazione a consumo per la variante 1M su Pro e Max, o per richiederla al vostro amministratore su Team ed Enterprise625* Esegui `/model` per passare a un modello che non fattura i crediti di utilizzo

332* Se l'errore persiste dopo `/model`, un ID modello 1M potrebbe essere impostato altrove. Consultate [There's an issue with the selected model](#theres-an-issue-with-the-selected-model) per i percorsi di configurazione da controllare in ordine di priorità.626* Per darti più tempo per raggiungere quel terminale, imposta [`dialogExpiry`](/docs/it/settings-reference#dialogexpiry) su un valore più lungo o `"never"`

333* Per rimuovere completamente le varianti 1M dal selettore di modello, impostate [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/it/env-vars)627

628Prima della v2.1.236, questo messaggio non appariva: mentre un client Remote Control era connesso, Claude Code attendeva 60 secondi per una risposta e poi continuava il turno sul tuo modello predefinito.

334 629

335<h3 id="server-is-temporarily-limiting-requests">630<h3 id="server-is-temporarily-limiting-requests">

336 Il server sta limitando temporaneamente le richieste631 Server is temporarily limiting requests

337</h3>632</h3>

338 633

339L'API ha applicato un throttle di breve durata non correlato alla vostra quota di piano.634L'API ha applicato una limitazione di breve durata non correlata alla quota del tuo piano.

340 635

341```text theme={null}636```text theme={null}

342API Error: Server is temporarily limiting requests (not your usage limit)637API Error: Server is temporarily limiting requests (not your usage limit)

343```638```

344 639

345Claude Code distingue questi dai vostri limiti di piano dall'assenza delle intestazioni di quota unificate che una vera risposta di limite contiene. A partire da v2.1.199 questo viene [ritentato automaticamente](#automatic-retries) con backoff prima di essere mostrato, indipendentemente da come vi autenticate. Nelle versioni precedenti, una sessione acceduta con un abbonamento claude.ai falliva il turno alla prima occorrenza; solo le autenticazioni con chiave API ed Enterprise lo ritentavano.640Claude Code distingue questi dalla tua quota di piano per l'assenza delle intestazioni di quota unificata che una vera risposta di limite porta. A partire dalla v2.1.199 questo viene [ritentato automaticamente](#automatic-retries) con backoff prima di essere mostrato, indipendentemente da come ti autentichi. Nelle versioni precedenti, una sessione con accesso tramite abbonamento claude.ai ha fallito il turno alla prima occorrenza; solo le chiavi API e gli accessi Enterprise lo hanno ritentato.

346 641

347**Cosa fare:**642**Cosa fare:**

348 643

349* Attendete brevemente e riprovate644* Attendi brevemente e riprova

350* Controllate [status.claude.com](https://status.claude.com) se persiste645* Controlla [status.claude.com](https://status.claude.com) se persiste

351 646

352<h3 id="request-rejected-429">647<h3 id="request-rejected-429">

353 Richiesta rifiutata (429)648 Request rejected (429)

354</h3>649</h3>

355 650

356Avete raggiunto il limite di velocità configurato per la vostra chiave API, il progetto Amazon Bedrock o il progetto Google Cloud.651Hai raggiunto il limite di velocità configurato per la tua chiave API, il progetto Amazon Bedrock o il progetto Google Cloud.

357 652

358```text theme={null}653```text theme={null}

359API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.654API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

360```655```

361 656

362La frase finale indica dove controllare l'integrità del servizio e varia in base al provider. Le configurazioni di Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry indicano lo stato del servizio di quel provider invece della pagina di stato di Anthropic. Un `ANTHROPIC_BASE_URL` personalizzato indica l'host del gateway.657La frase finale nomina dove controllare l'integrità del servizio e varia in base al provider. Le configurazioni Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry nominano lo stato del servizio di quel provider invece della pagina di stato Anthropic. Un `ANTHROPIC_BASE_URL` personalizzato nomina l'host del gateway.

658

659**Cosa fare:**

660

661* Esegui `/status` e conferma che la credenziale attiva è quella che ti aspetti. Un `ANTHROPIC_API_KEY` casuale nel tuo ambiente può instradare le richieste attraverso una chiave di livello inferiore invece del tuo abbonamento.

662* Controlla la console del tuo provider per i limiti attivi e richiedi un livello più elevato se necessario

663* Per le chiavi API Anthropic, vedi il [riferimento ai limiti di velocità](https://platform.claude.com/docs/en/api/rate-limits) per come funzionano i livelli e come impostare i limiti di spesa per workspace

664* Riduci la concorrenza: abbassa [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/it/env-vars), evita di eseguire molti subagenzi paralleli, o passa a un modello più piccolo con `/model` per esecuzioni script ad alto volume

665

666<h3 id="spend-limit-reached">

667 Spend limit reached

668</h3>

669

670Ti connetti tramite un [gateway di app Claude](/docs/it/claude-apps-gateway) e hai superato un [limite di spesa](/docs/it/claude-apps-gateway-spend-limits) impostato dall'operatore del gateway. Il gateway blocca le tue richieste fino a quando il periodo denominato non si ripristina o l'operatore non aumenta il limite. Contrassegna ogni risposta `429` bloccata con `x-should-retry: false`, quindi Claude Code mostra questo messaggio senza ritentare.

671

672```text theme={null}

673spend limit reached (daily; resets 2026-08-09 00:00 UTC)

674```

675

676Il messaggio nomina il periodo del limite e l'ora di ripristino, e quando l'operatore ha configurato un `blocked_message`, le sue istruzioni lo seguono. Prima della v2.1.225, il messaggio leggeva solo `spend limit reached`; un gateway su una versione precedente invia ancora quella forma più breve.

363 677

364**Cosa fare:**678**Cosa fare:**

365 679

366* Eseguite `/status` e confermate che le credenziali attive siano quelle che vi aspettate. Un `ANTHROPIC_API_KEY` casuale nel vostro ambiente può instradare le richieste attraverso una chiave di livello inferiore invece del vostro abbonamento.680* Attendi l'ora di ripristino che il messaggio nomina, o segui le istruzioni dell'operatore se il messaggio le contiene

367* Controllate la console del vostro provider per i limiti attivi e richiedete un livello superiore se necessario681* Chiedi al tuo operatore del gateway di aumentare il limite se lo raggiungi regolarmente

368* Per le chiavi API di Anthropic, consultate il [riferimento dei limiti di velocità](https://platform.claude.com/docs/en/api/rate-limits) per sapere come funzionano i livelli e come impostare i limiti di spesa per workspace682

369* Riducete la concorrenza: abbassate [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/it/env-vars), evitate di eseguire molti subagent paralleli, o passate a un modello più piccolo con `/model` per esecuzioni scriptate ad alto volume683Un messaggio correlato, `spend limit unavailable`, significa che il gateway non poteva leggere i suoi record di spesa e ha bloccato la richiesta come precauzione piuttosto che per il tuo limite. Di solito si risolve da solo; se persiste, comunica al tuo operatore del gateway.

370 684

371<h3 id="credit-balance-is-too-low">685<h3 id="credit-balance-is-too-low">

372 Il saldo dei crediti è troppo basso686 Credit balance is too low

373</h3>687</h3>

374 688

375La vostra organizzazione Console ha esaurito i crediti prepagati.689L'organizzazione della tua Console ha esaurito i crediti prepagati, o Claude Code sta inviando le tue richieste con una chiave API Console quando intendevi usare il tuo abbonamento.

376 690

377```text theme={null}691```text theme={null}

378Credit balance is too low692Credit balance is too low

380 694

381**Cosa fare:**695**Cosa fare:**

382 696

383* Aggiungete crediti su [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing), e considerate di abilitare l'auto-reload lì in modo che il saldo si ricarichi prima di raggiungere lo zero697* Se hai un piano Pro, Max, Team o Enterprise e vedi questo, esegui `/status` e controlla la riga `API key`. Un `ANTHROPIC_API_KEY` approvato nel tuo ambiente instrada le richieste attraverso quella chiave invece del tuo abbonamento. Annullalo nella shell corrente e rimuovilo dal tuo profilo shell, quindi riavvia `claude`. Esegui `/login` se non hai ancora effettuato l'accesso con il tuo abbonamento.

384* Passate all'autenticazione con abbonamento con `/login` se avete un piano Pro, Max, Team o Enterprise698* Aggiungi crediti su [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing), e considera di abilitare il ricaricamento automatico lì in modo che il saldo si riempia prima di raggiungere lo zero

385* Impostate i limiti di spesa per workspace nella Console per evitare che un singolo progetto esaurisca il saldo dell'organizzazione. Consultate [Manage costs effectively](/docs/it/costs).699* Imposta i limiti di spesa per workspace nella Console per evitare che un singolo progetto dreni il saldo dell'organizzazione. Vedi [Manage costs effectively](/docs/it/costs).

700

701<h3 id="could-not-update-your-spend-limit">

702 Could not update your spend limit

703</h3>

704

705Il server ha rifiutato una modifica del limite di spesa che hai effettuato dal prompt che appare quando raggiungi il tuo limite di spesa.

706

707```text theme={null}

708Could not update your spend limit: <reason from the server>

709```

710

711Quando il server spiega il rifiuto, il messaggio termina con quel motivo, e ritentare lo stesso valore fallisce di nuovo. Quando il fallimento non ha un motivo fornito dal server, come una connessione interrotta, il messaggio legge `Could not update your spend limit. Press Enter to retry.` e ritentare può avere successo. Prima della v2.1.216, Claude Code mostrava la forma generica per ogni fallimento.

712

713**Cosa fare:**

714

715* Se il messaggio include un motivo, scegli un limite che lo soddisfi, come un importo inferiore

716* Se il messaggio mostra solo la forma generica, ritenta; il fallimento potrebbe essere transitorio

717* Se la modifica continua a fallire, effettuala dalle tue [impostazioni di fatturazione claude.ai](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) nel browser invece

386 718

387<h2 id="authentication-errors">719<h2 id="authentication-errors">

388 Errori di autenticazione720 Errori di autenticazione

389</h2>721</h2>

390 722

391Questi errori significano che Claude Code non può provare la vostra identità all'API. Eseguite `/status` in qualsiasi momento per vedere quale credenziale è attualmente attiva.723Questi errori significano che Claude Code non può provare la Vostra identità all'API. Eseguite `/status` in qualsiasi momento per vedere quale credenziale è attualmente attiva.

392 724

393<h3 id="not-logged-in">725<h3 id="not-logged-in">

394 Non connesso726 Non connesso

402 734

403**Cosa fare:**735**Cosa fare:**

404 736

405* Eseguite `/login` per autenticarvi con il vostro abbonamento Claude o account Console737* Eseguite `/login` per autenticarvi con il Vostro abbonamento Claude o l'account Console

406* Se vi aspettavate che una variabile d'ambiente vi autenticasse, confermate che `ANTHROPIC_API_KEY` sia impostata ed esportata nella shell dove avete lanciato `claude`738* Se vi aspettavate che una variabile d'ambiente vi autenticasse, confermate che `ANTHROPIC_API_KEY` sia impostata ed esportata nella shell dove avete lanciato `claude`

407* Per CI o automazione dove il login interattivo non è possibile, configurate uno script [`apiKeyHelper`](/docs/it/settings#available-settings) che recuperi una chiave all'avvio739* Per CI o automazione dove il login interattivo non è possibile, configurate uno script [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper) che recuperi una chiave all'avvio

408* Consultate [Precedenza dell'autenticazione](/docs/it/authentication#authentication-precedence) per comprendere quale credenziale Claude Code utilizza quando sono presenti più credenziali740* Vedete [Precedenza dell'autenticazione](/docs/it/authentication#authentication-precedence) per capire quale credenziale Claude Code utilizza quando sono presenti più credenziali

409 741

410Se vi viene richiesto di accedere ripetutamente, consultate [Non connesso o token scaduto](/docs/it/troubleshoot-install#not-logged-in-or-token-expired) per le correzioni dell'orologio di sistema e del Portachiavi di macOS.742Se vi viene chiesto di accedere ripetutamente, vedete [Non connesso o token scaduto](/docs/it/troubleshoot-install#not-logged-in-or-token-expired) per i controlli dell'orologio di sistema e i passaggi di recupero dell'archiviazione delle credenziali di macOS.

411 743

412<h3 id="could-not-resolve-authentication-method">744<h3 id="could-not-resolve-authentication-method">

413 Impossibile risolvere il metodo di autenticazione745 Impossibile risolvere il metodo di autenticazione

414</h3>746</h3>

415 747

416La sessione ha raggiunto il client API senza alcuna credenziale. Questo appare nelle [sessioni in background](/docs/it/agent-view), sessioni cloud e contesti Agent SDK dove il controllo del login interattivo non viene eseguito prima della prima richiesta.748La sessione ha raggiunto il client API senza alcuna credenziale. Le [sessioni in background](/docs/it/agent-view) e le sessioni cloud mostrano questo messaggio quando il worker si avvia senza una credenziale. Le esecuzioni interattive, `-p` e Agent SDK segnalano la stessa condizione di [Non connesso](#not-logged-in) e scrivono questa stringa solo nel loro log di debug, quindi se l'avete trovata lì, seguite quella voce invece.

417 749

418```text theme={null}750```text theme={null}

419Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted751Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

420```752```

421 753

422Prima della v2.1.174, una sessione in background o cloud assegnata a un worker pre-inizializzato inattivo poteva fallire in questo modo anche quando erano configurate credenziali valide. Eseguite l'aggiornamento per recuperare. Nelle versioni attuali l'errore significa che nessuna credenziale era disponibile per il processo worker.754Sulle versioni attuali l'errore significa che nessuna credenziale era disponibile al processo worker. Prima della v2.1.174, una sessione in background assegnata a un worker pre-inizializzato inattivo poteva fallire in questo modo anche quando le credenziali valide erano configurate. Prima della v2.1.176, anche una sessione cloud che era rimasta inattiva prima di essere rivendicata poteva farlo. Aggiornate per recuperare.

423 755

424**Cosa fare:**756**Cosa fare:**

425 757

426* Eseguite l'aggiornamento alla v2.1.174 o successiva se questo appare in una sessione in background o cloud e le vostre credenziali sono già configurate758* Aggiornate alla v2.1.176 o successiva se questo appare in una sessione in background o cloud e le Vostre credenziali sono già configurate

427* Confermate che `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` o le credenziali del vostro provider cloud siano impostate nell'ambiente che avvia il worker, non solo nella vostra shell interattiva759* Confermate che `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` o le Vostre credenziali del provider cloud siano impostati nell'ambiente che avvia il worker, non solo nella Vostra shell interattiva

428* Per Agent SDK, consultate [configurazione dell'autenticazione](/docs/it/agent-sdk/overview#get-started)760* Per Agent SDK, vedete [configurazione dell'autenticazione nella guida rapida](/docs/it/agent-sdk/quickstart#setup)

429* Eseguite `/status` in una sessione interattiva nello stesso ambiente per confermare quale fonte di credenziale si risolve761* Eseguite `/status` in una sessione interattiva nello stesso ambiente per confermare quale fonte di credenziale si risolve

430 762

431<h3 id="invalid-api-key">763<h3 id="invalid-api-key">

432 Chiave API non valida764 Chiave API non valida

433</h3>765</h3>

434 766

435La variabile d'ambiente `ANTHROPIC_API_KEY` o lo script `apiKeyHelper` ha restituito una chiave che l'API ha rifiutato.767La variabile d'ambiente `ANTHROPIC_API_KEY` o lo script `apiKeyHelper` ha restituito una chiave che l'API ha rifiutato, oppure Claude Code ha bloccato una chiave da `ANTHROPIC_API_KEY` prima di inviarla.

436 768

437```text theme={null}769```text theme={null}

438Invalid API key · Fix external API key770Invalid API key · Fix external API key

439```771```

440 772

773Quando il messaggio continua oltre `Fix external API key` con una descrizione come `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`, l'API non ha mai visto la chiave. Claude Code ha trovato un carattere che le intestazioni HTTP non possono trasportare e ha fermato la richiesta prima di inviarla. Vedete [Valore di intestazione di richiesta non valido](#invalid-request-header-value) per come leggere la descrizione e correggere il valore.

774

441**Cosa fare:**775**Cosa fare:**

442 776

443* Controllate gli errori di digitazione e confermate che la chiave non sia stata revocata nella [Console](https://platform.claude.com/settings/keys)777* Controllate gli errori di battitura e confermate che la chiave non sia stata revocata nella [Console](https://platform.claude.com/settings/keys)

444* Eseguite `env | grep ANTHROPIC` nella stessa shell. Strumenti come direnv, plugin shell dotenv e terminali IDE possono caricare una chiave obsoleta da un file `.env` nel vostro progetto senza che la impostiate esplicitamente.778* Nella stessa shell, eseguite `env | grep ANTHROPIC`, oppure in PowerShell `Get-ChildItem Env:ANTHROPIC*`. Strumenti come direnv, plugin shell dotenv e terminali IDE possono caricare una chiave obsoleta da un file `.env` nel Vostro progetto senza che la impostiate esplicitamente.

445* Annullate l'impostazione di `ANTHROPIC_API_KEY` ed eseguite `/login` per utilizzare invece l'autenticazione tramite abbonamento779* Annullate l'impostazione di `ANTHROPIC_API_KEY` ed eseguite `/login` per utilizzare invece l'autenticazione dell'abbonamento

446* Se la chiave proviene da uno script [`apiKeyHelper`](/docs/it/settings#available-settings), eseguite lo script direttamente per confermare che stampi una chiave valida su stdout780* Se la chiave proviene da uno script [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper), eseguite lo script direttamente per confermare che stampi una chiave valida su stdout

447* Eseguite `/status` per confermare quale fonte di credenziale Claude Code sta effettivamente utilizzando781* Eseguite `/status` per confermare quale fonte di credenziale Claude Code sta effettivamente utilizzando

448 782

449<h3 id="your-apikeyhelper-script-is-failing">783<h3 id="your-apikeyhelper-script-is-failing">

450 Lo script apiKeyHelper sta fallendo784 Lo script apiKeyHelper non funziona

451</h3>785</h3>

452 786

453Il comando configurato nell'impostazione [`apiKeyHelper`](/docs/it/settings#available-settings) è uscito con un errore, ha raggiunto il timeout o non ha stampato nulla su stdout. Senza una chiave dallo script, la richiesta raggiunge l'API con una credenziale segnaposto, e l'API la rifiuta con `401`.787Claude Code ha eseguito il comando nella Vostra impostazione [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper) e non ha ottenuto una chiave indietro. Senza una, la richiesta raggiunge l'API con una credenziale segnaposto e l'API la rifiuta con `401`. Il pannello `Authentication` nel terminale mostra quale di questi è accaduto:

788

789* Il comando è uscito con un errore o è scaduto

790* Il comando non ha stampato nulla su stdout

791* Il comando ha stampato qualcosa di diverso dalla chiave, come un banner di login o una riga di log. Il pannello mostra `returned output that cannot be used as an API key` e dice cosa c'è di sbagliato, senza ripetere l'output. Prima della v2.1.227, Claude Code inviava tutto ciò che il comando stampava, dopo aver tagliato gli spazi bianchi circostanti.

454 792

455```text theme={null}793```text theme={null}

456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output794Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

457```795```

458 796

459Claude Code esegue nuovamente lo script e ritenta la richiesta fino a due volte in più prima di mostrare questo messaggio, quindi il fallimento emerge entro tre tentativi. Prima della v2.1.208, Claude Code spendeva l'intero [budget di retry](#automatic-retries) reinviando la richiesta con la credenziale segnaposto e poi segnalava un errore di autenticazione generico `401` invece del fallimento dello script.797In [modalità non interattiva](/docs/it/headless), stderr trasporta anche il motivo specifico, con il prefisso `apiKeyHelper failed:`.

798

799Claude Code riesegue lo script e ritenta la richiesta fino a due volte in più prima di mostrare questo messaggio, quindi l'errore emerge entro tre tentativi. Prima della v2.1.208, Claude Code spendeva l'intero [budget di ripetizione](#automatic-retries) reinviando la richiesta con la credenziale segnaposto e poi segnalava un errore di autenticazione generico `401` invece dell'errore dello script.

800

801L'esecuzione di `/login` non aiuta qui: l'output dell'helper [ha la precedenza](/docs/it/authentication#authentication-precedence) su un login salvato finché l'impostazione è presente.

802

803**Cosa fare:**

804

805* Eseguite il comando configurato in `apiKeyHelper` direttamente nella Vostra shell per riprodurre l'errore

806* Se il comando segnala una sessione scaduta, riauthenticate con il Vostro provider di credenziali, ad esempio accedendo di nuovo al Vostro SSO o vault di segreti

807* Correggete il comando in modo che stampi solo la chiave su stdout, come un singolo token di ASCII stampabile fino a 16.384 caratteri, e uscite con codice 0. Vedete [ruotare le credenziali con apiKeyHelper](/docs/it/llm-gateway-connect#rotate-credentials-with-apikeyhelper) per una configurazione funzionante.

808* Eseguite `/status` per confermare che `apiKeyHelper` sia la fonte di credenziale attiva. Ogni volta che il comando fallisce, il suo codice di uscita e l'output di errore appaiono in un pannello `Authentication` nel terminale. Prima della v2.1.212, il pannello era intitolato `Cloud authentication`.

809

810<h3 id="invalid-request-header-value">

811 Valore di intestazione di richiesta non valido

812</h3>

813

814Un valore che Claude Code stava per inviare come intestazione di richiesta contiene un carattere che le intestazioni HTTP non possono trasportare: un'interruzione di riga, un byte NUL o un carattere sopra `U+00FF`, come una virgoletta ricurva o uno spazio di larghezza zero. Claude Code ferma la richiesta prima che qualsiasi cosa sia inviata e nomina la variabile o l'impostazione da correggere. La causa usuale è una credenziale incollata da un documento o chat che trasportava un carattere invisibile o un'interruzione di riga errata.

815

816Claude Code esegue questo controllo quando invia richieste all'API Claude direttamente o attraverso un [gateway LLM](/docs/it/llm-gateway). Su un provider cloud di terze parti come [Amazon Bedrock](/docs/it/amazon-bedrock), Claude Code non lo esegue prima di inviare.

817

818```text theme={null}

819Invalid auth token · Fix external auth token

820Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable

821Invalid request header from the environment · Fix the environment variable

822```

823

824La prima parte del messaggio dipende da dove proviene il valore errato:

825

826* `Invalid auth token`: un token bearer da [`ANTHROPIC_AUTH_TOKEN`](/docs/it/env-vars) o [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/it/env-vars)

827* `Invalid ANTHROPIC_CUSTOM_HEADERS`: un nome o valore di intestazione che avete impostato in [`ANTHROPIC_CUSTOM_HEADERS`](/docs/it/env-vars). La descrizione conta quale coppia `Name: Value` è in colpa, come `distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS`, senza ripetere il nome o il valore, poiché li avete scelti entrambi.

828* `Invalid request header from the environment`: un valore che Claude Code copia in un'intestazione di richiesta da un'altra variabile d'ambiente, come `CLAUDE_AGENT_SDK_CLIENT_APP`. La descrizione nomina la variabile da correggere.

829

830Claude Code segnala un `ANTHROPIC_API_KEY` errato catturato da questo controllo come [Chiave API non valida](#invalid-api-key), con la stessa descrizione finale. Segnala una credenziale `/login` salvata errata come [Non connesso](#not-logged-in) invece; eseguite `/login` per salvarne una nuova. L'output di uno script [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper) non raggiunge mai questo controllo: Claude Code lo convalida quando lo script viene eseguito e l'output che un'intestazione HTTP non può trasportare fallisce con [Lo script apiKeyHelper non funziona](#your-apikeyhelper-script-is-failing).

831

832Dopo il secondo `·`, il messaggio descrive il problema, come in questo esempio completo:

833

834```text theme={null}

835Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

836```

460 837

461Eseguire `/login` non aiuta qui: l'output dell'helper [ha la precedenza](/docs/it/authentication#authentication-precedence) su un login salvato finché l'impostazione è presente.838Le posizioni contano i caratteri a partire da uno. La descrizione è costruita da frasi fisse e conteggi di caratteri, quindi non include mai il valore stesso. Nomina il carattere offensivo solo quando è un carattere invisibile o tipografico ben noto, come un byte order mark, uno spazio di larghezza zero o una virgoletta ricurva, e segnala tutto il resto come `a non-ASCII character`.

462 839

463**Cosa fare:**840**Cosa fare:**

464 841

465* Eseguite il comando configurato in `apiKeyHelper` direttamente nella vostra shell per riprodurre il fallimento842* Reimpostate la variabile o l'impostazione che il messaggio nomina, riscrivendo i caratteri intorno alla posizione segnalata piuttosto che incollando dalla stessa fonte di nuovo

466* Se il comando segnala una sessione scaduta, ri-autenticatevi con il vostro provider di credenziali, ad esempio accedendo di nuovo al vostro SSO o vault di segreti843* Per `ANTHROPIC_CUSTOM_HEADERS`, mantenete una coppia `Name: Value` per riga e riscritte la coppia che il messaggio conta

467* Correggete il comando in modo che stampi la chiave su stdout e esca con codice 0. Consultate [ruotare le credenziali con apiKeyHelper](/docs/it/llm-gateway-connect#rotate-credentials-with-apikeyhelper) per una configurazione funzionante.844* Eseguite `/status` per confermare quale fonte di credenziale è attiva

468* Eseguite `/status` per confermare che `apiKeyHelper` è la fonte di credenziale attiva. Ogni volta che il comando fallisce, il suo codice di uscita e l'output di errore appaiono in un pannello `Cloud authentication` nel terminale.

469 845

470<h3 id="this-organization-has-been-disabled">846<h3 id="this-organization-has-been-disabled">

471 Questa organizzazione è stata disabilitata847 Questa organizzazione è stata disabilitata

472</h3>848</h3>

473 849

474Una `ANTHROPIC_API_KEY` obsoleta da un'organizzazione Console disabilitata sta sovrascrivendo il vostro login tramite abbonamento.850Claude Code sta utilizzando un `ANTHROPIC_API_KEY` obsoleto da un'organizzazione Console disabilitata. Quando avete un login di abbonamento salvato, la chiave lo sostituisce.

475 851

476```text theme={null}852```text theme={null}

477Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials853Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead

854Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable

478API Error: 400 ... This organization has been disabled.855API Error: 400 ... This organization has been disabled.

479```856```

480 857

481Le variabili d'ambiente hanno la precedenza su `/login`, quindi una chiave esportata nel vostro profilo shell o caricata da un file `.env` viene utilizzata anche quando avete un abbonamento Pro o Max funzionante. In modalità non interattiva (`-p`), la chiave viene sempre utilizzata quando presente.858Il suggerimento dopo il `·` dipende dalle Vostre credenziali salvate: la prima forma appare quando un `/login` memorizzato può subentrare dopo aver annullato l'impostazione della chiave, e la seconda quando la chiave è la Vostra unica credenziale.

859

860Le variabili d'ambiente hanno la precedenza su `/login`, quindi una chiave esportata nel Vostro profilo shell o caricata da un file `.env` è utilizzata anche quando avete un abbonamento Pro o Max funzionante. In modalità non interattiva (`-p`), la chiave è sempre utilizzata quando presente.

482 861

483**Cosa fare:**862**Cosa fare:**

484 863

485* Annullate l'impostazione di `ANTHROPIC_API_KEY` nella shell corrente e rimuovetela dal vostro profilo shell, quindi riavviate `claude`864* Annullate l'impostazione di `ANTHROPIC_API_KEY` nella shell corrente e rimuovetela dal Vostro profilo shell, quindi riavviate `claude`

486* Eseguite `/status` in seguito per confermare che la credenziale attiva sia il vostro abbonamento865* Se il messaggio dice `Update or unset`, non avete un login salvato su cui ricadere. Annullate l'impostazione della chiave ed eseguite `/login`, oppure sostituite la chiave con una da un'organizzazione Console attiva.

487* Se nessuna variabile d'ambiente è impostata e l'errore persiste, l'organizzazione disabilitata è quella collegata al vostro `/login`. Contattate il supporto o accedete con un account diverso.866* Eseguite `/status` in seguito per confermare che la credenziale attiva sia il Vostro abbonamento

867* Se nessuna variabile d'ambiente è impostata e l'errore persiste, l'organizzazione disabilitata è quella legata al Vostro `/login`. Contattate il supporto o accedete con un account diverso.

488 868

489<h3 id="your-organization-has-disabled-api-key-authentication">869<h3 id="your-organization-has-disabled-api-key-authentication">

490 La vostra organizzazione ha disabilitato l'autenticazione tramite chiave API870 La Vostra organizzazione ha disabilitato l'autenticazione con chiave API

491</h3>871</h3>

492 872

493Questo messaggio richiede Claude Code v2.1.169 o successiva. L'amministratore dell'organizzazione Console ha disattivato l'autenticazione tramite chiave API, quindi l'API rifiuta la chiave che Claude Code sta inviando. L'hint di recupero dopo il `·` varia a seconda di dove proviene la chiave:873Questo messaggio richiede Claude Code v2.1.169 o successiva. L'amministratore dell'organizzazione Console ha disattivato l'autenticazione con chiave API, quindi l'API rifiuta la chiave che Claude Code sta inviando. Il suggerimento di recupero dopo il `·` varia a seconda di dove proviene la chiave:

494 874

495```text theme={null}875```text theme={null}

496Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account876Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

499Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account879Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

500```880```

501 881

502Le variabili d'ambiente e `apiKeyHelper` hanno la precedenza su `/login`, quindi eseguire solo `/login` non aiuta mentre uno di essi sta ancora fornendo una chiave. Consultate [Precedenza dell'autenticazione](/docs/it/authentication#authentication-precedence).882Le variabili d'ambiente e `apiKeyHelper` hanno la precedenza su `/login`, quindi eseguire `/login` da solo non aiuta mentre uno dei due sta ancora fornendo una chiave. Vedete [Precedenza dell'autenticazione](/docs/it/authentication#authentication-precedence).

503 883

504**Cosa fare:**884**Cosa fare:**

505 885

506* Se il messaggio nomina `ANTHROPIC_API_KEY`, annullate l'impostazione nella shell corrente e rimuovetela dal vostro profilo shell o file `.env`, quindi riavviate `claude`886* Se il messaggio nomina `ANTHROPIC_API_KEY`, annullate l'impostazione nella shell corrente e rimuovetela dal Vostro profilo shell o file `.env`, quindi riavviate `claude`

507* Se il messaggio nomina `apiKeyHelper`, rimuovete l'impostazione [`apiKeyHelper`](/docs/it/settings#available-settings) dal vostro `settings.json`887* Se il messaggio nomina `apiKeyHelper`, rimuovete l'impostazione [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper) dal Vostro `settings.json`

508* Eseguite `/login` per accedere con il vostro account claude.ai888* Eseguite `/login` per accedere con il Vostro account claude.ai

509* Eseguite `/status` in seguito per confermare che la credenziale attiva sia il vostro abbonamento piuttosto che una chiave API889* Eseguite `/status` in seguito per confermare che la credenziale attiva sia il Vostro abbonamento piuttosto che una chiave API

510* Se avete bisogno dell'autenticazione tramite chiave API per l'automazione, chiedete all'amministratore della vostra organizzazione di riattivarla nella Console890* Se avete bisogno dell'autenticazione con chiave API per l'automazione, chiedete all'amministratore dell'organizzazione di riattivarla nella Console

511 891

512<h3 id="your-organization-has-disabled-claude-subscription-access">892<h3 id="your-organization-has-disabled-claude-subscription-access">

513 La vostra organizzazione ha disabilitato l'accesso tramite abbonamento Claude893 La Vostra organizzazione ha disabilitato l'accesso all'abbonamento Claude

514</h3>894</h3>

515 895

516La vostra organizzazione Claude non consente l'accesso a Claude Code con un login tramite abbonamento. Eseguire `/login` di nuovo con lo stesso account restituisce lo stesso errore.896La Vostra organizzazione Claude non consente l'accesso a Claude Code con un login di abbonamento. L'esecuzione di `/login` di nuovo con lo stesso account restituisce lo stesso errore.

517 897

518```text theme={null}898```text theme={null}

519Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access899Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

520```900```

521 901

522Questa è un'impostazione dell'organizzazione lato server, quindi non può essere sovrascritta dalle impostazioni locali, variabili d'ambiente o flag CLI.902Questa è un'impostazione dell'organizzazione lato server, quindi non può essere ignorata dalle impostazioni locali, dalle variabili d'ambiente o dai flag CLI.

523 903

524Agent SDK e modalità non interattiva `-p` presentano questo come il codice di errore `oauth_org_not_allowed`.904Agent SDK e la modalità non interattiva `-p` presentano questo come il codice di errore `oauth_org_not_allowed`.

525 905

526**Cosa fare:**906**Cosa fare:**

527 907

528* Chiedete al vostro amministratore di abilitare l'accesso a Claude Code per la vostra organizzazione908* Chiedete al Vostro amministratore di abilitare l'accesso a Claude Code per la Vostra organizzazione

529* Autenticatevi con una chiave API Console invece del vostro abbonamento. Consultate [Autenticazione Claude Console](/docs/it/authentication#claude-console-authentication) per la configurazione.909* Autenticate con una chiave API Console invece del Vostro abbonamento. Vedete [Autenticazione Claude Console](/docs/it/authentication#claude-console-authentication) per la configurazione.

530* Se siete l'amministratore e non vedete un'opzione per abilitare l'accesso, contattate il [supporto Anthropic](https://support.claude.com)910* Se siete l'amministratore e non vedete un'opzione per abilitare l'accesso, contattate il [supporto Anthropic](https://support.claude.com)

531 911

532<h3 id="routines-are-disabled-by-your-organizations-policy">912<h3 id="routines-are-disabled-by-your-organizations-policy">

533 Le routine sono disabilitate dalla politica della vostra organizzazione913 Le routine sono disabilitate dalla politica dell'organizzazione

534</h3>914</h3>

535 915

536Un Owner nella vostra organizzazione Team o Enterprise ha disattivato le routine a livello di organizzazione. L'errore appare quando tentate di creare o eseguire una routine, incluso da `/schedule` e dall'interfaccia utente [Routines](/docs/it/routines) su claude.ai/code.916Un Proprietario nella Vostra organizzazione Team o Enterprise ha disattivato le routine a livello di organizzazione. L'errore appare quando tentate di creare o eseguire una routine, ad esempio dall'interfaccia utente [Routine](/docs/it/routines) su claude.ai/code. Su Claude Code v2.1.227 o successiva, la stessa impostazione [nasconde anche `/schedule`](/docs/it/routines#troubleshooting) nella CLI.

537 917

538```text theme={null}918```text theme={null}

539Routines are disabled by your organization's policy.919Routines are disabled by your organization's policy.

540```920```

541 921

542Questa è un'impostazione lato server, quindi non può essere sovrascritta dalle impostazioni locali, variabili d'ambiente o flag CLI.922Questa è un'impostazione lato server, quindi non può essere ignorata dalle impostazioni locali, dalle variabili d'ambiente o dai flag CLI.

543 923

544**Cosa fare:**924**Cosa fare:**

545 925

546* Chiedete a un Owner nella vostra organizzazione di abilitare l'interruttore **Routines** su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)926* Chiedete a un Proprietario nella Vostra organizzazione di abilitare l'interruttore **Routines** su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)

547* Per lavori programmati una tantum che non richiedono routine a livello di organizzazione, consultate [attività programmate](/docs/it/scheduled-tasks)927* Per lavoro programmato una tantum che non richiede routine a livello di organizzazione, vedete [attività programmate](/docs/it/scheduled-tasks)

548 928

549<h3 id="remote-control-requires-the-anthropic-api">929<h3 id="remote-control-requires-the-anthropic-api">

550 Remote Control richiede l'API Anthropic930 Remote Control richiede l'API Anthropic

551</h3>931</h3>

552 932

553La sessione non sta comunicando direttamente con l'API Anthropic, quindi non c'è un backend claude.ai per [Remote Control](/docs/it/remote-control) con cui associarsi.933La sessione non sta parlando direttamente all'API Anthropic, quindi non c'è un backend claude.ai per [Remote Control](/docs/it/remote-control) con cui associarsi.

554 934

555```text theme={null}935```text theme={null}

556Remote Control is only available when using Claude via api.anthropic.com.936Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

557```937```

558 938

559Questo appare su Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry. A partire dalla v2.1.196 appare anche quando [`ANTHROPIC_BASE_URL`](/docs/it/env-vars) punta a un host diverso da `api.anthropic.com`, come un [gateway LLM](/docs/it/llm-gateway) o proxy, anche quando vi accedete con claude.ai.939Una seconda frase spiega cosa ha instradato la sessione lontano dall'API Anthropic; prima della v2.1.219, il messaggio era solo la prima frase. A seconda della causa, il messaggio nomina:

940

941* Una variabile del provider `CLAUDE_CODE_USE_*`, come `CLAUDE_CODE_USE_BEDROCK` per [Amazon Bedrock](/docs/it/amazon-bedrock) o `CLAUDE_CODE_USE_VERTEX` per [Agent Platform di Google Cloud](/docs/it/google-vertex-ai)

942* [`ANTHROPIC_BASE_URL`](/docs/it/env-vars) che punta a un host diverso da `api.anthropic.com`, come un [gateway LLM](/docs/it/llm-gateway) o proxy, anche quando vi accedete con claude.ai; prima della v2.1.196, un URL di base personalizzato non bloccava Remote Control

943* Un accesso [gateway cloud](/docs/it/claude-apps-gateway) aziendale effettuato tramite `/login`, che non supporta Remote Control e non ha alcuna variabile da annullare

560 944

561**Cosa fare:**945**Cosa fare:**

562 946

563* Annullate l'impostazione di `ANTHROPIC_BASE_URL` e riavviate la sessione, oppure avviate Remote Control da una sessione che comunica direttamente con l'API Anthropic947* Annullate l'impostazione della variabile che il messaggio nomina, come `CLAUDE_CODE_USE_BEDROCK` o `ANTHROPIC_BASE_URL`, e riavviate la sessione, oppure avviate Remote Control da una sessione che parla direttamente all'API Anthropic

564* Per questo e gli altri messaggi di avvio di Remote Control, consultate [Risoluzione dei problemi di Remote Control](/docs/it/remote-control#troubleshooting)948* Se la variabile non è impostata nella Vostra shell, controllate la chiave `env` nei Vostri [file di impostazioni](/docs/it/settings#where-settings-live), che applica le variabili d'ambiente a ogni sessione

949* Per questo e gli altri messaggi di avvio di Remote Control, vedete [Risolvere i problemi di Remote Control](/docs/it/remote-control#troubleshooting)

565 950

566<h3 id="oauth-token-revoked-or-expired">951<h3 id="remote-control-couldnt-refresh-your-login">

567 Token OAuth revocato o scaduto952 Remote Control non ha potuto aggiornare il Vostro login

568</h3>953</h3>

569 954

570Il vostro login salvato non è più valido. Un token revocato significa che vi siete disconnessi ovunque o un amministratore ha rimosso l'accesso; un token scaduto significa che l'aggiornamento automatico ha fallito durante la sessione.955Claude Code esegue una connessione [Remote Control](/docs/it/remote-control) dal vivo su credenziali di breve durata che ottiene e rinnova utilizzando il Vostro login claude.ai salvato. Quando claude.ai smette di accettare quel login, o Claude Code non ha più alcun login salvato, Claude Code ferma Remote Control e ha bisogno che vi accediate di nuovo. Uno qualsiasi dei due errori può accadere mentre Claude Code sta ancora connettendosi o più tardi, quando rinnova le credenziali.

571 956

572Entrambi i messaggi segnalano un rifiuto che l'API ha restituito per una richiesta che Claude Code ha inviato. Quando il login salvato è già stato cancellato dopo un aggiornamento fallito, vedete invece [Login scaduto](#login-expired).957Quando Claude Code chiede al servizio di login di aggiornare il Vostro login salvato e non riceve risposta, mantiene Remote Control in esecuzione e ritenta l'aggiornamento mentre la credenziale corrente della connessione è ancora valida. Un aggiornamento non riceve risposta quando Claude Code non può raggiungere il servizio di login, la richiesta scade o il servizio fallisce senza rifiutare il Vostro login. Se il servizio di login non sta ancora rispondendo quando quella credenziale scade, Claude Code ferma Remote Control e segnala `OAuth token refresh failed`.

958

959Quando Claude Code ferma Remote Control, mostra il motivo in un avviso e in una riga di trascrizione che inizia con `Remote Control disconnected`. La Vostra sessione locale continua a funzionare senza Remote Control. Questa sezione copre queste righe:

573 960

574```text theme={null}961```text theme={null}

575OAuth token revoked · Please run /login962Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control

576OAuth token has expired · Please run /login963Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control

577API Error: 401 ... authentication_error964Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control

965Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control

966Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate

967Remote Control disconnected — JWT refresh failed: no OAuth token — run /login

968Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

578```969```

579 970

971Claude Code nomina la causa nel mezzo del messaggio:

972

973* `Claude.ai login expired` e `Claude.ai login was rejected`: claude.ai non accetta più il Vostro token di login salvato, perché è scaduto o è stato revocato

974* `OAuth token unavailable`: Claude Code non aveva alcun token di login salvato quando la credenziale della connessione è scaduta per il rinnovo

975* `OAuth token refresh failed`: claude.ai ha rifiutato il Vostro token di login salvato mentre Claude Code stava riconnettendosi e l'aggiornamento del token non ha prodotto uno nuovo

976* `JWT refresh failed: no OAuth token`: Claude Code non ha trovato alcun token di login salvato per rinnovare

977* `Signed out of Claude`: vi siete disconnessi su questa macchina, ad esempio eseguendo `/logout` in un altro terminale, quindi Claude Code non ha alcun login salvato rimasto per rinnovare la connessione

978

580**Cosa fare:**979**Cosa fare:**

581 980

582* Eseguite `/login` per accedere di nuovo981* Eseguite `/login` per accedere di nuovo

583* Se l'errore ritorna nella stessa sessione dopo la ri-autenticazione, eseguite prima `/logout` per cancellare completamente il token memorizzato, quindi `/login`982* Eseguite `/remote-control` per riconnettere la sessione. I messaggi che terminano con `run /login to restore Remote Control` non hanno bisogno di questo passaggio: Claude Code si riconnette automaticamente una volta che vi siete acceduti.

584* Per prompt ripetuti di accesso tra i lanci, consultate i controlli dell'orologio di sistema e del Portachiavi di macOS in [Risoluzione dei problemi](/docs/it/troubleshoot-install#not-logged-in-or-token-expired)

585* Per altri errori inclusi `403 Forbidden` e problemi del browser OAuth, consultate [Login e autenticazione](/docs/it/troubleshoot-install#login-and-authentication)

586 983

587<h3 id="login-expired">984Prima della v2.1.224, `OAuth token refresh failed — run /login to re-authenticate` leggeva `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`, e `JWT refresh failed: no OAuth token — run /login` leggeva `no OAuth token available for recovery (code <N>)`. I messaggi `Claude.ai login expired`, `Claude.ai login was rejected` e `OAuth token unavailable` sono stati aggiunti nella v2.1.225.

588 Login scaduto

589</h3>

590 985

591Claude Code ha tentato di rinnovare il vostro login salvato claude.ai o Claude Console e il servizio OAuth ha rifiutato il token di aggiornamento memorizzato, quindi Claude Code ha cancellato le credenziali salvate. Dopo di che, ogni richiesta si ferma localmente prima di raggiungere l'API, perché solo `/login` può creare nuove credenziali. Prima della v2.1.206, Claude Code inviava comunque la richiesta con qualsiasi credenziale rimanesse nell'ambiente, e ogni modello falliva poi con [C'è un problema con il modello selezionato](#theres-an-issue-with-the-selected-model) o un 401 invece di un prompt per accedere.986Prima della v2.1.238, Claude Code segnalava i casi che ora dicono `Signed out of Claude` come `JWT refresh failed: no OAuth token — run /login`, e fermava Remote Control con `Claude.ai login expired — run /login to restore Remote Control` non appena un aggiornamento di login non riceveva risposta.

592 987

593```text theme={null}988<h3 id="remote-control-stopped-because-the-signed-in-account-changed">

594Login expired · Please run /login989 Remote Control si è fermato perché l'account connesso è cambiato

595```990</h3>

596 991

597In [modalità non interattiva](/docs/it/headless) (`-p`) e [Agent SDK](/docs/it/agent-sdk/overview), il messaggio legge come segue, e il codice di errore strutturato è `authentication_failed`:992Claude Code mostra questa riga durante una sessione [Remote Control](/docs/it/remote-control) quando vi accedete a un account claude.ai diverso o a un'organizzazione diversa su questa macchina. Avete effettuato il cambio al di fuori della sessione Claude Code, ad esempio eseguendo `/login` in un altro terminale.

993

994Una sessione Remote Control che avete avviato mentre eravate connessi tramite `/login` appartiene all'account claude.ai e all'organizzazione che erano connessi al momento.

598 995

599```text theme={null}996```text theme={null}

600Failed to authenticate: OAuth session expired and could not be refreshed997Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

601```998```

602 999

603Questo non è lo stesso stato di [Token OAuth revocato o scaduto](#oauth-token-revoked-or-expired). Quei messaggi segnalano un 401 che l'API ha restituito. Claude Code stesso produce `Login expired` per un login che ha già fallito a rinnovare, quindi non invia alcuna richiesta.1000Claude Code ferma la sessione Remote Control non appena claude.ai conferma che l'account o l'organizzazione è cambiato. La Vostra sessione locale continua a funzionare senza Remote Control.

~~604~~

605Le sessioni autenticate con una chiave API, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/it/env-vars) o un provider di terze parti non utilizzano il login salvato e non vedono mai questo messaggio.

606 1001

607**Cosa fare:**1002**Cosa fare:**

608 1003

609* Eseguite `/login` per accedere di nuovo. Riprovare senza accedere mostra lo stesso messaggio su ogni richiesta.1004* Eseguite `/remote-control` per avviare una nuova sessione Remote Control con l'account o l'organizzazione corrente

610* In modalità non interattiva, eseguite `claude` nello stesso ambiente, completate `/login`, quindi rieseguite il vostro comando. Per l'automazione che non può accedere in modo interattivo, autenticatevi con `ANTHROPIC_API_KEY` o [generate un token di lunga durata con `claude setup-token`](/docs/it/authentication#generate-a-long-lived-token).1005* Per tornare indietro, eseguite `/login` e accedete di nuovo all'account o all'organizzazione precedente. Quindi eseguite `/remote-control`.

611* Se l'accesso continua a fallire, consultate [Login e autenticazione](/docs/it/troubleshoot-install#login-and-authentication)

612 1006

613<h3 id="oauth-scope-requirement">1007Prima della v2.1.234, Claude Code non notava quando vi passavate a un account o un'organizzazione diversa al di fuori della sessione Claude Code. Claude Code manteneva la sessione Remote Control connessa fino a quando una richiesta successiva al server Remote Control non falliva con `Remote Control server rejected the request (HTTP 404)`. Quel fallimento potrebbe arrivare ore dopo il cambio.

614 Requisito di ambito OAuth1008

1009<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">

1010 Remote Control si è fermato perché l'app che esegue la sessione si è disconnessa o ha cambiato account

615</h3>1011</h3>

616 1012

617Il token memorizzato precede un ambito di autorizzazione che una funzione più recente necessita. Lo vedete più spesso da `/usage` e dall'indicatore di utilizzo della riga di stato:1013Quando l'app desktop Claude o un IDE ospita la Vostra sessione, Claude Code ottiene il Vostro token di login da quell'app piuttosto che da `/login`. Quando claude.ai rifiuta quel token, Claude Code chiede all'app uno nuovo. Se l'app risponde che è disconnessa, o che è ora connessa a un account Claude diverso, Claude Code termina la sessione [Remote Control](/docs/it/remote-control) e invia all'app una di queste righe:

618 1014

619```text theme={null}1015```text theme={null}

620OAuth token does not meet scope requirement: user:profile1016Remote Control stopped — the app running this session is now signed in to a different Claude account

1017Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

621```1018```

622 1019

1020La Vostra sessione locale continua a funzionare senza Remote Control.

1021

623**Cosa fare:**1022**Cosa fare:**

624 1023

625* Eseguite `/login` per ottenere un nuovo token con gli ambiti attuali. Non è necessario disconnettervi prima.1024* Se l'app è disconnessa, accedete di nuovo, quindi riattivate Remote Control nell'app

1025* Se l'app ha cambiato account, Claude Code non può continuare la sessione terminata con il nuovo account. Avviate una nuova sessione Remote Control con quell'account.

626 1026

627<h3 id="aws-credentials-expired-or-invalid">1027Prima della v2.1.238, Claude Code inviava all'app i messaggi `run /login` elencati sotto [Remote Control non ha potuto aggiornare il Vostro login](#remote-control-couldnt-refresh-your-login) in entrambi i casi.

628 Credenziali AWS scadute o non valide1028

1029<h3 id="oauth-token-revoked-or-expired">

1030 Token OAuth revocato o scaduto

629</h3>1031</h3>

630 1032

631Questo messaggio richiede Claude Code v2.1.198 o successiva e appare solo quando [`awsAuthRefresh`](/docs/it/amazon-bedrock#advanced-credential-configuration) è impostato nel vostro file di impostazioni. Il vostro token di sessione AWS è scaduto o è stato rifiutato, e l'aggiornamento automatico che Claude Code ha già eseguito non ha prodotto una credenziale che l'API accetta. Appare su un 401 da [Claude Platform on AWS](/docs/it/claude-platform-on-aws) o dall'[endpoint Mantle](/docs/it/amazon-bedrock#use-the-mantle-endpoint), che è come questi provider segnalano un token di sicurezza scaduto.1033Il Vostro login salvato non è più valido. Un token revocato significa che vi siete disconnessi ovunque o un amministratore ha rimosso l'accesso; un token scaduto significa che l'aggiornamento automatico è fallito a metà sessione.

632 1034

633L'hint di azione nel mezzo nomina il comando `awsAuthRefresh` dalle vostre impostazioni, quindi varia. La parte stabile è il `AWS credentials expired or invalid` iniziale:1035Entrambi i messaggi segnalano un rifiuto che l'API ha restituito per una richiesta che Claude Code ha inviato. Quando il login salvato è già stato cancellato dopo un aggiornamento fallito, vedete [Login scaduto](#login-expired) invece. Se vi autenticate con un token di lunga durata in [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/it/env-vars), vedete gli stessi messaggi quando quel token scade o viene revocato.

634 1036

635```text theme={null}1037```text theme={null}

636AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...1038OAuth token revoked · Please run /login

1039OAuth token has expired · Please run /login

1040API Error: 401 ... authentication_error

637```1041```

638 1042

639Senza `awsAuthRefresh` configurato, lo stesso 401 mostra il messaggio generico `Please run /login` invece, che non può aggiornare le credenziali AWS.

~~640~~

641**Cosa fare:**1043**Cosa fare:**

642 1044

643* Eseguite il comando `awsAuthRefresh` nominato nel messaggio, come `aws sso login --profile myprofile`, in un altro terminale e completate l'accesso al browser, quindi riprovate1045* Eseguite `/login` per accedere di nuovo

644* In una sessione interattiva, eseguite `/login`, scegliete **3rd-party platform**, quindi selezionate **Claude Platform on AWS · refresh credentials** sotto **Using 3rd-party platforms** per eseguire lo stesso comando senza riavviare Claude Code. Consultate [Configurare le credenziali AWS](/docs/it/claude-platform-on-aws#1-configure-aws-credentials)1046* Se l'errore ritorna nella stessa sessione dopo la riauthenticazione, eseguite prima `/logout` per cancellare completamente il token memorizzato, quindi `/login`

645* Se l'errore si ripete dopo che il comando di aggiornamento ha avuto successo, confermate che l'identità sia valida al di fuori di Claude Code con `aws sts get-caller-identity` nella stessa shell e profilo1047* Se vi autenticate con la variabile d'ambiente `CLAUDE_CODE_OAUTH_TOKEN`, Claude Code continua a inviare il valore che avete impostato dopo che una richiesta fallisce con un 401, piuttosto che passare al token di un login salvato. [`/status`](/docs/it/commands) mostra questa credenziale come una riga `Auth token` che legge `CLAUDE_CODE_OAUTH_TOKEN`. Generare un token fresco con [`claude setup-token`](/docs/it/authentication#generate-a-long-lived-token) e riavviare con esso, oppure annullate l'impostazione della variabile ed eseguite `/login`. Prima della v2.1.225, Claude Code poteva sostituire il valore della variabile a metà sessione con il token di accesso di breve durata da un login salvato, e la sessione falliva di nuovo con errori 401 una volta che quel token scadeva.

1048* Per i prompt ripetuti di accesso tra i lanci, vedete i controlli dell'orologio di sistema e i passaggi di recupero dell'archiviazione delle credenziali di macOS in [Risoluzione dei problemi](/docs/it/troubleshoot-install#not-logged-in-or-token-expired)

1049* Per altri errori inclusi `403 Forbidden` e problemi del browser OAuth, vedete [Login e autenticazione](/docs/it/troubleshoot-install#login-and-authentication)

646 1050

647<h3 id="aws-authentication-failed">1051<h3 id="api-error-401-invalid-authentication-credentials">

648 Autenticazione AWS non riuscita1052 API Error: 401 Credenziali di autenticazione non valide

649</h3>1053</h3>

650 1054

651Questo messaggio richiede Claude Code v2.1.198 o successiva e appare solo quando [`awsAuthRefresh`](/docs/it/amazon-bedrock#advanced-credential-configuration) è impostato nel vostro file di impostazioni. Il vostro provider AWS ha restituito un 403, oppure [Amazon Bedrock](/docs/it/amazon-bedrock) ha restituito un 401.1055L'API ha riconosciuto il formato della Vostra credenziale ma ha rifiutato l'account o l'organizzazione dietro di essa. Anthropic restituisce questo messaggio quando una credenziale è stata revocata di recente, quando un'organizzazione è stata disabilitata o ha rimosso il Vostro accesso, o quando l'account stesso è stato disattivato, quindi un token scaduto non è la causa. La credenziale può essere il Vostro login salvato o un `ANTHROPIC_API_KEY` approvato, e la correzione differisce, quindi iniziate eseguendo `/status` per vedere quale è attivo.

~~652~~

653Claude Code non può dire quale causa avete riscontrato. Amazon Bedrock segnala un token di sicurezza scaduto come un 403, ma un 403 è anche come segnala un diniego di autorizzazione, come un `AccessDeniedException` da un'autorizzazione IAM mancante o un modello che non è abilitato per il vostro account.

~~654~~

655Un 401 da Amazon Bedrock finisce anche qui piuttosto che sotto [Credenziali AWS scadute o non valide](#aws-credentials-expired-or-invalid), perché Amazon Bedrock non segnala un token scaduto come un 401. Un 401 da quell'endpoint in genere proviene da qualcos'altro nel percorso della richiesta, come un proxy aziendale.

~~656~~

657Un aggiornamento delle credenziali corregge un token scaduto e non può correggere le altre cause, quindi il messaggio offre entrambe:

658 1056

659```text theme={null}1057```text theme={null}

660AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...1058Please run /login · API Error: 401 Invalid authentication credentials

661```1059```

662 1060

663L'hint di azione nel mezzo nomina il comando `awsAuthRefresh` dalle vostre impostazioni, quindi varia. La parte stabile è il `AWS authentication failed` iniziale.

~~664~~

665**Cosa fare:**1061**Cosa fare:**

666 1062

667* Eseguite il comando `awsAuthRefresh` nominato nel messaggio, o `aws sso login`, nel caso in cui una credenziale scaduta sia la causa1063* Se `/status` mostra una riga `API key` che non è contrassegnata come non in uso, un [`ANTHROPIC_API_KEY`](/docs/it/authentication#authentication-precedence) approvato è la credenziale attiva e ha la precedenza sul Vostro login, quindi `/login` non lo sostituisce. Ruotate la chiave nella Console Claude, oppure ricadete sul Vostro abbonamento eseguendo `unset ANTHROPIC_API_KEY`, oppure in PowerShell `Remove-Item Env:ANTHROPIC_API_KEY`.

668* Se le vostre credenziali sono attuali, confermate che le autorizzazioni IAM in [Configurazione IAM](/docs/it/amazon-bedrock#iam-configuration) siano allegate all'identità che state utilizzando e che il modello selezionato sia abilitato per il vostro account e regione1064* Se `/status` mostra solo il Vostro login, eseguite `/login` una volta. Se la credenziale è stata revocata, un login fresco la sostituisce.

669* Eseguite `aws sts get-caller-identity` per confermare quale identità utilizzano le vostre richieste; un `AWS_PROFILE` obsoleto o profilo predefinito è una causa comune di una mancata corrispondenza di autorizzazioni1065* Se lo stesso messaggio ritorna per lo stesso account di login, l'account o l'organizzazione non è più attivo. Controllate l'account e l'organizzazione che `/status` segnala, e chiedete al Vostro amministratore dell'organizzazione di ripristinare l'accesso.

1066* Se [`ANTHROPIC_BASE_URL`](/docs/it/env-vars) punta a un [gateway LLM](/docs/it/llm-gateway), il testo dopo `401` è il messaggio del Vostro gateway piuttosto che di Anthropic, e `/login` non lo cambia. Correggete invece la credenziale che il Vostro gateway si aspetta.

670 1067

671<h3 id="aws-default-chain-credential-resolve-timed-out">1068<h3 id="login-expired">

672 Risoluzione della credenziale della catena predefinita AWS scaduta1069 Login scaduto

673</h3>1070</h3>

674 1071

675Il provider di credenziali della catena predefinita AWS non ha prodotto credenziali entro 60 secondi, quindi Claude Code ha fermato la risoluzione e ha fallito la richiesta. Il fallimento è la risoluzione locale delle credenziali: la richiesta non ha mai raggiunto [Amazon Bedrock](/docs/it/amazon-bedrock), [Claude Platform on AWS](/docs/it/claude-platform-on-aws) o l'[endpoint Mantle](/docs/it/amazon-bedrock#use-the-mantle-endpoint). Claude Code cancella la [cache delle credenziali](/docs/it/amazon-bedrock#credential-caching-and-resolution-timeout) e ritenta prima che questo errore emerga, quindi nel momento in cui lo vedete la catena si è bloccata su tentativi ripetuti.1072Claude Code ha tentato di rinnovare il Vostro login claude.ai o Claude Console salvato e il servizio OAuth ha rifiutato il token di aggiornamento memorizzato, quindi Claude Code ha cancellato le credenziali salvate. Dopo di che, ogni richiesta di modello si ferma localmente con questo messaggio prima di raggiungere l'API, perché solo `/login` può creare nuove credenziali.

1073

1074Prima della v2.1.206, Claude Code inviava comunque la richiesta del modello con qualsiasi credenziale rimanesse nell'ambiente, e ogni modello falliva con [C'è un problema con il modello selezionato](#theres-an-issue-with-the-selected-model) o un 401 invece di un prompt per accedere.

676 1075

677```text theme={null}1076```text theme={null}

678API Error: AWS default-chain credential resolve timed out1077Login expired · Please run /login

679```1078```

680 1079

681Le cause comuni sono un comando `credential_process` nel vostro profilo AWS che attende un input che non può ricevere, e un container o VM il cui servizio di metadati dell'istanza (IMDS) non risponde mai al probe della catena. Prima della v2.1.207, una catena bloccata lasciava la richiesta in attesa indefinitamente invece di fallire con questo messaggio.1080In [modalità non interattiva](/docs/it/headless) (`-p`) e [Agent SDK](/docs/it/agent-sdk/overview), il messaggio legge come segue, e il codice di errore strutturato è `authentication_failed`:

682 1081

683**Cosa fare:**1082```text theme={null}

1083Failed to authenticate: OAuth session expired and could not be refreshed

1084```

684 1085

685* Eseguite `aws sts get-caller-identity` nella stessa shell con lo stesso `AWS_PROFILE`. Se si blocca anche, correggete il profilo; un comando `credential_process` che richiede in modo interattivo è una causa comune.1086Questo non è lo stesso stato di [Token OAuth revocato o scaduto](#oauth-token-revoked-or-expired). Quei messaggi segnalano un 401 che l'API ha restituito. Claude Code stesso produce `Login expired` per un login che ha già fallito di rinnovare, quindi non invia alcuna richiesta. Quando il rinnovo fallisce perché l'account stesso è sospeso piuttosto che il login essere obsoleto, Claude Code mostra [Il Vostro account è in sospeso](#your-account-is-on-hold) invece.

686* Completate il passaggio di accesso prima di avviare Claude Code, ad esempio `aws sso login --profile myprofile`, in modo che la catena si risolva dalla cache SSO locale invece di attendere un flusso del browser

687* Se la vostra catena esegue un accesso interattivo che legittimamente necessita di più di 60 secondi, come SSO con MFA attraverso un wrapper come `aws-vault`, aumentate il limite in millisecondi con [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/it/env-vars)

688 1087

689<h2 id="network-and-connection-errors">1088Le sessioni autenticate con una chiave API, [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/it/env-vars) o un provider di terze parti non utilizzano il login salvato e non vedono mai questo messaggio.

690 Errori di rete e connessione

691</h2>

692 1089

693Questi errori significano che una richiesta di rete da Claude Code non ha raggiunto la sua destinazione, o qualcosa tra Claude Code e l'API ha alterato la risposta durante il percorso di ritorno. Di solito originano dalla vostra rete locale, proxy o firewall, oppure dalla politica di rete dell'ambiente cloud.1090Potete controllare questo stato prima che una richiesta fallisca: [`/status`](/docs/it/commands) mostra una riga `Login` che legge `Expired — log in again`, più l'organizzazione e l'email che ha salvato per il login scaduto. La riga appare solo quando il login salvato è la Vostra credenziale attiva e non può più essere rinnovato. Le sessioni autenticate in un altro modo non mostrano la riga, anche se un login scaduto rimane salvato. Prima della v2.1.210, `/status` non dava alcuna indicazione in questo stato che un login fosse mai esistito, perché la credenziale cancellata non le lasciava nulla da segnalare.

694 1091

695<h3 id="unable-to-connect-to-api">1092**Cosa fare:**

696 Impossibile connettersi all'API1093

1094* Eseguite `/login` per accedere di nuovo. Riprovare senza accedere mostra lo stesso messaggio su ogni richiesta.

1095* In modalità non interattiva, eseguite `claude` nello stesso ambiente, completate `/login`, quindi rieseguite il Vostro comando. Per l'automazione che non può accedere in modo interattivo, autenticate con `ANTHROPIC_API_KEY` o [generate un token di lunga durata con `claude setup-token`](/docs/it/authentication#generate-a-long-lived-token).

1096* Se l'accesso continua a fallire, vedete [Login e autenticazione](/docs/it/troubleshoot-install#login-and-authentication)

1097

1098<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">

1099 La politica dell'amministratore richiede un accesso al gateway Cloud

697</h3>1100</h3>

698 1101

699La connessione TCP all'API non è riuscita o non si è mai completata.1102Un [impostazione gestita](/docs/it/managed-settings) di un amministratore su questa macchina ha impostato [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) a `"gateway"` o ha impostato [`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl). A meno che non selezioniate un provider cloud attraverso una variabile come `CLAUDE_CODE_USE_BEDROCK`, Claude Code accetta quindi solo l'accesso [gateway delle app Claude](/docs/it/claude-apps-gateway). Vedete uno di due messaggi:

700 1103

701```text theme={null}1104```text theme={null}

702Unable to connect to API. Check your internet connection1105Not signed in to the Cloud gateway — run /login.

703Unable to connect to API (ECONNREFUSED)

704Unable to connect to API (ECONNRESET)

705Unable to connect to API (ETIMEDOUT)

706fetch failed

707Request timed out. Check your internet connection and proxy settings

708```1106```

709 1107

710Le cause comuni includono l'assenza di accesso a Internet, una VPN che blocca `api.anthropic.com`, o un proxy aziendale richiesto che non è configurato.1108Le richieste di modello falliscono con questo messaggio quando la sessione non ha alcun accesso al gateway, ad esempio perché non avete eseguito `/login` da quando la politica ha raggiunto la macchina.

1109

1110Se avete anche una credenziale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` o `apiKeyHelper` configurata e le impostazioni gestite impostano `forceLoginMethod`, Claude Code esce all'avvio invece con un messaggio che inizia:

1111

1112```text theme={null}

1113Administrator policy requires a Cloud gateway sign-in on this machine; the

1114Anthropic-issued credential configured here (ANTHROPIC_API_KEY,

1115ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.

1116```

711 1117

712**Cosa fare:**1118**Cosa fare:**

713 1119

714* Confermate di poter raggiungere l'host dell'API dalla stessa shell eseguendo `curl -I https://api.anthropic.com`. Su Windows PowerShell utilizzate `curl.exe -I https://api.anthropic.com` in modo che l'alias `Invoke-WebRequest` integrato non venga utilizzato.1120* Eseguite `/login` e completate l'accesso sulla schermata **Cloud gateway**

715* Se siete dietro un proxy aziendale, impostate `HTTPS_PROXY` prima di avviare Claude Code e consultate [Configurazione di rete](/docs/it/network-config)1121* Per il messaggio di avvio, rimuovete l'impostazione `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` o `apiKeyHelper` che avete configurato, quindi avviate `claude` ed eseguite `/login`

716* Se instradiate il traffico attraverso un gateway LLM o un relay, impostate [`ANTHROPIC_BASE_URL`](/docs/it/env-vars) al suo indirizzo. Consultate [Connettere Claude Code a un gateway LLM](/docs/it/llm-gateway-connect) per la configurazione.1122* Se ritenete che la macchina non dovrebbe richiedere il gateway, chiedete all'amministratore che la gestisce di rimuovere `forceLoginMethod` e `forceLoginGatewayUrl` dalle sue impostazioni gestite

717* Assicuratevi che il vostro firewall consenta gli host elencati in [Requisiti di accesso di rete](/docs/it/network-config#network-access-requirements)

718* I guasti intermittenti vengono [ritentati automaticamente](#automatic-retries); i guasti persistenti indicano un problema di rete locale

719 1123

720Se `curl` ha successo ma Claude Code continua a fallire, la causa è solitamente qualcosa tra il runtime e la rete piuttosto che la rete stessa:1124Su v2.1.265, una regressione ha anche mostrato il primo messaggio in alcune configurazioni di gateway LLM e proxy che si autenticano con una chiave API, `apiKeyHelper` o intestazioni personalizzate, anche senza alcun requisito di amministratore sulla macchina. Aggiornate alla v2.1.266 o successiva. Non è necessario modificare la Vostra configurazione.

721 1125

722* Su Linux e WSL, controllate `/etc/resolv.conf` per un nameserver non raggiungibile. WSL in particolare può ereditare un resolver rotto dall'host.1126Prima della v2.1.261, su macchine che impostano `forceLoginMethod` a `"gateway"`, Claude Code utilizzava un login salvato rimasto invece di fallire le richieste di modello, e segnalava una credenziale d'ambiente configurata con `This machine's managed settings require a first-party login` invece del messaggio di avvio. Prima della v2.1.265, una macchina le cui impostazioni gestite impostano solo `forceLoginGatewayUrl` non richiedeva l'accesso al gateway, e Claude Code utilizzava una credenziale rimasta lì.

723* Su macOS, un client VPN che è stato disconnesso o disinstallato può lasciare dietro un'interfaccia tunnel o una regola di routing. Controllate `ifconfig` per interfacce `utun` obsolete e rimuovete l'estensione di rete della VPN in Impostazioni di Sistema.

724* Docker Desktop e runtime di container simili possono intercettare il traffico in uscita. Chiudeteli e ritentate per escludere questa possibilità.

725 1127

726<h3 id="bedrock-streaming-response-has-an-unexpected-content-type">1128<h3 id="your-account-is-on-hold">

727 La risposta di streaming di Bedrock ha un content-type inaspettato1129 Il Vostro account è in sospeso

728</h3>1130</h3>

729 1131

730Un gateway o un proxy tra Claude Code e [Amazon Bedrock](/docs/it/amazon-bedrock) sta trasformando il corpo della risposta di streaming o la sua intestazione `Content-Type`. Amazon Bedrock trasmette le risposte come `application/vnd.amazon.eventstream`, e Claude Code rifiuta una risposta di streaming riuscita che segnala un content-type diverso invece di decodificare un corpo che non può leggere. La richiesta non viene ritentata.1132L'account Claude dietro il Vostro login è stato sospeso. Claude Code mostra il primo messaggio quando tenta di rinnovare il Vostro login salvato e apprende della sospensione, e il secondo quando un accesso che completate nel browser lo segnala:

731 1133

732```text theme={null}1134```text theme={null}

733Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.1135Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted

1136Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

734```1137```

735 1138

736Prima della v2.1.208, la stessa configurazione errata si presentava come `API Error: Truncated event message received` dopo che l'intera risposta era stata memorizzata nel buffer.1139L'accesso di nuovo con lo stesso account non cancella il messaggio, perché la sospensione è sull'account piuttosto che sul login. In [modalità non interattiva](/docs/it/headless) (`-p`) e [Agent SDK](/docs/it/agent-sdk/overview), il codice di errore strutturato è `account_on_hold`. Prima della v2.1.235, Claude Code segnalava un account sospeso come [Login scaduto · Please run /login](#login-expired), i cui passaggi di recupero non possono cancellare una sospensione.

737 1140

738**Cosa fare:**1141**Cosa fare:**

739 1142

740* Configurate il gateway per passare il corpo della risposta `InvokeModelWithResponseStream` e la sua intestazione `Content-Type` senza modifiche. Un intermediario che riemette il flusso come server-sent events è una causa comune.1143* Aprite il link nel messaggio per visualizzare i dettagli della sospensione o presentare ricorso

741* Se il gateway riscrive solo l'intestazione e passa il corpo binario intatto, impostate [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/it/env-vars) per saltare il controllo fino a quando il gateway non viene corretto. Consultate [Errori di streaming dietro un gateway o un proxy](/docs/it/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy).1144* Se avete un altro account Claude o una chiave API che non è interessata dalla sospensione, potete continuare a lavorare mentre la sospensione viene risolta: eseguite `/login` con quell'account, oppure impostate la chiave con `ANTHROPIC_API_KEY`

742 1145

743<h3 id="ssl-certificate-errors">1146<h3 id="anthropic-profile-login-expired">

744 Errori di certificato SSL1147 Login del profilo Anthropic scaduto

745</h3>1148</h3>

746 1149

747Un proxy o un'appliance di sicurezza sulla vostra rete sta intercettando il traffico TLS con il proprio certificato, e Claude Code non lo considera attendibile.1150Claude Code si sta autenticando attraverso un profilo di credenziale Anthropic la cui credenziale di login salvata è scaduta, e il profilo non contiene alcuna credenziale di aggiornamento che Claude Code possa utilizzare per rinnovarla. Claude Code ferma ogni richiesta localmente senza riprovare, perché un nuovo tentativo leggerebbe la stessa credenziale scaduta.

748 1151

749```text theme={null}1152```text theme={null}

750Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates1153Anthropic profile login expired · Re-authenticate your Anthropic profile

751Unable to connect to API: Self-signed certificate detected1154Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

752```1155```

753 1156

754A partire dalla v2.1.199, un guasto di convalida del certificato non viene ritentato, quindi questo errore appare al primo tentativo invece che dopo il completo [budget di retry](#automatic-retries). Le versioni precedenti hanno speso alcuni minuti ritentando prima di mostrarlo. Le condizioni TLS transitorie, come un timeout di handshake, continuano a essere ritentate.1157Questo appare solo quando la credenziale attiva proviene da un profilo di credenziale Anthropic, uno che selezionate con la variabile d'ambiente `ANTHROPIC_PROFILE`, che Claude Code scopre come il profilo attivo nella Vostra directory di configurazione Anthropic, o che Claude Code ha scritto quando vi siete [acceduti senza una chiave API](/docs/it/authentication#sign-in-without-an-api-key). Le sessioni che si autenticano con l'opzione claude.ai di `/login`, una chiave API, un token bearer come `ANTHROPIC_AUTH_TOKEN` o un provider di terze parti non vedono mai questo messaggio.

755 1158

756Durante `/login` e il controllo di connettività all'avvio, lo stesso guasto viene segnalato con il codice OpenSSL e la correzione inline:1159Su una macchina che [offre l'accesso senza chiave](/docs/it/authentication#sign-in-without-an-api-key), eseguite `/login`, scegliete l'account Anthropic Console e accedete di nuovo per rinnovare un profilo che l'accesso Console senza chiave o il CLI della Claude Platform `ant auth login` ha scritto. Claude Code sostituisce la credenziale scaduta in quel profilo. Per un profilo di federazione o uno che un altro strumento ha creato, `/login` non rinnova la credenziale. Quale forma vedete dipende dal fatto che abbiate selezionato il profilo o Claude Code l'abbia scoperto:

757 1160

758```text theme={null}1161* Quando impostate `ANTHROPIC_PROFILE` esplicitamente, il messaggio termina con `Re-authenticate your Anthropic profile`.

759SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.1162* Quando Claude Code ha scoperto il profilo dalla Vostra directory di configurazione, il messaggio offre `/login`, perché Claude Code dà la precedenza a un `/login` funzionante rispetto al profilo scoperto e quindi si autentica con il Vostro account claude.ai o Console invece. Prima della v2.1.234, Claude Code mostrava il modulo `Re-authenticate your Anthropic profile` anche in questo caso.

760```

761 1163

762**Cosa fare:**1164**Cosa fare:**

763 1165

764* Esportate il bundle CA della vostra organizzazione e puntate Claude Code ad esso con `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`1166* Accedete di nuovo al profilo, quindi riprovate: su una macchina che [offre l'accesso senza chiave](/docs/it/authentication#sign-in-without-an-api-key), eseguite `/login` e scegliete l'account Anthropic Console per un profilo che l'accesso Console senza chiave o il CLI della Claude Platform `ant auth login` ha scritto; per altri profili, utilizzate lo strumento che li ha creati

765* Consultate [Configurazione di rete](/docs/it/network-config#custom-ca-certificates) per le istruzioni di configurazione complete1167* Se un amministratore ha fornito la credenziale del profilo, chiedetegli di emetterne una nuova

766* Non impostate `NODE_TLS_REJECT_UNAUTHORIZED=0`, che disabilita completamente la convalida del certificato1168* Eseguite `/status` per confermare la fonte di credenziale attiva e il nome del profilo

1169* Per smettere di utilizzare il profilo, annullate l'impostazione di `ANTHROPIC_PROFILE` se l'avete impostato, quindi autenticate in un altro modo, come `/login` o `ANTHROPIC_API_KEY`

767 1170

768<h3 id="host-not-allowed-in-a-cloud-session">1171<h3 id="oauth-scope-requirement">

769 Host non consentito in una sessione cloud1172 Requisito di ambito OAuth

770</h3>1173</h3>

771 1174

772Una richiesta HTTP in uscita da una sessione cloud o routine è stata bloccata dalla politica di rete dell'ambiente.1175Il token memorizzato precede un ambito di autorizzazione che una funzione più recente necessita. Vedete questo più spesso da `/usage` e dall'indicatore di utilizzo della riga di stato:

773 1176

774```text theme={null}1177```text theme={null}

775HTTP 4031178OAuth token does not meet scope requirement: user:profile

776x-deny-reason: host_not_allowed

777```1179```

778 1180

779Potete anche vedere un certificato TLS che non corrisponde al certificato reale della destinazione. L'ambiente cloud instrada il traffico in uscita attraverso un proxy che applica la politica di rete, quindi un certificato non corrispondente significa che il proxy ha terminato la connessione, non la destinazione.

~~780~~

781Questo non è un problema di rete lato client. Le sessioni cloud e le [routine](/docs/it/routines) vengono eseguite all'interno di un ambiente sandbox il cui traffico in uscita è filtrato in base all'allowlist dell'ambiente. L'ambiente **Default** utilizza l'accesso **Trusted**, che consente l'[allowlist predefinito](/docs/it/claude-code-on-the-web#default-allowed-domains) dei registri di pacchetti, API dei provider cloud, registri di container e domini di sviluppo comuni, ma blocca tutto il resto.

~~782~~

783**Cosa fare:**1181**Cosa fare:**

784 1182

785* Aprite la routine per la modifica, o avviate una sessione cloud. Selezionate l'icona cloud che mostra il nome del vostro ambiente, come **Default**, per aprire il selettore. Passate il mouse sopra il vostro ambiente e fate clic sull'icona delle impostazioni.1183* Eseguite `/login` per ottenere un nuovo token con gli ambiti attuali. Non è necessario disconnettervi prima.

786* Nella finestra di dialogo **Update cloud environment**, cambiate **Network access** da **Trusted** a **Custom**, quindi aggiungete il dominio bloccato a **Allowed domains**. Inserite un dominio per riga. Selezionate **Also include default list of common package managers** per mantenere l'[allowlist predefinito](/docs/it/claude-code-on-the-web#default-allowed-domains) insieme ai vostri domini personalizzati. Selezionate **Full** invece se desiderate un accesso senza restrizioni.

787* Fate clic su **Save changes**. L'esecuzione successiva utilizza l'allowlist aggiornato.

~~788~~

789Consultate [Accesso di rete](/docs/it/claude-code-on-the-web#network-access) per i livelli di accesso e l'allowlist predefinito. Le sessioni CLI locali non sono interessate da questa politica.

790 1184

791<h3 id="couldnt-reconnect-to-your-remote-control-session">1185<h3 id="claude-ai-rejected-the-session-token">

792 Impossibile riconnettersi alla sessione Remote Control1186 claude.ai ha rifiutato il token della sessione

793</h3>1187</h3>

794 1188

1189Una richiesta [connettore claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) è fallita perché claude.ai ha rifiutato il token dal Vostro login Claude Code, di solito un login che è scaduto e non ha potuto essere rinnovato. Il token rifiutato è il Vostro login, non l'autorizzazione del connettore in claude.ai, quindi autorizzare di nuovo il connettore non lo risolve. In `/mcp`, il connettore mostra come `connected · session token rejected` e la sua vista dettagliata legge:

1190

795```text theme={null}1191```text theme={null}

796Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.1192claude.ai rejected the session token. Run /login, then reconnect.

797```1193```

798 1194

799La ripresa con `claude --resume` o `claude --continue` si ricollega alla sessione [Remote Control](/docs/it/remote-control) registrata in quella conversazione. Questo messaggio significa che la riconnessione non è riuscita per un motivo che potrebbe essere temporaneo, come un'interruzione di rete o un errore del server, quindi Claude Code non può confermare se la sessione remota esiste ancora. La vostra sessione locale continua a funzionare senza Remote Control.

~~800~~

801**Cosa fare:**1195**Cosa fare:**

802 1196

803* Eseguite `/remote-control` per ritentare la connessione1197* Eseguite `/login` per accedere di nuovo

804* Avviate Claude Code senza `--resume` per creare una nuova sessione Remote Control1198* Riconnettete il connettore da `/mcp`, oppure eseguite `/mcp reconnect <server>`. Riconnettere prima di accedere di nuovo lascia il connettore nello stesso stato. L'opzione **Reconnect** del pannello `/mcp` segnala `your claude.ai session token was rejected`; il modulo `/mcp reconnect <server>` digitato segnala una riconnessione riuscita anche se il token è ancora rifiutato.

805* Per altri messaggi di avvio di Remote Control, consultate [Risoluzione dei problemi di Remote Control](/docs/it/remote-control#troubleshooting)

~~806~~

807Non vedrete questo messaggio quando il server conferma che la sessione precedente non esiste più; Claude Code ne crea una nuova in quel caso. Prima della v2.1.200, qualsiasi guasto di riconnessione creava una nuova sessione Remote Control, il che lasciava sessioni extra nell'elenco delle sessioni su claude.ai/code.

~~808~~

809<h2 id="request-errors">

810 Errori di richiesta

811</h2>

812 1199

813Questi errori riguardano il contenuto della tua richiesta. La maggior parte proviene dall'API dopo che ha rifiutato la richiesta; alcuni sono prodotti localmente da Claude Code prima che venga inviata qualsiasi richiesta.1200Prima della v2.1.222, Claude Code contrassegnava il connettore come necessitante di autenticazione invece, che vi indicava il flusso di autorizzazione del connettore anche se completarlo non risolveva lo stato.

814 1201

815<h3 id="prompt-is-too-long">1202<h3 id="issuer-mismatch-in-authorization-response">

816 Il prompt è troppo lungo1203 Mancata corrispondenza dell'emittente nella risposta di autorizzazione

817</h3>1204</h3>

818 1205

819La conversazione più i file allegati superano la finestra di contesto del modello.1206Durante un [accesso MCP OAuth](/docs/it/mcp#authenticate-with-remote-mcp-servers), il server di autorizzazione ha reindirizzato di nuovo a Claude Code con un parametro `iss` che non nomina l'emittente che Claude Code si aspettava dai metadati OAuth del server. Un emittente sbagliato a questo passaggio è come appare un attacco di mix-up del server di autorizzazione, quindi Claude Code fallisce l'accesso invece di scambiare il codice di autorizzazione. Claude Code mostra l'errore nel menu del server `/mcp` dopo l'accesso del browser:

820 1207

821```text theme={null}1208```text theme={null}

822Prompt is too long1209Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

823```1210```

824 1211

1212`expected` è l'emittente dai metadati OAuth del server, e `received` è il valore `iss` che il reindirizzamento ha trasportato. Un accesso il cui reindirizzamento non trasporta alcun parametro `iss` passa il controllo, a meno che i metadati del server non impostino `authorization_response_iss_parameter_supported`, nel qual caso Claude Code fallisce l'accesso.

1213

825**Cosa fare:**1214**Cosa fare:**

826 1215

827* Esegui `/compact` per riassumere i turni precedenti e liberare spazio, oppure `/clear` per ricominciare da capo1216* Riprovate l'accesso da `/mcp`

828* Esegui `/context` per visualizzare una suddivisione di ciò che consuma la finestra: prompt di sistema, strumenti, file di memoria e messaggi1217* Se l'errore si ripete, segnalarlo all'operatore del server. La correzione è lato server: il server di autorizzazione deve restituire lo stesso emittente nel parametro `iss` che pubblicizza nei suoi metadati

829* Disabilita i server MCP che non stai utilizzando con `/mcp disable <name>` per rimuovere le loro definizioni di strumenti dal contesto1218* Per connettervi mentre il server viene corretto, avviate Claude Code con [`MCP_SDK_GENERATION=v1`](/docs/it/env-vars), il cui [runtime](/docs/it/mcp#mcp-client-runtimes) non esegue questo controllo. Questo rimuove una protezione contro gli attacchi di mix-up, quindi preferite la correzione lato server

830* Riduci i file di memoria `CLAUDE.md` di grandi dimensioni, oppure sposta le istruzioni in [regole con ambito di percorso](/docs/it/memory#path-specific-rules) che si caricano solo quando rilevanti

831* I subagent ereditano ogni definizione di strumento MCP dalla sessione padre, il che può riempire la loro finestra di contesto prima del primo turno. Disabilita i server MCP che non stai utilizzando prima di generare subagent.

832* L'auto-compact è abilitato per impostazione predefinita e normalmente previene questo errore. Se hai impostato [`DISABLE_AUTO_COMPACT`](/docs/it/env-vars), riabilitalo o esegui `/compact` manualmente prima che la finestra si riempia.

833 1219

834Vedi [Esplora la finestra di contesto](/docs/it/context-window) per una visualizzazione interattiva di come il contesto si riempie.1220Prima della v2.1.232, Claude Code utilizzava il runtime v2 solo in un rollout graduale o quando impostavate `MCP_SDK_GENERATION=v2`.

835 1221

836<h3 id="error-during-compaction-conversation-too-long">1222<h3 id="aws-credentials-expired-or-invalid">

837 Errore durante la compattazione: Conversazione troppo lunga1223 Credenziali AWS scadute o non valide

838</h3>1224</h3>

839 1225

840`/compact` stesso ha avuto esito negativo perché non c'è abbastanza contesto libero per contenere il riassunto che produce.1226Questo messaggio richiede Claude Code v2.1.198 o successiva e appare solo quando [`awsAuthRefresh`](/docs/it/amazon-bedrock#advanced-credential-configuration) è impostato nel Vostro file di impostazioni. Il Vostro token di sessione AWS è scaduto o è stato rifiutato, e l'aggiornamento automatico che Claude Code ha già eseguito non ha prodotto una credenziale che l'API accetta. Appare su un 401 da [Claude Platform su AWS](/docs/it/claude-platform-on-aws) o dall'[endpoint Mantle](/docs/it/amazon-bedrock#use-the-mantle-endpoint), che è come quei provider segnalano un token di sicurezza scaduto.

1227

1228Il suggerimento di azione nel mezzo nomina il comando `awsAuthRefresh` dalle Vostre impostazioni, quindi varia. La parte stabile è il `AWS credentials expired or invalid` iniziale:

841 1229

842```text theme={null}1230```text theme={null}

843Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.1231AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

844```1232```

845 1233

846Questo può accadere quando la finestra è già piena nel momento in cui auto-compact si attiva, oppure quando esegui `/compact` dopo aver visto `Prompt is too long`.1234Senza `awsAuthRefresh` configurato, lo stesso 401 mostra il messaggio generico `Please run /login` invece, che non può aggiornare le credenziali AWS.

847 1235

848**Cosa fare:**1236**Cosa fare:**

849 1237

850* Premi Esc due volte per aprire l'elenco dei messaggi e tornare indietro di diversi turni. Questo elimina i messaggi più recenti dal contesto. Quindi esegui `/compact` di nuovo.1238* Eseguite il comando `awsAuthRefresh` nominato nel messaggio, come `aws sso login --profile myprofile`, in un altro terminale e completate l'accesso del browser, quindi riprovate

851* Se tornare indietro non libera abbastanza spazio, esegui `/clear` per avviare una sessione nuova. La tua conversazione precedente viene preservata e può essere riaperta con `/resume`.1239* In una sessione interattiva, eseguite `/login`, scegliete **3rd-party platform**, quindi selezionate **Claude Platform on AWS · refresh credentials** sotto **Using 3rd-party platforms** per eseguire lo stesso comando senza riavviare Claude Code. Vedete [Configurare le credenziali AWS](/docs/it/claude-platform-on-aws#1-configure-aws-credentials)

1240* Se l'errore si ripete dopo che il comando di aggiornamento ha avuto successo, confermate che l'identità è valida al di fuori di Claude Code con `aws sts get-caller-identity` nella stessa shell e profilo

852 1241

853<h3 id="request-too-large">1242<h3 id="aws-authentication-failed">

854 Richiesta troppo grande1243 Autenticazione AWS non riuscita

855</h3>1244</h3>

856 1245

857Il corpo della richiesta grezza ha superato il limite di byte dell'API prima della tokenizzazione, di solito a causa di un file incollato di grandi dimensioni o di un allegato.1246Questo messaggio richiede Claude Code v2.1.198 o successiva e appare solo quando [`awsAuthRefresh`](/docs/it/amazon-bedrock#advanced-credential-configuration) è impostato nel Vostro file di impostazioni. Il Vostro provider AWS ha restituito un 403, oppure [Amazon Bedrock](/docs/it/amazon-bedrock) ha restituito un 401.

1247

1248Claude Code non può dire quale causa avete colpito. Amazon Bedrock segnala un token di sicurezza scaduto come un 403, ma un 403 è anche come segnala un rifiuto di autorizzazione, come un `AccessDeniedException` da un'autorizzazione IAM mancante o un modello che non è abilitato per il Vostro account.

1249

1250Un 401 da Amazon Bedrock atterra anche qui piuttosto che sotto [Credenziali AWS scadute o non valide](#aws-credentials-expired-or-invalid), perché Amazon Bedrock non segnala un token scaduto come un 401. Un 401 da quell'endpoint di solito proviene da qualcos'altro nel percorso della richiesta, come un proxy aziendale.

1251

1252Un aggiornamento delle credenziali corregge un token scaduto e non può correggere le altre cause, quindi il messaggio offre entrambi:

858 1253

859```text theme={null}1254```text theme={null}

860Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.1255AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

861```1256```

862 1257

863Questo è un limite di dimensione sulla richiesta HTTP, separato dal [limite della finestra di contesto](#prompt-is-too-long).1258Il suggerimento di azione nel mezzo nomina il comando `awsAuthRefresh` dalle Vostre impostazioni, quindi varia. La parte stabile è il `AWS authentication failed` iniziale.

864 1259

865**Cosa fare:**1260**Cosa fare:**

866 1261

867* Premi Esc due volte e torna indietro oltre il turno che ha aggiunto il contenuto di dimensioni eccessive1262* Eseguite il comando `awsAuthRefresh` nominato nel messaggio, o `aws sso login`, nel caso in cui una credenziale scaduta sia la causa

868* Fai riferimento ai file di grandi dimensioni per percorso invece di incollarne i contenuti, in modo che Claude possa leggerli in blocchi1263* Se le Vostre credenziali sono attuali, confermate che le autorizzazioni IAM in [Configurazione IAM](/docs/it/amazon-bedrock#iam-configuration) siano allegate all'identità che state utilizzando e che il modello selezionato sia abilitato per il Vostro account e la Vostra regione

869* Per le immagini, vedi [L'immagine era troppo grande](#image-was-too-large) di seguito1264* Eseguite `aws sts get-caller-identity` per confermare quale identità le Vostre richieste utilizzano; un `AWS_PROFILE` obsoleto o un profilo predefinito è una causa comune di una mancata corrispondenza di autorizzazione

870 1265

871<h3 id="image-was-too-large">1266<h3 id="could-not-load-aws-or-google-cloud-credentials">

872 L'immagine era troppo grande1267 Impossibile caricare le credenziali AWS o Google Cloud

873</h3>1268</h3>

874 1269

875Un'immagine incollata o allegata supera i limiti di dimensione o dimensione dell'API.1270Claude Code non ha potuto ottenere credenziali utilizzabili dalla catena del provider di credenziali AWS o dalle Vostre credenziali predefinite dell'applicazione Google sulla macchina su cui viene eseguito, quindi nessuna richiesta ha raggiunto il Vostro provider cloud. Claude Code cancella le Vostre credenziali memorizzate nella cache e ritenta due volte prima di mostrare questo messaggio. Il dettaglio dopo il `·` nomina la causa specifica, come una sessione SSO scaduta, credenziali predefinite mancanti segnalate come `Could not load the default credentials`, o un accesso revocato segnalato come `invalid_grant`:

876 1271

877```text theme={null}1272```text theme={null}

878Image was too large. Double press esc to go back and try again with a smaller image.1273API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.

879API Error: 400 ... image dimensions exceed max allowed size1274API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

880```1275```

881 1276

882Claude Code sostituisce l'immagine non elaborabile con un segnaposto di testo e riprova, quindi i messaggi successivi hanno esito positivo. Nelle versioni precedenti a 2.1.142, un'immagine incollata potrebbe rimanere nella conversazione e ripetere lo stesso errore su ogni messaggio successivo. Per recuperare su quelle versioni, premi Esc due volte e torna indietro oltre il turno in cui è stata aggiunta l'immagine.1277In [modalità non interattiva](/docs/it/headless) con `-p` e in [Agent SDK](/docs/it/agent-sdk/overview), il codice di errore strutturato è `cloud_credential_error`. Prima della v2.1.267, il messaggio mostrava solo il testo di dettaglio dopo `API Error:`, e il codice strutturato era `server_error` o `unknown`.

883 1278

884**Cosa fare:**1279**Cosa fare:**

885 1280

886* Ridimensiona l'immagine prima di incollarla. L'API accetta immagini fino a 8000 pixel sul bordo più lungo per una singola immagine, o 2000 pixel quando molte immagini sono nel contesto.1281* Eseguite il comando di accesso del Vostro provider, come `aws sso login --profile myprofile` o `gcloud auth application-default login`, quindi riprovate. [Credenziali Bedrock, Agent Platform o Foundry non si caricano](/docs/it/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading) mostra come confermare le credenziali al di fuori di Claude Code

887* Fai uno screenshot più stretto della regione rilevante invece dello schermo intero1282* Se il dettaglio legge `AWS default-chain credential resolve timed out`, la catena si è bloccata piuttosto che fallire, quindi seguite [Timeout della risoluzione delle credenziali della catena predefinita AWS](#aws-default-chain-credential-resolve-timed-out) invece

888 1283

889<h3 id="unable-to-resize-image">1284<h3 id="aws-default-chain-credential-resolve-timed-out">

890 Impossibile ridimensionare l'immagine1285 Timeout della risoluzione delle credenziali della catena predefinita AWS

891</h3>1286</h3>

892 1287

893Claude Code non ha potuto ridimensionare un'immagine allegata prima di inviarla all'API.1288La catena del provider di credenziali predefinite AWS non ha prodotto credenziali entro 60 secondi, quindi Claude Code ha fermato la risoluzione e ha fallito la richiesta. Questo timeout è una causa di [Impossibile caricare le credenziali AWS o Google Cloud](#could-not-load-aws-or-google-cloud-credentials). L'errore è la risoluzione delle credenziali locali: la richiesta non ha mai raggiunto [Amazon Bedrock](/docs/it/amazon-bedrock), [Claude Platform su AWS](/docs/it/claude-platform-on-aws) o l'[endpoint Mantle](/docs/it/amazon-bedrock#use-the-mantle-endpoint). Claude Code cancella la Vostra [cache delle credenziali](/docs/it/amazon-bedrock#credential-caching-and-resolution-timeout) e ritenta prima che questo errore emerga, quindi al momento in cui lo vedete la catena si è bloccata su tentativi ripetuti.

894 1289

895```text theme={null}1290```text theme={null}

896Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.1291API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

897Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.

898Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.

899Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

900```1292```

901 1293

902Claude Code normalmente ridimensiona automaticamente le immagini di grandi dimensioni. Questi errori significano che il processore di immagini nativo non ha potuto caricarsi o ha restituito un errore, quindi l'immagine non potrebbe essere ridimensionata per rientrare nei limiti dell'API.1294Le cause comuni sono un comando `credential_process` nel Vostro profilo AWS che attende un input che non può ricevere, e un contenitore o una VM il cui servizio di metadati dell'istanza (IMDS) non risponde mai al probe della catena.

1295

1296Prima della v2.1.267, il messaggio leggeva `API Error: AWS default-chain credential resolve timed out`.

1297Prima della v2.1.207, una catena bloccata lasciava la richiesta in attesa indefinitamente invece di fallire.

903 1298

904**Cosa fare:**1299**Cosa fare:**

905 1300

906* Se il messaggio ti chiede di convertire l'immagine, convertila in PNG, JPEG, GIF o WebP e allegala di nuovo. Claude Code può verificare le dimensioni per questi formati senza il processore di immagini.1301* Eseguite `aws sts get-caller-identity` nella stessa shell con lo stesso `AWS_PROFILE`. Se si blocca anche, correggete il profilo; un comando `credential_process` che richiede in modo interattivo è una causa comune.

907* Se il messaggio segnala un limite di dimensione o dimensione, ridimensiona o ricomprimi l'immagine al di sotto di quel limite prima di allegare.1302* Completate il passaggio di accesso prima di avviare Claude Code, ad esempio `aws sso login --profile myprofile`, in modo che la catena si risolva dalla cache SSO locale invece di attendere un flusso del browser

1303* Se la Vostra catena esegue un accesso interattivo che legittimamente ha bisogno di più di 60 secondi, come SSO con MFA attraverso un wrapper come `aws-vault`, aumentate il limite in millisecondi con [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/it/env-vars)

908 1304

909<h3 id="pdf-errors">1305<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">

910 Errori PDF1306 Timeout della verifica della configurazione di Bedrock in attesa di AWS

911</h3>1307</h3>

912 1308

913Il PDF che hai allegato non potrebbe essere elaborato.1309Una chiamata ad AWS durante la [procedura guidata di configurazione di Bedrock](/docs/it/amazon-bedrock#sign-in-with-bedrock), come la ricerca delle credenziali o il controllo dell'identità, non è stata completata entro il limite di 60 secondi. La procedura guidata smette di attendere e fallisce il passaggio di verifica:

914 1310

915```text theme={null}1311```text theme={null}

916PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.1312Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

917PDF is password protected. Try removing protection or extracting text first.

918The PDF file was not valid. Try converting to a different format first.

919```1313```

920 1314

921**Cosa fare:**1315Il numero riflette il Vostro limite: 60 secondi per impostazione predefinita, o il valore che impostate in [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/it/env-vars).

~~922~~

923* Per i PDF di grandi dimensioni, chiedi a Claude di leggere un intervallo di pagine con lo strumento Read invece di allegare l'intero file, oppure estrai il testo con uno strumento come `pdftotext` e fai riferimento al file di output per percorso

924* Per i PDF protetti o non validi, rimuovi la password o riesporta il file dall'applicazione sorgente, quindi riprova

925 1316

926<h3 id="extra-inputs-are-not-permitted">1317Le cause comuni sono una rete o un proxy che blocca le richieste ad AWS, incluso l'aggiornamento del token SSO, e un helper di credenziali ancora in attesa di input che non potete vedere. Aumentate il limite solo quando l'helper legittimamente ha bisogno di più tempo.

927 Gli input aggiuntivi non sono consentiti

928</h3>

929 1318

930Un proxy o un gateway LLM tra Claude Code e l'API ha rimosso l'intestazione della richiesta `anthropic-beta`, quindi l'API ha rifiutato i campi che dipendono da essa.1319Una singola richiesta bloccata ad AWS può anche fallire sul suo timeout per richiesta, che mostra un messaggio più breve sullo stesso passaggio:

931 1320

932```text theme={null}1321```text theme={null}

933API Error: 400 ... Extra inputs are not permitted ... context_management1322A request to AWS timed out. Check your network and proxy settings, then try again.

934API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples

935API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

936```1323```

937 1324

938Claude Code invia campi solo beta come `context_management`, `effort` e `input_examples` dello strumento insieme a un'intestazione `anthropic-beta` che li abilita. Quando un gateway inoltra il corpo ma elimina l'intestazione, l'API vede campi che non riconosce.1325Quando gli stessi timeout si verificano sul passaggio di pin del modello, la procedura guidata contrassegna un modello come `unreachable` invece di mostrare uno dei due messaggi.

939 1326

940**Cosa fare:**1327**Cosa fare:**

941 1328

942* Configura il tuo gateway per inoltrare l'intestazione `anthropic-beta`. Vedi [feature pass-through](/docs/it/llm-gateway-protocol#feature-pass-through) per ciò che i gateway devono inoltrare.1329* Eseguite `aws sts get-caller-identity` nella stessa shell. Se si blocca anche, il blocco è al di fuori di Claude Code, nella Vostra rete, nel Vostro proxy o nell'helper di credenziali nel Vostro profilo AWS; correggete prima quello.

943* Come fallback, imposta [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/it/env-vars) prima di avviare. Questo disabilita le funzioni che richiedono l'intestazione beta in modo che le richieste abbiano esito positivo attraverso un gateway che non può inoltrarla.1330* Completate qualsiasi accesso interattivo prima di aprire la procedura guidata, ad esempio `aws sso login --profile myprofile`

1331* Se un helper di credenziali nel Vostro profilo AWS legittimamente ha bisogno di più di 60 secondi per richiedervi, aumentate il limite in millisecondi con [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/it/env-vars)

944 1332

945<h3 id="theres-an-issue-with-the-selected-model">1333<h3 id="cloud-gateway-session-expired">

946 C'è un problema con il modello selezionato1334 Sessione del gateway cloud scaduta

947</h3>1335</h3>

948 1336

949Il nome del modello configurato non è stato riconosciuto o il tuo account non ha accesso ad esso. A partire da v2.1.160 il suggerimento finale, mostrato qui nella sua forma interattiva, varia in base alla superficie.1337Vi siete acceduti attraverso un [gateway delle app Claude](/docs/it/claude-apps-gateway), e la sessione del gateway salvata su questa macchina è scaduta e non ha potuto essere rinnovata, oppure il gateway non la accetta più, ad esempio dopo che il [JWT secret del gateway è stato sostituito](/docs/it/claude-apps-gateway-deploy#jwt-secret-rotation). Se vedete questa riga quando avviate `claude` in modo interattivo, la sessione si è aperta disconnessa dal gateway:

950 1338

951```text theme={null}1339```text theme={null}

952There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.1340Cloud gateway session expired — run /login to reconnect.

953```1341```

954 1342

955**Cosa fare:**1343La stessa riga può apparire a metà sessione quando la credenziale del gateway scade e Claude Code non può rinnovarla.

~~956~~

957* **CLI interattiva**: esegui `/model` per scegliere dai modelli disponibili per il tuo account.

958* **Modalità non interattiva (`-p`)**: passa `--model` con un alias o ID valido, oppure imposta [`ANTHROPIC_MODEL`](/docs/it/env-vars). Il testo di errore mostra `Run --model` su questa superficie.

959* **Agent SDK**: il testo di errore omette il suggerimento perché il modello è impostato a livello di programmazione. Imposta [`model` su `Options`](/docs/it/agent-sdk/typescript#options) in TypeScript o [`ClaudeAgentOptions(model=...)`](/docs/it/agent-sdk/python#claudeagentoptions) in Python, e gestisci l'errore strutturato `model_not_found` per visualizzare il tuo ritentativo o selettore di modello.

960* Usa un alias come `sonnet` o `opus` invece di un ID completamente versionato. Gli alias si risolvono in un valore predefinito mantenuto in modo che non diventino obsoleti. Vedi [Configurazione del modello](/docs/it/model-config).

961* Se il modello sbagliato continua a tornare nella CLI, un ID obsoleto è impostato da qualche parte. Controlla in [ordine di priorità](/docs/it/model-config#setting-your-model): il flag `--model`, la variabile di ambiente `ANTHROPIC_MODEL`, quindi il campo `model` in `.claude/settings.local.json`, il `.claude/settings.json` del tuo progetto e `~/.claude/settings.json`. Rimuovi il valore obsoleto e Claude Code torna al valore predefinito del tuo account.

962* Claude Code segnala un accesso a claude.ai scaduto come [Accesso scaduto](#login-expired), non come questo errore. Prima di v2.1.206, un accesso scaduto che non poteva più essere aggiornato ha avuto esito negativo con ogni modello con questo errore; esegui `/login` se vedi questo su una versione precedente.

963* Per le distribuzioni di Google Cloud's Agent Platform, vedi [Risoluzione dei problemi di Google Cloud's Agent Platform](/docs/it/google-vertex-ai#troubleshooting).

~~964~~

965<h3 id="model-is-not-a-recognized-model-id">

966 Il modello non è un ID modello riconosciuto

967</h3>

968 1344

969La stringa del modello che hai passato a un cambio di modello non è un alias di modello, un ID di modello che questa versione di Claude Code conosce, o un ID che inizia con `claude-`. Le cause comuni sono un errore di battitura nell'ID, un nome visualizzato come `Sonnet 5` dove è previsto l'ID `claude-sonnet-5`, o un alias che solo le versioni più recenti di Claude Code riconoscono. Claude Code rifiuta il cambio immediatamente. Prima di v2.1.200, Claude Code salvava la stringa e aveva esito negativo sulla richiesta successiva con [C'è un problema con il modello selezionato](#theres-an-issue-with-the-selected-model).1345In un'esecuzione [non interattiva](/docs/it/headless), una sessione in background o altra sessione incustodita, o un sottocomando `claude` diverso da `claude auth`, Claude Code esce con questo messaggio invece quando il gateway non accetta più la sessione:

970 1346

971```text theme={null}1347```text theme={null}

972Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?1348Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

973```1349```

974 1350

975Il suggerimento finale nomina l'alias o l'ID del modello più vicino. Quando nulla è abbastanza vicino, legge `Run /model to see available models.` invece.1351**Cosa fare:**

976 1352

977Claude Code produce questo errore localmente nel momento in cui il cambio è richiesto, prima che venga effettuata qualsiasi richiesta API. Si applica quando un modello è impostato tramite il metodo [Agent SDK](/docs/it/agent-sdk/typescript) `setModel()` o da un'app come l'[app Desktop](/docs/it/desktop) che esegue la CLI di Claude Code per te.1353* Eseguite `/login` nella sessione e completate l'accesso del browser

1354* Per un lancio non interattivo, avviate `claude` nello stesso ambiente, eseguite `/login`, quindi rieseguite il Vostro comando

978 1355

979**Cosa fare:**1356<h2 id="network-and-connection-errors">

1357 Errori di rete e connessione

1358</h2>

980 1359

981* Esegui `/model` senza argomenti per aprire il selettore e scegli dai modelli disponibili per il tuo account, quindi passa l'alias o l'ID mostrato lì1360La maggior parte di questi errori significa che una richiesta di rete da Claude Code non ha raggiunto la sua destinazione, oppure qualcosa tra Claude Code e l'API ha alterato la risposta durante il percorso; quando una voce ha anche una causa locale, come un'archivio fallito, il corpo lo specifica. Di solito originano dalla tua rete locale, proxy o firewall, oppure dalla politica di rete dell'ambiente cloud.

982* Se hai utilizzato un alias che una versione più recente di Claude Code supporta, esegui `claude update`. Un ID completo che inizia con `claude-` passa questo controllo anche quando il modello è più recente della tua versione di Claude Code, quindi l'aggiornamento non è necessario per quelli.

983* Un modello salvato prima di v2.1.200 non viene riparato da questo controllo. Se un valore obsoleto continua a tornare, rimuovilo dalle posizioni elencate in [C'è un problema con il modello selezionato](#theres-an-issue-with-the-selected-model).

984* Il controllo viene eseguito solo sull'API Anthropic. Su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](/docs/it/claude-platform-on-aws) e dietro un [gateway LLM](/docs/it/llm-gateway) o un `ANTHROPIC_BASE_URL` personalizzato, il tuo provider o gateway definisce i nomi dei modelli, quindi Claude Code accetta qualsiasi stringa e la passa attraverso.

985 1361

986<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">1362<h3 id="unable-to-connect-to-api">

1363 Unable to connect to API

1364</h3>

1365

1366La connessione TCP all'API non è riuscita o non si è mai completata. Per i codici di errore di connessione comuni, il nome del messaggio specifica il tipo di errore e mantiene il codice tra parentesi:

1367

1368```text theme={null}

1369Unable to connect to API. Check your internet connection

1370Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)

1371Can't reach the API server — check your internet or DNS (ENOTFOUND)

1372No internet route — check your connection or VPN (EHOSTUNREACH)

1373Couldn't connect through your proxy (ERR_PROXY_TUNNEL)

1374Connection dropped (ECONNRESET)

1375fetch failed

1376Request timed out. Check your internet connection and proxy settings

1377```

1378

1379Un codice che Claude Code non riconosce appare come `Unable to connect to API` seguito dal codice tra parentesi. Alcuni di questi messaggi possono mostrare più di un codice: `Connection refused` può mostrare `ConnectionRefused` o `ECONNREFUSED`, ad esempio, e `Can't reach the API server` può mostrare `ENOTFOUND` o `FailedToOpenSocket`.

1380

1381Prima della v2.1.227, ognuno di questi messaggi codificati leggeva `Unable to connect to API` seguito dal codice, ad esempio `Unable to connect to API (ECONNREFUSED)`.

1382

1383Le cause comuni includono nessun accesso a Internet, una VPN che blocca `api.anthropic.com`, o un proxy aziendale richiesto che non è configurato.

1384

1385**Cosa fare:**

1386

1387* Conferma di poter raggiungere l'host API dalla stessa shell eseguendo `curl -I https://api.anthropic.com`. Su Windows PowerShell usa `curl.exe -I https://api.anthropic.com` in modo che l'alias `Invoke-WebRequest` integrato non sia utilizzato.

1388* Se sei dietro un proxy aziendale, imposta `HTTPS_PROXY` prima di avviare Claude Code e vedi [Network configuration](/docs/it/network-config)

1389* Se instrada attraverso un gateway LLM o un relay, imposta [`ANTHROPIC_BASE_URL`](/docs/it/env-vars) al suo indirizzo. Vedi [Connect Claude Code to an LLM gateway](/docs/it/llm-gateway-connect) per la configurazione.

1390* Assicurati che il tuo firewall consenta gli host elencati in [Network access requirements](/docs/it/network-config#network-access-requirements)

1391* I guasti intermittenti vengono [ritentati automaticamente](#automatic-retries); i guasti persistenti indicano un problema di rete locale

1392

1393Se `curl` ha successo ma Claude Code continua a fallire, la causa è solitamente qualcosa tra il runtime e la rete piuttosto che la rete stessa:

1394

1395* Su Linux e WSL, controlla `/etc/resolv.conf` per un nameserver non raggiungibile. WSL in particolare può ereditare un resolver rotto dall'host.

1396* Su macOS, un client VPN che è stato disconnesso o disinstallato può lasciare dietro un'interfaccia tunnel o una regola di routing. Controlla `ifconfig` per interfacce `utun` stantie e rimuovi l'estensione di rete della VPN in Impostazioni di Sistema.

1397* Docker Desktop e runtime di container simili possono intercettare il traffico in uscita. Chiudili e riprova per escludere questa possibilità.

1398

1399<h3 id="unable-to-connect-to-anthropic-services">

1400 Unable to connect to Anthropic services

1401</h3>

1402

1403Durante la configurazione della prima esecuzione, Claude Code verifica di poter raggiungere `api.anthropic.com` e `platform.claude.com` prima di mostrare il passaggio di accesso. Quando uno dei controlli fallisce, Claude Code stampa il motivo ed esce.

1404

1405```text theme={null}

1406Unable to connect to Anthropic services

1407Failed to connect to api.anthropic.com: ECONNREFUSED

1408Connection to api.anthropic.com timed out after 10 seconds

1409A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

1410```

1411

1412Claude Code invia il controllo attraverso la stessa [proxy configuration](/docs/it/network-config) delle richieste API e assegna a ogni sonda 10 secondi. Quando la sonda fallita è passata attraverso un proxy, il messaggio nomina la variabile di ambiente che l'ha configurata, come `HTTPS_PROXY`. Prima della v2.1.222, il controllo utilizzava un diverso trasporto proxy senza timeout: dietro un URL proxy con lo schema `https://`, potrebbe bloccarsi su `Checking connectivity...` indefinitamente e poi fallire anche se le richieste API attraverso lo stesso proxy hanno successo.

1413

1414Claude Code salta questo controllo quando un [managed settings file, MDM policy, o policy helper](/docs/it/managed-settings) imposta [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod) a `"gateway"`, o imposta [`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl) senza `forceLoginMethod`. Con entrambe le configurazioni, Claude Code apre il passaggio di accesso sulla schermata **Cloud gateway** piuttosto che su un metodo di accesso Anthropic. Claude Code salta anche il controllo quando una fonte di managed settings sulla macchina esiste ma non può essere letta, poiché quella fonte potrebbe contenere la configurazione del gateway. Prima della v2.1.247, Claude Code eseguiva il controllo anche sotto questa configurazione e usciva con questo errore quando gli endpoint di Anthropic non erano raggiungibili.

1415

1416**Cosa fare:**

1417

1418* Se il messaggio nomina una variabile proxy, controlla che il suo valore punti al proxy giusto e chiedi al tuo team di rete di consentire connessioni HTTPS attraverso di esso all'host nel messaggio. Vedi [Network configuration](/docs/it/network-config).

1419* Lavora attraverso i controlli in [Unable to connect to API](#unable-to-connect-to-api). Il test `curl` e la guida del firewall lì si applicano anche a questo controllo.

1420* Se la tua organizzazione accede attraverso un [cloud gateway](/docs/it/claude-apps-gateway) e questo errore appare al primo avvio, aggiorna a Claude Code v2.1.247 o successivo.

1421* Se la tua rete è aperta e il guasto persiste, Claude Code potrebbe non essere [disponibile nel tuo paese](https://www.anthropic.com/supported-countries)

1422

1423<h3 id="socket-is-closed">

1424 Socket is closed

1425</h3>

1426

1427`Socket is closed` significa che la connessione che trasporta una risposta in streaming è stata chiusa mentre la risposta stava ancora arrivando. La causa più comune è un proxy aziendale su Windows che interrompe un tunnel stabilito a metà risposta.

1428

1429A seconda di quanto la risposta era progredita, Claude Code ritenta la richiesta, mantiene ciò che Claude ha prodotto, o termina il turno. Vedi [Automatic retries](#automatic-retries).

1430

1431Prima della v2.1.214, Claude Code non ritentava questo guasto e il turno si fermava con un errore contenente `Socket is closed`.

1432

1433**Cosa fare:**

1434

1435* Se vedi questo errore, aggiorna a v2.1.214 o successivo con `claude update`, quindi invia di nuovo il tuo messaggio

1436* Se i turni continuano a fallire dietro lo stesso proxy dopo l'aggiornamento, lavora attraverso [Unable to connect to API](#unable-to-connect-to-api) e controlla la configurazione del proxy in [Network configuration](/docs/it/network-config)

1437

1438<h3 id="api-returned-an-empty-or-malformed-response">

1439 API returned an empty or malformed response

1440</h3>

1441

1442Claude Code mostra questo errore quando il suo ritentativo non in streaming di una richiesta in streaming fallita ottiene uno stato HTTP di successo ma il corpo non è un messaggio API Claude: comunemente una pagina di errore HTML o di accesso, un corpo vuoto, o JSON in un altro formato. Un proxy, gateway, o pagina di accesso di rete che risponde al posto dell'API è la solita fonte. Claude Code non ritenta la richiesta e il turno termina con questo errore.

1443

1444```text theme={null}

1445API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

1446```

1447

1448Dopo quell'apertura, il messaggio segnala ciò che è tornato e quale richiesta ha fallito:

1449

1450* Una clausola `Response:` con il tipo di contenuto, il tipo di corpo, come `body is an HTML page` o `empty body`, la sua dimensione in byte, e se la risposta ha portato un id di richiesta Anthropic. Quando la risposta nomina un server riconoscibile, come `nginx` o `cloudflare`, o porta intestazioni intermediarie, come `cf-ray` o `via`, la clausola elenca anche quelli.

1451* Una frase che nomina l'id della richiesta in streaming fallita e il guasto che ha attivato il ritentativo. Quando uno stream si era aperto prima del guasto, segnala anche quanti eventi di stream sono arrivati e, se ce ne sono stati, quanto tempo lo stream era stato silenzioso quando il tentativo è fallito.

1452

1453Prima della v2.1.234, il messaggio terminava dopo `intercepting the request`.

1454

1455**Cosa fare:**

1456

1457* Leggi la clausola `Response:` per vedere quale sistema ha risposto. Un corpo HTML, nessun id di richiesta Anthropic, o un server nominato come `nginx` o `cloudflare` significa che qualcosa tra Claude Code e l'API ha risposto al suo posto

1458* Se instrada attraverso un [LLM gateway](/docs/it/llm-gateway-connect#troubleshoot-gateway-errors), testa il percorso con una richiesta diretta e correggi l'hop che restituisce la risposta non-API

1459* Su una rete con una pagina di accesso, come Wi-Fi ospite, completa l'accesso in un browser, quindi riprova

1460* Se solo il percorso non in streaming attraverso il tuo gateway è rotto, imposta [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`](/docs/it/env-vars#variables) in modo che una richiesta che fallisce a metà stream vada al percorso di ritentativo normale invece di questo fallback, tranne quando l'endpoint di streaming stesso restituisce `404`, dove Claude Code continua comunque a fare fallback

1461

1462<h3 id="streaming-response-ended-before-any-complete-data-was-received">

1463 Streaming response ended before any complete data was received

1464</h3>

1465

1466Una risposta in streaming dal tuo provider di modelli è stata completata senza fornire dati utilizzabili, quindi Claude Code ha reinviato la richiesta senza streaming per terminare il turno. Claude Code mostra l'avviso una volta per sessione, solo in sessioni interattive. Prima della v2.1.239, Claude Code ritentava silenziosamente senza streaming.

1467

1468```text theme={null}

1469Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

1470```

1471

1472Claude Code invia ogni richiesta interessata due volte: il tentativo di streaming vuoto e il ritentativo. La causa solita è un proxy o gateway che consuma o trasforma il corpo della risposta in streaming durante il percorso di ritorno.

1473

1474**Cosa fare:**

1475

1476* Configura qualsiasi proxy o gateway tra Claude Code e il tuo provider di modelli per passare i corpi della risposta in streaming e le loro intestazioni senza modifiche

1477* Su [Amazon Bedrock](/docs/it/amazon-bedrock), vedi [Streaming errors behind a gateway or proxy](/docs/it/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy) per i requisiti di intestazione e corpo

1478

1479<h3 id="bedrock-streaming-response-has-an-unexpected-content-type">

1480 Bedrock streaming response has an unexpected content-type

1481</h3>

1482

1483Un gateway o proxy tra Claude Code e [Amazon Bedrock](/docs/it/amazon-bedrock) sta trasformando il corpo della risposta in streaming o la sua intestazione `Content-Type`. Amazon Bedrock trasmette le risposte come `application/vnd.amazon.eventstream`. Piuttosto che decodificare un corpo che non può leggere, Claude Code rifiuta una risposta in streaming riuscita che segnala un content-type diverso. Claude Code non ritenta la richiesta.

1484

1485```text theme={null}

1486Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

1487```

1488

1489Prima della v2.1.208, la stessa configurazione errata è emersa come `API Error: Truncated event message received` dopo che l'intera risposta era stata memorizzata nel buffer.

1490

1491**Cosa fare:**

1492

1493* Configura il gateway per passare il corpo della risposta `InvokeModelWithResponseStream` e la sua intestazione `Content-Type` senza modifiche. Un intermediario che ri-emette lo stream come server-sent events è una causa comune.

1494* Impostare [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/it/env-vars) nasconde questo errore, ma Claude Code non decodifica un corpo binario sotto un'intestazione riscritta, quindi quelle richieste ricadono in un percorso più lento non in streaming. Vedi [Streaming errors behind a gateway or proxy](/docs/it/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy).

1495

1496<h3 id="ssl-certificate-errors">

1497 SSL certificate errors

1498</h3>

1499

1500Un proxy o appliance di sicurezza sulla tua rete sta intercettando il traffico TLS con il suo certificato, e Claude Code non lo ritiene attendibile.

1501

1502```text theme={null}

1503Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

1504Unable to connect to API: Self-signed certificate detected. Check your proxy or corporate SSL certificates

1505```

1506

1507A partire dalla v2.1.199, un guasto di convalida del certificato non viene ritentato, quindi questo errore appare al primo tentativo invece che dopo il [retry budget](#automatic-retries) completo. Le versioni precedenti spendevano alcuni minuti ritentando prima di mostrarlo. Le condizioni TLS transitorie, come un timeout di handshake, continuano a ritentare.

1508

1509Durante `/login` e il controllo di connettività all'avvio, lo stesso guasto è segnalato con il codice OpenSSL e la correzione inline:

1510

1511```text theme={null}

1512SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

1513```

1514

1515Su [Amazon Bedrock](/docs/it/amazon-bedrock), le richieste che Claude Code stesso invia ad AWS, come le chiamate di credenziale di ruolo STS e SSO, la scoperta del modello, e i controlli della procedura guidata di configurazione, dipendono dalla stessa configurazione del certificato. Vedi [Certificate errors behind a TLS-inspecting proxy](/docs/it/amazon-bedrock#certificate-errors-behind-a-tls-inspecting-proxy).

1516

1517**Cosa fare:**

1518

1519* Esporta il bundle CA della tua organizzazione e punta Claude Code ad esso con `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`

1520* Vedi [Network configuration](/docs/it/network-config#custom-ca-certificates) per le istruzioni di configurazione complete

1521* Non impostare `NODE_TLS_REJECT_UNAUTHORIZED=0`, che disabilita completamente la convalida del certificato

1522

1523<h3 id="host-not-allowed-in-a-cloud-session">

1524 Host not allowed in a cloud session

1525</h3>

1526

1527Una richiesta HTTP in uscita da una sessione cloud o routine è stata bloccata dalla politica di rete dell'ambiente.

1528

1529```text theme={null}

1530HTTP 403

1531x-deny-reason: host_not_allowed

1532```

1533

1534Potresti anche vedere un certificato TLS che non corrisponde al certificato reale della destinazione. Le sessioni cloud instradano il traffico in uscita attraverso un proxy che applica la politica di rete, quindi un certificato non corrispondente significa che il proxy ha terminato la connessione, non la destinazione.

1535

1536Questo non è un problema di rete lato client. Le sessioni cloud e [routines](/docs/it/routines) vengono eseguite all'interno di una VM sandbox la cui rete di traffico in uscita attraverso la rete della sessione è filtrata alla [allowlist dell'ambiente cloud](/docs/it/cloud-environments); le [operazioni GitHub](/docs/it/cloud-environments#github-proxy) e il traffico del connettore MCP utilizzano canali separati, motivo per cui possono continuare a funzionare mentre altri host sono bloccati. L'ambiente **Default** utilizza accesso **Trusted**, che consente la [allowlist predefinita](/docs/it/cloud-environments#default-allowed-domains) di registri di pacchetti, API di provider cloud, registri di container, e domini di sviluppo comuni e blocca altri domini su quel percorso.

1537

1538**Cosa fare:**

1539

1540* Apri la routine per la modifica, o avvia una sessione cloud. Seleziona l'icona cloud che mostra il nome del tuo ambiente, come **Default**, per aprire il selettore. Passa il mouse sopra il tuo ambiente e fai clic sull'icona delle impostazioni.

1541* Nella finestra di dialogo **Update cloud environment**, cambia **Network access** da **Trusted** a **Custom**, quindi aggiungi il dominio bloccato a **Allowed domains**. Inserisci un dominio per riga. Seleziona **Also include default list of common package managers** per mantenere la [allowlist predefinita](/docs/it/cloud-environments#default-allowed-domains) insieme ai tuoi domini personalizzati. Seleziona **Full** invece se desideri accesso senza restrizioni.

1542* Fai clic su **Save changes**. La prossima esecuzione utilizza l'allowlist aggiornata.

1543

1544Vedi [Network access](/docs/it/cloud-environments#network-access) per i livelli di accesso e l'allowlist predefinita. Le sessioni CLI locali non sono interessate da questa politica.

1545

1546<h3 id="the-proxy-refused-the-connection">

1547 The proxy refused the connection

1548</h3>

1549

1550Vedi questo messaggio quando Claude legge un [artifact](/docs/it/artifacts) attraverso il proxy che hai impostato in `HTTPS_PROXY` o una [proxy variable](/docs/it/network-config#environment-variables) correlata. Il contenuto dell'artifact proviene da `*.frame.claudeusercontent.com`, quindi Claude Code invia prima al proxy una richiesta `CONNECT` chiedendogli di aprire un tunnel a quell'host. Quando il proxy rifiuta, nulla raggiunge l'host, e il messaggio porta lo stato HTTP del proxy:

1551

1552```text theme={null}

1553artifact content fetch failed (proxy refused the connection: HTTP 407)

1554artifact content fetch failed (proxy refused the connection: HTTP 403)

1555the proxy refused the connection to the artifact's content host (HTTP 502)

1556```

1557

1558Lo stato è la risposta del proxy al `CONNECT`. L'host non ha mai risposto, quindi ogni stato punta a una correzione diversa:

1559

1560* `HTTP 407`: il proxy richiede credenziali che non ha ricevuto. Mettile nell'URL del proxy, come mostra [Basic authentication](/docs/it/network-config#basic-authentication).

1561* `HTTP 403`: il proxy rifiuta di fare tunnel a `*.frame.claudeusercontent.com`. Chiedi a chiunque gestisca il proxy di consentire quell'host, che [Network access requirements](/docs/it/network-config#network-access-requirements) elenca.

1562* Qualsiasi altro stato, come `HTTP 502`: il proxy non ha aperto il tunnel per suo motivo, come il mancato raggiungimento dell'host. Cerca lo stato nei log del proxy.

1563* `unreadable reply` al posto di uno stato: qualunque cosa sia all'indirizzo del proxy non ha risposto con una riga di stato HTTP. Controlla che l'indirizzo sia un proxy HTTP.

1564

1565**Cosa fare:**

1566

1567* Controlla l'indirizzo e le credenziali nella variabile proxy, come descrive [Proxy configuration](/docs/it/network-config#proxy-configuration), quindi esegui `curl -x http://proxy.example.com:8080 -I https://api.anthropic.com` dalla shell in cui avvii Claude Code, usando il tuo URL proxy. Su Windows PowerShell, esegui `curl.exe`. Se questa sonda fallisce allo stesso modo, correggi prima la configurazione del proxy. Se ha successo, il rifiuto è specifico dell'host dell'artifact.

1568* Se la tua rete consente a Claude Code di raggiungere l'host dell'artifact direttamente, aggiungi `.frame.claudeusercontent.com` a [`NO_PROXY`](/docs/it/network-config#environment-variables). Mantieni la voce stretta: una voce `.claudeusercontent.com` più ampia bypassa anche il proxy per `bridge.claudeusercontent.com`, che le organizzazioni con [IP allowlisting](/docs/it/network-config#organization-ip-allowlists-and-proxy-egress) devono mantenere sul proxy.

1569

1570Prima della v2.1.238, Claude Code segnalava un tunnel rifiutato come un errore di rete generico.

1571

1572<h3 id="the-cloud-environments-service-returned-an-empty-or-unexpected-response">

1573 The cloud environments service returned an empty or unexpected response

1574</h3>

1575

1576Claude Code richiede il tuo elenco di [cloud environments](/docs/it/cloud-environments) in diversi punti, come quando crei una sessione cloud dalla CLI o esegui [`/remote-env`](/docs/it/cloud-environments#select-an-environment-from-the-cli). Quando non riesce a leggere la risposta del server, mostra uno di questi messaggi:

1577

1578```text theme={null}

1579The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.

1580The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.

1581The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

1582```

1583

1584Il server ha accettato la richiesta ma ha risposto con un corpo che non è l'elenco degli ambienti: vuoto, non JSON, o JSON senza l'elenco. Questo di solito accompagna un'interruzione lato servizio e si risolve da solo. A seconda della superficie che ha richiesto l'elenco, Claude Code può aggiungere un prefisso, come `couldn't list environments:` nella finestra di dialogo `/remote-env`.

1585

1586**Cosa fare:**

1587

1588* Ritenta l'azione. Claude Code richiede di nuovo l'elenco ogni volta

1589* Se il messaggio continua ad apparire, controlla [status.claude.com](https://status.claude.com) per gli incidenti attivi

1590

1591Prima della v2.1.236, Claude Code mostrava un TypeError JavaScript grezzo invece di questi messaggi.

1592

1593<h3 id="couldnt-reconnect-to-your-remote-control-session">

1594 Couldn't reconnect to your Remote Control session

1595</h3>

1596

1597```text theme={null}

1598Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

1599```

1600

1601La ripresa con `claude --resume` o `claude --continue` si riconnette alla sessione [Remote Control](/docs/it/remote-control) registrata in quella conversazione. Questo messaggio significa che la riconnessione è fallita per un motivo che potrebbe essere temporaneo, come un'interruzione di rete o un errore del server, quindi Claude Code non può confermare se la sessione remota esiste ancora. La tua sessione locale continua a funzionare senza Remote Control.

1602

1603**Cosa fare:**

1604

1605* Esegui `/remote-control` per ritentare la connessione

1606* Avvia una nuova sessione con `claude --remote-control` per creare una nuova sessione Remote Control

1607* Per altri messaggi di avvio di Remote Control, vedi [Troubleshoot Remote Control](/docs/it/remote-control#troubleshooting)

1608

1609Se il server segnala invece che la sessione precedente è scomparsa, non vedi questo messaggio. Claude Code avvia una nuova sessione al suo posto o mostra [`Previous session is unavailable — run /remote-control to start a new one`](/docs/it/remote-control#previous-session-is-unavailable), a seconda del [record di riconnessione della conversazione](/docs/it/remote-control#resume-outcomes). Dalla v2.1.227 alla v2.1.231, Claude Code mostrava un messaggio che inizia con `Remote Control could not resume the previous session under the current login` invece, e le [versioni precedenti si comportavano diversamente di nuovo](/docs/it/remote-control#reconnect-history).

1610

1611<h3 id="sessions-ended-while-this-machine-was-offline">

1612 Sessions ended while this machine was offline

1613</h3>

1614

1615Claude Code mostra questo messaggio nel terminale che esegue [`claude remote-control`](/docs/it/remote-control#start-a-remote-control-session) dopo che la tua macchina è stata offline abbastanza a lungo che il server ha pulito l'ambiente Remote Control che la tua macchina stava servendo. Le sessioni in quell'ambiente sono terminate e non puoi riprendere. Il conteggio è il numero di sessioni che sono terminate.

1616

1617```text theme={null}

16182 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

1619```

1620

1621**Cosa fare:**

1622

1623* Quando Claude Code elenca i worktrees mantenuti sotto questo messaggio, raccogli qualsiasi lavoro non committato da loro

1624* Esegui `claude remote-control` per avviare un ambiente nuovo

1625

1626<h3 id="couldnt-share-the-transcript">

1627 Couldn't share the transcript

1628</h3>

1629

1630Dopo che accetti di condividere la trascrizione della tua sessione da un prompt di sondaggio, come il [session quality survey](/docs/it/data-usage#session-quality-surveys), Claude Code la carica su Anthropic, o salva un archivio locale invece su provider di terze parti, su sessioni [Claude apps gateway](/docs/it/claude-apps-gateway), e quando nessuna credenziale Anthropic è disponibile. Questo messaggio significa che la condivisione non è stata completata.

1631

1632```text theme={null}

1633Couldn't share the transcript.

1634```

1635

1636Il caricamento deve rientrare in un limite di 8 MiB. Su una sessione lunga, Claude Code progressivamente elimina parti della condivisione, le impostazioni del modello dell'ultima richiesta per prime, quindi la conversazione strutturata e le trascrizioni dei subagent, e mostra questo messaggio solo quando nessuna versione ridotta può essere inviata o un errore di rete o server interrompe il caricamento. Quando Claude Code salva un archivio locale invece, il messaggio significa che non poteva scrivere l'archivio.

1637

1638**Cosa fare:**

1639

1640* Esegui `/feedback` per inviare la trascrizione con una descrizione di ciò che è accaduto. Vedi [Report an error](#report-an-error) se `/feedback` non è disponibile nel tuo ambiente

1641* Se anche altre richieste stanno fallendo, controlla la tua connessione di rete e vedi [Unable to connect to API](#unable-to-connect-to-api)

1642

1643<h2 id="request-errors">

1644 Errori di richiesta

1645</h2>

1646

1647Questi errori riguardano il contenuto della Vostra richiesta. La maggior parte proviene dall'API dopo che ha rifiutato la richiesta; alcuni sono prodotti localmente da Claude Code prima che venga inviata qualsiasi richiesta.

1648

1649<h3 id="prompt-is-too-long">

1650 Prompt troppo lungo

1651</h3>

1652

1653La conversazione più i file allegati superano la finestra di contesto del modello.

1654

1655```text theme={null}

1656Prompt is too long

1657```

1658

1659In una sessione interattiva, Claude Code mostra questo errore come:

1660

1661```text theme={null}

1662Context limit reached · /compact or /clear to continue

1663```

1664

1665La riga nomina solo `/clear` quando [`DISABLE_COMPACT`](/docs/it/env-vars) è impostato. Le forme più lunghe dell'errore, come la forma di compattazione non riuscita di seguito, mantengono la dicitura `Prompt is too long ·`. Nell'output `-p` e nella trascrizione, il testo rimane `Prompt is too long`.

1666

1667Quando avete disattivato la compattazione automatica nelle Vostre [impostazioni utente](/docs/it/settings-reference#autocompactenabled), la riga dice anche:

1668

1669```text theme={null}

1670Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

1671```

1672

1673L'interruttore **Auto-compact** in `/config` scrive `autoCompactEnabled` nelle impostazioni utente. L'hint appare solo quando una modifica `/config` avrebbe effetto. Ad esempio, non appare quando [`DISABLE_AUTO_COMPACT`](/docs/it/env-vars) o [`DISABLE_COMPACT`](/docs/it/env-vars) ha disattivato la compattazione automatica. Non appare nemmeno quando un ambito di precedenza superiore, come le impostazioni di progetto o gestite, ha impostato `autoCompactEnabled` su `false`. Prima della v2.1.235, la riga non conteneva alcun hint di compattazione automatica.

1674

1675Amazon Bedrock segnala questa condizione come `Input is too long for requested model.`, che Claude Code gestisce allo stesso modo. Prima della v2.1.217, Claude Code non riconosceva la dicitura di Bedrock, quindi la compattazione automatica non si attivava mai e `/compact` falliva con lo stesso errore.

1676

1677Un [gateway di app Claude](/docs/it/claude-apps-gateway-config#upstream-error-messages) segnala questa condizione come `capability_rejected: prompt_too_long` quando un upstream cloud rifiuta la richiesta nella forma di errore propria del provider. Claude Code tratta il token come `Prompt is too long`. Prima della v2.1.228, Claude Code non riconosceva il token, quindi la compattazione automatica non si attivava.

1678

1679Quando la compattazione automatica è stata eseguita su questo turno e ha fallito su un errore sottostante, come un modello non disponibile o un errore di autenticazione, il messaggio nomina quell'errore dopo un separatore:

1680

1681```text theme={null}

1682Prompt is too long · automatic compaction failed: <the underlying error>

1683```

1684

1685Risolvete prima l'errore nominato; `/compact` fallisce sullo stesso errore finché non lo fate. Prima della v2.1.229, una compattazione automatica non riuscita mostrava `Prompt is too long` senza la causa.

1686

1687Una conversazione a singolo scambio non ha turni precedenti da riassumere. Quando la compattazione automatica si sarebbe eseguita su uno, Claude Code salta il tentativo e spiega cosa riempie la richiesta. Quando l'API non segnala i conteggi dei token nel suo errore, il messaggio recita:

1688

1689```text theme={null}

1690Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

1691```

1692

1693Quando l'API segnala i conteggi dei token nel suo errore, Claude Code li confronta con la sua stima della dimensione della conversazione per dire quale è la maggior parte della richiesta: il contenuto della conversazione stessa, o il prompt di sistema, le definizioni degli strumenti e il contenuto degli allegati che Claude Code invia con essa. Quando il contenuto della conversazione è la maggior parte della richiesta, il messaggio recita:

1694

1695```text theme={null}

1696Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

1697```

1698

1699Quando la maggior parte della richiesta è al di fuori della conversazione, il messaggio recita:

1700

1701```text theme={null}

1702Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

1703```

1704

1705Prima della v2.1.162, Claude Code tentava comunque la compattazione e mostrava il semplice `Prompt is too long` quando falliva.

1706

1707**Cosa fare:**

1708

1709* In una conversazione multi-turno, eseguite `/compact` per riassumere i turni precedenti e liberare spazio, oppure `/clear` per ricominciare da capo. Una conversazione a singolo scambio non può essere compattata, quindi riducete la richiesta

1710* Eseguite `/context` per vedere una suddivisione di ciò che consuma la finestra: prompt di sistema, strumenti, file di memoria e messaggi

1711* Disabilitate i server MCP che non state utilizzando con `/mcp disable <name>` per rimuovere le loro definizioni di strumenti dal contesto

1712* Tagliate i file di memoria `CLAUDE.md` di grandi dimensioni, oppure spostate le istruzioni in [regole con ambito di percorso](/docs/it/memory#path-specific-rules) che si caricano solo quando rilevanti

1713* I subagent ereditano ogni definizione di strumento MCP dalla sessione padre, che può riempire la loro finestra di contesto prima del primo turno. Disabilitate i server MCP che non state utilizzando prima di generare subagent.

1714* La compattazione automatica è attiva per impostazione predefinita e normalmente previene questo errore. Se l'avete disattivata in `/config` o con [`DISABLE_AUTO_COMPACT`](/docs/it/env-vars), riattivatela. Se la mantenete disattivata, eseguite `/compact` voi stessi prima che la finestra si riempia.

1715

1716Vedete [Explore the context window](/docs/it/context-window) per una visualizzazione interattiva di come il contesto si riempie.

1717

1718<h3 id="context-exceeds-the-token-limit">

1719 Il contesto supera il limite di token

1720</h3>

1721

1722`/context` mostra questo avviso in cima al suo output quando la conversazione ha superato la finestra di contesto del modello. Le richieste falliscono con [`Prompt is too long`](#prompt-is-too-long) finché non liberate spazio. Una sessione interattiva mostra quell'errore come la riga `Context limit reached`.

1723

1724```text theme={null}

1725Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

1726```

1727

1728Quando il limite che avete superato è una finestra di compattazione più piccola della finestra di contesto del modello, come il limite di 200K su modelli con contesto 1M, l'avviso recita diversamente. Le richieste hanno ancora successo oltre una finestra di compattazione; eseguite il comando nominato per riportare l'utilizzo sotto di essa.

1729

1730```text theme={null}

1731Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

1732```

1733

1734Entrambe le forme nominano `/clear` invece di `/compact` quando avete impostato [`DISABLE_COMPACT`](/docs/it/env-vars).

1735

1736**Cosa fare:**

1737

1738* In una conversazione multi-turno, eseguite `/compact` per riassumere i turni precedenti e liberare spazio. Per ricominciare da capo, eseguite `/clear`

1739* Per altri modi di ridurre l'utilizzo, vedete [Prompt is too long](#prompt-is-too-long)

1740

1741Prima della v2.1.216, `/context` mostrava l'utilizzo sopra il 100% senza una riga di avviso che spiegasse cosa significava o come recuperare.

1742

1743<h3 id="error-during-compaction-conversation-too-long">

1744 Errore durante la compattazione: Conversazione troppo lunga

1745</h3>

1746

1747`/compact` stesso ha fallito perché non c'è abbastanza contesto libero per contenere il riassunto che produce.

1748

1749```text theme={null}

1750Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

1751```

1752

1753Questo può accadere quando la finestra è già piena nel momento in cui la compattazione automatica si attiva, oppure quando eseguite `/compact` dopo aver visto [`Prompt is too long`](#prompt-is-too-long). In una sessione interattiva, quell'errore è la riga `Context limit reached`.

1754

1755**Cosa fare:**

1756

1757* Premete Esc due volte per aprire l'elenco dei messaggi e tornare indietro di diversi turni. Questo elimina i messaggi più recenti dal contesto. Quindi eseguite `/compact` di nuovo.

1758* Se tornare indietro non libera abbastanza spazio, eseguite `/clear` per avviare una sessione nuova. La Vostra conversazione precedente è preservata e può essere riaperta con `/resume`.

1759

1760Questo messaggio e altri fallimenti di `/compact` vengono visualizzati nello stile di errore. Prima della v2.1.216, venivano renderizzati nello stesso stile attenuato dell'output di comando riuscito, quindi potevate leggere una compattazione non riuscita come un successo.

1761

1762<h3 id="request-too-large">

1763 Richiesta troppo grande

1764</h3>

1765

1766Il corpo della richiesta grezza ha superato il limite di 32MB dell'API prima della tokenizzazione, solitamente a causa di contenuto incollato di grandi dimensioni, risultati di strumenti o allegati. Questo limite è separato dalla [finestra di contesto](#prompt-is-too-long).

1767

1768```text theme={null}

1769Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

1770```

1771

1772Quando la richiesta è andata direttamente all'API Claude e l'API stessa l'ha rifiutata, Claude Code misura la conversazione e formula il messaggio in base al fatto che il recupero possa funzionare. Attraverso un proxy, gateway o provider cloud ottenete il messaggio generale. Le forme misurate:

1773

1774* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: le immagini o i documenti hanno spinto la richiesta oltre il limite. Claude Code ritenta con essi rimossi.

1775* `Request too large for the API's 32MB request limit`: i messaggi da soli superano il limite, quindi il messaggio dice `compacting cannot make it fit` e Claude Code non ritenta. In [modalità non interattiva](/docs/it/headless), il messaggio vi dice di ridurre l'input o avviare una nuova sessione.

1776

1777Prima della v2.1.212, le conversazioni con abbastanza immagini accumulate fallivano ad ogni turno con `Request too large (max 32MB). Double press esc to go back and try with a smaller file.` Prima della v2.1.229, Claude Code mostrava il consiglio di allegato per ogni rifiuto, anche quando la compattazione non poteva aiutare.

1778

1779**Cosa fare:**

1780

1781* Se il messaggio dice `compacting cannot make it fit`, premete Esc due volte per tornare indietro oltre il turno che ha aggiunto il contenuto di grandi dimensioni, oppure eseguite `/clear` per ricominciare da capo

1782* Altrimenti, eseguite `/compact`, che elimina le immagini e gli allegati accumulati

1783* Fate riferimento ai file di grandi dimensioni per percorso invece di incollarne i contenuti, in modo che Claude possa leggerli in blocchi

1784* Per le immagini, vedete [Image was too large](#image-was-too-large) di seguito

1785

1786<h3 id="image-was-too-large">

1787 L'immagine era troppo grande

1788</h3>

1789

1790Un'immagine incollata o allegata supera i limiti di dimensione o dimensione dell'API.

1791

1792```text theme={null}

1793Image was too large. Double press esc to go back and try again with a smaller image.

1794API Error: 400 ... image dimensions exceed max allowed size

1795```

1796

1797Claude Code sostituisce l'immagine non elaborabile con un segnaposto di testo e ritenta, quindi i messaggi successivi hanno successo. Nelle versioni precedenti alla 2.1.142, un'immagine incollata poteva rimanere nella conversazione e ripetere lo stesso errore ad ogni messaggio successivo. Per recuperare su quelle versioni, premete Esc due volte e tornate indietro oltre il turno in cui l'immagine è stata aggiunta.

1798

1799**Cosa fare:**

1800

1801* Ridimensionate l'immagine prima di incollarla. L'API accetta immagini fino a 8000 pixel sul lato più lungo per una singola immagine, o 2000 pixel quando molte immagini sono nel contesto.

1802* Fate uno screenshot più stretto della regione rilevante invece dello schermo intero

1803

1804<h3 id="unable-to-resize-image">

1805 Impossibile ridimensionare l'immagine

1806</h3>

1807

1808Claude Code non ha potuto ridimensionare un'immagine allegata prima di inviarla all'API.

1809

1810```text theme={null}

1811Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.

1812Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.

1813Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.

1814Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

1815Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.

1816Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.

1817Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

1818```

1819

1820Claude Code normalmente ridimensiona automaticamente le immagini di grandi dimensioni. Questi errori significano che l'immagine non poteva essere decodificata o ridimensionata per rientrare nei limiti dell'API.

1821

1822**Cosa fare:**

1823

1824* Se il messaggio vi chiede di convertire l'immagine, convertitela in PNG, JPEG, GIF o WebP e allegatela di nuovo. Claude Code può verificare le dimensioni per questi formati dall'intestazione del file, senza decodificare l'immagine.

1825* Se il messaggio segnala un limite di dimensione o dimensione, ridimensionate o ricomprimete l'immagine al di sotto di quel limite prima di allegarla.

1826* Se il messaggio nomina una causa, come un JPEG CMYK, un WebP animato o un file possibilmente danneggiato, risalvate l'immagine nel formato che il messaggio suggerisce e allegatela di nuovo.

1827

1828<h3 id="pdf-errors">

1829 Errori PDF

1830</h3>

1831

1832Il PDF che avete allegato non poteva essere elaborato. I messaggi sono mostrati qui nella loro forma non interattiva; in una sessione interattiva invece vi chiedono di premere esc due volte e riprovare.

1833

1834```text theme={null}

1835PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).

1836PDF is password protected. Try using a CLI tool to extract or convert the PDF.

1837The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

1838```

1839

1840**Cosa fare:**

1841

1842* Per i PDF di grandi dimensioni, chiedete a Claude di leggere un intervallo di pagine con lo strumento Read invece di allegare l'intero file, oppure estraete il testo con uno strumento come `pdftotext` e fate riferimento al file di output per percorso

1843* Per i PDF protetti o non validi, rimuovete la password o riesportate il file dall'applicazione sorgente, quindi riprovate

1844

1845<h3 id="extra-inputs-are-not-permitted">

1846 Gli input extra non sono consentiti

1847</h3>

1848

1849Un proxy o gateway LLM tra Claude Code e l'API ha rimosso l'intestazione della richiesta `anthropic-beta`, quindi l'API ha rifiutato i campi che dipendono da essa.

1850

1851```text theme={null}

1852API Error: 400 ... Extra inputs are not permitted ... context_management

1853API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

1854```

1855

1856Claude Code invia campi solo beta come `context_management` e `effort` insieme a un'intestazione `anthropic-beta` che li abilita. Quando un gateway inoltra il corpo ma elimina l'intestazione, l'API vede campi che non riconosce.

1857

1858**Cosa fare:**

1859

1860* Configurate il Vostro gateway per inoltrare l'intestazione `anthropic-beta`. Vedete [feature pass-through](/docs/it/llm-gateway-protocol#feature-pass-through) per ciò che i gateway devono inoltrare.

1861* Come fallback, impostate [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/it/env-vars) prima di avviare. [Disable pre-release capabilities](/docs/it/llm-gateway-protocol#disable-pre-release-capabilities) copre l'ambito esatto.

1862

1863<h3 id="tool-input-schema-is-invalid">

1864 Lo schema di input dello strumento non è valido

1865</h3>

1866

1867Uno strumento nella richiesta ha dichiarato un `input_schema` che non supera la convalida JSON Schema dell'API, quindi l'API ha rifiutato l'intera richiesta. Il numero dopo `tools.` è la posizione dello strumento che fallisce nell'elenco degli strumenti della richiesta, non un nome che potete cercare.

1868

1869```text theme={null}

1870API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid

1871API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

1872```

1873

1874La prima forma significa che lo schema non è uno schema JSON valido draft 2020-12. La seconda significa che un nome di proprietà di livello superiore non corrisponde al pattern che il messaggio cita.

1875

1876Claude Code [esclude gli strumenti MCP il cui schema di input fallirebbe questa convalida](/docs/it/mcp#tools-with-invalid-input-schemas) quando carica gli strumenti di un server, quindi le richieste normalmente non ne includono mai uno.

1877

1878Su un [deployment dove il recupero dei flag è disattivato](/docs/it/env-vars#features-that-need-feature-flag-fetching), o su una macchina i cui flag non sono mai arrivati, Claude Code registra nel log del server quale strumento verrebbe rifiutato ma lo invia comunque, quindi questo errore può ancora verificarsi.

1879

1880L'errore può anche verificarsi per uno strumento il cui schema dichiara un dialetto JSON Schema diverso da draft 2020-12 in `$schema`. Claude Code non controlla questi schemi rispetto al meta-schema JSON Schema, anche se il controllo del nome della proprietà di livello superiore si applica comunque.

1881

1882Prima della v2.1.216, nessun deployment eseguiva i controlli di esclusione.

1883

1884**Cosa fare:**

1885

1886* Se la Vostra versione di Claude Code è precedente alla v2.1.216, eseguite `claude update`.

1887* Rimuovete o [disabilitate](/docs/it/mcp#disable-a-server-without-removing-it) il server MCP che dichiara lo schema non valido. L'errore nomina lo strumento solo per posizione. Sulla v2.1.216 o successiva, controllate il log di ogni server per una riga che nomina uno strumento il cui schema di input verrebbe rifiutato. Se nessun log ne nomina uno, disabilitate i server uno alla volta.

1888* Se mantenete il server, correggete l'`input_schema` dello strumento. Lo schema deve essere uno schema JSON valido, e i nomi delle proprietà di livello superiore devono essere da 1 a 64 caratteri e usare solo lettere ASCII e cifre, `_`, `.` e `-`. Vedete [Tools with invalid input schemas](/docs/it/mcp#tools-with-invalid-input-schemas).

1889

1890<h3 id="theres-an-issue-with-the-selected-model">

1891 C'è un problema con il modello selezionato

1892</h3>

1893

1894Il nome del modello configurato non è stato riconosciuto o il Vostro account non ha accesso ad esso. A partire dalla v2.1.160 l'hint finale, mostrato qui nella sua forma interattiva, varia per superficie.

1895

1896```text theme={null}

1897There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

1898```

1899

1900**Cosa fare:**

1901

1902* **CLI interattiva**: eseguite `/model` per scegliere dai modelli disponibili per il Vostro account.

1903* **Modalità non interattiva (`-p`)**: passate `--model` con un alias o ID valido, oppure impostate [`ANTHROPIC_MODEL`](/docs/it/env-vars). Il testo di errore mostra `Run --model` su questa superficie.

1904* **Agent SDK**: il testo di errore omette l'hint perché il modello è impostato a livello di programmazione. Impostate [`model` su `Options`](/docs/it/agent-sdk/typescript#options) in TypeScript o [`ClaudeAgentOptions(model=...)`](/docs/it/agent-sdk/python#claudeagentoptions) in Python, e gestite l'errore strutturato `model_not_found` per mostrare il Vostro proprio ritentativo o selettore di modello.

1905* Usate un alias come `sonnet` o `opus` invece di un ID completo con versione. Gli alias si risolvono in un valore predefinito mantenuto in modo che non diventino obsoleti. Vedete [Model configuration](/docs/it/model-config).

1906* Se il modello sbagliato continua a tornare nella CLI, un ID obsoleto è impostato da qualche parte. Controllate i posti in cui potete impostare un modello in [ordine di priorità](/docs/it/model-config#setting-your-model) e rimuovete il valore obsoleto.

1907* Un modello appena lanciato può essere disponibile sull'API Anthropic prima che Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry lo offra. Se avete fissato un nuovo ID modello su uno di questi provider e vedete questo errore, controllate il catalogo dei modelli del Vostro provider per la disponibilità nella Vostra regione, e mantenete la versione precedente fissata finché quella nuova non appare lì.

1908* Claude Code segnala un login claude.ai scaduto come [Login expired](#login-expired), non come questo errore. Prima della v2.1.206, un login scaduto che non poteva più essere aggiornato falliva ad ogni modello con questo errore; eseguite `/login` se lo vedete su una versione più vecchia.

1909* Per i deployment di Google Cloud's Agent Platform, vedete [Google Cloud's Agent Platform troubleshooting](/docs/it/google-vertex-ai#troubleshooting).

1910

1911<h3 id="model-is-not-a-recognized-model-id">

1912 Il modello non è un ID modello riconosciuto

1913</h3>

1914

1915La stringa di modello che avete passato a un cambio di modello non è un alias di modello, un ID di modello che questa versione di Claude Code conosce, o un ID che inizia con `claude-`. Le cause solite sono un errore di battitura nell'ID, un nome visualizzato come `Sonnet 5` dove è previsto l'ID `claude-sonnet-5`, o un alias che solo le versioni più recenti di Claude Code riconoscono. Claude Code rifiuta il cambio immediatamente. Prima della v2.1.200, Claude Code salvava la stringa e falliva alla richiesta successiva con [There's an issue with the selected model](#theres-an-issue-with-the-selected-model).

1916

1917```text theme={null}

1918Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

1919```

1920

1921L'hint finale nomina l'alias o l'ID modello più simile. Quando nulla è abbastanza simile, recita `Run /model to see available models.` invece.

1922

1923Claude Code produce questo errore localmente nel momento in cui il cambio è richiesto, prima che venga effettuata qualsiasi richiesta API. Si applica quando un modello è impostato attraverso il metodo [Agent SDK](/docs/it/agent-sdk/typescript) `setModel()`, da un'app come l'[app Desktop](/docs/it/desktop) che esegue la CLI di Claude Code per voi, o quando scegliete un modello da un dispositivo connesso attraverso [Remote Control](/docs/it/remote-control). Prima della v2.1.260, il controllo non copriva le scelte di Remote Control, quindi Claude Code applicava la scelta e la richiesta successiva falliva con [There's an issue with the selected model](#theres-an-issue-with-the-selected-model).

1924

1925**Cosa fare:**

1926

1927* Eseguite `/model` senza argomenti per aprire il selettore e scegliere dai modelli disponibili per il Vostro account, quindi passate l'alias o l'ID mostrato lì

1928* Se avete usato un alias che una versione più recente di Claude Code supporta, eseguite `claude update`. Un ID completo che inizia con `claude-` passa questo controllo locale anche quando il modello è più recente della Vostra versione di Claude Code. Il server può comunque richiedere una versione minima per quel modello; vedete [Claude Code does not support this model](#claude-code-does-not-support-this-model).

1929* Un modello salvato prima della v2.1.200 non viene riparato da questo controllo. Se un valore obsoleto continua a tornare, rimuovetelo dalle posizioni elencate sotto [Setting your model](/docs/it/model-config#setting-your-model).

1930* Il controllo viene eseguito solo sull'API Anthropic. Su qualsiasi altro provider o gateway, incluso un `ANTHROPIC_BASE_URL` personalizzato, il provider definisce i nomi dei modelli, quindi Claude Code accetta qualsiasi stringa e lo passa. Claude Code può comunque scrivere la [riga diagnostica di modello non riconosciuto](#unrecognized-model-id-on-a-request) al momento della richiesta, su ogni provider.

1931

1932<h3 id="model-not-found">

1933 Modello non trovato

1934</h3>

1935

1936Avete scelto un modello con `/model <name>` e Claude Code non ha potuto confermare che esista un modello con quel nome. Quando il nome non è un [alias di modello](/docs/it/model-config#model-aliases) o un'altra ortografia che Claude Code accetta localmente, `/model` lo verifica con una richiesta API minima, e questo errore è solitamente la risposta del Vostro endpoint API. Un nome che non può essere un ID modello affatto, come uno contenente spazi, riceve lo stesso messaggio.

1937

1938```text theme={null}

1939Model 'claude-opus-9' not found

1940```

1941

1942Su provider con ID modello specifici del provider, il messaggio può aggiungere un suggerimento `Try '...' instead` che nomina l'ID del Vostro provider per un modello di fallback.

1943

1944**Cosa fare:**

1945

1946* Eseguite `/model` senza argomenti e scegliete dai modelli disponibili per il Vostro account, oppure usate un [alias di modello](/docs/it/model-config#model-aliases) come `sonnet`, che si risolve in un valore predefinito mantenuto

1947* Se avete digitato un ID completo, controllarlo rispetto al catalogo dei modelli del Vostro provider. Un modello appena lanciato può essere disponibile sull'API Anthropic prima che il Vostro provider o regione lo offra.

1948* Prima della v2.1.265, `/model` rifiutava anche l'ortografia dell'alias `opusplan[1m]` con questo errore. Su quelle versioni, aggiornate Claude Code, oppure impostate il modello in [settings](/docs/it/model-config#setting-your-model) o con `--model` invece.

1949

1950<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

987 Claude Opus non è disponibile con il piano Claude Pro1951 Claude Opus non è disponibile con il piano Claude Pro

988</h3>1952</h3>

989 1953

990Il tuo piano di abbonamento attivo non include il modello che hai selezionato.1954Il Vostro piano di abbonamento attivo non include il modello che avete selezionato.

1955

1956```text theme={null}

1957Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

1958```

1959

1960**Cosa fare:**

1961

1962* Eseguite `/model` e selezionate un modello che il Vostro piano include

1963* Se avete aggiornato il Vostro piano di recente e lo vedete ancora, eseguite `/logout` quindi `/login`. Il token memorizzato riflette il Vostro piano al momento in cui avete effettuato l'accesso, quindi l'aggiornamento sul web non ha effetto in una sessione esistente finché non vi autenticate di nuovo.

1964* Vedete [claude.com/pricing](https://claude.com/pricing) per quali modelli ogni piano include

1965

1966<h3 id="claude-code-does-not-support-this-model">

1967 Claude Code non supporta questo modello

1968</h3>

1969

1970L'API ha rifiutato la richiesta con un 400 perché la Vostra versione di Claude Code è inferiore a un minimo richiesto. O il modello che avete selezionato richiede una versione più recente, che il server controlla per modello, oppure la politica della Vostra organizzazione ne richiede una. Il 400 porta il codice di errore `claude_code_version_too_old`, e il messaggio dice quale minimo si applica.

1971

1972```text theme={null}

1973API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.

1974```

1975

1976La dicitura della politica organizzativa recita:

1977

1978```text theme={null}

1979API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.

1980```

1981

1982**Cosa fare:**

1983

1984* Eseguite `claude update`, oppure aggiornate l'app Claude desktop, quindi avviate una nuova sessione

1985* Per la dicitura per modello, potete continuare a lavorare nella sessione corrente passando a un altro modello con `/model`

1986* Per la dicitura della politica organizzativa, aggiornate prima di continuare

1987

1988<h3 id="model-is-restricted-by-your-organizations-settings">

1989 Il modello è limitato dalle impostazioni della Vostra organizzazione

1990</h3>

1991

1992L'amministratore della Vostra organizzazione ha disabilitato questo modello nella console di amministrazione claude.ai, oppure è escluso da un elenco di consentiti [`availableModels`](/docs/it/model-config#restrict-model-selection) nelle impostazioni gestite. Quando il modello limitato è stato impostato con `--model`, `ANTHROPIC_MODEL` o l'impostazione `model`, Claude Code sostituisce un modello consentito e continua. Digitare `/model <name>` per un modello limitato viene rifiutato con `Run /model to choose a different model.` e la sessione mantiene il suo modello corrente.

1993

1994```text theme={null}

1995Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

1996```

1997

1998Un avviso con prefisso un nome di agente, skill o comando significa che la restrizione si è applicata al [modello richiesto di quel subagent](/docs/it/sub-agents#choose-a-model): il subagent viene eseguito sul modello sostituito e il modello della Vostra sessione rimane invariato. Prima della v2.1.223, Claude Code mostrava l'avviso solo per i subagent lanciati con lo strumento Agent.

1999

2000Claude Code tratta un alias di famiglia di modelli, uno di `opus`, `sonnet`, `haiku` o `fable`, come una richiesta per quella famiglia piuttosto che per la sua versione più recente. Sull'API Anthropic e su [Claude Platform on AWS](/docs/it/claude-platform-on-aws), un alias di famiglia limitato si risolve nella versione più recente della famiglia che la Vostra organizzazione e l'elenco di consentiti `availableModels` consentono, e l'avviso di sostituzione nomina quella versione. Claude Code rifiuta `/model <alias>` solo quando ogni versione della famiglia è limitata. Prima della v2.1.205, un alias di famiglia veniva sostituito o rifiutato in base alla sua versione più recente sola, anche quando una versione più vecchia della stessa famiglia era consentita.

2001

2002**Cosa fare:**

2003

2004* Eseguite `/model` per scegliere dai modelli che la Vostra organizzazione consente. I modelli limitati sono nascosti dal selettore.

2005* Se il modello limitato è stato impostato in `--model`, `ANTHROPIC_MODEL`, il campo `model` di un file di impostazioni, o il frontmatter `model` di un [subagent](/docs/it/sub-agents#choose-a-model), skill o comando, rimuovete o aggiornate quel valore in modo che l'avviso non si ripeta

2006* Se avete bisogno di accesso al modello limitato, chiedete all'amministratore della Vostra organizzazione di abilitarlo. Vedete [Organization model restrictions](/docs/it/model-config#organization-model-restrictions).

2007

2008<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">

2009 Il cambio di modello è stato bloccato da un hook PreModelSwitch

2010</h3>

2011

2012Un [hook PreModelSwitch](/docs/it/hooks#premodelswitch) non ha approvato il cambio di modello che voi o un client avete richiesto, quindi la sessione mantiene il suo modello corrente. Quando il cambio è venuto da un host [Agent SDK](/docs/it/agent-sdk/overview) o [Remote Control](/docs/it/remote-control) piuttosto che da un comando che avete digitato, il messaggio recita `Model switch blocked by a PreModelSwitch hook` senza nominare il modello di destinazione.

2013

2014```text theme={null}

2015Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.

2016```

2017

2018La ragione dopo i due punti dice cosa ha rifiutato il cambio:

2019

2020* **Una ragione che un hook ha scritto**: un hook PreModelSwitch ha fornito quella ragione quando ha [negato il cambio o chiesto conferma](/docs/it/hooks#premodelswitch-decision-control). Affrontate ciò che chiede, oppure scegliete un modello che i Vostri hook consentono.

2021* **`PreModelSwitch hook <name> did not respond before its timeout`**: un hook che non risponde prima del suo [timeout](/docs/it/hooks#timeouts) blocca il cambio. Correggete il comando sospeso o aumentate il `timeout` di quell'hook, quindi cambiate di nuovo.

2022* **`confirmation required, and this session cannot ask`**: un hook ha risposto `ask` senza una ragione, e una richiesta di controllo non ha modo di mostrare il prompt di conferma. Un comando `/model` in un'esecuzione [`-p`](/docs/it/headless) segnala la stessa condizione con `(run /model interactively to confirm)` dopo la ragione. Effettuate il cambio da una sessione interattiva, oppure cambiate la decisione dell'hook per questo modello.

2023* **`so organization-managed PreModelSwitch hooks could not be checked`**: Claude Code non ha potuto dire quali hook PreModelSwitch i [plugin gestiti](/docs/it/settings-reference#enabledplugins) della Vostra organizzazione forniscono, ad esempio perché un plugin gestito non ha caricato. Uno di questi hook potrebbe bloccare il cambio, quindi Claude Code rifiuta piuttosto che applicare il cambio non controllato. L'inizio della ragione nomina cosa ha fallito. Claude Code ricontrolla ad ogni tentativo di cambio, quindi un fallimento che da allora si è chiarito smette di bloccare; se continua a fallire, eseguite `claude --debug` e cambiate di nuovo per catturare i dettagli, quindi correggete il plugin o chiedete al Vostro admin di correggerlo.

2024* **`a PreModelSwitch hook failed before answering`** o **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: l'esecuzione dell'hook è terminata senza un verdetto, e Claude Code non lo tratta come approvazione. Eseguite `claude --debug` per vedere cosa ha fallito, quindi cambiate di nuovo.

2025

2026Prima della v2.1.260, il rifiuto del plugin gestito recitava `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`. Claude Code ha ritentato il caricamento del plugin una volta e poi ha rifiutato i cambi successivi nella sessione, anche quando la Vostra organizzazione non gestiva alcun plugin. Riavviate la sessione per eseguire il caricamento del plugin di nuovo su quelle versioni.

2027

2028<h3 id="couldnt-save-it-as-your-default">

2029 Non è stato possibile salvarlo come predefinito

2030</h3>

2031

2032Avete scelto un modello da salvare come predefinito, ad esempio con `/model <name>` o `Enter` nel selettore `/model`, e Claude Code non ha potuto scrivere la scelta nel Vostro file di impostazioni utente, `~/.claude/settings.json`. Il cambio stesso si è applicato, quindi la sessione corrente viene eseguita sul modello che avete scelto, ma il Vostro predefinito rimane invariato e la sessione successiva inizia sul valore precedente.

2033

2034```text theme={null}

2035Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)

2036```

2037

2038La ragione dopo il percorso del file dice cosa ha fallito:

2039

2040* **`can't be written (<code>)`**: la scrittura ha fallito con il codice di errore del sistema operativo tra parentesi, come `EROFS` quando il file, o il file a cui si collega, si trova su un filesystem che rifiuta le scritture. Rendete il file scrivibile e cambiate di nuovo. Se un altro strumento genera il file, impostate la chiave `model` in quello strumento; vedete [A change you made in Claude Code is lost in new sessions](/docs/it/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions).

2041* **`isn't valid JSON`**: il file su disco non analizza, e Claude Code lo lascia intatto piuttosto che sovrascrivere il contenuto che non può leggere di nuovo. Correggete l'errore di sintassi, quindi cambiate di nuovo; vedete [Fix a broken settings file](/docs/it/settings#fix-a-broken-settings-file).

2042

2043Un avviso che termina `couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)` significa che la scrittura non era terminata dopo tre secondi. Continua in background, quindi il predefinito potrebbe comunque essere salvato; controllate quale modello la Vostra sessione successiva inizia, oppure eseguite `/model <name>` di nuovo.

2044

2045Prima della v2.1.265, l'avviso diceva che il modello era `saved as your default for new sessions` anche quando la scrittura falliva.

2046

2047<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

2048 thinking.type.enabled non è supportato per questo modello

2049</h3>

2050

2051La Vostra versione di Claude Code è più vecchia del minimo per il modello selezionato. La CLI ha inviato una configurazione di thinking che il modello non accetta più.

2052

2053```text theme={null}

2054API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

2055```

2056

2057**Cosa fare:**

2058

2059* Eseguite `claude update` e riavviate Claude Code. Opus 4.7 ha bisogno della v2.1.111 o successiva. Opus 4.8 ha bisogno della v2.1.154 o successiva. Sonnet 5 ha bisogno della v2.1.197 o successiva. Opus 5 ha bisogno della v2.1.219 o successiva

2060* Se non potete aggiornare, eseguite `/model` e selezionate Opus 4.6 o Sonnet 4.6 invece

2061* Se lo incontrate nell'[Agent SDK](/docs/it/agent-sdk/overview), aggiornate il pacchetto SDK. Opus 4.8 ha bisogno di TypeScript SDK v0.3.154 o successiva e Python SDK v0.2.88 o successiva. Sonnet 5 ha bisogno di TypeScript SDK v0.3.197 o successiva. Opus 5 ha bisogno di TypeScript SDK v0.3.219 o successiva

2062

2063<h3 id="effort-isnt-available-with-thinking-turned-off">

2064 Effort non è disponibile con thinking disattivato

2065</h3>

2066

2067Avete disattivato il [thinking esteso](/docs/it/model-config#extended-thinking) e avete eseguito a un [livello di effort](/docs/it/model-config#adjust-effort-level) superiore a `high`. Il modello non accetta quella combinazione, quindi l'API ha rifiutato la richiesta.

2068

2069```text theme={null}

2070API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

2071```

2072

2073**Cosa fare:**

2074

2075* [Abbassate il livello di effort](/docs/it/model-config#set-the-effort-level) a `high` o inferiore.

2076* Riattivate il thinking, ad esempio annullando [`MAX_THINKING_TOKENS`](/docs/it/env-vars) o rimuovendo [`"alwaysThinkingEnabled": false`](/docs/it/settings-reference#alwaysthinkingenabled) dalle Vostre impostazioni.

2077

2078Prima della v2.1.242, Claude Code mostrava il messaggio proprio dell'API: `API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` Prima della v2.1.251, Claude Code inviava la richiesta al livello di effort che avete impostato, quindi Opus 5 rifiutava ogni richiesta superiore a `high` con thinking disattivato. Claude Code ora invia effort `high` invece ai modelli che sa rifiutano la combinazione, come Opus 5, quindi sulla v2.1.251 o successiva questo errore vi raggiunge solo da un modello che Claude Code non sa rifiuta.

2079

2080<h3 id="thinking-budget-exceeds-output-limit">

2081 Il budget di thinking supera il limite di output

2082</h3>

2083

2084Il budget di thinking esteso configurato supera la lunghezza massima della risposta, quindi non c'è spazio rimasto per la risposta effettiva.

2085

2086```text theme={null}

2087API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

2088```

2089

2090Claude Code regola automaticamente questi valori sull'API Anthropic. Solitamente vedete questo errore su Amazon Bedrock o Google Cloud's Agent Platform quando [`MAX_THINKING_TOKENS`](/docs/it/env-vars) è impostato più alto del limite di output del provider, oppure quando la modalità piano aumenta il budget di thinking.

2091

2092**Cosa fare:**

2093

2094* Abbassate `MAX_THINKING_TOKENS`, oppure aumentate [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/it/env-vars) sopra il budget di thinking

2095* Vedete [Extended thinking](/docs/it/model-config#extended-thinking) per come il budget interagisce con la lunghezza di output

2096

2097<h3 id="tool-use-or-thinking-block-mismatch">

2098 Mancata corrispondenza di blocco di tool use o thinking

2099</h3>

2100

2101La cronologia della conversazione ha raggiunto l'API in uno stato incoerente, solitamente dopo che una chiamata di strumento è stata interrotta o un turno è stato modificato a metà flusso.

2102

2103```text theme={null}

2104API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

2105API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks

2106API Error: 400 ... thinking blocks ... cannot be modified

2107```

2108

2109Tutte e tre le varianti significano la stessa cosa: la sequenza di blocchi `tool_use`, `tool_result` e `thinking` nella cronologia non corrisponde più a ciò che l'API si aspetta.

2110

2111**Cosa fare:**

2112

2113* Se state usando Opus 4.7 o Opus 4.8, eseguite `claude update` prima. Le versioni precedenti alla v2.1.156 possono attivare questo errore durante il normale uso di strumenti, e `/rewind` non lo cancella.

2114* Eseguite `/rewind`, oppure premete Esc due volte, per tornare indietro a un checkpoint prima del turno corrotto e continuare da lì. Vedete [Checkpointing](/docs/it/checkpointing) per come i checkpoint vengono creati e ripristinati.

2115

2116<h3 id="unsupported-tool-content-removed">

2117 Contenuto di strumento non supportato rimosso

2118</h3>

2119

2120Quando Claude Code si connette direttamente all'API Anthropic e carica o visualizza un'anteprima di una sessione salvata, rimuove il contenuto dello strumento che l'API Anthropic non accetta e lascia questa riga dove il contenuto rimosso si trovava tra due blocchi di thinking:

2121

2122```text theme={null}

2123[Unsupported tool content removed]

2124```

2125

2126Tale contenuto raggiunge un file di sessione quando qualcosa di diverso dall'API Anthropic risponde nel formato dell'API, tipicamente un proxy di terze parti impostato attraverso [`ANTHROPIC_BASE_URL`](/docs/it/env-vars) che traduce le chiamate di strumento di un altro provider. Claude Code lo rimuove solo quando la sessione si connette direttamente all'API Anthropic, e carica la cronologia salvata come è quando la sessione viene eseguita attraverso un proxy o su un altro provider. Prima della v2.1.246, Claude Code inviava il tool use e il suo risultato di nuovo all'API, e ogni turno della sessione ripresa falliva con un errore 400 come `messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...`.

2127

2128**Cosa fare:**

2129

2130* Nessuna azione necessaria quando vedete la riga segnaposto. La sessione continua senza il contenuto rimosso.

2131* Se ogni turno di una sessione ripresa fallisce con l'errore 400 invece, eseguite `claude update` e riprendete la sessione di nuovo. Le versioni precedenti alla v2.1.246 non rimuovono il contenuto.

2132

2133<h3 id="usage-policy-refusal">

2134 Rifiuto della politica di utilizzo

2135</h3>

2136

2137L'API ha rifiutato di rispondere perché il contenuto nella conversazione ha attivato un controllo della [Politica di utilizzo](https://www.anthropic.com/legal/aup). Il messaggio include un ID richiesta che potete citare al supporto se ritenete che il rifiuto sia scorretto.

2138

2139```text theme={null}

2140API Error: Opus 4.6 can't help with this. Start a new session to continue.

2141

2142Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

2143```

2144

2145Il messaggio nomina il modello che ha rifiutato, o `Claude` quando nessun modello è registrato.

2146

2147Il controllo valuta l'intera conversazione, non solo il Vostro prompt più recente, quindi inviare un nuovo messaggio nella stessa sessione solitamente riattiva lo stesso rifiuto. Lo stesso si applica dopo aver uscito e riaperto la sessione con `--continue` o `--resume`, poiché la trascrizione su disco contiene ancora il contenuto che attiva. Su [Amazon Bedrock](/docs/it/amazon-bedrock), [Google Cloud's Agent Platform](/docs/it/google-vertex-ai) e [Microsoft Foundry](/docs/it/microsoft-foundry), questo messaggio copre anche le richieste che le misure di sicurezza del modello hanno contrassegnato come un argomento di cibersicurezza. Vedete [Safety measures flagged a cybersecurity topic](#safety-measures-flagged-a-cybersecurity-topic).

2148

2149Prima della v2.1.219, il messaggio recitava `Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.`

2150

2151**Cosa fare:**

2152

2153* Premete Esc due volte o eseguite `/rewind` per tornare indietro a un checkpoint prima del turno che ha attivato il rifiuto, quindi riformulate o prendete un approccio diverso. Vedete [Checkpointing](/docs/it/checkpointing).

2154* Se non riuscite a identificare quale turno l'ha causato, eseguite `/clear` per avviare una conversazione nuova nello stesso progetto. La Vostra conversazione precedente è preservata su disco e rimane disponibile in `/resume`.

2155* In [modalità non interattiva](/docs/it/headless) (`-p`), dove il rewind non è disponibile, ritentate con un prompt riformulato in una nuova sessione senza `--continue`. I controlli della politica variano per modello, quindi passare a un modello diverso con `--model` può anche risolvere il rifiuto in alcuni casi.

2156

2157<h3 id="safety-measures-flagged-a-cybersecurity-topic">

2158 Le misure di sicurezza hanno contrassegnato un argomento di cibersicurezza

2159</h3>

2160

2161Le misure di sicurezza del modello hanno contrassegnato il contenuto nella conversazione come un argomento di cibersicurezza. Il messaggio nomina il modello che ha contrassegnato la richiesta:

2162

2163```text theme={null}

2164API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

2165```

2166

2167Il messaggio si collega al [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude), che concede accesso per il lavoro di cibersicurezza legittimo.

2168

2169Su [Amazon Bedrock](/docs/it/amazon-bedrock), [Google Cloud's Agent Platform](/docs/it/google-vertex-ai) e [Microsoft Foundry](/docs/it/microsoft-foundry), un contrassegno di cibersicurezza produce il messaggio di [rifiuto della politica di utilizzo](#usage-policy-refusal) invece.

2170

2171La salvaguardia stessa è lato server e precede la v2.1.203; i rilasci client da allora hanno cambiato solo la formulazione del messaggio.

2172Dalla v2.1.203 alla v2.1.218, il messaggio recitava `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:` seguito dallo stesso link del centro assistenza, e le sessioni interattive aggiungevano `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`

2173Prima della v2.1.203, recitava `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` seguito da un link di modulo di esenzione.

2174

2175**Cosa fare:**

2176

2177* Se il Vostro lavoro richiede questo contenuto, applicate per l'accesso attraverso il [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)

2178* Se la Vostra richiesta non riguardava un argomento di cibersicurezza, eseguite `/feedback` per segnalare il falso positivo

2179* Per continuare a lavorare nella stessa sessione, premete Esc due volte o eseguite `/rewind` per tornare indietro a un checkpoint prima del turno che ha attivato il contrassegno, quindi prendete un approccio diverso. Vedete [Checkpointing](/docs/it/checkpointing).

2180

2181<h2 id="installation-errors">

2182 Errori di installazione

2183</h2>

2184

2185Questi errori compaiono durante l'installazione o l'aggiornamento di Claude Code, dallo [script di installazione](/docs/it/setup#install-claude-code), `claude install`, o `claude update`. Per i problemi di `command not found`, PATH, permessi e TLS durante la configurazione, vedere [Risoluzione dei problemi di installazione e accesso](/docs/it/troubleshoot-install).

2186

2187<h3 id="installation-was-killed-before-it-could-finish">

2188 L'installazione è stata interrotta prima di poter terminare

2189</h3>

2190

2191Lo script di installazione segnala quando il passaggio `claude install` viene terminato da un segnale. Su Linux, il codice di uscita 137 significa che il processo ha ricevuto SIGKILL, e su un host con poca memoria è solitamente il killer out-of-memory (OOM) del kernel. Lo script stampa questa spiegazione ed esce con il codice 137:

2192

2193```text theme={null}

2194Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

2195Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

2196```

2197

2198Per qualsiasi altro segnale fatale, e per il codice di uscita 137 su macOS, lo script stampa `Installation was killed before it could finish (exit code <N>)` con il codice di uscita effettivo e omette la spiegazione della memoria insufficiente. Il messaggio proviene dallo script di installazione che macOS e Linux utilizzano, che copre anche le installazioni all'interno di WSL; gli script di installazione nativi di Windows non lo stampano mai. Prima della v2.1.200, lo script usciva con solo la riga `Killed` nuda della shell.

2199

2200**Cosa fare:**

2201

2202* Interrompere altri processi per liberare memoria, quindi eseguire nuovamente il programma di installazione

2203* Aggiungere spazio di swap o passare a un'istanza più grande. Vedere [Installazione interrotta su server Linux con poca memoria](/docs/it/troubleshoot-install#install-killed-on-low-memory-linux-servers) per i comandi del file di swap.

2204

2205<h3 id="the-connection-dropped-while-downloading-the-update">

2206 La connessione è stata interrotta durante il download dell'aggiornamento

2207</h3>

2208

2209La connessione al server di download si è chiusa mentre `claude install`, `claude update`, o l'[aggiornamento automatico](/docs/it/setup#auto-updates) stava recuperando il binario di Claude Code, e i tentativi di ripetizione non hanno recuperato. Claude Code ritenta il download quando la connessione si interrompe, il trasferimento si blocca, o il file scaricato non supera il checksum, fino a tre tentativi in totale. Un errore HTTP completato, come un 404, non viene ritentato perché il server ha già risposto. Prima della v2.1.202, una singola connessione interrotta faceva fallire il download immediatamente con il semplice errore `aborted` invece di ritentare.

2210

2211```text theme={null}

2212The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

2213```

2214

2215Il testo tra parentesi nomina quale tentativo ha fallito e l'errore di rete sottostante. `claude update` precede il messaggio con `Error: Failed to install native update` su stderr.

2216

2217Un download che rimane connesso ma non termina entro 10 minuti fallisce con `Download timed out: exceeded the total deadline` invece. Claude Code non ritenta un download scaduto, perché una connessione troppo lenta per terminare entro il limite non terminerà nemmeno con un tentativo immediato. I passaggi seguenti si applicano a entrambi i messaggi.

2218

2219La causa più comune è un proxy o un gateway che chiude un trasferimento lungo prima che termini. Il binario di Claude Code è un download di grandi dimensioni, quindi un limite di connessione proxy che non influisce mai sul traffico API normale può comunque interromperlo.

2220

2221**Cosa fare:**

2222

2223* Eseguire `claude update` di nuovo. Su una rete altrimenti sana, il download di solito ha successo alla prossima esecuzione. Per il messaggio di timeout, eseguirlo di nuovo da una rete più veloce o meno limitata.

2224* Se la rete richiede un proxy, impostare `HTTPS_PROXY` prima di eseguire il programma di installazione o `claude update`. Vedere [Verificare la connettività di rete](/docs/it/troubleshoot-install#check-network-connectivity).

2225* Se un proxy aziendale continua a chiudere il trasferimento, chiedere al team di rete di consentire il download completo da `downloads.claude.ai`. Vedere [Requisiti di accesso alla rete](/docs/it/network-config#network-access-requirements).

2226* Eseguire `claude doctor` dalla shell per la diagnostica dell'installazione

2227

2228<h2 id="command-line-errors">

2229 Errori da riga di comando

2230</h2>

2231

2232Questi errori provengono dal comando `claude` da riga di comando e dai suoi sottocomandi, da un nome di comando che invii al prompt, e da comandi come `/security-review` che raccolgono il contesto eseguendo comandi shell prima che il loro prompt venga eseguito. Lo stesso vale per gli errori da `/tui`, che riavvia la CLI.

2233

2234<h3 id="conflict-between-bg-and-print">

2235 Conflitto tra --bg e --print

2236</h3>

2237

2238Questo messaggio richiede Claude Code v2.1.198 o successivo. Hai combinato `--bg` con `-p` o `--print` nella stessa invocazione di `claude`. `--bg` avvia una [sessione in background](/docs/it/agent-view#from-your-shell) a cui ti colleghi successivamente con `claude agents`, mentre `--print` esegue [in modo non interattivo](/docs/it/headless) e non avvia mai la sessione interattiva a cui `claude agents` si collega. Prima della v2.1.198 questa combinazione creava silenziosamente un lavoro in background che non poteva mai essere collegato.

2239

2240```text theme={null}

2241--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

2242```

2243

2244**Cosa fare:**

2245

2246* Rimuovi `-p` o `--print`. `--bg` accetta il prompt come argomento posizionale, quindi `claude --bg "<task>"` è il comando completo. Vedi [Dispatch new agents from your shell](/docs/it/agent-view#from-your-shell).

2247* Per eseguire il prompt in modo non interattivo e stampare il risultato invece di creare una sessione in background, rimuovi `--bg` ed esegui `claude -p "<task>"`

2248

2249<h3 id="invalid-agents-configuration">

2250 Configurazione --agents non valida

2251</h3>

2252

2253Il valore che hai passato a `--agents` non è valido, quindi `claude` esce con codice 1 invece di avviare la sessione. Quando passi `--safe-mode`, `--resume`, o `--continue`, o imposti [`CLAUDE_CODE_SAFE_MODE`](/docs/it/env-vars#variables), Claude Code non controlla il valore e avvia la sessione. Prima della v2.1.242, Claude Code avviava comunque la sessione e ometteva le definizioni che non poteva caricare.

2254

2255```text theme={null}

2256Error: Invalid --agents configuration:

2257<what failed>

2258```

2259

2260Quello che segue la prima riga dipende da come il valore ha fallito. Claude Code esegue questi controlli in ordine e si ferma al primo che fallisce. Se il tuo valore ha due tipi di problema, vedi il secondo solo dopo aver corretto il primo:

2261

22621. Quando il valore non viene analizzato come JSON, Claude Code stampa una riga `invalid JSON:` con il messaggio del parser JSON stesso

22632. Quando viene analizzato ma una definizione di agente non corrisponde allo schema per [subagenti definiti da CLI](/docs/it/sub-agents#choose-the-subagent-scope), Claude Code stampa una riga per problema

22643. Quando un nome di agente inizia con `-`, Claude Code stampa `<name>: agent names must not start with '-'`

2265

2266Quando ci sono più di 20 righe di problema, Claude Code stampa le prime 20 e sostituisce il resto con `…and N more`.

2267

2268**Cosa fare:**

2269

2270* Correggi ogni problema che il messaggio elenca, quindi esegui di nuovo il comando. Vedi [i campi che un subagente definito da CLI accetta](/docs/it/sub-agents#choose-the-subagent-scope).

2271

2272<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">

2273 Le sessioni cloud non possono essere create da una sessione --restricted

2274</h3>

2275

2276Quando avvii una sessione con [`--restricted`](/docs/it/cli-reference#cli-flags), Claude Code rifiuta di creare [sessioni cloud](/docs/it/claude-code-on-the-web#from-terminal-to-web) da essa, perché la nuova sessione verrebbe eseguita al di fuori del processo ristretto e non farebbe rispettare la modalità ristretta. Claude Code rifiuta sul client, prima di contattare il server, quindi nessuna sessione cloud viene creata:

2277

2278```text theme={null}

2279Cloud sessions cannot be created from a --restricted session: they would not enforce it.

2280```

2281

2282**Cosa fare:**

2283

2284* Esegui l'attività localmente nella sessione ristretta

2285* Se controlli come è stata avviata la sessione, avvia una nuova sessione `claude` senza `--restricted` e crea la sessione cloud da lì

2286

2287Prima della v2.1.248, Claude Code non aveva il flag `--restricted`; le versioni precedenti rifiutano il flag stesso con un errore di opzione sconosciuta.

2288

2289<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

2290 Il valore --json-schema non è un JSON Schema valido

2291</h3>

2292

2293Lo schema che hai passato a [`--json-schema`](/docs/it/cli-reference#cli-flags) in [modalità non interattiva](/docs/it/headless#get-structured-output) ha fallito la compilazione di JSON Schema, quindi `claude` esce con codice 1 invece di eseguire il prompt. Prima della v2.1.205, uno schema non valido produceva output non strutturato senza errore, e qualsiasi schema che utilizzava la parola chiave `format` era trattato come non valido.

2294

2295```text theme={null}

2296Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

2297```

2298

2299Il testo dopo il secondo due punti è la diagnostica del validatore e nomina la parola chiave o la posizione che ha fallito. Gli schemi che utilizzano la parola chiave `format`, come `"format": "email"`, sono validi: Claude Code accetta `format` come annotazione e non la applica.

2300

2301Claude Code esegue due controlli prima della compilazione dello schema: rifiuta un valore che non è JSON analizzabile con `Error: --json-schema is not valid JSON`, e JSON valido che non è un oggetto con `Error: --json-schema must be a JSON object`.

2302

2303**Cosa fare:**

2304

2305* Correggi la parte dello schema che la diagnostica nomina, quindi riesegui il comando

2306* Se la diagnostica è `schema too large`, riduci l'annidamento dello schema e il riutilizzo di `$ref`

2307* Vedi [Get structured output](/docs/it/headless#get-structured-output) per uno schema funzionante e un comando

2308

2309<h3 id="settings-file-exceeds-the-2mib-limit">

2310 Il file di impostazioni supera il limite di 2MiB

2311</h3>

2312

2313Il file che hai passato a [`--settings`](/docs/it/cli-reference#cli-flags) è più grande di 2 MiB, quindi `claude` esce con codice 1 all'avvio invece di caricarlo. Un file di impostazioni è un piccolo documento JSON, quindi un file di questa dimensione di solito significa che il percorso punta al file sbagliato. Prima della v2.1.214, Claude Code leggeva il file senza controllo delle dimensioni, e un file di più gigabyte o un file di dispositivo come `/dev/zero` faceva crescere la memoria senza limiti.

2314

2315```text theme={null}

2316Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

2317```

2318

2319Claude Code rifiuta un percorso `--settings` che non è un file regolare allo stesso modo: un dispositivo, FIFO o socket segnala `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))` seguito dal percorso, e una directory segnala un motivo `EISDIR`.

2320

2321**Cosa fare:**

2322

2323* Punta `--settings` a un file JSON di impostazioni regolare sotto 2 MiB. Vedi [Settings](/docs/it/settings) per il formato.

2324

2325<h3 id="the-current-directory-no-longer-exists">

2326 La directory corrente non esiste più

2327</h3>

2328

2329Hai avviato `claude` da una directory che è stata eliminata o spostata dopo che la tua shell vi è entrata, ad esempio una worktree o una directory temporanea che un'altra shell ha rimosso. Claude Code non può leggere la sua directory di lavoro, quindi esce con codice 1 prima di avviare la sessione, sia in modalità interattiva che [non interattiva](/docs/it/headless). Prima della v2.1.239, Claude Code si bloccava con il codice sorgente del bundle minimizzato e uno stack `ENOENT ... uv_cwd` grezzo su stderr invece di questo messaggio.

2330

2331```text theme={null}

2332The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.

2333error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

2334```

2335

2336La causa e la correzione sono le stesse per entrambe le forme.

2337

2338Quando Claude Code non può leggere la directory di lavoro per un motivo diverso, come un cambio di permessi, il messaggio nomina il codice di errore invece: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`

2339

2340Su macOS, `EPERM` per una directory in `~/Desktop`, `~/Documents`, `~/Downloads`, o iCloud Drive di solito significa che macOS sta bloccando l'accesso della tua app terminale a quella cartella. Altri comandi che leggono quella cartella falliscono allo stesso modo: `ls` lì segnala `Operation not permitted`, anche con `sudo`.

2341

2342**Cosa fare:**

2343

2344* Cambia a una directory che esiste, come la tua home o la directory del progetto, quindi esegui di nuovo `claude`

2345* Se la directory è stata ricreata nello stesso percorso, la tua shell ne tiene ancora quella eliminata. Esegui `cd "$PWD"` o esci e rientra nella directory, quindi esegui di nuovo `claude`

2346* Per `EPERM` su macOS, esci dalla tua app terminale con Cmd+Q, aprila di nuovo, torna a quella cartella, ed esegui `claude`. Se `ls` in quella cartella continua a fallire, apri **System Settings > Privacy & Security > Files and Folders**, attiva la cartella per la tua app terminale, quindi riapri il terminale

2347

2348<h3 id="directory-couldnt-be-resolved-to-a-real-location">

2349 La directory non potrebbe essere risolta a una posizione reale

2350</h3>

2351

2352Hai eseguito `/add-dir` per una sottodirectory della tua directory di lavoro, e Claude Code non potrebbe risolvere la directory a una posizione reale.

2353

2354Hai già accesso ai file a una sottodirectory della directory di lavoro, quindi `/add-dir` carica solo le sue skills, comandi e agenti. Prima di caricarli, Claude Code verifica che la posizione reale della directory, con eventuali symlink risolti, sia all'interno della directory di lavoro. Quando Claude Code non può risolvere quella posizione, non carica nulla e mostra questo messaggio:

2355

2356```text theme={null}

2357packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

2358```

2359

2360**Cosa fare:**

2361

2362* Verifica che il percorso nomini una directory reale all'interno della directory di lavoro, quindi esegui di nuovo `/add-dir`

2363* Il messaggio non cambia il tuo accesso ai file; riporta solo che il contenuto `.claude/` della directory non è stato caricato

2364

2365Prima della v2.1.261, questo messaggio appariva anche per ogni `/add-dir <subdirectory>` quando la directory di lavoro era su un automount `/net/<host>`, dove Claude Code rifiuta di risolvere i percorsi per progettazione; la directory era fine e riprovare non poteva aiutare.

2366

2367<h3 id="workspace-not-trusted-when-starting-remote-control">

2368 Workspace non attendibile all'avvio di Remote Control

2369</h3>

2370

2371Hai avviato la modalità server [Remote Control](/docs/it/remote-control) con `claude remote-control` o il suo alias `claude rc` in una directory che non hai attendibile. Il comando non mostra il dialogo di attendibilità dell'area di lavoro stesso, quindi esce con codice 1 e nomina la correzione:

2372

2373```text theme={null}

2374Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

2375```

2376

2377Nella tua home directory il messaggio è diverso, perché il dialogo di attendibilità dell'area di lavoro non salva mai l'attendibilità per la home directory, quindi accettarlo lì non può soddisfare questo controllo. Prima della v2.1.214, la home directory mostrava il messaggio sopra, il cui consiglio non può avere successo lì.

2378

2379```text theme={null}

2380Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

2381```

2382

2383**Cosa fare:**

2384

2385* Esegui `claude` nella directory, accetta il [dialogo di attendibilità dell'area di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust), quindi esegui di nuovo `claude remote-control`

2386* Nella tua home directory, cambia a una directory del progetto e avvia Remote Control lì

2387

2388<h3 id="not-carried-over-to-the-sessions-remote-control-starts">

2389 Non trasportato alle sessioni che Remote Control avvia

2390</h3>

2391

2392Hai avviato [Remote Control](/docs/it/remote-control) con un flag `claude` globale prima del verbo `remote-control`, uno che limiterebbe o configurerebbe le sessioni che Remote Control avvia, come `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, o `--mcp-config`. Un flag posizionato prima del verbo non raggiunge mai quelle sessioni. Claude Code rifiuta di avviare invece, nominando il flag:

2393

2394```text theme={null}

2395Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

2396```

2397

2398Claude Code non rifiuta i flag globali che sono innocui da eliminare, come `--verbose`, `--model`, o un `--session-id` o `--plugin-dir` iniettato dal wrapper: li ignora e Remote Control si avvia.

2399

2400Claude Code rifiuta anche di avviare per un flag globale che non riconosce ancora come innocuo, quindi un flag aggiunto in una versione più recente può apparire in questo messaggio fino a quando una versione successiva non lo contrassegna come innocuo.

2401

2402**Cosa fare:**

2403

2404* Rimuovi il flag da prima del verbo e passa [le opzioni proprie di Remote Control](/docs/it/remote-control#start-a-remote-control-session) dopo di esso; `claude remote-control --help` le elenca

2405* Quando il flag rifiutato è `--permission-mode`, esegui `claude remote-control --permission-mode <mode>` per impostare la modalità di permesso per le sessioni che Remote Control avvia

2406

2407Prima della v2.1.248, `claude remote-control` non accettava i suoi flag quando un flag globale veniva per primo, e il comando falliva con un errore `unknown option`.

2408

2409<h3 id="claude-import-is-not-yet-available-in-this-build">

2410 claude import non è ancora disponibile in questa build

2411</h3>

2412

2413Hai eseguito [`claude import`](/docs/it/cli-reference#cli-commands), e Claude Code ha trovato il flusso di importazione disattivato, quindi il comando esce con codice 1 invece di avviare l'importazione. Prima della v2.1.222, una build con il flusso di importazione disattivato trattava `import` come un prompt e avviava una sessione interattiva invece di stampare questo messaggio.

2414

2415```text theme={null}

2416`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

2417```

2418

2419Claude Code attiva `claude import` attraverso un feature flag che recupera da Anthropic e memorizza nella cache su disco. Questo messaggio significa che il valore memorizzato nella cache è disattivato. La causa è di solito una delle seguenti:

2420

2421* Non hai avviato una sessione dall'installazione, quindi Claude Code non ha ancora recuperato il flag. Il primo `claude import` può stampare questo anche quando la funzione è disponibile per te.

2422* Usi Claude Code attraverso Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o Claude Platform su AWS, o attraverso un [gateway di app Claude](/docs/it/claude-apps-gateway#availability-and-limitations). Claude Code non recupera i feature flag in queste sessioni, quindi `claude import` rimane non disponibile.

2423* Hai impostato `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK`, o [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/it/env-vars), che disattivano il recupero dei feature flag, quindi `claude import` rimane non disponibile.

2424

2425**Cosa fare:**

2426

2427* Su un'installazione nuova, avvia `claude`, attendi che la sessione si carichi, esci, ed esegui di nuovo `claude import`

2428* Dove il recupero dei feature flag rimane disattivato, configura tu stesso: aggiungi server MCP con [`claude mcp add`](/docs/it/mcp#installing-mcp-servers), e crea i file [`CLAUDE.md`](/docs/it/memory#how-claude-md-files-load), [skills e comandi](/docs/it/skills#where-skills-live), e [subagenti](/docs/it/sub-agents#choose-the-subagent-scope) che vuoi trasportare. Il messaggio nomina anche `~/.claude/settings.json`. Della configurazione che `claude import` trasporta, quel file contiene solo la [modalità di permesso](/docs/it/settings-reference#permission-settings); Claude Code non legge i server MCP da esso.

2429

2430<h3 id="could-not-read-claude-code-config">

2431 Non potrebbe leggere la configurazione di Claude Code

2432</h3>

2433

2434Hai eseguito [`claude import`](/docs/it/cli-reference#cli-commands) mentre Claude Code non potrebbe analizzare `~/.claude.json`, il file dove memorizza il tuo login e lo stato per progetto. Il sottocomando legge quel file per controllare la disponibilità ma non mostra il dialogo di recupero che la sessione interattiva mostra, quindi esce con codice 1. Prima della v2.1.222, `claude import` con un file di configurazione illeggibile avviava una sessione interattiva, il cui dialogo di recupero gestiva il file.

2435

2436```text theme={null}

2437Could not read Claude Code config — run `claude` with no arguments to recover it.

2438```

2439

2440**Cosa fare:**

2441

2442* Esegui `claude` senza argomenti. Claude Code rileva il file non valido e offre di ripristinarlo. Quindi esegui di nuovo `claude import`.

2443* Per mantenere le modifiche manuali che hai fatto, correggi la sintassi JSON in `~/.claude.json` in un editor invece, quindi riesegui `claude import`

2444

2445<h3 id="could-not-import-a-server-from-claude-desktop">

2446 Non potrebbe importare un server da Claude Desktop

2447</h3>

2448

2449Claude Code non potrebbe aggiungere uno dei server che hai selezionato in `claude mcp add-from-claude-desktop`. Il comando importa comunque gli altri server selezionati e stampa una riga per server che non potrebbe aggiungere. Prima della v2.1.205, il primo server che falliva fermava l'importazione e nessuno dei server selezionati veniva aggiunto.

2450

2451```text theme={null}

2452Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

2453```

2454

2455Il testo dopo il nome del server è il motivo. Il più comune è il controllo del nome: Claude Desktop consente caratteri nei nomi dei server, come spazi e punti, che `claude mcp` limita a lettere, numeri, trattini e sottolineature. Altri motivi includono una configurazione del server che fallisce la validazione e un server bloccato dalla [politica MCP](/docs/it/managed-mcp) della tua organizzazione.

2456

2457**Cosa fare:**

2458

2459* Rinomina il server in `claude_desktop_config.json` per usare solo lettere, numeri, trattini e sottolineature, quindi esegui di nuovo `claude mcp add-from-claude-desktop`

2460* Aggiungi quel server direttamente con `claude mcp add` o `claude mcp add-json` con un nome valido. Vedi [Import MCP servers from Claude Desktop](/docs/it/mcp#import-mcp-servers-from-claude-desktop).

2461

2462<h3 id="cannot-add-mcp-server-to-the-managed-scope">

2463 Non potrebbe aggiungere il server MCP allo scope gestito

2464</h3>

2465

2466Hai eseguito `claude mcp add` o `claude mcp add-json` con `--scope managed`. Quello scope contiene i server che la tua organizzazione fornisce attraverso l'impostazione gestita [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers). Claude Code li legge solo dalle impostazioni gestite, quindi il comando non può scrivere un server in quello scope.

2467

2468```text theme={null}

2469Cannot add MCP server to scope: managed

2470```

2471

2472**Cosa fare:**

2473

2474* Aggiungi il server a uno scope in cui puoi scrivere: `local`, `user`, o `project`. Senza `--scope`, il comando usa `local`. Vedi [MCP installation scopes](/docs/it/mcp#mcp-installation-scopes)

2475* Per fornire il server a ogni utente nella tua organizzazione, aggiungilo a [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) nelle impostazioni gestite che distribuisci

2476

2477<h3 id="cant-read-mcp-json">

2478 Non potrebbe leggere .mcp.json

2479</h3>

2480

2481Un comando che legge il [`.mcp.json`](/docs/it/mcp#project-scope) del progetto, come `claude mcp add` o `claude mcp add-json` con `--scope project`, o `claude mcp remove`, ha trovato che il file nella tua directory corrente non è un file regolare o è più grande di 2 MiB, quindi esce con questo errore invece di leggere il file.

2482

2483```text theme={null}

2484Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

2485```

2486

2487Prima della v2.1.257, un FIFO a `.mcp.json` lasciava il comando in attesa per sempre senza output, e un symlink a un file di dispositivo come `/dev/zero` faceva crescere la memoria fino a quando il processo veniva ucciso.

2488

2489**Cosa fare:**

2490

2491* Controlla cosa si trova a `.mcp.json` nella tua directory corrente. Sostituiscilo con un file JSON ordinario nel [formato project-scope](/docs/it/mcp#project-scope), o eliminalo, quindi esegui di nuovo il comando.

2492

2493<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">

2494 Il server è ospitato da Anthropic e non supporta OAuth locale

2495</h3>

2496

2497Hai avviato un accesso per un server MCP il cui URL punta a un host connettore ospitato da Anthropic che si autentica attraverso un provider di identità di terze parti. Questi host includono `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, e `gcal.mcp.claude.com`. Claude Code rifiuta di avviare il suo flusso OAuth locale per questi host sia dal pannello `/mcp` che da `claude mcp login`, perché [il loro accesso funziona solo attraverso claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai).

2498

2499```text theme={null}

2500"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

2501```

2502

2503Claude Code corrisponde a questi host per URL, quindi il messaggio appare quando un server che hai aggiunto con `claude mcp add` o in `.mcp.json` punta a uno di loro.

2504

2505**Cosa fare:**

2506

2507* Rimuovi la tua voce con `claude mcp remove <name>`, così non può nascondere il connettore claude.ai allo stesso URL

2508* Dopo averlo rimosso, connetti il servizio su [claude.ai/customize/connectors](https://claude.ai/customize/connectors), mentre sei connesso all'account che usi in Claude Code. Una volta connesso, [il connettore appare in Claude Code automaticamente](/docs/it/mcp#use-mcp-servers-from-claude-ai) se il tuo metodo di autenticazione attivo è un accesso di sottoscrizione claude.ai

2509

2510<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">

2511 Il server ha rifiutato l'intestazione Authorization coniata dal headersHelper configurato

2512</h3>

2513

2514Un server MCP il cui [`headersHelper`](/docs/it/mcp#use-dynamic-headers-for-custom-authentication) fornisce l'intestazione `Authorization` ha risposto alla connessione con HTTP 401 o 403, quindi Claude Code segnala la connessione come fallita. Poiché l'helper fornisce l'intestazione `Authorization`, Claude Code [non ricade su OAuth](/docs/it/mcp#authenticate-with-remote-mcp-servers) per il server:

2515

2516```text theme={null}

2517Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

2518```

2519

2520Claude Code riesegue l'helper ad ogni tentativo di connessione, quindi un nuovo tentativo dopo un rifiuto transitorio, come una gara di rotazione del token, può avere successo con una credenziale nuova.

2521

2522**Cosa fare:**

2523

2524* Esegui il comando `headersHelper` tu stesso nel modo in cui Claude Code lo esegue: dalla [directory in cui Claude Code lo esegue](/docs/it/mcp#where-the-helper-runs), con le [variabili di ambiente che Claude Code imposta per esso](/docs/it/mcp#use-dynamic-headers-for-custom-authentication), e senza le [variabili di credenziale che Claude Code rimuove](/docs/it/mcp#which-variables-a-helper-can-read) per un server da un `.mcp.json` del progetto, un plugin, o un file agente del progetto. Controlla che stampi un valore `Authorization` che l'endpoint del server accetta

2525* Dopo aver corretto l'helper o la sua fonte di credenziale, seleziona il server in `/mcp` e scegli **Reconnect**

2526

2527Prima della v2.1.248, Claude Code eseguiva la scoperta OAuth per un server il cui helper forniva l'intestazione `Authorization`. Quella scoperta potrebbe fallire con `Incompatible auth server: does not support dynamic client registration` invece di segnalare la credenziale rifiutata.

2528

2529<h3 id="mcp-permission-prompt-tool-not-found">

2530 Strumento di prompt di permesso MCP non trovato

2531</h3>

2532

2533Lo strumento che hai passato a [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags) non era tra gli strumenti MCP connessi quando l'esecuzione ha avuto bisogno per la prima volta di una decisione di permesso, perché il suo server non si è mai connesso o perché nessun server connesso espone uno strumento con quel nome. Claude Code invia comunque il tuo prompt: l'esecuzione [non interattiva](/docs/it/headless) esce con questo errore, e codice di uscita 1, alla prima chiamata di strumento che necessita di approvazione, quindi non produce alcuna risposta anche se la richiesta è stata fatta. Prima del primo prompt, Claude Code attende fino al timeout di connessione per server di 30 secondi impostato da [`MCP_TIMEOUT`](/docs/it/env-vars) affinché quel server si connetta. Prima della v2.1.206, l'avvio non attendeva che il server finisse di connettersi, quindi un server che si avvia lentamente ma sano produceva questo errore anche.

2534

2535```text theme={null}

2536Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

2537```

2538

2539L'elenco dopo `Available MCP tools:` nomina gli strumenti MCP che erano connessi quando l'attesa è terminata.

2540

2541**Cosa fare:**

2542

2543* Controlla che il server si avvii e rimanga connesso: esegui `claude mcp list` nella stessa directory e conferma che il server è elencato come connesso

2544* Conferma che il nome dello strumento corrisponda al nome `mcp__<server>__<tool>` che il server espone

2545* Se il server ha bisogno di più di 30 secondi per avviarsi, aumenta [`MCP_TIMEOUT`](/docs/it/env-vars)

2546

2547<h3 id="oauth-callback-port-is-already-in-use">

2548 La porta di callback OAuth è già in uso

2549</h3>

2550

2551Quando accedi a un server MCP remoto con OAuth, Claude Code avvia un listener locale per ricevere il callback di accesso. Se la porta di cui quel listener ha bisogno è tenuta da un altro processo, l'accesso fallisce con questo messaggio. Questo accade principalmente con una [porta di callback fissa](/docs/it/mcp#use-a-fixed-oauth-callback-port) impostata attraverso la variabile [`MCP_OAUTH_CALLBACK_PORT`](/docs/it/env-vars) o `--callback-port`, poiché senza una Claude Code sceglie una porta disponibile.

2552

2553```text theme={null}

2554OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

2555```

2556

2557Su Windows, il comando suggerito è `netstat -ano | findstr :<port>` invece.

2558

2559**Cosa fare:**

2560

2561* Esegui il comando dal messaggio per trovare il processo che tiene la porta, e fermalo o attendi che finisca

2562* Se un altro programma ha bisogno permanentemente di quella porta, registra un URI di reindirizzamento diverso con il server e imposta la sua porta con `MCP_OAUTH_CALLBACK_PORT` o `--callback-port`, a seconda di quale usi

2563* Quindi avvia di nuovo l'accesso, ad esempio selezionando il server in `/mcp`

2564

2565<h3 id="security-review-fails-without-origin-head">

2566 /security-review fallisce senza origin/HEAD

2567</h3>

2568

2569[`/security-review`](/docs/it/commands#all-commands) costruisce il suo contesto di revisione facendo il diff del tuo branch rispetto a `origin/HEAD`, il ref locale che registra quale branch è il predefinito sul tuo remote `origin`. Quando quel ref non esiste, i comandi git che raccolgono il diff falliscono e la revisione si ferma prima di iniziare.

2570

2571```text theme={null}

2572Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]

2573fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.

2574Use '--' to separate paths from revisions, like this:

2575'git <command> [<revision>...] -- [<file>...]'

2576```

2577

2578Il comando citato varia tra le esecuzioni: la revisione avvia diversi comandi `git` rispetto a `origin/HEAD` contemporaneamente e segnala quale fallisce per primo, quindi potresti vedere `git log` o un diverso `git diff` al suo posto. Git crea il ref solo quando il branch predefinito del remote è sia pubblicizzato dal remote che coperto dal tuo refspec di fetch. Un `git clone` completo di un remote con commit soddisfa entrambe le condizioni. I checkout single-branch e CI recuperano un refspec troppo stretto, un HEAD lato server lasciato puntare a un branch che nessuno ha spinto non pubblicizza nulla, e un repository senza un remote `origin`, o uno da cui non hai mai recuperato, non fornisce nessuno dei due.

2579

2580Claude Code mostra lo stesso errore per qualsiasi skill che [inietta contesto dinamico](/docs/it/skills#when-an-injected-command-fails). Un comando iniettato fallito interrompe l'invocazione di quella skill. Due stringhe sibling si attivano prima che il comando venga eseguito affatto:

2581

2582* `Shell command permission check failed for pattern "..."`: il controllo di permesso del comando ha restituito qualcosa di diverso da allow. I comandi iniettati non chiedono mai, quindi l'invocazione si interrompe senza chiederti. Pre-approva i comandi che nessuna regola corrisponde con [`allowed-tools`](/docs/it/skills#pre-approve-tools-for-a-skill). Una regola ask o deny corrispondente interrompe comunque l'invocazione indipendentemente da `allowed-tools`

2583* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: il frontmatter della skill richiede bash su una macchina senza di esso. Installa Git per Windows o cambia il frontmatter a `shell: powershell`. Vedi [How injected commands run](/docs/it/skills#how-injected-commands-run)

2584

2585**Cosa fare:**

2586

2587* Crea il ref nominando il branch predefinito del tuo remote: `git remote set-head origin <default-branch>`. Questo funziona ogni volta che il ref di tracciamento locale `origin/<default-branch>` esiste. Se non esiste, come nei cloni single-branch, recupera prima il branch: esegui `git remote set-branches --add origin <branch>`, quindi `git fetch origin`, quindi riesegui il comando set-head. Riesegui `/security-review`.

2588* Se preferisci non nominare il branch, esegui `git fetch origin` e quindi `git remote set-head origin --auto`, che chiede al remote quale branch è il suo predefinito. Fallisce con `error: Cannot determine remote HEAD` quando il remote non pubblicizza un branch predefinito, perché è vuoto o il suo HEAD punta a un branch che nessuno ha spinto; nomina il branch esplicitamente invece. Fallisce con `error: Not a valid ref` quando il tuo clone non recupera quel branch; allarga il refspec come sopra prima.

2589* Se il repository non ha un remote, aggiungine uno con `git remote add origin <url>` e recupera prima di creare il ref. Se il remote è vuoto, spinge il tuo branch prima con `git push -u origin HEAD` e nomina quel branch nel comando set-head; `origin/HEAD` quindi punta al branch che hai appena spinto, quindi `/security-review` vede un diff vuoto fino a quando il branch non diverge da esso.

2590

2591<h3 id="input-must-be-provided-when-using-print">

2592 L'input deve essere fornito quando si usa --print

2593</h3>

2594

2595Bare `claude` ha bisogno che stdout sia un terminale per avviare l'interfaccia utente interattiva. Quando stdout viene reindirizzato, o la console non è un vero terminale, come PowerShell ISE e alcuni riquadri di output IDE, `claude` esegue [in modo non interattivo](/docs/it/headless) invece. Questo è lo stesso modo di `claude -p`, che richiede un prompt, quindi il messaggio nomina `--print` anche se non hai passato il flag. Passare `-p`/`--print` senza prompt e nulla piped su stdin produce lo stesso errore ovunque.

2596

2597```text theme={null}

2598Error: Input must be provided either through stdin or as a prompt argument when using --print

2599```

2600

2601**Cosa fare:**

2602

2603* Per l'uso interattivo, esegui `claude` in un vero terminale: Windows Terminal o la console PowerShell piuttosto che ISE, e il terminale integrato del tuo IDE piuttosto che un riquadro di output

2604* Per l'uso una tantum, passa il prompt: `claude -p "your question"`, o piped con `echo "your question" | claude -p`

2605

2606<h3 id="input-contained-only-whitespace">

2607 L'input conteneva solo spazi bianchi

2608</h3>

2609

2610In [modalità non interattiva](/docs/it/headless), Claude Code rifiuta un prompt composto interamente da spazi, tabulazioni o newline invece di inviarlo, perché l'API rifiuta i messaggi senza testo visibile. Quale messaggio vedi dipende da dove è venuto il prompt vuoto:

2611

2612* **Argomento prompt o stdin piped per `claude -p`**: `claude` esce con `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`

2613* **Messaggio inviato a una sessione `--input-format stream-json` o [Agent SDK](/docs/it/agent-sdk/overview) in esecuzione**: Claude Code termina il turno senza chiamare il modello e la sessione rimane utilizzabile. Il rifiuto arriva come messaggio informativo e come testo del risultato del turno: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`

2614

2615Prima della v2.1.229, Claude Code inviava il messaggio solo spazi bianchi all'API, che rifiutava la richiesta con un errore 400.

2616

2617**Cosa fare:**

2618

2619* Includi testo visibile nel prompt. Se uno script costruisce il prompt da una variabile o file, controlla che la fonte non sia vuota prima di chiamare Claude Code.

2620

2621<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">

2622 stream-json input ha trasportato oltre 256M caratteri senza newline

2623</h3>

2624

2625Il tuo programma ha inviato più di 268.435.456 caratteri su stdin senza newline a un'esecuzione `claude -p --input-format stream-json`, quindi Claude Code stampa questo errore su stderr e esce con codice 1 invece di bufferizzare più input. Il messaggio dichiara quel budget come `256M`. Prima della v2.1.257, Claude Code bufferizzava tale input senza limiti, facendo crescere la memoria fino a quando il processo si bloccava o veniva ucciso.

2626

2627```text theme={null}

2628Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

2629```

2630

2631L'input così lungo senza newline di solito significa che il produttore non è affatto un produttore stream-json, come un file binario o output di log semplice piped per errore. Un singolo messaggio oltre il budget fallisce lo stesso controllo.

2632

2633**Cosa fare:**

2634

2635* Controlla cosa è piped su stdin. Con [`--input-format stream-json`](/docs/it/cli-reference#cli-flags), ogni messaggio deve essere una singola riga JSON terminata da newline

2636* Per inviare testo semplice invece, rimuovi `--input-format stream-json`; `claude -p` legge un prompt di testo semplice da stdin per impostazione predefinita

2637

2638<h3 id="unknown-command">

2639 Comando sconosciuto

2640</h3>

2641

2642Hai inviato un nome `/` che non corrisponde a nessun comando in questa sessione, quindi Claude Code segnala il nome invece di eseguire qualcosa:

2643

2644```text theme={null}

2645Unknown command: /hepl. Did you mean /help?

2646```

2647

2648Claude Code suggerisce il nome di comando o alias più vicino che il menu elenca in questa sessione. Quando nulla è vicino, il messaggio termina dopo il nome. La causa è di solito una delle seguenti:

2649

2650* Un errore di battitura, come `/hepl` per `/help`. [How the command menu matches what you type](/docs/it/commands#how-the-command-menu-matches-what-you-type) copre la scelta di una corrispondenza vicina prima di inviare

2651* Un comando che esiste ma non è disponibile in questa sessione perché un requisito non è soddisfatto, come la tua piattaforma, piano, o metodo di autenticazione. Le voci di risoluzione dei problemi per [`/web-setup`](/docs/it/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) e [`/schedule`](/docs/it/routines#schedule-returns-unknown-command) affrontano due casi comuni. Alcuni comandi rispondono con il loro messaggio quando la politica della tua organizzazione li disabilita

2652* Un comando da un [plugin](/docs/it/plugins) o [server MCP](/docs/it/mcp#use-mcp-prompts-as-commands) che non è installato o connesso in questa sessione

2653

2654Claude Code non tratta ogni prompt che inizia con `/` come un comando. Invia il prompt a Claude come messaggio normale quando la prima parola dopo il `/` inizia con punteggiatura, come il `/--` che apre un commento Lean doc, o è un percorso come `/var/log/syslog`.

2655

2656Prima della v2.1.236, se premevi `Enter` mentre il menu dei comandi elencava una corrispondenza vicina per il nome che hai digitato, Claude Code eseguiva quella corrispondenza, quindi un errore di battitura come `/hepl` eseguiva `/help` invece di produrre questo messaggio.

2657

2658**Cosa fare:**

2659

2660* Esegui il nome suggerito, o digita `/` seguito da parte del nome per vedere cosa è disponibile in questa sessione

2661* Se Claude Code segnala un comando documentato come sconosciuto, controlla la sua riga nel [riferimento dei comandi](/docs/it/commands) per il requisito che nomina

2662

2663<h3 id="diff-is-too-large-for-ultrareview">

2664 Il diff è troppo grande per ultrareview

2665</h3>

2666

2667Il diff tra il tuo branch e il branch base, incluse le modifiche non committate e staged, supera i limiti di dimensione per un [ultrareview](/docs/it/ultrareview), quindi `/code-review ultra` e il sottocomando `claude ultrareview` rifiutano la revisione prima che la sessione cloud si avvii. Una revisione rifiutata non usa un'esecuzione gratuita e non fattura crediti di utilizzo. Il messaggio nomina i limiti in vigore, la dimensione del tuo diff, e i file che contribuiscono il maggior numero di righe modificate. Prima della v2.1.216, il messaggio mostrava solo le statistiche di diff grezze.

2668

2669```text theme={null}

2670Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

2671```

2672

2673La revisione di una pull request applica gli stessi limiti; quella forma del messaggio inizia `PR #<N> is too large for ultrareview` e nomina i conteggi di file e righe della PR.

2674

2675**Cosa fare:**

2676

2677* Passa un branch base più vicino al tuo lavoro, come `/code-review ultra develop`, così la revisione copre solo il diff rispetto a quel branch

2678* Dividi il cambiamento in branch più piccoli e rivedi ognuno. I file che il messaggio nomina contribuiscono il maggior numero di righe modificate, quindi inizia spostando quelli nel loro proprio branch.

2679

2680<h3 id="could-not-find-merge-base-with-the-base-branch">

2681 Non potrebbe trovare merge-base con il branch base

2682</h3>

2683

2684`/code-review ultra` e il sottocomando `claude ultrareview` rivedono il diff tra il tuo branch e un branch base, che ha bisogno di un commit che i due condividono. Quando `git merge-base` non ne trova nessuno, Claude Code rifiuta la revisione prima che la sessione cloud si avvii. Su un clone che Claude Code può verificare è completo, con almeno un branch, ricade a [rivedere ogni file tracciato](/docs/it/ultrareview#diff-limits-and-fallbacks) invece di rifiutare. Vedi questo rifiuto quando il branch base non può essere trovato affatto, quando Claude Code non può verificare che il tuo clone è completo, o nel raro repository dove il diff dell'intero albero non è possibile, come il formato di oggetto SHA-256.

2685

2686```text theme={null}

2687Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

2688```

2689

2690L'indizio dopo la prima frase dipende da cosa Claude Code ha osservato:

2691

2692* **Non hai passato un branch base**: Claude Code ha confrontato rispetto al branch predefinito del repository e suggerisce di passare il tuo base esplicitamente, come nell'esempio sopra

2693* **Hai passato un branch base che era già nel tuo clone**: l'indizio legge ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

2694* **Hai passato un branch base che non era nel tuo clone**: Claude Code lo ha recuperato da origin prima di confrontare. L'indizio legge ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``; quando Claude Code non può dire se il tuo clone è shallow, suggerisce `git fetch --unshallow origin` invece. Prima della v2.1.221, l'indizio suggeriva `git fetch --unshallow origin` per ogni branch base recuperato, e su un clone completo quel comando fallisce con `fatal: --unshallow on a complete repository does not make sense`.

2695

2696**Cosa fare:**

2697

2698* Se un altro branch è il tuo vero base, passalo esplicitamente: `/code-review ultra <branch>`

2699* Se il tuo clone potrebbe non avere la cronologia completa, esegui `git fetch --unshallow origin` e riesegui la revisione

2700

2701<h3 id="your-checkout-has-no-branches">

2702 Il tuo checkout non ha branch

2703</h3>

2704

2705Un checkout può avere commit ma nessun branch: se esegui `git init` seguito da `git fetch <url>` e `git checkout FETCH_HEAD`, ottieni un HEAD staccato senza refs. Claude Code pacchetto il tuo repository come un git bundle per caricarlo per un [ultrareview](/docs/it/ultrareview), e non può fare il bundle di un repository che non ha branch o altri refs, quindi `/code-review ultra` e il sottocomando `claude ultrareview` rifiutano la revisione prima che la sessione cloud si avvii.

2706

2707```text theme={null}

2708Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

2709```

2710

2711Prima della v2.1.221, Claude Code tentava di rivedere ogni file tracciato in questo checkout, e il caricamento falliva.

2712

2713**Cosa fare:**

2714

2715* Crea un branch al tuo commit corrente con `git checkout -b <name>`, quindi riesegui la revisione

2716

2717<h3 id="no-github-account-is-connected-to-your-claude-account">

2718 Nessun account GitHub è connesso al tuo account Claude

2719</h3>

2720

2721Hai eseguito `/code-review ultra <PR#>` o `claude ultrareview <PR#>`, e prima di creare la sessione cloud Claude Code chiede al server se [l'account GitHub connesso al tuo account Claude](/docs/it/ultrareview#review-a-pull-request) può raggiungere il repository della PR. Nessun account è connesso, o la connessione è scaduta, quindi il clone cloud fallirebbe e Claude Code rifiuta il lancio. Claude Code non spende un'esecuzione gratuita o fattura crediti di utilizzo per un lancio rifiutato.

2722

2723```text theme={null}

2724Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

2725```

2726

2727Quando [`/web-setup`](/docs/it/web-quickstart#connect-from-your-terminal) non è disponibile nella tua sessione, il messaggio nomina solo il link claude.ai.

2728

2729**Cosa fare:**

2730

2731* Esegui `/web-setup` per connettere il tuo login GitHub CLI al tuo account Claude, o connetti un account su [claude.ai/connect-github](https://claude.ai/connect-github)

2732* Riesegui la revisione un minuto dopo la connessione

2733

2734Prima della v2.1.248, Claude Code non controllava questo prima del lancio.

2735

2736<h3 id="your-connected-github-account-cant-see-the-repository">

2737 Il tuo account GitHub connesso non può vedere il repository

2738</h3>

2739

2740Hai eseguito `/code-review ultra <PR#>` o `claude ultrareview <PR#>`, e [l'account GitHub connesso al tuo account Claude](/docs/it/ultrareview#review-a-pull-request) non può leggere il repository della PR, quindi il clone cloud fallirebbe e Claude Code rifiuta il lancio. Claude Code non spende un'esecuzione gratuita o fattura crediti di utilizzo per un lancio rifiutato.

2741

2742```text theme={null}

2743Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

2744```

2745

2746Quando [`/web-setup`](/docs/it/web-quickstart#connect-from-your-terminal) non è disponibile nella tua sessione, il messaggio nomina solo l'installazione dell'app.

2747

2748**Cosa fare:**

2749

2750* Se il tuo CLI `gh` locale può leggere il repository, esegui `/web-setup` per connettere quel login al tuo account Claude

2751* Riesegui la revisione dopo il cambiamento

2752

2753Prima della v2.1.248, Claude Code non controllava questo prima del lancio.

2754

2755<h3 id="the-github-app-preflight-failed-transiently">

2756 Il preflight dell'app GitHub ha fallito transitoriamente

2757</h3>

2758

2759Hai avviato una [sessione cloud](/docs/it/claude-code-on-the-web) da un repository locale, e due passaggi hanno fallito insieme. Claude Code non potrebbe costruire o caricare il bundle del tuo repository. Prima del caricamento, ha controllato se il servizio cloud può clonare il repository da GitHub, e piuttosto che una risposta definitiva, quel controllo è terminato in un errore che un nuovo tentativo potrebbe chiarire, come un errore di rete, un timeout, o un errore di server temporaneo. Il messaggio completo inizia con cosa ha fermato il bundle, ad esempio `Could not upload repo bundle (<error>)`, e termina con la frase di preflight:

2760

2761```text theme={null}

2762Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

2763```

2764

2765**Cosa fare:**

2766

2767* Riesegui il comando dopo un momento. Quando il controllo GitHub passa, Claude Code può avviare la sessione da un clone GitHub, quindi il caricamento fallito non blocca più il lancio

2768* Se i nuovi tentativi continuano a fallire, l'inizio del messaggio nomina cosa ha fermato il caricamento. Quando quella causa è qualcosa che puoi correggere, correggila così la sessione può avviarsi dal tuo repository locale invece

2769

2770Prima della v2.1.251, Claude Code terminava il messaggio con `Please set up GitHub on https://claude.ai/code` anche quando il controllo GitHub falliva solo transitoriamente, e il consiglio di configurazione non può chiarire un fallimento transitorio.

2771

2772<h3 id="failed-to-resume-the-conversation">

2773 Impossibile riprendere la conversazione

2774</h3>

2775

2776Claude Code non potrebbe leggere o elaborare la trascrizione salvata per la sessione che hai selezionato dal [picker `claude --resume`](/docs/it/sessions#use-the-session-picker), quindi termina il processo piuttosto che continuare in uno stato parzialmente caricato. Il messaggio include il comando per riprovare:

2777

2778```text theme={null}

2779Failed to resume the conversation.

2780Run claude --resume <session-id> to retry, or claude to start a new session.

2781```

2782

2783Claude Code esce con codice 1 dopo aver mostrato il messaggio. Il picker `/resume` all'interno di una sessione in esecuzione segnala `Failed to resume conversation` nella conversazione invece, e la tua sessione corrente continua a funzionare. Prima della v2.1.216, una ripresa fallita dal picker `claude --resume` rimase sullo spinner `Resuming conversation…` indefinitamente invece di mostrare questo messaggio.

2784

2785**Cosa fare:**

2786

2787* Esegui `claude --resume <session-id>` con l'ID della sessione dal messaggio per riprovare

2788* Se il nuovo tentativo fallisce di nuovo, esegui `claude` per avviare una nuova sessione

2789

2790<h3 id="no-conversation-found-with-the-session-id">

2791 Nessuna conversazione trovata con l'ID della sessione

2792</h3>

2793

2794Hai passato un ID della sessione a `claude --resume <session-id>` e nessuna trascrizione salvata lo ha corrisposto:

2795

2796```text theme={null}

2797No conversation found with session ID: <session-id>

2798```

2799

2800Claude Code esce con codice 1 dopo aver mostrato il messaggio. Claude Code [cerca prima il progetto corrente, quindi ogni altro progetto su questa macchina](/docs/it/sessions#resume-a-session) per l'ID. Prima della v2.1.223, la ricerca si fermava alla directory del progetto corrente e ai suoi git worktrees, quindi riprendi dalla directory in cui la sessione ha lavorato l'ultima volta.

2801

2802Cause comuni:

2803

2804* **ID digitato male**: per un'esecuzione non interattiva, l'ID è il campo `session_id` dell'output [`--output-format json`](/docs/it/headless#get-structured-output)

2805* **Trascrizione eliminata**: Claude Code rimuove le trascrizioni dopo il [periodo di conservazione](/docs/it/sessions#where-transcripts-are-stored), 30 giorni per impostazione predefinita, seguendo le [regole di pulizia della conservazione](/docs/it/claude-directory#cleaned-up-automatically)

2806* **Macchina diversa**: Claude Code memorizza le trascrizioni localmente, quindi riprendi la sessione sulla macchina dove è stata eseguita

2807* **Copie duplicate**: se hai copiato una directory di progetto sotto `~/.claude/projects` così due trascrizioni portano lo stesso ID, Claude Code segnala questo messaggio piuttosto che riprendere una copia arbitrariamente

2808

2809**Cosa fare:**

2810

2811* Per una sessione interattiva, apri il [picker della sessione](/docs/it/sessions#use-the-session-picker) con `claude --resume` e premi `Ctrl+A` per allargarlo a ogni progetto su questa macchina, quindi seleziona la sessione

2812* Le sessioni create con `claude -p` o l'[Agent SDK](/docs/it/agent-sdk/overview) non appaiono nel picker, quindi ri-controlla l'ID rispetto al `session_id` che la tua esecuzione originale ha stampato

2813

2814<h3 id="cannot-switch-renderers-in-this-session">

2815 Impossibile cambiare renderer in questa sessione

2816</h3>

2817

2818Quando cambi renderer, Claude Code riavvia il suo processo. Hai eseguito [`/tui`](/docs/it/fullscreen#enable-fullscreen-rendering) in una sessione che Claude Code rifiuta di riavviare, quindi non cambia e non salva nulla. Quale messaggio vedi ti dice la causa:

2819

2820* `Cannot switch renderers while work is running in the background`: hai lavoro in background in esecuzione che un riavvio abbandonarebbe, come una shell in background o un subagente. Attendi che il lavoro finisca o fermalo con [`/tasks`](/docs/it/commands), quindi esegui di nuovo `/tui fullscreen` o `/tui default`

2821* `Cannot switch renderers in this session`: la sessione ha restrizioni che Claude Code non può passare al processo riavviato. Prima della v2.1.234, Claude Code riavviava comunque e la sessione riavviata veniva eseguita senza di esse

2822

2823Nel messaggio delle restrizioni, la parte tra parentesi nomina le restrizioni che Claude Code ha trovato:

2824

2825```text theme={null}

2826Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

2827```

2828

2829Ogni motivo che il messaggio può mostrare tra parentesi:

2830

2831* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: hai avviato la sessione con un flag che Claude Code non passa di nuovo al processo riavviato. Questi flag includono [`--system-prompt`](/docs/it/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, un allowlist [`--tools`](/docs/it/cli-reference#cli-flags), [`--setting-sources`](/docs/it/cli-reference#cli-flags), e [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags)

2832* `permission rules set for this session only`: un [aggiornamento di permesso](/docs/it/hooks#permission-update-entries) da un hook o chiamante SDK ha aggiunto regole deny o ask con la destinazione `session`. Le regole di allow con scope di sessione non attivano il rifiuto. Un riavvio le elimina, e Claude Code chiede di nuovo invece

2833* `ask-before-running rules with no command-line form`: un aggiornamento di permesso ha aggiunto regole ask insieme alle regole che Claude Code passa di nuovo come `--allowed-tools` e `--disallowed-tools`. Nessun flag esiste per le regole ask

2834* `permission rules a command line cannot carry intact` e `added directories a command line cannot carry intact`: un aggiornamento di permesso ha aggiunto una regola o un percorso di directory a metà sessione. La riga di comando del processo riavviato non può portare il suo testo come lo stesso valore

2835

2836**Cosa fare:**

2837

2838* In una sessione avviata senza quelle restrizioni, esegui `/tui fullscreen`, o `/tui default` per cambiare di nuovo. Claude Code salva l'impostazione [`tui`](/docs/it/settings-reference#tui) lì

2839

2840<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

2841 /terminal-setup ha lasciato la tua keymap Zed invariata

2842</h3>

2843

2844Hai eseguito [`/terminal-setup`](/docs/it/terminal-config#enter-multiline-prompts) in Zed, e Claude Code non potrebbe completare l'aggiornamento al tuo Zed `keymap.json`, quindi ha lasciato il file come era.

2845

2846Ogni messaggio nomina il percorso della tua keymap e termina con il blocco di scorciatoie da tastiera da aggiungere tu stesso:

2847

2848```text theme={null}

2849Couldn't update your Zed keymap, so it was left unchanged.

2850To add the binding yourself, add this block to the keymap array in <path to keymap.json>:

2851{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

2852```

2853

2854La prima riga del messaggio nomina la causa:

2855

2856* `Couldn't read your Zed keymap, so it was left unchanged.`: Claude Code non potrebbe leggere il file, ad esempio a causa di permessi di file

2857* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: il file è stato letto bene ma non viene analizzato come un array di blocchi di scorciatoie da tastiera, anche con commenti `//` e virgole finali consentiti

2858* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code non potrebbe copiare il file in un backup `.bak` accanto ad esso, quindi non ha cambiato nulla

2859* `Couldn't update your Zed keymap, so it was left unchanged.`: il risultato unito non ha verificato come una keymap valida che porta la scorciatoia da tastiera, quindi Claude Code lo ha scartato invece di scrivere. Un blocco di scorciatoia da tastiera con una chiave duplicata può causare questo

2860

2861**Cosa fare:**

2862

2863* Copia il blocco dal messaggio nell'array di livello superiore nel tuo `keymap.json` al percorso che il messaggio nomina

2864* Per `isn't a readable list of keybindings`, correggi l'errore di sintassi, o rendi il valore di livello superiore del file un array, quindi esegui di nuovo `/terminal-setup`

2865

2866Prima della v2.1.247, `/terminal-setup` non potrebbe analizzare una keymap Zed che utilizzava commenti `//` o virgole finali, e ha sostituito l'intero file con solo la sua scorciatoia da tastiera mentre segnalava la scorciatoia da tastiera come installata. Per ripristinare una keymap che una versione precedente ha sostituito, usa il file di backup `.bak` descritto sotto [Enter multiline prompts](/docs/it/terminal-config#enter-multiline-prompts).

2867

2868<h3 id="skill-usage-reports-are-not-available-on-this-connection">

2869 I rapporti di utilizzo delle skill non sono disponibili su questa connessione

2870</h3>

2871

2872Hai eseguito [`/skill-doctor`](/docs/it/skills#find-unused-skills) su [Remote Control](/docs/it/remote-control), dal tuo telefono o browser. Claude Code non invia il rapporto di utilizzo delle skill su Remote Control e risponde con questo messaggio invece:

2873

2874```text theme={null}

2875Skill usage reports are not available on this connection.

2876```

2877

2878**Cosa fare:**

2879

2880* Esegui `/skill-doctor` nel terminale sulla macchina dove la sessione è in esecuzione, o esegui `claude -p "/skill-doctor"` lì

2881

2882<h2 id="plugin-errors">

2883 Errori dei plugin

2884</h2>

2885

2886Questi errori provengono dalla configurazione di [plugin](/docs/it/plugins) e [marketplace](/docs/it/plugin-marketplaces). Per i problemi dei plugin che non producono uno dei messaggi in questa pagina, come un URL del marketplace che non si carica o un plugin che si installa ma non appare, vedere [Risoluzione dei problemi dei plugin](/docs/it/discover-plugins#troubleshooting).

2887

2888<h3 id="plugin-eval-is-currently-in-early-access">

2889 plugin eval is currently in early access

2890</h3>

2891

2892Avete eseguito [`claude plugin eval`](/docs/it/plugin-evals) o `claude plugin eval init` e ha terminato con codice 1 con uno di questi messaggi prima di fare qualsiasi cosa:

2893

2894```text theme={null}

2895`plugin eval` is currently in early access

2896```

2897

2898```text theme={null}

2899`plugin eval` is currently unavailable

2900```

2901

2902Il primo messaggio significa che la vostra build è più vecchia della v2.1.269, la prima versione in cui il comando è generalmente disponibile. Il secondo significa che Anthropic ha disattivato il comando lato server; nulla sulla vostra macchina lo riattiva.

2903

2904**Cosa fare:**

2905

2906* Eseguite `claude --version`, quindi `claude update`, ed eseguite il comando di nuovo in una nuova sessione. Vedere i [requisiti per plugin evals](/docs/it/plugin-evals#requirements)

2907* Se vedete il secondo messaggio su una build attuale, riprovate più tardi dopo un altro `claude update`

2908

2909<h3 id="marketplace-is-registered-from-an-untrusted-source">

2910 Marketplace is registered from an untrusted source

2911</h3>

2912

2913Il marketplace è registrato con un nome che è [riservato per i marketplace ufficiali di Anthropic](/docs/it/plugin-marketplaces#marketplace-schema), ma la sua fonte registrata non è un repository GitHub di `anthropics`. Claude Code ri-controlla i nomi riservati ogni volta che carica o aggiorna un marketplace, quindi il marketplace e i plugin installati da esso smettono di caricarsi. Prima della v2.1.205, il nome era controllato solo quando il marketplace veniva aggiunto, quindi una voce registrata prima che il suo nome diventasse riservato continuava a caricarsi.

2914

2915```text theme={null}

2916Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

2917```

2918

2919Per un marketplace la cui fonte non è un repository GitHub o un URL Git, come una directory locale, la frase centrale recita `can only be used with GitHub sources from the 'anthropics' organization` invece. `claude plugin marketplace add` esegue lo stesso controllo e rifiuta un nome riservato con `Failed to add marketplace:` seguito dalla stessa frase del nome riservato.

2920

2921**Cosa fare:**

2922

2923* Se il marketplace è già registrato, eseguite `claude plugin marketplace remove <name>`, quindi aggiungetelo di nuovo dal repository ufficiale `github.com/anthropics`

2924* Se pubblicate un marketplace di terze parti che ha utilizzato il nome prima che diventasse riservato, rinominatelo e chiedete agli utenti di aggiungerlo di nuovo dalla vostra fonte

2925* Vedere l'elenco dei nomi riservati in [Marketplace schema](/docs/it/plugin-marketplaces#marketplace-schema)

2926

2927<h3 id="plugin-command-references-user-config">

2928 Plugin command references user\_config in a shell command

2929</h3>

2930

2931Un hook del plugin, [monitor](/docs/it/plugins-reference#monitors), o un comando MCP [`headersHelper`](/docs/it/mcp#use-dynamic-headers-for-custom-authentication) fa riferimento a un'[opzione del plugin](/docs/it/plugins-reference#user-configuration) `${user_config.KEY}`, e la stringa sostituita verrebbe passata a una shell. Un valore configurato contenente `$(...)`, backtick, o `;` verrebbe eseguito come codice lì, quindi Claude Code rifiuta di avviare il componente invece di sostituire il valore. Il controllo viene eseguito sul modello di comando, quindi l'errore appare anche quando nessun valore è ancora configurato. Prima della v2.1.207, il valore veniva sostituito nel comando della shell.

2932

2933La formulazione dipende da quale superficie ha fatto riferimento all'opzione. Un hook in forma shell segnala:

2934

2935```text theme={null}

2936Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

2937```

2938

2939Un monitor segnala:

2940

2941```text theme={null}

2942Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.

2943```

2944

2945Un MCP `headersHelper` segnala:

2946

2947```text theme={null}

2948headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).

2949```

2950

2951**Cosa fare:**

2952

2953* Per un hook, aggiungete un array `args` in modo che venga eseguito in [forma exec](/docs/it/hooks#exec-form-and-shell-form), dove ogni `${user_config.KEY}` diventa un argomento senza shell in mezzo. Oppure eliminate il riferimento e leggete la variabile di ambiente `$CLAUDE_PLUGIN_OPTION_<KEY>` all'interno dello script

2954* Per un monitor, eliminate il riferimento e fate in modo che lo script del monitor legga il valore da un file di configurazione

2955* Per un `headersHelper`, spostate `${user_config.KEY}` nel campo `headers` del server, che non viene analizzato dalla shell, oppure leggete il valore all'interno dello script helper

2956

2957<h3 id="plugin-archive-integrity-check-failed">

2958 Plugin archive integrity check failed

2959</h3>

2960

2961La voce del marketplace del plugin utilizza una [fonte `archive`](/docs/it/plugin-marketplaces#zip-archives) con un pin `sha256`, e il digest del file scaricato non corrisponde al pin. Claude Code rifiuta l'installazione, quindi nulla cambia nella cache del plugin. La mancata corrispondenza ha tre possibili cause:

2962

2963* Il file all'URL è cambiato dopo che l'autore ha calcolato il pin

2964* L'autore ha inserito il digest sbagliato nella voce del marketplace

2965* L'URL serve un file diverso da quello che l'autore ha fissato

2966

2967```text theme={null}

2968Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

2969```

2970

2971**Cosa fare:**

2972

2973* Se pubblicate il plugin, ricalcolate il digest del file esatto che l'URL serve, ad esempio con `shasum -a 256 my-plugin.zip`, o `Get-FileHash -Algorithm SHA256 my-plugin.zip` in PowerShell, e aggiornate `sha256` nella voce del marketplace

2974* Se installate il plugin, eseguite `/plugin marketplace update <name>` per aggiornare il catalogo nel caso in cui la voce sia stata corretta, quindi riprovate l'installazione

2975* Se i digest continuano a non corrispondere dopo un aggiornamento, chiedete al proprietario del marketplace quale file hanno fissato prima di installare

2976

2977<h3 id="path-escapes-plugin-directory">

2978 Path escapes plugin directory

2979</h3>

2980

2981Un percorso del componente del plugin, dichiarato nel `plugin.json` del plugin o nella sua [voce del marketplace](/docs/it/plugin-marketplaces#plugin-entries), si risolve al di fuori della directory del plugin stesso. Claude Code elimina quel percorso e carica il resto del plugin. Il nome del componente nel messaggio, come `commands` o `hooks`, nomina il campo che ha dichiarato il percorso.

2982

2983```text theme={null}

2984commands path escapes plugin directory: ./../shared.md

2985```

2986

2987Nell'output del comando `claude plugin`, lo stesso errore recita `Path escapes plugin directory: ./../shared.md (commands)`.

2988

2989Claude Code rifiuta sia un percorso che punta al di fuori del plugin come scritto, come `../shared-utils`, sia un symlink che porta al di fuori del plugin e non è uno che le [regole dei symlink del marketplace](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks) consentono. Per un symlink, il messaggio dice anche dove il percorso si risolve:

2990

2991```text theme={null}

2992commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

2993```

2994

2995Su macOS e Linux, Claude Code rifiuta anche un percorso del componente che contiene una barra rovesciata in qualsiasi punto, anche quando il percorso rimane all'interno del plugin. Un plugin i cui percorsi dei componenti utilizzano separatori in stile Windows si carica su Windows e attiva questo rifiuto sulle altre piattaforme:

2996

2997```text theme={null}

2998commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

2999```

3000

3001Prima della v2.1.251, Claude Code caricava un percorso `commands` dichiarato in una voce del marketplace anche quando puntava al di fuori della directory del plugin. Claude Code ha già rifiutato i percorsi dichiarati in `plugin.json` e gli altri percorsi dei componenti in una voce del marketplace.

3002

3003Prima della v2.1.257, il controllo guardava solo l'ortografia del percorso, non dove un symlink porta.

3004

3005**Cosa fare:**

3006

3007* Spostate il file referenziato all'interno della directory del plugin e puntate il percorso ad esso con un percorso relativo `./`

3008* Se il percorso è un symlink a un file al di fuori del plugin, sostituite il symlink con una copia del file

3009* Se il messaggio dice che il percorso contiene una barra rovesciata, scrivete il percorso con barre in avanti, ad esempio `./commands/deploy.md`

3010* Per condividere file con altri plugin nello stesso marketplace, collegateli con un symlink all'interno della directory del plugin, seguendo le [regole dei symlink](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks)

3011

3012<h3 id="path-could-not-be-checked">

3013 Path could not be checked

3014</h3>

3015

3016Claude Code ha chiesto al sistema operativo se un percorso del plugin esiste e ha ricevuto un errore diverso da "non trovato", quindi non carica ciò che il percorso nomina. Quanto del plugin si carica dipende da quale percorso ha fallito:

3017

3018* Una delle [cartelle dei componenti predefinite](/docs/it/plugins-reference#file-locations-reference) di un plugin, come `skills/` o `commands/`: gli altri componenti del plugin si caricano comunque

3019* La directory del plugin stesso: nulla da quel plugin si carica

3020

3021Non vedete questo errore per un percorso che non esiste affatto. In `/plugin`, l'errore appare sotto il plugin e nomina il percorso e il codice che il sistema operativo ha restituito:

3022

3023```text theme={null}

3024skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

3025```

3026

3027In `claude plugin list`, lo stesso errore recita `Path not found: /home/user/my-plugin/skills (skills, ELOOP)`.

3028

3029Le cause che producono questo errore includono:

3030

3031* `ELOOP`: un symlink nel percorso punta a se stesso o forma un ciclo

3032* `EIO` o `ESTALE`: il percorso è su un mount di rete che è rotto o stantio

3033* `EACCES`: una delle directory sopra il percorso nega il permesso di attraversarla

3034

3035**Cosa fare:**

3036

3037* Sostituite un symlink che punta a se stesso con una cartella reale, oppure eliminatelo

3038* Se il percorso è su un mount di rete, rimontate la condivisione

3039* Se il codice è `EACCES`, ripristinate il vostro permesso di esecuzione sulle directory sopra il percorso

3040* Eseguite `/reload-plugins` dopo aver corretto il percorso, o riavviate Claude Code, per caricare il plugin o il componente

3041

3042Prima della v2.1.265, Claude Code trattava una cartella dei componenti predefinita che non poteva controllare come assente e caricava il plugin senza quel componente, senza errore.

3043

3044<h3 id="marketplace-entry-path-does-not-stay-inside-the-marketplace-directory">

3045 Marketplace entry path does not stay inside the marketplace directory

3046</h3>

3047

3048La [voce del marketplace](/docs/it/plugin-marketplaces#plugin-entries) del plugin dichiara un percorso di origine che Claude Code non può risolvere a una posizione all'interno della directory del marketplace stesso, quindi il plugin non si installa o non si carica. Il rifiuto copre:

3049

3050* Un percorso di voce che è assoluto, esce dal marketplace con `..`, o è scritto come un percorso di rete

3051* Una voce in un marketplace recuperato da una fonte remota, come git o un URL, che raggiunge il suo target attraverso un symlink che si risolve al di fuori della directory del marketplace

3052* Una voce relativa in un marketplace aggiunto da un URL diretto al suo `marketplace.json`: Claude Code scarica solo quel file, quindi nessun file di plugin locale esiste per il percorso da nominare. Vedere [Plugins with relative paths fail in URL-based marketplaces](/docs/it/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)

3053

3054`claude plugin install` segnala il rifiuto così:

3055

3056```text theme={null}

3057Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped or link-traversing entry, an entry of a fetched marketplace that resolves outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

3058```

3059

3060Quando la voce di un plugin già installato fallisce lo stesso controllo, `claude plugin list` mostra il plugin come `failed to load` con:

3061

3062```text theme={null}

3063Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

3064```

3065

3066**Cosa fare:**

3067

3068* Se mantenete il marketplace, scrivete il `source` della voce come un percorso relativo semplice come `./plugins/my-plugin`, e mantenete qualsiasi symlink che attraversa puntato all'interno della directory del marketplace

3069* Se avete aggiunto il marketplace da un URL diretto, le voci relative non possono risolversi. Chiedete all'autore del marketplace di utilizzare [un'altra fonte di plugin](/docs/it/plugin-marketplaces#plugin-sources), o aggiungete il marketplace dal suo repository git invece

3070

3071<h3 id="failed-to-load-marketplace-configuration">

3072 Failed to load marketplace configuration

3073</h3>

3074

3075Claude Code mantiene i marketplace dei plugin che avete aggiunto in un file di registro in `~/.claude/plugins/known_marketplaces.json`. Un comando di plugin che ha bisogno del registro, come `claude plugin install`, fallisce con uno di due messaggi quando Claude Code non può utilizzare il file:

3076

3077* `Failed to load marketplace configuration`: il file non è JSON valido, o non può essere letto. Un file vuoto fallisce in questo modo.

3078* `Marketplace configuration file is corrupted`: il file è JSON valido ma i suoi contenuti non corrispondono allo schema del registro.

3079

3080Un file mancante non è un fallimento: Claude Code lo tratta come un registro senza marketplace.

3081

3082Con un file vuoto, `claude plugin install` segnala:

3083

3084```text theme={null}

3085✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

3086```

3087

3088Prima della v2.1.246, `claude plugin install` non segnalava questo fallimento.

3089

3090**Cosa fare:**

3091

3092* Aprite `~/.claude/plugins/known_marketplaces.json` e riparate il JSON, o correggete le voci che il messaggio nomina come non corrispondenti allo schema del registro

3093* Se non potete ripararla, eliminate il file o sostituite i suoi contenuti con `{}`, quindi aggiungete di nuovo ogni marketplace con `claude plugin marketplace add <source>`. Claude Code ri-registra i marketplace che le vostre impostazioni utente o gestite dichiarano in [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) la prossima volta che lo avviate in una cartella che avete considerato attendibile.

3094

3095<h2 id="tool-errors">

3096 Errori degli strumenti

3097</h2>

3098

3099Questi errori provengono dagli strumenti integrati di Claude. Claude corregge la maggior parte degli errori degli strumenti autonomamente. Quando è necessario un cambiamento da parte vostra, l'elenco **Cosa fare** di quell'errore specifica cosa cambiare.

3100

3101<h3 id="agent-would-be-spawned-with-zero-tools">

3102 Agent would be spawned with zero tools

3103</h3>

3104

3105Ogni voce nell'elenco [`tools` del subagent](/docs/it/sub-agents#supported-frontmatter-fields) non ha corrisposto a uno strumento utilizzabile, quindi Claude Code ha rifiutato di avviare il subagent: senza strumenti, non poteva agire. Il messaggio raggruppa le vostre voci in base a cosa è andato storto:

3106

3107* **Unrecognized**: la voce non corrisponde a nessun nome di strumento, di solito un errore di battitura come `Grpe` per `Grep`.

3108* **Not available to subagents**: la voce nomina uno strumento reale che [i subagent non possono usare](/docs/it/sub-agents#available-tools). I subagent in background mantengono un set di strumenti integrati più piccolo, quindi una voce che solo un subagent in foreground può usare finisce qui quando il subagent verrebbe eseguito in background, che è l'impostazione predefinita. Se elencate `Agent`, il messaggio lo segnala nel gruppo successivo.

3109* **Matched no tools in this session**: la voce è valida ma nessuno strumento nella sessione corrente la corrisponde in questo momento, come `mcp__github__*` senza server MCP GitHub connesso, o `Agent` per un subagent al [limite di profondità](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents).

3110

3111Omettere il campo `tools` non attiva mai questo rifiuto. Se lasciate l'elenco `tools` vuoto, o `disallowedTools` rimuove ogni voce in esso, Claude Code salta anche il rifiuto e avvia il subagent senza strumenti.

3112

3113Prima della v2.1.208, il subagent veniva avviato senza strumenti e poteva restituire un risultato vuoto o confuso.

3114

3115```text theme={null}

3116Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

3117```

3118

3119**Cosa fare:**

3120

3121* Correggete ogni voce che l'errore nomina rispetto agli [strumenti disponibili per i subagent](/docs/it/sub-agents#available-tools)

3122* Rimuovete le voci per gli strumenti che la sessione non ha, come gli strumenti MCP da un server che non è connesso

3123* Per uno strumento che [i subagent in background eliminano](/docs/it/sub-agents#available-tools), come `LSP`, rimuovete la voce. Per mantenere lo strumento, [disattivate la fork mode](/docs/it/sub-agents#turn-fork-mode-on-or-off) e chiedete a Claude di eseguire il subagent in foreground

3124* Eliminate il campo `tools` invece di elencare gli strumenti per dare al subagent ogni [strumento disponibile per i subagent](/docs/it/sub-agents#available-tools)

3125* Per un elenco `tools` che contiene solo `Agent`, aumentate il [limite di profondità](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents) o date all'agent almeno uno strumento aggiuntivo: Claude Code trattiene `Agent` a quel limite, quindi un elenco con nient'altro in esso si risolve in nessuno strumento

3126

3127<h3 id="file-is-covered-by-a-read-deny-rule">

3128 File is covered by a Read deny rule

3129</h3>

3130

3131Lo strumento Edit o Write è stato chiamato su un percorso corrispondente a una [regola di negazione `Read`](/docs/it/permissions#read-and-edit), inclusa la creazione di un nuovo file in quel percorso. Entrambi gli strumenti cambiano il contenuto che Claude deve essere in grado di leggere di nuovo, quindi Claude Code rifiuta la chiamata prima di qualsiasi accesso ai file. NotebookEdit non è coperto dalle regole di negazione `Read`. Prima della v2.1.228, la regola bloccava solo lo strumento Edit, e prima della v2.1.208, solo una regola di negazione `Edit` bloccava le modifiche.

3132

3133```text theme={null}

3134File is covered by a Read deny rule in your permission settings and cannot be edited.

3135```

3136

3137Quando Claude Code rifiuta lo strumento Write, il messaggio termina con `and cannot be written` invece.

3138

3139**Cosa fare:**

3140

3141* Se Claude dovrebbe essere in grado di cambiare il file, rimuovete o restringete la regola di negazione `Read` in `/permissions` o nelle [impostazioni](/docs/it/settings-reference#permission-settings)

3142* Se il file deve rimanere intatto, mantenete la regola e aggiungete una regola di negazione `Edit` per lo stesso percorso per bloccare anche lo strumento NotebookEdit

3143

3144<h3 id="subagent-type-is-required">

3145 subagent\_type is required

3146</h3>

3147

3148```text theme={null}

3149subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

3150```

3151

3152Claude ha chiamato lo [strumento Agent](/docs/it/tools-reference#agent-tool-behavior) senza un `subagent_type`, e questa sessione non ha un [subagent per uso generale](/docs/it/sub-agents#built-in-subagents) su cui fare affidamento. Questo è il caso in due configurazioni:

3153

3154* [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/it/env-vars) è impostato in modalità non interattiva, che rimuove ogni subagent integrato

3155* L'agent del thread principale della sessione ha una [lista di consentiti `tools: Agent(...)`](/docs/it/sub-agents#restrict-which-subagents-can-be-spawned) che esclude `general-purpose`

3156

3157**Cosa fare:**

3158

3159* Di solito nulla: il messaggio elenca i subagent che la sessione ha, quindi Claude può riprovare con uno di essi

3160* Se Claude continua a fallire, aggiungete `general-purpose` alla lista di consentiti `tools: Agent(...)`, o disattivate `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`

3161

3162Prima della v2.1.235, la stessa chiamata falliva con `Agent type 'general-purpose' not found`.

3163

3164<h3 id="memory-index-is-over-its-read-limit">

3165 Memory index is over its read limit

3166</h3>

3167

3168Claude ha scritto nell'indice di [memoria automatica](/docs/it/memory#auto-memory) `MEMORY.md` e lo ha lasciato oltre uno dei suoi limiti di lettura: 200 righe o 25KB. La scrittura è riuscita, ma solo le prime 200 righe o 25KB, a seconda di quale viene raggiunto per primo, vengono caricate all'inizio di una sessione, quindi tutto ciò che supera il limite viene eliminato ogni volta che l'indice viene letto. Prima della v2.1.210, un indice oltre il limite veniva silenziosamente troncato al caricamento successivo senza segnale al momento della scrittura.

3169

3170```text theme={null}

3171Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

3172```

3173

3174Solo il contenuto che viene caricato conta verso i limiti. Il frontmatter YAML e i commenti HTML a livello di blocco vengono rimossi prima che l'indice venga caricato, quindi sono esclusi dalla misurazione. Prima della v2.1.211, Claude Code misurava il file grezzo, e il frontmatter o i commenti potevano attivare questo errore anche quando il contenuto caricato si adattava.

3175

3176Claude Code consegna l'errore a Claude dopo la scrittura piuttosto che stamparlo come banner nel vostro terminale, quindi potreste notarlo solo nella trascrizione.

3177

3178Quando la scrittura di Claude avvicina il file a un limite senza superarlo, Claude Code restituisce un promemoria più mite per compattare l'indice invece di questo errore.

3179

3180**Cosa fare:**

3181

3182* Lasciate che Claude riscrivi `MEMORY.md`, o chiedetegli di farlo: mantenete una riga per voce, spostate i dettagli in file di argomenti e unite o eliminate le voci obsolete

3183* Per ridurre l'indice voi stessi, vedete [Audit and edit your memory](/docs/it/memory#audit-and-edit-your-memory)

3184

3185<h3 id="pkill-pattern-matches-the-claude-code-process">

3186 pkill pattern matches the Claude Code process

3187</h3>

3188

3189Un comando `pkill` in una chiamata dello strumento Bash ha usato un pattern, tipicamente con `-f`, che corrisponde al processo Claude Code stesso, quindi Claude Code rifiuta il comando invece di permettergli di terminare la sessione. Claude Code testa il pattern con `pgrep` prima di eseguire `pkill` e rifiuta quando il suo ID di processo è nel risultato. Il controllo viene eseguito solo su Linux; su macOS, `pkill` viene eseguito senza modifiche. Prima della v2.1.214, il comando veniva eseguito e un pattern corrispondente terminava la sessione Claude Code a metà turno.

3190

3191```text theme={null}

3192pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

3193```

3194

3195Il rifiuto appare nel risultato dello strumento Bash piuttosto che come banner nel vostro terminale, e Claude di solito regola il comando autonomamente.

3196

3197**Cosa fare:**

3198

3199* Restringete il pattern in modo che corrisponda solo al processo previsto, ad esempio il percorso completo del binario di destinazione piuttosto che una breve sottostringa

3200* Per arrestare i processi avviati dalla shell corrente, usate `pkill -P $$` con il pattern, che limita la corrispondenza ai processi figli della shell stessa

3201

3202<h3 id="failed-to-write-to-a-teammate-inbox">

3203 Failed to write to a teammate's inbox

3204</h3>

3205

3206Claude Code non ha potuto scrivere un messaggio nella casella di posta di un compagno di squadra sotto `~/.claude/teams/{team-name}/inboxes/`, quindi il destinatario non ha ricevuto nulla. La scrittura fallisce quando Claude Code non può creare o aggiornare il file, ad esempio perché il disco è pieno, la directory non è scrivibile, o un altro agent tiene il blocco della casella di posta troppo a lungo. Prima della v2.1.224, Claude Code segnalava il messaggio come inviato anche quando la scrittura falliva.

3207

3208L'errore appare nel risultato dello strumento dell'agent mittente piuttosto che come banner nel vostro terminale, e il suo testo dice a Claude di riprovare:

3209

3210```text theme={null}

3211Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.

3212```

3213

3214I messaggi del protocollo strutturato del [team di agent](/docs/it/agent-teams) falliscono allo stesso modo, e l'errore nomina il messaggio non consegnato: quando Claude Code non può scrivere un'approvazione del piano, un rifiuto del piano, una richiesta di arresto o un rifiuto di arresto, l'errore recita `Failed to write the <message> to <name>'s inbox — nothing was sent`. L'`approvazione del piano` in quell'elenco è la decisione del lead che approva il piano di un compagno di squadra; la presentazione del piano del compagno di squadra è il messaggio separato `richiesta di approvazione del piano`. Quel messaggio e altri due messaggi del protocollo portano il loro testo di messaggio e conseguenza:

3215

3216* `Failed to write the plan approval request to the lead's inbox — plan not submitted; try again`: il piano del compagno di squadra non ha mai raggiunto il lead, e il compagno di squadra rimane in modalità piano fino a quando una nuova presentazione non riesce

3217* `The permission request could not be delivered to the team lead (mailbox write failed)`: la richiesta di autorizzazione del compagno di squadra non ha mai raggiunto il lead, quindi nessuno ha approvato la chiamata dello strumento

3218* `The confirmation could not be written to team-lead's inbox.`: l'approvazione dell'arresto stesso ha avuto effetto e il compagno di squadra esce; solo la conferma al lead manca

3219

3220Quando voi stessi inviate un messaggio a un compagno di squadra, digitando `@name` seguito dal messaggio nella sessione del lead, lo stesso errore appare come notifica, `Couldn't write to @name's inbox — message not sent. Try again.`, e Claude Code mantiene il vostro testo nella casella del prompt in modo che possiate inviarlo di nuovo.

3221

3222**Cosa fare:**

3223

3224* Chiedete al mittente di inviare di nuovo il messaggio; la contesa per il blocco della casella di posta è transitoria e si risolve al nuovo tentativo

3225* Controllate lo spazio libero su disco e verificate che `~/.claude/teams` e i file sotto di esso siano scrivibili dal vostro utente

3226

3227<h3 id="message-too-large-for-cross-session-delivery">

3228 Message too large for cross-session delivery

3229</h3>

3230

3231Il [messaggio tra sessioni](/docs/it/cross-session-messaging) di Claude a un'altra delle vostre sessioni su questa macchina era troppo lungo per essere inviato. Claude Code lo ha rifiutato e la sessione ricevente non ha ricevuto nulla. Il rifiuto appare nel risultato dello strumento della sessione mittente, non come banner nel vostro terminale. Nomina entrambe le dimensioni e come fare in modo che il messaggio si adatti:

3232

3233```text wrap theme={null}

3234Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.

3235```

3236

3237L'invio dello stesso testo fallisce allo stesso modo.

3238

3239**Cosa fare:**

3240

3241* Chiedete a Claude di riassumere il messaggio, o di mettere il contenuto in massa in un file e inviare il percorso del file

3242* Chiedete a Claude di dividere il contenuto in diversi messaggi più brevi

3243

3244Prima della v2.1.235, Claude Code segnalava un messaggio di dimensioni eccessive come inviato. La sessione ricevente lo eliminava senza leggerlo.

3245

3246<h3 id="too-many-messages-to-this-session-just-now">

3247 Too many messages to this session just now

3248</h3>

3249

3250Claude ha inviato una raffica rapida di [messaggi tra sessioni](/docs/it/cross-session-messaging) a una delle vostre sessioni su questa macchina, e la raffica ha raggiunto ciò che quella casella di posta della sessione accetta. Claude Code ha rifiutato l'invio successivo e la sessione ricevente non ha ricevuto nulla da esso. Il rifiuto appare nel risultato dello strumento della sessione mittente, non come banner nel vostro terminale:

3251

3252```text wrap theme={null}

3253Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.

3254```

3255

3256**Cosa fare:**

3257

3258* Di solito nulla: Claude raggruppa il contenuto rimanente in un messaggio, o aspetta prima di inviare di più

3259* Se avete voi stessi richiesto la raffica, chiedete a Claude di combinare ciò che rimane in un singolo messaggio

3260

3261Prima della v2.1.236, Claude Code segnalava questi invii come inviati. La sessione ricevente li eliminava senza leggerli.

3262

3263<h3 id="refusing-to-send-a-cross-session-message">

3264 Refusing to send a cross-session message

3265</h3>

3266

3267Prima che Claude Code scriva un [messaggio tra sessioni](/docs/it/cross-session-messaging) a un'altra delle vostre sessioni su questa macchina, verifica che la socket della casella di posta della sessione di destinazione sia l'endpoint a cui il messaggio era indirizzato. Quando un controllo fallisce, Claude Code rifiuta l'invio nella sessione mittente e la sessione di destinazione non riceve nulla. Per un messaggio che Claude invia, il rifiuto appare nel risultato dello strumento della sessione mittente:

3268

3269```text theme={null}

3270Failed to send to api-worker: Refusing to send: reply target is a symlink

3271```

3272

3273Il testo dopo `Refusing to send:` nomina il controllo che ha fallito:

3274

3275* `reply target is a symlink`: un collegamento simbolico si trova nel percorso della socket della sessione di destinazione. Claude Code non consegna attraverso di esso, perché un collegamento lì potrebbe reindirizzare il messaggio a un endpoint che la sessione di destinazione non ha creato.

3276* `cannot vet reply target`: Claude Code non ha potuto ispezionare il percorso di destinazione affatto, ad esempio perché la lettura è fallita con un errore di autorizzazione.

3277* `connected endpoint is not the expected process`: il processo che tiene la socket non è la sessione a cui il messaggio era indirizzato, quindi l'indirizzo è obsoleto o un altro processo ha sostituito la socket.

3278* `connected endpoint identity could not be read`: Claude Code si è connesso ma non ha potuto leggere quale processo tiene l'altro capo, quindi non ha potuto confermare la destinazione. Questo può essere transitorio.

3279* `connected endpoint is not owned by this user`: il processo che tiene la socket viene eseguito con un account utente diverso, quindi non è una delle vostre sessioni.

3280* `connected endpoint owner could not be read`: Claude Code si è connesso ma non ha potuto leggere quale account utente possiede l'altro capo, quindi non ha potuto confermare che l'endpoint è vostro.

3281* `connected endpoint is a different process with the expected pid`: l'ID del processo corrisponde a quello a cui il messaggio era indirizzato, ma Claude Code non ha potuto confermare che è lo stesso processo. Di solito quella sessione è uscita e il sistema operativo ha riutilizzato il suo ID di processo, quindi l'indirizzo è obsoleto.

3282

3283**Cosa fare:**

3284

3285* Di solito nulla: i controlli impediscono a un messaggio di raggiungere un endpoint diverso dalla sessione a cui era indirizzato, e nulla è stato inviato

3286* Chiedete a Claude di elencare di nuovo le vostre sessioni e di inviare di nuovo; un rifiuto causato da un indirizzo obsoleto si risolve una volta che Claude invia a quello corrente

3287* Se `reply target is a symlink` si ripete per una sessione, controllate cosa ha creato un collegamento nel percorso della socket di quella sessione, mostrato nel suo `/status` sotto `Peer address`

3288* Per `connected endpoint identity could not be read`, inviate di nuovo; la condizione può essere transitoria

3289* Se `connected endpoint is not owned by this user` appare su una macchina condivisa, la sessione a quell'indirizzo viene eseguita con l'account di un altro utente, quindi Claude non può inviarle messaggi dal vostro

3290

3291Prima della v2.1.248, Claude Code non controllava l'utente proprietario dell'endpoint o l'ora di inizio del processo, quindi i rifiuti che nominano quei controlli non appaiono nelle versioni precedenti.

3292

3293<h3 id="refusing-after-a-symlink-changed">

3294 Refusing to read, write, or search a path

3295</h3>

3296

3297Claude Code controlla le [regole di autorizzazione](/docs/it/permissions#read-and-edit) di un percorso di file, quindi conferma di nuovo quella risoluzione quando lo strumento apre il file o avvia la ricerca. Quando non può confermare che il percorso conduce ancora alla posizione che il controllo ha approvato, Claude Code rifiuta l'operazione invece di seguirla. Il rifiuto appare nel risultato dello strumento:

3298

3299```text theme={null}

3300Refusing to read /path/to/file: its symlink resolution changed after permission was checked. If a link in the working directory is being rewritten concurrently, stop that and retry.

3301```

3302

3303Il testo dopo il percorso nomina il motivo:

3304

3305* `its symlink resolution changed after permission was checked`: un collegamento simbolico lungo il percorso, o in una radice di ricerca Grep o Glob, è stato sostituito tra il controllo di autorizzazione e l'operazione

3306* `its parent-directory symlink resolution changed after permission was checked`: una directory attraverso cui passa il percorso di scrittura non si risolve più nella posizione approvata

3307* `it is a symbolic link. Write to the link's target path instead`: un collegamento simbolico si trova nella posizione di scrittura approvata stessa

3308* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`: una regola di negazione `Read` per la ricerca nomina un percorso che passa attraverso un collegamento simbolico, e quel collegamento è cambiato mentre Claude Code stava preparando la ricerca

3309* `it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.`: la radice di ricerca esiste ma non ha potuto essere aperta; il codice tra parentesi è l'errore del sistema operativo

3310* `its permission check expired before it ran (too many concurrent file operations). Retry.`: Claude Code ha eliminato il record di approvazione in molte operazioni di file simultanee prima che lo strumento lo usasse; riprovare esegue un controllo di autorizzazione fresco

3311* `ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration`: Claude Code non ha potuto risolvere il binario `rg` a un percorso assoluto, quindi rifiuta le ricerche al di fuori della directory di lavoro piuttosto che eseguirne una che le vostre regole di negazione non coprono

3312

3313**Cosa fare:**

3314

3315* Di solito nulla: il rifiuto raggiunge Claude come risultato dello strumento, e l'operazione rifiutata non viene eseguita

3316* Se un rifiuto di collegamento simbolico si ripete su un percorso, trovate cosa continua a riscrivere un collegamento lì, come uno strumento di compilazione o un file watcher, o chiedete a Claude di usare il percorso risolto del file invece di quello collegato

3317* Se questo rifiuto appare per ogni file mentre Claude Code viene eseguito su Windows all'interno di un AppContainer o sandbox con token limitato, aggiornate alla v2.1.265 o successiva

3318* Per il rifiuto di ripgrep, installate ripgrep con il vostro gestore di pacchetti in modo che `rg` si risolva a un percorso assoluto su `PATH`, o mantenete le ricerche sotto la directory di lavoro

3319

3320Prima della v2.1.251, Claude Code ri-controllava la risoluzione di un percorso solo per le scritture di file, quindi un collegamento sostituito dopo il controllo di autorizzazione poteva reindirizzare una lettura o una ricerca a una posizione diversa senza un messaggio. Di questi rifiuti, solo il rifiuto di scrittura della directory padre appare nelle versioni precedenti.

3321

3322<h3 id="task-output-swap-refused">

3323 Task output swap refused

3324</h3>

3325

3326Claude Code salva l'output di ogni comando Bash in un file sotto la sua directory temporanea. Ogni volta che apre uno di questi file, controlla che il percorso conduca ancora al file che ha creato, senza collegamento simbolico, collegamento fisico aggiuntivo o directory spostata che lo reindirizza. Questo messaggio significa che quel controllo è fallito, quindi Claude Code ha rifiutato l'operazione piuttosto che scrivere o leggere l'output attraverso quel percorso. Il messaggio appare nel risultato dello strumento Bash:

3327

3328```text wrap theme={null}

3329task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

3330```

3331

3332Il testo tra parentesi nomina il controllo che ha fallito. Motivi come `output symlink was re-pointed`, `output file identity changed`, e `not a regular file` segnalano tutti la stessa condizione: qualcosa nel percorso di output o lungo di esso non è più il file che Claude Code ha creato. Solo alcuni motivi portano una frase `To recover:`.

3333

3334Se il controllo fallisce mentre un comando è ancora in esecuzione, Claude Code arresta il comando e il suo risultato segnala:

3335

3336```text theme={null}

3337Command killed: its output file was replaced or could no longer be verified

3338```

3339

3340**Cosa fare:**

3341

3342* Aggiornate alla v2.1.260 o successiva. Le versioni precedenti a volte mostravano questo messaggio quando nessun collegamento o directory spostata era presente

3343* Riavviate Claude Code con [`CLAUDE_CODE_TMPDIR`](/docs/it/env-vars) impostato su una directory fresca

3344* O controllate la directory del vostro progetto sotto la directory temporanea di Claude Code, `/private/tmp/claude-501/-Users-you-my-project` nel messaggio di esempio. Se quel percorso è un collegamento simbolico, o una directory che non dovrebbe essere lì, rimuovete il collegamento o la directory stessa piuttosto che la destinazione del collegamento, e riavviate Claude Code

3345* Se il rifiuto si ripete, un processo sta sostituendo, collegando o rimuovendo voci sotto la directory temporanea di Claude Code mentre la sessione viene eseguita. Impostate [`CLAUDE_CODE_TMPDIR`](/docs/it/env-vars) su una directory che nient'altro gestisce e riavviate

3346

3347<h3 id="the-source-file-is-not-valid-utf-8-text">

3348 The source file is not valid UTF-8 text

3349</h3>

3350

3351Claude ha tentato di pubblicare un [artifact](/docs/it/artifacts) da un file i cui byte non si decodificano come testo, o il cui testo contiene già il carattere di sostituzione `U+FFFD`, quindi Claude Code ha rifiutato la pubblicazione prima di caricare qualsiasi cosa. Il messaggio appare nel risultato dello strumento Artifact e nomina la prima posizione da correggere:

3352

3353```text wrap theme={null}

3354file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.

3355

3356file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.

3357```

3358

3359Claude Code decodifica il file come UTF-8, o come UTF-16 quando inizia con un byte-order mark UTF-16 little-endian. Quando un file UTF-16 di questo tipo non si decodifica, il primo messaggio nomina `UTF-16` e vi dice comunque di riscrivere il file come UTF-8. Quando seguono più posizioni di quella nominata, il messaggio aggiunge un conteggio come `(+2 more)` dopo la posizione.

3360

3361**Cosa fare:**

3362

3363* Di solito nulla: Claude riscrive il file e pubblica di nuovo

3364* Se il file è uno che avete scritto o esportato, salvatelo di nuovo come UTF-8, e sostituite ogni `U+FFFD` con il carattere che un'edizione, incolla o conversione precedente ha perso

3365* Per mostrare un `U+FFFD` intenzionale sulla pagina, scrivetelo come `�` nell'HTML invece del carattere letterale

3366

3367Prima della v2.1.267, Claude Code caricava un file di questo tipo senza controllarlo, e il server rifiutava la pubblicazione invece.

3368

3369<h2 id="background-session-errors">

3370 Errori di sessione in background

3371</h2>

3372

3373Le [sessioni in background](/docs/it/agent-view) vengono eseguite senza un terminale interattivo proprio, quindi i comandi che ne richiedono uno si comportano diversamente lì. Questi messaggi appaiono nella trascrizione di una sessione in background, nel terminale che si collega a una, nella sessione o shell da cui si invia, o, per le [voci worktree-guard](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) di seguito, in qualsiasi sessione isolata in un worktree o che esegue un subagent isolato da worktree; dove un messaggio è specifico di una superficie, la sua voce lo dice.

3374

3375<h3 id="commands-refused-in-a-background-session">

3376 Comandi rifiutati in una sessione in background

3377</h3>

3378

3379I comandi che aprono una finestra di dialogo interattiva non possono farlo mentre nessun terminale è collegato a una sessione in background. `/install-github-app`, l'elenco delle impostazioni `/mcp` e le azioni di autenticazione nel menu del server MCP rispondono con un messaggio, e la sessione appare sotto **Needs input** nella [vista agente](/docs/it/agent-view) in modo che tu possa trovarla, collegarti ed eseguire di nuovo il comando. Mentre un terminale è collegato, questi comandi funzionano normalmente.

3380

3381Prima della v2.1.216, la sessione non appariva sotto **Needs input** dopo uno di questi rifiuti. Nella v2.1.213 attraverso v2.1.215, i comandi funzionavano ancora mentre un terminale era collegato, e il messaggio di rifiuto ti diceva di collegarti ed eseguire di nuovo il comando. Dalla v2.1.208 attraverso v2.1.212, Claude Code li rifiutava anche mentre un terminale era collegato, con un messaggio come `Can't open MCP settings in a background session`; su quelle versioni, esegui il comando da una sessione `claude` regolare invece, o esegui l'upgrade. Prima della v2.1.208, aprivano la loro finestra di dialogo all'interno della sessione in background. Solo nella v2.1.208, Claude Code ha anche rifiutato il selettore `/model` in una sessione in background, e `/upgrade` ha stampato l'URL di upgrade invece di aprire un browser.

3382

3383La formulazione nomina il comando. L'elenco delle impostazioni `/mcp` riporta:

3384

3385```text theme={null}

3386Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view — open it and run /mcp to manage servers, or use `/mcp enable|disable|reconnect <server>` to steer without the panel.

3387```

3388

3389**Cosa fare:**

3390

3391* Collegati alla sessione dalla vista agente, dove è elencata sotto **Needs input**, ed esegui di nuovo il comando

3392* Oppure usa il modulo che il messaggio nomina, come `/mcp reconnect <server>`, `/mcp enable`, o `/mcp disable`, che funzionano senza collegarsi

3393

3394<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">

3395 Scrittura o comando bloccato perché il percorso non può essere risolto in modo sicuro

3396</h3>

3397

3398Claude ha indirizzato un file o una directory di lavoro attraverso un'ortografia che la [guardia di isolamento worktree](/docs/it/agent-view#how-file-edits-are-isolated) non può risolvere in un'unica posizione verificabile. La guardia controlla le scritture e le directory di lavoro dei comandi in [qualsiasi sessione isolata in un worktree](/docs/it/worktrees#how-claude-code-enforces-isolation), interattiva o in background, e in [subagent isolati da worktree](/docs/it/worktrees#isolate-subagents-with-worktrees). Risolve i symlink prima di controllare che l'operazione non raggiunga il checkout condiviso, e quando la risoluzione fallisce, blocca l'operazione piuttosto che lasciarla atterrare lì. Il messaggio nomina le forme di percorso che rifiuta e come riprovare:

3399

3400```text theme={null}

3401This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

3402```

3403

3404Un comando bloccato riporta la stessa causa per la sua directory di lavoro e termina con `re-run the command from its direct symlink-free path`. Prima della v2.1.217, la guardia confrontava le ortografie dei percorsi senza risolvere i symlink, quindi queste ortografie non erano bloccate e una scrittura instradata attraverso un symlink poteva atterrare nel checkout condiviso.

3405

3406**Cosa fare:**

3407

3408* Di solito nulla: il messaggio completo va a Claude come errore dello strumento, e Claude riprova con il percorso diretto che nomina. Per una modifica di file bloccata, la vista della conversazione mostra solo una breve riga `Error editing file`; il messaggio completo appare nella vista della trascrizione, che apri con `Ctrl+O`. Un comando bloccato lo stampa nel suo output di comando.

3409* Se il blocco si ripete sullo stesso file, il percorso probabilmente passa attraverso un symlink committato il cui target contiene `..`, come `docs/current -> ../README.md`; chiedi a Claude di modificare il file target dal suo percorso reale invece che attraverso il link

3410

3411<h3 id="write-or-command-blocked-because-the-path-names-a-network-location">

3412 Scrittura o comando bloccato perché il percorso nomina una posizione di rete

3413</h3>

3414

3415Claude ha indirizzato un file o una directory di lavoro attraverso un percorso che nomina un'unità che non è sulla tua macchina, una condivisione UNC come `\\server\share\file` o un percorso di automount `/net`, mentre il checkout della sessione è su un disco locale. La stessa [guardia di isolamento worktree](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) non può verificare che tale percorso rimanga fuori dal checkout condiviso, quindi blocca l'operazione. Isolare la sessione in un worktree non solleva il blocco. Il messaggio nomina la forma di percorso da usare invece:

3416

3417```text theme={null}

3418This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

3419```

3420

3421Un comando bloccato riporta la stessa causa per la sua directory di lavoro e termina con `re-run the command from its local, plainly-spelled path`. Prima della v2.1.217, la guardia confrontava solo il testo del percorso, quindi indirizzare un file all'interno del checkout attraverso un percorso UNC o `/net` non era bloccato.

3422

3423**Cosa fare:**

3424

3425* Di solito nulla: Claude riprova con l'ortografia locale che il messaggio chiede

3426* Se il file è su una condivisione di rete piuttosto che un file locale scritto con un percorso di rete, è al di fuori dell'area di lavoro locale della sessione; modificalo da una sessione interattiva regolare invece

3427

3428<h3 id="this-session-has-no-saved-transcript">

3429 Questa sessione non ha una trascrizione salvata

3430</h3>

3431

3432Hai collegato una [sessione in background](/docs/it/agent-view) interrotta che è stata messa in background da un'altra conversazione con `←` o `/background` e interrotta prima che la sua prima risposta finisse. Fino a quando quella prima risposta non finisce, la conversazione vive ancora solo nella sessione da cui è stata messa in background, quindi `claude attach` rifiuta di avviare la sessione interrotta piuttosto che iniziare una conversazione vuota con lo stesso ID di sessione. Il messaggio termina con il comando `claude respawn` per questa sessione:

3433

3434```text theme={null}

3435This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

3436```

3437

3438Aprire la stessa riga della sessione nella [vista agente](/docs/it/agent-view) mostra `Press enter again to restart this session fresh` sotto l'elenco invece, e un secondo `Enter` sulla riga riavvia la sessione con una conversazione vuota. Prima della v2.1.212, aprire la riga mostrava il messaggio di rifiuto senza modo di riavviare dalla vista agente. Prima della v2.1.211, aprire la sessione interrotta avviava silenziosamente quella conversazione vuota e poteva rieseguire il prompt originale della sessione.

3439

3440**Cosa fare:**

3441

3442* La conversazione che hai messo in background è intatta: riprendi con [`claude --resume`](/docs/it/sessions) o continua a lavorarci

3443* Per avviare la sessione interrotta da zero comunque, esegui `claude respawn <id>` con l'ID dal messaggio, o premi `Enter` due volte sulla sua riga nella vista agente

3444* Se la sessione ha finito una risposta e vedi ancora questo rifiuto su una versione prima della v2.1.214, una cartella illeggibile in `~/.claude/projects` potrebbe far sì che la scansione della trascrizione perda la conversazione salvata; aggiorna alla v2.1.214 o successiva, che tollera le cartelle illeggibili durante la scansione

3445

3446<h3 id="this-session-is-running-in-another-terminal">

3447 Questa sessione è in esecuzione in un altro terminale

3448</h3>

3449

3450Hai aperto la riga di una sessione interrotta nella [vista agente](/docs/it/agent-view), e la sua conversazione salvata è già aperta in un altro processo Claude Code attivo su questa macchina, quindi Claude Code rifiuta di avviare un secondo processo che scriverebbe sulla stessa trascrizione. Quale messaggio vedi dipende da [cosa tiene la conversazione](/docs/it/agent-view#opening-a-session-says-the-conversation-is-already-open):

3451

3452```text theme={null}

3453Can't open — this session is running in another terminal

3454This conversation is already open in another running Claude session — use that one, or close it and try again

3455```

3456

3457* **`running in another terminal`**: un terminale tiene la conversazione, ad esempio uno in cui l'hai ripresa con `claude --resume` o `/resume`. La riga mostra anche `Open in a terminal`.

3458* **`already open in another running Claude session`**: un altro processo Claude Code non interattivo la tiene, ad esempio un processo [sessione in background](/docs/it/agent-view#the-supervisor-process) per la stessa conversazione che non è ancora uscito.

3459

3460Claude Code salva una risposta che hai digitato quando apri la riga e la invia come il prossimo prompt della sessione quando la sessione si avvia di nuovo.

3461

3462**Cosa fare:**

3463

3464* Continua la conversazione nel processo che l'ha aperta, o esci da quel processo e apri di nuovo la riga

3465

3466Prima della v2.1.248, esisteva solo il rifiuto `already open in another running Claude session`: una conversazione ripresa in un terminale non contava come aperta, e aprire la riga avviava un secondo processo Claude Code che scriveva sulla stessa conversazione.

3467

3468<h3 id="this-sessions-saved-conversation-is-no-longer-on-disk">

3469 La conversazione salvata di questa sessione non è più su disco

3470</h3>

3471

3472Hai aperto una [sessione in background](/docs/it/agent-view) che è terminata mentre il servizio in background era spento, e la [pulizia della trascrizione](/docs/it/settings-reference#cleanupperioddays) ha da allora rimosso la sua conversazione salvata, ad esempio dopo che la macchina è stata spenta per settimane. Aprire una tale riga normalmente [riprende la sua conversazione salvata](/docs/it/agent-view#sessions-show-as-failed-after-shutdown). Non avendo nulla da riprendere, Claude Code rifiuta piuttosto che rieseguire il prompt originale della sessione senza chiedere:

3473

3474```text theme={null}

3475This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

3476```

3477

3478`claude attach <id>` stampa questo testo. Nella vista agente, il piè di pagina è più breve e termina con `ctrl+x deletes the row`.

3479

3480**Cosa fare:**

3481

3482* Esegui `claude rm <id>` per eliminare la riga. Quando uno dei [casi mantenuti](/docs/it/agent-view#what-deleting-a-session-removes) si applica, `claude rm` mantiene la riga e il worktree invece e nomina il motivo

3483* Per eseguire di nuovo il prompt originale della sessione come una conversazione fresca, esegui `claude respawn <id>`

3484

3485Prima della v2.1.248, aprire una tale riga rieseguiva il prompt originale della sessione invece di rifiutare, tirando un compito di settimane fa in primo piano.

3486

3487<h3 id="worktree-has-commits-that-are-not-pushed-anywhere">

3488 Worktree ha commit che non sono spinti da nessuna parte

3489</h3>

3490

3491Hai provato a eliminare una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) il cui worktree contiene commit che Claude Code non può confermare siano salvati altrove. Claude Code mantiene il worktree e la riga della sessione piuttosto che distruggere i commit senza vederli. `claude rm` nomina il ramo e i commit non spinti, e dice come procedere:

3492

3493```text theme={null}

3494kept 7c5dcf5d — 2 unpushed commits on claude/fix-login (a1b2c3d Fix login flow, … and 1 more)

3495 worktree: /home/you/project/.claude/worktrees/fix-login

3496 push them, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

3497```

3498

3499Quando Claude Code non può riassumere i commit, il messaggio legge `worktree has commits that are not pushed anywhere` invece. Nella [vista agente](/docs/it/agent-view), la riga della sessione mostra `not deleted` con lo stesso motivo.

3500

3501I commit su un remote non bloccano l'eliminazione. Nemmeno i commit sulla copia locale del ramo predefinito del tuo remote `origin`, purché quel ramo sia estratto nel tuo checkout principale, la directory del repository stesso piuttosto che un worktree.

3502

3503**Cosa fare:**

3504

3505* Per mantenere i commit, spingi il ramo del worktree, o uniscilo al ramo predefinito estratto nel tuo checkout principale, quindi elimina di nuovo la sessione

3506* Per scartare i commit, esegui il comando `claude rm <id> --discard-unpushed` che il messaggio ha stampato, o premi `Ctrl+X` due volte sulla riga della sessione nella vista agente di nuovo. Questo rimuove la sessione e il worktree insieme al suo ramo, ai commit non spinti e a qualsiasi modifica non committata. Se il worktree ha guadagnato un commit dal rifiuto, Claude Code lo mantiene di nuovo e mostra lo stato aggiornato

3507* Quando il messaggio dice che il worktree è anche registrato da un'altra sessione terminata, eliminare di nuovo non lo scarta: spingi i commit, quindi elimina di nuovo la sessione

3508

3509Prima della v2.1.260, il messaggio non nominava il ramo o i commit, e eliminare di nuovo era rifiutato allo stesso modo: eliminare la sessione senza spingere significava rimuovere il worktree tu stesso con `git worktree remove --force <path>`, quindi eseguire di nuovo `claude rm <id>`.

3510

3511Prima della v2.1.248, il ramo predefinito estratto nel tuo checkout principale non contava: un ramo che avevi già unito lì attivava ancora questo rifiuto fino a quando i suoi commit non raggiungevano un remote.

3512

3513<h3 id="terminal-host-process-died">

3514 Il processo host del terminale è morto

3515</h3>

3516

3517Ogni [terminale della sessione in background](/docs/it/agent-view) viene eseguito in un processo host sotto il servizio in background, e quel processo è morto mentre il servizio manteneva ancora la sua connessione, quindi la sessione non poteva essere raggiunta.

3518

3519Su Linux e WSL, il servizio in background controlla ogni processo host ogni pochi secondi, contrassegna la sessione come fallita quando il processo è uscito ma la sua connessione al servizio non si è mai chiusa, e mostra il motivo sulla sua riga nella [vista agente](/docs/it/agent-view#read-session-state):

3520

3521```text theme={null}

3522terminal host process died — press Enter to restart

3523```

3524

3525Se apri la riga prima che il controllo venga eseguito, il piè di pagina mostra `This session's terminal host process died (the conversation is saved) — press Enter to restart it` e la riga diventa fallita.

3526

3527Dalla shell, `claude attach <id>` riavvia una sessione già contrassegnata come fallita per un host morto, e altrimenti stampa il motivo e esce:

3528

3529```text theme={null}

3530Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

3531```

3532

3533La conversazione è salvata comunque.

3534

3535Una riga che esegue un [comando shell](/docs/it/agent-view#run-a-shell-command) invece mostra `terminal host process died — its output is gone; the command was not run again`, e `claude attach` stampa `This command's terminal host process died — its output is gone and the command was not run again`. Claude Code non riesegue mai il comando per te.

3536

3537**Cosa fare:**

3538

3539* Nella vista agente, premi `Enter` sulla riga fallita; la sessione si riavvia su un nuovo processo host e la conversazione riprende

3540* Dalla shell, esegui di nuovo `claude attach <id>`. Claude Code stampa `Session <id>'s terminal host died — restarting it on a fresh one…` e riapre la sessione

3541* Non puoi riavviare una riga di comando shell in questo modo; invia di nuovo il comando per rieseguirlo

3542

3543Prima della v2.1.247, un processo host morto poteva passare ogni controllo di vitalità che il servizio in background eseguiva, quindi aprire la sessione mostrava `opening… · esc to cancel` indefinitamente e `claude attach <id>` aspettava senza segnalare un errore.

3544

3545<h3 id="session-isnt-responding">

3546 La sessione non sta rispondendo

3547</h3>

3548

3549Hai aperto una [sessione in background](/docs/it/agent-view) e il servizio in background ha accettato l'apertura, ma nessun output è arrivato per circa dieci secondi, quindi Claude Code conclude che il processo che trasmette il terminale della sessione non può fornire output, e termina il tentativo invece di aspettare.

3550

3551Nella vista agente, Claude Code offre un riavvio nel piè di pagina:

3552

3553```text theme={null}

3554Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).

3555```

3556

3557Dalla shell, `claude attach <id>` stampa il motivo e esce:

991 3558

992```text theme={null}3559```text theme={null}

993Claude Opus is not available with the Claude Pro plan · Select a different model in /model3560Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).

994```3561```

995 3562

3563Claude Code non riavvia mai una riga che esegue un [comando shell](/docs/it/agent-view#run-a-shell-command) per te, perché un riavvio rieseguirebbe il comando.

3564

996**Cosa fare:**3565**Cosa fare:**

997 3566

998* Esegui `/model` e seleziona un modello che il tuo piano include3567* Nella vista agente, premi `Enter` sulla stessa riga di nuovo. Claude Code interrompe il processo che non risponde e riavvia la sessione, e la conversazione riprende. Nulla viene interrotto senza quella seconda pressione

999* Se hai aggiornato il tuo piano di recente e vedi ancora questo, esegui `/logout` quindi `/login`. Il token memorizzato riflette il tuo piano al momento dell'accesso, quindi l'aggiornamento sul web non ha effetto in una sessione esistente fino a quando non ti autentica di nuovo.3568* Dalla shell, esegui `claude stop <id>`, quindi `claude attach <id>`

1000* Vedi [claude.com/pricing](https://claude.com/pricing) per quali modelli ogni piano include3569* Per una riga di comando shell, premi `Ctrl+X` nella vista agente o esegui `claude stop <id>` per interromperla; invia di nuovo il comando per rieseguirlo

1001 3570

1002<h3 id="model-is-restricted-by-your-organizations-settings">3571<h3 id="session-was-stopped-while-the-respawn-was-in-flight">

1003 Il modello è limitato dalle impostazioni della tua organizzazione3572 La sessione è stata interrotta mentre il respawn era in volo

1004</h3>3573</h3>

1005 3574

1006L'amministratore della tua organizzazione ha disabilitato questo modello nella console di amministrazione di claude.ai, oppure è escluso da un elenco di autorizzazioni [`availableModels`](/docs/it/model-config#restrict-model-selection) nelle impostazioni gestite. Quando il modello limitato è stato impostato con `--model`, `ANTHROPIC_MODEL` o l'impostazione `model`, Claude Code sostituisce un modello consentito e continua. Digitare `/model <name>` per un modello limitato viene rifiutato con `Run /model to choose a different model.` e la sessione mantiene il suo modello attuale.3575Hai aperto una [sessione in background](/docs/it/agent-view) il cui processo non era in esecuzione, e mentre Claude Code la stava riavviando, un altro processo Claude Code l'ha interrotta, ad esempio `claude stop` in un altro terminale. Claude Code mantiene la sessione interrotta:

1007 3576

1008```text theme={null}3577```text theme={null}

1009Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.3578Session <id> was stopped while the respawn was in flight

1010```3579```

1011 3580

1012Claude Code tratta un alias della famiglia di modelli, uno di `opus`, `sonnet`, `haiku` o `fable`, come una richiesta per quella famiglia piuttosto che per la sua versione più recente. Sull'API Anthropic e su [Claude Platform on AWS](/docs/it/claude-platform-on-aws), un alias della famiglia limitata si risolve nella versione più recente della famiglia che la tua organizzazione e l'elenco di autorizzazioni `availableModels` consentono, e l'avviso di sostituzione nomina quella versione. Claude Code rifiuta `/model <alias>` solo quando ogni versione della famiglia è limitata. Prima di v2.1.205, un alias della famiglia veniva sostituito o rifiutato in base alla sua versione più recente sola, anche quando una versione precedente della stessa famiglia era consentita.3581Aprire una sessione che hai appena inviato, mentre il suo processo è ancora in avvio, aspetta il processo invece. Prima della v2.1.246, aprirla in quel momento poteva interromperla e mostrare questo messaggio.

1013 3582

1014**Cosa fare:**3583**Cosa fare:**

1015 3584

1016* Esegui `/model` per scegliere dai modelli che la tua organizzazione consente. I modelli limitati sono nascosti dal selettore.3585* Se non hai interrotto la sessione, apri di nuovo la sua riga nella vista agente o esegui `claude respawn <id>` per riavviarla

1017* Se il modello limitato è stato impostato in `--model`, `ANTHROPIC_MODEL` o il campo `model` di un file di impostazioni, rimuovi o aggiorna quel valore in modo che l'avviso non si ripeta ad ogni avvio3586* Se l'hai interrotta tu stesso, non rimane nulla da fare: la sessione rimane interrotta

1018* Se hai bisogno di accesso al modello limitato, chiedi all'amministratore della tua organizzazione di abilitarlo. Vedi [Restrizioni del modello dell'organizzazione](/docs/it/model-config#organization-model-restrictions).

1019 3587

1020<h3 id="thinking-type-enabled-is-not-supported-for-this-model">3588<h3 id="session-agent-no-longer-available">

1021 thinking.type.enabled non è supportato per questo modello3589 Agente della sessione non più disponibile

1022</h3>3590</h3>

1023 3591

1024La tua versione di Claude Code è più vecchia del minimo per Sonnet 5, Opus 4.8 o Opus 4.7. La CLI ha inviato una configurazione di thinking che il modello non accetta più.3592Hai ripreso una sessione che stava eseguendo un [agente personalizzato](/docs/it/sub-agents#invoke-subagents-explicitly), avviato con `--agent` o l'impostazione `agent`, e Claude Code non ha trovato un agente con quel nome. Cerca prima nella directory originale della sessione, quando hai [fiducia in quell'area di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust), quindi nella directory da cui riprendi. La sessione riprende comunque, ma con gli strumenti predefiniti, quindi le restrizioni dello strumento dell'agente non si applicano più:

1025 3593

1026```text theme={null}3594```text theme={null}

1027API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.3595This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

1028```3596```

1029 3597

3598L'avviso nomina solo le directory che Claude Code ha cercato, e appare nella conversazione ripresa sia che tu svegli una [sessione in background](/docs/it/agent-view), esegua `/resume` o `claude --resume`, o riprenda in [modalità non interattiva](/docs/it/headless), dove va anche a stderr. Le sessioni che usano `--input-format stream-json` non lo mostrano, perché l'Agent SDK fornisce agenti dopo l'avvio.

3599

3600Claude Code non salva il fallback nella sessione, quindi l'avviso si ripete ad ogni ripresa fino a quando non agisci. L'agente `claude` integrato non attiva l'avviso, poiché il fallback al set di strumenti predefinito non cambia nulla per esso. Prima della v2.1.216, Claude Code continuava silenziosamente come l'agente predefinito, e la ricerca copriva solo la directory da cui riprendevi, quindi un agente con ambito di progetto era perso ad ogni ripresa da un'altra directory.

3601

1030**Cosa fare:**3602**Cosa fare:**

1031 3603

1032* Esegui `claude update` e riavvia Claude Code. Opus 4.7 ha bisogno di v2.1.111 o successivo. Opus 4.8 ha bisogno di v2.1.154 o successivo. Sonnet 5 ha bisogno di v2.1.197 o successivo3604* Ricrea il file dell'agente in `.claude/agents/<name>.md` nel progetto della sessione, o in `~/.claude/agents/<name>.md` per un agente personale, quindi riprendi di nuovo

1033* Se non puoi aggiornare, esegui `/model` e seleziona Opus 4.6 o Sonnet 4.6 invece3605* Oppure riprendi con `--agent <name>` nominando un agente che esiste, per eseguire la sessione come quell'agente invece

1034* Se lo riscontri nell'[Agent SDK](/docs/it/agent-sdk/overview), aggiorna il pacchetto SDK invece. Opus 4.8 ha bisogno di TypeScript SDK v0.3.154 o successivo e Python SDK v0.2.88 o successivo. Sonnet 5 ha bisogno di TypeScript SDK v0.3.197 o successivo3606* Se l'agente ha ambito di progetto e non hai fiducia nella directory originale della sessione, esegui Claude Code lì una volta, accetta la finestra di dialogo di fiducia, quindi riprendi di nuovo

1035 3607

1036<h3 id="thinking-budget-exceeds-output-limit">3608<h3 id="claude_code_process_wrapper-launcher-errors">

1037 Il budget di thinking supera il limite di output3609 Errori del launcher CLAUDE\_CODE\_PROCESS\_WRAPPER

1038</h3>3610</h3>

1039 3611

1040Il budget di thinking esteso configurato supera la lunghezza massima della risposta, quindi non c'è spazio rimasto per la risposta effettiva.3612[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/it/corporate-launcher) è impostato, e il suo valore non può essere usato, quindi Claude Code rifiuta di avviare il processo interessato piuttosto che eseguirlo senza il launcher. I problemi di configurazione sono segnalati con un messaggio che inizia con il nome della variabile e dichiara il motivo, ad esempio:

1041 3613

1042```text theme={null}3614```text theme={null}

1043API Error: 400 ... max_tokens must be greater than thinking.budget_tokens3615CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

1044```3616```

1045 3617

1046Claude Code regola questi valori automaticamente sull'API Anthropic. Normalmente vedi questo errore su Amazon Bedrock o Google Cloud's Agent Platform quando [`MAX_THINKING_TOKENS`](/docs/it/env-vars) è impostato più alto del limite di output del provider, o quando la modalità piano aumenta il budget di thinking.3618Un launcher che si avvia ma esce senza sostituirsi con Claude Code fallisce la sessione che stava avviando, e la riga della sessione nella vista agente riporta che il launcher `must exec, not daemonize`, seguito da qualsiasi cosa il launcher abbia stampato. Una sessione che non può avviarsi o raggiungere il servizio in background a causa del launcher riporta il problema del launcher come motivo all'interno di `Couldn't reach the background service (...)`.

1047 3619

1048**Cosa fare:**3620**Cosa fare:**

1049 3621

1050* Abbassa `MAX_THINKING_TOKENS`, oppure aumenta [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/it/env-vars) al di sopra del budget di thinking3622* Imposta la variabile al percorso assoluto di un eseguibile che termina chiamando `exec "$@"`. Vedi [il contratto del launcher](/docs/it/corporate-launcher#the-launcher-contract) per il contratto completo

1051* Vedi [Extended thinking](/docs/it/model-config#extended-thinking) per come il budget interagisce con la lunghezza dell'output3623* Controlla `/status`, che mostra il comando di avvio risolto nella sua voce Self-exec e avverte quando il servizio in background in esecuzione non corrisponde, o esegui `claude daemon status` da una shell

3624* Dopo aver corretto il valore nel blocco `env` delle [impostazioni](/docs/it/corporate-launcher#set-up-the-launcher), riavvia il servizio in background con `claude daemon stop --any` in modo che il prossimo invio avvii uno avvolto

1052 3625

1053<h3 id="tool-use-or-thinking-block-mismatch">3626<h3 id="eunknown-when-starting-a-background-session">

1054 Mancata corrispondenza tra l'uso dello strumento o il blocco di thinking3627 EUNKNOWN quando si avvia una sessione in background

1055</h3>3628</h3>

1056 3629

1057La cronologia della conversazione ha raggiunto l'API in uno stato incoerente, di solito dopo che una chiamata di strumento è stata interrotta o un turno è stato modificato a metà flusso.3630Windows ha rifiutato di avviare un programma con un codice di errore che non ha un nome standard, quindi l'errore emerge come `EUNKNOWN`. Il trigger solito è una politica di restrizione del software, come Group Policy o AppLocker, che blocca il programma in fase di avvio. L'errore appare quando avvii una [sessione in background](/docs/it/agent-view) con `/background` o `claude --bg`:

1058 3631

1059```text theme={null}3632```text theme={null}

1060API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.3633Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

1061API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks

1062API Error: 400 ... thinking blocks ... cannot be modified

1063```3634```

1064 3635

1065Tutte e tre le varianti significano la stessa cosa: la sequenza di blocchi `tool_use`, `tool_result` e `thinking` nella cronologia non corrisponde più a ciò che l'API si aspetta.3636Su alcuni account il messaggio dice `daemon` al posto di `background service`.

3637

3638Su un'installazione npm, un `EUNKNOWN` che appare mentre `npm install -g @anthropic-ai/claude-code` sta sostituendo il binario ha la stessa causa di [`EACCES` durante una reinstallazione](#eacces-when-starting-a-background-session) e si cancella quando riprovi dopo che l'installazione finisce.

3639

3640Claude Code avvia il servizio in background attraverso PowerShell in modo che il servizio sopravviva alla chiusura del terminale, usando PowerShell 7 quando è installato e Windows PowerShell 5.1 altrimenti. Quando nessun PowerShell può essere eseguito, Claude Code avvia il servizio direttamente invece, quindi una politica che blocca solo PowerShell non causa questo errore. Se lo vedi mentre nessun npm install è in esecuzione, la politica sta bloccando l'eseguibile Claude Code stesso.

3641

3642Prima della v2.1.212, Claude Code usava solo Windows PowerShell 5.1 per avviare il servizio, quindi qualsiasi macchina dove Group Policy bloccava PowerShell 5.1 falliva con `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`, anche con PowerShell 7 installato.

1066 3643

1067**Cosa fare:**3644**Cosa fare:**

1068 3645

1069* Se stai utilizzando Opus 4.7 o Opus 4.8, esegui prima `claude update`. Le versioni precedenti a v2.1.156 possono attivare questo errore durante l'uso normale dello strumento, e `/rewind` non lo cancella.3646* Se il messaggio legge `Couldn't start the session`, aggiorna alla v2.1.212 o successiva. Su versioni precedenti puoi anche eseguire `claude daemon run` in un terminale separato per primo, quindi avviare di nuovo la sessione in background. Quel comando esegue il servizio in background in primo piano del terminale, quindi il servizio dura solo finché quel terminale rimane aperto.

1070* Esegui `/rewind`, o premi Esc due volte, per tornare indietro a un checkpoint prima del turno corrotto e continua da lì. Vedi [Checkpointing](/docs/it/checkpointing) per come i checkpoint vengono creati e ripristinati.3647* Se un npm install stava sostituendo il binario, aspetta che finisca, quindi avvia di nuovo la sessione in background

3648* Se l'errore appare su v2.1.212 o successiva mentre nessun npm install è in esecuzione, chiedi al tuo amministratore Windows di consentire l'eseguibile Claude Code nella politica di restrizione

3649* Se il servizio in background si interrompe quando chiudi il terminale, Claude Code l'ha avviato senza PowerShell. Installa PowerShell 7, o chiedi al tuo amministratore di sbloccare PowerShell, in modo che il servizio possa sopravvivere al terminale.

1071 3650

1072<h3 id="usage-policy-refusal">3651<h3 id="eacces-when-starting-a-background-session">

1073 Rifiuto della politica di utilizzo3652 EACCES quando si avvia una sessione in background

1074</h3>3653</h3>

1075 3654

1076L'API ha rifiutato di rispondere perché il contenuto nella conversazione ha attivato un controllo della [Politica di utilizzo](https://www.anthropic.com/legal/aup). Il messaggio include un ID di richiesta che puoi citare al supporto se ritieni che il rifiuto sia errato.3655Claude Code non poteva eseguire il suo stesso binario per avviare il [servizio in background](/docs/it/agent-view#the-supervisor-process) che ospita le sessioni in background. Su un'installazione npm, questo di solito significa che `npm install -g @anthropic-ai/claude-code` stava sostituendo il binario in quel momento, sia che l'abbia eseguito tu che l'[auto-updater](/docs/it/setup#auto-updates). L'errore appare quando apri una sessione dalla [vista agente](/docs/it/agent-view):

1077 3656

1078```text theme={null}3657```text theme={null}

1079API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.3658Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

1080```3659```

1081 3660

1082Il controllo valuta la conversazione completa, non solo il tuo prompt più recente, quindi inviare un nuovo messaggio nella stessa sessione di solito riattiva lo stesso rifiuto. Lo stesso vale dopo l'uscita e la riapertura della sessione con `--continue` o `--resume`, poiché la trascrizione su disco contiene ancora il contenuto che attiva il controllo. Su [Amazon Bedrock](/docs/it/amazon-bedrock), [Google Cloud's Agent Platform](/docs/it/google-vertex-ai) e [Microsoft Foundry](/docs/it/microsoft-foundry), questo messaggio copre anche le richieste che le misure di sicurezza del modello hanno contrassegnato come un argomento di cibersicurezza. Vedi [Le misure di sicurezza hanno contrassegnato un argomento di cibersicurezza](#safety-measures-flagged-a-cybersecurity-topic).3661Quando avvii una sessione con `/background` o `claude --bg`, lo stesso motivo appare all'interno di `Couldn't reach the background service (...)`. Durante la stessa finestra di reinstallazione l'errore può nominare un altro codice invece, come `ENOENT` o `ENOEXEC`, o `EUNKNOWN` o `EPERM` su Windows; un `EUNKNOWN` che persiste attraverso i tentativi ha una [causa diversa](#eunknown-when-starting-a-background-session).

3662

3663Su un'installazione npm, Claude Code aspetta che la reinstallazione finisca e riprova da solo: fino a dieci secondi, e fino a due minuti mentre un npm install di Claude Code è visibilmente ancora in esecuzione sulla macchina, che copre un altro processo Claude Code che scarica un aggiornamento. Quando l'installazione dura più di quella attesa, l'errore nomina l'aggiornamento invece del codice di errore nudo:

3664

3665```text theme={null}

3666Claude Code is being updated by npm on this machine (still not runnable after 2 min, EACCES) — try again when the update finishes

3667```

3668

3669Prima della v2.1.257, l'attesa si fermava a dieci secondi in ogni caso, quindi questo errore appariva mentre un altro processo Claude Code stava ancora scaricando un aggiornamento. Prima della v2.1.246, Claude Code falliva subito, senza aspettare.

1083 3670

1084**Cosa fare:**3671**Cosa fare:**

1085 3672

1086* Premi Esc due volte o esegui `/rewind` per tornare indietro a un checkpoint prima del turno che ha attivato il rifiuto, quindi riformula o prendi un approccio diverso. Vedi [Checkpointing](/docs/it/checkpointing).3673* Aspetta alcuni secondi, quindi apri di nuovo la sessione o invia di nuovo. Quando il messaggio dice che Claude Code è in fase di aggiornamento, riprova dopo che l'aggiornamento finisce.

1087* Se non riesci a identificare quale turno l'ha causato, esegui `/clear` per avviare una conversazione nuova nello stesso progetto. La tua conversazione precedente viene preservata su disco e rimane disponibile in `/resume`.3674* Se l'errore persiste mentre nessun npm install è in esecuzione, il tuo utente non può eseguire il binario installato. Controlla i suoi permessi e quelli della sua directory, o reinstalla Claude Code.

1088* In [modalità non interattiva](/docs/it/headless) (`-p`), dove il rewind non è disponibile, riprova con un prompt riformulato in una sessione nuova senza `--continue`. I controlli delle politiche variano in base al modello, quindi passare a un modello diverso con `--model` può anche risolvere il rifiuto in alcuni casi.

1089 3675

1090<h3 id="safety-measures-flagged-a-cybersecurity-topic">3676<h3 id="background-service-exited-before-it-became-reachable">

1091 Le misure di sicurezza hanno contrassegnato un argomento di cibersicurezza3677 Il servizio in background è uscito prima di diventare raggiungibile

1092</h3>3678</h3>

1093 3679

1094Le misure di sicurezza del modello hanno contrassegnato il contenuto nella conversazione come un argomento di cibersicurezza. Il messaggio nomina il modello che ha contrassegnato la richiesta:3680Il processo che Claude Code ha avviato come [servizio in background](/docs/it/agent-view#the-supervisor-process) è uscito prima di accettare connessioni, quindi Claude Code non poteva aprire la tua sessione. Quando il servizio ha stampato un errore prima di uscire, il motivo tra parentesi fornisce il codice di uscita o il segnale e la prima riga che il servizio ha stampato, che nomina cosa l'ha fermato:

1095 3681

1096```text theme={null}3682```text theme={null}

1097API Error: Opus 4.8 has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude.3683Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

~~1098~~

1099If you were not engaging in a cybersecurity topic, please send feedback via /feedback.

1100```3684```

1101 3685

1102Il messaggio si collega al [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude), che concede l'accesso per il lavoro di cibersicurezza legittimo. La salvaguardia stessa è lato server e precede v2.1.203; questa versione ha cambiato solo la formulazione del messaggio e la pagina a cui si collega.3686Quando apri una sessione dalla [vista agente](/docs/it/agent-view), lo stesso motivo segue `Couldn't start the background service —`. Quando il servizio non ha stampato nulla prima di uscire, il messaggio dice `nothing on stderr` invece.

1103 3687

1104Quello che vedi dipende dal tuo provider e dalla modalità:3688Claude Code riporta l'errore con la riga di errore del servizio. Prima della v2.1.246, l'errore emergeva solo dopo un'attesa di 45 secondi, come `background service did not become reachable within 45s`, senza la riga di errore del servizio.

1105 3689

1106* Su [Amazon Bedrock](/docs/it/amazon-bedrock), [Google Cloud's Agent Platform](/docs/it/google-vertex-ai) e [Microsoft Foundry](/docs/it/microsoft-foundry), un flag di cibersicurezza produce il messaggio di [rifiuto della politica di utilizzo](#usage-policy-refusal) invece.3690Due motivi citati hanno cause note:

1107* [La modalità non interattiva](/docs/it/headless) omette la frase `/feedback`.

1108 3691

1109Prima di v2.1.203, il messaggio leggeva `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` seguito da un link del modulo di esenzione.3692* `Error: claude native binary not installed.`: un npm install stava sostituendo il binario Claude Code in quel momento, quindi il servizio ha eseguito il placeholder di npm invece. Riprova dopo che l'installazione finisce; se la riga persiste senza nessun install in esecuzione, [completa l'npm install](/docs/it/troubleshoot-install#native-binary-not-found-after-npm-install). Prima della v2.1.257, un auto-aggiornamento npm di macOS ha prodotto questo errore ad ogni avvio durante la finestra di installazione.

3693* `nothing on stderr` con codice di uscita 1, ad ogni avvio, su Windows: `daemon.lock` nomina un processo che Claude Code non può né segnalare né provare sia andato, quindi ogni nuovo servizio conclude che un altro lo tiene e esce. Un lock il cui scrittore Claude Code può provare sia andato viene sostituito da solo e non produce questo errore. Quando l'errore si ripete ad ogni avvio, elimina `~/.claude/daemon.lock`, quindi apri di nuovo la sessione o invia di nuovo. Prima della v2.1.257, tale lock bloccava ogni avvio fino a quando non eliminavi il file.

1110 3694

1111**Cosa fare:**3695**Cosa fare:**

1112 3696

1113* Se il tuo lavoro richiede questo contenuto, richiedi l'accesso tramite il [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)3697* Se il messaggio cita una riga, correggi quello che nomina, quindi apri di nuovo la sessione o invia di nuovo. Il prossimo tentativo avvia di nuovo il servizio

1114* Se la tua richiesta non riguardava un argomento di cibersicurezza, esegui `/feedback` per segnalare il falso positivo3698* Esegui `claude daemon status` per controllare se un servizio è in esecuzione ora

1115* Per continuare a lavorare nella stessa sessione, premi Esc due volte o esegui `/rewind` per tornare indietro a un checkpoint prima del turno che ha attivato il flag, quindi prendi un approccio diverso. Vedi [Checkpointing](/docs/it/checkpointing).

1116 3699

1117<h2 id="installation-errors">3700<h3 id="working-directory-no-longer-exists-when-starting-a-background-session">

1118 Errori di installazione3701 La directory di lavoro non esiste più quando si avvia una sessione in background

3702</h3>

3703

3704Hai provato ad avviare una [sessione in background](/docs/it/agent-view) in una directory che non esiste più. Questo accade quando invii dalla vista agente o esegui `/background` dopo che la directory in cui stavi lavorando è stata eliminata o spostata. Accade anche quando ti colleghi a o riavvii una sessione il cui processo è uscito e la cui directory è scomparsa, perché il nuovo processo si avvierebbe in quella stessa directory. Claude Code non avvia la sessione, e il messaggio nomina la directory mancante:

3705

3706```text theme={null}

3707Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

3708```

3709

3710Prima della v2.1.257, la sessione sembrava avviarsi e poi mostrava nella vista agente come una riga fallita con lo stesso motivo.

3711

3712**Cosa fare:**

3713

3714* Ricrea la directory che il messaggio nomina, o invia da una directory che esiste, quindi riprova

3715

3716<h2 id="wrapper-and-ide-errors">

3717 Errori del wrapper e dell'IDE

1119</h2>3718</h2>

1120 3719

1121Questi errori compaiono durante l'installazione o l'aggiornamento di Claude Code, dallo [script di installazione](/docs/it/setup#install-claude-code), `claude install`, o `claude update`. Per i problemi di `command not found`, PATH, permessi e TLS durante la configurazione, vedere [Risoluzione dei problemi di installazione e accesso](/docs/it/troubleshoot-install).3720Questi errori provengono dal programma che ha avviato Claude Code per voi, come un'estensione IDE o un'applicazione [Agent SDK](/docs/it/agent-sdk/overview), piuttosto che da Claude Code stesso.

1122 3721

1123<h3 id="installation-was-killed-before-it-could-finish">3722<h3 id="claude-code-process-exited-with-code-n">

1124 L'installazione è stata interrotta prima di poter terminare3723 Il processo Claude Code è uscito con codice N

1125</h3>3724</h3>

1126 3725

1127Lo script di installazione segnala quando il passaggio `claude install` viene terminato da un segnale. Su Linux, il codice di uscita 137 significa che il processo ha ricevuto SIGKILL, e su un host con poca memoria è solitamente il killer out-of-memory (OOM) del kernel. Lo script stampa questa spiegazione ed esce con il codice 137:3726Il processo `claude` sottostante è uscito con un codice diverso da zero. Il codice di uscita da solo non dice cosa è fallito: l'errore reale si trova nell'output del processo stesso, che il wrapper allega quando lo ha catturato e altrimenti mantiene nei suoi log.

1128 3727

1129```text theme={null}3728```text theme={null}

1130Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.3729Error: Claude Code process exited with code 1

1131Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

1132```3730```

1133 3731

1134Per qualsiasi altro segnale fatale, e per il codice di uscita 137 su macOS, lo script stampa `Installation was killed before it could finish (exit code <N>)` con il codice di uscita effettivo e omette la spiegazione dell'esaurimento della memoria. Il messaggio proviene dallo script di installazione che macOS e Linux utilizzano, che copre anche le installazioni all'interno di WSL; gli script di installazione nativi di Windows non lo stampano mai. Prima della v2.1.200, lo script usciva con solo la riga `Killed` della shell.3732**Cosa fare:**

3733

3734* In VS Code, seguite il collegamento **View output logs** mostrato con l'errore per vedere il guasto sottostante

3735* In un'applicazione Agent SDK, catturate l'errore intorno al vostro ciclo di messaggi. Le voci sotto [CLI process exit](/docs/it/agent-sdk/troubleshooting#cli-process-exit) coprono ciò che il vostro codice riceve in ogni linguaggio SDK.

3736* Eseguite `claude` in un terminale nello stesso progetto. Il guasto di solito si riproduce lì con il suo messaggio di errore reale, che potete quindi cercare su questa pagina.

3737* Eseguite `claude doctor` in un terminale per verificare l'installazione e la configurazione

3738

3739<h3 id="could-not-locate-the-claude-cli-on-path">

3740 Could not locate the Claude CLI on PATH

3741</h3>

3742

3743L'[estensione VS Code](/docs/it/vs-code) mostra questo errore su Windows quando aprite Claude Code nel terminale integrato, la shell del terminale è PowerShell e l'estensione non riesce a trovare l'eseguibile `claude` installato su PATH. L'estensione si rifiuta di avviare Claude Code finché non trova il `claude` installato su PATH.

3744

3745```text theme={null}

3746Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

3747```

1135 3748

1136**Cosa fare:**3749**Cosa fare:**

1137 3750

1138* Interrompere altri processi per liberare memoria, quindi eseguire nuovamente il programma di installazione3751* Aprite una nuova finestra PowerShell al di fuori di VS Code ed eseguite `where.exe claude`. Se non stampa un percorso, la CLI non è su PATH: aggiungete la sua directory di installazione seguendo [Verify your PATH](/docs/it/troubleshoot-install#verify-your-path). Se stampa un percorso, la voce proviene dal vostro profilo PowerShell o da una modifica di PATH che VS Code non ha ancora raccolto; i prossimi due passaggi coprono questi casi.

1139* Aggiungere spazio di swap o passare a un'istanza più grande. Vedere [Installazione interrotta su server Linux con poca memoria](/docs/it/troubleshoot-install#install-killed-on-low-memory-linux-servers) per i comandi del file di swap.3752* Impostate la voce PATH come variabile di ambiente utente o di sistema, non nel vostro profilo PowerShell. L'estensione non esegue il vostro profilo, quindi una modifica di PATH che vive solo lì non la raggiunge mai.

3753* Riavviate VS Code dopo aver modificato PATH. L'estensione controlla il PATH che VS Code ha catturato all'avvio, quindi una modifica di PATH ha effetto solo dopo un riavvio.

1140 3754

1141<h3 id="the-connection-dropped-while-downloading-the-update">3755<h2 id="rewind-warnings-and-errors">

1142 La connessione è stata interrotta durante il download dell'aggiornamento3756 Avvisi e errori di Rewind

3757</h2>

3758

3759Questi messaggi provengono da un ripristino del codice [`/rewind`](/docs/it/checkpointing). `Restored the code, but skipped N files` è un avviso che indica che Claude Code ha saltato alcuni percorsi. `No files were restored` è un errore che significa che non ha ripristinato nulla.

3760

3761<h3 id="restored-the-code-but-skipped-files">

3762 Restored the code, but skipped files

1143</h3>3763</h3>

1144 3764

1145La connessione al server di download si è chiusa mentre `claude install`, `claude update`, o l'[aggiornatore automatico](/docs/it/setup#auto-updates) stava scaricando il binario di Claude Code, e i tentativi di ripetizione non hanno recuperato. Claude Code ritenta il download quando la connessione si interrompe, il trasferimento si blocca, o il file scaricato non supera il checksum, fino a tre tentativi in totale. Un errore HTTP completato, come un 404, non viene ritentato perché il server ha già risposto. Prima della v2.1.202, una singola connessione interrotta faceva fallire il download immediatamente con il semplice errore `aborted` invece di ritentare.3765Un ripristino del codice `/rewind` ha saltato uno o più percorsi tracciati invece di scrivere o eliminare attraverso di essi. Claude Code salta un percorso quando:

3766

3767* è, o è diventato, un symlink, hard link, o altro file non regolare

3768* la sua directory è cambiata dal checkpoint

3769* il suo backup non può essere letto in modo sicuro

3770

3771I percorsi saltati mantengono i loro contenuti attuali. Prima della v2.1.216, `/rewind` scriveva e eliminava attraverso i link nei percorsi tracciati e non segnalava un ripristino parziale.

1146 3772

1147```text theme={null}3773```text theme={null}

1148The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.3774Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file, its directory changed since the checkpoint, or its backup could not be safely read. Skipped files were left untouched — run with --debug for the paths.

1149```3775```

1150 3776

1151Il testo tra parentesi nomina quale tentativo ha fallito e l'errore di rete sottostante. `claude update` precede il messaggio con `Error: Failed to install native update` su stderr.3777**Cosa fare:**

1152 3778

1153Un download che rimane connesso ma non termina entro 10 minuti fallisce con `Download timed out: exceeded the total deadline` invece. Claude Code non ritenta un download scaduto, perché una connessione troppo lenta per terminare entro la scadenza non terminerà nemmeno su un tentativo immediato di ripetizione. I passaggi seguenti si applicano a entrambi i messaggi. Prima della v2.1.205, la stessa scadenza di 10 minuti era segnalata come il generico `timeout of 600000ms exceeded` del client HTTP.3779* Identificare quali file sono stati saltati in modo da poter gestire ognuno con i passaggi seguenti. Il messaggio fornisce solo un conteggio; il log di debug in `~/.claude/debug/<session-id>.txt` nomina ogni percorso saltato mentre il ripristino viene eseguito, quindi attivare la registrazione di debug con `/debug` prima del prossimo ripristino. Su macOS o Linux, è possibile invece trovare i link direttamente: `find . -type l` per i symlink e `find . -type f -links +1` per i file con hard link.

3780* Se un file saltato è un link che hai creato intenzionalmente, come un file di configurazione gestito da un gestore dotfile o un file con hard link da strumenti come pnpm, il rewind ha lasciato i suoi contenuti intatti. Per annullare le modifiche della sessione ad esso, chiedi a Claude di invertire la modifica o modifica il file tu stesso

3781* Se non hai creato il link, ispeziona il percorso prima di fidarti dei suoi contenuti: qualcosa ha sostituito il file dopo il checkpoint

1154 3782

1155La causa più comune è un proxy o un gateway che chiude un trasferimento lungo prima che termini. Il binario di Claude Code è un download di grandi dimensioni, quindi un limite di connessione proxy che non influisce mai sul traffico API normale può comunque interromperlo.3783<h3 id="no-files-were-restored">

3784 No files were restored

3785</h3>

3786

3787Claude Code mostra questo messaggio quando ripristini il codice con [`/rewind`](/docs/it/checkpointing) e non riesce a ripristinare nessuno dei file in quel checkpoint. Per ogni file, il backup che Claude Code ha salvato prima di modificarlo è mancante, oppure Claude Code non ha potuto scrivere o eliminare il file.

3788

3789```text theme={null}

3790Failed to restore the code:

3791No files were restored: 1 file failed (backup missing, or the file could not be updated)

3792```

3793

3794Claude Code elimina i backup di una sessione nella [retention sweep](/docs/it/claude-directory#cleaned-up-automatically), per impostazione predefinita circa 30 giorni dopo l'ultimo salvataggio della sessione. Se riprendi una sessione dopo questo periodo, `/rewind` elenca ancora i suoi checkpoint, ma il ripristino a uno di essi può fallire con questo errore. Se il messaggio dice anche `N paths were skipped for link safety`, vedi [Restored the code, but skipped files](#restored-the-code-but-skipped-files) per quei percorsi.

1156 3795

1157**Cosa fare:**3796**Cosa fare:**

1158 3797

1159* Eseguire `claude update` di nuovo. Su una rete altrimenti sana, il download di solito ha successo alla prossima esecuzione. Per il messaggio di timeout, eseguirlo di nuovo da una rete più veloce o meno limitata.3798* Annulla le modifiche in un altro modo: chiedi a Claude di invertire le sue modifiche, o ripristina i file dal controllo versione. Quando i backup sono spariti, l'esecuzione di `/rewind` di nuovo fallisce allo stesso modo.

1160* Se la rete richiede un proxy, impostare `HTTPS_PROXY` prima di eseguire il programma di installazione o `claude update`. Vedere [Verificare la connettività di rete](/docs/it/troubleshoot-install#check-network-connectivity).3799* Se Claude Code non ha potuto scrivere o eliminare un file, correggi ciò che blocca la scrittura, come i permessi dei file, quindi esegui `/rewind` di nuovo.

1161* Se un proxy aziendale continua a chiudere il trasferimento, chiedere al team di rete di consentire il download completo da `downloads.claude.ai`. Vedere [Requisiti di accesso alla rete](/docs/it/network-config#network-access-requirements).3800* Per mantenere i backup più a lungo nelle sessioni future, aumenta [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays).

1162* Eseguire `claude doctor` dalla shell per la diagnostica dell'installazione

1163 3801

1164<h2 id="command-line-errors">3802Prima della v2.1.260, Claude Code saltava silenziosamente i file i cui backup erano mancanti, e il rewind sembrava avere successo.

1165 Errori da riga di comando3803

3804<h2 id="session-saving-warnings">

3805 Avvisi di salvataggio della sessione

1166</h2>3806</h2>

1167 3807

1168Questi errori provengono dal comando `claude` da riga di comando e dai suoi sottocomandi. Claude Code li stampa prima di eseguire il vostro prompt o di inviare qualsiasi richiesta API.3808Claude Code mostra questi avvisi su una riga persistente sotto la casella di input quando non sta salvando la trascrizione della sessione. La sessione continua a funzionare comunque; gli avvisi indicano che la sessione potrebbe mancare da [`--resume`](/docs/it/sessions) in seguito.

1169 3809

1170<h3 id="conflict-between-bg-and-print">3810<h3 id="transcript-writes-are-failing">

1171 Conflitto tra --bg e --print3811 I salvataggi della trascrizione stanno fallendo

1172</h3>3812</h3>

1173 3813

1174Questo messaggio richiede Claude Code v2.1.198 o successivo. Avete combinato `--bg` con `-p` o `--print` nella stessa invocazione di `claude`. `--bg` avvia una [sessione in background](/docs/it/agent-view#from-your-shell) a cui vi collegherete successivamente con `claude agents`, mentre `--print` esegue [in modo non interattivo](/docs/it/headless) e non avvia mai la sessione interattiva a cui `claude agents` si collega. Prima della v2.1.198 questa combinazione creava silenziosamente un job in background che non poteva mai essere collegato.3814Claude Code salva la trascrizione su disco mentre lavori, e i suoi salvataggi nel [file della trascrizione](/docs/it/sessions#where-transcripts-are-stored) stanno fallendo. Il messaggio nomina la causa con il codice di errore sottostante, ad esempio un disco pieno:

1175 3815

1176```text theme={null}3816```text theme={null}

3817Transcript writes are failing (disk full — ENOSPC) · recent messages may not be saved for resume

1177```3818```

1178 3819

3820L'avviso appare in diversi punti a seconda dell'errore:

3821

3822* Al primo fallimento per condizioni che non si risolvono da sole: un disco pieno, un quota disco superata, un filesystem di sola lettura, un percorso che supera il limite di lunghezza del filesystem, o, su macOS e Linux, un errore di permesso

3823* Dopo fallimenti ripetuti che durano almeno un minuto per tutto il resto, inclusi errori di permesso su Windows, dove una scansione antivirus può far fallire un singolo salvataggio che poi riesce al nuovo tentativo

3824

3825Prima della v2.1.217, Claude Code scartava i salvataggi falliti senza un avviso, e un successivo `--resume` mancante di messaggi recenti era il primo segno.

3826

1179**Cosa fare:**3827**Cosa fare:**

1180 3828

1181* Eliminate `-p` o `--print`. `--bg` accetta il prompt come argomento posizionale, quindi `claude --bg "<task>"` è il comando completo. Vedere [Dispatch new agents from your shell](/docs/it/agent-view#from-your-shell).3829* Correggere la condizione che il codice di errore nomina: liberare spazio su disco per `ENOSPC`; aumentare o cancellare la quota per `EDQUOT`; ripristinare l'accesso in scrittura alla posizione della trascrizione per `EACCES`, `EPERM`, o `EROFS`

1182* Per eseguire il prompt in modo non interattivo e stampare il risultato invece di creare una sessione in background, eliminate `--bg` ed eseguite `claude -p "<task>"`3830* L'avviso si cancella da solo al prossimo salvataggio riuscito; non è necessario riavviare

3831* I messaggi inviati mentre l'avviso era visualizzato potrebbero comunque mancare quando riprendi la sessione in seguito

1183 3832

1184<h3 id="the-json-schema-value-is-not-a-valid-json-schema">3833<h3 id="transcript-saving-is-off-skip-prompt-history">

1185 Il valore di --json-schema non è uno schema JSON valido3834 Il salvataggio della trascrizione è disattivato perché CLAUDE\_CODE\_SKIP\_PROMPT\_HISTORY è impostato

1186</h3>3835</h3>

1187 3836

1188Lo schema che avete passato a [`--json-schema`](/docs/it/cli-reference#cli-flags) in [modalità non interattiva](/docs/it/headless#get-structured-output) non ha superato la compilazione dello schema JSON, quindi `claude` esce con codice 1 invece di eseguire il prompt. Prima della v2.1.205, uno schema non valido produceva output non strutturato senza errore, e qualsiasi schema che utilizzava la parola chiave `format` era trattato come non valido.3837Questa sessione è stata avviata con [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/it/env-vars) impostato, quindi Claude Code non scrive alcuna trascrizione o cronologia dei prompt per essa:

1189 3838

1190```text theme={null}3839```text theme={null}

1191Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values3840Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set · --resume will not find this session; if unintended, unset it and restart

1192```3841```

1193 3842

1194Il testo dopo il secondo due punti è la diagnostica del validatore e nomina la parola chiave o la posizione che non ha superato il controllo. Gli schemi che utilizzano la parola chiave `format`, come `"format": "email"`, sono validi: Claude Code accetta `format` come annotazione e non la applica.3843La variabile è un'esclusione intenzionale per sessioni script effimere, ma può anche raggiungere una sessione attraverso un profilo shell, uno script wrapper, o un processo padre che l'ha esportata.

~~1195~~

1196Claude Code esegue due controlli prima della compilazione dello schema: rifiuta un valore che non è JSON analizzabile con `Error: --json-schema is not valid JSON`, e JSON valido che non è un oggetto con `Error: --json-schema must be a JSON object`.

1197 3844

1198**Cosa fare:**3845**Cosa fare:**

1199 3846

1200* Correggete la parte dello schema che la diagnostica nomina, quindi rieseguite il comando3847* Se hai impostato la variabile di proposito, non è necessaria alcuna azione; l'avviso conferma che la sessione non apparirà in `--resume`, `--continue`, o nella cronologia della freccia su

1201* Se la diagnostica è `schema too large`, riducete l'annidamento dello schema e il riutilizzo di `$ref`3848* Se non l'hai fatto, rimuovi la variabile dalla shell o dallo script che avvia `claude`, quindi avvia una nuova sessione. I messaggi della sessione corrente non vengono salvati retroattivamente.

1202* Vedere [Get structured output](/docs/it/headless#get-structured-output) per uno schema e un comando funzionanti

1203 3849

1204<h3 id="could-not-import-a-server-from-claude-desktop">3850<h3 id="transcript-saving-is-off-child-session-marker">

1205 Impossibile importare un server da Claude Desktop3851 Il salvataggio della trascrizione è disattivato a causa di un marcatore CLAUDE\_CODE\_CHILD\_SESSION ereditato

1206</h3>3852</h3>

1207 3853

1208Claude Code non ha potuto aggiungere uno dei server che avete selezionato in `claude mcp add-from-claude-desktop`. Il comando importa comunque gli altri server selezionati e stampa una riga per ogni server che non ha potuto aggiungere. Prima della v2.1.205, il primo server che non riusciva fermava l'importazione e nessuno dei server selezionati veniva aggiunto.3854Claude Code imposta [`CLAUDE_CODE_CHILD_SESSION`](/docs/it/env-vars) nei sottoprocessi che genera, e tratta una sessione interattiva che lo eredita come annidata: Claude Code non salva alcuna trascrizione per essa, quindi le sessioni che Claude stesso avvia non riempiono il tuo elenco `--resume`. Questo avviso significa che la tua sessione corrente ha ereditato il marcatore:

1209 3855

1210```text theme={null}3856```text theme={null}

1211Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3857Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts

1212```3858```

1213 3859

1214Il testo dopo il nome del server è il motivo. Il più comune è il controllo del nome: Claude Desktop consente caratteri nei nomi dei server, come spazi e punti, che `claude mcp` limita a lettere, numeri, trattini e sottolineature. Altri motivi includono una configurazione del server che non supera la convalida e un server bloccato dalla [politica MCP](/docs/it/managed-mcp) della vostra organizzazione.3860L'avviso è previsto quando hai eseguito `claude` dall'interno di un'altra sessione Claude Code; segnala una classificazione errata quando il marcatore è trapelato attraverso un intermediario di lunga durata, ad esempio un terminale, una sessione `screen`, o un launcher che una sessione Claude Code ha originariamente avviato.

3861

3862All'interno di tmux, Claude Code rileva un marcatore che è arrivato attraverso l'ambiente globale del server tmux e continua a salvare, quindi questo avviso non appare per quel caso.

1215 3863

1216**Cosa fare:**3864**Cosa fare:**

1217 3865

1218* Rinominate il server in `claude_desktop_config.json` per utilizzare solo lettere, numeri, trattini e sottolineature, quindi eseguite di nuovo `claude mcp add-from-claude-desktop`3866* Se hai avviato questa sessione dall'interno di un'altra sessione Claude Code di proposito, non è necessaria alcuna azione

1219* Aggiungete quel server direttamente con `claude mcp add` o `claude mcp add-json` con un nome valido. Vedere [Import MCP servers from Claude Desktop](/docs/it/mcp#import-mcp-servers-from-claude-desktop).3867* Se questa è una sessione di primo livello, esci e riavvia con [`CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`](/docs/it/env-vars) impostato. Il salvataggio si applica dal riavvio, quindi i messaggi inviati prima non vengono salvati.

3868* Per correggere i futuri avvii dallo stesso terminale o launcher, rimuovi `CLAUDE_CODE_CHILD_SESSION` dal suo ambiente

1220 3869

1221<h3 id="mcp-permission-prompt-tool-not-found">3870<h2 id="configuration-warnings">

1222 Strumento di prompt di autorizzazione MCP non trovato3871 Avvisi di configurazione

3872</h2>

3873

3874Claude Code scrive la maggior parte di questi messaggi su stderr, non nella conversazione, e scrive la maggior parte di essi all'avvio. Una voce lo dice quando il suo messaggio appare altrove, ad esempio nel log di debug o come avviso di avvio nella vista della conversazione, o in un altro momento, ad esempio la [riga diagnostica modello non riconosciuto](#unrecognized-model-id-on-a-request) al momento della richiesta.

3875

3876<h3 id="fullscreen-failed-start-notice">

3877 Il renderer fullscreen non ha finito di avviarsi

1223</h3>3878</h3>

1224 3879

1225Lo strumento che avete passato a [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags) non era tra gli strumenti MCP connessi quando l'esecuzione ha avuto bisogno per la prima volta di una decisione di autorizzazione, sia perché il suo server non si è mai connesso sia perché nessun server connesso espone uno strumento con quel nome. Claude Code invia comunque il vostro prompt: l'esecuzione [non interattiva](/docs/it/headless) esce con questo errore, e codice di uscita 1, alla prima chiamata di strumento che necessita di approvazione, quindi non produce alcuna risposta anche se la richiesta è stata effettuata. Prima del primo prompt, Claude Code attende fino al timeout di connessione per server di 30 secondi impostato da [`MCP_TIMEOUT`](/docs/it/env-vars) affinché quel server si connetta. Prima della v2.1.206, l'avvio non attendeva che il server finisse di connettersi, quindi un server che si avvia lentamente ma sano produceva questo errore anche.3880Una precedente sessione [fullscreen](/docs/it/fullscreen) su questa macchina è uscita prima di finire di avviarsi, quindi Claude Code avvia questa sessione sul renderer classico e stampa uno di questi avvisi:

1226 3881

1227```text theme={null}3882```text theme={null}

1228Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3883Claude Code's fullscreen renderer didn't finish starting last time on this machine, so this launch is using the classic renderer. It will try fullscreen again next launch; /tui default keeps the classic renderer.

3884

3885Claude Code's fullscreen renderer has repeatedly failed to start on this machine, so it has been turned off here. Run /tui fullscreen to try it again (this also resets after an update).

1229```3886```

1230 3887

1231L'elenco dopo `Available MCP tools:` nomina gli strumenti MCP che erano connessi quando l'attesa è terminata.3888**Cosa fare:**

3889

3890* Seguire [Fullscreen rendering](/docs/it/fullscreen#fullscreen-renderer-didnt-finish-starting). Dice quale avviso ricevete, cosa Claude Code fa nelle sessioni successive, e come provare di nuovo fullscreen o mantenere il renderer classico.

3891* Se la sessione che è morta ha stampato un messaggio di uscita, vedere [Claude Code è uscito dopo un errore di interfaccia irrecuperabile](#exited-after-an-unrecoverable-interface-error) per quello che nomina.

3892

3893Prima della v2.1.236, Claude Code non stampava alcun avviso e continuava ad avviare sessioni nel rendering fullscreen dopo un avvio fallito.

3894

3895<h3 id="exited-after-an-unrecoverable-interface-error">

3896 Claude Code è uscito dopo un errore di interfaccia irrecuperabile

3897</h3>

3898

3899Claude Code stampa questo messaggio quando esce perché la sua interfaccia terminale ha riscontrato un errore da cui non può recuperare, in uno dei due renderer. La seconda frase appare solo quando l'errore si è verificato mentre il renderer [fullscreen](/docs/it/fullscreen) si stava avviando:

3900

3901```text theme={null}

3902Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).

3903```

1232 3904

1233**Cosa fare:**3905**Cosa fare:**

1234 3906

1235* Verificate che il server si avvii e rimanga connesso: eseguite `claude mcp list` nella stessa directory e confermate che il server è elencato come connesso3907* Avviare di nuovo Claude Code. Per riprendere la conversazione, eseguire `claude --resume` nella stessa directory.

1236* Confermate che il nome dello strumento corrisponda al nome `mcp__<server>__<tool>` che il server espone3908* Se il messaggio nomina il renderer fullscreen, [Fullscreen rendering](/docs/it/fullscreen#fullscreen-renderer-didnt-finish-starting) dice cosa fa il prossimo avvio, che dipende da come avete attivato fullscreen, e come provare di nuovo fullscreen o mantenere il renderer classico.

1237* Se il server ha bisogno di più di 30 secondi per avviarsi, aumentate [`MCP_TIMEOUT`](/docs/it/env-vars)

1238 3909

1239<h2 id="plugin-errors">3910Prima della v2.1.236, Claude Code usciva senza stampare un messaggio dopo questo tipo di errore.

1240 Errori dei plugin3911

1241</h2>3912<h3 id="agent-descriptions-are-over-the-15000-token-limit">

3913 Le descrizioni degli agenti superano il limite di 15.0k token

3914</h3>

1242 3915

1243Questi errori provengono dalla configurazione dei [plugin](/docs/it/plugins) e del [marketplace](/docs/it/plugin-marketplaces). Per i problemi dei plugin che non producono uno dei messaggi in questa pagina, come un URL del marketplace che non si carica o un plugin che si installa ma non appare, vedere [Risoluzione dei problemi dei plugin](/docs/it/discover-plugins#troubleshooting).3916Claude Code mostra questo avviso come avviso di avvio nella vista della conversazione piuttosto che su stderr. Le descrizioni combinate dei vostri [subagenti](/docs/it/sub-agents), ad eccezione di quelli incorporati, superano 15.000 token come Claude Code le stima. Ogni agente conta il suo nome più il suo frontmatter `description`. Claude Code carica ogni agente indipendentemente dal fatto che il totale superi il limite, quindi l'avviso non cambia cosa viene caricato.

1244 3917

1245<h3 id="marketplace-is-registered-from-an-untrusted-source">3918```text theme={null}

1246 Il marketplace è registrato da una fonte non attendibile3919Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

3920```

3921

3922**Cosa fare:**

3923

3924* Accorciare il frontmatter `description` dei vostri file di agente, o chiedere a Claude di tagliarli per voi.

3925* Rimuovere i file di agente che non usate più.

3926

3927<h3 id="workspace-has-not-been-trusted">

3928 Lo spazio di lavoro non è stato considerato attendibile

1247</h3>3929</h3>

1248 3930

1249Il marketplace è registrato con un nome che è [riservato per i marketplace ufficiali di Anthropic](/docs/it/plugin-marketplaces#marketplace-schema), ma la sua fonte registrata non è un repository GitHub di `anthropics`. Claude Code ricontrolla i nomi riservati ogni volta che carica o aggiorna un marketplace, quindi il marketplace e i plugin installati da esso smettono di caricarsi. Prima della v2.1.205, il nome veniva controllato solo quando il marketplace veniva aggiunto, quindi una voce registrata prima che il suo nome diventasse riservato continuava a caricarsi.3931Claude Code ha trovato regole `permissions.allow` o voci `permissions.additionalDirectories` nel `.claude/settings.json` o `.claude/settings.local.json` del progetto e non le ha applicate, perché [le regole allow dalle impostazioni del progetto richiedono la fiducia dello spazio di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust). Il conteggio, il nome dell'impostazione e il file nominato nel messaggio variano con la vostra configurazione. Le regole `deny` e `ask` non sono interessate.

1250 3932

1251```text theme={null}3933```text theme={null}

1252Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.3934Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

1253```3935```

1254 3936

1255**Cosa fare:**3937**Cosa fare:**

1256 3938

1257* Eseguire `claude plugin marketplace remove <name>`, quindi aggiungere di nuovo il marketplace dal repository ufficiale `github.com/anthropics`3939* Eseguire `claude` nella directory e accettare la finestra di dialogo di fiducia. [Project allow rules and workspace trust](/docs/it/permissions#project-allow-rules-and-workspace-trust) dice quale cartella copre tale accettazione.

1258* Se pubblicate un marketplace di terze parti che ha utilizzato il nome prima che diventasse riservato, rinominatelo e chiedete agli utenti di aggiungerlo di nuovo dalla vostra fonte3940* In [modalità non interattiva](/docs/it/headless) con `-p` nessuna finestra di dialogo viene mostrata. Impostare la voce `hasTrustDialogAccepted` in `~/.claude.json` usando la chiave `projects` esatta che il messaggio stampa.

1259* Vedere l'elenco dei nomi riservati in [Schema del marketplace](/docs/it/plugin-marketplaces#marketplace-schema)3941* Se il messaggio nomina `.claude/settings.local.json` e avete avviato Claude Code al di fuori di un repository git o nella vostra home directory, aggiornare alla v2.1.200 o successiva. Le versioni 2.1.196 attraverso 2.1.199 hanno trattato il vostro `.claude/settings.local.json` come fornito dal repository in quegli spazi di lavoro. Sulla v2.1.207 e successiva, l'aggiornamento non è sufficiente al di fuori di un repository git se non avete considerato attendibile la cartella: determinare che una cartella non è all'interno di un repository esegue git, e Claude Code esegue quel controllo solo dopo che accettate la finestra di dialogo di fiducia, quindi usate il primo passaggio. La vostra home directory e qualsiasi altra [configuration home](/docs/it/permissions#project-allow-rules-and-workspace-trust) sono esenti e non aspettano la finestra di dialogo. Vedere [Project allow rules and workspace trust](/docs/it/permissions#project-allow-rules-and-workspace-trust).

1260 3942

1261<h3 id="plugin-command-references-user-config">3943<h3 id="working-directory-is-a-network-path">

1262 Il comando del plugin fa riferimento a user\_config in un comando shell3944 La directory di lavoro è un percorso di rete

1263</h3>3945</h3>

1264 3946

1265Un hook del plugin, [monitor](/docs/it/plugins-reference#monitors), o un comando MCP [`headersHelper`](/docs/it/mcp#use-dynamic-headers-for-custom-authentication) fa riferimento a un'[opzione del plugin](/docs/it/plugins-reference#user-configuration) `${user_config.KEY}`, e la stringa sostituita verrebbe passata a una shell. Un valore configurato contenente `$(...)`, backtick o `;` verrebbe eseguito come codice lì, quindi Claude Code rifiuta di avviare il componente invece di sostituire il valore. Il controllo viene eseguito sul modello di comando, quindi l'errore appare anche quando nessun valore è ancora configurato. Prima della v2.1.207, il valore veniva sostituito nel comando shell.3947Claude Code non aggiunge percorsi di rete come directory di lavoro. Cercare un percorso di rete può contattare l'host che nomina, e su Windows quel contatto può inviare all'host le vostre credenziali, quindi Claude Code rifiuta il percorso senza cercarlo. Vedete questo messaggio quando eseguite `/add-dir` con tale percorso, o come avviso all'avvio. Quando appare all'avvio, Claude Code si avvia senza quella directory.

1266 3948

1267La formulazione dipende da quale superficie ha fatto riferimento all'opzione. Un hook in forma shell segnala:3949```text theme={null}

3950\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).

3951```

3952

3953I percorsi che Claude Code rifiuta in questo modo includono:

3954

3955* Condivisioni UNC come `\\server\share`

3956* Percorsi di montaggio automatico come `/net/<host>`, a meno che non abbiate avviato Claude Code da una directory sotto il montaggio automatico di quell'host

3957* Percorsi locali che raggiungono una posizione di rete attraverso un collegamento simbolico o una giunzione

3958

3959Le lettere di unità mappate e i percorsi `\\wsl$` non contano come percorsi di rete.

3960

3961**Cosa fare:**

3962

3963* Su Windows, mappare la condivisione a una lettera di unità, ad esempio con `net use Z: \\server\share`, e passare l'unità all'avvio con `claude --add-dir Z:\`.

3964* Su macOS o Linux, montare la condivisione in un percorso locale e aggiungere quel percorso invece.

3965* Se il percorso è in `permissions.additionalDirectories`, rimuoverlo dal file di impostazioni che lo elenca.

3966

3967Prima della v2.1.257, Claude Code accettava un percorso di rete raggiungibile come directory di lavoro.

3968

3969<h3 id="remote-managed-settings-failed-to-load">

3970 Le impostazioni gestite da remoto non hanno potuto essere caricate

3971</h3>

3972

3973La vostra sessione è idonea per [impostazioni gestite dal server](/docs/it/server-managed-settings), ma Claude Code non ha potuto recuperarle, quindi mostra questo avviso nelle sessioni interattive. La causa tra parentesi nomina cosa è fallito, come `network error`, `request timed out`, o `authentication rejected (401)`, e il resto della riga dice quale politica la sessione esegue:

3974

3975* **Impostazioni memorizzate nella cache da un recupero precedente riuscito**: Claude Code esegue la sessione su quella politica memorizzata nella cache, ad eccezione delle [variabili di ambiente trattenute](/docs/it/server-managed-settings#fetch-and-caching-behavior), e la riga legge `using cached policy`.

3976* **Nessuna cache**: Claude Code esegue la sessione senza impostazioni gestite dal server, e la riga legge `no remote policy applied`.

3977

3978**Cosa fare:**

3979

3980* Agire sulla causa che il messaggio nomina: per una causa di rete, verificare che questa macchina possa raggiungere `api.anthropic.com`; per una causa di autenticazione, controllare il vostro accesso con `/status`

3981* Eseguire `/status` o `claude doctor` per la diagnostica completa

3982

3983Prima della v2.1.248, Claude Code segnalava un recupero di impostazioni fallito solo nel log di debug.

3984

3985<h3 id="managed-settings-were-not-approved">

3986 Le impostazioni gestite non sono state approvate

3987</h3>

3988

3989Le [impostazioni gestite dal server](/docs/it/server-managed-settings) della vostra organizzazione includono impostazioni che necessitano della vostra approvazione, e avete rifiutato la [finestra di dialogo di approvazione della sicurezza](/docs/it/server-managed-settings#security-approval-dialogs), quindi Claude Code esce senza applicarle:

1268 3990

1269```text theme={null}3991```text theme={null}

1270Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}3992Managed settings were not approved; exiting without applying them.

1271```3993```

1272 3994

1273Un monitor segnala:3995**Cosa fare:**

3996

3997* Avviare di nuovo Claude Code e approvare la finestra di dialogo per continuare secondo le impostazioni della vostra organizzazione. Una finestra di dialogo rifiutata non viene ricordata, quindi appare di nuovo al prossimo avvio.

3998* Se siete incerti su un'impostazione che la finestra di dialogo elenca, chiedete a chi mantiene le impostazioni gestite della vostra organizzazione prima di approvare

3999

4000<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

4001 Il server MCP è bloccato dalla politica gestita aziendale

4002</h3>

4003

4004Avete selezionato **Reconnect** su un server in `/mcp`, o riattivato un server disabilitato lì, e un'impostazione che [limita i server MCP](/docs/it/managed-mcp) blocca quel server. Claude Code rifiuta di connetterlo e mostra:

1274 4005

1275```text theme={null}4006```text theme={null}

1276Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.4007MCP server <name> is blocked by enterprise managed policy

1277```4008```

1278 4009

1279Un MCP `headersHelper` segnala:4010Una qualsiasi di queste impostazioni può produrre il messaggio:

4011

4012* Una voce [`deniedMcpServers`](/docs/it/managed-mcp#policy-based-control-with-allowlists-and-denylists) che corrisponde al server, inclusa una nel vostro `~/.claude/settings.json` o nel `.claude/settings.json` del progetto

4013* Un elenco [`allowedMcpServers`](/docs/it/managed-mcp#policy-based-control-with-allowlists-and-denylists) che il server non corrisponde

4014* [`strictPluginOnlyCustomization`](/docs/it/settings-reference#strictpluginonlycustomization) con `mcp` bloccato, che blocca i server configurati in `~/.claude.json` e `.mcp.json`

4015* [`disableClaudeAiConnectors`](/docs/it/mcp#disable-claude-ai-connectors), quando il server è un connettore claude.ai

4016

4017**Cosa fare:**

4018

4019* Controllare i vostri file di impostazioni utente e progetto per una di queste impostazioni e cambiarla o rimuoverla

4020* Se nessuna delle vostre impostazioni spiega il blocco, chiedete al vostro amministratore quale impostazione gestita blocca il server

4021

4022Prima della v2.1.257, **Reconnect** e ri-abilitare in `/mcp` potevano connettere un server che un aggiornamento di politica mid-session bloccava.

4023

4024<h3 id="managed-settings-document-could-not-be-parsed">

4025 Il documento delle impostazioni gestite non ha potuto essere analizzato

4026</h3>

4027

4028La vostra organizzazione distribuisce [impostazioni gestite](/docs/it/managed-settings), e uno dei documenti distribuiti è presente ma non può essere analizzato come un oggetto JSON, quindi Claude Code esce con codice 1 all'avvio invece di eseguire senza la politica che il documento contiene. La riga nomina la fonte fallita prima del messaggio:

1280 4029

1281```text theme={null}4030```text theme={null}

1282headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).4031/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.

1283```4032```

1284 4033

4034La fonte è una di:

4035

4036* Il percorso del file `managed-settings.json` o un file drop-in sotto `managed-settings.d`

4037* Il profilo delle preferenze gestite macOS, `per-user managed preferences` o `device-level managed preferences`

4038* Il valore del registro Windows, `Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`

4039

4040[Find entries Claude Code dropped](/docs/it/managed-settings#find-entries-claude-code-dropped) elenca cosa rende ogni fonte non analizzabile.

4041

4042Claude Code rifiuta di avviarsi anche quando un'altra fonte amministrativa fornisce una politica valida. Vedete questo errore nelle sessioni interattive, `claude -p`, sessioni Agent SDK, [sessioni in background](/docs/it/agent-view), e la maggior parte dei sottocomandi, `claude doctor` incluso. Il rifiuto fallisce chiuso di proposito: le impostazioni in un documento che Claude Code non può analizzare non possono essere applicate, e avviarsi comunque eseguirebbe sessioni senza i controlli dell'organizzazione.

4043

4044Un problema di schema in un documento analizzabile non produce questo errore. [Find entries Claude Code dropped](/docs/it/managed-settings#find-entries-claude-code-dropped) copre cosa Claude Code fa con uno.

4045

4046Quando una directory `managed-settings.d/` esiste ma non può essere elencata, Claude Code segnala `Managed settings drop-in directory could not be read:` seguito dall'errore sottostante invece. [Find entries Claude Code dropped](/docs/it/managed-settings#find-entries-claude-code-dropped) copre quando un errore di lettura esce all'avvio.

4047

1285**Cosa fare:**4048**Cosa fare:**

1286 4049

1287* Per un hook, aggiungere un array `args` in modo che venga eseguito in [forma exec](/docs/it/hooks#exec-form-and-shell-form), dove ogni `${user_config.KEY}` diventa un argomento senza shell in mezzo. Oppure eliminare il riferimento e leggere la variabile di ambiente `$CLAUDE_PLUGIN_OPTION_<KEY>` all'interno dello script4050* Se amministrate la macchina, correggere il documento nominato in modo che si analizzi come un oggetto JSON, o rimuovere il file, il profilo o il valore del registro. Un `managed-settings.json` vuoto conta come `{}` e non blocca l'avvio.

1288* Per un monitor, eliminare il riferimento e fare in modo che lo script del monitor legga il valore da un file di configurazione4051* Se non lo fate, chiedete al vostro amministratore di correggere il documento distribuito. Nulla nei vostri file di impostazioni causa o cancella questo errore.

1289* Per un `headersHelper`, spostare `${user_config.KEY}` nel campo `headers` del server, che non viene analizzato dalla shell, oppure leggere il valore all'interno dello script helper

1290 4052

1291<h2 id="tool-errors">4053<h3 id="headershelper-not-run">

1292 Errori degli strumenti4054 headersHelper non eseguito

1293</h2>4055</h3>

1294 4056

1295Questi errori provengono dai strumenti integrati di Claude che rifiutano un input. Claude corregge la maggior parte degli errori degli strumenti da solo; i due seguenti richiedono una modifica da parte vostra, perché provengono da una definizione di subagent o da una regola di autorizzazione che controllate.4057Claude Code ha connesso un server MCP con i suoi `headers` statici soli e ha saltato il [`headersHelper`](/docs/it/mcp#use-dynamic-headers-for-custom-authentication) del server, perché l'helper è un comando shell e la cartella non ha fiducia salvata. Una cartella ottiene fiducia salvata quando impostate la sua voce in `~/.claude.json` a mano o, al di fuori della vostra home directory, quando accettate la finestra di dialogo di fiducia per essa in una sessione interattiva. Vedere [Trust a folder before its headersHelper runs](/docs/it/mcp#trust-a-folder-before-its-headershelper-runs) per quali server questo controllo si applica.

1296 4058

1297<h3 id="agent-would-be-spawned-with-zero-tools">4059Claude Code scrive questa riga in [modalità non interattiva](/docs/it/headless) solo, una volta per server. In una sessione interattiva scrive lo stesso rifiuto al log di debug invece.

1298 L'agente verrebbe generato con zero strumenti4060

4061```text theme={null}

4062MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.

4063```

4064

4065La chiave `projects` che il messaggio stampa è la cartella [Project allow rules and workspace trust](/docs/it/permissions#project-allow-rules-and-workspace-trust) dice Claude Code chiavi la fiducia su. Accettare la finestra di dialogo di fiducia per una cartella genitore non soddisfa il controllo, e una sessione `-p` o SDK non la soddisfa nemmeno.

4066

4067**Cosa fare:**

4068

4069* Eseguire `claude` nella cartella che il messaggio nomina, accettare la finestra di dialogo di fiducia, quindi eseguire di nuovo il vostro comando `-p` o SDK

4070* Impostare la voce `hasTrustDialogAccepted` in `~/.claude.json` voi stessi, usando la chiave `projects` esatta che il messaggio stampa

4071* Se avete avviato la sessione nella vostra home directory, lavorare da una directory di progetto che avete considerato attendibile. Quando accettate la finestra di dialogo di fiducia nella vostra home directory, Claude Code mantiene quella fiducia per la sessione corrente solo.

4072

4073<h3 id="malformed-tool-content-rule">

4074 Regola Tool(content) malformata

1299</h3>4075</h3>

1300 4076

1301Nulla nell'[elenco `tools` di un subagent](/docs/it/sub-agents#supported-frontmatter-fields) si è risolto in uno strumento, quindi Claude Code rifiuta di avviare il subagent piuttosto che avviarne uno che non può agire. Il messaggio raggruppa le voci in base al motivo per cui non si sono risolte: non è uno strumento riconosciuto, uno strumento che non è disponibile per i subagent, o riconosciuto ma che non corrisponde a nessuno strumento nella sessione corrente. L'omissione del campo `tools` non attiva mai questo rifiuto. Un pattern di server MCP come `mcp__github__*` non è esente: quando nessuno strumento connesso proviene da quel server, l'avvio viene rifiutato con il pattern nel gruppo matched-nothing. Prima della v2.1.208, il subagent veniva avviato senza strumenti e restituiva un risultato vuoto o confuso.4077Una [regola di permesso](/docs/it/permissions#permission-rule-syntax) in uno dei vostri file di impostazioni non ha la forma `Tool` o `Tool(content)`, ad esempio perché il testo segue la parentesi di chiusura o una delle parentesi manca. Claude Code salta la regola e la elenca nella finestra di dialogo delle impostazioni non valide quando una sessione interattiva si avvia, e nell'output di [`claude doctor`](/docs/it/debug-your-config#check-resolved-settings):

1302 4078

1303```text theme={null}4079```text theme={null}

1304Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.4080Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal

1305```4081```

1306 4082

1307**Cosa fare:**4083**Cosa fare:**

1308 4084

1309* Correggete ogni voce che l'errore nomina rispetto agli [strumenti disponibili per i subagent](/docs/it/sub-agents#available-tools)4085* Nel file di impostazioni elencato con il messaggio, riscrivere la regola in modo che termini alla sua parentesi di chiusura, ad esempio `Bash(ls *)` al posto di `Bash(ls) x`

1310* Rimuovete le voci per gli strumenti che la sessione non ha, come gli strumenti MCP da un server che non è connesso4086* Lasciare le parentesi all'interno del contenuto come sono. Sono letterali, quindi una regola come `Edit(./Finance (2024)/**)` è valida senza escape

1311* Per dare al subagent ogni strumento che ha il genitore, eliminate il campo `tools` invece di elencare gli strumenti

1312 4087

1313<h3 id="file-is-covered-by-a-read-deny-rule">4088Prima della v2.1.260, Claude Code segnalava una regola con parentesi non abbinate come `Mismatched parentheses`.

1314 Il file è coperto da una regola di negazione Read4089

4090<h3 id="is-not-matched-by-file-permission-checks">

4091 Non è abbinato dai controlli di permesso dei file

1315</h3>4092</h3>

1316 4093

1317Lo strumento Edit è stato chiamato su un percorso corrispondente a una [regola di negazione `Read`](/docs/it/permissions#read-and-edit), inclusa la creazione di un nuovo file in quel percorso. La modifica riscrive il contenuto che Claude deve essere in grado di leggere di nuovo, quindi la chiamata viene rifiutata prima di qualsiasi accesso ai file. La regola blocca solo lo strumento Edit: Write e NotebookEdit non sono coperti da regole di negazione `Read`. Prima della v2.1.208, solo una regola di negazione `Edit` bloccava le modifiche, e una regola di negazione `Read` da sola non lo faceva.4094Claude Code ha trovato una regola di permesso `Write`, `NotebookEdit`, `MultiEdit`, o `Glob` [permission rule](/docs/it/permissions#read-and-edit) con un percorso in uno dei vostri [file di impostazioni](/docs/it/settings#where-settings-live), in [impostazioni gestite](/docs/it/managed-settings), o in un valore di flag `--allowedTools`, `--disallowedTools`, o `--settings`. Controlla i permessi dei file rispetto alle regole `Edit` e `Read` solo, quindi non consulta mai una regola di percorso che nomina uno degli altri strumenti di file. Mantiene la regola e non cambia nient'altro; l'avviso nomina la regola, la sua fonte tra parentesi, e la sostituzione da scrivere:

1318 4095

1319```text theme={null}4096```text theme={null}

1320File is covered by a Read deny rule in your permission settings and cannot be edited.4097Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

1321```4098```

1322 4099

1323**Cosa fare:**4100**Cosa fare:**

1324 4101

1325* Se Claude dovrebbe essere in grado di modificare il file, rimuovete o restringete la regola di negazione `Read` in `/permissions` o nelle [impostazioni](/docs/it/settings#permission-settings)4102* Sostituire le regole `Write(path)`, `NotebookEdit(path)`, e legacy `MultiEdit(path)` con `Edit(path)`. Le regole `Edit` coprono tutti gli strumenti di modifica dei file.

1326* Se il file deve rimanere intatto, mantenete la regola e aggiungete una regola di negazione `Edit` per lo stesso percorso in modo che anche gli strumenti Write e NotebookEdit vengano bloccati4103* Ad eccezione di `--allowedTools`, dove Claude Code accetta una regola `Glob` senza avviso, sostituire le regole `Glob(path)` con `Read(path)`.

4104* Correggere la regola alla fonte che l'avviso nomina tra parentesi: un percorso di file di impostazioni, o il flag stesso per `--allowed-tools` e `--disallowed-tools`. Un percorso `claude-settings-<hash>.json` che non esiste su disco rappresenta un valore `--settings` inline. Correggere il JSON che passate a quel flag.

4105* Lasciare sole le regole di nome di strumento nudo come `Write` o `Glob`. Claude Code le abbina a livello di [tool level](/docs/it/permissions#match-all-uses-of-a-tool) e non avvisa su di esse.

4106* Se la fonte legge `managed policy settings`, inoltrare l'avviso a chi mantiene le vostre impostazioni gestite, poiché non potete cancellarlo voi stessi.

1327 4107

1328<h2 id="background-session-errors">4108In una [sessione in background](/docs/it/agent-view) o con `--output-format json` o `stream-json`, Claude Code scrive l'avviso al log di debug invece di stderr, quindi l'output letto dalla macchina rimane pulito. Eseguire con `--debug` per catturarlo in `~/.claude/debug/<session-id>.txt`. Prima della v2.1.210, Claude Code accettava queste regole senza un avviso.

1329 Errori di sessione in background

1330</h2>

1331 4109

1332Le [sessioni in background](/docs/it/agent-view) vengono eseguite senza un terminale interattivo proprio, quindi i comandi che ne richiedono uno si comportano diversamente lì. Questi messaggi appaiono nella trascrizione di una sessione in background, nella vista agente o dopo il collegamento.4110<h3 id="has-a-wildcard-before-the-rest-of-the-command">

4111 Ha un carattere jolly prima del resto del comando

4112</h3>

1333 4113

1334<h3 id="commands-refused-in-a-background-session">4114Claude Code ha trovato una regola allow `Bash` il cui `*` viene prima di una parola successiva che determina quale comando è, come `Bash(git * main)` o `Bash(git -C * status *)`, in uno dei vostri [file di impostazioni](/docs/it/settings#where-settings-live), in [impostazioni gestite](/docs/it/managed-settings), o in un valore di flag `--allowedTools` o `--settings`. Il `*` corrisponde a qualsiasi testo, incluse le opzioni inserite in quella posizione: `Bash(git * main)` approva anche `git -c core.fsmonitor=<script> diff main`, dove `-c` fa eseguire a git un programma che il comando nomina. [Wildcard patterns](/docs/it/permissions#wildcard-patterns) mostra le regole di corrispondenza.

1335 Comandi rifiutati in una sessione in background4115

4116L'avviso esiste in modo che possiate restringere una regola il cui carattere jolly è più ampio di quanto intendete. Claude Code mantiene la regola e non cambia nulla su come corrisponde; l'avviso nomina la regola e la sua fonte tra parentesi:

4117

4118```text theme={null}

4119Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).

4120```

4121

4122**Cosa fare:**

4123

4124* Sostituire il `*` prima del sottocomando con il valore esatto che intendete: `Bash(git checkout main)` al posto di `Bash(git * main)`.

4125* Spostare ogni `*` dopo il sottocomando: `Bash(git status *)` al posto di `Bash(git -C * status *)`. Scrivere una regola per sottocomando che volete permettere.

4126* Correggere la regola alla fonte che l'avviso nomina tra parentesi: un percorso di file di impostazioni, o il flag `--allowed-tools` stesso. Un percorso `claude-settings-<hash>.json` che non esiste su disco rappresenta un valore `--settings` inline. Correggere il JSON che passate a quel flag.

4127* Se la fonte legge `managed policy settings`, inoltrare l'avviso a chi mantiene le vostre impostazioni gestite, poiché non potete cancellarlo voi stessi.

4128

4129Claude Code non avvisa su regole deny e ask con la stessa forma: rifiuta o chiede i comandi extra che corrispondono piuttosto che approvarli. Non avvisa nemmeno su regole il cui sottocomando viene prima del primo `*`, come `Bash(git commit *)`, o regole in cui nessuna parola diversa da un'opzione segue il `*`, come `Bash(git *)`, o su regole di prefisso `:*` come `Bash(git:*)`.

4130

4131In una [sessione in background](/docs/it/agent-view) o con `--output-format json` o `stream-json`, Claude Code scrive l'avviso al log di debug invece di stderr, quindi l'output letto dalla macchina rimane pulito. Eseguire con `--debug` per catturarlo in `~/.claude/debug/<session-id>.txt`. Prima della v2.1.246, Claude Code accettava queste regole senza un avviso.

4132

4133<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

4134 crossSessionInbound deve essere uno di accept, hold, refuse

1336</h3>4135</h3>

1337 4136

1338I comandi che aprono una finestra di dialogo interattiva vengono rifiutati in una sessione in background con un messaggio che nomina un modulo che funziona lì o che ti dice di eseguire il comando da un terminale regolare. `/install-github-app`, l'elenco delle impostazioni `/mcp` e le azioni di autenticazione nel menu del server MCP vengono tutti rifiutati in questo modo. Prima della versione 2.1.208, aprivano la loro finestra di dialogo all'interno della sessione in background.4137Un file di impostazioni imposta [`crossSessionInbound`](/docs/it/settings-reference#crosssessioninbound) a un valore che Claude Code non riconosce, come il typo `"reject"`. La seconda frase dell'avviso dipende da quale file contiene il valore; in un file utente, progetto, locale, o `--settings` legge:

1339Nella versione 2.1.208 solamente, il selettore `/model` è stato rifiutato anche in una sessione in background e `/upgrade` ha stampato l'URL di aggiornamento invece di aprire un browser.4138

4139```text theme={null}

4140"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.

4141```

4142

4143In [impostazioni gestite](/docs/it/managed-settings), Claude Code tratta il valore non riconosciuto come `refuse`, il valore più restrittivo, e l'avviso dice che i messaggi cross-session vengono rifiutati fino a quando un amministratore non lo corregge. Per come l'hold si combina con i valori nei vostri altri file di impostazioni, vedere [`crossSessionInbound`](/docs/it/settings-reference#crosssessioninbound).

4144

4145**Cosa fare:**

4146

4147* Impostare la chiave a `"accept"`, `"hold"`, o `"refuse"`, o rimuoverla

4148* Quando l'avviso nomina impostazioni gestite, chiedere all'amministratore di correggere il valore

4149

4150Prima della v2.1.248, Claude Code ignorava un valore non riconosciuto senza avviso.

4151

4152<h3 id="the-200k-limit-isnt-enforced">

4153 Il limite di 200K non è applicato

4154</h3>

1340 4155

1341La formulazione nomina il comando che è stato rifiutato. L'elenco delle impostazioni `/mcp` riporta:4156Avete impostato [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/it/env-vars), che normalmente fa sì che [auto-compaction](/docs/it/model-config#default-auto-compact-thresholds) mantenga le sessioni su modelli con contesto 1M a una finestra di 200K, ma nessuna soglia di compattazione limita questa sessione a o sotto 200K, quindi la conversazione può crescere oltre.

1342 4157

1343```text theme={null}4158```text theme={null}

1344Can't open MCP settings in a background session — use `/mcp enable|disable|reconnect <server>` to steer, or run /mcp from an interactive terminal to authenticate.4159CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).

1345```4160```

1346 4161

4162Claude Code applica il limite di 200K da solo per ogni modello che riconosce come avente una finestra nativa di 1M, e per ID di modello che non riconosce compatta alla finestra che assume. L'avviso appare quando altra configurazione sconfigge tale applicazione:

4163

4164* L'ID del modello non è uno che Claude Code riconosce, come un alias di [LLM gateway](/docs/it/llm-gateway), e avete impostato [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/it/env-vars) o aumentato la finestra assunta oltre 200K con [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/it/env-vars). In questo caso il messaggio offre anche `or update to a Claude Code version that recognizes <model>` come rimedio.

4165* Un beta `context-1m` richiesto attraverso [`ANTHROPIC_BETAS`](/docs/it/env-vars) o il flag [`--betas`](/docs/it/cli-reference#cli-flags) chiede ancora all'API la finestra 1M su un modello che accetta quel beta, mentre nulla compatta la sessione a 200K

4166

1347**Cosa fare:**4167**Cosa fare:**

1348 4168

1349* Usa il modulo che il messaggio nomina, come `/mcp reconnect <server>`, `/mcp enable` o `/mcp disable`4169* Impostare [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/it/env-vars), o l'impostazione [`autoCompactWindow`](/docs/it/settings-reference#autocompactwindow) a `200000`, in modo che auto-compaction compatti al confine di 200K

1350* Per i flussi di accesso e autorizzazione, esegui il comando da una sessione `claude` regolare in un terminale4170* Se il messaggio nomina un ID di modello che questa versione non riconosce, eseguire `claude update`. Una versione che riconosce l'ID come modello con contesto 1M applica il limite senza ulteriore configurazione.

4171* Se volete che la sessione usi la finestra completa del modello invece, disimpostare `CLAUDE_CODE_DISABLE_1M_CONTEXT`; l'avviso segnala solo che il limite di 200K non è applicato

1351 4172

1352<h3 id="claude_code_process_wrapper-launcher-errors">4173In una [sessione in background](/docs/it/agent-view) o con `--output-format json` o `stream-json`, Claude Code scrive l'avviso al log di debug invece di stderr.

1353 Errori del launcher CLAUDE\_CODE\_PROCESS\_WRAPPER4174

4175<h3 id="unrecognized-model-id-on-a-request">

4176 ID modello non riconosciuto su una richiesta

1354</h3>4177</h3>

1355 4178

1356[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/it/corporate-launcher) è impostato e il suo valore non può essere utilizzato, quindi Claude Code rifiuta di avviare il processo interessato piuttosto che eseguirlo senza il launcher. I problemi di configurazione vengono segnalati con un messaggio che inizia con il nome della variabile e dichiara il motivo, ad esempio:4179Claude Code ha inviato una richiesta per un ID di modello che la vostra versione di Claude Code non riconosce, e non ha trovato alcuna voce [`modelOverrides`](/docs/it/model-config#override-model-ids-per-version) che mappa quell'ID a un modello che riconosce. Claude Code invia comunque la richiesta con l'ID come lo avete configurato, e non esce o cambia modelli.

1357 4180

1358```text theme={null}4181```text theme={null}

1359CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file4182[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

1360```4183```

1361 4184

1362Un launcher che si avvia ma esce senza sostituirsi con Claude Code non riesce nella sessione che stava avviando, e la riga della sessione nella vista agente riporta che il launcher `must exec, not daemonize`, seguito da qualsiasi cosa il launcher abbia stampato. Una sessione che non può avviarsi o raggiungere il servizio in background a causa del launcher riporta il problema del launcher come motivo all'interno di `Couldn't reach the background service (...)`.4185In uno script o harness che legge stderr, abbinare il prefisso `[claude-code:unrecognized_model]`. Dopo il prefisso e uno spazio, Claude Code scrive un oggetto JSON su una riga. Claude Code può aggiungere campi ad esso in una versione successiva, quindi ignorare qualsiasi campo che non vi aspettate. Scrive almeno questi due:

4186

4187* `model`: la stringa del modello come l'avete configurata

4188* `query_source`: il percorso della richiesta che ha usato il modello. Claude Code segnala `sdk` per un'esecuzione `-p` e un valore che inizia con `agent:` per un subagente.

4189

4190Claude Code scrive la riga in uno di due posti, a seconda di come la eseguite:

4191

4192* In [modalità non interattiva](/docs/it/headless) con `-p`, Claude Code la scrive su stderr sotto ogni `--output-format`, in modo che possiate analizzare stdout senza filtrare la riga

4193* In una sessione interattiva o una [sessione in background](/docs/it/agent-view), Claude Code la scrive al log di debug invece; eseguire con `--debug` per catturarla in `~/.claude/debug/<session-id>.txt`

4194

4195Claude Code scrive la riga una volta per stringa di modello per processo. Scrive una riga separata per ogni ulteriore ID non riconosciuto, come uno che un [subagente](/docs/it/sub-agents#choose-a-model) o [funzionalità in background](/docs/it/costs#background-token-usage) usa.

4196

4197Claude Code non scrive la riga per ID di provider che risolve a un modello che riconosce, come ID Amazon Bedrock `us.anthropic.claude-...`, ID di Google Cloud's Agent Platform con un suffisso di versione `@`, e nomi di distribuzione Microsoft Foundry che contengono un ID di modello Claude. Claude Code controlla il modello dietro un [ARN del profilo di inferenza dell'applicazione](/docs/it/amazon-bedrock#map-each-model-version-to-an-inference-profile) di Amazon Bedrock piuttosto che l'ARN stesso. Non scrive alcuna riga per un ARN che non può risolvere, come uno digitato male.

1363 4198

1364**Cosa fare:**4199**Cosa fare:**

1365 4200

1366* Imposta la variabile al percorso assoluto di un eseguibile che termina chiamando `exec "$@"`. Vedi [il contratto del launcher](/docs/it/corporate-launcher#the-launcher-contract) per il contratto completo4201* Se avete impostato l'ID di proposito, come un alias di [LLM gateway](/docs/it/llm-gateway), aggiungere una voce [`modelOverrides`](/docs/it/model-config#override-model-ids-per-version) al vostro [file di impostazioni](/docs/it/settings#where-settings-live) con l'ID come suo valore. Usare un ID di modello Anthropic come chiave, non un alias di famiglia come `opus`. Per `my-proxy-model` dalla riga di esempio, aggiungere questa voce:

1367* Controlla `/status`, che mostra il comando di avvio risolto nella sua voce Self-exec e avverte quando il servizio in background in esecuzione non corrisponde, oppure esegui `claude daemon status` da una shell

1368* Dopo aver corretto il valore nel blocco `env` delle [impostazioni](/docs/it/corporate-launcher#set-up-the-launcher), riavvia il servizio in background con `claude daemon stop --any` in modo che il prossimo invio avvii uno avvolto

1369 4202

1370<h2 id="configuration-warnings">4203 ```json theme={null}

1371 Avvisi di configurazione4204 {

1372</h2>4205 "modelOverrides": {

4206 "claude-opus-4-6": "my-proxy-model"

4207 }

4208 }

4209 ```

1373 4210

1374Claude Code scrive questi messaggi su stderr all'avvio anziché mostrare un errore nella conversazione. Segnalano la configurazione che ha letto ma non ha applicato.4211 Claude Code allora tratta `my-proxy-model` come `claude-opus-4-6` e smette di scrivere la riga.

1375 4212

1376<h3 id="workspace-has-not-been-trusted">4213* Se l'ID nomina un modello più nuovo della vostra versione di Claude Code, eseguire `claude update`

1377 Lo spazio di lavoro non è stato considerato attendibile4214

4215* Se l'ID è un typo, correggerlo in quale dei [posti dove potete impostare un modello](/docs/it/model-config#setting-your-model) o [variabili di alias](/docs/it/model-config#environment-variables) lo contiene. Se `query_source` inizia con `agent:`, correggerlo dove impostate il [modello del subagente](/docs/it/sub-agents#choose-a-model) invece.

4216

4217Prima della v2.1.233, Claude Code non scriveva alcuna riga quando inviava una richiesta per un ID di modello che non riconosceva.

4218

4219<h3 id="stale-sandbox-mask-files-left-by-a-killed-session">

4220 File di maschera sandbox stantii lasciati da una sessione uccisa

1378</h3>4221</h3>

1379 4222

1380Claude Code ha trovato regole `permissions.allow` o voci `permissions.additionalDirectories` nel file `.claude/settings.json` o `.claude/settings.local.json` del progetto e non le ha applicate, perché [le regole di autorizzazione dal progetto richiedono l'attendibilità dello spazio di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust). Il conteggio, il nome dell'impostazione e il file denominato nel messaggio variano in base alla configurazione. Le regole `deny` e `ask` non sono interessate.4223`claude doctor` stampa questo avviso nei suoi diagnostici, e `/status` elenca la stessa riga. Appare su Linux e WSL2 quando [sandboxing](/docs/it/sandboxing) è abilitato con isolamento del filesystem attivo.

4224

4225Mentre un comando sandboxato esegue, la sandbox mantiene un rifiuto di scrittura su un file che non esiste ancora creando un segnaposto di lettura sola di 0 byte lì, e lo rimuove dopo. Una sessione uccisa prima che quella pulizia esegua, ad esempio da SIGKILL, lascia i segnaposti dietro. Sessioni successive li legano di sola lettura di nuovo ad ogni avvio, quindi una scrittura di impostazioni come salvare "Sì, e non chiedere di nuovo" fallisce dove uno siede.

1381 4226

1382```text theme={null}4227```text theme={null}

1383Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.4228- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json

4229 Fix: Remove each with `rm <path>` while no other Claude Code session is running in that project — a 0-byte read-only file where a settings file belongs makes "Yes, and don't ask again" fail to save, and the sandbox binds it read-only again on every start

1384```4230```

1385 4231

1386**Cosa fare:**4232**Cosa fare:**

1387 4233

1388* Eseguire `claude` nella directory e accettare la finestra di dialogo di attendibilità. La finestra di dialogo viene visualizzata anche quando una directory padre è già considerata attendibile, elenca le regole che vengono trattenute e consente di rifiutare e continuare a lavorare senza di esse. Prima della v2.1.200, nessuna finestra di dialogo veniva visualizzata in quella situazione, quindi questo passaggio non poteva essere completato lì.4234* Chiudere qualsiasi altra sessione di Claude Code in esecuzione in quel progetto, quindi eliminare ogni file elencato con `rm`. L'avviso nomina fino a tre file e conta il resto, quindi rieseguire `claude doctor` dopo l'eliminazione fino a quando l'avviso non appare più. Un segnaposto che la sandbox di un'altra sessione sta ancora usando è una parte viva della protezione di scrittura di quella sessione

1389* In [modalità non interattiva](/docs/it/headless) con `-p` nessuna finestra di dialogo viene mostrata. Impostare la voce `hasTrustDialogAccepted` in `~/.claude.json` utilizzando la chiave `projects` esatta che il messaggio stampa.4235* Se una scelta di permesso che avete salvato con "Sì, e non chiedere di nuovo" non è rimasta, salvarla di nuovo dopo aver eliminato il segnaposto

1390* Se il messaggio nomina `.claude/settings.local.json` e hai avviato Claude Code al di fuori di un repository git o nella directory home, aggiorna alla v2.1.200 o successiva. Le versioni da 2.1.196 a 2.1.199 hanno trattato il tuo `.claude/settings.local.json` come fornito dal repository in quegli spazi di lavoro. Sulla v2.1.207 e successive, l'aggiornamento non è sufficiente al di fuori di un repository git se non hai considerato attendibile la cartella: determinare che una cartella non si trova all'interno di un repository esegue git, e Claude Code esegue quel controllo solo dopo che accetti la finestra di dialogo di attendibilità, quindi utilizza il primo passaggio. La directory home e qualsiasi altra [home di configurazione](/docs/it/permissions#project-allow-rules-and-workspace-trust) sono esenti e non attendono la finestra di dialogo. Vedi [Regole di autorizzazione del progetto e attendibilità dello spazio di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust).4236

4237Prima della v2.1.257, `claude doctor` non contrassegnava questi file; le versioni precedenti lasciano gli stessi segnaposti dietro quando una sessione viene uccisa.

1391 4238

1392<h2 id="responses-seem-lower-quality-than-usual">4239<h2 id="responses-seem-lower-quality-than-usual">

1393 Le risposte sembrano di qualità inferiore al solito4240 Le risposte sembrano di qualità inferiore al solito

1398 4244

1399* Un [`--fallback-model`](/docs/it/cli-reference#cli-flags) configurato subentra dopo un errore di disponibilità, solo per quel turno, con un avviso nella trascrizione4245* Un [`--fallback-model`](/docs/it/cli-reference#cli-flags) configurato subentra dopo un errore di disponibilità, solo per quel turno, con un avviso nella trascrizione

1400* Un controllo di avvio di Amazon Bedrock o della piattaforma Agent di Google Cloud trova il tuo modello predefinito non disponibile4246* Un controllo di avvio di Amazon Bedrock o della piattaforma Agent di Google Cloud trova il tuo modello predefinito non disponibile

1401* Il [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) su Fable 5 sposta la sessione al modello Opus predefinito e mostra un avviso nella trascrizione4247* Il [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) su Fable 5.1, Fable 5 e Opus 5 sposta la sessione al modello di fallback della categoria contrassegnata, quando quella categoria ne ha uno, e mostra un avviso nella trascrizione

1402 4248

1403Il controllo della selezione del modello di seguito cattura il secondo e il terzo caso; il primo appare come un avviso nella trascrizione piuttosto che come un cambio `/model`. La [configurazione del modello](/docs/it/model-config) spiega quando si applica ogni fallback.4249Il controllo della selezione del modello di seguito cattura il secondo e il terzo caso; il primo appare come un avviso nella trascrizione piuttosto che come un cambio `/model`. La [configurazione del modello](/docs/it/model-config) spiega quando si applica ogni fallback.

1404 4250

feature-availability.md +1 −1

Details

41* **Server MCP**: i [connettori da claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) si caricano solo quando il tuo abbonamento claude.ai è il metodo di autenticazione attivo. La [ricerca degli strumenti](/docs/it/mcp#configure-tool-search) è disattivata per impostazione predefinita quando `ANTHROPIC_BASE_URL` punta a un host non di prima parte, e non è supportata su modelli Google Cloud's Agent Platform precedenti alla generazione Claude 4.5 o su distribuzioni Microsoft Foundry [ospitate su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)41* **Server MCP**: i [connettori da claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) si caricano solo quando il tuo abbonamento claude.ai è il metodo di autenticazione attivo. La [ricerca degli strumenti](/docs/it/mcp#configure-tool-search) è disattivata per impostazione predefinita quando `ANTHROPIC_BASE_URL` punta a un host non di prima parte, e non è supportata su modelli Google Cloud's Agent Platform precedenti alla generazione Claude 4.5 o su distribuzioni Microsoft Foundry [ospitate su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)

42* **Subagents**: il [subagent Explore integrato](/docs/it/sub-agents#built-in-subagents) limita il suo modello ereditato a Opus sull'API Claude, e eredita il modello della conversazione principale direttamente su qualsiasi altro provider, incluso Claude Platform on AWS42* **Subagents**: il [subagent Explore integrato](/docs/it/sub-agents#built-in-subagents) limita il suo modello ereditato a Opus sull'API Claude, e eredita il modello della conversazione principale direttamente su qualsiasi altro provider, incluso Claude Platform on AWS

43* **[Commands](/docs/it/commands#all-commands)**:43* **[Commands](/docs/it/commands#all-commands)**:

~~44 * `/design-sync` e `/import` con la sua forma di subcommand `claude import` non sono disponibili su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform on AWS~~44 * `/design-sync` e `/import` con la sua forma di subcommand `claude import` non sono disponibili su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform on AWS, e tramite un [gateway di app Claude](/docs/it/claude-apps-gateway#availability-and-limitations)

45 * `/voice` richiede un account claude.ai45 * `/voice` richiede un account claude.ai

46 * `/list-agents` e il suo alias `/peers` sono disponibili solo in sessioni dove [la messaggistica tra sessioni è abilitata](/docs/it/cross-session-messaging#availability)46 * `/list-agents` e il suo alias `/peers` sono disponibili solo in sessioni dove [la messaggistica tra sessioni è abilitata](/docs/it/cross-session-messaging#availability)

47 47

fullscreen.md +4 −2

Details

33 * Se è stato eseguito un rewind prima del primo messaggio, Claude Code si riavvia con una conversazione vuota33 * Se è stato eseguito un rewind prima del primo messaggio, Claude Code si riavvia con una conversazione vuota

34* La [modalità di autorizzazione](/docs/it/permission-modes) e il [livello di impegno](/docs/it/model-config#adjust-effort-level)34* La [modalità di autorizzazione](/docs/it/permission-modes) e il [livello di impegno](/docs/it/model-config#adjust-effort-level)

35* Il modello selezionato per ultimo con [`/model`](/docs/it/model-config#setting-your-model)35* Il modello selezionato per ultimo con [`/model`](/docs/it/model-config#setting-your-model)

~~36* Le regole passate con [`--allowed-tools` o `--disallowed-tools`](/docs/it/cli-reference#cli-flags), e i flag `--agent`, `--agents` e `--append-system-prompt`~~36* Le regole passate con [`--allowed-tools` o `--disallowed-tools`](/docs/it/cli-reference#cli-flags), e i flag `--agent`, `--agents`, `--append-system-prompt`, e `--system-prompt-snapshot`

37 37

38Claude Code rifiuta di riavviarsi se la sessione ha una restrizione che non può passare al processo riavviato. Le restrizioni che non può passare includono:38Claude Code rifiuta di riavviarsi se la sessione ha una restrizione che non può passare al processo riavviato. Le restrizioni che non può passare includono:

39 39

149 149

150Queste azioni sono riassociabili. Vedere [Azioni di scorrimento](/docs/it/keybindings#scroll-actions) per l'elenco completo dei nomi delle azioni, incluse le varianti di mezza pagina e pagina intera che non hanno un'associazione predefinita.150Queste azioni sono riassociabili. Vedere [Azioni di scorrimento](/docs/it/keybindings#scroll-actions) per l'elenco completo dei nomi delle azioni, incluse le varianti di mezza pagina e pagina intera che non hanno un'associazione predefinita.

151 151

152Mentre sei scorso verso l'alto, una riga di intestazione attenuata nella parte superiore della conversazione mostra il prompt più recente che è stato scorso al di sopra della vista. Fare clic sulla riga per saltare a quel prompt.

153

152<h3 id="auto-follow">154<h3 id="auto-follow">

153 Follow automatico155 Follow automatico

154</h3>156</h3>

179 181

180Un valore di `3` corrisponde all'impostazione predefinita in `vim` e applicazioni simili. L'impostazione accetta qualsiasi valore positivo fino a 20, inclusi valori frazionari inferiori a 1 come `0.25` per rallentare lo scorrimento accelerato del trackpad e della rotella del mouse nei terminali che amplificano già gli eventi della rotella.182Un valore di `3` corrisponde all'impostazione predefinita in `vim` e applicazioni simili. L'impostazione accetta qualsiasi valore positivo fino a 20, inclusi valori frazionari inferiori a 1 come `0.25` per rallentare lo scorrimento accelerato del trackpad e della rotella del mouse nei terminali che amplificano già gli eventi della rotella.

181 183

182Per regolare la velocità di scorrimento in modo interattivo, eseguire `/scroll-speed`. La finestra di dialogo mostra un righello che è possibile scorrere mentre è aperta in modo da poter sentire il cambiamento immediatamente. Premere `←` e `→` per regolare la velocità, `r` per ripristinare il valore predefinito rilevato automaticamente e `Invio` per salvare. La finestra di dialogo procede a step di numeri interi fino a 10 e sui terminali che supportano un controllo più fine offre anche step di un quarto fino a 0,25. Gli step di un quarto richiedono Claude Code v2.1.172 o versione successiva.184Per regolare la velocità di scorrimento in modo interattivo, eseguire `/scroll-speed`. La finestra di dialogo mostra un righello che è possibile scorrere mentre è aperta in modo da poter sentire il cambiamento immediatamente. Premere `←` e `→` per regolare la velocità, `r` per ripristinare il valore predefinito rilevato automaticamente e `Invio` per salvare. La finestra di dialogo procede a step di numeri interi fino a 10 e sui terminali che supportano un controllo più fine offre anche step di un quarto fino a 0,25.

183 185

184Il comando scrive lo stesso valore impostato dalla variabile di ambiente `CLAUDE_CODE_SCROLL_SPEED`, persistito in `~/.claude/settings.json`. Il massimo della finestra di dialogo è 10: se imposti un valore più alto tramite la variabile di ambiente, la finestra di dialogo mostra 10 e il salvataggio dalla finestra di dialogo persiste 10. Il comando non è disponibile nel terminale IDE JetBrains.186Il comando scrive lo stesso valore impostato dalla variabile di ambiente `CLAUDE_CODE_SCROLL_SPEED`, persistito in `~/.claude/settings.json`. Il massimo della finestra di dialogo è 10: se imposti un valore più alto tramite la variabile di ambiente, la finestra di dialogo mostra 10 e il salvataggio dalla finestra di dialogo persiste 10. Il comando non è disponibile nel terminale IDE JetBrains.

185 187

github-actions-cloud-providers.md +324 −0 created

Details

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.

5# Usa Claude Code GitHub Actions con i provider cloud

7> Esegui Claude Code GitHub Actions tramite Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry invece dell'API Claude

9[Claude Code GitHub Actions](/docs/it/github-actions) chiama l'API Claude per impostazione predefinita. Per instradare l'inferenza attraverso il tuo account cloud, imposta l'input del provider dell'azione GitHub di Claude Code e configura il tuo cloud per fidarsi del token OpenID Connect (OIDC) del flusso di lavoro. Il flusso di lavoro si autentica con quel token, quindi non memorizzi alcuna credenziale cloud di lunga durata nel tuo repository.

11<Info>

12 Questa pagina si basa sulla [configurazione di GitHub Actions](/docs/it/github-actions#setup). Presuppone che tu conosca già il file del flusso di lavoro e il passaggio `anthropics/claude-code-action`, e copre solo ciò che cambia un provider cloud.

13</Info>

15<h2 id="choose-your-provider">

16 Scegli il tuo provider

17</h2>

19Claude Code GitHub Action supporta tre provider e i passaggi di configurazione di seguito differiscono solo nella configurazione lato cloud. Usa quello dove la tua organizzazione ha già accesso ai modelli Claude. Comunichi all'azione GitHub di Claude Code quale provider utilizzare con un input nel blocco `with:` del passaggio `anthropics/claude-code-action`:

21* **Amazon Bedrock**: `use_bedrock: "true"`

22* **Google Cloud's Agent Platform**: `use_vertex: "true"`

23* **Microsoft Foundry**: `use_foundry: "true"`

25Gli esempi di flusso di lavoro completi nella sezione [Configura l'integrazione](#set-up-the-integration) includono già l'input per ogni provider.

27<h2 id="prerequisites">

28 Prerequisiti

29</h2>

31Prima di iniziare, hai bisogno di:

33* Accesso amministratore al repository dove viene eseguita l'azione GitHub di Claude Code, per installare un'app GitHub e aggiungere segreti

34* Autorizzazione per creare risorse di identità nel tuo account cloud: ruoli IAM e provider di identità OIDC su AWS, risorse Workload Identity Federation e account di servizio su Google Cloud, o applicazioni Microsoft Entra su Azure

35* Accesso ai modelli Claude sul tuo provider:

36 * **Amazon Bedrock**: accesso concesso ai modelli Claude. I profili di inferenza tra regioni, come gli ID modello `us.` negli esempi di questa pagina, necessitano dell'accesso concesso in ogni regione del loro gruppo di regioni. Vedi [Claude Code su Amazon Bedrock](/docs/it/amazon-bedrock)

37 * **Google Cloud's Agent Platform**: un progetto con l'API Agent Platform abilitata e accesso ai modelli Claude. Vedi [Claude Code su Google Cloud's Agent Platform](/docs/it/google-vertex-ai)

38 * **Microsoft Foundry**: una risorsa Foundry con una distribuzione di modello Claude. Vedi [Claude Code su Microsoft Foundry](/docs/it/microsoft-foundry)

40<h2 id="set-up-the-integration">

41 Configurare l'integrazione

42</h2>

44Oltre ai prerequisiti, è necessario creare quattro cose: un'identità GitHub per l'azione GitHub di Claude Code, la configurazione della fiducia lato cloud, i segreti del repository e il file del workflow. I passaggi seguenti illustrano ciascuno di essi.

46<Steps>

47 <Step title="Scegliere un'identità GitHub">

48 L'azione GitHub di Claude Code esegue il push dei commit e pubblica commenti attraverso un'identità GitHub. La [configurazione rapida](/docs/it/github-actions#quick-setup) installa l'app GitHub ufficiale di Claude per questo scopo. Con un provider cloud, scegli l'identità tu stesso:

50 * **App GitHub ufficiale di [Claude](https://github.com/apps/claude)**: installala nel repository, oppure salta al passaggio successivo se è già installata

51 * **App GitHub personalizzata**: crea la tua app, descritta di seguito, quando desideri solo i tre permessi che l'azione GitHub di Claude Code utilizza piuttosto che l'[insieme completo dell'app ufficiale](/docs/it/github-actions#github-app-permissions)

52 * **Token `GITHUB_TOKEN` automatico di GitHub**: nessuna app da creare o installare, ma GitHub non attiva i tuoi workflow CI sui commit effettuati con esso

54 Gli esempi di workflow nel quarto passaggio si autenticano con un'app personalizzata. Quel passaggio spiega anche cosa modificare per le altre due opzioni.

56 Per creare un'app personalizzata, [registra una nuova app GitHub](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) con i webhook disabilitati, poiché questa integrazione non li utilizza. Concedi tre permessi del repository:

58 * **Contents**: lettura e scrittura

59 * **Issues**: lettura e scrittura

60 * **Pull requests**: lettura e scrittura

62 Dopo aver registrato l'app, genera una chiave privata e conserva il file `.pem` scaricato, annota l'ID app dalla pagina delle impostazioni dell'app, e [installa l'app](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app) nel repository dove viene eseguita l'azione GitHub di Claude Code. Aggiungi la chiave e l'ID come segreti nel terzo passaggio.

63 </Step>

65 <Step title="Configurare l'autenticazione cloud">

66 Configura il tuo cloud per fidarsi del token OIDC che GitHub emette al workflow, in modo che ogni esecuzione del workflow ottenga credenziali cloud di breve durata. I punti elenco in ogni scheda riassumono cosa creare, e ogni scheda collega la guida del fornitore cloud per i passaggi a livello di console.

68 <Tabs>

69 <Tab title="Amazon Bedrock">

70 Crea la configurazione della fiducia nel tuo account AWS, seguendo la [guida AWS per la creazione di provider di identità OIDC](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html):

72 * Aggiungi un provider di identità OIDC GitHub con URL del provider `https://token.actions.githubusercontent.com` e audience `sts.amazonaws.com`

73 * Crea un ruolo IAM di cui il provider si fida come identità web, e allega la politica di invocazione con ambito dalla [configurazione IAM](/docs/it/amazon-bedrock#iam-configuration), che concede `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, e `bedrock:GetInferenceProfile`, insieme a due azioni di sottoscrizione `aws-marketplace`

74 * Limita la politica di fiducia del ruolo al tuo repository con una condizione di soggetto come `repo:your-org/your-repo:*`. Vedi la [guida di hardening OIDC di GitHub](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) per il formato del claim

76 Annota l'ARN del ruolo. Lo aggiungerai come segreto nel passaggio successivo.

77 </Tab>

79 <Tab title="Google Cloud's Agent Platform">

80 Crea le risorse di federazione nel tuo progetto Google Cloud, seguendo la [documentazione di Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation):

82 * Abilita tre API: IAM Credentials, Security Token Service (STS), e l'API Agent Platform, il cui nome del servizio è `aiplatform.googleapis.com`

83 * Crea un Workload Identity Pool con un provider OIDC GitHub il cui emittente è `https://token.actions.githubusercontent.com`, e aggiungi una condizione di attributo che limita il pool al tuo repository

84 * Crea un account di servizio dedicato con solo il ruolo `Vertex AI User`, che è `roles/aiplatform.user`, e consenti al pool di rappresentarlo

86 Annota il nome della risorsa completa del provider e l'indirizzo email dell'account di servizio. Li aggiungerai come segreti nel passaggio successivo.

87 </Tab>

89 <Tab title="Microsoft Foundry">

90 Crea un'applicazione Microsoft Entra con una credenziale federata per il tuo repository, seguendo [la guida di Microsoft per l'autenticazione da GitHub Actions](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect):

92 * Registra un'applicazione Microsoft Entra e aggiungi una credenziale di identità federata che si fida dei token che GitHub emette al tuo repository. Un'identità gestita assegnata dall'utente funziona al posto di un'applicazione. Entrambe hanno l'ID client che annoti di seguito

93 * Assegna all'applicazione il ruolo `Azure AI User` sulla tua risorsa Foundry. Vedi [configurazione RBAC di Azure](/docs/it/microsoft-foundry#azure-rbac-configuration) per un ruolo personalizzato più ristretto

95 Annota l'ID client dell'applicazione, il tuo ID tenant e il tuo ID sottoscrizione. Li aggiungerai come segreti nel passaggio successivo.

96 </Tab>

97 </Tabs>

98 </Step>

100 <Step title="Aggiungere i segreti del repository">

101 Nel repository dove viene eseguita l'azione GitHub di Claude Code, aggiungi i segreti per il tuo provider, più i due segreti dell'app se hai creato un'app GitHub personalizzata nel primo passaggio. Vedi la guida di GitHub su [come usare i segreti in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).

102

103 | Segreto | Necessario per | Valore |

104 | -------------------------------- | ----------------------------- | ------------------------------------------------- |

105 | `AWS_ROLE_TO_ASSUME` | Amazon Bedrock | L'ARN del ruolo IAM |

106 | `GCP_WORKLOAD_IDENTITY_PROVIDER` | Google Cloud's Agent Platform | Il nome della risorsa completa del provider |

107 | `GCP_SERVICE_ACCOUNT` | Google Cloud's Agent Platform | L'indirizzo email dell'account di servizio |

108 | `AZURE_CLIENT_ID` | Microsoft Foundry | L'ID client dell'applicazione Entra |

109 | `AZURE_TENANT_ID` | Microsoft Foundry | Il tuo ID tenant Microsoft Entra |

110 | `AZURE_SUBSCRIPTION_ID` | Microsoft Foundry | Il tuo ID sottoscrizione Azure |

111 | `APP_ID` | App GitHub personalizzata | L'ID dell'app GitHub |

112 | `APP_PRIVATE_KEY` | App GitHub personalizzata | Il contenuto del file della chiave privata `.pem` |

113 </Step>

114

115 <Step title="Creare il file del workflow">

116 Crea un file di workflow per il tuo provider, come `.github/workflows/claude.yml`. Ogni esempio risponde alle menzioni `@claude`, si autentica su GitHub con un'app personalizzata, e include il permesso `id-token: write`, che GitHub richiede per emettere il token OIDC che il tuo provider cloud scambia per le credenziali.

117

118 Se hai scelto un'identità GitHub diversa nel primo passaggio, regola l'esempio:

119

120 * **App GitHub ufficiale di Claude**: elimina il passaggio Generate GitHub App token e la riga `github_token`

121 * **Token automatico di GitHub**: elimina il passaggio di generazione del token e cambia la riga `github_token` in `github_token: ${{ secrets.GITHUB_TOKEN }}`

122

123 <Warning>

124 Nei repository pubblici, un commento contenente la frase di attivazione da qualsiasi utente avvia questo workflow. I passaggi delle credenziali vengono eseguiti prima che l'azione GitHub di Claude Code verifichi l'accesso in scrittura del commentatore, quindi l'azione rifiuta gli utenti non autorizzati solo dopo che il workflow ha generato un token dell'app e ha effettuato l'accesso al tuo provider cloud, il che lascia voci nel registro di audit e consuma minuti di Actions. Per evitare queste esecuzioni, aggiungi un passaggio che verifica l'accesso in scrittura del commentatore prima dei passaggi delle credenziali.

125 </Warning>

126

127 <Tabs>

128 <Tab title="Amazon Bedrock">

129 Sostituisci il valore `aws-region` con il tuo. Il passaggio delle credenziali lo esporta come `AWS_REGION` per il resto del job.

130

131 ```yaml theme={null}

132 name: Claude PR Action

133

134 permissions:

135 contents: write

136 pull-requests: write

137 issues: write

138 id-token: write

139

140 on:

141 issue_comment:

142 types: [created]

143 pull_request_review_comment:

144 types: [created]

145 issues:

146 types: [opened]

147

148 jobs:

149 claude-pr:

150 if: |

151 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

152 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

153 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

154 runs-on: ubuntu-latest

155 steps:

156 - name: Checkout repository

157 uses: actions/checkout@v6

158

159 - name: Generate GitHub App token

160 id: app-token

161 uses: actions/create-github-app-token@v2

162 with:

163 app-id: ${{ secrets.APP_ID }}

164 private-key: ${{ secrets.APP_PRIVATE_KEY }}

165

166 - name: Configure AWS Credentials (OIDC)

167 uses: aws-actions/configure-aws-credentials@v4

168 with:

169 role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}

170 aws-region: us-west-2

171

172 - uses: anthropics/claude-code-action@v1

173 with:

174 github_token: ${{ steps.app-token.outputs.token }}

175 use_bedrock: "true"

176 claude_args: '--model us.anthropic.claude-sonnet-4-6'

177 ```

178

179 <Tip>

180 Gli ID dei modelli Bedrock includono un prefisso del profilo di inferenza tra regioni come `us.`. Usa il prefisso per il gruppo di regioni dove hai concesso l'accesso al modello.

181 </Tip>

182 </Tab>

183

184 <Tab title="Google Cloud's Agent Platform">

185 Sostituisci il valore `CLOUD_ML_REGION` con il tuo. Non è necessario codificare l'ID del progetto, perché il workflow lo legge dall'output del passaggio `auth`.

186

187 ```yaml theme={null}

188 name: Claude PR Action

189

190 permissions:

191 contents: write

192 pull-requests: write

193 issues: write

194 id-token: write

195

196 on:

197 issue_comment:

198 types: [created]

199 pull_request_review_comment:

200 types: [created]

201 issues:

202 types: [opened]

203

204 jobs:

205 claude-pr:

206 if: |

207 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

208 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

209 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

210 runs-on: ubuntu-latest

211 steps:

212 - name: Checkout repository

213 uses: actions/checkout@v6

214

215 - name: Generate GitHub App token

216 id: app-token

217 uses: actions/create-github-app-token@v2

218 with:

219 app-id: ${{ secrets.APP_ID }}

220 private-key: ${{ secrets.APP_PRIVATE_KEY }}

221

222 - name: Authenticate to Google Cloud

223 id: auth

224 uses: google-github-actions/auth@v2

225 with:

226 workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}

227 service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

228

229 - uses: anthropics/claude-code-action@v1

230 with:

231 github_token: ${{ steps.app-token.outputs.token }}

232 use_vertex: "true"

233 claude_args: '--model claude-sonnet-5'

234 env:

235 ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}

236 CLOUD_ML_REGION: us-east5

237 ```

238 </Tab>

239

240 <Tab title="Microsoft Foundry">

241 Sostituisci `your-resource-name` con il nome della tua risorsa Foundry. Claude Code costruisce l'URL dell'endpoint da esso. Il passaggio `azure/login` effettua l'accesso con il token OIDC del workflow, e Claude Code raccoglie le credenziali attraverso la [catena di credenziali predefinita](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview) di Azure.

242

243 ```yaml theme={null}

244 name: Claude PR Action

245

246 permissions:

247 contents: write

248 pull-requests: write

249 issues: write

250 id-token: write

251

252 on:

253 issue_comment:

254 types: [created]

255 pull_request_review_comment:

256 types: [created]

257 issues:

258 types: [opened]

259

260 jobs:

261 claude-pr:

262 if: |

263 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

264 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

265 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

266 runs-on: ubuntu-latest

267 steps:

268 - name: Checkout repository

269 uses: actions/checkout@v6

270

271 - name: Generate GitHub App token

272 id: app-token

273 uses: actions/create-github-app-token@v2

274 with:

275 app-id: ${{ secrets.APP_ID }}

276 private-key: ${{ secrets.APP_PRIVATE_KEY }}

277

278 - name: Authenticate to Azure

279 uses: azure/login@v2

280 with:

281 client-id: ${{ secrets.AZURE_CLIENT_ID }}

282 tenant-id: ${{ secrets.AZURE_TENANT_ID }}

283 subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

284

285 - uses: anthropics/claude-code-action@v1

286 with:

287 github_token: ${{ steps.app-token.outputs.token }}

288 use_foundry: "true"

289 claude_args: '--model claude-sonnet-5'

290 env:

291 ANTHROPIC_FOUNDRY_RESOURCE: your-resource-name

292 ```

293

294 <Tip>

295 Usa un ID modello che corrisponda a un deployment di Claude nella tua risorsa Foundry. Vedi [Claude Code su Microsoft Foundry](/docs/it/microsoft-foundry) per la configurazione del modello e il pinning della versione.

296 </Tip>

297 </Tab>

298 </Tabs>

299

300 Con qualsiasi provider, puoi limitare la durata dell'esecuzione e il costo aggiungendo `--max-turns` a `claude_args`. Vedi [Gestire i costi](/docs/it/github-actions#manage-costs).

301 </Step>

302

303 <Step title="Testare la configurazione">

304 Menziona `@claude` in un commento su un issue o PR, quindi guarda l'esecuzione nella scheda Actions del repository. Claude risponde in un commento sullo stesso issue o PR.

305 </Step>

306</Steps>

307

308<h2 id="troubleshooting">

309 Risoluzione dei problemi

310</h2>

311

312Un'esecuzione non riuscita di solito si interrompe in uno di due punti:

313

314* **Errori di autenticazione**: di solito una configurazione OIDC errata. Verifica che il flusso di lavoro includa il permesso `id-token: write`, che la condizione del repository della configurazione di trust corrisponda esattamente al tuo repository, e che i nomi dei segreti nel tuo flusso di lavoro corrispondano a quelli che hai aggiunto

315* **Problemi di trigger e CI**: si comportano allo stesso modo di quando l'azione GitHub di Claude Code chiama l'API Claude. Vedi la [sezione di risoluzione dei problemi](/docs/it/github-actions#troubleshooting) della pagina principale e le [FAQ](https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md) dell'azione GitHub di Claude Code

316

317<h2 id="what’s-next">

318 Cosa fare dopo

319</h2>

320

321* [Claude Code GitHub Actions](/docs/it/github-actions) per esempi, parametri e best practice

322* [Claude Code su Amazon Bedrock](/docs/it/amazon-bedrock) per gli ID modello Bedrock e le regioni

323* [Claude Code su Google Cloud's Agent Platform](/docs/it/google-vertex-ai) per gli ID modello di Agent Platform e le regioni

324* [Claude Code su Microsoft Foundry](/docs/it/microsoft-foundry) per la configurazione del modello e dell'endpoint di Foundry

glossary.md +3 −3

Details

104 Checkpoint104 Checkpoint

105</h3>105</h3>

106 106

107Un punto di ripristino creato ad ogni prompt che invii. Claude Code acquisisce snapshot dei file prima di ogni modifica in modo che un checkpoint possa ripristinarli. Premi `Esc` due volte o esegui `/rewind` per ripristinare il codice, la conversazione o entrambi a un punto precedente, o per riassumere parte della conversazione da un messaggio selezionato. I checkpoint sono salvati con la conversazione, quindi una sessione ripresa può ancora `/rewind` verso di essi. Sono separati da git e non tracciano le modifiche apportate tramite lo strumento Bash.107Un punto di ripristino creato ad ogni prompt che invii che avvia un turno. Claude Code acquisisce snapshot dei file prima di ogni modifica in modo che un checkpoint possa ripristinarli. Premi `Esc` due volte o esegui `/rewind` per ripristinare il codice, la conversazione o entrambi a un punto precedente, o per riassumere parte della conversazione da un messaggio selezionato. I checkpoint sono salvati con la conversazione, quindi una sessione ripresa può ancora `/rewind` verso di essi. Sono separati da git e non tracciano le modifiche apportate tramite lo strumento Bash.

108 108

109Scopri di più: [Checkpointing](/docs/it/checkpointing)109Scopri di più: [Checkpointing](/docs/it/checkpointing)

110 110

120 CLAUDE.md120 CLAUDE.md

121</h3>121</h3>

122 122

123Un file markdown di istruzioni persistenti che scrivi per Claude, caricato all'inizio di ogni sessione come messaggio utente dopo il prompt di sistema. Metti qui le convenzioni di progetto, le note sull'architettura e le regole "fai sempre X". CLAUDE.md sopravvive alla [compaction](#compaction) e viene riletto fresco dal disco in seguito.123Un file markdown di istruzioni persistenti che scrivi per Claude, caricato all'inizio di ogni sessione come messaggio utente dopo il prompt di sistema. Metti qui le convenzioni di progetto, le note sull'architettura e le regole "fai sempre X". CLAUDE.md a livello di radice del progetto sopravvive alla [compaction](#compaction) e viene riletto fresco dal disco in seguito.

124 124

125Puoi posizionare CLAUDE.md a livello di progetto in `./CLAUDE.md` o `./.claude/CLAUDE.md`, a livello di utente in `~/.claude/CLAUDE.md`, o come [managed policy](#managed-settings) per la tua organizzazione. Tutti i file scoperti vengono concatenati nel contesto piuttosto che sovrascriversi a vicenda, ordinati dall'ambito più ampio al più specifico.125Puoi posizionare CLAUDE.md a livello di progetto in `./CLAUDE.md` o `./.claude/CLAUDE.md`, a livello di utente in `~/.claude/CLAUDE.md`, o come [managed policy](#managed-settings) per la tua organizzazione. Tutti i file scoperti vengono concatenati nel contesto piuttosto che sovrascriversi a vicenda, ordinati dall'ambito più ampio al più specifico.

126 126

266 Output style266 Output style

267</h3>267</h3>

268 268

269Una configurazione che modifica il prompt di sistema di Claude per cambiare il comportamento della risposta, il tono o il formato. A differenza di [CLAUDE.md](#claude-md), che Claude Code consegna come messaggio utente dopo il prompt di sistema, uno output style cambia il prompt di sistema stesso.269Una configurazione che modifica le istruzioni che Claude Code fornisce a Claude, per impostare il comportamento della risposta, il tono o il formato. A differenza di [CLAUDE.md](#claude-md), che aggiunge il contesto del progetto insieme alle istruzioni predefinite di Claude Code, uno stile di output personalizzato può sostituire le istruzioni predefinite di ingegneria del software.

270 270

271Scopri di più: [Output styles](/docs/it/output-styles)271Scopri di più: [Output styles](/docs/it/output-styles)

272 272

headless.md +10 −5

Details

207 207

208I messaggi dai [subagent](/docs/it/sub-agents) appaiono nel flusso come messaggi `assistant` e `user` il cui campo `parent_tool_use_id` è l'ID della chiamata dello strumento che ha generato il subagent. I messaggi dalla conversazione principale portano `null` in quel campo.208I messaggi dai [subagent](/docs/it/sub-agents) appaiono nel flusso come messaggi `assistant` e `user` il cui campo `parent_tool_use_id` è l'ID della chiamata dello strumento che ha generato il subagent. I messaggi dalla conversazione principale portano `null` in quel campo.

209 209

210Per impostazione predefinita, Claude Code emette solo i blocchi `tool_use` e `tool_result` dei subagent. Passa [`--forward-subagent-text`](/docs/it/cli-reference#cli-flags) o imposta [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/it/env-vars) per emettere anche i blocchi di testo e thinking dei subagent, in modo da poter ricostruire la trascrizione di ogni subagent. Questo richiede Claude Code v2.1.211 o successivo.210Il primo messaggio da un subagent in esecuzione in [primo piano](/docs/it/sub-agents#run-subagents-in-foreground-or-background) è un messaggio `user` che contiene il prompt che lo guida. Dopo quel primo messaggio, Claude Code emette:

211

212* **Per impostazione predefinita**: i blocchi `tool_use` e `tool_result` del subagent.

213* **Con [`--forward-subagent-text`](/docs/it/cli-reference#cli-flags) o [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/it/env-vars)**: anche i blocchi di testo e thinking del subagent, in modo da poter ricostruire la trascrizione di ogni subagent. Questo richiede Claude Code v2.1.211 o successivo.

211 214

212Quando abiliti una delle due opzioni, Claude Code inoltra i messaggi dai [subagent a ogni profondità di annidamento](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents): quando un subagent genera il suo subagent, i messaggi del subagent annidato portano l'ID della chiamata dello strumento Agent che lo ha generato in `parent_tool_use_id`, in modo da poter ricostruire l'albero di annidamento completo seguendo quegli ID. Prima della v2.1.219, i messaggi dai subagent annidati non apparivano nel flusso.215Quando abiliti una delle due opzioni, Claude Code inoltra i messaggi dai [subagent a ogni profondità di annidamento](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents): quando un subagent genera il suo subagent, i messaggi del subagent annidato portano l'ID della chiamata dello strumento Agent che lo ha generato in `parent_tool_use_id`, in modo da poter ricostruire l'albero di annidamento completo seguendo quegli ID. Prima della v2.1.219, i messaggi dai subagent annidati non apparivano nel flusso.

213 216

217Le skills che [vengono eseguite in un subagent](/docs/it/skills#run-skills-in-a-subagent) appaiono nel flusso allo stesso modo: il primo messaggio della skill biforcata è un messaggio `user` che contiene il contenuto della skill che guida l'esecuzione. Se abiliti una delle due opzioni, il flusso contiene anche i blocchi di testo e thinking della skill biforcata. Prima della v2.1.265, solo i blocchi `tool_use` e `tool_result` della skill biforcata apparivano nel flusso.

218

214<h4 id="handle-api-retries">219<h4 id="handle-api-retries">

215 Gestire i tentativi API220 Gestire i tentativi API

216</h4>221</h4>

228| `no_response` | object, opzionale | presente solo quando il tentativo non riuscito ha [ricevuto nessuna intestazione di risposta in tempo](/docs/it/errors#no-response-from-api). `waited_ms` è quanto tempo quel tentativo ha atteso e `retry_wait_ms` è quanto tempo il tentativo attenderà. In questi eventi, `max_retries` riflette il tentativo che questa causa normalmente ottiene, non il budget a livello di sessione. Richiede Claude Code v2.1.261 o successivo |233| `no_response` | object, opzionale | presente solo quando il tentativo non riuscito ha [ricevuto nessuna intestazione di risposta in tempo](/docs/it/errors#no-response-from-api). `waited_ms` è quanto tempo quel tentativo ha atteso e `retry_wait_ms` è quanto tempo il tentativo attenderà. In questi eventi, `max_retries` riflette il tentativo che questa causa normalmente ottiene, non il budget a livello di sessione. Richiede Claude Code v2.1.261 o successivo |

229| `error` | string | categoria di errore: `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, o `unknown` |234| `error` | string | categoria di errore: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, o `unknown` |

232 237

293Per impostare una linea di base per l'intera sessione invece di elencare i singoli strumenti, passa una [modalità di autorizzazione](/docs/it/permission-modes). Per `-p`, la [modalità di autorizzazione iniziale incorporata](/docs/it/permission-modes#which-mode-a-session-starts-in) è Manual su ogni piano, quindi passa la modalità di autorizzazione che desideri:298Per impostare una linea di base per l'intera sessione invece di elencare i singoli strumenti, passa una [modalità di autorizzazione](/docs/it/permission-modes). Per `-p`, la [modalità di autorizzazione iniziale incorporata](/docs/it/permission-modes#which-mode-a-session-starts-in) è Manual su ogni piano, quindi passa la modalità di autorizzazione che desideri:

294 299

295* **`auto`**: passa `--permission-mode auto` per avere un classificatore che esamini la maggior parte delle azioni invece di te300* **`auto`**: passa `--permission-mode auto` per avere un classificatore che esamini la maggior parte delle azioni invece di te

296* **`dontAsk`**: Claude Code nega qualsiasi cosa non sia nelle tue regole `permissions.allow` o nel [set di comandi di sola lettura](/docs/it/permissions#read-only-commands), utile per esecuzioni CI bloccate. `AskUserQuestion`, strumenti connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), e strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) vengono negati anche quando una regola di autorizzazione corrisponde301* **`dontAsk`**: Claude Code nega qualsiasi cosa che comporterebbe altrimenti un prompt, il che è utile per esecuzioni CI bloccate. Le azioni che non necessitano di approvazione in modalità Manual vengono comunque eseguite, come le letture di file nelle tue directory di lavoro e il [set di comandi di sola lettura](/docs/it/permissions#read-only-commands), così come le azioni coperte dalle tue voci `--allowedTools` o dalle regole `permissions.allow`. `AskUserQuestion`, strumenti connettore [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), e strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) vengono negati anche quando una regola di autorizzazione corrisponde

297* **`acceptEdits`**: Claude scrive file senza chiedere, e Claude Code approva automaticamente i comandi del filesystem comuni come `mkdir`, `touch`, `mv` e `cp`. Le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque. A parte il set di comandi di sola lettura, altri comandi shell e richieste di rete hanno ancora bisogno di una voce `--allowedTools` o di una regola `permissions.allow`. Consulta [cosa `acceptEdits` approva automaticamente](/docs/it/permission-modes#auto-approve-file-edits-with-acceptedits-mode) per l'elenco completo302* **`acceptEdits`**: Claude scrive file senza chiedere, e Claude Code approva automaticamente i comandi del filesystem comuni come `mkdir`, `touch`, `mv` e `cp`. Le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque. A parte il set di comandi di sola lettura, altri comandi shell e richieste di rete hanno ancora bisogno di una voce `--allowedTools` o di una regola `permissions.allow`. Consulta [cosa `acceptEdits` approva automaticamente](/docs/it/permission-modes#auto-approve-file-edits-with-acceptedits-mode) per l'elenco completo

298 303

299Questo esempio applica le correzioni di lint con `acceptEdits` come linea di base:304Questo esempio applica le correzioni di lint con `acceptEdits` come linea di base:

hooks-guide.md +42 −37

Details

499 499

500Claude Code attiva eventi hook in punti specifici del suo ciclo di vita. Quando un evento si attiva, Claude Code esegue tutti gli hooks corrispondenti in parallelo; consultate [Campi del gestore hook](/docs/it/hooks#hook-handler-fields) per come vengono trattati i gestori duplicati. La tabella sottostante mostra ogni evento e quando si attiva:500Claude Code attiva eventi hook in punti specifici del suo ciclo di vita. Quando un evento si attiva, Claude Code esegue tutti gli hooks corrispondenti in parallelo; consultate [Campi del gestore hook](/docs/it/hooks#hook-handler-fields) per come vengono trattati i gestori duplicati. La tabella sottostante mostra ogni evento e quando si attiva:

501 501

502| Event | When it fires |502| Evento | Quando si attiva |

503| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |503| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

505| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |505| `Setup` | Quando avvii Claude Code con `--init-only`, o con `--init` o `--maintenance` in modalità `-p`. Per la preparazione una tantum in CI o script |

507| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |507| `UserPromptExpansion` | Quando un comando digitato dall'utente si espande in un prompt, prima che raggiunga Claude. Può bloccare l'espansione |

510| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |510| `PermissionDenied` | Quando la modalità automatica nega una chiamata a uno strumento, inclusi i rifiuti senza un verdetto del classificatore. Utilizza JSON `hookSpecificOutput.retry: true` per indicare al modello che può riprovare la chiamata allo strumento negata. Claude Code ignora `retry` quando il classificatore non ha prodotto alcun verdetto |

523| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |523| `InstructionsLoaded` | Quando un file CLAUDE.md o `.claude/rules/*.md` viene caricato nel contesto. Si attiva all'inizio della sessione e quando i file vengono caricati in modo pigro durante una sessione |

525| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |525| `CwdChanged` | Quando la directory di lavoro cambia, ad esempio quando Claude esegue un comando `cd`. Utile per la gestione reattiva dell'ambiente con strumenti come direnv |

526| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |526| `DirectoryAdded` | Quando una directory di lavoro viene aggiunta a metà sessione tramite `/add-dir` o la richiesta di controllo SDK `register_repo_root` |

528| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |528| `WorktreeCreate` | Quando un worktree viene creato tramite `--worktree`, `isolation: "worktree"`, o per una sessione in background. Sostituisce il comportamento git predefinito |

529| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |529| `WorktreeRemove` | Quando un worktree viene rimosso all'uscita della sessione, quando un subagente termina, o quando elimini una sessione in background |

532| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |532| `PreModelSwitch` | Prima che Claude Code applichi un cambio di modello che hai richiesto tu o un client. Può bloccare il cambio |

533| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session |533| `PostModelSwitch` | Dopo che il modello della sessione cambia, inclusi i cambiamenti che Claude Code effettua autonomamente, come il ripristino del modello quando riprendi una sessione |

537 537

538Ogni hook ha un `type` che determina come si esegue. La maggior parte degli hooks utilizza `"type": "command"`, che esegue un comando shell. Sono disponibili altri quattro tipi:538Ogni hook ha un `type` che determina come si esegue. La maggior parte degli hooks utilizza `"type": "command"`, che esegue un comando shell. Sono disponibili altri quattro tipi:

539 539

734| `StopFailure` | tipo di errore | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` |734| `StopFailure` | tipo di errore | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, `unknown` |

1077 Hook JSON non ha effetto1077 Hook JSON non ha effetto

1078</h3>1078</h3>

1079 1079

1080Il vostro hook stampa JSON valido, ma la decisione non ha effetto e nessun errore appare nella trascrizione.1080Il vostro hook stampa JSON valido, ma la decisione non ha effetto e nessun errore appare nella trascrizione. Controllate quale causa si applica:

1081

1082* **Output extra prima del JSON**: qualcos'altro scrive su stdout per primo, solitamente un `echo` incondizionato nel vostro profilo shell, quindi l'output non inizia più con `{` e Claude Code non lo analizza come JSON. La causa e la soluzione seguono questo elenco.

1083* **Un campo al livello sbagliato**: confrontate il posizionamento di ogni campo rispetto al formato [JSON output](/docs/it/hooks#json-output). Ad esempio, `permissionDecision` appartiene dentro `hookSpecificOutput`, non al livello superiore.

1081 1084

1082Quando Claude Code esegue un hook di comando in forma shell, uno senza `args`, genera `sh -c` su macOS e Linux, Git Bash su Windows, o PowerShell quando Git Bash non è installato per impostazione predefinita. Questa shell è non interattiva, ma Git Bash e alcune configurazioni, come `BASH_ENV` che punta a `~/.bashrc`, comunque forniscono il vostro profilo. Se quel profilo contiene istruzioni `echo` incondizionate, l'output viene anteposto al vostro JSON dell'hook:1085Quando Claude Code esegue un hook di comando in forma shell, uno senza `args`, genera `sh -c` su macOS e Linux, Git Bash su Windows, o PowerShell quando Git Bash non è installato per impostazione predefinita. Questa shell è non interattiva, ma Git Bash e alcune configurazioni, come `BASH_ENV` che punta a `~/.bashrc`, comunque forniscono il vostro profilo. Se quel profilo contiene istruzioni `echo` incondizionate, l'output viene anteposto al vostro JSON dell'hook:

1083 1086

1097 1100

1098La variabile `$-` contiene i flag della shell, e `i` significa interattiva. Gli hooks si eseguono in shell non interattive, quindi l'echo viene saltato.1101La variabile `$-` contiene i flag della shell, e `i` significa interattiva. Gli hooks si eseguono in shell non interattive, quindi l'echo viene saltato.

1099 1102

1103Quando il vostro hook restituisce `permissionDecision` o `additionalContext` al livello superiore invece che dentro `hookSpecificOutput`, il JSON comunque si analizza, e Claude Code ignora i campi posizionati male senza segnalare un errore. Per vedere quali campi ha ignorato, avviate Claude Code con `claude --debug` e cercate nel [debug log](/docs/it/hooks#debug-hooks) `Hook JSON output had unrecognized keys`.

1104

1100<h3 id="debug-techniques">1105<h3 id="debug-techniques">

1101 Tecniche di debug1106 Tecniche di debug

1102</h3>1107</h3>

interactive-mode.md +37 −2

Details

141 141

142Consulta il [riferimento dei comandi](/docs/it/commands) per l'elenco completo dei comandi inclusi in Claude Code.142Consulta il [riferimento dei comandi](/docs/it/commands) per l'elenco completo dei comandi inclusi in Claude Code.

143 143

144<h3 id="complete-a-command-mid-prompt">

145 Completare un comando a metà del prompt

146</h3>

147

148Il completamento dei comandi funziona anche a metà di un prompt: digita `/` dopo uno spazio, quindi le prime lettere di un nome, come in `esegui i test, quindi /com`. Solo i comandi i cui nomi iniziano con quelle lettere corrispondono, quindi un percorso di file come `/tmp/notes.md` non mantiene un elenco aperto. Claude Code esegue un comando solo quando il comando [inizia il tuo messaggio](/docs/it/commands).

149

150* **Nel [rendering a schermo intero](/docs/it/fullscreen)**: i risultati si aprono come un elenco mentre digiti, senza alcuna riga evidenziata, quindi `Invio` invia comunque il tuo prompt così come digitato. Premi `Tab` per inserire il risultato principale, oppure seleziona una riga con i tasti freccia e `Invio`.

151* **Al di fuori dello schermo intero**: il resto del risultato principale appare come testo fantasma al tuo cursore, con un conteggio come `+2` quando più comandi corrispondono. Premi `Tab` per inserire l'unico risultato, oppure per aprire l'elenco quando più risultati corrispondono, quindi seleziona una riga con i tasti freccia e `Invio`.

152

153In entrambi i renderer, premi `Tab` su un `/` nudo a metà prompt per elencare ogni comando.

154

155Una skill di plugin corrisponde anche al suo nome nudo, quindi `/deploy` trova una skill denominata `myplugin:deploy-app`. Quando inserisci il risultato, Claude Code scrive il `/myplugin:deploy-app` completo.

156

144<h2 id="vim-editor-mode">157<h2 id="vim-editor-mode">

145 Modalità editor Vim158 Modalità editor Vim

146</h2>159</h2>

371* Uscite con `Escape`, `Backspace`, o `Ctrl+U` su un prompt vuoto384* Uscite con `Escape`, `Backspace`, o `Ctrl+U` su un prompt vuoto

372* Incollare testo che inizia con `!` in un prompt vuoto entra automaticamente in modalità shell, corrispondendo al comportamento di `!` digitato385* Incollare testo che inizia con `!` in un prompt vuoto entra automaticamente in modalità shell, corrispondendo al comportamento di `!` digitato

373 386

374In una sessione interattiva regolare, i comandi che digitate in modalità shell vengono eseguiti al di fuori della [sandbox](/docs/it/sandboxing) anche quando avete abilitato il sandboxing, perché la sandbox si applica ai comandi che Claude esegue. Vedere [modalità sandbox rigorosa](/docs/it/sandboxing#the-unsandboxed-retry-escape-hatch) per le sessioni in cui i comandi in modalità shell vengono eseguiti anche in sandbox, come le sessioni in background con modalità sandbox rigorosa attivata.387A meno che la vostra sessione non sia una di quelle elencate in [modalità sandbox rigorosa](/docs/it/sandboxing#the-unsandboxed-retry-escape-hatch), i comandi che digitate in modalità shell vengono eseguiti al di fuori della [sandbox](/docs/it/sandboxing) anche quando avete abilitato il sandboxing, perché la sandbox si applica ai comandi che Claude esegue.

375 388

376Claude risponde automaticamente all'output del comando una volta che arriva nella trascrizione, quindi potete eseguire `! npm test` e ottenere una spiegazione degli errori senza un secondo prompt. La risposta costa lo stesso di inviare un prompt normale. Per ripristinare il comportamento precedente in cui l'output viene aggiunto al contesto senza una risposta, impostare [`respondToBashCommands`](/docs/it/settings-reference#respondtobashcommands) a `false` in `settings.json`. Prima della v2.1.186, la modalità shell aggiungeva sempre l'output al contesto senza una risposta.389Claude risponde automaticamente all'output del comando una volta che arriva nella trascrizione, quindi potete eseguire `! npm test` e ottenere una spiegazione degli errori senza un secondo prompt. La risposta costa lo stesso di inviare un prompt normale. Per ripristinare il comportamento precedente in cui l'output viene aggiunto al contesto senza una risposta, impostare [`respondToBashCommands`](/docs/it/settings-reference#respondtobashcommands) a `false` in `settings.json`. Prima della v2.1.186, la modalità shell aggiungeva sempre l'output al contesto senza una risposta.

377 390

577 590

578Esegui `/diff` per rivedere le modifiche nel tuo albero di lavoro senza lasciare Claude Code. Vedrai le modifiche che Claude ha apportato finora insieme a qualsiasi altra cosa che non hai ancora committato.591Esegui `/diff` per rivedere le modifiche nel tuo albero di lavoro senza lasciare Claude Code. Vedrai le modifiche che Claude ha apportato finora insieme a qualsiasi altra cosa che non hai ancora committato.

579 592

593Nelle modifiche che `/diff` legge da git, un submodule appare come una singola voce, e solo quando cambia il commit a cui punta; le modifiche ai file all'interno del submodule non appaiono lì.

594

580Nel [rendering a schermo intero](/docs/it/fullscreen), `/diff` apre il [pannello diff](#diff-panel) accanto alla conversazione, che rimane aperto e si aggiorna mentre continui a lavorare. Nel renderer classico, `/diff` apre il [visualizzatore diff](#diff-viewer) al posto del prompt, e lo chiudi quando hai finito di leggere.595Nel [rendering a schermo intero](/docs/it/fullscreen), `/diff` apre il [pannello diff](#diff-panel) accanto alla conversazione, che rimane aperto e si aggiorna mentre continui a lavorare. Nel renderer classico, `/diff` apre il [visualizzatore diff](#diff-viewer) al posto del prompt, e lo chiudi quando hai finito di leggere.

581 596

582<h3 id="diff-panel">597<h3 id="diff-panel">

664 679

665L'elenco attività è la lista di controllo di Claude: elementi che Claude ha creato per pianificare il lavoro multi-step, con indicatori che mostrano cosa è in sospeso, in corso o completato. È separato dalla visualizzazione delle attività in background. Per visualizzare shell in esecuzione e subagent, utilizzare [`/tasks`](/docs/it/commands) invece.680L'elenco attività è la lista di controllo di Claude: elementi che Claude ha creato per pianificare il lavoro multi-step, con indicatori che mostrano cosa è in sospeso, in corso o completato. È separato dalla visualizzazione delle attività in background. Per visualizzare shell in esecuzione e subagent, utilizzare [`/tasks`](/docs/it/commands) invece.

666 681

667Su [Opus 4.8, Sonnet 5, Fable 5, Mythos 5 e versioni successive di queste famiglie](/docs/it/tools-reference#task-tool-availability), Claude tiene traccia del lavoro multi-step senza una lista di controllo scritta, e Claude Code non fornisce gli strumenti che riempiono questo elenco, quindi rimane vuoto. Se desiderate l'elenco attività su questi modelli comunque, attivate con `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` o uno degli altri modi in [Disponibilità dello strumento Task](/docs/it/tools-reference#task-tool-availability). Su modelli precedenti come Opus 4.7, e dopo che avete attivato, l'elenco attività funziona come segue:682L'elenco si riempie solo nelle sessioni che dispongono degli strumenti di tracciamento delle attività, che Claude Code fornisce per impostazione predefinita su [modelli Claude 3.x, Opus 4 fino a 4.7, Sonnet 4 fino a 4.6 e Haiku 4.5](/docs/it/tools-reference#task-tool-availability). Su qualsiasi altro modello, incluso un ID modello che Claude Code non riconosce, l'elenco rimane vuoto a meno che non optiate per `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` o uno degli altri modi in [Disponibilità dello strumento Task](/docs/it/tools-reference#task-tool-availability). Quando la sessione dispone degli strumenti, l'elenco attività funziona come segue:

668 683

669* Premere `Ctrl+T` per attivare/disattivare la visualizzazione dell'elenco attività. La visualizzazione mostra fino a cinque attività alla volta. Quando Claude non ha ancora creato elementi della lista di controllo, l'attivazione non ha effetto visibile perché non c'è nulla da visualizzare684* Premere `Ctrl+T` per attivare/disattivare la visualizzazione dell'elenco attività. La visualizzazione mostra fino a cinque attività alla volta. Quando Claude non ha ancora creato elementi della lista di controllo, l'attivazione non ha effetto visibile perché non c'è nulla da visualizzare

670* Se lasciate l'elenco espanso, Claude Code ripristina la visualizzazione espansa la prossima volta che avviate una sessione che contiene ancora attività, ad esempio con `--resume` o `--continue`. Quando l'elenco attività è vuoto, Claude Code lo avvia compresso685* Se lasciate l'elenco espanso, Claude Code ripristina la visualizzazione espansa la prossima volta che avviate una sessione che contiene ancora attività, ad esempio con `--resume` o `--continue`. Quando l'elenco attività è vuoto, Claude Code lo avvia compresso

793 808

794Claude Code ignora le variabili di ambiente del token di `glab`, come `GITLAB_TOKEN`, quando controlla lo stato, quindi non ottenete alcun badge da un token esportato da solo. Claude Code cerca anche `glab` e il suo login una volta per sessione, quindi riavviate Claude Code dopo aver installato `glab` o aver eseguito `glab auth login`.809Claude Code ignora le variabili di ambiente del token di `glab`, come `GITLAB_TOKEN`, quando controlla lo stato, quindi non ottenete alcun badge da un token esportato da solo. Claude Code cerca anche `glab` e il suo login una volta per sessione, quindi riavviate Claude Code dopo aver installato `glab` o aver eseguito `glab auth login`.

795 810

811<h2 id="issue-reference-links">

812 Link di riferimento ai problemi

813</h2>

814

815Quando Claude menziona un problema come `owner/repo#123`, potete fare clic sul riferimento per aprirlo, purché il vostro terminale supporti i hyperlink. Se Claude Code non rileva il supporto dei hyperlink nel vostro terminale, impostate [`FORCE_HYPERLINK`](/docs/it/env-vars) su `1` per attivare i link, oppure su `0` per mantenere i riferimenti come testo semplice.

816

817Ottenete un link solo per il modulo a due parti `owner/repo#123`. Questi rimangono come testo semplice:

818

819* Un `#123` isolato

820* Un percorso GitLab annidato come `group/subgroup/project#123`

821* Qualsiasi riferimento all'interno di uno span di codice o di un blocco di codice

822

823Claude Code costruisce il link per l'host del repository che identifica dal vostro git remote, non per il repository che il riferimento nomina:

824

825| Host del vostro repository | Dove `owner/repo#123` si collega |

826| :------------------------------------------------------------------------------ | :----------------------------------------------------- |

827| github.com, un host GitHub Enterprise, o qualsiasi host non elencato di seguito | `https://<host>/owner/repo/issues/123` |

828| gitlab.com | `https://gitlab.com/owner/repo/-/issues/123` |

829| bitbucket.org, codeberg.org, o gitea.com | Nessun link; il riferimento rimane come testo semplice |

830

796<h2 id="see-also">831<h2 id="see-also">

797 Vedere anche832 Vedere anche

798</h2>833</h2>

keybindings.md +5 −1

Details

505ctrl+k ctrl+s Premi Ctrl+K, rilascia, quindi Ctrl+S505ctrl+k ctrl+s Premi Ctrl+K, rilascia, quindi Ctrl+S

506```506```

507 507

508Premere ogni sequenza di tasti entro 3 secondi da quella precedente. Se si attende più a lungo, Claude Code annulla l'accordo e mostra un breve avviso che lo comunica.

509

508<h3 id="special-keys">510<h3 id="special-keys">

509 Tasti speciali511 Tasti speciali

510</h3>512</h3>

540 542

541Questo funziona anche per i binding degli accordi. Annullare l'associazione di ogni accordo che condivide un prefisso libera quel prefisso per l'uso come binding a tasto singolo. Un accordo in qualsiasi contesto attivo mantiene il suo prefisso riservato, quindi è necessario annullare l'associazione di ogni accordo nel contesto che lo definisce.543Questo funziona anche per i binding degli accordi. Annullare l'associazione di ogni accordo che condivide un prefisso libera quel prefisso per l'uso come binding a tasto singolo. Un accordo in qualsiasi contesto attivo mantiene il suo prefisso riservato, quindi è necessario annullare l'associazione di ogni accordo nel contesto che lo definisce.

542 544

543Claude Code associa questi accordi predefiniti sul prefisso `ctrl+x`: `ctrl+x ctrl+k`, `ctrl+x ctrl+e`, e `ctrl+x enter` in `Chat`, `ctrl+x ctrl+b` in `Task`, e `ctrl+x b` in `DiffPanel`. L'accordo `ctrl+x enter` richiede v2.1.247 o successivo, e `ctrl+x b` richiede v2.1.260 o successivo. Per reclamare `ctrl+x` stesso come binding a tasto singolo, annullare l'associazione di tutti loro:545Claude Code associa questi accordi predefiniti sul prefisso `ctrl+x`: `ctrl+x ctrl+k`, `ctrl+x ctrl+e`, `ctrl+x enter`, `ctrl+x ctrl+a`, e `ctrl+x tab` in `Chat`, `ctrl+x ctrl+b` in `Task`, e `ctrl+x b` in `DiffPanel`. L'accordo `ctrl+x enter` richiede v2.1.247 o successivo, e `ctrl+x b`, `ctrl+x ctrl+a`, e `ctrl+x tab` richiedono v2.1.260 o successivo. Per reclamare `ctrl+x` stesso come binding a tasto singolo, annullare l'associazione di tutti loro:

544 546

545```json theme={null}547```json theme={null}

546{548{

563 "ctrl+x ctrl+k": null,565 "ctrl+x ctrl+k": null,

564 "ctrl+x ctrl+e": null,566 "ctrl+x ctrl+e": null,

565 "ctrl+x enter": null,567 "ctrl+x enter": null,

568 "ctrl+x ctrl+a": null,

569 "ctrl+x tab": null,

566 "ctrl+x": "chat:newline"570 "ctrl+x": "chat:newline"

567 }571 }

568 }572 }

large-codebases.md +18 −18

Details

176Le regole di negazione possono coprire tutti coloro che lavorano nel repository, solo voi, o ogni sessione sulla macchina, a seconda di quale file di impostazioni vi inserite:176Le regole di negazione possono coprire tutti coloro che lavorano nel repository, solo voi, o ogni sessione sulla macchina, a seconda di quale file di impostazioni vi inserite:

177 177

178* **Tutti coloro che lavorano nel repository**: impegnate le regole a `.claude/settings.json`, alla radice del repository se avviate Claude lì, o in ogni `.claude/` del pacchetto se avviate da sottodirectory. Come altre impostazioni di progetto su questa pagina, quel file non viene ereditato dalle directory padre.178* **Tutti coloro che lavorano nel repository**: impegnate le regole a `.claude/settings.json`, alla radice del repository se avviate Claude lì, o in ogni `.claude/` del pacchetto se avviate da sottodirectory. Come altre impostazioni di progetto su questa pagina, quel file non viene ereditato dalle directory padre.

179* **Solo voi**: usate `.claude/settings.local.json` alla radice del repository, che si carica in ogni sessione CLI all'interno del repository indipendentemente dalla directory di avvio, tranne nei casi in cui Claude Code [non utilizza la radice del repository](/docs/it/settings#where-claude-code-looks-for-each-file), come su Windows. I modelli relativi come l'esempio `Read(./vendor/**)` ancora [si ancorano alla directory di lavoro corrente della sessione](/docs/it/permissions#read-and-edit) piuttosto che alla radice del repository, quindi se avviate sessioni da sottodirectory, scrivete le regole in questo file come percorsi assoluti `//`, come `Read(//absolute/path/to/repo/vendor/**)`. Prima della v2.1.211, `.claude/settings.local.json` si caricava anche solo dalla directory di avvio.179* **Solo voi**: usate `.claude/settings.local.json` alla radice del repository, che si carica in ogni sessione CLI all'interno del repository indipendentemente dalla directory di avvio, tranne nei casi in cui Claude Code [non utilizza la radice del repository](/docs/it/settings#where-claude-code-looks-for-each-file), come su Windows. I modelli relativi come l'esempio `Read(./**/vendor/**/*)` ancora [si ancorano alla directory di lavoro corrente della sessione](/docs/it/permissions#read-and-edit) piuttosto che alla radice del repository, quindi se avviate sessioni da sottodirectory, scrivete le regole in questo file come percorsi assoluti `//`, come `Read(//absolute/path/to/repo/**/vendor/**/*)`. Prima della v2.1.211, `.claude/settings.local.json` si caricava anche solo dalla directory di avvio.

180* **Tutti, applicato in ogni sessione**: impostate le regole in [impostazioni gestite](/docs/it/managed-settings), che le impostazioni utente e progetto non possono ignorare.180* **Tutti, applicato in ogni sessione**: impostate le regole in [impostazioni gestite](/docs/it/managed-settings), che le impostazioni utente e progetto non possono ignorare.

181 181

182L'esempio sottostante blocca gli artefatti di build e un SDK venduto:182L'esempio sottostante blocca gli artefatti di build e un SDK venduto. I suoi modelli di directory terminano con `/**/*` piuttosto che `/**` in modo che ogni regola copra tutto all'interno della directory ma non la directory stessa. Claude può quindi ancora elencare quelle directory o cambiarvi dentro, ad esempio con `ls dist` o `cd build`.

183 183

184```json .claude/settings.json theme={null}184```json .claude/settings.json theme={null}

185{185{

186 "permissions": {186 "permissions": {

187 "deny": [187 "deny": [

188 "Read(./**/dist/**)",188 "Read(./**/dist/**/*)",

189 "Read(./**/build/**)",189 "Read(./**/build/**/*)",

190 "Read(./**/*.generated.*)",190 "Read(./**/*.generated.*)",

191 "Read(./vendor/**)"191 "Read(./**/vendor/**/*)"

192 ]192 ]

193 }193 }

194}194}

422Ad esempio, puoi scrivere uno script che legge la directory di avvio dall'[input dell'hook](/docs/it/hooks#common-input-fields), la cerca in una mappa percorso-a-plugin impegnata al repository, e stampa la raccomandazione per Claude da trasmettere nella sua prima risposta. Vedi [Automatizza azioni con hook](/docs/it/hooks-guide) per scrivere e registrare l'hook.422Ad esempio, puoi scrivere uno script che legge la directory di avvio dall'[input dell'hook](/docs/it/hooks#common-input-fields), la cerca in una mappa percorso-a-plugin impegnata al repository, e stampa la raccomandazione per Claude da trasmettere nella sua prima risposta. Vedi [Automatizza azioni con hook](/docs/it/hooks-guide) per scrivere e registrare l'hook.

423 423

424<h2 id="put-it-together">424<h2 id="put-it-together">

425 Mettilo insieme425 Mettere tutto insieme

426</h2>426</h2>

427 427

428La configurazione combinata sottostante usa il layout del monorepo. Gli stessi file funzionano per qualsiasi sottodirectory in un albero singolo di grandi dimensioni. Le impostazioni di progetto si caricano solo dalla directory da cui avvii Claude, quindi il `.claude/settings.json` di ogni sottodirectory deve essere autonomo piuttosto che stratificato su un file radice.428La configurazione combinata di seguito utilizza il layout monorepo. Gli stessi file funzionano per qualsiasi sottodirectory in un grande albero singolo. Il `.claude/settings.json` di ogni sottodirectory deve essere autonomo piuttosto che stratificato su un file radice.

429 429

430L'esempio impegna `worktree`, `additionalDirectories` e le regole di negazione `Read` in `.claude/settings.json` in modo che ogni sviluppatore in `packages/api/` ottenga lo stesso accesso ai fratelli, percorsi sparse e esclusioni. Il file sottostante è le impostazioni per area impegnate per `packages/api/`:430L'esempio esegue il commit di `worktree`, `additionalDirectories` e le regole di negazione `Read` in `.claude/settings.json` in modo che ogni sviluppatore in `packages/api/` ottenga lo stesso accesso ai sibling, percorsi sparsi ed esclusioni. Il file di seguito è la configurazione per area impegnata per `packages/api/`:

431 431

432```json packages/api/.claude/settings.json theme={null}432```json packages/api/.claude/settings.json theme={null}

433{433{

446 "../shared"446 "../shared"

447 ],447 ],

448 "deny": [448 "deny": [

449 "Read(./**/dist/**)",449 "Read(./**/dist/**/*)",

450 "Read(./**/build/**)"450 "Read(./**/build/**/*)"

451 ]451 ]

452 }452 }

453}453}

454```454```

455 455

456Poiché questa sessione avvia da `packages/api/`, i file CLAUDE.md dei pacchetti fratelli sono già fuori ambito, quindi `claudeMdExcludes` non è necessario qui. Aggiungilo a `.claude/settings.local.json` della radice del repository invece se avvii anche sessioni dalla radice.456Poiché questa sessione inizia da `packages/api/`, i file CLAUDE.md dei pacchetti sibling sono già fuori portata, quindi `claudeMdExcludes` non è necessario qui. Aggiungetelo invece al `.claude/settings.local.json` della radice del repository se avviate anche sessioni dalla radice.

457 457

458La voce `additionalDirectories` si applica quando avvii Claude da `packages/api/` direttamente. Dentro un worktree creato da questa sessione, la directory di lavoro è la radice del worktree, quindi questo file di impostazioni non si carica. I pacchetti fratelli sono già raggiungibili dentro il worktree senza di esso, ma le regole di negazione hanno bisogno di una seconda copia in `.claude/settings.json` della radice del repository in modo che le sessioni del worktree le raccolgano, come la [nota delle impostazioni del worktree](#check-out-only-the-directories-you-need) descrive:458La voce `additionalDirectories` si applica quando avviate Claude da `packages/api/` direttamente. All'interno di un worktree creato da questa sessione, la directory di lavoro è la radice del worktree, quindi questo file di impostazioni non si carica. I pacchetti sibling sono già raggiungibili all'interno del worktree senza di esso, ma le regole di negazione hanno bisogno di una seconda copia nel `.claude/settings.json` della radice del repository in modo che le sessioni worktree le raccolgano, come la [nota sulle impostazioni worktree](#check-out-only-the-directories-you-need) descrive:

459 459

460```json .claude/settings.json theme={null}460```json .claude/settings.json theme={null}

461{461{

462 "permissions": {462 "permissions": {

463 "deny": [463 "deny": [

464 "Read(./**/dist/**)",464 "Read(./**/dist/**/*)",

465 "Read(./**/build/**)"465 "Read(./**/build/**/*)"

466 ]466 ]

467 }467 }

468}468}

473```text theme={null}473```text theme={null}

474monorepo/474monorepo/

475 CLAUDE.md475 CLAUDE.md

476 .claude/settings.json # regole di negazione per sessioni del worktree476 .claude/settings.json # deny rules for worktree sessions

477 packages/477 packages/

478 api/478 api/

479 CLAUDE.md479 CLAUDE.md

480 .claude/settings.json # worktree, additionalDirectories, regole di negazione480 .claude/settings.json # worktree, additionalDirectories, deny rules

481 .claude/skills/api-testing/SKILL.md481 .claude/skills/api-testing/SKILL.md

482 web/482 web/

483 CLAUDE.md483 CLAUDE.md

488 488

489Con questa configurazione, avviando Claude da `packages/api/`:489Con questa configurazione, avviando Claude da `packages/api/`:

490 490

491* Carica il root CLAUDE.md e `packages/api/CLAUDE.md`, salta `packages/web/CLAUDE.md`491* Carica il CLAUDE.md radice e `packages/api/CLAUDE.md`, salta `packages/web/CLAUDE.md`

492* Può leggere e modificare file in `packages/api/` e `packages/shared/`492* Può leggere e modificare file in `packages/api/` e `packages/shared/`

493* Salta le letture dell'output di build sotto `dist/` e `build/` in `packages/api/`493* Salta le letture dell'output di build sotto `dist/` e `build/` in `packages/api/`

494* Ha la skill api-testing disponibile su richiesta494* Ha la skill api-testing disponibile su richiesta

495* Crea worktrees contenenti `.claude/`, `packages/api/`, `packages/shared/` e file a livello di radice, con le regole di negazione applicate attraverso il worktree dal file di impostazioni della radice495* Crea worktree contenenti `.claude/`, `packages/api/`, `packages/shared/` e file a livello radice, con le regole di negazione applicate nel worktree dal file di impostazioni radice

496 496

497<h2 id="scope-and-plan-changes-that-span-packages">497<h2 id="scope-and-plan-changes-that-span-packages">

498 Ambito e pianifica i cambiamenti che si estendono tra pacchetti498 Ambito e pianifica i cambiamenti che si estendono tra pacchetti

llm-gateway-protocol.md +12 −3

Details

54 Endpoint opzionali e traffico di avvio54 Endpoint opzionali e traffico di avvio

55</h3>55</h3>

56 56

57Gli endpoint di conteggio dei token sono gli unici opzionali: quando sono assenti, Claude Code ricorre al conteggio dell'utilizzo del contesto attraverso l'endpoint di inferenza. Le richieste di inferenza vengono inviate a `/v1/messages?beta=true`, quindi abbinate sul percorso, non sull'URL completo. Il metodo Google Cloud's Agent Platform allega i suffissi al percorso del modello dell'editore, come in `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`.57Gli endpoint di conteggio dei token sono gli unici opzionali: quando sono assenti, Claude Code ricorre a una stima basata su caratteri dell'utilizzo del contesto.

59Abbinate sul percorso, non sull'URL completo:

61* Le richieste di inferenza vengono inviate a `/v1/messages?beta=true`

62* Il metodo Google Cloud's Agent Platform allega i suffissi al percorso del modello dell'editore, come in `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`

58 63

59Un gateway vede anche il traffico di avvio best-effort che può rifiutare senza rompere nulla. Un gateway in formato Anthropic Messages riceve una sonda di riscaldamento della connessione `HEAD /api/hello`, che Claude Code salta quando è configurato un proxy HTTP o un certificato client. Un gateway in formato Amazon Bedrock riceve una richiesta `GET /inference-profiles?type=SYSTEM_DEFINED` e, quando il modello configurato è un profilo di inferenza, ricerche `GET /inference-profiles/{profile}`.64Un gateway vede anche il traffico di avvio best-effort che può rifiutare senza rompere nulla. Un gateway in formato Anthropic Messages riceve una sonda di riscaldamento della connessione `HEAD /api/hello`, che Claude Code salta quando è configurato un proxy HTTP o un certificato client. Un gateway in formato Amazon Bedrock riceve una richiesta `GET /inference-profiles?type=SYSTEM_DEFINED` e, quando il modello configurato è un profilo di inferenza, ricerche `GET /inference-profiles/{profile}`.

60 65

152| Beta [tool fields](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | Le intestazioni beta relative agli strumenti si associano ai campi dello schema dello strumento come `strict` e `defer_loading` | `400` che nomina il campo dello schema dello strumento non riconosciuto quando il corpo passa attraverso senza la sua intestazione | Inoltrare entrambi, o [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |157| Beta [tool fields](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | Le intestazioni beta relative agli strumenti si associano ai campi dello schema dello strumento come `strict` e `defer_loading` | `400` che nomina il campo dello schema dello strumento non riconosciuto quando il corpo passa attraverso senza la sua intestazione | Inoltrare entrambi, o [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |

153| [Sforzo](https://platform.claude.com/docs/en/build-with-claude/effort) e [output strutturati](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | Il campo del corpo `output_config` contiene impostazioni di sforzo, formato di output strutturato e budget dei compiti; ciascuno si associa con la sua intestazione beta | `400` che nomina `output_config`, spesso `Extra inputs are not permitted`, su upstream Amazon Bedrock e Google Cloud's Agent Platform | Inoltrare il campo e le sue intestazioni insieme |158| [Sforzo](https://platform.claude.com/docs/en/build-with-claude/effort) e [output strutturati](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | Il campo del corpo `output_config` contiene impostazioni di sforzo, formato di output strutturato e budget dei compiti; ciascuno si associa con la sua intestazione beta | `400` che nomina `output_config`, spesso `Extra inputs are not permitted`, su upstream Amazon Bedrock e Google Cloud's Agent Platform | Inoltrare il campo e le sue intestazioni insieme |

154| [Prompt caching](/docs/it/prompt-caching) | Nessun accoppiamento beta. Claude Code allega marcatori `cache_control` ai blocchi `system` e alle voci `messages`, incluse le voci `role: "system"` aggiunte a metà conversazione | Nessun errore: la conversazione viene fatturata come input non memorizzato in cache ad ogni turno, visibile come `input_tokens` elevati con poca o nessuna attività di cache in `usage` | Inoltrare `cache_control` invariato ovunque appaia, e non convertire il contenuto del blocco `system` o del messaggio in stringhe semplici |159| [Prompt caching](/docs/it/prompt-caching) | Nessun accoppiamento beta. Claude Code allega marcatori `cache_control` ai blocchi `system` e alle voci `messages`, incluse le voci `role: "system"` aggiunte a metà conversazione | Nessun errore: la conversazione viene fatturata come input non memorizzato in cache ad ogni turno, visibile come `input_tokens` elevati con poca o nessuna attività di cache in `usage` | Inoltrare `cache_control` invariato ovunque appaia, e non convertire il contenuto del blocco `system` o del messaggio in stringhe semplici |

155| [Conteggio dei token](https://platform.claude.com/docs/en/build-with-claude/token-counting) | Nessun accoppiamento beta; utilizza l'endpoint `count_tokens` | Claude Code ricade al conteggio dell'utilizzo del contesto attraverso l'endpoint dei messaggi | Esporre l'endpoint in modo che i conteggi dei token non consumino richieste di inferenza |160| [Conteggio dei token](https://platform.claude.com/docs/en/build-with-claude/token-counting) | Nessun accoppiamento beta; utilizza l'endpoint `count_tokens` | Nessun errore: Claude Code ricade a una stima basata su caratteri, quindi `/context` mostra conteggi approssimativi | Esporre l'endpoint per conteggi di token esatti |

156 161

157Le variabili `ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [variables](/docs/it/model-config) dichiarano le capacità del modello solo nelle configurazioni del provider: `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, e [`CLAUDE_CODE_USE_MANTLE`](/docs/it/amazon-bedrock#use-the-mantle-endpoint). Non hanno effetto dietro un gateway `ANTHROPIC_BASE_URL`.162Le variabili `ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [variables](/docs/it/model-config) dichiarano le capacità del modello solo nelle configurazioni del provider: `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, e [`CLAUDE_CODE_USE_MANTLE`](/docs/it/amazon-bedrock#use-the-mantle-endpoint). Non hanno effetto dietro un gateway `ANTHROPIC_BASE_URL`.

158 163

160 Ritentativo automatico e inoltro degli errori165 Ritentativo automatico e inoltro degli errori

161</h3>166</h3>

162 167

163Quando l'upstream rifiuta il campo `thinking`, una [thinking signature](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), un messaggio di sistema a metà conversazione, o il marcatore `cache_control` su uno di questi messaggi, Claude Code ritenta la richiesta e disabilita la capacità rifiutata per il resto della conversazione. Claude Code non ritenta i rifiuti di gestione del contesto o di campi dello schema dello strumento; quegli errori `400` raggiungono lo sviluppatore.168Ciò che Claude Code fa dopo un rifiuto upstream dipende da ciò che è stato rifiutato:

169

170* Quando l'upstream rifiuta il campo `thinking`, un messaggio di sistema a metà conversazione, o il marcatore `cache_control` su tale messaggio, Claude Code ritenta la richiesta e disabilita la capacità rifiutata per il resto della conversazione

171* Quando l'upstream rifiuta una [thinking signature](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), Claude Code ritenta la richiesta senza i blocchi di pensiero precedenti della conversazione e li mantiene fuori da ogni richiesta successiva. Le nuove risposte includono ancora il pensiero

172* Claude Code non ritenta i rifiuti di gestione del contesto o di campi dello schema dello strumento, quindi quegli errori `400` raggiungono lo sviluppatore

164 173

165La logica di ritentativo corrisponde alla formulazione dell'errore dell'upstream, quindi inoltrare i corpi della risposta di errore invariati. Un gateway che avvolge gli errori upstream nel suo involucro interrompe il percorso di recupero, anche quando preserva il codice di stato, a meno che il messaggio dell'involucro non contenga un token `capability_rejected:` stabile. [Il gateway delle app Claude sostituisce questi token per la formulazione degli errori dei provider cloud](/docs/it/claude-apps-gateway-config#upstream-error-messages), ad esempio `capability_rejected: prompt_too_long`.174La logica di ritentativo corrisponde alla formulazione dell'errore dell'upstream, quindi inoltrare i corpi della risposta di errore invariati. Un gateway che avvolge gli errori upstream nel suo involucro interrompe il percorso di recupero, anche quando preserva il codice di stato, a meno che il messaggio dell'involucro non contenga un token `capability_rejected:` stabile. [Il gateway delle app Claude sostituisce questi token per la formulazione degli errori dei provider cloud](/docs/it/claude-apps-gateway-config#upstream-error-messages), ad esempio `capability_rejected: prompt_too_long`.

166 175

llm-gateway-rollout.md +1 −1

Details

207 207

208Aggiungete le variabili condizionali dalla tabella allo stesso blocco `env`. Un `ANTHROPIC_BASE_URL` gestito è applicato e non può essere sovrascritto da un'esportazione di shell di uno sviluppatore, poiché Claude Code lo applica sopra l'ambiente del processo e le impostazioni di priorità inferiore.208Aggiungete le variabili condizionali dalla tabella allo stesso blocco `env`. Un `ANTHROPIC_BASE_URL` gestito è applicato e non può essere sovrascritto da un'esportazione di shell di uno sviluppatore, poiché Claude Code lo applica sopra l'ambiente del processo e le impostazioni di priorità inferiore.

209 209

210Non includete `forceLoginMethod` o `forceLoginOrgUUID` nelle impostazioni gestite insieme a una credenziale gateway. Una delle due chiavi, con qualsiasi valore, blocca `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `apiKeyHelper` all'avvio, in modo che gli sviluppatori vedano `This machine's managed settings require a first-party login` e non possano procedere.210Non includete `forceLoginMethod` o `forceLoginOrgUUID` nelle impostazioni gestite insieme a una credenziale gateway. Una delle due chiavi, con qualsiasi valore, blocca `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `apiKeyHelper` all'avvio, e gli sviluppatori non possono procedere. Vedono `This machine's managed settings require a first-party login`, o [`Administrator policy requires a Cloud gateway sign-in`](/docs/it/errors#administrator-policy-requires-a-cloud-gateway-sign-in) sotto un valore `"gateway"`.

211 211

212La consegna di [impostazioni gestite dal server](/docs/it/server-managed-settings#platform-availability) richiede una connessione diretta a `api.anthropic.com`, quindi non raggiunge le sessioni instradate dal gateway. Le distribuzioni gateway utilizzano questo percorso di impostazioni gestite basato su file, che applica le stesse chiavi.212La consegna di [impostazioni gestite dal server](/docs/it/server-managed-settings#platform-availability) richiede una connessione diretta a `api.anthropic.com`, quindi non raggiunge le sessioni instradate dal gateway. Le distribuzioni gateway utilizzano questo percorso di impostazioni gestite basato su file, che applica le stesse chiavi.

213 213

managed-settings.md +445 −0 created

Details

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.

5# Distribuire impostazioni gestite

7> Distribuire impostazioni gestite su ogni macchina dello sviluppatore: meccanismi di consegna per sistema operativo, come Claude Code combina le fonti gestite e come verificare l'applicazione.

9Le impostazioni gestite sono le impostazioni che la tua organizzazione distribuisce su ogni macchina dello sviluppatore. Claude Code le applica al di sopra di ogni altro livello, quindi nessun valore utente, progetto, locale o `--settings` le sostituisce, ad eccezione di poche [eccezioni sensibili alla sicurezza](/docs/it/settings#exceptions-to-managed-settings-precedence) dove un valore più restrittivo da un livello inferiore conta ancora.

11Questa pagina è per l'amministratore che distribuisce impostazioni gestite o esegue il debug del motivo per cui una non si applica. Per decidere cosa applicare, inizia con la tabella [Decide what to enforce](/docs/it/admin-setup#decide-what-to-enforce). Per il percorso della console claude.ai, vedi [Server-managed settings](/docs/it/server-managed-settings). Per sapere in quale file vanno i valori propri dello sviluppatore, vedi [Settings](/docs/it/settings).

13<h2 id="deploy-a-managed-settings-file">

14 Distribuire un file di impostazioni gestite

15</h2>

17Questo è il modo più veloce per mettere una policy su ogni macchina: un file `managed-settings.json`. Se non hai ancora scelto come distribuire le impostazioni gestite, o i tuoi dispositivi sono sotto MDM o gli sviluppatori eseguono sessioni cloud, leggi prima [Choose a delivery mechanism](#choose-a-delivery-mechanism).

19<Steps>

20 <Step title="Scrivi managed-settings.json">

21 Scrivi un `managed-settings.json` che contenga le chiavi che hai deciso di applicare, nella stessa forma JSON di `settings.json`. La tabella [Decide what to enforce](/docs/it/admin-setup#decide-what-to-enforce) elenca le chiavi dietro ogni controllo, e ogni voce nel [settings reference](/docs/it/settings-reference) dice se una fonte gestita può impostarla. Questo file blocca due letture di file, disattiva la modalità bypass e fa sì che Claude Code ignori le regole di autorizzazione da file utente, progetto e locale e da `--allowedTools`:

23 ```json managed-settings.json theme={null}

24 {

25 "permissions": {

26 "deny": [

27 "Read(./.env)",

28 "Read(./secrets/**)"

29 ],

30 "disableBypassPermissionsMode": "disable"

31 },

32 "allowManagedPermissionRulesOnly": true

33 }

34 ```

36 Per un esempio più completo che mostra la forma di più chiavi gestite, incluso il metodo di accesso, i modelli, i server MCP e i marketplace, vedi [An organization's managed settings](/docs/it/settings-example#an-organizations-managed-settings).

37 </Step>

39 <Step title="Posiziona il file su ogni macchina">

40 Salva il file come `managed-settings.json` nella directory di sistema per il sistema operativo, utilizzando qualsiasi strumento già posiziona file sulla tua flotta:

42 * **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`

43 * **Linux e WSL**: `/etc/claude-code/managed-settings.json`

44 * **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`

45 </Step>

47 <Step title="Conferma che la policy è stata applicata">

48 Su una macchina, esegui `/status` all'interno di Claude Code. La riga `Setting sources` mostra `Enterprise managed settings (file)`. Distribuisci al resto della flotta dopo; [Check that a policy is in force](#check-that-a-policy-is-in-force) copre cosa guardare quando la riga manca.

49 </Step>

50</Steps>

52<span id="managed-settings-delivery" />

54<span id="delivery-mechanisms" />

56<h2 id="choose-a-delivery-mechanism">

57 Scegli un meccanismo di consegna

58</h2>

60Il file nei passaggi precedenti è uno dei quattro modi per ottenere impostazioni gestite su una macchina. Ogni meccanismo porta le stesse chiavi di policy di un file `settings.json`, quindi il [settings reference](/docs/it/settings-reference) si applica a tutti loro. Poche chiavi sono legate a fonti particolari, e la riga Scope di ogni voce dice quale:

62* **Delivery controls**: [`policyHelper`](/docs/it/settings-reference#policyhelper), [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings), e [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior)

63* **Gateway login keys**: [`forceLoginGatewayUrl`](/docs/it/settings-reference#forcelogingatewayurl) e il valore `"gateway"` di [`forceLoginMethod`](/docs/it/settings-reference#forceloginmethod)

65Un file di impostazioni gestite, un profilo MDM, o la console claude.ai applica una policy a tutti coloro che raggiunge. Per dare a un gruppo di sviluppatori una policy diversa, distribuisci un file o profilo diverso a quel gruppo; la console claude.ai [non può ancora indirizzare un gruppo](/docs/it/server-managed-settings#current-limitations), mentre un [Claude apps gateway](/docs/it/claude-apps-gateway) auto-ospitato distribuisce impostazioni gestite per gruppo IdP.

67Quando più di un meccanismo distribuisce una policy alla stessa macchina, Claude Code per impostazione predefinita ne usa uno e ignora gli altri. [How Claude Code combines managed sources](#how-claude-code-combines-managed-sources) fornisce l'ordine e l'opt-in che applica ogni fonte.

69Le righe MDM e file sono insieme chiamate impostazioni gestite da endpoint, perché la policy è archiviata sul dispositivo dello sviluppatore, al contrario della riga server-managed, dove Claude Code la recupera.

71Scegli un meccanismo in base a come già gestisci i dispositivi, utilizzando la tabella sottostante.

74| :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |

75| [Server-managed settings](/docs/it/server-managed-settings) | Nella console admin claude.ai, o su un [Claude apps gateway](/docs/it/claude-apps-gateway) auto-ospitato | Recuperato all'avvio e sottoposto a polling ogni ora; vedi [changes that need approval](#where-and-when-a-policy-applies) | Vuoi un posto per cambiare la policy per un'organizzazione claude.ai senza toccare ogni macchina |

76| MDM o policy a livello di sistema operativo | Come profilo di configurazione macOS o valore di registro Windows `HKLM`, tramite Jamf, Intune, Group Policy, o uno strumento simile; vedi [where each mechanism stores the policy](#where-each-mechanism-stores-the-policy) | Letto all'avvio e controllato per modifiche ogni 30 minuti | Gestisci già i dispositivi con MDM o Group Policy |

77| Basato su file | Come `managed-settings.json` in una directory di sistema su ogni macchina; vedi [where each mechanism stores the policy](#where-each-mechanism-stores-the-policy) | Letto all'avvio e ricaricato quando un file cambia | Macchine senza MDM, host Linux, o immagini che costruisci tu stesso |

78| HKCU registry, Windows e WSL | Come valore di registro Windows `HKCU`; vedi [where each mechanism stores the policy](#where-each-mechanism-stores-the-policy) | Letto all'avvio e controllato per modifiche ogni 30 minuti; Claude Code lo usa solo quando nessun'altra fonte gestita distribuisce una chiave di policy e nessuna [host-supplied parent settings](#let-an-embedding-host-add-policy) fornisce una chiave restrittiva | Non puoi scrivere la chiave a livello di macchina `HKLM` |

80I modelli di avvio per Jamf, Iru, Intune e Group Policy si trovano nel [MDM examples repository](https://github.com/anthropics/claude-code/tree/main/examples/mdm).

82Per i server MCP gestiti, che distribuisci insieme a uno qualsiasi di questi tramite `managed-mcp.json` o fornisci tramite la chiave [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers), vedi [Managed MCP configuration](/docs/it/managed-mcp).

84<h3 id="where-and-when-a-policy-applies">

85 Dove e quando una policy si applica

86</h3>

88Una policy distribuita raggiunge le sessioni dello sviluppatore come segue:

90* **Surfaces**: sulla macchina dello sviluppatore, il terminale, le estensioni VS Code e JetBrains, la scheda Code dell'app desktop, e le sessioni [Agent SDK](/docs/it/agent-sdk/typescript) leggono tutte queste fonti. Le sessioni Agent SDK caricano impostazioni gestite anche quando `settingSources` esclude i file utente, progetto e locale.

91* **Cloud sessions**: una sessione in un ambiente ospitato da Anthropic non legge un profilo MDM o file del dispositivo, quindi la policy per essa deve provenire da impostazioni server-managed. Una sessione in un [ambiente auto-ospitato](/docs/it/self-hosted-environments) legge anche il file di impostazioni gestite nella sua immagine runner, per impostazione predefinita solo quando le impostazioni server-managed non distribuiscono una chiave di policy, a parte le [chiavi che Claude Code legge da ogni fonte admin](#keys-read-from-every-admin-source). [How Claude Code combines managed sources](#how-claude-code-combines-managed-sources) copre l'opt-in che applica entrambi.

92* **Cowork sessions**: [Cowork](https://claude.com/docs/cowork/overview) nell'app Claude Desktop esegue le sue sessioni su Claude Code. In una sessione Cowork, Claude Code non recupera mai impostazioni server-managed dalla console admin claude.ai, anche quando l'utente accede con un account Team o Enterprise, quindi quale policy si applica dipende da dove viene eseguita la sessione:

94 * **Sulla macchina dell'utente**: per impostazione predefinita, Claude Code in una sessione Cowork legge la policy MDM o a livello di sistema operativo e il file di impostazioni gestite su quel dispositivo, quindi distribuisci la policy lì.

95 * **In una sandbox VM completa**: quando la tua configurazione gestita di Claude Desktop imposta [`requireCoworkFullVmSandbox`](https://claude.com/docs/third-party/claude-desktop/configuration#requirecoworkfullvmsandbox), Claude Code viene eseguito all'interno di una macchina virtuale dove la policy MDM del dispositivo e il file di impostazioni gestite non sono presenti.

96 * **Remote Cowork sessions**: queste vengono eseguite su VM gestite da Anthropic, dove Claude Code non ha policy del dispositivo da leggere.

98 La tabella [surface coverage](/docs/it/model-config#surface-coverage) confronta Cowork con le altre surface.

99* **Running sessions**: la maggior parte dei cambiamenti raggiunge una sessione in esecuzione secondo la pianificazione nella [tabella del meccanismo di consegna](#choose-a-delivery-mechanism), senza un riavvio.

100 * I cambiamenti a [`forceRemoteSettingsRefresh`](/docs/it/settings-reference#forceremotesettingsrefresh), [`requiredMinimumVersion`](/docs/it/settings-reference#requiredminimumversion), e [alcune chiavi modificabili dall'utente](/docs/it/settings#when-edits-take-effect) hanno effetto al prossimo avvio della sessione.

101 * Una voce [`policyHelper`](/docs/it/settings-reference#policyhelper) nuova o modificata ha effetto al prossimo avvio. Se le impostazioni server-managed oscurano l'helper a quell'avvio, l'helper viene eseguito non appena un fetch segnala che quelle impostazioni sono state rimosse.

102* **Changes that need approval**: a parte gli [aggiornamenti che aspettano il prossimo avvio](/docs/it/server-managed-settings#fetch-and-caching-behavior), un cambiamento server-managed a un'impostazione che [ha bisogno di approvazione](/docs/it/server-managed-settings#security-approval-dialogs), come un hook o una variabile `env`, aspetta che lo sviluppatore accetti la finestra di dialogo in una sessione interattiva, e si applica per l'esecuzione corrente in una sessione che un'estensione IDE o l'Agent SDK ospita. Gli altri cambiamenti server-managed si applicano al prossimo polling.

103* **Long-lived sessions**: una sessione lasciata aperta per settimane può ancora rimanere indietro rispetto a un rollout. [`requiredMinimumVersion`](/docs/it/settings-reference#requiredminimumversion) blocca un binario obsoleto dall'avvio e non termina una sessione già in esecuzione.

104

105<span id="format-the-policy-for-each-platform" />

106

107<h3 id="where-each-mechanism-stores-the-policy">

108 Dove ogni meccanismo archivia la policy

109</h3>

110

111Le chiavi sono le stesse ovunque, ma ogni meccanismo le archivia in un posto e forma diversi:

112

113* **Server-managed**: i server di Anthropic, o il tuo gateway, contengono la policy. Claude Code mantiene una cache locale che applica all'avvio e [sostituisce ad ogni fetch riuscito](/docs/it/server-managed-settings#security-considerations).

114* **macOS configuration profile**: il dominio delle preferenze gestite `com.anthropic.claudecode`. Usa le stesse chiavi di livello superiore di `managed-settings.json`, con impostazioni nidificate come dizionari e liste come array plist.

115* **Windows HKLM registry**: il JSON come valore `REG_SZ` o `REG_EXPAND_SZ` denominato `Settings` sotto `HKLM\SOFTWARE\Policies\ClaudeCode`.

116* **File-based**: `managed-settings.json`, una directory opzionale `managed-settings.d/`, e `managed-mcp.json` nella directory di sistema: `/Library/Application Support/ClaudeCode/` su macOS, `/etc/claude-code/` su Linux e WSL, e `C:\Program Files\ClaudeCode\` su Windows. Claude Code non legge il percorso Windows legacy `C:\ProgramData\ClaudeCode\managed-settings.json`.

117* **Windows HKCU registry**: lo stesso valore `Settings` sotto `HKCU\SOFTWARE\Policies\ClaudeCode`.

118

119<h3 id="split-a-file-based-policy-across-teams">

120 Dividi una policy basata su file tra i team

121</h3>

122

123Se diversi team possiedono parti di una policy, metti ogni parte nel suo file in `managed-settings.d/`, accanto a `managed-settings.json` nella stessa directory di sistema, invece di modificare un file condiviso.

124

125Claude Code unisce `managed-settings.json` per primo, poi ogni file `*.json` nella directory in ordine alfabetico. Nomina i file con prefissi numerici per controllare l'ordine, come `10-telemetry.json` e `20-security.json`. Claude Code ignora i file nascosti e i file che non terminano in `.json`.

126

127Quando due file impostano la stessa chiave, Claude Code li combina secondo queste regole:

128

129* **Single values**, come `"model": "opus"` o `"cleanupPeriodDays": 7`: il valore del file successivo sostituisce quello precedente

130* **Lists**, come `permissions.deny` o `sandbox.network.allowedDomains`: le due liste si combinano, con i duplicati rimossi

131* **Nested blocks**, come `env` o `sandbox`: i due blocchi si uniscono chiave per chiave, e ogni chiave all'interno segue queste stesse regole

132* **`fallbackModel`**: la catena successiva sostituisce quella precedente completamente

133* **[`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) e [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers)**: una voce successiva con lo stesso nome sostituisce quella precedente completamente

134* **[`modelPicker`](/docs/it/settings-reference#modelpicker)**: la lineup successiva sostituisce quella precedente completamente

135

136<span id="precedence-within-the-managed-tier" />

137

138<span id="which-managed-source-claude-code-uses" />

139

140<h2 id="how-claude-code-combines-managed-sources">

141 Come Claude Code combina le fonti gestite

142</h2>

143

144Quando la tua organizzazione distribuisce più di una fonte gestita alla stessa macchina, la chiave [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior) decide cosa Claude Code fa con le altre:

145

146* **`"first-wins"`, l'impostazione predefinita**: Claude Code usa la fonte con il ranking più alto che distribuisce almeno una chiave di policy e ignora il resto piuttosto che unirle, a parte le poche chiavi in [Keys read from every admin source](#keys-read-from-every-admin-source). Claude Code non mostra alcun avviso per le fonti che salta; `/status` [nomina la fonte che ha usato e quelle che ha saltato](#read-the-source-in-/status).

147* **`"merge"`**: Claude Code applica ogni fonte admin che distribuisce una chiave di policy e le combina per tipo di chiave: sulla maggior parte delle chiavi il valore della fonte con ranking più alto si applica, le liste si uniscono, e i lock prendono il valore più restrittivo. [Compose every managed source](#compose-every-managed-source) dice dove impostare la chiave e come ogni tipo di chiave si combina. Richiede Claude Code v2.1.242 o successivo.

148

149Entrambe le impostazioni classificano le fonti nello stesso modo. Due termini ricorrono in questa sezione:

150

151* **Policy key**: qualsiasi chiave di impostazioni diversa dalle due chiavi di controllo, [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings) e [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior). Un file di impostazioni gestite o una policy MDM che contiene solo quelli non conta, e Claude Code passa alla fonte successiva.

152* **Admin source**: una delle prime tre fonti sottostanti. Il registro HKCU è scrivibile dall'utente e non è uno.

153

154Claude Code controlla le fonti in questo ordine, priorità più alta per prima:

155

1561. Impostazioni remote, consegnate da claude.ai come [server-managed settings](/docs/it/server-managed-settings) o da un [Claude apps gateway](/docs/it/claude-apps-gateway). Claude Code recupera questa fonte solo quando la sessione si autentica all'API di Anthropic direttamente con un [login o chiave idonei](/docs/it/server-managed-settings#platform-availability), o accede a un gateway con `/login`. Su altri provider, o quando `ANTHROPIC_BASE_URL` punta da qualche parte diversa dall'API di Anthropic, inizia dalla fonte successiva

1572. Policy MDM o a livello di sistema operativo: il plist macOS o la chiave di registro HKLM

1583. File di impostazioni gestite, `managed-settings.d/*.json` e `managed-settings.json` uniti insieme

1594. Il registro HKCU, su Windows, e su WSL una volta che il registro HKLM o il file di impostazioni gestite Windows attiva [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings) e il valore HKCU lo imposta anche. Claude Code lo legge solo quando nessuna fonte sopra di esso distribuisce una chiave di policy e nessuna [host-supplied parent settings](#let-an-embedding-host-add-policy) fornisce una chiave restrittiva

160

161Questo diagramma mostra la classificazione, con esempi delle chiavi cross-source che Claude Code legge dalle prime tre fonti sotto entrambe le impostazioni:

162

163<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="Diagramma che mostra le quattro fonti di impostazioni gestite classificate dalle impostazioni remote in alto attraverso MDM, file di impostazioni gestite e il registro HKCU in basso. Per impostazione predefinita la prima fonte con una chiave di policy fornisce la policy e il resto viene saltato; con managedSourcesBehavior impostato su merge, ogni fonte admin con una chiave di policy contribuisce, combinata per tipo di chiave, e il registro HKCU rimane fuori. Un pannello laterale mostra che le chiavi cross-source come i lock sandbox, forceRemoteSettingsRefresh e il merge env per variabile vengono letti da ogni fonte admin, che esclude il registro HKCU." width="680" height="330" data-path="images/managed-source-precedence.svg" />

164

165<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="Diagramma che mostra le quattro fonti di impostazioni gestite classificate dalle impostazioni remote in alto attraverso MDM, file di impostazioni gestite e il registro HKCU in basso. Per impostazione predefinita la prima fonte con una chiave di policy fornisce la policy e il resto viene saltato; con managedSourcesBehavior impostato su merge, ogni fonte admin con una chiave di policy contribuisce, combinata per tipo di chiave, e il registro HKCU rimane fuori. Un pannello laterale mostra che le chiavi cross-source come i lock sandbox, forceRemoteSettingsRefresh e il merge env per variabile vengono letti da ogni fonte admin, che esclude il registro HKCU." width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />

166

167<h3 id="keys-read-from-every-admin-source">

168 Chiavi lette da ogni fonte admin

169</h3>

170

171Sotto l'impostazione predefinita `"first-wins"`, Claude Code legge la maggior parte delle chiavi solo dalla [fonte che ha selezionato](#how-claude-code-combines-managed-sources), e ignora un valore in una fonte con ranking inferiore anche quando la fonte selezionata lascia quella chiave non impostata.

172

173Poche chiavi funzionano diversamente. Claude Code le legge da ogni fonte admin, quindi una policy MDM con ranking inferiore o un file di impostazioni gestite può ancora impostarle quando la fonte selezionata non lo fa. Claude Code lascia fuori il registro HKCU scrivibile dall'utente da quella scansione; quando HKCU è l'unica fonte e nessun host fornisce impostazioni parent, HKCU si applica come qualsiasi fonte selezionata.

174

175Le chiavi cross-source includono:

176

177* `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`: un `true` in qualsiasi fonte admin attiva il lock. Mentre un lock è attivo, Claude Code unisce l'allowlist che blocca, `sandbox.network.allowedDomains` insieme alle regole di autorizzazione `WebFetch(domain:...)`, o `sandbox.filesystem.allowRead`, attraverso ogni fonte admin. Senza il lock, Claude Code tratta l'allowlist come qualsiasi altra chiave, quindi sotto `"first-wins"` l'allowlist di una fonte admin non selezionata viene ignorata

178* `allowAllClaudeAiMcps`

179* I percorsi binari sandbox `sandbox.bwrapPath` e `sandbox.socatPath`

180* Il binario sandbox `ripgrep`, [`sandbox.ripgrep`](/docs/it/settings-reference#sandbox-ripgrep)

181* `sandbox.filesystem.disabled` e `sandbox.network.strictAllowlist`

182* [`useAutoModeDuringPlan`](/docs/it/settings-reference#useautomodeduringplan) e [`syncClaudeAiSkills`](/docs/it/settings-reference#syncclaudeaiskills), dove un `false` da qualsiasi fonte admin disattiva il comportamento. Un `false` nelle impostazioni utente o locale dello sviluppatore lo disattiva anche; ogni chiave può solo negare

183* [`enableArtifact`](/docs/it/settings-reference#enableartifact), dove un `false` da qualsiasi fonte admin disattiva lo [Artifact tool](/docs/it/artifacts). Un `false` nelle impostazioni utente, progetto o locale dello sviluppatore lo disattiva anche, e nessuna fonte lo riattiva; vedi [which lower-level values still count](/docs/it/settings#exceptions-to-managed-settings-precedence). Richiede Claude Code v2.1.242 o successivo

184* [`maxEffortLevel`](/docs/it/settings-reference#maxeffortlevel), dove il cap più basso in qualsiasi fonte admin si applica. Se uno sviluppatore imposta un cap più basso nelle sue stesse impostazioni o con `--settings`, Claude Code applica quello; nessuna fonte può aumentare il cap. Richiede Claude Code v2.1.267 o successivo

185* Un opt-out di commit-trailer in `attribution`, o nel deprecato `includeCoAuthoredBy`, da qualsiasi livello

186* [`forceRemoteSettingsRefresh`](/docs/it/server-managed-settings)

187* `env`, unito per variabile attraverso le fonti admin: ogni variabile proviene dalla fonte con priorità più alta che la definisce, quindi le fonti inferiori riempiono le variabili che quelle superiori lasciano non impostate. Poche variabili seguono le loro stesse regole; [Per-key exceptions across managed sources](/docs/it/server-managed-settings#per-key-exceptions-across-managed-sources) nomina ognuna. Richiede Claude Code v2.1.223 o successivo. Prima di v2.1.223, Claude Code applicava solo il blocco `env` completo della fonte selezionata

188

189<h3 id="compose-every-managed-source">

190 Componi ogni fonte gestita

191</h3>

192

193Per fare in modo che Claude Code applichi ogni fonte admin che la tua organizzazione distribuisce, imposta [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior) su `"merge"` nella fonte con ranking più alto che distribuisci. Claude Code legge la chiave solo dalla fonte con ranking più alto che porta la chiave o una chiave di policy, quindi una fonte inferiore non può optare per l'unione con la fonte sopra di essa, e una macchina che non riceve mai impostazioni server-managed ha bisogno della chiave nel suo profilo MDM anche. Il registro HKCU scrivibile dall'utente non si unisce mai con un'altra fonte. Richiede Claude Code v2.1.242 o successivo.

194

195Sotto `"merge"`, Claude Code aggiunge le voci di lista di una fonte inferiore, come regole `permissions.allow` e hook, alla policy, quindi attivalo solo quando ogni fonte classificata sotto la tua più alta è sotto il controllo di un amministratore.

196

197Questa tabella mostra come Claude Code combina ogni tipo di chiave sotto `"merge"`. La voce [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior) nomina ogni chiave in tre delle righe: restriction allowlists, values taken whole, e keys read from the highest-ranked source only.

198

199| Tipo di chiave | Come Claude Code la combina | Esempi |

200| :------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |

201| Lists | Combina le voci da ogni fonte | `permissions.allow`, `hooks`, `sandbox.network.allowedDomains`, `deniedMcpServers` |

202| Locks | Applica il valore più restrittivo che qualsiasi fonte imposta; un valore più permissivo si applica solo dalla fonte con ranking più alto | `allowManagedHooksOnly`, `permissions.disableBypassPermissionsMode`, `crossSessionInbound` |

203| Restriction allowlists | Prende la lista completamente dalla fonte con ranking più alto che la imposta, senza aggiungere voci da fonti inferiori | `availableModels`, `allowedMcpServers`, `strictKnownMarketplaces`, `allowedChannelPlugins`, e la catena `fallbackModel` |

204| Values taken whole | Prende il valore completamente dalla fonte con ranking più alto che lo imposta, senza combinare voci o campi da fonti inferiori | `sandbox.credentials.awsPairs`, `sandbox.ripgrep` |

205| Provided MCP servers | Combina i nomi dei server da ogni fonte; quando due fonti impostano lo stesso nome, applica la voce completa della fonte con ranking più alto | `managedMcpServers` |

206| Chiavi lette solo dalla fonte con ranking più alto | Ignora la chiave in ogni fonte inferiore, anche quando la fonte con ranking più alto la lascia non impostata | Helper di credenziali come `apiKeyHelper`, pin di accesso come `forceLoginOrgUUID`, `modelPicker`, `permissions.defaultMode` |

207| `env` | Si unisce per variabile attraverso le fonti admin sotto entrambe le impostazioni, come [Keys read from every admin source](#keys-read-from-every-admin-source) descrive | |

208| Ogni altra chiave | Prende il valore dalla fonte con ranking più alto che lo imposta | `model`, `cleanupPeriodDays` |

209

210Per confermare quali fonti si sono combinate su una macchina, [leggi la riga `Setting sources` in `/status`](#read-the-source-in-/status); quella sezione dice cosa significa ogni etichetta.

211

212<h3 id="compute-the-policy-with-a-helper-program">

213 Calcola la policy con un programma helper

214</h3>

215

216Un [`policyHelper`](/docs/it/settings-reference#policyhelper) è un eseguibile che la tua policy MDM o il file di impostazioni gestite nomina, e Claude Code lo esegue per calcolare le impostazioni gestite all'avvio. Quando la fonte selezionata ne configura uno e l'helper emette un oggetto `managedSettings`, quell'output cambia cosa Claude Code legge:

217

218* **L'oggetto `managedSettings` emesso è l'unica impostazione gestita per la sessione**, incluso per le [chiavi che altrimenti legge da ogni fonte admin](#keys-read-from-every-admin-source), a parte [`forceRemoteSettingsRefresh`, che ha la sua stessa regola di avvio](/docs/it/settings-reference#forceremotesettingsrefresh)

219

220Per quale helper esegue i fallimenti, e cosa Claude Code fa quando uno lo fa, vedi [Helper failures](/docs/it/settings-reference#helper-failures).

221

222<span id="parent-settings-from-embedding-hosts" />

223

224<span id="control-policy-from-an-embedding-host" />

225

226<span id="merge-policy-from-an-embedding-host" />

227

228<h3 id="let-an-embedding-host-add-policy">

229 Lascia che un host di embedding aggiunga policy

230</h3>

231

232Quando un'altra applicazione avvia Claude Code, come Claude Desktop, un'estensione IDE, o un'app Agent SDK, quell'host può passare le sue stesse impostazioni gestite tramite l'opzione SDK `managedSettings`. Claude Code chiama queste impostazioni parent.

233

234Per impostazione predefinita, Claude Code ignora le impostazioni parent ogni volta che una fonte admin è presente: impostazioni server-managed, una policy MDM o a livello di sistema operativo, o un file di impostazioni gestite.

235

236Per fare in modo che Claude Code unisca le impostazioni parent insieme a una fonte admin, imposta [`parentSettingsBehavior`](/docs/it/settings-reference#parentsettingsbehavior) su `"merge"` nella fonte gestita con priorità più alta; Claude Code legge la chiave solo da quella fonte.

237

238Claude Code quindi mantiene solo i valori dell'host che limitano quello che Claude può fare, con un gap da conoscere: a meno che tu non imposti anche i lock `allowManaged*Only`, le regole di autorizzazione allow dell'host e gli allowlist sandbox si applicano ancora. Vedi [Restrict parent settings](/docs/it/claude-apps-gateway#restrict-parent-settings) per i lock.

239

240Un [`policyHelper`](/docs/it/settings-reference#policyhelper) può disattivare l'unione parent indipendentemente da questa chiave; la sua voce dice quando.

241

242Claude Code applica anche questi controlli ai valori forniti da parent da soli:

243

244* Quando qualsiasi fonte admin imposta `allowManagedPermissionRulesOnly`, Claude Code elimina le [regole di autorizzazione allow fornite da parent](/docs/it/claude-apps-gateway#restrict-parent-settings) e `additionalDirectories` mentre le legge, anche quando una fonte con ranking più alto lascia la chiave non impostata. L'effetto della chiave sulle tue stesse regole di autorizzazione proviene dalle impostazioni gestite che Claude Code applica, o dalle impostazioni parent che hai scelto di unire

245* Claude Code applica il valore `forceLoginOrgUUID` o `allowedMcpServers` nelle impostazioni gestite che applica e blocca uno fornito da parent. Un valore in una fonte admin inferiore che Claude Code non applica né si applica né blocca quello del parent. La voce [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior) dice quale fonte fornisce ogni chiave sotto `"merge"`. Prima di v2.1.223, un valore in qualsiasi fonte admin bloccava quello del parent

246* Un valore `availableModels` segue la stessa regola di `allowedMcpServers`

247

248<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">

249 Mantieni l'accesso alla cartella Cowork quando si applicano solo regole gestite

250</h4>

251

252[Cowork](https://claude.com/docs/cowork/overview) nell'app Claude Desktop esegue le sue sessioni su Claude Code e concede a ogni sessione l'accesso alle sue cartelle di lavoro, come la cartella che l'utente connette, tramite regole di autorizzazione che fornisce quando avvia la sessione. Quando la tua policy gestita imposta [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly), Claude Code mantiene solo le regole di autorizzazione nella policy gestita: elimina le regole di autorizzazione che un host fornisce come impostazioni parent, come `--allowedTools`, o in un file di impostazioni, quindi le scritture in quelle cartelle perdono la loro pre-approvazione. In una sessione Cowork che chiede prima delle modifiche, Cowork non può mostrare il prompt, e Claude segnala ogni scrittura come bloccata perché il percorso si risolve in una posizione protetta o un percorso al di fuori della cartella connessa.

253

254Per ripristinare le scritture, aggiungi regole di autorizzazione per quelle cartelle alla fonte gestita che Claude Code [seleziona](#precedence-within-the-managed-tier) su quelle macchine: su una flotta gestita da MDM, è la policy MDM piuttosto che un file di impostazioni gestite separato. Questo esempio usa la forma file, e una policy MDM prende le stesse chiavi. Mantiene `allowManagedPermissionRulesOnly` impostato e consente modifiche sotto una cartella `CoworkProjects` nella directory home di ogni utente; sostituisci il percorso con le cartelle che i tuoi utenti connettono:

255

256```json managed-settings.json theme={null}

257{

258 "allowManagedPermissionRulesOnly": true,

259 "permissions": {

260 "allow": [

261 "Edit(~/CoworkProjects/**)"

262 ]

263 }

264}

265```

266

267Dopo aver distribuito la policy, Claude può salvare file sotto quella cartella in una nuova sessione Cowork. [Read and Edit rules](/docs/it/permissions#read-and-edit) coprono la sintassi del percorso, inclusa la forma `//` per i percorsi assoluti.

268

269<h3 id="what-a-developer-can-change">

270 Cosa uno sviluppatore può cambiare

271</h3>

272

273I file di impostazioni propri di uno sviluppatore, i valori `--settings` e i file di progetto non sostituiscono mai un valore gestito; le [eccezioni](/docs/it/settings#exceptions-to-managed-settings-precedence) solo lasciano che un valore più restrittivo di livello inferiore conti. Quattro cose si trovano al di fuori di quella regola:

274

275* **Il modello per una sessione**: un `model` gestito è un default, non un lock. `--model` e `ANTHROPIC_MODEL` scelgono ancora il modello per quella sessione, quindi distribuisci [`availableModels`](/docs/it/settings-reference#availablemodels) per limitare la scelta.

276* **Diritti admin locali**: uno sviluppatore che è un amministratore sulla macchina può modificare la fonte gestita stessa, motivo per cui gli strumenti MDM possono ridistribuire il profilo o il file su una pianificazione e motivo per cui il registro HKLM e il dominio delle preferenze gestite macOS esistono.

277* **La cache server-managed**: le impostazioni server-managed provengono dai server di Anthropic, e una modifica alla cache locale [dura solo fino al prossimo fetch riuscito](/docs/it/server-managed-settings#security-considerations).

278* **Altri strumenti**: le impostazioni gestite vincolano solo Claude Code. Uno sviluppatore che chiama l'API da un altro strumento non è sotto di loro.

279

280<span id="verify-enforcement" />

281

282<span id="verify-that-a-policy-is-in-force" />

283

284<h2 id="check-that-a-policy-is-in-force">

285 Verifica che una policy sia in vigore

286</h2>

287

288Uno sviluppatore segnala che una policy non si applica, o vuoi confermare che un rollout è arrivato prima di spingerlo alla flotta. Due comandi su quella macchina lo rispondono: `/status` mostra quale fonte gestita Claude Code ha selezionato, e `claude doctor` elenca cosa ha eliminato.

289

290<h3 id="read-the-source-in-/status">

291 Leggi la fonte in /status

292</h3>

293

294Sulla macchina dello sviluppatore, esegui `/status` all'interno di Claude Code e leggi la riga `Setting sources`. Quando una fonte gestita è in vigore, la riga elenca `Enterprise managed settings` con la fonte che Claude Code ha selezionato tra parentesi:

295

296* `(remote)`: impostazioni server-managed da claude.ai o un gateway

297* `(plist)` o `(HKLM)`: una policy MDM o del sistema operativo

298* `(file)`, `(drop-ins)`, o `(file + drop-ins)`: `managed-settings.json`, la directory drop-in, o entrambi

299* `(remote + file, merged)`, o un altro elenco che termina in `, merged`: la tua organizzazione [compone ogni fonte gestita](#compose-every-managed-source), e Claude Code ha unito le fonti elencate nella policy. Una fonte inferiore può ancora fornire variabili `env` senza apparire nell'elenco. Richiede Claude Code v2.1.242 o successivo

300* `(HKCU)`: il fallback del registro scrivibile dall'utente

301* `(parent process)`: un [host di embedding](#let-an-embedding-host-add-policy) ha fornito impostazioni restrittive

302* `(helper)`: un [`policyHelper`](/docs/it/settings-reference#policyhelper) configurato dalla fonte MDM o file selezionata

303

304Quando Claude Code ha trovato una fonte gestita sulla macchina e non l'ha selezionata, una seconda riga, `Skipped sources`, nomina ogni tale fonte. Leggila per distinguere una policy che non ha mai raggiunto la macchina da una che l'ha raggiunta e che una fonte con priorità più alta ha ignorato. Richiede Claude Code v2.1.242 o successivo.

305

306Quando la policy non si applica, la riga `Setting sources` ti dice quale dei due problemi hai:

307

308* **La riga manca**: Claude Code non ha trovato alcuna fonte gestita che distribuisca una chiave di policy.

309

310 Se hai distribuito un file di impostazioni gestite, controlla che si trovi al percorso per il sistema operativo e che contenga una [chiave di policy](#how-claude-code-combines-managed-sources) piuttosto che solo le chiavi di controllo. Un file che non è JSON valido non produce questo stato; Claude Code [rifiuta di avviarsi](#find-entries-claude-code-dropped) invece.

311

312 Quando hai distribuito tramite impostazioni server-managed, esegui `claude doctor`, che segnala l'[esito del fetch](/docs/it/server-managed-settings#verify-settings-delivery).

313* **La riga nomina una fonte diversa da quella che hai distribuito**: una fonte con priorità più alta è presente e Claude Code ha ignorato la tua, e `Skipped sources` l'elenca. [How Claude Code combines managed sources](#how-claude-code-combines-managed-sources) fornisce l'ordine.

314

315<span id="invalid-entries-in-managed-settings" />

316

317<h3 id="find-entries-claude-code-dropped">

318 Trova voci che Claude Code ha eliminato

319</h3>

320

321Quando un file di impostazioni gestite, un profilo MDM, un valore di registro, o un payload server-managed non supera la convalida dello schema, Claude Code prima salta le singole voci che può riparare, come una regola di autorizzazione non valida, con un avviso per ognuna, quindi elimina qualsiasi chiave di livello superiore il cui valore ancora non supera e continua a applicare ogni chiave valida rimanente.

322

323Claude Code è più rigoroso con il `managedSettings` che un [`policyHelper`](/docs/it/settings-reference#policyhelper) emette: fa le stesse riparazioni di voce, ma qualsiasi violazione dello schema che sopravvive fa fallire l'intera esecuzione dell'helper, e all'avvio Claude Code rifiuta di avviarsi, lo stesso che per un helper che esce con non-zero.

324

325Quando un file di impostazioni gestite, un file drop-in, un plist MDM, o un valore di registro HKLM è presente ma non può essere analizzato come un oggetto JSON, Claude Code rifiuta di avviarsi e stampa [un errore che nomina la fonte](/docs/it/errors#managed-settings-document-could-not-be-parsed), anche quando un'altra fonte admin distribuisce una policy valida. Ogni fonte fallisce in questo modo quando:

326

327* **File di impostazioni gestite o file drop-in**: il file non è JSON valido, o il suo livello superiore non è un oggetto

328* **MDM plist**: il `plutil` di macOS segnala il plist malformato, o il suo contenuto convertito non è un oggetto JSON

329* **Valore di registro HKLM**: il valore `Settings` non è una stringa, è vuoto, o non contiene un oggetto JSON

330

331Tre stati di fonte non causano questo rifiuto:

332

333* Un file, profilo, o valore di registro assente non è un fallimento; Claude Code viene eseguito senza quella fonte.

334* Un file di impostazioni gestite vuoto conta come `{}`.

335* Un valore malformato nella chiave di registro HKCU scrivibile dall'utente non blocca mai l'avvio. Claude Code lo segnala come un avviso in `/status` e `claude doctor` invece.

336

337Se un file di impostazioni gestite, un file drop-in, o una directory `managed-settings.d/` non può essere letto e nessuna fonte admin fornisce una policy, le sessioni firmate con credenziali claude.ai o Claude Console escono all'avvio con un messaggio per contattare un amministratore.

338

339Per trovare una voce eliminata, guarda in uno di tre posti:

340

341* Le sessioni interattive mostrano una finestra di dialogo all'avvio che elenca le voci non valide.

342* Le esecuzioni non interattive con `-p` stampano un riepilogo su stderr.

343* [`claude doctor`](/docs/it/debug-your-config) elenca ogni voce non valida con la sua fonte e campo.

344

345<h4 id="keys-that-fail-closed">

346 Chiavi che falliscono chiuse

347</h4>

348

349Poche chiavi di applicazione non vengono eliminate quando non valide. Claude Code applica un fallback più restrittivo fino a quando il valore non viene corretto; la tabella mostra cosa applica per ogni chiave:

350

351| Campo | Comportamento quando presente ma non valido |

352| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

353| `allowedMcpServers` | Applicato come un allowlist vuoto fino a quando il valore non viene corretto, quindi nessun server MCP che gli utenti aggiungono viene ammesso. I server che la tua organizzazione distribuisce tramite [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) si caricano ancora, e i server `managed-mcp.json` si caricano per [How a server is evaluated](/docs/it/managed-mcp#how-a-server-is-evaluated). Una voce non valida individuale viene rimossa e il sottoinsieme valido viene applicato. |

354| `allowedHttpHookUrls` | Claude Code applica un [allowlist](/docs/it/settings-reference#allowedhttphookurls) gestito vuoto fino a quando non correggi il valore, quindi un hook HTTP viene eseguito solo se un altro file di impostazioni elenca il suo URL. Se solo una voce individuale non è valida, Claude Code rimuove quella voce e applica il resto. |

355| `httpHookAllowedEnvVars` | Claude Code applica un [allowlist](/docs/it/settings-reference#httphookallowedenvvars) gestito vuoto fino a quando non correggi il valore, quindi una variabile di intestazione viene interpolata solo se un altro file di impostazioni la nomina. Se solo una voce individuale non è valida, Claude Code rimuove quella voce e applica il resto. |

356| `allowedChannelPlugins` | Claude Code applica un allowlist vuoto fino a quando non correggi il valore, quindi nessun plugin di canale passato a `--channels` viene ammesso. Se solo una voce individuale non è valida, rimuove quella voce e applica il resto. |

357| `allowManagedHooksOnly` | Trattato come `true` fino a quando non viene corretto: le [restrizioni hook](/docs/it/settings-reference#allowmanagedhooksonly) si applicano e, a meno che `disableCommandPluginSources` non sia esplicitamente `false`, i plugin sourced da comando sono disabilitati. |

358| `allowManagedMcpServersOnly` | Trattato come `true`. |

359| `disableCommandPluginSources` | Trattato come `true`, quindi i plugin sourced da comando rimangono disabilitati fino a quando il valore non viene corretto. |

360| `availableModels` | Applicato come un allowlist vuoto fino a quando non viene corretto, quindi solo il modello Default è disponibile; una voce non stringa viene rimossa e il sottoinsieme valido viene applicato. |

361| `enforceAvailableModels` | Trattato come `true`. |

362| `forceLoginOrgUUID` | Nessuna organizzazione è autorizzata ad accedere fino a quando il valore non viene corretto. |

363| `crossSessionInbound` | Trattato come `refuse`, il valore più restrittivo, quindi i [messaggi cross-session](/docs/it/cross-session-messaging#control-inbound-messages) in entrata vengono rifiutati fino a quando il valore non viene corretto. Lo sviluppatore vede [un avviso](/docs/it/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse). |

364| `deniedMcpServers` | Una voce non valida individuale viene rimossa e il sottoinsieme valido viene applicato. Un valore completamente non valido viene eliminato con un avviso, poiché negare ogni server bloccherebbe i server che la policy non ha mai nominato. |

365| `sandbox.credentials` | Una voce non valida recuperabile viene degradata a `mode: "deny"` con un avviso; una non recuperabile viene rimossa; le voci valide rimangono applicate. Vedi [invalid credential entries](/docs/it/settings-reference#invalid-credential-entries-in-managed-settings) |

366

367`allowedHttpHookUrls` e `httpHookAllowedEnvVars` si uniscono tra i file di impostazioni, quindi le voci nelle tue impostazioni utente, progetto o locale si applicano ancora mentre l'elenco gestito è vuoto. I fallback per queste due chiavi e per `allowedChannelPlugins` richiedono Claude Code v2.1.267 o successivo; le versioni precedenti eliminano l'intera chiave quando il suo valore o qualsiasi voce non è valida.

368

369`requiredMinimumVersion` e `requiredMaximumVersion` falliscono aperti per design: un valore non valido viene eliminato piuttosto che applicato.

370

371Questa tolleranza si applica solo alle impostazioni gestite. I file di impostazioni utente, progetto e locale rimangono rigorosi: un file il cui JSON o forma di livello superiore non supera la convalida viene rifiutato completamente e segnalato, e una voce individuale che fallisce, come una regola di autorizzazione malformata, viene saltata con un avviso mentre il resto del file si applica.

372

373<span id="managed-only-settings" />

374

375<h2 id="keys-only-a-managed-source-can-set">

376 Chiavi che solo una fonte gestita può impostare

377</h2>

378

379Claude Code legge le seguenti chiavi solo da una fonte gestita; posizionarle nei file di impostazioni utente o progetto non ha effetto.

380

381La maggior parte di loro sono lock: il valore che un lock governa, come regole di autorizzazione o `sandbox.network.allowedDomains`, è una chiave ordinaria che qualsiasi livello può impostare, e il lock dice a Claude Code di onorare solo il valore gestito.

382

383La tabella copre i controlli di autorizzazione, plugin e consegna. Per qualsiasi chiave non elencata qui, la colonna Scope del [settings reference](/docs/it/settings-reference#all-settings) index dice se è managed-only; le chiavi managed-only rimanenti lì includono l'URL di accesso al gateway, versione, browser, mobile-simulator, host SSH, Desktop local-session, percorso binario sandbox, prezzo del modello, e controlli CLAUDE.md.

384

385| Impostazione | Descrizione |

386| :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

387| [`allowAllClaudeAiMcps`](/docs/it/settings-reference#allowallclaudeaimcps) | Carica i connettori claude.ai che Claude Code recupera da solo insieme a un `managed-mcp.json` distribuito invece di sopprimerli |

388| [`allowedChannelPlugins`](/docs/it/settings-reference#allowedchannelplugins) | Allowlist di plugin di canale che possono inviare messaggi. Sostituisce l'allowlist Anthropic predefinito quando impostato. Richiede `channelsEnabled: true`. Vedi [Restrict which channel plugins can run](/docs/it/channels#restrict-which-channel-plugins-can-run) |

389| [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) | Quando `true`, limita quali hook vengono eseguiti; vedi [what runs under `allowManagedHooksOnly`](/docs/it/settings-reference#what-runs-under-allowmanagedhooksonly) per l'elenco completo degli effetti |

390| [`allowManagedMcpServersOnly`](/docs/it/settings-reference#allowmanagedmcpserversonly) | Quando `true`, solo `allowedMcpServers` dalle impostazioni gestite sono rispettati. `deniedMcpServers` si unisce ancora da tutte le fonti. Vedi [Managed MCP configuration](/docs/it/managed-mcp) |

391| [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) | Rende le impostazioni gestite l'unica fonte di impostazioni delle regole di autorizzazione. La voce elenca ogni fonte che ignora |

392| [`blockedMarketplaces`](/docs/it/settings-reference#blockedmarketplaces) | Blocklist di fonti di marketplace. Le fonti bloccate vengono controllate prima del download, quindi non toccano mai il filesystem. Vedi [managed marketplace restrictions](/docs/it/plugin-marketplaces#managed-marketplace-restrictions) |

393| [`channelsEnabled`](/docs/it/settings-reference#channelsenabled) | Consenti [channels](/docs/it/channels) per l'organizzazione. Vedi [enterprise controls](/docs/it/channels#enterprise-controls) per il default su ogni piano |

394| [`disableCommandPluginSources`](/docs/it/settings-reference#disablecommandpluginsources) | Quando `true`, blocca completamente le [fonti plugin `command`](/docs/it/plugin-marketplaces#command-sources), quindi il comando dichiarato dal marketplace non viene mai eseguito. Blocca anche i comandi [`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) del marketplace, tranne per un marketplace che le impostazioni gestite stesse dichiarano. Quando non impostato, segue `allowManagedHooksOnly`. Richiede Claude Code v2.1.229 o successivo, e il blocco `headersHelper` richiede v2.1.238 o successivo |

395| [`disableSideloadFlags`](/docs/it/settings-reference#disablesideloadflags) | Rifiuta i flag `--plugin-dir`, `--plugin-url`, `--agents`, e `--mcp-config` all'avvio. Nelle sessioni cloud, Claude Code elimina i server MCP che il server ha consegnato tramite `--mcp-config`, diversi dalle voci in-process `type: "sdk"`, e avvia la sessione. Richiede Claude Code v2.1.193 o successivo |

396| [`forceRemoteSettingsRefresh`](/docs/it/settings-reference#forceremotesettingsrefresh) | Quando `true`, blocca l'avvio CLI fino a quando le impostazioni gestite remote non vengono recuperate di fresco e esce se il fetch fallisce. Vedi [fail-closed enforcement](/docs/it/server-managed-settings#enforce-fail-closed-startup) |

397| [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) | Server MCP remoti forniti a ogni utente insieme ai loro. Fornisce server piuttosto che bloccare qualcosa. Vedi [Provide servers through managed settings](/docs/it/managed-mcp#provide-servers-through-managed-settings). Richiede Claude Code v2.1.259 o successivo |

398| [`managedSourcesBehavior`](/docs/it/settings-reference#managedsourcesbehavior) | Se Claude Code applica solo la fonte gestita con priorità più alta o [compone ogni una di loro](#compose-every-managed-source) |

399| [`parentSettingsBehavior`](/docs/it/settings-reference#parentsettingsbehavior) | Se le impostazioni parent fornite dall'host si uniscono sotto la policy gestita |

400| [`pluginSuggestionMarketplaces`](/docs/it/settings-reference#pluginsuggestionmarketplaces) | Marketplace i cui plugin Claude Code può suggerire agli utenti |

401| [`pluginTrustMessage`](/docs/it/settings-reference#plugintrustmessage) | Messaggio personalizzato aggiunto all'avviso di fiducia del plugin mostrato prima dell'installazione |

402| [`policyHelper`](/docs/it/settings-reference#policyhelper) | Eseguibile che calcola le impostazioni gestite all'avvio; vedi [Compute managed settings with a policy helper](/docs/it/settings-reference#policyhelper) |

403| [`sandbox.filesystem.allowManagedReadPathsOnly`](/docs/it/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | Quando `true`, solo i percorsi `filesystem.allowRead` dalle impostazioni gestite sono rispettati. `denyRead` si unisce ancora da tutte le fonti |

404| [`sandbox.network.allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) | Onora solo le regole di autorizzazione `allowedDomains` e `WebFetch(domain:...)` gestite; blocca altri domini senza chiedere |

405| [`strictKnownMarketplaces`](/docs/it/settings-reference#strictknownmarketplaces) | Controlla quali fonti di marketplace di plugin gli utenti possono aggiungere e installare plugin da. Vedi [managed marketplace restrictions](/docs/it/plugin-marketplaces#managed-marketplace-restrictions) |

406| [`strictPluginOnlyCustomization`](/docs/it/settings-reference#strictpluginonlycustomization) | Blocca skills, agents, hooks e server MCP da fonti utente e progetto; `true` blocca tutti e quattro, un array nomina quale |

407| [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings) | Quando impostato nel registro HKLM o in un file sotto `C:\Program Files\ClaudeCode`, fai leggere a WSL la catena di policy Windows, e leggi `/etc/claude-code` solo quando nessun file di impostazioni gestite o drop-in sotto quella directory distribuisce una [chiave di policy](#how-claude-code-combines-managed-sources); la voce fornisce l'ordine |

408

409<Note>

410 Sui piani Team e Enterprise, un Owner abilita o disabilita [Remote Control](/docs/it/remote-control) e [web sessions](/docs/it/claude-code-on-the-web) a livello di organizzazione nelle [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). Remote Control può inoltre essere disabilitato per dispositivo con l'impostazione [`disableRemoteControl`](/docs/it/settings-reference#disableremotecontrol). Le sessioni web non hanno chiave di impostazioni gestite per dispositivo.

411

412 Per verificare se queste impostazioni dell'organizzazione hanno raggiunto una determinata macchina, esegui `claude doctor` lì e leggi la riga `Organization policy`, che dice dove Claude Code ha caricato la policy o perché non l'ha caricata. Richiede Claude Code v2.1.261 o successivo. In una sessione in esecuzione, `/status` mostra la stessa riga quando la policy non è stata caricata.

413</Note>

414

415<h2 id="turn-telemetry-off-for-your-organization">

416 Disattivare la telemetria per la vostra organizzazione

417</h2>

418

419Claude Code invia [telemetria](/docs/it/data-usage#telemetry-services) operazionale ad Anthropic per impostazione predefinita nelle sessioni che utilizzano l'API Anthropic, sia direttamente, tramite un gateway LLM, o tramite un `ANTHROPIC_BASE_URL` personalizzato; [Default behaviors by API provider](/docs/it/data-usage#default-behaviors-by-api-provider) indica quali provider la inviano. Per disattivarla per ogni sviluppatore senza affidarsi alla shell di ogni persona, fornite `DISABLE_TELEMETRY` tramite il blocco `env` delle vostre impostazioni gestite. Questo esempio imposta `DISABLE_TELEMETRY` per tutti gli sviluppatori raggiunti dalla policy:

420

421```json theme={null}

422{

423 "env": {

424 "DISABLE_TELEMETRY": "1"

425 }

426}

427```

428

429Claude Code applica un valore di `1` senza mostrare all'utente la [finestra di dialogo di approvazione](/docs/it/server-managed-settings#environment-variables-and-the-approval-dialog).

430

431Se disattivate la telemetria, Claude Code smette di inviare i dati di utilizzo che alimentano la [dashboard di analitiche](/docs/it/analytics) della vostra organizzazione per gli sviluppatori raggiunti dalla policy. La variabile disattiva anche il recupero dei feature flag, il che rende Remote Control, la modalità auto predefinita e le altre [funzionalità che richiedono il recupero dei feature flag](/docs/it/env-vars#features-that-need-feature-flag-fetching) non disponibili per quegli sviluppatori.

432

433[Where and when a policy applies](#where-and-when-a-policy-applies) indica quale meccanismo di distribuzione raggiunge ogni superficie, e [Platform availability](/docs/it/server-managed-settings#platform-availability) indica quali sessioni saltano il recupero delle impostazioni gestite dal server.

434

435Se la vostra organizzazione utilizza chiavi di crittografia gestite dal cliente e instrada Claude Code tramite un gateway, [Configure proxies and gateways](/docs/it/third-party-integrations#configure-proxies-and-gateways) spiega perché quelle sessioni hanno bisogno di questa variabile.

436

437<h2 id="see-also">

438 Vedi anche

439</h2>

440

441* [Set up Claude Code for your organization](/docs/it/admin-setup): decidi cosa applicare e come

442* [Server-managed settings](/docs/it/server-managed-settings): distribuisci policy dalla console claude.ai o da un gateway

443* [Managed MCP configuration](/docs/it/managed-mcp): controlla quali server MCP gli sviluppatori possono usare

444* [All settings](/docs/it/settings-reference): ogni chiave, con se una fonte gestita può impostarla

445* [Example settings files](/docs/it/settings-example#an-organizations-managed-settings): un `managed-settings.json` completo che mostra la forma delle chiavi gestite

mcp.md +14 −8

Details

52 * `Marketplace "claude-plugins-official" non trovato`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.52 * `Marketplace "claude-plugins-official" non trovato`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

53 * Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.53 * Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.

54 54

~~55 Controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, esegui quel comando.~~55 Se il riepilogo dell'installazione segnala `Run /reload-plugins to activate.`, Claude Code esegue quindi quel ricaricamento per te. Se il ricaricamento avverte che il tuo prossimo messaggio rileggerebbe la conversazione, esegui `/reload-plugins --force`.

56 </Step>56 </Step>

57 57

58 <Step title="Esegui lo skill di compilazione">58 <Step title="Esegui lo skill di compilazione">

102 Il trasporto SSE (Server-Sent Events) è deprecato. Utilizza server HTTP invece, dove disponibili.102 Il trasporto SSE (Server-Sent Events) è deprecato. Utilizza server HTTP invece, dove disponibili.

103</Warning>103</Warning>

104 104

105Alcuni servizi espongono ancora solo un endpoint SSE. Utilizza lo stesso comando del trasporto HTTP, con `--transport sse`:105Alcuni servizi espongono ancora solo un endpoint SSE. Aggiungili con lo stesso comando `claude mcp add --transport http <name> <url>` di [un server HTTP](#option-1-add-a-remote-http-server). Claude Code prova prima il trasporto HTTP e passa a SSE quando il server non lo accetta. Il passaggio automatico richiede Claude Code v2.1.265 o successivo.

106

107Su una versione precedente, o per connettersi su SSE direttamente, passa invece `--transport sse`:

106 108

107```bash theme={null}109```bash theme={null}

108# Sintassi di base110# Sintassi di base

183 Da un URL185 Da un URL

184</h4>186</h4>

185 187

186Un URL significa che il server è remoto. Per un endpoint `https://`, aggiungilo con `--transport http`, o con `--transport sse` quando le istruzioni dicono che l'endpoint utilizza SSE. Per un endpoint `wss://`, utilizza invece l'[Opzione 4](#option-4-add-a-remote-websocket-server), poiché `--transport` non accetta `ws`:188Un URL significa che il server è remoto. Per un endpoint `https://`, aggiungilo con `--transport http`, o segui l'[Opzione 2](#option-2-add-a-remote-sse-server) quando le istruzioni dicono che l'endpoint utilizza SSE. Per un endpoint `wss://`, utilizza invece l'[Opzione 4](#option-4-add-a-remote-websocket-server), poiché `--transport` non accetta `ws`:

187 189

188```bash theme={null}190```bash theme={null}

189claude mcp add --transport http example https://mcp.example.com/mcp191claude mcp add --transport http example https://mcp.example.com/mcp

307Quando completi l'autenticazione da `/mcp` e la connessione fallisce ancora con uno stato HTTP o un codice di errore di trasporto, Claude Code aggiunge quel codice e l'origine dell'URL che ha provato al messaggio che stampa dopo il tentativo. L'origine è lo schema e l'host, più la porta quando l'URL ne nomina una, come `https://mcp.example.com`.309Quando completi l'autenticazione da `/mcp` e la connessione fallisce ancora con uno stato HTTP o un codice di errore di trasporto, Claude Code aggiunge quel codice e l'origine dell'URL che ha provato al messaggio che stampa dopo il tentativo. L'origine è lo schema e l'host, più la porta quando l'URL ne nomina una, come `https://mcp.example.com`.

308 310

309* Il percorso e la query non appaiono mai in quel messaggio.311* Il percorso e la query non appaiono mai in quel messaggio.

310* Claude Code prende l'origine dopo l'espansione `${VAR}`, quindi un host che proviene da una variabile appare espanso.312* Per un server nella [scope](#mcp-installation-scopes) locale, di progetto, o utente o nella configurazione MCP gestita, l'origine mostra l'host come scritto in quella configurazione, quindi un riferimento `${VAR}` nell'host non viene espanso nel messaggio.

311* Per un fallimento senza codice di stato o di errore, Claude Code mostra il testo di errore senza l'origine.313* Per un fallimento senza codice di stato o di errore, Claude Code mostra il testo di errore senza l'origine.

312 314

313Un server remoto la cui configurazione ha un `url` vuoto viene mostrato come `not configured` in `/mcp`, in `claude mcp list`, e nel gestore [`/plugin`](/docs/it/plugins), e Claude Code non tenta di connettersi ad esso. Un plugin può includere una voce segnaposto come questa per un connettore che configuri in seguito, quindi Claude Code non lo segnala come un errore o un problema di configurazione. La vista dei dettagli del server in `/mcp` legge `No URL configured for this server`; imposta l'`url` della voce per connetterlo. Prima della v2.1.208, Claude Code segnalava un `url` vuoto come un problema di configurazione con un prompt per riconnettersi.315Un server remoto la cui configurazione ha un `url` vuoto viene mostrato come `not configured` in `/mcp`, in `claude mcp list`, e nel gestore [`/plugin`](/docs/it/plugins), e Claude Code non tenta di connettersi ad esso. Un plugin può includere una voce segnaposto come questa per un connettore che configuri in seguito, quindi Claude Code non lo segnala come un errore o un problema di configurazione. La vista dei dettagli del server in `/mcp` legge `No URL configured for this server`; imposta l'`url` della voce per connetterlo. Prima della v2.1.208, Claude Code segnalava un `url` vuoto come un problema di configurazione con un prompt per riconnettersi.

371* Non registra un server [channel](#push-messages-with-channels) che si connette sulla revisione più recente, perché quella revisione non può trasportare messaggi di canale.373* Non registra un server [channel](#push-messages-with-channels) che si connette sulla revisione più recente, perché quella revisione non può trasportare messaggi di canale.

372* Fallisce un [accesso OAuth MCP](#authenticate-with-remote-mcp-servers) la cui risposta di autorizzazione nomina un emittente inaspettato.374* Fallisce un [accesso OAuth MCP](#authenticate-with-remote-mcp-servers) la cui risposta di autorizzazione nomina un emittente inaspettato.

373 375

374Anthropic può mantenere un server specifico sul protocollo precedente, o fuori da quel flusso, con un flag di funzionalità che Claude Code recupera. In una sessione [Claude Code sul web](/docs/it/cloud-environments#network-access), Claude Code chiede ai suoi connettori MCP solo se imposti `MCP_PROTOCOL_NEGOTIATION` su `auto`.376Anthropic può mantenere un server specifico sul protocollo precedente, o fuori da quel flusso, con un flag di funzionalità che Claude Code recupera.

375 377

376Per scegliere il runtime tu stesso, imposta [`MCP_SDK_GENERATION`](/docs/it/env-vars) su `v1` o `v2`. Per decidere se Claude Code chiede, imposta [`MCP_PROTOCOL_NEGOTIATION`](/docs/it/env-vars) su `auto` o `legacy`. Dove Claude Code utilizza v1 per impostazione predefinita, fissare `v2` non lo fa chiedere, quindi imposta anche `auto`.378Per scegliere il runtime tu stesso, imposta [`MCP_SDK_GENERATION`](/docs/it/env-vars) su `v1` o `v2`. Per decidere se Claude Code chiede, imposta [`MCP_PROTOCOL_NEGOTIATION`](/docs/it/env-vars) su `auto` o `legacy`. Dove Claude Code utilizza v1 per impostazione predefinita, fissare `v2` non lo fa chiedere, quindi imposta anche `auto`.

377 379

535 537

536* **Ciclo di vita automatico**: i server si connettono e si disconnettono in questi punti:538* **Ciclo di vita automatico**: i server si connettono e si disconnettono in questi punti:

537 * All'avvio della sessione, Claude Code connette automaticamente i server per i plugin abilitati. In `/mcp`, un server di plugin remoto (HTTP o SSE) che hai usato prima può mostrare lo stato [`cached`](#server-status-detail) invece; Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti539 * All'avvio della sessione, Claude Code connette automaticamente i server per i plugin abilitati. In `/mcp`, un server di plugin remoto (HTTP o SSE) che hai usato prima può mostrare lo stato [`cached`](#server-status-detail) invece; Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti

538 * Se abiliti o disabiliti un plugin durante una sessione, esegui `/reload-plugins` per connettere o disconnettere i suoi server MCP. In una sessione senza un terminale interattivo, il ricaricamento non connette o disconnette i server MCP del plugin; quelle modifiche hanno effetto nella tua prossima sessione540 * Se abiliti o disabiliti un plugin durante una sessione, Claude Code connette o disconnette i suoi server MCP quando il cambiamento si applica. [Applicare i cambiamenti dei plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) descrive quando è. In una sessione senza un terminale interattivo, `/reload-plugins` non connette o disconnette i server MCP del plugin; quelle modifiche hanno effetto nella tua prossima sessione

539 * Quando ricarichi, Claude Code mantiene le connessioni live dei server di plugin la cui configurazione è invariata, e fa lo stesso quando [sostituisci l'elenco dei server MCP della sessione](/docs/it/agent-sdk/typescript#mcpsetserversresult) dall'Agent SDK senza nominarli541 * Quando ricarichi, Claude Code mantiene le connessioni live dei server di plugin la cui configurazione è invariata, e fa lo stesso quando [sostituisci l'elenco dei server MCP della sessione](/docs/it/agent-sdk/typescript#mcpsetserversresult) dall'Agent SDK senza nominarli

540 * Quando [sposti la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory) su v2.1.246 o successivo, Claude Code connette i server dei plugin che le impostazioni della nuova directory abilitano e disconnette i server dei plugin che non sono più abilitati, quindi non devi eseguire `/reload-plugins` dopo lo spostamento542 * Quando [sposti la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory) su v2.1.246 o successivo, Claude Code connette i server dei plugin che le impostazioni della nuova directory abilitano e disconnette i server dei plugin che non sono più abilitati, quindi non devi eseguire `/reload-plugins` dopo lo spostamento

541 * Nelle [sessioni web](/docs/it/claude-code-on-the-web), una chiamata MCP a un server di plugin che non è ancora connesso, come subito dopo il risveglio di una sessione inattiva, avvia il server su richiesta e attende che si connetta543 * Nelle [sessioni web](/docs/it/claude-code-on-the-web), una chiamata MCP a un server di plugin che non è ancora connesso, come subito dopo il risveglio di una sessione inattiva, avvia il server su richiesta e attende che si connetta

584</Note>586</Note>

585 587

586```bash theme={null}588```bash theme={null}

587# Aggiungi un server con ambio locale (predefinito)589# Aggiungi un server con ambito locale (predefinito)

588claude mcp add --transport http stripe https://mcp.stripe.com590claude mcp add --transport http stripe https://mcp.stripe.com

589 591

590# Specifica esplicitamente l'ambito locale592# Specifica esplicitamente l'ambito locale

634 636

635Per motivi di sicurezza, Claude Code richiede l'approvazione in sessioni interattive prima di utilizzare server con ambito del progetto dai file `.mcp.json`. Per ripristinare queste scelte di approvazione, esegui `claude mcp reset-project-choices`.637Per motivi di sicurezza, Claude Code richiede l'approvazione in sessioni interattive prima di utilizzare server con ambito del progetto dai file `.mcp.json`. Per ripristinare queste scelte di approvazione, esegui `claude mcp reset-project-choices`.

636 638

637Nelle esecuzioni `claude -p`, nelle sessioni [Agent SDK](/docs/it/headless) e nelle [sessioni cloud](/docs/it/claude-code-on-the-web), Claude Code non può mostrare quel prompt: carica i server con ambito del progetto senza chiedere. Claude Code salta anche il prompt in una sessione che avvii in modalità `bypassPermissions` con [`skipDangerousModePermissionPrompt`](/docs/it/settings-reference#skipdangerousmodepermissionprompt) impostato. Per mantenere un server fuori comunque:639Nelle esecuzioni `claude -p`, nelle sessioni [Agent SDK](/docs/it/headless) e nelle [sessioni cloud](/docs/it/claude-code-on-the-web), Claude Code non può mostrare quel prompt: carica i server con ambito del progetto senza chiedere. Claude Code salta anche il prompt in una sessione che avvii in modalità `bypassPermissions` con [`skipDangerousModePermissionPrompt`](/docs/it/settings-reference#skipdangerousmodepermissionprompt) impostato nelle tue impostazioni utente o nelle impostazioni gestite. Per mantenere un server fuori comunque:

638 640

639* Aggiungilo a [`disabledMcpjsonServers`](/docs/it/settings-reference#disabledmcpjsonservers), che lo blocca in ogni modalità di autorizzazione.641* Aggiungilo a [`disabledMcpjsonServers`](/docs/it/settings-reference#disabledmcpjsonservers), che lo blocca in ogni modalità di autorizzazione.

640* Escludi completamente le impostazioni del progetto con [`--setting-sources`](/docs/it/cli-reference#cli-flags) o l'opzione `settingSources` dell'SDK.642* Escludi completamente le impostazioni del progetto con [`--setting-sources`](/docs/it/cli-reference#cli-flags) o l'opzione `settingSources` dell'SDK.

778* Per un server a cui non hai effettuato l'accesso, uno di questi codici di stato lo contrassegna in `/mcp` in modo che tu possa completare il flusso OAuth.780* Per un server a cui non hai effettuato l'accesso, uno di questi codici di stato lo contrassegna in `/mcp` in modo che tu possa completare il flusso OAuth.

779* Per un [connettore claude.ai](#use-mcp-servers-from-claude-ai), un `401` causato dal rifiuto di claude.ai del tuo token di sessione non contrassegna il connettore, perché la riautorizzazione del connettore non può risolvere il tuo accesso. Claude Code mostra invece lo [stato di rifiuto del token di sessione](/docs/it/errors#claude-ai-rejected-the-session-token).781* Per un [connettore claude.ai](#use-mcp-servers-from-claude-ai), un `401` causato dal rifiuto di claude.ai del tuo token di sessione non contrassegna il connettore, perché la riautorizzazione del connettore non può risolvere il tuo accesso. Claude Code mostra invece lo [stato di rifiuto del token di sessione](/docs/it/errors#claude-ai-rejected-the-session-token).

780* Per un server il cui header `Authorization` hai configurato, in `headers` o tramite un [`headersHelper`](#use-dynamic-headers-for-custom-authentication), un `401` o `403` durante la connessione non contrassegna il server, perché la credenziale da correggere è quella che hai configurato. Claude Code segnala invece la connessione come non riuscita.782* Per un server il cui header `Authorization` hai configurato, in `headers` o tramite un [`headersHelper`](#use-dynamic-headers-for-custom-authentication), un `401` o `403` durante la connessione non contrassegna il server, perché la credenziale da correggere è quella che hai configurato. Claude Code segnala invece la connessione come non riuscita.

783* Per un connettore [consegnato a una sessione cloud](#how-connectors-reach-claude-code), Claude Code non esegue un flusso di accesso, perché il proxy della sessione si autentica al connettore con l'autorizzazione che hai concesso in claude.ai. Quando un connettore lì ha bisogno di autorizzazione di nuovo, riconnettilo su [claude.ai/customize/connectors](https://claude.ai/customize/connectors) piuttosto che dalla sessione.

781 784

782Quando una richiesta a un server OAuth a cui hai già effettuato l'accesso restituisce `401 Unauthorized`, Claude Code aggiorna il token archiviato, si riconnette e ritenta la richiesta una volta. Contrassegna il server in `/mcp` solo se anche quel tentativo non riesce. Prima della v2.1.206, un aggiornamento del token che non riusciva per un motivo transitorio, come un errore di rete, contrassegnava un server OAuth come richiedente autenticazione per il resto della sessione anche se il suo token di aggiornamento era ancora valido.785Quando una richiesta a un server OAuth a cui hai già effettuato l'accesso restituisce `401 Unauthorized`, Claude Code aggiorna il token archiviato, si riconnette e ritenta la richiesta una volta. Contrassegna il server in `/mcp` solo se anche quel tentativo non riesce. Prima della v2.1.206, un aggiornamento del token che non riusciva per un motivo transitorio, come un errore di rete, contrassegnava un server OAuth come richiedente autenticazione per il resto della sessione anche se il suo token di aggiornamento era ancora valido.

783 786

923 Suggerimenti:926 Suggerimenti:

924 927

925 * Il segreto client viene archiviato in modo sicuro nel tuo portachiavi di sistema (macOS) o in un file di credenziali, non nella tua configurazione928 * Il segreto client viene archiviato in modo sicuro nel tuo portachiavi di sistema (macOS) o in un file di credenziali, non nella tua configurazione

929 * Puoi impostare il segreto client solo quando aggiungi il server. Quando ti autentichi con `claude mcp login` o da `/mcp`, Claude Code utilizza il segreto archiviato e non richiede uno o legge `MCP_CLIENT_SECRET`

930 * Per aggiungere o modificare il segreto in seguito, rimuovi il server con `claude mcp remove <name>`, quindi aggiungilo di nuovo con `--client-secret` e lo stesso `--scope`

926 * Se il server utilizza un client OAuth pubblico senza segreto, utilizza solo `--client-id` senza `--client-secret`931 * Se il server utilizza un client OAuth pubblico senza segreto, utilizza solo `--client-id` senza `--client-secret`

927 * Questi flag si applicano solo ai trasporti HTTP e SSE. Non hanno effetto sui server stdio932 * Questi flag si applicano solo ai trasporti HTTP e SSE. Non hanno effetto sui server stdio

928 * Utilizza `claude mcp get <name>` per verificare che le credenziali OAuth siano configurate per un server933 * Utilizza `claude mcp get <name>` per verificare che le credenziali OAuth siano configurate per un server

1328* **Limite configurabile**: è possibile regolare il massimo numero di token di output MCP consentiti utilizzando la variabile di ambiente `MAX_MCP_OUTPUT_TOKENS`1333* **Limite configurabile**: è possibile regolare il massimo numero di token di output MCP consentiti utilizzando la variabile di ambiente `MAX_MCP_OUTPUT_TOKENS`

1329* **Limite predefinito**: il massimo predefinito è 25.000 token1334* **Limite predefinito**: il massimo predefinito è 25.000 token

1330* **Ambito**: la variabile di ambiente si applica agli strumenti che non dichiarano il proprio limite. Gli strumenti che impostano [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) utilizzano invece quel valore per il contenuto di testo, indipendentemente da ciò che `MAX_MCP_OUTPUT_TOKENS` è impostato. Gli strumenti che restituiscono dati di immagine sono comunque soggetti a `MAX_MCP_OUTPUT_TOKENS`1335* **Ambito**: la variabile di ambiente si applica agli strumenti che non dichiarano il proprio limite. Gli strumenti che impostano [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) utilizzano invece quel valore per il contenuto di testo, indipendentemente da ciò che `MAX_MCP_OUTPUT_TOKENS` è impostato. Gli strumenti che restituiscono dati di immagine sono comunque soggetti a `MAX_MCP_OUTPUT_TOKENS`

1336* **Oltre il limite**: quando un risultato senza contenuto di immagine supera il limite, Claude Code lo salva in un file e lo sostituisce nella conversazione con un messaggio che nomina il percorso del file, in modo che Claude legga il file quando ha bisogno del contenuto. Il file si trova nella directory `tool-results` della sessione sotto [`~/.claude/projects/`](/docs/it/claude-directory#cleaned-up-automatically).

1331 1337

1332Per aumentare il limite per gli strumenti che producono output di grandi dimensioni:1338Per aumentare il limite per gli strumenti che producono output di grandi dimensioni:

1333 1339

memory.md +66 −31

Details

25Claude Code ha due sistemi di memoria complementari. Entrambi vengono caricati all'inizio di ogni conversazione. Claude li tratta come contesto, non come configurazione forzata. Per bloccare un'azione indipendentemente da ciò che Claude decide, utilizza un [hook PreToolUse](/docs/it/hooks-guide) invece. Più specifiche e concise sono le tue istruzioni, più coerentemente Claude le segue.25Claude Code ha due sistemi di memoria complementari. Entrambi vengono caricati all'inizio di ogni conversazione. Claude li tratta come contesto, non come configurazione forzata. Per bloccare un'azione indipendentemente da ciò che Claude decide, utilizza un [hook PreToolUse](/docs/it/hooks-guide) invece. Più specifiche e concise sono le tue istruzioni, più coerentemente Claude le segue.

26 26

27| | File CLAUDE.md | Memoria automatica |27| | File CLAUDE.md | Memoria automatica |

~~28| :---------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------- |~~28| :---------------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |

29| **Chi lo scrive** | Tu | Claude |29| **Chi lo scrive** | Tu | Claude |

34 34

35Usa file CLAUDE.md quando vuoi guidare il comportamento di Claude. La memoria automatica consente a Claude di imparare dalle tue correzioni senza sforzo manuale.35Usa file CLAUDE.md quando vuoi guidare il comportamento di Claude. La memoria automatica consente a Claude di imparare dalle tue correzioni senza sforzo manuale.

36 36

70 70

71I file CLAUDE.md e CLAUDE.local.md nella gerarchia di directory sopra la directory di lavoro vengono caricati completamente all'avvio. I file nelle sottodirectory vengono caricati su richiesta quando Claude legge i file in quelle directory. Vedi [Come vengono caricati i file CLAUDE.md](#how-claude-md-files-load) per l'ordine di risoluzione completo.71I file CLAUDE.md e CLAUDE.local.md nella gerarchia di directory sopra la directory di lavoro vengono caricati all'avvio. I file nelle sottodirectory vengono caricati su richiesta quando Claude legge i file in quelle directory. Vedi [Come vengono caricati i file CLAUDE.md](#how-claude-md-files-load) per l'ordine di risoluzione completo.

72 72

73Per i progetti di grandi dimensioni, puoi suddividere le istruzioni in file specifici per argomento utilizzando [regole di progetto](#organize-rules-with-claude/rules/). Le regole ti consentono di limitare le istruzioni a tipi di file specifici o sottodirectory.73Per i progetti di grandi dimensioni, puoi suddividere le istruzioni in file specifici per argomento utilizzando [regole di progetto](#organize-rules-with-claude/rules/). Le regole ti consentono di limitare le istruzioni a tipi di file specifici o sottodirectory.

74 74

76 Configura un CLAUDE.md di progetto76 Configura un CLAUDE.md di progetto

77</h3>77</h3>

78 78

79Un CLAUDE.md di progetto può essere archiviato in `./CLAUDE.md` o `./.claude/CLAUDE.md`. Crea questo file e aggiungi istruzioni che si applicano a chiunque lavori sul progetto: comandi di compilazione e test, standard di codifica, decisioni architettoniche, convenzioni di denominazione e flussi di lavoro comuni. Queste istruzioni vengono condivise con il tuo team tramite controllo del codice sorgente, quindi concentrati su standard a livello di progetto piuttosto che su preferenze personali.79Un CLAUDE.md di progetto può essere archiviato in `./CLAUDE.md` o `./.claude/CLAUDE.md`. Crea questo file e aggiungi istruzioni che si applicano a chiunque lavori sul progetto: comandi di compilazione e test, standard di codifica, decisioni architettoniche, convenzioni di denominazione e flussi di lavoro comuni. Queste istruzioni vengono condivise con il tuo team tramite controllo del codice sorgente, quindi concentrati su standard a livello di progetto piuttosto che su preferenze personali. Per confermare che il file è stato caricato, esegui `/context` in una sessione e controlla l'elenco sotto **Memory files**.

80 80

81<Tip>81<Tip>

82 Esegui `/init` per generare automaticamente un CLAUDE.md iniziale. Claude analizza la tua base di codice e crea un file con comandi di compilazione, istruzioni di test e convenzioni di progetto che scopre. Se esiste già un CLAUDE.md, `/init` suggerisce miglioramenti piuttosto che sovrascriverlo. Perfezionalo da lì con istruzioni che Claude non scoprirebbe da solo.82 Esegui `/init` per generare automaticamente un CLAUDE.md iniziale. Claude analizza la tua base di codice e crea un file con comandi di compilazione, istruzioni di test e convenzioni di progetto che scopre. Se esiste già un CLAUDE.md, `/init` suggerisce miglioramenti piuttosto che sovrascriverlo. Perfezionalo da lì con istruzioni che Claude non scoprirebbe da solo.

121- flusso di lavoro git @docs/git-instructions.md121- flusso di lavoro git @docs/git-instructions.md

122```122```

123 123

124Per le preferenze personali per progetto che non vuoi archiviare nel controllo del codice sorgente, crea un `CLAUDE.local.md` nella radice del progetto. Si carica insieme a `CLAUDE.md` e viene trattato allo stesso modo. Aggiungi `CLAUDE.local.md` al tuo `.gitignore` in modo che non venga sottoposto a commit; eseguire `/init` e scegliere l'opzione personale lo fa per te.124Per le preferenze personali per progetto che non vuoi archiviare nel controllo del codice sorgente, crea un `CLAUDE.local.md` nella radice del progetto. Si carica insieme a `CLAUDE.md` e viene trattato allo stesso modo. Aggiungi `CLAUDE.local.md` al tuo `.gitignore` in modo che non venga sottoposto a commit. Con `CLAUDE_CODE_NEW_INIT=1` impostato, eseguire `/init` e scegliere l'opzione personale lo fa per te.

125 125

126Se lavori su più git worktrees dello stesso repository, un `CLAUDE.local.md` ignorato da git esiste solo nel worktree dove lo hai creato. Per condividere istruzioni personali tra worktrees, importa un file dalla tua home directory invece:126Se lavori su più git worktrees dello stesso repository, un `CLAUDE.local.md` ignorato da git esiste solo nel worktree dove lo hai creato. Per condividere istruzioni personali tra worktrees, importa un file dalla tua home directory invece:

127 127

131```131```

132 132

133<Warning>133<Warning>

134 La prima volta che Claude Code incontra importazioni esterne in un progetto, mostra una finestra di dialogo di approvazione che elenca i file. Se rifiuti, le importazioni rimangono disabilitate e la finestra di dialogo non appare di nuovo.134 Un'importazione in un file di memoria a livello di progetto è esterna quando il suo percorso si risolve al di fuori della tua directory di lavoro, come l'importazione della home directory sopra. La prima volta che Claude Code incontra importazioni esterne in un progetto, mostra una finestra di dialogo di approvazione che elenca i file. Se rifiuti, le importazioni rimangono disabilitate e la finestra di dialogo non appare di nuovo.

135</Warning>135

136 Claude Code mostra la finestra di dialogo per proteggerti da file che altre persone eseguono il commit in un progetto condiviso. I file di memoria con ambito utente, come `~/.claude/CLAUDE.md` e `~/.claude/rules/`, sono file che hai scritto tu stesso. Tranne nelle sessioni [Cowork](https://claude.com/product/cowork) sul tuo desktop, Claude Code carica le loro importazioni senza la finestra di dialogo e le considera attendibili come il resto della tua configurazione personale.

136 137

137Per un approccio più strutturato all'organizzazione delle istruzioni, vedi [`.claude/rules/`](#organize-rules-with-claude/rules/).138 Nelle sessioni Cowork sul tuo desktop, Claude Code salta qualsiasi importazione in un file con ambito utente che si risolve a un percorso al di fuori della directory di lavoro della sessione e carica il resto del file. In quelle sessioni salta anche un `~/.claude/CLAUDE.md` che è esso stesso un symlink o un hard link, e una directory `~/.claude/rules/` symlink o un file di regola che punta al di fuori della directory di lavoro.

139</Warning>

138 140

139<h3 id="agents-md">141<h3 id="agents-md">

140 AGENTS.md142 AGENTS.md

156ln -s AGENTS.md CLAUDE.md158ln -s AGENTS.md CLAUDE.md

157```159```

158 160

159Su Windows, la creazione di un symlink richiede privilegi di amministratore o modalità sviluppatore, quindi usa l'importazione `@AGENTS.md` invece.161Il comando non stampa alcun output in caso di successo. Nella tua prossima sessione, esegui `/context` e conferma che `CLAUDE.md` appare sotto **Memory files**.

160 162

161L'esecuzione di [`/init`](/docs/it/commands) in un repository che ha già un `AGENTS.md` lo legge e incorpora le parti rilevanti nel `CLAUDE.md` generato. Legge anche altre configurazioni di strumenti come `.cursorrules`, `.devin/rules/` e `.windsurfrules`.163L'esecuzione di [`/init`](/docs/it/commands) legge le regole Cursor, in `.cursor/rules/` o `.cursorrules`, e le regole Copilot, in `.github/copilot-instructions.md`, e incorpora le parti rilevanti nel `CLAUDE.md` generato. Con `CLAUDE_CODE_NEW_INIT=1` impostato, `/init` legge anche `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` o `.windsurfrules`, e `.clinerules`.

164

165Puoi anche eseguire [`/import`](/docs/it/commands) per portare la configurazione di un agente di codifica supportato in Claude Code, che aggiunge una copia una tantum di file di istruzioni come `AGENTS.md` al `CLAUDE.md` corrispondente e trasporta server MCP, comandi, subagent e skills. Richiede Claude Code v2.1.213 o successivo.

162 166

163<h3 id="how-claude-md-files-load">167<h3 id="how-claude-md-files-load">

164 Come vengono caricati i file CLAUDE.md168 Come vengono caricati i file CLAUDE.md

165</h3>169</h3>

166 170

167Claude Code legge i file CLAUDE.md camminando verso l'alto nell'albero delle directory dalla tua directory di lavoro corrente, controllando ogni directory lungo il percorso per i file `CLAUDE.md` e `CLAUDE.local.md`. Ciò significa che se esegui Claude Code in `foo/bar/`, carica le istruzioni da `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` e qualsiasi file `CLAUDE.local.md` accanto a loro.171Claude Code carica `CLAUDE.md` e `CLAUDE.local.md` dalla tua directory di lavoro corrente e da ogni directory sopra di essa. Esegui Claude Code in `foo/bar/` e carica le istruzioni da `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` e qualsiasi file `CLAUDE.local.md` accanto a loro.

168 172

169Tutti i file scoperti vengono concatenati nel contesto piuttosto che sovrascriversi a vicenda. All'interno della gerarchia di directory, il contenuto è ordinato dalla radice del file system fino alla tua directory di lavoro. Per l'esempio `foo/bar/`, `foo/CLAUDE.md` appare nel contesto prima di `foo/bar/CLAUDE.md`, quindi le istruzioni più vicine a dove hai lanciato Claude vengono lette per ultime. All'interno di ogni directory, `CLAUDE.local.md` viene aggiunto dopo `CLAUDE.md`, quindi le tue note personali sono l'ultima cosa che Claude legge a quel livello.173Tutti i file scoperti vengono concatenati nel contesto piuttosto che sovrascriversi a vicenda. All'interno della gerarchia di directory, il contenuto è ordinato dalla radice del file system fino alla tua directory di lavoro. Per l'esempio `foo/bar/`, `foo/CLAUDE.md` appare nel contesto prima di `foo/bar/CLAUDE.md`, quindi le istruzioni più vicine a dove hai lanciato Claude vengono lette per ultime. All'interno di ogni directory, `CLAUDE.local.md` viene aggiunto dopo `CLAUDE.md`, quindi le tue note personali sono l'ultima cosa che Claude legge a quel livello.

170 174

216 220

217Le regole senza [frontmatter `paths`](#path-specific-rules) vengono caricate all'avvio con la stessa priorità di `.claude/CLAUDE.md`.221Le regole senza [frontmatter `paths`](#path-specific-rules) vengono caricate all'avvio con la stessa priorità di `.claude/CLAUDE.md`.

218 222

223Le regole di progetto vengono saltate se escludi `project` da [`--setting-sources`](/docs/it/cli-reference). Prima della v2.1.211, le regole che si caricano su richiesta, incluse le regole con ambito di percorso e le regole nelle directory `.claude/rules/` annidate, si caricavano anche quando `project` era escluso.

224

219<h4 id="path-specific-rules">225<h4 id="path-specific-rules">

220 Regole specifiche del percorso226 Regole specifiche del percorso

221</h4>227</h4>

257---263---

258```264```

259 265

266Ogni gruppo tra parentesi graffe moltiplica il numero di modelli espansi: `src/*.{ts,tsx}` si espande a due modelli, e `{a,b}/{c,d}/*.{ts,tsx}` a otto. Per mantenere l'espansione limitata, l'intero elenco `paths` di una regola condivide un budget di 1.000 modelli espansi e 4 MiB, e i modelli senza parentesi graffe non contano contro di esso.

267

268Claude Code utilizza qualsiasi modello che supererebbe il budget non espanso, e le sue parentesi graffe letterali non corrispondono a nessun file. Prima della v2.1.217, un valore `paths` con molti gruppi tra parentesi graffe bloccava o causava l'arresto anomalo della CLI all'avvio.

269

260La sintassi glob tratta `[` come l'inizio di un'espressione tra parentesi graffe come `[abc]`. Un modello con un `[` che non può essere letto come un'espressione tra parentesi graffe, come `photos [2024/**`, non è valido: non corrisponde a nulla, e gli altri modelli della regola continuano a funzionare. Per abbinare un `[` letterale in un nome di file, sfuggilo come `photos \[2024/**`. Prima della v2.1.207, un modello non valido causava il fallimento dello strumento Read per ogni file su cui la regola veniva valutata, invece di non corrispondere a nulla.270La sintassi glob tratta `[` come l'inizio di un'espressione tra parentesi graffe come `[abc]`. Un modello con un `[` che non può essere letto come un'espressione tra parentesi graffe, come `photos [2024/**`, non è valido: non corrisponde a nulla, e gli altri modelli della regola continuano a funzionare. Per abbinare un `[` letterale in un nome di file, sfuggilo come `photos \[2024/**`. Prima della v2.1.207, un modello non valido causava il fallimento dello strumento Read per ogni file su cui la regola veniva valutata, invece di non corrispondere a nulla.

261 271

262<h4 id="share-rules-across-projects-with-symlinks">272<h4 id="share-rules-across-projects-with-symlinks">

263 Condividi le regole tra i progetti con symlink273 Condividi le regole tra i progetti con symlink

264</h4>274</h4>

265 275

266La directory `.claude/rules/` supporta symlink, quindi puoi mantenere un set di regole condivise e collegarle a più progetti. I symlink vengono risolti e caricati normalmente, e i symlink circolari vengono rilevati e gestiti correttamente.276La directory `.claude/rules/` supporta symlink, quindi puoi mantenere un set di regole condivise e collegarle a più progetti. I symlink circolari vengono rilevati e gestiti correttamente.

277

278Claude Code tratta un symlink il cui target è al di fuori della tua directory di lavoro come un'[importazione esterna](#import-additional-files). Le regole collegate non si caricano fino a quando non approvi le importazioni esterne per il progetto, e dopo di che solo quelle senza un campo [`paths`](#path-specific-rules) si caricano. Claude Code chiede quell'approvazione solo quando un file di memoria di progetto importa un file al di fuori della directory di lavoro con `@path`, non per i symlink da soli. Per caricare le regole condivise senza quell'approvazione, mantienile in [`~/.claude/rules/`](#user-level-rules), dove si applicano a ogni progetto sulla tua macchina.

267 279

268Questo esempio collega sia una directory condivisa che un file individuale:280Questo esempio collega sia una directory condivisa che un file individuale:

269 281

306 </Step>318 </Step>

307 319

308 <Step title="Distribuisci con il tuo sistema di gestione della configurazione">320 <Step title="Distribuisci con il tuo sistema di gestione della configurazione">

309 Usa MDM, Group Policy, Ansible o strumenti simili per distribuire il file tra le macchine degli sviluppatori. Vedi [impostazioni gestite](/docs/it/permissions#managed-settings) per altre opzioni di configurazione a livello di organizzazione.321 Usa MDM, Group Policy, Ansible o strumenti simili per distribuire il file tra le macchine degli sviluppatori. Vedi [impostazioni gestite](/docs/it/managed-settings) per altre opzioni di configurazione a livello di organizzazione.

310 </Step>322 </Step>

311</Steps>323</Steps>

312 324

326}338}

327```339```

328 340

329Un CLAUDE.md gestito e [impostazioni gestite](/docs/it/settings#settings-files) servono a scopi diversi. Usa le impostazioni per l'applicazione tecnica e CLAUDE.md per la guida comportamentale:341Un CLAUDE.md gestito e [impostazioni gestite](/docs/it/managed-settings) servono a scopi diversi. Usa le impostazioni per l'applicazione tecnica e CLAUDE.md per la guida comportamentale:

330 342

331| Preoccupazione | Configura in |343| Preoccupazione | Configura in |

332| :----------------------------------------------------- | :------------------------------------------------------------ |344| :----------------------------------------------------- | :------------------------------------------------------------ |

357}369}

358```370```

359 371

360I modelli vengono abbinati ai percorsi di file assoluti usando la sintassi glob. Puoi configurare `claudeMdExcludes` in qualsiasi [livello di impostazioni](/docs/it/settings#settings-files): utente, progetto, locale o politica gestita. Gli array si uniscono tra i livelli.372I modelli vengono abbinati ai percorsi di file assoluti usando la sintassi glob. Puoi configurare `claudeMdExcludes` in qualsiasi [livello di impostazioni](/docs/it/settings#where-settings-live): utente, progetto, locale o politica gestita. Gli array si uniscono tra i livelli.

373

374Per escludere un file di regole che raggiungi attraverso un [symlink](#share-rules-across-projects-with-symlinks), sia che il file che la sua directory sia il link, scrivi il modello rispetto a uno dei due percorsi: il percorso del file sotto `.claude/rules/` o il suo target di link. Un modello che corrisponde a uno dei due percorsi esclude il file. Prima della v2.1.239, solo un modello che corrispondeva al target del link escludeva il file.

361 375

362I file CLAUDE.md della politica gestita non possono essere esclusi. Ciò garantisce che le istruzioni a livello di organizzazione si applichino sempre indipendentemente dalle impostazioni individuali.376I file CLAUDE.md della politica gestita non possono essere esclusi. Ciò garantisce che le istruzioni a livello di organizzazione si applichino sempre indipendentemente dalle impostazioni individuali.

363 377

365 Memoria automatica379 Memoria automatica

366</h2>380</h2>

367 381

368La memoria automatica consente a Claude di accumulare conoscenze tra le sessioni senza che tu scriva nulla. Claude salva note per se stesso mentre lavora: comandi di compilazione, approfondimenti sul debug, note sull'architettura, preferenze di stile del codice e abitudini di flusso di lavoro. Claude non salva qualcosa ogni sessione. Decide cosa vale la pena ricordare in base al fatto che l'informazione sarebbe utile in una conversazione futura.382La memoria automatica consente a Claude di accumulare conoscenze tra le sessioni senza che tu scriva nulla. Mentre lavora, Claude salva quattro tipi di note per se stesso. Claude registra il tipo come campo `type` nel frontmatter del file di memoria:

383

384* `user`: il tuo ruolo, competenze e preferenze di lavoro

385* `feedback`: correzioni che dai a Claude e approcci che confermi

386* `project`: lavoro in corso, scadenze e decisioni che Claude non può derivare dal codice o dalla cronologia git

387* `reference`: dove trovare informazioni al di fuori del progetto, come un issue tracker o una dashboard

388

389Claude salta qualsiasi cosa possa derivare dalla codebase, come architettura, percorsi di file o correzioni di debug. Salta anche qualsiasi cosa i tuoi file CLAUDE.md dicono già.

390

391Claude non salva qualcosa ogni sessione. Decide cosa vale la pena ricordare in base al fatto che l'informazione sarebbe utile in una conversazione futura.

369 392

370<h3 id="enable-or-disable-auto-memory">393<h3 id="enable-or-disable-auto-memory">

371 Abilita o disabilita la memoria automatica394 Abilita o disabilita la memoria automatica

372</h3>395</h3>

373 396

374La memoria automatica è attivata per impostazione predefinita. Per attivarla/disattivarla, apri `/memory` in una sessione e usa l'interruttore di memoria automatica, oppure imposta `autoMemoryEnabled` nelle impostazioni del tuo progetto:397La memoria automatica è attivata per impostazione predefinita. Per attivarla/disattivarla, apri `/memory` in una sessione e usa l'interruttore di memoria automatica, che salva `autoMemoryEnabled` nelle impostazioni utente in `~/.claude/settings.json`. Per disattivarla per un singolo progetto, imposta `autoMemoryEnabled` nelle impostazioni di quel progetto:

375 398

376```json theme={null}399```json theme={null}

377{400{

387 410

388Ogni progetto ottiene la propria directory di memoria in `~/.claude/projects/<project>/memory/`. Il percorso `<project>` è derivato dal repository git, quindi tutti i worktrees e le sottodirectory all'interno dello stesso repo condividono una directory di memoria automatica. Al di fuori di un repository git, viene utilizzata la radice del progetto.411Ogni progetto ottiene la propria directory di memoria in `~/.claude/projects/<project>/memory/`. Il percorso `<project>` è derivato dal repository git, quindi tutti i worktrees e le sottodirectory all'interno dello stesso repo condividono una directory di memoria automatica. Al di fuori di un repository git, viene utilizzata la radice del progetto.

389 412

413Se imposti [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/it/sessions#name-the-project-directory-yourself) accanto a `CLAUDE_CONFIG_DIR`, Claude Code utilizza quel nome come directory `<project>` sotto `<config dir>/projects/` indipendentemente da quale repository avvii, quindi i progetti avviati con quella directory di configurazione condividono una directory di memoria automatica. Richiede Claude Code v2.1.234 o successivo.

414

390Per archiviare la memoria automatica in una posizione diversa, imposta `autoMemoryDirectory` nel tuo `settings.json`. Viene letto da qualsiasi [ambito di impostazioni](/docs/it/settings#settings-precedence): utente, progetto, locale, politica, o `--settings`.415Per archiviare la memoria automatica in una posizione diversa, imposta `autoMemoryDirectory` nel tuo `settings.json`. Viene letto da qualsiasi [ambito di impostazioni](/docs/it/settings#settings-precedence): utente, progetto, locale, politica, o `--settings`.

391 416

392```json theme={null}417```json theme={null}

395}420}

396```421```

397 422

398Il valore deve essere un percorso assoluto o iniziare con `~/`. Quando impostato nel `.claude/settings.json` o `.claude/settings.local.json` di un progetto, il valore viene rispettato solo dopo che accetti la finestra di dialogo di trust dell'area di lavoro per quella cartella, lo stesso gate che governa i hooks.423Il valore deve essere un percorso assoluto o iniziare con `~/`. Quando lo imposti nel `.claude/settings.json` o `.claude/settings.local.json` di un progetto, Claude Code lo rispetta secondo la stessa [regola di trust dell'area di lavoro dei hook nei file di impostazioni](/docs/it/permissions#what-runs-before-you-trust-a-folder).

399 424

400La directory contiene un punto di ingresso `MEMORY.md` e file di argomento opzionali:425La directory contiene un indice `MEMORY.md` e un file di argomento per memoria:

401 426

402```text theme={null}427```text theme={null}

403~/.claude/projects/<project>/memory/428~/.claude/projects/<project>/memory/

404├── MEMORY.md # Indice conciso, caricato in ogni sessione429├── MEMORY.md # Indice, una riga per memoria, caricato in ogni sessione

405├── debugging.md # Note dettagliate sui modelli di debug430├── user_role.md # Una memoria

406├── api-conventions.md # Decisioni di progettazione API431├── feedback_testing.md # Una memoria

407└── ... # Qualsiasi altro file di argomento che Claude crea432└── ... # Qualsiasi altro file di argomento che Claude crea

408```433```

409 434

411 436

412La memoria automatica è locale alla macchina. Tutti i worktrees e le sottodirectory all'interno dello stesso repository git condividono una directory di memoria automatica. I file non vengono condivisi tra macchine o ambienti cloud.437La memoria automatica è locale alla macchina. Tutti i worktrees e le sottodirectory all'interno dello stesso repository git condividono una directory di memoria automatica. I file non vengono condivisi tra macchine o ambienti cloud.

413 438

439Claude Code elimina i vecchi transcript di sessione dopo il periodo di conservazione [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays), ma esclude i file di memoria nella directory di memoria da quella [scansione di conservazione](/docs/it/claude-directory#cleaned-up-automatically). `MEMORY.md` e i file di argomento rimangono fino a quando tu o Claude non li modificate o eliminate.

440

414<h3 id="how-it-works">441<h3 id="how-it-works">

415 Come funziona442 Come funziona

416</h3>443</h3>

417 444

418Le prime 200 righe di `MEMORY.md`, o i primi 25KB, a seconda di quale viene raggiunto per primo, vengono caricate all'inizio di ogni conversazione. Il contenuto oltre quella soglia non viene caricato all'inizio della sessione. Claude mantiene `MEMORY.md` conciso spostando le note dettagliate in file di argomento separati.445Le prime 200 righe di `MEMORY.md`, o i primi 25KB, a seconda di quale viene raggiunto per primo, vengono caricate all'inizio di ogni conversazione. Il contenuto oltre quella soglia non viene caricato all'inizio della sessione. Claude mantiene `MEMORY.md` conciso spostando le note dettagliate in file di argomento separati.

419 446

420Questo limite si applica solo a `MEMORY.md`. I file CLAUDE.md vengono caricati completamente indipendentemente dalla lunghezza, anche se i file più brevi producono una migliore aderenza.447Dopo che Claude scrive in `MEMORY.md`, Claude Code misura il file rispetto ai limiti di lettura di 200 righe e 25KB. Se il file è vicino a un limite, Claude Code ricorda a Claude di accorciarlo: mantieni una riga per voce, sposta i dettagli nei file di argomento e unisci o elimina le voci obsolete. Se il file supera un limite, la scrittura ha comunque successo, ma Claude Code restituisce un [errore che dice a Claude di riscrivere l'indice](/docs/it/errors#memory-index-is-over-its-read-limit), perché tutto ciò che supera il limite viene eliminato al caricamento successivo.

421 448

422I file di argomento come `debugging.md` o `patterns.md` non vengono caricati all'avvio. Claude li legge su richiesta usando i suoi strumenti di file standard quando ha bisogno delle informazioni.449Questo limite si applica solo a `MEMORY.md`. Claude Code carica un file CLAUDE.md fino a 4 MiB completamente e salta un file più grande. I file più brevi producono una migliore aderenza.

423 450

424Claude legge e scrive file di memoria durante la tua sessione. Quando vedi "Writing memory" o "Recalled memory" nell'interfaccia di Claude Code, Claude sta attivamente aggiornando o leggendo da `~/.claude/projects/<project>/memory/`.451Claude Code non carica i file di argomento come `user_role.md` o `feedback_testing.md` all'avvio. Claude li legge su richiesta usando i suoi strumenti di file standard quando ha bisogno delle informazioni.

452

453La memoria automatica della conversazione principale non viene caricata nei [subagenti](/docs/it/sub-agents#what-loads-at-startup); l'eccezione è un [fork](/docs/it/sub-agents#fork-the-current-conversation), che eredita la conversazione padre e il prompt di sistema. La memoria automatica di un subagente, abilitata con il campo `memory` del subagente, è una directory separata.

454

455Claude legge e scrive file di memoria durante la tua sessione. Quando vedi messaggi come "Saved 2 memories" o "Recalled 2 memories" nell'interfaccia di Claude Code, Claude sta attivamente aggiornando o leggendo da `~/.claude/projects/<project>/memory/`.

456

457Quando Claude scrive un file di memoria che inizia con frontmatter YAML, Claude Code registra l'ora di scrittura in un campo frontmatter `modified` come timestamp ISO 8601. Il timestamp mostra quanto è attuale il fatto, sia per te che per Claude quando lo legge di nuovo. Qualsiasi file che ha frontmatter ottiene il campo la prossima volta che Claude lo scrive, inclusi i file creati in versioni precedenti; Claude Code non aggiunge mai frontmatter a un file che non ne ha. Il campo `modified` richiede Claude Code v2.1.214 o successivo.

425 458

426<h3 id="audit-and-edit-your-memory">459<h3 id="audit-and-edit-your-memory">

427 Controlla e modifica la tua memoria460 Controlla e modifica la tua memoria

433 Visualizza e modifica con `/memory`466 Visualizza e modifica con `/memory`

434</h2>467</h2>

435 468

436Il comando `/memory` elenca tutti i file CLAUDE.md, CLAUDE.local.md e rules caricati nella tua sessione corrente, ti consente di attivare o disattivare la memoria automatica e fornisce un collegamento per aprire la cartella di memoria automatica. Seleziona qualsiasi file per aprirlo nel tuo editor.469Il comando `/memory` elenca i tuoi file CLAUDE.md, CLAUDE.local.md e altri file di memoria in tutti gli ambiti utente e progetto, incluse le voci CLAUDE.md utente e progetto per i file che non esistono ancora. Ti consente inoltre di attivare o disattivare la memoria automatica e fornisce un'opzione per aprire la cartella di memoria automatica. Seleziona qualsiasi file per aprirlo nel tuo editor; selezionando uno che non esiste ancora lo crea prima. Per verificare quali file sono effettivamente caricati nella sessione corrente, esegui `/context`.

470

471Gli editor GUI come VS Code aprono il file in una finestra separata e puoi continuare a utilizzare la sessione mentre è aperta. Prima della v2.1.216, `/memory` attendeva che chiudessi il file prima di rispondere. Gli editor terminali come Vim prendono il controllo del terminale fino a quando non esci.

437 472

438Quando chiedi a Claude di ricordare qualcosa, come "usa sempre pnpm, non npm" o "ricorda che i test API richiedono un'istanza Redis locale", Claude lo salva nella memoria automatica. Per aggiungere istruzioni a CLAUDE.md, chiedi direttamente a Claude, come "aggiungi questo a CLAUDE.md", oppure modifica il file tu stesso tramite `/memory`.473Quando chiedi a Claude di ricordare qualcosa, come "usa sempre pnpm, non npm" o "ricorda che i test API richiedono un'istanza Redis locale", Claude lo salva nella memoria automatica. Per aggiungere istruzioni a CLAUDE.md, chiedi direttamente a Claude, come "aggiungi questo a CLAUDE.md", oppure modifica il file tu stesso tramite `/memory`.

439 474

451 486

452Per eseguire il debug:487Per eseguire il debug:

453 488

454* Esegui `/memory` per verificare che i tuoi file CLAUDE.md e CLAUDE.local.md vengono caricati. Se un file non è elencato, Claude non può vederlo.489* Esegui `/context` e controlla l'elenco sotto **Memory files** per verificare che i tuoi file CLAUDE.md e CLAUDE.local.md siano stati caricati. Se un file non è presente lì, Claude non può vederlo. Usa `/memory` per aprire e modificare i file.

455* Verifica che il CLAUDE.md rilevante si trovi in una posizione che viene caricata per la tua sessione (vedi [Scegli dove mettere i file CLAUDE.md](#choose-where-to-put-claude-md-files)).490* Verifica che il CLAUDE.md rilevante si trovi in una posizione che viene caricata per la tua sessione (vedi [Scegli dove mettere i file CLAUDE.md](#choose-where-to-put-claude-md-files)).

456* Rendi le istruzioni più specifiche. "Usa indentazione a 2 spazi" funziona meglio di "formatta il codice bene".491* Rendi le istruzioni più specifiche. "Usa indentazione a 2 spazi" funziona meglio di "formatta il codice bene".

457* Cerca istruzioni conflittuali tra i file CLAUDE.md. Se due file danno una guida diversa per lo stesso comportamento, Claude potrebbe sceglierne una arbitrariamente.492* Cerca istruzioni conflittuali tra i file CLAUDE.md. Se due file danno una guida diversa per lo stesso comportamento, Claude potrebbe sceglierne una arbitrariamente.

458 493

459Se l'istruzione è qualcosa che deve essere eseguito in un punto specifico, come prima di ogni commit o dopo ogni modifica di file, scrivila come un [hook](/docs/it/hooks-guide). Gli hook vengono eseguiti come comandi shell in eventi del ciclo di vita fissi e si applicano indipendentemente da ciò che Claude decide di fare.494Se l'istruzione è qualcosa che deve essere eseguito in un punto specifico, come prima di ogni commit o dopo ogni modifica di file, scrivila come un [hook](/docs/it/hooks-guide). Gli hook vengono eseguiti come comandi shell in eventi del ciclo di vita fissi e si applicano indipendentemente da ciò che Claude decide di fare.

460 495

461Per le istruzioni che vuoi a livello di prompt di sistema, usa [`--append-system-prompt`](/docs/it/cli-reference#system-prompt-flags). Questo deve essere passato ad ogni invocazione, quindi è più adatto a script e automazione che all'uso interattivo.496Per le istruzioni che vuoi a livello di prompt di sistema, usa [`--append-system-prompt`](/docs/it/cli-reference#system-prompt-flags). Questo deve essere passato al lancio, quindi è più adatto a script e automazione che all'uso interattivo. Per come si comporta quando riprendi una conversazione, vedi [System prompt flags in resumed conversations](/docs/it/cli-reference#system-prompt-flags-in-resumed-conversations).

462 497

463<Tip>498<Tip>

464 Usa l'hook [`InstructionsLoaded`](/docs/it/hooks#instructionsloaded) per registrare esattamente quali file di istruzioni vengono caricati, quando vengono caricati e perché. Questo è utile per eseguire il debug di regole specifiche del percorso o file caricati pigriamente nelle sottodirectory.499 Usa l'hook [`InstructionsLoaded`](/docs/it/hooks#instructionsloaded) per registrare esattamente quali file di istruzioni vengono caricati, quando vengono caricati e perché. Questo è utile per eseguire il debug di regole specifiche del percorso o file caricati pigriamente nelle sottodirectory.

474 Il mio CLAUDE.md è troppo grande509 Il mio CLAUDE.md è troppo grande

475</h3>510</h3>

476 511

477I file con più di 200 righe consumano più contesto e possono ridurre l'aderenza. Usa [regole con ambito di percorso](#path-specific-rules) per caricare istruzioni solo quando Claude lavora con file corrispondenti, oppure riduci il contenuto che non è necessario in ogni sessione. La divisione in [importazioni `@path`](#import-additional-files) aiuta l'organizzazione ma non riduce il contesto, poiché i file importati vengono caricati all'avvio.512I file con più di 200 righe consumano più contesto e possono ridurre l'aderenza. Claude Code salta un file superiore a 4 MiB. Usa [regole con ambito di percorso](#path-specific-rules) per caricare istruzioni solo quando Claude lavora con file corrispondenti, oppure riduci il contenuto che non è necessario in ogni sessione. La divisione in [importazioni `@path`](#import-additional-files) aiuta l'organizzazione ma non riduce il contesto, poiché i file importati vengono caricati all'avvio.

478 513

479Il controllo [`/doctor`](/docs/it/commands#all-commands) propone riduzioni per un CLAUDE.md archiviato: taglia il contenuto che Claude può derivare dalla base di codice, come layout di directory, elenchi di dipendenze e panoramiche dell'architettura, e mantiene i rischi, la logica e le convenzioni che differiscono dai valori predefiniti dello strumento. Il controllo di riduzione richiede Claude Code v2.1.206 o successivo.514Il controllo [`/doctor`](/docs/it/commands#all-commands) propone riduzioni per un CLAUDE.md archiviato: taglia il contenuto che Claude può derivare dalla base di codice, come layout di directory, elenchi di dipendenze e panoramiche dell'architettura, e mantiene i rischi, la logica e le convenzioni che differiscono dai valori predefiniti dello strumento. Il controllo di riduzione richiede Claude Code v2.1.206 o successivo.

480 515

482 Le istruzioni sembrano perse dopo `/compact`517 Le istruzioni sembrano perse dopo `/compact`

483</h3>518</h3>

484 519

485CLAUDE.md di progetto sopravvive alla compattazione: dopo `/compact`, Claude rilegge il tuo CLAUDE.md dal disco e lo reinetta nella sessione. I file CLAUDE.md annidati nelle sottodirectory non vengono reinettati automaticamente; vengono ricaricati la prossima volta che Claude legge un file in quella sottodirectory.520CLAUDE.md di progetto sopravvive alla compattazione: dopo `/compact`, Claude rilegge il tuo CLAUDE.md dal disco e lo reinetta nella sessione. I file CLAUDE.md annidati nelle sottodirectory e le regole con [frontmatter `paths:`](#path-specific-rules) vengono ricaricati quando Claude legge i file a cui si applicano.

486 521

487Se un'istruzione è scomparsa dopo la compattazione, è stata data solo nella conversazione o si trova in un CLAUDE.md annidato che non è stato ancora ricaricato. Aggiungi istruzioni solo per conversazione a CLAUDE.md per farle persistere. Vedi [Cosa sopravvive alla compattazione](/docs/it/context-window#what-survives-compaction) per il breakdown completo.522Se un'istruzione è scomparsa dopo la compattazione, è stata data solo nella conversazione, si trova in un CLAUDE.md annidato che non è stato ancora ricaricato, oppure è una regola con ambito di percorso che non ha corrisposto a un file da allora. Aggiungi istruzioni solo per conversazione a CLAUDE.md per farle persistere. Vedi [Cosa sopravvive alla compattazione](/docs/it/context-window#what-survives-compaction) per il breakdown completo.

488 523

489Vedi [Scrivi istruzioni efficaci](#write-effective-instructions) per una guida su dimensione, struttura e specificità.524Vedi [Scrivi istruzioni efficaci](#write-effective-instructions) per una guida su dimensione, struttura e specificità.

490 525

mobile.md +104 −0 created

Details

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.

5# Claude Code su mobile

7> Avvia, monitora e guida i task di Claude Code dal tuo telefono con l'app Claude per iOS e Android.

9L'app Claude per [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) e [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) è un client per le sessioni di Claude Code piuttosto che un luogo dove il codice viene eseguito. Dal tuo telefono raggiungi [sessioni cloud](#start-and-monitor-cloud-sessions) nel cloud, una sessione in esecuzione sulla tua macchina tramite [Remote Control](#continue-a-local-session-with-remote-control), o l'app Desktop tramite [Dispatch](/docs/it/desktop#sessions-from-dispatch).

11<Note>

12 Claude Code non ha un'app mobile separata: le sessioni cloud e Remote Control vivono entrambe nella scheda **Code** nell'app Claude, e Dispatch è un task a cui invii messaggi nell'app.

13</Note>

15<h2 id="get-the-app">

16 Scarica l'app

17</h2>

19<Steps>

20 <Step title="Scarica l'app Claude">

21 Installa l'app Claude per [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) o [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude). Su un iPad, installa la stessa app iOS.

23 <Tip>

24 Esegui `/mobile` in una sessione di Claude Code per visualizzare un codice QR di download che puoi scansionare. `/ios` e `/android` fanno la stessa cosa.

25 </Tip>

26 </Step>

28 <Step title="Accedi">

29 Accedi con lo stesso account claude.ai e organizzazione che usi per Claude Code. Le sessioni cloud e Remote Control richiedono un account claude.ai, quindi non sono raggiungibili con una chiave API della Console Anthropic o da un provider di terze parti come Amazon Bedrock.

30 </Step>

32 <Step title="Apri la scheda Code">

33 Tocca **Code** nella navigazione dell'app per raggiungere le tue sessioni, o apri [claude.ai/code/new](https://claude.ai/code/new) sul tuo telefono per avviare una nuova sessione Code nell'app. Se non vedi la scheda Code, il tuo piano o organizzazione potrebbe non includere queste funzionalità; vedi [disponibilità per piano di abbonamento](/docs/it/feature-availability#availability-by-subscription-plan).

34 </Step>

35</Steps>

37<h2 id="work-from-your-phone">

38 Lavora dal tuo telefono

39</h2>

41Dall'app puoi avviare sessioni cloud, guidare una sessione di Claude Code in esecuzione sul tuo computer, o inviare un task a Dispatch tramite messaggio. L'app è la stessa per tutti e tre; differiscono nel luogo dove avviene il lavoro.

43| Funzionalità | A cosa ti connetti | Quando usare |

44| :------------------------------------------------ | :-------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

45| [Claude Code sul web](/docs/it/claude-code-on-the-web) | Una sessione cloud su infrastruttura cloud, gestita da Anthropic per impostazione predefinita | Il tuo repository è su GitHub e il task dovrebbe continuare a essere eseguito dopo aver messo il telefono via. Vedi la [guida rapida web](/docs/it/web-quickstart) per configurare. |

46| [Remote Control](/docs/it/remote-control) | Una sessione di Claude Code in esecuzione sul tuo computer | Il lavoro ha bisogno del tuo filesystem locale, strumenti o server MCP. |

47| [Dispatch](/docs/it/desktop#sessions-from-dispatch) | L'app Desktop sul tuo computer | Vuoi inviare un task tramite messaggio e lasciare che Dispatch decida come eseguirlo. Richiede un piano Pro o Max. |

49Se il tuo computer sarà spento, usa le sessioni cloud, che vengono eseguite nel cloud e continuano con il tuo laptop chiuso. Remote Control e Dispatch guidano la tua macchina, quindi deve rimanere accesa con Claude Code o l'app Desktop in esecuzione. Se la tua macchina va in sospensione durante una sessione Remote Control, Claude Code si riconnette quando la macchina torna online.

51Per un confronto più completo, vedi [lavora quando sei lontano dal tuo terminale](/docs/it/platforms#work-when-you-are-away-from-your-terminal).

53Le sessioni cloud e Remote Control vengono eseguite dalla scheda **Code**. Per Dispatch, che invii come task nell'app, vedi [sessioni da Dispatch](/docs/it/desktop#sessions-from-dispatch).

55<h3 id="start-and-monitor-cloud-sessions">

56 Avvia e monitora le sessioni cloud

57</h3>

59Claude Code sul web esegue task su infrastruttura cloud, gestita da Anthropic per impostazione predefinita, quindi una sessione continua dopo aver messo il telefono via. Dalla scheda Code, seleziona un repository e un branch, descrivi il task e invialo. Le sessioni persistono tra i dispositivi: un task che avvii sul tuo laptop è pronto per la revisione dal tuo telefono, e uno che avvii dal tuo telefono ti sta aspettando quando torni alla tua scrivania.

61Apri una sessione nell'app per controllare i progressi, rispondere alle domande di Claude, o guidarla in una nuova direzione. Puoi anche dire a Claude di [osservare una pull request](/docs/it/claude-code-on-the-web#auto-fix-pull-requests) e correggere i fallimenti CI o i commenti di revisione man mano che arrivano. Per connettere GitHub e configurare il tuo ambiente, segui la [guida rapida web](/docs/it/web-quickstart), e vedi [Claude Code sul web](/docs/it/claude-code-on-the-web) per tutto quello che le sessioni cloud possono fare.

63<h3 id="continue-a-local-session-with-remote-control">

64 Continua una sessione locale con Remote Control

65</h3>

67Remote Control connette l'app Claude a una sessione di Claude Code in esecuzione sulla tua macchina, quindi l'esecuzione del codice e l'accesso al filesystem rimangono locali mentre guidi la sessione dal tuo telefono. Avvia la sessione sul tuo computer con `claude remote-control`, o esegui `/remote-control` in una sessione già aperta. Quindi scansiona il codice QR della sessione che il terminale può visualizzare, o apri l'app Claude, tocca **Code**, e scegli la sessione dall'elenco. Vedi [connetti da un altro dispositivo](/docs/it/remote-control#connect-from-another-device) per ogni opzione.

69Quando aggiungi un allegato nell'app Claude, raggiunge anche la sessione locale:

71* **Foto**: Claude vede le foto allegate direttamente come parte del tuo messaggio. Claude Code salva anche ogni foto in `~/.claude/uploads/` e dice a Claude il percorso del file salvato, quindi Claude può copiare l'immagine nei file che crea.

72* **Altri file**: Claude Code li scarica sulla tua macchina e li passa a Claude come riferimenti di file `@`.

74Per i requisiti, le modalità di invocazione e la risoluzione dei problemi, vedi la [panoramica di Remote Control](/docs/it/remote-control).

76<h3 id="get-push-notifications">

77 Ricevi notifiche push

78</h3>

80Quando Remote Control è attivo, Claude può inviare notifiche push al tuo telefono, tipicamente quando un task a lunga esecuzione finisce o quando ha bisogno di una decisione da te. Puoi anche chiederne una nel tuo prompt, come `notificami quando i test finiscono`. Vedi [notifiche push mobile](/docs/it/remote-control#mobile-push-notifications) per i due toggle `/config` e la risoluzione dei problemi di consegna.

82Dispatch invia la sua propria notifica quando una sessione Code che ha generato finisce o ha bisogno della tua approvazione, descritta in [sessioni da Dispatch](/docs/it/desktop#sessions-from-dispatch).

84<h2 id="limitations">

85 Limitazioni

86</h2>

88Il client mobile copre la maggior parte di quello che una sessione ha bisogno, con alcune limitazioni:

90* **Comandi solo locali**: comandi che vengono eseguiti solo nell'interfaccia del terminale, come `/plugin` e `/resume`, non funzionano dall'app. Le [limitazioni di Remote Control](/docs/it/remote-control#limitations) elencano i comandi che funzionano da mobile e come il loro comportamento differisce.

91* **Modalità di autorizzazione**: le sessioni cloud offrono Accept edits, Plan e Auto nel dropdown della modalità, e le sessioni Remote Control offrono Manual, Accept edits e Plan. Non puoi selezionare Bypass permissions dall'app in nessuno dei due casi, e non puoi selezionare Auto per una sessione Remote Control. Vedi [cambia modalità di autorizzazione](/docs/it/permission-modes#switch-permission-modes).

92* **Piani Dispatch**: Dispatch richiede un piano Pro o Max e non è disponibile su Team o Enterprise.

94<h2 id="related-resources">

95 Risorse correlate

96</h2>

98* [Piattaforme e integrazioni](/docs/it/platforms): confronta ogni superficie su cui Claude Code viene eseguito

99* [Claude Code sul web](/docs/it/claude-code-on-the-web): come vengono eseguite le sessioni cloud e come spostare il lavoro da e verso il tuo terminale

100* [Configura ambienti cloud](/docs/it/cloud-environments): livelli di accesso di rete, variabili di ambiente e script di configurazione per le sessioni cloud

101* [Remote Control](/docs/it/remote-control): continua una sessione locale da qualsiasi dispositivo

102* [Sessioni da Dispatch](/docs/it/desktop#sessions-from-dispatch): come i task Dispatch diventano sessioni Code nell'app Desktop

103* [Channels](/docs/it/channels): chiedi a Claude qualcosa dal tuo telefono tramite Telegram, Discord o iMessage mentre il lavoro viene eseguito sulla tua macchina

104* [Claude Code in Slack](/docs/it/slack): delega task di codifica dal tuo workspace Slack menzionando `@Claude`

model-config.md +20 −8

Details

91* **Dimensionate i compiti più grandi**: dategli lavoro che normalmente dividereste in pezzi. Sostiene lunghe sessioni senza perdere il filo.91* **Dimensionate i compiti più grandi**: dategli lavoro che normalmente dividereste in pezzi. Sostiene lunghe sessioni senza perdere il filo.

92 92

93<Note>93<Note>

94 Fable 5.1 richiede Claude Code v2.1.257 o successiva. Se una richiesta per esso da una versione più vecchia fallisce, consultare [Claude Code does not support this model](/docs/it/errors#claude-code-does-not-support-this-model). Fable 5 richiede v2.1.170 o successiva. Eseguire `claude update` per aggiornare. Per la disponibilità con zero data retention, consultare [Model availability under ZDR](/docs/it/zero-data-retention#model-availability-under-zdr).94 Fable 5.1 richiede Claude Code v2.1.257 o successiva. Se una richiesta per esso da una versione più vecchia fallisce, consultare [Claude Code does not support this model](/docs/it/errors#claude-code-does-not-support-this-model). Eseguire `claude update` per aggiornare. Per la disponibilità con zero data retention, consultare [Model availability under ZDR](/docs/it/zero-data-retention#model-availability-under-zdr).

95</Note>95</Note>

96 96

97Sull'API Anthropic, il selettore `/model` elenca un modello Fable solo dopo che il server lo segnala come disponibile per la vostra organizzazione. Quando digitate `/model fable` o un ID del modello Fable, Claude Code controlla la disponibilità direttamente con il server, quindi una selezione digitata può avere successo anche quando il selettore non elenca la voce.97Sull'API Anthropic, il selettore `/model` elenca un modello Fable solo dopo che il server lo segnala come disponibile per la vostra organizzazione. Quando digitate `/model fable` o un ID del modello Fable, Claude Code controlla la disponibilità direttamente con il server, quindi una selezione digitata può avere successo anche quando il selettore non elenca la voce.

113 113

114Quello che potete fare mentre il prompt è in attesa dipende dalla sessione:114Quello che potete fare mentre il prompt è in attesa dipende dalla sessione:

115 115

116* Con Remote Control connesso o nella sessione di un compagno di squadra, premete un tasto qualsiasi al terminale per annullare la scadenza e Claude Code attende la vostra risposta.116* Con Remote Control connesso o nella sessione di un compagno di squadra, premete un tasto qualsiasi al terminale per annullare la scadenza, e Claude Code attende la vostra risposta.

117* In una sessione in background, rispondete prima della scadenza.117* In una sessione in background, rispondete prima della scadenza.

118* Se inviate un nuovo messaggio dal client remoto prima che qualcuno abbia digitato al terminale, Claude Code termina il turno allo stesso modo e il vostro nuovo messaggio inizia il turno successivo. Dopo che qualcuno digita al terminale, Claude Code continua ad aspettare la risposta e mette in coda il vostro nuovo messaggio dietro di essa.118* Se inviate un nuovo messaggio dal client remoto prima che qualcuno abbia digitato al terminale, Claude Code termina il turno allo stesso modo e il vostro nuovo messaggio inizia il turno successivo. Dopo che qualcuno digita al terminale, Claude Code continua ad aspettare la risposta e mette in coda il vostro nuovo messaggio dietro di essa.

119 119

136* `Enter`: passa il modello e salva come vostro valore predefinito136* `Enter`: passa il modello e salva come vostro valore predefinito

137* `s`: passa il modello solo per questa sessione137* `s`: passa il modello solo per questa sessione

138 138

139Digitare `/model <name>` direttamente si comporta come `Enter`. Un modello impostato con `/model` in [modalità non interattiva](/docs/it/headless), con il flag `-p`, si applica solo alla sessione attuale e non viene salvato come vostro valore predefinito. Le impostazioni di progetto e gestite mantengono comunque la precedenza e si riapplicano al prossimo avvio. Un [modello predefinito dell'organizzazione](#organization-default-model) che il vostro amministratore ha configurato per ignorare la selezione dell'utente si riapplica anche al prossimo avvio.139Digitare `/model <name>` direttamente si comporta come `Enter`. Se impostate un modello con `/model` in [modalità non interattiva](/docs/it/headless), con il flag `-p`, la vostra scelta si applica solo alla sessione attuale e non viene salvata come vostro valore predefinito; `/model` in quella modalità richiede Claude Code v2.1.205 o successiva. Le impostazioni di progetto e gestite mantengono comunque la precedenza e si riapplicano al prossimo avvio. Un [modello predefinito dell'organizzazione](#organization-default-model) che il vostro amministratore ha configurato per ignorare la selezione dell'utente si riapplica anche al prossimo avvio.

140 140

141Nella v2.1.144 attraverso v2.1.152, `/model` si applicava solo alla sessione attuale e `d` nel selettore salvava un valore predefinito.141Nella v2.1.144 attraverso v2.1.152, `/model` si applicava solo alla sessione attuale e `d` nel selettore salvava un valore predefinito.

142 142

425 Limiti di sforzo dell'organizzazione425 Limiti di sforzo dell'organizzazione

426</h2>426</h2>

427 427

428La vostra organizzazione può limitare il [livello di sforzo](#adjust-effort-level) in due modi. Su un piano Claude Enterprise, gli amministratori dell'organizzazione impostano limiti di sforzo per ruolo, descritti di seguito. Su qualsiasi piano e qualsiasi provider, inclusi Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry, l'impostazione gestita [`maxEffortLevel`](/docs/it/settings-reference#maxeffortlevel) limita lo sforzo sul client. Quando entrambi si applicano a un modello, si applica il limite inferiore.

429

428Gli amministratori dell'organizzazione nei piani Claude Enterprise possono impostare un [livello di sforzo](#adjust-effort-level) massimo per modello per ogni ruolo personalizzato, insieme alle [restrizioni del modello a livello di organizzazione](#organization-model-restrictions). I livelli superiori al limite non vengono offerti nel selettore `/effort`, e denominare un livello superiore con `--effort` o `/effort` viene eseguito al limite. Nelle sessioni interattive e nelle esecuzioni in testo semplice `--print`, un avviso nomina i livelli richiesti e applicati; con output `json` o `stream-json` o negli agenti in background, il limite si applica silenziosamente. I limiti sono per modello, quindi il cambio di modelli può modificare quali livelli sono disponibili. Quando diversi vostri ruoli concedono lo stesso modello, si applica il limite meno restrittivo. Richiede Claude Code v2.1.195 o successivo.430Gli amministratori dell'organizzazione nei piani Claude Enterprise possono impostare un [livello di sforzo](#adjust-effort-level) massimo per modello per ogni ruolo personalizzato, insieme alle [restrizioni del modello a livello di organizzazione](#organization-model-restrictions). I livelli superiori al limite non vengono offerti nel selettore `/effort`, e denominare un livello superiore con `--effort` o `/effort` viene eseguito al limite. Nelle sessioni interattive e nelle esecuzioni in testo semplice `--print`, un avviso nomina i livelli richiesti e applicati; con output `json` o `stream-json` o negli agenti in background, il limite si applica silenziosamente. I limiti sono per modello, quindi il cambio di modelli può modificare quali livelli sono disponibili. Quando diversi vostri ruoli concedono lo stesso modello, si applica il limite meno restrittivo. Richiede Claude Code v2.1.195 o successivo.

429 431

430I limiti di sforzo vengono forniti insieme alle [restrizioni del modello dell'organizzazione](#organization-model-restrictions) e raggiungono le stesse sessioni.432I limiti di sforzo vengono forniti insieme alle [restrizioni del modello dell'organizzazione](#organization-model-restrictions) e raggiungono le stesse sessioni.

463 465

464Questo abbina il ragionamento di Opus per la pianificazione con l'efficienza di Sonnet per l'esecuzione.466Questo abbina il ragionamento di Opus per la pianificazione con l'efficienza di Sonnet per l'esecuzione.

465 467

466La fase Opus in modalità piano utilizza la stessa finestra di contesto dell'impostazione del modello `opus`. Sui livelli di abbonamento in cui Opus viene [aggiornato automaticamente a 1M di contesto](#extended-context), `opusplan` riceve l'aggiornamento anche in modalità piano. Per forzare il contesto 1M per entrambe le fasi quando non sei su un livello di aggiornamento automatico, imposta il modello su `opusplan[1m]`.468La fase Opus in modalità piano utilizza la stessa finestra di contesto dell'impostazione del modello `opus`. Sui livelli di abbonamento in cui Opus viene [aggiornato automaticamente a 1M di contesto](#extended-context), `opusplan` riceve l'aggiornamento anche in modalità piano. Per forzare il contesto 1M per entrambe le fasi quando non sei su un livello di aggiornamento automatico, [imposta il modello](#setting-your-model) su `opusplan[1m]`, ad esempio con `/model opusplan[1m]`. Impostarlo con `/model` richiede Claude Code v2.1.265 o successiva; nelle versioni precedenti, usa il flag `--model` o l'impostazione `model`.

467 469

468Quando [`availableModels`](#restrict-model-selection) esclude l'Opus più recente ma consente una versione precedente, ad esempio `["sonnet", "claude-opus-4-6"]`, `opusplan` utilizza l'Opus più recente consentito per la pianificazione e rimane su Sonnet solo quando ogni Opus è escluso. Una sessione Haiku che normalmente si aggiornerebbe a Sonnet in modalità piano utilizza allo stesso modo il Sonnet più recente consentito e rimane su Haiku solo quando ogni Sonnet è escluso. Prima della v2.1.205, la modalità piano rimase sul modello della sessione ogni volta che la versione più recente della famiglia di aggiornamento era esclusa, anche quando l'elenco consentito ne consentiva una precedente.470Quando [`availableModels`](#restrict-model-selection) esclude l'Opus più recente ma consente una versione precedente, ad esempio `["sonnet", "claude-opus-4-6"]`, `opusplan` utilizza l'Opus più recente consentito per la pianificazione e rimane su Sonnet solo quando ogni Opus è escluso. Una sessione Haiku che normalmente si aggiornerebbe a Sonnet in modalità piano utilizza allo stesso modo il Sonnet più recente consentito e rimane su Haiku solo quando ogni Sonnet è escluso. Prima della v2.1.205, la modalità piano rimase sul modello della sessione ogni volta che la versione più recente della famiglia di aggiornamento era esclusa, anche quando l'elenco consentito ne consentiva una precedente.

469 471

580 582

581Se imposti un livello che il modello attivo non supporta, Claude Code fallback al livello supportato più alto pari o inferiore a quello impostato. Ad esempio, `xhigh` viene eseguito come `high` su Opus 4.6. La tua organizzazione può anche limitare quali livelli sono disponibili per un modello; vedere [Limiti di sforzo dell'organizzazione](#organization-effort-limits).583Se imposti un livello che il modello attivo non supporta, Claude Code fallback al livello supportato più alto pari o inferiore a quello impostato. Ad esempio, `xhigh` viene eseguito come `high` su Opus 4.6. La tua organizzazione o le tue stesse impostazioni possono anche limitare i livelli che un modello offre; vedere [Limiti di sforzo dell'organizzazione](#organization-effort-limits).

582 584

583Con l'impostazione [`ultracode`](/docs/it/settings-reference#ultracode) disattivata, Claude Code risolve il livello di sforzo della sessione in questo ordine, prendendo il primo che si applica:585Con l'impostazione [`ultracode`](/docs/it/settings-reference#ultracode) disattivata, Claude Code risolve il livello di sforzo della sessione in questo ordine, prendendo il primo che si applica:

584 586

619 621

620L'impostazione `effortLevel` persistente e la variabile di ambiente `CLAUDE_CODE_EFFORT_LEVEL` non accettano `ultracode`. Quando `CLAUDE_CODE_EFFORT_LEVEL` è impostato su un livello diverso da `xhigh`, le richieste vengono eseguite a quel livello e l'orchestrazione del flusso di lavoro di ultracode rimane inattiva. Selezionare ultracode mostra quindi un avviso che la variabile di ambiente sostituisce lo sforzo per la sessione.622L'impostazione `effortLevel` persistente e la variabile di ambiente `CLAUDE_CODE_EFFORT_LEVEL` non accettano `ultracode`. Quando `CLAUDE_CODE_EFFORT_LEVEL` è impostato su un livello diverso da `xhigh`, le richieste vengono eseguite a quel livello e l'orchestrazione del flusso di lavoro di ultracode rimane inattiva. Selezionare ultracode mostra quindi un avviso che la variabile di ambiente sostituisce lo sforzo per la sessione.

621 623

622Quando ultracode non è disponibile, ad esempio quando i [flussi di lavoro sono disattivati](/docs/it/workflows#turn-workflows-off), `--effort ultracode` imposta solo lo sforzo `xhigh`.624<span id="when-ultracode-is-available" />

625

626Ultracode non è disponibile quando:

627

628* [I flussi di lavoro sono disattivati](/docs/it/workflows#turn-workflows-off)

629* Il modello non supporta lo sforzo `xhigh`

630* Un [limite di sforzo](#organization-effort-limits) inferiore a `xhigh` si applica al modello

631

632In questi casi `--effort ultracode` avvia la sessione con ultracode disattivato, al livello di sforzo più alto che il modello e qualsiasi limite consentono, fino a `xhigh`.

623 633

624<h4 id="choose-an-effort-level">634<h4 id="choose-an-effort-level">

625 Scegli un livello di sforzo635 Scegli un livello di sforzo

658* **Da un dispositivo connesso**: in una sessione [Remote Control](/docs/it/remote-control#what-connected-devices-see), scegli un livello dal controllo dello sforzo sul tuo telefono o nel tuo browser. Il livello si applica solo alla sessione corrente, anche se termina anche il [mantenimento dello sforzo predefinito del modello](#adjust-effort-level). Richiede Claude Code v2.1.234 o successiva668* **Da un dispositivo connesso**: in una sessione [Remote Control](/docs/it/remote-control#what-connected-devices-see), scegli un livello dal controllo dello sforzo sul tuo telefono o nel tuo browser. Il livello si applica solo alla sessione corrente, anche se termina anche il [mantenimento dello sforzo predefinito del modello](#adjust-effort-level). Richiede Claude Code v2.1.234 o successiva

659* **Frontmatter di skill e subagente**: imposta `effort` in un file markdown [skill](/docs/it/skills#frontmatter-reference) o [subagente](/docs/it/sub-agents#supported-frontmatter-fields) per sostituire il livello di sforzo quando quella skill o subagente viene eseguito669* **Frontmatter di skill e subagente**: imposta `effort` in un file markdown [skill](/docs/it/skills#frontmatter-reference) o [subagente](/docs/it/sub-agents#supported-frontmatter-fields) per sostituire il livello di sforzo quando quella skill o subagente viene eseguito

660 670

661Lo sforzo del frontmatter si applica quando quella skill o subagente è attivo, sostituendo il livello della sessione ma non la variabile di ambiente.671Lo sforzo del frontmatter si applica quando quella skill o subagente è attivo, sostituendo il livello della sessione ma non la variabile di ambiente. Un [`maxEffortLevel`](/docs/it/settings-reference#maxeffortlevel) o [limite di sforzo dell'organizzazione](#organization-effort-limits) limita comunque il livello a cui la skill o il subagente viene eseguito.

672

673Su Fable 5, Opus 4.8 e Opus 4.7, lo sforzo del frontmatter si applica anche mentre il [mantenimento dello sforzo predefinito del modello](#adjust-effort-level) è in vigore. Prima della v2.1.267, il mantenimento aveva la precedenza e Claude Code ignorava il livello del frontmatter mentre il mantenimento era attivo.

662 674

663La chiave `effortLevel` nelle [impostazioni gestite](/docs/it/managed-settings) è un predefinito iniziale, non un'applicazione: gli utenti possono modificarla per una sessione con `/effort` o `--effort`, e il valore gestito si riafferma come predefinito nelle nuove sessioni.675Se imposti `effortLevel` nelle [impostazioni gestite](/docs/it/managed-settings), Claude Code lo applica al passo delle impostazioni dell'[ordine di risoluzione dello sforzo](#adjust-effort-level), e gli utenti possono comunque modificare il livello con `/effort` o `--effort`. Per mantenere gli utenti a o sotto un livello, imposta [`maxEffortLevel`](/docs/it/settings-reference#maxeffortlevel).

664 676

665Il cursore dello sforzo appare in `/model` quando è selezionato un modello supportato. Il livello di sforzo corrente è anche mostrato nell'intestazione della sessione accanto al nome del modello, ad esempio "con sforzo basso", in modo che tu possa confermare quale impostazione è attiva senza aprire `/model`. Il piè di pagina mostra anche brevemente il livello di sforzo all'avvio e quando cambia.677Il cursore dello sforzo appare in `/model` quando è selezionato un modello supportato. Il livello di sforzo corrente è anche mostrato nell'intestazione della sessione accanto al nome del modello, ad esempio "con sforzo basso", in modo che tu possa confermare quale impostazione è attiva senza aprire `/model`. Il piè di pagina mostra anche brevemente il livello di sforzo all'avvio e quando cambia.

666 678

monitoring-usage.md +19 −9

Details

219**`claude_code.interaction`**219**`claude_code.interaction`**

220 220

222| ------------------------- | ------------------------------------------------------------------------------- | ----------------------- |222| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

226| `parent.source` | Come lo span ha ottenuto il suo genitore di traccia: `env` quando è stato genitore sotto un `TRACEPARENT` in entrata, `none` quando ha avviato la sua propria traccia. Richiede Claude Code v2.1.268 o successivo | |

227 228

228**`claude_code.llm_request`**229**`claude_code.llm_request`**

229 230

231| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |232| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |

237| `query_source_safe` | Forma limitata di `query_source`, emessa indipendentemente dal fatto che la traccia beta dettagliata sia attiva, con valori come `repl_main_thread` o `agent.builtin.general-purpose`. `:` diventa `.` e gli agenti denominati dall'utente appaiono come `agent.custom`. Richiede Claude Code v2.1.268 o successivo | |

237| `parent_agent_id` | Identificatore dell'agente che ha generato questo. Assente per la sessione principale e per gli agenti generati direttamente da essa | |239| `parent_agent_id` | Identificatore dell'agente che ha generato questo. Assente per la sessione principale e per gli agenti generati direttamente da essa | |

238| `workflow.run_id` | Identificatore di esecuzione della [Workflow](/docs/it/workflows) tool run che ha generato questo agente, con prefisso `wf_`. Assente per gli agenti non generati da un workflow | |240| `workflow.run_id` | Identificatore di esecuzione della [Workflow](/docs/it/workflows) tool run che ha generato questo agente, con prefisso `wf_`. Assente per gli agenti non generati da un workflow | |

246| `first_content_ms` | Tempo dall'inizio della richiesta al primo blocco di contenuto del tentativo riuscito, in millisecondi. Assente sulle richieste che sono ricadute nel percorso non in streaming. Richiede Claude Code v2.1.268 o successivo | |

258| `error_class` | Token di classe di errore breve quando la richiesta non è riuscita, come `api_timeout` o `server_overload`. Richiede Claude Code v2.1.268 o successivo | |

256| `stop_reason` | `stop_reason` della risposta API, come `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn`, o `refusal` | |260| `stop_reason` | `stop_reason` della risposta API, come `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn`, o `refusal` | |

257| `gen_ai.response.finish_reasons` | Stesso valore di `stop_reason`, racchiuso in un array di stringhe. Convenzione semantica OpenTelemetry GenAI | |261| `gen_ai.response.finish_reasons` | Stesso valore di `stop_reason`, racchiuso in un array di stringhe. Convenzione semantica OpenTelemetry GenAI | |

261**`claude_code.tool`**265**`claude_code.tool`**

262 266

264| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |268| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

270| `tool_name_safe` | Forma di `tool_name` che non contiene nomi scelti dall'utente. I nomi degli strumenti integrati passano verbatim. I nomi degli strumenti MCP appaiono come `mcp_other`, tranne i nomi degli strumenti che corrispondono a poche forme fisse, come gli strumenti `playwright` denominati `browser_*`, che passano verbatim. Richiede Claude Code v2.1.268 o successivo | |

271| `bash_command_class` | Per lo strumento Bash: categoria del primo programma del comando da un elenco fisso, come `vcs` o `package_manager`. `other` per un programma al di fuori dell'elenco, `unparsed` quando la riga non può essere analizzata. Richiede Claude Code v2.1.268 o successivo | |

272| `bash_argv0` | Per lo strumento Bash: il primo programma del comando quando è nello stesso elenco fisso, come `git` o `npm`. `other` per qualsiasi programma al di fuori dell'elenco. Richiede Claude Code v2.1.268 o successivo | |

289**`claude_code.tool.execution`**296**`claude_code.tool.execution`**

290 297

292| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |299| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

297| `error` | Stringa di categoria di errore quando l'esecuzione non è riuscita, come `Error:ENOENT` o `ShellError`. Contiene il messaggio di errore completo quando il gate è impostato | `OTEL_LOG_TOOL_DETAILS` |304| `error` | Stringa di categoria di errore quando l'esecuzione non è riuscita, come `Error:ENOENT` o `ShellError`. Contiene il messaggio di errore completo quando il gate è impostato | `OTEL_LOG_TOOL_DETAILS` |

305| `error_class` | La categoria di errore in forma di identificatore, con caratteri al di fuori di lettere, cifre e sottolineature sostituiti da `_`, come `Error_ENOENT` o `ShellError`. Contiene la categoria anche quando `error` contiene il messaggio completo. Richiede Claude Code v2.1.268 o successivo | |

298 306

299**`claude_code.hook`**307**`claude_code.hook`**

300 308

500| `user.account_id` | ID dell'account in formato taggato corrispondente alle API di amministrazione Anthropic (quando autenticato), come `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (predefinito: true) |508| `user.account_id` | ID dell'account in formato taggato corrispondente alle API di amministrazione Anthropic (quando autenticato), come `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (predefinito: true) |

501| `user.id` | Identificatore anonimo casuale generato al primo avvio e persistente in `~/.claude.json`. Non contiene informazioni personali e non è derivato dal tuo account Claude. L'eliminazione del file produce un nuovo valore non correlato al prossimo avvio. | Sempre incluso |509| `user.id` | Identificatore anonimo casuale generato al primo avvio e persistente in `~/.claude.json`. Non contiene informazioni personali e non è derivato dal tuo account Claude. L'eliminazione del file produce un nuovo valore non correlato al prossimo avvio. | Sempre incluso |

504| Chiavi da `OTEL_RESOURCE_ATTRIBUTES` | Attributi personalizzati che imposti, come `department` o `team.id`. Vedi [Supporto per organizzazioni multi-team](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (predefinito: true) |512| Chiavi da `OTEL_RESOURCE_ATTRIBUTES` | Attributi personalizzati che imposti, come `department` o `team.id`. Vedi [Supporto per organizzazioni multi-team](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (predefinito: true) |

505 513

1329 1337

1330Claude Code ritenta internamente le richieste API non riuscite ed emette un singolo evento `claude_code.api_error` solo dopo che rinuncia, quindi l'evento stesso è il segnale terminale per quella richiesta. I tentativi di ripetizione intermedi non vengono registrati come eventi separati.1338Claude Code ritenta internamente le richieste API non riuscite ed emette un singolo evento `claude_code.api_error` solo dopo che rinuncia, quindi l'evento stesso è il segnale terminale per quella richiesta. I tentativi di ripetizione intermedi non vengono registrati come eventi separati.

1331 1339

1332L'attributo `attempt` sull'evento registra il numero totale di tentativi. `CLAUDE_CODE_MAX_RETRIES` ha un valore predefinito di 10 ed è limitato a 15; a partire da v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta il valore predefinito e rimuove il limite. Quando la richiesta esaurisce tutti i tentativi su un errore transitorio, `attempt` è uguale a uno più di quel limite effettivo: 11 per impostazione predefinita, e mai più di 16 a meno che il watchdog non sia impostato. Un valore inferiore indica un errore non ritentabile come una risposta `400`.1340L'attributo `attempt` sull'evento registra il numero totale di tentativi. `CLAUDE_CODE_MAX_RETRIES` ha un valore predefinito di 10 ed è limitato a 15. A partire da v2.1.199, puoi impostare `CLAUDE_CODE_RETRY_WATCHDOG` per aumentare il valore predefinito e rimuovere il limite.

1341

1342Quando la richiesta esaurisce tutti i tentativi su un errore transitorio, `attempt` è uguale a uno più di quel limite effettivo: 11 per impostazione predefinita, e mai più di 16 a meno che il watchdog non sia impostato. Un valore inferiore indica un errore non ritentabile come una risposta `400`, o una causa con il suo proprio budget di tentativi più piccolo. Ad esempio, Claude Code ritenta un errore nel caricamento delle credenziali AWS o Google Cloud al massimo due volte.

1333 1343

1334Per distinguere una sessione che si è ripresa da una che si è bloccata, raggruppa gli eventi per `session.id` e verifica se esiste un evento `api_request` successivo dopo l'errore.1344Per distinguere una sessione che si è ripresa da una che si è bloccata, raggruppa gli eventi per `session.id` e verifica se esiste un evento `api_request` successivo dopo l'errore.

1335 1345

1358 Attribuisci le azioni agli utenti1368 Attribuisci le azioni agli utenti

1359</h3>1369</h3>

1360 1370

1361Gli [attributi standard](#standard-attributes) su ogni evento includono l'identità dell'utente autenticato: `user.email`, `user.account_uuid`, `user.account_id`, e `organization.id` quando accedete con un account Claude, più `user.id` e il `session.id` per sessione. `user.id` è un identificatore con ambito di installazione, tranne nelle sessioni [Claude apps gateway](/docs/it/claude-apps-gateway), dove è il soggetto IdP dal token emesso dal gateway.1371Gli [attributi standard](#standard-attributes) su ogni evento includono l'identità dell'utente autenticato: `user.email`, `user.account_uuid`, `user.account_id`, e `organization.id` quando accedete con un account Claude o, in una [sessione cloud](/docs/it/claude-code-on-the-web), quando le credenziali della sessione stessa le portano, più `user.id` e il `session.id` per sessione. `user.id` è un identificatore con ambito di installazione, tranne nelle sessioni [Claude apps gateway](/docs/it/claude-apps-gateway), dove è il soggetto IdP dal token emesso dal gateway.

1362 1372

1363Le chiamate agli strumenti MCP, i comandi Bash e le modifiche ai file sono quindi attribuite allo sviluppatore che ha avviato la sessione. Claude Code non agisce con un account di servizio separato; l'identità registrata su ogni evento è l'account Claude dello sviluppatore, o l'identità IdP dello sviluppatore in una sessione [Claude apps gateway](/docs/it/claude-apps-gateway).1373Le chiamate agli strumenti MCP, i comandi Bash e le modifiche ai file sono quindi attribuite allo sviluppatore che ha avviato la sessione. Claude Code non agisce con un account di servizio separato; l'identità registrata su ogni evento è l'account Claude dello sviluppatore, o l'identità IdP dello sviluppatore in una sessione [Claude apps gateway](/docs/it/claude-apps-gateway).

1364 1374

1486 1496

1487* L'esportazione OpenTelemetry al tuo backend è opt-in e richiede una configurazione esplicita. Per la telemetria operazionale separata di Anthropic e come disabilitarla, vedi [Data usage](/docs/it/data-usage#telemetry-services)1497* L'esportazione OpenTelemetry al tuo backend è opt-in e richiede una configurazione esplicita. Per la telemetria operazionale separata di Anthropic e come disabilitarla, vedi [Data usage](/docs/it/data-usage#telemetry-services)

1488* I contenuti dei file grezzi e i frammenti di codice non sono inclusi nelle metriche o negli eventi. I percorsi di traccia degli span sono un percorso dati separato: vedi il punto `OTEL_LOG_TOOL_CONTENT` di seguito1498* I contenuti dei file grezzi e i frammenti di codice non sono inclusi nelle metriche o negli eventi. I percorsi di traccia degli span sono un percorso dati separato: vedi il punto `OTEL_LOG_TOOL_CONTENT` di seguito

1489* Quando autenticato tramite OAuth, `user.email` è incluso negli attributi di telemetria. Se questo è una preoccupazione per la tua organizzazione, lavora con il tuo backend di telemetria per filtrare o oscurare questo campo1499* Quando autenticato tramite OAuth, `user.email` è incluso negli attributi di telemetria, inviato solo all'endpoint OTel che configuri, mai ad Anthropic. Se questo è una preoccupazione per la tua organizzazione, lavora con il tuo backend di telemetria per filtrare o oscurare questo campo

1490* Il contenuto del prompt dell'utente non viene raccolto per impostazione predefinita. Viene registrata solo la lunghezza del prompt. Per includere il contenuto del prompt, imposta `OTEL_LOG_USER_PROMPTS=1`1500* Il contenuto del prompt dell'utente non viene raccolto per impostazione predefinita. Viene registrata solo la lunghezza del prompt. Per includere il contenuto del prompt, imposta `OTEL_LOG_USER_PROMPTS=1`

1491* Il testo della risposta dell'assistente non viene raccolto per impostazione predefinita. Viene registrata solo la lunghezza della risposta. Per includere il testo della risposta, imposta `OTEL_LOG_ASSISTANT_RESPONSES=1`. Come tutti i dati OpenTelemetry da Claude Code, il testo della risposta viene inviato solo all'endpoint OTel che configuri, mai ad Anthropic. Quando questa variabile non è impostata, `OTEL_LOG_USER_PROMPTS` viene utilizzato come fallback, quindi imposta `OTEL_LOG_ASSISTANT_RESPONSES=0` se desideri il contenuto del prompt senza il contenuto della risposta1501* Il testo della risposta dell'assistente non viene raccolto per impostazione predefinita. Viene registrata solo la lunghezza della risposta. Per includere il testo della risposta, imposta `OTEL_LOG_ASSISTANT_RESPONSES=1`. Come tutti i dati OpenTelemetry da Claude Code, il testo della risposta viene inviato solo all'endpoint OTel che configuri, mai ad Anthropic. Quando questa variabile non è impostata, `OTEL_LOG_USER_PROMPTS` viene utilizzato come fallback, quindi imposta `OTEL_LOG_ASSISTANT_RESPONSES=0` se desideri il contenuto del prompt senza il contenuto della risposta

1492* Gli argomenti di input dello strumento e i parametri non vengono registrati per impostazione predefinita. Per includerli, imposta `OTEL_LOG_TOOL_DETAILS=1`. Per i server integrati di Claude Desktop, nelle sessioni di cui Claude Desktop è proprietario, `tool_decision` e `tool_result` portano la coppia `mcp_server_name`/`mcp_tool_name`, nomi creati dall'host piuttosto che contenuto degli argomenti, anche con il flag disattivato. L'eccezione richiede Claude Code v2.1.214 o successivo. Questi dati vengono inviati solo all'endpoint OTEL che configuri, mai ad Anthropic. Gli argomenti potrebbero comunque contenere valori sensibili, quindi configura il tuo backend di telemetria per filtrare o oscurare questi attributi secondo necessità. Quando abilitato:1502* Gli argomenti di input dello strumento e i parametri non vengono registrati per impostazione predefinita. Per includerli, imposta `OTEL_LOG_TOOL_DETAILS=1`. Per i server integrati di Claude Desktop, nelle sessioni di cui Claude Desktop è proprietario, `tool_decision` e `tool_result` portano la coppia `mcp_server_name`/`mcp_tool_name`, nomi creati dall'host piuttosto che contenuto degli argomenti, anche con il flag disattivato. L'eccezione richiede Claude Code v2.1.214 o successivo. Questi dati vengono inviati solo all'endpoint OTEL che configuri, mai ad Anthropic. Gli argomenti potrebbero comunque contenere valori sensibili, quindi configura il tuo backend di telemetria per filtrare o oscurare questi attributi secondo necessità. Quando abilitato:

network-config.md +1 −0

Details

247| `*.frame.claudeusercontent.com` | Letture di contenuto [Artifact](/docs/it/artifacts). La CLI recupera i file di un artifact da questo host quando Claude ne apre uno, e solo quando lo strumento Artifact è [disponibile](/docs/it/artifacts#availability) per il vostro account. Per disattivare lo strumento e eliminare questo requisito, impostate [`"enableArtifact": false`](/docs/it/settings-reference#enableartifact) o [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/it/env-vars); Claude Code rispetta anche l'impostazione deprecata [`disableArtifact`](/docs/it/settings-reference#disableartifact). Consultate [Disabilitare gli artifact](/docs/it/artifacts#disable-artifacts) per come queste impostazioni interagiscono |247| `*.frame.claudeusercontent.com` | Letture di contenuto [Artifact](/docs/it/artifacts). La CLI recupera i file di un artifact da questo host quando Claude ne apre uno, e solo quando lo strumento Artifact è [disponibile](/docs/it/artifacts#availability) per il vostro account. Per disattivare lo strumento e eliminare questo requisito, impostate [`"enableArtifact": false`](/docs/it/settings-reference#enableartifact) o [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/it/env-vars); Claude Code rispetta anche l'impostazione deprecata [`disableArtifact`](/docs/it/settings-reference#disableartifact). Consultate [Disabilitare gli artifact](/docs/it/artifacts#disable-artifacts) per come queste impostazioni interagiscono |

248| `raw.githubusercontent.com` | Feed del changelog per [`/release-notes`](/docs/it/commands). Nelle sessioni interattive, Claude Code lo recupera anche in background all'avvio quando il changelog memorizzato nella cache non copre ancora la versione in esecuzione, ad esempio al primo avvio dopo un aggiornamento; le sessioni non interattive e cloud non lo recuperano mai |248| `raw.githubusercontent.com` | Feed del changelog per [`/release-notes`](/docs/it/commands). Nelle sessioni interattive, Claude Code lo recupera anche in background all'avvio quando il changelog memorizzato nella cache non copre ancora la versione in esecuzione, ad esempio al primo avvio dopo un aggiornamento; le sessioni non interattive e cloud non lo recuperano mai |

249| `*-review.googlesource.com` | Ricerca di modifiche Gerrit su checkout `googlesource.com`. Quando una sessione di una scheda Claude Desktop Code si avvia o riprende su un checkout [attendibile](/docs/it/permissions#project-allow-rules-and-workspace-trust) il cui `origin` è un host `googlesource.com`, Claude Code chiede anonimamente al server `-review` di quell'host la modifica aperta corrispondente al `Change-Id` di HEAD, una volta per avvio o ripresa. Altri tipi di sessione saltano la ricerca e nessun altro host Gerrit viene contattato. Facoltativo: disabilitare con [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/it/env-vars) |

249| `http-intake.logs.us5.datadoghq.com` | Eventi di telemetria operazionale, inviati solo quando la CLI utilizza direttamente l'API Anthropic, mai per Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry. Facoltativo: disabilitare con [`DISABLE_TELEMETRY`](/docs/it/data-usage#telemetry-services) o `DO_NOT_TRACK` |250| `http-intake.logs.us5.datadoghq.com` | Eventi di telemetria operazionale, inviati solo quando la CLI utilizza direttamente l'API Anthropic, mai per Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry. Facoltativo: disabilitare con [`DISABLE_TELEMETRY`](/docs/it/data-usage#telemetry-services) o `DO_NOT_TRACK` |

250| `browser-intake-us5-datadoghq.com` | Rapporti di errore operazionali, inviati quando la CLI utilizza direttamente l'API Anthropic e un gate di rollout lato server li abilita. Facoltativo: disabilitare con `DISABLE_ERROR_REPORTING` o `DISABLE_TELEMETRY`; consultate [Servizi di telemetria](/docs/it/data-usage#telemetry-services) |251| `browser-intake-us5-datadoghq.com` | Rapporti di errore operazionali, inviati quando la CLI utilizza direttamente l'API Anthropic e un gate di rollout lato server li abilita. Facoltativo: disabilitare con `DISABLE_ERROR_REPORTING` o `DISABLE_TELEMETRY`; consultate [Servizi di telemetria](/docs/it/data-usage#telemetry-services) |

251| `formulae.brew.sh` | Controlli della versione di aggiornamento nelle installazioni Homebrew. Altri metodi di installazione non contattano questo host |252| `formulae.brew.sh` | Controlli della versione di aggiornamento nelle installazioni Homebrew. Altri metodi di installazione non contattano questo host |

overview.md +10 −10

Details

18 <Tab title="Terminal">18 <Tab title="Terminal">

19 Il CLI completo per lavorare con Claude Code direttamente nel tuo terminale. Modifica file, esegui comandi e gestisci l'intero progetto dalla riga di comando.19 Il CLI completo per lavorare con Claude Code direttamente nel tuo terminale. Modifica file, esegui comandi e gestisci l'intero progetto dalla riga di comando.

20 20

~~21 To install Claude Code, use one of the following methods:~~21 Per installare Claude Code, utilizza uno dei seguenti metodi:

22 22

23 <Tabs>23 <Tabs>

~~24 <Tab title="Native Install (Recommended)">~~24 <Tab title="Installazione nativa (consigliata)">

25 **macOS, Linux, WSL:**25 **macOS, Linux, WSL:**

26 26

27 ```bash theme={null}27 ```bash theme={null}

40 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd40 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

41 ```41 ```

42 42

43 If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.43 Se vedi `The token '&&' is not a valid statement separator`, sei in PowerShell, non in CMD. Se vedi `'irm' is not recognized as an internal or external command`, sei in CMD, non in PowerShell. Il tuo prompt mostra `PS C:\` quando sei in PowerShell e `C:\` senza il `PS` quando sei in CMD.

44 44

45 If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.45 Se il comando di installazione non riesce con `syntax error near unexpected token '<'`, un `403`, o un altro errore curl, consulta [Troubleshoot installation](/docs/it/troubleshoot-install#find-your-error) per abbinare l'errore a una soluzione e per metodi di installazione alternativi.

46 46

47 [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.47 [Git for Windows](https://git-scm.com/downloads/win) è consigliato su Windows nativo in modo che Claude Code possa utilizzare lo strumento Bash. Se Git for Windows non è installato, Claude Code utilizza PowerShell come strumento shell. Le configurazioni WSL non necessitano di Git for Windows.

48 48

49 <Info>49 <Info>

~~50 Native installations automatically update in the background to keep you on the latest version.~~50 Le installazioni native si aggiornano automaticamente in background per mantenerti sulla versione più recente.

51 </Info>51 </Info>

52 </Tab>52 </Tab>

53 53

56 brew install --cask claude-code56 brew install --cask claude-code

57 ```57 ```

58 58

59 Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.59 Homebrew offre due cask. `claude-code` traccia il canale di rilascio stabile, che in genere è circa una settimana indietro e salta i rilasci con regressioni importanti. `claude-code@latest` traccia il canale più recente e riceve nuove versioni non appena vengono rilasciate.

60 60

61 <Info>61 <Info>

62 Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.62 Le installazioni Homebrew non si aggiornano automaticamente. Esegui `brew upgrade claude-code` o `brew upgrade claude-code@latest`, a seconda di quale cask hai installato, per ottenere le funzionalità più recenti e le correzioni di sicurezza.

63 </Info>63 </Info>

64 </Tab>64 </Tab>

65 65

69 ```69 ```

70 70

71 <Info>71 <Info>

~~72 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.~~72 Le installazioni WinGet non si aggiornano automaticamente. Esegui `winget upgrade Anthropic.ClaudeCode` periodicamente per ottenere le funzionalità più recenti e le correzioni di sicurezza.

73 </Info>73 </Info>

74 </Tab>74 </Tab>

75 </Tabs>75 </Tabs>

76 76

~~77 You can also install with [apt, dnf, or apk](/docs/en/setup#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.~~77 Puoi anche installare con [apt, dnf, o apk](/docs/it/setup#install-with-linux-package-managers) su Debian, Fedora, RHEL e Alpine.

78 78

79 Quindi avvia Claude Code in qualsiasi progetto. Sostituisci `your-project` con il percorso di una directory di progetto sulla tua macchina:79 Quindi avvia Claude Code in qualsiasi progetto. Sostituisci `your-project` con il percorso di una directory di progetto sulla tua macchina:

80 80

permission-modes.md +33 −33

Details

22| [`acceptEdits`](#auto-approve-file-edits-with-acceptedits-mode) | Letture, modifiche di file e comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.) | Iterare sul codice che stai revisionando |22| [`acceptEdits`](#auto-approve-file-edits-with-acceptedits-mode) | Letture, modifiche di file e comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.) | Iterare sul codice che stai revisionando |

23| [`plan`](#analyze-before-you-edit-with-plan-mode) | Letture, più comandi approvati dal classificatore quando [la modalità auto](#eliminate-prompts-with-auto-mode) è disponibile | Esplorare una codebase prima di modificarla |23| [`plan`](#analyze-before-you-edit-with-plan-mode) | Letture, più comandi approvati dal classificatore quando [la modalità auto](#eliminate-prompts-with-auto-mode) è disponibile | Esplorare una codebase prima di modificarla |

27 27

28La modalità che esamina ogni azione è denominata **Manual** nella CLI, in `claude --help`, nelle estensioni VS Code e JetBrains, e nell'app desktop. Il suo valore di configurazione è `default`, che è quello utilizzato da hooks e integrazioni SDK. La CLI accetta `manual` come alias ovunque digiti il valore, ad esempio `claude --permission-mode manual` o `"defaultMode": "manual"`. L'etichetta Manual e l'alias `manual` richiedono Claude Code v2.1.200 o successivo. L'etichetta dell'app desktop non dipende dalla tua versione CLI.28La modalità che esamina ogni azione è denominata **Manual** nella CLI, in `claude --help`, nelle estensioni VS Code e JetBrains, e nell'app desktop. Il suo valore di configurazione è `default`, che è quello utilizzato da hooks e integrazioni SDK. La CLI accetta `manual` come alias ovunque digiti il valore, ad esempio `claude --permission-mode manual` o `"defaultMode": "manual"`. L'etichetta Manual e l'alias `manual` richiedono Claude Code v2.1.200 o successivo. L'etichetta dell'app desktop non dipende dalla tua versione CLI.

128La prossima sessione che avvii mostra `⏸ manual mode on` nella barra di stato.128La prossima sessione che avvii mostra `⏸ manual mode on` nella barra di stato.

129 129

130<h2 id="switch-permission-modes">130<h2 id="switch-permission-modes">

131 Cambia modalità di autorizzazione131 Cambiare le modalità di autorizzazione

132</h2>132</h2>

133 133

134Ogni interfaccia ha il suo controllo per cambiare le modalità di autorizzazione durante una sessione e il suo modo di scegliere la modalità di autorizzazione che le nuove sessioni iniziano. Chiedere a Claude nella chat di cambiare la modalità di autorizzazione non funziona. Seleziona la tua interfaccia per vedere i suoi controlli.134Ogni interfaccia ha il proprio controllo per cambiare le modalità di autorizzazione durante una sessione e il proprio modo di scegliere la modalità di autorizzazione con cui iniziano le nuove sessioni. Seleziona la tua interfaccia per vedere i suoi controlli.

135 135

136<Tabs>136<Tabs>

137 <Tab title="CLI">137 <Tab title="CLI">

138 **Durante una sessione**: premi `Shift+Tab` per ciclo le modalità di autorizzazione. Da `auto`, il primo pressione passa a `default`, e il ciclo quindi esegue `default` → `acceptEdits` → `plan` → di nuovo a `default`. Le modalità opzionali, descritte di seguito, si inseriscono dopo `plan`. La barra di stato mostra la modalità attiva come un `⏸ manual mode on` grigio per `default`, o come `⏵⏵ accept edits on`, `⏸ plan mode on`, `⏵⏵ auto mode on`, `⏵⏵ don't ask on`, o `⏵⏵ bypass permissions on`.138 **Durante una sessione**: premi `Shift+Tab` per ciclo attraverso le modalità di autorizzazione. Da `auto`, il primo pressione passa a `default`, e il ciclo quindi esegue `default` → `acceptEdits` → `plan` → ritorno a `default`. Le modalità opzionali, descritte di seguito, si inseriscono dopo `plan`. La barra di stato mostra la modalità attiva come `⏸ manual mode on` grigio per `default`, oppure come `⏵⏵ accept edits on`, `⏸ plan mode on`, `⏵⏵ auto mode on`, `⏵⏵ don't ask on`, o `⏵⏵ bypass permissions on`.

139 139

140 Non tutte le modalità sono nel ciclo predefinito:140 Non tutte le modalità sono nel ciclo predefinito:

141 141

142 * `auto`: appare quando [la modalità auto è disponibile](#eliminate-prompts-with-auto-mode); il ciclo ad essa passa le modalità di autorizzazione senza un prompt di conferma142 * `auto`: appare quando [auto mode è disponibile](#eliminate-prompts-with-auto-mode); il ciclo ad essa passa le modalità di autorizzazione senza un prompt di conferma

143 * `bypassPermissions`: appare dopo aver iniziato con `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, `--allow-dangerously-skip-permissions`, o `permissions.defaultMode: "bypassPermissions"` nelle [impostazioni utente, `--settings`, o gestite](/docs/it/settings-reference#permissions-defaultmode). La variante `--allow-` aggiunge la modalità di autorizzazione al ciclo senza attivarla143 * `bypassPermissions`: appare dopo che inizi con `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, `--allow-dangerously-skip-permissions`, o `permissions.defaultMode: "bypassPermissions"` in [impostazioni utente, `--settings`, o impostazioni gestite](/docs/it/settings-reference#permissions-defaultmode). La variante `--allow-` aggiunge la modalità di autorizzazione al ciclo senza attivarla

144 * `dontAsk`: non appare mai nel ciclo; impostala con `--permission-mode dontAsk`144 * `dontAsk`: non appare mai nel ciclo; impostala con `--permission-mode dontAsk`

145 145

146 Le modalità opzionali abilitate si inseriscono dopo `plan`, con `bypassPermissions` per primo e `auto` per ultimo. Se hai entrambe abilitate, ciclerai attraverso `bypassPermissions` sulla strada verso `auto`.146 Le modalità opzionali abilitate si inseriscono dopo `plan`, con `bypassPermissions` per primo e `auto` per ultimo. Se hai entrambe abilitate, ciclerai attraverso `bypassPermissions` sulla strada verso `auto`.

147 147

148 **Da un prompt di autorizzazione Bash**: nelle modalità di autorizzazione Manual e `acceptEdits`, quando [la modalità auto](#eliminate-prompts-with-auto-mode) è disponibile, Claude Code aggiunge **Sì, e passa alla modalità auto** al prompt di autorizzazione di un comando Bash. Selezionalo per approvare il comando e passare la sessione alla modalità auto. I prompt dello [strumento PowerShell](/docs/it/tools-reference#powershell-tool) non offrono l'opzione. Richiede Claude Code v2.1.247 o successivo.148 **Da un prompt di autorizzazione Bash**: nelle modalità di autorizzazione Manual e `acceptEdits`, quando [auto mode](#eliminate-prompts-with-auto-mode) è disponibile, Claude Code aggiunge **Yes, and switch to auto mode** al prompt di autorizzazione di un comando Bash. Selezionalo per approvare il comando e passare la sessione alla modalità auto. I prompt dello [strumento PowerShell](/docs/it/tools-reference#powershell-tool) non offrono l'opzione. Richiede Claude Code v2.1.247 o successivo.

149 149

150 Claude Code non aggiunge l'opzione ai prompt forzati da una delle tue [regole `ask`](/docs/it/permissions#manage-permissions) o da un [hook](/docs/it/hooks#pretooluse-decision-control), perché la modalità auto ti mostra comunque quei prompt, quindi il passaggio non li rimuoverebbe.150 Claude Code non aggiunge l'opzione ai prompt forzati da una delle tue [regole `ask`](/docs/it/permissions#manage-permissions) o da un [hook](/docs/it/hooks#pretooluse-decision-control), perché la modalità auto ti mostra comunque quei prompt, quindi il passaggio non li rimuoverebbe.

151 151

155 claude --permission-mode plan155 claude --permission-mode plan

156 ```156 ```

157 157

158 **Come impostazione predefinita**: imposta `permissions.defaultMode` all'ambito che desideri, come descritto in [Inizia in una modalità di autorizzazione diversa](#start-in-a-different-mode).158 **Come predefinito**: imposta `permissions.defaultMode` nell'ambito che desideri, come descritto in [Inizia in una modalità di autorizzazione diversa](#start-in-a-different-mode).

159 159

160 Lo stesso flag `--permission-mode` funziona con `-p` per [esecuzioni non interattive](/docs/it/headless).160 Lo stesso flag `--permission-mode` funziona con `-p` per [esecuzioni non interattive](/docs/it/headless).

161 </Tab>161 </Tab>

162 162

163 <Tab title="VS Code">163 <Tab title="VS Code">

164 **Durante una sessione**: fai clic sull'indicatore di modalità in fondo alla casella di prompt. Utilizza queste etichette per le modalità in questa pagina:164 **Durante una sessione**: fai clic sull'indicatore di modalità nella parte inferiore della casella del prompt. Utilizza queste etichette per le modalità in questa pagina:

165 165

166 | Etichetta UI | Modalità |166 | Etichetta UI | Modalità |

167 | :----------------- | :------------------ |167 | :----------------- | :------------------ |

173 173

174 **Come impostazione predefinita**: per fissare la modalità di autorizzazione in cui le conversazioni iniziano, imposta `claudeCode.initialPermissionMode` nelle impostazioni utente di VS Code su `default`, `manual`, `acceptEdits`, `plan`, o `bypassPermissions`. L'impostazione non accetta `auto`; per iniziare in Auto, lasciala non impostata e scegli **Auto** dall'indicatore di modalità una volta, come il punto 2 di seguito descrive. L'estensione avvia ogni nuova conversazione nel primo di questi che si applica:174 **Come predefinito**: per fissare la modalità di autorizzazione con cui iniziano le conversazioni, imposta `claudeCode.initialPermissionMode` nelle impostazioni utente di VS Code su `default`, `manual`, `acceptEdits`, `plan`, o `bypassPermissions`. L'impostazione non accetta `auto`; per iniziare in Auto, lasciala non impostata e seleziona **Auto** dall'indicatore di modalità una volta, come descrive l'elemento 2 di seguito. L'estensione inizia ogni nuova conversazione nel primo di questi che si applica:

175 175

176 1. `claudeCode.initialPermissionMode`176 1. `claudeCode.initialPermissionMode`

177 2. La modalità che hai scelto per ultima dall'indicatore di modalità, se era Manual, Edit automatically, o Auto. Scegliere Plan o Bypass permissions si applica solo a quella conversazione177 2. La modalità che hai selezionato per ultimo dall'indicatore di modalità, se era Manual, Edit automatically, o Auto. Selezionare Plan o Bypass permissions si applica solo a quella conversazione

178 3. `permissions.defaultMode` dalle [impostazioni gestite](/docs/it/managed-settings) o `~/.claude/settings.json`, sui piani Pro, Max e Team con il [recupero dei flag di funzionalità](#which-mode-a-session-starts-in) disponibile178 3. `permissions.defaultMode` da [impostazioni gestite](/docs/it/managed-settings) o `~/.claude/settings.json`, su piani Pro, Max e Team con [feature-flag fetching](#which-mode-a-session-starts-in) disponibile

179 4. L'[impostazione predefinita integrata](#which-mode-a-session-starts-in) per il tuo piano, provider e impostazioni organizzative179 4. Il [predefinito incorporato](#which-mode-a-session-starts-in) per il tuo piano, provider e impostazioni dell'organizzazione

180 180

181 L'estensione non legge mai il `.claude/settings.json` o `.claude/settings.local.json` di un progetto per la modalità di autorizzazione iniziale, e nelle conversazioni che non soddisfano le condizioni del punto 3 non legge alcun file di impostazioni. Quando `claudeCode.claudeProcessWrapper` è impostato, i punti 3 e 4 non si applicano nemmeno: quelle conversazioni iniziano in Manual a meno che il punto 1 o il punto 2 non imposti una modalità di autorizzazione.181 L'estensione non legge mai il `.claude/settings.json` o `.claude/settings.local.json` di un progetto per la modalità di autorizzazione iniziale, e nelle conversazioni che non soddisfano le condizioni dell'elemento 3 non legge alcun file di impostazioni. Quando `claudeCode.claudeProcessWrapper` è impostato, gli elementi 3 e 4 non si applicano nemmeno: quelle conversazioni iniziano in Manual a meno che l'elemento 1 o l'elemento 2 non imposti una modalità di autorizzazione.

182 182

183 Auto appare nell'indicatore di modalità quando [la modalità auto è disponibile](#eliminate-prompts-with-auto-mode).183 Auto appare nell'indicatore di modalità quando [auto mode è disponibile](#eliminate-prompts-with-auto-mode).

184 184

185 Bypass permissions richiede l'interruttore **Allow dangerously skip permissions** nelle impostazioni dell'estensione. Senza di esso, la modalità di autorizzazione non appare nell'indicatore, e un valore `bypassPermissions` dal punto 1 o dal punto 3 avvia la conversazione in Manual invece. Auto da qualsiasi punto allo stesso modo avvia la conversazione in Manual quando la modalità auto non è disponibile.185 Bypass permissions richiede l'interruttore **Allow dangerously skip permissions** nelle impostazioni dell'estensione. Senza di esso, la modalità di autorizzazione non appare nell'indicatore, e un valore `bypassPermissions` dall'elemento 1 o dall'elemento 3 inizia la conversazione in Manual invece. Auto da qualsiasi elemento allo stesso modo inizia la conversazione in Manual quando la modalità auto non è disponibile.

186 186

187 Vedi la [guida di VS Code](/docs/it/vs-code) per i dettagli specifici dell'estensione.187 Vedi la [guida VS Code](/docs/it/vs-code) per i dettagli specifici dell'estensione.

188 </Tab>188 </Tab>

189 189

190 <Tab title="JetBrains">190 <Tab title="JetBrains">

191 Il plugin JetBrains esegue Claude Code nel terminale dell'IDE, quindi il cambio di modalità di autorizzazione funziona come nella CLI: premi `Shift+Tab` per ciclo, o passa `--permission-mode` al lancio.191 Il plugin JetBrains esegue Claude Code nel terminale dell'IDE, quindi il cambio delle modalità di autorizzazione funziona come nella CLI: premi `Shift+Tab` per ciclo, o passa `--permission-mode` al lancio.

192 </Tab>192 </Tab>

193 193

194 <Tab title="Desktop">194 <Tab title="Desktop">

195 **Durante una sessione**: nella scheda Code, utilizza il selettore di modalità accanto al pulsante di invio. Non tutte le modalità appaiono nel selettore:195 **Durante una sessione**: nella scheda Code, utilizza il selettore di modalità accanto al pulsante di invio. Non tutte le modalità appaiono nel selettore:

196 196

197 * **Auto**: appare quando [la modalità auto è disponibile](#eliminate-prompts-with-auto-mode)197 * **Auto**: appare quando [auto mode è disponibile](#eliminate-prompts-with-auto-mode)

198 * **Bypass permissions**: richiede l'interruttore **Allow bypass permissions mode** nelle impostazioni di Desktop sui piani Pro e Max; sui piani Team e Enterprise, la politica organizzativa lo controlla invece198 * **Bypass permissions**: richiede l'interruttore **Allow bypass permissions mode** nelle impostazioni Desktop su piani Pro e Max; su piani Team e Enterprise, la politica dell'organizzazione la controlla invece

199 199

200 La scheda Cowork non utilizza queste modalità. Cowork ha le sue modalità di autorizzazione, abilitate separatamente, e la scheda Cowork non mostra alcun selettore di modalità finché una modalità oltre la sua impostazione predefinita non è abilitata per il tuo account. Vedi la [documentazione di Cowork](https://claude.com/docs/cowork/overview).200 La scheda Cowork non utilizza queste modalità. Cowork ha le sue proprie modalità di autorizzazione, abilitate separatamente, e la scheda Cowork non mostra alcun selettore di modalità fino a quando una modalità oltre il suo predefinito non è abilitata per il tuo account. Vedi la [documentazione Cowork](https://claude.com/docs/cowork/overview).

201 201

202 Per i dettagli specifici del desktop, vedi [Scegli una modalità di autorizzazione](/docs/it/desktop#choose-a-permission-mode) nella guida di Desktop.202 Per i dettagli specifici del desktop, vedi [Scegli una modalità di autorizzazione](/docs/it/desktop#choose-a-permission-mode) nella guida Desktop.

203 203

204 **Come impostazione predefinita**: imposta `defaultMode` nelle [impostazioni](/docs/it/settings#where-settings-live). L'app desktop legge gli stessi file di impostazioni della CLI e applica la modalità di autorizzazione alle nuove sessioni locali.204 **Come predefinito**: imposta `defaultMode` in [impostazioni](/docs/it/settings#where-settings-live). L'app desktop legge gli stessi file di impostazioni della CLI e applica la modalità di autorizzazione alle nuove sessioni locali.

205 205

206 Una modalità che scegli nel selettore di modalità viene ricordata per cartella e ha la precedenza su `defaultMode` per quella cartella. Plan è l'eccezione: selezionarla si applica solo alla sessione corrente.206 Una modalità che scegli nel selettore di modalità viene ricordata per cartella e ha la precedenza su `defaultMode` per quella cartella. Plan è l'eccezione: selezionarla si applica solo alla sessione corrente.

207 207

209 </Tab>209 </Tab>

210 210

211 <Tab title="Web and mobile">211 <Tab title="Web and mobile">

212 Utilizza il menu a discesa della modalità accanto alla casella di prompt su [claude.ai/code](https://claude.ai/code) o nell'app mobile. I prompt di autorizzazione appaiono in claude.ai per l'approvazione. Quali modalità appaiono dipende da dove viene eseguita la sessione:212 Utilizza il menu a discesa della modalità accanto alla casella del prompt su [claude.ai/code](https://claude.ai/code) o nell'app mobile. I prompt di autorizzazione appaiono in claude.ai per l'approvazione. Quali modalità appaiono dipende da dove viene eseguita la sessione:

213 213

214 * **Cloud sessions** su [Claude Code sul web](/docs/it/claude-code-on-the-web): Accept edits, Plan, e Auto. Accept edits corrisponde alla modalità `default`: le sessioni cloud pre-approvano le modifiche ai file indipendentemente dalla modalità, quindi il menu a discesa mostra Accept edits invece di Manual. Le sessioni cloud rispettano comunque `defaultMode: "acceptEdits"` dalle impostazioni. La modalità Auto appare solo quando la tua organizzazione la consente e il modello selezionato la supporta. Bypass permissions non è disponibile.214 * **Sessioni cloud** su [Claude Code sul web](/docs/it/claude-code-on-the-web): Accept edits, Plan e Auto. Accept edits corrisponde alla modalità `default`: le sessioni cloud pre-approvano le modifiche ai file indipendentemente dalla modalità, quindi il menu a discesa mostra Accept edits invece di Manual. Le sessioni cloud rispettano comunque `defaultMode: "acceptEdits"` dalle impostazioni. La modalità Auto appare solo quando la tua organizzazione la consente e il modello selezionato la supporta. Bypass permissions non è disponibile.

215 * **Sessioni [Remote Control](/docs/it/remote-control)** sulla tua macchina locale: Manual, Accept edits, e Plan. Non puoi selezionare Auto o Bypass permissions dall'app.215 * **Sessioni [Remote Control](/docs/it/remote-control)** sulla tua macchina locale: Manual, Accept edits e Plan. Non puoi selezionare Auto o Bypass permissions dall'app.

216 * Ad eccezione di Bypass permissions, il menu a discesa mostra la modalità di autorizzazione in cui si trova la sessione locale, inclusa una impostata dal terminale. Si aggiorna quando la modalità di autorizzazione cambia nell'app o nel terminale. La sessione non segnala mai Bypass permissions a claude.ai, quindi il passaggio ad essa dal terminale non cambia quello che il menu a discesa mostra.216 * Ad eccezione di Bypass permissions, il menu a discesa mostra la modalità di autorizzazione in cui si trova la sessione locale, inclusa una impostata dal terminale. Si aggiorna quando la modalità di autorizzazione cambia nell'app o nel terminale. La sessione non segnala mai Bypass permissions a claude.ai, quindi il passaggio ad essa dal terminale non cambia quello che il menu a discesa mostra.

217 * Le sessioni ospitate dall'[app desktop](/docs/it/desktop) o dall'[estensione VS Code](/docs/it/vs-code) segnalano i cambiamenti di modalità di autorizzazione a claude.ai mentre accadono, come le sessioni ospitate in un terminale.217 * Le sessioni ospitate dall'[app desktop](/docs/it/desktop) o dall'[estensione VS Code](/docs/it/vs-code) segnalano i cambiamenti della modalità di autorizzazione a claude.ai mentre accadono, come le sessioni ospitate in un terminale.

218 * Prima della v2.1.202, le sessioni connesse con `/remote-control` o `claude --remote-control` non segnalano affatto la loro modalità di autorizzazione, quindi claude.ai e l'app mobile potevano mostrare una modalità di autorizzazione in cui la sessione non era. La mancata corrispondenza ha interessato solo l'etichetta. Claude Code ha generato prompt di autorizzazione dalla modalità di autorizzazione effettiva della sessione, e appaiono comunque nell'app per l'approvazione.218 * Prima di v2.1.202, le sessioni connesse con `/remote-control` o `claude --remote-control` non segnalarono affatto la loro modalità di autorizzazione, quindi claude.ai e l'app mobile potevano mostrare una modalità di autorizzazione in cui la sessione non era. La discrepanza ha interessato solo l'etichetta. Claude Code ha generato prompt di autorizzazione dalla modalità di autorizzazione effettiva della sessione, e hanno comunque apparso nell'app per l'approvazione.

219 219

220 Per Remote Control, la macchina locale che esegue la sessione deve essere connessa con il tuo account claude.ai; le chiavi API non sono supportate. Puoi anche impostare la modalità di autorizzazione iniziale al lancio di quella sessione locale:220 Per Remote Control, la macchina locale che esegue la sessione deve essere connessa con il tuo account claude.ai; le chiavi API non sono supportate. Puoi anche impostare la modalità di autorizzazione iniziale al lancio di quella sessione locale:

221 221

409* Installazione di dipendenze dichiarate nei tuoi file di lock o manifest409* Installazione di dipendenze dichiarate nei tuoi file di lock o manifest

410* Lettura di `.env` e invio di credenziali al loro API corrispondente410* Lettura di `.env` e invio di credenziali al loro API corrispondente

411* Richieste HTTP di sola lettura411* Richieste HTTP di sola lettura

412* Push a qualsiasi ramo del repository su cui stai lavorando, incluso il ramo predefinito. Un ramo non predefinito il cui nome lo contrassegna come target di deploy o pubblicazione, come `production` o `gh-pages`, non è coperto: il classificatore giudica un push lì sui suoi stessi termini. Il contenuto del push è ancora controllato rispetto alle altre regole, le [regole `permissions.deny`](/docs/it/permissions#manage-permissions) possono comunque bloccare i push a rami specifici completamente in ogni modalità, e la protezione del ramo del remote si applica comunque. Prima della v2.1.211, solo i push al ramo su cui hai iniziato, i rami che Claude ha creato, e i push di routine al ramo predefinito erano consentiti per impostazione predefinita, e prima della v2.1.203 qualsiasi push diretto al ramo predefinito era bloccato412* Push a qualsiasi ramo del repository su cui stai lavorando, incluso il ramo predefinito. Un ramo non predefinito il cui nome lo contrassegna come target di deploy o pubblicazione, come `production` o `gh-pages`, non è coperto: il classificatore giudica un push lì sui suoi stessi termini. Il contenuto del push è ancora controllato rispetto alle altre regole, le [regole `permissions.deny`](/docs/it/permissions#manage-permissions) possono comunque bloccare i comandi push [come scritti](/docs/it/permissions#bash-rule-limits) in ogni modalità, e la protezione del ramo del remote si applica comunque. Prima della v2.1.211, solo i push al ramo su cui hai iniziato, i rami che Claude ha creato, e i push di routine al ramo predefinito erano consentiti per impostazione predefinita, e prima della v2.1.203 qualsiasi push diretto al ramo predefinito era bloccato

413 413

414Claude Code v2.1.195 e successivi consentono anche questi per impostazione predefinita:414Claude Code v2.1.195 e successivi consentono anche questi per impostazione predefinita:

415 415

471 <Accordion title="Come il classificatore valuta le azioni">471 <Accordion title="Come il classificatore valuta le azioni">

472 Ogni azione passa attraverso un ordine di decisione fisso. Il primo passaggio corrispondente vince:472 Ogni azione passa attraverso un ordine di decisione fisso. Il primo passaggio corrispondente vince:

473 473

474 1. Le azioni che corrispondono alle tue [regole allow, ask, o deny](/docs/it/permissions#manage-permissions) si risolvono immediatamente. Le scritture su [percorsi protetti](#protected-paths) vengono instradate al classificatore anche quando una regola allow corrisponde, e così fanno le rimozioni `rm` e `rmdir` che prendono di mira un [percorso critico](#critical-paths) in Claude Code v2.1.218 e successivi. Gli strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) ti chiedono direttamente anche quando una regola allow corrisponde, e così fanno gli strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) in sessioni dove quella impostazione raggiunge Claude Code. Le regole ask che corrispondono sul contenuto di un comando, come `Bash(git push *)`, ricadono in un prompt di autorizzazione474 1. Le azioni che corrispondono alle tue [regole allow, ask, o deny](/docs/it/permissions#manage-permissions) si risolvono immediatamente. Le scritture su [percorsi protetti](#protected-paths) vengono instradate al classificatore anche quando una regola allow corrisponde, e così fanno le rimozioni `rm` e `rmdir` che prendono di mira un [percorso critico](#critical-paths) in Claude Code v2.1.218 e successivi. Gli strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) ti chiedono direttamente anche quando una regola allow corrisponde, e così fanno gli strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) in sessioni dove quella impostazione raggiunge Claude Code. Le regole ask che corrispondono sul contenuto di un comando, come `Bash(git push *)`, ricadono in un [prompt di autorizzazione](/docs/it/permissions#bash-rule-limits)

475 2. Le azioni di sola lettura e le modifiche di file nella tua directory di lavoro vengono auto-approvate, tranne le scritture su [percorsi protetti](#protected-paths) e [la prima lettura al di fuori delle directory di lavoro](#first-read-outside-the-working-directories), che ti richiede475 2. Le azioni di sola lettura e le modifiche di file nella tua directory di lavoro vengono auto-approvate, tranne le scritture su [percorsi protetti](#protected-paths) e [la prima lettura al di fuori delle directory di lavoro](#first-read-outside-the-working-directories), che ti richiede

476 3. Tutto il resto va al classificatore. Gli strumenti connector e gli strumenti MCP contrassegnati [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) che ti chiedono direttamente nel passaggio 1 non raggiungono mai il classificatore, quindi un'approvazione richiesta dall'organizzazione o un passaggio di consenso non viene mai auto-approvato476 3. Tutto il resto va al classificatore. Gli strumenti connector e gli strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) che ti chiedono direttamente nel passaggio 1 non raggiungono mai il classificatore, quindi un'approvazione richiesta dall'organizzazione o un passaggio di consenso non viene mai auto-approvato

477 4. Se il classificatore blocca, Claude riceve il motivo e prova un'alternativa. Nella maggior parte delle sessioni il motivo è il testo fisso `Blocked by classifier` piuttosto che una spiegazione scritta, in Claude Code v2.1.208 e successivi; vedi [Rivedi i dinieghi](/docs/it/auto-mode-config#review-denials)477 4. Se il classificatore blocca, Claude riceve il motivo e prova un'alternativa. Nella maggior parte delle sessioni il motivo è il testo fisso `Blocked by classifier` piuttosto che una spiegazione scritta; vedi [Rivedi i dinieghi](/docs/it/auto-mode-config#review-denials)

478 478

479 Entrando in modalità auto, le regole allow ampie che concedono l'esecuzione arbitraria di codice vengono eliminate:479 Entrando in modalità auto, le regole allow ampie che concedono l'esecuzione arbitraria di codice vengono eliminate:

480 480

518 Consenti solo strumenti pre-approvati con la modalità dontAsk518 Consenti solo strumenti pre-approvati con la modalità dontAsk

519</h2>519</h2>

520 520

521Se imposti la modalità `dontAsk`, Claude Code nega automaticamente ogni chiamata di strumento che altrimenti richiederebbe una richiesta. Claude esegue solo le azioni che corrispondono alle tue regole `permissions.allow`, ai [comandi Bash di sola lettura](/docs/it/permissions#read-only-commands), e alle chiamate approvate da un [hook PreToolUse](/docs/it/permissions#extend-permissions-with-hooks). Utilizza questa modalità per pipeline CI o ambienti limitati in cui pre-definisci esattamente cosa Claude può fare; la sessione non attende mai input. La barra di stato mostra `⏵⏵ don't ask on` mentre questa modalità è attiva.521Se imposti la modalità `dontAsk`, Claude Code nega automaticamente ogni chiamata di strumento che altrimenti richiederebbe una richiesta. Claude esegue ancora azioni che non richiedono approvazione in modalità Manual, come le letture di file all'interno delle tue directory di lavoro e i [comandi Bash di sola lettura](/docs/it/permissions#read-only-commands), più le azioni che corrispondono alle tue regole `permissions.allow` e le chiamate approvate da un [hook PreToolUse](/docs/it/permissions#extend-permissions-with-hooks). Utilizza questa modalità per pipeline CI o ambienti limitati in cui pre-definisci cosa Claude può fare; la sessione non attende mai input. La barra di stato mostra `⏵⏵ don't ask on` mentre questa modalità è attiva.

522 522

523Claude Code nega le chiamate che corrispondono alle tue regole [`ask`](/docs/it/permissions#manage-permissions) esplicite piuttosto che richiedere una conferma. Nega anche lo strumento integrato `AskUserQuestion` anche se le tue regole di autorizzazione lo corrispondono, e fa lo stesso agli strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) in sessioni dove quella impostazione raggiunge Claude Code. Nega gli strumenti MCP contrassegnati [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) allo stesso modo, perché la loro scheda di approvazione necessita di una risposta che questa modalità non raccoglie mai; questo richiede Claude Code v2.1.199 o successivo.523Claude Code nega le chiamate che corrispondono alle tue regole [`ask`](/docs/it/permissions#manage-permissions) esplicite piuttosto che richiedere una conferma. Nega anche lo strumento integrato `AskUserQuestion` anche se le tue regole di autorizzazione lo corrispondono, e fa lo stesso agli strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) in sessioni dove quella impostazione raggiunge Claude Code. Nega gli strumenti MCP contrassegnati [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) allo stesso modo, perché la loro scheda di approvazione necessita di una risposta che questa modalità non raccoglie mai; questo richiede Claude Code v2.1.199 o successivo.

524 524

permissions.md +8 −4

Details

82Claude Code supporta diverse modalità di autorizzazione che controllano come approva le chiamate di strumenti. Vedi [Permission modes](/docs/it/permission-modes) per quando utilizzare ciascuna. Per modificare la modalità in cui iniziano le sessioni, imposta `defaultMode` nei tuoi [file di impostazioni](/docs/it/settings#where-settings-live). [Which mode a session starts in](/docs/it/permission-modes#which-mode-a-session-starts-in) copre il valore predefinito integrato per ogni piano e cosa legge l'estensione VS Code.82Claude Code supporta diverse modalità di autorizzazione che controllano come approva le chiamate di strumenti. Vedi [Permission modes](/docs/it/permission-modes) per quando utilizzare ciascuna. Per modificare la modalità in cui iniziano le sessioni, imposta `defaultMode` nei tuoi [file di impostazioni](/docs/it/settings#where-settings-live). [Which mode a session starts in](/docs/it/permission-modes#which-mode-a-session-starts-in) copre il valore predefinito integrato per ogni piano e cosa legge l'estensione VS Code.

83 83

85| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |85| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

86| `default` | Richiede l'autorizzazione al primo utilizzo di ogni strumento. Etichettato come Manual nella CLI, nelle estensioni VS Code e JetBrains, e nell'app desktop, e Claude Code accetta `manual` come alias. L'etichetta e l'alias richiedono Claude Code v2.1.200 o successivo. L'etichetta dell'app desktop non dipende dalla tua versione CLI |86| `default` | Richiede l'autorizzazione al primo utilizzo di ogni strumento. Etichettato come Manual nella CLI, nelle estensioni VS Code e JetBrains, e nell'app desktop, e Claude Code accetta `manual` come alias. L'etichetta e l'alias richiedono Claude Code v2.1.200 o successivo. L'etichetta dell'app desktop non dipende dalla tua versione CLI |

87| `acceptEdits` | Accetta automaticamente le modifiche ai file e i comandi comuni del filesystem come `mkdir`, `touch`, `mv` e `cp` per i percorsi nella directory di lavoro o `additionalDirectories` |87| `acceptEdits` | Accetta automaticamente le modifiche ai file e i comandi comuni del filesystem come `mkdir`, `touch`, `mv` e `cp` per i percorsi nella directory di lavoro o `additionalDirectories` |

88| `plan` | Claude legge i file ed esegue comandi shell di sola lettura per esplorare ma non modifica i tuoi file sorgente; con [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) disponibile, i comandi approvati dal classificatore vengono eseguiti anche. Etichettato Plan nella CLI e nell'estensione VS Code |88| `plan` | Claude legge i file ed esegue comandi shell di sola lettura per esplorare ma non modifica i tuoi file sorgente; con [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) disponibile, i comandi approvati dal classificatore vengono eseguiti anche. Etichettato Plan nella CLI e nell'estensione VS Code |

89| `auto` | Auto-approva le chiamate di strumento con controlli di sicurezza in background che verificano che le azioni si allineino con la tua richiesta |89| `auto` | Auto-approva le chiamate di strumento con controlli di sicurezza in background che verificano che le azioni si allineino con la tua richiesta |

90| `dontAsk` | Nega automaticamente gli strumenti a meno che non siano pre-approvati tramite `/permissions` o regole `permissions.allow`. `AskUserQuestion`, strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool), e strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) nelle sessioni in cui tale impostazione raggiunge Claude Code vengono negati anche se li hai consentiti |90| `dontAsk` | Nega automaticamente ogni chiamata che altrimenti richiederebbe un prompt; le letture di file nelle tue directory di lavoro e altre azioni che non richiedono approvazione vengono comunque eseguite, così come gli strumenti pre-approvati tramite `/permissions` o regole `permissions.allow`. `AskUserQuestion`, strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool), e strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) nelle sessioni in cui tale impostazione raggiunge Claude Code vengono negati anche se li hai consentiti |

91| `bypassPermissions` | Salta i prompt di autorizzazione, ad eccezione delle [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves) |91| `bypassPermissions` | Salta i prompt di autorizzazione, ad eccezione delle [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves) |

92 92

93<Warning>93<Warning>

455Quando Claude accede a un symlink, le regole di autorizzazione controllano due percorsi: il symlink stesso e il file a cui si risolve. Le regole allow e deny trattano quella coppia diversamente: le regole allow ricadono nel richiedere un prompt, mentre le regole deny bloccano completamente.455Quando Claude accede a un symlink, le regole di autorizzazione controllano due percorsi: il symlink stesso e il file a cui si risolve. Le regole allow e deny trattano quella coppia diversamente: le regole allow ricadono nel richiedere un prompt, mentre le regole deny bloccano completamente.

456 456

457* **Regole allow**: si applicano solo quando sia il percorso del symlink che il suo target corrispondono. Un symlink all'interno di una directory consentita che punta al di fuori di essa richiede comunque un prompt.457* **Regole allow**: si applicano solo quando sia il percorso del symlink che il suo target corrispondono. Un symlink all'interno di una directory consentita che punta al di fuori di essa richiede comunque un prompt.

458* **Regole deny**: si applicano quando il percorso del symlink o il suo target corrisponde. Un symlink che punta a un file negato è esso stesso negato.458* **Regole deny**: si applicano quando il percorso del symlink o il suo target corrisponde. Un symlink che punta a un file negato è esso stesso negato. Ad esempio, con `Read(./project/**)` consentito e `Read(~/.ssh/**)` negato, un symlink in `./project/key` che punta a `~/.ssh/id_rsa` viene bloccato: il target non supera la regola allow e corrisponde alla regola deny.

459 459

460Ad esempio, con `Read(./project/**)` consentito e `Read(~/.ssh/**)` negato, un symlink in `./project/key` che punta a `~/.ssh/id_rsa` viene bloccato: il target non supera la regola allow e corrisponde alla regola deny.460Su macOS e Linux, una regola deny o ask scritta attraverso una directory con symlink con un modello `//`, `~/` o `/` si applica anche alla posizione reale della directory. Ad esempio, su macOS, dove `/etc` si risolve a `/private/etc`, `Read(//etc/**)` blocca anche `/private/etc/hosts`. Prima della v2.1.268, una regola deny o ask scritta attraverso una directory con symlink non si applicava a un percorso dato dalla sua posizione reale.

461 461

462Quando uno strumento apre un file approvato, Claude Code [conferma che il percorso si risolve ancora alla posizione che il controllo di autorizzazione ha approvato](/docs/it/errors#refusing-after-a-symlink-changed).462Quando uno strumento apre un file approvato, Claude Code [conferma che il percorso si risolve ancora alla posizione che il controllo di autorizzazione ha approvato](/docs/it/errors#refusing-after-a-symlink-changed).

463 463

490| `WebFetch` | Claude esegue il fetch senza chiedervi un prompt. Non cambia quali host i comandi in sandbox possono raggiungere. | Claude Code rimuove lo strumento `WebFetch`, quindi Claude non può eseguire il fetch affatto. Non cambia quali host i comandi in sandbox possono raggiungere. |490| `WebFetch` | Claude esegue il fetch senza chiedervi un prompt. Non cambia quali host i comandi in sandbox possono raggiungere. | Claude Code rimuove lo strumento `WebFetch`, quindi Claude non può eseguire il fetch affatto. Non cambia quali host i comandi in sandbox possono raggiungere. |

491| `WebFetch(domain:*)` | Claude esegue il fetch senza chiedervi un prompt, e i comandi in sandbox possono raggiungere qualsiasi host. | Claude Code mantiene lo strumento e rifiuta ogni fetch, e i comandi in sandbox non possono raggiungere alcun host. |491| `WebFetch(domain:*)` | Claude esegue il fetch senza chiedervi un prompt, e i comandi in sandbox possono raggiungere qualsiasi host. | Claude Code mantiene lo strumento e rifiuta ogni fetch, e i comandi in sandbox non possono raggiungere alcun host. |

492 492

493Le due forme differiscono anche sulle letture degli [artifact](/docs/it/artifacts), le pagine che lo strumento Artifact pubblica su claude.ai. Una regola deny o ask WebFetch nuda non si applica a quelle letture. Una regola `domain:` che copre `claude.ai` o l'host di contenuto `*.claudeusercontent.com`, come `WebFetch(domain:claude.ai)` o `WebFetch(domain:*)`, nega ogni lettura o chiede un prompt prima di essa. Una regola [`Artifact`](/docs/it/artifacts#disable-artifacts) fa lo stesso.

494

495Quando una regola blocca una lettura, la negazione nomina la regola. Prima della v2.1.268, una regola deny WebFetch nuda bloccava ogni lettura di artifact, e una regola ask nuda chiedeva un prompt prima di ognuna.

496

493Per consentire a Claude di eseguire il fetch liberamente mantenendo l'elenco di consentiti della sandbox come è, utilizzate la forma nuda. Questo `settings.json` fa questo:497Per consentire a Claude di eseguire il fetch liberamente mantenendo l'elenco di consentiti della sandbox come è, utilizzate la forma nuda. Questo `settings.json` fa questo:

494 498

495```json theme={null}499```json theme={null}

platforms.md +10 −10

Details

48 Lavora quando sei lontano dal tuo terminale48 Lavora quando sei lontano dal tuo terminale

49</h2>49</h2>

50 50

~~51Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.~~51Claude Code offre diversi modi di lavorare quando non sei al tuo terminale. Differiscono in ciò che attiva il lavoro, dove Claude viene eseguito e quanto setup è necessario.

52 52

54| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |54| :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |

56| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI or VS Code) | Run `claude remote-control` | Steering in-progress work from another device |56| [Remote Control](/docs/it/remote-control) | Guida una sessione in esecuzione da [claude.ai/code](https://claude.ai/code) o dall'app mobile Claude | La tua macchina (CLI o VS Code) | Esegui `claude remote-control` | Guidare il lavoro in corso da un altro dispositivo |

57| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |57| [Channels](/docs/it/channels) | Invia eventi da un'app di chat come Telegram o Discord, o dal tuo server | La tua macchina (CLI) | [Installa un plugin channel](/docs/it/channels#quickstart) o [crea il tuo](/docs/it/channels-reference) | Reagire a eventi esterni come errori CI o messaggi di chat |

58| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |58| [Slack](/docs/it/slack) | Menziona `@Claude` in un canale del team | Cloud Anthropic | [Installa l'app Slack](/docs/it/slack#setting-up-claude-code-in-slack) con [Claude Code sul web](/docs/it/claude-code-on-the-web) abilitato | PR e revisioni dalla chat del team |

59| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |59| [Self-hosted environments](/docs/it/self-hosted-environments) | Avvia una [sessione cloud](/docs/it/claude-code-on-the-web) e scegli l'ambiente della tua organizzazione | L'infrastruttura della tua organizzazione | [Distribuisci runner](/docs/it/self-hosted-environments-quickstart), su piani Team e Enterprise | Sessioni cloud che devono essere eseguite all'interno della tua rete |

61 61

62Se non sei sicuro da dove iniziare, [installa la CLI](/docs/it/quickstart) ed eseguila in una directory di progetto. Se preferisci non usare un terminale, [Desktop](/docs/it/desktop-quickstart) ti offre lo stesso motore con un'interfaccia grafica.62Se non sei sicuro da dove iniziare, [installa la CLI](/docs/it/quickstart) ed eseguila in una directory di progetto. Se preferisci non usare un terminale, [Desktop](/docs/it/desktop-quickstart) ti offre lo stesso motore con un'interfaccia grafica.

63 63

plugin-dependencies.md +2 −0

Details

123 123

124La copia locale della dipendenza soddisfa la voce di dipendenza del vostro plugin, anche quando la voce nomina un marketplace, quindi non è necessario installare la dipendenza dal suo marketplace. Claude Code non controlla un [vincolo di versione](#declare-a-dependency-with-a-version-constraint) rispetto a una copia locale, quindi il `plugin.json` locale non ha bisogno di una `version`. Prima della v2.1.242, una voce di dipendenza che nominava un marketplace non corrispondeva mai alla copia locale, e Claude Code disabilitava il vostro plugin al caricamento.124La copia locale della dipendenza soddisfa la voce di dipendenza del vostro plugin, anche quando la voce nomina un marketplace, quindi non è necessario installare la dipendenza dal suo marketplace. Claude Code non controlla un [vincolo di versione](#declare-a-dependency-with-a-version-constraint) rispetto a una copia locale, quindi il `plugin.json` locale non ha bisogno di una `version`. Prima della v2.1.242, una voce di dipendenza che nominava un marketplace non corrispondeva mai alla copia locale, e Claude Code disabilitava il vostro plugin al caricamento.

125 125

126Quando entrambi i plugin si trovano in una cartella padre, potete passare quella cartella a `--plugin-dir` una sola volta. Se la cartella non è essa stessa un plugin, Claude Code carica ogni cartella figlio che ha un `.claude-plugin/plugin.json`. Richiede Claude Code v2.1.265 o successivo.

127

126Se non avete installato la dipendenza dal suo marketplace, il vostro plugin smette di caricarsi quando la copia locale scompare:128Se non avete installato la dipendenza dal suo marketplace, il vostro plugin smette di caricarsi quando la copia locale scompare:

127 129

128* **Avete disabilitato la copia locale**: Claude Code disabilita il vostro plugin al prossimo caricamento del plugin. Per una voce di dipendenza che nomina un marketplace, Claude Code segnala `Dependency "<name>@inline" is disabled — enable it or remove the dependency`; per una voce con nome semplice, la segnala per il suo nome semplice. `<name>@inline` è il modo in cui Claude Code identifica ogni plugin `--plugin-dir` e `--plugin-url`.130* **Avete disabilitato la copia locale**: Claude Code disabilita il vostro plugin al prossimo caricamento del plugin. Per una voce di dipendenza che nomina un marketplace, Claude Code segnala `Dependency "<name>@inline" is disabled — enable it or remove the dependency`; per una voce con nome semplice, la segnala per il suo nome semplice. `<name>@inline` è il modo in cui Claude Code identifica ogni plugin `--plugin-dir` e `--plugin-url`.

plugin-evals.md +705 −0 created

Details

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.

5# Testare i plugin con evals

7> Scrivi casi di eval per il tuo plugin Claude Code, eseguili con claude plugin eval, valuta i risultati, confrontali con una baseline senza plugin e gating CI sul punteggio.

9`claude plugin eval` esegue il tuo [plugin](/docs/it/plugins) rispetto a una suite di casi di test e valuta i risultati. Ogni caso è un prompt realistico più uno o più grader. Un grader è un controllo pass/fail su ciò che Claude ha prodotto, come una regex sulla risposta, se uno strumento particolare è stato chiamato, o una rubrica che un secondo modello valuta sulla risposta.

11Non devi scrivere la suite a mano; `claude plugin eval init` ti pone domande sul tuo plugin, propone i casi e i grader, li prova, scrive i file, e puoi chiedere a Claude di fare lo stesso da una sessione che hai già aperta.

13Usa evals per misurare quanto affidabilmente il tuo plugin guida Claude verso il risultato corretto, per catturare regressioni quando modifichi il plugin o viene rilasciato un nuovo modello, e per vedere quale contributo il plugin apporta rispetto a nessun plugin.

15Questa pagina è per gli autori di plugin e skill che hanno un plugin funzionante e vogliono testarne il comportamento, e per i team che gating le modifiche ai plugin in CI. Il suo formato di caso è separato dal file `evals/evals.json` che il [plugin skill-creator](/docs/it/skills#run-evals-with-skill-creator) utilizza. Per creare un plugin, vedi [Creare plugin](/docs/it/plugins); per controllare i file di un plugin per errori di sintassi e schema piuttosto che il suo comportamento, usa [`claude plugin validate`](/docs/it/plugins-reference#plugin-validate).

17<Note>

18 Ogni esecuzione di eval e ogni grader judge è una vera chiamata al modello sul tuo account, conteggiata rispetto all'utilizzo del tuo piano o alla tua fattura API, quindi controlla prima i [requisiti](#requirements). Poi [crea la tua prima suite di eval](#create-your-first-eval-suite), o vai a [Eseguire evals in CI](#run-evals-in-ci) se ne hai già una.

19</Note>

21<h2 id="requirements">

22 Requisiti

23</h2>

25Per eseguire plugin evals hai bisogno di:

27* Claude Code v2.1.269 o successivo. Esegui `claude --version` per controllare e `claude update` per aggiornare.

28* Una directory di plugin con un manifesto `plugin.json` o `.claude-plugin/plugin.json`, o un [plugin skills-directory](/docs/it/plugins-reference#skills-directory-plugins).

29* La stessa autenticazione e provider di modello che le tue normali sessioni Claude Code utilizzano. Le esecuzioni di eval, i grader valutati da judge, e `claude plugin eval init` chiamano il modello con le tue credenziali, quindi contano rispetto ai tuoi limiti di utilizzo del piano o alla tua fattura API. Quando il comando riporta un costo, la cifra è una [stima del prezzo di listino](/docs/it/costs) di quelle chiamate.

31<h2 id="how-an-eval-run-works">

32 Come funziona un'esecuzione di eval

33</h2>

35Una suite di eval vive in una directory chiamata `evals/` dentro il tuo plugin, organizzata come mostra [Scrivere e perfezionare i casi](#write-and-refine-cases). Ogni caso è la sua sottodirectory con un [prompt](#set-run-limits-and-tools-in-prompt-md) e uno o più [grader](#grade-the-result). Il prompt è qualcosa che una persona che usa il tuo plugin potrebbe digitare, come una richiesta che una delle sue skill dovrebbe gestire.

37<h3 id="what-happens-in-a-run">

38 Cosa succede in un'esecuzione

39</h3>

41Per ogni esecuzione di un caso, Claude Code avvia una sessione fresca, [isolata](#how-runs-are-isolated) [non-interattiva](/docs/it/headless) con solo il tuo plugin caricato, invia il prompt, e lascia che Claude lavori finché non finisce o non raggiunge il limite di turni o tempo del caso. Ogni grader quindi controlla la risposta finale, la trascrizione, o un file che Claude ha creato, e passa o fallisce.

43<h3 id="how-a-case-is-scored">

44 Come viene valutato un caso

45</h3>

47Un'esecuzione di un agente non deterministico ti dice poco, quindi ogni caso viene eseguito tre volte per impostazione predefinita. Il punteggio di un'esecuzione è la frazione dei suoi grader che hanno passato, ponderata se imposti pesi, e il punteggio del caso è la media tra le sue esecuzioni. Un caso passa quando il suo punteggio soddisfa la [`--threshold`](#command-options), `1.0` per impostazione predefinita. Nelle chiamate di modello, una suite fa approssimativamente casi × esecuzioni esecuzioni di agenti con il plugin e altrettante per la [baseline senza plugin](#the-no-plugin-baseline), più tre brevi chiamate judge per grader `llm` o `baseline` per esecuzione.

49<h3 id="the-no-plugin-baseline">

50 La baseline senza plugin

51</h3>

53Un punteggio alto di per sé non ti dice se il plugin ha aiutato, perché Claude potrebbe fare altrettanto bene senza di esso. Per separare i due, le esecuzioni di ogni caso vengono ripetute senza plugin caricato per impostazione predefinita, e ottieni due punteggi, `WITH` e `W/OUT`. La loro differenza, `Δ`, è quello che il plugin ha contribuito. Se un caso ottiene 1.0 sia con che senza il plugin, il plugin non è quello che l'ha fatto passare. I due set di esecuzioni sono chiamati with-arm e without-arm; [Confrontare con una baseline senza plugin](#compare-against-a-no-plugin-baseline) copre come i grader vengono valutati tra loro e come disattivare la baseline.

55<h2 id="create-your-first-eval-suite">

56 Crea la tua prima suite di eval

57</h2>

59Questa procedura scrive un caso per il tuo plugin, lo esegue, e legge il risultato. Prima di iniziare, assicurati di avere:

61* Claude Code v2.1.269 o successivo e gli altri [requisiti](#requirements)

62* Un terminale aperto nella directory root del tuo plugin, quella che contiene `plugin.json` o `.claude-plugin/plugin.json`

63* Una skill nel plugin che vuoi testare, e una richiesta che un utente digiterebbe che dovrebbe attivarla

65<Steps>

66 <Step title="Crea i casi">

67 Dalla root del plugin, esegui:

69 ```bash theme={null}

70 claude plugin eval init

71 ```

73 Se Claude Code non ha già fiducia in questa directory, prima chiede `Trust this plugin directory?`; rispondi `y`. Una sessione Claude Code interattiva si apre quindi. Claude legge il tuo plugin e ti chiede quale sia un buon risultato, propone prompt che dovrebbero e non dovrebbero attivare il plugin, progetta grader per ognuno, li pilota una volta per controllare che si comportino, e scrive una directory di caso per prompt sotto `evals/`, ognuna denominata dal suo prompt. Quando Claude ti dice che la suite è pronta, esci da quella sessione con `/exit` o Ctrl+D per tornare alla tua shell.

75 Se hai già una sessione Claude Code aperta nella root del plugin, puoi invece chiedere a Claude di eseguire `claude plugin eval init`. Claude esegue il comando e poi ti pone le stesse domande in quella conversazione.

77 Se preferisci scrivere un caso tu stesso per vedere esattamente cosa contengono i file, segui [Scrivi un caso a mano](#write-a-case-manually) e torna qui per eseguirlo.

78 </Step>

80 <Step title="Esegui la suite">

81 Di nuovo alla tua shell nella root del plugin, esegui ogni caso sotto `evals/`:

83 ```bash theme={null}

84 claude plugin eval .

85 ```

87 Hai già fiducia in questa directory durante il passaggio 1, quindi l'esecuzione inizia immediatamente. Se hai scritto il caso a mano invece, l'esecuzione prima chiede `Trust this plugin directory? [y/N]`; rispondi `y`. [Cosa un'esecuzione può accedere](#security) spiega a cosa stai acconsentendo.

89 Ogni caso viene eseguito tre volte con il tuo plugin e tre volte senza, quindi un caso è sei esecuzioni. Una linea di progresso viene stampata mentre ogni esecuzione finisce, con il punteggio di quella esecuzione e il verdetto di ogni grader.

90 </Step>

92 <Step title="Leggi il riepilogo">

93 Quando la suite finisce vedi una tabella di riepilogo, seguita da dove è andato il rapporto:

95 ```text theme={null}

96 CASE WITH W/OUT Δ RUNS COST NOTES

97 first-case 1.00 0.33 +0.67 6 $0.41

99 1 case(s) · mean Δ +0.67 · 74s · $0.41

100 Report: /Users/you/my-plugin/evals/results/2026-09-10T17-02-11-482Z/report.html

101 Published: https://claude.ai/... · keep local next time with --no-publish

102 ```

103

104 `WITH` è il punteggio del caso con il tuo plugin caricato, `W/OUT` è il punteggio senza di esso, e un `Δ` positivo significa che il plugin ha aumentato il punteggio. `COST` è una stima del prezzo di listino delle chiamate al modello, e `NOTES` mostra la spiegazione del grader con il peso più alto che fallisce, o l'errore dell'esecuzione, dal with-arm.

105 </Step>

106

107 <Step title="Apri il rapporto e itera">

108 Apri l'URL `Published:`, o il percorso `Report:` quando non appare una linea `Published:`, per vedere il verdetto di ogni grader e la spiegazione per ogni esecuzione, e per i grader `llm` i voti del judge e l'estratto che ha valutato. La linea `Published:` appare solo quando il tuo account può [pubblicare rapporti](#html-report).

109

110 Il risultato più comune della prima ricerca è un `Δ` vicino a zero con il grader `tool_used: Skill` del caso che fallisce, il che significa che Claude non sta scegliendo la tua skill sulla formulazione naturale. Regola la [`description`](/docs/it/skills#frontmatter-reference) della skill, esegui di nuovo `claude plugin eval .`, e confronta.

111

112 Per iterare su un caso in modo economico, esegui un singolo arm una volta. Un'esecuzione singola è rumorosa, quindi conferma qualsiasi modifica alle tre esecuzioni predefinite prima di fidarti. Con un arm la tabella mostra colonne `SCORE` e `PASS%` invece di `WITH`, `W/OUT`, e `Δ`:

113

114 ```bash theme={null}

115 claude plugin eval . --case <case-name> --runs 1 --ablation none

116 ```

117

118 Sostituisci `<case-name>` con uno dei nomi di directory sotto `evals/`.

119 </Step>

120</Steps>

121

122<h2 id="write-and-refine-cases">

123 Scrivi e perfeziona i casi

124</h2>

125

126I casi che `claude plugin eval init` scrive sono file semplici che puoi aprire, modificare e aggiungere. Un caso è una directory sotto la directory eval del plugin che contiene un `prompt.md`, un `case.yaml`, o entrambi. Per raggruppare i casi, annidali sotto una directory che non è essa stessa un caso; qualsiasi cosa dentro una directory di caso, come `graders/` e file fixture, appartiene a quel caso.

127

128Questo è il layout che `claude plugin eval init` scrive e quello da usare per le nuove suite. Il [riferimento della suite di eval](#eval-suite-reference) ha l'albero completo, inclusi mock e risultati:

129

130```text theme={null}

131my-plugin/

132├── .claude-plugin/plugin.json

133├── skills/...

134└── evals/

135 ├── first-case/

136 │ ├── prompt.md # frontmatter: case fields; body: the prompt

137 │ ├── graders/

138 │ │ ├── criteria.md # frontmatter: type + options; body: rubric or pattern

139 │ │ └── skill-fired.md

140 │ └── case.yaml # optional: only for context.* fields

141 ├── ignores-unrelated-request/

142 │ └── ...

143 └── results/ # written by each run; add to .gitignore

144```

145

146<h3 id="write-a-case-manually">

147 Scrivi un caso a mano

148</h3>

149

150Avere Claude che scrive i casi con `claude plugin eval init` è il percorso consigliato. Per scriverne uno tu stesso invece, inizia da un modello vuoto. Il seguente comando scrive un caso denominato `first-case` con un `prompt.md` segnaposto e un grader segnaposto, e non esegue nulla:

151

152```bash theme={null}

153claude plugin eval init --bare first-case

154```

155

156```text theme={null}

157evals/first-case/

158├── prompt.md # the prompt sent to Claude, plus run limits

159└── graders/

160 └── criteria.md # one grader: how to score the result

161```

162

163In `prompt.md` scrivi il messaggio che Claude riceve in ogni esecuzione, e imposta i limiti dell'esecuzione e gli strumenti che il caso può usare nel suo frontmatter. Apri `evals/first-case/prompt.md` e sostituisci il corpo segnaposto con una richiesta che una delle tue skill dovrebbe gestire, formulata nel modo in cui un utente la digiterebbe piuttosto che nominare la skill. Questo esempio è per una skill che redige messaggi di commit; usa la tua richiesta:

164

165```markdown theme={null}

166---

167max_turns: 10

168allowed_tools: [Read, Glob, Grep, Skill]

169---

170

171Write me a commit message for this change: I renamed getUser to fetchUser and updated the three call sites.

172```

173

174Ogni esecuzione inizia in una directory di lavoro vuota, quindi metti quello di cui il compito ha bisogno nel prompt stesso, o [configura lo spazio di lavoro](#add-setup-or-history-with-case-yaml) prima. L'[elenco completo dei campi frontmatter](#prompt-md-fields) copre il modello, il timeout, i tag e le variabili di ambiente.

175

176Ogni file sotto `graders/` è un controllo applicato dopo l'esecuzione. Apri `evals/first-case/graders/criteria.md` e sostituisci il segnaposto con una rubrica per il modello judge, scritta come condizioni PASS e FAIL concrete:

177

178```markdown theme={null}

179---

180type: llm

181---

182

183PASS if <what a correct response contains>.

184FAIL if <what a wrong or missing response looks like>.

185```

186

187Poi aggiungi un secondo grader che controlla se la tua skill è quella che ha prodotto la risposta. Crea `evals/first-case/graders/skill-fired.md`, sostituendo `your-skill-name` con il `name` dal `SKILL.md` della tua skill:

188

189```markdown theme={null}

190---

191type: tool_used

192tool: Skill

193input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'

194---

195```

196

197Questo passa quando Claude ha invocato quella skill almeno una volta durante l'esecuzione, incluso dalla sua forma `plugin-name:skill-name` con namespace. [Tipi di grader](#grader-types) elenca gli altri controlli disponibili, come la corrispondenza di una regex o la conferma che un file è stato creato.

198

199Con entrambi i file salvati, esegui il caso nel modo in cui la [guida rapida](#create-your-first-eval-suite) fa, con `claude plugin eval .` dalla root del plugin.

200

201<h3 id="set-run-limits-and-tools-in-prompt-md">

202 Imposta i limiti di esecuzione e gli strumenti in prompt.md

203</h3>

204

205Imposta `max_turns`, `timeout_seconds`, `model`, `tags` di un caso, e gli `allowed_tools` che può usare nel frontmatter di `prompt.md`; il riferimento [prompt.md frontmatter](#prompt-md-fields) elenca ogni campo e il suo valore predefinito. Claude riceve il corpo esattamente come l'hai scritto. Le menzioni `@path` in esso non vengono espanse in allegati di file, quindi se Claude ha bisogno di leggere un file, concedi uno strumento per esso in `allowed_tools`.

206

207<h3 id="grade-the-result">

208 Scegli e pesa i grader

209</h3>

210

211Il frontmatter di un grader imposta il suo `type`, e opzionalmente un `weight` che lo fa contare per più del punteggio dell'esecuzione e un [`arm`](#compare-against-a-no-plugin-baseline) che controlla come viene valutato rispetto alla baseline. Dei sei tipi, `regex`, `tool_used`, `tool_order`, e `file_exists` vengono calcolati dalla trascrizione e dai file e non costano nulla, mentre `llm` e `baseline` chiamano un modello judge e si aggiungono al costo dell'esecuzione.

212

213Non ci sono grader di codice personalizzato. [Tipi di grader](#grader-types) elenca il tipo di ogni, le opzioni e la condizione di passaggio, e [cosa un grader può guardare](#what-a-grader-can-look-at) elenca i valori che `target` e `focus` accettano.

214

215Il judge per i grader `llm` e `baseline` è un modello piccolo e veloce per impostazione predefinita. Passa `--judge-model sonnet` o un ID modello completo per usarne uno più forte per le rubriche sfumate.

216

217<h4 id="choose-graders-that-give-a-stable-signal">

218 Scegli grader che danno un segnale stabile

219</h4>

220

221Un grader `llm` chiede a un modello un verdetto, quindi la sua risposta può differire tra le esecuzioni, e differisce di più il testo più lungo che deve leggere. Queste abitudini mantengono i punteggi di una suite abbastanza stabili da fidarsi:

222

223* Per output lungo come un file generato, valutalo con un grader `regex` sui contenuti del file, che controlla l'intero file allo stesso modo ogni volta. Mantieni i grader `llm` per output brevi, con rubriche scritte come condizioni PASS e FAIL concrete.

224* Dai a ogni caso un grader sul risultato, come il messaggio finale o un file prodotto, e uno su come Claude ci è arrivato, come `tool_used` o `tool_order`. Insieme ti dicono sia se la risposta era corretta che se il tuo plugin l'ha prodotta.

225* Se il grader `tool_used: Skill` di un caso passa ma `Δ` è negativo, sospetta il judge prima del plugin. Un modello judge piccolo può contrassegnare una risposta corretta come sbagliata perché è formattata diversamente da quello che la rubrica descrive. Riesegui con `--judge-model sonnet`, e stringi la rubrica in modo che la formattazione non decida il verdetto.

226* Per controllare che una build o un test sia passato dentro l'esecuzione, chiedi al prompt a Claude di eseguirlo e scrivere il risultato in un file, valuta quel file, e asserire che il comando è stato eseguito con un grader `tool_used` il cui `input_match` nomina il comando.

227

228<h3 id="compare-against-a-no-plugin-baseline">

229 Valuta rispetto alla baseline senza plugin

230</h3>

231

232Quando un plugin è sotto test, ogni caso viene eseguito in due arm per impostazione predefinita. Il with-arm è le sue esecuzioni con il plugin caricato, e il without-arm è lo stesso numero di esecuzioni senza plugin. Il riepilogo e il rapporto mostrano entrambi i punteggi e `Δ`, il punteggio with-arm meno il punteggio without-arm. Passa `--ablation none` per eseguire solo il with-arm, che dimezza il costo quando non hai bisogno del confronto, come durante l'iterazione sui grader.

233

234In un'esecuzione a due arm, alcuni grader vengono riportati con `scored: false`. Un controllo come "la skill è stata invocata" non può mai passare senza il plugin, quindi contarlo spingerebbe il without-arm verso zero e gonfierebbe `Δ`. Per mantenere i due arm comparabili, Claude Code esclude tali grader dal punteggio in entrambi gli arm e li riporta nel with-arm come indicatori pass/fail solo. Questo include:

235

236* Ogni grader `tool_used` il cui `tool` è `Skill`

237* Qualsiasi grader che contrassegni `arm: with-only`

238

239Se ogni grader in un caso è uno di questi, vengono valutati normalmente invece, poiché non ci sarebbe nulla di sinistra da valutare. Imposta `arm: both` su un grader per valutarlo in entrambi gli arm indipendentemente, che è quello che vuoi per un controllo "non deve invocare la skill" con `min: 0` e `max: 0`. Sotto `--ablation none` nulla viene escluso, quindi la stessa suite può produrre un punteggio assoluto diverso nei due modi.

240

241<h3 id="use-a-different-eval-directory">

242 Usa una directory eval diversa

243</h3>

244

245Se `evals/` è già presa da un altro strumento, mantieni la suite in una directory diversa. Puoi registrare quella directory nel `plugin.json` del plugin in modo che ogni esecuzione e ogni collaboratore la usi, o passarla sulla riga di comando per un'esecuzione singola:

246

247* **In `plugin.json`**: aggiungi `"experimental": { "evals": "quality/evals" }`.

248* **Sulla riga di comando**: passa `--eval-dir quality/evals` sia a `claude plugin eval` che a `claude plugin eval init`.

249

250Se imposti entrambi, viene usata la directory del flag. Dai un percorso relativo di nomi di directory semplici come `qa` o `quality/evals`; un percorso assoluto o uno contenente `..` viene rifiutato: come valore di flag è un errore, mentre un valore di manifest inutilizzabile stampa una riga `Warning:` e l'esecuzione usa `evals/` invece. I casi, i risultati, e l'output `init` si spostano tutti in quella directory.

251

252<h2 id="set-up-fixtures-and-mocks">

253 Configurare fixture e mock

254</h2>

255

256Un caso può richiedere più di un prompt: file o un repository git nell'area di lavoro, una conversazione precedente da continuare, o risposte dai server MCP con cui il vostro plugin comunica. Ognuno di questi viene configurato accanto al caso in modo che le esecuzioni rimangono ripetibili.

257

258<h3 id="add-setup-or-history-with-case-yaml">

259 Inizializzare l'area di lavoro o la conversazione

260</h3>

261

262Ogni esecuzione inizia in un'area di lavoro vuota. Quando un caso ha bisogno di più del prompt, aggiungete un `case.yaml` accanto a `prompt.md` con un blocco `context`.

263

264Per creare file fixture o un repository git prima, scrivete uno script Bash nella directory del caso e nominate lo script in `context.scaffold_script`. Lo script viene eseguito come voi, al di fuori della sandbox dell'agente, e solo quando passate `--scaffold`, quindi passate questo flag solo per suite che voi o la vostra organizzazione avete scritto. Per continuare una conversazione precedente, salvate la trascrizione come file `.jsonl` e nominate lo file in `context.history_file`, e il prompt del caso diventa il turno utente successivo. Per permettere a Claude di leggere directory fixture nel caso durante l'esecuzione, elencatele in `context.add_dirs`.

265

266Un `case.yaml` ha anche bisogno di `schema_version: "1.1"` e `name`; il riferimento [case.yaml fields](#case-yaml-fields) ha l'elenco completo.

267

268Questo `case.yaml` inizializza un'area di lavoro da uno script e permette a Claude di leggere fixture da una directory `resources/`:

269

270```yaml theme={null}

271schema_version: "1.1"

272name: changelog-from-diff

273tags: [smoke]

274context:

275 scaffold_script: fixture.sh

276 add_dirs: [resources]

277```

278

279<h3 id="mock-mcp-servers">

280 Mock dei server MCP

281</h3>

282

283Potete valutare un plugin le cui skill chiamano tool MCP senza il servizio reale dietro di essi. Mettete un file Markdown per tool sotto `evals/mocks/<server>/<tool>.md` per l'intera suite, o sotto la directory `mocks/` del caso stesso per un singolo caso, dove `<server>` è il nome del server nella [configurazione MCP](/docs/it/plugins-reference#mcp-servers) del vostro plugin.

284

285Un'esecuzione non avvia mai i veri server MCP del vostro plugin a meno che non lo chiediate. Claude Code registra un sostituto sotto il nome di ogni server. I tool con un file mock rispondono da esso e sono consentiti senza una concessione `--allow-tools`, e un tool senza file mock non è disponibile per Claude. Un server senza alcun mock appare nella riga di progresso `mocked:` del caso come `plugin_<plugin>_<server>[not started: no mock]`.

286

287Il corpo del file è quello che il tool restituisce a Claude. Questo mock sostituisce un tool `create_issue` su un server denominato `tracker`, controlla l'input che Claude invia, e ripete il titolo. Salvate lo come `evals/mocks/tracker/create_issue.md`:

288

289```markdown theme={null}

290---

291expect:

292 title: string

293 priority: [low, medium, high]

294---

295

296Created issue #4821: {{input.title}}

297```

298

299Inserite i campi dalla chiamata dell'input con `{{input.<field>}}`, e il contenuto di un file fixture accanto al mock con `{{file:fixtures/{input.<field>}.json}}`. Il blocco `expect:` protegge l'input. Se una chiamata lo viola, l'esecuzione si interrompe con punteggio 0 e registra il motivo, in modo che un caso possa asserire cosa il vostro plugin ha chiesto al server di fare. Impostate `error: true` per restituire il corpo come errore di tool, oppure `type: agent` per far rispondere un modello piccolo come il server da istruzioni nel corpo. Il [mock file reference](#mock-files) elenca ogni chiave e i file `_server.md` e `_tools.json`.

300

301Per valutare le chiamate stesse, puntate un grader a `target: mock_calls`.

302

303Per eseguire contro i veri server MCP del plugin, passate uno di questi flag. In entrambi i casi questi processi vengono eseguiti come voi, al di fuori della sandbox dell'esecuzione, e i loro tool hanno bisogno di una concessione [`--allow-tools`](#grant-tools):

304

305* **`--allow-real-servers`**: avvia il processo reale per ogni server che non avete mockato, e continua a rispondere ai tool mockati dai loro file

306* **`--mocks off`**: ignora `mocks/` completamente e avvia ogni server che il plugin dichiara

307

308<h4 id="replay-agent-mock-answers">

309 Riprodurre risposte mock dell'agente

310</h4>

311

312Un mock `type: agent` risponde con una chiamata al [`--judge-model`](#command-options), quindi il suo output varia tra le esecuzioni e cambia se cambiate il giudice. Quando un'esecuzione si completa senza errore o interruzione, Claude Code salva ogni risposta che un mock dell'agente ha dato sotto la directory dei risultati in `mock-recordings/`.

313

314Aprite `ADOPT.txt` lì per vedere ogni registrazione e la directory `.replay/<server>/` in cui copiarla, accanto al mock che l'ha prodotta. Dopo aver copiato una registrazione lì, le esecuzioni successive rispondono alla chiamata identica da essa senza alcuna chiamata al modello. Committete `mocks/.replay/` insieme al resto di `mocks/` in modo che le esecuzioni CI siano ripetibili.

315

316<h2 id="run-evals">

317 Esegui evals

318</h2>

319

320Una volta che una suite esiste, `claude plugin eval` la esegue. Scegli quale plugin e quali casi eseguire con l'argomento target, concedi qualsiasi strumento che i casi hanno bisogno oltre il set di sola lettura con `--allow-tools`, e controlla il conteggio delle esecuzioni, i modelli, il costo, e l'output con le altre opzioni.

321

322<h3 id="choose-what-to-evaluate">

323 Scegli cosa valutare

324</h3>

325

326La maggior parte delle volte esegui `claude plugin eval .` dalla root del plugin, che esegue ogni caso nella suite con il plugin in cui stai caricato. Per eseguire un singolo file di caso, o per valutare un plugin che hai installato piuttosto che uno che stai sviluppando, passa un target diverso:

327

328| Target | Cosa viene eseguito |

329| :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

330| La directory root di un plugin, come `.` | Ogni caso sotto la sua directory eval, con quel plugin caricato |

331| Un singolo file `prompt.md` o `case.yaml` | Quel caso, con il suo plugin contenitore caricato |

332| Un plugin installato per nome, `name` o `name@marketplace` | I casi nella directory eval della copia installata, con la copia installata caricata. I risultati vengono scritti sotto `./evals/results/` nella tua directory corrente, o `./<dir>/results/` con `--eval-dir` |

333| `name@skills-dir` | Lo stesso, per un [plugin skills-directory](/docs/it/plugins-reference#skills-directory-plugins) |

334| Omesso | La directory corrente come percorso |

335

336Aggiungi `--case <glob>` per filtrare per nome di caso e `--tag <tag>` per mantenere i casi con uno qualsiasi dei tag dati. Metti il target prima di `--tag`, `--allow-tools`, e `--json`. I primi due prendono un elenco e `--json` prende un percorso opzionale, quindi ognuno di loro legge un target che segue come il suo valore proprio.

337

338<h3 id="grant-tools">

339 Concedi strumenti

340</h3>

341

342Le esecuzioni non si fermano mai per chiedere il permesso. Gli strumenti incorporati che hanno bisogno di una concessione che non hai dato, come `Bash`, `Write`, `Edit`, `WebFetch`, e `WebSearch`, vengono rimossi dalla sessione, quindi Claude non può chiamarli affatto. L'allowlist è gli strumenti di sola lettura che il caso elenca in `allowed_tools`, da `Read`, `Glob`, `Grep`, `NotebookRead`, `Skill`, `Agent`, `TodoWrite`, e gli strumenti di task `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `TaskStop`, e `TaskOutput`, più quello che concedi con `--allow-tools`, che si applica a ogni caso nell'esecuzione. Per lasciare che i casi usino `Bash`, `Write`, `Edit`, `WebFetch`, o `WebSearch`, concedili tu stesso:

343

344```bash theme={null}

345claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"

346```

347

348Quando un caso ha chiesto uno strumento che non hai concesso, l'esecuzione lo elenca su stderr come `not granted`. Gli strumenti su un server MCP [mockato](#mock-mcp-servers) non hanno bisogno di concessione. Gli strumenti su un vero server MCP del plugin hanno bisogno sia del server avviato, con `--allow-real-servers` o `--mocks off`, che di una concessione per nome, come `--allow-tools "mcp__plugin_my-plugin_github__*"`; gli strumenti MCP di un plugin sono denominati `mcp__plugin_<plugin>_<server>__<tool>`.

349

350Quando concedi `Bash` in qualsiasi forma, ogni comando viene eseguito sotto la [sandbox a livello di OS](/docs/it/sandboxing) di Claude Code. Le scritture sono confinate allo spazio di lavoro dell'esecuzione, la tua directory home e la configurazione di Claude Code sono illeggibili, e l'accesso alla rete è limitato ai domini che concedi con `--allow-tools "WebFetch(domain:example.com)"`. Se concedi Bash o PowerShell su una macchina senza backend sandbox, Claude Code rifiuta ogni esecuzione piuttosto che eseguirla non confinata, e il caso mostra un errore di esecuzione e di solito ottiene un punteggio 0. Windows nativo non ha backend, quindi esegui le suite che concedono shell sotto WSL2; su Linux, installa prima `bubblewrap` e `socat`. Vedi i [prerequisiti di sandboxing](/docs/it/sandboxing).

351

352<h3 id="command-options">

353 Opzioni di comando

354</h3>

355

356Questa tabella copre le opzioni per il conteggio delle esecuzioni, i modelli, la valutazione, il costo, le concessioni di strumenti, i mock, e l'output. Esegui `claude plugin eval --help` per l'elenco completo, che include anche `--case`, `--tag`, `--eval-dir`, `--no-scaffold`, `--report`, e `--verbose`.

357

358| Opzione | Predefinito | Effetto |

359| :------------------------- | :-------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

360| `--runs <n>` | `runs` di ogni caso, altrimenti 3 | Esecuzioni per caso per arm |

361| `-j`, `--concurrency <n>` | `1` | Esegui fino a questo numero di esecuzioni di agenti contemporaneamente, da 1 a 8. Condividono il limite di velocità del tuo account, quindi questo accorcia il tempo di parete piuttosto che aumentare la velocità oltre quel limite. I risultati mantengono l'ordine dei casi |

362| `--model <model>` | `model` di ogni caso, altrimenti `ANTHROPIC_MODEL` se impostato, altrimenti il predefinito di Claude Code | Modello per l'agente sotto test. Fissalo in CI in modo che un rollout di modello non sia scambiato per una regressione del plugin |

363| `--judge-model <model>` | Un modello piccolo e veloce | Modello per i grader `llm` e `baseline` |

364| `--ablation <mode>` | `with-without` quando un plugin si risolve, altrimenti `none` | Se eseguire anche ogni caso senza il plugin per misurare cosa aggiunge. `none` esegue un arm; `with-without` aggiunge la baseline senza plugin |

365| `--threshold <0..1>` | `1.0` | Un caso passa quando il suo punteggio with-arm è almeno questo. Qualsiasi caso sotto di esso fa uscire il comando 1 |

366| `--max-cost-usd <usd>` | Nessun limite | Un limite sul costo stimato al prezzo di listino dell'esecuzione, non sull'utilizzo del piano. Controllato prima che ogni esecuzione inizi. Una volta speso, nulla di ulteriore inizia; le esecuzioni già in volo finiscono, quindi la spesa può superare il limite di quelle esecuzioni. Se un'esecuzione rimane non avviata, il comando esce 2 con risultati parziali |

367| `--allow-tools <tools...>` | Nessuno | Concedi strumenti oltre il set di sola lettura. Vedi [Concedi strumenti](#grant-tools) |

368| `--scaffold` | Spento | Esegui lo [`scaffold_script`](#add-setup-or-history-with-case-yaml) di ogni caso |

369| `--trust-plugin` | Spento | Salta il primo prompt di fiducia per un plugin il cui codice e suite eseguiresti tu stesso. Passalo in CI in modo che il lavoro non sia mai rifiutato da o rimasto in attesa al prompt. Vedi [Cosa un'esecuzione può accedere](#security) |

370| `--mocks <mode>` | `record` | `record` risponde alle chiamate di strumenti MCP dai [mock](#mock-mcp-servers), non avvia i veri server del plugin, e salva le risposte dei mock dell'agente per la riproduzione. `off` ignora i mock e avvia i server MCP reali del plugin |

371| `--allow-real-servers` | Spento | Con `--mocks record`, avvia anche i veri server MCP del plugin per i server che non hanno mock |

372| `--json [path]` | Spento | Stampa il [documento di risultato](#json-result) su stdout, o scrivilo in un percorso che termina in `.json`. L'esecuzione è silenziosa: nessuna linea di progresso o tabella di riepilogo |

373| `--output-dir <dir>` | `<eval dir>/results/<timestamp>/` | Dove vanno `aggregate-result.json` e `report.html` |

374| `--no-publish` | | Mantieni il rapporto HTML locale. Vedi [Rapporto HTML](#html-report) |

375| `--publish-report` | | Pubblica il rapporto anche dove rimarrebbe locale per impostazione predefinita, come un'esecuzione che una sessione Claude Code ha avviato |

376| `--keep-temp` | Spento | Mantieni la directory sandbox di ogni esecuzione e stampa il suo percorso, per il debug di quello che Claude ha prodotto |

377

378<h3 id="run-evals-in-ci">

379 Esegui evals in CI

380</h3>

381

382Nel tuo lavoro CI, esegui la suite con `--json` per scrivere il risultato per l'archiviazione, e fallisci la build sul codice di uscita. Passa `--trust-plugin` in modo che il lavoro non aspetti mai al [primo prompt di fiducia](#security), fissa entrambi i modelli in modo che i punteggi siano comparabili nel tempo, mantieni il rapporto locale, e imposta un limite di costo come limite superiore:

383

384```bash theme={null}

385claude plugin eval . \

386 --trust-plugin \

387 --json results.json \

388 --threshold 0.8 \

389 --model claude-sonnet-5 \

390 --judge-model claude-haiku-4-5 \

391 --no-publish \

392 --max-cost-usd 20

393```

394

395Il codice di uscita del lavoro ti dice cosa è successo:

396

397| Codice di uscita | Significato |

398| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

399| 0 | Ogni caso ha ottenuto un punteggio pari o superiore a `--threshold` e ogni file di caso è stato caricato |

400| 1 | Un caso ha ottenuto un punteggio inferiore alla soglia, un file di caso non è stato caricato, non sono stati trovati casi, un'esecuzione non poteva essere avviata, la directory del plugin non è attendibile e `--trust-plugin` non è stato passato, o un'opzione non era valida |

401| 2 | Esecuzione parziale: il limite `--max-cost-usd` è stato raggiunto, o la tua credenziale è stata rifiutata prima o alla prima esecuzione. `results.json` è ancora scritto con `partial: true` e il motivo |

402| 130 | Interrotto. I risultati parziali sono scritti |

403| 143 | Terminato, come da un timeout CI |

404

405I problemi di scrittura o pubblicazione del rapporto HTML non cambiano mai il codice di uscita. Per vedere perché un caso ha ottenuto un punteggio basso, eseguilo localmente senza `--json` in modo che le linee di progresso per caso e per grader vengano stampate.

406

407Un runner CI ha bisogno di un'installazione di Claude Code e [credenziali nell'ambiente](/docs/it/authentication) come `ANTHROPIC_API_KEY`. Senza `--trust-plugin`, un lavoro la cui directory di checkout Claude Code non ha già fiducia è rifiutato con uscita 1 quando non ha terminale, o aspetta al prompt quando il runner ne alloca uno. `claude plugin eval init` ha bisogno di un terminale per farti le sue domande; in CI, esegui `claude plugin eval init --bare <name>` per ottenere il modello vuoto.

408

409Per mantenere i costi prevedibili, dai alle suite di ogni cambio veloce solo grader che non chiamano un judge, usa `--ablation none` dove non hai bisogno di `Δ`, e lascia i documenti `partial: true` e le esecuzioni con `skippedPaidGraders` fuori da qualsiasi tendenza che grafici.

410

411<h2 id="read-the-results">

412 Leggi i risultati

413</h2>

414

415Ogni esecuzione con almeno un caso scrive una directory `results/<timestamp>/` dentro la directory eval, contenente `aggregate-result.json` e `report.html`. Per un target di percorso che è sotto il plugin; per un plugin che hai denominato, è sotto la tua directory corrente, come la [tabella target](#choose-what-to-evaluate) mostra. La tabella di riepilogo, il JSON, e il rapporto rendono tutti gli stessi dati di risultato.

416

417<h3 id="html-report">

418 Rapporto HTML

419</h3>

420

421`report.html` è un singolo file autonomo che non fa richieste esterne, quindi puoi allegarlo a un lavoro CI o aprirlo dal disco. Questo esempio è la parte superiore di un rapporto per un'esecuzione di suite a tre casi con `--threshold 0.8`; il costo mostrato è una stima al prezzo di listino e varia con il modello e il numero di casi:

422

423<img src="https://mintcdn.com/claude-code/qq7LHDi_F0aeFHgk/images/plugin-eval-report.png?fit=max&auto=format&n=qq7LHDi_F0aeFHgk&q=85&s=106eb6e6a70a6565f891ea3a4564f87d" alt="Parte superiore di un rapporto eval: una linea di verdetto che legge "Plugin effect: +33.3 pts vs baseline, improved 2, flat 1, regressed 0 of 3 cases", cinque riquadri di riepilogo per il punteggio della suite, il delta di ablazione, il punteggio di base, i casi che superano la soglia, e le esecuzioni perfette, quindi il primo caso con il suo delta, la barra del punteggio, e un'esecuzione i cui due grader mostrano entrambi il passaggio" width="1360" height="1032" data-path="images/plugin-eval-report.png" />

424

425Leggilo dall'alto verso il basso:

426

427* **La linea di verdetto e i riquadri** rispondono se il plugin ha aiutato in tutta la suite. Il punteggio della suite è la media dei punteggi con plugin per caso, Ablation Δ è quanto quella si trova sopra o sotto il punteggio di base, e Cases conta quanti hanno raggiunto la soglia. Perfect runs è la quota di esecuzioni con plugin dove ogni grader ha superato.

428* **Ogni scheda di caso** mostra il `Δ` del caso e il punteggio con plugin, con un segno sulla barra alla soglia. Un caso il cui `Δ` è negativo ottiene un bordo sinistro rosso, quindi le regressioni risaltano quando scorri.

429* **All'interno di un caso**, le esecuzioni con plugin vengono prima e le esecuzioni di base dopo. Ogni esecuzione elenca i suoi grader con un chip di passaggio o fallimento. Un grader fallito è già espanso con la sua spiegazione, e un grader `llm` mostra anche i voti del giudice e le prove che gli sono state mostrate, che è dove scopri perché un'esecuzione ha ottenuto un punteggio basso. I grader che non contano verso il punteggio, come `tool_used: Skill`, portano un badge `plugin-fired indicator`.

430* **Prompt e Graders**, sotto le esecuzioni, mostrano il prompt del caso e la rubrica o il modello di ogni grader, quindi qualcuno che legge il rapporto senza la suite può vedere cosa è stato chiesto e cosa è contato come buono.

431

432Se sei connesso con un abbonamento claude.ai e gli [artifact](/docs/it/artifacts) sono disponibili per il tuo account, Claude Code pubblica anche il rapporto come artifact privato e stampa `Published: <url>`. Passa `--no-publish` per mantenerlo locale. Se non appare una linea `Published:`, come con l'autenticazione con chiave API, il file locale è il rapporto.

433

434Un'esecuzione che una sessione Claude Code ha avviato, come quando chiedi a Claude di eseguire la suite per te, rimane anche locale, e la sua linea `Report:` dice `kept local`. Aggiungi `--publish-report` a quel comando per pubblicarla.

435

436<h3 id="json-result">

437 Risultato JSON

438</h3>

439

440`aggregate-result.json`, e l'output `--json`, è un documento versionato con `schemaVersion: 1` per gli script CI da analizzare. I nomi dei campi sono camelCase e i nuovi campi vengono aggiunti senza rinominare quelli esistenti, quindi scrivi il tuo script per ignorare i campi che non riconosce.

441

442Questi sono i campi che uno script di gating di solito legge. Il documento porta anche la configurazione della suite, ogni definizione di grader, e risultati di grader per esecuzione con spiegazioni e prove:

443

444| Campo | Significato |

445| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

446| `partial`, `partialReason` | `true` con `cost_ceiling`, `interrupted`, o `auth_failed` quando la suite non è finita. Lascia i risultati parziali fuori dai grafici di tendenza |

447| `aggregates.overallScore` | Punteggio medio del caso in tutta la suite |

448| `aggregates.casesPassed`, `aggregates.casesTotal` | Casi pari o superiori a `--threshold`, e il totale |

449| `aggregates.meanDelta` | Media `Δ` tra i casi, in modalità a due arm |

450| `cases[].name` | Nome del caso |

451| `cases[].aggregates.score` | Punteggio medio dell'esecuzione with-arm per il caso |

452| `cases[].aggregates.delta` | Punteggio with-arm meno punteggio without-arm. Omesso quando gli arm non sono comparabili |

453| `cases[].arms.with[].error` | `null`, o perché un'esecuzione è terminata anormalmente, come `timed out after 300s`. Un'esecuzione che è iniziata ma è terminata male è ancora valutata su quello che ha prodotto, quindi un errore non nullo non implica punteggio 0 |

454| `cases[].arms.with[].aborted` | Presente quando un [mock](#mock-mcp-servers) `expect:` o `abort_when` ha fermato l'esecuzione, con `server`, `tool`, e `reason`. L'esecuzione ottiene un punteggio 0 e `error` rimane `null` |

455| `cases[].arms.with[].skippedPaidGraders` | `true` quando il limite di costo ha saltato i grader judge di questa esecuzione, quindi il suo punteggio non è comparabile |

456| `costUsd`, `durationSeconds`, `claudeVersion` | Costo stimato al prezzo di listino incluse le chiamate judge, secondi di parete, e la versione di Claude Code che ha eseguito la suite |

457

458<h2 id="security">

459 Cosa un'esecuzione può accedere

460</h2>

461

462`claude plugin eval` carica le skill e gli hook del plugin target e esegue la sua suite di eval sulla tua macchina, come te. Puntare a un plugin è la stessa decisione di fiducia di `claude --plugin-dir`, quindi valuta solo i plugin di cui ti fidi. L'isolamento descritto in questa sezione limita quello che l'agente sotto test può raggiungere; non è un confine contro il codice del plugin stesso, e una suite che passa non dice nulla su se il plugin è sicuro.

463

464<h3 id="trust-the-plugin-directory">

465 Fidati della directory del plugin

466</h3>

467

468La prima volta che esegui `claude plugin eval` rispetto a una directory, Claude Code chiede `Trust this plugin directory?` prima di caricare qualsiasi cosa da essa, a meno che non hai già accettato il prompt di fiducia lì in una sessione `claude` interattiva. All'interno di un repository git, rispondere sì fidati dell'intero repository, per le sessioni interattive anche. Quando stdin o stdout non è un terminale, o sotto `--json`, l'esecuzione non può chiedere ed è rifiutata con uscita 1; passa `--trust-plugin` per asserire la fiducia tu stesso, solo per un plugin che eseguiresti sulla tua macchina. Un target che nomini piuttosto che dai come percorso, significando un plugin installato o un plugin skills-directory, salta il prompt.

469

470Alcune parti del plugin e della suite vengono eseguite solo quando passi il loro flag per quella esecuzione: uno [`scaffold_script`](#add-setup-or-history-with-case-yaml) di un caso con `--scaffold`, [strumenti oltre il set di sola lettura](#grant-tools) con `--allow-tools`, e i [veri server MCP](#mock-mcp-servers) del plugin con `--allow-real-servers` o `--mocks off`. Un `allowed_tools` di un caso e un frontmatter `allowed-tools` proprio di una skill non possono ampliare nessuno di loro. Quando il plugin spedisce hook che non hai scritto, o inizi i suoi veri server MCP, tratta i suoi punteggi come consultivi a meno che non l'hai eseguito in un ambiente isolato come un contenitore o runner CI, poiché gli hook e i server vengono eseguiti fuori dalla sandbox dell'agente e potrebbero toccare i file che i grader leggono.

471

472<h3 id="how-runs-are-isolated">

473 Come le esecuzioni sono isolate

474</h3>

475

476Ogni esecuzione ottiene una directory home, directory di lavoro, e configurazione di Claude Code monouso, e l'agente sotto test viene eseguito lì come processo figlio `claude -p` con solo il tuo plugin caricato. Tieni a mente queste conseguenze quando scrivi i casi:

477

478* **Nulla di personale o a livello di progetto carica.** Le tue impostazioni utente, gli hook, i file `CLAUDE.md`, i server MCP, gli altri plugin installati, la memoria, e le skill sono assenti, e nessun `.claude/` o `.mcp.json` con scope di progetto sopra la sandbox viene letto. La maggior parte del tuo ambiente shell è anche trattenuta; solo un [allowlist](#prompt-md-fields) e le variabili `EVAL_*` raggiungono l'esecuzione. Se il plugin ha bisogno di setup, spediscilo nel plugin, crealo in uno `scaffold_script`, o passa le variabili `EVAL_*`.

479* **La politica gestita può ancora limitare un'esecuzione.** Le restrizioni nelle [impostazioni gestite](/docs/it/managed-settings) che un amministratore ha distribuito alla macchina si applicano dentro un'esecuzione, quindi i risultati su una macchina gestita possono differire da una non gestita da quella politica.

480* **Lo strumento Artifact è spento.** Una skill che pubblica un [artifact](/docs/it/artifacts) può essere valutata solo su quello che produce prima di quel passaggio.

481* **Le definizioni del caso sono nascoste all'agente.** Un'esecuzione non può leggere la directory eval, quindi Claude non può vedere il prompt del caso, i suoi grader, o i casi fratelli.

482* **Nessuna sandbox di rete al di fuori dei comandi shell.** I comandi shell che concedi vengono eseguiti sotto le regole sandbox della rete. Una concessione `WebFetch(domain:…)` raggiunge quel dominio direttamente, e gli hook del plugin stesso e qualsiasi vero server MCP che inizi possono raggiungere qualsiasi host.

483

484<h2 id="eval-suite-reference">

485 Riferimento della suite di eval

486</h2>

487

488Tutto quello che una suite di eval può contenere vive sotto la directory eval del plugin, `evals/` a meno che non hai [configurato un'altra](#use-a-different-eval-directory). Questo albero mostra ogni file che `claude plugin eval` legge o scrive lì; solo `prompt.md` o `case.yaml` è richiesto per un caso per esistere:

489

490```text theme={null}

491evals/

492├── <case>/ # one directory per case; nest under a non-case directory to group

493│ ├── prompt.md # frontmatter: case and run fields; body: the prompt

494│ ├── case.yaml # optional: context.* fields, or the whole case in one file

495│ ├── graders/

496│ │ └── <name>.md # one grader per file; frontmatter: type and options; body: rubric

497│ ├── mocks/ # optional: mocks for this case only, same layout as below

498│ └── <fixtures, scripts, transcripts referenced by case.yaml>

499├── mocks/ # optional: suite-wide MCP mocks

500│ ├── <server>/

501│ │ ├── <tool>.md # one mocked tool; body: the tool result

502│ │ ├── _server.md # optional: one agent that answers several tools

503│ │ ├── _tools.json # optional: saved tools/list response for real descriptions and schemas

504│ │ └── fixtures/ # files inserted with {{file:fixtures/...}}

505│ └── .replay/<server>/ # adopted agent-mock recordings, answered without a model call

506└── results/<timestamp>/ # written by each run; add results/ to .gitignore

507 ├── aggregate-result.json

508 ├── report.html

509 └── mock-recordings/ # agent-mock answers from clean runs, with ADOPT.txt

510```

511

512<h3 id="prompt-md-fields">

513 prompt.md frontmatter

514</h3>

515

516Il frontmatter di `prompt.md` accetta questi campi. Una chiave sconosciuta è un errore:

517

518| Campo | Predefinito | Scopo |

519| :--------------------- | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

520| `schema_version` | `"1.1"`, impostato per te | Versione del formato del caso. I casi scritti come `prompt.md` lo ottengono automaticamente, quindi raramente lo imposti |

521| `name` | Il nome della directory | Nome del caso. I glob `--case` lo corrispondono e il rapporto lo chiave |

522| `description` | | Per gli umani. Non usato al momento dell'esecuzione |

523| `tags` | `[]` | Etichette per il filtraggio `--tag`. Un caso viene eseguito se uno qualsiasi dei suoi tag corrisponde |

524| `plugins` | Il plugin contenitore più vicino | Directory di plugin sotto test, relative alla directory del caso. Imposta `plugins: ["../.."]` quando il rilevamento automatico non trova il tuo plugin; vedi [il plugin non è stato caricato](#the-baseline-arm-shows-no-plugin-or-delta-is-zero) |

525| `runs` | `3` | Esecuzioni per arm, da 1 a 50. `--runs` lo sostituisce |

526| `expected_outcome` | | Per gli umani. Non usato al momento dell'esecuzione |

527| `model` | Il predefinito della sessione figlio | Modello per l'agente sotto test. `--model` lo sostituisce |

528| `max_turns` | `10` | Limite di turni, fino a 200. Colpirlo viene registrato come errore di esecuzione e di solito abbassa il punteggio, quindi impostalo generosamente |

529| `timeout_seconds` | `300` | Limite di parete per esecuzione, fino a 3600 |

530| `allowed_tools` | `[]` | Strumenti che il caso vuole, come `[Read, Glob, Grep, Skill]`. Gli strumenti di sola lettura vengono concessi quando elencati qui; per qualsiasi altra cosa, vedi [Concedi strumenti](#grant-tools) |

531| `append_system_prompt` | | Testo aggiunto al prompt di sistema della sessione figlio |

532| `env` | `{}` | Variabili di ambiente extra per la sessione figlio. Le chiavi devono corrispondere a `EVAL_[A-Z0-9_]*`; qualsiasi altra chiave fallisce l'esecuzione. L'esecuzione eredita solo un allowlist dalla tua shell: le basi come `PATH` e locale, le impostazioni proxy e certificato, le variabili che selezionano e autenticano il tuo provider di modello, la maggior parte di `ANTHROPIC_*` e `CLAUDE_CODE_*` configurazione, e `EVAL_*`. Per consegnare al plugin qualsiasi altra cosa, come un'impostazione di toolchain, esportala come variabile `EVAL_*` |

533

534<h3 id="case-yaml-fields">

535 case.yaml fields

536</h3>

537

538`case.yaml` descrive lo stesso caso in YAML e aggiunge i campi che puntano ad altri file. Richiede `schema_version: "1.1"` e `name`. I campi `prompt.md` `description`, `tags`, `plugins`, `runs`, e `expected_outcome` vanno al livello superiore; `model`, `max_turns`, `timeout_seconds`, `allowed_tools`, `append_system_prompt`, e `env` vanno sotto `execution:`. Quando entrambi i file esistono, il frontmatter di `prompt.md` sostituisce i campi corrispondenti di `case.yaml`, il corpo di `prompt.md` è il prompt, e `graders/*.md` vengono aggiunti dopo qualsiasi grader elencato in `case.yaml`.

539

540Questi campi esistono solo in `case.yaml`:

541

542| Campo | Scopo |

543| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

544| `context.scaffold_script` | Uno script Bash nella directory del caso che viene eseguito nello spazio di lavoro vuoto prima che Claude inizi, per creare file fixture o un repository git. Viene eseguito solo quando passi [`--scaffold`](#add-setup-or-history-with-case-yaml) |

545| `context.history_file` | Una trascrizione `.jsonl` nella directory del caso da riprendere. Il prompt del caso diventa il turno utente successivo |

546| `context.add_dirs` | Directory dentro la directory del caso che Claude può leggere durante l'esecuzione, concesse in sola lettura |

547| `execution.prompt` | Il prompt, quando mantieni l'intero caso in `case.yaml` e ometti `prompt.md` |

548| `graders` | Un elenco di grader, ognuno con un `name` più le stesse chiavi che un file `graders/*.md` prende nel frontmatter. Per i grader `llm`, metti la rubrica in `criteria` |

549

550<h3 id="grader-frontmatter">

551 Frontmatter del grader

552</h3>

553

554Ogni file di grader sotto `graders/` prende queste chiavi nel frontmatter, più le opzioni per il suo tipo. Il nome del grader è il nome del file senza `.md`:

555

556| Chiave | Predefinito | Scopo |

557| :------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

558| `type` | richiesto | Uno dei [tipi di grader](#grader-types) |

559| `weight` | `1` | Peso relativo nel punteggio dell'esecuzione. Qualsiasi numero positivo |

560| `arm` | non impostato | `with-only` esclude il grader dalla valutazione in un'[esecuzione a due arm](#compare-against-a-no-plugin-baseline); `both` forza un grader `tool_used: Skill` ad essere valutato in entrambi gli arm |

561

562<h4 id="what-a-grader-can-look-at">

563 Cosa un grader può guardare

564</h4>

565

566I grader `regex` prendono un `target` e i grader `llm` prendono un `focus`. Entrambi accettano gli stessi valori:

567

568| Valore | Cosa vede il grader |

569| :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

570| `last_message` | Il testo della risposta finale di Claude. Questo è il predefinito |

571| `trace` | L'intera sessione come JSON, un messaggio per riga. Un grader `regex` vede ogni messaggio; un judge `llm` vede i primi 12 e gli ultimi 12. Le virgolette e le newline dentro di esso sono JSON-escaped, quindi una regex corrisponde a `\"` piuttosto che `"` |

572| `files` | L'elenco dei percorsi che Claude ha creato durante l'esecuzione, uno per riga. Non i loro contenuti, e non i file che uno scaffold ha creato o che Claude ha solo modificato |

573| `{ source: file, path: <path> }` | I contenuti di un file nello spazio di lavoro dopo l'esecuzione. Usalo per valutare quello che il plugin ha prodotto. Un file PNG, JPEG, GIF, o WebP viene mostrato a un judge `llm` come immagine. Un judge `llm` rifiuta altri file binari come `.pptx` o PDF; rendili come immagine o scrivili come testo e valuta quello |

574| `mock_calls` | Ogni chiamata che Claude ha fatto a uno [strumento MCP mockato](#mock-mcp-servers), con il suo input e la risposta del mock |

575

576<h4 id="grader-types">

577 Tipi di grader

578</h4>

579

580Ogni tipo di grader sotto elenca le sue opzioni e quando passa:

581

582| Tipo | Opzioni | Passa quando |

583| :------------ | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

584| `regex` | `pattern`, `flags`, `match`, `target` | La regex JavaScript `pattern` viene trovata nel target. Imposta `match: not_contains` per richiedere assenza o `match: "count:N"` per richiedere esattamente N corrispondenze. Metti l'insensibilità alle maiuscole in `flags: i`; l'inline `(?i)` non è supportato |

585| `tool_used` | `tool`, `input_match`, `min`, `max` | Il numero di chiamate a `tool` il cui input JSON-encoded corrisponde alla regex opzionale `input_match` è tra `min`, predefinito 1, e `max`, predefinito illimitato. Per asserire che uno strumento non è mai stato chiamato, imposta sia `min: 0` che `max: 0` |

586| `tool_order` | `before`, `after` | Entrambi gli strumenti sono stati chiamati e la prima chiamata corrispondente a `before` precede la prima chiamata corrispondente a `after`. Ognuno è un nome di strumento o `{ tool, input_match }` |

587| `file_exists` | `path`, `exists` | Un file che Claude ha creato corrisponde al glob `path`, o nessuno con `exists: false`. Solo i file creati durante l'esecuzione contano |

588| `llm` | `criteria`, `focus` | Un modello judge vota PASS sulla rubrica in almeno due di tre voti. Nel layout `.md` il corpo del file è i criteri |

589| `baseline` | `baseline_file`, `criteria` | Un judge trova che l'esecuzione soddisfa i criteri almeno altrettanto bene della trascrizione di riferimento a `baseline_file`, un `.jsonl` nella directory del caso |

590

591<h3 id="mock-files">

592 File mock

593</h3>

594

595Un file `<tool>.md` sotto `mocks/<server>/` risponde a uno strumento. Il suo corpo è il risultato dello strumento, con sostituzioni `{{input.<field>}}` e `{{file:fixtures/<name>}}`. Il suo frontmatter accetta queste chiavi:

596

597| Chiave | Predefinito | Scopo |

598| :----------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

599| `type` | `fixed` | `fixed` restituisce il corpo come scritto. `agent` tratta il corpo come istruzioni per un modello piccolo che gioca il server per l'esecuzione e vede le chiamate precedenti come storia |

600| `expect` | non impostato | Una mappa da percorsi di input punteggiati a un nome di tipo come `string`, `number`, `boolean`, `array`, o `object`, un `/regex/`, un letterale, o un elenco di letterali consentiti. Una chiamata che lo viola interrompe l'esecuzione con punteggio 0 ed è riportata come `aborted` con il server, lo strumento, e il motivo |

601| `error` | `false` | `fixed` solo. Restituisci il corpo come errore dello strumento |

602| `abort_when` | non impostato | `agent` solo. Prosa che elenca le uniche condizioni sotto le quali l'agente può interrompere l'esecuzione |

603

604Due file opzionali si trovano accanto ai file dello strumento nella directory di un server:

605

606* **`_server.md`**: un singolo mock `type: agent` che risponde a diversi strumenti, elencati nella sua chiave frontmatter `tools:`. Un `<tool>.md` per lo stesso strumento ha precedenza. Metti una guardia `expect:` sul singolo `<tool>.md`, non qui

607* **`_tools.json`**: una risposta `tools/list` salvata dal vero server, in modo che gli strumenti mockati portino le loro vere descrizioni e schemi di input invece di un placeholder permissivo

608

609La directory `mocks/` propria di un caso usa lo stesso layout e sostituisce i file della suite file per file.

610

611<h2 id="troubleshooting">

612 Risoluzione dei problemi

613</h2>

614

615Questi sono i problemi che gli autori incontrano più spesso, chiavi su quello che vedi.

616

617<h3 id="plugin-eval-is-currently-in-early-access">

618 "plugin eval is currently in early access"

619</h3>

620

621La tua build precede la disponibilità generale del comando. Esegui `claude update`, poi esegui di nuovo il comando in una sessione fresca.

622

623<h3 id="plugin-eval-is-currently-unavailable">

624 "plugin eval is currently unavailable"

625</h3>

626

627Anthropic ha disattivato il comando lato server. Nulla sulla tua macchina lo riattiva; esegui `claude update` e riprova in una sessione fresca più tardi.

628

629<h3 id="is-not-a-trusted-plugin-directory-and-this-run-cannot-stop-to-ask-you-about-it">

630 "is not a trusted plugin directory, and this run cannot stop to ask you about it"

631</h3>

632

633Questa è la prima esecuzione rispetto a una directory di cui Claude Code non ha ancora fiducia, e non può chiedere perché stdin o stdout non è un terminale o hai passato `--json`. Esegui `claude plugin eval <dir>` una volta in un terminale e rispondi al prompt, o passa `--trust-plugin` se ti fidi del codice e della suite del plugin. Vedi [Cosa un'esecuzione può accedere](#security).

634

635<h3 id="no-eval-cases-found">

636 "No eval cases found"

637</h3>

638

639Nessun `<case>/prompt.md` o `<case>/case.yaml` esiste sotto la directory eval in vigore, o i tuoi filtri `--case` e `--tag` non hanno corrisposto a nessun caso. Esegui dalla root del plugin, o esegui `claude plugin eval init` per creare una suite.

640

641<h3 id="the-baseline-arm-shows-no-plugin-or-delta-is-zero">

642 Il baseline arm mostra nessun plugin, o delta è zero

643</h3>

644

645Se il riepilogo non ha colonna `W/OUT`, o il caso fallisce con "ablation requested but no plugin resolved", nessun plugin è stato trovato per il caso. Aggiungi `plugins: ["../.."]` al caso, dando il percorso dalla directory del caso alla directory del plugin.

646

647Se il plugin è stato caricato e `Δ` è ancora vicino a zero con il tuo grader `tool_used: Skill` che fallisce, questo è di solito un risultato reale, significando che la `description` della skill non attiva sulla formulazione del prompt. Regola la descrizione e riesegui la stessa suite.

648

649<h3 id="everything-scores-zero-although-the-right-files-were-produced">

650 Tutto ottiene un punteggio zero sebbene i file corretti siano stati prodotti

651</h3>

652

653I tuoi grader puntano a `files`, l'elenco dei percorsi creati, quando intendevi i contenuti del file. Usa `{ source: file, path: <path> }` come `target` o `focus`. Separatamente, `file_exists` conta solo i file creati durante l'esecuzione, quindi un file che lo scaffold ha creato o che Claude ha solo modificato è invisibile ad esso; valuta i suoi contenuti, o usa `tool_used` su `Edit`.

654

655<h3 id="a-regex-over-the-trace-doesn’t-match-text-i-can-see">

656 Una regex sulla traccia non corrisponde al testo che posso vedere

657</h3>

658

659Il `target` predefinito è `last_message`, non la traccia. Quando fai il target `trace`, è JSON per riga, quindi le virgolette appaiono come `\"`. Le regex usano la sintassi JavaScript, quindi metti `i` in `flags` piuttosto che scrivere `(?i)`.

660

661<h3 id="tools-are-denied-mcp-tools-are-missing-or-bash-won’t-run">

662 Gli strumenti vengono negati, gli strumenti MCP mancano, o Bash non verrà eseguito

663</h3>

664

665Qualsiasi cosa oltre il set di sola lettura ha bisogno della tua concessione, come `--allow-tools Bash Write`. I tuoi server MCP personali non caricano mai in un'esecuzione. I server del plugin stesso non si avviano a meno che non [opti per esso](#mock-mcp-servers), e i loro strumenti hanno quindi bisogno anche di una concessione `--allow-tools "mcp__plugin_<plugin>_<server>__*"`; uno strumento mockato non ha bisogno di nessuno dei due.

666

667<h3 id="the-run-exits-1-but-the-results-look-fine">

668 L'esecuzione esce 1 ma i risultati sembrano bene

669</h3>

670

671Il `--threshold` predefinito è 1.0, quindi il comando esce 1 quando qualsiasi caso ottiene un punteggio inferiore a perfetto. Imposta una soglia che corrisponda al tuo bar. L'uscita 1 copre anche un file di caso che non è stato caricato, che viene riportato su stderr sopra la tabella.

672

673<h3 id="json-output-path-must-end-in-json">

674 "--json output path must end in .json"

675</h3>

676

677Hai messo il target dopo `--json`, quindi è stato letto come il percorso di output. Metti il target per primo, come in `claude plugin eval . --json`, o dai a `--json` un percorso `.json` esplicito.

678

679<h3 id="a-grader-shows-passed-false-under-a-run-that-scored-1-0">

680 Un grader mostra passed: false sotto un'esecuzione che ha ottenuto un punteggio 1.0

681</h3>

682

683Quel grader è escluso dal punteggio per design in un'esecuzione a due arm, e il suo campo `scored` è `false`. Vedi [Confrontare con una baseline senza plugin](#compare-against-a-no-plugin-baseline).

684

685<h3 id="runs-fail-with-a-usage-limit-or-rate-limit-error-partway-through">

686 Le esecuzioni falliscono con un errore di limite di utilizzo o limite di velocità a metà strada

687</h3>

688

689Se il tuo account raggiunge il limite di utilizzo del piano o un limite di velocità API mentre una suite è in esecuzione, ogni esecuzione successiva termina con quell'errore, viene valutata su quello che ha prodotto, e di solito ottiene un punteggio 0. La suite finisce comunque e non è contrassegnata `partial`, quindi il risultato può sembrare una regressione. Controlla la colonna `NOTES` o `cases[].arms.with[].error` nel JSON per il messaggio di limite prima di fidarti dei punteggi, poi riesegui dopo che il limite si ripristina, con `--runs 1` o un filtro `--case` se hai bisogno di rimanere sotto di esso.

690

691<h3 id="runs-time-out-or-hit-the-turn-cap">

692 Le esecuzioni scadono o colpiscono il limite di turni

693</h3>

694

695I predefiniti sono 10 turni e 300 secondi. Aumenta `max_turns` e `timeout_seconds` nel caso per compiti che hanno bisogno di più, e usa `--max-cost-usd` come limite di costo piuttosto che limiti stretti per esecuzione.

696

697<h2 id="see-also">

698 Vedi anche

699</h2>

700

701* [Creare plugin](/docs/it/plugins): costruisci il plugin che stai testando, e caricalo con `--plugin-dir` durante lo sviluppo

702* [Riferimento dei plugin](/docs/it/plugins-reference#plugin-eval): le voci di comando `plugin eval` e `plugin eval init` e la chiave `experimental.evals` del manifesto

703* [Skills](/docs/it/skills): come la descrizione di una skill decide quando Claude la invoca, che è quello che un caso che controlla se la skill si attiva sta misurando

704* [Sandboxing](/docs/it/sandboxing): la sandbox a livello di OS che si applica quando concedi Bash a un'esecuzione

705* [Creare e distribuire un marketplace di plugin](/docs/it/plugin-marketplaces): pubblica il plugin una volta che la sua suite passa

plugin-hints.md +1 −1

Details

36Condiziona l'emissione su una variabile di ambiente in modo che il marcatore sia improbabile che appaia quando un utente esegue direttamente la tua CLI, quindi scrivi il tag su stderr sulla sua propria riga. Scegli quale variabile controllare:36Condiziona l'emissione su una variabile di ambiente in modo che il marcatore sia improbabile che appaia quando un utente esegue direttamente la tua CLI, quindi scrivi il tag su stderr sulla sua propria riga. Scegli quale variabile controllare:

37 37

38* `CLAUDECODE`: impostata su ogni versione di Claude Code, quindi raggiunge il maggior numero di sessioni. È anche impostata nelle sessioni tmux e nei sottoprocessi del server MCP stdio che Claude Code avvia. Le estensioni IDE la impostano anche nei loro terminali integrati, dove un utente potrebbe eseguire direttamente la tua CLI.38* `CLAUDECODE`: impostata su ogni versione di Claude Code, quindi raggiunge il maggior numero di sessioni. È anche impostata nelle sessioni tmux e nei sottoprocessi del server MCP stdio che Claude Code avvia. Le estensioni IDE la impostano anche nei loro terminali integrati, dove un utente potrebbe eseguire direttamente la tua CLI.

39* `CLAUDE_CODE_CHILD_SESSION`: impostata solo nei sottoprocessi che Claude Code stesso genera, come le chiamate di strumenti, i comandi hook e i comandi della [riga di stato](/docs/it/statusline), quindi il tag normalmente non raggiunge un terminale umano. Un processo di lunga durata che è stato avviato all'interno di una sessione, come un server tmux, acquisisce la variabile, quindi le shell avviate successivamente da quel processo mostrano comunque il tag grezzo. Richiede Claude Code v2.1.172 o successivo, quindi le sessioni su versioni precedenti non ricevono il suggerimento.39* `CLAUDE_CODE_CHILD_SESSION`: impostata solo nei sottoprocessi che Claude Code stesso genera, come le chiamate di strumenti, i comandi hook e i comandi della [riga di stato](/docs/it/statusline), quindi il tag normalmente non raggiunge un terminale umano. Un processo di lunga durata che è stato avviato all'interno di una sessione, come un server tmux, acquisisce la variabile, quindi le shell avviate successivamente da quel processo mostrano comunque il tag grezzo.

40 40

41I seguenti esempi condizionano su `CLAUDECODE` per la massima copertura e emettono un suggerimento per un plugin denominato `example-cli` nel marketplace ufficiale:41I seguenti esempi condizionano su `CLAUDECODE` per la massima copertura e emettono un suggerimento per un plugin denominato `example-cli` nel marketplace ufficiale:

42 42

plugin-marketplaces.md +15 −8

Details

96 </Step>96 </Step>

97 97

98 <Step title="Aggiungi e installa">98 <Step title="Aggiungi e installa">

99 Dalla directory che contiene `my-marketplace`, avvia Claude Code ed esegui i seguenti comandi. Il comando install apre una vista dei dettagli del plugin dove selezioni un ambito di installazione per confermare l'installazione. Controlla il riepilogo dell'installazione: se riporta `Run /reload-plugins to activate.`, esegui quel comando.99 Dalla directory che contiene `my-marketplace`, avvia Claude Code ed esegui i seguenti comandi. Il comando install apre una vista dei dettagli del plugin dove selezioni un ambito di installazione per confermare l'installazione. Controlla il riepilogo dell'installazione: se riporta `Run /reload-plugins to activate.`, vedi [Applica le modifiche ai plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting).

100 100

101 ```shell theme={null}101 ```shell theme={null}

102 /plugin marketplace add ./my-marketplace102 /plugin marketplace add ./my-marketplace

174 174

175<Note>175<Note>

176 **Nomi riservati**: i seguenti nomi di marketplace sono riservati per uso ufficiale di Anthropic e non possono essere utilizzati da marketplace di terze parti: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `healthcare`. Anche i nomi che impersonano marketplace ufficiali, come `official-claude-plugins` o `anthropic-plugins-v2`, sono bloccati. La riserva di questi nomi impedisce a un marketplace di terze parti di presentarsi come fonte pubblicata da Anthropic.176 **Nomi riservati**: i seguenti nomi di marketplace sono riservati per uso ufficiale di Anthropic e non possono essere utilizzati da marketplace di terze parti: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `claude-tag-plugins`, `healthcare`. Anche i nomi che impersonano marketplace ufficiali, come `official-claude-plugins` o `anthropic-plugins-v2`, sono bloccati. La riserva di questi nomi impedisce a un marketplace di terze parti di presentarsi come fonte pubblicata da Anthropic.

177 177

178 Claude Code ricontrolla i nomi riservati ogni volta che carica un marketplace, non solo quando ne aggiungi uno. Un marketplace registrato con uno di questi nomi prima che il nome diventasse riservato smette di caricarsi e segnala che è [registrato da una fonte non attendibile](/docs/it/errors#marketplace-is-registered-from-an-untrusted-source). Rimuovi quel marketplace e aggiungilo di nuovo dalla fonte ufficiale di Anthropic. Un marketplace di terze parti interessato da un nome appena riservato si carica di nuovo non appena lo aggiungi di nuovo con un nome diverso. Prima della v2.1.205, `first-party-plugins` e `healthcare` non erano riservati, e un marketplace già registrato con un nome riservato continuava a caricarsi.178 Claude Code ricontrolla i nomi riservati ogni volta che carica un marketplace, non solo quando ne aggiungi uno. Un marketplace registrato con uno di questi nomi prima che il nome diventasse riservato smette di caricarsi e segnala che è [registrato da una fonte non attendibile](/docs/it/errors#marketplace-is-registered-from-an-untrusted-source). Rimuovi quel marketplace e aggiungilo di nuovo dalla fonte ufficiale di Anthropic. Un marketplace di terze parti interessato da un nome appena riservato si carica di nuovo non appena lo aggiungi di nuovo con un nome diverso. Prima della v2.1.205, `first-party-plugins` e `healthcare` non erano riservati, e un marketplace già registrato con un nome riservato continuava a caricarsi. Prima della v2.1.265, `claude-tag-plugins` non era riservato.

179</Note>179</Note>

180 180

181<h3 id="owner-fields">181<h3 id="owner-fields">

226 226

228| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |228| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

229| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Ritorna a `name` quando omesso. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. |229| `displayName` | string | Nome leggibile mostrato nelle superfici dell'interfaccia utente. Quando né la voce né il `plugin.json` del plugin ne impostano uno, gli utenti vedono il `name` del plugin. Può contenere spazi e qualsiasi maiuscola/minuscola. Non utilizzato per il namespacing o la ricerca. |

231| `version` | string | Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una [`command` source](#command-sources) non è bloccato da nessuno dei due campi. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management). |231| `version` | string | Versione del plugin. Se impostato (qui o in `plugin.json`), il plugin è bloccato a questa stringa e gli utenti ricevono aggiornamenti solo quando cambia. Un plugin con una [`command` source](#command-sources) non è bloccato da nessuno dei due campi. Se non impostato in nessuno dei due posti, la versione proviene dalla prossima source in [version management](/docs/it/plugins-reference#version-management). |

241| `relevance` | object | Segnali che indicano a Claude Code quando suggerire questo plugin agli utenti. Ha effetto solo per i marketplace che un amministratore consente nelle impostazioni gestite. Vedi [Recommend plugins for your org](/docs/it/plugin-relevance). |241| `relevance` | object | Segnali che indicano a Claude Code quando suggerire questo plugin agli utenti. Ha effetto solo per i marketplace che un amministratore consente nelle impostazioni gestite. Vedi [Recommend plugins for your org](/docs/it/plugin-relevance). |

242| `defaultEnabled` | boolean | Se il plugin è abilitato dopo l'installazione (predefinito: true). Impostare su `false` per installare il plugin disabilitato fino a quando l'utente non acconsente. Ha la precedenza sullo stesso campo nel `plugin.json` del plugin. Vedi [Default enablement](/docs/it/plugins-reference#default-enablement). |242| `defaultEnabled` | boolean | Se il plugin è abilitato dopo l'installazione (predefinito: true). Impostare su `false` per installare il plugin disabilitato fino a quando l'utente non acconsente. Ha la precedenza sullo stesso campo nel `plugin.json` del plugin. Vedi [Default enablement](/docs/it/plugins-reference#default-enablement). |

243 243

244Sia la voce che il `plugin.json` del plugin stesso possono impostare i campi di visualizzazione `displayName`, `description`, `author`, `homepage`, `repository`, `license` e `keywords`. Negli elenchi e nei dettagli dei plugin, prima e dopo l'installazione:

245

246* Per un campo che imposti sulla voce, gli utenti vedono il valore della voce, anche quando `plugin.json` ne imposta uno diverso.

247* Per un campo che la voce lascia non impostato, gli utenti vedono il valore di `plugin.json`.

248

249Prima dell'installazione, Claude Code può leggere `plugin.json` solo per le voci con una [relative-path source](#relative-paths), i cui file di plugin si trovano all'interno del marketplace stesso. Per una voce con qualsiasi altro tipo di source, gli utenti vedono solo i campi della voce stessa fino a quando non installano il plugin.

250

244**Campi di configurazione dei componenti:**251**Campi di configurazione dei componenti:**

245 252

307}314}

308```315```

309 316

310I percorsi si risolvono relativamente alla radice del marketplace, che è la directory contenente `.claude-plugin/`. Nell'esempio sopra, `./plugins/my-plugin` punta a `<repo>/plugins/my-plugin`, anche se `marketplace.json` si trova in `<repo>/.claude-plugin/marketplace.json`. Non usare `../` per fare riferimento a percorsi al di fuori della radice del marketplace.317I percorsi si risolvono relativamente alla radice del marketplace, che è la directory contenente `.claude-plugin/`. Nell'esempio sopra, `./plugins/my-plugin` punta a `<repo>/plugins/my-plugin`, anche se `marketplace.json` si trova in `<repo>/.claude-plugin/marketplace.json`. Non usare `../` per fare riferimento a percorsi al di fuori della radice del marketplace. Su macOS e Linux, Claude Code rifiuta una voce di percorso con una barra rovesciata ovunque dopo il `./` iniziale, quindi scrivi i separatori come `/` su ogni piattaforma.

311 318

312Un bare name è un singolo nome di directory senza `/`, come `"formatter"`. Per scrivere bare names invece di percorsi `./`, imposta [`metadata.pluginRoot`](#optional-fields) sulla directory in cui si risolvono. Con `"pluginRoot": "./plugins"`, Claude Code risolve `"source": "formatter"` a `./plugins/formatter`. Richiede Claude Code v2.1.239 o successivo.319Un bare name è un singolo nome di directory senza `/`, come `"formatter"`. Per scrivere bare names invece di percorsi `./`, imposta [`metadata.pluginRoot`](#optional-fields) sulla directory in cui si risolvono. Con `"pluginRoot": "./plugins"`, Claude Code risolve `"source": "formatter"` a `./plugins/formatter`. Richiede Claude Code v2.1.239 o successivo.

313 320

1270 Validazione e test1277 Validazione e test

1271</h2>1278</h2>

1272 1279

1273Testa il tuo marketplace prima di condividerlo.1280Testa il tuo marketplace prima di condividerlo. La validazione controlla la struttura dei file; per testare se un plugin cambia il comportamento di Claude su prompt realistici, esegui la sua suite di eval con [`claude plugin eval`](/docs/it/plugin-evals) prima di pubblicare una nuova versione.

1274 1281

1275Dalla tua directory marketplace, valida la sintassi JSON:1282Dalla tua directory marketplace, valida la sintassi JSON:

1276 1283

1465| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | La directory che hai denominato non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file di skill, agente o comando da verificare | Esegui dalla radice del marketplace, o crea `.claude-plugin/marketplace.json` con i campi obbligatori |1472| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | La directory che hai denominato non ha `.claude-plugin/marketplace.json` o `plugin.json`, e nessun file di skill, agente o comando da verificare | Esegui dalla radice del marketplace, o crea `.claude-plugin/marketplace.json` con i campi obbligatori |

1466| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controlla le virgole mancanti, le virgole extra o le stringhe non quotate |1473| `Invalid JSON syntax: Unexpected token...` | Errore di sintassi JSON in marketplace.json | Controlla le virgole mancanti, le virgole extra o le stringhe non quotate |

1468| `plugins[0].source: Path contains ".."` | Il percorso di origine contiene `..` | Usa percorsi relativi alla radice del marketplace senza `..`. Vedi [Percorsi relativi](#relative-paths) |1475| `plugins[0].source: Path contains ".."` | Il percorso di origine contiene `..` | Usa percorsi relativi alla radice del marketplace senza `..`. Vedi [Relative paths](#relative-paths) |

1469| `Marketplace name cannot contain control or bidirectional-formatting characters` | Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace` |1476| `Marketplace name cannot contain control or bidirectional-formatting characters` | Il `name` del marketplace contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, questi caratteri producevano l'errore `Marketplace name impersonates an official Anthropic/Claude marketplace` |

1470| `Plugin name cannot contain control or bidirectional-formatting characters` | Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo |1477| `Plugin name cannot contain control or bidirectional-formatting characters` | Un `name` di plugin contiene un carattere di formattazione bidirezionale Unicode o un carattere di controllo, come un escape o una newline | Rimuovi il carattere dal nome. Prima della v2.1.247, Claude Code non eseguiva questo controllo |

1471 1478

1609 I plugin con percorsi relativi non riescono nei marketplace basati su URL1616 I plugin con percorsi relativi non riescono nei marketplace basati su URL

1610</h3>1617</h3>

1611 1618

1612**Sintomi**: Hai aggiunto un marketplace tramite URL (come `https://example.com/marketplace.json`), ma i plugin con origini di percorso relativo come `"./plugins/my-plugin"` non riescono a installare con errori "path not found".1619**Sintomi**: Hai aggiunto un marketplace tramite URL (come `https://example.com/marketplace.json`), ma i plugin con origini di percorso relativo come `"./plugins/my-plugin"` non riescono a installare con `its marketplace entry path does not stay inside the marketplace directory`. I plugin già installati non riescono a caricare con `Plugin source path refused`. Entrambi i messaggi hanno una [voce di riferimento errore](/docs/it/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).

1613 1620

1614**Causa**: L'aggiunta di un marketplace basato su URL scarica solo il file `marketplace.json` stesso, e Claude Code non recupera i file dei plugin per percorso relativo da quel server. I percorsi relativi nella voce del marketplace fanno riferimento a file sul server remoto che non sono stati scaricati.1621**Causa**: L'aggiunta di un marketplace basato su URL scarica solo il file `marketplace.json` stesso, e Claude Code non recupera i file dei plugin per percorso relativo da quel server. I percorsi relativi nella voce del marketplace fanno riferimento a file sul server remoto che non sono stati scaricati.

1615 1622

plugins.md +10 −2

Details

179<Warning>179<Warning>

180 **Errore comune**: Non mettere `commands/`, `agents/`, `skills/` o `hooks/` dentro la directory `.claude-plugin/`. Solo `plugin.json` va dentro `.claude-plugin/`. Tutte le altre directory devono essere al livello radice del plugin.180 **Errore comune**: Non mettere `commands/`, `agents/`, `skills/` o `hooks/` dentro la directory `.claude-plugin/`. Solo `plugin.json` va dentro `.claude-plugin/`. Tutte le altre directory devono essere al livello radice del plugin.

181 181

182 La radice del plugin è la directory del singolo plugin: quella che passi a `--plugin-dir` o che contiene `.claude-plugin/plugin.json`. Non è mai `~/.claude/`. Ad esempio, Claude Code non legge un `.mcp.json` posizionato in `~/.claude/.mcp.json`.182 La radice del plugin è la directory del singolo plugin, come `my-first-plugin/` dalla [guida rapida](#quickstart). Non è mai `~/.claude/`. Ad esempio, Claude Code non legge un `.mcp.json` posizionato in `~/.claude/.mcp.json`.

183</Warning>183</Warning>

184 184

2344. Test coverage2344. Test coverage

235```235```

236 236

237Dopo aver installato il plugin, controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, esegui quel comando per caricare gli Skills. Per una guida completa sulla creazione di Skill inclusa la divulgazione progressiva e le restrizioni degli strumenti, vedi [Agent Skills](/docs/it/skills).237Dopo aver installato il plugin, controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, vedi [Applica le modifiche del plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) per caricare gli Skills nella tua sessione corrente. Per una guida completa sulla creazione di Skill inclusa la divulgazione progressiva e le restrizioni degli strumenti, vedi [Agent Skills](/docs/it/skills).

238 238

239<h3 id="add-lsp-servers-to-your-plugin">239<h3 id="add-lsp-servers-to-your-plugin">

240 Aggiungi server LSP al tuo plugin240 Aggiungi server LSP al tuo plugin

340 Per testare un plugin insieme a un plugin da cui dipende, vedi [Testa un plugin e la sua dipendenza localmente](/docs/it/plugin-dependencies#test-a-plugin-and-its-dependency-locally).340 Per testare un plugin insieme a un plugin da cui dipende, vedi [Testa un plugin e la sua dipendenza localmente](/docs/it/plugin-dependencies#test-a-plugin-and-its-dependency-locally).

341</Tip>341</Tip>

342 342

343Provare il plugin con `--plugin-dir` ti dice che può funzionare. Per scoprire quanto spesso Claude effettivamente lo raggiunge e ottiene il risultato giusto, eseguilo su un set di prompt di test con [`claude plugin eval`](/docs/it/plugin-evals). Ogni prompt viene eseguito più volte con e senza il plugin caricato, quindi puoi vedere cosa contribuisce il plugin e catturare regressioni quando lo modifichi o una nuova versione del modello viene rilasciata.

344

345Per caricare diversi plugin da un unico posto, passa una cartella che li contiene, ad esempio `--plugin-dir ./plugins`. Il caricamento di una cartella di plugin richiede Claude Code v2.1.265 o successivo. Claude Code legge il livello superiore della cartella per decidere quali plugin caricare, e in una sessione interattiva osserva anche la cartella per i cambiamenti successivi:

346

347* **Cosa si carica**: se la cartella non ha un manifest o componenti di plugin al suo livello superiore, Claude Code la tratta come una cartella di plugin. Ogni sottocartella immediata che ha un manifest `.claude-plugin/plugin.json` si carica come un plugin separato. Claude Code salta tutto il resto nella cartella senza segnalare un errore, inclusi i plugin che non hanno un manifest.

348* **Cambiamenti durante una sessione interattiva**: una sottocartella che aggiungi si carica come un nuovo plugin una volta che il suo manifest è in posizione, e quando rimuovi una sottocartella, il suo plugin si scarica. Claude Code stampa una riga nella sessione per ogni cambiamento. Se l'applicazione di un cambiamento a metà conversazione [invaliderebbe la cache del prompt](/docs/it/prompt-caching#enabling-or-disabling-a-plugin), Claude Code la trattiene, e la riga dice di eseguire `/reload-plugins` per applicarla.

349

343Per testare un plugin che è già stato confezionato come archivio `.zip` e ospitato su un URL, come un artefatto di build CI, usa `--plugin-url` invece. Claude Code recupera l'archivio all'avvio e lo carica solo per quella sessione. Se Claude Code non riesce a recuperare l'archivio, o l'archivio non è valido, si avvia senza il plugin e registra un errore di caricamento del plugin che puoi rivedere nella scheda **Errors** del gestore `/plugin`. Le stesse [considerazioni sulla fiducia](/docs/it/discover-plugins#security) si applicano come per qualsiasi fonte di plugin: punta questo flag solo ad archivi che controlli o di cui ti fidi.350Per testare un plugin che è già stato confezionato come archivio `.zip` e ospitato su un URL, come un artefatto di build CI, usa `--plugin-url` invece. Claude Code recupera l'archivio all'avvio e lo carica solo per quella sessione. Se Claude Code non riesce a recuperare l'archivio, o l'archivio non è valido, si avvia senza il plugin e registra un errore di caricamento del plugin che puoi rivedere nella scheda **Errors** del gestore `/plugin`. Le stesse [considerazioni sulla fiducia](/docs/it/discover-plugins#security) si applicano come per qualsiasi fonte di plugin: punta questo flag solo ad archivi che controlli o di cui ti fidi.

344 351

345Per caricare più plugin, ripeti il flag per ogni URL:352Per caricare più plugin, ripeti il flag per ogni URL:

510 Per gli sviluppatori di plugin517 Per gli sviluppatori di plugin

511</h3>518</h3>

512 519

520* [Test dei plugin con evals](/docs/it/plugin-evals): misura cosa cambia il tuo plugin e blocca CI su di esso

513* [Crea e distribuisci un marketplace](/docs/it/plugin-marketplaces): pacchetto e condividi i tuoi plugin521* [Crea e distribuisci un marketplace](/docs/it/plugin-marketplaces): pacchetto e condividi i tuoi plugin

514* [Riferimento plugin](/docs/it/plugins-reference): specifiche tecniche complete522* [Riferimento plugin](/docs/it/plugins-reference): specifiche tecniche complete

515* Approfondisci componenti specifici del plugin:523* Approfondisci componenti specifici del plugin:

plugins-reference.md +135 −67

Details

121 121

122Gli hook del plugin rispondono agli stessi eventi del ciclo di vita degli [hook definiti dall'utente](/docs/it/hooks):122Gli hook del plugin rispondono agli stessi eventi del ciclo di vita degli [hook definiti dall'utente](/docs/it/hooks):

123 123

124| Event | When it fires |124| Evento | Quando si attiva |

125| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |125| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

127| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |127| `Setup` | Quando avvii Claude Code con `--init-only`, o con `--init` o `--maintenance` in modalità `-p`. Per la preparazione una tantum in CI o script |

129| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |129| `UserPromptExpansion` | Quando un comando digitato dall'utente si espande in un prompt, prima che raggiunga Claude. Può bloccare l'espansione |

132| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |132| `PermissionDenied` | Quando la modalità automatica nega una chiamata a uno strumento, inclusi i rifiuti senza un verdetto del classificatore. Utilizza JSON `hookSpecificOutput.retry: true` per indicare al modello che può riprovare la chiamata allo strumento negata. Claude Code ignora `retry` quando il classificatore non ha prodotto alcun verdetto |

145| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |145| `InstructionsLoaded` | Quando un file CLAUDE.md o `.claude/rules/*.md` viene caricato nel contesto. Si attiva all'inizio della sessione e quando i file vengono caricati in modo pigro durante una sessione |

147| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |147| `CwdChanged` | Quando la directory di lavoro cambia, ad esempio quando Claude esegue un comando `cd`. Utile per la gestione reattiva dell'ambiente con strumenti come direnv |

148| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |148| `DirectoryAdded` | Quando una directory di lavoro viene aggiunta a metà sessione tramite `/add-dir` o la richiesta di controllo SDK `register_repo_root` |

150| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |150| `WorktreeCreate` | Quando un worktree viene creato tramite `--worktree`, `isolation: "worktree"`, o per una sessione in background. Sostituisce il comportamento git predefinito |

151| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |151| `WorktreeRemove` | Quando un worktree viene rimosso all'uscita della sessione, quando un subagente termina, o quando elimini una sessione in background |

154| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |154| `PreModelSwitch` | Prima che Claude Code applichi un cambio di modello che hai richiesto tu o un client. Può bloccare il cambio |

155| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session |155| `PostModelSwitch` | Dopo che il modello della sessione cambia, inclusi i cambiamenti che Claude Code effettua autonomamente, come il ripristino del modello quando riprendi una sessione |

159 159

160**Tipi di hook**:160**Tipi di hook**:

161 161

488 "lspServers": "./.lsp.json",488 "lspServers": "./.lsp.json",

489 "experimental": {489 "experimental": {

490 "themes": "./themes/",490 "themes": "./themes/",

491 "monitors": "./monitors.json"491 "monitors": "./monitors.json",

492 "evals": "quality/evals"

492 },493 },

493 "dependencies": [494 "dependencies": [

494 "helper-lib",495 "helper-lib",

579| `experimental.evals` | string\|array | Directory sotto la radice del plugin che contiene i [casi di eval](/docs/it/plugin-evals#use-a-different-eval-directory) del plugin, quando non è la directory predefinita `evals/`. `claude plugin eval --eval-dir` la sostituisce | `"quality/evals"` |

580| `dependencies` | array | Altri plugin richiesti da questo plugin, facoltativamente con vincoli di versione semver. Vedere [Vincolare le versioni delle dipendenze del plugin](/docs/it/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |582| `dependencies` | array | Altri plugin richiesti da questo plugin, facoltativamente con vincoli di versione semver. Vedere [Vincolare le versioni delle dipendenze del plugin](/docs/it/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

984 Riferimento dei comandi CLI986 Riferimento dei comandi CLI

985</h2>987</h2>

986 988

987Claude Code fornisce comandi CLI per la gestione non interattiva dei plugin, utili per scripting e automazione.989Claude Code fornisce comandi CLI per la gestione non interattiva dei plugin, utile per scripting e automazione.

988 990

989<h3 id="plugin-init">991<h3 id="plugin-init">

990 plugin init992 plugin init

998claude plugin init <name> [options]1000claude plugin init <name> [options]

999```1001```

1000 1002

1001**Argomenti:**1003Il comando accetta questi argomenti:

1002 1004

1003* `<name>`: Nome del plugin. Diventa lo spazio dei nomi della skill e il nome della directory sotto `~/.claude/skills/`, quindi non può contenere spazi o separatori di percorso.1005* `<name>`: Nome del plugin. Diventa lo spazio dei nomi della skill e il nome della directory sotto `~/.claude/skills/`, quindi non può contenere spazi o separatori di percorso.

1004 1006

1005**Opzioni:**1007Il comando accetta queste opzioni:

1006 1008

1008| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- |1010| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- |

1015 1017

1016**Alias:** `new`1018`claude plugin new` è un alias per questo comando.

1017 1019

1018Ogni valore `--with` aggiunge un file di avvio per quel componente, pronto per essere modificato:1020Ogni valore `--with` aggiunge un file di avvio per quel componente, pronto per essere modificato:

1019 1021

1029 1031

1030Il plugin creato con lo scaffolding utilizza la fonte `@skills-dir` piuttosto che un marketplace. Gli amministratori possono bloccare questa fonte con `strictKnownMarketplaces` o aggiungendo `{"source": "skills-dir"}` a `blockedMarketplaces` nelle [impostazioni gestite](/docs/it/plugin-marketplaces#managed-marketplace-restrictions). Quando bloccato, `plugin init` fallisce prima di scrivere.1032Il plugin creato con lo scaffolding utilizza la fonte `@skills-dir` piuttosto che un marketplace. Gli amministratori possono bloccare questa fonte con `strictKnownMarketplaces` o aggiungendo `{"source": "skills-dir"}` a `blockedMarketplaces` nelle [impostazioni gestite](/docs/it/plugin-marketplaces#managed-marketplace-restrictions). Quando bloccato, `plugin init` fallisce prima di scrivere.

1031 1033

1032**Esempi:**1034Questi esempi mostrano invocazioni comuni:

1033 1035

1034```bash theme={null}1036```bash theme={null}

1035# Crea lo scaffolding di un plugin minimo1037# Crea lo scaffolding di un plugin minimo

1052claude plugin install <plugin> [options]1054claude plugin install <plugin> [options]

1053```1055```

1054 1056

1055**Argomenti:**1057Il comando accetta questi argomenti:

1056 1058

1057* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name` per un marketplace specifico1059* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name` per un marketplace specifico

1058 1060

1059**Opzioni:**1061Il comando accetta queste opzioni:

1060 1062

1062| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |1064| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1064| `--config <key=value>` | Imposta un'opzione [`userConfig`](#user-configuration) dichiarata nel manifest del plugin. Ripeti il flag per impostare più opzioni | |1066| `--config <key=value>` | Imposta un'opzione [`userConfig`](#user-configuration) dichiarata nel manifest del plugin. Ripeti il flag per impostare più opzioni | |

1065| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |1067| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |

1068| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout invece del messaggio leggibile, per l'uso negli script. Vedi [Formato del risultato JSON](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |

1067 1070

1068L'ambito determina quale file di impostazioni il plugin installato viene aggiunto. Ad esempio, `--scope project` scrive in `enabledPlugins` in .claude/settings.json, rendendo il plugin disponibile a chiunque cloni il repository del progetto.1071L'ambito determina quale file di impostazioni il plugin installato viene aggiunto. Ad esempio, `--scope project` scrive in `enabledPlugins` in .claude/settings.json, rendendo il plugin disponibile a chiunque cloni il repository del progetto.

1069 1072

1070**Esempi:**1073<span id="plugin-json-result" />Con `--json`, l'ultima riga di stdout è un oggetto JSON. Analizza solo quella riga, perché Claude Code stampa qualsiasi comando che il marketplace dichiara prima di essa. Tre campi sono sempre presenti:

1074

1075* `command`: il sottocomando che è stato eseguito, come `install`

1076* `outcome`: `ok` o `failed`

1077* `message`: una descrizione leggibile del risultato

1078

1079Altri campi, come `pluginId`, `scope` e `failureCode`, appaiono solo quando applicabili. L'opzione `--json` su `plugin uninstall`, `plugin update`, `plugin enable` e `plugin disable` stampa lo stesso oggetto con i campi propri di quel sottocomando. Un errore di utilizzo, come uno `--scope` non valido, non stampa alcuna riga di risultato ed esce con 1 con il motivo su stderr.

1080

1081Questi esempi mostrano invocazioni comuni:

1071 1082

1072```bash theme={null}1083```bash theme={null}

1073# Installa nell'ambito utente (predefinito)1084# Installa nell'ambito utente (predefinito)

1090claude plugin uninstall <plugin> [options]1101claude plugin uninstall <plugin> [options]

1091```1102```

1092 1103

1093**Argomenti:**1104Il comando accetta questi argomenti:

1094 1105

1095* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`1106* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`

1096 1107

1097**Opzioni:**1108Il comando accetta queste opzioni:

1098 1109

1100| :-------------------- | :--------------------------------------------------------------------------------------------------------------- | :---------- |1111| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1103| `--prune` | Rimuovi anche le dipendenze auto-installate che nessun altro plugin richiede. Vedi [plugin prune](#plugin-prune) | |1114| `--prune` | Rimuovi anche le dipendenze auto-installate che nessun altro plugin richiede. Vedi [plugin prune](#plugin-prune) | |

1116| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello [stesso formato di `plugin install --json`](#plugin-json-result). Non può essere combinato con `--prune`. Richiede Claude Code v2.1.268 o successivo | |

1106 1118

1107**Alias:** `remove`, `rm`1119`claude plugin remove` e `claude plugin rm` sono alias per questo comando.

1108 1120

1109Per impostazione predefinita, la disinstallazione dall'ultimo ambito rimanente elimina anche la directory `${CLAUDE_PLUGIN_DATA}` del plugin. Usa `--keep-data` per preservarla, ad esempio quando reinstalli dopo aver testato una nuova versione.1121Per impostazione predefinita, la disinstallazione dall'ultimo ambito rimanente elimina anche la directory `${CLAUDE_PLUGIN_DATA}` del plugin. Usa `--keep-data` per preservarla, ad esempio quando reinstalli dopo aver testato una nuova versione.

1110 1122

1122claude plugin prune [options]1134claude plugin prune [options]

1123```1135```

1124 1136

1125**Opzioni:**1137Il comando accetta queste opzioni:

1126 1138

1128| :-------------------- | :--------------------------------------------------------------------------- | :---------- |1140| :-------------------- | :--------------------------------------------------------------------------- | :---------- |

1133 1145

1134**Alias:** `autoremove`1146`claude plugin autoremove` è un alias per questo comando.

1135 1147

1136Il comando elenca le dipendenze orfane e chiede conferma prima di rimuoverle. Per rimuovere un plugin e pulire le sue dipendenze in un unico passaggio, esegui `claude plugin uninstall <plugin> --prune`.1148Il comando elenca le dipendenze orfane e chiede conferma prima di rimuoverle. Per rimuovere un plugin e pulire le sue dipendenze in un unico passaggio, esegui `claude plugin uninstall <plugin> --prune`.

1137 1149

1145claude plugin enable <plugin> [options]1157claude plugin enable <plugin> [options]

1146```1158```

1147 1159

1148**Argomenti:**1160Il comando accetta questi argomenti:

1149 1161

1150* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`1162* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`

1151 1163

1152**Opzioni:**1164Il comando accetta queste opzioni:

1153 1165

1155| :-------------------- | :------------------------------------------------------------------------------------------------------------------------- | :---------- |1167| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1169| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello [stesso formato di `plugin install --json`](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |

1158 1171

1159<h3 id="plugin-disable">1172<h3 id="plugin-disable">

1166claude plugin disable [plugin] [options]1179claude plugin disable [plugin] [options]

1167```1180```

1168 1181

1169**Argomenti:**1182Il comando accetta questi argomenti:

1170 1183

1171* `[plugin]`: Nome del plugin o `plugin-name@marketplace-name`. Facoltativo quando si usa `--all`1184* `[plugin]`: Nome del plugin o `plugin-name@marketplace-name`. Facoltativo quando si usa `--all`

1172 1185

1173**Opzioni:**1186Il comando accetta queste opzioni:

1174 1187

1176| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :---------- |1189| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1178| `-s, --scope <scope>` | Ambito da disabilitare: `user`, `project` o `local`. Quando omesso, Claude Code rileva l'ambito in cui il plugin è installato | Auto-detect |1191| `-s, --scope <scope>` | Ambito da disabilitare: `user`, `project` o `local`. Quando omesso, Claude Code rileva l'ambito in cui il plugin è installato | Auto-detect |

1192| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello [stesso formato di `plugin install --json`](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |

1180 1194

1181<h3 id="plugin-update">1195<h3 id="plugin-update">

1188claude plugin update <plugin> [options]1202claude plugin update <plugin> [options]

1189```1203```

1190 1204

1191**Argomenti:**1205Il comando accetta questi argomenti:

1192 1206

1193* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`1207* `<plugin>`: Nome del plugin o `plugin-name@marketplace-name`

1194 1208

1195**Opzioni:**1209Il comando accetta queste opzioni:

1196 1210

1198| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |1212| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1200| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |1214| `-y, --yes` | Accetta un comando che il marketplace del plugin dichiara, senza il prompt di conferma: il comando che produce un plugin con una [`command` source](/docs/it/plugin-marketplaces#command-sources), o l'[`headersHelper`](/docs/it/plugin-marketplaces#authenticate-archive-downloads) che autentica un download di archivio. Accettare un `headersHelper` richiede Claude Code v2.1.238 o successivo. Claude Code stampa comunque il comando per primo. Obbligatorio quando stdin o stdout non è un TTY. Non ha effetto all'interno di una sessione di Claude Code, quindi esegui il comando dal tuo terminale | |

1215| `--json` | Stampa il risultato come un oggetto JSON sulla ultima riga di stdout, nello [stesso formato di `plugin install --json`](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo | |

1202 1217

1203<Note>1218<Note>

1216claude plugin list [options]1231claude plugin list [options]

1217```1232```

1218 1233

1219**Opzioni:**1234Il comando accetta queste opzioni:

1220 1235

1222| :------------ | :-------------------------------------------------------------- | :---------- |1237| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1223| `--json` | Output come JSON | |1238| `--json` | Output come JSON. Una riga di plugin con problemi di caricamento o avvisi di authoring porta array di stringhe `errors` o `notes`. Su Claude Code v2.1.268 o successivo, array paralleli `errorDetails` e `noteDetails` forniscono il `type` diagnostico di ogni voce e i nomi a cui si riferisce, come il plugin, il marketplace, il server o il file | |

1226 1241

1242claude plugin details <name>1257claude plugin details <name>

1243```1258```

1244 1259

1245**Argomenti:**1260Il comando accetta questi argomenti:

1246 1261

1247* `<name>`: Nome del plugin o `plugin-name@marketplace-name`1262* `<name>`: Nome del plugin o `plugin-name@marketplace-name`

1248 1263

1249**Opzioni:**1264Il comando accetta queste opzioni:

1250 1265

1252| :----------- | :--------------------------------- | :---------- |1267| :----------- | :--------------------------------- | :---------- |

1297claude plugin validate <path> [options]1312claude plugin validate <path> [options]

1298```1313```

1299 1314

1300**Argomenti:**1315Il comando accetta questi argomenti:

1301 1316

1302* `<path>`: Percorso a una directory di plugin o una directory di marketplace. Vedi [Validate a plugin or a directory without a manifest](/docs/it/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) per quali file una esecuzione di plugin copre.1317* `<path>`: Percorso a una directory di plugin o una directory di marketplace. Vedi [Validate a plugin or a directory without a manifest](/docs/it/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) per quali file una esecuzione di plugin copre.

1303 1318

1304**Opzioni:**1319Il comando accetta queste opzioni:

1305 1320

1307| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |1322| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |

1321 1336

1322All'interno di una sessione interattiva, `/plugin validate <path>` esegue gli stessi controlli inline.1337All'interno di una sessione interattiva, `/plugin validate <path>` esegue gli stessi controlli inline.

1323 1338

1339<h3 id="plugin-eval">

1340 plugin eval

1341</h3>

1342

1343Esegui i [eval cases](/docs/it/plugin-evals) di un plugin e segnala i risultati valutati. Richiede Claude Code v2.1.269 o successivo. Ogni caso è un prompt più grader; Claude Code lo esegue più volte in una sessione isolata con solo il plugin target caricato, e per impostazione predefinita anche senza il plugin in modo che il rapporto mostri la differenza. Vedi [Test plugins with evals](/docs/it/plugin-evals) per il formato del caso, i grader, i risultati e l'utilizzo in CI.

1344

1345```bash theme={null}

1346claude plugin eval [target] [options]

1347```

1348

1349Il `target` facoltativo è una directory di plugin, un singolo file `prompt.md` o `case.yaml`, un plugin installato come `name` o `name@marketplace`, o `name@skills-dir`, e predefinito è la directory corrente. Mettilo prima di `--tag`, `--allow-tools` e `--json`.

1350

1351Questa tabella elenca le opzioni che la maggior parte delle esecuzioni utilizza. Esegui `claude plugin eval --help` per l'insieme completo, inclusi `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp` e `--verbose`.

1352

1353| Opzione | Descrizione | Predefinito |

1354| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |

1355| `--runs <n>` | Esecuzioni per caso per braccio | Ogni `runs` del caso, altrimenti 3 |

1356| `-j, --concurrency <n>` | Sessioni di agent da eseguire contemporaneamente, da 1 a 8. Condividono il tuo limite di velocità | `1` |

1357| `--model <model>` | Modello per l'agent in test | Ogni `model` del caso, altrimenti `ANTHROPIC_MODEL` se impostato, altrimenti il predefinito di Claude Code |

1358| `--judge-model <model>` | Modello per i grader `llm` e `baseline` | Un modello piccolo e veloce |

1359| `--ablation <mode>` | `none` o `with-without`. Vedi [Compare against a no-plugin baseline](/docs/it/plugin-evals#compare-against-a-no-plugin-baseline) | `with-without` quando un plugin si risolve, altrimenti `none` |

1360| `--threshold <0..1>` | Esci con 1 se un caso qualsiasi punteggia al di sotto di questo | `1.0` |

1361| `--max-cost-usd <usd>` | Interrompi prima della prossima esecuzione una volta che la spesa raggiunge questo, esci con 2 e segnala risultati parziali | Nessun limite |

1362| `--allow-tools <tools...>` | Concedi strumenti oltre l'insieme di sola lettura, come `Bash`, `Write`, `Edit` o `"mcp__plugin_<plugin>_<server>__*"`. Vedi [Grant tools](/docs/it/plugin-evals#grant-tools) | |

1363| `--scaffold` | Esegui lo [`scaffold_script`](/docs/it/plugin-evals#add-setup-or-history-with-case-yaml) di ogni caso | Off |

1364| `--trust-plugin` | Salta il prompt di fiducia della prima esecuzione, per CI. Vedi [What a run can access](/docs/it/plugin-evals#security) | Off |

1365| `--mocks <mode>` | `record` o `off`. Vedi [Mock MCP servers](/docs/it/plugin-evals#mock-mcp-servers) | `record` |

1366| `--eval-dir <dir>` | Directory sotto il plugin che contiene i casi | Il `experimental.evals` del manifest, altrimenti `evals` |

1367| `--json [path]` | Stampa il [result document](/docs/it/plugin-evals#json-result) su stdout, o scrivilo in un percorso `.json` | |

1368| `--no-publish` | Mantieni il rapporto HTML locale | |

1369| `-h, --help` | Visualizza la guida per il comando | |

1370

1371Il comando esce con 0 quando ogni caso soddisfa la soglia, 1 su un caso fallito, un errore di caricamento o una directory di plugin non attendibile, 2 su un'esecuzione parziale, 130 quando interrotto e 143 quando terminato. Vedi [Run evals in CI](/docs/it/plugin-evals#run-evals-in-ci).

1372

1373<h3 id="plugin-eval-init">

1374 plugin eval init

1375</h3>

1376

1377Crea una suite di eval per il plugin nella directory corrente. Richiede Claude Code v2.1.269 o successivo. In un terminale questo avvia un'intervista di authoring che legge il plugin, propone casi e grader, li pilota e scrive i file. Con `--bare`, o senza un terminale, scrive invece un modello di singolo caso vuoto. Esegui da dentro una sessione interattiva di Claude Code, stampa le istruzioni dell'intervista per quella sessione da seguire piuttosto che scrivere un modello. Vedi [Create your first eval suite](/docs/it/plugin-evals#create-your-first-eval-suite).

1378

1379```bash theme={null}

1380claude plugin eval init [name] [options]

1381```

1382

1383Il `name` facoltativo è un nome di caso: l'intervista non ne ha bisogno, mentre `--bare` e il percorso del modello senza terminale lo richiedono. Accetta queste opzioni:

1384

1385| Opzione | Descrizione | Predefinito |

1386| :------------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------- |

1387| `--bare` | Scrivi un `prompt.md` vuoto e `graders/criteria.md` per `<name>` invece di eseguire l'intervista | |

1388| `-i, --interactive` | Richiedi l'intervista. Fallisce senza un terminale invece di scrivere un modello | |

1389| `--eval-dir <dir>` | Directory sotto la directory corrente in cui scrivere i casi | Il `experimental.evals` del manifest, altrimenti `evals` |

1390| `-h, --help` | Visualizza la guida per il comando | |

1391

1324<h3 id="plugin-tag">1392<h3 id="plugin-tag">

1325 plugin tag1393 plugin tag

1326</h3>1394</h3>

1331claude plugin tag [path] [options]1399claude plugin tag [path] [options]

1332```1400```

1333 1401

1334**Argomenti:**1402Il comando accetta questi argomenti:

1335 1403

1336* `[path]`: Percorso alla directory del plugin. Predefinito è la directory corrente.1404* `[path]`: Percorso alla directory del plugin. Predefinito è la directory corrente.

1337 1405

1338**Opzioni:**1406Il comando accetta queste opzioni:

1339 1407

1341| :-------------------- | :------------------------------------------------------------------------- | :---------- |1409| :-------------------- | :------------------------------------------------------------------------- | :---------- |

prompt-caching.md +122 −112

Details

14 Come è organizzata la cache14 Come è organizzata la cache

15</h2>15</h2>

16 16

17Ogni volta che invii un messaggio in Claude Code, effettua una nuova richiesta API. Il modello non ricorda nulla tra le richieste, quindi Claude Code rinvia il contesto completo: il prompt di sistema, il contesto del tuo progetto, ogni messaggio precedente e risultato dello strumento, e il tuo nuovo messaggio. Il nuovo contenuto viene aggiunto alla fine, il che significa che la maggior parte di ogni richiesta è identica a quella precedente. Il prompt caching è il modo in cui l'API evita di rielaborare la parte che non è cambiata.17Ogni volta che inviate un messaggio in Claude Code, viene effettuata una nuova richiesta API. Il modello non ricorda nulla tra le richieste, quindi Claude Code invia di nuovo il contesto completo: il prompt di sistema, il contesto del vostro progetto, ogni messaggio precedente e risultato dello strumento, e il vostro nuovo messaggio. I nuovi contenuti vengono aggiunti alla fine, il che significa che la maggior parte di ogni richiesta è identica a quella precedente. Il prompt caching è il modo in cui l'API evita di rielaborare la parte che non è cambiata.

18 18

19L'API memorizza nella cache abbinando l'inizio di ogni richiesta, chiamato prefisso, al contenuto che ha elaborato di recente. Su un turno normale, il prefisso è l'intera richiesta precedente e solo lo scambio più recente è nuovo. La corrispondenza è esatta, quindi una modifica in qualsiasi punto del prefisso ricalcola tutto ciò che viene dopo. Non esiste caching per file o per segmento. Vedi [come funziona il prompt caching](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#how-prompt-caching-works) nel riferimento API per il meccanismo sottostante.19L'API memorizza nella cache confrontando l'inizio di ogni richiesta, chiamato prefisso, con il contenuto che ha elaborato di recente. In un turno normale, il prefisso è l'intera richiesta precedente e solo lo scambio più recente è nuovo. La corrispondenza è esatta, quindi una modifica in qualsiasi punto del prefisso ricalcola tutto ciò che viene dopo. Non esiste una cache per file o per segmento. Consultate [come funziona il prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works) nel riferimento API per il meccanismo sottostante.

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/_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" />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 dalla corrispondenza del prefisso, Claude Code ordina ogni richiesta in modo che il contenuto che cambia raramente tra i turni venga per primo:

26 26

28| --------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |28| --------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |

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.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 si trova ora dietro un prefisso diverso. La terza colonna fornisce trigger comuni piuttosto che un elenco esaustivo, e le sezioni seguenti coprono l'insieme completo.

34 34

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.35La regola di corrispondenza del prefisso spiega la maggior parte dei comportamenti su 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 compaiono nella tabella dei layer ma comunque influenzano ciò che rimane memorizzato nella cache:~~37Due impostazioni non compaiono nella tabella dei layer ma influiscono comunque su ciò che rimane memorizzato nella cache:

38 38

~~39* **Model**: ogni modello ha la sua cache. Cambiare modelli ricalcola l'intera richiesta anche quando il contenuto è identico. Vedi [Switching models](#switching-models) di seguito.~~39* **Model**: ogni modello ha la propria cache. Cambiare modello ricalcola l'intera richiesta anche quando il contenuto è identico. Consultate [Switching models](#switching-models) di seguito.

40* **Effort level**: sulla maggior parte dei modelli, ogni livello di sforzo ha la sua cache, quindi cambiare lo sforzo a metà sessione ricalcola l'intera richiesta. Su Fable 5.1 con una chiave API o un abbonamento Claude, la cache rimane intatta per impostazione predefinita. Vedi [Changing effort level](#changing-effort-level) di seguito.40* **Effort level**: sulla maggior parte dei modelli, ogni livello di sforzo ha la propria cache, quindi cambiare lo sforzo a metà sessione ricalcola l'intera richiesta. Su Fable 5.1 con una chiave API o un abbonamento Claude, la cache rimane intatta per impostazione predefinita. Consultate [Changing effort level](#changing-effort-level) di seguito.

41 41

42<Tip>42<Tip>

43 Scegli il tuo modello e il livello di sforzo all'inizio di una sessione, quindi salva `/compact` per le pause naturali tra i compiti. Meno modifiche fai a metà compito, più alto sarà il tuo tasso di cache hit.43 Scegliete il vostro modello e il livello di sforzo all'inizio di una sessione, quindi riservate `/compact` per le pause naturali tra i compiti. Meno modifiche apportate a metà compito, più alto sarà il vostro tasso di cache hit.

44</Tip>44</Tip>

45 45

46<h3 id="where-the-cache-lives">46<h3 id="where-the-cache-lives">

47 Dove vive la cache47 Dove vive la cache

48</h3>48</h3>

49 49

~~50Il caching avviene lato server, nell'infrastruttura che serve il tuo modello. Dove si trova dipende da come ti autentichi:~~50La memorizzazione nella cache avviene lato server, nell'infrastruttura che serve il vostro modello. Dove si trova dipende da come vi autenticate:

51 51

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)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 cloud~~53* **Amazon Bedrock o Google Cloud's Agent Platform**: la cache vive nell'infrastruttura di servizio del vostro provider cloud

54* **Microsoft Foundry**: dipende dall'[opzione di hosting](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry#hosting-options) della distribuzione. Le distribuzioni ospitate su Azure vengono servite sull'infrastruttura Azure; le distribuzioni ospitate su Anthropic vengono servite sull'infrastruttura di Anthropic54* **Microsoft Foundry**: dipende dall'[hosting option](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) della distribuzione. Le distribuzioni ospitate su Azure vengono servite sull'infrastruttura Azure; le distribuzioni ospitate su Anthropic vengono servite sull'infrastruttura di Anthropic

~~55* **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~~55* **Custom `ANTHROPIC_BASE_URL` o [LLM gateway](/docs/it/llm-gateway)**: la cache vive ovunque le vostre richieste vengono inoltrate, e se il caching funziona dipende dal gateway

56 56

~~57Claude Code inoltre aggiunge il contesto di sistema a metà conversazione, come notifiche di cambio file, e contrassegna quel blocco per il caching su ogni provider e connessione.~~57Claude Code aggiunge anche il contesto di sistema a metà conversazione, come notifiche di cambio file, e contrassegna quel blocco per la memorizzazione nella cache su ogni provider e connessione a meno che non impostiate [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/it/llm-gateway-protocol#disable-pre-release-capabilities), nel qual caso quel blocco viene inviato senza cache.

58 58

59All'endpoint proprio del provider, Amazon Bedrock e il suo [endpoint Mantle](/docs/it/amazon-bedrock#use-the-mantle-endpoint), Google Cloud's Agent Platform, e Microsoft Foundry memorizzano nella cache il blocco nello stesso modo in cui lo fa Claude API.59All'endpoint proprio del provider, Amazon Bedrock e il suo [Mantle endpoint](/docs/it/amazon-bedrock#use-the-mantle-endpoint), Google Cloud's Agent Platform, e Microsoft Foundry memorizzano nella cache il blocco nello stesso modo in cui lo fa Claude API.

60 60

61Quando le tue richieste passano attraverso un [LLM gateway](/docs/it/llm-gateway), un `ANTHROPIC_BASE_URL` personalizzato, o un override di URL di base del provider cloud come [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/it/env-vars), ciò che rimane memorizzato nella cache dipende da come il gateway gestisce i [marcatori `cache_control`](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints) che Claude Code invia:61Quando le vostre richieste passano attraverso un [LLM gateway](/docs/it/llm-gateway), un `ANTHROPIC_BASE_URL` personalizzato, o un override di URL di base del provider cloud come [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/it/env-vars), ciò che rimane memorizzato nella cache dipende da come il gateway gestisce i [marcatori `cache_control`](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) che Claude Code invia:

62 62

~~63* **Li inoltra invariati**: il blocco e la tua conversazione vengono memorizzati nella cache nello stesso modo dell'endpoint proprio del provider.~~63* **Li inoltra invariati**: il blocco e la vostra conversazione vengono memorizzati nella cache nello stesso modo dell'endpoint proprio del provider.

64* **Rifiuta la richiesta contrassegnata con un errore `400` che nomina `cache_control`**: Claude Code rinvia la richiesta con il marcatore spostato dal blocco al tuo ultimo messaggio di conversazione, e lo mantiene lì per il resto della conversazione. Il blocco viene fatturato come input non memorizzato nella cache; la tua conversazione rimane memorizzata nella cache.64* **Rifiuta la richiesta contrassegnata con un errore `400` che nomina `cache_control`**: Claude Code invia di nuovo la richiesta con il marcatore spostato dal blocco al vostro ultimo messaggio di conversazione, e lo mantiene lì per il resto della conversazione. Il blocco viene fatturato come input non memorizzato nella cache; la vostra conversazione rimane memorizzata nella cache.

65* **Rimuove i marcatori mentre restituisce successo**: l'intera cronologia della conversazione viene fatturata come input non memorizzato nella cache ad ogni turno. Un gateway che converte il contenuto del sistema in forma di blocco in una stringa semplice rilascia il marcatore nello stesso modo.65* **Rimuove i marcatori mentre restituisce il successo**: l'intera cronologia della conversazione viene fatturata come input non memorizzato nella cache ad ogni turno. Un gateway che converte il contenuto del sistema in forma di blocco in una stringa semplice rilascia il marcatore nello stesso modo.

66 66

67Per 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.67Per ciò che ogni provider memorizza ed elabora, consultate [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.

68 68

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

70 Azioni che invalidano la cache70 Azioni che invalidano la cache

71</h2>71</h2>

72 72

73Queste azioni causano la mancanza di parte o tutta la cache nella richiesta successiva. Vedi un turno più lento e più costoso una sola volta, dopo il quale il nuovo prefisso viene memorizzato nella cache. La maggior parte di essi sono evitabili a metà compito una volta che sai che hanno un costo. Un cambio di modello può sembrare gratuito finché non noti il turno più lento che segue.73Queste azioni causano la mancanza della cache nella richiesta successiva, in parte o completamente. Vedrai un turno più lento e più costoso una sola volta, dopo il quale il nuovo prefisso viene memorizzato nella cache. La maggior parte di esse è evitabile durante un'attività una volta che conosci il loro costo. Un cambio di modello può sembrare gratuito finché non noti il turno più lento che segue.

74 74

~~75* [Switching models](#switching-models)~~75* [Cambio di modelli](#switching-models)

~~76* [Changing effort level](#changing-effort-level)~~76* [Modifica del livello di sforzo](#changing-effort-level)

~~77* [Turning on fast mode](#turning-on-fast-mode)~~77* [Attivazione della modalità veloce](#turning-on-fast-mode)

~~78* [Connecting or disconnecting an MCP server](#connecting-or-disconnecting-an-mcp-server)~~78* [Connessione o disconnessione di un server MCP](#connecting-or-disconnecting-an-mcp-server)

~~79* [Enabling or disabling a plugin](#enabling-or-disabling-a-plugin)~~79* [Abilitazione o disabilitazione di un plugin](#enabling-or-disabling-a-plugin)

~~80* [Denying an entire tool](#denying-an-entire-tool)~~80* [Negazione di uno strumento completo](#denying-an-entire-tool)

~~81* [Changing output style](#changing-output-style)~~81* [Compattazione della conversazione](#compacting-the-conversation)

~~82* [Compacting the conversation](#compacting-the-conversation)~~82* [Accumulo di molte immagini](#accumulating-many-images)

~~83* [Accumulating many images](#accumulating-many-images)~~83* [Aggiornamento di Claude Code](#upgrading-claude-code)

~~84* [Upgrading Claude Code](#upgrading-claude-code)~~

85 84

86<h3 id="switching-models">85<h3 id="switching-models">

~~87 Switching models~~86 Cambio di modelli

88</h3>87</h3>

89 88

90Ogni 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.89Ogni modello ha la propria cache. Passare 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.

91 90

92Quando esegui `/model` al terminale, Claude Code ti chiede di confermare il cambio solo mentre la cache è ancora calda. La cache rimane calda per un [cache TTL](#cache-lifetime) dopo che Claude Code ha inviato l'ultima richiesta in questa conversazione o Claude ha risposto. Una volta che quel tempo passa, la cache è scaduta, quindi Claude Code cambia senza chiedere.91Quando esegui `/model` nel terminale, Claude Code ti chiede di confermare il cambio solo mentre la cache è ancora calda. La cache rimane calda per un [cache TTL](#cache-lifetime) dopo che Claude Code ha inviato l'ultima richiesta in questa conversazione o dopo che Claude ha risposto. Una volta trascorso quel tempo, la cache è scaduta, quindi Claude Code passa senza chiedere.

93 92

94Prima della v2.1.238, Claude Code non controllava il cache TTL e chiedeva anche dopo che la cache era scaduta.93Prima della v2.1.238, Claude Code non controllava il cache TTL e chiedeva anche dopo che la cache era scaduta.

95 94

96Puoi anche richiedere questa conferma o saltarla con un [hook PreModelSwitch](/docs/it/hooks#premodelswitch-decision-control).95Puoi anche richiedere questa conferma o saltarla con un [hook PreModelSwitch](/docs/it/hooks#premodelswitch-decision-control).

97 96

98L'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.97L'[impostazione del modello `opusplan`](/docs/it/model-config#opusplan-model-setting) si risolve in Opus durante la modalità piano e Sonnet durante l'esecuzione, quindi ogni attivazione/disattivazione della modalità piano è un cambio di modello e avvia una cache nuova.

99 98

100Il [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) su modelli Fable e Opus 5 è anche un cambio di modello. Quando un classificatore di sicurezza contrassegna una richiesta in una categoria che ha un modello di fallback, Claude Code riesegue la richiesta su quel modello e la sessione continua lì.99[Il fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) sui modelli Fable e Opus 5 è anche un cambio di modello. Quando un classificatore di sicurezza contrassegna una richiesta in una categoria che ha un modello di fallback, Claude Code riesegue la richiesta su quel modello e la sessione continua lì.

101 100

102Quando una skill o il frontmatter di un comando nomina un [`model`](/docs/it/skills#frontmatter-reference) diverso dal modello corrente della sessione, quel turno è anche un cambio di modello: la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Il modello della sessione riprende al tuo prossimo prompt. Una skill `context: fork` imposta il [modello del subagent con fork](/docs/it/skills#run-skills-in-a-subagent) invece.101Quando il frontmatter di una skill o di un comando nomina un [`model`](/docs/it/skills#frontmatter-reference) diverso dal modello corrente della sessione, quel turno è anche un cambio di modello: la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Il modello della sessione riprende al tuo prossimo prompt. Una skill `context: fork` imposta il [modello del subagent con fork](/docs/it/skills#run-skills-in-a-subagent) invece.

103 102

104<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

105 Changing effort level104 Modifica del livello di sforzo

106</h3>105</h3>

107 106

108Sulla maggior parte dei modelli, cambiare il [livello di effort](/docs/it/model-config#adjust-effort-level) a metà sessione significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Mentre la cache è ancora calda, Claude Code ti chiede di confermare il cambio per primo.107Sulla maggior parte dei modelli, modificare il [livello di sforzo](/docs/it/model-config#adjust-effort-level) a metà sessione significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Mentre la cache è ancora calda, Claude Code ti chiede di confermare il cambio prima.

109 108

110Su Fable 5.1 con una chiave API o un abbonamento Claude, cambiare effort mantiene la cache, e Claude Code applica il nuovo livello senza chiedere. Questo non si applica su Amazon Bedrock, su Google Cloud's Agent Platform, o su un [gateway di app Claude](/docs/it/claude-apps-gateway), o quando imposti [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/it/llm-gateway-protocol#disable-pre-release-capabilities) o la tua organizzazione ha una configurazione HIPAA.109Su Fable 5.1 con una chiave API o un abbonamento Claude, modificare lo sforzo mantiene la cache, e Claude Code applica il nuovo livello senza chiedere. Questo non si applica su Amazon Bedrock, su Google Cloud's Agent Platform, o su un [gateway di app Claude](/docs/it/claude-apps-gateway), o quando imposti [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/it/llm-gateway-protocol#disable-pre-release-capabilities) o la tua organizzazione ha una configurazione HIPAA.

111 110

112Prima della v2.1.260, cambiare effort su Fable 5.1 con una chiave API o un abbonamento Claude invalidava anche la cache.111Prima della v2.1.260, modificare lo sforzo su Fable 5.1 con una chiave API o un abbonamento Claude invalidava anche la cache.

113 112

114<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

115 Turning on fast mode114 Attivazione della modalità veloce

116</h3>115</h3>

117 116

118L'abilitazione della [fast mode](/docs/it/fast-mode) aggiunge un'intestazione di richiesta che fa parte della chiave della cache, quindi la prima richiesta che Claude Code invia con la fast mode attiva legge l'intera cronologia della conversazione senza cache hit. Claude Code imposta quell'intestazione una volta quando un turno inizia e la mantiene per l'intero turno, quindi quando attivi la fast mode mentre Claude sta lavorando, la cache miss dall'intestazione accade sulla prima richiesta del tuo turno successivo. 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. Se il tuo modello corrente non supporta la fast mode, l'abilitazione della fast mode [cambia anche il tuo modello](#switching-models), e quel cambio avvia una cache fresca di per sé dalla richiesta successiva nel turno in esecuzione.117L'abilitazione della [modalità veloce](/docs/it/fast-mode) aggiunge un'intestazione di richiesta che fa parte della chiave di cache, quindi la prima richiesta che Claude Code invia con la modalità veloce attiva legge l'intera cronologia della conversazione senza cache hit. Claude Code imposta quell'intestazione una volta quando inizia un turno e la mantiene per l'intero turno, quindi quando attivi la modalità veloce mentre Claude sta lavorando, il cache miss dall'intestazione si verifica sulla prima richiesta del tuo turno successivo. Quei token di input non memorizzati nella cache vengono fatturati alle [tariffe della modalità veloce](/docs/it/fast-mode#understand-the-cost-tradeoff), motivo per cui attivare la modalità veloce all'inizio di una sessione costa meno che attivarla in profondità in una sessione lunga. Se il tuo modello attuale non supporta la modalità veloce, l'abilitazione della modalità veloce [cambia anche il tuo modello](#switching-models), e quel cambio avvia una cache nuova dalla richiesta successiva nel turno in esecuzione.

119 118

120Il 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. Se [esaurisci i crediti di utilizzo](/docs/it/fast-mode#handle-rate-limits) a metà sessione, Claude Code ritenta ogni richiesta fast mode rifiutata alla velocità standard allo stesso modo, quindi questo fallback mantiene anche la cache. `/clear` e `/compact` ripristinano questo, poiché ricostruiscono la cache in quei punti comunque.119Il costo si applica una volta per conversazione. Dopo il primo turno in modalità veloce, Claude Code continua a inviare l'intestazione e varia solo l'impostazione di velocità della richiesta, che non fa parte della chiave di cache. Disattivare la modalità veloce, 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. Se [esaurisci i crediti di utilizzo](/docs/it/fast-mode#handle-rate-limits) a metà sessione, Claude Code ritenta ogni richiesta in modalità veloce rifiutata alla velocità standard nello stesso modo, quindi questo fallback mantiene anche la cache. `/clear` e `/compact` ripristinano questo, poiché ricostruiscono la cache in quei punti comunque.

121 120

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

123 Connecting or disconnecting an MCP server122 Connessione o disconnessione di un server MCP

124</h3>123</h3>

125 124

126Le 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:125Le definizioni degli strumenti si trovano nel livello del prompt di sistema, quindi la cache si invalida quando l'insieme delle definizioni degli strumenti nella richiesta cambia tra i turni. Attivare/disattivare 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 [server MCP](/docs/it/mcp) fa questo dipende dal fatto che i suoi strumenti siano differiti dalla [ricerca degli strumenti](/docs/it/mcp#scale-with-mcp-tool-search) o caricati nel prefisso:

127 126

128* **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.127* **Strumenti differiti**, l'impostazione predefinita sui modelli supportati: un server che si connette, si disconnette, o cambia il suo elenco di strumenti aggiunge solo nuovo contenuto e non disturba nulla già memorizzato nella cache.

129* **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 modelli di Google Cloud's Agent Platform precedenti alla generazione Claude 4.5, con un gateway `ANTHROPIC_BASE_URL` personalizzato, o su una [distribuzione di Microsoft Foundry ospitata su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) una volta che Claude Code rileva che la distribuzione rifiuta la tool search. 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).128* **Strumenti caricati nel prefisso**: qualsiasi modifica a essi invalida la cache. Questo accade quando la [ricerca degli strumenti non è disponibile o è disabilitata](/docs/it/mcp#configure-tool-search), ad esempio sui modelli di Google Cloud's Agent Platform precedenti alla generazione Claude 4.5, con un gateway `ANTHROPIC_BASE_URL` personalizzato, o su una distribuzione Microsoft Foundry [ospitata su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) una volta che Claude Code rileva che la distribuzione rifiuta la ricerca degli strumenti. 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).

130 129

131Quando 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.130Quando gli strumenti si caricano nel prefisso, la causa più comune di un'invalidazione è un server che si connette o si 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 [aggiornamento dinamico dello strumento](/docs/it/mcp#dynamic-tool-updates) che cambia il suo elenco di strumenti.

132 131

133Modificare 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.132Modificare la tua configurazione MCP non cambia di per sé la cache. La nuova configurazione ha effetto solo dopo un riavvio, che è quando il server si connette o si disconnette.

134 133

135<h3 id="enabling-or-disabling-a-plugin">134<h3 id="enabling-or-disabling-a-plugin">

136 Enabling or disabling a plugin135 Abilitazione o disabilitazione di un plugin

137</h3>136</h3>

138 137

139Quando abiliti o disabiliti un [plugin](/docs/it/plugins), il costo del cambio dipende da quali tipi di componenti il plugin fornisce. I casi seguenti coprono ogni tipo di componente, quando Claude Code applica il cambio, e cosa accade quando disabiliti un plugin di nuovo nella stessa sessione.138Quando abiliti o disabiliti un [plugin](/docs/it/plugins), il costo del cambio dipende da quali tipi di componenti fornisce il plugin. I casi seguenti coprono ogni tipo di componente, quando Claude Code applica il cambio, e cosa accade quando disabiliti di nuovo un plugin nella stessa sessione.

140 139

141<h4 id="plugin-components-that-keep-the-cache">140<h4 id="plugin-components-that-keep-the-cache">

142 Plugin components that keep the cache141 Componenti del plugin che mantengono la cache

143</h4>142</h4>

144 143

145Claude Code non invalida mai la cache per le skill, i comandi, gli agenti, gli hook, i monitor o i temi di un plugin. Aggiunge il loro contenuto dopo la conversazione esistente, quindi la richiesta successiva paga per quel contenuto e legge comunque tutto ciò che lo precede dalla cache.144Claude Code non invalida mai la cache per le skill, i comandi, gli agenti, gli hook, i monitor o i temi di un plugin. Aggiunge il loro contenuto dopo la conversazione esistente, quindi la richiesta successiva paga per quel contenuto e legge comunque tutto ciò che lo precede dalla cache.

146 145

147<h4 id="plugins-that-provide-mcp-servers">146<h4 id="plugins-that-provide-mcp-servers">

148 Plugins that provide MCP servers147 Plugin che forniscono server MCP

149</h4>148</h4>

150 149

151Quando abiliti o disabiliti un plugin che fornisce [MCP server](/docs/it/plugins-reference#mcp-servers), Claude Code segue le stesse regole di quando [connetti o disconnetti un MCP server](#connecting-or-disconnecting-an-mcp-server):150Quando abiliti o disabiliti un plugin che fornisce [server MCP](/docs/it/plugins-reference#mcp-servers), Claude Code segue le stesse regole di quando [connetti o disconnetti un server MCP](#connecting-or-disconnecting-an-mcp-server):

152 151

153* Se Claude Code rimanda gli strumenti del server, mantiene la cache.152* Se Claude Code differisce gli strumenti del server, mantiene la cache.

154* Se Claude Code li carica nel prefisso, la richiesta successiva rilegge l'intera conversazione.153* Se Claude Code li carica nel prefisso, la richiesta successiva rilegge l'intera conversazione.

155 154

156<h4 id="code-intelligence-plugins">155<h4 id="code-intelligence-plugins">

157 Code intelligence plugins156 Plugin di intelligenza del codice

158</h4>157</h4>

159 158

160Quando abiliti un [plugin di code intelligence](/docs/it/discover-plugins#code-intelligence), Claude ottiene lo [strumento LSP](/docs/it/tools-reference#lsp-tool-behavior).159Quando abiliti un [plugin di intelligenza del codice](/docs/it/discover-plugins#code-intelligence), Claude ottiene lo [strumento LSP](/docs/it/tools-reference#lsp-tool-behavior).

161 160

162<h4 id="when-plugin-changes-apply">161<h4 id="when-plugin-changes-apply">

163 When plugin changes apply162 Quando i cambiamenti del plugin si applicano

164</h4>163</h4>

165 164

166Claude Code applica un cambio di plugin quando esegui [`/reload-plugins`](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) o avvii una nuova sessione. Paghi il costo, sia annunci aggiunti che una rilettura completa, al primo turno dopo che il cambio si applica, non quando esegui `/plugin enable` o `/plugin disable`. Claude Code può anche applicare un cambio di per sé in tre casi:165Un cambio che fai nel menu `/plugin` passa attraverso [`/reload-plugins`](/docs/it/discover-plugins#apply-plugin-changes-without-restarting), che Claude Code esegue per te quando chiudi il menu. Paghi il costo, sia annunci aggiunti che una rilettura completa, al primo turno dopo che il cambio si applica. Claude Code può anche applicare un cambio da solo:

167 166

168* Per un plugin con una sorgente `command`, Claude Code [può ricaricare il plugin stesso](/docs/it/plugin-marketplaces#when-claude-code-re-runs-the-command).167* Per un plugin con una fonte `command`, Claude Code [può ricaricare il plugin stesso](/docs/it/plugin-marketplaces#when-claude-code-re-runs-the-command).

169* Quando [installi un plugin dall'interfaccia `/plugin`](/docs/it/discover-plugins#install-plugins), Claude Code può attivarlo durante l'installazione. Claude Code ti dice nel riepilogo dell'installazione se l'ha fatto o se eseguire `/reload-plugins`.168* Quando [installi un plugin dall'interfaccia `/plugin`](/docs/it/discover-plugins#install-plugins), Claude Code può attivarlo durante l'installazione. Il riepilogo dell'installazione ti dice se l'ha fatto.

170* Quando [sposti la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory) su v2.1.246 o successivo, Claude Code applica i plugin che le impostazioni della nuova directory abilitano come parte dello spostamento, senza l'avviso di rilettura completa che trattiene un `/reload-plugins`.169* Quando [sposti la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory) su v2.1.246 o successiva, Claude Code applica i plugin che le impostazioni della nuova directory abilitano come parte dello spostamento, senza l'avviso di rilettura completa che tiene un `/reload-plugins`.

170* Nelle sessioni interattive, quando aggiungi o rimuovi un plugin in una [cartella di plugin](/docs/it/plugins#test-your-plugins-locally) che hai passato con `--plugin-dir`, il cambio si applica subito. Se applicarlo attiverebbe una rilettura completa, Claude Code trattiene il cambio e mostra un avviso per eseguire `/reload-plugins`. Richiede Claude Code v2.1.265 o successiva.

171 171

172Quando esegui `/reload-plugins` e il ricaricamento attiverebbe una rilettura completa, Claude Code mostra un avviso e non applica il ricaricamento. Rieseguilo con `--force` per applicare il ricaricamento comunque.172Quando `/reload-plugins` viene eseguito e il ricaricamento attiverebbe una rilettura completa, Claude Code mostra un avviso e non applica il ricaricamento. Esegui `/reload-plugins --force` per applicarlo comunque.

173 173

174`/reload-plugins` viene eseguito anche in sessioni senza un terminale interattivo, come l'app desktop, l'Agent SDK, e [modalità non interattiva](/docs/it/headless) con `-p`, quando lo digiti direttamente nella sessione. Richiede Claude Code v2.1.260 o successivo.174`/reload-plugins` viene eseguito anche in sessioni senza un terminale interattivo, come l'app desktop, l'Agent SDK, e la [modalità non interattiva](/docs/it/headless) con `-p`, quando lo digiti direttamente nella sessione. Richiede Claude Code v2.1.260 o successiva.

175 175

176In quelle sessioni il ricaricamento applica tutto tranne i cambiamenti dei server MCP del plugin, che [hanno effetto nella tua sessione successiva](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) e quindi non costano mai una rilettura completa a metà sessione.176In quelle sessioni il ricaricamento applica tutto tranne i cambiamenti del server MCP del plugin, che [hanno effetto nella tua sessione successiva](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) e quindi non costano mai una rilettura completa a metà sessione.

177 177

178<h4 id="plugins-you-enable-and-then-disable-in-one-session">178<h4 id="plugins-you-enable-and-then-disable-in-one-session">

179 Plugins you enable and then disable in one session179 Plugin che abiliti e poi disabiliti in una sessione

180</h4>180</h4>

181 181

182Quando disabiliti un plugin che hai abilitato in precedenza nella sessione, Claude Code 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.182Quando disabiliti un plugin che hai abilitato in precedenza nella sessione, Claude Code 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 ricostruire.

183 183

184<h3 id="denying-an-entire-tool">184<h3 id="denying-an-entire-tool">

185 Denying an entire tool185 Negazione di uno strumento completo

186</h3>186</h3>

187 187

188Aggiungere 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. Claude Code carica le definizioni degli strumenti incorporati nel layer del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache. Claude Code applica il cambio alla richiesta successiva, sia che tu aggiunga la regola tramite `/permissions` o [modificando direttamente un file di impostazioni](/docs/it/settings#when-edits-take-effect). Questo include una regola che aggiungi tramite `/permissions` nel mezzo di un turno.188L'aggiunta di un nome di strumento semplice come `Bash` o `WebFetch` come [regola di negazione](/docs/it/permissions#manage-permissions) rimuove completamente quello strumento dal contesto di Claude. Claude Code carica le definizioni degli strumenti incorporati nel livello del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache. Claude Code applica il cambio alla richiesta successiva, sia che tu aggiunga la regola tramite `/permissions` o [modificando direttamente un file di impostazioni](/docs/it/settings#when-edits-take-effect). Questo include una regola che aggiungi tramite `/permissions` nel mezzo di un turno.

189 189

190Solo 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.190Solo una regola di negazione che corrisponde nella posizione del nome dello strumento ha questo effetto: un nome di strumento semplice, la forma equivalente `Bash(*)`, o un [glob del nome dello strumento](/docs/it/permissions#tool-name-wildcards) come `"*"`. Un glob che corrisponde solo agli strumenti MCP, come `"mcp__*"`, rimuove quegli strumenti nello stesso modo ma lascia la cache intatta quando gli strumenti corrispondenti sono [differiti](#connecting-or-disconnecting-an-mcp-server), l'impostazione predefinita, poiché le definizioni differite non erano mai nel prefisso memorizzato nella cache. Le regole di negazione 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.

~~191~~

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

193 Changing output style

194</h3>

~~195~~

196Lo [stile di output](/docs/it/output-styles) fa parte del prompt di sistema. Quando cambi stili a metà sessione con `/config` o l'impostazione `outputStyle`, Claude usa il nuovo stile a partire dal tuo prossimo messaggio, e quella richiesta legge l'intera cronologia della conversazione senza cache hit. Per mantenere quel costo piccolo, cambia stili prima del tuo primo messaggio in una sessione o subito dopo `/clear` o `/compact`, quando c'è poca o nessuna cronologia della conversazione da rileggere.

~~197~~

198Prima della v2.1.251, un cambio di stile a metà sessione manteneva la cache ma non si applicava finché non eseguivi `/clear` o non avviavi una nuova sessione.

199 191

200<h3 id="compacting-the-conversation">192<h3 id="compacting-the-conversation">

201 Compacting the conversation193 Compattazione della conversazione

202</h3>194</h3>

203 195

204La [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.196La [compattazione](/docs/it/context-window#what-survives-compaction) sostituisce la cronologia dei tuoi messaggi con un riepilogo. Per progettazione, questo invalida il livello 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 livello del prompt di sistema a meno che la conversazione non sia stata [ripresa mantenendo un prompt di sistema che altrimenti sarebbe cambiato](#resuming-a-session); in quel caso la prima compattazione passa al prompt corrente e quel livello si ricostruisce una volta. Ricarica il contesto del progetto dal disco, che cache-hit solo se CLAUDE.md e la memoria sono invariati da quando la sessione è iniziata.

205 197

206Per produrre il riepilogo, Claude Code invia una richiesta separata con lo stesso prompt di sistema, strumenti e cronologia della tua conversazione, più un'istruzione di riepilogo aggiunta come messaggio utente finale. Mentre la cache è calda, quella richiesta legge il tuo prefisso dalla cache, quindi una `/compact` a metà sessione costa una frazione di quello che la dimensione del contesto suggerisce e spende la maggior parte del suo tempo generando il riepilogo.198Per produrre il riepilogo, Claude Code invia una richiesta separata con lo stesso prompt di sistema, strumenti e cronologia della tua conversazione, più un'istruzione di riepilogo aggiunta come messaggio utente finale. Mentre la cache è calda, quella richiesta legge il tuo prefisso dalla cache, quindi un `/compact` a metà sessione costa una frazione di quello che la dimensione del contesto suggerisce e spende la maggior parte del suo tempo generando il riepilogo.

207 199

208Dopo una pausa più lunga della [durata della cache](#cache-lifetime), non c'è cache rimasta da leggere, quindi la richiesta di riepilogo rielabora la cronologia completa come input non memorizzato nella cache. Questo è il motivo per cui `/compact` costa di più quando [riprendi una sessione vecchia](/docs/it/sessions#resume-from-a-summary). In entrambi i casi caldi e freddi, il turno dopo la compaction ricostruisce la cache della conversazione solo per il riepilogo molto più breve, quindi quel turno non è la parte lenta.200Dopo una pausa più lunga della [durata della cache](#cache-lifetime), non c'è cache rimasta da leggere, quindi la richiesta di riepilogo rielabora la cronologia completa come input non memorizzato nella cache. Questo è il motivo per cui `/compact` costa di più quando [riprendi una sessione vecchia](/docs/it/sessions#resume-from-a-summary). In entrambi i casi caldi e freddi, il turno dopo la compattazione ricostruisce la cache della conversazione solo per il riepilogo molto più breve, quindi quel turno non è la parte lenta.

209 201

210<Tip>202<Tip>

211 La compaction funziona a tuo favore quando il contesto che scardi è contenuto di cui non hai più bisogno. Per scegliere quando il suo overhead accade, esegui `/compact` a una pausa naturale nel tuo lavoro, come tra i compiti, invece di aspettare che la compaction automatica si attivi a metà compito. Se sei andato su un percorso che vuoi abbandonare completamente, [`/rewind`](#rewinding-the-conversation) a un turno precedente invece. Il rewind tronca a un prefisso che è già memorizzato nella cache, piuttosto che costruirne uno nuovo come fa la compaction.203 La compattazione funziona a tuo favore quando il contesto che scarta è contenuto che non ti serve più. Per scegliere quando il suo sovraccarico accade, esegui `/compact` a una pausa naturale nel tuo lavoro, ad esempio tra le attività, invece di aspettare che la compattazione automatica si attivi a metà attività. Se sei andato su un percorso che vuoi abbandonare completamente, [`/rewind`](#rewinding-the-conversation) a un turno precedente. Il riavvolgimento tronca a un prefisso che è già memorizzato nella cache, piuttosto che costruirne uno nuovo come fa la compattazione.

212</Tip>204</Tip>

213 205

214<h3 id="accumulating-many-images">206<h3 id="accumulating-many-images">

215 Accumulating many images207 Accumulo di molte immagini

216</h3>208</h3>

217 209

218L'API limita quante immagini e PDF ogni richiesta può contenere. Per i numeri attuali, vedi [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) nella documentazione dell'API. Claude Code limita anche la dimensione totale delle immagini e dei PDF in una richiesta, quindi gli screenshot grandi raggiungono il limite con meno immagini di quelli piccoli.210L'API limita quante immagini e PDF ogni richiesta può contenere. Per i numeri attuali, vedi [Limiti di richiesta](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) nella documentazione dell'API. Claude Code limita anche la dimensione totale delle immagini e dei PDF in una richiesta, quindi gli screenshot grandi raggiungono il limite con meno immagini di quelli piccoli.

219 211

220Quando la richiesta successiva passerebbe uno dei due limiti, Claude Code rimuove un batch delle immagini e dei PDF più vecchi da quello che invia, il che lascia spazio per altri prima di dover rimuovere di nuovo. Claude non può più vedere le immagini rimosse. Se Claude ne ha bisogno di nuovo, condividila di nuovo.212Quando la richiesta successiva supererebbe uno dei due limiti, Claude Code rimuove un batch delle immagini e dei PDF più vecchi da quello che invia, il che lascia spazio per altri prima di dover rimuovere di nuovo. Claude non può più vedere le immagini rimosse. Se Claude ne ha bisogno di nuovo, condividila di nuovo.

221 213

222Rimuovere immagini cambia i messaggi che le contenevano, quindi la richiesta successiva rielabora la conversazione dal primo di quei messaggi in poi. Poiché Claude Code rimuove un batch alla volta, vedi un turno più lento per batch piuttosto che uno con ogni nuovo screenshot.214La rimozione di immagini cambia i messaggi che le contenevano, quindi la richiesta successiva rielabora la conversazione dal primo di quei messaggi in poi. Poiché Claude Code rimuove un batch alla volta, vedi un turno più lento per batch piuttosto che uno con ogni nuovo screenshot.

223 215

224<h3 id="upgrading-claude-code">216<h3 id="upgrading-claude-code">

225 Upgrading Claude Code217 Aggiornamento di Claude Code

226</h3>218</h3>

227 219

228Una 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. L'[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.220Una nuova versione di Claude Code in genere aggiorna il prompt di sistema o le definizioni degli strumenti, quindi la prima conversazione che inizi dopo un aggiornamento costruisce la sua cache da zero. L'[aggiornamento automatico](/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 non memorizzato nella cache dopo il riavvio piuttosto che una sorpresa durante una sessione. Imposta `DISABLE_AUTOUPDATER=1` per controllare quando gli aggiornamenti si applicano.

229 221

230<Note>222<Note>

231 [Riprendere una sessione](/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.223 Per quello che costa riprendere una conversazione che hai iniziato prima dell'aggiornamento, vedi [Ripresa di una sessione](#resuming-a-session).

232</Note>224</Note>

233 225

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

235 Azioni che mantengono la cache227 Azioni che mantengono la cache

236</h2>228</h2>

237 229

238Queste azioni aggiungono alla fine della conversazione o non toccano affatto la richiesta. Alcune di esse, come modificare CLAUDE.md, mantengono la cache per lo stesso motivo per cui la modifica non raggiunge la sessione in esecuzione fino a `/clear`, `/compact` o un riavvio.230Queste azioni aggiungono alla fine della conversazione o non toccano affatto la richiesta. Alcune di esse, come la modifica di CLAUDE.md, mantengono la cache per lo stesso motivo per cui la modifica non raggiunge la sessione in esecuzione fino a `/clear`, `/compact` o un riavvio.

239 231

240* [Modifica dei file nel tuo repository](#editing-files-in-your-repository)232* [Modifica di file nel tuo repository](#editing-files-in-your-repository)

241* [Modifica di CLAUDE.md durante la sessione](#editing-claude-md-mid-session)233* [Modifica di CLAUDE.md durante la sessione](#editing-claude-md-mid-session)

242* [Cambio della modalità di autorizzazione](#changing-permission-mode)234* [Modifica della modalità di autorizzazione](#changing-permission-mode)

235* [Modifica dello stile di output](#changing-output-style)

243* [Invocazione di skills e comandi](#invoking-skills-and-commands)236* [Invocazione di skills e comandi](#invoking-skills-and-commands)

244* [Esecuzione di `/recap`](#running-%2Frecap)237* [Esecuzione di `/recap`](#running-%2Frecap)

245* [Riavvolgimento della conversazione](#rewinding-the-conversation)238* [Ripristino della conversazione](#rewinding-the-conversation)

246* [Generazione di un subagent](#subagents-and-the-cache)239* [Generazione di un subagent](#subagents-and-the-cache)

247 240

248<h3 id="editing-files-in-your-repository">241<h3 id="editing-files-in-your-repository">

249 Modifica dei file nel tuo repository242 Modifica di file nel tuo repository

250</h3>243</h3>

251 244

252I contenuti dei file entrano nel contesto solo quando Claude li legge, e le letture si aggiungono alla conversazione. Modificare un file che Claude ha letto in precedenza non cambia retroattivamente la lettura precedente nella cronologia. Invece, Claude Code aggiunge un `<system-reminder>` notando che il file è cambiato, e Claude lo rilegge se necessario.245I contenuti dei file entrano nel contesto solo quando Claude li legge, e le letture si aggiungono alla conversazione. La modifica di un file che Claude ha precedentemente letto non cambia retroattivamente la lettura precedente nella cronologia. Invece, Claude Code aggiunge un `<system-reminder>` che nota il cambio del file, e Claude lo rilegge se necessario.

253 246

254<h3 id="editing-claude-md-mid-session">247<h3 id="editing-claude-md-mid-session">

255 Modifica di CLAUDE.md durante la sessione248 Modifica di CLAUDE.md durante la sessione

256</h3>249</h3>

257 250

258I 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.251I 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. La modifica di questi file 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.

259 252

260[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.253[I file CLAUDE.md annidati nelle sottodirectory](/docs/it/memory) e [le regole con frontmatter `paths:`](/docs/it/memory#path-specific-rules) vengono caricati successivamente, quando Claude legge per la prima volta un file corrispondente. La modifica di 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.

261 254

262<h3 id="changing-permission-mode">255<h3 id="changing-permission-mode">

263 Cambio della modalità di autorizzazione256 Modifica della modalità di autorizzazione

257</h3>

258

259Il passaggio tra [modalità di autorizzazione](/docs/it/permission-modes), ad esempio da Manuale ad accettazione di 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à plan con l'impostazione del modello [`opusplan`](/docs/it/model-config#opusplan-model-setting), che commuta il modello tra Opus e Sonnet quando entri o esci dalla modalità plan. Questo rende il toggle della modalità un [cambio di modello](#switching-models).

260

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

262 Modifica dello stile di output

264</h3>263</h3>

265 264

266Passare tra [modalità di autorizzazione](/docs/it/permission-modes), come da manuale 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).265Quando cambi [stili di output](/docs/it/output-styles) durante la sessione con `/config` o l'impostazione `outputStyle`, Claude utilizza il nuovo stile a partire dal tuo prossimo messaggio. Claude Code fornisce le istruzioni del nuovo stile come messaggio nella conversazione, quindi quella richiesta legge comunque il prompt di sistema e la conversazione precedente dalla cache.

266

267Prima della v2.1.251, un cambio di stile durante la sessione manteneva la cache ma non si applicava fino a quando non eseguivi `/clear` o non avviavi una nuova sessione.

267 268

268<h3 id="invoking-skills-and-commands">269<h3 id="invoking-skills-and-commands">

269 Invocazione di skills e comandi270 Invocazione di skills e comandi

270</h3>271</h3>

271 272

272[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. Una skill o un comando il cui frontmatter nomina un `model` può essere un [cambio di modello](#switching-models) per quel turno.273[Skills](/docs/it/skills) e [comandi](/docs/it/commands) iniettano le loro istruzioni come messaggi utente nel punto di invocazione. Nulla di precedente nella conversazione cambia. Una skill o un comando il cui frontmatter nomina un `model` può essere un [cambio di modello](#switching-models) per quel turno.

273 274

274<h3 id="running-/recap">275<h3 id="running-/recap">

275 Esecuzione di `/recap`276 Esecuzione di `/recap`

276</h3>277</h3>

277 278

278[`/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.279[`/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 cronologia dei tuoi messaggi, quindi il prefisso memorizzato nella cache rimane intatto.

279 280

280<h3 id="rewinding-the-conversation">281<h3 id="rewinding-the-conversation">

281 Riavvolgimento della conversazione282 Ripristino della conversazione

282</h3>283</h3>

283 284

284[`/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.285[`/rewind`](/docs/it/checkpointing) tronca la tua conversazione fino a un turno precedente. La cronologia rimanente è lo stesso contenuto da cui la cache è stata costruita in quel momento, e il prompt di sistema e i livelli di contesto del progetto rimangono invariati, quindi la richiesta successiva raggiunge la voce di cache precedente. Ogni turno da allora ha letto attraverso quel prefisso, che ha mantenuto la voce attiva anche se il turno originale era più tempo fa rispetto al TTL.

286

287Il 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 nella [modifica di file nel tuo repository](#editing-files-in-your-repository).

288

289<h2 id="resuming-a-session">

290 Ripresa di una sessione

291</h2>

292

293Quando [riprendete una sessione](/docs/it/sessions#resume-a-session), Claude Code invia di nuovo l'intera conversazione e la richiesta legge dalla cache qualsiasi parte del suo prefisso che rimane invariata e ancora entro la [durata della cache](#cache-lifetime). La tabella dei livelli in cima a questa pagina indica quali modifiche apporta ogni livello.

285 294

286Il 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, lo stesso di [modifica dei file nel tuo repository](#editing-files-in-your-repository).295Il prompt di sistema cambierebbe dopo un [aggiornamento di Claude Code](#upgrading-claude-code) o con un testo [`--append-system-prompt`](/docs/it/cli-reference#system-prompt-flags) diverso alla ripresa. Per impostazione predefinita, la conversazione ripresa mantiene il prompt di sistema con cui è stata avviata, quindi la sua cronologia rimane dietro lo stesso prompt e la modifica ha effetto una volta che la conversazione viene compattata o in una nuova conversazione. [System prompt flags in resumed conversations](/docs/it/cli-reference#system-prompt-flags-in-resumed-conversations) copre `--system-prompt-snapshot off` e la modalità bare, dove questo non si applica.

287 296

288<h2 id="cache-lifetime">297<h2 id="cache-lifetime">

289 Cache lifetime298 Cache lifetime

343 Cache scope352 Cache scope

344</h2>353</h2>

345 354

346In Claude Code, la cache è effettivamente scoped a una macchina e una directory. Il prompt di sistema incorpora la directory di lavoro, la piattaforma, la shell, la versione del sistema operativo e i percorsi della memoria automatica, quindi due sessioni in directory diverse costruiscono prefissi diversi e si perdono la cache l'una dell'altra. Questo include i worktrees dello stesso repository, poiché ogni worktree ha la sua directory di lavoro.355In Claude Code, la cache è effettivamente scoped a una macchina e una directory. Ogni conversazione porta con sé la directory di lavoro, la piattaforma, la shell e la versione del sistema operativo, e il prompt di sistema nomina i tuoi percorsi di memoria automatica, quindi due sessioni in directory diverse costruiscono prefissi diversi e si perdono la cache l'una dell'altra. Questo include i worktrees dello stesso repository, poiché ogni worktree ha la sua directory di lavoro.

347 356

348Le 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.357Le 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é ogni conversazione porta anche il ramo e i commit recenti da quello snapshot.

349 358

350La 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/en/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.359La 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/en/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.

351 360

382 391

383* **Session copies**: una sessione che [copi con `/fork`](/docs/it/agent-view#copy-the-session-with-%2Ffork) riceve la sua istruzione di isolamento come messaggio alla fine della conversazione copiata, quindi la cache che la conversazione originale ha costruito rimane intatta.392* **Session copies**: una sessione che [copi con `/fork`](/docs/it/agent-view#copy-the-session-with-%2Ffork) riceve la sua istruzione di isolamento come messaggio alla fine della conversazione copiata, quindi la cache che la conversazione originale ha costruito rimane intatta.

384* **Compaction**: la chiamata di riepilogo descritta in [Compacting the conversation](#compacting-the-conversation) utilizza lo stesso approccio di condivisione dei prefissi.393* **Compaction**: la chiamata di riepilogo descritta in [Compacting the conversation](#compacting-the-conversation) utilizza lo stesso approccio di condivisione dei prefissi.

394* **Resumed subagents**: quando Claude [riprende un subagent](/docs/it/sub-agents#resume-subagents), la prima richiesta dell'esecuzione ripresa può leggere la cache che l'esecuzione originale ha riscaldato.

385* **Workflow fan-outs**: in un [workflow fan-out](/docs/it/workflows#prompt-caching-in-a-fan-out) di agenti con lo stesso prefisso, Claude Code tiene tutti tranne il primo per un massimo di 5 secondi per impostazione predefinita, quindi le loro prime richieste possono leggere il prefisso che il primo agente ha memorizzato nella cache.395* **Workflow fan-outs**: in un [workflow fan-out](/docs/it/workflows#prompt-caching-in-a-fan-out) di agenti con lo stesso prefisso, Claude Code tiene tutti tranne il primo per un massimo di 5 secondi per impostazione predefinita, quindi le loro prime richieste possono leggere il prefisso che il primo agente ha memorizzato nella cache.

386 396

387<h2 id="disable-prompt-caching">397<h2 id="disable-prompt-caching">

quickstart.md +10 −10

Details

27 Passaggio 1: Installa Claude Code27 Passaggio 1: Installa Claude Code

28</h2>28</h2>

29 29

~~30To install Claude Code, use one of the following methods:~~30Per installare Claude Code, utilizza uno dei seguenti metodi:

31 31

32<Tabs>32<Tabs>

~~33 <Tab title="Native Install (Recommended)">~~33 <Tab title="Installazione nativa (consigliata)">

34 **macOS, Linux, WSL:**34 **macOS, Linux, WSL:**

35 35

36 ```bash theme={null}36 ```bash theme={null}

49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

50 ```50 ```

51 51

52 If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.52 Se vedi `The token '&&' is not a valid statement separator`, sei in PowerShell, non in CMD. Se vedi `'irm' is not recognized as an internal or external command`, sei in CMD, non in PowerShell. Il tuo prompt mostra `PS C:\` quando sei in PowerShell e `C:\` senza il `PS` quando sei in CMD.

53 53

54 If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.54 Se il comando di installazione non riesce con `syntax error near unexpected token '<'`, un `403`, o un altro errore curl, consulta [Troubleshoot installation](/docs/it/troubleshoot-install#find-your-error) per abbinare l'errore a una soluzione e per metodi di installazione alternativi.

55 55

56 [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.56 [Git for Windows](https://git-scm.com/downloads/win) è consigliato su Windows nativo in modo che Claude Code possa utilizzare lo strumento Bash. Se Git for Windows non è installato, Claude Code utilizza PowerShell come strumento shell. Le configurazioni WSL non necessitano di Git for Windows.

57 57

58 <Info>58 <Info>

~~59 Native installations automatically update in the background to keep you on the latest version.~~59 Le installazioni native si aggiornano automaticamente in background per mantenerti sulla versione più recente.

60 </Info>60 </Info>

61 </Tab>61 </Tab>

62 62

65 brew install --cask claude-code65 brew install --cask claude-code

66 ```66 ```

67 67

68 Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.68 Homebrew offre due cask. `claude-code` traccia il canale di rilascio stabile, che in genere è circa una settimana indietro e salta i rilasci con regressioni importanti. `claude-code@latest` traccia il canale più recente e riceve nuove versioni non appena vengono rilasciate.

69 69

70 <Info>70 <Info>

71 Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.71 Le installazioni Homebrew non si aggiornano automaticamente. Esegui `brew upgrade claude-code` o `brew upgrade claude-code@latest`, a seconda di quale cask hai installato, per ottenere le funzionalità più recenti e le correzioni di sicurezza.

72 </Info>72 </Info>

73 </Tab>73 </Tab>

74 74

78 ```78 ```

79 79

80 <Info>80 <Info>

~~81 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.~~81 Le installazioni WinGet non si aggiornano automaticamente. Esegui `winget upgrade Anthropic.ClaudeCode` periodicamente per ottenere le funzionalità più recenti e le correzioni di sicurezza.

82 </Info>82 </Info>

83 </Tab>83 </Tab>

84</Tabs>84</Tabs>

85 85

~~86You can also install with [apt, dnf, or apk](/docs/en/setup#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.~~86Puoi anche installare con [apt, dnf, o apk](/docs/it/setup#install-with-linux-package-managers) su Debian, Fedora, RHEL e Alpine.

87 87

88Per confermare che l'installazione ha funzionato, esegui:88Per confermare che l'installazione ha funzionato, esegui:

89 89

remote-control.md +19 −22

Details

132 Verifica lo stato della connessione132 Verifica lo stato della connessione

133</h3>133</h3>

134 134

135In una sessione di terminale interattiva, un indicatore `/rc active` si trova nel footer sotto la casella di input mentre la connessione è attiva, ed è nascosto se il terminale è troppo stretto per contenerlo. Il testo dell'indicatore è un collegamento alla sessione su claude.ai. Selezionalo con il tasto freccia giù e premi Invio, oppure esegui `/remote-control` di nuovo, per aprire un pannello di stato con l'URL della sessione e un codice QR che puoi utilizzare per [connetterti da un altro dispositivo](#connect-from-another-device). Il pannello di stato offre anche un'opzione di disconnessione. Selezionala per disattivare Remote Control; la tua sessione locale continua a funzionare nel terminale.135In una sessione di terminale interattiva, un indicatore `/rc active` si mostra mentre la connessione è attiva, ed è nascosto se il terminale è troppo stretto per contenerlo. Con il [rendering a schermo intero](/docs/it/fullscreen) si trova alla fine della riga della directory di lavoro nell'intestazione di avvio, e senza di esso, nel footer sotto la casella di input.

136 136

137Se la connessione non riesce, Claude Code mostra una notifica con il motivo dell'errore e cambia l'indicatore a uno stato di errore che rimane nel footer. Per leggere il motivo di nuovo, seleziona l'indicatore con il tasto freccia giù e premi Invio. Per riconnetterti, esegui `/remote-control`, a meno che il [motivo non dica che la sessione è stata presa in consegna o terminata altrove, o che il server non riesce a trovarla](#session-ended-elsewhere).137Il testo dell'indicatore è un collegamento alla sessione su claude.ai. Esegui `/remote-control` di nuovo per aprire un pannello di stato con l'URL della sessione e un codice QR per [connetterti da un altro dispositivo](#connect-from-another-device). Quando l'indicatore è nel footer, puoi anche aprire il pannello selezionando l'indicatore con il tasto freccia giù e premendo Invio. Il pannello offre anche un'opzione di disconnessione, che disattiva Remote Control mentre la tua sessione locale continua a funzionare nel terminale.

138 138

139Leggi il motivo prima di riconnetterti. Quando la sessione è stata presa in consegna o terminata da un altro dispositivo, app, o sessione di Claude Code, o il server non riesce a trovarla, il motivo dice quale, e Claude Code omette il suo solito consiglio di eseguire `/remote-control`:139Se la connessione non riesce, Claude Code mostra una notifica con il motivo dell'errore, aggiunge una riga di avviso con il motivo alla conversazione, e cambia l'indicatore a uno stato di errore che rimane nel posto. Per riconnetterti, esegui `/remote-control`, a meno che il [motivo non dica che la sessione è stata presa in consegna o terminata altrove, o che il server non riesce a trovarla](#session-ended-elsewhere).

140 140

141<span id="session-ended-elsewhere" />141<span id="session-ended-elsewhere" />Leggi il motivo prima di riconnetterti. Quando la sessione è stata presa in consegna o terminata da un altro dispositivo, app, o sessione di Claude Code, o il server non riesce a trovarla, il motivo dice quale, e Claude Code omette il suo solito consiglio di eseguire `/remote-control`:

142 142

143* **Un altro dispositivo o sessione di Claude Code ha preso in consegna la sessione**: esegui `/remote-control` solo se vuoi riprendertela da quel dispositivo.143* **Un altro dispositivo o sessione di Claude Code ha preso in consegna la sessione**: esegui `/remote-control` solo se vuoi riprendertela da quel dispositivo.

144* **Hai terminato o archiviato la sessione da un altro dispositivo o app**: esegui `/remote-control` solo se la vuoi indietro; Claude Code riapre una sessione archiviata.144* **Hai terminato o archiviato la sessione da un altro dispositivo o app**: esegui `/remote-control` solo se la vuoi indietro; Claude Code riapre una sessione archiviata.

243 243

244La tua sessione locale di Claude Code effettua solo richieste HTTPS in uscita e non apre mai porte in ingresso sulla tua macchina. Quando avvii Remote Control, si registra con l'API Anthropic e esegue il polling per il lavoro. Quando ti connetti da un altro dispositivo, il server instrada i messaggi tra il client web o mobile e la tua sessione locale su una connessione in streaming.244La tua sessione locale di Claude Code effettua solo richieste HTTPS in uscita e non apre mai porte in ingresso sulla tua macchina. Quando avvii Remote Control, si registra con l'API Anthropic e esegue il polling per il lavoro. Quando ti connetti da un altro dispositivo, il server instrada i messaggi tra il client web o mobile e la tua sessione locale su una connessione in streaming.

245 245

246Tutto il traffico viaggia attraverso l'API Anthropic su TLS, lo stesso trasporto di sicurezza di qualsiasi sessione di Claude Code. La connessione utilizza più credenziali di breve durata, ognuna limitata a un singolo scopo e con scadenza indipendente.246Tutto il traffico viaggia attraverso l'API Anthropic su TLS, lo stesso trasporto di sicurezza di qualsiasi sessione di Claude Code. La connessione utilizza più credenziali di breve durata, ognuna limitata a un singolo scopo e con scadenza indipendente. Quando la credenziale di registrazione di un server `claude remote-control` scade, il server si registra di nuovo con l'API Anthropic e continua a servire le sue sessioni.

247 247

248Mentre Remote Control è connesso, la trascrizione della sessione, inclusi i tuoi messaggi, le risposte di Claude e l'attività degli strumenti, viene archiviata sui server Anthropic. La trascrizione archiviata mantiene la conversazione sincronizzata tra i tuoi dispositivi e consente alla sessione di riconnettersi dopo un'interruzione di rete. L'esecuzione e l'accesso al filesystem rimangono sulla tua macchina, e le trascrizioni archiviate vengono conservate secondo la politica di [utilizzo dei dati](/docs/it/data-usage).248Mentre Remote Control è connesso, la trascrizione della sessione, inclusi i tuoi messaggi, le risposte di Claude e l'attività degli strumenti, viene archiviata sui server Anthropic. La trascrizione archiviata mantiene la conversazione sincronizzata tra i tuoi dispositivi e consente alla sessione di riconnettersi dopo un'interruzione di rete. L'esecuzione e l'accesso al filesystem rimangono sulla tua macchina, e le trascrizioni archiviate vengono conservate secondo la politica di [utilizzo dei dati](/docs/it/data-usage).

249 249

368 * **Modalità server**: Claude Code rinuncia dopo circa 10 minuti e il processo `claude remote-control` esce. Esegui di nuovo `claude remote-control` per avviare una nuova sessione.368 * **Modalità server**: Claude Code rinuncia dopo circa 10 minuti e il processo `claude remote-control` esce. Esegui di nuovo `claude remote-control` per avviare una nuova sessione.

369 * **Sessione interattiva**: continua a lavorare localmente. Claude Code continua a riprovare finché dura l'interruzione e si riconnette automaticamente quando la rete ritorna.369 * **Sessione interattiva**: continua a lavorare localmente. Claude Code continua a riprovare finché dura l'interruzione e si riconnette automaticamente quando la rete ritorna.

370* **Heartbeat di presenza non riusciti**: se una sessione interattiva si disconnette con `could not reach the Remote Control server for about 30 minutes`, esegui `/remote-control` per riconnetterti. Claude Code mostra questo messaggio solo quando gli heartbeat di presenza della sessione non hanno funzionato mentre il resto della connessione è rimasto attivo; registra di nuovo la sessione per circa 30 minuti prima di disconnettersi.370* **Heartbeat di presenza non riusciti**: se una sessione interattiva si disconnette con `could not reach the Remote Control server for about 30 minutes`, esegui `/remote-control` per riconnetterti. Claude Code mostra questo messaggio solo quando gli heartbeat di presenza della sessione non hanno funzionato mentre il resto della connessione è rimasto attivo; registra di nuovo la sessione per circa 30 minuti prima di disconnettersi.

371* **Dialoghi inoltrati scadono**: Claude Code mantiene aperti i prompt di autorizzazione e le domande `AskUserQuestion` finché non le rispondi. Quando Claude Code inoltra un altro tipo di dialogo alla sessione remota, come il prompt di scelta del modello mostrato dopo un rifiuto di sicurezza, attende cinque minuti per impostazione predefinita, quindi chiude il dialogo e continua con il valore predefinito senza azione del dialogo. Il prompt di consenso dei crediti di utilizzo [Fable](/docs/it/model-config#fable-and-usage-credits) a metà sessione segue la stessa scadenza ma non viene inoltrato: Claude Code lo mostra solo nel terminale dove viene eseguita la sessione, e se nessuno ha risposto lì entro la scadenza, termina il turno senza inviare la richiesta. La selezione del modello rimane invariata e Claude Code chiede di nuovo al tuo prossimo messaggio. Imposta [`dialogExpiry`](/docs/it/settings-reference#dialogexpiry) per regolare o disabilitare la scadenza. Richiede Claude Code v2.1.224 o successivo. Claude Code applica la stessa scadenza al dialogo di approvazione per un messaggio tra sessioni trattenuto. [Le regole di scadenza dei messaggi trattenuti](/docs/it/cross-session-messaging#control-inbound-messages) coprono i casi in cui Claude Code mantiene il dialogo aperto oltre.371* **Dialoghi inoltrati scadono**: Claude Code mantiene aperti i prompt di autorizzazione e le domande `AskUserQuestion` finché non le rispondi. Quando Claude Code inoltra un altro tipo di dialogo alla sessione remota, come il prompt di scelta del modello mostrato dopo un rifiuto di sicurezza, attende cinque minuti per impostazione predefinita, quindi chiude il dialogo e continua con il valore predefinito senza azione del dialogo. Imposta [`dialogExpiry`](/docs/it/settings-reference#dialogexpiry) per regolare o disabilitare la scadenza. Richiede Claude Code v2.1.224 o successivo.

372* **Il prompt di consenso dei crediti di utilizzo Fable non viene inoltrato**: Claude Code mostra il prompt di consenso dei crediti di utilizzo [Fable](/docs/it/model-config#fable-and-usage-credits) a metà sessione solo dove viene eseguita la sessione, non sul tuo dispositivo. Quando la sessione viene eseguita in un terminale e nessuno lì risponde prima che Claude Code chiuda il prompt, il turno termina senza inviare la richiesta; vedi [Il prompt per confermare non ha ricevuto risposta](/docs/it/errors#the-prompt-to-confirm-went-unanswered).

372* **Alcuni comandi sono solo locali**: i comandi che funzionano solo nell'interfaccia del terminale, come `/plugin` o `/resume`, funzionano solo dalla CLI locale, indipendentemente dal fatto che tu passi un argomento o meno. I seguenti funzionano da mobile e web:373* **Alcuni comandi sono solo locali**: i comandi che funzionano solo nell'interfaccia del terminale, come `/plugin` o `/resume`, funzionano solo dalla CLI locale, indipendentemente dal fatto che tu passi un argomento o meno. I seguenti funzionano da mobile e web:

373 * Comandi con output di testo: `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap` e `/reload-plugins`. `/usage-credits` stampa l'URL di fatturazione invece di aprire un browser. `/reload-plugins` funziona solo quando la sessione viene eseguita in un terminale interattivo; una sessione senza uno lo rifiuta.374 * Comandi con output di testo: `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap` e `/reload-plugins`. `/usage-credits` stampa l'URL di fatturazione invece di aprire un browser. `/reload-plugins` funziona solo quando la sessione viene eseguita in un terminale interattivo; una sessione senza uno lo rifiuta.

374 * `/model`, `/effort`, `/fast`, `/color` e `/rename`: passa il valore come argomento, ad esempio `/model sonnet` o `/effort high`. Da mobile e web, `/model` e `/effort` accettano l'argomento al posto del selettore del terminale o del cursore.375 * `/model`, `/effort`, `/fast`, `/color` e `/rename`: passa il valore come argomento, ad esempio `/model sonnet` o `/effort high`. Da mobile e web, `/model` e `/effort` accettano l'argomento al posto del selettore del terminale o del cursore.

375 * `/mcp`: dall'app mobile, restituisce un riepilogo testuale dello stato del server invece di aprire il selettore. Sul web, `/mcp` da solo apre una directory dei [connettori claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) invece di restituire il riepilogo. I [sottocomandi](/docs/it/commands#all-commands) `reconnect`, `enable` e `disable` funzionano da entrambi. A differenza della CLI locale, `/mcp reconnect` senza nome del server riconnette ogni server che ha avuto un errore o necessita autenticazione.376 * `/mcp`: dall'app mobile, restituisce un riepilogo testuale dello stato del server invece di aprire il selettore. Sul web, `/mcp` da solo apre una directory dei [connettori claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) invece di restituire il riepilogo. I sottocomandi `reconnect`, `enable` e `disable` [](/docs/it/commands#all-commands) funzionano da entrambi. A differenza della CLI locale, `/mcp reconnect` senza nome del server riconnette ogni server che ha avuto un errore o necessita autenticazione.

376 * `/config`, dalla v2.1.181: dall'app mobile, passa `key=value` per impostare un'impostazione, o eseguilo senza argomenti per elencare le chiavi che puoi impostare. Sul web, `/config` apre la sezione Claude Code delle tue impostazioni, e ignora il testo dopo il comando.377 * `/config`, dalla v2.1.181: dall'app mobile, passa `key=value` per impostare un'impostazione, o eseguilo senza argomenti per elencare le chiavi che puoi impostare. Sul web, `/config` apre la sezione Claude Code delle tue impostazioni, e ignora il testo dopo il comando.

377 * Su Team ed Enterprise, `/usage-credits` da mobile o web non invia una [richiesta di crediti di utilizzo al tuo amministratore](/docs/it/costs#add-usage-credits-to-your-subscription). L'invio richiede una conferma che appare solo nella CLI interattiva, quindi il comando ti dice di eseguirlo lì. Prima della v2.1.211, il modulo di testo inviava la richiesta senza conferma.378 * Su Team ed Enterprise, `/usage-credits` da mobile o web non invia una [richiesta di crediti di utilizzo al tuo amministratore](/docs/it/costs#add-usage-credits-to-your-subscription). L'invio richiede una conferma che appare solo nella CLI interattiva, quindi il comando ti dice di eseguirlo lì. Prima della v2.1.211, il modulo di testo inviava la richiesta senza conferma.

378 * `/autocompact`, dalla v2.1.221: passa la dimensione della finestra come argomento, ad esempio `/autocompact 500k`. Senza argomenti, stampa la dimensione della finestra corrente come testo invece di aprire il dialogo che il comando mostra in una sessione di terminale.379 * `/autocompact`, dalla v2.1.221: passa la dimensione della finestra come argomento, ad esempio `/autocompact 500k`. Senza argomenti, stampa la dimensione della finestra corrente come testo invece di aprire il dialogo che il comando mostra in una sessione di terminale.

380 * `/advisor`, dalla v2.1.260: passa il modello come argomento, ad esempio `/advisor opus`, o passa `off` per disattivare l'advisor. Entrambi i moduli si applicano solo alla sessione corrente e lasciano invariato il tuo valore predefinito salvato. Senza argomenti, stampa l'advisor corrente come testo invece di aprire il selettore.

379 381

380<h2 id="troubleshooting">382<h2 id="troubleshooting">

381 Risoluzione dei problemi383 Risoluzione dei problemi

446* **L'errore menziona `disableRemoteControl`**: il tuo amministratore IT ha disabilitato Remote Control su questo dispositivo tramite [impostazioni gestite](/docs/it/managed-settings), indipendentemente dall'interruttore a livello di organizzazione e da come sei autenticato.448* **L'errore menziona `disableRemoteControl`**: il tuo amministratore IT ha disabilitato Remote Control su questo dispositivo tramite [impostazioni gestite](/docs/it/managed-settings), indipendentemente dall'interruttore a livello di organizzazione e da come sei autenticato.

447* **Il tuo piano claude.ai è Pro o Max**: Claude Code è ancora autenticato con un'organizzazione Team o Enterprise da un accesso precedente, quindi controlla la politica Remote Control di quell'organizzazione. Esegui `/status` per vedere quale piano e organizzazione usa il tuo accesso. Esegui `claude auth logout` quindi `claude auth login` per accedere di nuovo con il tuo piano attuale.449* **Il tuo piano claude.ai è Pro o Max**: Claude Code è ancora autenticato con un'organizzazione Team o Enterprise da un accesso precedente, quindi controlla la politica Remote Control di quell'organizzazione. Esegui `/status` per vedere quale piano e organizzazione usa il tuo accesso. Esegui `claude auth logout` quindi `claude auth login` per accedere di nuovo con il tuo piano attuale.

448* **La politica dell'organizzazione non è stata caricata su questa macchina**: esegui `claude doctor` e leggi la riga `Organization policy`. Se la riga mostra che la politica non è caricata, è quello che mantiene Remote Control disabilitato. Prima della v2.1.261, `claude doctor` non stampava questa riga.450* **La politica dell'organizzazione non è stata caricata su questa macchina**: esegui `claude doctor` e leggi la riga `Organization policy`. Se la riga mostra che la politica non è caricata, è quello che mantiene Remote Control disabilitato. Prima della v2.1.261, `claude doctor` non stampava questa riga.

451* **Il messaggio non dice di contattare l'amministratore della tua organizzazione**: la tua organizzazione ha una configurazione HIPAA incompatibile con Remote Control, e `/status` elenca `HIPAA` nella sua riga `Compliance`. In questo stato l'interruttore Remote Control del pannello di amministrazione è disattivato, quindi un Owner non può modificarlo lì. Contatta il supporto Anthropic per discutere le opzioni. Prima della v2.1.267, questo caso mostrava "Remote Control isn't available for your organization due to its compliance policy" invece.

449* **Altrimenti, un Owner non l'ha abilitato per la tua organizzazione**: Remote Control è disabilitato per impostazione predefinita su piani Team e Enterprise. Un Owner può abilitarlo su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) attivando l'interruttore **Remote Control**. Questo interruttore è un'impostazione organizzativa lato server.452* **Altrimenti, un Owner non l'ha abilitato per la tua organizzazione**: Remote Control è disabilitato per impostazione predefinita su piani Team e Enterprise. Un Owner può abilitarlo su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) attivando l'interruttore **Remote Control**. Questo interruttore è un'impostazione organizzativa lato server.

450 453

451<h3 id="remote-control-isn’t-available-for-your-organization-due-to-its-compliance-policy">

452 "Remote Control isn't available for your organization due to its compliance policy"

453</h3>

~~454~~

455La tua organizzazione ha una configurazione di conservazione dei dati o conformità incompatibile con Remote Control; la parentesi alla fine del messaggio la nomina. In questo stato l'interruttore Remote Control del pannello di amministrazione è disattivato, quindi un Owner non può modificarlo lì. Contatta il supporto Anthropic per discutere le opzioni.

~~456~~

457<h3 id="remote-credentials-fetch-failed">454<h3 id="remote-credentials-fetch-failed">

458 "Remote credentials fetch failed"455 "Remote credentials fetch failed"

459</h3>456</h3>

523 Scegli l'approccio giusto520 Scegli l'approccio giusto

524</h2>521</h2>

525 522

526Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.523Claude Code offre diversi modi di lavorare quando non sei al tuo terminale. Differiscono in ciò che attiva il lavoro, dove Claude viene eseguito e quanto setup è necessario.

527 524

529| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |526| :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |

531| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI or VS Code) | Run `claude remote-control` | Steering in-progress work from another device |528| [Remote Control](/docs/it/remote-control) | Guida una sessione in esecuzione da [claude.ai/code](https://claude.ai/code) o dall'app mobile Claude | La tua macchina (CLI o VS Code) | Esegui `claude remote-control` | Guidare il lavoro in corso da un altro dispositivo |

532| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |529| [Channels](/docs/it/channels) | Invia eventi da un'app di chat come Telegram o Discord, o dal tuo server | La tua macchina (CLI) | [Installa un plugin channel](/docs/it/channels#quickstart) o [crea il tuo](/docs/it/channels-reference) | Reagire a eventi esterni come errori CI o messaggi di chat |

533| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |530| [Slack](/docs/it/slack) | Menziona `@Claude` in un canale del team | Cloud Anthropic | [Installa l'app Slack](/docs/it/slack#setting-up-claude-code-in-slack) con [Claude Code sul web](/docs/it/claude-code-on-the-web) abilitato | PR e revisioni dalla chat del team |

534| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |531| [Self-hosted environments](/docs/it/self-hosted-environments) | Avvia una [sessione cloud](/docs/it/claude-code-on-the-web) e scegli l'ambiente della tua organizzazione | L'infrastruttura della tua organizzazione | [Distribuisci runner](/docs/it/self-hosted-environments-quickstart), su piani Team e Enterprise | Sessioni cloud che devono essere eseguite all'interno della tua rete |

536 533

537<h2 id="related-resources">534<h2 id="related-resources">

538 Risorse correlate535 Risorse correlate

sandbox-environments.md +1 −1

Details

181 181

182[Claude Code on the web](/docs/it/claude-code-on-the-web) esegue ogni sessione in una macchina virtuale isolata gestita da Anthropic. Un proxy di rete applica una whitelist predefinita, e un proxy separato tiene il tuo token GitHub al di fuori della sandbox mentre emette credenziali scoped per l'accesso al repository all'interno di essa. Le sessioni che la vostra organizzazione instrada a un [ambiente self-hosted](/docs/it/self-hosted-environments) vengono eseguite su infrastruttura che voi stessi provisionate, dove l'isolamento, il controllo dell'egress e le credenziali git sono responsabilità della vostra distribuzione.182[Claude Code on the web](/docs/it/claude-code-on-the-web) esegue ogni sessione in una macchina virtuale isolata gestita da Anthropic. Un proxy di rete applica una whitelist predefinita, e un proxy separato tiene il tuo token GitHub al di fuori della sandbox mentre emette credenziali scoped per l'accesso al repository all'interno di essa. Le sessioni che la vostra organizzazione instrada a un [ambiente self-hosted](/docs/it/self-hosted-environments) vengono eseguite su infrastruttura che voi stessi provisionate, dove l'isolamento, il controllo dell'egress e le credenziali git sono responsabilità della vostra distribuzione.

183 183

184Utilizzate questo approccio quando desiderate l'isolamento completo della VM senza provisioning dell'infrastruttura da soli, o quando state delegando attività da un dispositivo che non dispone di un ambiente di sviluppo locale. Richiede un abbonamento Claude. Quando avviate una sessione dall'interfaccia web, avete anche bisogno di un account GitHub connesso affinché la sandbox possa clonare il vostro repository. Quando avviate dalla CLI con `--cloud`, Claude Code può [raggruppare e caricare il vostro repository locale](/docs/it/claude-code-on-the-web#send-local-repositories-without-github) invece se GitHub non è connesso. Consultate [Claude Code on the web](/docs/it/claude-code-on-the-web) per la disponibilità del piano e le opzioni di autenticazione GitHub.184Utilizzate questo approccio quando desiderate l'isolamento completo della VM senza provisioning dell'infrastruttura da soli, o quando state delegando attività da un dispositivo che non dispone di un ambiente di sviluppo locale. Richiede un abbonamento Claude. Quando avviate una sessione dall'interfaccia web, avete anche bisogno di un account GitHub connesso affinché la sandbox possa clonare il vostro repository. Quando avviate dalla CLI con `--cloud`, Claude Code può [raggruppare e caricare il vostro repository locale](/docs/it/claude-code-on-the-web#send-local-repositories-without-github) invece. Consultate [Claude Code on the web](/docs/it/claude-code-on-the-web) per la disponibilità del piano e le opzioni di autenticazione GitHub.

185 185

186<h2 id="enforce-isolation-across-an-organization">186<h2 id="enforce-isolation-across-an-organization">

187 Applicare l'isolamento in un'organizzazione187 Applicare l'isolamento in un'organizzazione

sandboxing.md +374 −82

Details

28 /sandbox28 /sandbox

29 ```29 ```

30 30

~~31 Questo apre il pannello sandbox con tre schede:~~31 Questo apre il pannello sandbox con tre schede, più una scheda Dependencies su Linux quando il filtro seccomp facoltativo è mancante:

32 32

33 * **Mode**: scegli come i comandi sandboxati vengono approvati, trattato nel passaggio successivo33 * **Mode**: scegli come i comandi sandboxati vengono approvati, trattato nel passaggio successivo

34 * **Overrides**: scegli se i comandi che falliscono sotto la sandbox possono ricadere nell'esecuzione non sandboxata. Questa è l'impostazione [`allowUnsandboxedCommands`](/docs/it/settings#sandbox-settings)34 * **Overrides**: scegli se i comandi che falliscono sotto la sandbox possono ricadere nell'esecuzione non sandboxata. Questa è l'impostazione [`allowUnsandboxedCommands`](/docs/it/settings-reference#sandbox-allowunsandboxedcommands)

35 * **Config**: visualizza le impostazioni sandbox risolte35 * **Config**: visualizza le impostazioni sandbox risolte

36 36

37 Se il pannello mostra solo una scheda Dependencies, manca un pacchetto richiesto. Installalo come descritto in [Set up Linux and WSL2](#set-up-linux-and-wsl2), riavvia Claude Code ed esegui `/sandbox` di nuovo.37 Se il pannello mostra solo una scheda Dependencies, manca un pacchetto richiesto. Installalo come descritto in [Set up Linux and WSL2](#set-up-linux-and-wsl2), riavvia Claude Code ed esegui `/sandbox` di nuovo.

38 </Step>38 </Step>

39 39

40 <Step title="Scegli una modalità">40 <Step title="Scegli una modalità">

41 Nella scheda Mode, seleziona auto-allow o autorizzazioni regolari. Auto-allow esegue i comandi sandboxati senza richiedere, e le autorizzazioni regolari mantengono i prompt di autorizzazione regolari anche quando i comandi sono sandboxati. Vedi [Modalità sandbox](#sandbox-modes) per quali comandi richiedono comunque prompt in modalità auto-allow.41 Nella scheda Mode, seleziona auto-allow o autorizzazioni regolari. Auto-allow esegue i comandi sandboxati senza richiedere, e le autorizzazioni regolari mantengono i prompt di autorizzazione regolari anche quando i comandi sono sandboxati. Vedi [Sandbox modes](#sandbox-modes) per quali comandi richiedono comunque prompt in modalità auto-allow.

42 </Step>42 </Step>

43 43

44 <Step title="Esegui un comando Bash">44 <Step title="Esegui un comando Bash">

45 Chiedi a Claude di eseguire un comando, come una build o una suite di test. Per impostazione predefinita, i comandi all'interno della sandbox possono scrivere solo nella directory di lavoro e nella directory temporanea della sessione. La prima volta che un comando ha bisogno di un nuovo dominio di rete, Claude Code richiede l'approvazione.45 Chiedi a Claude di eseguire un comando, come una build o una suite di test. Per impostazione predefinita, i comandi all'interno della sandbox possono scrivere nella directory di lavoro, nella directory temporanea della sessione e in qualsiasi [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`. La prima volta che un comando ha bisogno di un nuovo dominio di rete, Claude Code richiede l'approvazione, o in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) invia la richiesta al classificatore.

46 46

47 I comandi che non possono essere eseguiti sandboxati ricadono nel flusso di autorizzazione regolare. Per ampliare o restringere questi confini, vedi [Configure sandboxing](#configure-sandboxing).47 I comandi che non possono essere eseguiti sandboxati ricadono nel flusso di autorizzazione regolare. Claude Code intitola il loro prompt di autorizzazione "Bash command (unsandboxed)" invece di "Bash command", così puoi dire quali comandi sono stati eseguiti al di fuori della sandbox. Per ampliare o restringere ciò che la sandbox consente, vedi [Configure sandboxing](#configure-sandboxing).

49 Se i comandi sandboxati falliscono con `Operation not permitted` all'interno di un contenitore, vedi la voce Bubblewrap sotto [Troubleshooting](#troubleshooting).

48 </Step>50 </Step>

49</Steps>51</Steps>

50 52

51Selezionare una modalità nel pannello scrive nelle impostazioni locali del tuo progetto in `.claude/settings.local.json`, che si applicano al progetto corrente e non vengono controllate in git. Per abilitare la sandbox in tutti i tuoi progetti, imposta [`sandbox.enabled`](/docs/it/settings#sandbox-settings) su `true` nelle impostazioni utente in `~/.claude/settings.json`. Per applicare il sandboxing per ogni sviluppatore in un'organizzazione, utilizza [impostazioni gestite](#enforce-sandboxing-with-managed-settings).53Quando selezioni una modalità nel pannello, Claude Code la salva nelle impostazioni locali del tuo progetto in `.claude/settings.local.json`, che si applicano al progetto corrente. Claude Code aggiunge quel file al tuo gitignore globale quando salva un'impostazione lì. Per abilitare la sandbox in tutti i tuoi progetti, imposta [`sandbox.enabled`](/docs/it/settings-reference#sandbox-enabled) su `true` nelle impostazioni utente in `~/.claude/settings.json`. Per applicare il sandboxing per ogni sviluppatore in un'organizzazione, utilizza [impostazioni gestite](#enforce-sandboxing-with-managed-settings).

55Per modificare la sandbox per una sessione senza scrivere in un file di impostazioni, avvia Claude Code con [`--settings`](/docs/it/settings#change-a-setting-for-one-session). Ad esempio, questo comando avvia una sessione sandboxata in cui Claude non può riprovare un comando bloccato al di fuori della sandbox:

57```bash theme={null}

58claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

59```

52 60

53<Warning>61<Warning>

54 Per impostazione predefinita, se la sandbox non può avviarsi perché mancano dipendenze o la piattaforma non è supportata, Claude Code mostra un avviso ed esegue i comandi senza sandboxing. Per rendere questo un errore grave, imposta [`sandbox.failIfUnavailable`](/docs/it/settings#sandbox-settings) su `true`. Questo è destinato a distribuzioni gestite che richiedono il sandboxing come gate di sicurezza.62 Per impostazione predefinita, se la sandbox non può avviarsi perché mancano dipendenze o la piattaforma non è supportata, Claude Code mostra un avviso ed esegue i comandi senza sandboxing. Per rendere questo un errore grave, imposta [`sandbox.failIfUnavailable`](/docs/it/settings-reference#sandbox-failifunavailable) su `true`. Questo è destinato a distribuzioni gestite che richiedono il sandboxing come gate di sicurezza.

55</Warning>63</Warning>

56 64

57<h3 id="set-up-linux-and-wsl2">65<h3 id="set-up-linux-and-wsl2">

79 </Tab>87 </Tab>

80</Tabs>88</Tabs>

81 89

82Dopo l'installazione, la scheda Dependencies in `/sandbox` mostra se `ripgrep`, `bubblewrap`, `socat` e il filtro seccomp sono disponibili sulla tua piattaforma. Ripgrep è incluso nel binario nativo di Claude Code. Il filtro seccomp è facoltativo e aggiunge il blocco del socket di dominio Unix. Installalo con `npm install -g @anthropic-ai/sandbox-runtime` se manca.90Quando una dipendenza è mancante, la scheda Dependencies in `/sandbox` elenca quale tra `ripgrep`, `bubblewrap`, `socat` e il filtro seccomp la tua piattaforma manca. Se non vedi la scheda dopo l'installazione e il riavvio di Claude Code, tutte le dipendenze sono presenti.

92Ripgrep è incluso nel binario nativo di Claude Code. Il filtro seccomp è facoltativo e aggiunge il blocco del socket di dominio Unix. Installalo con `npm install -g @anthropic-ai/sandbox-runtime` se è mancante.

83 93

84Quando manca una dipendenza richiesta, la scheda Dependencies è l'unica scheda mostrata fino a quando non la installi. Il controllo delle dipendenze viene eseguito all'avvio, quindi riavvia Claude Code dopo l'installazione dei pacchetti affinché `/sandbox` li rilevi.94Quando una dipendenza richiesta è mancante, la scheda Dependencies è l'unica scheda mostrata fino a quando non la installi. Quando solo il filtro seccomp facoltativo è mancante, la scheda Dependencies appare insieme alle altre schede. Il controllo delle dipendenze viene eseguito all'avvio, quindi riavvia Claude Code dopo l'installazione dei pacchetti affinché `/sandbox` li rilevi.

85 95

86<AccordionGroup>96<AccordionGroup>

87 <Accordion title="Ubuntu 24.04 e versioni successive: consenti a bubblewrap di creare spazi dei nomi utente">97 <Accordion title="Ubuntu 24.04 e versioni successive: consenti a bubblewrap di creare spazi dei nomi utente">

88 Su Ubuntu 24.04 e versioni successive, la politica AppArmor predefinita impedisce a bubblewrap di creare gli spazi dei nomi utente di cui ha bisogno per l'isolamento.98 Su Ubuntu 24.04 e versioni successive, la politica AppArmor predefinita impedisce a bubblewrap di creare gli spazi dei nomi utente di cui ha bisogno per l'isolamento.

89 99

90 Per verificare se il tuo ambiente applica questa restrizione, incluso all'interno di WSL2, esegui `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se la chiave non esiste o restituisce `0`, salta questo passaggio. Se restituisce `1`, aggiungi un profilo AppArmor che conceda a `bwrap` questa capacità:100 Per verificare se il tuo ambiente applica questa restrizione, incluso all'interno di WSL2, esegui `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se il comando restituisce `0`, salta questo passaggio. Se stampa un errore `No such file or directory`, la chiave non esiste e puoi saltare questo passaggio. Se restituisce `1`, aggiungi un profilo AppArmor che conceda a `bwrap` questa capacità:

91 101

92 ```bash theme={null}102 ```bash theme={null}

93 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'103 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'

111 <Accordion title="Note su WSL2">121 <Accordion title="Note su WSL2">

112 Controlla la tua versione WSL con `wsl -l -v` da PowerShell. Se vedi `Sandboxing requires WSL2`, la tua distribuzione sta eseguendo WSL1. Aggiornala a WSL2 o esegui Claude Code senza sandboxing.122 Controlla la tua versione WSL con `wsl -l -v` da PowerShell. Se vedi `Sandboxing requires WSL2`, la tua distribuzione sta eseguendo WSL1. Aggiornala a WSL2 o esegui Claude Code senza sandboxing.

113 123

114 Su WSL2, i comandi sandboxati non possono avviare binari Windows come `cmd.exe`, `powershell.exe`, o qualsiasi cosa sotto `/mnt/c/`. WSL li passa all'host Windows su un socket Unix, che la sandbox blocca. Se un comando ha bisogno di invocare un binario Windows, aggiungilo a [`excludedCommands`](/docs/it/settings#sandbox-settings) in modo che venga eseguito al di fuori della sandbox.124 Su WSL2, WSL passa il lancio di un binario Windows come `cmd.exe`, `powershell.exe` o qualsiasi cosa sotto `/mnt/c/` all'host Windows su un socket Unix, quindi se un comando sandboxato può lanciarne uno segue le [impostazioni Unix-socket](/docs/it/settings-reference#sandbox-network-allowunixsockets) della sandbox: il filtro seccomp facoltativo deve essere installato per bloccare il socket in primo luogo. Per consentire questi lanci, imposta `allowAllUnixSockets`; per tenerli completamente fuori dalla sandbox, aggiungi il comando a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands).

115 </Accordion>125 </Accordion>

116</AccordionGroup>126</AccordionGroup>

117 127

119 Sandbox modes129 Sandbox modes

120</h3>130</h3>

121 131

122Claude Code offre due modalità sandbox:132Claude Code offre due modalità sandbox. In entrambe, la sandbox applica le stesse restrizioni di filesystem e rete; la differenza è solo se i comandi sandboxati sono auto-approvati o richiedono autorizzazione esplicita.

123 133

124**Modalità auto-allow**: I comandi Bash tenteranno di eseguire all'interno della sandbox e sono automaticamente consentiti senza richiedere autorizzazione. I comandi che non possono essere sandboxati, come quelli che necessitano di accesso alla rete a host non consentiti, ricadono nel flusso di autorizzazione regolare, dove Claude Code controlla le tue [regole di autorizzazione](/docs/it/permissions) e ti richiede per qualsiasi comando che quelle regole non consentono già, con un prompt in modalità predefinita o il classificatore in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode).134<h4 id="auto-allow-mode">

135 Auto-allow mode

136</h4>

137

138Quando un comando può essere sandboxato, Claude Code lo esegue all'interno della sandbox e lo approva automaticamente, senza chiedere il tuo permesso. I comandi che non possono essere sandboxati, come quelli che necessitano di accesso alla rete a host non consentiti, ricadono nel flusso di autorizzazione regolare, dove Claude Code controlla le tue [regole di autorizzazione](/docs/it/permissions) e blocca qualsiasi comando che quelle regole non consentono già, con un prompt in modalità Manual.

125 139

126Anche in modalità auto-allow, si applicano i seguenti:140Anche in modalità auto-allow, si applicano i seguenti:

127 141

128* Le [regole di negazione](/docs/it/permissions) esplicite sono sempre rispettate142* Le [regole di negazione](/docs/it/permissions) esplicite sono sempre rispettate

129* I comandi `rm` o `rmdir` che puntano a `/`, alla tua directory home o ad altri percorsi critici del sistema attivano comunque un prompt di autorizzazione143* I comandi `rm` o `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths) passano comunque attraverso il flusso di autorizzazione regolare

130* Le [regole ask](/docs/it/permissions) con ambito di contenuto come `Bash(git push *)` forzano comunque un prompt anche per i comandi sandboxati144* Le [regole ask](/docs/it/permissions) con ambito di contenuto come `Bash(git push *)` forzano comunque un prompt anche per i comandi sandboxati

131* Una regola ask `Bash` semplice, o la forma equivalente `Bash(*)`, viene saltata per i comandi che vengono eseguiti sandboxati; si applica comunque ai comandi che ricadono nel flusso di autorizzazione regolare145* Una regola ask `Bash` semplice, o la forma equivalente `Bash(*)`, viene saltata per i comandi che vengono eseguiti sandboxati; si applica comunque ai comandi che ricadono nel flusso di autorizzazione regolare. In [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode), la regola non viene saltata: richiede per i comandi sandboxati anche, inclusi quelli di sola lettura. Prima della v2.1.212, il salto si applicava anche in plan mode

146

147<Info>

148 La modalità auto-allow funziona indipendentemente dall'impostazione della modalità di autorizzazione, con un'eccezione: [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode). Anche se non sei in modalità "accetta modifiche", i comandi Bash sandboxati vengono eseguiti automaticamente quando auto-allow è abilitato. Ciò significa che i comandi Bash che modificano file entro i confini della sandbox vengono eseguiti senza richiedere, anche in modalità Manual, dove gli strumenti di modifica dei file richiederebbero.

132 149

133**Modalità autorizzazioni regolari**: Tutti i comandi Bash passano attraverso il flusso di autorizzazione regolare, anche quando sandboxati. Questo fornisce più controllo ma richiede più approvazioni.150 In plan mode, auto-allow non amplia le approvazioni; vedi [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode) per come Claude Code blocca i comandi mentre pianifichi. Prima della v2.1.212, auto-allow eseguiva i comandi sandboxati senza un prompt in plan mode anche.

151</Info>

134 152

135In entrambe le modalità, la sandbox applica le stesse restrizioni di filesystem e rete. La differenza è solo se i comandi sandboxati sono auto-approvati o richiedono autorizzazione esplicita.153<h4 id="regular-permissions-mode">

154 Regular permissions mode

155</h4>

136 156

137La directory temporanea della sessione è scrivibile all'interno della sandbox per impostazione predefinita, insieme alla directory di lavoro. Claude Code imposta `$TMPDIR` su questa directory per i comandi sandboxati, quindi gli strumenti che scrivono file temporanei funzionano senza configurazione aggiuntiva. I comandi non sandboxati ereditano il tuo `$TMPDIR` della shell invariato, il che significa che i comandi sandboxati e non sandboxati risolvono `$TMPDIR` in directory diverse. Per passare file temporanei tra i due, scrivili nella directory di lavoro.157Tutti i comandi Bash passano attraverso il flusso di autorizzazione regolare, anche quando sandboxati. Questo fornisce più controllo ma richiede più approvazioni.

138 158

139Alcuni comandi non possono essere eseguiti all'interno della sandbox, come strumenti incompatibili con essa o che necessitano di un host che non hai consentito. Piuttosto che fallire il compito o richiedere di disattivare il sandboxing, Claude Code include un escape hatch: quando un comando fallisce a causa di restrizioni della sandbox, Claude analizza il fallimento e potrebbe riprovare il comando con il parametro `dangerouslyDisableSandbox`. Il comando riprovato viene eseguito al di fuori della sandbox, quindi passa attraverso il flusso di autorizzazione regolare: in modalità predefinita ottieni un prompt di conferma; in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) il classificatore valuta il comando sottostante invece di richiedere la tua approvazione. Per essere richiesto su ogni riprovazione non sandboxata anche in modalità auto, aggiungi una [regola ask](/docs/it/permissions#match-by-input-parameter) per `Bash(dangerouslyDisableSandbox:true)`.159<h4 id="the-unsandboxed-retry-escape-hatch">

160 The unsandboxed retry escape hatch

161</h4>

140 162

141Puoi disabilitare questo escape hatch impostando `"allowUnsandboxedCommands": false` nelle tue [impostazioni sandbox](/docs/it/settings#sandbox-settings). Quando disabilitato, che la scheda Overrides di `/sandbox` mostra come **Modalità sandbox rigorosa**, il parametro `dangerouslyDisableSandbox` viene completamente ignorato e tutti i comandi devono essere eseguiti sandboxati o essere esplicitamente elencati in `excludedCommands`.163Alcuni comandi non possono essere eseguiti all'interno della sandbox, come strumenti incompatibili con essa o che necessitano di un host che non hai consentito. Claude Code segnala le violazioni della sandbox nel risultato del comando bloccato, nominando il percorso o l'host che la sandbox ha negato, così Claude vede cosa la sandbox ha bloccato. Piuttosto che fallire il compito o richiedere di disattivare il sandboxing, Claude Code include un escape hatch: Claude analizza la violazione e potrebbe riprovare il comando con il parametro `dangerouslyDisableSandbox`.

142 164

143<Info>165Il comando riprovato viene eseguito al di fuori della sandbox, quindi passa attraverso il flusso di autorizzazione regolare. In modalità Manual ottieni un prompt di conferma. In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il classificatore valuta il comando sottostante. Mentre [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) è attivo, una riprovazione che necessita di approvazione per essere eseguita al di fuori della sandbox ti richiede invece. Per essere richiesto su ogni riprovazione non sandboxata anche in modalità auto, aggiungi una [regola ask](/docs/it/permissions#match-by-input-parameter) per `Bash(dangerouslyDisableSandbox:true)`.

144 La modalità auto-allow funziona indipendentemente dall'impostazione della modalità di autorizzazione. Anche se non sei in modalità "accetta modifiche", i comandi Bash sandboxati verranno eseguiti automaticamente quando auto-allow è abilitato. Ciò significa che i comandi Bash che modificano file entro i confini della sandbox verranno eseguiti senza richiedere, anche quando gli strumenti di modifica dei file normalmente richiederebbero approvazione.166

145</Info>167Puoi disabilitare questo escape hatch impostando `"allowUnsandboxedCommands": false` nelle tue [impostazioni sandbox](/docs/it/settings-reference#sandbox-settings). Con l'escape hatch disabilitato, Claude Code ignora il parametro `dangerouslyDisableSandbox`, e ogni comando che Claude esegue deve essere eseguito sandboxato a meno che non lo abbia elencato in `excludedCommands`. La scheda **Overrides** di `/sandbox` mostra questa impostazione come **Strict sandbox mode**.

168

169La modalità strict sandbox si applica ai comandi che Claude esegue. I comandi che digiti tu stesso al prompt [shell-mode](/docs/it/interactive-mode#shell-mode-with-prefix) con il prefisso `!` vengono eseguiti al di fuori della sandbox a meno che la sessione non sia una di queste:

170

171* **Una [sessione in background](/docs/it/agent-view)**: la modalità strict sandbox copre anche i comandi shell-mode

172* **Una sessione Linux con [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars#variables) impostato**: ogni comando viene eseguito sandboxato, inclusi i comandi shell-mode

173

174Prima della v2.1.260, la modalità strict sandbox sandboxava i comandi shell-mode in ogni sessione.

175

176<h4 id="temporary-directories">

177 Temporary directories

178</h4>

179

180La directory temporanea della sessione è scrivibile all'interno della sandbox per impostazione predefinita, insieme alla directory di lavoro. A meno che tu non [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation), Claude Code imposta `$TMPDIR` su questa directory per i comandi sandboxati, così gli strumenti che scrivono file temporanei funzionano senza configurazione aggiuntiva. I comandi non sandboxati ereditano il tuo `$TMPDIR` della shell invariato, quindi mentre l'isolamento del filesystem è attivo, i comandi sandboxati e non sandboxati risolvono `$TMPDIR` in directory diverse. Per passare file temporanei tra i due, scrivili nella directory di lavoro invece.

146 181

147<h2 id="configure-sandboxing">182<h2 id="configure-sandboxing">

148 Configure sandboxing183 Configura il sandboxing

149</h2>184</h2>

150 185

151Personalizza il comportamento della sandbox tramite il file `settings.json`. Vedi [Settings](/docs/it/settings#sandbox-settings) per il riferimento di configurazione completo.186Personalizza il comportamento della sandbox attraverso il tuo file `settings.json`. Vedi [Settings](/docs/it/settings-reference#sandbox-settings) per il riferimento di configurazione completo.

152 187

153Per impostazione predefinita, i comandi sandboxati possono scrivere solo nella directory di lavoro corrente e nella directory temporanea della sessione. Se i comandi dei sottoprocessi come `kubectl`, `terraform` o `npm` devono scrivere al di fuori di quelle directory, utilizza `sandbox.filesystem.allowWrite` per concedere l'accesso a percorsi specifici:188Per impostazione predefinita, i comandi in sandbox possono scrivere nella directory di lavoro corrente, nella directory temporanea della sessione e in qualsiasi [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`. Se i comandi dei sottoprocessi come `kubectl`, `terraform` o `npm` devono scrivere al di fuori di quelle directory, usa `sandbox.filesystem.allowWrite` per concedere l'accesso a percorsi specifici:

154 189

155```json theme={null}190```json theme={null}

156{191{

163}198}

164```199```

165 200

166Questi percorsi sono applicati a livello del sistema operativo, quindi tutti i comandi in esecuzione all'interno della sandbox, inclusi i loro processi figlio, li rispettano. Questo è l'approccio consigliato quando uno strumento ha bisogno di accesso in scrittura a una posizione specifica, piuttosto che escludere completamente lo strumento dalla sandbox con `excludedCommands`.201Questi percorsi sono applicati a livello del sistema operativo, quindi tutti i comandi in esecuzione all'interno della sandbox, inclusi i loro processi figlio, li rispettano. Questo è l'approccio consigliato quando uno strumento ha bisogno dell'accesso in scrittura a una posizione specifica, piuttosto che escludere completamente lo strumento dalla sandbox con `excludedCommands`.

202

203Quando definisci lo stesso array del filesystem in più [ambiti di impostazioni](/docs/it/settings#settings-precedence), Claude Code li unisce, combinando i percorsi da ogni ambito piuttosto che sostituire l'array di un ambito con quello di un altro.

204

205Se escludi un'origine con [`--setting-sources`](/docs/it/cli-reference) sulla CLI o [`settingSources`](/docs/it/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) in Agent SDK, Claude Code ignora le sue voci `sandbox.filesystem`, le sue regole di permesso `Edit` e le sue regole di negazione `Read` quando costruisce la configurazione della sandbox. Richiede Claude Code v2.1.246 o successivo.

167 206

168Quando lo stesso array di filesystem è definito in più [ambiti di impostazioni](/docs/it/settings#settings-precedence), gli array vengono uniti: i percorsi da ogni ambito vengono combinati, non sostituiti.207Quando modifichi questi elenchi del filesystem durante una sessione, Claude Code [applica la modifica alla sessione in esecuzione](/docs/it/settings#when-edits-take-effect), quindi il prossimo comando in sandbox viene eseguito con i nuovi percorsi.

169 208

170I prefissi di percorso controllano come i percorsi vengono risolti:209I prefissi dei percorsi controllano come vengono risolti i percorsi:

171 210

173| :--------------------- | :------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |212| :--------------------- | :------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |

175| `~/` | Relativo alla directory home | `~/.kube` diventa `$HOME/.kube` |214| `~/` | Relativo alla directory home | `~/.kube` diventa `$HOME/.kube` |

176| `./` o nessun prefisso | Relativo alla radice del progetto per le impostazioni del progetto, o a `~/.claude` per le impostazioni utente | `./output` in `.claude/settings.json` si risolve in `<project-root>/output` |215| `./` o nessun prefisso | Relativo alla radice del progetto per le impostazioni del progetto, o a `~/.claude` per le impostazioni utente | `./output` in `.claude/settings.json` si risolve in `<project-root>/output` |

177 216

178Questa sintassi differisce dalle [regole di autorizzazione Read e Edit](/docs/it/permissions#read-and-edit), che utilizzano `//path` per assoluto e `/path` per relativo al progetto. I percorsi del filesystem della sandbox utilizzano convenzioni standard: `/tmp/build` è assoluto.217Questa sintassi differisce dalle [regole di permesso Read e Edit](/docs/it/permissions#read-and-edit), che usano `//path` per assoluto e `/path` per relativo al progetto. I percorsi del filesystem della sandbox usano convenzioni standard: `/tmp/build` è assoluto. Per come Claude Code tratta una barra finale o un wildcard in questi percorsi, vedi [Prefissi dei percorsi della sandbox](/docs/it/settings-reference#sandbox-path-prefixes).

179 218

180Puoi anche negare l'accesso in scrittura o lettura utilizzando `sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead`, e ri-consentire percorsi specifici all'interno di una regione negata utilizzando `sandbox.filesystem.allowRead`. Quando le regole di lettura si sovrappongono, il percorso più specifico vince:219Puoi anche negare l'accesso in scrittura o lettura usando `sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead`, e ri-consentire percorsi specifici all'interno di una regione negata usando `sandbox.filesystem.allowRead`. Quando le regole di lettura si sovrappongono, il percorso più specifico vince:

181 220

182| Regole di esempio | Risultato |221| Regole di esempio | Risultato |

183| :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |222| :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

184| `"denyRead": ["~/"]` con `"allowRead": ["~/projects"]` | `~/projects` è leggibile e il resto della directory home rimane bloccato. L'allow più stretto riaprire quella parte della regione negata |223| `"denyRead": ["~/"]` con `"allowRead": ["~/projects"]` | `~/projects` è leggibile e il resto della directory home rimane bloccato. L'allow più ristretto riapre quella parte della regione negata |

185| `"allowRead": ["~/"]` con `"denyRead": ["~/.env"]` | `~/.env` rimane bloccato e il resto della directory home è leggibile. Un deny esatto rimane all'interno di un allow più ampio, quindi un allow ampio non può silenziosamente riesporsi un segreto |224| `"allowRead": ["~/"]` con `"denyRead": ["~/.env"]` | `~/.env` rimane bloccato e il resto della directory home è leggibile. Il deny si mantiene all'interno di un allow più ampio, quindi un allow ampio non può silenziosamente ri-esporre un segreto |

225| `"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]` | Ogni `.env` sotto la directory home rimane bloccato e il resto è leggibile. Un [wildcard deny](/docs/it/settings-reference#sandbox-path-prefixes) si mantiene all'interno di un allow più ampio nello stesso modo in cui lo fa un percorso esatto |

186 226

187L'esempio seguente blocca la lettura dall'intera directory home consentendo comunque letture dal progetto corrente. Posizionalo nel `.claude/settings.json` del tuo progetto, perché il percorso relativo `.` si risolve nella radice del progetto solo quando la configurazione si trova nelle impostazioni del progetto:227L'esempio seguente blocca la lettura dall'intera directory home mantenendo comunque la lettura dal progetto corrente. Posizionalo nel `.claude/settings.json` del tuo progetto, perché il percorso relativo `.` si risolve alla radice del progetto solo quando la configurazione si trova nelle impostazioni del progetto:

188 228

189```json theme={null}229```json theme={null}

190{230{

198}238}

199```239```

200 240

201Il `.` in `allowRead` si risolve nella radice del progetto perché questa configurazione si trova nelle impostazioni del progetto. Se hai posizionato la stessa configurazione in `~/.claude/settings.json`, `.` si risolverebbe in `~/.claude` invece, e i file del progetto rimarrebbero bloccati dalla regola `denyRead`.241Se avessi posizionato la stessa configurazione in `~/.claude/settings.json`, `.` si risolverebbe in `~/.claude` invece, e i file del progetto rimarrebbero bloccati dalla regola `denyRead`.

242

243Per negare ai comandi in sandbox l'accesso in lettura alle directory home e ai volumi montati mantenendo le directory di lavoro leggibili, imposta [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) invece di scrivere regole di percorso.

244

245<h3 id="disable-filesystem-isolation">

246 Disabilita l'isolamento del filesystem

247</h3>

248

249Imposta `sandbox.filesystem.disabled` su `true` per saltare l'isolamento del filesystem mantenendo l'isolamento della rete. L'esempio seguente disattiva l'isolamento del filesystem mantenendo una lista di permessi di domini di rete:

250

251```json theme={null}

252{

253 "sandbox": {

254 "enabled": true,

255 "filesystem": {

256 "disabled": true

257 },

258 "network": {

259 "allowedDomains": ["github.com", "*.npmjs.org"]

260 }

261 }

262}

263```

264

265La sandbox ha due livelli indipendenti: [l'isolamento del filesystem](#filesystem-isolation) controlla quali percorsi i comandi in sandbox possono leggere e scrivere, e [l'isolamento della rete](#network-isolation) controlla quali domini possono raggiungere. Con il livello del filesystem disattivato, i comandi in sandbox ottengono accesso in lettura e scrittura senza restrizioni al filesystem host, mentre il loro egresso di rete rimane confinato ai tuoi domini consentiti. Disattiva il livello quando esegui il sandbox per controllare dove i comandi si connettono piuttosto che cosa scrivono.

266

267L'impostazione è disattivata per impostazione predefinita e si applica sulle piattaforme dove la sandbox viene eseguita: macOS, Linux e WSL2. Richiede Claude Code v2.1.216 o successivo.

268

269<Warning>

270 Con l'isolamento del filesystem disattivato e i comandi auto-consentiti, un comando in sandbox può scrivere file che i comandi successivi eseguono o leggono, come file di avvio della shell, eseguibili su `$PATH` o `~/.claude/settings.json`, e usarli per ampliare il proprio accesso alla prossima esecuzione. Imposta `filesystem.disabled` su `true` solo per carichi di lavoro di cui ti fidi che non escalino il proprio accesso. Bloccare i domini di rete con [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) riduce il rischio ma non lo elimina, poiché quel blocco si applica solo ai comandi in esecuzione all'interno della sandbox.

271</Warning>

272

273<h4 id="which-settings-can-disable-it">

274 Quali impostazioni possono disabilitarlo

275</h4>

276

277Poiché disattivare l'isolamento del filesystem amplia ciò che i comandi in sandbox possono fare, Claude Code onora `filesystem.disabled` solo da queste fonti di impostazioni:

278

279* Le impostazioni utente, le impostazioni gestite e il flag CLI `--settings` possono impostarlo. Le impostazioni del progetto in `.claude/settings.json` e `.claude/settings.local.json` non possono, quindi un progetto estratto non può disattivare l'isolamento del filesystem.

280* Quando le impostazioni gestite configurano `sandbox.filesystem` in generale, o elencano qualsiasi voce `sandbox.credentials.files` con `"mode": "deny"`, solo le impostazioni gestite possono impostare la chiave. Questo mantiene in vigore le restrizioni del filesystem distribuite dall'amministratore; per rilassare tale distribuzione, imposta `"disabled": true` nelle impostazioni gestite.

281* Quando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) è impostato, Claude Code ignora `filesystem.disabled` da ogni fonte, incluse le impostazioni gestite, e mantiene l'isolamento del filesystem attivo.

282

283Se una voce gestita `credentials.files` fissa `filesystem.disabled`, bloccando la chiave alle impostazioni gestite in modo che gli sviluppatori non possano disattivare l'isolamento del filesystem, dipende dalla `mode` della voce e da cosa accade alla voce quando la sandbox si avvia:

284

285| Voce gestita | Fissa `filesystem.disabled` | Cosa protegge il file quando l'isolamento è disattivato |

286| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |

287| `"mode": "deny"` | Sì | Niente: il blocco di lettura fa parte del livello del filesystem |

288| `"mode": "mask"`, applicato come maschera | No | La mascheratura stessa: la [copia sentinella e il proxy](#mask-credential-files) su Linux e WSL2, le proprie regole di lettura della sandbox su macOS |

289| `"mode": "mask"`, [fallback a `deny`](#mask-credential-files) al setup | No | Niente, come `deny`. Elenca un percorso che non può essere mascherato, come una directory, come voce esplicita `deny`, che fissa la chiave |

290| `"mode": "mask"`, [degradato a `deny` dalla validazione](/docs/it/managed-settings#invalid-entries-in-managed-settings) | Sì, come una voce esplicita `deny` | Niente, come `deny` |

291

292Un fallback accade quando la sandbox si avvia, dopo che Claude Code ha già letto le impostazioni su cui viene eseguito il controllo del pin, quindi una voce con fallback non fissa mai. La validazione riscrive una voce non valida a `deny` mentre le impostazioni si caricano, quindi una voce degradata fissa come una che hai scritto come `deny`.

293

294<h4 id="what-changes-when-filesystem-isolation-is-off">

295 Cosa cambia quando l'isolamento del filesystem è disattivato

296</h4>

297

298Impostare `filesystem.disabled` solleva le protezioni che il livello del filesystem stesso applica. Le protezioni che altri livelli applicano continuano a funzionare:

299

300| Protezione | Con l'isolamento del filesystem disattivato |

301| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

302| `filesystem.denyRead` e [`credentials.files`](#protect-credentials) blocchi di lettura `deny` | Non applicati. Il livello del filesystem applica entrambi |

303| `credentials.envVars` voci `deny` e `mask` | Applicati. Lo scrubbing delle variabili di ambiente è indipendente dal livello del filesystem |

304| [`credentials.files` voci `mask`](#mask-credential-files) applicate come maschere | Applicati: la mascheratura è indipendente dal livello del filesystem. Una voce che ha [fallback a `deny`](#mask-credential-files) non è applicata, come qualsiasi voce `deny` |

305

306Due altre cose cambiano:

307

308* I comandi in sandbox ereditano il `$TMPDIR` della tua shell invece della directory temporanea della sessione, perché ogni directory temporanea è scrivibile e Claude Code non reindirizza più i comandi a quella della sessione.

309

310 Su Linux la variabile è spesso non impostata nella shell padre, quindi può espandersi vuota all'interno dei comandi in sandbox; Claude Code dice a Claude attraverso la sua guida dello strumento Bash di creare directory di lavoro con `mktemp -d` invece di fare affidamento su `$TMPDIR`.

311* [`autoAllowBashIfSandboxed`](/docs/it/settings-reference#sandbox-autoallowbashifsandboxed) continua a impostare il valore predefinito su `true`, quindi i comandi in sandbox continuano a essere eseguiti senza prompt. Impostalo su `false` per richiedere prompt per i comandi in sandbox.

202 312

203<h3 id="protect-credentials">313<h3 id="protect-credentials">

204 Protect credentials314 Proteggi le credenziali

205</h3>315</h3>

206 316

207L'impostazione `sandbox.credentials` dichiara file di credenziali e variabili di ambiente da proteggere dai comandi sandboxati. Ogni voce nomina un percorso di file o una variabile di ambiente e una `mode`. Il blocco dedicato `credentials` mantiene le regole delle credenziali raggruppate insieme e separate dalle regole generali del filesystem. Richiede Claude Code v2.1.187 o successivo.317L'impostazione `sandbox.credentials` dichiara file di credenziali e variabili di ambiente da proteggere dai comandi in sandbox. Ogni voce nomina un percorso di file o una variabile di ambiente e una `mode`. Il blocco dedicato `credentials` mantiene le regole delle credenziali raggruppate insieme e separate dalle regole generali del filesystem. Richiede Claude Code v2.1.187 o successivo.

208 318

209Per le voci con `"mode": "deny"`, i percorsi dei file vengono negati per le letture all'interno della sandbox, la stessa restrizione che applica `filesystem.denyRead`, e le variabili di ambiente vengono rimosse prima di ogni esecuzione di comando sandboxato.319Per le voci con `"mode": "deny"`, i percorsi dei file vengono negati per le letture all'interno della sandbox, la stessa restrizione che `filesystem.denyRead` applica, e le variabili di ambiente vengono non impostate prima di ogni comando in sandbox. La protezione del file fa parte del livello del filesystem, quindi non si applica se [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation); la protezione della variabile di ambiente continua comunque.

210 320

211L'esempio seguente blocca le letture del file delle credenziali AWS e della directory SSH e rimuove `GITHUB_TOKEN` e `NPM_TOKEN` dall'ambiente dei comandi sandboxati:321L'esempio seguente blocca le letture del file delle credenziali AWS e della directory SSH e rimuove `GITHUB_TOKEN` e `NPM_TOKEN` dall'ambiente dei comandi in sandbox:

212 322

213```json theme={null}323```json theme={null}

214{324{

228}338}

229```339```

230 340

231Le voci di file supportano solo `"mode": "deny"`. Le voci di variabili di ambiente accettano anche `"mode": "mask"`, descritto di seguito.341Le voci delle variabili di ambiente e le voci dei file accettano anche `"mode": "mask"`, descritte sotto [Maschera le credenziali](#mask-credentials).

342

343I percorsi dei file seguono le stesse [regole di prefisso](/docs/it/settings-reference#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`.

344

345Claude Code unisce le voci `deny` da ogni [ambito di impostazioni](/docs/it/settings#settings-precedence) che la sessione carica. Una voce `deny` restringe solo l'accesso, quindi qualsiasi ambito può aggiungerne una, ma nessun ambito può rimuoverne una che un altro ambito ha aggiunto.

346

347Quando [escludi una fonte di impostazioni](#configure-sandboxing):

348

349* **Impostazioni del progetto o locali**: Claude Code non applica nessuna delle loro voci `credentials`. Richiede Claude Code v2.1.246 o successivo.

350* **Impostazioni utente**: Claude Code applica comunque le voci `deny` in `~/.claude/settings.json` e mantiene le sue [voci `mask` del file](#mask-credential-files) come restrizioni, ma elimina le sue [voci `mask` delle variabili di ambiente](#mask-environment-variables).

351

352Non esiste un elenco di negazione delle credenziali integrato, quindi solo i file e le variabili che elenchi sono limitati.

232 353

233I percorsi dei file seguono le stesse [regole di prefisso](/docs/it/settings#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`, e le voci `deny` da ogni [ambito di impostazioni](/docs/it/settings#settings-precedence) vengono unite. Una voce `deny` restringe solo l'accesso, quindi qualsiasi ambito può aggiungerne una, ma nessun ambito può rimuoverne una che un altro ambito ha aggiunto.354`sandbox.credentials` influisce solo sui comandi Bash in sandbox. Per rimuovere le credenziali da tutti i sottoprocessi indipendentemente dal sandboxing, imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars).

234 355

235Non esiste un elenco di negazione delle credenziali integrato, quindi solo i file e le variabili che elenchi sono limitati. L'impostazione influisce solo sui comandi Bash sandboxati. Per rimuovere le credenziali di Anthropic e dei provider cloud da tutti i sottoprocessi indipendentemente dal sandboxing, imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars).356<h3 id="mask-credentials">

357 Maschera le credenziali

358</h3>

359

360La mascheratura va oltre una voce `deny` sotto [Proteggi le credenziali](#protect-credentials). Invece di bloccare una credenziale, Claude Code mostra ai comandi in sandbox un segnaposto, la sentinella, e il [proxy della sandbox](#network-isolation) scambia il valore reale sulle richieste in uscita agli host che consenti. Per i file, la sostituzione è il comportamento di Linux e WSL2; [macOS blocca il file invece](#mask-credential-files).

236 361

237<h4 id="mask-environment-variables">362<h4 id="mask-environment-variables">

238 Mask environment variables363 Maschera le variabili di ambiente

239</h4>364</h4>

240 365

241`"mode": "mask"` protegge una credenziale mantenendo il funzionamento degli strumenti che si autenticano con essa. `deny` rimuove completamente la variabile, il che interrompe anche gli strumenti che ne hanno bisogno, come `gh` o `npm`. Richiede Claude Code v2.1.199 o successivo.366`"mode": "mask"` protegge una credenziale mantenendo gli strumenti che si autenticano con essa funzionanti. `deny` rimuove completamente la variabile, il che rompe anche gli strumenti che ne hanno bisogno, come `gh` o `npm`. Richiede Claude Code v2.1.199 o successivo.

367

368Con `mask`, il comando in sandbox vede un valore sentinella per sessione invece di quello reale. Ogni voce `mask` può elencare `injectHosts`, gli host a cui il valore reale è consentito raggiungere. Quando una richiesta esce dalla sandbox per uno di loro, il [proxy della sandbox](#network-isolation) sostituisce la sentinella con il valore reale. Il comando e tutto ciò che registra non contengono mai la credenziale reale, ma le sue richieste si autenticano comunque.

369

370Il proxy sostituisce la credenziale all'interno dei contenuti della richiesta, quindi deve vederli. Imposta [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) in modo che il proxy termini TLS stesso.

371

372Senza di esso, la mascheratura fallisce senza esporre nulla: il comando continua a vedere solo la sentinella, ma la sentinella raggiunge il server invariata e l'autenticazione fallisce. Claude Code segnala questa configurazione errata all'avvio.

242 373

243Con `mask`, il comando sandboxato vede un valore sentinella per sessione invece di quello reale. Quando una richiesta esce dalla sandbox per uno degli `injectHosts` della credenziale, il [proxy della sandbox](#network-isolation) sostituisce il sentinella con il valore reale. Il comando e tutto ciò che registra non contengono mai la credenziale reale, ma le sue richieste si autenticano comunque.374La sostituzione copre intestazioni e corpi di richiesta. Le richieste che si autenticano con una firma derivata dalla credenziale, piuttosto che dalla credenziale stessa, hanno bisogno di una nuova firma al proxy; [Firma di nuovo le richieste AWS](#re-sign-aws-requests) copre come funziona per AWS.

244 375

245Il proxy sostituisce la credenziale all'interno dei contenuti della richiesta, quindi deve vederli. Imposta [`network.tlsTerminate`](/docs/it/settings#sandbox-settings) in modo che il proxy termini TLS stesso. Senza di esso, il mascheramento fallisce in modo chiuso: il comando vede ancora solo il sentinella, ma il sentinella raggiunge il server invariato e l'autenticazione fallisce. Claude Code segnala questa configurazione errata all'avvio.376Il proxy inietta solo sulle connessioni che la [lista di permessi del dominio](#network-isolation) ammette, quindi ogni destinazione `injectHosts` deve anche essere raggiungibile attraverso `network.allowedDomains`.

246 377

247L'esempio seguente maschera due token. `GH_TOKEN` viene sostituito solo sulle richieste a `api.github.com`, mentre `NPM_TOKEN` non ha `injectHosts` e viene sostituito sulle richieste a ogni host in `network.allowedDomains`. Ogni voce `injectHosts` deve essere coperta da `network.allowedDomains`.378L'esempio seguente maschera due token. `GH_TOKEN` viene sostituito solo sulle richieste a `api.github.com`, mentre `NPM_TOKEN` non ha `injectHosts` e viene sostituito sulle richieste a ogni host in `network.allowedDomains`.

248 379

249```json theme={null}380```json theme={null}

250{381{

264}395}

265```396```

266 397

267A differenza di `deny`, il mascheramento autorizza il proxy a inviare la tua credenziale reale agli host elencati, quindi viene rispettato solo dalle impostazioni che tu o il tuo amministratore controllate: impostazioni utente, impostazioni gestite e il flag CLI `--settings`. Le voci `mask`, `network.tlsTerminate` e [`credentials.allowPlaintextInject`](/docs/it/settings#sandbox-settings) nel `.claude/settings.json` o `.claude/settings.local.json` di un repository vengono ignorate.398<span id="ipv6-destinations-in-injecthosts" />Scrivi una destinazione IPv6 diversamente nei due elenchi, perché ogni elenco ha il suo matcher:

399

400* **`network.allowedDomains`**: la [forma tra parentesi che gli elenchi di domini usano](#ipv6-addresses-in-domain-lists), come `"[::1]"`. Il proxy controlla questo elenco per ammettere la connessione.

401* **`injectHosts`**: l'indirizzo nudo nella sua forma canonica compressa, come `"::1"` o `"2001:db8::1"`. Il proxy confronta ogni voce con l'indirizzo di destinazione nudo della connessione, ignorando le porte, quindi una forma tra parentesi, con ID zona o diversamente compressa non corrisponde mai e il proxy non inietta mai la credenziale lì.

402

403`claude doctor` contrassegna le voci `injectHosts` che non possono mai corrispondere con l'avviso `Sandbox credential injectHosts entries can never match their destination`. Questo controllo richiede Claude Code v2.1.229 o successivo.

404

405A differenza di `deny`, la mascheratura autorizza il proxy a inviare la tua credenziale reale agli host elencati, quindi Claude Code la onora solo dalle impostazioni che tu o il tuo amministratore controllate: impostazioni utente, impostazioni gestite e il flag CLI `--settings`. Claude Code ignora le voci `mask` nel `.claude/settings.json` o `.claude/settings.local.json` di un repository. In quei file ignora anche `network.tlsTerminate` e [`credentials.allowPlaintextInject`](/docs/it/settings-reference#sandbox-credentials-allowplaintextinject), l'impostazione che consente al proxy di iniettare credenziali in richieste non crittografate. Se [escludi le impostazioni utente](#configure-sandboxing), Claude Code elimina anche le voci `mask` delle variabili di ambiente in `~/.claude/settings.json`.

406

407Quando il tuo amministratore fornisce voci `mask`, `network.tlsTerminate` o `credentials.allowPlaintextInject` attraverso le impostazioni gestite dal server, contano come [impostazioni che richiedono approvazione](/docs/it/server-managed-settings#security-approval-dialogs).

268 408

269Quando la stessa variabile è elencata con `deny` in qualsiasi ambito, `deny` ha la precedenza.409Quando la stessa variabile è elencata con `deny` in qualsiasi ambito, `deny` ha la precedenza.

270 410

411La mascheratura sostituisce l'intero valore della variabile per impostazione predefinita, il che si adatta a un token nudo. I campi di voce opzionali, che richiedono Claude Code v2.1.224 o successivo, gestiscono valori con struttura:

412

413* `extract`: un'espressione regolare che Claude Code applica su tutto il valore, sostituendo solo il testo catturato dal gruppo 1 di ogni corrispondenza, quindi uno strumento che analizza il valore, come una stringa di connessione `DATABASE_URL`, continua a funzionare all'interno della sandbox. Il pattern deve contenere almeno un gruppo di cattura.

414* `onExtractNoMatch` controlla cosa accade quando il pattern non corrisponde a nulla:

415 * `warn`, il valore predefinito, avverte e passa la variabile attraverso senza mascheratura

416 * `deny` non imposta la variabile all'interno della sandbox

417 * `error` interrompe il setup della sandbox finché non fissi la configurazione

418* `decode: "jwt"`: per una variabile che contiene un JSON Web Token (JWT). Claude Code verifica che il valore sia un JWT e lo sostituisce con un token falso strutturalmente valido, quindi il codice all'interno della sandbox che decodifica il token continua a funzionare. Aggiungi `maskClaims` per elencare i claim del payload di livello superiore da mascherare individualmente invece di sostituire l'intero token; gli altri claim rimangono leggibili. Quando il valore non si verifica come JWT, o nessun claim elencato corrisponde, Claude Code passa la variabile attraverso senza mascheratura con un avviso. `decode` non può essere combinato con `extract`.

419

420Vedi le [righe `credentials.envVars[]` nel riferimento delle impostazioni](/docs/it/settings-reference#sandbox-settings) per l'elenco completo dei campi.

421

422<h4 id="re-sign-aws-requests">

423 Firma di nuovo le richieste AWS

424</h4>

425

426Le richieste AWS portano firme SigV4 sui contenuti della richiesta, quindi maschera `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY` insieme. Il proxy rileva una richiesta SigV4 dalla sentinella della chiave di accesso e la firma di nuovo dopo aver sostituito i valori reali. Mascherare solo il segreto lascia le richieste firmate con il segnaposto, che il proxy non può rilevare, quindi falliscono su AWS; Claude Code avverte di questo caso all'avvio, ma non quando solo l'ID della chiave di accesso è mascherato. Una richiesta rilevata che il proxy non può firmare di nuovo, come una senza il suo header `x-amz-date`, fallisce con un errore del proxy invece di raggiungere il server con una firma rotta.

427

428Claude Code collega le variabili convenzionali `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN` in una credenziale automaticamente quando mascheri i loro interi valori. Se la tua credenziale AWS si trova in variabili con altri nomi, raggruppale tu stesso con [`credentials.awsPairs`](/docs/it/settings-reference#sandbox-credentials-awspairs), che richiede Claude Code v2.1.224 o successivo. Questo esempio aggiunge l'accoppiamento a una configurazione che già maschera `MY_KEY_ID`, `MY_SECRET_KEY` e `MY_SESSION_TOKEN` a valore intero, come nella [configurazione di mascheratura sopra](#mask-environment-variables):

429

430```json theme={null}

431{

432 "sandbox": {

433 "credentials": {

434 "awsPairs": [

435 {

436 "accessKeyIdVar": "MY_KEY_ID",

437 "secretAccessKeyVar": "MY_SECRET_KEY",

438 "sessionTokenVar": "MY_SESSION_TOKEN"

439 }

440 ]

441 }

442 }

443}

444```

445

446Ogni voce segue queste regole:

447

448* `accessKeyIdVar` e `secretAccessKeyVar` nominano le voci `envVars` mascherate che contengono l'ID della chiave di accesso e la chiave segreta. L'opzionale `sessionTokenVar` nomina la voce che contiene il token di sessione per le credenziali temporanee; quando impostato, il proxy invia il token reale come `x-amz-security-token` sulle richieste firmate di nuovo.

449* Ogni variabile nominata deve essere una voce `mask` che maschera il suo intero valore, senza `extract` o `decode`.

450* Il proxy firma di nuovo le richieste sugli host elencati nella voce `injectHosts` dell'ID della chiave di accesso.

451* Nominare una qualsiasi delle variabili convenzionali in una coppia sostituisce l'accoppiamento automatico.

452

453Come le voci `mask`, `awsPairs` è onorato solo dalle impostazioni utente, dalle impostazioni gestite e dal flag CLI `--settings`.

454

455Tre forme di richiesta AWS portano firme che il proxy non può ricalcolare. Quando tale richiesta è firmata con il segnaposto di una coppia mascherata, il proxy la fallisce piuttosto che inoltrarla con una firma rotta; le richieste firmate con credenziali non mascherate non sono mai interessate. L'impostazione [`credentials.sigv4`](/docs/it/settings-reference#sandbox-credentials-sigv4), che richiede Claude Code v2.1.224 o successivo, rilassa questo per forma: impostare la chiave di una forma su `passthrough` inoltra la richiesta con la sua firma derivata dal segnaposto, quindi lo strumento che chiama riceve la propria risposta di rifiuto di AWS invece di un errore del proxy. Come `awsPairs`, `sigv4` è onorato solo dalle impostazioni utente, dalle impostazioni gestite e dal flag CLI `--settings`.

456

457| Forma di richiesta | Chiave `sigv4` | Perché il proxy non può firmarla di nuovo |

458| :----------------------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------- |

459| caricamenti di streaming aws-chunked | `streaming` | Le firme per chunk si concatenano dalla firma del seed, quindi la firma di nuovo richiederebbe la riscrittura del corpo |

460| URL prescritti | `presigned` | La firma si trova nell'URL stesso, senza header `Authorization` |

461| Firme asimmetriche SigV4A | `sigv4a` | Non esiste un HMAC a chiave condivisa da ricalcolare |

462

463<h4 id="mask-credential-files">

464 Maschera i file di credenziali

465</h4>

466

467Le voci dei file accettano anche `"mode": "mask"`, che richiede Claude Code v2.1.221 o successivo. Ciò che un comando in sandbox vede dipende dalla piattaforma:

468

469* **Linux e WSL2**: i comandi in sandbox leggono una copia sentinella del file, un sostituto il cui segreto è sostituito con un valore segnaposto, e il [proxy della sandbox](#network-isolation) sostituisce il valore reale all'uscita.

470* **macOS**: i comandi in sandbox non possono leggere il file elencato. Claude Code non costruisce nessuna copia sentinella e non sostituisce nulla all'uscita, quindi gli strumenti che si autenticano con il file non funzionano all'interno della sandbox, lo stesso effetto di `deny`. A differenza di una voce `deny`, il blocco di lettura si mantiene anche quando [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation).

471

472Su ogni piattaforma, Claude Code applica il requisito [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) e `injectHosts` nello stesso modo che per le [variabili di ambiente mascherate](#mask-environment-variables), e ignora le impostazioni del repository nello stesso modo. Se [escludi le impostazioni utente](#configure-sandboxing), Claude Code mantiene le voci `mask` del file in `~/.claude/settings.json` come restrizioni, ma le voci non autorizzano più il proxy a sostituire il valore reale.

473

474L'esempio seguente maschera un token GitHub memorizzato in `~/.config/gh/hosts.yml`; il pattern `extract`, coperto di seguito, dice a Claude Code quale parte del file è il segreto. Su Linux e WSL2, i comandi in sandbox che leggono il file ottengono una sentinella al posto del token, e il proxy sostituisce il token reale sulle richieste a `api.github.com`:

475

476```json theme={null}

477{

478 "sandbox": {

479 "enabled": true,

480 "network": {

481 "tlsTerminate": {},

482 "allowedDomains": ["*.github.com"]

483 },

484 "credentials": {

485 "files": [

486 {

487 "path": "~/.config/gh/hosts.yml",

488 "mode": "mask",

489 "extract": "oauth_token:\\s*(\\S+)",

490 "injectHosts": ["api.github.com"]

491 }

492 ]

493 }

494 }

495}

496```

497

498Per confermare che la maschera è attiva, chiedi a Claude di eseguire `cat ~/.config/gh/hosts.yml` in un comando in sandbox: su Linux e WSL2 l'output mostra un valore sentinella al posto del token, e su macOS la lettura fallisce invece.

499

500Su Linux e WSL2, il pattern `extract` è ciò che mantiene il resto di `hosts.yml` leggibile. Claude Code applica l'espressione regolare su tutto il file e sostituisce solo il testo catturato dal gruppo 1 di ogni corrispondenza, quindi `gh` continua a analizzare la sua configurazione e solo il token è un segnaposto. Usa `extract` per qualsiasi file strutturato che gli strumenti analizzano, come `.netrc`, JSON o YAML; il pattern deve contenere almeno un gruppo di cattura. Senza `extract`, Claude Code sostituisce l'intero contenuto del file con un valore sentinella, il che si adatta a un file che contiene un singolo segreto nudo e nient'altro.

501

502Per un file che contiene un JSON Web Token (JWT), imposta `decode: "jwt"` invece di, o insieme a, `extract`. `decode` richiede Claude Code v2.1.224 o successivo. Claude Code trova candidati JWT con un pattern integrato, o con il tuo pattern `extract` quando impostato, verifica che ogni candidato sia un JWT, e lo sostituisce con un token falso strutturalmente valido, quindi il codice che decodifica il token all'interno della sandbox continua a funzionare. Aggiungi `maskClaims` per mascherare solo i claim del payload di livello superiore nominati all'interno di ogni token verificato e lascia gli altri claim leggibili. Quando nessun candidato si verifica, o nessun claim nominato corrisponde, il campo `onExtractNoMatch` di seguito governa il risultato, come fa per un pattern che non corrisponde a nulla.

503

504Due campi opzionali affinano come si comporta la corrispondenza. Entrambi si applicano solo quando `mode` è `mask` e `extract` o `decode` è impostato. Su macOS, Claude Code applica le voci `mask` come `deny` prima che il pattern venga eseguito ogni volta che l'isolamento del filesystem è attivo, quindi questi campi, e i risultati di non corrispondenza di seguito, hanno effetto lì solo quando [l'isolamento del filesystem è disattivato](#disable-filesystem-isolation):

505

506* `onExtractNoMatch` controlla cosa accade quando la corrispondenza non trova nulla da mascherare nel file:

507

508 * `warn`, il valore predefinito, avverte e salta la voce, quindi i comandi in sandbox possono leggere il file reale senza mascheratura. Il valore predefinito si adatta alle credenziali che possono essere legittimamente assenti; se il segreto potrebbe essere presente ma il pattern potrebbe perderlo, usa `deny`

509 * `deny` rende il file illeggibile invece

510 * `error` interrompe il setup della sandbox finché non fissi la configurazione

511

512 Claude Code tratta `deny` come `error` ogni volta che il blocco di lettura non sarebbe applicato: quando [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation), e quando una voce `filesystem.allowRead` da qualsiasi fonte di impostazioni riapre il percorso del file.

513* `maskDuplicates` sostituisce anche copie verbatim di ogni valore di credenziale mascherato, un'acquisizione `extract` o un token verificato `decode`, trovato al di fuori degli intervalli corrispondenti, per un segreto ripetuto dove la corrispondenza non raggiunge. Corrisponde a sottostringhe grezze, quindi un valore breve o comune sarebbe sostituito ovunque appaia; riservalo per segreti lunghi e ad alta entropia. Valore predefinito: false.

514

515`mask` si applica a un singolo file, quindi elenca ogni file di credenziale individualmente. Claude Code fallback a `deny` per una voce `mask` che non può mascherare in sicurezza: un percorso di directory, un pattern glob, un file più grande di 8 MiB, o un file che non è testo UTF-8. Scrivi le directory come voci esplicite `deny` invece; la tabella sotto [Quali impostazioni possono disabilitarlo](#which-settings-can-disable-it) copre se ogni forma fissa `filesystem.disabled` e come si comporta con l'isolamento del filesystem disattivato.

516

271<h2 id="how-sandboxing-works">517<h2 id="how-sandboxing-works">

272 Come funziona il sandboxing518 Come funziona il sandboxing

273</h2>519</h2>

278 524

279Lo strumento Bash in sandbox limita l'accesso al file system a directory specifiche:525Lo strumento Bash in sandbox limita l'accesso al file system a directory specifiche:

280 526

281* **Comportamento di scrittura predefinito**: accesso in lettura e scrittura alla directory di lavoro corrente e alle sue sottodirectory, più la directory temporanea della sessione a cui `$TMPDIR` punta527* **Comportamento di scrittura predefinito**: accesso in lettura e scrittura alla directory di lavoro corrente e alle sue sottodirectory, qualsiasi directory aggiunta con `--add-dir`, `/add-dir`, o [`permissions.additionalDirectories`](/docs/it/settings-reference#permissions-additionaldirectories), più la directory temporanea della sessione a cui `$TMPDIR` punta

282* **Comportamento di lettura predefinito**: accesso in lettura all'intero computer, ad eccezione di determinate directory negate. Nota che questo predefinito consente comunque la lettura di file di credenziali come `~/.aws/credentials` e `~/.ssh/`. Utilizza [`sandbox.credentials`](#protect-credentials) per bloccare le letture di questi file e annullare le variabili di ambiente segrete, oppure aggiungi i percorsi a `denyRead`.528* **Comportamento di lettura predefinito**: accesso in lettura all'intero computer, ad eccezione di determinate directory negate. Nota che questo predefinito consente comunque la lettura di file di credenziali come `~/.aws/credentials` e `~/.ssh/`. Utilizza [`sandbox.credentials`](#protect-credentials) per bloccare le letture di questi file e annullare le variabili di ambiente segrete, oppure aggiungi i percorsi a `denyRead`.

283* **Accesso bloccato**: non è possibile modificare file al di fuori della directory di lavoro corrente e della directory temporanea della sessione senza autorizzazione esplicita, inclusi file di configurazione shell come `~/.bashrc` e binari di sistema in `/bin/`529* **Accesso bloccato**: non è possibile modificare file al di fuori della directory di lavoro, delle directory aggiunte e della directory temporanea della sessione senza autorizzazione esplicita, inclusi file di configurazione shell come `~/.bashrc` e binari di sistema in `/bin/`

284* **Git worktrees**: quando la directory di lavoro è un [git worktree collegato](/docs/it/worktrees), la sandbox consente anche scritture nella directory `.git` condivisa del repository principale in modo che comandi come `git commit` possano aggiornare i ref e l'indice. Le scritture in `hooks/` e `config` all'interno di quella directory rimangono negate.530* **Git worktrees**: quando la directory di lavoro è un [git worktree collegato](/docs/it/worktrees), la sandbox consente anche scritture nella directory `.git` condivisa del repository principale in modo che comandi come `git commit` possano aggiornare i ref e l'indice. Le scritture in `hooks/` e `config` all'interno di quella directory rimangono negate.

285* **Configurabile**: definisci percorsi consentiti e negati personalizzati tramite le impostazioni531* **Configurabile**: definisci percorsi consentiti e negati personalizzati tramite le impostazioni

286 532

287Puoi concedere l'accesso in scrittura a percorsi aggiuntivi utilizzando `sandbox.filesystem.allowWrite` nelle impostazioni. Queste restrizioni sono applicate a livello del sistema operativo, quindi si applicano a tutti i comandi dei sottoprocessi, inclusi strumenti come `kubectl`, `terraform` e `npm`, non solo agli strumenti di file di Claude.533Per saltare completamente l'isolamento del file system mantenendo l'isolamento della rete, imposta [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).

534

535<h3 id="protected-paths">

536 Percorsi protetti

537</h3>

538

539All'interno delle directory in cui i comandi in sandbox possono scrivere, la sandbox nega comunque le scritture ai file da cui Claude Code carica la configurazione e il codice. Un comando che potrebbe modificare quei file potrebbe concedere a se stesso le autorizzazioni, oppure aggiungere un hook o un server MCP che Claude Code esegue al di fuori della sandbox. Il sistema di autorizzazione ha i suoi [percorsi protetti](/docs/it/permission-modes#protected-paths), che controllano cosa Claude Code approva prima che uno strumento venga eseguito; l'elenco della sandbox si applica a un comando che è già in esecuzione. Copre quattro gruppi di percorsi:

540

541* **Nella directory di lavoro e nelle directory sopra di essa**: i file di impostazioni `.claude`, le directory `.claude/skills`, `.claude/agents`, `.claude/commands` e `.claude/hooks`, `.mcp.json`, e i file che Claude Code esegue autonomamente, come `.claude/workflows` e `.claude/scheduled_tasks.json`

542* **Solo nella directory di lavoro**: file di avvio shell come `.bashrc` e `.zshrc`, `.gitconfig`, le directory `.vscode` e `.idea`, e `hooks` e `config` all'interno di `.git`

543* **File che trasformerebbero la directory di lavoro in un repository git bare**: `HEAD`, `objects` e `refs` al livello superiore, più `config` e `hooks` lì quando già esistono, anche quando la directory `config` appartiene al progetto piuttosto che a git. Su Linux e WSL2, la sandbox elimina un file `HEAD` di livello superiore o una directory `objects` o `refs` che appare mentre un comando in sandbox è in esecuzione

544* **In `~/.claude`, o nella directory a cui `CLAUDE_CONFIG_DIR` punta**: la maggior parte dei suoi contenuti, più `~/.claude.json` e l'archivio credenziali `.credentials.json`

545

546Se un symlink appare al percorso di un file di impostazioni protetto durante la sessione, la sandbox nega anche le scritture al file a cui punta, a partire dal comando successivo.

547

548Non c'è modo di esentare uno di questi percorsi: una voce `allowWrite` o una regola di autorizzazione `Edit` che copre il percorso non solleva la protezione. L'unico modo per disattivare la protezione è [`filesystem.disabled`](#disable-filesystem-isolation), che disattiva l'isolamento del file system per ogni percorso. Per vedere la maggior parte di questi percorsi risolti per la tua macchina, esegui `/sandbox` e apri la scheda **Config**, che li elenca sotto **Denied within allowed**, mescolati con le tue voci `denyWrite` personali.

549

550Se `git merge` o `git checkout` fallisce con `unable to unlink old` su uno di questi percorsi, vedi [Troubleshooting](#troubleshooting).

288 551

289<h3 id="network-isolation">552<h3 id="network-isolation">

290 Isolamento della rete553 Isolamento della rete

292 555

293L'accesso alla rete è controllato tramite un server proxy in esecuzione al di fuori della sandbox:556L'accesso alla rete è controllato tramite un server proxy in esecuzione al di fuori della sandbox:

294 557

295* **Restrizioni di dominio**: nessun dominio è pre-consentito. La prima volta che un comando ha bisogno di un nuovo dominio, Claude Code richiede l'approvazione. A partire dalla v2.1.191, scegliere Sì consente l'host per il resto della sessione corrente, quindi le connessioni successive allo stesso host non richiedono di nuovo il prompt. Pre-consenti i domini con [`allowedDomains`](/docs/it/settings#sandbox-settings) per evitare completamente il prompt.558* **Restrizioni di dominio**: Claude Code non pre-consente alcun dominio per impostazione predefinita. La prima volta che un comando ha bisogno di un nuovo dominio, Claude Code richiede l'approvazione, oppure in [modalità automatica](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) invia la richiesta al classificatore. Se scegli Sì quando richiesto, Claude Code consente l'host per il resto della sessione corrente e non richiede di nuovo il prompt per le connessioni successive allo stesso host. Se scegli "Sì, e non chiedere di nuovo", Claude Code salva una regola di autorizzazione `WebFetch(domain:...)` alle tue [impostazioni locali](/docs/it/permissions#permission-system), in modo che l'host rimanga consentito nelle sessioni future. Pre-consenti i domini con [`allowedDomains`](/docs/it/settings-reference#sandbox-network-alloweddomains) per evitare completamente il prompt. Claude Code pre-consente anche i domini dalle regole di autorizzazione `WebFetch(domain:...)`, come descritto in [Regole di autorizzazione](#permission-rules).

296* **Blocco gestito**: se [`allowManagedDomainsOnly`](/docs/it/settings#sandbox-settings) è impostato nelle impostazioni gestite, i domini non consentiti vengono bloccati automaticamente invece di richiedere, e solo `allowedDomains` dalle impostazioni gestite vengono rispettati.559* **Allowlist rigoroso**: se imposti [`strictAllowlist`](/docs/it/settings-reference#sandbox-network-strictallowlist) a `true` nelle impostazioni utente, gestite o CLI `--settings`, Claude Code nega ai comandi in sandbox l'accesso a qualsiasi host al di fuori dell'allowlist invece di richiedere. L'allowlist è lo stesso contro cui la sandbox altrimenti richiede: `allowedDomains` più domini dalle regole di autorizzazione `WebFetch(domain:...)`, oppure solo le voci di impostazioni gestite quando `allowManagedDomainsOnly` è impostato. Claude Code applica questo solo ai comandi in sandbox; gli strumenti in-process come `WebFetch` seguono comunque le loro [regole di autorizzazione](#permission-rules). Impostarlo nel `.claude/settings.json` o `.claude/settings.local.json` di un repository non ha effetto. Richiede Claude Code v2.1.219 o successivo.

560* **Blocco gestito**: se [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) è impostato nelle impostazioni gestite, i domini non consentiti vengono bloccati automaticamente invece di richiedere, e solo `allowedDomains` e le regole di autorizzazione `WebFetch(domain:...)` dalle impostazioni gestite vengono rispettati.

561* **Proxy aziendale**: quando la tua rete richiede che il traffico in uscita passi attraverso un proxy aziendale, imposta `HTTPS_PROXY`, `HTTP_PROXY` e `NO_PROXY` come [configurazione proxy](/docs/it/network-config#proxy-configuration) descrive, nel blocco `env` delle tue impostazioni in modo che gli [agenti in background](/docs/it/network-config#set-network-variables-in-settings-not-the-shell) li ottengano anche, oppure nell'ambiente da cui avvii Claude Code. Claude Code applica l'allowlist di dominio e quindi esegue il tunneling delle connessioni consentite attraverso quel proxy upstream.

297* **Supporto proxy personalizzato**: gli utenti avanzati possono implementare regole personalizzate sul traffico in uscita562* **Supporto proxy personalizzato**: gli utenti avanzati possono implementare regole personalizzate sul traffico in uscita

298* **Copertura completa**: le restrizioni si applicano a tutti gli script, programmi e sottoprocessi generati dai comandi563* **Copertura completa**: le restrizioni si applicano a tutti gli script, programmi e sottoprocessi generati dai comandi

299 564

565In una regola `WebFetch(domain:...)`, la sandbox rispetta due forme di wildcard: un `*.` iniziale, come `*.example.com`, e un `*` nudo. La forma `*` nuda richiede Claude Code v2.1.186 o successivo. Un wildcard in qualsiasi altra posizione, come `WebFetch(domain:example.*)`, corrisponde comunque ai fetch ma non ha effetto sui comandi in sandbox.

566

300<Note>567<Note>

301 Il proxy integrato applica l'allowlist in base al nome host richiesto e, per impostazione predefinita, non termina o ispeziona il traffico TLS. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings#sandbox-settings), disponibile in Claude Code v2.1.199 e versioni successive, fa sì che il proxy integrato termini TLS stesso, che le voci di credenziali [`mask`](#protect-credentials) richiedono. Vedi [Limitazioni di sicurezza](#security-limitations) per le implicazioni dell'impostazione predefinita, e [Configurazione proxy personalizzata](#custom-proxy-configuration) se il tuo modello di minaccia richiede l'ispezione TLS.568 Il proxy integrato applica l'allowlist in base al nome host richiesto e, per impostazione predefinita, non termina o ispeziona il traffico TLS. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate), disponibile in Claude Code v2.1.199 e successivo, fa sì che il proxy integrato termini TLS stesso, che le voci di credenziali [`mask`](#mask-credentials) richiedono. Vedi [Limitazioni di sicurezza](#security-limitations) per le implicazioni dell'impostazione predefinita, e [Configurazione proxy personalizzata](#custom-proxy-configuration) se il tuo modello di minaccia richiede l'ispezione TLS.

302</Note>569</Note>

303 570

571<h4 id="ipv6-addresses-in-domain-lists">

572 Indirizzi IPv6 negli elenchi di dominio

573</h4>

574

575Gli elenchi di dominio della sandbox sono `allowedDomains`, `deniedDomains` e le regole `WebFetch(domain:...)` che li alimentano. Per corrispondere a un indirizzo IPv6 in uno qualsiasi di essi, scrivi il letterale tra parentesi: `"[::1]"` corrisponde a quell'indirizzo su ogni porta, e `"[::1]:443"` lo corrisponde sulla porta 443 solo. Scrivi la porta come numero da 1 a 65535 senza zeri iniziali. La forma tra parentesi richiede Claude Code v2.1.229 o successivo. Prima di v2.1.229, quando il testo dopo l'ultimo due punti di una voce non tra parentesi era un numero di porta, Claude Code lo leggeva come uno, quindi `::1:443` denominava l'indirizzo `::1` sulla porta 443.

576

577Quando scegli "Sì, e non chiedere di nuovo" al prompt di approvazione della rete per un indirizzo IPv6, Claude Code salva la regola `WebFetch(domain:...)` con l'indirizzo tra parentesi, in modo che la regola continui a corrispondere all'indirizzo nelle sessioni future.

578

579Una voce non tra parentesi con due o più due punti è ambigua: `::1:443` è sia un indirizzo IPv6 completo che un indirizzo seguito da una porta. Claude Code applica le ortografie ambigue in modo conservativo invece di indovinare quale lettura intendevi:

580

581* **Elenchi di negazione**: Claude Code nega ogni lettura che la voce analizza come, quindi qualunque lettura intendevi è bloccata. Per una voce senza lettura analizzabile, Claude Code non blocca nulla.

582* **Elenchi di consentimento**: Claude Code non consente mai più di quello che hai scritto. Riscrive una voce ambigua alla sua lettura host-e-porta quando quella lettura analizza in modo pulito, e può eliminare completamente la voce piuttosto che ampliare l'allowlist.

583

584Esegui `claude doctor` nel tuo terminale per trovare le voci interessate: l'avviso `Sandbox network domain entries have unreliable spellings` nomina fino a tre di esse e conta il resto. Riscrivi ognuna nella forma tra parentesi per cancellare l'avviso. L'avviso nomina anche voci la cui ortografia è inaffidabile per altri motivi, come `@`, caratteri di percorso o query, o wildcard all'interno di parentesi.

585

304<h3 id="os-level-enforcement">586<h3 id="os-level-enforcement">

305 Applicazione a livello del sistema operativo587 Applicazione a livello del sistema operativo

306</h3>588</h3>

307 589

308Lo strumento Bash in sandbox sfrutta le primitive di sicurezza del sistema operativo:590Lo strumento Bash in sandbox utilizza primitive di sicurezza del sistema operativo:

309 591

310* **macOS**: utilizza Seatbelt per l'applicazione della sandbox592* **macOS**: utilizza Seatbelt per l'applicazione della sandbox

311* **Linux**: utilizza [bubblewrap](https://github.com/containers/bubblewrap) per l'isolamento593* **Linux**: utilizza [bubblewrap](https://github.com/containers/bubblewrap) per l'isolamento

312* **WSL2**: utilizza bubblewrap, come Linux594* **WSL2**: utilizza bubblewrap, come Linux

313 595

314WSL1 non è supportato perché bubblewrap richiede funzionalità del kernel disponibili solo in WSL2. Queste restrizioni a livello del sistema operativo assicurano che tutti i processi figlio generati dai comandi di Claude Code ereditino gli stessi confini di sicurezza.596WSL1 non è supportato perché bubblewrap richiede funzionalità del kernel disponibili solo in WSL2.

315 597

316Questi stessi primitivi sono disponibili come pacchetto standalone [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), che la pagina [Sandbox environments](/docs/it/sandbox-environments#sandbox-runtime) copre come approccio separato per avvolgere l'intero processo di Claude Code.598Questi stessi primitivi sono disponibili come pacchetto standalone [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), che la pagina [Sandbox environments](/docs/it/sandbox-environments#sandbox-runtime) copre come approccio separato per avvolgere l'intero processo di Claude Code.

317 599

327 609

328Le regole di autorizzazione e il sandboxing controllano cose diverse:610Le regole di autorizzazione e il sandboxing controllano cose diverse:

329 611

330* **Le regole di autorizzazione** controllano quali strumenti Claude Code può utilizzare e vengono valutate prima che qualsiasi strumento venga eseguito. Si applicano a tutti gli strumenti: Bash, Read, Edit, WebFetch, MCP e altri.612* **Le regole di autorizzazione** controllano quali strumenti Claude Code può utilizzare e vengono valutate prima che qualsiasi strumento venga eseguito. Si applicano a tutti gli strumenti: Bash, Read, Edit, WebFetch, MCP e altri, tranne per il fatto che una regola di negazione o richiesta non può bloccare [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior) mentre qualsiasi altro strumento rimane.

331* **Il sandboxing** fornisce l'applicazione a livello del sistema operativo che limita ciò che i comandi Bash possono accedere a livello di filesystem e rete. Si applica solo ai comandi Bash e ai loro processi figlio.613* **Il sandboxing** fornisce l'applicazione a livello del sistema operativo che limita ciò che i comandi Bash possono accedere a livello di filesystem e rete. Si applica solo ai comandi Bash e ai loro processi figlio.

332 614

333I due livelli differiscono anche nel modo in cui vengono applicati. Claude Code valuta le decisioni di autorizzazione prima che un comando venga eseguito, in base alla stringa di comando e, in modalità auto, il giudizio di un classificatore separato su se il comando è sicuro. Il sistema operativo applica il confine della sandbox al processo in esecuzione, quindi vale indipendentemente da ciò che il modello ha scelto di eseguire e anche se un comando consentito fa più di quanto il suo nome suggerisca.615I due livelli differiscono anche nel modo in cui vengono applicati. Claude Code valuta le decisioni di autorizzazione prima che un comando venga eseguito, in base alla stringa di comando e, in modalità auto, il giudizio di un classificatore separato su se il comando è sicuro. Il sistema operativo applica il confine della sandbox al processo in esecuzione, quindi vale indipendentemente da ciò che il modello ha scelto di eseguire e anche se un comando consentito fa più di quanto il suo nome suggerisca.

339| `sandbox.filesystem.allowWrite` | Concede l'accesso in scrittura dei sottoprocessi a percorsi al di fuori della directory di lavoro |621| `sandbox.filesystem.allowWrite` | Concede l'accesso in scrittura dei sottoprocessi a percorsi al di fuori della directory di lavoro |

340| `sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead` | Blocca l'accesso dei sottoprocessi a percorsi specifici |622| `sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead` | Blocca l'accesso dei sottoprocessi a percorsi specifici |

624| [`sandbox.filesystem.disabled`](#disable-filesystem-isolation) | Disattiva completamente il livello di filesystem mantenendo l'isolamento di rete |

342| Regole di consentimento `Edit` | Concedono l'accesso in scrittura a percorsi specifici, allo stesso modo di `sandbox.filesystem.allowWrite` |625| Regole di consentimento `Edit` | Concedono l'accesso in scrittura a percorsi specifici, allo stesso modo di `sandbox.filesystem.allowWrite` |

346| Sandbox `deniedDomains` | Blocca domini specifici anche quando un wildcard `allowedDomains` più ampio altrimenti li permetterebbe |629| Sandbox `deniedDomains` | Blocca domini specifici anche quando un wildcard `allowedDomains` più ampio altrimenti li permetterebbe |

347 630

348I percorsi dalle impostazioni `sandbox.filesystem` e dalle regole di autorizzazione vengono uniti insieme nella configurazione finale della sandbox.631I percorsi e i domini dalle impostazioni della sandbox e dalle regole di autorizzazione vengono uniti insieme nella configurazione finale della sandbox.

349 632

350Il [repository claude-code nella directory examples](https://github.com/anthropics/claude-code/tree/main/examples/settings) include configurazioni di impostazioni iniziali per scenari di distribuzione comuni, inclusi esempi specifici della sandbox. Utilizzali come punti di partenza e adattali alle tue esigenze.633Il [repository claude-code nella directory examples](https://github.com/anthropics/claude-code/tree/main/examples/settings) include configurazioni di impostazioni iniziali per scenari di distribuzione comuni, inclusi esempi specifici della sandbox. Utilizzali come punti di partenza e adattali alle tue esigenze.

351 634

356`/sandbox` non è una [modalità di autorizzazione](/docs/it/permission-modes). Le modalità di autorizzazione decidono se una chiamata di strumento viene eseguita e se vieni richiesto prima, mentre la sandbox limita ciò che un comando Bash può accedere una volta che viene eseguito. Differiscono in ciò che controllano e cosa sostituisce il prompt per azione:639`/sandbox` non è una [modalità di autorizzazione](/docs/it/permission-modes). Le modalità di autorizzazione decidono se una chiamata di strumento viene eseguita e se vieni richiesto prima, mentre la sandbox limita ciò che un comando Bash può accedere una volta che viene eseguito. Differiscono in ciò che controllano e cosa sostituisce il prompt per azione:

357 640

358| | Cosa controlla | Cosa sostituisce il prompt |641| | Cosa controlla | Cosa sostituisce il prompt |

359| :--------------------------------------------------------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |642| :--------------------------------------------------------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

362| `--dangerously-skip-permissions` | Se ogni chiamata di strumento viene eseguita | Niente. I controlli di [percorso protetto](/docs/it/permission-modes#protected-paths) vengono anche saltati; solo le [regole ask](/docs/it/permissions#manage-permissions) esplicite, gli strumenti connector [che la tua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), gli strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) e la rimozione di `/` o della tua directory home richiedono comunque un prompt |645| `--dangerously-skip-permissions` | Se ogni chiamata di strumento viene eseguita | Niente. I controlli di [percorso protetto](/docs/it/permission-modes#protected-paths) vengono anche saltati; le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque |

363 646

364La [modalità auto-allow](#sandbox-modes) della sandbox è separata dalla [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): auto-allow approva i comandi Bash perché il confine della sandbox li contiene, mentre la modalità auto utilizza un classificatore per esaminare le azioni. I due funzionano indipendentemente e possono essere combinati. Per scegliere un confine di isolamento per esecuzioni incustodite, vedi [Sandbox environments](/docs/it/sandbox-environments#how-isolation-relates-to-permission-modes).647La [modalità auto-allow](#sandbox-modes) della sandbox è separata dalla [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): auto-allow approva i comandi Bash perché il confine della sandbox li contiene, mentre la modalità auto utilizza un classificatore per esaminare le azioni. I due funzionano indipendentemente e possono essere combinati. Per scegliere un confine di isolamento per esecuzioni incustodite, vedi [Sandbox environments](/docs/it/sandbox-environments#how-isolation-relates-to-permission-modes). Per una tabella degli accoppiamenti comuni tra modalità di autorizzazione e sandbox con i flag che avviano ciascuno, vedi [Common setups](/docs/it/permission-modes#common-setups).

365 648

366<h2 id="configure-the-sandbox-for-your-organization">649<h2 id="configure-the-sandbox-for-your-organization">

367 Configura la sandbox per la tua organizzazione650 Configura la sandbox per la tua organizzazione

373 Enforce sandboxing with managed settings656 Enforce sandboxing with managed settings

374</h3>657</h3>

375 658

376Per richiedere la sandbox per ogni sviluppatore, fornisci le chiavi `sandbox` tramite [impostazioni gestite](/docs/it/settings#settings-files), sia come file gestito dal tuo MDM che tramite [impostazioni gestite dal server](/docs/it/server-managed-settings) su Claude.ai.659Per richiedere la sandbox per ogni sviluppatore, fornisci le chiavi `sandbox` tramite [impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms), sia come file gestito dal tuo MDM che tramite [impostazioni gestite dal server](/docs/it/server-managed-settings) su Claude.ai.

377 660

378La seguente configurazione di impostazioni gestite abilita la sandbox, rifiuta di avviare Claude Code se la sandbox non può inizializzarsi e impedisce al modello di riprovare i comandi al di fuori della sandbox:661La seguente configurazione di impostazioni gestite abilita la sandbox, rifiuta di avviare Claude Code se la sandbox non può inizializzarsi e impedisce al modello di riprovare i comandi al di fuori della sandbox:

379 662

390Le due chiavi oltre `enabled` controllano cosa succede quando la sandbox non può eseguire un comando:673Le due chiavi oltre `enabled` controllano cosa succede quando la sandbox non può eseguire un comando:

391 674

392* **`failIfUnavailable`**: una dipendenza mancante come bubblewrap su Linux blocca l'avvio di Claude Code piuttosto che mostrare un avviso e ricadere nell'esecuzione non sandboxata675* **`failIfUnavailable`**: una dipendenza mancante come bubblewrap su Linux blocca l'avvio di Claude Code piuttosto che mostrare un avviso e ricadere nell'esecuzione non sandboxata

393* **`allowUnsandboxedCommands: false`**: l'escape hatch `dangerouslyDisableSandbox` viene ignorato, quindi i comandi che falliscono sotto la sandbox non possono essere riprovati al di fuori di essa676* **`allowUnsandboxedCommands: false`**: Claude Code ignora l'escape hatch `dangerouslyDisableSandbox`, quindi quando un comando fallisce sotto la sandbox, Claude non può riprovarlo senza sandbox

394 677

395Due aggiunte meritano considerazione insieme a loro. Aggiungi `excludedCommands` per qualsiasi strumento approvato dall'organizzazione che deve essere eseguito senza isolamento. Aggiungi voci [`sandbox.credentials`](#protect-credentials) per directory di credenziali come `~/.aws` e `~/.ssh` e per variabili di ambiente segrete, poiché la politica di lettura predefinita le consente comunque.678Due aggiunte meritano considerazione insieme a loro. Aggiungi `excludedCommands` per qualsiasi strumento approvato dall'organizzazione che deve essere eseguito senza isolamento. Aggiungi voci [`sandbox.credentials`](#protect-credentials) per directory di credenziali come `~/.aws` e `~/.ssh` e per variabili di ambiente segrete, poiché la politica di lettura predefinita le consente comunque.

396 679

680Questa configurazione sandboxa i comandi che Claude esegue. Uno sviluppatore può comunque digitare un comando al [prompt della modalità shell con `!`](/docs/it/interactive-mode#shell-mode-with-prefix) ed eseguirlo al di fuori della sandbox, con lo stesso accesso che ha già in qualsiasi terminale al di fuori di Claude Code. Vedi [L'escape hatch di riprovazione senza sandbox](#the-unsandboxed-retry-escape-hatch) per le sessioni in cui i comandi digitati vengono eseguiti in sandbox.

681

397La sandbox non viene eseguita su Windows nativo, quindi se la tua flotta include host Windows, limita questa configurazione a macOS e Linux o fai in modo che quegli utenti eseguano Claude Code all'interno di WSL2 o di un container.682La sandbox non viene eseguita su Windows nativo, quindi se la tua flotta include host Windows, limita questa configurazione a macOS e Linux o fai in modo che quegli utenti eseguano Claude Code all'interno di WSL2 o di un container.

398 683

399<h3 id="keep-developers-from-widening-the-policy">684<h3 id="keep-developers-from-widening-the-policy">

400 Keep developers from widening the policy685 Keep developers from widening the policy

401</h3>686</h3>

402 687

403Per chiavi booleane come `enabled` e `failIfUnavailable`, Claude Code utilizza il valore gestito e ignora qualsiasi cosa uno sviluppatore imposti localmente. Per chiavi array come `excludedCommands` e `allowRead`, Claude Code unisce le voci da ogni ambito, quindi uno sviluppatore può aggiungere voci che ampliano la politica.688Per chiavi booleane come `enabled` e `failIfUnavailable`, Claude Code utilizza il valore gestito e ignora qualsiasi cosa uno sviluppatore imposti localmente. Per chiavi array come `excludedCommands` e `allowRead`, Claude Code unisce le voci da ogni ambito che la sessione carica, quindi uno sviluppatore può aggiungere voci che ampliano la politica.

689

690Imposta `allowManagedReadPathsOnly` su `true` nelle impostazioni gestite in modo che solo le voci `allowRead` dalle impostazioni gestite vengono rispettate. Questo impedisce agli sviluppatori di ampliare l'accesso in lettura oltre i percorsi approvati dall'organizzazione. Per bloccare i domini di rete ai valori gestiti allo stesso modo, imposta [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly).

404 691

405Imposta `allowManagedReadPathsOnly` su `true` nelle impostazioni gestite in modo che solo le voci `allowRead` dalle impostazioni gestite vengono rispettate. Le voci `allowRead` dell'utente, del progetto e locali vengono ignorate. Questo impedisce agli sviluppatori di ampliare l'accesso in lettura oltre i percorsi approvati dall'organizzazione. Per bloccare i domini di rete ai valori gestiti allo stesso modo, imposta [`allowManagedDomainsOnly`](/docs/it/settings#sandbox-settings).692Quando le impostazioni gestite configurano `sandbox.filesystem` o elencano qualsiasi voce `sandbox.credentials.files` con `"mode": "deny"`, solo le impostazioni gestite possono impostare [`filesystem.disabled`](#disable-filesystem-isolation), quindi gli sviluppatori non possono disattivare le restrizioni del filesystem distribuite dall'amministratore. Se una voce `mask` fissa la chiave dipende da come si risolve; la tabella sotto [Which settings can disable it](#which-settings-can-disable-it) copre i quattro casi.

406 693

407`excludedCommands` non ha un equivalente blocco solo gestito, quindi uno sviluppatore può sempre aggiungere voci che eseguono comandi aggiuntivi al di fuori della sandbox. Mantieni l'elenco gestito ristretto.694`excludedCommands` non ha un equivalente blocco solo gestito, quindi uno sviluppatore può sempre aggiungere voci che eseguono comandi aggiuntivi al di fuori della sandbox. Mantieni l'elenco gestito ristretto.

408 695

417* Registrare tutte le richieste di rete704* Registrare tutte le richieste di rete

418* Integrarsi con l'infrastruttura di sicurezza esistente705* Integrarsi con l'infrastruttura di sicurezza esistente

419 706

420Per puntare Claude Code al tuo proxy, imposta le porte proxy nelle [impostazioni sandbox](/docs/it/settings#sandbox-settings):707Per puntare Claude Code al tuo proxy, imposta le porte proxy nelle [impostazioni sandbox](/docs/it/settings-reference#sandbox-settings):

421 708

422```json theme={null}709```json theme={null}

423{710{

436 723

437Alcuni comandi falliscono all'interno della sandbox anche se funzionano al di fuori di essa. Le correzioni seguenti coprono i casi più comuni.724Alcuni comandi falliscono all'interno della sandbox anche se funzionano al di fuori di essa. Le correzioni seguenti coprono i casi più comuni.

438 725

439* **I comandi falliscono con un errore host-not-allowed**: molti strumenti CLI devono raggiungere host specifici. Concedere l'autorizzazione quando richiesto aggiunge l'host al tuo elenco consentito in modo che lo strumento venga eseguito all'interno della sandbox in futuro.726* **I comandi falliscono con un errore host-not-allowed**: molti strumenti CLI devono raggiungere host specifici. Concedere l'autorizzazione quando richiesto aggiunge l'host al vostro elenco consentito in modo che lo strumento venga eseguito all'interno della sandbox in futuro.

440* **`jest` si blocca o fallisce**: `watchman` è incompatibile con la sandbox. Esegui `jest --no-watchman` invece.727* **`jest` si blocca o fallisce**: `watchman` è incompatibile con la sandbox. Eseguite `jest --no-watchman` invece.

441* **I CLI basati su Go falliscono la verifica TLS su macOS**: strumenti come `gh`, `gcloud` e `terraform` potrebbero fallire la verifica TLS sotto Seatbelt. Elenca questi strumenti in `excludedCommands` per eseguirli al di fuori della sandbox. Se stai utilizzando `httpProxyPort` con un proxy MITM e CA personalizzato, imposta [`enableWeakerNetworkIsolation`](/docs/it/settings#sandbox-settings) su `true` invece.728* **I CLI basati su Go falliscono la verifica TLS su macOS**: strumenti come `gh`, `gcloud` e `terraform` potrebbero fallire la verifica TLS sotto Seatbelt. Elencate questi strumenti in `excludedCommands` per eseguirli al di fuori della sandbox. Se state utilizzando `httpProxyPort` con un proxy MITM e CA personalizzato, impostate [`enableWeakerNetworkIsolation`](/docs/it/settings-reference#sandbox-enableweakernetworkisolation) su `true` invece.

442* **`open`, `osascript`, o i flussi di autenticazione basati su browser falliscono con errore `-600` su macOS**: la sandbox blocca gli Apple Events per impostazione predefinita. Imposta [`allowAppleEvents`](/docs/it/settings#sandbox-settings) su `true` nelle impostazioni utente, gestite o CLI per consentirli. Le impostazioni del progetto vengono ignorate per questa chiave. L'abilitazione rimuove l'isolamento dell'esecuzione del codice, poiché i comandi sandboxati possono quindi avviare altre applicazioni non sandboxate senza prompt dell'utente e inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso dell'automazione macOS (TCC). In alternativa, aggiungi il comando a `excludedCommands` per eseguirlo al di fuori della sandbox.729* **`open`, `osascript`, o i flussi di autenticazione basati su browser falliscono con errore `-600` su macOS**: la sandbox blocca gli Apple Events per impostazione predefinita. Impostate [`allowAppleEvents`](/docs/it/settings-reference#sandbox-allowappleevents) su `true` nelle impostazioni utente, gestite o CLI per consentirli. Le impostazioni del progetto vengono ignorate per questa chiave. L'abilitazione rimuove l'isolamento dell'esecuzione del codice, poiché i comandi sandboxati possono quindi avviare altre applicazioni non sandboxate senza prompt dell'utente e inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso dell'automazione macOS (TCC). In alternativa, aggiungete il comando a `excludedCommands` per eseguirlo al di fuori della sandbox.

443* **I comandi `docker` falliscono**: `docker` è incompatibile con la sandbox. Aggiungi `docker *` a `excludedCommands` per eseguirlo al di fuori della sandbox.730* **I comandi `docker` falliscono**: `docker` è incompatibile con la sandbox. Aggiungete `docker *` a `excludedCommands` per eseguirlo al di fuori della sandbox.

444* **Bubblewrap non riesce ad avviarsi all'interno di un container**: in un container senza privilegi, bubblewrap non può montare un filesystem `/proc` fresco. Imposta [`enableWeakerNestedSandbox`](/docs/it/settings#sandbox-settings) su `true` in modo che la sandbox interna bind-monti il `/proc` esistente del container invece. Utilizza questa impostazione solo quando il container esterno fornisce già il confine di isolamento di cui hai bisogno, poiché espone le informazioni del processo ai comandi sandboxati che un mount `/proc` fresco nasconderebbe.731* **`pbcopy`, `xclip`, o `wl-copy` non aggiorna gli appunti**: queste utilità degli appunti possono non riuscire a raggiungere gli appunti di sistema dall'interno della sandbox, nel qual caso il testo inviato tramite pipe a loro non arriva. Per mettere l'output di Claude negli appunti, chiedete a Claude di stamparlo nella sua risposta, quindi eseguite [`/copy`](/docs/it/commands), che scrive negli appunti dal processo Claude Code piuttosto che da un comando sandboxato. In alternativa, aggiungete `pbcopy *`, `wl-copy *`, o `xclip *` a `excludedCommands` per eseguire il comando al di fuori della sandbox.

445* **Filtro seccomp su Linux**: il filtro seccomp è richiesto per bloccare i socket di dominio Unix. La scheda Dependencies in `/sandbox` mostra se è disponibile. Se manca, esegui `npm install -g @anthropic-ai/sandbox-runtime` per installare l'helper.732* **Un comando git fallisce con `unable to unlink old`**: `git merge`, `git checkout` e comandi simili falliscono in questo modo quando devono sostituire un file a cui la sandbox nega le scritture, sia che il file sia sotto un [percorso protetto](#protected-paths) come `.claude/skills`, sotto una delle vostre voci `denyWrite`, o al di fuori delle directory in cui la sandbox consente ai comandi di scrivere. Su Linux e WSL2 l'errore termina con `Read-only file system`.

446* **`--dangerously-skip-permissions` fallisce come root**: questo flag viene bloccato quando viene eseguito come root o tramite sudo su Linux e macOS, perché l'accesso root combinato con nessun prompt di autorizzazione può modificare qualsiasi file o servizio sul sistema. Il controllo viene saltato automaticamente all'interno di una sandbox riconosciuta. Per eseguire autonomamente in un container, utilizza la configurazione [dev container](/docs/it/devcontainer), che esegue Claude Code come utente non root.733

734 Dopo il fallimento, Claude potrebbe [offrire di rieseguire il comando al di fuori della sandbox](#the-unsandboxed-retry-escape-hatch); approvate quel nuovo tentativo, o eseguite il comando git voi stessi in un altro terminale. Se avete impostato `allowUnsandboxedCommands` su `false`, Claude non può offrire il nuovo tentativo, quindi eseguite il comando voi stessi. Se lo stesso comando git fallisce spesso, aggiungetelo a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands).

735* **Bubblewrap non riesce ad avviarsi all'interno di un container**: in un container senza privilegi, bubblewrap non può montare un filesystem `/proc` fresco, quindi i comandi sandboxati falliscono con un errore `bwrap` come `Can't mount proc on /newroot/proc: Operation not permitted`. Impostate [`enableWeakerNestedSandbox`](/docs/it/settings-reference#sandbox-enableweakernestedsandbox) su `true` in modo che la sandbox interna bind-monti il `/proc` esistente del container invece. Utilizzate questa impostazione solo quando il container esterno fornisce già il confine di isolamento di cui avete bisogno, poiché espone le informazioni del processo ai comandi sandboxati che un mount `/proc` fresco nasconderebbe.

736* **File di sola lettura a 0 byte appaiono nei percorsi delle impostazioni `.claude`, e "Sì, e non chiedere più" non salva**: su Linux e WSL2, la sandbox mantiene un diniego di scrittura su un file che non esiste ancora creando un placeholder di sola lettura a 0 byte lì mentre un comando sandboxato viene eseguito. La sandbox rimuove il placeholder in seguito. Se una sessione viene terminata prima che quella pulizia venga eseguita, ad esempio da SIGKILL, i placeholder rimangono. Le sessioni successive li bind-montano di sola lettura di nuovo ad ogni avvio, quindi una scrittura delle impostazioni come il salvataggio di una scelta di autorizzazione fallisce dove uno si trova.

737

738 Eseguite `claude doctor` per elencare i file placeholder rimasti. L'avviso [`Stale sandbox mask files left by a killed session`](/docs/it/errors#stale-sandbox-mask-files-left-by-a-killed-session) nomina fino a tre di essi e conta il resto. Eliminate ogni file con `rm` mentre nessun'altra sessione Claude Code è in esecuzione in quel progetto. Prima della v2.1.257, Claude Code lasciava gli stessi placeholder dietro senza segnalarli.

739* **`--dangerously-skip-permissions` fallisce come root**: questo flag viene bloccato quando viene eseguito come root o tramite sudo su Linux e macOS, perché l'accesso root combinato con nessun prompt di autorizzazione può modificare qualsiasi file o servizio sul sistema. Il controllo viene saltato automaticamente all'interno di una sandbox riconosciuta. Per eseguire autonomamente in un container, utilizzate la configurazione [dev container](/docs/it/devcontainer), che esegue Claude Code come utente non root.

447 740

448<h2 id="limitations">741<h2 id="limitations">

449 Limitazioni742 Limitazioni

455 Limitazioni di sicurezza748 Limitazioni di sicurezza

456</h3>749</h3>

457 750

458* **Filtraggio della rete**: il sandbox limita i domini a cui i processi possono connettersi. Per impostazione predefinita il proxy integrato non termina o ispeziona TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings#sandbox-settings) termina TLS al proxy per la [sostituzione delle credenziali `mask`](#protect-credentials) ma non aggiunge filtraggio dei contenuti. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.751* **Filtraggio della rete**: il sandbox limita i domini a cui i processi possono connettersi. Per impostazione predefinita il proxy integrato non termina o ispeziona TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) termina TLS al proxy per la [sostituzione delle credenziali `mask`](#mask-credentials) ma non aggiunge filtraggio dei contenuti. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.

459 752

460<Warning>753<Warning>

461 Consentire domini ampi come `github.com` può creare percorsi per l'esfiltrazione di dati. Poiché il proxy prende la sua decisione di consentimento dal nome host fornito dal client senza ispezionare TLS, il codice in esecuzione all'interno della sandbox potrebbe potenzialmente utilizzare [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o tecniche simili per raggiungere host al di fuori dell'allowlist. Se il tuo modello di minaccia richiede garanzie più forti, configura un [proxy personalizzato](#custom-proxy-configuration) che termina TLS e ispeziona il traffico, e installa il suo certificato CA all'interno della sandbox. L'isolamento della rete più consapevole di TLS è un'area di sviluppo attiva.754 Consentire domini ampi come `github.com` può creare percorsi per l'esfiltrazione di dati. Poiché il proxy prende la sua decisione di consentimento dal nome host fornito dal client senza ispezionare TLS, il codice in esecuzione all'interno della sandbox potrebbe potenzialmente utilizzare [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o tecniche simili per raggiungere host al di fuori dell'allowlist. Se il tuo modello di minaccia richiede garanzie più forti, configura un [proxy personalizzato](#custom-proxy-configuration) che termina TLS e ispeziona il traffico, e installa il suo certificato CA all'interno della sandbox. L'isolamento della rete più consapevole di TLS è un'area di sviluppo attiva.

462</Warning>755</Warning>

463 756

464* **Escalation dei privilegi tramite socket Unix**: la configurazione `allowUnixSockets` può inavvertitamente concedere l'accesso a potenti servizi di sistema che potrebbero portare a bypass della sandbox. Ad esempio, consentire l'accesso a `/var/run/docker.sock` concede effettivamente l'accesso al sistema host attraverso il socket Docker. Considera attentamente qualsiasi socket Unix che consenti attraverso la sandbox.757* **Escalation dei privilegi tramite socket Unix**: la configurazione `allowUnixSockets` può inavvertitamente concedere l'accesso a servizi di sistema che potrebbero portare a bypass della sandbox. Ad esempio, consentire l'accesso a `/var/run/docker.sock` concede effettivamente l'accesso al sistema host attraverso il socket Docker. Considera attentamente qualsiasi socket Unix che consenti attraverso la sandbox.

465* **Escalation dei permessi del filesystem**: i permessi di scrittura del filesystem eccessivamente ampi possono abilitare attacchi di escalation dei privilegi. Consentire scritture a directory contenenti eseguibili in `$PATH`, directory di configurazione di sistema o file di configurazione della shell dell'utente come `.bashrc` o `.zshrc` può portare all'esecuzione di codice in diversi contesti di sicurezza quando altri utenti o processi di sistema accedono a questi file.758* **Escalation dei permessi del filesystem**: i permessi di scrittura del filesystem eccessivamente ampi possono abilitare attacchi di escalation dei privilegi. Consentire scritture a directory contenenti eseguibili in `$PATH`, directory di configurazione di sistema o file di configurazione della shell dell'utente come `.bashrc` o `.zshrc` può portare all'esecuzione di codice in diversi contesti di sicurezza quando altri utenti o processi di sistema accedono a questi file.

466* **Forza della sandbox Linux**: l'implementazione Linux fornisce un forte isolamento del filesystem e della rete ma include una modalità `enableWeakerNestedSandbox` che le consente di funzionare all'interno di ambienti Docker senza namespace privilegiati, o su host Linux dove gli spazi dei nomi utente senza privilegi sono disabilitati da sysctl. Questa opzione indebolisce considerevolmente la sicurezza e dovrebbe essere utilizzata solo quando l'isolamento aggiuntivo è altrimenti applicato.759* **Forza della sandbox Linux**: l'implementazione Linux fornisce un forte isolamento del filesystem e della rete ma include una modalità `enableWeakerNestedSandbox` che le consente di funzionare all'interno di ambienti Docker senza namespace privilegiati, o su host Linux dove gli spazi dei nomi utente senza privilegi sono disabilitati da sysctl. Questa opzione indebolisce considerevolmente la sicurezza e dovrebbe essere utilizzata solo quando l'isolamento aggiuntivo è altrimenti applicato.

467* **Apple Events su macOS**: la sandbox macOS blocca gli Apple Events per impostazione predefinita. L'impostazione `allowAppleEvents` rimuove questa restrizione in modo che strumenti come `open` e `osascript` funzionino, ma rimuove l'isolamento dell'esecuzione del codice: i comandi sandboxati possono avviare altre applicazioni senza sandbox senza alcun prompt dell'utente, e possono inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso per l'automazione macOS per app (TCC). È onorato solo dalle impostazioni utente, gestite o CLI. Le impostazioni del progetto non possono abilitarlo.760* **Apple Events su macOS**: la sandbox macOS blocca gli Apple Events per impostazione predefinita. L'impostazione `allowAppleEvents` rimuove questa restrizione in modo che strumenti come `open` e `osascript` funzionino, ma rimuove l'isolamento dell'esecuzione del codice: i comandi sandboxati possono avviare altre applicazioni senza sandbox senza alcun prompt dell'utente, e possono inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso per l'automazione macOS per app (TCC). È onorato solo dalle impostazioni utente, gestite o CLI. Le impostazioni del progetto non possono abilitarlo.

468* **File di impostazioni protetti**: la sandbox nega automaticamente l'accesso in scrittura ai file `settings.json` di Claude Code a ogni ambito e alla directory delle impostazioni gestite, quindi un comando sandboxato non può modificare la sua stessa politica.

469 761

470<h3 id="platform-and-tool-compatibility">762<h3 id="platform-and-tool-compatibility">

471 Compatibilità della piattaforma e degli strumenti763 Compatibilità della piattaforma e degli strumenti

483 775

484* **Strumenti di file integrati**: Read, Edit e Write utilizzano il sistema di autorizzazione direttamente piuttosto che eseguire attraverso la sandbox. Vedi [permissions](/docs/it/permissions).776* **Strumenti di file integrati**: Read, Edit e Write utilizzano il sistema di autorizzazione direttamente piuttosto che eseguire attraverso la sandbox. Vedi [permissions](/docs/it/permissions).

485* **Utilizzo del computer**: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. I prompt di autorizzazione per app gating ogni applicazione. Vedi [computer use nella CLI](/docs/it/computer-use) o [computer use in Desktop](/docs/it/desktop#let-claude-use-your-computer).777* **Utilizzo del computer**: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. I prompt di autorizzazione per app gating ogni applicazione. Vedi [computer use nella CLI](/docs/it/computer-use) o [computer use in Desktop](/docs/it/desktop#let-claude-use-your-computer).

486* **Variabili di ambiente**: i comandi Bash sandboxati ereditano l'ambiente del processo padre per impostazione predefinita, incluse le credenziali impostate lì. Usa [`sandbox.credentials`](#protect-credentials) per annullare o mascherare variabili specifiche per i comandi sandboxati, o imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) per rimuovere le credenziali di Anthropic e del provider cloud dai sottoprocessi.778* **Variabili di ambiente**: i comandi Bash sandboxati ereditano l'ambiente del processo padre per impostazione predefinita, incluse le credenziali impostate lì. Usa [`sandbox.credentials`](#protect-credentials) per annullare o mascherare variabili specifiche per i comandi sandboxati, o imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) per rimuovere le credenziali dai sottoprocessi.

487* **Subagenti**: i [subagenti](/docs/it/sub-agents) vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagente vengono sandboxati quando il sandboxing è abilitato nella sessione padre.779* **Subagenti**: i [subagenti](/docs/it/sub-agents) vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagente vengono sandboxati quando il sandboxing è abilitato nella sessione padre.

488 780

489<Warning>781<Warning>

490 Il sandboxing efficace richiede sia l'isolamento del filesystem che della rete. Senza isolamento della rete, un agente compromesso potrebbe esfiltare file sensibili come chiavi SSH. Senza isolamento del filesystem, un agente compromesso potrebbe backdoor le risorse di sistema per ottenere accesso alla rete. Quando ampli i predefiniti, verifica che un percorso `allowWrite`, una voce `allowedDomains` ampia o un'eccezione `excludedCommands` non annulli una restrizione dall'altro lato.782 Il sandboxing efficace richiede sia l'isolamento del filesystem che della rete. Senza isolamento della rete, un agente compromesso potrebbe esfiltare file sensibili come chiavi SSH. Senza isolamento del filesystem, sia da una politica permissiva che da [disabilitazione del livello filesystem](#disable-filesystem-isolation), un agente compromesso potrebbe backdoor le risorse di sistema per ottenere accesso alla rete. Quando ampli i predefiniti, verifica che un percorso `allowWrite`, una voce `allowedDomains` ampia o un'eccezione `excludedCommands` non annulli una restrizione dall'altro lato.

491</Warning>783</Warning>

492 784

493<h2 id="see-also">785<h2 id="see-also">

497* [Sandbox environments](/docs/it/sandbox-environments): confronta la sandbox integrata con dev container, container e VM789* [Sandbox environments](/docs/it/sandbox-environments): confronta la sandbox integrata con dev container, container e VM

498* [Security](/docs/it/security): funzionalità di sicurezza complete e best practice790* [Security](/docs/it/security): funzionalità di sicurezza complete e best practice

499* [Permissions](/docs/it/permissions): configurazione delle autorizzazioni e controllo dell'accesso791* [Permissions](/docs/it/permissions): configurazione delle autorizzazioni e controllo dell'accesso

500* [Settings](/docs/it/settings): riferimento di configurazione completo792* [All settings](/docs/it/settings-reference): ogni chiave di configurazione

501* [CLI reference](/docs/it/cli-reference): opzioni della riga di comando793* [CLI reference](/docs/it/cli-reference): opzioni della riga di comando

scheduled-tasks.md +15 −15

Details

8 8

9Le attività pianificate consentono a Claude di rieseguire automaticamente un prompt a intervalli regolari. Utilizzarle per eseguire il polling di una distribuzione, monitorare una PR, controllare una compilazione a lunga esecuzione o ricordarsi di fare qualcosa più tardi nella sessione. Per reagire agli eventi man mano che si verificano invece di eseguire il polling, vedere [Channels](/docs/it/channels): il vostro CI può inviare il fallimento direttamente nella sessione. Per mantenere la sessione in funzione turno dopo turno fino al raggiungimento di una condizione piuttosto che a intervalli, vedere [`/goal`](/docs/it/goal).9Le attività pianificate consentono a Claude di rieseguire automaticamente un prompt a intervalli regolari. Utilizzarle per eseguire il polling di una distribuzione, monitorare una PR, controllare una compilazione a lunga esecuzione o ricordarsi di fare qualcosa più tardi nella sessione. Per reagire agli eventi man mano che si verificano invece di eseguire il polling, vedere [Channels](/docs/it/channels): il vostro CI può inviare il fallimento direttamente nella sessione. Per mantenere la sessione in funzione turno dopo turno fino al raggiungimento di una condizione piuttosto che a intervalli, vedere [`/goal`](/docs/it/goal).

10 10

11Le attività hanno ambito di sessione: vivono nella conversazione corrente e si interrompono quando si avvia una nuova. La ripresa con `--resume` o `--continue` ripristina qualsiasi attività che non sia [scaduta](#seven-day-expiry): un'attività ricorrente creata negli ultimi 7 giorni, oppure una singola la cui ora pianificata non è ancora passata. Per la pianificazione che sopravvive indipendentemente da qualsiasi sessione, utilizzare [Routines](/docs/it/routines) per creare una routine su infrastruttura gestita da Anthropic, configurare un'[Attività pianificata Desktop](/docs/it/desktop-scheduled-tasks) o utilizzare [GitHub Actions](/docs/it/github-actions).11Le attività hanno ambito di sessione: vivono nella conversazione corrente e si interrompono quando si avvia una nuova. Quando si riprende con `--resume` o `--continue`, Claude Code ripristina le attività che non hanno [scaduto](#seven-day-expiry), ad eccezione di quelle elencate in [Limitazioni](#limitations). Per la pianificazione che sopravvive indipendentemente da qualsiasi sessione, utilizzare [Routines](/docs/it/routines) per creare una routine nel cloud, configurare un'[Attività pianificata Desktop](/docs/it/desktop-scheduled-tasks) o utilizzare [GitHub Actions](/docs/it/github-actions).

12 12

13<h2 id="compare-scheduling-options">13<h2 id="compare-scheduling-options">

14 Confrontare le opzioni di pianificazione14 Confrontare le opzioni di pianificazione

15</h2>15</h2>

16 16

~~17Claude Code offers three ways to schedule recurring or one-off work:~~17Claude Code offre tre modi per pianificare lavori ricorrenti o una tantum:

18 18

~~22| Requires machine on | No | Yes | Yes |~~22| Richiede macchina accesa | No | Sì | Sì |

~~23| Requires open session | No | No | Yes |~~23| Richiede sessione aperta | No | No | Sì |

~~25| Access to local files | No (fresh clone) | Yes | Yes |~~25| Accesso ai file locali | No (clone fresco) | Sì | Sì |

~~28| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |~~28| Pianificazione personalizzabile | Via `/schedule` nella CLI | Sì | Sì |

30 30

31<Tip>31<Tip>

33</Tip>33</Tip>

34 34

35<h2 id="run-a-prompt-repeatedly-with-/loop">35<h2 id="run-a-prompt-repeatedly-with-/loop">

237 237

238* Le attività si attivano solo mentre Claude Code è in esecuzione e inattivo. La chiusura del terminale o l'uscita dalla sessione le interrompe. [Mettere in background la sessione](/docs/it/agent-view#from-inside-a-session) trasporta le attività `/loop` a una sessione in background, che continua a funzionare senza un terminale.238* Le attività si attivano solo mentre Claude Code è in esecuzione e inattivo. La chiusura del terminale o l'uscita dalla sessione le interrompe. [Mettere in background la sessione](/docs/it/agent-view#from-inside-a-session) trasporta le attività `/loop` a una sessione in background, che continua a funzionare senza un terminale.

239* Nessun recupero per attivazioni perse. Se l'ora pianificata di un'attività passa mentre Claude è occupato in una richiesta a lunga esecuzione, si attiva una sola volta quando Claude diventa inattivo, non una volta per ogni intervallo perso.239* Nessun recupero per attivazioni perse. Se l'ora pianificata di un'attività passa mentre Claude è occupato in una richiesta a lunga esecuzione, si attiva una sola volta quando Claude diventa inattivo, non una volta per ogni intervallo perso.

240* L'avvio di una nuova conversazione cancella tutte le attività con ambito di sessione. La ripresa con `claude --resume` o `claude --continue` ripristina le attività ricorrenti che non hanno [scaduto](#seven-day-expiry) e le attività una tantum la cui ora pianificata non è ancora passata. Le attività Bash in background e monitor non vengono mai ripristinate al riavvio.240* L'avvio di una nuova conversazione cancella tutte le attività con ambito di sessione. Quando si riprende una sessione con `claude --resume` o `claude --continue`, Claude Code ripristina le attività pianificate con `CronCreate`, ad eccezione delle attività ricorrenti che hanno [scaduto](#seven-day-expiry) e delle attività una tantum la cui ora pianificata è già passata. Un `/loop` [auto-regolato](#let-claude-choose-the-interval) non viene ripristinato, quindi eseguire `/loop` di nuovo per riavviarlo. Le attività Bash in background e monitor non vengono mai ripristinate al riavvio.

241* Con il [recupero dei feature flag disattivato](/docs/it/env-vars#features-that-need-feature-flag-fetching), Claude Code memorizza un'attività che hai chiesto di mantenere tra le sessioni nella directory `.claude` del progetto. Quando quella directory o il file dell'attività in essa è un symlink, Claude Code restituisce un errore invece di pianificare l'attività.241* Con il [recupero dei feature flag disattivato](/docs/it/env-vars#features-that-need-feature-flag-fetching), Claude Code memorizza un'attività che hai chiesto di mantenere tra le sessioni nella directory `.claude` del progetto. Quando quella directory o il file dell'attività in essa è un symlink, Claude Code restituisce un errore invece di pianificare l'attività.

242 242

243Per l'automazione basata su cron che deve essere eseguita senza supervisione:243Per l'automazione basata su cron che deve essere eseguita senza supervisione:

security.md +1 −1

Details

60* **Sistema di permessi**: In Manual mode, le operazioni sensibili richiedono un'approvazione esplicita60* **Sistema di permessi**: In Manual mode, le operazioni sensibili richiedono un'approvazione esplicita

61* **Analisi consapevole del contesto**: Rileva istruzioni potenzialmente dannose analizzando la richiesta completa61* **Analisi consapevole del contesto**: Rileva istruzioni potenzialmente dannose analizzando la richiesta completa

62* **Sanitizzazione dell'input**: Previene l'iniezione di comandi elaborando gli input dell'utente62* **Sanitizzazione dell'input**: Previene l'iniezione di comandi elaborando gli input dell'utente

63* **Approvazione dei comandi di rete**: I comandi che recuperano contenuti dal web come `curl` e `wget` non sono approvati automaticamente per impostazione predefinita. In Manual mode richiedono un'approvazione come qualsiasi altro comando Bash non di sola lettura, quindi è possibile comunque approvarli una volta o aggiungere una regola di autorizzazione esplicita come `Bash(curl *)`. Per bloccarli completamente, aggiungeteli a [`permissions.deny`](/docs/it/permissions#tool-specific-permission-rules)63* **Approvazione dei comandi di rete**: I comandi che recuperano contenuti dal web come `curl` e `wget` non sono approvati automaticamente per impostazione predefinita. In Manual mode richiedono un'approvazione come qualsiasi altro comando Bash non di sola lettura, quindi è possibile comunque approvarli una volta o aggiungere una regola di autorizzazione esplicita come `Bash(curl *)`. Per bloccarli completamente, aggiungeteli a [`permissions.deny`](/docs/it/permissions#tool-specific-permission-rules). Una regola di negazione corrisponde al comando [come scritto](/docs/it/permissions#bash-rule-limits); per l'applicazione della rete che non dipende dal testo del comando, vedere [isolamento della rete sandbox](/docs/it/sandboxing#network-isolation)

64 64

65<h3 id="privacy-safeguards">65<h3 id="privacy-safeguards">

66 Misure di protezione della privacy66 Misure di protezione della privacy

security-guidance.md +1 −5

Details

43* `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.43* `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

44* Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.44* Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.

45 45

~~46Controlla il riepilogo dell'installazione. Se segnala `Run /reload-plugins to activate.`, applica la modifica in sospeso senza un riavvio:~~46Controlla il riepilogo dell'installazione. Se segnala `Run /reload-plugins to activate.`, consulta [Applica le modifiche ai plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) per attivare il plugin nella tua sessione corrente.

~~48```text theme={null}~~

~~49/reload-plugins~~

~~50```~~

51 47

52<h3 id="enable-in-cloud-sessions-and-shared-repositories">48<h3 id="enable-in-cloud-sessions-and-shared-repositories">

53 Abilita nelle sessioni cloud e nei repository condivisi49 Abilita nelle sessioni cloud e nei repository condivisi

self-hosted-environments.md +164 −0 created

Details

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.

5# Ambienti self-hosted

7> Esegui sessioni cloud di Claude Code su infrastrutture che controlli: configura un ambiente self-hosted, distribuisci runner e instrada le sessioni al tuo calcolo.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise e sono disabilitati per impostazione predefinita. Vedi [Disponibilità e limitazioni](#availability-and-limitations) per il percorso di abilitazione e cosa è escluso.

11</Note>

13Un ambiente self-hosted esegue sessioni cloud di Claude Code su infrastrutture che la tua organizzazione gestisce. Una [sessione cloud](/docs/it/claude-code-on-the-web) è qualsiasi sessione che viene eseguita in un luogo diverso dalla macchina dello sviluppatore: gli sviluppatori le avviano da claude.ai, dalle app mobile e desktop, dal terminale con [`claude --cloud`](/docs/it/claude-code-on-the-web#from-terminal-to-web), e da [routine pianificate](/docs/it/routines), e per impostazione predefinita vengono eseguite su infrastrutture di Anthropic. In un ambiente self-hosted, quelle stesse sessioni vengono eseguite all'interno della tua rete, e l'esperienza dello sviluppatore è altrimenti la stessa a parte le differenze in [Disponibilità e limitazioni](#availability-and-limitations) e i [problemi noti](/docs/it/self-hosted-environments-deploy#known-issues-and-limitations) della pagina di distribuzione.

15Se il tuo team non utilizza sessioni cloud, non c'è nulla da configurare qui: le sessioni in un terminale o IDE vengono sempre eseguite sulla macchina dello sviluppatore. Se desideri eseguire Claude Code sulla tua macchina sempre accesa e controllarla da altri dispositivi, utilizza [Remote Control](/docs/it/remote-control), che è disponibile anche sui piani Pro e Max. Quando sei pronto per la configurazione, vai direttamente alla [guida rapida](/docs/it/self-hosted-environments-quickstart); per rivedere prima il profilo di sicurezza, inizia con [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy). Il resto di questa pagina spiega come funziona il self-hosting e quando sceglierlo.

17<h2 id="how-self-hosted-environments-work">

18 Come funzionano gli ambienti self-hosted

19</h2>

21Il self-hosting ha tre parti:

23* **Environment**: una destinazione denominata a cui possono essere inviate sessioni cloud. La tua organizzazione crea ambienti nelle impostazioni di amministrazione di claude.ai, e ognuno raggruppa un insieme di runner.

24* **Runner**: un programma in esecuzione su host all'interno della tua rete. I runner eseguono le sessioni; l'idea è la stessa di un runner CI self-hosted.

25* **Session**: un'attività Claude Code avviata da uno sviluppatore.

27Quando uno sviluppatore avvia una sessione cloud, l'interfaccia utente di avvio della sessione mostra un selettore di ambiente che elenca gli ambienti ospitati da Anthropic insieme a quelli creati dalla tua organizzazione. Se scelgono il tuo, il piano di controllo di Anthropic posiziona la sessione nella coda del tuo ambiente, dove un runner la rivendica, clona il repository scelto dallo sviluppatore e avvia un processo Claude Code sul tuo host per eseguirlo. Il runner si autentica al tuo host git con credenziali che configuri; [Configura git](/docs/it/self-hosted-environments-deploy#configure-git) copre le opzioni. Le sessioni raggiungono i tuoi servizi interni dall'interno della tua rete, e il tuo host git allo stesso modo quando è interno; il traffico verso Anthropic, il polling della coda, il flusso di eventi della sessione e l'inferenza del modello, è HTTPS in uscita verso `api.anthropic.com`, con il breve elenco di ulteriori host che le sessioni possono raggiungere in [Requisiti di rete](/docs/it/self-hosted-environments-deploy#network-requirements). Anthropic non si connette mai alla tua rete.

29<div style={{maxWidth: "640px", margin: "0 auto"}}>

30 <Frame>

31 <img src="https://mintcdn.com/claude-code/Y0sJ2uDoOVbOVZrQ/images/self-hosted-network-paths.svg?fit=max&auto=format&n=Y0sJ2uDoOVbOVZrQ&q=85&s=8056103fc1c5564c7f0ef219d260b99d" className="dark:hidden" alt="Diagramma dell'architettura di un ambiente self-hosted: il confine della tua rete contiene un runner, due processi di sessione Claude Code al suo interno e il tuo host git, con api.anthropic.com all'esterno che contiene coda, flusso di sessione e inferenza. Il runner esegue il polling della coda e raggiunge l'host git, ogni processo di sessione apre le proprie connessioni di flusso, inferenza e git, e ogni connessione è in uscita dalla tua rete, senza nessuna in entrata." width="680" height="320" data-path="images/self-hosted-network-paths.svg" />

33 <img src="https://mintcdn.com/claude-code/Y0sJ2uDoOVbOVZrQ/images/self-hosted-network-paths-dark.svg?fit=max&auto=format&n=Y0sJ2uDoOVbOVZrQ&q=85&s=fec6aef3b0740d80eaf6d6a7000a2233" className="hidden dark:block" alt="Diagramma dell'architettura di un ambiente self-hosted: il confine della tua rete contiene un runner, due processi di sessione Claude Code al suo interno e il tuo host git, con api.anthropic.com all'esterno che contiene coda, flusso di sessione e inferenza. Il runner esegue il polling della coda e raggiunge l'host git, ogni processo di sessione apre le proprie connessioni di flusso, inferenza e git, e ogni connessione è in uscita dalla tua rete, senza nessuna in entrata." width="680" height="320" data-path="images/self-hosted-network-paths-dark.svg" />

34 </Frame>

35</div>

37I due riquadri Claude Code nel diagramma sono processi di sessione: un runner che esegue due sessioni contemporaneamente, fino alla sua capacità configurata. Un runner serve un [proprietario](#key-concepts) alla volta e si blocca a quel proprietario quando rivendica la sua prima sessione, quindi il codice estratto non si mescola mai tra proprietari; [Ciclo di vita del runner](#runner-lifecycle) copre la regola.

39Puoi avviare i runner tu stesso e mantenerli in esecuzione, oppure eseguire l'[orchestrator di autoscaling](/docs/it/self-hosted-environments-configuration#on-demand-runners), un secondo processo che ospiti, che avvia i runner mentre le sessioni si accodano; ogni runner esce da solo quando il suo lavoro finisce. In entrambi i casi, configuri l'ambiente una volta, e appare nel selettore su ogni superficie supportata.

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

42 Disponibilità e limitazioni

43</h2>

45Controlla questi punti prima di pianificare un rollout:

47* **Piani**: beta pubblica per organizzazioni Team ed Enterprise. Gli ambienti self-hosted sono disabilitati per impostazione predefinita; un [Owner](/docs/it/cloud-environments#organization-shared-environments) attiva **Allow self-hosted environments** sulla [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments), che richiede che [Claude Code on the web](/docs/it/claude-code-on-the-web) sia abilitato per l'organizzazione.

48* **Zero Data Retention**: non disponibile per organizzazioni con [Zero Data Retention](/docs/it/zero-data-retention) abilitato.

49* **Inferenza del modello**: le sessioni utilizzano l'API Anthropic, e l'inferenza non può essere instradata attraverso [Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry](/docs/it/third-party-integrations), o un [gateway LLM](/docs/it/llm-gateway).

50* **Superfici**: le sessioni avviate da [Claude Code on the web](/docs/it/claude-code-on-the-web), dalle app mobile e desktop, da [routine pianificate](/docs/it/routines), e dal terminale, con [`claude --cloud`](/docs/it/claude-code-on-the-web#from-terminal-to-web) o un [dispatch `--environment`](/docs/it/self-hosted-environments-testing#run-the-test-loop), possono essere eseguite in ambienti self-hosted. Le sessioni [Claude Tag](https://claude.com/docs/claude-tag/overview) possono essere eseguite in esse, ma Claude non può ancora utilizzare [Access bundles](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle) in quelle sessioni. Le sessioni [Claude Security](/docs/it/claude-security) e [Code Review](/docs/it/code-review) non vengono ancora instradate ad esse. Il supporto per quelle due superfici segue separatamente.

51* **Repository**: le sessioni estraggono repository da GitHub; vedi [Opzioni di autenticazione GitHub](/docs/it/claude-code-on-the-web#github-authentication-options).

52* **Fatturazione**: le sessioni in un ambiente self-hosted consumano l'utilizzo di Claude Code della tua organizzazione allo stesso modo delle sessioni negli ambienti ospitati da Anthropic.

54<h2 id="why-self-host">

55 Perché fare self-hosting

56</h2>

58La maggior parte dei team è meglio servita da ambienti ospitati da Anthropic, che non richiedono infrastrutture da eseguire o mantenere. Il self-hosting è per team le cui esigenze di rete, tooling o conformità richiedono di mantenere l'esecuzione della sessione su infrastrutture che controllano. Se è così, pianifica la proprietà operativa che comporta: costruisci e mantieni l'immagine del runner, gestisci la flotta e controlli la sua rete.

60In cambio, il self-hosting ti dà accesso alla rete, tooling personalizzato e controllo della conformità:

62* **Accesso alla rete**: le sessioni vengono eseguite all'interno della tua rete e possono raggiungere servizi interni, database e registri senza esporli a Internet pubblico

63* **Tooling personalizzato**: pre-installa compilatori, SDK e CLI interni nella tua immagine di runner in modo che ogni sessione inizi pronta a compilare

64* **Conformità**: gli estratti di repository e gli artefatti di compilazione rimangono su infrastrutture che controlli. Il contenuto della sessione va comunque a `api.anthropic.com` per l'inferenza del modello.

66<h2 id="environments-runners-and-sessions">

67 Ambienti, runner e sessioni

68</h2>

70Gli ambienti vengono gestiti sulla pagina **Cloud environments** nelle impostazioni di amministrazione di claude.ai; i runner sono processi che avvii e gestisci sulla tua infrastruttura.

72<h3 id="key-concepts">

73 Concetti chiave

74</h3>

76Questi termini appaiono in tutte le pagine self-hosted:

78| Termine | Che cos'è |

79| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

80| Environment | Un gruppo denominato dei tuoi runner, creato nelle impostazioni di claude.ai. Le sessioni vengono instradate a un ambiente, non a un singolo runner. |

81| Environment secret | La singola credenziale condivisa che i runner utilizzano per autenticarsi e registrarsi con l'ambiente. Mostrata una sola volta alla creazione dell'ambiente, etichettata come **environment key** nell'interfaccia di amministrazione. |

82| Runner | Il processo di lunga durata che distribuisci. Un runner si registra con l'ambiente, riceve un token di runner e esegue il polling per le sessioni. |

83| Session | Un'attività Claude Code, avviata da claude.ai, dall'app mobile o da un'altra superficie Anthropic come una routine pianificata o un agente. Ogni sessione viene eseguita come un processo Claude Code figlio che il runner genera. |

85Nei campi API, nelle rivendicazioni di token e nei nomi delle metriche, l'ambiente appare come `pool`, e l'ID dell'ambiente è il `pool_id`. Il [riferimento](/docs/it/self-hosted-environments-reference) mappa i due nomi, inclusi i nomi di flag `pool` deprecati.

87Un runner serve un proprietario alla volta. La prima sessione che un runner raccoglie blocca il runner a quel proprietario della sessione, e il runner quindi esegue sessioni solo per quel proprietario, fino a una capacità configurata. Chi è il proprietario dipende da come è stata avviata la sessione:

89* **Sessioni avviate da un utente**: il proprietario è l'account di quell'utente.

90* **Sessioni del canale Claude Tag**: Claude le esegue senza alcun account utente allegato, quindi il proprietario è l'[agente Claude Tag](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity) che ha avviato la sessione. Ogni sessione di canale che quell'agente avvia ha lo stesso proprietario, chiunque abbia inviato il messaggio Slack, quindi un runner bloccato ad esso serve sessioni che persone diverse hanno avviato quando lo esegui a una `--capacity` superiore a uno o con un `--drain-grace-sec` positivo. Un runner bloccato a un utente non raccoglie mai questi, e un runner bloccato a un agente Claude Tag non raccoglie mai le sessioni di un utente.

92La dimensione minima della flotta è quindi il numero di proprietari che ti aspetti siano attivi contemporaneamente, contando utenti e agenti Claude Tag.

94<h3 id="session-lifecycle">

95 Ciclo di vita della sessione

96</h3>

98Quando uno sviluppatore avvia una sessione e seleziona il tuo ambiente, il piano di controllo di Anthropic posiziona la sessione nella coda dell'ambiente. Da lì:

1001. Un runner con capacità libera rivendica la sessione e mantiene un lease su di essa.

1012. Il runner clona il repository nella sua directory di lavoro e genera un processo Claude Code figlio.

1023. Il figlio trasmette gli eventi indietro su HTTPS mentre il runner continua a eseguire il polling; ogni polling aggiorna il lease e funge anche da heartbeat.

1034. Se il runner smette di eseguire il polling per circa 60 secondi, il server rimette in coda la sessione per un altro runner.

104

105Il runner assegna a ogni richiesta di polling 10 secondi. Quando una richiesta scade, viene persa o riceve una risposta che il runner non può analizzare, il runner continua a servire le sue sessioni attive e riprova dopo un secondo o due invece di aspettare il prossimo polling programmato. Ad esempio, un proxy di intercettazione che risponde al polling con la sua stessa pagina produce una risposta che il runner non può analizzare. Ogni volta che un'altra richiesta fallisce in uno di questi modi, il runner raddoppia il gap prima del prossimo tentativo, fino a 20 secondi, e accorcia il gap ogni volta che il lease sta per scadere.

106

107<h3 id="runner-lifecycle">

108 Ciclo di vita del runner

109</h3>

110

111La prima sessione che un runner raccoglie blocca il runner a quel proprietario della sessione, e il runner esegue fino a `--capacity` sessioni concorrenti per quel proprietario. Mentre il runner ha sessioni attive e non ha ricevuto un segnale di arresto o raggiunto il suo tempo di ritiro, il runner continua a rivendicare il lavoro in coda del proprietario bloccato. Quello che succede una volta che finiscono dipende da [`--drain-grace-sec`](/docs/it/self-hosted-environments-reference#runner-cli-flags):

112

113* **Al valore predefinito di `0`**: il runner esce non appena le sue sessioni attive finiscono, senza eseguire il polling per altri, quindi l'orchestrator che lo distribuisci, come Kubernetes, può riavviarlo con un disco fresco, pronto a servire qualsiasi proprietario.

114* **A un valore positivo**: il runner continua a eseguire il polling della coda del proprietario bloccato per quel numero di secondi prima di uscire.

115

116Questo ciclo di vita isola il codice estratto di ogni proprietario senza richiedere al runner di eliminare lo stato del disco tra proprietari.

117

118Il modo in cui la tua infrastruttura arresta un runner decide se hai bisogno di `--retire-at`. Un kill che consegna `SIGTERM` non ha bisogno di flag: il runner drena come [Shutdown timing](/docs/it/self-hosted-environments-deploy#shutdown-timing) descrive, o continua a servire le sessioni che già tiene quando imposti [`--defer-shutdown-max-min`](/docs/it/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal). Se la tua infrastruttura invece distrugge gli host a un'ora di parete nota senza un segnale, o con un periodo di grazia troppo breve per drenare, come un limite di durata della sandbox o una reclama di istanza spot, passa `--retire-at <epoch-seconds>` impostato a pochi minuti prima di quel momento. Al momento del ritiro:

119

1201. Il runner smette di accettare nuovo lavoro.

1212. Il runner rilascia ogni sessione attiva attraverso lo stesso percorso di rilascio che il flag [`--release-idle-session-min`](/docs/it/self-hosted-environments-reference#runner-cli-flags) utilizza, quindi la sessione riprende su un runner fresco quando l'utente invia il suo prossimo messaggio. Quando il runner rilascia ogni sessione dipende dal suo stato:

122 * Il runner rilascia una sessione che è a metà turno non appena quel turno finisce.

123 * Quando un turno finisce e lascia attività in background in esecuzione, il runner aspetta fino a 60 secondi per loro, quindi rilascia la sessione anche se sono ancora in esecuzione. Se le attività hanno finito ma il turno successivo che legge i loro risultati non è ancora stato eseguito, il runner mantiene la sessione fino a quando quel turno finisce, e aspetta non più di [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](/docs/it/self-hosted-environments-reference#environment-variable-only-settings) per l'inizio di quel turno.

1243. Il runner esce 0 una volta che tutte le sue sessioni sono rilasciate.

125

126Un turno che sopravvive al kill è comunque perso; [Shutdown timing](/docs/it/self-hosted-environments-deploy#shutdown-timing) copre il dimensionamento del margine. Senza `--retire-at`, un kill di host senza segnale è indistinguibile da un crash: il piano di controllo registra un worker perso piuttosto che un rilascio pulito, e la sessione viene rimessa in coda a un altro runner.

127

128<h3 id="network-paths">

129 Percorsi di rete

130</h3>

131

132Il runner e le sue sessioni effettuano diversi tipi di connessione in uscita, e non è richiesta alcuna connettività in entrata da Anthropic:

133

134* **Piano di controllo**: il runner esegue il polling di `api.anthropic.com` per il lavoro e pubblica gli eventi di progresso della configurazione e di errore, tutto HTTPS in uscita. Il polling funge anche da heartbeat del runner.

135* **SCM connector**: l'orchestrator facoltativo [SCM connector](/docs/it/self-hosted-environments-reference#scm-connector-flags) tunnel è l'unica connessione WebSocket.

136* **Git**: il runner clona da e spinge verso il tuo host git su HTTPS o SSH, autenticato con credenziali che la tua distribuzione fornisce; [Configura git](/docs/it/self-hosted-environments-deploy#configure-git) copre le opzioni, incluse credenziali coniate per sessione e il [proxy git Anthropic](/docs/it/self-hosted-environments-deploy#use-the-anthropic-git-proxy), che instrada git attraverso `api.anthropic.com` invece.

137* **Session child**: il processo Claude Code figlio della sessione mantiene il flusso di eventi della sessione a `api.anthropic.com`, e effettua le proprie chiamate in uscita per l'inferenza del modello e per i comandi git eseguiti durante la sessione. Vedi [Requisiti di rete](/docs/it/self-hosted-environments-deploy#network-requirements) per l'elenco completo dell'uscita. Il [diagramma sopra](#how-self-hosted-environments-work) mostra questi percorsi, a parte l'SCM connector facoltativo.

138

139L'inferenza del modello utilizza l'API Anthropic. Il piano di controllo consegna l'endpoint API a ogni sessione, e la sessione si autentica con un token OAuth emesso da Anthropic e limitato alla sessione, quindi l'inferenza non può essere instradata attraverso [Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry](/docs/it/third-party-integrations), o un [gateway LLM](/docs/it/llm-gateway) negli ambienti self-hosted.

140

141I proxy di uscita aziendali sono supportati. Il runner e l'[orchestrator di autoscaling](/docs/it/self-hosted-environments-configuration#on-demand-runners) facoltativo rispettano il proxy e le variabili di ambiente mTLS descritte in [Configurazione di rete](/docs/it/network-config), come `HTTPS_PROXY` e `NO_PROXY`; impostale nell'ambiente di ogni processo. Le variabili coprono le chiamate del piano di controllo, il WebSocket [SCM connector](/docs/it/self-hosted-environments-reference#scm-connector-flags) dell'orchestrator, e il clone integrato per i remote HTTPS, e le sessioni le ereditano dal runner. Lo streaming della sessione utilizza server-sent events su HTTPS, quindi un proxy nel percorso non deve memorizzare le risposte nel buffer.

142

143Se il tuo proxy richiede anche un'intestazione `Proxy-Authorization`, il runner può aggiungerla a ogni connessione che apre al proxy; vedi [Autentica a un proxy di uscita](/docs/it/self-hosted-environments-deploy#authenticate-to-an-egress-proxy).

144

145<h2 id="what-stays-on-your-infrastructure">

146 Cosa rimane sulla tua infrastruttura

147</h2>

148

149Gli estratti di repository, gli artefatti di compilazione, i segreti e tutti i file che una sessione crea o modifica rimangono sulle macchine che fornisci. La conversazione stessa, inclusi i prompt, le risposte e i risultati degli strumenti, va a `api.anthropic.com` per l'inferenza del modello, e Anthropic archivia la trascrizione della sessione in modo che tu possa riprendere la sessione da un'altra [superficie supportata](#availability-and-limitations).

150

151Un ambiente self-hosted sposta l'esecuzione della sessione nella tua rete. Il piano di controllo rimane ospitato da Anthropic: l'orchestrazione della sessione, l'accodamento e l'interfaccia di claude.ai continuano a essere eseguiti su infrastrutture di Anthropic.

152

153<h2 id="get-started">

154 Inizia

155</h2>

156

157Le pagine degli ambienti self-hosted sono organizzate per quello che stai facendo:

158

159* [Guida rapida](/docs/it/self-hosted-environments-quickstart): installa Claude Code, crea un ambiente, avvia un runner e instrada la tua prima sessione

160* [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy): hardening della sicurezza, uscita di rete, credenziali git, ricette Kubernetes e Compose, problemi noti e risoluzione dei problemi

161* [Personalizza sessioni](/docs/it/self-hosted-environments-configuration): script wrapper per credenziali per sessione, hook del ciclo di vita, runner on-demand, server MCP e autorizzazioni

162* [Testa end to end](/docs/it/self-hosted-environments-testing): un test di fumo CI che verifica un'immagine di runner prima di promuoverla

163* [Riferimento](/docs/it/self-hosted-environments-reference): ogni flag CLI, variabile di ambiente, metrica e l'endpoint di salute

164* [Verifica l'identità della sessione](/docs/it/self-hosted-environments-identity): convalida il token di sessione dai tuoi servizi prima di concedere l'accesso

self-hosted-environments-configuration.md +435 −0 created

Details

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.

5# Personalizzare le sessioni negli ambienti self-hosted

7> Personalizzare le sessioni degli ambienti self-hosted con script wrapper per credenziali per sessione, hook del ciclo di vita e spawning di runner su richiesta.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; un [Owner](/docs/it/cloud-environments#organization-shared-environments) li abilita attivando **Allow self-hosted environments** nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). Questa pagina presuppone un runner funzionante; consultare la [guida rapida](/docs/it/self-hosted-environments-quickstart) per la configurazione e [Deploy to production](/docs/it/self-hosted-environments-deploy) per le ricette della flotta.

11</Note>

13Un [ambiente self-hosted](/docs/it/self-hosted-environments) esegue le [sessioni cloud](/docs/it/claude-code-on-the-web) di Claude Code sulla propria infrastruttura, eseguite da un processo runner che si distribuisce. Senza configurazione, quel runner clona il repository della sessione, avvia Claude Code e pulisce. Questa pagina è per l'ingegnere della piattaforma che gestisce i runner: copre i punti di estensione per quando questi valori predefiniti non si adattano, dal provisioning delle credenziali per sessione alla sostituzione completa del checkout. I wrapper e gli hook vengono eseguiti come file eseguibili sull'host del runner, che è Linux o macOS, e gli esempi su questa pagina presuppongono una shell POSIX.

15Alcune variabili di ambiente hook su questa pagina utilizzano ancora `pool`, come `CLAUDE_RUNNER_POOL_ID`; i nomi dei flag CLI e delle variabili di ambiente utilizzano `environment`, come `--environment-secret-file`.

17<h2 id="wrapper-scripts">

18 Script wrapper

19</h2>

21Utilizzare uno script wrapper quando ogni sessione ha bisogno di una configurazione che il runner non può fare da solo: provisioning di credenziali di breve durata limitate al creatore della sessione, esportazione di segreti specifici dell'ambiente, preparazione di toolchain di linguaggio o applicazione di limiti di risorse attorno al processo figlio. Il runner avvia il wrapper al posto del binario Claude Code, una volta per sessione. Terminare il wrapper con `exec` in `$CLAUDE_RUNNER_CLAUDE_BIN`, il binario del runner stesso, in modo che i segnali e i codici di uscita si propaghino correttamente.

23Puntare `--exec-path`, o `SELF_HOSTED_RUNNER_EXEC_PATH`, al wrapper quando si avvia il runner:

25```bash theme={null}

26claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

27```

29Il runner imposta quanto segue nell'ambiente del wrapper:

31| Variabile | Descrizione |

32| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il JWT della sessione, con prefisso `sk-ant-cc-`. Il suo claim `act` identifica il creatore della sessione, con l'email del creatore e il soggetto del provider di identità upstream quando la superficie di creazione li ha registrati. Il valore è il token al momento dello spawn; gli aggiornamenti arrivano sullo stdin del figlio, quindi un wrapper vede solo il valore iniziale. Consultare [Verify session identity](/docs/it/self-hosted-environments-identity). |

34| `CCR_SESSION_ACCOUNT_EMAIL` | L'email del creatore della sessione, pre-estratta dal runner dal claim `act.email` del token senza verifica della firma. Adatto per l'etichettatura, come i trailer dei commit. Quando l'email controlla il rilascio delle credenziali, verificare il token e leggere il claim da esso; consultare [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Non impostato quando il token non contiene un'email del creatore. Trattare come informazioni personali identificabili. |

35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` o `scheduled_trigger`. Anthropic registra il valore una volta alla creazione della sessione, quindi il wrapper e ogni hook del ciclo di vita vedono lo stesso valore. Utilizzarlo solo per l'analisi dell'adozione e l'etichettatura, non come segnale di autorizzazione. Non impostato quando la sessione non ha una superficie registrata o riconosciuta, quindi fare riferimento ad esso come `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sotto `set -u`. Richiede Claude Code v2.1.229 o successivo. |

36| `CLAUDE_RUNNER_CLAUDE_BIN` | Percorso assoluto al binario Claude Code del runner stesso. Terminare il wrapper con `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` per passare al binario bloccato senza hardcodificare un percorso di installazione. |

37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID sessione nel modulo taggato `cse_...`. Questa è la stessa sessione che gli [hook del ciclo di vita](#lifecycle-hooks) vedono come `CLAUDE_RUNNER_SESSION_ID` nel modulo `session_...`; le variabili UUID corrispondono su entrambi, e sostituire il prefisso `cse_` con `session_` produce l'ID mostrato nell'URL della sessione. |

38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico, per i sistemi che si basano su UUID. |

39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Percorso assoluto a un file per sessione che contiene il JWT della sessione corrente, mantenuto aggiornato negli aggiornamenti dei token. I sottoprocessi della shell lo leggono per il loro header `Authorization` quando scaricano gli allegati che l'utente ha aggiunto alla sessione. `exec` preserva la variabile automaticamente; un wrapper che ricostruisce l'ambiente del figlio deve portare la variabile, o i download degli allegati si interrompono silenziosamente. |

40| `CLAUDE_CONFIG_DIR` | Directory di configurazione Claude per sessione, scritta all'inizio della sessione dallo snapshot della configurazione dell'host del runner che il runner acquisisce all'avvio; consultare [Permissions and tool approval](#permissions-and-tool-approval). Le scritture qui sono isolate a questa sessione. |

41| `ANTHROPIC_BASE_URL` | L'URL di base dell'API che il figlio utilizzerà, fornito dal piano di controllo per sessione e normalmente `https://api.anthropic.com`. Non sovrascriverlo: la credenziale di inferenza della sessione è un token OAuth emesso da Anthropic che altri provider non accettano, quindi l'inferenza negli ambienti self-hosted non è instradabile altrove. |

42| `CLAUDE_CODE_OAUTH_TOKEN` | Il token di accesso OAuth di breve durata che il figlio utilizza per l'inferenza del modello, limitato solo all'inferenza del modello e al caricamento di file, con una durata di circa 30 minuti. Il runner lo ricrea prima della scadenza e fornisce la rotazione sullo stdin del figlio, quindi un wrapper che non [mantiene stdin allegato](#keep-stdin-and-file-descriptor-3-attached) vede solo il valore iniziale. Non fare affidamento sulla lista di indirizzi IP della propria organizzazione per limitare l'uso di questo token: trattarlo come una credenziale bearer che rimane utilizzabile per circa 30 minuti se trapela, e non registrarlo, scriverlo su disco o inoltarlo al di fuori del contenitore della sessione. |

44Il wrapper eredita anche il resto dell'ambiente gestito del figlio, incluse tutte le variabili di ambiente fornite dal server. `exec` le propaga tutte automaticamente; se il wrapper avvia il figlio in un altro modo, inoltrare l'ambiente completo.

46<h3 id="keep-stdin-and-file-descriptor-3-attached">

47 Mantenere stdin e il descrittore di file 3 allegati

48</h3>

50Lo stdin del figlio è il canale di controllo del runner. Gli aggiornamenti dei token e i segnali di fine sessione arrivano su di esso. Il runner apre anche una pipe sul descrittore di file 3 e legge i segnali di attività del figlio da esso per guidare i timeout di inattività e avvio. Un semplice `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva entrambi automaticamente.

52Se il wrapper mette in background il figlio con un semplice `&`, interrompe lo stdin del figlio: la sessione sembra sana fino a quando la durata di circa 30 minuti del token OAuth iniziale non scade, quindi ogni chiamata API fallisce con `401 authentication_error`. Se il wrapper deve mettere in background il figlio, ad esempio per mantenere vivo un trap di teardown, salvare stdin sul descrittore di file 4 o superiore e ricollegarlo esplicitamente:

54```bash theme={null}

55exec 4<&0

56"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&4 4<&- &

57CHILD=$!

58trap 'teardown' EXIT

59wait "$CHILD"

60```

62Non chiudere o riutilizzare il descrittore di file 3 nel wrapper. Il reindirizzamento dello stdout e dello stderr del figlio va bene.

64<h3 id="provision-credentials-scoped-to-the-session-creator">

65 Provisioning di credenziali limitate al creatore della sessione

66</h3>

68Utilizzare il subcomando `decode-token` per leggere i claim dal JWT della sessione. Legge il token da un argomento, da `CLAUDE_CODE_SESSION_ACCESS_TOKEN` o da stdin, in quell'ordine; consultare [Verify the token inside the session](/docs/it/self-hosted-environments-identity#verify-the-token-inside-the-session) per ciò che controlla. L'esempio seguente decodifica l'identità del creatore, la scambia con credenziali AWS di breve durata e fa exec in Claude Code:

70```bash theme={null}

71#!/bin/bash

72# Basarsi sull'ID utente Anthropic stabile e richiedere un creatore umano.

73CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \

74 | jq -re '.act.sub // "" | select(startswith("user:"))') \

75 || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

77creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \

78 || { echo "credential exchange failed" >&2; exit 1; }

79eval "$creds"

81exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

82```

84Utilizzare `jq -re` piuttosto che `jq -r` quando il claim estratto controlla una decisione di autenticazione, in modo che un claim assente esca con codice diverso da zero invece di passare la stringa letterale `null` a valle. Le sessioni create da un'identità di servizio dell'organizzazione, come sessioni di bot e agenti, portano un soggetto `agent:` piuttosto che `user:`, quindi questo esempio le rifiuta; se l'ambiente serve quelle sessioni, decidere esplicitamente se il wrapper ricade a una credenziale predefinita per loro invece di uscire. Quando lo scambio di credenziali ha bisogno del soggetto SSO o dell'email, leggere `.act.attested_by.sub` o `.act.email` e gestire la loro assenza: il token li porta solo quando la superficie di creazione li ha registrati, e una [sessione inviata da CLI](/docs/it/self-hosted-environments-testing#run-the-test-loop) può mancare di entrambi. Per il riferimento completo dei claim e la verifica da servizi al di fuori del runner, consultare [Verify session identity](/docs/it/self-hosted-environments-identity).

86<h2 id="lifecycle-hooks">

87 Hook del ciclo di vita

88</h2>

90Gli hook del ciclo di vita sostituiscono le fasi della pipeline per sessione del runner con i propri script. Puntare il runner a una directory di hook con `--hooks-dir <path>`, o `SELF_HOSTED_RUNNER_HOOKS_DIR`. Il runner cerca file eseguibili con nomi ben noti; qualsiasi hook che non è presente ricade nel comportamento integrato, quindi si scrivono solo quelli di cui si ha bisogno. Gli hook vengono eseguiti con i privilegi del runner stesso, e i figli della sessione condividono quel UID, quindi montare la directory degli hook in sola lettura, o cuocerla nell'immagine, in modo che il codice della sessione non possa modificarla; consultare la [sezione di hardening](/docs/it/self-hosted-environments-deploy#harden-your-deployment).

92Questi hook sono distinti dagli [hook di Claude Code](/docs/it/hooks), che vengono eseguiti all'interno della sessione; gli hook del ciclo di vita vengono eseguiti sul runner, attorno alla sessione.

94<h3 id="checkout">

95 checkout

96</h3>

98Viene eseguito una volta per repository, al posto del clone e del fetch integrati del runner. Utilizzare l'hook per clonare da uno specchio di lettura, seminare un albero di lavoro da un archivio o applicare l'autenticazione git per sessione. Il runner imposta:

100| Variabile | Descrizione |

101| :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

102| `CLAUDE_RUNNER_REPO_URL` | URL del repository da clonare, dopo che `--git-host-rewrite` e `--git-ssh-rewrite` sono stati applicati |

103| `CLAUDE_RUNNER_REPO_REF` | Revisione da controllare: ramo, tag o commit SHA come la sessione lo ha richiesto. Vuoto significa il ramo predefinito del repository. |

104| `CLAUDE_RUNNER_CHECKOUT_PATH` | Percorso assoluto dove l'albero di lavoro deve essere lasciato |

105| `CLAUDE_RUNNER_SESSION_ID` | ID sessione nel modulo taggato `session_...`, per la registrazione e la correlazione |

106| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico |

107| `CLAUDE_RUNNER_API_BASE_URL` | URL di base dell'API Anthropic per le chiamate limitate alla sessione |

108| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app` o `ios`. Non impostato quando la sessione non ha una superficie registrata o riconosciuta. |

109| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il token di accesso della sessione, per le chiamate API limitate alla sessione |

110

111Lo script deve lasciare un albero di lavoro in `CLAUDE_RUNNER_CHECKOUT_PATH` controllato alla revisione richiesta. HEAD staccato va bene; il runner crea il ramo di lavoro della sessione in cima. Il runner verifica che il percorso contenga un `.git` in seguito; se l'hook materializza una fonte non-git come Perforce o un tarball scompattato, impostare `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` nell'ambiente del runner per saltare quel controllo. I flussi basati su Git come la creazione del ramo di lavoro e il push dei risultati richiedono un checkout git, quindi esportare i risultati da alberi non-git con un hook [`post-session`](#post-session).

112

113Il runner non passa una credenziale git all'hook. Invece, coniare una credenziale di clone per sessione dall'identità della sessione: verificare `CLAUDE_CODE_SESSION_ACCESS_TOKEN` con una libreria JWT standard rispetto all'endpoint JWKS sotto `CLAUDE_RUNNER_API_BASE_URL`, come descritto in [Verify the token from your service](/docs/it/self-hosted-environments-identity#verify-the-token-from-your-service), quindi fare in modo che il servizio di credenziale emetta una credenziale di clone di breve durata per l'identità nel claim `act` del token. `CLAUDE_RUNNER_CLAUDE_BIN` non è impostato nell'ambiente dell'hook di checkout, quindi il subcomando `decode-token` non è disponibile qui. Ricadere in qualsiasi autenticazione git che l'host ha già, come un agente SSH, un helper di credenziale o `.netrc`, è anche un'opzione.

114

115Quando l'hook esce con codice diverso da zero, o esce 0 senza lasciare un checkout utilizzabile dietro, ciò che il runner fa dipende dal repository:

116

117* **Un repository a cui la sessione spinge i risultati**: il runner fallisce la sessione e su un'uscita diversa da zero mostra la coda dello stderr dello script all'utente.

118* **Un repository che la sessione legge solo**, come un repository aggiunto a una sessione in esecuzione: il runner registra una riga `[runner:warn]` con il dettaglio del fallimento, pubblica un passo `Skipped` alla sessione, rimuove ciò che l'hook ha lasciato al percorso di checkout e continua con i repository rimanenti. Quando il runner non può rimuovere il percorso immediatamente, ritenta la rimozione alla fine della sessione. Se saltare lascia la sessione senza alcun repository, il runner fallisce comunque la sessione.

119

120Prima della v2.1.228, il runner falliva la sessione su un fallimento dell'hook per qualsiasi repository, quindi un repository di sola lettura che l'hook non poteva servire falliva di nuovo la sessione su ogni nuovo runner su cui la sessione riprendeva.

121

122Il runner rimuove il percorso di checkout dopo la fine della sessione.

123

124<h3 id="post-session">

125 post-session

126</h3>

127

128Viene eseguito una volta per sessione, dopo che il figlio Claude Code è uscito e prima che il runner smantelli l'area di lavoro. Questo hook è la tua unica possibilità di salvare il lavoro non committato: a `--capacity` superiore a uno, il runner elimina i worktree per sessione subito dopo il ritorno dell'hook, e a `--capacity 1` il [clone canonico](/docs/it/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout) riutilizzato viene hard-reset quando la sessione successiva inizia, quindi i cambiamenti tracciati non committati non sopravvivono su nessuno dei due percorsi. Gli usi tipici sono il push di un ramo snapshot di cambiamenti non committati, l'archiviazione di log o l'emissione di un evento di fine sessione ai propri sistemi.

129

130L'hook si attiva ad ogni fine sessione dove un processo figlio è stato generato, qualunque sia la causa; i valori `CLAUDE_RUNNER_EXIT_REASON` di seguito enumerano i casi. Non può attivarsi quando il runner termina bruscamente, come una preemption VM o una perdita di potenza; se hai bisogno di garanzie contro la terminazione brusca, fai uno snapshot periodicamente dall'interno della sessione con un hook Claude Code `PostToolUse` invece. Il runner imposta:

131

132| Variabile | Descrizione |

133| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

134| `CLAUDE_RUNNER_SESSION_ID` | ID sessione nel modulo taggato `session_...` |

135| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico |

136| `CLAUDE_RUNNER_EXIT_REASON` | Come la sessione è terminata; consultare i valori sotto la tabella |

137| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Percorsi assoluti separati da due punti degli alberi di lavoro della sessione. Vuoto per sessioni senza repository. |

138| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Percorso al log di debug della sessione, ancora su disco mentre l'hook viene eseguito |

139| `CLAUDE_RUNNER_API_BASE_URL` | URL di base dell'API Anthropic per le chiamate limitate alla sessione |

140| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app` o `ios`. Non impostato quando la sessione non ha una superficie registrata o riconosciuta. Richiede Claude Code v2.1.229 o successivo. |

141| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il token di accesso della sessione, per le chiamate API limitate alla sessione |

142

143`CLAUDE_RUNNER_EXIT_REASON` assume uno di quattro valori:

144

145* `completed`: la sessione è terminata in modo pulito. Il processo Claude Code è uscito normalmente, oppure la sessione è stata archiviata o eliminata mentre era ancora in esecuzione.

146* `failed`: il processo Claude Code è andato in crash, oppure la configurazione è fallita dopo l'avvio.

147* `interrupted`: il runner ha interrotto la sessione. Ha rilasciato la sessione per liberare lo slot, la sessione è scaduta all'avvio, il server ha spostato la sessione da questo runner, il runner era in drenaggio, oppure la sessione ha superato il limite [`--kill-session-after-min`](/docs/it/self-hosted-environments-reference#runner-cli-flags).

148* `abandoned`: riservato per una sessione che un altro runner ha rivendicato. L'hook attualmente non si attiva in quel caso.

149

150I [contatori del ciclo di vita della sessione](/docs/it/self-hosted-environments-reference#session-lifecycle-counter-semantics) contano un rilascio, un timeout di avvio e uno spostamento del server come `completed` piuttosto che `interrupted`, perché il runner ha restituito lo slot in modo pulito. Aspettati quella differenza se confronti le ricevute dell'hook con i contatori.

151

152Lo stato di uscita dell'hook non influisce mai sul risultato della sessione; un fallimento viene registrato e ignorato. Il runner attende fino a `--post-session-hook-timeout-sec`, 60 secondi per impostazione predefinita, ad ogni fine sessione incluso l'arresto del runner. Questo esempio salva il lavoro non committato in un ramo di salvataggio:

153

154```bash theme={null}

155#!/usr/bin/env bash

156set -u

157IFS=':'

158# Configurazione pin che la sessione potrebbe aver piantato in .git/config del checkout:

159# -c gli override battono le impostazioni locali del repository, bloccando fsmonitor scritto dalla sessione,

160# hook-path e configurazione gpg-program dall'esecuzione di codice con i privilegi dell'hook.

161# Credenziale locale del repository, core.sshCommand e pushurl si applicano ancora; se l'hook

162# contiene credenziali che la sessione non aveva, pin anche l'URL di push e l'helper (consultare la nota sotto lo script).

163g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \

164 -c commit.gpgsign=false "$@"; }

165for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do

166 cd "$ws" 2>/dev/null || continue

167 [ -z "$(g status --porcelain 2>/dev/null)" ] && continue

168 g add -A

169 g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue

170 g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true

171done

172```

173

174L'hook spinge con qualsiasi credenziale git disponibile nel suo stesso ambiente sull'host del runner. Sotto la [postura no-credentials-in-the-image](/docs/it/self-hosted-environments-deploy#configure-git), incluso quando il clone integrato passa attraverso il proxy git di Anthropic, non ce ne sono, quindi conia una credenziale di push di breve durata all'interno dell'hook prima di spingere: scambia il token della sessione che l'hook riceve in `CLAUDE_CODE_SESSION_ACCESS_TOKEN` con il servizio di token proprio, verificandolo come [Verify session identity](/docs/it/self-hosted-environments-identity) descrive. Quando l'hook contiene una credenziale che la sessione non aveva, pin anche dove spinge: sostituisci `origin` con un URL fornito dall'operatore e passa `-c credential.helper=` più il tuo helper, in modo che la configurazione locale che la sessione ha scritto non possa reindirizzare il push credenziale.

175

176<h4 id="hook-timing-when-the-runner-releases-a-session">

177 Hook timing quando il runner rilascia una sessione

178</h4>

179

180Una sessione rilasciata può riprendere su un altro runner. Su un runner su v2.1.236 o successivo, ciò che la sessione stava facendo al rilascio decide se può riprendere prima che questo hook finisca:

181

182* **Inattivo dopo un turno, o timeout all'avvio**: il runner ferma il figlio ed esegue questo hook fino al completamento. Solo allora rilascia la sessione. Un messaggio utente inviato mentre l'hook viene eseguito non può riprendere la sessione su un altro runner prima che l'hook finisca.

183* **In attesa che l'utente risponda a un prompt, come un prompt di autorizzazione**: il runner rilascia la sessione per primo, quindi esegue questo hook. Un messaggio utente inviato mentre l'hook viene eseguito può riprendere la sessione su un altro runner prima che l'hook finisca.

184

185Questo si applica ogni volta che il runner rilascia una sessione: al timeout di inattività, al momento [`--retire-at`](/docs/it/self-hosted-environments-reference#runner-cli-flags), e, su un runner su v2.1.260 o successivo, al limite [`--kill-session-after-min`](/docs/it/self-hosted-environments-reference#runner-cli-flags) di una sessione. Una sessione il cui turno è terminato e che contiene solo attività in background conta come inattiva qui. Prima della v2.1.236, il runner rilasciava la sessione per primo e quindi eseguiva questo hook in entrambi i casi.

186

187Durante un drenaggio `SIGTERM`, il runner mantiene il lease della sessione fino al completamento dell'hook; consultare [Shutdown timing](/docs/it/self-hosted-environments-deploy#shutdown-timing).

188

189<h3 id="command">

190 command

191</h3>

192

193Viene eseguito una volta per sessione dopo il checkout, al posto dello spawn del figlio integrato. L'hook riceve lo stesso ambiente di uno [script wrapper](#wrapper-scripts) e dovrebbe fare `exec` in `"$CLAUDE_RUNNER_CLAUDE_BIN"` allo stesso modo. Utilizzare l'hook `command` per mantenere tutta la personalizzazione in una directory di hook; utilizzare `--exec-path` quando il wrapper vive altrove. Se `--exec-path` è anche impostato, il flag ha la precedenza e l'hook `command` viene ignorato.

194

195Sempre fare `exec` del binario del runner stesso piuttosto che di un `claude` risolto da PATH; altrimenti si sconfigge il [pinning della versione](/docs/it/self-hosted-environments-deploy#pin-the-version).

196

197<h2 id="on-demand-runners">

198 Runner su richiesta

199</h2>

200

201Invece di eseguire una flotta fissa, è possibile avviare un runner per sessione. L'orchestratore è un subcomando separato e senza stato che esegue il polling di Anthropic per le richieste di spawn, una per sessione in coda senza runner disponibile, ed esegue l'hook `spawn-runner` per ciascuna. L'hook invia un carico di lavoro alla propria piattaforma: un Kubernetes Job, un'istanza EC2, un dispatch Nomad.

202

203I runner su richiesta migliorano l'igiene delle credenziali. Su una flotta fissa, il segreto dell'ambiente vive su ogni host del runner, che è lo stesso host che esegue le sessioni utente. Con l'orchestratore, il segreto dell'ambiente rimane solo sull'host dell'orchestratore, che non esegue mai il codice utente; ogni runner generato riceve un ordine di lavoro monouso che registra esattamente un runner e quindi scade.

204

205Per avviare l'orchestratore, passare il segreto dell'ambiente e una directory di hook contenente uno script `spawn-runner` eseguibile:

206

207```bash theme={null}

208claude self-hosted-runner orchestrator \

209 --environment-secret-file /etc/claude/environment-secret \

210 --hooks-dir /etc/claude/hooks

211```

212

213L'orchestratore non mantiene alcuno stato tra i poll, quindi è possibile eseguire due o più repliche rispetto allo stesso ambiente per la disponibilità. Ogni richiesta di spawn viene rivendicata lato server da esattamente una replica. Tutte le repliche devono utilizzare lo stesso valore `--expected-spawn-seconds`; consultare il [contratto dell'hook](#the-spawn-runner-hook).

214

215<h3 id="the-spawn-runner-hook">

216 L'hook spawn-runner

217</h3>

218

219L'orchestratore esegue `${hooks-dir}/spawn-runner` una volta per richiesta di spawn. L'hook deve inviare il lavoro in modo asincrono, senza attendere l'avvio del runner, e tornare entro `--hook-timeout`, 60 secondi per impostazione predefinita. L'hook riceve:

220

221| Variabile | Descrizione |

222| :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

223| `CLAUDE_RUNNER_WORK_ORDER_FILE` | Percorso a un file temporaneo contenente il JWT dell'ordine di lavoro firmato con cui il nuovo runner si registra. Eliminato dopo l'uscita dell'hook. Non registrare il contenuto del file. |

224| `CLAUDE_RUNNER_ORDER_ID` | Chiave di idempotenza opaca, unica per richiesta di spawn e sicura per i nomi delle risorse Kubernetes. Utilizzarla come chiave di dedup del provisioner. |

225| `CLAUDE_RUNNER_SESSION_ID` | La sessione per cui è questa richiesta. Vuoto per le richieste di pre-warming, che avviano un runner standby prima di qualsiasi sessione specifica quando [`--min-idle`](/docs/it/self-hosted-environments-reference#orchestrator-cli-flags) è impostato, quindi non assumere che la variabile sia impostata. |

226| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico. Vuoto per le richieste di pre-warming. |

227| `CLAUDE_RUNNER_ATTEMPT` | Quante richieste di spawn questa sessione ha avuto. `0` per le richieste di pre-warming. |

228| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Ora del server dalla risposta del poll header HTTP `Date`. Quando l'hook verifica l'`exp` del JWT dell'ordine di lavoro, confrontare rispetto a questo valore invece dell'orologio locale per tollerare lo skew. Vuoto quando il gateway ha omesso l'header. |

229| `CLAUDE_RUNNER_POOL_ID` | L'ID dell'ambiente a cui il nuovo runner dovrebbe unirsi, nel modulo `ccpool_...` |

230| `CLAUDE_RUNNER_ACCOUNT_ID` | ID taggato dell'account che ha accodato la sessione, per l'instradamento per account, la quota o il chargeback. Vuoto quando non disponibile, e sempre vuoto per le sessioni del canale Claude Tag, che nessun account accoda. |

231| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email dell'account che ha accodato la sessione. Vuoto quando non disponibile. Trattare l'email come informazioni personali identificabili e non registrarla. |

232| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL della prima fonte git della sessione, per l'instradamento a un runner con quel repository pre-riscaldato. Vuoto quando la sessione non ha fonti git. |

233| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisione della prima fonte git della sessione: ramo, SHA o tag. Vuoto quando non specificato. |

234| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON di `{url, revision}` per tutte le fonti git della sessione, per gli hook che instradano su un repository secondario. Vuoto quando non ci sono fonti. |

235| `CLAUDE_RUNNER_CORRELATION_ID` | L'ID di correlazione fornito alla creazione della sessione, ripetuto in modo che l'hook possa mappare questo ordine di lavoro alla richiesta che ha creato la sessione. Vuoto quando la sessione non ne ha uno. |

236| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app`, `ios` o `scheduled_trigger`, per l'analisi dell'adozione. Non impostato quando la sessione non ha una superficie registrata o riconosciuta, e per le richieste di pre-warming; controllarlo con `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, che rimane sicuro sotto `set -u`. |

237

238Il runner generato si registra con l'ordine di lavoro al posto del segreto dell'ambiente:

239

240* **Avviarlo con l'ordine di lavoro**: puntare [`--environment-secret-file`](/docs/it/self-hosted-environments-reference#runner-cli-flags) a un file contenente il JWT dell'ordine di lavoro, o impostare `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` al valore JWT.

241* **Copiare il JWT prima che l'hook esca**: l'orchestratore elimina il file dell'ordine di lavoro dopo l'uscita dell'hook, quindi copiare il JWT nel carico di lavoro che si invia, come un Kubernetes Secret sul Job generato, piuttosto che passare il percorso del file.

242* **Utilizzare `--capacity 1` sui runner generati**: un ordine di lavoro legato alla sessione registra esattamente un runner legato a quella sessione, quindi una capacità più alta aggiunge slot che non ricevono mai lavoro, e il runner registra un avviso all'avvio.

243* **Gli ordini di lavoro di pre-warming si registrano non legati**: il runner standby non è legato a una sessione e rivendica il lavoro in coda come un runner di flotta fissa.

244

245Il contratto ha quattro regole agnostiche del provisioner:

246

2471. **Essere idempotenti su `CLAUDE_RUNNER_ORDER_ID`.** La rielaborazione della stessa richiesta deve generare al massimo un runner. Derivare un nome di risorsa deterministico dall'ID e lasciare che la propria piattaforma rifiuti il duplicato.

2482. **Non ritentare il carico di lavoro.** Un ID ordine significa al massimo un carico di lavoro creato. Se il runner non si registra mai, Anthropic richiede con un ID ordine fresco dopo `--expected-spawn-seconds`.

2493. **Utilizzare il contratto del codice di uscita.** Uscita 0 significa inviato. Uscita 1 significa fallimento ritentabile; la sessione si ritira e viene riottenuta. Uscita 2 o superiore significa non ritentabile; la sessione è bloccata dallo spawn di nuovo fino a quando un [Owner](/docs/it/cloud-environments#organization-shared-environments) non seleziona **Retry** su di essa nella scheda **Activity** dell'ambiente. Su uscita diversa da zero, la coda dello stderr dell'hook appare lì come motivo del fallimento, quindi scrivere l'errore azionabile su stderr e mai segreti. Per una richiesta di pre-warming non c'è sessione da fallire: l'orchestratore registra un'uscita diversa da zero localmente solo, e il server richiede di nuovo lo spawn dopo il lease.

2504. **Impostare `--expected-spawn-seconds` ad almeno il tempo di avvio p99.** Questo è il lease lato server. Tutte le repliche dell'orchestratore devono utilizzare lo stesso valore.

251

252Tutto ciò che l'hook scrive su stdout o stderr appare nel log dell'orchestratore con le credenziali automaticamente redatte. Se le sessioni rimangono in coda, controllare il corpo `/healthz` dell'orchestratore per i conteggi della coda, quindi aprire la scheda **Activity** dell'ambiente sulla [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): espandere una sessione fallita lì per il suo errore di spawn e selezionare **Retry** per richiederlo di nuovo.

253

254<h2 id="mcp-servers">

255 Server MCP

256</h2>

257

258Per rendere i [server MCP](/docs/it/mcp) disponibili in ogni sessione, aggiungerli al momento della compilazione dell'immagine con lo stesso comando `claude mcp add` utilizzato su un'installazione desktop. Se il runner è un processo nudo piuttosto che un contenitore, eseguire lo stesso comando come utente del runner sull'host, quindi riavviare il runner: legge la configurazione dell'host una volta all'avvio. Il flag `--scope user` è obbligatorio; l'ambito locale predefinito scrive sotto una chiave per directory che il runner non semina nelle sessioni. Ad esempio, nel Dockerfile:

259

260```dockerfile theme={null}

261RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar

262RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

263```

264

265Il runner fa uno snapshot della configurazione dell'host una volta all'avvio. Lo snapshot acquisisce la chiave `mcpServers` dal `.claude.json` dell'host, che vive accanto piuttosto che dentro `~/.claude/`, e il runner semina solo quella chiave nella configurazione isolata di ogni sessione; lo stato dell'account e la cronologia del progetto vengono eliminati. Per confermare che i server hanno raggiunto le sessioni, avviare una sessione sull'ambiente e chiedere a Claude di elencare i suoi strumenti MCP; il runner registra anche un avviso di avvio per qualsiasi voce acquisita il cui `type` non riconosce e elimina la voce, quindi è possibile vedere perché quel server manca dalle sessioni. Quando `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` è impostato, il runner legge `.claude.json` da quella directory invece, quindi puntare la variabile a una directory vuota disabilita anche la semina MCP.

266

267Claude Code carica anche server MCP da altre fonti:

268

269* Il file MCP gestito a livello aziendale]\(/it/managed-mcp) al suo percorso di sistema standard: `/etc/claude-code/managed-mcp.json` sugli host del runner Linux, `/Library/Application Support/ClaudeCode/managed-mcp.json` sugli host macOS. Utilizzarlo per flotte bloccate dove solo i server elencati dall'amministratore possono caricarsi. Consultare [exclusive control with managed-mcp.json](/docs/it/managed-mcp#exclusive-control-with-managed-mcp-json) per le regole di precedenza. Quando questo file è sull'host del runner, Claude Code salta i server MCP che il piano di controllo di Anthropic fornisce a una sessione, inclusi i connettori claude.ai, e li nomina in un avviso su stderr del figlio della sessione, che il runner registra al livello di log `debug`. Prima della v2.1.229, quelle sessioni uscivano all'avvio con `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.

270* La chiave [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) nelle [impostazioni gestite](/docs/it/managed-settings) sull'host del runner: fornisce server HTTP e SSE senza prendere il controllo esclusivo, quindi i server dalle altre fonti si caricano ancora. Richiede Claude Code v2.1.259 o successivo.

271* `<repo>/.mcp.json`: ambito del progetto. Committare il file al repository; i suoi server sono pre-approvati nelle sessioni cloud.

272

273Quando la consegna del connettore è abilitata per l'organizzazione, il piano di controllo di Anthropic fornisce i connettori configurati su claude.ai alle sessioni create in modo interattivo attraverso la configurazione MCP fornita dal server, instradata attraverso `api.anthropic.com`. Le sessioni create a livello di programmazione, come i [dispatch CLI](/docs/it/self-hosted-environments-testing#run-the-test-loop), non ricevono la consegna del connettore; fornire loro server MCP attraverso una qualsiasi delle altre fonti che questa sezione elenca. Il token OAuth del figlio non porta un ambito per recuperare i connettori direttamente, quindi il figlio non tenta quel recupero stesso; la consegna è guidata dal server.

274

275`settings.json` non porta definizioni di server MCP, e non c'è un campo `mcpServers` di livello superiore nello schema delle impostazioni. Nelle impostazioni gestite, fornire server con la chiave [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) invece.

276

277Le sessioni ereditano l'ambiente del runner, quindi impostare [`ENABLE_TOOL_SEARCH`](/docs/it/mcp#scale-with-mcp-tool-search) lì per controllare la ricerca dello strumento MCP per ogni sessione che un runner genera; la pagina MCP copre i valori.

278

279<h2 id="prompt-sessions-to-push-their-work">

280 Prompt delle sessioni per spingere il loro lavoro

281</h2>

282

283Le sessioni ospitate da Anthropic eseguono un hook [`Stop`](/docs/it/hooks#stop), l'hook Claude Code che viene eseguito quando Claude finisce di rispondere, che richiede a Claude di committare e spingere il suo lavoro. Il runner non ne installa uno. Senza di esso, una sessione che termina con cambiamenti non committati lascia quel lavoro solo sul disco del runner, e il pulsante **Create PR** in claude.ai/code rimane inattivo fino a quando il ramo non esiste sul remoto.

284

285L'implementazione di riferimento di seguito ha due parti. Unire il blocco delle impostazioni in `~/.claude/settings.json` sull'host del runner, che il runner semina in ogni sessione, e salvare lo script come `~/.claude/hooks/stop-hook-nudge.sh` sull'host del runner e renderlo eseguibile:

286

287```json theme={null}

288{

289 "hooks": {

290 "Stop": [

291 {

292 "hooks": [

293 {

294 "type": "command",

295 "timeout": 10,

296 "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""

297 }

298 ]

299 }

300 ]

301 }

302}

303```

304

305```sh theme={null}

306#!/bin/sh

307# Implementazione di riferimento dello stop-hook per runner self-hosted.

308#

309# Spinge Claude una volta per turno se la directory del progetto ha cambiamenti

310# non committati O commit non spinti, in modo che il lavoro non vada perso quando

311# una sessione inattiva viene rilasciata e in modo che il pulsante "Create PR" su

312# claude.ai/code si illumini.

313#

314# Livello runner (nessun cambio del repository): rilasciare questo file in ~/.claude/hooks/

315# sull'host del runner e unire il blocco delle impostazioni dello stop-hook accompagnante

316# in ~/.claude/settings.json — il runner semina entrambi in ogni sessione.

317# Alternativa a livello di repository: committare a <repo>/.claude/hooks/ e cambiare il

318# percorso del comando settings.json a $CLAUDE_PROJECT_DIR/.claude/hooks/.

319#

320# stdin: payload JSON dell'hook (consultare https://code.claude.com/docs/en/hooks)

321# stdout: {"decision":"block","reason":"..."} per spingere, o nulla per consentire lo stop.

322

323# Guardia di rientrata: l'imbracatura imposta stop_hook_active=true quando reinvoca

324# lo stop hook dopo un blocco. Uscire in modo da spingere solo una volta per turno. L'

325# imbracatura emette JSON compatto (nessuno spazio dopo i due punti), che questo

326# pattern si basa; usare jq se hai bisogno di un controllo tollerante agli spazi bianchi.

327in=$(cat)

328case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

329

330d="$CLAUDE_PROJECT_DIR"

331

332# Non un repository git → nulla da spingere.

333git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

334

335# Nessun remoto → "spingere al remoto" è insodisfacibile; uscire.

336[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

337

338# Cambiamenti non committati (staged, unstaged o untracked). Escludere .claude/

339# interamente — le impostazioni seminate dall'operatore e lo stato di runtime scritto da CLI

340# (blocco dello scheduler, worktree, stato della routine) vivono lì e nessuno è

341# "lavoro non committato" che il modello ha bisogno di spingere.

342s=$(git -C "$d" status --porcelain -- . ':(exclude).claude/' 2>/dev/null)

343if [ -n "$s" ]; then

344 printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'

345 exit 0

346fi

347

348# Commit non spinti. Contare i commit su HEAD non raggiungibili da alcun

349# ref di tracciamento remoto o FETCH_HEAD. Questo funziona uniformemente per:

350# - checkout init+fetch (runner predefinito: solo FETCH_HEAD esiste)

351# - checkout basati su clone (origin/* esiste)

352# - il runner predefinito: il figlio inizia sul ramo di risultato della sessione,

353# che il runner crea dopo il checkout

354# - HEAD staccato, quando una configurazione personalizzata salta quella creazione di ramo

355# Senza alcun punto di riferimento (mai recuperato), rimanere silenzioso piuttosto che

356# falso positivo su un turno di sola lettura.

357base=""

358git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"

359if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then

360 exit 0

361fi

362# shellcheck disable=SC2086 # $base è "" o "FETCH_HEAD", word-split intenzionale

363unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0

364if [ "$unpushed" -gt 0 ]; then

365 branch=$(git -C "$d" symbolic-ref --short -q HEAD)

366 if [ -n "$branch" ]; then

367 # $branch è influenzato dall'attaccante — git-check-ref-format(1) consente `"`

368 # nei nomi dei ref. `\` è vietato (regola 10) ma comunque sfuggito come difesa

369 # economica in profondità.

370 # Sfuggire ai metacaratteri JSON prima di interpolare nel payload costruito a mano

371 # in modo che un ramo come x","continue":false non possa iniettare chiavi nel

372 # JSON di output dell'hook che l'imbracatura analizza. $unpushed è sicuro — il

373 # guard -gt sopra rifiuta qualsiasi cosa che non sia un semplice intero.

374 branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')

375 printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"

376 else

377 printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"

378 fi

379 exit 0

380fi

381

382exit 0

383```

384

385L'hook spinge Claude a committare e spingere prima della fine della sessione, e rimane silenzioso quando la directory non è un repository git o non ha un remoto.

386

387<h2 id="permissions-and-tool-approval">

388 Autorizzazioni e approvazione degli strumenti

389</h2>

390

391Una sessione self-hosted non ha un terminale allegato, quindi un prompt di autorizzazione senza risposta blocca il turno fino a quando l'utente non risponde nell'interfaccia utente. Il piano di controllo di Anthropic invia l'elenco degli strumenti di ogni sessione e le regole di autorizzazione con il payload di lavoro; la configurazione predefinita pre-approva le chiamate di routine, incluso `Bash`, e le sessioni cloud [pre-approvano le modifiche ai file indipendentemente dalla modalità](/docs/it/permission-modes#switch-permission-modes). Una chiamata che nulla pre-approva richiede attraverso l'interfaccia utente della sessione.

392

393<Note>

394 Pinare solo la modalità auto su un ambiente le cui sessioni contenitore vengono eseguite con [default-deny network egress](/docs/it/self-hosted-environments-deploy#default-deny-egress) e il resto della [sezione di hardening](/docs/it/self-hosted-environments-deploy#harden-your-deployment) in atto. Le chiamate di routine, incluse le richieste di rete `Bash`, vengono eseguite senza un umano nel ciclo sia sul set di strumenti pre-approvati predefinito che in modalità auto, quindi il confine di rete è ciò che limita dove quelle chiamate possono raggiungere.

395</Note>

396

397Per mantenere i prompt al minimo indipendentemente da ciò che il piano di controllo invia, pinare la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) dal script wrapper o dall'hook [`command`](#command). La modalità auto consente alle sessioni di funzionare senza prompt di autorizzazione di routine: un modello di classificatore separato esamina le azioni prima che vengono eseguite e blocca quelle che rifiuta, e le regole di richiesta esplicita forzano comunque un prompt; la pagina delle modalità di autorizzazione copre ciò che il classificatore controlla. Il runner aggiunge flag calcolati dal server prima di invocare il wrapper, e per flag a valore singolo come `--permission-mode` il parser onora l'ultima occorrenza, quindi un flag che si aggiunge dopo `"$@"` sovrascrive il valore inviato dal server:

398

399```bash theme={null}

400#!/bin/bash

401exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

402```

403

404Per pre-approvare strumenti specifici, aggiungere `--allowed-tools` con le proprie regole, ad esempio `--allowed-tools "Bash(bazel *) Bash(yarn *) mcp__internal__*"`. I flag di elenco come `--allowed-tools` e `--disallowed-tools` si accumulano tra le occorrenze piuttosto che sovrascrivere, quindi le proprie regole si applicano in cima a qualsiasi regola che il piano di controllo invia. Per restringere, aggiungere `--disallowed-tools`, che nega gli strumenti anche se un'altra regola li consente.

405

406<h3 id="how-each-session’s-config-is-assembled">

407 Come la configurazione di ogni sessione viene assemblata

408</h3>

409

410Il runner fornisce a ogni sessione la propria directory di configurazione, seminata da uno snapshot in memoria di `~/.claude/` dell'host che il runner acquisisce una volta all'avvio: `settings.json`, `CLAUDE.md`, hook, agenti, comandi e skill nell'immagine del runner si applicano a ogni sessione come baseline a livello di utente. Poiché lo snapshot viene acquisito all'avvio, i cambiamenti di configurazione su un host in esecuzione hanno effetto solo dopo un riavvio del runner. Impostare `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` per seminare da un percorso diverso, o puntarlo a una directory vuota per disabilitare la semina.

411

412Il `.claude/settings.json` committato nel repository si sovrappone come impostazioni del progetto. Le sessioni leggono anche [`managed-settings.json`](/docs/it/settings#where-settings-live) dal percorso di sistema standard nell'immagine del runner. Se le sue chiavi si applicano insieme alle [impostazioni gestite dal server](/docs/it/server-managed-settings) segue [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources): per impostazione predefinita, quando l'organizzazione fornisce qualsiasi chiave gestita dal server, le sessioni ignorano il file dell'immagine del runner a parte le [chiavi che Claude Code legge da ogni fonte di amministrazione](/docs/it/managed-settings#keys-read-from-every-admin-source), come il blocco `env`, i blocchi sandbox, i percorsi binari sandbox e `forceRemoteSettingsRefresh`. Consultare [settings precedence](/docs/it/settings#settings-precedence).

413

414Quando il piano di controllo di Anthropic fornisce una sessione con [hook Claude Code](/docs/it/hooks), il runner li installa insieme, non sopra, la propria configurazione. Richiede Claude Code v2.1.229 o successivo.

415

416* **Dove atterrano**: il runner scrive ogni script di hook fornito in una sottodirectory riservata `hooks/.ccr-launcher/` della directory di configurazione della sessione e registra gli script in un file di impostazioni separato che passa alla sessione con `--settings`, lasciando il `settings.json` seminato e i propri script in `hooks/<name>` intatti. Il runner ricrea la sottodirectory riservata per ogni sessione e non semina il contenuto dell'host in `~/.claude/hooks/.ccr-launcher/` nelle sessioni.

417* **Chi li crea**: il piano di controllo popola gli script da costanti fisse nella propria distribuzione, mai da input per sessione o di terze parti.

418* **Cosa ancora li governa**: gli hook forniti attraverso `--settings` entrano nella configurazione ordinaria dell'hook unito, non nel livello gestito, quindi le impostazioni gestite si applicano ancora. `disableAllHooks` li disabilita, e non sono tra le categorie che [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) mantiene caricate.

419

420<h3 id="repository-committed-permission-rules">

421 Regole di autorizzazione committate nel repository

422</h3>

423

424Non mettere una voce `"Edit"`, `"Write"` o `"NotebookEdit"` nuda in un `permissions.allow` committato nel repository. Una regola di strumento file nuda corrisponde allo strumento indipendentemente dal percorso, concedendo scritture ovunque sull'host piuttosto che solo l'area di lavoro, quindi la guardia di confinamento dell'ambito di scrittura del runner contrassegna la sessione; con [`--confine-repo-settings enforce`](/docs/it/self-hosted-environments-reference#runner-cli-flags) rifiuta di generare la sessione invece di registrare e continuare. Consultare la [sezione di hardening](/docs/it/self-hosted-environments-deploy#harden-your-deployment).

425

426Un repository non ha bisogno di alcuna regola di strumento file: le sessioni cloud [pre-approvano le modifiche ai file indipendentemente dalla modalità](/docs/it/permission-modes#switch-permission-modes). Se si committano una regola, limitarla all'area di lavoro, come `"Edit(/**)"`; una singola barra iniziale è relativa alla radice del progetto, che è l'area di lavoro della sessione. Le regole di strumento file nude vanno bene nel `settings.json` a livello di host dell'operatore, poiché quel file non è committato nel repository.

427

428Un `defaultMode` di `auto` è onorabile solo dal file di impostazioni a livello di immagine o a livello di utente, quindi un repository estratto non può concedere a se stesso la modalità auto. Per quali modalità le sessioni cloud accettano e la sintassi completa della regola, consultare [permission modes](/docs/it/permission-modes).

429

430<h2 id="what’s-next">

431 Cosa c'è dopo

432</h2>

433

434* [Reference](/docs/it/self-hosted-environments-reference): ogni flag CLI, variabile di ambiente e metrica

435* [Verify session identity](/docs/it/self-hosted-environments-identity): convalidare il token della sessione da servizi al di fuori del runner

self-hosted-environments-deploy.md +541 −0 created

Details

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.

5# Distribuisci ambienti self-hosted in produzione

7> Esegui runner self-hosted in produzione: hardening della sicurezza, controllo dell'egress di rete, credenziali git, ricette Kubernetes e Compose, e risoluzione dei problemi.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; [Disponibilità e limitazioni](/docs/it/self-hosted-environments#availability-and-limitations) copre il percorso di abilitazione. Questa pagina copre l'esecuzione della flotta in produzione; consulta la [guida rapida](/docs/it/self-hosted-environments-quickstart) per il tuo primo runner e sessione.

11</Note>

13Un [ambiente self-hosted](/docs/it/self-hosted-environments) esegue [sessioni cloud](/docs/it/claude-code-on-the-web) di Claude Code su runner che distribuisci all'interno della tua rete, e in produzione quelle sessioni eseguono codice diretto dal modello per conto di chiunque possa inviare una sessione all'ambiente. Questa pagina è per l'operatore che porta un ambiente funzionante in produzione. Funziona attraverso la distribuzione in ordine: cosa bloccare prima di connettere sistemi reali, l'egress di cui ha bisogno la flotta, come le sessioni si autenticano al tuo host git, le ricette di distribuzione stesse, e cosa controllare quando le sessioni si comportano male.

15<h2 id="harden-your-deployment">

16 Hardening della tua distribuzione

17</h2>

19Un runner self-hosted esegue codice arbitrario diretto dal modello sulla tua infrastruttura per conto di chiunque possa inviare una sessione al suo ambiente. Questo è qualsiasi membro della tua organizzazione Anthropic, e chiunque possa avviare una sessione del canale [Claude Tag](https://claude.com/docs/claude-tag/overview) in un ambito che un Owner ha instradato all'ambiente. Lavora su ogni elemento prima di connettere un ambiente ai sistemi di produzione:

21* **Container effimeri per sessione**: esegui ogni processo runner in un container o VM fresco che viene distrutto quando il processo esce, con `--capacity 1` e il valore predefinito `--drain-grace-sec 0` in modo che ogni container serva esattamente una sessione. A una capacità più alta, o con un drain grace positivo, un container serve più sessioni dallo stesso [owner bloccato](/docs/it/self-hosted-environments#key-concepts); vedi [Ciclo di vita del runner](/docs/it/self-hosted-environments#runner-lifecycle). Non riutilizzare un filesystem tra i riavvii del runner, tranne nella configurazione deliberata [pre-warmed checkout](#reuse-a-pre-warmed-checkout), e mai tra owner.

22* **Nessuna credenziale ampia nell'immagine**: non includere chiavi SSH di lunga durata, credenziali del provider cloud, o token di accesso personale che concedono più di quanto una sessione necessita. Crea credenziali utilizzate durante una sessione, come token push o API, per sessione dal tuo [script wrapper](/docs/it/self-hosted-environments-configuration#wrapper-scripts). Per il clone iniziale, che avviene prima che lo script wrapper venga eseguito, usa un [`checkout` lifecycle hook](/docs/it/self-hosted-environments-configuration#checkout) o [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy); vedi [Configura git](#configure-git).

23* **Mantieni il segreto dell'ambiente lontano dagli host che eseguono sessioni**: il segreto dell'ambiente può registrare runner e raccogliere qualsiasi sessione in coda sull'ambiente. Su una flotta fissa vive su ogni host runner, dove il codice di qualsiasi sessione può leggere il file segreto. Preferisci [runner on-demand](/docs/it/self-hosted-environments-configuration#on-demand-runners), dove il segreto rimane sull'host dell'orchestrator, che non esegue mai codice utente, e ogni runner riceve un ordine di lavoro monouso che registra esattamente un runner. Su una flotta fissa, tratta il file environment-secret come leggibile da ogni sessione e ruota il segreto dopo qualsiasi sospetto compromesso della sessione.

24* **Egress di rete default-deny**: limita il traffico in uscita del container runner e sessione al tuo confine di rete su ogni ambiente; [Default-deny egress](#default-deny-egress) copre cosa consentire e perché.

25* **IAM host con privilegi minimi**: l'identità di calcolo allegata all'host runner, come un profilo di istanza o un account di servizio del nodo, dovrebbe concedere solo ciò di cui il runner stesso ha bisogno. Le sessioni dovrebbero ottenere le proprie credenziali attraverso il tuo script wrapper piuttosto che ereditare quelle dell'host.

26* **Blocca l'endpoint dei metadati cloud dalle sessioni**: mantenere le sessioni fuori dall'identità dell'host richiede il blocco del loro accesso all'endpoint dei metadati cloud, e le politiche di egress a livello di subnet non intercettano il traffico dei metadati link-local, quindi bloccalo nel container stesso:

28 * IMDSv2 con un hop limit di uno

29 * GKE Workload Identity con metadata concealment

30 * Un esplicito deny per `169.254.169.254` nello spazio dei nomi di rete del container della sessione

32 Il blocco si applica anche al tuo script wrapper e ai lifecycle hook, poiché condividono il container. Autentica qualsiasi scambio di token con il [session JWT](/docs/it/self-hosted-environments-identity) contro il tuo servizio di token su egress allowlisted, o usa un'identità web basata su file come IAM Roles for Service Accounts (IRSA) su Amazon EKS.

33* **Isolamento del filesystem per runner**: ogni processo runner ottiene la propria directory di lavoro che nessun altro processo sull'host può leggere o scrivere. Rendi `--hooks-dir`, lo script wrapper, e la `~/.claude/` dell'host di sola lettura per la sessione, sia incorporato nell'immagine che montato in sola lettura.

34* **Dispatch non ha controllo di accesso per ambiente**: qualsiasi membro della tua organizzazione Anthropic può inviare una sessione a qualsiasi suo ambiente. Se un Owner [instrada i canali Claude Tag all'ambiente](/docs/it/cloud-environments#set-the-environment-a-claude-tag-channel-uses), chiunque l'[impostazione di accesso Claude Tag](https://claude.com/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude) ammette può avviare sessioni di canale che vengono eseguite lì. Per impostazione predefinita, questo è chiunque nell'area di lavoro Slack connessa, con o senza un account Claude. Tratta ogni host runner come raggiungibile per l'esecuzione di codice da parte di chiunque possa inviare a esso, e posiziona sull'host runner solo i dati e le credenziali che tutte quelle persone sono autorizzate a leggere. [`--lock-to-account`](/docs/it/self-hosted-environments-reference#runner-cli-flags) limita quale account le sessioni di un dato host eseguono, ma non restringe chi può inviare all'ambiente. Per rendere gli ambienti self-hosted l'unica opzione di selezione, un [Owner](/docs/it/cloud-environments#organization-shared-environments) può nascondere gli ambienti ospitati da Anthropic per l'intera organizzazione dalla pagina [**Cloud environments**](https://claude.ai/admin-settings/cloud-environments).

35* **Applica la guardia repo-settings**: scegli la modalità di guardia con [`--confine-repo-settings`](/docs/it/self-hosted-environments-reference#runner-cli-flags). Il valore predefinito `warn` registra una violazione e comunque genera la sessione, `enforce` rifiuta la sessione, e `off` disabilita la scansione. Il runner scansiona le impostazioni impegnate di ogni repository per:

37 * Una concessione che si risolve al di fuori dello spazio di lavoro della sessione stessa: una voce `additionalDirectories`, una regola `Edit`, `Write`, o `NotebookEdit` in `permissions.allow`, o una voce `sandbox.filesystem.allowWrite` o `allowRead`

38 * Un blocco `env` non vuoto

39 * Un override della postura dell'operatore come `sandbox.enabled: false`

41 La guardia viene eseguita indipendentemente da [`--trust-workspace`](/docs/it/self-hosted-environments-reference#runner-cli-flags), e non copre i repository hook, `.mcp.json`, o le regole Bash; vedi [Permessi e approvazione degli strumenti](/docs/it/self-hosted-environments-configuration#permissions-and-tool-approval) per dove quelle concessioni appartengono.

43<Note>

44 La lista di indirizzi IP consentiti della tua organizzazione non copre il traffico del runner self-hosted per impostazione predefinita. Non fare affidamento su di essa come controllo di rete per il traffico del runner o della sessione; applica invece default-deny egress al tuo confine di rete, e contatta il tuo team di account Anthropic se desideri l'applicazione della lista di indirizzi IP consentiti per la tua organizzazione.

45</Note>

47<h2 id="network-requirements">

48 Requisiti di rete

49</h2>

51Il runner e i figli della sessione che genera fanno connessioni in uscita agli host di seguito. Limita l'egress del container della sessione a questi host e ai servizi interni specifici che le sessioni devono raggiungere; [Default-deny egress](#default-deny-egress) copre come e perché.

53Questi host sono sempre richiesti:

55| Host | Porta | Utilizzato per |

56| :----------------------------------------------------------------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

57| `api.anthropic.com` | 443, HTTPS; WSS solo per il connettore SCM | Piano di controllo del runner e streaming della sessione, inferenza del modello, flag delle funzionalità, analitiche dei prodotti, recuperi della chiave [JWKS](/docs/it/self-hosted-environments-identity), firma dei commit, il proxy git quando `--use-anthropic-git-proxy` è impostato, e il tunnel [SCM connector](/docs/it/self-hosted-environments-reference#scm-connector-flags) dell'orchestrator quando `--scm-connector-host` è impostato |

58| Il tuo host git, come `github.com` o il tuo host GitHub Enterprise | 443 o 22 | Clonazione e push dei repository. Non necessario se il runner usa `--use-anthropic-git-proxy`, che instrada il traffico git attraverso `api.anthropic.com`. |

60Se questi host sono necessari dipende dalla tua configurazione:

62| Host | Porta | Quando richiesto |

63| :----------------------------------- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

64| `downloads.claude.ai` | 443 | Al momento dell'installazione, quando installi o aggiorni Claude Code sull'host con il programma di installazione nativo; lo script `install.sh` stesso viene servito da `claude.ai`. Al momento dell'esecuzione della sessione, solo quando le sessioni installano plugin dal marketplace ufficiale di Anthropic. |

65| `storage.googleapis.com` | 443 | Al momento dell'esecuzione della sessione, per i conteggi di installazione dei plugin e i metadati mostrati in `/plugin`. |

66| `code.claude.com` e `claude.com` | 443 | Ricerche di documentazione dall'agente claude-code-guide integrato e richieste WebFetch pre-approvate durante le sessioni. Il blocco di questi host influisce solo sulle ricerche di documentazione. |

67| `*.frame.claudeusercontent.com` | 443 | Solo quando lo [strumento Artifact](/docs/it/artifacts#availability) è disponibile per le sessioni nella tua organizzazione; i valori predefiniti variano in base al piano, secondo la tabella di disponibilità lì. Imposta `CLAUDE_CODE_DISABLE_ARTIFACT=1` sul runner per mantenere lo strumento disabilitato indipendentemente dall'impostazione dell'organizzazione. |

68| `registry.npmjs.org` | 443 | Quando una sessione installa un plugin, sia per il recupero dei pacchetti plugin da fonte npm che per l'installazione delle dipendenze Node.js di un plugin, o quando un server MCP lanciato da `npx` viene eseguito |

69| `http-intake.logs.us5.datadoghq.com` | 443 | Metriche operative di Anthropic. Solo quando `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` è impostato; disabilitato per impostazione predefinita negli ambienti self-hosted. |

70| `browser-intake-us5-datadoghq.com` | 443 | Caricamenti di rapporti di errore di Anthropic, inviati solo quando la [segnalazione di errori](/docs/it/data-usage#telemetry-services) è abilitata per l'account della sessione. Soppressa da `DISABLE_ERROR_REPORTING=1` o `DISABLE_TELEMETRY=1`. |

72Il runner non raggiunge `statsig.anthropic.com`, `*.sentry.io`, `claude.ai`, o `platform.claude.com`. Questi host appaiono in alcuni elenchi di controllo di rete enterprise più vecchi, ma non è necessario aggiungerli alla lista di indirizzi consentiti per il traffico del runner o della sessione: i recuperi dei flag delle funzionalità vanno a `api.anthropic.com`, e il runner si autentica con il segreto dell'ambiente piuttosto che con OAuth interattivo. Due flussi lato host raggiungono `claude.ai`, quindi eseguili da un host il cui egress lo consente piuttosto che ampliare l'egress del container della sessione: il programma di installazione a una riga recupera `install.sh` da `claude.ai` al momento dell'installazione, e il `claude auth login` interattivo, che la [configurazione guidata](/docs/it/self-hosted-environments-quickstart#set-up-an-environment-and-runner), la modalità firmata di `doctor`, e il [dispatch da CI](/docs/it/self-hosted-environments-testing#authenticate-from-ci) usano, accede attraverso `claude.ai`, `claude.com`, e `platform.claude.com`. `mcp-proxy.anthropic.com` non è richiesto neanche: le sessioni self-hosted non lo usano, e la consegna dei tuoi connettori claude.ai dell'organizzazione alle sessioni, quando abilitata per la tua organizzazione, viene instradata attraverso `api.anthropic.com`. Vedi [Server MCP](/docs/it/self-hosted-environments-configuration#mcp-servers).

74<h3 id="default-deny-egress">

75 Default-deny egress

76</h3>

78Distribuisci container runner e sessione in un segmento di rete o namespace il cui traffico in uscita è limitato agli host nella [tabella dei requisiti di rete](#network-requirements), al tuo host git, e ai servizi interni specifici che le sessioni devono raggiungere. Il prodotto non può verificare o applicare questo, quindi applicalo al tuo confine di rete su ogni ambiente. Il codice della sessione è diretto dal modello e può tentare connessioni a host arbitrari; default-deny egress a livello di rete limita dove questi tentativi possono atterrare. Questo si applica indipendentemente dalla modalità di permesso: il set di strumenti pre-approvato predefinito include già `Bash`, quindi l'egress della shell viene eseguito senza un prompt anche senza [modalità auto](/docs/it/self-hosted-environments-configuration#permissions-and-tool-approval).

80Per i dettagli su quale telemetria ogni sessione emette e come disattivarla, vedi [Telemetria](/docs/it/self-hosted-environments-reference#telemetry).

82<h3 id="authenticate-to-an-egress-proxy">

83 Autentica a un proxy di egress

84</h3>

86Alcuni proxy di egress aziendali richiedono un'intestazione `Proxy-Authorization` su ogni connessione. Il token in quell'intestazione spesso ruota troppo velocemente per essere scritto nell'URL del proxy che imposti in `HTTPS_PROXY`. Imposta `HTTPS_PROXY` o `HTTP_PROXY` all'URL del tuo proxy come al solito, quindi imposta `--proxy-authorization-command` o `--proxy-authorization-file` per dire al runner dove leggere il valore dell'intestazione. Entrambi i flag richiedono Claude Code v2.1.238 o successivo.

88<h4 id="choose-where-the-proxy-authorization-value-comes-from">

89 Scegli da dove viene il valore `Proxy-Authorization`

90</h4>

92Scegli il flag che corrisponde a come produci il token `Proxy-Authorization`:

94* **[`--proxy-authorization-command <command>`](/docs/it/self-hosted-environments-reference#runner-cli-flags)**: scegli questo per un token che generi su richiesta. Il runner esegue il comando della shell e usa il suo stdout ritagliato come valore dell'intestazione, ad esempio `Bearer <token>`.

95* **[`--proxy-authorization-file <path>`](/docs/it/self-hosted-environments-reference#runner-cli-flags)**: scegli questo per un token che un altro processo ruota in posizione. Il runner legge il file e usa i suoi contenuti ritagliati come valore dell'intestazione.

97<h4 id="configurations-the-runner-refuses-to-start-with">

98 Configurazioni che il runner rifiuta di avviare con

99</h4>

100

101Ogni flag ha anche una forma di variabile di ambiente, elencata accanto ad esso nel [riferimento dei flag CLI del runner](/docs/it/self-hosted-environments-reference#runner-cli-flags). Prima che il runner contatti il tuo proxy o il piano di controllo, controlla i flag e le loro variabili, e rifiuta di avviare in tre casi:

102

103* **Entrambi i flag impostati**: un flag più la variabile di ambiente dell'altro flag conta come impostazione di entrambi.

104* **Nessun URL proxy**: né `HTTPS_PROXY` né `HTTP_PROXY` contiene un URL `http://` o `https://`. Il runner legge entrambe le variabili in maiuscole o minuscole, e non consulta `ALL_PROXY`.

105* **Uno dei flag passato al sottocomando orchestrator**: `self-hosted-runner orchestrator` non accetta i flag o le loro variabili di ambiente. Passa il flag a ogni runner che l'orchestrator avvia invece.

106

107<h4 id="what-the-runner-changes-while-a-proxy-authorization-flag-is-set">

108 Cosa cambia il runner mentre un flag proxy-authorization è impostato

109</h4>

110

111Con uno dei flag impostati, il runner avvia un listener proprio e invia il traffico proxy da se stesso, dai suoi lifecycle hook, e dalle sue sessioni attraverso quel listener. Il listener aggiunge l'intestazione `Proxy-Authorization` sulla strada verso il tuo proxy.

112

113* **Listener**: il listener è un proxy forward su `127.0.0.1`. Il runner avvia il listener prima di registrarsi con il piano di controllo, e esce all'avvio se il listener non può avviarsi.

114* **Variabili proxy**: il runner riscrive quale di `HTTPS_PROXY` e `HTTP_PROXY` hai impostato in modo che punti al listener. Quel valore riscritto raggiunge il runner stesso, i suoi lifecycle hook, e ogni sessione che esegue.

115* **Rotazione del token**: un token ruotato ha effetto senza un riavvio. Per ogni connessione che il listener apre al tuo proxy, il runner esegue il tuo comando o legge di nuovo il tuo file e aggiunge il risultato come intestazione.

116* **Ambiente della sessione**: una sessione raggiunge il tuo proxy solo attraverso il listener. Nell'ambiente di ogni sessione il runner rimuove `ALL_PROXY`, rimuove qualsiasi ortografia di `HTTPS_PROXY` o `HTTP_PROXY` che non hai impostato, e fissa `NO_PROXY` al valore del runner stesso.

117* **Log**: il runner non registra mai il valore dell'intestazione.

118

119<h2 id="configure-git">

120 Configura git

121</h2>

122

123Il runner gestisce i checkout dei repository ma non configura l'identità git o le credenziali per impostazione predefinita. Controlli l'immagine e l'ambiente del processo del runner, quindi controlli la configurazione git. Scegli uno di due approcci:

124

125* **Lascia che il runner configuri git**: avvia il runner con `--configure-git` per fargli scrivere la stessa identità e configurazione di firma dei commit che usano le sessioni ospitate da Anthropic

126* **Spedisci la configurazione git nella tua immagine**: imposta l'identità e le credenziali push tu stesso, ad esempio per eseguire il commit sotto la tua identità bot

127

128Piani minimi di versione git sull'host runner: [`--configure-git`](#let-the-runner-configure-git) la firma dei commit SSH richiede Git 2.34 o più recente, [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) richiede 2.32 o più recente, e la ripresa delle sessioni da rami spinti da [`--push-outcome-on-release`](/docs/it/self-hosted-environments-reference#runner-cli-flags) richiede 2.29 o più recente. Git 2.24 è sufficiente se ometti tutti e tre e gestisci l'identità git tu stesso.

129

130<h3 id="let-the-runner-configure-git">

131 Lascia che il runner configuri git

132</h3>

133

134Avvia il runner con `--configure-git`, o imposta `SELF_HOSTED_RUNNER_CONFIGURE_GIT=1`, per fargli scrivere la configurazione git globale all'avvio:

135

136* `user.name = Claude` e `user.email = noreply@anthropic.com`, corrispondendo alle sessioni ospitate da Anthropic

137* Firma dei commit e dei tag in formato SSH, instradata attraverso uno shim gestito dal runner che firma ogni commit tramite il servizio di firma di Anthropic usando le credenziali della sessione stessa. Le firme sono verificabili su GitHub rispetto alla chiave di firma SSH pubblicata di Anthropic.

138* `push.negotiate = true`, in modo che git chieda al tuo host git quali commit ha già prima di impacchettare un push. Richiede Claude Code v2.1.257 o successivo.

139* `core.hooksPath` che punta a una directory di hook gestita dal runner. I suoi hook `commit-msg` e `prepare-commit-msg` aggiungono un trailer `Co-authored-by:` per il creatore della sessione a ogni commit, costruito dall'email in [`CCR_SESSION_ACCOUNT_EMAIL`](/docs/it/self-hosted-environments-configuration#wrapper-scripts) e omesso quando quella variabile non è impostata. Se la tua immagine imposta già `core.hooksPath`, il runner lascia la tua impostazione in posizione, salta l'installazione di questi hook, e stampa un avviso `[runner:git]`.

140

141La firma dei commit richiede git 2.34 o più recente; il runner controlla all'avvio e esce con un errore se il tuo git è più vecchio. Questo flag non configura le credenziali push, che fornisci comunque nell'immagine.

142

143<h3 id="ship-git-config-in-your-image">

144 Spedisci la configurazione git nella tua immagine

145</h3>

146

147L'identità git è richiesta per qualsiasi commit. Impostala a livello di sistema nel tuo Dockerfile in modo che la configurazione si applichi indipendentemente da quale utente il processo runner esegue:

148

149```dockerfile theme={null}

150RUN git config --system user.name "Claude" && \

151 git config --system user.email "noreply@anthropic.com"

152```

153

154Senza un'identità, `git commit` fallisce con `Please tell me who you are` e le sessioni non possono fare progressi. Puoi usare la tua identità bot invece; il runner non sovrascrive questi valori.

155

156Non incorporare credenziali push di lunga durata o ampiamente scoped in un'immagine runner condivisa: una credenziale nell'immagine è disponibile a ogni sessione che l'immagine esegue, chiunque l'abbia avviata. Invece, crea un token a breve durata, con scope minimo per sessione dal tuo [script wrapper](/docs/it/self-hosted-environments-configuration#wrapper-scripts), usando l'identità del creatore della sessione decodificata dal session JWT. Abbinalo a un container per sessione effimero, che richiede `--capacity 1`, in modo che nessuna credenziale sopravviva alla sessione che l'ha creata; vedi la [sezione hardening](#harden-your-deployment).

157

158Se devi configurare le credenziali push a livello di immagine, ad esempio per una chiave di distribuzione di sola lettura, limitale il più possibile:

159

160* Una chiave di distribuzione SSH limitata a un repository con una riscrittura `url.<base>.insteadOf`

161* Un `credential.helper` che restituisce un token con scope minimo

162* `GIT_SSH_COMMAND` che punta a una chiave con scope ristretto

163

164Qualsiasi meccanismo tu configuri deve funzionare senza un prompt, perché il clone integrato del runner e il fetch disabilitano i prompt che git, SSH, e Git Credential Manager mostrerebbero altrimenti:

165

166* Il runner imposta `GIT_TERMINAL_PROMPT=0`, in modo che git non chieda un nome utente o una password.

167* Il runner esegue SSH con `BatchMode=yes`, aggiunto al tuo `GIT_SSH_COMMAND` se ne imposti uno, in modo che SSH non chieda una passphrase o una conferma dell'host.

168* Il runner imposta `GCM_INTERACTIVE=never`, in modo che Git Credential Manager non apra una finestra di dialogo di accesso.

169* Il runner cancella `core.askPass`, quindi se usi un helper askpass, impostalo attraverso la variabile di ambiente `GIT_ASKPASS` invece.

170

171Se il tuo host git rifiuta la credenziale, o non ne hai configurata una, il runner riprova alcune volte e poi fallisce la preparazione del repository. Il runner non passa queste impostazioni nell'ambiente della sessione.

172

173Se le directory di checkout sono di proprietà di un uid diverso dal processo runner, git rifiuta di operare su di esse; aggiungi `safe.directory`:

174

175```dockerfile theme={null}

176RUN git config --system --add safe.directory '*'

177```

178

179<h3 id="use-the-anthropic-git-proxy">

180 Usa il proxy git di Anthropic

181</h3>

182

183Avvia il runner con `--use-anthropic-git-proxy`, o imposta `CLAUDE_RUNNER_USE_GIT_PROXY=1`, per fargli clonare attraverso il proxy git di Anthropic, autenticato con il token a breve durata della sessione stessa. Per le sessioni utente ordinarie, il proxy usa il token OAuth di GitHub o GitHub Enterprise memorizzato per il creatore della sessione; per le sessioni bot e agente, usa il token di installazione dell'app GitHub della tua organizzazione. In entrambi i casi, l'immagine del runner non ha bisogno di credenziali git: nessuna chiave SSH, nessun credential helper, nessun `.netrc`. Questo è lo stesso percorso di autenticazione che usano gli ambienti ospitati da Anthropic.

184

185Il proxy richiede `--capacity 1` perché l'URL del proxy è per sessione, e git 2.32 o più recente perché git più vecchio ignora il meccanismo di configurazione che il proxy usa per isolare le sessioni l'una dall'altra. Il runner rifiuta di avviarsi se uno dei due requisiti non è soddisfatto. Poiché il proxy recupera dal lato di Anthropic, il tuo host git deve essere raggiungibile dall'infrastruttura di Anthropic, lo stesso requisito che hanno le sessioni ospitate da Anthropic; per un host git che è solo instradabile all'interno della tua rete, usa un [`checkout` lifecycle hook](/docs/it/self-hosted-environments-configuration#checkout) invece. Ogni processo runner gestisce una sessione alla volta, quindi esegui più repliche per il parallelismo. Quando il proxy è abilitato, `--git-host-rewrite` e `--git-ssh-rewrite` non hanno effetto: l'URL del proxy punta a `api.anthropic.com`, non al tuo host git.

186

187Il runner segnala anche l'opt-in ad Anthropic quando si registra, stampando `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)` all'avvio. Ogni sessione su un runner con opt-in usa quindi o git gestito da Anthropic o l'URL del proxy per sessione. Quando una sessione usa l'URL del proxy per sessione, il runner registra una riga `[runner:warn]` dicendo così.

188

189<h3 id="rewrite-git-urls-for-private-networks">

190 Riscrivi gli URL git per le reti private

191</h3>

192

193Gli URL dei repository arrivano dal piano di controllo come HTTPS, con il nome host del tuo host git; per GitHub Enterprise, questo è il nome host che hai configurato per l'[integrazione GitHub Enterprise](/docs/it/github-enterprise-server) nelle impostazioni di amministrazione di Claude Code su claude.ai. Due flag ripetibili riscrivono quegli URL prima del clone:

194

195* `--git-host-rewrite <from>=<to>`: per split-horizon DNS, dove Anthropic raggiunge il tuo host git tramite un nome host esterno ma i runner devono usarne uno interno

196* `--git-ssh-rewrite <host>`: per host git che accettano solo SSH, riscrivendo `https://<host>/owner/repo` a `git@<host>:owner/repo`

197

198La riscrittura dell'host viene eseguita per prima, quindi elenca il nome host interno in `--git-ssh-rewrite` se hai bisogno di entrambi. Per il controllo completo del checkout, usa un [`checkout` lifecycle hook](/docs/it/self-hosted-environments-configuration#checkout).

199

200<h2 id="build-the-runner-image">

201 Costruisci l'immagine del runner

202</h2>

203

204Anthropic non pubblica un'immagine runner pre-costruita. Costruisci la tua intorno al binario `claude`, stratificando qualsiasi toolchain di cui i tuoi repository hanno bisogno: runtime di linguaggio, compilatori, gestori di pacchetti, e sidecar [MCP](/docs/it/mcp).

205

206Le ricette di seguito usano `--capacity 4`, in modo che un container serva fino a quattro sessioni concorrenti dallo stesso owner bloccato. Questo non fornisce l'isolamento del container per sessione nella [sezione hardening](#harden-your-deployment): prima di connettere un ambiente ai sistemi di produzione, esegui le ricette a `--capacity 1` con un container per sessione, o usa [runner on-demand](/docs/it/self-hosted-environments-configuration#on-demand-runners), che mantengono anche il segreto dell'ambiente lontano dagli host che eseguono sessioni.

207

208Questo Dockerfile è un punto di partenza minimo:

209

210```dockerfile theme={null}

211FROM debian:bookworm-slim

212ARG CLAUDE_CODE_VERSION

213RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client \

214 && rm -rf /var/lib/apt/lists/*

215RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \

216 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude

217RUN git config --system user.name "Claude" \

218 && git config --system user.email "noreply@anthropic.com" \

219 && git config --system --add safe.directory '*'

220ENTRYPOINT ["claude"]

221```

222

223Scambia `linux-x64` con `linux-arm64` se i tuoi nodi sono ARM, o con `linux-x64-musl` o `linux-arm64-musl` su un'immagine basata su musl come Alpine; vedi [Configurazione Alpine Linux](/docs/it/setup#alpine-linux-and-musl-based-distributions) per i pacchetti extra di cui le immagini musl hanno bisogno. L'URL è la posizione di rilascio standard di Claude Code, quindi puoi verificare il binario scaricato rispetto al manifesto firmato del rilascio come descritto in [Integrità binaria e firma del codice](/docs/it/setup#binary-integrity-and-code-signing). Costruisci l'immagine con Claude Code versione 2.1.224 o successiva, quindi spingila al tuo registro e fai riferimento ad essa nelle ricette di seguito:

224

225```bash theme={null}

226docker build --build-arg CLAUDE_CODE_VERSION=2.1.224 -t <your-registry>/claude-runner:latest .

227```

228

229<h2 id="size-cpu-and-memory-for-sessions">

230 Dimensiona CPU e memoria per le sessioni

231</h2>

232

233Dimensiona il container o l'host di un runner per le sessioni che esegue piuttosto che per il processo runner. Il runner stesso esegue il polling per il lavoro, prepara il checkout di ogni sessione, esegue i tuoi [lifecycle hook](/docs/it/self-hosted-environments-configuration#lifecycle-hooks), e avvia e supervisiona i processi della sessione. Il carico proviene dalle sessioni: ognuna è un processo Claude Code più tutto ciò che avvia, come build, suite di test, installazioni di pacchetti, e [server MCP](/docs/it/mcp).

234

235Per una sessione, inizia con i seguenti valori, indicati come richieste e limiti di Kubernetes o l'equivalente della tua piattaforma, e trattali come un punto di partenza piuttosto che un requisito:

236

237* **Memoria**: una richiesta e un limite di 4 GiB ciascuno, che soddisfa il minimo di 4 GB nei [requisiti di sistema](/docs/it/setup#system-requirements) di Claude Code. Mantieni i due uguali in modo che lo scheduler conti la memoria completa del container. Quando il container raggiunge il suo limite di memoria, il kernel uccide i processi al suo interno, il che può terminare una sessione a metà compito.

238* **CPU**: una richiesta di 2 CPU e un limite di 4 CPU, in modo che una sessione possa scoppiare sopra la richiesta durante le build. Il kernel limita un container al suo limite di CPU piuttosto che uccidere i processi al suo interno, quindi le sessioni al limite vengono eseguite più lentamente ma continuano a funzionare.

239

240In una specifica di container Kubernetes, imposta quei valori iniziali con il seguente blocco `resources`:

241

242```yaml theme={null}

243resources:

244 requests:

245 cpu: "2"

246 memory: 4Gi

247 limits:

248 cpu: "4"

249 memory: 4Gi

250```

251

252Le build e i test sono solitamente la parte più grande e più variabile del carico di una sessione, quindi esegui una build rappresentativa del tuo repository, misura il suo picco di CPU e memoria, e aumenta qualsiasi valore iniziale che non lascia spazio per il processo Claude Code in cima a quel picco.

253

254Il runner usa `--capacity` per limitare quante sessioni esegue contemporaneamente. Non divide CPU o memoria tra di loro, quindi le sessioni su un runner condividono la CPU e la memoria del container. Per limitare la quota di una sessione, applica limiti dal tuo [script wrapper](/docs/it/self-hosted-environments-configuration#wrapper-scripts). Cosa dare a un container quindi dipende da quante sessioni serve contemporaneamente:

255

256* **Una sessione per runner**: dai a ogni container i valori di una sessione. Usa questo dimensionamento a `--capacity 1`, che la [sezione hardening](#harden-your-deployment) consiglia, e per [runner on-demand](/docs/it/self-hosted-environments-configuration#on-demand-runners), dove imposti i valori sul carico di lavoro che il tuo hook [`spawn-runner`](/docs/it/self-hosted-environments-configuration#the-spawn-runner-hook) invia, come il modello di pod di un Kubernetes Job.

257* **Diverse sessioni per runner**: a un `--capacity` sopra uno, moltiplica i valori di una sessione per la capacità, perché fino a quel numero di sessioni possono essere eseguite nel container contemporaneamente. Le ricette [Kubernetes](#kubernetes) e [Docker Compose](#docker-compose) eseguono `--capacity 4` senza limiti di CPU o memoria, quindi aggiungi limiti dimensionati per la capacità che esegui.

258

259<h2 id="kubernetes">

260 Kubernetes

261</h2>

262

263Il runner serve `GET /healthz` sulla porta 8080 per impostazione predefinita, configurabile con `--health-port`, quindi i probe di Kubernetes funzionano senza configurazione extra. L'endpoint restituisce `200` ogni volta che il processo è vivo, quindi i probe di seguito rilevano un processo morto, non uno bloccato; per catturare un runner che ha smesso di eseguire il polling, avvisa sulla serie `last_poll_age_seconds` da [`/metrics`](/docs/it/self-hosted-environments-reference#prometheus-metrics). Il Deployment di seguito monta il segreto dell'ambiente da un Kubernetes Secret, punta i probe di liveness e readiness a `/healthz`, e imposta un periodo di grazia di terminazione di 90 secondi. Vedi [Shutdown timing](#shutdown-timing) per il motivo per cui il periodo di grazia è importante.

264

265Il manifesto non imposta `resources` di CPU o memoria sul container runner. Aggiungi un blocco dimensionato per la capacità che esegui, come [Dimensiona CPU e memoria per le sessioni](#size-cpu-and-memory-for-sessions) descrive.

266

267```yaml theme={null}

268apiVersion: apps/v1

269kind: Deployment

270metadata:

271 name: claude-runner

272 namespace: claude-runners

273spec:

274 replicas: 3

275 selector:

276 matchLabels:

277 app: claude-runner

278 template:

279 metadata:

280 labels:

281 app: claude-runner

282 app.kubernetes.io/part-of: claude-code-self-hosted-runner

283 spec:

284 terminationGracePeriodSeconds: 90

285 containers:

286 - name: runner

287 image: <your-registry>/claude-runner:latest

288 args:

289 - self-hosted-runner

290 - --environment-secret-file

291 - /etc/claude/environment-secret

292 - --capacity

293 - "4"

294 volumeMounts:

295 - name: environment-secret

296 mountPath: /etc/claude

297 readOnly: true

298 ports:

299 - name: health

300 containerPort: 8080

301 readinessProbe:

302 httpGet:

303 path: /healthz

304 port: 8080

305 initialDelaySeconds: 5

306 periodSeconds: 10

307 livenessProbe:

308 httpGet:

309 path: /healthz

310 port: 8080

311 initialDelaySeconds: 30

312 periodSeconds: 30

313 volumes:

314 - name: environment-secret

315 secret:

316 secretName: claude-runner-environment-secret

317```

318

319Il Deployment di sopra vive in uno spazio dei nomi `claude-runners`. Crea prima lo spazio dei nomi:

320

321```bash theme={null}

322kubectl create namespace claude-runners

323```

324

325Crea il Secret di supporto da un file locale che contiene il valore che hai copiato nel passaggio [**Copy environment key**](/docs/it/self-hosted-environments-quickstart#set-up-an-environment-and-runner) dell'interfaccia utente di amministrazione, in modo che il segreto non appaia mai nella tua cronologia della shell. Esegui `(umask 077 && cat > ./environment-secret)`, incolla il segreto, premi Invio, quindi Ctrl-D. Quindi crea il Secret e cancella il file:

326

327```bash theme={null}

328kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

329```

330

331<h2 id="docker-compose">

332 Docker Compose

333</h2>

334

335Il servizio Compose di seguito riavvia il runner ogni volta che esce, il che copre sia i crash che l'uscita normale dopo il drenaggio. Una politica di riavvio di Docker riavvia lo stesso container con il suo strato scrivibile intatto, quindi il runner torna su un filesystem riutilizzato piuttosto che su uno fresco che la [postura hardening](#harden-your-deployment) consiglia; usa questa ricetta per la valutazione, e per la produzione ricrea il container per esecuzione o usa un orchestrator che lo fa.

336

337```yaml theme={null}

338services:

339 claude-runner:

340 image: <your-registry>/claude-runner:latest

341 command:

342 - self-hosted-runner

343 - --environment-secret-file

344 - /run/secrets/environment-secret

345 - --capacity

346 - "4"

347 secrets:

348 - environment-secret

349 restart: always

350 stop_grace_period: 90s

351

352secrets:

353 environment-secret:

354 file: ./environment-secret

355```

356

357<h2 id="shutdown-timing">

358 Shutdown timing

359</h2>

360

361Su `SIGTERM`, il runner smette di accettare nuovo lavoro e, a meno che tu non imposti [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal), aspetta fino a `--drain-wait-sec`, zero per impostazione predefinita, affinché i turni in volo finiscano, termina il processo tree di ogni sessione, ed esegue il [`post-session` lifecycle hook](/docs/it/self-hosted-environments-configuration#post-session). Quel process tree include i comandi che Claude stava ancora eseguendo nella sessione.

362

363Il percorso di drenaggio completo ha bisogno di fino a `--session-stop-grace-sec` + `--drain-wait-sec` + `--post-session-hook-timeout-sec`, più 15 secondi di overhead fisso per la pulizia del processo, più 30 secondi in più quando [`--push-outcome-on-release`](/docs/it/self-hosted-environments-reference#runner-cli-flags) è impostato. Questo è 80 secondi ai valori predefiniti, e il runner registra il totale all'avvio. Le sessioni si drenano in parallelo sotto questo unico budget, quindi il totale non cresce con `--capacity`.

364

365Al valore predefinito `--drain-wait-sec 0`, un riavvio rolling interrompe i turni in volo; ogni sessione riprende su un altro runner, perdendo il lavoro non spinto come descritto sotto [Problemi noti](#additional-limitations). Imposta `--drain-wait-sec`, e aumenta il periodo di grazia per corrispondere, per lasciare che i turni finiscano per primi.

366

367Durante tutto quel percorso, il runner continua a fare heartbeat al piano di controllo a capacità zero, in modo che il lease della sessione non scada e venga rimesso in coda a un altro runner mentre il hook `post-session` sta ancora scrivendo il lavoro non impegnato. L'heartbeat si ferma proprio prima che il runner si deregistri.

368

369Dai al runner almeno il totale che registra all'avvio prima che l'host lo fermi. Dove imposti questo dipende da come i tuoi host si fermano:

370

371* **Con un periodo di grazia `SIGTERM`**: imposta `terminationGracePeriodSeconds` su Kubernetes, `stop_grace_period` su Docker Compose, o l'equivalente del tuo orchestrator ad almeno quel totale. Il valore predefinito di Kubernetes di 30 secondi è più breve del percorso di drenaggio del runner, quindi Kubernetes ferma il pod prima che il runner finisca il drenaggio.

372* **Con [`--retire-at`](/docs/it/self-hosted-environments-reference#runner-cli-flags)**: dimensiona il margine tra il tempo di ritiro e il tempo di arresto dell'host per coprire i turni tipici, più il hold del compito di background che [Runner lifecycle](/docs/it/self-hosted-environments#runner-lifecycle) descrive, più quel stesso totale. Calcola il tempo di ritiro ad ogni lancio, ad esempio `date +%s` più la durata prevista del runner.

373* **Con [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal)**: aggiungi due parti in più al totale del percorso di drenaggio. La prima è i minuti che configuri. La seconda è la grazia post-release che [Defer the drain past the first signal](#defer-the-drain-past-the-first-signal) descrive, 75 secondi ai valori predefiniti. Con il flag impostato, il runner stampa anche la figura combinata all'avvio, dopo il totale del percorso di drenaggio.

374

375<h3 id="defer-the-drain-past-the-first-signal">

376 Defer the drain past the first signal

377</h3>

378

379Imposta [`--defer-shutdown-max-min <n>`](/docs/it/self-hosted-environments-reference#runner-cli-flags) se desideri che un runner che stai riavviando continui a servire le sessioni che tiene per fino a `n` minuti, invece di drenare su il primo segnale. Al primo `SIGTERM` o `SIGINT`, il runner smette di accettare nuovo lavoro e continua a servire le sessioni che tiene. Continua a eseguire il polling in modo che il piano di controllo non rimetta in coda quelle sessioni. Richiede Claude Code v2.1.238 o successivo.

380

381<h4 id="what-happens-to-the-sessions-the-runner-holds-after-the-first-signal">

382 Cosa succede alle sessioni che il runner tiene dopo il primo segnale

383</h4>

384

385Nei primi due stadi che seguono il segnale, il runner rilascia le sessioni, e una sessione rilasciata riprende su un runner fresco quando il suo utente invia il suo prossimo messaggio. Contando dal primo segnale, il runner si muove attraverso tre stadi:

386

387* **Per i primi `n` minuti**: il runner serve le sue sessioni normalmente e continua a applicare `--startup-timeout-min` e `--kill-session-after-min`. Se imposti anche [`--release-idle-session-min`](/docs/it/self-hosted-environments-reference#runner-cli-flags), il runner rilascia qualsiasi sessione il cui utente è stato inattivo per quel tempo; senza di esso, le sessioni inattive rimangono sul runner.

388* **Quando i `n` minuti scadono**: il runner rilascia ogni sessione che ancora tiene, inattiva o no. Il runner aspetta che il turno di una sessione a metà turno finisca, e fino a 60 secondi in più per i compiti di background di un turno, prima di rilasciare quella sessione.

389* **Quando la grazia post-release scade**: il runner drena qualsiasi sessione che ancora tiene, e il piano di controllo rimette in coda ogni sessione drenata a un altro runner subito. La grazia post-release inizia quando i `n` minuti scadono ed è 75 secondi ai valori predefiniti. Se imposti `--drain-wait-sec` sopra 60 secondi, la grazia post-release è `--drain-wait-sec` più 15 secondi invece.

390

391In qualsiasi stadio, il runner esce 0 non appena non tiene sessioni. Un secondo segnale taglia gli stadi corti: il runner drena immediatamente, come fa al primo segnale senza `--defer-shutdown-max-min`. Una volta che un drenaggio è in corso, il prossimo segnale forza l'uscita del runner. Questo vale se un secondo segnale o la grazia post-release che scade ha avviato il drenaggio.

392

393<h4 id="size-the-stop-timeout">

394 Dimensiona il timeout di arresto

395</h4>

396

397Dai al timeout di arresto del tuo host almeno la somma di tre parti: i `n` minuti che configuri, la grazia post-release, e il percorso di drenaggio completo che [Shutdown timing](#shutdown-timing) descrive. Con le impostazioni predefinite la grazia post-release è 75 secondi e il percorso di drenaggio è 80 secondi, quindi consenti `n` minuti più 155 secondi. Il runner stampa questa somma all'avvio ogni volta che `--defer-shutdown-max-min` è impostato.

398

399Se il timeout di arresto scade prima che il runner finisca, l'host uccide il runner. Le sessioni che ancora tiene non ottengono nessun hook `post-session`. Il runner non si deregistra, e il piano di controllo rimette in coda le sessioni circa un minuto dopo. Se non puoi dare al timeout di arresto quella somma, lascia `--defer-shutdown-max-min` non impostato in modo che il runner dreni al primo segnale invece.

400

401<h3 id="what-reaches-a-running-post-session-hook">

402 Cosa raggiunge un hook post-session in esecuzione

403</h3>

404

405L'hook `post-session` e il figlio della sessione Claude ciascuno vengono eseguiti nel loro proprio gruppo di processo POSIX, separato da quello del runner, quindi i meccanismi di arresto li raggiungono diversamente:

406

407* **Un `SIGTERM` mentre il runner sta già drenando**: forza l'uscita del runner immediatamente, saltando tutto ciò che rimane del percorso di drenaggio. Senza [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal), questo è il secondo `SIGTERM` che il runner riceve. Niente segnala un hook `post-session` in esecuzione a metà, quindi su un host nudo dove un processo init adotta orfani, finisce da solo, ma non supervisionato: il suo budget di timeout non si applica più, e una scrittura al tubo di log chiuso può ucciderlo con `SIGPIPE`, quindi un hook che ha bisogno di sopravvivere a un'uscita forzata lì dovrebbe reindirizzare il suo output a un file. Nelle ricette di container su questa pagina il runner è il PID 1 del container e la sua uscita termina il container, e sotto il `KillMode=control-group` predefinito di systemd l'uccisione a livello di cgroup raggiunge anche l'hook, come la voce **Cgroup-wide kills** descrive; in entrambi, tratta un'uscita forzata come fatale per l'hook e fai affidamento al periodo di grazia invece.

408* **Segnali a livello di gruppo di processo**, come `kill -- -<pid>` in uno script wrapper, controllo del lavoro della shell, o un watchdog a livello di gruppo: raggiungono il runner e un sottoprocesso di hook `checkout` a metà, che rimane allegato al gruppo deliberatamente, ma non un hook `post-session` a metà esecuzione o il figlio della sessione.

409* **Uccisioni a livello di cgroup**, come il `KillMode=control-group` predefinito di systemd o il `SIGKILL` che Kubernetes consegna all'intero container quando `terminationGracePeriodSeconds` scade: raggiungono tutto, incluso l'hook. L'isolamento del gruppo di processo non protegge da questi, motivo per cui il periodo di grazia deve coprire il percorso di drenaggio completo.

410* **Il timeout dell'hook stesso**: quando un hook supera `--post-session-hook-timeout-sec`, il runner invia `SIGTERM` all'intero gruppo di processo dell'hook, quindi `SIGKILL` due secondi dopo, in modo che un worker che l'hook ha biforcato, come tar, rsync, o git, termini con la shell wrapper invece di sopravvivere come orfano. La supervisione del runner termina una volta che l'stdio dell'hook si chiude: un worker che ha reindirizzato il suo output a un file e sopravvive allo stadio `SIGTERM` è oltre la portata del runner.

411

412Quando il drenaggio inizia, e di nuovo su un'uscita forzata, il runner registra quanti hook `post-session` sono ancora in esecuzione, in modo che tu possa distinguere un drenaggio tranquillo da uno che è a metà snapshot.

413

414<h2 id="keep-the-base-directory-and-capacity-identical-across-runners">

415 Mantieni la directory di base e la capacità identiche tra i runner

416</h2>

417

418Se un runner muore a metà sessione, il server rimette in coda la sessione e un altro runner nell'ambiente la raccoglie. Quel runner deriva il percorso di checkout dal suo proprio `--base-dir` e `--capacity`: `--capacity 1` controlla direttamente sotto `--base-dir`, e un `--capacity` sopra `1` usa worktree per sessione invece. Quando i runner nello stesso ambiente usano valori diversi per uno dei due flag, la directory di lavoro della sessione ripresa cambia, e i percorsi assoluti che l'agente ha registrato in precedenza, in modifiche, chiamate di strumenti, o le sue stesse note, puntano a una posizione che non esiste più.

419

420Usa lo stesso `--base-dir` e `--capacity` su ogni runner in un ambiente, e non usare un valore per host come un ID istanza o nome host.

421

422La directory di base è predefinita a `/workspace`, con l'eccezione che la riga di riferimento [`--base-dir`](/docs/it/self-hosted-environments-reference#runner-cli-flags) registra. Il runner ha bisogno di accesso in scrittura ad essa. All'avvio, prima di registrarsi, il runner crea la directory e conferma che può scrivere ad essa, e esce con `cannot create or write to base directory` quando non può. Un runner avviato come root crea il `/workspace` predefinito da solo. Per un runner non root, crea la directory e dai al runner la proprietà dell'utente prima di avviare il runner, o punta `--base-dir` a una directory che l'utente già possiede.

423

424<h2 id="reuse-a-pre-warmed-checkout">

425 Riutilizza un checkout pre-riscaldato

426</h2>

427

428Per i repository grandi, il clone può dominare l'avvio della sessione. A `--capacity 1` senza un [`checkout` hook](/docs/it/self-hosted-environments-configuration#checkout), il runner mantiene un clone canonico per repository a `<base-dir>/<repo-owner>/<repo>` e lo riutilizza tra le sessioni: recupera il ref richiesto, stacca `HEAD`, e lo resetta duramente, il che è quasi istantaneo quando poco è cambiato. Per saltare il clone freddo, fornisci il clone in uno di due modi:

429

430* **Clone nell'immagine**: costruisci il clone nella tua immagine runner a quel percorso. Ogni container fresco inizia quindi con il clone caldo senza riutilizzare un disco.

431* **Clone su un volume persistente**: su runner che pre-blocchi a un account di un utente con [`--lock-to-account`](/docs/it/self-hosted-environments-reference#runner-cli-flags), punta `--base-dir` a un volume persistente, in modo che il disco serva solo quell'account. Un runner pre-bloccato non raccoglie mai sessioni di canale Claude Tag, quindi questa opzione non si applica ai runner che le servono.

432

433Cosa il percorso di riutilizzo fa e non garantisce:

434

435* **Qualsiasi forma di clone funziona**: un clone completo, shallow, o single-branch al percorso viene usato così com'è. Il runner non passa mai `--depth` quando recupera in un clone esistente, quindi un pre-warm completo mantiene la sua cronologia completa e uno shallow rimane shallow. `CLAUDE_RUNNER_FETCH_DEPTH` (`full`, `0`, o un numero; predefinito 50) controlla solo il clone freddo che il runner fa quando nessun clone esiste ancora.

436* **Le modifiche tracciate si resettano, i file non tracciati persistono**: ogni sessione inizia da un reset duro che cancella le modifiche tracciate della sessione precedente, ma il runner non esegue mai `git clean`, quindi i file non tracciati dalle sessioni precedenti dell'owner bloccato rimangono nell'albero.

437* **Con il proxy git, il reset diventa un checkout**: con [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), il runner sanitizza il `.git/` del clone prima di ogni sessione, mantenendo l'object store, i ref, e lo stato shallow ma eliminando l'indice, in modo che ogni sessione paghi un checkout completo dell'albero di lavoro invece di un reset quasi istantaneo; comunque non ri-clona mai. I pre-warm dei submodule non sono supportati sotto il proxy.

438* **I clone lunghi non hanno bisogno di workaround**: il runner limita ogni operazione git con un watchdog senza progresso di 120 secondi e un hard cap di 30 minuti, non un timeout piatto, quindi un clone freddo lento che continua a segnalare progresso si completa.

439

440<h2 id="pin-the-version">

441 Fissa la versione

442</h2>

443

444Il processo Claude Code figlio di ogni sessione esegue il binario del runner stesso, e il runner disattiva l'auto-aggiornamento all'interno delle sessioni che genera, quindi ogni sessione esegue la versione che hai installato sull'host o costruito nell'immagine. Un aggiornamento a livello di host ha effetto la prossima volta che il runner si avvia.

445

446* **Per mantenere una flotta su una versione**: costruisci l'immagine con una versione fissata, o su un host nudo installa una versione specifica e [disabilita gli auto-aggiornamenti](/docs/it/setup#disable-auto-updates)

447* **Per aggiornare**: installa la versione più recente o ricostruisci l'immagine, quindi riavvia i runner

448* **Plugin**: i marketplace dei plugin non si auto-aggiornano neanche; imposta `FORCE_AUTOUPDATE_PLUGINS=1` nell'ambiente del runner per lasciare che i plugin si auto-aggiornino mentre il binario rimane fissato

449

450<h2 id="scale-the-fleet">

451 Scala la flotta

452</h2>

453

454Il tuo orchestrator decide quando aggiungere o rimuovere runner. A causa del [blocco one-owner-per-runner](/docs/it/self-hosted-environments#runner-lifecycle), il numero minimo di repliche è il numero di utenti e agenti Claude Tag che ti aspetti siano attivi contemporaneamente; `--capacity` controlla il parallelismo all'interno delle sessioni di un owner, non tra owner.

455

456Due approcci di scaling sono disponibili:

457

458* **Flotta fissa**: esegui un set statico di repliche runner e scala sulle [metriche Prometheus](/docs/it/self-hosted-environments-reference#prometheus-metrics) che ogni runner serve

459* **Runner on-demand**: esegui il sottocomando `claude self-hosted-runner orchestrator`, che esegue il polling di Anthropic per le sessioni in coda senza runner disponibile e invoca il tuo hook `spawn-runner` per avviarne uno per sessione. Vedi [Runner on-demand](/docs/it/self-hosted-environments-configuration#on-demand-runners).

460

461<h2 id="known-issues-and-limitations">

462 Problemi noti e limitazioni

463</h2>

464

465Le seguenti sono le limitazioni in questa versione, con workaround dove uno esiste.

466

467<h3 id="connector-traffic-leaves-your-network">

468 Il traffico del connettore lascia la tua rete

469</h3>

470

471Anthropic chiama gli strumenti del connettore dalla sua stessa infrastruttura piuttosto che dal tuo runner. Gli strumenti del connettore sono i connettori claude.ai, come GitHub, Slack, e Linear. Quando Claude usa un connettore in una sessione self-hosted, quel traffico va attraverso `api.anthropic.com` piuttosto che originare all'interno del tuo confine di rete.

472

473Per mantenere un connettore fuori dalle sessioni self-hosted, filtralo con le [impostazioni di politica `allowedMcpServers` e `deniedMcpServers`](/docs/it/managed-mcp#policy-based-control-with-allowlists-and-denylists). Claude Code applica queste impostazioni ai connettori che Anthropic consegna così come ai server che semini dall'host runner e ai server che gli utenti aggiungono, quindi se distribuisci una lista di indirizzi consentiti per altri server, Claude Code blocca anche i connettori consegnati. Per mantenere i connettori disponibili insieme a una lista di indirizzi consentiti basata su URL, aggiungi voci che corrispondono ai percorsi proxy di Anthropic per i connettori consegnati:

474

475* `https://api.anthropic.com/v2/ccr-sessions/*`

476* `https://api.anthropic.com/v1/code/sessions/*`

477* `https://api.anthropic.com/v1/code/mcp/*`

478

479Se il traffico dello strumento deve rimanere all'interno della tua rete, esegui gli strumenti equivalenti come server MCP locali sull'immagine del runner invece. Vedi [Server MCP](/docs/it/self-hosted-environments-configuration#mcp-servers).

480

481<h3 id="some-sessions-don’t-count-as-idle">

482 Alcune sessioni non contano come inattive

483</h3>

484

485Una sessione che tiene un compito di background che non finisce mai non conta come inattiva, quindi `--release-idle-session-min` non rilascerà lo slot di quella sessione. Una sessione che sta aspettando un'approvazione richiesta dall'interno di una chiamata di strumento in esecuzione non conta neanche come inattiva. Imposta sempre `--kill-session-after-min` insieme ad essa come un hard backstop in modo che nessuna sessione possa tenere uno slot indefinitamente.

486

487`--kill-session-after-min` è un backstop per le sessioni runaway. Su un runner su v2.1.260 o successivo, una sessione che raggiunge il limite non viene terminata immediatamente. Il runner le dà una finestra di grazia, 15 minuti per impostazione predefinita, che puoi cambiare con [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](/docs/it/self-hosted-environments-reference#environment-variable-only-settings):

488

489* Se la sessione sta aspettando il suo utente, o il suo turno è finito e tiene solo compiti di background, il runner la rilascia subito. La sessione riprende quando il suo utente invia il suo prossimo messaggio.

490* Se un turno è ancora in esecuzione, il runner aspetta che il turno finisca, o che la sessione aspetti successivamente il suo utente, e poi la rilascia.

491* Se la sessione è ancora sul runner quando la finestra di grazia scade, il runner la termina, e il lavoro di qualsiasi turno in esecuzione è perso. Un turno che aspetta un'approvazione richiesta dall'interno di una chiamata di strumento in esecuzione è un modo in cui una sessione sopravvive alla finestra.

492

493Una sessione rilasciata riprende da un clone fresco, quindi il lavoro che non aveva spinto è comunque perso; vedi [Le sessioni riprese perdono il lavoro non spinto](#additional-limitations). Prima di v2.1.260, il runner terminava ogni sessione al limite, dopo aver aspettato al massimo la finestra di grazia affinché un turno in esecuzione finisca.

494

495Imposta il flag sopra la tua sessione più lunga prevista, come `--kill-session-after-min 480` per 8 ore. Per liberare slot dalle conversazioni che diventano inattive, usa `--release-idle-session-min` invece.

496

497<h3 id="additional-limitations">

498 Limitazioni aggiuntive

499</h3>

500

501* **Le sessioni riprese perdono il lavoro non spinto**: quando una sessione viene rilasciata o il suo runner viene riavviato, e l'utente invia un altro messaggio, la sessione riprende su un runner fresco che clona il repository di nuovo dal suo ramo iniziale, quindi il lavoro che la sessione non aveva spinto è perso. Imposta [`--push-outcome-on-release`](/docs/it/self-hosted-environments-reference#runner-cli-flags) per fare in modo che il runner faccia un best-effort push dei rami di risultato della sessione prima di rilasciarla, in modo che la sessione ripresa inizi da quei commit invece; questo preserva il lavoro impegnato, non un albero di lavoro sporco. Prima di abilitarlo, limita chi può spingere ai ref `claude/*` sul remote di origine, ad esempio con un branch ruleset: al momento della ripresa, il runner recupera il ramo precedentemente spinto senza verificare chi l'ha spinto, quindi chiunque abbia accesso push a quei ref può posizionare contenuto nello spazio di lavoro ripreso. Il runner scarta anche la configurazione per sessione al momento della ripresa, il che significa la directory di configurazione Claude della sessione e qualsiasi stato della shell che la sessione ha scritto; `--push-outcome-on-release` non copre quelli.

502* **I repository privati non possono essere aggiunti a metà sessione**: un repository aggiunto a una sessione dopo che è iniziato non viene clonato con credenziali su un runner self-hosted, quindi l'aggiunta fallisce. Seleziona ogni repository di cui la sessione ha bisogno quando la crei.

503* **Alcuni connettori non appaiono nelle sessioni self-hosted**: un connettore che non hai ancora connesso nelle Impostazioni di claude.ai non è elencato in una sessione self-hosted, e la sessione non ti chiederà di connettarlo. Connettilo prima nelle Impostazioni, quindi avvia una sessione fresca. L'aggiunta di un connettore a una sessione già in esecuzione non rende i suoi strumenti disponibili a Claude; avvia una sessione fresca per raccogliere un connettore appena aggiunto.

504

505<h3 id="report-an-issue">

506 Segnala un problema

507</h3>

508

509Per i problemi con gli ambienti self-hosted, contatta il tuo team di account Anthropic.

510

511<h2 id="troubleshooting">

512 Troubleshooting

513</h2>

514

515Per una diagnosi guidata, eseguire il subcommand doctor sull'host del runner. Il subcommand doctor avvia una sessione Claude Code interattiva con i log e lo stato del runner allegati. Accedere con `claude auth login` su quell'host prima in modo che la sessione possa interrogare l'ambiente, i suoi runner e le sue sessioni in coda. Senza questo accesso, ad esempio quando l'host si autentica con una chiave API, è limitato all'endpoint di salute locale, alle metriche e al log del runner, e legge il log solo se è stato avviato il runner con `--log-file`.

516

517```bash theme={null}

518claude self-hosted-runner doctor

519```

520

521Problemi comuni:

522

523* **Il runner non appare nell'ambiente**: confermare che l'host possa raggiungere `api.anthropic.com` su HTTPS, che il segreto dell'ambiente sia attuale e che l'orologio dell'host sia entro cinque minuti dall'ora reale; uno scostamento maggiore causa il fallimento dell'autenticazione. Il runner registra `[runner:fatal]` con il motivo del rifiuto in caso di errore di autenticazione.

524* **Il runner esce all'avvio con `cannot create or write to base directory`**: il runner non può creare o scrivere in `--base-dir`, che per impostazione predefinita è `/workspace`. Correggere la proprietà della directory o puntare `--base-dir` a un percorso scrivibile, come descritto in [Keep the base directory and capacity identical across runners](#keep-the-base-directory-and-capacity-identical-across-runners). Se il runner registra invece `[runner:fatal]` dicendo che il controllo della directory di base è scaduto, la directory si trova su un mount NFS o CSI bloccato. Controllare l'integrità del mount piuttosto che i permessi. Il runner stampa entrambi questi errori di avvio su stderr prima di aprire `--log-file`, quindi cercarli nel terminale o nei log del container della piattaforma piuttosto che nel file di log. Prima della v2.1.225, il runner non controllava la directory di base all'avvio e questa configurazione errata causava il fallimento delle sessioni dopo il pickup.

525* **Le sessioni rimangono in coda**: ogni runner online può essere bloccato a un proprietario diverso. Controllare la [metrica](/docs/it/self-hosted-environments-reference#prometheus-metrics) `claude_code_self_hosted_runner_locked_account` di ogni runner o il campo `locked_account` della sua riga di log `[runner:health]` per vedere chi la detiene. Entrambi mostrano l'email del proprietario solo dopo che il runner ha ricevuto un token di sessione con un claim `act.email`, che le sessioni di un agente Claude Tag non hanno mai. Senza il claim, il runner non emette alcuna serie `locked_account` e registra `locked_account=yes`, il che indica che il runner è bloccato ma non a quale proprietario. Aggiungere repliche o attendere che un runner esistente si svuoti e si riavvii. Se l'ambiente utilizza runner on-demand, controllare l'orchestrator; vedere [On-demand runners](/docs/it/self-hosted-environments-configuration#on-demand-runners).

526* **Le sessioni falliscono immediatamente dopo il pickup**: aprire la sessione in claude.ai/code per vedere l'errore. Le cause più comuni sono le [credenziali git](#configure-git) mancanti nell'immagine del runner e gli strumenti di compilazione non installati. Una directory di base non scrivibile arresta il runner all'avvio invece di far fallire le sessioni. Vedere la voce **Il runner esce all'avvio con `cannot create or write to base directory`** in questo elenco.

527* **Le sessioni non riescono a raggiungere la rete attraverso un proxy di uscita autenticante**: quando l'origine impostata con [`--proxy-authorization-command` o `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) fallisce, scade dopo 30 secondi o produce un valore vuoto, il runner risponde a quella connessione con `502 Bad Gateway` e registra il motivo. Il runner redige lo stderr del comando in quel log e non registra mai il valore dell'intestazione. Con `--proxy-authorization-command`, eseguire il comando stesso sull'host per confermare che stampa l'intero valore dell'intestazione su stdout. Se il runner esce invece all'avvio con `could not start the proxy-authorization listener`, non ha potuto aprire il suo listener di loopback.

528* **Il runner registra righe `Poll failed` contenenti `rejecting the malformed poll response`**: il runner ha ricevuto una risposta di work-poll il cui corpo non è il JSON previsto dalla coda, il più delle volte perché qualcosa tra il runner e `api.anthropic.com`, come un proxy intercettante o un portale captive, ha risposto con la sua stessa pagina. Il runner rifiuta la risposta, la conta sotto il tipo `transport` della [metrica](/docs/it/self-hosted-environments-reference#prometheus-metrics) `claude_code_self_hosted_runner_poll_errors_total`, e riprova secondo la pianificazione di poll fallito descritta in [Session lifecycle](/docs/it/self-hosted-environments#session-lifecycle). Il runner continua a servire le sue sessioni live. Configurare il proxy per passare le risposte da `api.anthropic.com` inalterate. Prima della v2.1.246, il runner leggeva tale risposta come una coda di lavoro vuota, il che potrebbe terminare le sue sessioni live o farla uscire.

529* **Il ramo di una sessione non esiste più sul remoto**: per un'origine git che la sessione legge solo, il runner salta quella origine e continua con le rimanenti. Per l'origine a cui la sessione spinge i risultati, un ramo eliminato, tipicamente perché è stato unito e auto-eliminato, fa fallire la sessione con un errore che nomina il repository e il ramo e chiede di ripristinare il ramo e riprovare. Il runner fa fallire la sessione con lo stesso errore quando saltare lascerebbe senza alcun repository. Prima della v2.1.228, tale sessione iniziava in una directory vuota.

530* **Le sessioni impiegano minuti per avviarsi**: il clone iniziale di solito domina. Osservare la [metrica](/docs/it/self-hosted-environments-reference#prometheus-metrics) `claude_code_self_hosted_runner_session_init_duration_seconds` per confermare e ridurre il clone con un [pre-warmed checkout](#reuse-a-pre-warmed-checkout) o un `CLAUDE_RUNNER_FETCH_DEPTH` più piccolo.

531* **Il pod viene terminato durante lo scarico**: aumentare `terminationGracePeriodSeconds` ad almeno il valore che il runner registra all'avvio. Vedere [Shutdown timing](#shutdown-timing).

532

533Una volta inizializzata la registrazione, il runner scrive il suo log del ciclo di vita, incluse le righe `[runner:fatal]`, su stdout e l'output di debug su stderr, il tutto come righe di testo semplice piuttosto che JSON. Gli errori di avvio descritti nelle voci di troubleshooting sopra stampano su stderr prima di quel punto. Acquisire entrambi i flussi con `--log-file`, che consente anche a `self-hosted-runner doctor` di seguirli, o con la raccolta di log della piattaforma. Il processo figlio di ogni sessione scrive un log di debug separato. In caso di errore il runner preserva il log, stampa il percorso del log nel log del runner e visualizza la coda del log insieme alla sessione in claude.ai/code.

534

535<h2 id="what’s-next">

536 Cosa c'è dopo

537</h2>

538

539* [Personalizza le sessioni](/docs/it/self-hosted-environments-configuration): script wrapper, lifecycle hook, runner on-demand, server MCP, e permessi

540* [Testa end to end](/docs/it/self-hosted-environments-testing): verifica una nuova immagine runner da CI prima di promuoverla

541* [Riferimento](/docs/it/self-hosted-environments-reference): ogni flag CLI, variabile di ambiente, e metrica

self-hosted-environments-identity.md +270 −0 created

Details

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.

5# Verificare l'identità della sessione negli ambienti self-hosted

7> Verificare il JWT CLAUDE_CODE_SESSION_ACCESS_TOKEN in modo che i servizi sulla vostra rete possano fidarsi delle richieste provenienti da sessioni nel vostro ambiente self-hosted.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; un [Owner](/docs/it/cloud-environments#organization-shared-environments) li abilita attivando **Allow self-hosted environments** nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). Questa pagina copre la verifica dell'identità della sessione; consultare la [guida rapida](/docs/it/self-hosted-environments-quickstart) per la configurazione e [Deploy to production](/docs/it/self-hosted-environments-deploy) per le ricette della flotta.

11</Note>

13Un [ambiente self-hosted](/docs/it/self-hosted-environments) consente alle sessioni di [Claude Code sul web](/docs/it/claude-code-on-the-web) di eseguirsi su infrastrutture che voi gestite invece che su quelle di Anthropic. Poiché la sessione viene eseguita all'interno della vostra rete, Claude può chiamare direttamente i vostri servizi interni. Questi servizi hanno bisogno di un modo per confermare che una richiesta proviene da una sessione Claude Code nel vostro ambiente e per identificare l'identità dell'utente o del servizio che ha creato quella sessione.

15Ogni sessione in un ambiente self-hosted riceve un JSON Web Token (JWT) firmato nella variabile di ambiente `CLAUDE_CODE_SESSION_ACCESS_TOKEN`. Una sessione presenta il token come qualsiasi credenziale bearer; ad esempio, uno script che Claude esegue può chiamare il vostro servizio con `curl -H "Authorization: Bearer $CLAUDE_CODE_SESSION_ACCESS_TOKEN"`. Anthropic firma il token e pubblica le chiavi di verifica in un endpoint JWKS pubblico. I vostri servizi recuperano quelle chiavi, verificano la firma e leggono i claim per decidere quale accesso concedere.

17<h2 id="the-session-token">

18 Il token della sessione

19</h2>

21Prima di scrivere il codice di verifica, sapete cosa stabilisce il token e la forma che la vostra libreria JWT vedrà.

23<h3 id="what-the-token-proves">

24 Cosa prova il token

25</h3>

27Un token valido stabilisce alcuni fatti e deliberatamente non altri:

29* **Prova**: Anthropic ha emesso il token per una sessione specifica in un ambiente specifico e come è stata creata la sessione: da un utente nella vostra organizzazione, o dall'identità del servizio della vostra organizzazione, che è come iniziano le [sessioni del canale Claude Tag](https://claude.com/docs/claude-tag/concepts/agent-identity)

30* **Non prova**: quale processo sull'host del runner lo presenta. Il token si trova in una variabile di ambiente all'interno della sessione, quindi qualsiasi codice che Claude esegue e qualsiasi tool o server MCP che la sessione avvia può leggerlo e presentarlo.

32Due conseguenze per i vostri servizi:

34* Verificate il claim `aud` rispetto all'ID del vostro ambiente, il valore `ccpool_...` mostrato con il vostro ambiente nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments), per rifiutare i token emessi per l'ambiente di qualsiasi altra organizzazione.

35* Limitate le credenziali che derivate dal token a quello che una singola sessione di codifica dovrebbe essere in grado di fare, non a tutto quello che il creatore della sessione può fare. Consultare [Scope derived credentials](#scope-derived-credentials).

37<h3 id="token-format">

38 Formato del token

39</h3>

41Il valore di `CLAUDE_CODE_SESSION_ACCESS_TOKEN` ha un prefisso `sk-ant-cc-` seguito da un JWT standard a tre parti:

43```text theme={null}

44sk-ant-cc-<base64url header>.<base64url payload>.<base64url signature>

45```

47Rimuovete il prefisso prima di passare il valore a una libreria JWT. I token emessi per le sessioni cloud ospitate da Anthropic portano invece un prefisso `sk-ant-si-` e sono firmati da un diverso set di chiavi, quindi rifiutate qualsiasi valore che non inizi con `sk-ant-cc-`.

49L'algoritmo di firma è `ES256`, che è ECDSA sulla curva P-256 con SHA-256. L'intestazione del token porta un `kid` che identifica quale chiave nel JWKS lo ha firmato.

51<h2 id="verify-the-token">

52 Verificare il token

53</h2>

55La verifica viene eseguita in uno di due posti. I servizi sulla vostra rete verificano il token crittograficamente rispetto alle chiavi pubblicate da Anthropic, e gli script wrapper all'interno della sessione possono invece utilizzare il decoder integrato del binario del runner.

57<h3 id="verify-the-token-from-your-service">

58 Verificare il token dal vostro servizio

59</h3>

61Anthropic pubblica le chiavi di verifica in un endpoint pubblico e non autenticato:

63```text theme={null}

64https://api.anthropic.com/v1/code/.well-known/jwks.json

65```

67La risposta è un [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517) standard. Anthropic ruota periodicamente le chiavi di firma e le chiavi precedenti a una rotazione rimangono nel set abbastanza a lungo affinché i token che hanno firmato continuino a verificarsi, quindi non fissate una singola chiave. L'endpoint imposta `Cache-Control: public, max-age=300`, quindi memorizzare nella cache il set di chiavi e recuperarlo ogni cinque minuti è sicuro.

69Verificate ogni token in arrivo rispetto a questi controlli:

71<Steps>

72 <Step title="Controllare il prefisso">

73 Rifiutate il valore se non inizia con `sk-ant-cc-`, quindi rimuovete quel prefisso. Il resto è un JWT compatto standard.

74 </Step>

76 <Step title="Verificare la firma">

77 Recuperate il JWKS, selezionate la chiave il cui `kid` corrisponde all'intestazione del token e verificate la firma `ES256`. Rifiutate i token il cui header `alg` non è `ES256`. Se un token arriva con un `kid` che non è nel vostro set di chiavi memorizzato nella cache, recuperate il JWKS una volta prima di rifiutarlo: dopo una rotazione, i nuovi token sono firmati con una chiave che il vostro set memorizzato nella cache non ha ancora.

78 </Step>

80 <Step title="Verificare l'emittente">

81 Rifiutate il token se `iss` non è esattamente `ccr`.

82 </Step>

84 <Step title="Verificare il pubblico rispetto al vostro ambiente">

85 Il claim `aud` è un array. Rifiutate il token a meno che non contenga l'ID del vostro ambiente, che ha la forma `ccpool_...`. L'ID dell'ambiente è mostrato nella finestra di dialogo dei dettagli del vostro ambiente nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments) e appare come il claim `ccr:pool_id` in qualsiasi token di sessione dell'ambiente. Questo controllo è quello che limita il token al vostro ambiente e rifiuta i token emessi per altre organizzazioni.

86 </Step>

88 <Step title="Verificare il ruolo">

89 Rifiutate il token se `ccr:role` non è esattamente `session_worker`. Altri token emessi per ambienti self-hosted, come i segreti dell'ambiente, i token del runner e gli ordini di lavoro, sono firmati dallo stesso set di chiavi ma portano ruoli diversi.

90 </Step>

92 <Step title="Verificare la scadenza">

93 Rifiutate il token se `exp` è nel passato. Anthropic emette i token di sessione con una durata di vita di quattro ore per impostazione predefinita e un massimo di otto ore. Il runner aggiorna il token prima della scadenza e invia il nuovo valore alla sessione, quindi i sottoprocessi che Claude avvia dopo un aggiornamento lo ereditano. Una sessione può quindi presentare diversi token validi distinti al vostro servizio nel corso della sua durata.

94 </Step>

96 <Step title="Leggere l'identità">

97 L'identità dell'utente che crea è nel claim `act`: `act.sub` è il suo ID utente Anthropic nella forma con prefisso `user:<id>` e `act.email`, quando la superficie di creazione ne ha registrato uno, è il suo indirizzo email. Le sessioni che l'identità del servizio della vostra organizzazione crea, incluse le sessioni del canale Claude Tag, portano invece un soggetto `agent:`, quindi trattate una sessione come creata dall'utente solo quando `act.sub` porta il prefisso `user:`, piuttosto che testare se i claim di identità sono assenti. Consultare il [riferimento dei claim](#claims-reference) per la struttura completa e i claim duplicati piatti.

98 </Step>

99</Steps>

100

101I controlli si mappano direttamente sulle librerie JWT standard. Gli esempi seguenti implementano la sequenza completa in Node.js con [`jose`](https://www.npmjs.com/package/jose), che gestisce il recupero JWKS, la memorizzazione nella cache e la selezione di `kid`, e in Python con [`PyJWT`](https://pyjwt.readthedocs.io/) e il suo client JWKS integrato.

102

103<Tabs>

104 <Tab title="Node.js (jose)">

105 ```typescript theme={null}

106 import { createRemoteJWKSet, jwtVerify } from "jose";

107

108 const JWKS = createRemoteJWKSet(

109 new URL("https://api.anthropic.com/v1/code/.well-known/jwks.json")

110 );

111

112 const PREFIX = "sk-ant-cc-";

113 const EXPECTED_POOL_ID = "ccpool_...";

114

115 export async function verifySessionToken(raw: string) {

116 if (!raw.startsWith(PREFIX)) {

117 throw new Error("not a self-hosted runner session token");

118 }

119 const jwt = raw.slice(PREFIX.length);

120

121 const { payload } = await jwtVerify(jwt, JWKS, {

122 issuer: "ccr",

123 audience: EXPECTED_POOL_ID,

124 algorithms: ["ES256"],

125 });

126

127 if (payload["ccr:role"] !== "session_worker") {

128 throw new Error("token is not a session_worker token");

129 }

130

131 const act = payload.act as { email?: string; sub?: string };

132 return {

133 sessionId: payload["ccr:session_id"] as string,

134 poolId: payload["ccr:pool_id"] as string,

135 orgId: payload["ccr:org_id"] as string,

136 creatorEmail: act?.email,

137 creatorSub: act?.sub,

138 };

139 }

140 ```

141 </Tab>

142

143 <Tab title="Python (PyJWT)">

144 ```python theme={null}

145 import jwt

146 from jwt import PyJWKClient

147

148 JWKS_URL = "https://api.anthropic.com/v1/code/.well-known/jwks.json"

149 PREFIX = "sk-ant-cc-"

150 EXPECTED_POOL_ID = "ccpool_..."

151

152 jwks = PyJWKClient(JWKS_URL)

153

154

155 def verify_session_token(raw: str) -> dict:

156 if not raw.startswith(PREFIX):

157 raise ValueError("not a self-hosted runner session token")

158 token = raw.removeprefix(PREFIX)

159

160 signing_key = jwks.get_signing_key_from_jwt(token)

161 payload = jwt.decode(

162 token,

163 signing_key.key,

164 algorithms=["ES256"],

165 issuer="ccr",

166 audience=EXPECTED_POOL_ID,

167 )

168

169 if payload.get("ccr:role") != "session_worker":

170 raise ValueError("token is not a session_worker token")

171

172 act = payload.get("act") or {}

173 return {

174 "session_id": payload["ccr:session_id"],

175 "pool_id": payload["ccr:pool_id"],

176 "org_id": payload["ccr:org_id"],

177 "creator_email": act.get("email"),

178 "creator_sub": act.get("sub"),

179 }

180 ```

181 </Tab>

182</Tabs>

183

184<h3 id="verify-the-token-inside-the-session">

185 Verificare il token all'interno della sessione

186</h3>

187

188Gli [script wrapper](/docs/it/self-hosted-environments-configuration#wrapper-scripts) vengono eseguiti all'interno della sessione, prima che Claude inizi. Invece di chiamare una libreria JWT, possono eseguire il sottocomando `self-hosted-runner decode-token` del binario del runner. Il sottocomando legge il token da un argomento posizionale, da `CLAUDE_CODE_SESSION_ACCESS_TOKEN` o da stdin piped, in quell'ordine, quindi rimuove il prefisso, verifica la firma rispetto all'endpoint JWKS, controlla la scadenza e stampa i claim come JSON. Il sottocomando esegue solo i controlli di firma e scadenza; non controlla `iss`, `aud` o `ccr:role`. Quando la decisione di autenticazione del vostro wrapper dipende da questi claim, leggete i claim dal JSON stampato e confrontateli esplicitamente.

189

190Questo comando estrae l'identità del creatore, preferendo il soggetto del provider SSO, quindi l'indirizzo email, quindi il soggetto `act.sub` del creatore, `user:<id>` o `agent:<id>`:

191

192```bash theme={null}

193"$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token | jq -re '.act.attested_by.sub // .act.email // .act.sub'

194```

195

196I wrapper ricevono il percorso assoluto al binario del runner stesso in `CLAUDE_RUNNER_CLAUDE_BIN`; utilizzate quel percorso piuttosto che un `claude` risolto da PATH in modo che la decodifica venga eseguita sullo stesso binario che il runner stesso utilizza.

197

198Utilizzate `jq -re` piuttosto che `jq -r` in modo che un claim mancante causi un'uscita diversa da zero. Con solo `-r`, un claim mancante stampa la stringa letterale `null` e esce con zero, il che passa silenziosamente un valore errato a valle. Passate `--no-verify` a `decode-token` solo per l'ispezione offline dove l'endpoint JWKS è irraggiungibile.

199

200<h2 id="claims-reference">

201 Riferimento dei claim

202</h2>

203

204La tabella seguente elenca i claim del token di sessione rilevanti per la verifica. Leggete l'identità dallo spazio dei nomi `ccr:*` e dalla catena `act`; i claim piatti `account_email`, `organization_uuid` e `account_uuid` sono duplicati di compatibilità all'indietro che potrebbero essere rimossi. Le sessioni che l'identità del servizio della vostra organizzazione crea, incluse le sessioni del canale Claude Tag, portano un soggetto `agent:` in `act.sub` e omettono `act.email`, `ccr:account_id`, `account_email` e `account_uuid`. I due claim di email sono facoltativi anche per le sessioni create dall'utente: Anthropic li registra al momento della creazione della sessione solo quando le credenziali della richiesta di creazione portano un'email, e una sessione inviata dalla CLI può mancare di entrambi, quindi basate l'identità su `act.sub` o `ccr:account_id` piuttosto che su email. I token possono anche portare claim aggiuntivi oltre questa tabella; ignorate i claim che non riconoscete.

205

206| Claim | Tipo | Descrizione |

207| :------------------ | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| `iss` | string | Sempre `ccr`. |

209| `sub` | string | `ccr:session:<session_id>`. |

210| `aud` | array di string | Contiene sempre `anthropic-api`. Per le sessioni negli ambienti self-hosted l'array contiene anche l'ID del vostro ambiente, come `ccpool_...`. Verificate l'ID dell'ambiente, non `anthropic-api`. |

211| `exp` | number | Scadenza come timestamp Unix. Durata di vita predefinita di quattro ore, massimo di otto ore. |

212| `iat` | number | Emesso come timestamp Unix. |

213| `jti` | string | Identificatore univoco del token. |

214| `ccr:role` | string | Sempre `session_worker` per i token di sessione. |

215| `ccr:session_id` | string | L'ID della sessione. Stesso valore del suffisso di `sub`. |

216| `ccr:pool_id` | string | L'ID del vostro ambiente. Stesso valore che appare in `aud`. |

217| `ccr:org_id` | string | L'ID della vostra organizzazione Anthropic. |

218| `ccr:account_id` | string | L'ID dell'account Anthropic dell'utente che crea: il valore di `act.sub` senza il prefisso `user:`, un ID taggato `user_...`. Lo stesso valore che il `CLAUDE_RUNNER_ACCOUNT_ID` dell'[hook spawn-runner](/docs/it/self-hosted-environments-configuration#the-spawn-runner-hook) porta e che [`--lock-to-account`](/docs/it/self-hosted-environments-reference#runner-cli-flags) accetta, quindi i tre si confrontano come stringhe uguali. |

219| `account_email` | string | Duplicato di `act.email`; assente ogni volta che `act.email` lo è. |

220| `organization_uuid` | string | L'UUID della vostra organizzazione Anthropic. |

221| `account_uuid` | string | L'UUID dell'account Anthropic dell'utente che crea. |

222| `act` | object | Catena di delega [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693). Consultare [La catena `act`](#the-act-chain). |

223

224<h3 id="the-act-chain">

225 La catena `act`

226</h3>

227

228Il claim `act` registra il percorso di delega completo dall'identità dell'utente o del servizio che ha creato la sessione fino all'[ambiente](/docs/it/self-hosted-environments#key-concepts) il cui segreto ha ammesso il runner e l'identità che ha creato quel segreto. Il creatore è l'attore più esterno, quindi `act.sub` li identifica direttamente.

229

230| Percorso | Descrizione |

231| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

232| `act.sub` | L'ID utente Anthropic dell'utente che crea, nella forma `user:<id>`, o `agent:<id>` quando l'identità del servizio della vostra organizzazione ha creato la sessione, come fa per le sessioni del canale Claude Tag. |

233| `act.email` | L'indirizzo email dell'utente che crea, quando uno è stato registrato al momento della creazione della sessione. Non lo richiedete; basate su `act.sub`. |

234| `act.attested_by` | L'attestazione del provider di identità upstream per l'utente che crea, quando disponibile. `act.attested_by.sub` è il soggetto che il vostro provider SSO, come Google o Okta, ha emesso. Preferite questo a `act.email` quando mappate a identità nei vostri sistemi. |

235| `act.act` | Il runner che ha generato la sessione. `act.act.sub` è `ccr:runner:<runner_id>`. |

236| `act.act.act` | L'ambiente. `act.act.act.sub` è `ccr:pool:<pool_id>`. |

237| `act.act.act.act` | L'identità che ha creato il segreto dell'ambiente con cui il runner si è registrato. La catena termina qui. |

238

239<h2 id="scope-derived-credentials">

240 Scope derived credentials

241</h2>

242

243Il token di sessione identifica l'utente o l'identità del servizio che ha creato la sessione, ma non lo trattate come equivalente a quel creatore che accede direttamente. Il token si trova in una variabile di ambiente all'interno della sessione, quindi qualsiasi codice che Claude esegue e qualsiasi tool o server MCP che la sessione avvia può leggerlo e presentarlo.

244

245La verifica è anche offline: un token che verifica rispetto al JWKS rimane valido fino al suo `exp`, qualunque cosa sia accaduta alla sessione da allora, e Anthropic non pubblica un feed di revoca per i token di sessione. Limitate qualsiasi cosa deriviate dal token di conseguenza.

246

247Quando il vostro servizio scambia il token per credenziali interne, emettete credenziali limitate a quello che una sessione di codifica dovrebbe raggiungere:

248

249* **Limitate le capacità**: concedete accesso in lettura e scrittura alle risorse di cui la sessione ha bisogno per i compiti di codifica, non alle capacità amministrative che il creatore detiene altrove.

250* **Limitate la durata**: limitate le credenziali derivate al `exp` del token, o più breve.

251* **Controllate come la sessione**: registrate `ccr:session_id` e `jti` insieme all'identità del creatore in modo da poter tracciare le azioni di nuovo a una sessione specifica.

252

253<h2 id="related-environment-variables">

254 Variabili di ambiente correlate

255</h2>

256

257L'identità del creatore appare anche in variabili di ambiente semplici su due superfici che non verificano mai il token:

258

259* **L'[hook `spawn-runner`](/docs/it/self-hosted-environments-configuration#the-spawn-runner-hook), sull'orchestratore**: l'hook viene eseguito prima che esista un runner per una sessione in coda e riceve l'identità del creatore in variabili come `CLAUDE_RUNNER_ACCOUNT_EMAIL` e `CLAUDE_RUNNER_ACCOUNT_ID`. L'orchestratore le legge dall'ordine di lavoro, il token firmato monouso che autorizza l'avvio di un runner, senza verificare la firma dell'ordine di lavoro stesso; i claim sono attendibili perché l'ordine di lavoro arriva sulla connessione dell'orchestratore ad Anthropic, che il segreto dell'ambiente autentica.

260* **[Script wrapper](/docs/it/self-hosted-environments-configuration#wrapper-scripts), all'interno della sessione**: i wrapper ricevono `CCR_SESSION_ACCOUNT_EMAIL`, l'email del creatore pre-estratta dal token senza verifica della firma. La variabile è adatta per l'etichettatura, come i trailer di commit, non per le decisioni di autenticazione.

261

262Utilizzate le variabili semplici per le decisioni lato orchestratore come la selezione di un'immagine di macchina. Utilizzate `CLAUDE_CODE_SESSION_ACCESS_TOKEN` quando un servizio a valle ha bisogno di una prova crittografica indipendente piuttosto che fidarsi dell'ambiente del runner.

263

264<h2 id="what’s-next">

265 Cosa c'è dopo

266</h2>

267

268* [Self-hosted environments](/docs/it/self-hosted-environments): l'ambiente, il runner e il modello di sessione; la [guida rapida](/docs/it/self-hosted-environments-quickstart) e [Deploy to production](/docs/it/self-hosted-environments-deploy) contengono la configurazione e le operazioni

269* [Customize sessions](/docs/it/self-hosted-environments-configuration): script wrapper che consumano il token e l'hook `spawn-runner`

270* [Reference](/docs/it/self-hosted-environments-reference): flag CLI, variabili di ambiente e metriche

self-hosted-environments-quickstart.md +128 −0 created

Details

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.

5# Guida rapida agli ambienti self-hosted

7> Configura il tuo primo ambiente self-hosted: installa Claude Code, crea l'ambiente, avvia un runner e indirizza una sessione ad esso.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; [Disponibilità e limitazioni](/docs/it/self-hosted-environments#availability-and-limitations) copre il percorso di abilitazione. Questa pagina avvia la tua prima sessione; vedi [Ambienti self-hosted](/docs/it/self-hosted-environments) per sapere cosa sono e [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy) per l'hardening e le ricette di fleet.

11</Note>

13Un [ambiente self-hosted](/docs/it/self-hosted-environments) esegue [sessioni cloud](/docs/it/claude-code-on-the-web) di Claude Code su infrastrutture che la tua organizzazione gestisce, eseguite da processi runner che distribuisci. Questa guida rapida configura il tuo primo, il più piccolo che funziona: un runner su un singolo host, che esegue una sessione di test. Ci sono due passaggi: [crea l'ambiente, avvia un runner e indirizza una sessione ad esso](#set-up-an-environment-and-runner), quindi [invia un messaggio a quella sessione dal tuo terminale](#send-a-follow-up-message-to-a-running-session). Ti sposterai tra due superfici: claude.ai per creare l'ambiente, controllarne lo stato e indirizzare una sessione, e un terminale sull'host per tutto ciò che il runner fa.

15Alla fine avrai un ambiente nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments), un runner che esegue il polling per il lavoro, e una sessione in esecuzione sul tuo host. Prima di connettere repository reali o sistemi interni, lavora attraverso [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy), che copre il profilo di sicurezza, il controllo dell'egress, le credenziali git e l'orchestrazione.

17<h2 id="prerequisites">

18 Prerequisiti

19</h2>

21<h3 id="organization-and-roles">

22 Organizzazione e ruoli

23</h3>

25Il lato claude.ai ha bisogno di:

27* **Allow self-hosted environments** attivato da un [Owner](/docs/it/cloud-environments#organization-shared-environments) nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments); il pulsante **New** non appare finché non è attivato. Se non hai il ruolo, qualcuno che lo ha può creare l'ambiente e passarti il suo secret; i passaggi del runner e del terminale su questa pagina non richiedono alcun ruolo claude.ai, e dove un passaggio controlla lo stato nell'interfaccia di amministrazione, le proprie righe di log del runner ti danno lo stesso segnale.

28* Una [connessione GitHub](/docs/it/claude-code-on-the-web#github-authentication-options) per la tua organizzazione, in modo che gli sviluppatori possano selezionare repository quando avviano sessioni.

30<h3 id="host-and-network">

31 Host e rete

32</h3>

34L'host del runner ha bisogno di:

36* Un host o container Linux o macOS con HTTPS in uscita verso `api.anthropic.com`, verso `claude.ai` e gli host di download a cui reindirizza per il passaggio di installazione sottostante, e verso il tuo host git per il clone; la [tabella dei requisiti di rete](/docs/it/self-hosted-environments-deploy#network-requirements) ha l'elenco completo. Windows non è supportato come host runner; esegui il runner in un container Linux invece. Le workstation degli sviluppatori non sono interessate, poiché le sessioni iniziano da claude.ai in un browser.

37* Un orologio sincronizzato all'ora reale, ad esempio con NTP. L'autenticazione fallisce quando l'orologio è più di cinque minuti indietro; vedi [Troubleshooting](/docs/it/self-hosted-environments-deploy#troubleshooting).

39<h3 id="software-on-the-runner-host">

40 Software sull'host del runner

41</h3>

43Installa sull'host prima di iniziare:

45* **Claude Code v2.1.224 o successivo**, con uno qualsiasi dei [metodi di installazione standard](/docs/it/setup). Il runner fa parte del binario `claude` standard, e le versioni precedenti non riconoscono il subcommand `self-hosted-runner`. Il canale `latest` dell'installer nativo porta ogni release non appena viene pubblicata; il canale `stable`, il cask Homebrew `claude-code`, e i repository apt, dnf e apk stabili rimangono indietro di circa una settimana. Per fissare la versione esatta che la tua fleet esegue, vedi [Installa una versione specifica](/docs/it/setup#install-a-specific-version). Per le immagini container, vedi il Dockerfile in [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy#build-the-runner-image).

46* **Git 2.24 o più recente**. Alcune opzioni git nella pagina di distribuzione richiedono versioni più recenti; [Configura git](/docs/it/self-hosted-environments-deploy#configure-git) indica ogni limite.

48Conferma che l'host è pronto:

50```bash theme={null}

51claude self-hosted-runner --help

52```

54Un host pronto stampa il testo di utilizzo del runner, elencando flag come `--environment-secret-file`. Sulle versioni precedenti a 2.1.224, il comando stampa l'output `claude --help` generale invece; aggiorna con `claude update` o reinstalla dal canale `latest`.

56<h2 id="set-up-an-environment-and-runner">

57 Configura un ambiente e un runner

58</h2>

60Claude Code include una configurazione guidata: una sessione Claude Code interattiva che ti guida attraverso la creazione dell'ambiente nell'interfaccia di amministrazione, avvia un runner locale con il file secret che salvi, conferma che il runner si registra, e scrive un foglio di aiuto in `./runner-setup/CHEAT-SHEET.md`. Eseguilo su una macchina dove hai effettuato l'accesso con `claude auth login` usando un account che detiene un ruolo Owner; non è disponibile con chiavi API o provider di modelli di terze parti. Su host dove una sessione interattiva non è possibile, usa i passaggi manuali sottostanti invece. Conferma che il [controllo della versione](#software-on-the-runner-host) è passato per primo: sulle versioni precedenti a 2.1.224, questo comando avvia una sessione Claude ordinaria con le parole come prompt invece della configurazione guidata. Per avviare la configurazione guidata, esegui il subcommand setup e segui i prompt:

62```bash theme={null}

63claude self-hosted-runner setup

64```

66Per configurare manualmente invece:

68<Steps>

69 <Step title="Crea un ambiente">

70 Vai alla [pagina **Cloud environments**](https://claude.ai/admin-settings/cloud-environments) nelle impostazioni di amministrazione. Sotto **Self-hosted environments**, seleziona **New**, nomina l'ambiente, e seleziona **Create**. Nel secondo passaggio della procedura guidata, seleziona **Copy environment key** per copiare il secret dell'ambiente, che l'interfaccia di amministrazione etichetta come environment key. claude.ai mostra il secret una volta, e non puoi recuperarlo in seguito; scade 365 giorni dopo la creazione. L'ID `ccpool_...` dell'ambiente rimane visibile nella sua finestra di dialogo dei dettagli; ne avrai bisogno per il controllo `aud` nella [verifica del token](/docs/it/self-hosted-environments-identity) e per l'invio di [sessioni di test da CI](/docs/it/self-hosted-environments-testing#run-the-test-loop).

72 Se perdi il secret o hai bisogno di ruotarlo, crea un nuovo secret dalla scheda **Configuration** dell'ambiente, distribuisci il nuovo secret ai tuoi runner, quindi revoca quello vecchio. I runner che detengono un secret revocato falliscono il loro prossimo poll autenticato ed escono, registrando `poll auth failed`, e il tuo orchestrator li riavvia con il nuovo secret.

73 </Step>

75 <Step title="Avvia un runner">

76 Crea la directory del secret. Questo passaggio e il successivo richiedono root per il percorso `/etc/claude`; qualsiasi percorso che il processo runner può leggere funziona, quindi regola entrambi i comandi e il valore `--environment-secret-file` insieme se ne usi uno diverso.

78 ```bash theme={null}

79 mkdir -p /etc/claude

80 ```

82 Scrivi il secret dell'ambiente in un file. Il comando sottostante legge dal tuo terminale in modo che il secret rimanga fuori dalla cronologia della shell: incolla il valore che hai copiato, premi Invio, quindi Ctrl-D, e l'`umask` della subshell rende il file leggibile solo dal suo proprietario.

84 ```bash theme={null}

85 (umask 077 && cat > /etc/claude/environment-secret)

86 ```

88 Scegli una directory di base, sostituendo `<writable-dir>` nel comando del runner sottostante con un percorso assoluto che il runner può scrivere o creare. Il runner crea la directory all'avvio, quindi controlla i repository e crea directory per sessione sotto di essa. Senza `--base-dir` usa `/workspace`, che funziona solo se quella directory esiste già ed è scrivibile o avvii il runner come root.

90 Se il runner non può creare o scrivere nel percorso, esce all'avvio con un errore che nomina la directory invece di registrarsi. Vedi [Troubleshooting](/docs/it/self-hosted-environments-deploy#troubleshooting).

92 Quindi avvia il runner con `--environment-secret-file` e `--base-dir`. Il runner si registra con il tuo ambiente e inizia il polling per il lavoro. Se il runner esce, riavvialo manualmente. Le distribuzioni di produzione eseguono il runner sotto un orchestrator che riavvia i runner usciti, normalmente con un filesystem fresco per ogni riavvio; [Riutilizza un checkout pre-riscaldato](/docs/it/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout) copre la configurazione del disco persistente supportata.

94 ```bash theme={null}

95 claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

96 ```

97 </Step>

99 <Step title="Verifica che il runner appaia">

100 Ritorna alla [pagina **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). Lo stato del tuo ambiente cambia da **No runners deployed** a **Healthy** entro pochi secondi dall'avvio del runner; apri l'ambiente e seleziona **Activity** per vedere il runner stesso.

101 </Step>

102

103 <Step title="Indirizza una sessione all'ambiente">

104 Avvia una sessione su claude.ai/code e seleziona il tuo ambiente dal selettore di ambiente, dove gli ambienti self-hosted appaiono insieme a quelli ospitati da Anthropic. Il runner clona con qualsiasi credenziale git che l'host ha già, quindi scegli un repository che questo host può già clonare, o uno pubblico; le opzioni di credenziale per i repository privati in produzione sono su [Configura git](/docs/it/self-hosted-environments-deploy#configure-git). Il prossimo runner disponibile raccoglie la sessione in coda e registra `Picked up session <session-id>` insieme al suo conteggio attivo e alla capacità, in modo che tu possa confermare dall'output del runner stesso quale host ha preso la sessione. Guarda la sessione lavorare e leggi le risposte di Claude su [claude.ai/code](https://claude.ai/code). Se la sessione rimane in coda invece, vedi [Troubleshooting](/docs/it/self-hosted-environments-deploy#troubleshooting).

105 </Step>

106</Steps>

107

108Il runner esce per progettazione una volta che le sue sessioni attive finiscono; vedi [Runner lifecycle](/docs/it/self-hosted-environments#runner-lifecycle). Per la produzione, distribuiscilo sotto un orchestrator che lo riavvia all'uscita. Vedi [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy).

109

110<h2 id="send-a-follow-up-message-to-a-running-session">

111 Inviare un messaggio di follow-up a una sessione in esecuzione

112</h2>

113

114Una volta che una sessione è in esecuzione nel vostro ambiente, inviatele un follow-up dalla CLI `claude` su qualsiasi macchina dove siete collegati con `claude auth login`; il comando non ha bisogno di essere eseguito dalla macchina che ha avviato la sessione. Il comando invia un messaggio:

115

116```bash theme={null}

117claude -p "your message" --cloud <session-id>

118```

119

120Per `<session-id>`, passate l'ID bare `session_...` o `cse_...` oppure l'URL claude.ai/code della sessione. Un invio riuscito stampa `Sent to cloud session.` con l'ID della sessione e un link di visualizzazione. I moduli di ID accettati, l'output JSON, i requisiti dell'account e della policy, e il riferimento agli errori si trovano su [Send follow-ups from the CLI](/docs/it/claude-code-on-the-web#send-follow-ups-from-the-cli), poiché il comando funziona allo stesso modo contro le sessioni ospitate da Anthropic.

121

122<h2 id="what’s-next">

123 Cosa c'è dopo

124</h2>

125

126* [Distribuisci in produzione](/docs/it/self-hosted-environments-deploy): indurire la distribuzione, controllare l'egress, configurare le credenziali git, ed eseguire la fleet sotto Kubernetes o Compose

127* [Personalizza sessioni](/docs/it/self-hosted-environments-configuration): script wrapper, hook del ciclo di vita, runner on-demand, server MCP, e permessi

128* [Testa end to end](/docs/it/self-hosted-environments-testing): un test di fumo CI che invia una sessione e legge le risposte di Claude

self-hosted-environments-reference.md +342 −0 created

Details

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.

5# Riferimento per ambienti self-hosted

7> Riferimento completo per il runner self-hosted e l'orchestrator: flag CLI, variabili d'ambiente e metriche Prometheus.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; un [Owner](/docs/it/cloud-environments#organization-shared-environments) li abilita attivando **Allow self-hosted environments** nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments). Questa pagina è il riferimento per flag e metriche; consultare la [guida rapida](/docs/it/self-hosted-environments-quickstart) per la configurazione e [Deploy to production](/docs/it/self-hosted-environments-deploy) per le ricette della flotta.

11</Note>

13Questa pagina è il riferimento per i due processi che eseguite in un [ambiente self-hosted](/docs/it/self-hosted-environments): il runner, che esegue le [sessioni cloud](/docs/it/claude-code-on-the-web) di Claude Code sui vostri host, e l'orchestrator di autoscaling opzionale, che avvia i runner mentre le sessioni si accodano. Ognuno ha la propria tabella di flag. Entrambi vengono eseguiti su host Linux o macOS, per i quali i valori predefiniti come `/workspace` e `~/.claude` sono presupposti. Eseguite `claude self-hosted-runner --help` per l'elenco autorevole sulla vostra versione installata.

15Le serie di metriche e alcuni campi API utilizzano ancora `pool` per quello che queste pagine chiamano un ambiente; entrambi i termini denominano la stessa cosa. L'ID dell'ambiente è il campo `pool_id`, con la forma `ccpool_...`: ovunque queste pagine mostrino un identificatore `pool`, esso denomina l'ambiente. I flag CLI e le variabili d'ambiente lo scrivono come `environment`, come in `--environment-secret-file`; i nomi deprecati `pool` continuano a funzionare, come la riga [`--environment-secret-file`](#runner-cli-flags) descrive.

17<h2 id="runner-cli-flags">

18 Flag CLI del runner

19</h2>

21La maggior parte dei flag ha una variabile d'ambiente corrispondente. Quando entrambi sono impostati, il flag ha la precedenza. I flag di durata accettano minuti o secondi sulla CLI, ma la variabile d'ambiente associata è sempre in millisecondi, indicata dal suffisso `_MS`, e la colonna Default mostra l'unità del flag: `--exit-if-unused-min 10` è equivalente a `SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000`, e un valore Helm come `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15"` significa 15 millisecondi, non il valore predefinito di 15 minuti.

24| :---------------------------------------- | :------------------------------------------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

26| `--base-dir <path>` | `SELF_HOSTED_RUNNER_BASE_DIR` | `/workspace`; nessuno su Windows | Directory per i checkout dei repository e le directory di lavoro per sessione. Il runner necessita dell'accesso in scrittura a questo percorso o al suo genitore. Il runner crea la directory all'avvio e esce con `cannot create or write to base directory` quando non riesce a crearla o scrivervi. Prima della v2.1.225, il runner creava la directory quando la prima sessione iniziava, quindi un percorso inutilizzabile causava il fallimento delle sessioni piuttosto che dell'avvio. Su Windows, che non è un host runner supportato, non c'è un valore predefinito: il runner esce all'avvio a meno che non passi il flag o imposti la variabile. Usa lo stesso valore su ogni runner in un ambiente. Vedi [Keep the base directory and capacity identical across runners](/docs/it/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners). |

27| `--capacity <n>` | none | `1` | Numero massimo di sessioni simultanee che questo runner gestisce. Tutte le sessioni appartengono allo stesso [owner](/docs/it/self-hosted-environments#key-concepts) bloccato. Usa lo stesso valore su ogni runner in un ambiente; vedi [Keep the base directory and capacity identical across runners](/docs/it/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners). |

28| `--client-label <label>` | `SELF_HOSTED_RUNNER_CLIENT_LABEL` | l'hostname dell'host | Etichetta che il runner invia quando si registra. Il runner lo segnala anche come etichetta `client_label` di [`claude_code_self_hosted_runner_info`](#prometheus-metrics). Richiede Claude Code v2.1.248 o successivo. |

29| `--configure-git` | `SELF_HOSTED_RUNNER_CONFIGURE_GIT=1` | off | All'avvio, scrivi l'identità git globale, abilita la firma dei commit Anthropic, attiva la negoziazione push di git e installa hook di commit che aggiungono un trailer `Co-authored-by:`. La negoziazione push richiede Claude Code v2.1.257 o successivo. Vedi [Configure git](/docs/it/self-hosted-environments-deploy#configure-git). |

30| `--confine-repo-settings <mode>` | `SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS` | `warn` | Imposta la modalità della guardia che contrassegna una sessione quando le impostazioni impegnate di un repository tentano di concedere accesso in scrittura o lettura al di fuori dello spazio di lavoro della sessione, impostare variabili d'ambiente o eseguire l'override della postura sandbox o hooks dell'operatore, come `sandbox.enabled: false` o `disableAllHooks`. Il valore predefinito `warn` registra la violazione e avvia comunque la sessione, `enforce` rifiuta la sessione e `off` disabilita la scansione. Vedi [Harden your deployment](/docs/it/self-hosted-environments-deploy#harden-your-deployment). |

32| `--defer-shutdown-max-min <n>` | `SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS` | `0` | Al primo `SIGTERM` o `SIGINT`, continua a servire le sessioni già collegate invece di drenare, quindi rilascia tutto ciò che è ancora collegato N minuti dopo e esci. Aumenta il timeout di arresto del tuo host prima di impostare questo. Vedi [Defer the drain past the first signal](/docs/it/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal). `0` disabilita. Richiede Claude Code v2.1.238 o successivo. |

33| `--drain-grace-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_GRACE_MS` | `0` | Fino a quando il runner riceve un segnale di arresto o raggiunge il suo tempo di ritiro, controlla quando il runner esce dopo che le sue sessioni attive finiscono: `0` esce immediatamente senza polling per altri, e un valore positivo mantiene il runner attivo e ri-polling della coda dell'owner bloccato per quel numero di secondi, al costo dell'isolamento del contenitore per sessione descritto nella [sezione hardening](/docs/it/self-hosted-environments-deploy#harden-your-deployment). Dopo un primo segnale che hai differito con [`--defer-shutdown-max-min`](/docs/it/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), il runner esce non appena non contiene sessioni, indipendentemente da quello che imposti qui. |

34| `--drain-wait-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_WAIT_MS` | `0` | Una volta che il drenaggio inizia, che è su `SIGTERM` a meno che non imposti [`--defer-shutdown-max-min`](/docs/it/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), attendi fino a N secondi affinché il turno in volo di ogni sessione e i compiti in background finiscano prima di terminare il figlio. Durante questa attesa, il runner conta un compito in background che ha appena finito come ancora in esecuzione fino a quando il turno di follow-up che legge il suo risultato inizia, per al massimo la finestra [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings). |

35| `--environment-secret-file <path>` | `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` | required | Percorso a un file contenente il segreto dell'ambiente, o, per i runner generati dall'[orchestrator](/docs/it/self-hosted-environments-configuration#on-demand-runners), il JWT del work-order monouso. `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` porta il valore del segreto direttamente, non un percorso di file. Il flag `--pool-secret-file` più vecchio e la variabile `SELF_HOSTED_RUNNER_POOL_SECRET` ancora funzionano e stampano un avviso di deprecazione su stderr; le build del runner del programma di anteprima più vecchie di 2.1.216 riconoscono solo quei nomi più vecchi. |

36| `--exec-path <path>` | `SELF_HOSTED_RUNNER_EXEC_PATH` | own binary | File binario o script wrapper da generare per ogni sessione. Vedi [Wrapper scripts](/docs/it/self-hosted-environments-configuration#wrapper-scripts). |

42| `--kill-session-after-min <n>` | `SELF_HOSTED_RUNNER_MAX_LIFETIME_MS` | `0` | Limita una sessione a N minuti di tempo reale, come limite di sicurezza per le sessioni bloccate. Su v2.1.260 o successivo, il runner rilascia una sessione che raggiunge il limite in modo che possa riprendere al prossimo messaggio dell'utente, e la termina solo se è ancora sul runner quando la finestra di grazia [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) finisce. Prima della v2.1.260, il runner terminava la sessione al limite. Vedi [Some sessions don't count as idle](/docs/it/self-hosted-environments-deploy#some-sessions-don%E2%80%99t-count-as-idle) per i dettagli e come scegliere un valore. `0` disabilita. |

43| `--lock-to-account <id>` | `SELF_HOSTED_RUNNER_LOCK_TO_ACCOUNT` | unset | Pre-blocca il runner a un account specifico all'avvio invece di bloccare alla prima sessione. Accetta un indirizzo email o un ID `user_...` nell'organizzazione dell'ambiente. Un runner pre-bloccato non raccoglie mai sessioni del canale Claude Tag, che non hanno account. |

44| `--log-file <path>` | `SELF_HOSTED_RUNNER_LOG_FILE` | unset | Specchia i log del runner in un file oltre a stdout e stderr, creato con permessi `0600`. Richiesto per `self-hosted-runner doctor` per accodare i log localmente. |

46| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | Budget per l'hook [`post-session`](/docs/it/self-hosted-environments-configuration#post-session) alla fine di ogni sessione, incluso l'arresto del runner |

47| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | unset | Comando shell che il runner esegue per ogni connessione al tuo proxy di uscita, usando il suo stdout ritagliato come valore dell'intestazione `Proxy-Authorization`. Richiede `HTTPS_PROXY` o `HTTP_PROXY`, e non può essere combinato con `--proxy-authorization-file`. Vedi [Authenticate to an egress proxy](/docs/it/self-hosted-environments-deploy#authenticate-to-an-egress-proxy). Richiede Claude Code v2.1.238 o successivo. |

48| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | unset | File che il runner legge per ogni connessione al tuo proxy di uscita, usando i suoi contenuti ritagliati come valore dell'intestazione `Proxy-Authorization`. Usa questo flag per un token che un altro processo ruota in posizione. Porta gli stessi requisiti di `--proxy-authorization-command`, e non può essere combinato con esso. Vedi [Authenticate to an egress proxy](/docs/it/self-hosted-environments-deploy#authenticate-to-an-egress-proxy). Richiede Claude Code v2.1.238 o successivo. |

49| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | off | Alla fine di una sessione avviata dal runner come un drenaggio o una versione inattiva, esegui il push dei rami di risultato tracciati a `origin` prima di eliminare lo spazio di lavoro, in modo che i commit in volo sopravvivano a un riavvio. Best-effort; aggiunge 30 secondi al budget di arresto, e richiede git 2.29 o più recente per riprendere dal ramo sottoposto a push. Limita l'accesso push ai ref `claude/*` prima di abilitare; vedi [Resumed sessions lose unpushed work](/docs/it/self-hosted-environments-deploy#additional-limitations). I repository estratti tramite un hook del ciclo di vita `checkout` non vengono sottoposti a push; fai uno snapshot di quelli dall'hook [`post-session`](/docs/it/self-hosted-environments-configuration#post-session) invece. |

50| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | Rilascia uno slot di sessione dopo N minuti di inattività una volta che un turno finisce o la sessione attende l'azione dell'utente. Una sessione che è ancora a metà turno, inclusa una che contiene un compito in background che non finisce mai o un'approvazione richiesta dall'interno di una chiamata di strumento in esecuzione, non conta come inattiva; abbina con `--kill-session-after-min` come backstop duro. Dopo che il compito in background di una sessione finisce, il runner considera la sessione occupata fino a quando il turno di follow-up che legge il risultato inizia, per al massimo la finestra [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings). Fino a quando il runner riceve un segnale di arresto o raggiunge il suo tempo di ritiro, un rilascio che lascia il runner senza sessioni attive avvia lo stesso percorso di uscita di un drenaggio normale, governato da `--drain-grace-sec`. Dopo un primo segnale che hai differito con [`--defer-shutdown-max-min`](/docs/it/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal), il runner esce non appena un rilascio lo lascia senza sessioni. `0` disabilita. |

51| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | unset | Ritira il runner a un timestamp Unix assoluto in secondi, per l'infrastruttura che uccide il runner a un'ora nota; [Runner lifecycle](/docs/it/self-hosted-environments#runner-lifecycle) descrive la sequenza di rilascio e come dimensionare il margine. I valori prima del 2001 o dopo l'anno 5138 vengono rifiutati dal flag e ignorati dalla variabile d'ambiente. |

52| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | Quanto tempo aspettare affinché il processo Claude esca correttamente dopo la fine di una sessione, prima di forzare l'uccisione. Aumenta il valore se gli hook `SessionEnd` del figlio hanno bisogno di più tempo. |

53| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | Rilascia uno slot di sessione se il figlio non ha segnalato che si è inizializzato entro N minuti dalla generazione. Cancellato dal segnale di init del figlio sul [canale di attività](/docs/it/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached), non dall'output ordinario, dopo di che `--release-idle-session-min` prende il sopravvento. `0` disabilita. |

54| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | on | Semina la fiducia persistente per i percorsi del repository di ogni sessione in modo che `permissions.allow` e `additionalDirectories` impegnati nel repo siano onorati. Imposta `false` per eliminare le concessioni di autorizzazione impegnate nel repo e configurare le regole di autorizzazione nella `settings.json` della configurazione dell'host; le impostazioni `sandbox.*` impegnate nel repository si applicano comunque in entrambi i casi, motivo per cui la [guardia repo-settings](/docs/it/self-hosted-environments-deploy#harden-your-deployment) le scansiona indipendentemente da questo flag. |

55| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | off | Clona tramite il [proxy git di Anthropic](/docs/it/self-hosted-environments-deploy#use-the-anthropic-git-proxy) invece dell'autenticazione git gestita dal cliente. Richiede `--capacity 1` e git 2.32 o più recente; il runner rifiuta di avviarsi altrimenti. Sostituisce i flag di riscrittura. |

57La maggior parte dei flag di durata ha un massimo, scelto per mantenere ogni timeout entro il limite del timer a 32 bit del runtime di circa 24,85 giorni. I flag `--*-min` hanno un limite di 10080 minuti, 7 giorni; `--drain-grace-sec` a 604800 secondi, anche 7 giorni; e `--drain-wait-sec` a 86400 secondi, 24 ore. `--session-stop-grace-sec` e `--post-session-hook-timeout-sec` non hanno limiti. Superare un limite si comporta diversamente per superficie:

59* **Flag**: l'avvio fallisce con un errore.

60* **Variabile d'ambiente**: il runner fissa il valore al limite del timer piuttosto che rifiutarlo.

62<h2 id="orchestrator-cli-flags">

63 Flag CLI dell'orchestrator

64</h2>

66Il sottocomando `self-hosted-runner orchestrator`, che genera [runner on-demand](/docs/it/self-hosted-environments-configuration#on-demand-runners), accetta `--api-url`, `--environment-secret-file`, `--hooks-dir`, `--health-port` e `--log-level` con gli stessi valori predefiniti del runner e, dove il flag del runner ne ha uno, la stessa variabile d'ambiente, tranne che `--hooks-dir` è obbligatorio e deve contenere un hook `spawn-runner`. Accetta anche i suoi flag:

68| Flag | Default | Description |

69| :------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

70| `--hook-concurrency <n>` | `4` | Numero massimo di hook `spawn-runner` in esecuzione in parallelo. Limita anche quante richieste di spawn vengono rivendicate per polling. |

71| `--hook-timeout <sec>` | `60` | Termina l'albero dei processi dell'hook dopo questo numero di secondi. Il timeout più la sua grazia di 5 secondi deve rimanere al di sotto di `--expected-spawn-seconds`; l'orchestrator lo applica all'avvio. |

72| `--expected-spawn-seconds <sec>` | `120` | Tempo di avvio p99 previsto per i runner generati, nell'intervallo applicato dal server da 10 a 3600. Inviato ad ogni polling come il lease lato server; se nessun runner si registra prima che trascorra, la sessione viene ri-offerta con un ID ordine nuovo. Tutte le repliche devono condividere questo valore. |

73| `--min-idle <n>` | `0` | Mantieni almeno N slot di sessione inattivi liberi generando proattivamente runner di standby. `0` disabilita il pre-riscaldamento. Abbina con il `--exit-if-unused-min` del runner in modo che i runner di standby in eccesso si riprendano. |

74| `--debug-dir <path>` | unset | Scrivi il work order e lo stderr dell'hook di ogni richiesta di spawn su disco. Solo debug; non impostare mai in produzione. |

76<h3 id="scm-connector-flags">

77 Flag del connettore SCM

78</h3>

80L'orchestrator può mantenere una connessione WebSocket permanente al piano di controllo di Anthropic in modo che i flussi pre-sessione ospitati, come il selettore di repository e il risolutore di ramo o ref, possano raggiungere un host GitHub Enterprise Server che è instradabile solo dall'interno della tua rete. Il connettore rimane disattivato a meno che non imposti `--scm-connector-host`.

82| Flag | Default | Description |

83| :------------------------------------------------------ | :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

84| `--scm-connector-host <host[:port]>` | unset | Nome host di GitHub Enterprise Server a cui inoltrare le richieste. La porta predefinita è `443`. L'impostazione di questo flag abilita il connettore. |

85| `--scm-connector-id <n>` | required with `--scm-connector-host` | L'ID numerico della connessione GitHub Enterprise Server della tua organizzazione. Contatta il tuo team di account Anthropic per il valore quando abiliti il connettore. |

86| `--scm-connector-provider <slug>` | `ghe` | Segmento di percorso che identifica il provider, corrispondente a `^[a-z0-9-]{1,32}$`. |

87| `--scm-connector-ca-file <path>` | unset | Bundle CA aggiuntivo, in formato PEM, per le connessioni TLS all'host GitHub Enterprise Server. |

88| `--scm-connector-host-rewrite <from>=<to_host:to_port>` | unset | Solo per test end-to-end: reindirizza la connessione TCP mantenendo l'intestazione Host e TLS SNI come `--scm-connector-host`. |

90Il connettore si autentica con il segreto dell'ambiente esistente dell'orchestrator e si riconnette automaticamente: con backoff esponenziale su una connessione interrotta, o un ritardo fisso di 30 secondi quando il piano di controllo chiude la connessione perché un'altra replica dell'orchestrator la contiene già.

92<h2 id="environment-variable-only-settings">

93 Impostazioni solo variabili d'ambiente

94</h2>

96Queste impostazioni del runner vengono lette solo dall'ambiente e coprono il comportamento che la maggior parte delle distribuzioni lascia al valore predefinito:

98| Env var | Default | Description |

99| :----------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | Quanto tempo il runner considera una sessione occupata dopo che un compito in background finisce mentre il turno di follow-up che legge il risultato non è ancora iniziato. Le righe [`--drain-wait-sec` e `--release-idle-session-min`](#runner-cli-flags) descrivono dove si applica la tenuta su drenaggio e rilascio inattivo, e [Runner lifecycle](/docs/it/self-hosted-environments#runner-lifecycle) descrive dove si applica al ritiro `--retire-at`. `0` o un valore inutilizzabile ricade al valore predefinito, quindi la tenuta non può essere disattivata. Richiede Claude Code v2.1.228 o successivo. |

101| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | Directory acquisita nello snapshot di avvio del runner e seminata nella `CLAUDE_CONFIG_DIR` di ogni sessione; le modifiche su disco si applicano dopo un riavvio del runner. L'impostazione della variabile sposta anche dove il runner legge `.claude.json` per il [seeding MCP](/docs/it/self-hosted-environments-configuration#mcp-servers), quindi impostarla, incluso al suo valore predefinito, trasferisce quella ricerca; punta a una directory vuota per disabilitare completamente il seeding. |

102| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | Quanto tempo il runner attende dopo che una sessione raggiunge il suo limite `--kill-session-after-min`, affinché un turno in esecuzione finisca o il rilascio si completi, prima di terminare la sessione |

103| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | Quanto tempo il runner attende che il sistema operativo consegni `SIGKILL` a un figlio bloccato in I/O non interrompibile prima di uscire lui stesso. Limitato inferiormente a `--post-session-hook-timeout-sec` più 15 secondi, e 30 in più quando `--push-outcome-on-release` è impostato, quindi il minimo effettivo è 75 secondi ai valori predefiniti. |

104| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | Profondità di fetch git per cloni freschi. Imposta un numero intero positivo, o `full` o `0` per un fetch completo. I repository già presenti nello spazio di lavoro mantengono la loro profondità esistente. |

105| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | unset | Quando `1`, salta il controllo della presenza `.git` dopo l'esecuzione di un hook `checkout`. Imposta questo quando il tuo hook materializza una fonte non-git. |

106| `FORCE_AUTOUPDATE_PLUGINS` | unset | Quando `1`, consenti ai marketplace dei plugin di auto-aggiornare anche se il binario è bloccato |

107| `CLAUDE_CODE_DISABLE_ARTIFACT` | unset | Quando `1`, disabilita lo strumento Artifact nelle sessioni indipendentemente dall'impostazione di amministrazione dell'organizzazione, e elimina il requisito di uscita `*.frame.claudeusercontent.com` |

108

109<h2 id="telemetry">

110 Telemetria

111</h2>

112

113I figli della sessione inviano telemetria operativa ad Anthropic a meno che non la disattivi. Nessun codice o contenuto del repository viene inviato. Imposta le variabili di telemetria sul processo del runner; il runner le ri-asserisce dopo aver applicato le variabili d'ambiente fornite dal server, quindi l'impostazione dell'operatore ha sempre la precedenza.

114

115Un controllo è specifico per gli ambienti self-hosted: `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` acconsente alle metriche operative di Datadog, che sono disattivate per impostazione predefinita negli ambienti self-hosted. I controlli generali di telemetria di Claude Code, `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_ERROR_REPORTING` e `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, si applicano ai figli della sessione come documentato nel [riferimento delle variabili d'ambiente](/docs/it/env-vars). `DISABLE_GROWTHBOOK` è correlato ma diverso: impostare `DISABLE_GROWTHBOOK=1` disabilita il recupero dei flag di funzionalità, e la telemetria rimane attiva a meno che `DISABLE_TELEMETRY` non sia anche impostato.

116

117`CLAUDE_CODE_ENABLE_TELEMETRY` non è correlato: abilita l'esportazione OpenTelemetry al tuo collettore, come descritto in [Monitoring](/docs/it/monitoring-usage), e non controlla l'analittica di Anthropic.

118

119<h2 id="health-endpoint">

120 Endpoint di salute

121</h2>

122

123Il runner serve `GET /healthz` sulla porta di salute configurata. La risposta è `200 OK` ogni volta che il processo è attivo, qualunque stato sia il ciclo di polling, quindi un probe HTTP su questo endpoint rileva solo un processo morto. Il corpo JSON descrive lo stato attuale:

124

125```json theme={null}

126{

127 "status": "ok",

128 "runner_id": "ccrunner_...",

129 "active_sessions": 2,

130 "last_poll_at": "2026-03-31T18:04:11.220Z",

131 "last_poll_age_ms": 842

132}

133```

134

135Usa `last_poll_age_ms` come segnale di vivacità nei probe personalizzati; un valore che cresce senza limiti indica che il ciclo di polling è bloccato. Sia `last_poll_at` che `last_poll_age_ms` sono `null` fino al completamento del primo polling.

136

137L'orchestrator serve il suo `/healthz` sulla sua porta di salute. Il suo endpoint restituisce sempre `200`, e il corpo porta un campo `connected` che segnala se il polling più recente ha avuto successo, più i conteggi della coda di spawn per stato in `queue_counts`. Gated readiness e alerting su `connected` piuttosto che sul codice di stato.

138

139Quando il [connettore SCM](#scm-connector-flags) è configurato, il corpo `/healthz` dell'orchestrator porta anche `scm_connector_connected` e un oggetto `scm_connector` con `connected`, `last_connected_at`, `last_error`, `reconnects` e `requests_forwarded`. Entrambi i campi sono `null` quando `--scm-connector-host` non è impostato.

140

141<h2 id="prometheus-metrics">

142 Metriche Prometheus

143</h2>

144

145Ogni runner serve metriche Prometheus su `GET /metrics` sulla stessa porta di `/healthz`. Serie chiave:

146

147| Series | Notes |

148| :-------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

149| `claude_code_self_hosted_runner_info{runner_id,version,client_label}` | Sempre `1`; utile per l'inventario della flotta e il rilevamento della deriva di versione |

150| `claude_code_self_hosted_runner_capacity` | `--capacity` configurato |

151| `claude_code_self_hosted_runner_active_sessions` | Sessioni attualmente in esecuzione |

152| `claude_code_self_hosted_runner_locked_account{email}` | Presente una volta che il runner si è bloccato a un utente e un token di sessione che porta un'affermazione `act.email` è stato emesso. La serie è assente su un runner bloccato a un agente Claude Tag, i cui token di sessione non portano `act.email`. Il valore dell'etichetta è l'email dell'account; se il tuo archivio di metriche è ampiamente leggibile, elimina o hash l'etichetta al momento della raschiatura, ad esempio con Prometheus `metric_relabel_configs`. |

153| `claude_code_self_hosted_runner_last_poll_age_seconds` | Secondi dall'ultimo polling riuscito. Avviso se superiore a 60. |

154| `claude_code_self_hosted_runner_poll_errors_total{error_kind}` | Errori cumulativi di PollWork per tipo: `transport`, `timeout`, `5xx`, `429` o `4xx`. Tutte e cinque le serie sono presenti dall'avvio del processo; avviso su `rate(...[5m]) > 0`. |

155| `claude_code_self_hosted_runner_sessions_started_total{client_platform}` | Processi figlio della sessione generati durante la vita del runner, una serie per origine della sessione come `web_claude_ai`, `ios`, `android`, `desktop_app` o `claude_code_cli`, o `unknown` quando il server non ne ha inviato uno. Le sessioni Slack portano `claude_in_slack` o `claude-in-slack` a seconda di quale integrazione Slack le ha create, quindi abbina entrambe con un selettore regex come `{client_platform=~"claude[-_]in[-_]slack"}`. Usa `sum()` per il totale della flotta. |

156| `claude_code_self_hosted_runner_sessions_completed_total{client_platform}` | Sessioni che sono terminate correttamente, etichettate allo stesso modo. Più ampio di una semplice uscita pulita: vedi [session lifecycle counter semantics](#session-lifecycle-counter-semantics) per cosa conta. |

157| `claude_code_self_hosted_runner_sessions_failed_total{client_platform}` | Sessioni che sono terminate in errore, etichettate allo stesso modo. Stessa avvertenza: vedi [session lifecycle counter semantics](#session-lifecycle-counter-semantics). |

158| `claude_code_self_hosted_runner_sessions_interrupted_total{client_platform}` | Sessioni che il runner ha terminato per un motivo operativo piuttosto che un risultato di sessione, etichettate allo stesso modo. Vedi [session lifecycle counter semantics](#session-lifecycle-counter-semantics). |

159| `claude_code_self_hosted_runner_initializing_sessions` | Sessioni attualmente nella fase di init, dall'assegnazione all'evento di init del figlio |

160| `claude_code_self_hosted_runner_session_init_duration_seconds` | Istogramma delle durate di init della sessione |

161| `claude_code_self_hosted_runner_session_init_errors_total` | Sessioni che hanno fallito prima di raggiungere init: un errore di hook di checkout, preparazione git, problema di token o un crash pre-init del figlio |

162| `claude_code_self_hosted_runner_session_start_hook_errors_total` | Hook `SessionStart` che hanno segnalato un risultato di errore, uno per esecuzione di hook fallita |

163| `claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform}` | Gauge per sessione di secondi dall'inattività della sessione. Utile per terminare le sessioni bloccate su un prompt di autorizzazione senza risposta. |

164

165L'orchestrator serve le sue serie su `GET /metrics` sulla stessa porta del suo `/healthz`:

166

167| Series | Notes |

168| :-------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

169| `claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname}` | Sempre `1` |

170| `claude_code_self_hosted_orchestrator_connected` | `1` quando il polling più recente ha avuto successo; scende a `0` dopo qualsiasi polling fallito, qualunque sia il tipo di errore |

171| `claude_code_self_hosted_orchestrator_last_poll_age_seconds` | Secondi dall'ultimo tentativo di polling, successo o errore, a differenza della metrica identicamente denominata del runner, che misura dall'ultimo successo; abbina con `connected` per catturare i polling falliti. Il ciclo di polling dell'orchestrator attende l'esecuzione dell'hook, quindi avviso sopra `--hook-timeout` più un margine, circa 90 secondi ai valori predefiniti, piuttosto che un flat 60. |

172| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | Errori cumulativi di PollSpawnHints per tipo: `transport`, `timeout`, `5xx`, `429` o `4xx`. Tutte e cinque le serie sono presenti dall'avvio del processo; avviso su `rate(...[5m]) > 0`. |

173| `claude_code_self_hosted_orchestrator_queue_pending_sessions` | Richieste di spawn rivendicabili in questo momento |

174| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | Richieste di spawn in backoff di retry dopo un errore di hook riprova |

175| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | Richieste di spawn bloccate fino a quando un Owner non le riprova dalla scheda **Activity** dell'ambiente; avviso se superiore a zero |

176| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | Sessioni totali in attesa di un runner per questo ambiente. Aggregato a livello di ambiente, identico su ogni istanza dell'orchestrator: usa `MAX` piuttosto che `SUM` tra le istanze. |

177| `claude_code_self_hosted_orchestrator_pool_active_sessions` | Sessioni attualmente assegnate a un runner vivo in questo ambiente. Aggregato a livello di ambiente, identico su ogni istanza dell'orchestrator: usa `MAX` piuttosto che `SUM` tra le istanze. |

178| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | Risultati cumulativi dell'hook `spawn-runner`: `ok`, `retryable`, `non_retryable`. Conta le invocazioni dell'hook dell'orchestrator, non i figli della sessione che i runner generano: non comparabili a `sessions_started_total`, poiché la capacità superiore a uno, i pool caldi e i runner generati di nuovo per la stessa sessione divergono i due. |

179| `claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds` | Istogramma delle durate dell'hook |

180| `claude_code_self_hosted_orchestrator_warm_hints_dispatched_total` | Richieste di spawn di standby inviate dall'avvio del processo |

181| `claude_code_self_hosted_orchestrator_session_queue_wait_seconds` | Istogramma di secondi che ogni sessione ha atteso nella coda prima che l'orchestrator la rivendicasse per spawn, registrato dal timestamp di attesa della coda che il piano di controllo invia con la richiesta di spawn di ogni sessione. Usa per l'avviso del tempo di coda p50/p99. I spawn di pre-riscaldamento non vengono campionati. |

182| `claude_code_self_hosted_orchestrator_clock_skew_seconds` | Skew dell'orologio locale meno server; diagnostico, presente una volta misurato |

183| `claude_code_self_hosted_orchestrator_scm_connector_connected` | `1` quando il WebSocket del [connettore SCM](#scm-connector-flags) è aperto; `0` durante la composizione o il backoff. Assente quando `--scm-connector-host` non è impostato. |

184| `claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total` | Richieste HTTP cumulative inoltrate all'host SCM configurato dall'avvio del processo. Assente quando `--scm-connector-host` non è impostato. |

185

186Per l'autoscaling, scegli la serie che corrisponde al tuo stile di scaling e gated prima che si nutra nello scaler:

187

188* **Scaling della profondità della coda**: alimenta `claude_code_self_hosted_orchestrator_pool_pending_sessions` nel tuo HPA o scaler KEDA, non `queue_pending_sessions`.

189* **Scaling della capacità**: scala sul rapporto tra `active_sessions` e `capacity` del runner.

190* **Gate su `connected`**: filtra la query con `claude_code_self_hosted_orchestrator_connected == 1` per istanza, quindi il valore stantio di una replica disconnessa non si nutre nello scaler.

191

192Durante un'interruzione completa del polling, ogni replica disconnessa, la query gated non restituisce dati. HPA mantiene il numero di replica attuale su una metrica mancante, ma lo scaler Prometheus di KEDA al suo `ignoreNullValues: "true"` predefinito legge il risultato vuoto come zero e scala in; imposta `ignoreNullValues: "false"` su ScaledObject, facoltativamente con un floor di replica `fallback`.

193

194Il seguente `PodMonitor` di Prometheus Operator copre entrambi i processi. Seleziona i pod per l'etichetta `app.kubernetes.io/part-of: claude-code-self-hosted-runner` e la porta denominata `health` che la [ricetta Kubernetes](/docs/it/self-hosted-environments-deploy#kubernetes) imposta; regola gli spazi dei nomi per corrispondere alla tua distribuzione:

195

196```yaml theme={null}

197# Example Prometheus Operator PodMonitor for the Claude Code self-hosted

198# runner + orchestrator. Adjust the namespace and label selectors to match

199# your deployment. Both the runner and the orchestrator serve /metrics on

200# their --health-port (default 8080).

201apiVersion: monitoring.coreos.com/v1

202kind: PodMonitor

203metadata:

204 name: claude-code-self-hosted-runner

205 namespace: monitoring

206spec:

207 namespaceSelector:

208 matchNames:

209 - claude-runners

210 selector:

211 matchExpressions:

212 # Matches the runner Deployment from the Kubernetes recipe, plus any

213 # on-demand runner Jobs and orchestrator pods you label the same way

214 # and give a named 'health' containerPort.

215 - key: app.kubernetes.io/part-of

216 operator: In

217 values: [claude-code-self-hosted-runner]

218 podMetricsEndpoints:

219 - port: health

220 path: /metrics

221 interval: 30s

222```

223

224Queste regole di avviso di esempio sono un punto di partenza; sintonizza le soglie per la dimensione della tua flotta:

225

226```yaml theme={null}

227# Example Prometheus alert rules for the Claude Code self-hosted runner

228# + orchestrator. Tune thresholds for your fleet size and SLOs.

229groups:

230 - name: claude-code-self-hosted-runner

231 rules:

232 - alert: ClaudeRunnerPollStale

233 expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60

234 for: 2m

235 labels: {severity: warning}

236 annotations:

237 summary: "Runner {{ $labels.pod }} has not polled in >60s"

238 - alert: ClaudeRunnerVersionDrift

239 expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1

240 for: 30m

241 labels: {severity: info}

242 annotations:

243 summary: "Runners are running mixed versions"

244 - alert: ClaudeRunnerInitErrorsHigh

245 expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3

246 for: 5m

247 labels: {severity: warning}

248 annotations:

249 summary: "Runner {{ $labels.pod }}: >3 session init failures in 10m (checkout hook / git / token / pre-init crash)"

250 - alert: ClaudeRunnerPollErrors

251 expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0

252 for: 2m

253 labels: {severity: warning}

254 annotations:

255 summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 5m)"

256 - alert: ClaudeRunnerSessionStartHookErrors

257 expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3

258 for: 5m

259 labels: {severity: warning}

260 annotations:

261 summary: "Runner {{ $labels.pod }}: >3 SessionStart hook failures in 10m"

262

263 - name: claude-code-self-hosted-orchestrator

264 rules:

265 - alert: ClaudeOrchestratorDisconnected

266 expr: claude_code_self_hosted_orchestrator_connected == 0

267 for: 2m

268 labels: {severity: critical}

269 annotations:

270 summary: "Orchestrator {{ $labels.pod }} cannot reach the Anthropic control plane"

271 - alert: ClaudeOrchestratorPollStale

272 expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90

273 for: 2m

274 labels: {severity: warning}

275 annotations:

276 summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"

277 - alert: ClaudeOrchestratorCircuitBroken

278 expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0

279 for: 1m

280 labels: {severity: critical}

281 annotations:

282 summary: "{{ $value }} sessions circuit-broken — spawn-runner hook is repeatedly non-retryable; fix infra then retry from the Activity tab"

283 - alert: ClaudeOrchestratorPollErrors

284 expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0

285 for: 2m

286 labels: {severity: warning}

287 annotations:

288 summary: "Orchestrator {{ $labels.pod }}: PollSpawnHints failing ({{ $value | humanize }}/s over 5m)"

289 - alert: ClaudeOrchestratorSpawnHookFailing

290 expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3

291 for: 5m

292 labels: {severity: warning}

293 annotations:

294 summary: "Orchestrator {{ $labels.pod }}: >3 spawn-runner hook failures in 5m"

295```

296

297<h3 id="pass-through-session-child-metrics">

298 Passa attraverso le metriche del figlio della sessione

299</h3>

300

301Ogni sessione viene eseguita nel suo processo figlio con le sue metriche OpenTelemetry; a `--capacity` superiore a uno, il runner riscrive come quelle metriche figlio vengono esposte. L'impostazione di `OTEL_METRICS_EXPORTER=prometheus` sull'host del runner e `CLAUDE_CODE_ENABLE_TELEMETRY=1` nell'ambiente della sessione, ad esempio dal tuo [script wrapper](/docs/it/self-hosted-environments-configuration#wrapper-scripts) o dall'ambiente del runner stesso, che le sessioni ereditano, ri-espone gli strumenti di contatore e gauge di ogni figlio sull'endpoint `/metrics` del runner, insieme alle serie del runner. Il runner riscrive l'esportatore del figlio per eseguire il push su OTLP a un ricevitore solo loopback sulla porta di salute, etichetta ogni serie con etichette `session_id` e `client_platform`, e rimuove le serie di una sessione quando quella sessione termina. Gli istogrammi non passano, e una metrica figlio il cui nome entrerebbe in collisione con il prefisso del runner è eliminata.

302

303Al `--capacity 1` predefinito, la riscrittura non si applica: il figlio della sessione lega il suo endpoint Prometheus sulla porta 9464 come al solito.

304

305<h3 id="session-lifecycle-counter-semantics">

306 Semantica del contatore del ciclo di vita della sessione

307</h3>

308

309I contatori `sessions_started_total`, `sessions_completed_total`, `sessions_failed_total` e `sessions_interrupted_total` classificano ogni sessione in base a come è terminata. Ogni figlio della sessione generato incrementa `sessions_started_total` al momento della generazione, e esattamente uno degli altri tre incrementa all'uscita, quindi `sessions_started_total` meno la somma degli altri tre è uguale al numero di figli della sessione attualmente in esecuzione.

310

311* `completed`: la sessione è terminata correttamente. Questo copre il figlio che esce da solo con codice `0`, la sessione archiviata o eliminata mentre il figlio era ancora connesso, e il runner che restituisce lo slot in modo pulito: il rilascio della sessione al timeout di inattività, al tempo di ritiro o al limite `--kill-session-after-min`; un timeout di avvio; o un deassign lato server che il ciclo di polling ha notato prima che il figlio uscisse. Incrementa `sessions_completed_total`.

312* `failed`: il figlio è uscito da solo con un codice diverso da zero, sia un crash che un errore di configurazione dopo la generazione. Incrementa `sessions_failed_total`.

313* `interrupted`: il runner ha terminato il figlio per un motivo operativo che non è né un successo della sessione né un errore del runner, come un drenaggio, o terminando una sessione che era ancora sul runner quando la finestra di grazia [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) dopo il suo limite `--kill-session-after-min` è terminata. Un riavvio rolling di Kubernetes che invia `SIGTERM` è un esempio di drenaggio. Incrementa `sessions_interrupted_total`.

314

315Prima della v2.1.260, il runner terminava ogni sessione che raggiungeva il suo limite `--kill-session-after-min` e la contava in `sessions_interrupted_total`.

316

317Il `CLAUDE_RUNNER_EXIT_REASON` dell'hook [`post-session`](/docs/it/self-hosted-environments-configuration#post-session) classifica gli handoff puliti diversamente. L'hook segnala un rilascio, un timeout di avvio e un deassign del server come `interrupted`, perché il runner ha fermato il figlio. Questi contatori registrano gli stessi eventi come `completed`, perché lo slot è stato restituito correttamente.

318

319Se riconcili le ricevute dell'hook direttamente contro `sessions_completed_total`, sottostimi i completamenti. Usa l'hook per le garanzie per sessione e i contatori per i tassi aggregati.

320

321Su un ambiente monouso, `--capacity 1` con il `--drain-grace-sec 0` predefinito, ogni processo del runner esce momenti dopo la fine della sua sessione. `sessions_completed_total`, `sessions_failed_total` e `sessions_interrupted_total` incrementano solo alla fine della sessione, subito prima di quell'uscita, quindi un raschiamento Prometheus ogni 15-60 secondi raramente cattura l'incremento prima che le serie del runner scompaiano; questi tre contatori di fine sessione sono i contatori terminali a cui il resto di questa sezione si riferisce. `sessions_started_total` incrementa alla generazione e rimane visibile per la vita della sessione, quindi si mostra in modo affidabile, ma su un ambiente monouso legge più vicino a "sessioni attualmente in esecuzione" che a un conteggio cumulativo.

322

323Usa la serie in questa tabella per l'obiettivo corrispondente invece dei contatori terminali:

324

325| Goal | Use |

326| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

327| Throughput | `claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}`, un contatore sull'orchestrator di lunga durata che incrementa una volta per hook `spawn-runner` riuscito e rimane significativo sotto `rate()`. Conta le invocazioni dell'hook piuttosto che le sessioni, quindi il pre-riscaldamento e i spawn ripetuti per la stessa sessione divergono da conteggi di sessione. |

328| Utilization | `sum(claude_code_self_hosted_runner_active_sessions)` contro `sum(claude_code_self_hosted_runner_capacity)`, entrambi i gauge validi ad ogni raschiamento indipendentemente dalla durata del runner |

329| Backlog | `claude_code_self_hosted_orchestrator_pool_pending_sessions` per la profondità della coda, e `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`, avviso se superiore a zero |

330| Failures | `claude_code_self_hosted_runner_sessions_failed_total`, best effort: i veri crash dopo la generazione incrementano, e `rate()` è significativo su runner che sopravvivono alle loro sessioni con `--drain-grace-sec` superiore a `0`. Un ambiente monouso ha lo stesso problema della finestra di raschiamento degli altri contatori terminali, quindi tratta qualsiasi valore diverso da zero che vedi come degno di indagine. I fallimenti prima della generazione, come un errore di hook di checkout, preparazione git o un problema di token, appaiono solo in `session_init_errors_total`. |

331

332Le righe `orchestrator_*` esistono solo su ambienti che eseguono l'[orchestrator on-demand](/docs/it/self-hosted-environments-configuration#on-demand-runners). Su una flotta fissa i cui runner sopravvivono alle loro sessioni, con `--drain-grace-sec` superiore a `0`, usa `sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m]))` per il throughput; su una flotta monouso quella serie ha lo stesso problema della finestra di raschiamento dei contatori terminali, quindi affidati al conteggio delle sessioni in coda. Controlla il backlog nella scheda **Activity** dell'ambiente, nella [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): i runner non esportano una serie di profondità della coda.

333

334Per la segnalazione dei risultati per sessione, usa l'hook [`post-session`](/docs/it/self-hosted-environments-configuration#post-session) invece: si attiva alla fine di ogni sessione dove un processo figlio è stato generato, a parte la terminazione abrupte del runner come una preemption VM, per il [contratto proprio dell'hook](/docs/it/self-hosted-environments-configuration#post-session).

335

336<h2 id="what’s-next">

337 Prossimi passi

338</h2>

339

340* [Self-hosted environments](/docs/it/self-hosted-environments): l'ambiente, il runner e il modello di sessione; la [guida rapida](/docs/it/self-hosted-environments-quickstart) e [Deploy to production](/docs/it/self-hosted-environments-deploy) contengono la configurazione e le operazioni

341* [Customize sessions](/docs/it/self-hosted-environments-configuration): script wrapper, hook del ciclo di vita e runner on-demand

342* [Verify session identity](/docs/it/self-hosted-environments-identity): il token di sessione, le sue affermazioni e come verificarlo

self-hosted-environments-testing.md +269 −0 created

Details

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.

5# Testare gli ambienti self-hosted end to end

7> Verificare un'immagine di runner self-hosted da CI: inviare una sessione con la CLI, leggere le risposte di Claude attraverso un hook Stop e scrivere lo script del ciclo completo.

9<Note>

10 Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; [Disponibilità e limitazioni](/docs/it/self-hosted-environments#availability-and-limitations) copre il percorso di abilitazione. Questa pagina è la ricetta di test CI; vedere [quickstart](/docs/it/self-hosted-environments-quickstart) per la configurazione e [Distribuire in produzione](/docs/it/self-hosted-environments-deploy) per le ricette della flotta.

11</Note>

13In un [ambiente self-hosted](/docs/it/self-hosted-environments), le [sessioni cloud](/docs/it/claude-code-on-the-web) di Claude Code vengono eseguite su un'immagine di runner che costruite e mantenete. Prima di distribuire una nuova immagine al vostro ambiente di produzione, eseguite una sessione completa contro un ambiente di test da uno script: create una sessione, leggete la risposta di Claude, inviate un follow-up e leggete anche quella risposta. Questa è la forma di un test di smoke CI che verifica l'immagine del vostro runner, l'accesso a git e qualsiasi strumento personalizzato prima di promuovere una modifica.

15Questa ricetta presuppone che abbiate già [configurato un ambiente e un runner](/docs/it/self-hosted-environments-quickstart#set-up-an-environment-and-runner), e che il vostro job CI avvii il processo del runner sullo stesso host dello script di test, la configurazione naturale per testare una nuova immagine di runner. Un hook Stop che installate sul runner scrive la risposta finale di ogni turno in un file locale, e lo script la legge da lì, quindi le uniche chiamate all'API Anthropic sono i due dispatch stessi. Se i vostri runner di test si trovano su infrastrutture separate, vedere [Runner di test remoti](#remote-test-runners).

17<h2 id="install-the-capture-hook-on-your-test-runner">

18 Installare l'hook di cattura sul vostro runner di test

19</h2>

21La lettura funziona attraverso un [hook Stop](/docs/it/hooks#stop) di Claude Code: quando Claude termina un turno, l'hook riceve il messaggio dell'assistente finale come `last_assistant_message` nel JSON stdin e lo aggiunge a `$E2E_REPLY_DIR/<session_id>.txt`. Installatelo nello stesso modo dell'[hook Stop commit-nudge](/docs/it/self-hosted-environments-configuration#prompt-sessions-to-push-their-work), su `~/.claude/` dell'host del runner, che il runner semina in ogni sessione.

23<h3 id="save-the-hook-files">

24 Salvare i file dell'hook

25</h3>

27Salvate i due file seguenti sull'host del runner:

29* Il blocco delle impostazioni: unite in `~/.claude/settings.json` sull'host del runner

30* Lo script: salvate come `~/.claude/hooks/e2e-stop-hook-capture.sh` sull'host del runner e rendetelo eseguibile

32```json theme={null}

33{

34 "hooks": {

35 "Stop": [

36 {

37 "hooks": [

38 {

39 "type": "command",

40 "timeout": 10,

41 "command": "\"$CLAUDE_CONFIG_DIR/hooks/e2e-stop-hook-capture.sh\""

42 }

43 ]

44 }

45 ]

46 }

47}

48```

50```sh theme={null}

51#!/bin/sh

52# Stop hook for testing a self-hosted environment end to end: writes each

53# turn's final assistant reply to $E2E_REPLY_DIR/<session_id>.txt so a

54# co-located test driver can read it without calling the Anthropic API.

55# Install on the TEST runner only. Requires jq.

57# No-op unless the driver is listening. Never fail the turn.

58[ -n "${E2E_REPLY_DIR:-}" ] && [ -d "$E2E_REPLY_DIR" ] || exit 0

60# CLAUDE_CODE_REMOTE_SESSION_ID is exported in cse_... form; the session

61# id the dispatch CLI prints is in session_... form. Same id, different

62# prefix.

63sid=$(printf '%s' "${CLAUDE_CODE_REMOTE_SESSION_ID:-}" | sed 's/^cse_/session_/')

64[ -n "$sid" ] || exit 0

66# last_assistant_message is absent when the final assistant turn had no

67# text, such as a tool-use-only turn. The `// empty` filter makes that a

68# zero-byte write rather than the literal string "null".

69jq -r '.last_assistant_message // empty' >> "$E2E_REPLY_DIR/$sid.txt" 2>/dev/null

70exit 0

71```

73<h3 id="before-you-start-the-runner">

74 Prima di avviare il runner

75</h3>

77Due cose da cui dipende l'hook:

79* Installatelo prima di avviare il runner. Il runner crea uno snapshot di `~/.claude/` una sola volta all'avvio, quindi un hook aggiunto a un runner in esecuzione ha effetto solo dopo un riavvio.

80* Esportate `E2E_REPLY_DIR` al processo del runner. L'hook è un no-op quando la variabile non è impostata o la directory non esiste, quindi impostatela ovunque avviate il runner, come l'unità systemd, la specifica del pod o il passo CI. Lo script di test di seguito lo richiede anche.

82Installate questo hook solo sui runner che servono il vostro ambiente di test. Scrive la risposta finale di ogni sessione su disco ogni volta che `E2E_REPLY_DIR` esiste, il che è innocuo su un runner CI monouso ma non qualcosa da portare in un'immagine di runner dell'ambiente di produzione dove la variabile potrebbe essere impostata accidentalmente.

84<h2 id="run-the-test-loop">

85 Eseguire il ciclo di test

86</h2>

88I flag di dispatch `--environment` e `--ref` richiedono Claude Code v2.1.224 o successivo sulla macchina che esegue lo script, lo stesso limite minimo del runner stesso. Con l'hook in posizione e un runner avviato su questo host, lo script di test:

901. Crea una sessione sull'ambiente di test con `claude -p "<prompt>" --environment <environment-id> --output-format json`, eseguito da un checkout git in modo che la CLI possa rilevare automaticamente il repository dal remote `origin`. L'opzionale `--ref <branch>` basa il checkout della sessione su un ref denominato invece di HEAD locale. Il comando crea la sessione, stampa una riga di JSON contenente `session_id` e esce senza attendere la risposta di Claude.

912. Attende che la risposta appaia in `$E2E_REPLY_DIR/<session_id>.txt`, scritta dall'hook Stop sul runner una volta completato il turno.

923. Invia un follow-up con `claude -p "<message>" --cloud <session_id> --output-format json` (vedere [Inviare un messaggio di follow-up a una sessione in esecuzione](/docs/it/claude-code-on-the-web#send-follow-ups-from-the-cli)), che pubblica un evento utente nella sessione esistente e esce.

934. Attende la risposta del follow-up nello stesso modo del passo 2.

95<h3 id="environment-dispatch-behavior">

96 Comportamento del dispatch `--environment`

97</h3>

99Claude Code crea la sessione, stampa l'ID della sessione e un link ad essa, e esce.

100

101Il flag ha la precedenza sull'impostazione [`remote.defaultEnvironmentId`](/docs/it/settings-reference#remote-defaultenvironmentid). Non supporta `--output-format stream-json` e non può essere combinato con flag che riprendono, si collegano o preconfigurano una sessione, come `--resume`, `--continue`, `--teleport`, `--session-id` o `--init-only`. `--cloud` viene rifiutato con un ID di sessione o URL, e nelle esecuzioni non interattive quando porta una descrizione. Un `--cloud` nudo viene trattato come assente. Da un terminale, potete passare l'attività come descrizione `--cloud` invece di un prompt posizionale.

102

103<h2 id="example-script">

104 Script di esempio

105</h2>

106

107Lo script seguente esegue il ciclo completo contro `$CLAUDE_TEST_ENVIRONMENT_ID`, l'ID `ccpool_...` del vostro ambiente di test, mostrato nella finestra di dialogo dei dettagli dell'ambiente nella pagina di amministrazione o restituito dalla [chiamata create-environment](#create-a-dedicated-test-environment), e asserisce su una frase sentinella in ogni risposta. Eseguitelo da un checkout git del repository su cui desiderate che la sessione funzioni, dopo aver avviato un runner su questo host con l'hook di cattura installato e `E2E_REPLY_DIR` esportato.

108

109```bash theme={null}

110#!/usr/bin/env bash

111# End-to-end test against a self-hosted environment, using Stop-hook read-back.

112# Prereqs: `claude auth login` has been run on this machine (see "Authenticate

113# from CI" below); jq is installed; CLAUDE_TEST_ENVIRONMENT_ID names an

114# environment whose runner is the one on this host, with the capture hook

115# installed and E2E_REPLY_DIR in its environment.

116

117set -euo pipefail

118

119: "${CLAUDE_TEST_ENVIRONMENT_ID:=${CLAUDE_TEST_POOL_ID:-}}" # CLAUDE_TEST_POOL_ID is the legacy spelling

120: "${CLAUDE_TEST_ENVIRONMENT_ID:?set CLAUDE_TEST_ENVIRONMENT_ID to a ccpool_... id served by a runner on this host}"

121: "${E2E_REPLY_DIR:?set E2E_REPLY_DIR to the directory the Stop hook on your test runner writes to, and export it to the runner process}"

122: "${TEST_REPO_REF:=main}"

123

124[ -d "$E2E_REPLY_DIR" ] || {

125 echo "FAIL: E2E_REPLY_DIR ($E2E_REPLY_DIR) does not exist. The Stop hook on the runner needs it." >&2

126 exit 1

127}

128

129# Waits until $E2E_REPLY_DIR/<session_id>.txt contains $2, or fails after

130# 90 seconds. Tune the timeout to your environment's cold-start time. The

131# file is written by the Stop hook on the runner.

132await_reply() {

133 local expect="$2" f="$E2E_REPLY_DIR/$1.txt"

134 local deadline=$(($(date +%s) + 90))

135 while :; do

136 if [ -f "$f" ] && grep -qF -- "$expect" "$f"; then

137 return

138 fi

139 [ "$(date +%s)" -lt "$deadline" ] || {

140 echo "FAIL: '$expect' not in $f within 90s. The Stop hook on the runner did not write it." >&2

141 echo "-- $E2E_REPLY_DIR contents --" >&2; ls -la "$E2E_REPLY_DIR" >&2

142 [ -f "$f" ] && { echo "-- $f --" >&2; cat "$f" >&2; }

143 exit 1

144 }

145 sleep 1

146 done

147}

148

149# 1. Create the session on the test environment. Run from a git checkout

150# so the CLI can auto-detect the repo. --ref pins the checkout to a named

151# ref regardless of local HEAD.

152TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"

153EXPECT1="ok: custom tools are reachable"

154create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \

155 --ref "$TEST_REPO_REF" --output-format json)

156echo "create: $create_json"

157SESSION_ID=$(jq -er '.session_id' <<<"$create_json")

158

159# 2. Wait for the turn-1 reply.

160await_reply "$SESSION_ID" "$EXPECT1"

161echo "turn-1 reply ok"

162

163# 3. Post a follow-up via the CLI.

164TURN2="e2e-probe-followup-$(date +%s): say exactly 'ok: follow-up delivered' and nothing else"

165EXPECT2="ok: follow-up delivered"

166followup_json=$(claude -p "$TURN2" --cloud "$SESSION_ID" --output-format json)

167echo "followup: $followup_json"

168jq -e '.ok == true' <<<"$followup_json" >/dev/null

169

170# 4. Wait for the turn-2 reply.

171await_reply "$SESSION_ID" "$EXPECT2"

172echo "turn-2 reply ok"

173

174echo "PASS: test-environment round-trip (session $SESSION_ID)"

175```

176

177Sostituite i prompt `TURN1`/`TURN2` e i sentinella `EXPECT1`/`EXPECT2` con qualsiasi cosa eserciti la vostra configurazione, come chiedere a Claude di eseguire uno dei vostri strumenti MCP personalizzati e asserire sul suo output.

178

179<h2 id="remote-test-runners">

180 Runner di test remoti

181</h2>

182

183Se i vostri runner di test si trovano su infrastrutture separate, come una flotta Kubernetes persistente con cui il vostro job CI non può condividere un filesystem, scambiate la scrittura del file nell'hook Stop con un POST a un endpoint su cui il vostro driver ascolta:

184

185```sh theme={null}

186#!/bin/sh

187# Variant of the capture hook for runners on separate infrastructure.

188# Set E2E_REPLY_URL on the runner to an endpoint the driver controls.

189[ -n "${E2E_REPLY_URL:-}" ] || exit 0

190sid=$(printf '%s' "${CLAUDE_CODE_REMOTE_SESSION_ID:-}" | sed 's/^cse_/session_/')

191[ -n "$sid" ] || exit 0

192jq -r '.last_assistant_message // empty' | \

193 curl -fsS -X POST --data-binary @- "$E2E_REPLY_URL/$sid" >/dev/null 2>&1

194exit 0

195```

196

197Dal lato del driver, eseguite qualsiasi cosa che accetti il POST e mantenga la risposta fino a quando il test non la richiede, come un piccolo listener HTTP all'interno del job CI o un ricevitore webhook che già eseguite. L'hook viene eseguito sulla vostra infrastruttura, quindi l'endpoint deve solo essere raggiungibile dai vostri runner.

198

199<h2 id="authenticate-from-ci">

200 Autenticarsi da CI

201</h2>

202

203Sia `claude -p ... --environment` che `claude -p ... --cloud` si autenticano con un token OAuth di claude.ai; le chiavi API, come `sk-ant-xxxxx`, non sono accettate per nessuna delle due chiamate. Due approcci rendono disponibile un token in CI.

204

205<h3 id="long-lived-ci-host">

206 Host CI di lunga durata

207</h3>

208

209Eseguite `claude auth login` una sola volta in modo interattivo sulla macchina che esegue lo script, utilizzando un account utente dedicato per l'automazione. Claude Code memorizza il token nel keychain del sistema operativo su macOS, o in `~/.claude/.credentials.json` su Linux e Windows. Su un host macOS il cui Keychain non può essere scritto, come è tipico in una sessione SSH dove il Keychain di login rimane bloccato, Claude Code memorizza il token in `~/.claude/.credentials.json` anche lì. Vedere [Gestione delle credenziali](/docs/it/authentication#credential-management).

210

211La CLI aggiorna automaticamente il token di accesso di breve durata ad ogni invocazione, ma la concessione del token di aggiornamento sottostante è limitata a 30 giorni dall'accesso iniziale, quindi eseguite di nuovo `claude auth login` in modo interattivo su quell'host ogni 30 giorni.

212

213<h3 id="ephemeral-ci-runners">

214 Runner CI effimeri

215</h3>

216

217Non esiste un token CI di lunga durata per questo oggi. L'ambito che concede il controllo della sessione remota, `user:sessions:claude_code`, è limitato lato server a 30 giorni, quindi `claude setup-token`, che conia un token di sola inferenza di un anno, non lo copre. Il [segreto dell'ambiente](/docs/it/self-hosted-environments-quickstart#set-up-an-environment-and-runner) non è accettato neanche, poiché autorizza solo un runner a registrarsi con l'ambiente, non a creare sessioni.

218

219Per fornire un accesso memorizzato su un runner effimero, impostate [`CLAUDE_CODE_OAUTH_REFRESH_TOKEN` e `CLAUDE_CODE_OAUTH_SCOPES`](/docs/it/env-vars#variables) in modo che `claude auth login` scambi il token senza un browser; lo stesso limite di 30 giorni si applica alla concessione di aggiornamento. Contattate il vostro team di account Anthropic se avete bisogno di un percorso di identità della macchina che non sia legato a un account umano.

220

221<h2 id="create-a-dedicated-test-environment">

222 Creare un ambiente di test dedicato

223</h2>

224

225Create e eliminate gli ambienti a livello di programmazione in modo che ogni esecuzione CI ottenga uno pulito; il runner che il vostro job CI avvia si registra nell'ambiente nuovo. Le chiamate di creazione e eliminazione di seguito sono gli stessi endpoint che la pagina di amministrazione **Cloud environments** su claude.ai utilizza, e richiedono l'intestazione `anthropic-beta: ccr-byoc-2025-07-29`.

226

227<h3 id="mint-the-admin-token">

228 Coniare il token di amministrazione

229</h3>

230

231`$ADMIN_TOKEN` è un token di accesso OAuth di claude.ai per un account che detiene un ruolo Owner, coniato nello stesso modo di [Autenticarsi da CI](#authenticate-from-ci):

232

233* **Coniarlo**: eseguite `claude auth login` con un account che detiene un ruolo Owner, quindi leggete il token di accesso corrente da dove [Host CI di lunga durata](#long-lived-ci-host) dice che Claude Code lo ha memorizzato.

234* **Leggerlo fresco ad ogni esecuzione**: la CLI ruota il token di accesso, e lo stesso limite di 30 giorni per la concessione di aggiornamento si applica, quindi non memorizzate una copia.

235* **Passarlo via stdin**: come fa l'esempio, in modo che il token non finisca mai nell'elenco degli argomenti di curl o nel vostro log di build.

236

237<h3 id="create-the-environment">

238 Creare l'ambiente

239</h3>

240

241Catturate la risposta senza ecoarla: `pool_secret` è una credenziale di lunga durata che può registrare runner nell'ambiente, quindi memorizzatela come segreto CI mascherato e stampate solo l'ID dell'ambiente. La forma `-H @-` che mantiene il token fuori dall'elenco dei processi richiede curl 7.55 o successivo; curl più vecchio tratta `@-` come un'intestazione letterale e invia la richiesta senza autorizzazione.

242

243```bash theme={null}

244create=$(curl -fsS -X POST -H @- \

245 -H "anthropic-beta: ccr-byoc-2025-07-29" -H "anthropic-version: 2023-06-01" \

246 -H "content-type: application/json" \

247 -d '{"name":"ci-test-environment"}' \

248 https://api.anthropic.com/v1/code/runners/self-hosted/pools \

249 <<<"Authorization: Bearer $ADMIN_TOKEN")

250ENVIRONMENT_ID=$(jq -er .pool.pool_id <<<"$create")

251ENVIRONMENT_SECRET=$(jq -er .pool_secret <<<"$create")

252```

253

254Fino a quando un [Owner non attiva **Allow self-hosted environments**](/docs/it/self-hosted-environments#availability-and-limitations) per l'organizzazione, la chiamata fallisce con un `403` `permission_error` che legge `self-hosted runners are disabled by your organization's policy`.

255

256Avviate un runner su questo host con `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET=$ENVIRONMENT_SECRET`, più l'hook di cattura e `E2E_REPLY_DIR` per [Installare l'hook di cattura](#install-the-capture-hook-on-your-test-runner), quindi eseguite lo script di test.

257

258<h3 id="delete-the-environment">

259 Eliminare l'ambiente

260</h3>

261

262Eliminate l'ambiente quando l'esecuzione finisce, in modo che ogni esecuzione CI inizi pulita:

263

264```bash theme={null}

265curl -fsS -X DELETE -H @- \

266 -H "anthropic-beta: ccr-byoc-2025-07-29" -H "anthropic-version: 2023-06-01" \

267 "https://api.anthropic.com/v1/code/runners/self-hosted/pools/$ENVIRONMENT_ID" \

268 <<<"Authorization: Bearer $ADMIN_TOKEN"

269```

sessions.md +3 −3

Details

37 37

38Una sessione ripresa ripristina la conversazione insieme allo stato salvato in essa:38Una sessione ripresa ripristina la conversazione insieme allo stato salvato in essa:

39 39

~~40* Cronologia della conversazione: la cronologia completa, incluse le chiamate agli strumenti e i risultati.~~40* Cronologia della conversazione: la cronologia completa, incluse le chiamate agli strumenti e i risultati. Uno strumento che era ancora in esecuzione quando il processo precedente è terminato, ad esempio in un arresto anomalo, non finisce o non viene eseguito di nuovo quando riprendi; Claude continua senza il suo output.

41* Modello: la sessione continua sul modello che stava utilizzando. Il modello non viene ripristinato quando è stato ritirato o non è consentito da `availableModels`, quando un flag `--model` o una variabile di ambiente della famiglia `ANTHROPIC_MODEL` ne seleziona uno al lancio, o su provider che utilizzano ID di distribuzione specifici del provider, come [Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry](/docs/it/third-party-integrations); vedi [configurazione del modello](/docs/it/model-config#setting-your-model) per l'ordine di risoluzione.41* Modello: la sessione continua sul modello che stava utilizzando. Il modello non viene ripristinato quando è stato ritirato o non è consentito da `availableModels`, quando un flag `--model` o una variabile di ambiente della famiglia `ANTHROPIC_MODEL` ne seleziona uno al lancio, o su provider che utilizzano ID di distribuzione specifici del provider, come [Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry](/docs/it/third-party-integrations); vedi [configurazione del modello](/docs/it/model-config#setting-your-model) per l'ordine di risoluzione.

42* Agent: una sessione avviata con [`--agent`](/docs/it/sub-agents#invoke-subagents-explicitly) o l'impostazione `agent` continua come quell'agent, mantenendo il suo prompt di sistema, le restrizioni degli strumenti e il modello. Passa `--agent` quando riprendi per sceglierne uno diverso. Claude Code cerca l'agent in due posti: la directory originale della sessione, a condizione che tu abbia [fiducia in quell'area di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust), e poi la directory da cui riprendi, quindi un agent con ambito di progetto si carica ancora quando riprendi da un'altra directory. Se Claude Code non trova l'agent in nessuno dei due posti, la sessione riprende con gli strumenti predefiniti e il prompt di sistema e mostra un [avviso che nomina l'agent](/docs/it/errors#session-agent-no-longer-available).42* Agent: una sessione avviata con [`--agent`](/docs/it/sub-agents#invoke-subagents-explicitly) o l'impostazione `agent` continua come quell'agent, mantenendo le sue restrizioni degli strumenti e il modello. Passa `--agent` quando riprendi per sceglierne uno diverso; per il prompt di sistema in entrambi i casi, vedi [Flag del prompt di sistema nelle conversazioni riprese](/docs/it/cli-reference#system-prompt-flags-in-resumed-conversations). Claude Code cerca l'agent in due posti: la directory originale della sessione, a condizione che tu abbia [fiducia in quell'area di lavoro](/docs/it/permissions#project-allow-rules-and-workspace-trust), e poi la directory da cui riprendi, quindi un agent con ambito di progetto si carica ancora quando riprendi da un'altra directory. Se Claude Code non trova l'agent in nessuno dei due posti, la sessione riprende con gli strumenti predefiniti e mostra un [avviso che nomina l'agent](/docs/it/errors#session-agent-no-longer-available).

43* Modalità di autorizzazione: se riprendi da un terminale con `claude --continue`, `claude --resume <session-id>` o `claude --resume <name>` quando il nome corrisponde a una sessione, senza `-p`, Claude Code ripristina la modalità di autorizzazione in cui era la sessione, tranne nei casi in [modalità di autorizzazione al ripristino](#permission-mode-on-resume), che copre anche il selezionatore di sessioni, `/resume` e la ripresa con `claude -p`. Passa `--permission-mode` o `--dangerously-skip-permissions` per ignorare la modalità ripristinata.43* Modalità di autorizzazione: se riprendi da un terminale con `claude --continue`, `claude --resume <session-id>` o `claude --resume <name>` quando il nome corrisponde a una sessione, senza `-p`, Claude Code ripristina la modalità di autorizzazione in cui era la sessione, tranne nei casi in [modalità di autorizzazione al ripristino](#permission-mode-on-resume), che copre anche il selezionatore di sessioni, `/resume` e la ripresa con `claude -p`. Passa `--permission-mode` o `--dangerously-skip-permissions` per ignorare la modalità ripristinata.

44* Obiettivo attivo: un [obiettivo](/docs/it/goal#resume-with-an-active-goal) che era ancora attivo quando la sessione è terminata si trasferisce; il suo conteggio dei turni, il timer e la linea di base della spesa di token si ripristinano.44* Obiettivo attivo: un [obiettivo](/docs/it/goal#resume-with-an-active-goal) che era ancora attivo quando la sessione è terminata si trasferisce; il suo conteggio dei turni, il timer e la linea di base della spesa di token si ripristinano.

45* Attività pianificate: le [attività che non sono scadute](/docs/it/scheduled-tasks#limitations) vengono ripristinate. Le attività Bash in background e le attività di monitoraggio non lo sono.45* Attività pianificate: le [attività che non sono scadute](/docs/it/scheduled-tasks#limitations) vengono ripristinate. Le attività Bash in background e le attività di monitoraggio non lo sono.

46 46

47Non ogni flag di configurazione dal lancio originale viene ripristinato. Se la sessione dipendeva da `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model` o directory aggiunte con `--add-dir`, passale di nuovo quando riprendi; le directory aggiunte a metà sessione con `/add-dir` non vengono ripristinate neanche, anche se il selezionatore di sessioni le usa ancora per individuare la sessione. I file di impostazioni standard, come `settings.json` e `settings.local.json`, vengono riletti al lancio, quindi la configurazione che vive in essi non ha bisogno di essere passata di nuovo.47Non ogni flag di configurazione dal lancio originale viene ripristinato. Se la sessione dipendeva da `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model` o directory aggiunte con `--add-dir`, passale di nuovo quando riprendi; le directory aggiunte a metà sessione con `/add-dir` non vengono ripristinate neanche, anche se il selezionatore di sessioni le usa ancora per individuare la sessione. I file di impostazioni standard, come `settings.json` e `settings.local.json`, vengono riletti al lancio, quindi la configurazione che vive in essi non ha bisogno di essere passata di nuovo. Per `--system-prompt` e `--append-system-prompt`, vedi [Flag del prompt di sistema nelle conversazioni riprese](/docs/it/cli-reference#system-prompt-flags-in-resumed-conversations).

48 48

49<h4 id="permission-mode-on-resume">49<h4 id="permission-mode-on-resume">

50 Modalità di autorizzazione al ripristino50 Modalità di autorizzazione al ripristino

settings.md +57 −54

Details

605 Quando gli edits hanno effetto605 Quando gli edits hanno effetto

606</h3>606</h3>

607 607

608Claude Code osserva i vostri file di impostazioni e li ricarica quando cambiano, quindi applica la maggior parte degli edits alla sessione in esecuzione senza un riavvio, inclusi gli edits a `permissions`, `hooks` e helper di credenziali come `apiKeyHelper`. Il ricaricamento copre le impostazioni utente, progetto, locale e gestite, e Claude Code esegue l'[hook `ConfigChange`](/docs/it/hooks#configchange) per ogni modifica di file di impostazioni che rileva, non per le impostazioni gestite che arrivano da MDM o dalla console claude.ai. Le impostazioni gestite che arrivano attraverso MDM o dalla console claude.ai raggiungono una sessione in esecuzione secondo una pianificazione piuttosto che al salvataggio; la [tabella di consegna](/docs/it/managed-settings#choose-a-delivery-mechanism) la fornisce per fonte.608Claude Code osserva i vostri file di impostazioni e li ricarica quando cambiano, quindi applica la maggior parte degli edits alla sessione in esecuzione senza un riavvio, inclusi gli edits a `permissions`, `hooks` e helper di credenziali come `apiKeyHelper`. Claude Code anche carica un file di impostazioni che create a metà sessione se la sua cartella esisteva quando la sessione è iniziata. Per la cartella `.claude/` del progetto, carica il file anche quando create la cartella nella stessa sessione.

609

610Il ricaricamento copre le impostazioni utente, progetto, locale e gestite, e Claude Code esegue l'[hook `ConfigChange`](/docs/it/hooks#configchange) per ogni modifica di file di impostazioni che rileva, non per le impostazioni gestite che arrivano da MDM o dalla console claude.ai. Le impostazioni gestite che arrivano attraverso MDM o dalla console claude.ai raggiungono una sessione in esecuzione secondo una pianificazione piuttosto che al salvataggio; la [tabella di consegna](/docs/it/managed-settings#choose-a-delivery-mechanism) la fornisce per fonte.

609 611

610Claude Code legge alcune chiavi solo una volta, all'avvio della sessione, quindi un edit a una di esse non raggiunge la sessione in esecuzione. Le chiavi lato amministratore che attendono anche un riavvio, come `requiredMinimumVersion`, sono elencate sotto [dove e quando si applica una politica](/docs/it/managed-settings#where-and-when-a-policy-applies). Quelle che è più probabile che modifichiate a metà sessione:612Claude Code legge alcune chiavi solo una volta, all'avvio della sessione, quindi un edit a una di esse non raggiunge la sessione in esecuzione. Le chiavi lato amministratore che attendono anche un riavvio, come `requiredMinimumVersion`, sono elencate sotto [dove e quando si applica una politica](/docs/it/managed-settings#where-and-when-a-policy-applies). Quelle che è più probabile che modifichiate a metà sessione:

611 613

651 Precedenza delle impostazioni653 Precedenza delle impostazioni

652</h2>654</h2>

653 655

654Quando la stessa chiave appare in più di un posto, Claude Code usa il valore dal livello più alto che la imposta. Lo stack sottostante mostra i livelli, il più alto in alto; una chiave a un livello più alto ignora la stessa chiave ovunque sotto.656Quando la stessa chiave appare in più di un posto, Claude Code utilizza il valore dal livello più alto che la imposta. Lo stack sottostante mostra i livelli, il più alto in alto; una chiave a un livello più alto sostituisce la stessa chiave ovunque al di sotto.

655 657

656<SettingsPrecedence />658<SettingsPrecedence />

657 659

658In ordine, precedenza più alta prima:660In ordine, dalla precedenza più alta in primo luogo:

659 661

6601. **Impostazioni gestite**: impostazioni che la vostra organizzazione distribuisce, da un file `managed-settings.json`, una politica MDM, o [impostazioni gestite dal server](/docs/it/server-managed-settings) dalla console claude.ai. Nulla di quello che impostate le ignora: una chiave che passate con `--settings` non ignora la stessa chiave gestita, e un flag come `--model` sceglie solo dai modelli che la vostra organizzazione consente. Un `model` gestito imposta il modello con cui ogni sessione inizia, e potete comunque cambiare con `/model`; il blocco è [`availableModels`](/docs/it/settings-reference#availablemodels), che vincola `/model`, `--model` e la chiave `model` nei vostri file. Quando la vostra organizzazione fornisce più di una fonte gestita, le regole per [precedenza all'interno del livello gestito](/docs/it/managed-settings#precedence-within-the-managed-tier) dicono cosa Claude Code legge da ognuna.6621. **Impostazioni gestite**: impostazioni che la tua organizzazione distribuisce, tramite un file `managed-settings.json`, una policy MDM, o [impostazioni gestite dal server](/docs/it/server-managed-settings) dalla console claude.ai. Nulla di quello che imposti le sostituisce: una chiave che passi con `--settings` non sostituisce la stessa chiave gestita, e un flag come `--model` sceglie solo dai modelli che la tua organizzazione consente. Un `model` gestito imposta il modello con cui inizia ogni sessione, e puoi comunque passare a `/model`; il blocco è [`availableModels`](/docs/it/settings-reference#availablemodels), che vincola `/model`, `--model`, e la chiave `model` nei tuoi file. Quando la tua organizzazione fornisce più di una fonte gestita, le regole per la [precedenza all'interno del livello gestito](/docs/it/managed-settings#precedence-within-the-managed-tier) dicono cosa Claude Code legge da ciascuna.

6612. **Argomenti della riga di comando**: flag che passate quando avviate `claude` da un terminale, per una sessione; vedere [Modificate un'impostazione per una sessione](#change-a-setting-for-one-session). Claude Code unisce JSON che passate con `--settings <file-or-json>` con i vostri file di impostazioni secondo le stesse regole degli altri livelli: prende una chiave che impostate qui sopra la stessa chiave nelle impostazioni locale, progetto o utente, e mantiene il valore di livello inferiore per una chiave che omettete.6632. **Argomenti della riga di comando**: flag che passi quando avvii `claude` da un terminale, per una sessione; vedi [Cambia un'impostazione per una sessione](#change-a-setting-for-one-session). Claude Code unisce il JSON che passi con `--settings <file-or-json>` con i tuoi file di impostazioni secondo le stesse regole degli altri livelli: prende una chiave che imposti qui rispetto alla stessa chiave nelle impostazioni locali, di progetto o utente, e mantiene il valore di livello inferiore per una chiave che ometti.

6623. **Impostazioni di progetto locale** (`.claude/settings.local.json`): le vostre impostazioni personali per questo progetto.6643. **Impostazioni locali del progetto** (`.claude/settings.local.json`): le tue impostazioni personali per questo progetto.

6634. **Impostazioni di progetto condivise** (`.claude/settings.json`): impostazioni che il vostro team controlla nel controllo del codice sorgente.6654. **Impostazioni di progetto condivise** (`.claude/settings.json`): impostazioni che il tuo team inserisce nel controllo del codice sorgente.

6645. **Impostazioni utente** (`~/.claude/settings.json`): le vostre impostazioni personali per ogni progetto.6665. **Impostazioni utente** (`~/.claude/settings.json`): le tue impostazioni personali per ogni progetto.

665 667

666Le variabili di ambiente non sono un livello in questo stack. Quando un comportamento ha sia una variabile shell che una chiave di impostazioni, quale si applica è deciso per coppia, non per livello: `ANTHROPIC_MODEL` esportato nella vostra shell si applica sopra la chiave `model` da qualsiasi file, mentre `ANTHROPIC_DEFAULT_MODEL` si applica solo quando nessun file imposta `model`. La [referenza delle variabili di ambiente](/docs/it/env-vars#precedence) dice quali chiavi hanno una coppia e quale Claude Code legge prima. Un blocco `env` dentro un file di impostazioni è una chiave ordinaria e segue i livelli sopra.668Le variabili di ambiente non sono un livello in questo stack. Quando un comportamento ha sia una variabile di shell che una chiave di impostazione, quale si applica è deciso per coppia, non per livello: `ANTHROPIC_MODEL` esportato nella tua shell si applica rispetto alla chiave `model` da qualsiasi file, mentre `ANTHROPIC_DEFAULT_MODEL` si applica solo quando nessun file imposta `model`. Il [riferimento delle variabili di ambiente](/docs/it/env-vars#precedence) dice quali chiavi hanno una coppia e quale Claude Code legge per primo. Un blocco `env` all'interno di un file di impostazioni è una chiave ordinaria e segue i livelli sopra.

667 669

668Per poche chiavi sensibili alla sicurezza, Claude Code onora un valore più rigoroso da un livello inferiore sopra un valore gestito; [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence) le elenca.670Per alcune chiavi sensibili alla sicurezza, Claude Code onora un valore più restrittivo da un livello inferiore rispetto a un valore gestito; [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence) le elenca.

669 671

670<h3 id="lists-merge-instead-of-overriding">672<h3 id="lists-merge-instead-of-overriding">

671 Gli elenchi si uniscono invece di ignorarsi673 Gli elenchi si uniscono invece di sostituirsi

672</h3>674</h3>

673 675

674Quando impostate la stessa chiave di elenco, come `permissions.allow`, in più di un file, Claude Code combina gli elenchi invece di sceglierne uno, quindi ogni file può aggiungere voci senza rimuovere quelle di un altro file. Quattro chiavi che contengono elenchi di modelli o voci per-modello seguono le loro regole:676Quando imposti la stessa chiave di elenco, come `permissions.allow`, in più di un file, Claude Code combina gli elenchi invece di sceglierne uno, così ogni file può aggiungere voci senza rimuovere quelle di un altro file. Quattro chiavi che contengono elenchi di modelli o voci per modello seguono le loro proprie regole:

675 677

676* [`fallbackModel`](/docs/it/settings-reference#fallbackmodel) è una catena ordinata dove la posizione ha significato, quindi Claude Code prende l'intero valore dal file con la precedenza più alta che la definisce.678* [`fallbackModel`](/docs/it/settings-reference#fallbackmodel) è una catena ordinata in cui la posizione ha significato, quindi Claude Code prende l'intero valore dal file con la precedenza più alta che lo definisce.

677* [`modelPicker`](/docs/it/settings-reference#modelpicker) contiene un elenco ordinato di righe più un flag di sostituzione, quindi Claude Code non unisce mai righe da due fonti. Prende l'intero valore dal più alto tra le impostazioni gestite, `--settings` e le impostazioni utente che la definisce, e ignora la chiave nelle impostazioni di progetto e locale. Richiede Claude Code v2.1.242 o successivo.679* [`modelPicker`](/docs/it/settings-reference#modelpicker) contiene un elenco ordinato di righe più un flag di sostituzione, quindi Claude Code non unisce mai righe da due fonti. Prende l'intero valore dal più alto tra impostazioni gestite, `--settings`, e impostazioni utente che lo definisce, e ignora la chiave nelle impostazioni di progetto e locali. Richiede Claude Code v2.1.242 o successivo.

678* [`availableModels`](/docs/it/settings-reference#availablemodels): quando le impostazioni gestite che Claude Code applica la definiscono, Claude Code applica quell'elenco così com'è e ignora le voci che aggiungete nelle impostazioni utente, progetto o locale, a meno che un'app che incorpora Claude Code non fornisca il suo elenco di modelli; vedere [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence). Tra le fonti gestite l'elenco non si unisce mai neanche; [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) dice quale elenco della fonte si applica. Tra gli ambiti non gestiti Claude Code unisce gli array come al solito.680* [`availableModels`](/docs/it/settings-reference#availablemodels): quando le impostazioni gestite che Claude Code applica lo definiscono, Claude Code applica quell'elenco così com'è e ignora le voci che aggiungi nelle impostazioni utente, di progetto o locali, a meno che un'app che incorpora Claude Code non fornisca il suo elenco di modelli; vedi [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence). Tra le fonti gestite l'elenco non si unisce mai; [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) dice quale elenco della fonte si applica. Tra gli ambiti non gestiti Claude Code unisce gli array come al solito.

679* [`modelSettings`](/docs/it/settings-reference#modelsettings): Claude Code lo risolve un modello alla volta, insieme a [`effortLevel`](/docs/it/settings-reference#effortlevel). La voce `modelSettings` dice quale file il valore si applica a un modello.681* [`modelSettings`](/docs/it/settings-reference#modelsettings): Claude Code lo risolve un modello alla volta, insieme a [`effortLevel`](/docs/it/settings-reference#effortlevel). La voce `modelSettings` indica quale valore del file si applica a un modello.

680 682

681<span id="examples" />683<span id="examples" />

682 684

684 Esempi di precedenza686 Esempi di precedenza

685</h3>687</h3>

686 688

687Mentre Claude lavora, Claude Code mostra un suggerimento di una riga sotto lo spinner, come "Usate /config per modificare la vostra modalità di permesso predefinita (inclusa la modalità Piano)". Supponiamo che volete quei suggerimenti spenti, quindi impostate [`spinnerTipsEnabled`](/docs/it/settings-reference#spinnertipsenabled) a `false` in `~/.claude/settings.json`. Ogni scenario sottostante è qualcosa che può riattivarli, e cosa potete fare al riguardo.689Mentre Claude lavora, Claude Code mostra un suggerimento di una riga sotto lo spinner, come "Usa /config per cambiare la tua modalità di autorizzazione predefinita (inclusa Plan Mode)". Supponiamo che tu voglia disattivare questi suggerimenti, quindi imposti [`spinnerTipsEnabled`](/docs/it/settings-reference#spinnertipsenabled) a `false` in `~/.claude/settings.json`. Ogni scenario sottostante è qualcosa che può riattivarli, e cosa puoi fare al riguardo.

688 690

689<h4 id="team-settings-override-personal-settings">691<h4 id="team-settings-override-personal-settings">

690 Le impostazioni del team ignorano le impostazioni personali692 Le impostazioni del team sostituiscono le impostazioni personali

691</h4>693</h4>

692 694

693Il `.claude/settings.json` del vostro team lo imposta a `true`. Claude Code usa il valore del progetto perché il progetto condiviso si trova sopra l'utente, quindi vedete i suggerimenti in quel progetto e da nessun'altra parte.695Il `.claude/settings.json` del tuo team lo imposta a `true`. Claude Code utilizza il valore del progetto perché il progetto condiviso si trova sopra l'utente, quindi vedi i suggerimenti in quel progetto e da nessun'altra parte.

694 696

695Potete recuperare il vostro valore: aggiungete `"spinnerTipsEnabled": false` a `.claude/settings.local.json` in quel progetto. Il progetto locale si trova sopra il progetto condiviso, quindi le vostre sessioni lì smettono di mostrare i suggerimenti e le sessioni dei vostri compagni di squadra non cambiano.697Puoi recuperare il tuo valore: aggiungi `"spinnerTipsEnabled": false` a `.claude/settings.local.json` in quel progetto. Il progetto locale si trova sopra il progetto condiviso, quindi le tue sessioni lì smettono di mostrare suggerimenti e le sessioni dei tuoi compagni di squadra non cambiano.

696 698

697<h4 id="organization-settings-override-everything">699<h4 id="organization-settings-override-everything">

698 Le impostazioni dell'organizzazione ignorano tutto700 Le impostazioni dell'organizzazione sostituiscono tutto

699</h4>701</h4>

700 702

701Le impostazioni gestite della vostra organizzazione lo impostano a `true`. Nulla di quello che mettete nelle impostazioni utente, progetto o locale spegne i suggerimenti, e neanche `--settings`. Gestito è il livello più alto.703Le impostazioni gestite della tua organizzazione lo impostano a `true`. Nulla di quello che metti nelle impostazioni utente, di progetto o locali disattiva i suggerimenti, e nemmeno `--settings`. Gestito è il livello più alto.

702 704

703Non potete recuperare il vostro valore. Eseguite `/status` per vedere quale fonte gestita si applica, e chiedete al vostro amministratore se la politica dovrebbe cambiare.705Non puoi recuperare il tuo valore. Esegui `/status` per vedere quale fonte gestita si applica, e chiedi al tuo amministratore se la policy dovrebbe cambiare.

704 706

705<h4 id="the-command-line-overrides-your-files-for-one-session">707<h4 id="the-command-line-overrides-your-files-for-one-session">

706 La riga di comando ignora i vostri file per una sessione708 La riga di comando sostituisce i tuoi file per una sessione

707</h4>709</h4>

708 710

709Avete avviato la sessione con `claude --settings '{"spinnerTipsEnabled": true}'`. La riga di comando si trova sopra ogni file tranne gestito, quindi quella sessione mostra i suggerimenti anche se i vostri file dicono `false`.711Hai avviato la sessione con `claude --settings '{"spinnerTipsEnabled": true}'`. La riga di comando si trova sopra ogni file tranne gestito, quindi quella sessione mostra suggerimenti anche se i tuoi file dicono `false`.

710 712

711Recuperate il vostro valore nella sessione successiva; `--settings` dura una sessione e non scrive in alcun file.713Recuperi il tuo valore nella sessione successiva; `--settings` dura una sessione e non scrive in nessun file.

712 714

713<h4 id="a-flag-or-environment-variable-sets-the-same-thing">715<h4 id="a-flag-or-environment-variable-sets-the-same-thing">

714 Un flag o una variabile di ambiente imposta la stessa cosa716 Un flag o una variabile di ambiente imposta la stessa cosa

715</h4>717</h4>

716 718

717Alcune chiavi hanno un flag della riga di comando o una variabile di ambiente che ignora il valore delle impostazioni indipendentemente da quale file lo ha impostato: `ANTHROPIC_MODEL` ignora l'impostazione [`model`](/docs/it/settings-reference#model), e `--model` ignora entrambi per una sessione.719Alcune chiavi hanno un flag della riga di comando o una variabile di ambiente che sostituisce il valore delle impostazioni indipendentemente da quale file lo ha impostato: `ANTHROPIC_MODEL` sostituisce l'impostazione [`model`](/docs/it/settings-reference#model), e `--model` sostituisce entrambi per una sessione.

718 720

719Se potete recuperare il vostro valore dipende dalla chiave: annullate la variabile o eliminate il flag, e controllate la voce della chiave sulla [referenza delle impostazioni](/docs/it/settings-reference) e la riga della variabile sulla [referenza delle variabili di ambiente](/docs/it/env-vars) per quale Claude Code usa.721Se puoi recuperare il tuo valore dipende dalla chiave: annulla l'impostazione della variabile o elimina il flag, e controlla la voce della chiave nel [riferimento delle impostazioni](/docs/it/settings-reference) e la riga della variabile nel [riferimento delle variabili di ambiente](/docs/it/env-vars) per sapere quale Claude Code utilizza.

720 722

721<span id="keys-ignored-in-a-repository-file" />723<span id="keys-ignored-in-a-repository-file" />

722 724

727<span id="which-value-applies-in-common-situations" />729<span id="which-value-applies-in-common-situations" />

728 730

729<h3 id="troubleshoot-a-setting-that-doesn’t-apply">731<h3 id="troubleshoot-a-setting-that-doesn’t-apply">

730 Risolvete i problemi di un'impostazione che non si applica732 Risolvi i problemi di un'impostazione che non si applica

731</h3>733</h3>

732 734

733Quando impostate una chiave e Claude Code non si comporta come se l'aveste fatto, iniziate con `/status` per vedere quali file ha caricato, quindi trovate il vostro sintomo sottostante. [Debug della vostra configurazione](/docs/it/debug-your-config) copre i controlli più ampi, incluso un test di configurazione pulita.735Quando imposti una chiave e Claude Code non si comporta come se l'avessi fatto, inizia con `/status` per vedere quali file ha caricato, quindi trova il tuo sintomo di seguito. [Debug della tua configurazione](/docs/it/debug-your-config) copre i controlli più ampi, incluso un test di configurazione pulita.

734 736

735<h4 id="a-value-you-set-is-ignored">737<h4 id="a-value-you-set-is-ignored">

736 Un valore che impostate è ignorato738 Un valore che hai impostato viene ignorato

737</h4>739</h4>

738 740

739Qualcos'altro imposta la stessa chiave, il file non può impostare quel valore, o il file non è stato caricato:741Qualcos'altro sta impostando la stessa chiave, il file non può impostare quel valore, o il file non è stato caricato:

740 742

741* **Un livello più alto lo imposta.** Un altro file di impostazioni, un flag `--settings`, o una fonte gestita imposta la chiave sopra la vostra; lo [stack](#settings-precedence) dice quale. Un flag o una variabile di ambiente può anche ignorare la chiave per conto suo, deciso chiave per chiave; la voce della chiave sulla [referenza delle impostazioni](/docs/it/settings-reference) dice quale Claude Code usa, e la voce [`env`](/docs/it/settings-reference#env) copre un valore `env` gestito rispetto a un'esportazione shell.743* **Un livello più alto lo imposta.** Un altro file di impostazioni, un flag `--settings`, o una fonte gestita imposta la chiave sopra la tua; lo [stack](#settings-precedence) dice quale. Un flag o una variabile di ambiente può anche sostituire la chiave di per sé, deciso chiave per chiave; la voce della chiave nel [riferimento delle impostazioni](/docs/it/settings-reference) dice quale Claude Code utilizza, e la [voce `env`](/docs/it/settings-reference#env) copre un valore `env` gestito rispetto a un'esportazione di shell.

742* **Una chiave di sicurezza mantiene il suo valore rigoroso.** Per poche chiavi Claude Code onora il valore restrittivo da qualsiasi file, quindi un progetto `true` per [`disableClaudeAiConnectors`](/docs/it/settings-reference#disableclaudeaiconnectors) rimane acceso; vedere [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence).744* **Una chiave di sicurezza mantiene il suo valore restrittivo.** Per alcune chiavi Claude Code onora il valore restrittivo da qualsiasi file, quindi un `true` di progetto per [`disableClaudeAiConnectors`](/docs/it/settings-reference#disableclaudeaiconnectors) rimane attivo; vedi [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence).

743* **Il file non può impostare quel valore.** I valori [`permissions.defaultMode`](/docs/it/settings-reference#permissions-defaultmode) `auto` e `bypassPermissions` non hanno effetto dalle impostazioni di progetto o locale; impostateli nelle impostazioni utente o gestite invece, o passate `--permission-mode` per una sessione. Prima della v2.1.257, `bypassPermissions` aveva effetto da qualsiasi file.745* **Il file non può impostare quel valore.** I valori [`permissions.defaultMode`](/docs/it/settings-reference#permissions-defaultmode) `auto` e `bypassPermissions` non hanno effetto dalle impostazioni di progetto o locali; impostali invece nelle impostazioni utente o gestite, o passa `--permission-mode` per una sessione. Prima della v2.1.257, `bypassPermissions` aveva effetto da qualsiasi file.

744* **Il file è rotto.** JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; vedere [Riparate un file di impostazioni rotto](#fix-a-broken-settings-file).746* **Il file è rotto.** JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; vedi [Ripara un file di impostazioni rotto](#fix-a-broken-settings-file).

745 747

746<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">748<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">

747 Una modifica che avete fatto in Claude Code è persa nelle nuove sessioni749 Una modifica che hai fatto in Claude Code viene persa nelle nuove sessioni

748</h4>750</h4>

749 751

750Quando salvate una scelta per le nuove sessioni da dentro Claude Code, come un modello predefinito con `/model`, Claude Code la scrive nel vostro file di impostazioni utente, `~/.claude/settings.json`. Se non potete scrivere in quel file, ad esempio perché un altro strumento lo genera o lo collega a una copia di sola lettura, la modifica si applica alla sessione corrente e è persa nella successiva. Impostate la chiave nello strumento che genera il file, o sostituite il file con uno in cui potete scrivere.752Quando salvi una scelta per le nuove sessioni dall'interno di Claude Code, come un modello predefinito con `/model`, Claude Code la scrive nel tuo file di impostazioni utente, `~/.claude/settings.json`. Se non puoi scrivere in quel file, ad esempio perché un altro strumento lo genera o lo collega a una copia di sola lettura, la modifica si applica alla sessione corrente e scompare nella successiva. Imposta la chiave nello strumento che genera il file, o sostituisci il file con uno in cui puoi scrivere.

751 753

752Se potete scrivere nel file e la modifica comunque non dura, controllate se la modifica era [solo per una sessione](#change-a-setting-for-one-session) o [un livello più alto imposta la stessa chiave](#a-value-you-set-is-ignored). Per la chiave `model`, [Una nuova sessione inizia su un modello diverso da quello che avete scelto](/docs/it/model-config#a-new-session-starts-on-a-different-model-than-you-picked) elenca più cause.754Se puoi scrivere nel file e la modifica comunque non dura, controlla se la modifica era [solo per una sessione](#change-a-setting-for-one-session) o [un livello più alto imposta la stessa chiave](#a-value-you-set-is-ignored). Per la chiave `model`, [Una nuova sessione inizia su un modello diverso da quello che hai scelto](/docs/it/model-config#a-new-session-starts-on-a-different-model-than-you-picked) elenca più cause.

753 755

754<h4 id="a-managed-change-hasn’t-reached-you">756<h4 id="a-managed-change-hasn’t-reached-you">

755 Una modifica gestita non vi ha raggiunto757 Una modifica gestita non ti ha raggiunto

756</h4>758</h4>

757 759

758Le fonti gestite raggiungono una sessione in esecuzione secondo la pianificazione nella [tabella di consegna](/docs/it/managed-settings#choose-a-delivery-mechanism), quindi riavviate prima la sessione. Se `/status` allora nomina una fonte diversa da quella che il vostro amministratore ha modificato, una fonte con priorità più alta si applica; [Come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) fornisce l'ordine.760Le fonti gestite raggiungono una sessione in esecuzione secondo la pianificazione nella [tabella di consegna](/docs/it/managed-settings#choose-a-delivery-mechanism), quindi riavvia prima la sessione. Se `/status` quindi nomina una fonte diversa da quella che il tuo amministratore ha modificato, una fonte con priorità più alta si applica; [Come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) fornisce l'ordine.

759 761

760<h4 id="a-committed-key-doesn’t-reach-teammates">762<h4 id="a-committed-key-doesn’t-reach-teammates">

761 Una chiave committata non raggiunge i compagni di squadra763 Una chiave impegnata non raggiunge i compagni di squadra

762</h4>764</h4>

763 765

764Due cose impediscono a una chiave in `.claude/settings.json` di applicarsi per tutti coloro che la clonano:766Due cose impediscono a una chiave in `.claude/settings.json` di applicarsi per tutti coloro che la clonano:

765 767

766* **Claude Code ignora la chiave in un file di repository.** Cercate `User, local, or managed`, `User or managed`, `Managed`, o `Global config` nella colonna Scope dell'[indice delle impostazioni](/docs/it/settings-reference#settings-index); quelle chiavi non si applicano mai dal file condiviso, a parte [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit), che un file di repository può comunque spegnere: mentre il file imposta la chiave e nessun valore utente, `--settings` o gestito lo fa, Claude Code legge l'impostazione come spenta. Le chiavi `Global config` si applicano solo da `~/.claude.json`.768* **Claude Code ignora la chiave in un file di repository.** Cerca `User, local, or managed`, `User or managed`, `Managed`, o `Global config` nella colonna Scope dell'[indice delle impostazioni](/docs/it/settings-reference#settings-index); quelle chiavi non si applicano mai dal file condiviso, a parte [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit), che un file di repository può comunque disattivare: mentre il file imposta la chiave e nessun valore utente, `--settings`, o gestito lo fa, Claude Code legge l'impostazione come disattivata. Le chiavi `Global config` si applicano solo da `~/.claude.json`.

767* **La chiave attende la fiducia.** Le regole `permissions.allow`, `permissions.additionalDirectories`, `extraKnownMarketplaces` e la maggior parte dei valori [`env`](/docs/it/settings-reference#env) si applicano solo dopo che ogni compagno di squadra [fidia della cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust). Fino ad allora vedono comunque i prompt e non ottengono i plugin da un marketplace che il file dichiara. Le regole `deny` e `ask` si applicano subito.769* **La chiave attende la fiducia.** Le regole `permissions.allow`, `permissions.additionalDirectories`, `extraKnownMarketplaces`, e la maggior parte dei valori [`env`](/docs/it/settings-reference#env) si applicano solo dopo che ogni compagno di squadra [affida la cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust). Fino ad allora vedono ancora i prompt e non ottengono plugin da un marketplace che il file dichiara. Le regole `deny` e `ask` si applicano subito.

768 770

769<h4 id="permission-rules-combine-differently-than-you-expected">771<h4 id="permission-rules-combine-differently-than-you-expected">

770 Le regole di permesso si combinano diversamente da come vi aspettate772 Le regole di autorizzazione si combinano diversamente da quanto ti aspettavi

771</h4>773</h4>

772 774

773* **Avete scelto "Sì, e non chiedere di nuovo" su un prompt di permesso ma ricevete comunque il prompt per lo stesso strumento.** Quella scelta ha salvato una regola `allow` nel vostro file locale, e una regola `allow` lì non supera una regola `ask` da un file di progetto o gestito; [come le regole di permesso si combinano](/docs/it/permissions#settings-precedence) spiega l'ordine. Nell'estensione VS Code la scheda di approvazione vi permette di scegliere il file di destinazione, incluso il file condiviso del progetto, che cambia la regola per tutti; nella CLI, Claude Code scrive solo nel vostro file locale.775* **Hai scelto "Sì, e non chiedere di nuovo" su un prompt di autorizzazione ma ricevi comunque un prompt per lo stesso strumento.** Quella scelta ha salvato una regola `allow` nel tuo file locale, e una regola `allow` lì non supera una regola `ask` da un file di progetto o gestito; [come si combinano le regole di autorizzazione](/docs/it/permissions#settings-precedence) spiega l'ordine. Nell'estensione VS Code la scheda di approvazione ti permette di scegliere il file di destinazione, incluso il file condiviso del progetto, che cambia la regola per tutti; nella CLI, Claude Code scrive solo nel tuo file locale.

774* **Le regole allow della vostra organizzazione si applicano comunque insieme alle vostre.** È previsto: Claude Code unisce [`permissions.allow`](/docs/it/settings-reference#permissions-allow) tra gli ambiti, a meno che la vostra organizzazione non imposti [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly).776* **Le regole di autorizzazione della tua organizzazione si applicano ancora insieme alle tue.** È previsto: Claude Code unisce [`permissions.allow`](/docs/it/settings-reference#permissions-allow) tra gli ambiti, a meno che la tua organizzazione non imposti [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly).

775 777

776<span id="security-keys-where-the-stricter-value-applies" />778<span id="security-keys-where-the-stricter-value-applies" />

777 779

779 Eccezioni alla precedenza delle impostazioni gestite781 Eccezioni alla precedenza delle impostazioni gestite

780</h3>782</h3>

781 783

782Per poche chiavi sensibili alla sicurezza, Claude Code onora un valore restrittivo da un ambito che altrimenti non potrebbe ignorare le impostazioni gestite. Trovate la chiave in questa tabella per vedere quale valore onora e da dove.784Per alcune chiavi i cui valori limitano una sessione, Claude Code onora un valore restrittivo da un ambito che altrimenti non potrebbe sostituire le impostazioni gestite. Trova la chiave in questa tabella per vedere quale valore onora e da dove.

783 785

785| :------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |787| :------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

786| [`disableClaudeAiConnectors`](/docs/it/settings-reference#disableclaudeaiconnectors) | `true` da qualsiasi ambito | Onorato anche quando una fonte gestita imposta `false` |788| [`disableClaudeAiConnectors`](/docs/it/settings-reference#disableclaudeaiconnectors) | `true` da qualsiasi ambito | Onorato anche quando una fonte gestita imposta `false` |

787| [`enableArtifact`](/docs/it/settings-reference#enableartifact) | `false` da qualsiasi ambito, e `disableArtifact: true` da qualsiasi ambito | Onorato anche quando una fonte gestita imposta `true`; nulla riattiva lo [strumento Artifact](/docs/it/artifacts#disable-artifacts). Richiede Claude Code v2.1.242 o successivo |789| [`enableArtifact`](/docs/it/settings-reference#enableartifact) | `false` da qualsiasi ambito, e `disableArtifact: true` da qualsiasi ambito | Onorato anche quando una fonte gestita imposta `true`; nulla riattiva lo [strumento Artifact](/docs/it/artifacts#disable-artifacts). Richiede Claude Code v2.1.242 o successivo |

789| [`remoteControlAtStartup`](/docs/it/settings-reference#remotecontrolatstartup) | `false` da `.claude/settings.json` o `.claude/settings.local.json` | Onorato anche quando una fonte gestita imposta `true`; un progetto o locale `true` è ignorato |791| [`remoteControlAtStartup`](/docs/it/settings-reference#remotecontrolatstartup) | `false` da `.claude/settings.json` o `.claude/settings.local.json` | Onorato anche quando una fonte gestita imposta `true`; un `true` di progetto o locale viene ignorato |

790| [`crossSessionInbound`](/docs/it/settings-reference#crosssessioninbound) | Un valore più rigoroso da `.claude/settings.json` o `.claude/settings.local.json`, sulla scala `accept` \< `hold` \< `refuse` | Onorato sopra i valori gestiti, `--settings` e utente; un valore di progetto o locale che non è più rigoroso è ignorato |792| [`crossSessionInbound`](/docs/it/settings-reference#crosssessioninbound) | Un valore più restrittivo da `.claude/settings.json` o `.claude/settings.local.json`, sulla scala `accept` \< `hold` \< `refuse` | Onorato rispetto ai valori gestiti, `--settings`, e utente; un valore di progetto o locale che non è più restrittivo viene ignorato |

791| [`useAutoModeDuringPlan`](/docs/it/settings-reference#useautomodeduringplan) | `false` da qualsiasi fonte gestita, `--settings`, `~/.claude/settings.json` o `.claude/settings.local.json` | Onorato anche quando la fonte gestita vincente imposta `true`; un `false` in `.claude/settings.json` è ignorato |793| [`useAutoModeDuringPlan`](/docs/it/settings-reference#useautomodeduringplan) | `false` da qualsiasi fonte gestita, `--settings`, `~/.claude/settings.json`, o `.claude/settings.local.json` | Onorato anche quando la fonte gestita vincente imposta `true`; un `false` in `.claude/settings.json` viene ignorato |

792| [`syncClaudeAiSkills`](/docs/it/settings-reference#syncclaudeaiskills) | `false` da qualsiasi fonte gestita, `--settings`, `~/.claude/settings.json` o `.claude/settings.local.json` | Onorato anche quando la fonte gestita vincente imposta `true`; un `false` in `.claude/settings.json` è ignorato |794| [`syncClaudeAiSkills`](/docs/it/settings-reference#syncclaudeaiskills) | `false` da qualsiasi fonte gestita, `--settings`, `~/.claude/settings.json`, o `.claude/settings.local.json` | Onorato anche quando la fonte gestita vincente imposta `true`; un `false` in `.claude/settings.json` viene ignorato |

795| [`maxEffortLevel`](/docs/it/settings-reference#maxeffortlevel) | Un limite inferiore da qualsiasi ambito, incluso `--settings` | Onorato anche quando le impostazioni gestite che Claude Code applica impostano un limite superiore; si applica il limite più basso. Richiede Claude Code v2.1.267 o successivo |

793 796

794Un'app che esegue Claude Code dentro se stessa e imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/it/env-vars) è anche un'eccezione. Claude Code prende la configurazione del modello di quell'app sopra le chiavi `model`, `fallbackModel` e `modelOverrides` da ogni fonte gestita, e sopra le variabili di selezione del modello in un blocco `env` gestito, come `ANTHROPIC_MODEL` e la famiglia `ANTHROPIC_DEFAULT_*_MODEL`. Claude Code mantiene un [`availableModels`](/docs/it/settings-reference#availablemodels) gestito in vigore a meno che l'app non fornisca il suo.797Un'app che esegue Claude Code al suo interno e imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/it/env-vars) è anche un'eccezione. Claude Code prende la configurazione del modello di quell'app rispetto alle chiavi `model`, `fallbackModel`, `modelPicker`, e `modelOverrides` da ogni fonte gestita, e rispetto alle variabili di selezione del modello in un blocco `env` gestito, come `ANTHROPIC_MODEL` e la famiglia `ANTHROPIC_DEFAULT_*_MODEL`. Claude Code mantiene un elenco di autorizzazione [`availableModels`](/docs/it/settings-reference#availablemodels) gestito in vigore a meno che l'app non fornisca il suo.

795 798

796<h2 id="settings-in-cloud-sessions">799<h2 id="settings-in-cloud-sessions">

797 Impostazioni nelle sessioni cloud800 Impostazioni nelle sessioni cloud

settings-example.md +396 −0 created

Details

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.

5# File di impostazioni di esempio

7> File settings.json realistici per uno sviluppatore, un team e un'organizzazione: copia uno, mantieni le chiavi che desideri e modifica i valori.

9Questa pagina contiene tre file `settings.json` di esempio, uno per ogni luogo in cui salvi un'impostazione:

11* Un file `~/.claude/settings.json` di uno sviluppatore

12* Un file `.claude/settings.json` di un team, sottoposto a commit nel repository

13* Un file `managed-settings.json` di un'organizzazione

15Ognuno è un file plausibile per quel lettore, quindi puoi vedere la struttura e copiare le parti che desideri. Nessuno di essi è una baseline consigliata. Ogni valore proviene dalla voce della chiave nel [riferimento delle impostazioni](/docs/it/settings-reference), che contiene il suo tipo, il valore predefinito e dove può essere impostato.

17Ogni esempio ha due schede. **Copyable settings file** è il file come lo salveresti. **What each key does** è lo stesso file con un commento sopra ogni chiave; Claude Code non accetta commenti in un file di impostazioni, quindi copia dalla prima scheda.

19<h2 id="your-own-settings">

20 Le tue impostazioni personali

21</h2>

23Le impostazioni personali di uno sviluppatore. Sceglie un modello e uno sforzo, regola il terminale e pre-approva un comando di sola lettura e una lettura di file. Tutto ciò che non è elencato mantiene il suo valore predefinito. Un file come questo va in `~/.claude/settings.json`, dove si applica a ogni progetto che apri.

25<Tabs>

26 <Tab title="Copyable settings file">

27 Salva questo come `~/.claude/settings.json`. È JSON valido senza commenti, quindi puoi incollarlo così com'è ed eliminare le chiavi che non desideri.

29 ```json ~/.claude/settings.json theme={null}

30 {

31 "model": "claude-sonnet-5",

32 "effortLevel": "xhigh",

33 "editorMode": "vim",

34 "theme": "light-daltonized",

35 "statusLine": {

36 "type": "command",

37 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",

38 "padding": 2

39 },

40 "spinnerTipsEnabled": false,

41 "preferredNotifChannel": "terminal_bell",

42 "permissions": {

43 "allow": [

44 "Bash(git diff *)",

45 "Read(~/.zshrc)"

46 ]

47 },

48 "autoUpdatesChannel": "stable",

49 "cleanupPeriodDays": 20

50 }

51 ```

52 </Tab>

54 <Tab title="What each key does">

55 Lo stesso file con un commento sopra ogni chiave. Leggilo qui; copia dall'altra scheda, perché Claude Code non accetta commenti in un file di impostazioni.

57 ```jsonc ~/.claude/settings.json theme={null}

58 {

59 // Inizia ogni sessione su Sonnet 5

60 "model": "claude-sonnet-5",

61 // Ragiona più profondamente del livello alto predefinito su modelli senza un livello salvato; /effort salva un livello per modello, e --effort ne imposta uno per una singola sessione

62 "effortLevel": "xhigh",

63 // Scorciatoie da tastiera Vim nel prompt

64 "editorMode": "vim",

65 // Il tema chiaro adatto ai daltonici

66 "theme": "light-daltonized",

67 // Una riga di stato sotto il prompt: nome del modello e contesto utilizzato

68 "statusLine": {

69 "type": "command",

70 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",

71 "padding": 2

72 },

73 // Nascondi i suggerimenti che ruotano sotto lo spinner

74 "spinnerTipsEnabled": false,

75 // Suona il campanello del terminale per le notifiche, come un'attività completata o un prompt di autorizzazione in attesa

76 "preferredNotifChannel": "terminal_bell",

77 // Consenti a Claude Code di eseguire git diff e leggere il tuo .zshrc senza chiedere

78 "permissions": {

79 "allow": [

80 "Bash(git diff *)",

81 "Read(~/.zshrc)"

82 ]

83 },

84 // Accetta gli aggiornamenti dal canale stabile

85 "autoUpdatesChannel": "stable",

86 // Elimina i trascritti delle sessioni e altri dati locali delle sessioni più vecchi di 20 giorni

87 "cleanupPeriodDays": 20

88 }

89 ```

90 </Tab>

91</Tabs>

93<h2 id="a-teams-shared-settings">

94 Le impostazioni condivise di un team

95</h2>

97Le impostazioni condivise di un team, sottoposte a commit nel repository in modo che tutti coloro che lo clonano ottengano le stesse autorizzazioni, hook, telemetria e marketplace di plugin. Salva un file come questo in `.claude/settings.json` nella parte superiore del repository. Cose da sapere prima di sottoporre a commit uno:

99* **Le sessioni cloud lo leggono anche.** Una [sessione cloud](/docs/it/settings#settings-in-cloud-sessions) su Claude Code sul web inizia da un clone del repository, quindi il file sottoposto a commit si applica anche lì.

100* **Le regole di autorizzazione attendono la fiducia.** Le regole di autorizzazione e le voci `extraKnownMarketplaces` hanno effetto dopo che ogni persona [si fida di questa cartella stessa](/docs/it/permissions#project-allow-rules-and-workspace-trust), non solo di una cartella padre; le regole di negazione e richiesta si applicano in ogni sessione, fidata o meno.

101* **L'hook è uno script nel repo.** L'hook di questo file esegue `.claude/hooks/block-rm.sh`; [How a hook resolves](/docs/it/hooks#how-a-hook-resolves) illustra come scriverlo.

102* **Le regole corrispondono al comando e al percorso come scritti.** `Bash(git push *)` non corrisponde a [`git -C . push`](/docs/it/permissions#bash-rule-limits). `Read(./.env)` da solo interrompe i file tool e i comandi che nominano il file, come `cat .env`, ma non [`grep -r` eseguito sulla directory](/docs/it/permissions#read-and-edit); il blocco `sandbox` in questo file colma questa lacuna, perché la sandbox [aggiunge i tuoi percorsi di negazione `Read`](/docs/it/settings-reference#sandbox-filesystem-denyread) a ciò che ogni comando in sandbox non può leggere.

103

104<Tabs>

105 <Tab title="Copyable settings file">

106 Salva questo come `.claude/settings.json` nella parte superiore del repository e sottoponi a commit. È JSON valido senza commenti, quindi puoi incollarlo così com'è ed eliminare le chiavi che non desideri.

107

108 ```json .claude/settings.json theme={null}

109 {

110 "permissions": {

111 "allow": [

112 "Bash(npm run *)"

113 ],

114 "ask": [

115 "Bash(git push *)"

116 ],

117 "deny": [

118 "Read(./.env)",

119 "Read(./.env.*)",

120 "Read(./secrets/**)"

121 ]

122 },

123 "env": {

124 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

125 "OTEL_METRICS_EXPORTER": "otlp",

126 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

127 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"

128 },

129 "hooks": {

130 "PreToolUse": [

131 {

132 "matcher": "Bash",

133 "hooks": [

134 {

135 "type": "command",

136 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"

137 }

138 ]

139 }

140 ]

141 },

142 "extraKnownMarketplaces": {

143 "acme-tools": {

144 "source": {

145 "source": "github",

146 "repo": "acme-corp/claude-plugins"

147 }

148 }

149 },

150 "enabledPlugins": {

151 "code-formatter@acme-tools": true

152 },

153 "sandbox": {

154 "enabled": true,

155 "filesystem": {

156 "allowWrite": [

157 "/tmp/build"

158 ]

159 },

160 "network": {

161 "allowedDomains": [

162 "registry.npmjs.org",

163 "*.example.com"

164 ]

165 }

166 },

167 "plansDirectory": "./plans"

168 }

169 ```

170 </Tab>

171

172 <Tab title="What each key does">

173 Lo stesso file con un commento sopra ogni chiave. Leggilo qui; copia dall'altra scheda, perché Claude Code non accetta commenti in un file di impostazioni.

174

175 ```jsonc .claude/settings.json theme={null}

176 {

177 "permissions": {

178 // Esegui gli script npm senza chiedere

179 "allow": [

180 "Bash(npm run *)"

181 ],

182 // Conferma prima dei comandi git push

183 "ask": [

184 "Bash(git push *)"

185 ],

186 // Nega le letture dei file env e della cartella dei segreti dai file tool e dai comandi che leggono i file

187 "deny": [

188 "Read(./.env)",

189 "Read(./.env.*)",

190 "Read(./secrets/**)"

191 ]

192 },

193 // Invia metriche OpenTelemetry al collector del team su gRPC; sostituisci l'endpoint con l'URL del tuo collector

194 "env": {

195 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

196 "OTEL_METRICS_EXPORTER": "otlp",

197 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

198 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"

199 },

200 // Prima di ogni comando Bash, esegui uno script nel repo che può bloccarlo

201 "hooks": {

202 "PreToolUse": [

203 {

204 "matcher": "Bash",

205 "hooks": [

206 {

207 "type": "command",

208 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"

209 }

210 ]

211 }

212 ]

213 },

214 // Registra il marketplace di plugin del team su ogni clone

215 "extraKnownMarketplaces": {

216 "acme-tools": {

217 "source": {

218 "source": "github",

219 "repo": "acme-corp/claude-plugins"

220 }

221 }

222 },

223 // Abilita un plugin da quel marketplace; un plugin da una fonte esterna come un repository GitHub richiede comunque che ogni persona lo installi una volta

224 "enabledPlugins": {

225 "code-formatter@acme-tools": true

226 },

227 // Comandi sandbox: directory di build scrivibile; npm e example.com pre-autorizzati, altri host ancora richiedono conferma

228 "sandbox": {

229 "enabled": true,

230 "filesystem": {

231 "allowWrite": [

232 "/tmp/build"

233 ]

234 },

235 "network": {

236 "allowedDomains": [

237 "registry.npmjs.org",

238 "*.example.com"

239 ]

240 }

241 },

242 // Mantieni i file di piano all'interno del repo

243 "plansDirectory": "./plans"

244 }

245 ```

246 </Tab>

247</Tabs>

248

249<h2 id="an-organizations-managed-settings">

250 Le impostazioni gestite di un'organizzazione

251</h2>

252

253Un file `managed-settings.json` che mostra la forma delle chiavi gestite, con un valore plausibile per ognuna. Non è una politica consigliata: scegli le chiavi che corrispondono ai tuoi requisiti e imposta i tuoi valori. L'esempio imposta queste chiavi:

254

255* `forceLoginMethod` e `forceLoginOrgUUID` fissano il metodo di accesso e l'organizzazione

256* `availableModels` e `enforceAvailableModels` limitano quali modelli possono utilizzare le sessioni

257* `permissions.deny` blocca due letture di file e comandi `curl` [come Claude li scrive](/docs/it/permissions#bash-rule-limits), e `disableBypassPermissionsMode` rimuove la modalità di autorizzazione di bypass

258* [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) e [`allowManagedMcpServersOnly`](/docs/it/settings-reference#allowmanagedmcpserversonly) rendono le liste di autorizzazione di autorizzazione e MCP gestite le uniche che si applicano

259* `allowedMcpServers` fissa il server MCP per URL

260* `strictKnownMarketplaces` consente un marketplace di plugin

261* `sandbox` esegue il sandboxing dei comandi con una lista di autorizzazione di rete fissa e nessun retry non sandboxato

262* `requiredMinimumVersion` imposta una versione minima di Claude Code

263* `cleanupPeriodDays` accorcia la conservazione dei trascritti delle sessioni e altri dati locali a sette giorni

264* `companyAnnouncements` mostra un messaggio all'avvio

265

266Gli amministratori distribuiscono un file come questo come `managed-settings.json`, o lo stesso JSON tramite MDM o [impostazioni gestite dal server](/docs/it/server-managed-settings). Un file distribuito si applica a ogni macchina o account che raggiunge. Per dare a un gruppo valori diversi, distribuisci un file o profilo diverso a quel gruppo, poiché [le impostazioni gestite dal server non supportano ancora la politica per gruppo](/docs/it/server-managed-settings#current-limitations).

267

268<Tabs>

269 <Tab title="Copyable settings file">

270 Distribuisci questo come `managed-settings.json`, o lo stesso JSON tramite MDM o la console claude.ai. È JSON valido senza commenti; sostituisci l'UUID dell'organizzazione di esempio, l'URL del server e il marketplace con i tuoi e elimina le chiavi che non desideri.

271

272 ```json managed-settings.json theme={null}

273 {

274 "forceLoginMethod": "claudeai",

275 "forceLoginOrgUUID": [

276 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

277 ],

278 "availableModels": [

279 "opus",

280 "sonnet"

281 ],

282 "enforceAvailableModels": true,

283 "permissions": {

284 "deny": [

285 "Bash(curl *)",

286 "Read(./.env)",

287 "Read(./secrets/**)"

288 ],

289 "disableBypassPermissionsMode": "disable"

290 },

291 "allowManagedPermissionRulesOnly": true,

292 "allowedMcpServers": [

293 {

294 "serverUrl": "https://api.githubcopilot.com/*"

295 }

296 ],

297 "allowManagedMcpServersOnly": true,

298 "strictKnownMarketplaces": [

299 {

300 "source": "github",

301 "repo": "acme-corp/approved-plugins"

302 }

303 ],

304 "sandbox": {

305 "enabled": true,

306 "failIfUnavailable": true,

307 "allowUnsandboxedCommands": false,

308 "network": {

309 "allowedDomains": [

310 "registry.npmjs.org",

311 "github.com"

312 ],

313 "allowManagedDomainsOnly": true

314 }

315 },

316 "requiredMinimumVersion": "2.1.150",

317 "cleanupPeriodDays": 7,

318 "companyAnnouncements": [

319 "Welcome to Acme Corp! Review our code guidelines at docs.example.com"

320 ]

321 }

322 ```

323 </Tab>

324

325 <Tab title="What each key does">

326 Lo stesso file con un commento sopra ogni chiave. Leggilo qui; copia dall'altra scheda, perché Claude Code non accetta commenti in un file di impostazioni.

327

328 ```jsonc managed-settings.json theme={null}

329 {

330 // Solo accessi claude.ai, e solo in questa organizzazione

331 "forceLoginMethod": "claudeai",

332 "forceLoginOrgUUID": [

333 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

334 ],

335 // Solo modelli Opus e Sonnet; con enforceAvailableModels, l'opzione Predefinito obbedisce anche alla lista

336 "availableModels": [

337 "opus",

338 "sonnet"

339 ],

340 "enforceAvailableModels": true,

341 "permissions": {

342 // Blocca curl, il file .env del progetto e la sua cartella dei segreti su ogni macchina

343 "deny": [

344 "Bash(curl *)",

345 "Read(./.env)",

346 "Read(./secrets/**)"

347 ],

348 // Rimuovi la modalità di bypass delle autorizzazioni da ogni sessione

349 "disableBypassPermissionsMode": "disable"

350 },

351 // Ignora le regole di autorizzazione dalle impostazioni utente, progetto e locali

352 "allowManagedPermissionRulesOnly": true,

353 // Solo il server MCP GitHub, abbinato per URL piuttosto che per nome, poiché un utente può

354 // nominare qualsiasi server "github". I server aggiunti dall'utente che non corrispondono non si caricano, incluso

355 // ogni server stdio quando la lista ha solo voci URL. La chiave allowManagedMcpServersOnly

356 // sotto rende questa lista gestita l'unica lista di autorizzazione che si applica

357 "allowedMcpServers": [

358 {

359 "serverUrl": "https://api.githubcopilot.com/*"

360 }

361 ],

362 "allowManagedMcpServersOnly": true,

363 // I plugin possono provenire solo da questo marketplace

364 "strictKnownMarketplaces": [

365 {

366 "source": "github",

367 "repo": "acme-corp/approved-plugins"

368 }

369 ],

370 // Esegui il sandboxing di ogni comando che Claude esegue, rifiuta di avviare se il sandbox non può essere

371 // configurato, e non consentire mai a un comando bloccato di riprovare al di fuori del sandbox; la rete

372 // limitata a npm e GitHub, e gli utenti non possono aggiungere domini

373 "sandbox": {

374 "enabled": true,

375 "failIfUnavailable": true,

376 "allowUnsandboxedCommands": false,

377 "network": {

378 "allowedDomains": [

379 "registry.npmjs.org",

380 "github.com"

381 ],

382 "allowManagedDomainsOnly": true

383 }

384 },

385 // Rifiuta di avviare su versioni più vecchie di 2.1.150

386 "requiredMinimumVersion": "2.1.150",

387 // Elimina i trascritti delle sessioni e altri dati locali delle sessioni dopo 7 giorni

388 "cleanupPeriodDays": 7,

389 // Un messaggio che ogni utente vede all'avvio

390 "companyAnnouncements": [

391 "Welcome to Acme Corp! Review our code guidelines at docs.example.com"

392 ]

393 }

394 ```

395 </Tab>

396</Tabs>

settings-reference.md +6509 −0 created

Details

Diff Too Large View Raw

setup.md +12 −10

Details

41 Siete nuovi al terminale? Consultate la [guida del terminale](/docs/it/terminal-guide) per istruzioni passo dopo passo.41 Siete nuovi al terminale? Consultate la [guida del terminale](/docs/it/terminal-guide) per istruzioni passo dopo passo.

42</Tip>42</Tip>

43 43

~~44To install Claude Code, use one of the following methods:~~44Per installare Claude Code, utilizza uno dei seguenti metodi:

45 45

46<Tabs>46<Tabs>

~~47 <Tab title="Native Install (Recommended)">~~47 <Tab title="Installazione nativa (consigliata)">

48 **macOS, Linux, WSL:**48 **macOS, Linux, WSL:**

49 49

50 ```bash theme={null}50 ```bash theme={null}

63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

64 ```64 ```

65 65

66 If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.66 Se vedi `The token '&&' is not a valid statement separator`, sei in PowerShell, non in CMD. Se vedi `'irm' is not recognized as an internal or external command`, sei in CMD, non in PowerShell. Il tuo prompt mostra `PS C:\` quando sei in PowerShell e `C:\` senza il `PS` quando sei in CMD.

67 67

68 If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.68 Se il comando di installazione non riesce con `syntax error near unexpected token '<'`, un `403`, o un altro errore curl, consulta [Troubleshoot installation](/docs/it/troubleshoot-install#find-your-error) per abbinare l'errore a una soluzione e per metodi di installazione alternativi.

69 69

70 [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.70 [Git for Windows](https://git-scm.com/downloads/win) è consigliato su Windows nativo in modo che Claude Code possa utilizzare lo strumento Bash. Se Git for Windows non è installato, Claude Code utilizza PowerShell come strumento shell. Le configurazioni WSL non necessitano di Git for Windows.

71 71

72 <Info>72 <Info>

~~73 Native installations automatically update in the background to keep you on the latest version.~~73 Le installazioni native si aggiornano automaticamente in background per mantenerti sulla versione più recente.

74 </Info>74 </Info>

75 </Tab>75 </Tab>

76 76

79 brew install --cask claude-code79 brew install --cask claude-code

80 ```80 ```

81 81

82 Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.82 Homebrew offre due cask. `claude-code` traccia il canale di rilascio stabile, che in genere è circa una settimana indietro e salta i rilasci con regressioni importanti. `claude-code@latest` traccia il canale più recente e riceve nuove versioni non appena vengono rilasciate.

83 83

84 <Info>84 <Info>

85 Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.85 Le installazioni Homebrew non si aggiornano automaticamente. Esegui `brew upgrade claude-code` o `brew upgrade claude-code@latest`, a seconda di quale cask hai installato, per ottenere le funzionalità più recenti e le correzioni di sicurezza.

86 </Info>86 </Info>

87 </Tab>87 </Tab>

88 88

92 ```92 ```

93 93

94 <Info>94 <Info>

~~95 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.~~95 Le installazioni WinGet non si aggiornano automaticamente. Esegui `winget upgrade Anthropic.ClaudeCode` periodicamente per ottenere le funzionalità più recenti e le correzioni di sicurezza.

96 </Info>96 </Info>

97 </Tab>97 </Tab>

98</Tabs>98</Tabs>

99 99

100You can also install with [apt, dnf, or apk](/docs/en/setup#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.100Puoi anche installare con [apt, dnf, o apk](/docs/it/setup#install-with-linux-package-managers) su Debian, Fedora, RHEL e Alpine.

101 101

102Dopo il completamento dell'installazione, aprite un terminale nel progetto su cui desiderate lavorare e avviate Claude Code:102Dopo il completamento dell'installazione, aprite un terminale nel progetto su cui desiderate lavorare e avviate Claude Code:

103 103

296}296}

297```297```

298 298

299Su un'installazione nativa o npm, confermate che la modifica ha avuto effetto eseguendo `claude doctor` e verificando che la riga `Auto-updates` mostri `disabled (set by env: DISABLE_AUTOUPDATER)` invece di `enabled`.

300

299`DISABLE_AUTOUPDATER` arresta solo il controllo in background; `claude update` e `claude install` continuano a funzionare. Per bloccare tutti i percorsi di aggiornamento, inclusi gli aggiornamenti manuali, impostate invece [`DISABLE_UPDATES`](/docs/it/env-vars). Utilizzate questo quando distribuite Claude Code attraverso i vostri canali e avete bisogno che gli utenti rimangano sulla versione che fornite.301`DISABLE_AUTOUPDATER` arresta solo il controllo in background; `claude update` e `claude install` continuano a funzionare. Per bloccare tutti i percorsi di aggiornamento, inclusi gli aggiornamenti manuali, impostate invece [`DISABLE_UPDATES`](/docs/it/env-vars). Utilizzate questo quando distribuite Claude Code attraverso i vostri canali e avete bisogno che gli utenti rimangano sulla versione che fornite.

300 302

301<h3 id="update-manually">303<h3 id="update-manually">

skills.md +26 −17

Details

28 28

29La maggior parte degli skill raggruppati sono disponibili in ogni sessione. Alcuni dipendono da una funzionalità specifica: `/workflow-authoring`, ad esempio, è disponibile solo quando i [dynamic workflows](/docs/it/workflows) sono abilitati.29La maggior parte degli skill raggruppati sono disponibili in ogni sessione. Alcuni dipendono da una funzionalità specifica: `/workflow-authoring`, ad esempio, è disponibile solo quando i [dynamic workflows](/docs/it/workflows) sono abilitati.

30 30

~~31Per disattivare gli skill raggruppati, utilizzate l'impostazione [`disableBundledSkills`](/docs/it/settings-reference#disablebundledskills), che disabilita ogni skill raggruppato eccetto `/doctor`.~~31Per disattivare gli skill raggruppati, utilizzate l'impostazione [`disableBundledSkills`](/docs/it/settings-reference#disablebundledskills).

32 32

33<Note>33<Note>

34 Il controllo di configurazione [`/doctor`](/docs/it/commands#all-commands) rimane digitabile quando `disableBundledSkills` è attivo, in Claude Code v2.1.205 e successivi. Per nasconderlo, impostate la variabile d'ambiente `DISABLE_DOCTOR_COMMAND` o una voce [`skillOverrides`](#override-skill-visibility-from-settings) di `"doctor": "off"`. Prima della v2.1.205, `/doctor` era un comando built-in piuttosto che uno skill raggruppato.34 Il controllo di configurazione [`/doctor`](/docs/it/commands#all-commands) rimane digitabile quando `disableBundledSkills` è attivo, in Claude Code v2.1.205 e successivi. Per nasconderlo, impostate la variabile d'ambiente `DISABLE_DOCTOR_COMMAND` o una voce [`skillOverrides`](#override-skill-visibility-from-settings) di `"doctor": "off"`. Prima della v2.1.205, `/doctor` era un comando built-in piuttosto che uno skill raggruppato.

136 136

137* **Cartelle collegate tramite symlink**: una voce `<skill-name>` nella posizione enterprise, personale o di progetto può essere un symlink a una directory altrove su disco. Claude Code legge `SKILL.md` dal target e carica la skill una sola volta anche se più posizioni puntano allo stesso target. Le skills dei plugin [gestiscono i symlink diversamente](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks).137* **Cartelle collegate tramite symlink**: una voce `<skill-name>` nella posizione enterprise, personale o di progetto può essere un symlink a una directory altrove su disco. Claude Code legge `SKILL.md` dal target e carica la skill una sola volta anche se più posizioni puntano allo stesso target. Le skills dei plugin [gestiscono i symlink diversamente](/docs/it/plugins-reference#share-files-within-a-marketplace-with-symlinks).

138* **Nome riservato**: non nominare una cartella di skill `synced`, in nessuna capitalizzazione. Claude Code usa `~/.claude/skills/synced/` per [skills scaricate da claude.ai](#where-synced-skills-load) e salta una skill che crei con quel nome nelle posizioni enterprise, personale e di progetto.138* **Nome riservato**: non nominare una cartella di skill `synced`, in nessuna capitalizzazione. Claude Code usa `~/.claude/skills/synced/` per [skills scaricate da claude.ai](#where-synced-skills-load) e salta una skill che crei con quel nome nelle posizioni enterprise, personale e di progetto.

139* **File di comando**: un file Markdown in `.claude/commands/` è il formato più vecchio e funziona ancora. Supporta lo stesso [frontmatter](#frontmatter-reference) eccetto `name` e `paths`, e lo invochi per il nome del file. Preferisci una skill per il nuovo lavoro, poiché le skills supportano anche [file di supporto](#add-supporting-files).139* **File di comando**: un file Markdown in `.claude/commands/` è il formato più vecchio e funziona ancora. Supporta lo stesso [frontmatter](#frontmatter-reference) eccetto `name` e `paths`. Per trovare il nome che digiti per invocarlo, vedi [Come una skill ottiene il suo nome di comando](#how-a-skill-gets-its-command-name). Preferisci una skill per il nuovo lavoro, poiché le skills supportano anche [file di supporto](#add-supporting-files).

140* **Cartella di skill come plugin**: aggiungi un `.claude-plugin/plugin.json` a una cartella di skill e si carica come [plugin](/docs/it/plugins-reference#skills-directory-plugins) denominato `<name>@skills-dir`, in modo che possa raggruppare agenti, hooks e server MCP. In un `.claude/skills/` di un progetto, questo richiede di accettare prima la finestra di dialogo di fiducia dell'area di lavoro.140* **Cartella di skill come plugin**: aggiungi un `.claude-plugin/plugin.json` a una cartella di skill e si carica come [plugin](/docs/it/plugins-reference#skills-directory-plugins) denominato `<name>@skills-dir`, in modo che possa raggruppare agenti, hooks e server MCP. In un `.claude/skills/` di un progetto, questo richiede di accettare prima la finestra di dialogo di fiducia dell'area di lavoro.

141 141

142<h3 id="discovery-from-parent-and-nested-directories">142<h3 id="discovery-from-parent-and-nested-directories">

234 234

235Claude Code etichetta le skills sincronizzate in modo che tu possa dire da dove provengono. Il menu `/skills` e `/context` raggruppano le skills sincronizzate sotto `claude.ai sync`, e il menu del comando `/` le contrassegna come provenienti da claude.ai.235Claude Code etichetta le skills sincronizzate in modo che tu possa dire da dove provengono. Il menu `/skills` e `/context` raggruppano le skills sincronizzate sotto `claude.ai sync`, e il menu del comando `/` le contrassegna come provenienti da claude.ai.

236 236

237Quando confronta i nomi, Claude Code ignora maiuscole/minuscole, spaziatura e caratteri invisibili, e tratta forme di compatibilità come lettere a larghezza intera e varianti di trattini come i loro equivalenti semplici, quindi una `Commit` sincronizzata non può caricarsi accanto a una `commit` locale. Un nome che differisce solo per una lettera simile da un altro alfabeto conta come un nome diverso, e l'etichetta `claude.ai sync` è come distingui i due.237Quando confronta i nomi, Claude Code ignora maiuscole/minuscole, spaziatura e caratteri invisibili, e tratta forme di compatibilità come lettere a larghezza intera e varianti di trattini come i loro equivalenti semplici, quindi una `Commit` sincronizzata non può caricarsi accanto a una `commit` locale. Un nome che differisce solo per una lettera simile da un altro alfabeto conta come un nome diverso, e l'etichetta `claude.ai sync` è come distingui i due. Questi controlli e etichette richiedono Claude Code v2.1.228 o successivo.

238 238

239<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">239<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">

240 Come Claude Code gestisce il frontmatter di una skill sincronizzata240 Come Claude Code gestisce il frontmatter di una skill sincronizzata

243Claude Code applica due regole al frontmatter di una skill sincronizzata:243Claude Code applica due regole al frontmatter di una skill sincronizzata:

244 244

245* Claude Code onora il frontmatter in ogni tipo di sessione, quindi una concessione `allowed-tools` passa attraverso il normale [flusso di permessi](/docs/it/permissions).245* Claude Code onora il frontmatter in ogni tipo di sessione, quindi una concessione `allowed-tools` passa attraverso il normale [flusso di permessi](/docs/it/permissions).

246* Claude Code igienizza il testo di visualizzazione che la skill fornisce, come la sua descrizione. Rimuove i caratteri di controllo, e nel testo che raggiunge Claude, come la descrizione, sfugge anche le parentesi angolari in modo che il testo non possa imitare la formattazione interna di Claude Code.246* Claude Code igienizza il testo di visualizzazione che la skill fornisce, come la sua descrizione. Rimuove i caratteri di controllo, e nel testo che raggiunge Claude, come la descrizione, sfugge anche le parentesi angolari in modo che il testo non possa imitare la formattazione interna di Claude Code. Questa igienizzazione richiede Claude Code v2.1.228 o successivo.

247 247

248<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">248<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">

249 Come Claude Code gestisce il corpo di una skill sincronizzata249 Come Claude Code gestisce il corpo di una skill sincronizzata

253 253

254* In una cloud session, il corpo mantiene il comportamento che una skill locale ha, perché la sessione viene eseguita in un contenitore isolato.254* In una cloud session, il corpo mantiene il comportamento che una skill locale ha, perché la sessione viene eseguita in un contenitore isolato.

255* In una sessione Cowork sul tuo desktop, il corpo mantiene il comportamento che una skill locale ha, eccetto che Claude Code sostituisce ogni riga di comando `!` con il placeholder [`disableSkillShellExecution`](#inject-dynamic-context), come fa per ogni skill che fornisci lì.255* In una sessione Cowork sul tuo desktop, il corpo mantiene il comportamento che una skill locale ha, eccetto che Claude Code sostituisce ogni riga di comando `!` con il placeholder [`disableSkillShellExecution`](#inject-dynamic-context), come fa per ogni skill che fornisci lì.

256* In qualsiasi altra sessione sulla tua macchina, Claude Code non esegue comandi [`!`](#inject-dynamic-context), non allega i file che i riferimenti `@` nominano come fa per una skill locale, e non sostituisce i placeholder `${CLAUDE_PROJECT_DIR}` e `${CLAUDE_SESSION_ID}`, quindi i riferimenti `@` e entrambi i placeholder raggiungono Claude come testo letterale. Una riga di comando `!` raggiunge Claude come testo letterale anche, o come quel placeholder quando `disableSkillShellExecution` è attivo.256* In qualsiasi altra sessione sulla tua macchina, Claude Code non esegue comandi [`!`](#inject-dynamic-context), non allega i file che i riferimenti `@` nominano come fa per una skill locale, e non sostituisce i placeholder `${CLAUDE_PROJECT_DIR}` e `${CLAUDE_SESSION_ID}`, quindi i riferimenti `@` e entrambi i placeholder raggiungono Claude come testo letterale. Una riga di comando `!` raggiunge Claude come testo letterale anche, o come quel placeholder quando `disableSkillShellExecution` è attivo. Questa gestione richiede Claude Code v2.1.228 o successivo.

257 257

258<h3 id="live-change-detection">258<h3 id="live-change-detection">

259 Modifica una skill durante una sessione259 Modifica una skill durante una sessione

271 271

272* **Skill personale o di progetto**: elimina la directory della skill, `~/.claude/skills/<skill-name>/` o `.claude/skills/<skill-name>/`. Claude Code [la elimina da `/skills` nella sessione corrente](#live-change-detection); il contenuto che Claude Code ha già caricato da essa segue il [ciclo di vita del contenuto della skill](#skill-content-lifecycle).272* **Skill personale o di progetto**: elimina la directory della skill, `~/.claude/skills/<skill-name>/` o `.claude/skills/<skill-name>/`. Claude Code [la elimina da `/skills` nella sessione corrente](#live-change-detection); il contenuto che Claude Code ha già caricato da essa segue il [ciclo di vita del contenuto della skill](#skill-content-lifecycle).

273* **Skill enterprise**: un amministratore elimina la directory della skill da `.claude/skills/` all'interno della [directory delle impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms), ad esempio `/etc/claude-code/.claude/skills/<skill-name>/` su Linux.273* **Skill enterprise**: un amministratore elimina la directory della skill da `.claude/skills/` all'interno della [directory delle impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms), ad esempio `/etc/claude-code/.claude/skills/<skill-name>/` su Linux.

274* **Skill di plugin**: disabilita o disinstalla il plugin che la fornisce, dal menu `/plugin` o con `/plugin uninstall <plugin-name>@<marketplace-name>`. Claude Code scarica le skills del plugin dopo aver eseguito `/reload-plugins` o riavviato; vedi [Applica i cambiamenti dei plugin senza riavviare](/docs/it/discover-plugins#apply-plugin-changes-without-restarting).274* **Skill di plugin**: disabilita o disinstalla il plugin che la fornisce, dal menu `/plugin` o con `/plugin uninstall <plugin-name>@<marketplace-name>`. Claude Code scarica le skills del plugin quando [il cambiamento si applica](/docs/it/discover-plugins#apply-plugin-changes-without-restarting) o quando riavvii.

275* **Skill sincronizzata da claude.ai**: disattiva la skill per il tuo account claude.ai, nello stesso luogo in cui l'hai [abilitata](#skills-in-cowork-and-cloud-sessions). Claude Code la rimuove da `~/.claude/skills/synced/` la prossima volta che [sincronizza le tue skills](#where-synced-skills-load). Se elimini la directory manualmente, la prossima sincronizzazione la scarica di nuovo mentre la skill rimane abilitata su claude.ai.275* **Skill sincronizzata da claude.ai**: disattiva la skill per il tuo account claude.ai, nello stesso luogo in cui l'hai [abilitata](#skills-in-cowork-and-cloud-sessions). Claude Code la rimuove da `~/.claude/skills/synced/` la prossima volta che [sincronizza le tue skills](#where-synced-skills-load). Se elimini la directory manualmente, la prossima sincronizzazione la scarica di nuovo mentre la skill rimane abilitata su claude.ai.

276* **Skill raggruppata**: imposta [`disableBundledSkills`](#bundled-skills) su `true` per disattivare ogni skill raggruppata eccetto `/doctor`, o imposta una skill su `"off"` in [`skillOverrides`](#override-skill-visibility-from-settings) per nasconderla.276* **Skill raggruppata**: imposta [`disableBundledSkills`](#bundled-skills) su `true` per disattivare le skills raggruppate, o imposta una skill su `"off"` in [`skillOverrides`](#override-skill-visibility-from-settings) per nasconderla.

277 277

278Per mantenere una skill personale o di progetto ma impedire a Claude di invocarla da solo, imposta [`disable-model-invocation: true`](#control-who-invokes-a-skill) nel suo frontmatter, o `"user-invocable-only"` in [`skillOverrides`](#override-skill-visibility-from-settings) quando non vuoi modificare il file.278Per mantenere una skill personale o di progetto ma impedire a Claude di invocarla da solo, imposta [`disable-model-invocation: true`](#control-who-invokes-a-skill) nel suo frontmatter, o `"user-invocable-only"` in [`skillOverrides`](#override-skill-visibility-from-settings) quando non vuoi modificare il file.

279 279

348| :------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |348| :------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

349| `name` | No | Nome visualizzato mostrato negli elenchi di skills. Predefinito al nome della directory. Vedi [Come una skill ottiene il suo nome di comando](#how-a-skill-gets-its-command-name) per come il campo interagisce con il nome che digiti per invocare la skill. |349| `name` | No | Nome visualizzato mostrato negli elenchi di skills. Predefinito al nome della directory. Vedi [Come una skill ottiene il suo nome di comando](#how-a-skill-gets-its-command-name) per come il campo interagisce con il nome che digiti per invocare la skill. |

350| `description` | Consigliato | Cosa fa la skill e quando usarla. Claude usa questo per decidere quando applicare la skill. Se omesso, usa il primo paragrafo del contenuto markdown. Metti il caso d'uso chiave per primo: il testo combinato `description` e `when_to_use` viene troncato a 1.536 caratteri nell'elenco delle skills per ridurre l'utilizzo del contesto. |350| `description` | Consigliato | Cosa fa la skill e quando usarla. Claude usa questo per decidere quando applicare la skill. Se omesso, usa il primo paragrafo non vuoto del contenuto markdown. Metti il caso d'uso chiave per primo: il testo combinato `description` e `when_to_use` viene troncato a 1.536 caratteri nell'elenco delle skills per ridurre l'utilizzo del contesto. |

351| `when_to_use` | No | Contesto aggiuntivo per quando Claude dovrebbe invocare la skill, come frasi trigger o richieste di esempio. Aggiunto a `description` nell'elenco delle skills e conta verso il limite di 1.536 caratteri. |351| `when_to_use` | No | Contesto aggiuntivo per quando Claude dovrebbe invocare la skill, come frasi trigger o richieste di esempio. Aggiunto a `description` nell'elenco delle skills e conta verso il limite di 1.536 caratteri. |

352| `argument-hint` | No | Suggerimento mostrato durante l'autocompletamento per indicare gli argomenti previsti. Esempio: `[issue-number]` o `[filename] [format]`. |352| `argument-hint` | No | Suggerimento mostrato durante l'autocompletamento per indicare gli argomenti previsti. Esempio: `[issue-number]` o `[filename] [format]`. |

353| `arguments` | No | Argomenti posizionali denominati per la [sostituzione `$name`](#available-string-substitutions) nel contenuto della skill. Accetta una stringa separata da spazi o un elenco YAML. I nomi si mappano alle posizioni degli argomenti in ordine. |353| `arguments` | No | Argomenti posizionali denominati per la [sostituzione `$name`](#available-string-substitutions) nel contenuto della skill. Accetta una stringa separata da spazi o un elenco YAML. I nomi si mappano alle posizioni degli argomenti in ordine. |

397La tabella seguente mostra da dove proviene il nome del comando per ogni layout:397La tabella seguente mostra da dove proviene il nome del comando per ogni layout:

398 398

400| :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |400| :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |

402| Directory [nidificata](#where-skills-live) `.claude/skills/`, quando il nome si scontra con un'altra skill | Percorso della sottodirectory relativo alla directory di lavoro, quindi il nome della directory skill | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |402| Directory [nidificata](#where-skills-live) `.claude/skills/`, quando il nome si scontra con un'altra skill | Percorso della sottodirectory relativo alla directory di lavoro, quindi il nome della directory skill | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |

404| File in una sottodirectory di `.claude/commands/` | Percorso della sottodirectory relativo a `commands/` con ogni `/` sostituito da `:`, quindi il nome del file senza estensione | `.claude/commands/frontend/component.md` → `/frontend:component` |

404| Sottodirectory `skills/` del plugin | Frontmatter `name` o il nome della directory, con namespace dal plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, o `/my-plugin:fancy` con `name: fancy` |405| Sottodirectory `skills/` del plugin | Frontmatter `name` o il nome della directory, con namespace dal plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, o `/my-plugin:fancy` con `name: fancy` |

405| `SKILL.md` radice del plugin | Frontmatter `name`, con il nome della directory del plugin come fallback | `my-plugin/SKILL.md` con `name: review` → `/my-plugin:review`. Vedi [Regole di comportamento del percorso](/docs/it/plugins-reference#path-behavior-rules) |406| `SKILL.md` radice del plugin | Frontmatter `name`, con il nome della directory del plugin come fallback | `my-plugin/SKILL.md` con `name: review` → `/my-plugin:review`. Vedi [Regole di comportamento del percorso](/docs/it/plugins-reference#path-behavior-rules) |

406 407

630 Iniettare contesto dinamico631 Iniettare contesto dinamico

631</h3>632</h3>

632 633

633La sintassi `` !`<command>` `` esegue comandi shell prima che il contenuto della skill sia inviato a Claude. L'output del comando sostituisce il placeholder, quindi Claude riceve dati effettivi, non il comando stesso. Claude Code non esegue questi comandi sulla tua macchina quando la skill è [sincronizzata dal tuo account claude.ai](#how-claude-code-handles-the-body-of-a-synced-skill).634La sintassi `` !`<command>` `` esegue comandi shell prima che il contenuto della skill sia inviato a Claude. L'output del comando sostituisce il placeholder, quindi Claude riceve dati effettivi, non il comando stesso. Claude Code non esegue questi comandi sulla tua macchina quando la skill è [sincronizzata dal tuo account claude.ai](#how-claude-code-handles-the-body-of-a-synced-skill). Questa restrizione richiede Claude Code v2.1.228 o successivo.

634 635

635Questa skill riassume una pull request recuperando dati PR live con GitHub CLI. I comandi `` !`gh pr diff` `` e altri vengono eseguiti per primi, e il loro output viene inserito nel prompt:636Questa skill riassume una pull request recuperando dati PR live con GitHub CLI. I comandi `` !`gh pr diff` `` e altri vengono eseguiti per primi, e il loro output viene inserito nel prompt:

636 637

668 669

669Per disabilitare questo comportamento per le skill e i comandi personalizzati da fonti utente, progetto, plugin o [additional-directory](#skills-from-additional-directories), imposta `"disableSkillShellExecution": true` in [settings](/docs/it/settings). Ogni comando viene sostituito con `[shell command execution disabled by policy]` invece di essere eseguito. Le skill bundled e gestite non sono interessate. Questa impostazione è più utile in [managed settings](/docs/it/managed-settings), dove gli utenti non possono sovrascriverla.670Per disabilitare questo comportamento per le skill e i comandi personalizzati da fonti utente, progetto, plugin o [additional-directory](#skills-from-additional-directories), imposta `"disableSkillShellExecution": true` in [settings](/docs/it/settings). Ogni comando viene sostituito con `[shell command execution disabled by policy]` invece di essere eseguito. Le skill bundled e gestite non sono interessate. Questa impostazione è più utile in [managed settings](/docs/it/managed-settings), dove gli utenti non possono sovrascriverla.

670 671

671Claude Code non esegue mai questi comandi sulla tua macchina quando appaiono in skill [sincronizzate dal tuo account claude.ai](#how-synced-skills-behave), indipendentemente da questa impostazione. [How Claude Code handles the body of a synced skill](#how-claude-code-handles-the-body-of-a-synced-skill) dice cosa Claude riceve al posto del comando in ogni tipo di sessione.672Claude Code non esegue mai questi comandi sulla tua macchina quando appaiono in skill [sincronizzate dal tuo account claude.ai](#how-synced-skills-behave), indipendentemente da questa impostazione. Questa restrizione richiede Claude Code v2.1.228 o successivo. [How Claude Code handles the body of a synced skill](#how-claude-code-handles-the-body-of-a-synced-skill) dice cosa Claude riceve al posto del comando in ogni tipo di sessione.

672 673

673<Tip>674<Tip>

674 Per richiedere un ragionamento più profondo quando una skill viene eseguita, includi `ultrathink` da qualsiasi parte nel contenuto della skill. Vedi [Use ultrathink for one-off deep reasoning](/docs/it/model-config#use-ultrathink-for-one-off-deep-reasoning).675 Per richiedere un ragionamento più profondo quando una skill viene eseguita, includi `ultrathink` da qualsiasi parte nel contenuto della skill. Vedi [Use ultrathink for one-off deep reasoning](/docs/it/model-config#use-ultrathink-for-one-off-deep-reasoning).

716 Eseguire skill in un subagent717 Eseguire skill in un subagent

717</h3>718</h3>

718 719

719Aggiungi `context: fork` al tuo frontmatter quando vuoi che una skill venga eseguita in isolamento. Il contenuto della skill diventa il prompt che guida il subagent. Non avrà accesso alla cronologia della tua conversazione.720Aggiungi `context: fork` al tuo frontmatter quando vuoi che una skill venga eseguita in isolamento. Claude Code avvia un nuovo subagent del tipo impostato nel campo `agent` e gli fornisce il contenuto della skill come suo prompt. Il subagent non vede la cronologia della tua conversazione, quindi le istruzioni della skill devono stare da sole.

721

722<Note>

723 Nonostante il nome, una skill con `context: fork` non viene eseguita in un [fork della conversazione corrente](/docs/it/sub-agents#fork-the-current-conversation), che darebbe al subagent tutto ciò che hai discusso finora. Quando l'attività dipende da quella cronologia, fai il fork della conversazione invece di usare `context: fork`.

724</Note>

720 725

721Il subagent forkato viene eseguito in [background](/docs/it/sub-agents#run-subagents-in-foreground-or-background): continui a lavorare mentre viene eseguito, e il suo risultato arriva nella tua conversazione quando si completa. Imposta `background: false` nel frontmatter per invece attendere il risultato nel turno che ha invocato la skill. Prima della v2.1.218, le skill forkate bloccavano sempre il turno fino al completamento.726Il subagent forkato viene eseguito in [background](/docs/it/sub-agents#run-subagents-in-foreground-or-background): continui a lavorare mentre viene eseguito, e il suo risultato arriva nella tua conversazione quando si completa. Imposta `background: false` nel frontmatter per invece attendere il risultato nel turno che ha invocato la skill. Prima della v2.1.218, le skill forkate bloccavano sempre il turno fino al completamento.

722 727

866 871

867Il controllo per entrambi è un confronto di base. Raccogli alcuni prompt realistici, esegui ognuno in una sessione nuova con la skill disponibile e di nuovo con essa [disabilitata](#override-skill-visibility-from-settings), e confronta i risultati. Una sessione nuova è importante perché il contesto residuo dalla creazione della skill maschererà le lacune nelle istruzioni scritte.872Il controllo per entrambi è un confronto di base. Raccogli alcuni prompt realistici, esegui ognuno in una sessione nuova con la skill disponibile e di nuovo con essa [disabilitata](#override-skill-visibility-from-settings), e confronta i risultati. Una sessione nuova è importante perché il contesto residuo dalla creazione della skill maschererà le lacune nelle istruzioni scritte.

868 873

874Due strumenti automatizzano quel confronto. Per una skill che viene fornita in un [plugin](/docs/it/plugins), [`claude plugin eval`](/docs/it/plugin-evals) esegue ogni prompt in una sessione isolata con e senza il plugin, la valuta con grader che definisci o che scrive per te, e esce con un codice diverso da zero al di sotto di una soglia in modo da poter controllare il CI su di essa. Per iterare su una singola skill all'interno di una conversazione Claude Code, il plugin skill-creator di seguito esegue un ciclo simile con il suo formato `evals/evals.json`. I due formati non sono intercambiabili.

875

869<h3 id="run-evals-with-skill-creator">876<h3 id="run-evals-with-skill-creator">

870 Esegui eval con skill-creator877 Esegui eval con skill-creator

871</h3>878</h3>

881* `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.888* `Marketplace "claude-plugins-official" not found`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

882* Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.889* Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.

883 890

884Se il riepilogo dell'installazione segnala `Run /reload-plugins to activate.`, esegui quel comando per rendere disponibili le skill del plugin nella sessione corrente. Quindi chiedi a Claude di valutare una skill esistente, ad esempio `evaluate my summarize-changes skill with skill-creator`. Il plugin ti guida attraverso la scrittura dei test case ed esegue il ciclo:891Se il riepilogo dell'installazione segnala `Run /reload-plugins to activate.`, Claude Code esegue quindi quel ricaricamento per te. Se il ricaricamento avverte che il tuo prossimo messaggio rileggerebbe la conversazione, esegui `/reload-plugins --force` per rendere disponibili le skill del plugin nella sessione corrente. Quindi chiedi a Claude di valutare una skill esistente, ad esempio `evaluate my summarize-changes skill with skill-creator`. Il plugin ti guida attraverso la scrittura dei test case ed esegue il ciclo:

885 892

886* **Test cases**: memorizza prompt, file di input e comportamento previsto in `evals/evals.json` all'interno della directory della skill893* **Test cases**: memorizza prompt, file di input e comportamento previsto in `evals/evals.json` all'interno della directory della skill

887* **Isolated runs**: genera un [subagent](/docs/it/sub-agents) per test case in modo che ogni esecuzione inizi con un contesto pulito, e registra il conteggio dei token e la durata894* **Isolated runs**: genera un [subagent](/docs/it/sub-agents) per test case in modo che ogni esecuzione inizi con un contesto pulito, e registra il conteggio dei token e la durata

1101</h2>1108</h2>

1102 1109

1103<h3 id="skill-not-triggering">1110<h3 id="skill-not-triggering">

1104 Skill non si attiva1111 Skill not triggering

1105</h3>1112</h3>

1106 1113

1107Se Claude non utilizza la vostra skill quando previsto:1114Se Claude non utilizza la vostra skill quando previsto:

11113. Provate a riformulare la vostra richiesta per corrispondere più strettamente alla descrizione11183. Provate a riformulare la vostra richiesta per corrispondere più strettamente alla descrizione

11124. Invocatela direttamente con `/skill-name` se la skill è invocabile dall'utente11194. Invocatela direttamente con `/skill-name` se la skill è invocabile dall'utente

1113 1120

1114Se il YAML del frontmatter è malformato, Claude Code carica il corpo della skill con metadati vuoti, quindi `/skill-name` funziona comunque ma Claude non ha alcuna `description` per corrispondere. Eseguite con `--debug` per vedere l'errore di parsing.1121Se il YAML del frontmatter è malformato, Claude Code carica il corpo della skill con metadati vuoti, quindi `/skill-name` funziona comunque ma Claude non può corrispondere alla vostra `description`. Eseguite con `--debug` per vedere l'errore di parsing.

1122

1123Se la skill è fornita in un plugin, potete misurare con quale frequenza si attiva su prompt realistici piuttosto che controllare uno alla volta: scrivete un caso di eval con un [grader `tool_used: Skill`](/docs/it/plugin-evals#create-your-first-eval-suite) ed eseguitelo con `claude plugin eval` dopo ogni modifica della descrizione.

1115 1124

1116Per trovare file `SKILL.md` il cui frontmatter non viene analizzato, eseguite [`claude plugin validate`](/docs/it/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) sulla directory delle skills, ad esempio `claude plugin validate .claude/skills` per le skills del progetto o `claude plugin validate ~/.claude/skills` per le skills personali. Richiede Claude Code v2.1.233 o successivo.1125Per trovare file `SKILL.md` il cui frontmatter non viene analizzato, eseguite [`claude plugin validate`](/docs/it/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) sulla directory delle skills, ad esempio `claude plugin validate .claude/skills` per le skills del progetto o `claude plugin validate ~/.claude/skills` per le skills personali. Richiede Claude Code v2.1.233 o successivo.

1117 1126

1118<h3 id="skill-triggers-too-often">1127<h3 id="skill-triggers-too-often">

1119 Skill si attiva troppo spesso1128 Skill triggers too often

1120</h3>1129</h3>

1121 1130

1122Se Claude utilizza la vostra skill quando non lo desiderate:1131Se Claude utilizza la vostra skill quando non lo desiderate:

11252. Aggiungete `disable-model-invocation: true` se desiderate solo l'invocazione manuale11342. Aggiungete `disable-model-invocation: true` se desiderate solo l'invocazione manuale

1126 1135

1127<h3 id="skill-descriptions-are-cut-short">1136<h3 id="skill-descriptions-are-cut-short">

1128 Le descrizioni delle skill sono tagliate1137 Skill descriptions are cut short

1129</h3>1138</h3>

1130 1139

1131Claude Code carica un elenco di nomi e descrizioni delle skill nel contesto in modo che Claude sappia cosa è disponibile. L'elenco contiene sempre ogni nome di skill, ma se avete molte skills, Claude Code accorcia le descrizioni per adattarsi al budget di caratteri dell'elenco, il che può rimuovere le parole chiave di cui Claude ha bisogno per corrispondere alla vostra richiesta. Il budget si scala all'1% della finestra di contesto del modello. Quando l'elenco supera il limite, Claude Code elimina le descrizioni a partire dalle skills che invocate meno, quindi le skills che utilizzate di più mantengono il loro testo completo.1140Claude Code carica un elenco di nomi e descrizioni delle skill nel contesto in modo che Claude sappia cosa è disponibile. L'elenco contiene sempre ogni nome di skill, ma se avete molte skills, Claude Code accorcia le descrizioni per adattarsi al budget di caratteri dell'elenco, il che può rimuovere le parole chiave di cui Claude ha bisogno per corrispondere alla vostra richiesta. Il budget si scala all'1% della finestra di contesto del modello. Quando l'elenco supera il limite, Claude Code elimina le descrizioni a partire dalle skills che invocate meno, quindi le skills che utilizzate di più mantengono il loro testo completo.

sub-agents.md +25 −20

Details

304| `name` | Yes | Identificatore univoco utilizzando lettere minuscole e trattini. [Hooks](/docs/it/hooks#subagentstart) ricevono questo valore come `agent_type`. Il nome del file non deve corrispondere. I nomi non possono contenere `:`, che è riservato per [identificatori con ambito plugin](/docs/it/plugins) come `my-plugin:reviewer`. Claude Code non carica un file il cui nome contiene uno e registra un errore nel log di debug. Prima di v2.1.218, tali nomi erano accettati |304| `name` | Yes | Identificatore univoco utilizzando lettere minuscole e trattini. [Hooks](/docs/it/hooks#subagentstart) ricevono questo valore come `agent_type`. Il nome del file non deve corrispondere. I nomi non possono contenere `:`, che è riservato per [identificatori con ambito plugin](/docs/it/plugins) come `my-plugin:reviewer`. Claude Code non carica un file il cui nome contiene uno e registra un errore nel log di debug. Prima di v2.1.218, tali nomi erano accettati |

305| `description` | Yes | Quando Claude dovrebbe delegare a questo subagent |305| `description` | Yes | Quando Claude dovrebbe delegare a questo subagent |

306| `tools` | No | [Strumenti](#available-tools) che il subagent può utilizzare. Eredita ogni strumento disponibile per i subagent se omesso. Se nessuna voce nell'elenco si risolve in uno strumento, il subagent di solito [non si avvia](/docs/it/errors#agent-would-be-spawned-with-zero-tools) con un errore che nomina le voci. Per precaricare Skills nel contesto, usi il campo `skills` piuttosto che elencare `Skill` qui |306| `tools` | No | [Strumenti](#available-tools) che il subagent può utilizzare. Eredita ogni strumento disponibile per i subagent se omesso. Se nessuna voce nell'elenco si risolve in uno strumento, il subagent di solito [non si avvia](/docs/it/errors#agent-would-be-spawned-with-zero-tools) con un errore che nomina le voci. Per precaricare Skills nel contesto, usi il campo `skills` piuttosto che elencare `Skill` qui |

307| `disallowedTools` | No | Strumenti da negare, rimossi dall'elenco ereditato o specificato |307| `disallowedTools` | No | Strumenti da negare, rimossi dall'elenco ereditato o specificato. Una voce con uno specificatore, come `Bash(git push *)`, comunque [rimuove lo strumento intero](#available-tools) |

308| `model` | No | [Modello](#choose-a-model) da utilizzare: `sonnet`, `opus`, `haiku`, `fable`, un ID modello completo come `claude-opus-5`, o `inherit`. Quando lo omette, Claude Code sceglie il modello nell'[ordine del modello subagent](#choose-a-model) |308| `model` | No | [Modello](#choose-a-model) da utilizzare: `sonnet`, `opus`, `haiku`, `fable`, un ID modello completo come `claude-opus-5`, o `inherit`. Quando lo omette, Claude Code sceglie il modello nell'[ordine del modello subagent](#choose-a-model) |

309| `permissionMode` | No | [Modalità di autorizzazione](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, o `manual` come alias per `default`. L'alias `manual` richiede Claude Code v2.1.200 o successivo. Ignorato per [subagent plugin](#choose-the-subagent-scope) |309| `permissionMode` | No | [Modalità di autorizzazione](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, o `manual` come alias per `default`. L'alias `manual` richiede Claude Code v2.1.200 o successivo. Ignorato per [subagent plugin](#choose-the-subagent-scope) |

310| `maxTurns` | No | Numero massimo di turni agentici prima che il subagent si fermi. Quando il subagent raggiunge il limite, Claude Code restituisce il suo output contrassegnato come parziale, e Claude può [riprenderlo](#resume-subagents) per continuare. Il contrassegno parziale richiede Claude Code v2.1.246 o successivo |310| `maxTurns` | No | Numero massimo di turni agentici prima che il subagent si fermi. Quando il subagent raggiunge il limite, Claude Code restituisce il suo output contrassegnato come parziale, e Claude può [riprenderlo](#resume-subagents) per continuare. Il contrassegno parziale richiede Claude Code v2.1.246 o successivo |

427 Strumenti disponibili427 Strumenti disponibili

428</h4>428</h4>

429 429

430I subagent ereditano gli [strumenti integrati](/docs/it/tools-reference) e gli strumenti MCP disponibili nella conversazione principale, ristretti da due filtri: il primo rimuove un breve elenco di strumenti da ogni subagent, e il secondo riduce il set di strumenti integrati per i subagent che vengono eseguiti in [background](#run-subagents-in-foreground-or-background), che è il predefinito. [Forks](#fork-the-current-conversation) saltano entrambi i filtri e ricevono il pool di strumenti esatto della conversazione principale. Il primo filtro rimuove questi strumenti, anche quando elencati nel campo `tools`:430I subagent ereditano gli [strumenti integrati](/docs/it/tools-reference) e gli strumenti MCP disponibili nella conversazione principale, ristretti da due filtri: il primo rimuove un breve elenco di strumenti da ogni subagent, e il secondo riduce il set di strumenti integrati per i subagent che vengono eseguiti in [background](#run-subagents-in-foreground-or-background), che è il predefinito. Su macOS, Linux e WSL, un subagent può anche ricevere gli strumenti Glob e Grep quando la conversazione principale non li ha, come descritto in [Comportamento dello strumento Glob](/docs/it/tools-reference#glob-tool-behavior). [Forks](#fork-the-current-conversation) saltano entrambi i filtri e ricevono il pool di strumenti esatto della conversazione principale. Il primo filtro rimuove questi strumenti, anche quando elencati nel campo `tools`:

431 431

432* `Agent`, quando il subagent è al [limite di profondità](#let-subagents-spawn-their-own-subagents); in un [fork](#fork-the-current-conversation) lo strumento rimane elencato ma restituisce un errore invece di generare432* `Agent`, quando il subagent è al [limite di profondità](#let-subagents-spawn-their-own-subagents); in un [fork](#fork-the-current-conversation) lo strumento rimane elencato ma restituisce un errore invece di generare

433* `AskUserQuestion`433* `AskUserQuestion`

439* `WaitForMcpServers`439* `WaitForMcpServers`

440* `Workflow`440* `Workflow`

441 441

442Il secondo filtro si applica ai subagent in esecuzione in background. A parte `Agent` e `ExitPlanMode`, che seguono le condizioni del primo filtro ovunque il subagent venga eseguito, un subagent in background mantiene ogni strumento MCP ma solo questi strumenti integrati: `Read`, `Grep`, `Glob`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage`, e `Artifact`. Claude Code rimuove ogni altro strumento integrato da un subagent in background, sia ereditato che elencato nel campo `tools`, quindi la stessa definizione può risolvere in strumenti diversi in foreground e background. La rimozione non segnala alcun errore a meno che non lasci l'elenco `tools` [risolvere a nulla](/docs/it/errors#agent-would-be-spawned-with-zero-tools). [`ListAgents`](/docs/it/cross-session-messaging) segue questi filtri come qualsiasi strumento integrato: un subagent in foreground lo eredita nelle sessioni dove la messaggistica tra sessioni è abilitata, e un subagent in background non lo mantiene.442Il secondo filtro si applica ai subagent in esecuzione in background. A parte `Agent` e `ExitPlanMode`, che seguono le condizioni del primo filtro ovunque il subagent venga eseguito, un subagent in background mantiene ogni strumento MCP ma solo questi strumenti integrati: `Read`, `Grep`, `Glob`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage`, e `Artifact`. Claude Code rimuove ogni altro strumento integrato da un subagent in background, sia ereditato che elencato nel campo `tools`, quindi la stessa definizione può risolvere in strumenti diversi in foreground e background. La rimozione non segnala alcun errore a meno che non lasci l'elenco `tools` [risolvere a nulla](/docs/it/errors#agent-would-be-spawned-with-zero-tools).

443

444[`ListAgents`](/docs/it/cross-session-messaging) segue questi filtri come qualsiasi strumento integrato: un subagent in foreground lo eredita nelle sessioni dove la messaggistica tra sessioni è abilitata, e un subagent in background non lo mantiene.

443 445

444I compagni di squadra in [agent teams](/docs/it/agent-teams) inoltre mantengono gli strumenti di attività e gli strumenti cron: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, e `CronList`.446I compagni di squadra in [agent teams](/docs/it/agent-teams) inoltre mantengono gli strumenti di attività e gli strumenti cron: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, e `CronList`.

445 447

479---481---

480```482```

481 483

484Una voce `disallowedTools` con uno specificatore, come `Bash(git push *)`, comunque rimuove lo strumento intero dal subagent, non solo i comandi corrispondenti. Per mantenere Bash e bloccare comandi specifici, aggiunga una [regola di negazione Bash](/docs/it/permissions#bash) come `Bash(git push *)` a `permissions.deny` nelle sue impostazioni. La regola si applica alla conversazione principale e ai subagent.

485

482<h4 id="restrict-which-subagents-can-be-spawned">486<h4 id="restrict-which-subagents-can-be-spawned">

483 Limiti quali subagent possono essere generati487 Limiti quali subagent possono essere generati

484</h4>488</h4>

570 Modalità di autorizzazione574 Modalità di autorizzazione

571</h4>575</h4>

572 576

573Imposti `permissionMode` per scegliere la modalità di autorizzazione in cui viene eseguito un subagent. Usi i valori di configurazione delle modalità, quindi la modalità Manual è `default`. Se la lascia non impostata, il subagent eredita la modalità della conversazione principale, che inizia come [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) su piani Pro, Max e Team a meno che le sue impostazioni o la sua organizzazione non la cambino. L'impostazione la sostituisce, tranne nei casi descritti di seguito.577Imposti `permissionMode` per scegliere la modalità di autorizzazione in cui viene eseguito un subagent. Usi i valori di configurazione delle modalità, quindi la modalità Manual è `default`. Se la lascia non impostata, il subagent eredita la modalità della conversazione principale, che inizia come [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) su piani Pro, Max e Team a meno che le sue impostazioni o la sua organizzazione non la cambino.

578

579La modalità di autorizzazione della conversazione principale decide se Claude Code utilizza il valore che imposta:

580

581* Quando la conversazione principale è in `bypassPermissions`, `acceptEdits`, o [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il subagent viene eseguito in quella stessa modalità e Claude Code ignora il `permissionMode` che imposta. Sotto auto mode, il classificatore valuta le chiamate di strumenti del subagent con le regole di blocco e consentimento della conversazione principale.

582* Quando la conversazione principale è in modalità `default`, `dontAsk`, o `plan`, il subagent viene eseguito nella modalità di autorizzazione che imposta, tranne `bypassPermissions`. Un subagent che dichiara `bypassPermissions` mantiene la modalità della conversazione principale. L'eccezione `bypassPermissions` richiede Claude Code v2.1.267 o successivo.

583

584`permissionMode` accetta questi valori, e `manual` come alias per `default`:

574 585

575| Mode | Behavior |586| Mode | Behavior |

576| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |587| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

578| `acceptEdits` | Auto-accetta modifiche ai file e comandi comuni del filesystem per i percorsi nella directory di lavoro o `additionalDirectories` |589| `acceptEdits` | Auto-accetta modifiche ai file e comandi comuni del filesystem per i percorsi nella directory di lavoro o `additionalDirectories` |

579| `auto` | [Auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): un classificatore in background esamina i comandi e le scritture di directory protette |590| `auto` | [Auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): un classificatore in background esamina i comandi e le scritture di directory protette |

580| `dontAsk` | Auto-nega prompt di autorizzazione. Gli strumenti esplicitamente consentiti continuano a funzionare; `AskUserQuestion`, strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool), e strumenti connettore [che la sua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) nelle sessioni dove quella impostazione raggiunge Claude Code vengono negati anche se li ha consentiti |591| `dontAsk` | Auto-nega prompt di autorizzazione. Gli strumenti esplicitamente consentiti continuano a funzionare; `AskUserQuestion`, strumenti MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool), e strumenti connettore [che la sua organizzazione ha impostato su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) nelle sessioni dove quella impostazione raggiunge Claude Code vengono negati anche se li ha consentiti |

581| `bypassPermissions` | Salta i prompt di autorizzazione |592| `bypassPermissions` | [Salta i prompt di autorizzazione](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode). Un subagent viene eseguito in questa modalità solo quando la conversazione principale lo fa |

583 594

584<Warning>

585 Usi `bypassPermissions` con cautela. Salta i prompt di autorizzazione, consentendo al subagent di eseguire operazioni senza approvazione, incluse le scritture in `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn` e `.mvn`.

~~586~~

587 Anche in questa modalità, le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque. Consulti [permission modes](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode) per i dettagli.

588</Warning>

~~589~~

590Se il principale utilizza `bypassPermissions` o `acceptEdits`, questo ha la precedenza e non può essere sovrascritto. Se il principale utilizza [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il subagent eredita auto mode e qualsiasi `permissionMode` nel suo frontmatter viene ignorato: il classificatore valuta le chiamate di strumenti del subagent con le stesse regole di blocco e consentimento della sessione principale.

~~591~~

592Se la modalità bypass è disabilitata da [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings), Claude Code ignora `permissionMode: bypassPermissions` nel frontmatter e il subagent viene eseguito con la modalità della sessione principale. Prima di v2.1.223, Claude Code applicava la modalità frontmatter anche con bypass disabilitato.

~~593~~

594<h4 id="preload-skills-into-subagents">595<h4 id="preload-skills-into-subagents">

595 Precarichi skills nei subagent596 Precarichi skills nei subagent

596</h4>597</h4>

611 612

612Il contenuto completo di ogni skill elencata viene iniettato nel contesto del subagent all'avvio. Questo campo controlla quali skills vengono precaricate, non quali skills il subagent può accedere: senza di esso, il subagent può comunque scoprire e invocare skills di progetto, utente e plugin tramite lo strumento Skill durante l'esecuzione. Per impedire a un subagent di invocare skills interamente, ometta `Skill` dall'elenco [`tools`](#available-tools) o aggiunga a `disallowedTools`.613Il contenuto completo di ogni skill elencata viene iniettato nel contesto del subagent all'avvio. Questo campo controlla quali skills vengono precaricate, non quali skills il subagent può accedere: senza di esso, il subagent può comunque scoprire e invocare skills di progetto, utente e plugin tramite lo strumento Skill durante l'esecuzione. Per impedire a un subagent di invocare skills interamente, ometta `Skill` dall'elenco [`tools`](#available-tools) o aggiunga a `disallowedTools`.

613 614

614Non può precaricare skills che impostano [`disable-model-invocation: true`](/docs/it/skills#control-who-invokes-a-skill), poiché il precaricamento attinge dallo stesso insieme di skills che Claude può invocare. Questo include la skill `/verify` in bundle: solo lei può eseguirla, quindi non può essere precaricata nemmeno. Se una skill elencata è mancante o disabilitata, ad esempio dalla politica della sua organizzazione, Claude Code la salta e registra un avviso nel log di debug.615Non può precaricare skills che impostano [`disable-model-invocation: true`](/docs/it/skills#control-who-invokes-a-skill), poiché il precaricamento attinge dallo stesso insieme di skills che Claude può invocare. Questo include la skill `/verify` in bundle: solo lei può eseguirla, quindi non può essere precaricata nemmeno.

616

617Se una skill elencata è mancante o disabilitata, ad esempio dalla politica della sua organizzazione, Claude Code la salta e registra un avviso nel log di debug.

615 618

616<Note>619<Note>

617 Questo è l'inverso di [eseguire una skill in un subagent](/docs/it/skills#run-skills-in-a-subagent). Con `skills` in un subagent, il subagent controlla il prompt di sistema e carica il contenuto della skill. Con `context: fork` in una skill, il contenuto della skill viene iniettato nell'agente che specifica. Entrambi utilizzano lo stesso sistema sottostante.620 Questo è l'inverso di [eseguire una skill in un subagent](/docs/it/skills#run-skills-in-a-subagent). Con `skills` in un subagent, il subagent controlla il prompt di sistema e carica il contenuto della skill. Con `context: fork` in una skill, il contenuto della skill viene iniettato nell'agente che specifica. In entrambi i casi il subagent inizia senza la sua cronologia di conversazione.

618</Note>621</Note>

619 622

620<h4 id="enable-persistent-memory">623<h4 id="enable-persistent-memory">

883 886

884Il prompt di sistema del subagent sostituisce completamente il prompt di sistema predefinito di Claude Code, nello stesso modo in cui [`--system-prompt`](/docs/it/cli-reference) fa. I file `CLAUDE.md` e la memoria del progetto continuano a caricarsi attraverso il flusso di messaggi normale. Il nome dell'agente appare come `@<name>` nell'intestazione di avvio in modo che possa confermare che è attivo.887Il prompt di sistema del subagent sostituisce completamente il prompt di sistema predefinito di Claude Code, nello stesso modo in cui [`--system-prompt`](/docs/it/cli-reference) fa. I file `CLAUDE.md` e la memoria del progetto continuano a caricarsi attraverso il flusso di messaggi normale. Il nome dell'agente appare come `@<name>` nell'intestazione di avvio in modo che possa confermare che è attivo.

885 888

886Questo funziona con i subagent integrati e personalizzati, e la scelta persiste quando riprende la sessione: Claude Code ripristina il prompt di sistema, le restrizioni di strumenti e il modello dell'agente insieme alla conversazione. Se l'agente non esiste più quando riprende, la sessione continua con gli strumenti predefiniti e il prompt di sistema e mostra un [avviso che nomina l'agente](/docs/it/errors#session-agent-no-longer-available).889Questo funziona con i subagent integrati e personalizzati, e la scelta persiste quando riprende la sessione: Claude Code ripristina le restrizioni di strumenti e il modello dell'agente insieme alla conversazione. Se l'agente non esiste più quando riprende, la sessione continua con gli strumenti predefiniti e mostra un [avviso che nomina l'agente](/docs/it/errors#session-agent-no-longer-available). Per il prompt di sistema in entrambi i casi, vedi [Flag del prompt di sistema nelle conversazioni riprese](/docs/it/cli-reference#system-prompt-flags-in-resumed-conversations).

887 890

888Per un subagent fornito da un plugin, può passare solo il nome dell'agente e Claude Code lo troverà:891Per un subagent fornito da un plugin, può passare solo il nome dell'agente e Claude Code lo troverà:

889 892

927 930

928Per una skill con `context: fork`, Claude Code segue le regole in [Esegua skills in un subagent](/docs/it/skills#run-skills-in-a-subagent) invece, indipendentemente dal fatto che la modalità fork sia attiva.931Per una skill con `context: fork`, Claude Code segue le regole in [Esegua skills in un subagent](/docs/it/skills#run-skills-in-a-subagent) invece, indipendentemente dal fatto che la modalità fork sia attiva.

929 932

930I subagent in background vengono eseguiti con un [set di strumenti integrati più piccolo](#available-tools) rispetto ai subagent in primo piano, ad eccezione dei fork di conversazione, e fanno emergere ogni prompt di autorizzazione nella sua sessione principale. Quando risponde a uno di questi prompt con una scelta che dura oltre quella singola chiamata di strumento, come una concessione che dura per il resto della sessione, Claude Code applica la sua risposta all'intera sessione, inclusa la sua conversazione principale.933I subagent in background vengono eseguiti con un [set di strumenti integrati più piccolo](#available-tools) rispetto ai subagent in primo piano, ad eccezione dei fork di conversazione e [subagent ripresi](#resume-subagents) in primo piano.

934

935I subagent in background fanno emergere ogni prompt di autorizzazione nella sua sessione principale. Quando risponde a uno di questi prompt con una scelta che dura oltre quella singola chiamata di strumento, come una concessione che dura per il resto della sessione, Claude Code applica la sua risposta all'intera sessione, inclusa la sua conversazione principale.

931 936

932Un subagent in background può lasciare un comando [Bash o PowerShell](/docs/it/tools-reference#background-commands) in background [in esecuzione oltre la fine del suo turno](/docs/it/interactive-mode#how-backgrounding-works). Quando quel comando termina, Claude Code invia al subagent una notifica.937Un subagent in background può lasciare un comando [Bash o PowerShell](/docs/it/tools-reference#background-commands) in background [in esecuzione oltre la fine del suo turno](/docs/it/interactive-mode#how-backgrounding-works). Quando quel comando termina, Claude Code invia al subagent una notifica.

933 938

1145[Claude resumes the subagent with full context from previous conversation]1150[Claude resumes the subagent with full context from previous conversation]

1146```1151```

1147 1152

1148Quando Claude invia a un subagent completato un messaggio con lo strumento `SendMessage`, il subagent riprende in background senza una nuova invocazione `Agent`. Lo stesso vale per un subagent che Claude ha fermato con lo strumento `TaskStop`, una volta che la sua esecuzione fermata è uscita.1153Quando Claude invia a un subagent completato un messaggio con lo strumento `SendMessage`, il subagent riprende in background senza una nuova invocazione `Agent`. Lo stesso vale per un subagent che Claude ha fermato con lo strumento `TaskStop`, una volta che la sua esecuzione fermata è uscita. La ripresa mantiene il [set di strumenti da dove il subagent è stato eseguito per la prima volta](#run-subagents-in-foreground-or-background) e può continuare a leggere la [cache del prompt che l'esecuzione originale ha riscaldato](/docs/it/prompt-caching#subagents-and-the-cache).

1149 1154

1150Un subagent che ha lo strumento `SendMessage` può inviare anche quel messaggio. In una sessione interattiva, l'agente ripreso segnala quindi al subagent che lo ha ripreso, non alla sua conversazione principale. Quel subagent attende il risultato prima di terminare il suo lavoro. Quando un subagent messaggia un agente a cui segnala, come il suo lanciatore, Claude Code riprende quell'agente senza reindirizzare i suoi risultati.1155Un subagent che ha lo strumento `SendMessage` può inviare anche quel messaggio. In una sessione interattiva, l'agente ripreso segnala quindi al subagent che lo ha ripreso, non alla sua conversazione principale. Quel subagent attende il risultato prima di terminare il suo lavoro. Quando un subagent messaggia un agente a cui segnala, come il suo lanciatore, Claude Code riprende quell'agente senza reindirizzare i suoi risultati.

1151 1156

terminal-config.md +3 −3

Details

240 240

241 | Token | Controlla |241 | Token | Controlla |

242 | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |242 | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

247 | `ide` | Indicatore di connessione IDE |247 | `ide` | Indicatore di connessione IDE |

third-party-integrations.md +1 −6

Details

227 Invest in documentation and memory227 Invest in documentation and memory

228</h3>228</h3>

229 229

230Ti consigliamo vivamente di investire nella documentazione in modo che Claude Code comprenda il tuo codebase. Le organizzazioni possono distribuire file CLAUDE.md a più livelli:230Ti consigliamo vivamente di investire nella documentazione in modo che Claude Code comprenda il tuo codebase. Le organizzazioni possono distribuire file CLAUDE.md a più livelli. Vedi [dove i file CLAUDE.md possono trovarsi](/docs/it/memory#choose-where-to-put-claude-md-files) e [come distribuire un CLAUDE.md a livello organizzativo](/docs/it/memory#deploy-organization-wide-claude-md).

~~231~~

232* **A livello organizzativo**: Distribuisci a directory di sistema come `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux e WSL), o `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) per gli standard a livello aziendale

233* **A livello di repository**: Crea file `CLAUDE.md` nelle radici dei repository contenenti l'architettura del progetto, i comandi di build e le linee guida per i contributi. Archivialo nel controllo del codice sorgente in modo che tutti gli utenti ne traggano beneficio

~~234~~

235Scopri di più in [Memory and CLAUDE.md files](/docs/it/memory).

236 231

237<h3 id="simplify-deployment">232<h3 id="simplify-deployment">

238 Simplify deployment233 Simplify deployment

tools-reference.md +26 −19

Details

31| `EnterWorktree` | Crea un [git worktree](/docs/it/worktrees) isolato e vi entra. Passa un `path` per entrare in un worktree esistente invece di crearne uno nuovo. Al primo ingresso il target può essere un worktree del repository corrente o, in uno spazio di lavoro multi-repo, di un repository annidato al suo interno. Prima della v2.1.203, un worktree di un repository annidato era rifiutato. Un `path` al di fuori di `.claude/worktrees/` richiede la tua approvazione prima di entrare, poiché sposta la directory di lavoro della sessione e l'accesso in scrittura a quella posizione. La creazione di nuovi worktree e i percorsi sotto `.claude/worktrees/` non richiedono prompt. Prima della v2.1.206, Claude entrava nei percorsi al di fuori di `.claude/worktrees/` senza un prompt. Da una sessione worktree, o da un subagent con una directory di lavoro fissata come [`isolation: worktree`](/docs/it/sub-agents#supported-frontmatter-fields), è disponibile solo il modulo `path` e il target deve trovarsi sotto `.claude/worktrees/` del repository della sessione | Yes |31| `EnterWorktree` | Crea un [git worktree](/docs/it/worktrees) isolato e vi entra. Passa un `path` per entrare in un worktree esistente invece di crearne uno nuovo. Al primo ingresso il target può essere un worktree del repository corrente o, in uno spazio di lavoro multi-repo, di un repository annidato al suo interno. Prima della v2.1.203, un worktree di un repository annidato era rifiutato. Un `path` al di fuori di `.claude/worktrees/` richiede la tua approvazione prima di entrare, poiché sposta la directory di lavoro della sessione e l'accesso in scrittura a quella posizione. La creazione di nuovi worktree e i percorsi sotto `.claude/worktrees/` non richiedono prompt. Prima della v2.1.206, Claude entrava nei percorsi al di fuori di `.claude/worktrees/` senza un prompt. Da una sessione worktree, o da un subagent con una directory di lavoro fissata come [`isolation: worktree`](/docs/it/sub-agents#supported-frontmatter-fields), è disponibile solo il modulo `path` e il target deve trovarsi sotto `.claude/worktrees/` del repository della sessione | Yes |

32| `ExitPlanMode` | Presenta un piano per l'approvazione ed esce da Plan Mode | Yes |32| `ExitPlanMode` | Presenta un piano per l'approvazione ed esce da Plan Mode | Yes |

33| `ExitWorktree` | Esce da una sessione worktree e ritorna alla directory originale. Non disponibile per i subagent che già vengono eseguiti nella propria directory di lavoro, come con [`isolation: worktree`](/docs/it/sub-agents#supported-frontmatter-fields) | No |33| `ExitWorktree` | Esce da una sessione worktree e ritorna alla directory originale. Non disponibile per i subagent che già vengono eseguiti nella propria directory di lavoro, come con [`isolation: worktree`](/docs/it/sub-agents#supported-frontmatter-fields) | No |

34| `Glob` | Trova file in base alla corrispondenza di pattern. Vedi [Comportamento dello strumento Glob](#glob-tool-behavior) | No |34| `Glob` | Trova file in base alla corrispondenza di pattern. Assente per impostazione predefinita su macOS, Linux e WSL. Vedi [Comportamento dello strumento Glob](#glob-tool-behavior) | No |

35| `Grep` | Cerca pattern nei contenuti dei file. Vedi [Comportamento dello strumento Grep](#grep-tool-behavior) | No |35| `Grep` | Cerca pattern nei contenuti dei file. Assente per impostazione predefinita su macOS, Linux e WSL. Vedi [Comportamento dello strumento Grep](#grep-tool-behavior) | No |

36| `ListAgents` | Elenca gli agenti con cui Claude può inviare messaggi con `SendMessage`: subagent nella sessione, compagni di squadra del [team di agenti](/docs/it/agent-teams), le tue altre sessioni locali di Claude Code e, mentre questa sessione è connessa a [Remote Control](/docs/it/remote-control), le tue sessioni di [Claude Code sul web](/docs/it/claude-code-on-the-web) e le tue sessioni Remote Control su altre macchine. Supporta il comando `/list-agents`. Vedi [messaggistica tra sessioni](/docs/it/cross-session-messaging). Richiede Claude Code v2.1.224 o successivo e appare solo nelle sessioni in cui la [messaggistica tra sessioni è abilitata](/docs/it/cross-session-messaging#availability). Le righe dei compagni di squadra e la prima riga che mostra il nome della sessione stessa richiedono v2.1.239 o successivo | No |36| `ListAgents` | Elenca gli agenti con cui Claude può inviare messaggi con `SendMessage`: subagent nella sessione, compagni di squadra del [team di agenti](/docs/it/agent-teams), le tue altre sessioni locali di Claude Code e, mentre questa sessione è connessa a [Remote Control](/docs/it/remote-control), le tue sessioni di [Claude Code sul web](/docs/it/claude-code-on-the-web) e le tue sessioni Remote Control su altre macchine. Supporta il comando `/list-agents`. Vedi [messaggistica tra sessioni](/docs/it/cross-session-messaging). Richiede Claude Code v2.1.224 o successivo e appare solo nelle sessioni in cui la [messaggistica tra sessioni è abilitata](/docs/it/cross-session-messaging#availability). Le righe dei compagni di squadra e la prima riga che mostra il nome della sessione stessa richiedono v2.1.239 o successivo | No |

37| `ListMcpResourcesTool` | Elenca le risorse esposte dai [server MCP](/docs/it/mcp) connessi | No |37| `ListMcpResourcesTool` | Elenca le risorse esposte dai [server MCP](/docs/it/mcp) connessi | No |

38| `LSP` | Intelligenza del codice tramite language server: salta alle definizioni, trova riferimenti, segnala errori di tipo e avvisi. Vedi [Comportamento dello strumento LSP](#lsp-tool-behavior) | No |38| `LSP` | Intelligenza del codice tramite language server: salta alle definizioni, trova riferimenti, segnala errori di tipo e avvisi. Vedi [Comportamento dello strumento LSP](#lsp-tool-behavior) | No |

50| `SendUserFile` | Invia file dalla sessione a te con una didascalia opzionale, in modo che un rapporto generato, un diagramma, uno screenshot o un artifact costruito raggiunga il tuo dispositivo invece di essere solo menzionato nella trascrizione. A partire dalla v2.1.196, l'input `display` opzionale controlla la presentazione: `render` apre il file inline nel client, `attach` mostra solo una scheda di download, e quando non impostato il client decide in base al tipo di file. Disponibile quando un client [Remote Control](/docs/it/remote-control) è connesso o la sessione viene eseguita in un ambiente cloud gestito come [Claude Code sul web](/docs/it/claude-code-on-the-web). La consegna viene eseguita tramite l'infrastruttura ospitata da Anthropic, quindi lo strumento non è disponibile su Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry | No |50| `SendUserFile` | Invia file dalla sessione a te con una didascalia opzionale, in modo che un rapporto generato, un diagramma, uno screenshot o un artifact costruito raggiunga il tuo dispositivo invece di essere solo menzionato nella trascrizione. A partire dalla v2.1.196, l'input `display` opzionale controlla la presentazione: `render` apre il file inline nel client, `attach` mostra solo una scheda di download, e quando non impostato il client decide in base al tipo di file. Disponibile quando un client [Remote Control](/docs/it/remote-control) è connesso o la sessione viene eseguita in un ambiente cloud gestito come [Claude Code sul web](/docs/it/claude-code-on-the-web). La consegna viene eseguita tramite l'infrastruttura ospitata da Anthropic, quindi lo strumento non è disponibile su Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry | No |

51| `ShareOnboardingGuide` | Carica `ONBOARDING.md` e restituisce un link di condivisione che i compagni di squadra possono aprire in Claude Code. Chiamato da `/team-onboarding` dopo che la guida è stata scritta. Disponibile per gli abbonati a claude.ai nei piani Pro, Max, Team ed Enterprise | Yes |51| `ShareOnboardingGuide` | Carica `ONBOARDING.md` e restituisce un link di condivisione che i compagni di squadra possono aprire in Claude Code. Chiamato da `/team-onboarding` dopo che la guida è stata scritta. Disponibile per gli abbonati a claude.ai nei piani Pro, Max, Team ed Enterprise | Yes |

52| `Skill` | Esegue una [skill](/docs/it/skills#control-who-invokes-a-skill) all'interno della conversazione principale | Yes |52| `Skill` | Esegue una [skill](/docs/it/skills#control-who-invokes-a-skill) all'interno della conversazione principale | Yes |

53| `TaskCreate` | Crea una nuova attività nell'elenco delle attività. Claude Code la omette nei modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) a meno che tu non accetti | No |53| `TaskCreate` | Crea una nuova attività nell'elenco delle attività. Fornito per impostazione predefinita solo sui modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) e su altri modelli quando accetti | No |

54| `TaskGet` | Recupera i dettagli completi per un'attività specifica. Claude Code la omette nei modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) a meno che tu non accetti | No |54| `TaskGet` | Recupera i dettagli completi per un'attività specifica. Fornito per impostazione predefinita solo sui modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) e su altri modelli quando accetti | No |

55| `TaskList` | Elenca tutte le attività con il loro stato attuale. Claude Code la omette nei modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) a meno che tu non accetti | No |55| `TaskList` | Elenca tutte le attività con il loro stato attuale. Fornito per impostazione predefinita solo sui modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) e su altri modelli quando accetti | No |

56| `TaskOutput` | Recupera l'output da un'attività in background. Deprecato a favore di `Read` sul percorso del file di output dell'attività. Quando nessuna attività corrisponde all'ID, l'errore elenca gli agenti di background in esecuzione per ID e descrizione. Prima della v2.1.203, l'errore nominava solo l'ID mancante | No |56| `TaskOutput` | Recupera l'output da un'attività in background. Deprecato a favore di `Read` sul percorso del file di output dell'attività. Quando nessuna attività corrisponde all'ID, l'errore elenca gli agenti di background in esecuzione per ID e descrizione. Prima della v2.1.203, l'errore nominava solo l'ID mancante | No |

57| `TaskStop` | Arresta un'attività di background in esecuzione per ID. Accetta anche un compagno di squadra del [team di agenti](/docs/it/agent-teams) o un agente di background denominato per ID agente o nome. Prima della v2.1.198, accettava solo un ID di attività di background. Quando nessuna attività corrisponde all'ID, l'errore elenca gli agenti di background in esecuzione per ID e descrizione, inclusi gli agenti che un altro agente ha generato. Prima della v2.1.203, l'errore elencava i compagni di squadra in esecuzione e gli agenti denominati ma non gli agenti di background che un altro agente ha generato, quindi non potevano essere identificati o arrestati dalla conversazione principale | No |57| `TaskStop` | Arresta un'attività di background in esecuzione per ID. Accetta anche un compagno di squadra del [team di agenti](/docs/it/agent-teams) o un agente di background denominato per ID agente o nome. Prima della v2.1.198, accettava solo un ID di attività di background. Quando nessuna attività corrisponde all'ID, l'errore elenca gli agenti di background in esecuzione per ID e descrizione, inclusi gli agenti che un altro agente ha generato. Prima della v2.1.203, l'errore elencava i compagni di squadra in esecuzione e gli agenti denominati ma non gli agenti di background che un altro agente ha generato, quindi non potevano essere identificati o arrestati dalla conversazione principale | No |

58| `TaskUpdate` | Aggiorna lo stato dell'attività, le dipendenze, i dettagli o elimina le attività. Claude Code la omette nei modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) a meno che tu non accetti | No |58| `TaskUpdate` | Aggiorna lo stato dell'attività, le dipendenze, i dettagli o elimina le attività. Fornito per impostazione predefinita solo sui modelli elencati in [Disponibilità dello strumento Task](#task-tool-availability) e su altri modelli quando accetti | No |

59| `TodoWrite` | Gestisce l'elenco di controllo delle attività della sessione. Disabilitato per impostazione predefinita a favore di `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Imposta `CLAUDE_CODE_ENABLE_TASKS=0` per riabilitarlo nelle [sessioni che hanno gli strumenti di tracciamento delle attività](#task-tool-availability) | No |59| `TodoWrite` | Gestisce l'elenco di controllo delle attività della sessione. Disabilitato per impostazione predefinita a favore di `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Imposta `CLAUDE_CODE_ENABLE_TASKS=0` per riabilitarlo nelle [sessioni che hanno gli strumenti di tracciamento delle attività](#task-tool-availability) | No |

60| `ToolSearch` | Cerca e carica strumenti differiti quando la [ricerca di strumenti](/docs/it/mcp#scale-with-mcp-tool-search) è abilitata | No |60| `ToolSearch` | Cerca e carica strumenti differiti quando la [ricerca di strumenti](/docs/it/mcp#scale-with-mcp-tool-search) è abilitata | No |

61| `WaitForMcpServers` | Attende uno o più [server MCP](/docs/it/mcp) che si stanno ancora connettendo in background, in modo che una richiesta possa utilizzare i loro strumenti senza riavviare la sessione. Claude lo chiama quando un server necessario non è ancora connesso. Appare solo quando la [ricerca di strumenti](/docs/it/mcp#scale-with-mcp-tool-search) è disabilitata, poiché `ToolSearch` gestisce l'attesa quando è abilitata | No |61| `WaitForMcpServers` | Attende uno o più [server MCP](/docs/it/mcp) che si stanno ancora connettendo in background, in modo che una richiesta possa utilizzare i loro strumenti senza riavviare la sessione. Claude lo chiama quando un server necessario non è ancora connesso. Appare solo quando la [ricerca di strumenti](/docs/it/mcp#scale-with-mcp-tool-search) è disabilitata, poiché `ToolSearch` gestisce l'attesa quando è abilitata | No |

73* in [`permissions.allow`](/docs/it/settings-reference#permissions-allow) e [`permissions.deny`](/docs/it/settings-reference#permissions-deny) nelle impostazioni, e nell'interfaccia `/permissions`73* in [`permissions.allow`](/docs/it/settings-reference#permissions-allow) e [`permissions.deny`](/docs/it/settings-reference#permissions-deny) nelle impostazioni, e nell'interfaccia `/permissions`

74* nei flag CLI [`--allowedTools` e `--disallowedTools`](/docs/it/cli-reference)74* nei flag CLI [`--allowedTools` e `--disallowedTools`](/docs/it/cli-reference)

75* nelle opzioni [`allowedTools` e `disallowedTools`](/docs/it/agent-sdk/permissions#allow-and-deny-rules) dell'Agent SDK75* nelle opzioni [`allowedTools` e `disallowedTools`](/docs/it/agent-sdk/permissions#allow-and-deny-rules) dell'Agent SDK

~~76* nel frontmatter [`tools` o `disallowedTools`](/docs/it/sub-agents#supported-frontmatter-fields) di un subagent~~

77* nel frontmatter [`allowed-tools`](/docs/it/skills#frontmatter-reference) di una skill76* nel frontmatter [`allowed-tools`](/docs/it/skills#frontmatter-reference) di una skill

78* nella condizione [`if`](/docs/it/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field) di un hook77* nella condizione [`if`](/docs/it/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field) di un hook

79 78

154 Cosa persiste tra i comandi153 Cosa persiste tra i comandi

155</h3>154</h3>

156 155

157* Quando Claude esegue `cd` nella sessione principale, la nuova directory di lavoro viene mantenuta per i successivi comandi Bash finché rimane all'interno della directory del progetto o di una [directory di lavoro aggiuntiva](/docs/it/permissions#working-directories) che hai aggiunto con `--add-dir`, `/add-dir`, o `additionalDirectories` nelle impostazioni. Le sessioni dei subagent non mantengono mai i cambiamenti della directory di lavoro.156* Quando Claude esegue `cd` nella sessione principale, la nuova directory di lavoro viene mantenuta per i successivi comandi Bash finché rimane all'interno della directory del progetto o di una [directory di lavoro aggiuntiva](/docs/it/permissions#working-directories) che hai aggiunto con `--add-dir`, `/add-dir`, o `additionalDirectories` nelle impostazioni. Questo include i comandi che Claude esegue in risposta ai tuoi messaggi successivi.

157 * Le sessioni dei subagent non mantengono mai i cambiamenti della directory di lavoro.

158 * Se `cd` finisce al di fuori di quelle directory, Claude Code ripristina la directory del progetto e aggiunge `Shell cwd was reset to <dir>` al risultato dello strumento.158 * Se `cd` finisce al di fuori di quelle directory, Claude Code ripristina la directory del progetto e aggiunge `Shell cwd was reset to <dir>` al risultato dello strumento.

159 * Per disabilitare questo mantenimento in modo che ogni comando Bash inizi nella directory del progetto, imposta `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`.159 * Per disabilitare questo mantenimento in modo che ogni comando Bash inizi nella directory del progetto, imposta `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`.

160* Le variabili di ambiente non persistono. Un `export` in un comando non sarà disponibile nel successivo.160* Le variabili di ambiente non persistono. Un `export` in un comando non sarà disponibile nel successivo.

196 196

197Un comando che un [subagent in foreground](/docs/it/sub-agents#run-subagents-in-foreground-or-background) ha avviato si ferma quando quel subagent fornisce la sua risposta finale. Un comando che la conversazione principale o un subagent in background ha avviato continua a essere eseguito dopo una risposta finale. In modalità non interattiva con il flag `-p`, i [comandi in background terminano poco dopo il risultato finale dell'esecuzione](/docs/it/headless#background-tasks-at-exit).197Un comando che un [subagent in foreground](/docs/it/sub-agents#run-subagents-in-foreground-or-background) ha avviato si ferma quando quel subagent fornisce la sua risposta finale. Un comando che la conversazione principale o un subagent in background ha avviato continua a essere eseguito dopo una risposta finale. In modalità non interattiva con il flag `-p`, i [comandi in background terminano poco dopo il risultato finale dell'esecuzione](/docs/it/headless#background-tasks-at-exit).

198 198

199Quando un comando raggiunge il suo timeout senza terminare, Claude Code lo sposta in background invece di fermarlo. Claude continua a lavorare mentre il comando continua. Claude Code applica le stesse regole di durata a un comando spostato come a qualsiasi altro comando in background, quindi termina comunque il comando di un subagent in foreground alla risposta finale di quel subagent. Impostare [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/it/env-vars#variables) disabilita lo spostamento automatico in background insieme al resto della funzionalità delle attività in background.199Quando un comando raggiunge il suo timeout senza terminare, Claude Code lo sposta in background invece di fermarlo, a meno che il comando non inizi con `sleep`. Claude continua a lavorare mentre il comando continua. Claude Code applica le stesse regole di durata a un comando spostato come a qualsiasi altro comando in background, quindi termina comunque il comando di un subagent in foreground alla risposta finale di quel subagent. Impostare [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/it/env-vars#variables) disabilita lo spostamento automatico in background insieme al resto della funzionalità delle attività in background.

~~200~~

201Claude Code non sposta mai automaticamente in background tre tipi di comando. Li ferma al timeout invece:

~~202~~

203* Un comando che inizia con `sleep`.

204* Un comando che esegue `git` in qualsiasi punto.

205* Un comando composto che Claude Code non riesce a analizzare completamente in comandi semplici. Claude Code tratta un'espansione di parametri come `${VAR}` come non analizzabile, quindi ferma un comando che termina con `; exit "${PIPESTATUS[0]}"` al timeout anche quando il resto di quel comando viene analizzato.

206 200

207Il risultato di un comando spostato in background indica cosa è successo:201Il risultato di un comando spostato in background indica cosa è successo:

208 202

291 Comportamento dello strumento Glob285 Comportamento dello strumento Glob

292</h2>286</h2>

293 287

294Lo strumento Glob trova file in base al modello di nome. Supporta la sintassi glob standard, incluso `**` per la corrispondenza ricorsiva delle directory:288Lo strumento Glob trova file in base al modello di nome. Su Windows, fa parte del set di strumenti predefinito. Su macOS, Linux e WSL, Claude Code esclude Glob e [Grep](#grep-tool-behavior) dal set di strumenti predefinito, e Claude esegue ricerche con `find` e `grep` attraverso lo strumento Bash. Nella shell di Claude questi due comandi eseguono versioni incorporate di `bfs` e `ugrep`, e le ricerche raggiungono i vostri hook e le regole di autorizzazione come chiamate `Bash`.

289

290Su macOS, Linux e WSL, recuperate gli strumenti Glob e Grep in questi casi:

291

292* Nominate `Glob` o `Grep` in [`--tools` o `--allowedTools`](/docs/it/cli-reference#cli-flags) quando avviate la sessione, o nelle opzioni equivalenti di [Agent SDK](/docs/it/agent-sdk/overview). Con `--tools` ottenete quelli che elencate, e nominare uno dei due strumenti in `--allowedTools` ripristina entrambi. Una regola di autorizzazione in un file di impostazioni non ha questo effetto.

293* Una [regola di negazione](/docs/it/permissions#match-all-uses-of-a-tool) delle autorizzazioni, il flag `--disallowedTools`, o [`--restricted`](/docs/it/cli-reference#cli-flags) rimuove `Bash` dalla sessione.

294* Un [subagent](/docs/it/sub-agents#available-tools) elenca `Glob` o `Grep` nel suo campo `tools` e omette `Bash`. Gli strumenti elencati tornano solo per quel subagent, o per l'intera sessione quando viene eseguito come agente della sessione principale attraverso [`--agent`](/docs/it/sub-agents#invoke-subagents-explicitly) o l'impostazione `agent`.

295

296Glob supporta la sintassi glob standard incluso `**` per la corrispondenza ricorsiva delle directory:

295 297

296* `**/*.js` corrisponde a tutti i file `.js` a qualsiasi profondità298* `**/*.js` corrisponde a tutti i file `.js` a qualsiasi profondità

297* `src/**/*.ts` corrisponde a tutti i file `.ts` sotto `src/`299* `src/**/*.ts` corrisponde a tutti i file `.ts` sotto `src/`

309 Comportamento dello strumento Grep311 Comportamento dello strumento Grep

310</h2>312</h2>

311 313

312Lo strumento Grep cerca pattern nei contenuti dei file. Dove [Glob](#glob-tool-behavior) trova i file per nome, Grep trova le righe al loro interno.314Lo strumento Grep cerca pattern nei contenuti dei file. Dove [Glob](#glob-tool-behavior) trova i file per nome, Grep trova le righe al loro interno. Su macOS, Linux e WSL, Grep è assente per impostazione predefinita nelle stesse condizioni di Glob. Vedi [Comportamento dello strumento Glob](#glob-tool-behavior) per quando entrambi gli strumenti sono disponibili.

313 315

314Grep è costruito su [ripgrep](https://github.com/BurntSushi/ripgrep) e utilizza la sintassi regex di ripgrep, non grep POSIX. I pattern che includono metacaratteri regex necessitano di escape. Ad esempio, trovare `interface{}` nel codice Go richiede il pattern `interface\{\}`.316Grep è costruito su [ripgrep](https://github.com/BurntSushi/ripgrep) e utilizza la sintassi regex di ripgrep, non grep POSIX. I pattern che includono metacaratteri regex necessitano di escape. Ad esempio, trovare `interface{}` nel codice Go richiede il pattern `interface\{\}`.

315 317

580 Disponibilità dello strumento Task582 Disponibilità dello strumento Task

581</h2>583</h2>

582 584

583In Claude Code v2.1.233 e versioni successive, i seguenti strumenti non sono disponibili su Opus 4.8, Sonnet 5, Fable 5, Mythos 5 o versioni successive di queste famiglie a meno che non si acconsenta esplicitamente: `TodoWrite`, `TaskCreate`, `TaskGet`, `TaskUpdate` e `TaskList`. Questi modelli tengono traccia del lavoro multi-step senza una checklist scritta, e le definizioni e i promemoria degli strumenti occupano contesto, quindi Claude Code li esclude. Senza di essi, Claude non aggiunge nulla all'[elenco attività](/docs/it/interactive-mode#task-list) mentre lavora. Su qualsiasi altro modello, come Opus 4.7, Claude Code fornisce i quattro strumenti Task per impostazione predefinita e `TodoWrite` solo quando si imposta [`CLAUDE_CODE_ENABLE_TASKS=0`](/docs/it/env-vars).585Gli strumenti di tracciamento delle attività, `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList` e `TodoWrite`, sono disponibili per impostazione predefinita solo sui modelli Claude 3.x, Opus 4 fino a 4.7, Sonnet 4 fino a 4.6 e Haiku 4.5. Ovunque gli strumenti siano disponibili, si ottengono i quattro strumenti Task, oppure `TodoWrite` quando si imposta [`CLAUDE_CODE_ENABLE_TASKS=0`](/docs/it/env-vars).

586

587Su tutti gli altri modelli, Claude Code esclude gli strumenti a meno che non si acconsenta esplicitamente. Lo stesso vale per un ID modello che Claude Code non riconosce, come un nome di modello personalizzato servito attraverso un [gateway LLM](/docs/it/llm-gateway). Sui modelli più recenti, Claude tiene traccia del lavoro multi-step senza una checklist scritta, e le definizioni e i promemoria degli strumenti occupano contesto. Senza gli strumenti, Claude non aggiunge nulla all'[elenco attività](/docs/it/interactive-mode#task-list) mentre lavora.

584 588

585Se desiderate utilizzare questi strumenti su uno dei modelli elencati comunque, eseguite una delle seguenti operazioni:589Se desiderate utilizzare questi strumenti su un modello che non li ha per impostazione predefinita, eseguite una delle seguenti operazioni:

586 590

587* Esportate [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](/docs/it/env-vars) prima di avviare Claude Code, ad esempio `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`. Claude Code fornisce quindi gli stessi strumenti su ogni modello e ogni provider591* Esportate [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](/docs/it/env-vars) prima di avviare Claude Code, ad esempio `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`. Claude Code fornisce quindi gli stessi strumenti su ogni modello e ogni provider

588* Nominate uno degli strumenti in [`--allowedTools`](/docs/it/cli-reference#cli-flags), ad esempio `claude --allowedTools TaskCreate`592* Nominate uno degli strumenti in [`--allowedTools`](/docs/it/cli-reference#cli-flags), ad esempio `claude --allowedTools TaskCreate`

593 597

594Claude Code fornisce a un subagent gli strumenti solo quando la vostra sessione li ha, anche quando il subagent esegue un modello diverso. Un membro del team [agent team](/docs/it/agent-teams) in-process segue la vostra sessione allo stesso modo, mentre un membro del team nel suo [split pane](/docs/it/agent-teams#choose-a-display-mode) viene eseguito come un processo Claude Code separato, quindi il suo modello decide. Senza gli strumenti Task, un agent coordina con il suo team attraverso messaggi invece dell'[elenco attività condiviso](/docs/it/agent-teams#assign-and-claim-tasks).598Claude Code fornisce a un subagent gli strumenti solo quando la vostra sessione li ha, anche quando il subagent esegue un modello diverso. Un membro del team [agent team](/docs/it/agent-teams) in-process segue la vostra sessione allo stesso modo, mentre un membro del team nel suo [split pane](/docs/it/agent-teams#choose-a-display-mode) viene eseguito come un processo Claude Code separato, quindi il suo modello decide. Senza gli strumenti Task, un agent coordina con il suo team attraverso messaggi invece dell'[elenco attività condiviso](/docs/it/agent-teams#assign-and-claim-tasks).

595 599

600L'insieme predefinito descritto qui si applica in Claude Code v2.1.268 e versioni successive.

601

596<h2 id="webfetch-tool-behavior">602<h2 id="webfetch-tool-behavior">

597 Comportamento dello strumento WebFetch603 Comportamento dello strumento WebFetch

598</h2>604</h2>

606* Gli URL HTTP vengono automaticamente aggiornati a HTTPS.612* Gli URL HTTP vengono automaticamente aggiornati a HTTPS.

607* Le pagine grandi vengono troncate a un limite di caratteri fisso prima dell'elaborazione.613* Le pagine grandi vengono troncate a un limite di caratteri fisso prima dell'elaborazione.

608* WebFetch memorizza nella cache ogni risposta per 15 minuti per impostazione predefinita, quindi i recuperi ripetuti dello stesso URL vengono restituiti rapidamente. Su Claude Code v2.1.233 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/it/env-vars#variables) per modificare il tempo in cui WebFetch mantiene ogni risposta.614* WebFetch memorizza nella cache ogni risposta per 15 minuti per impostazione predefinita, quindi i recuperi ripetuti dello stesso URL vengono restituiti rapidamente. Su Claude Code v2.1.233 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/it/env-vars#variables) per modificare il tempo in cui WebFetch mantiene ogni risposta.

615* Una pagina che non ha terminato il download entro cinque minuti, inclusi tutti i reindirizzamenti che WebFetch segue, fallisce con un errore di deadline. Su Claude Code v2.1.268 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/it/env-vars#variables) per modificare il limite, o a `0` per rimuoverlo.

609* Quando un URL reindirizza a un host diverso, WebFetch restituisce un risultato di testo che nomina l'URL originale e la destinazione del reindirizzamento invece di seguirlo. Claude quindi recupera il nuovo URL con una seconda chiamata WebFetch.616* Quando un URL reindirizza a un host diverso, WebFetch restituisce un risultato di testo che nomina l'URL originale e la destinazione del reindirizzamento invece di seguirlo. Claude quindi recupera il nuovo URL con una seconda chiamata WebFetch.

610* Quando il passaggio di estrazione colpisce un'API sovraccarica, Claude Code la riprova con backoff; un recupero che ancora fallisce restituisce un risultato di errore. Prima della v2.1.212, il testo di errore dell'API potrebbe raggiungere Claude come se fosse il contenuto della pagina estratta.617* Quando il passaggio di estrazione colpisce un'API sovraccarica, Claude Code la riprova con backoff; un recupero che ancora fallisce restituisce un risultato di errore. Prima della v2.1.212, il testo di errore dell'API potrebbe raggiungere Claude come se fosse il contenuto della pagina estratta.

611 618

troubleshooting.md +13 −0

Details

110 110

111Per consentire a un comando inviato di raggiungere direttamente gli appunti, aggiungi `pbcopy *`, `wl-copy *` o `xclip *` a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands) in modo che il comando venga eseguito al di fuori della sandbox.111Per consentire a un comando inviato di raggiungere direttamente gli appunti, aggiungi `pbcopy *`, `wl-copy *` o `xclip *` a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands) in modo che il comando venga eseguito al di fuori della sandbox.

112 112

113<h3 id="copied-text-doesn’t-reach-your-local-clipboard-over-ssh">

114 Copied text doesn't reach your local clipboard over SSH

115</h3>

116

117Quando Claude Code viene eseguito su una macchina remota tramite SSH, non può eseguire uno strumento degli appunti sulla tua macchina locale. Al di fuori di tmux, quando selezioni il testo nel [fullscreen rendering](/docs/it/fullscreen) o esegui `/copy`, Claude Code invia il testo al tuo terminale come una sequenza di escape OSC 52. Il tuo terminale decide se metterlo negli appunti. `/copy` segnala `Copied to clipboard` indipendentemente dal fatto che il testo sia arrivato, e al di fuori di tmux l'avviso di selezione legge `sent N chars via OSC 52`.

118

119Alcuni terminali non agiscono su OSC 52. iTerm2 lo ignora finché non attivi **Settings > General > Selection > Applications in terminal may access clipboard**, e macOS Terminal.app non lo supporta.

120

121Per ottenere il testo senza OSC 52:

122

123* Tieni premuto il tasto di selezione nativa del tuo terminale mentre trascini, quindi copia con il tuo solito scorciatoia, come `Cmd+C`. Il tasto è `Fn` in Terminal.app e `Option` in iTerm2. [Keep native text selection](/docs/it/fullscreen#keep-native-text-selection) lo elenca per altri terminali.

124* Imposta [`CLAUDE_CODE_DISABLE_MOUSE=1`](/docs/it/env-vars) sulla macchina remota in modo che il tuo terminale gestisca la selezione per l'intera sessione.

125

113<h3 id="search-and-discovery-issues">126<h3 id="search-and-discovery-issues">

114 Search and discovery issues127 Search and discovery issues

115</h3>128</h3>

vs-code.md +45 −10

Details

52 52

53 Il modo più veloce per aprire Claude è fare clic sull'icona Spark nella **Barra degli strumenti dell'editor** (angolo in alto a destra dell'editor). L'icona appare solo quando hai un file aperto.53 Il modo più veloce per aprire Claude è fare clic sull'icona Spark nella **Barra degli strumenti dell'editor** (angolo in alto a destra dell'editor). L'icona appare solo quando hai un file aperto.

54 54

55 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code editor che mostra l'icona Spark nella Barra degli strumenti dell'editor" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />55 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="Editor VS Code che mostra l'icona Spark nella Barra degli strumenti dell'editor" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />

56 56

57 Altri modi per aprire Claude Code:57 Altri modi per aprire Claude Code:

58 58

59 * **Activity Bar**: fai clic sull'icona Spark nella barra laterale sinistra per aprire l'elenco delle sessioni. Fai clic su qualsiasi sessione per aprirla come scheda editor completa, o avvia una nuova. Questa icona è sempre visibile nella Activity Bar.59 * **Activity Bar**: fai clic sull'icona Spark nella barra laterale sinistra per aprire l'elenco delle sessioni. Fai clic su qualsiasi sessione per aprirla nella tua [posizione preferita](#extension-settings), o avvia una nuova. Questa icona è sempre visibile nella Activity Bar.

60 * **Command Palette**: `Cmd+Shift+P` (Mac) o `Ctrl+Shift+P` (Windows/Linux), digita "Claude Code" e seleziona un'opzione come "Open in New Tab"60 * **Command Palette**: `Cmd+Shift+P` (Mac) o `Ctrl+Shift+P` (Windows/Linux), digita "Claude Code" e seleziona un'opzione come "Open in New Tab"

61 * **Status Bar**: se hai impostato [`preferredLocation`](#extension-settings) su `sidebar`, o hai aperto Claude con **Claude Code: Open in Side Bar**, fai clic su **✱ Claude Code** nell'angolo in basso a destra della finestra. Questo funziona anche quando nessun file è aperto.61 * **Status Bar**: se hai impostato [`preferredLocation`](#extension-settings) su `sidebar`, o hai aperto Claude con **Claude Code: Open in Side Bar**, fai clic su **✱ Claude Code** nell'angolo in basso a destra della finestra. Questo funziona anche quando nessun file è aperto.

62 62

80 80

81 Ecco un esempio di domanda su una riga particolare in un file:81 Ecco un esempio di domanda su una riga particolare in un file:

82 82

83 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code editor con le righe 2-3 selezionate in un file Python, e il pannello Claude Code che mostra una domanda su quelle righe con un riferimento @-mention" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />83 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="Editor VS Code con le righe 2-3 selezionate in un file Python, e il pannello Claude Code che mostra una domanda su quelle righe con un riferimento @-mention" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />

84 </Step>84 </Step>

85 85

86 <Step title="Rivedi le modifiche">86 <Step title="Rivedi le modifiche">

110 * **Manual**: Claude chiede l'autorizzazione prima delle modifiche ai file e della maggior parte dei comandi shell.110 * **Manual**: Claude chiede l'autorizzazione prima delle modifiche ai file e della maggior parte dei comandi shell.

111 * **Plan**: Claude descrive cosa farà e attende l'approvazione prima di apportare modifiche. VS Code apre automaticamente il piano come documento Markdown completo dove puoi aggiungere commenti inline per fornire feedback prima che Claude inizi.111 * **Plan**: Claude descrive cosa farà e attende l'approvazione prima di apportare modifiche. VS Code apre automaticamente il piano come documento Markdown completo dove puoi aggiungere commenti inline per fornire feedback prima che Claude inizi.

112 * **Edit automatically**: Claude apporta modifiche senza chiedere.112 * **Edit automatically**: Claude apporta modifiche senza chiedere.

113* **Model**: seleziona **Switch model…** dal menu dei comandi per cambiare il modello durante la sessione. Puoi anche fare clic sul nome del modello nella parte inferiore della casella di prompt per aprire lo stesso selettore. Quando il modello attuale supporta [livelli di sforzo](/docs/it/model-config#adjust-effort-level), il selettore mostra anche una riga **Effort**. Il pulsante del nome del modello e la riga **Effort** richiedono Claude Code v2.1.257 o successivo.113* **Model**: seleziona **Switch model…** dal menu dei comandi per cambiare il modello durante la sessione. Puoi anche fare clic sul nome del modello nella parte inferiore della casella di prompt per aprire lo stesso selettore. Quando il modello attuale supporta [livelli di sforzo](/docs/it/model-config#adjust-effort-level), il selettore mostra anche una riga **Effort** e il pulsante del nome del modello mostra il livello selezionato. Il pulsante del nome del modello e la riga **Effort** richiedono Claude Code v2.1.257 o successivo.

114* **Command menu**: fai clic su `/` o digita `/` per aprire il menu dei comandi. Le opzioni includono l'allegazione di file, il cambio di modelli e l'attivazione del pensiero esteso. La sezione Customize fornisce accesso ai server MCP, slash commands, stili di output, hooks, memoria, autorizzazioni e plugin. Gli elementi con un'icona di terminale si aprono nel terminale integrato.114* **Command menu**: fai clic su `/` o digita `/` per aprire il menu dei comandi. Le opzioni includono l'allegazione di file, il cambio di modelli e l'attivazione del pensiero esteso. La sezione Customize fornisce accesso ai server MCP, slash commands, stili di output, hooks, memoria, autorizzazioni e plugin. Gli elementi con un'icona di terminale si aprono nel terminale integrato.

115 * Per sfogliare comandi come `/usage` o [`/remote-control`](/docs/it/remote-control), seleziona **Slash commands** nella sezione Customize. Una finestra di dialogo li elenca con una casella di filtro. Scegline uno per eseguirlo. Digitare `/` nella casella di prompt suggerisce comunque i comandi inline. Richiede Claude Code v2.1.257 o successivo.115 * Per sfogliare comandi come `/usage` o [`/remote-control`](/docs/it/remote-control), seleziona **Slash commands** nella sezione Customize. Una finestra di dialogo li elenca con una casella di filtro. Scegline uno per eseguirlo. Digitare `/` nella casella di prompt suggerisce comunque i comandi inline. Richiede Claude Code v2.1.257 o successivo.

116 * Seleziona **Output styles** nella sezione Customize per scegliere uno [stile di output](/docs/it/output-styles), inclusi i tuoi stili personalizzati. Richiede Claude Code v2.1.257 o successivo.116 * Seleziona **Output styles** nella sezione Customize per scegliere uno [stile di output](/docs/it/output-styles), inclusi i tuoi stili personalizzati. Richiede Claude Code v2.1.257 o successivo.

141 141

142Quando selezioni il testo nell'editor, Claude può vedere il tuo codice evidenziato automaticamente. Il piè di pagina della casella di prompt mostra quante righe sono selezionate. Premi `Option+K` (Mac) / `Alt+K` (Windows/Linux) per inserire una menzione @-mention con il percorso del file e i numeri di riga (ad es. `@app.ts#5-10`). Fai clic sull'indicatore di selezione per attivare/disattivare se Claude può vedere il testo evidenziato - l'icona occhio-barra significa che la selezione è nascosta a Claude.142Quando selezioni il testo nell'editor, Claude può vedere il tuo codice evidenziato automaticamente. Il piè di pagina della casella di prompt mostra quante righe sono selezionate. Premi `Option+K` (Mac) / `Alt+K` (Windows/Linux) per inserire una menzione @-mention con il percorso del file e i numeri di riga (ad es. `@app.ts#5-10`). Fai clic sull'indicatore di selezione per attivare/disattivare se Claude può vedere il testo evidenziato - l'icona occhio-barra significa che la selezione è nascosta a Claude.

143 143

144Puoi anche tenere premuto `Shift` mentre trascini i file nella casella di prompt per aggiungerli come allegati. Fai clic sulla X su qualsiasi allegato per rimuoverlo dal contesto.144Per allegare un'immagine, incollala dagli appunti nella casella di prompt. Puoi anche tenere premuto `Shift` mentre trascini i file nella casella di prompt per aggiungerli come allegati. Fai clic sulla X su qualsiasi allegato per rimuoverlo dal contesto.

145 145

146<h3 id="resume-past-conversations">146<h3 id="resume-past-conversations">

147 Riprendi conversazioni passate147 Riprendi conversazioni passate

148</h3>148</h3>

149 149

150Fai clic sul pulsante **Session history** nella parte superiore del pannello Claude Code per accedere alla cronologia delle conversazioni. Puoi cercare per parola chiave o sfogliare per ora. Fai clic su qualsiasi conversazione per riprenderla con la cronologia completa dei messaggi. Per ulteriori informazioni sulla ripresa delle sessioni, consulta [Manage sessions](/docs/it/sessions).150Fai clic sul pulsante **Session history** nella parte superiore del pannello Claude Code per accedere alla cronologia delle conversazioni. Puoi cercare per parola chiave o sfogliare per ora.

151 151

152Le nuove sessioni ricevono titoli generati dall'IA in base al tuo primo messaggio. Passa il mouse su una sessione per rivelare le azioni di ridenominazione e archiviazione: rinomina per darle un titolo descrittivo, o archivia per spostarla nel gruppo **Archived sessions** nella parte inferiore dell'elenco.152Fai clic su qualsiasi conversazione per riprenderla con la cronologia completa dei messaggi. Se la conversazione è già aperta in un'altra scheda della finestra corrente, facendo clic su di essa passerai a quella scheda. Per ulteriori informazioni sulla ripresa delle sessioni, consulta [Manage sessions](/docs/it/sessions).

153

154* **Session titles**: le nuove sessioni ricevono titoli generati dall'IA in base al tuo primo messaggio.

155* **Rename and archive**: passa il mouse su una sessione per rivelare queste azioni. Rinomina per darle un titolo descrittivo, o archivia per spostarla nel gruppo **Archived sessions** nella parte inferiore dell'elenco.

156

157Per impostazione predefinita, una sessione senza attività per 14 giorni si sposta automaticamente in **Archived sessions**, a meno che non sia aperta, non letta o in un [gruppo](#organize-sessions-into-groups). L'archiviazione automatica richiede Claude Code v2.1.265 o successivo. Per modificare il periodo o disattivarlo, apri l'[impostazione Archive Inactive Sessions](vscode://settings/claudeCode.archiveInactiveSessions) e seleziona un numero di giorni o **Never**.

153 158

154Per ripristinare una sessione archiviata, espandi **Archived sessions** e fai clic su **Unarchive session**. Prima della v2.1.257, l'azione era **Delete session**, che nascondeva una sessione senza modo di ripristinarla. Le sessioni che hai eliminato allora appaiono sotto **Archived sessions** dopo l'aggiornamento.159Per ripristinare una sessione archiviata, espandi **Archived sessions** e fai clic su **Unarchive session**. Prima della v2.1.257, l'azione era **Delete session**, che nascondeva una sessione senza modo di ripristinarla. Le sessioni che hai eliminato allora appaiono sotto **Archived sessions** dopo l'aggiornamento.

155 160

186 Controlla account e utilizzo191 Controlla account e utilizzo

187</h3>192</h3>

188 193

189Esegui `/usage` per aprire la finestra di dialogo Account & usage. La finestra di dialogo richiede un accesso a claude.ai, quindi non è offerta su un [provider di terze parti](#use-third-party-providers). Mostra il tuo account connesso, il tuo piano e le barre di utilizzo per la sessione corrente e la settimana. Ogni barra mostra quanto tempo rimane prima che il suo limite si ripristini.194Esegui `/usage` per aprire la finestra di dialogo Account & usage. La finestra di dialogo richiede un accesso a claude.ai, quindi non è offerta su un [provider di terze parti](#use-third-party-providers). Mostra il tuo account connesso, il tuo piano e le barre di utilizzo per i limiti del tuo piano, come la sessione corrente e la settimana. Ogni barra mostra quanto tempo rimane prima che il suo limite si ripristini.

190 195

191La finestra di dialogo suddivide anche ciò che contribuisce ai limiti del tuo piano. Contrassegna i comportamenti che rappresentano il 10% o più dell'utilizzo recente, come mancate cache, contesto lungo e sessioni pesanti di subagent o altamente parallele, ognuna con un suggerimento per ridurlo. Le tabelle di attribuzione mostrano quanto utilizzo è provenuto da ogni skill, subagent, plugin e server MCP. Richiede Claude Code v2.1.174 o successivo.196La finestra di dialogo suddivide anche ciò che contribuisce ai limiti del tuo piano. Contrassegna i comportamenti che rappresentano il 10% o più dell'utilizzo recente, come mancate cache, contesto lungo e sessioni pesanti di subagent o altamente parallele, ognuna con un suggerimento per ridurlo. Le tabelle di attribuzione mostrano quanto utilizzo è provenuto da ogni skill, subagent, plugin e server MCP. Richiede Claude Code v2.1.174 o successivo.

192 197

212 Usa la barra laterale per la tua sessione Claude principale e apri schede aggiuntive per attività secondarie. Claude ricorda la tua posizione preferita. L'icona dell'elenco delle sessioni della Activity Bar è separata dal pannello Claude: l'elenco delle sessioni è sempre visibile nella Activity Bar, mentre l'icona del pannello Claude appare lì solo quando il pannello è ancorato alla barra laterale sinistra.217 Usa la barra laterale per la tua sessione Claude principale e apri schede aggiuntive per attività secondarie. Claude ricorda la tua posizione preferita. L'icona dell'elenco delle sessioni della Activity Bar è separata dal pannello Claude: l'elenco delle sessioni è sempre visibile nella Activity Bar, mentre l'icona del pannello Claude appare lì solo quando il pannello è ancorato alla barra laterale sinistra.

213</Tip>218</Tip>

214 219

220Dopo aver eseguito **Developer: Reload Window** o riavviato VS Code, se una chat torna con la sua conversazione dipende da dove era aperta:

221

222* **Scheda editor**: la conversazione torna con la sua scheda.

223* **Barra laterale**: la conversazione torna se hai inviato un messaggio o Claude ha risposto in essa negli ultimi 10 minuti. Se non torna, riprendi la conversazione da [Cronologia sessioni](#resume-past-conversations).

224

215<h3 id="run-multiple-conversations">225<h3 id="run-multiple-conversations">

216 Esegui più conversazioni226 Esegui più conversazioni

217</h3>227</h3>

266* **Install for this project**: condiviso con i collaboratori del progetto (ambito progetto)276* **Install for this project**: condiviso con i collaboratori del progetto (ambito progetto)

267* **Install locally**: solo per voi, solo in questo repository (ambito locale)277* **Install locally**: solo per voi, solo in questo repository (ambito locale)

268 278

279<h3 id="share-a-plugin-install-link">

280 Condividere un collegamento di installazione del plugin

281</h3>

282

283Per inviare a qualcuno un collegamento diretto all'installazione di un plugin specifico, fornitegli l'URL `install-plugin` dell'estensione. L'apertura di questo URL avvia o mette a fuoco VS Code, apre il pannello Claude Code e apre la finestra di dialogo **Manage plugins** sulla scelta dell'ambito di quel plugin. Nulla viene installato finché la persona non sceglie un ambito. Se il marketplace del plugin non è ancora configurato in Claude Code, la finestra di dialogo chiede prima di aggiungerlo.

284

285```text theme={null}

286vscode://anthropic.claude-code/install-plugin?plugin=code-review&marketplace=anthropics/claude-plugins-official

287```

288

289L'URL accetta due parametri di query:

290

291| Parametro | Descrizione |

292| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

293| `plugin` | Il nome del plugin come lo elenca il suo marketplace. Obbligatorio. |

294| `marketplace` | Da dove proviene il plugin, in qualsiasi forma la [scheda Marketplaces](#manage-marketplaces) accetti, come un `owner/repo` di GitHub o un URL git. Codificatelo in URL se contiene caratteri come `&`. Per impostazione predefinita è `anthropics/claude-plugins-official` quando omesso. |

295

296Due casi terminano con un messaggio nella finestra di dialogo invece della scelta dell'ambito:

297

298* **Il marketplace non elenca un plugin con quel nome**: la finestra di dialogo segnala che il plugin non è stato trovato. Controllate il valore `plugin` rispetto all'elenco del marketplace.

299* **Il plugin è già installato**: la finestra di dialogo lo comunica e nulla cambia.

300

301I README di GitHub, i problemi e alcuni altri host Markdown rimuovono i collegamenti il cui schema non è `http` o `https`, quindi un collegamento `vscode://` lì viene visualizzato come testo semplice. Inserite l'URL in un blocco di codice su questi host, come [Il collegamento viene visualizzato come testo semplice invece di essere cliccabile](/docs/it/deep-links#the-link-renders-as-plain-text-instead-of-being-clickable) descrive per i collegamenti `claude-cli://`.

302

269<h3 id="manage-marketplaces">303<h3 id="manage-marketplaces">

270 Gestire i marketplace304 Gestire i marketplace

271</h3>305</h3>

276* Fate clic sull'icona di aggiornamento per aggiornare l'elenco dei plugin di un marketplace310* Fate clic sull'icona di aggiornamento per aggiornare l'elenco dei plugin di un marketplace

277* Fate clic sull'icona del cestino per rimuovere un marketplace311* Fate clic sull'icona del cestino per rimuovere un marketplace

278 312

279Dopo aver apportato modifiche, un banner vi chiede di riavviare Claude Code per applicarle.313Le modifiche ai plugin che apportate nella finestra di dialogo si applicano immediatamente alle sessioni Claude Code aperte in quella finestra VS Code. Se la sessione da cui avete aperto la finestra di dialogo non riesce a ricaricare i suoi plugin, la finestra di dialogo offre di riprovare o di riavviare Claude in quella sessione.

280 314

281<Note>315<Note>

282 La gestione dei plugin in VS Code utilizza gli stessi comandi CLI dietro le quinte. I plugin e i marketplace che configurate nell'estensione sono disponibili anche nella CLI, e viceversa.316 La gestione dei plugin in VS Code utilizza gli stessi comandi CLI dietro le quinte. I plugin e i marketplace che configurate nell'estensione sono disponibili anche nella CLI, e viceversa.

382vscode://anthropic.claude-code/open?prompt=review%20my%20changes416vscode://anthropic.claude-code/open?prompt=review%20my%20changes

383```417```

384 418

385Per avviare una sessione terminale invece di una scheda VS Code, usa il gestore `claude-cli://` della CLI. Vedi [Launch sessions from links](/docs/it/deep-links).419L'estensione gestisce anche `vscode://anthropic.claude-code/install-plugin`, che [apre la finestra di dialogo del plugin su un plugin](#share-a-plugin-install-link). Per avviare una sessione terminale invece di una scheda VS Code, usa il gestore `claude-cli://` della CLI. Vedi [Launch sessions from links](/docs/it/deep-links).

386 420

387<h2 id="configure-settings">421<h2 id="configure-settings">

388 Configurare le impostazioni422 Configurare le impostazioni

414| `enableReopenClosedSessionShortcut` | `true` | Usa Cmd/Ctrl+Maiusc+T per riaprire la scheda della sessione Claude chiusa più di recente. Quando l'ultima scheda chiusa non era una sessione Claude, la scorciatoia esegue il comando di riapertura dell'editor chiuso normale di VS Code. |448| `enableReopenClosedSessionShortcut` | `true` | Usa Cmd/Ctrl+Maiusc+T per riaprire la scheda della sessione Claude chiusa più di recente. Quando l'ultima scheda chiusa non era una sessione Claude, la scorciatoia esegue il comando di riapertura dell'editor chiuso normale di VS Code. |

449| `archiveInactiveSessions` | `14` | [Archivia una sessione automaticamente](#resume-past-conversations) dopo questo numero di giorni senza attività: `1`, `2`, `7` o `14`. Impostare `0` per disattivarlo. Richiede Claude Code v2.1.265 o successivo |

416| `focusView` | `false` | Nascondi le chiamate di strumenti, i risultati degli strumenti e il pensiero dietro righe espandibili, lasciando i vostri prompt e le risposte di Claude. L'elenco di cose da fare più recente di Claude rimane visibile; questo richiede Claude Code v2.1.225 o successivo. È anche possibile attivare/disattivare Focus view dal menu dei comandi. Richiede Claude Code v2.1.221 o successivo |451| `focusView` | `false` | Nascondi le chiamate di strumenti, i risultati degli strumenti e il pensiero dietro righe espandibili, lasciando i vostri prompt e le risposte di Claude. L'elenco di cose da fare più recente di Claude rimane visibile; questo richiede Claude Code v2.1.225 o successivo. È anche possibile attivare/disattivare Focus view dal menu dei comandi. Richiede Claude Code v2.1.221 o successivo |

web-quickstart.md +21 −5

Details

70 </Step>70 </Step>

71 71

72 <Step title="Sign in with GitHub">72 <Step title="Sign in with GitHub">

73 Dopo l'accesso, claude.ai/code ti chiede di connettere GitHub. Segui il prompt e claude.ai/code ti invia alla pagina di autorizzazione di GitHub. Approva la richiesta di autorizzazione e GitHub ti restituisce a claude.ai/code. Le sessioni cloud funzionano con i repository GitHub esistenti e possono raggiungere qualsiasi repository che il tuo account GitHub può vedere. Per avviare un nuovo progetto, [crea prima un repository vuoto su GitHub](https://github.com/new).73 Dopo l'accesso, claude.ai/code ti chiede di connettere GitHub. Segui il prompt e claude.ai/code ti invia alla pagina di autorizzazione di GitHub. Approva la richiesta di autorizzazione e GitHub ti restituisce a claude.ai/code. Le sessioni cloud funzionano con i repository GitHub esistenti. Per avviare un nuovo progetto, [crea prima un repository vuoto su GitHub](https://github.com/new).

74 74

75 Quando Quick web setup è disattivato, come lo è per impostazione predefinita nei piani Team ed Enterprise, claude.ai/code ti chiede quindi di installare l'app Claude GitHub sui tuoi repository a meno che non sia già installata. Installala se desideri [Auto-fix](/docs/it/claude-code-on-the-web#auto-fix-pull-requests), che consente a Claude di rispondere ai fallimenti CI e ai commenti di revisione sulle pull request in quei repository; altrimenti fai clic su **Skip**. In entrambi i casi, le sessioni possono raggiungere gli stessi repository.75 Con questa connessione, una sessione può clonare qualsiasi repository pubblico, ma può lavorare in un repository privato solo quando l'App Claude GitHub è installata su di esso. [Installa l'App](https://github.com/apps/claude/installations/new) su ogni account GitHub o organizzazione i cui repository privati desideri utilizzare. Su un'organizzazione GitHub, un proprietario dell'organizzazione potrebbe aver bisogno di approvare l'installazione. L'installazione dell'App abilita anche [Auto-fix](/docs/it/claude-code-on-the-web#auto-fix-pull-requests), che consente a Claude di rispondere ai fallimenti CI e ai commenti di revisione sulle pull request in quei repository.

77 Se l'onboarding ti chiede di installare l'App a questo punto e preferisci farlo in seguito, fai clic su **Skip**.

76 </Step>78 </Step>

77 79

78 <Step title="Set up your Default environment">80 <Step title="Set up your Default environment">

91 Connetti dal tuo terminale93 Connetti dal tuo terminale

92</h3>94</h3>

93 95

94Se usi già la GitHub CLI (`gh`), puoi configurare Claude Code sul web senza aprire un browser. Questo richiede la [Claude Code CLI](/docs/it/quickstart). Quando esegui `/web-setup`, Claude Code legge il tuo token `gh` locale, lo collega al tuo account claude.ai e crea l'ambiente cloud **Default** se non ne hai uno. Nei piani Team ed Enterprise, `/web-setup` è disponibile solo dopo che un Owner attiva [Quick web setup](/docs/it/claude-code-on-the-web#github-authentication-options).96Se usi già la GitHub CLI (`gh`), puoi configurare Claude Code sul web senza aprire un browser. Questo richiede la [Claude Code CLI](/docs/it/quickstart). Nei piani Team ed Enterprise, `/web-setup` è disponibile solo dopo che un Owner attiva [Quick web setup](/docs/it/claude-code-on-the-web#github-authentication-options).

98Quando esegui `/web-setup`, Claude Code legge il token che `gh auth token` stampa, ti chiede di confermare e invia il token ad Anthropic. Anthropic lo archivia crittografato con il tuo account claude.ai e le tue sessioni cloud lo utilizzano per l'accesso a GitHub fino a quando non lo [rimuovi](#remove-the-web-setup-token). Una sessione cloud può quindi accedere a qualsiasi repository a cui quel token può accedere, senza alcuna installazione dell'App Claude GitHub.

100Se hai già connesso GitHub nel browser, `/web-setup` ti avverte che continuare sostituisce quella connessione per le tue sessioni cloud.

95 101

96<Note>102<Note>

97 Le organizzazioni con [Zero Data Retention](/docs/it/zero-data-retention) abilitato non possono utilizzare `/web-setup` o altre funzioni di sessione cloud. Se la GitHub CLI non è installata o non è autenticata, Claude Code apre il flusso di onboarding del browser.103 Le organizzazioni con [Zero Data Retention](/docs/it/zero-data-retention) abilitato non possono utilizzare `/web-setup` o altre funzioni di sessione cloud. Se la GitHub CLI non è installata o non è autenticata, Claude Code apre il flusso di onboarding del browser.

117 /web-setup123 /web-setup

118 ```124 ```

119 125

120 Questo sincronizza il tuo token `gh` al tuo account Claude. Se ha successo, Claude Code stampa `Connected as <your-github-username>` e apre [claude.ai/code](https://claude.ai/code) nel tuo browser. Se non hai ancora un ambiente cloud, `/web-setup` ne crea uno con accesso alla rete Trusted e nessuno script di configurazione. Puoi [modificare l'ambiente o aggiungere variabili](/docs/it/cloud-environments#configure-your-environment) in seguito. Una volta completato `/web-setup`, puoi avviare sessioni cloud dal tuo terminale con [`--cloud`](/docs/it/claude-code-on-the-web#from-terminal-to-web) o configurare attività ricorrenti con [`/schedule`](/docs/it/routines).126 Conferma il prompt per inviare il tuo token `gh` al tuo account Claude. Se ha successo, Claude Code stampa `Connected as <your-github-username>` e apre [claude.ai/code](https://claude.ai/code) nel tuo browser. Se non hai ancora un ambiente cloud, `/web-setup` ne crea uno con accesso alla rete Trusted e nessuno script di configurazione. Puoi [modificare l'ambiente o aggiungere variabili](/docs/it/cloud-environments#configure-your-environment) in seguito. Una volta completato `/web-setup`, puoi avviare sessioni cloud dal tuo terminale con [`--cloud`](/docs/it/claude-code-on-the-web#from-terminal-to-web) o configurare attività ricorrenti con [`/schedule`](/docs/it/routines).

121 </Step>127 </Step>

122</Steps>128</Steps>

123 129

130<h4 id="remove-the-web-setup-token">

131 Rimuovi il token `/web-setup`

132</h4>

133

134Per rimuovere il token dal tuo account Claude, disconnetti GitHub in [claude.ai/customize/connectors](https://claude.ai/customize/connectors). La disconnessione elimina le credenziali GitHub che le tue sessioni cloud utilizzano, che provengano dal browser o da `/web-setup`, quindi le sessioni cloud perdono l'accesso a GitHub fino a quando non ti connetti di nuovo. Il tuo `gh` locale rimane connesso e il token rimane valido su GitHub.

135

136Per invalidare il token stesso, revocalo su GitHub. Se hai effettuato l'accesso a `gh` tramite il browser, il token appartiene alla voce **GitHub CLI** in [**Settings > Applications > Authorized OAuth Apps**](https://github.com/settings/applications) su GitHub, e revocare quella voce disconnette anche la GitHub CLI sulle tue macchine. Le sessioni cloud perdono quindi l'accesso a GitHub fino a quando non esegui di nuovo `gh auth login` e `/web-setup`.

137

124<h2 id="start-a-task">138<h2 id="start-a-task">

125 Avvia un'attività139 Avvia un'attività

126</h2>140</h2>

204 Nessun repository appare dopo la connessione a GitHub218 Nessun repository appare dopo la connessione a GitHub

205</h3>219</h3>

206 220

207Una sessione cloud può utilizzare qualsiasi repository che l'account GitHub connesso può vedere, indipendentemente da quali repository l'app Claude GitHub è installata. Se un repository è mancante, verifica che l'account GitHub connesso abbia accesso ad esso su GitHub. Se vuoi anche [Auto-fix](/docs/it/claude-code-on-the-web#auto-fix-pull-requests) per un repository, installa l'app su di esso: su github.com, apri **Impostazioni → Applicazioni → Claude → Configura** e verifica che il repository sia elencato sotto **Accesso al repository**. I repository privati hanno bisogno della stessa autorizzazione di quelli pubblici.221Se hai connesso GitHub nel browser, le sessioni possono clonare qualsiasi repository pubblico, ma un repository privato appare solo quando l'app Claude GitHub è installata sull'account o sull'organizzazione che lo possiede e l'accesso ai repository dell'installazione lo include. [Installa l'app Claude GitHub](https://github.com/apps/claude/installations/new) lì, oppure chiedi a un proprietario dell'organizzazione di installarla o approvarla.

222

223Se hai connesso con `/web-setup`, le sessioni raggiungono ogni repository a cui il tuo token `gh` può accedere. Esegui `gh repo view OWNER/REPO` nella tua shell per verificare che il tuo accesso GitHub CLI possa vedere il repository, ed esegui `/web-setup` di nuovo se hai cambiato account `gh` da quando ti sei connesso.

208 224

209<h3 id="the-page-only-shows-a-github-login-button">225<h3 id="the-page-only-shows-a-github-login-button">

210 La pagina mostra solo un pulsante di accesso a GitHub226 La pagina mostra solo un pulsante di accesso a GitHub

whats-new/2026-w29.md +70 −0 created

Details

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.

5# Settimana 29 · 13–17 luglio 2026

7> Estrai dati live negli artifact pubblicati tramite connettori MCP e utilizza Claude Code con un lettore di schermo nella nuova modalità screen reader.

9<div className="digest-meta">

10 <span>Rilasci <a href="/docs/en/changelog#2-1-207">v2.1.207 → v2.1.212</a></span>

11 <span>2 funzionalità · 13–17 luglio</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Gli artifact chiamano i tuoi connettori MCP</span>

17 <span className="digest-feature-pill">web</span>

18 </div>

20 <p className="digest-feature-lede">Un artifact pubblicato può ora chiamare connettori MCP ogni volta che qualcuno lo visualizza, in modo che una dashboard mostri dati live e possa eseguire azioni su richiesta anziché essere uno snapshot della sessione che l'ha creato. Ogni chiamata viene eseguita attraverso le connessioni dell'account che visualizza, e i visualizzatori approvano l'accesso prima della prima chiamata del connettore della pagina. Questa settimana aggiunge anche link di condivisione pubblica, ruoli di editor per la modifica condivisa nei piani Team ed Enterprise, e artifact creati da sessioni Claude Tag.</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/ItzF3QVI6L0QypjJ/images/whats-new/artifacts-mcp.mp4?fit=max&auto=format&n=ItzF3QVI6L0QypjJ&q=85&s=ff8b81ed52b26c773899dc28cec959e6" data-path="images/whats-new/artifacts-mcp.mp4" />

24 </Frame>

26 <p className="digest-feature-try">Nomina il connettore e i dati che desideri nel tuo prompt:</p>

28 ```text title="Claude Code" wrap theme={null}

29 Build a dashboard artifact of open pull requests that pulls the live list through my GitHub connector when the page loads.

30 ```

32 <a className="digest-feature-link" href="/docs/it/artifacts#pull-live-data-with-mcp-connectors">Estrai dati live con connettori MCP</a>

33</div>

35<div className="digest-feature">

36 <div className="digest-feature-header">

37 <span className="digest-feature-title">Modalità screen reader</span>

38 <span className="digest-feature-pill">CLI</span>

39 </div>

41 <p className="digest-feature-lede">La modalità screen reader sostituisce l'interfaccia del terminale visivo con testo semplice e lineare: invece di caselle, spinner e ridisegni in-place, Claude Code stampa righe etichettate che un lettore di schermo come VoiceOver o NVDA legge in ordine, in modo che tu possa approvare i permessi e rivedere l'output da capo a fondo. Attivalo per sessione con un flag, per shell con la variabile di ambiente <code>CLAUDE\_AX\_SCREEN\_READER</code>, o ovunque con l'impostazione <code>axScreenReader</code>.</p>

43 <p className="digest-feature-try">Avvia una sessione in modalità screen reader:</p>

45 ```bash terminal theme={null}

46 claude --ax-screen-reader

47 ```

49 <a className="digest-feature-link" href="/docs/it/accessibility#turn-on-screen-reader-mode">Attiva la modalità screen reader</a>

50</div>

52<div className="digest-wins">

53 <p className="digest-wins-title">Altri vantaggi</p>

55 <div className="digest-wins-grid">

56 <div><code>/fork</code> ora copia la tua conversazione in una nuova sessione in background con la sua riga in <code>claude agents</code> mentre continui a lavorare; il subagent biforcato in-sessione che usava lanciare è ora <code>/subtask</code></div>

57 <div><a href="/docs/it/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry">Auto mode</a> non ha più bisogno dell'opt-in <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE</code> su Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry; gli amministratori possono disattivarlo con <code>disableAutoMode</code></div>

58 <div>Le chiamate di strumenti MCP che vengono eseguite più a lungo di due minuti ora si spostano automaticamente in background in modo che la sessione rimanga utilizzabile; regola o disabilita la soglia con <code>CLAUDE\_CODE\_MCP\_AUTO\_BACKGROUND\_MS</code></div>

59 <div>Nuovo <code>claude auto-mode reset</code> ripristina la configurazione predefinita della modalità auto, e `--yes` salta il prompt di conferma</div>

60 <div>Nuovo supporto <a href="/docs/it/corporate-launcher">corporate launcher</a>: <code>CLAUDE\_CODE\_PROCESS\_WRAPPER</code> o l'impostazione <code>processWrapper</code> esegue i processi che Claude Code avvia dal suo binario, come il servizio in background e le sessioni di visualizzazione dell'agente, attraverso un eseguibile wrapper richiesto</div>

61 <div>L'impostazione <code>vimInsertModeRemaps</code> mappa sequenze in modalità insert a due tasti come <code>jj</code> a Escape in modalità vim</div>

62 <div>`--forward-subagent-text` e <code>CLAUDE\_CODE\_FORWARD\_SUBAGENT\_TEXT</code> includono testo subagent e blocchi di thinking nell'<a href="/docs/it/headless">output stream-json</a></div>

63 <div>I limiti a livello di sessione fermano i loop incontrollati: le chiamate WebSearch e gli spawn di subagent hanno ciascuno un valore predefinito di 200, regolabili con <code>CLAUDE\_CODE\_MAX\_WEB\_SEARCHES\_PER\_SESSION</code> e <code>CLAUDE\_CODE\_MAX\_SUBAGENTS\_PER\_SESSION</code></div>

64 <div>Le regole di permesso "Consenti sempre" vengono salvate alla radice del repository, quindi le approvazioni concesse in un git worktree persistono tra sessioni e worktree</div>

65 <div>Amazon Bedrock, Agent Platform di Google Cloud e Claude Platform su AWS ora hanno come impostazione predefinita Claude Opus 4.8</div>

66 <div>La riga di riepilogo dello strumento compresso mostra un contatore di tempo trascorso live, quindi le chiamate di strumenti a lunga esecuzione visibilmente si incrementano anziché sembrare bloccate</div>

67 </div>

68</div>

70[Changelog completo per v2.1.207–v2.1.212 →](/docs/en/changelog#2-1-207)

whats-new/2026-w30.md +91 −0 created

Details

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.

5# Settimana 30 · 20–24 luglio 2026

7> Opus 5 diventa il modello Opus predefinito, Claude Code Desktop aggiunge un riquadro iOS Simulator, e il plugin Claude Security esegue la scansione del codice per individuare vulnerabilità.

9<div className="digest-meta">

10 <span>Releases <a href="/docs/en/changelog#2-1-214">v2.1.214 → v2.1.219</a></span>

11 <span>3 funzionalità · 20–24 luglio</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Claude Opus 5</span>

17 <span className="digest-feature-pill">nuovo modello</span>

18 </div>

20 <p className="digest-feature-lede">Claude Opus 5 è il nuovo modello Opus predefinito in Claude Code. È il predefinito su Max, Team Premium, Enterprise pay-as-you-go, e l'API Anthropic, e su Claude Platform su AWS, Amazon Bedrock, e Agent Platform di Google Cloud. Sull'API Anthropic e sui piani Max, Team ed Enterprise, Opus 5 funziona con una <a href="/docs/it/model-config#extended-context">finestra di contesto da 1M token</a>; su Amazon Bedrock e Agent Platform di Google Cloud, selezionare la variante modello 1M. Fast mode passa a Opus 5 a \$10/\$50 per MTok. Richiede v2.1.219 o successiva.</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/opus-5.mp4?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=8536b1cb3180e539008f39930403e47b" data-path="images/whats-new/opus-5.mp4" />

24 </Frame>

26 <p className="digest-feature-try">Passare a Opus 5 per nome, o selezionarlo dal selettore di modelli:</p>

28 ```text Claude Code theme={null}

29 > /model claude-opus-5

30 ```

32 <a className="digest-feature-link" href="/docs/it/model-config#available-models">Configurazione del modello</a>

33</div>

35<div className="digest-feature">

36 <div className="digest-feature-header">

37 <span className="digest-feature-title">iOS Simulator in Claude Code Desktop</span>

38 <span className="digest-feature-pill">Desktop</span>

39 </div>

41 <p className="digest-feature-lede">Claude Code Desktop su macOS ottiene un riquadro iOS Simulator, in beta pubblica su piani Pro, Max e Team. Quando Claude compila, avvia o controlla l'app in un simulatore, il riquadro si apre accanto alla conversazione e trasmette lo schermo del dispositivo in tempo reale, così è possibile guardare Claude toccare l'app per verificare le sue modifiche o controllare il dispositivo da soli. Richiede Xcode con la piattaforma iOS installata, e Claude Desktop v1.24012.0 o successiva.</p>

43 <Frame>

44 <img className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/ios-simulator.jpg?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=6c88418ed14ed0fb12cc1af75b17f2ee" alt="Claude Code Desktop con il riquadro iOS Simulator che mostra un'app iPhone accanto alla conversazione" width="2048" height="1152" data-path="images/whats-new/ios-simulator.jpg" />

45 </Frame>

47 <p className="digest-feature-try">Chiedere a Claude di eseguire o testare l'app, e il riquadro si apre quando l'app si avvia:</p>

49 ```text Claude Code theme={null}

50 > Build the app and run it in the simulator to check the onboarding flow.

51 ```

53 <a className="digest-feature-link" href="/docs/it/desktop-ios-simulator#run-your-app-in-the-simulator">Testare app iOS nel simulatore</a>

54</div>

56<div className="digest-feature">

57 <div className="digest-feature-header">

58 <span className="digest-feature-title">Claude Security plugin</span>

59 <span className="digest-feature-pill">plugin</span>

60 </div>

62 <p className="digest-feature-lede">Il plugin Claude Security esegue una scansione di vulnerabilità multi-agente della codebase all'interno di una sessione Claude Code: gli agenti mappano l'architettura, costruiscono un modello di minaccia, cercano vulnerabilità e rivedono indipendentemente ogni risultato prima di scrivere il rapporto in una directory <code>CLAUDE-SECURITY-\<timestamp>/</code>. Eseguire la scansione di un intero repository o solo il diff di un ramo, una pull request o un singolo commit, quindi trasformare i risultati scelti in patch revisionate da applicare personalmente.</p>

64 <p className="digest-feature-try">Installare il plugin dal marketplace ufficiale Anthropic, eseguire <code>/reload-plugins</code>, quindi avviare una scansione con <code>/claude-security</code>:</p>

66 ```text Claude Code theme={null}

67 > /plugin install claude-security@claude-plugins-official

68 ```

70 <a className="digest-feature-link" href="/docs/it/claude-security#scan-and-fix-your-codebase">Eseguire la scansione e correggere la codebase</a>

71</div>

73<div className="digest-wins">

74 <p className="digest-wins-title">Altri vantaggi</p>

76 <div className="digest-wins-grid">

77 <div><a href="/docs/it/code-review#review-a-diff-locally"><code>/code-review</code></a> ora funziona come un subagenteBackground con la propria finestra di contesto, quindi il lavoro di revisione rimane fuori dalla conversazione e i risultati arrivano quando si completa</div>

78 <div><code>/verify</code>, <code>/code-review</code> e <code>/deep-research</code> vengono eseguiti solo quando li si invoca; Claude non li avvia più autonomamente</div>

79 <div><a href="/docs/it/interactive-mode#emoji-shortcodes">Gli shortcode emoji</a> si completano automaticamente nell'input del prompt: digitare <code>:heart:</code> per inserire un emoji, o due o più caratteri dopo <code>:</code> per i suggerimenti; disattivarlo con <code>emojiCompletionEnabled</code></div>

80 <div>Le skill con <code>context: fork</code> <a href="/docs/it/skills#run-skills-in-a-subagent">vengono eseguite in background</a> per impostazione predefinita, e <code>background: false</code> nel frontmatter della skill attende il risultato nello stesso turno</div>

81 <div>Una sessione esegue fino a 20 subagentti contemporaneamente per impostazione predefinita; modificare il <a href="/docs/it/sub-agents#concurrent-subagent-limit">limite</a> con <code>CLAUDE\_CODE\_MAX\_CONCURRENT\_SUBAGENTS</code></div>

82 <div>`--max-budget-usd` ora applica il limite ai subagentti: una volta raggiunta la spesa, Claude non può avviarne altri e i subagentti background in esecuzione si fermano</div>

83 <div>Nuova impostazione <a href="/docs/it/sandboxing#disable-filesystem-isolation"><code>sandbox.filesystem.disabled</code></a> che salta l'isolamento del filesystem mantenendo il controllo dell'uscita di rete</div>

84 <div>In modalità auto, i controlli per i comandi <code>rm</code> pericolosi, i lavori in background e i percorsi Windows sospetti non aprono più finestre di dialogo di autorizzazione; il classificatore della modalità auto li decide invece</div>

85 <div>I controlli di autorizzazione Bash falliscono in modo chiuso su più forme di shell, inclusi i reindirizzamenti dei descrittori di file, i subscript delle variabili Zsh nei confronti <code>\[\[ ]]</code>, le invocazioni <code>help</code> e <code>man</code> che potrebbero eseguire opzioni non sicure, e i comandi superiori a 10.000 caratteri</div>

86 <div><a href="/docs/it/fast-mode">Fast mode</a> non supporta più Opus 4.7: <code>/fast</code> ora si applica a Opus 5 e Opus 4.8</div>

87 <div>Le chiamate di strumenti a lunga esecuzione emettono un heartbeat di progresso periodico invece di rimanere silenziose</div>

88 </div>

89</div>

91[Changelog completo per v2.1.214–v2.1.219 →](/docs/en/changelog#2-1-214)

whats-new/2026-w32.md +103 −0 created

Details

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.

5# Settimana 32 · 3–7 agosto 2026

7> Le sessioni di Claude Code si messaggiano tra loro, gli ambienti self-hosted eseguono sessioni cloud sulla vostra infrastruttura, e la modalità auto diventa la modalità di autorizzazione predefinita.

9<div className="digest-meta">

10 <span>Rilasci <a href="/docs/en/changelog#2-1-220">v2.1.220 → v2.1.224</a></span>

11 <span>3 funzionalità · 3–7 agosto</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Messaggistica tra sessioni</span>

17 <span className="digest-feature-pill">v2.1.224</span>

18 </div>

20 <p className="digest-feature-lede">Le vostre sessioni di Claude Code possono ora messaggiarsi tra loro. Claude scopre le vostre altre sessioni con lo strumento <code>ListAgents</code> e invia con <code>SendMessage</code>, sia quando lo chiedete voi sia autonomamente, ad esempio dopo che una modifica in una sessione influisce su ciò su cui sta lavorando un'altra. Un messaggio è testo che Claude scrive per l'altra sessione, mai la vostra cronologia di conversazione o file. Disponibile su macOS e Linux. Richiede v2.1.224 o successiva.</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/cross-session-messaging.mp4?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=8f33c3390f78660a4a26dc980f46159f" data-path="images/whats-new/cross-session-messaging.mp4" />

24 </Frame>

26 <p className="digest-feature-try">Con due sessioni aperte sulla stessa macchina, chiedete a una di loro di passare qualcosa:</p>

28 ```text title="Claude Code" wrap theme={null}

29 Tell the session working on the payments API that users.name is now users.display_name

30 ```

32 <p className="digest-feature-try">L'altra sessione mostra una riga <code>Message from</code> una volta che Claude ha letto il messaggio; premete <code>Ctrl+O</code> per espanderla. Per vedere quali sessioni Claude può raggiungere, eseguite <code>/list-agents</code>.</p>

34 <a className="digest-feature-link" href="/docs/it/cross-session-messaging#message-another-session">Messaggiate un'altra sessione</a>

35</div>

37<div className="digest-feature">

38 <div className="digest-feature-header">

39 <span className="digest-feature-title">Ambienti self-hosted</span>

40 <span className="digest-feature-pill">v2.1.224</span>

41 </div>

43 <p className="digest-feature-lede">Gli ambienti self-hosted eseguono sessioni cloud di Claude Code sulla vostra infrastruttura organizzativa, in beta pubblica sui piani Team ed Enterprise. Eseguite <code>claude self-hosted-runner</code> sulle vostre macchine o container per trasformarle in runner. Quando qualcuno sceglie il vostro ambiente mentre avvia una sessione da claude.ai, dalle app mobile o desktop, o da `claude --cloud`, quella sessione viene eseguita all'interno della vostra rete, con accesso ai vostri servizi interni. Un Owner attiva <strong>Allow self-hosted environments</strong> nelle <a href="https://claude.ai/admin-settings/cloud-environments">impostazioni di amministrazione</a> per primo.</p>

45 <Frame>

46 <img className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/self-hosted-environments.jpg?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=ae9152cb1670c8af517d1aee57689b14" alt="The self-hosted environments admin page listing environments such as linux-dev and macos-prod with their status and active session counts" width="2048" height="1152" data-path="images/whats-new/self-hosted-environments.jpg" />

47 </Frame>

49 <p className="digest-feature-try">Acceduti come Owner, eseguite la configurazione guidata, che vi guida attraverso la creazione dell'ambiente e avvia un runner:</p>

51 ```bash terminal theme={null}

52 claude self-hosted-runner setup

53 ```

55 <p className="digest-feature-try">L'ambiente mostra <strong>Healthy</strong> nelle impostazioni di amministrazione una volta che il runner si registra.</p>

57 <a className="digest-feature-link" href="/docs/it/self-hosted-environments-quickstart#set-up-an-environment-and-runner">Guida rapida agli ambienti self-hosted</a>

58</div>

60<div className="digest-feature">

61 <div className="digest-feature-header">

62 <span className="digest-feature-title">La modalità auto diventa la predefinita</span>

63 <span className="digest-feature-pill">CLI</span>

64 </div>

66 <p className="digest-feature-lede">A partire dal 14 agosto, la modalità auto è la modalità di autorizzazione predefinita per le nuove sessioni sui piani Pro, Max e Team. Se impostate una modalità predefinita voi stessi, rimane in vigore a meno che non accettiate il prompt di commutazione una tantum, e una modalità predefinita che la vostra organizzazione gestisce non cambia. Potete comunque cambiare modalità in qualsiasi momento. Già in vigore su quei piani: le chiamate del classificatore che la modalità auto effettua non contano più verso i vostri limiti di utilizzo.</p>

68 <p className="digest-feature-try">Per avviare ogni sessione in modalità auto prima della commutazione, impostatela come predefinita nelle vostre impostazioni utente:</p>

70 ```json ~/.claude/settings.json {3} theme={null}

71 {

72 "permissions": {

73 "defaultMode": "auto"

74 }

75 }

76 ```

78 <p className="digest-feature-try">Le nuove sessioni mostrano quindi <code>auto mode on</code> nella barra di stato.</p>

80 <a className="digest-feature-link" href="/docs/it/permission-modes#eliminate-prompts-with-auto-mode">Requisiti e controlli della modalità auto</a>

81</div>

83<div className="digest-wins">

84 <p className="digest-wins-title">Altri vantaggi</p>

86 <div className="digest-wins-grid">

87 <div>L'estensione VS Code ottiene <a href="/docs/it/vs-code#extension-settings">Focus view</a>, che nasconde l'attività dello strumento dietro una riga espandibile per turno; attivatela dal menu dei comandi o con <code>Ctrl+Alt+F</code> (<code>Ctrl+Option+F</code> su Mac)</div>

88 <div>I file di credenziali Sandbox accettano <a href="/docs/it/sandboxing#mask-credential-files"><code>mode: "mask"</code></a> su Linux e WSL2, quindi i comandi in sandbox leggono una copia sentinella mentre il proxy sandbox sostituisce il valore reale all'uscita; il mascheramento delle credenziali guadagna anche opzioni <code>extract</code>, <code>decode</code> consapevole di JWT, e re-firma AWS SigV4</div>

89 <div>I marketplace possono distribuire un plugin come <a href="/docs/it/plugin-marketplaces#zip-archives">archivio zip</a> con la nuova fonte <code>archive</code>, scaricato su HTTPS con un pin SHA-256 opzionale, quindi gli install funzionano senza git o npm</div>

90 <div><code>/review</code> è ora un alias di <a href="/docs/it/code-review#review-a-diff-locally"><code>/code-review</code></a>, e <code>/code-review</code> senza livello di sforzo riutilizza il livello che avete digitato per ultimo</div>

91 <div>Una sessione che copiate con <a href="/docs/it/agent-view#copy-the-session-with-%2Ffork"><code>/fork</code></a> ora effettua le sue modifiche al codice in un worktree proprio invece del checkout della sessione originale</div>

92 <div>I plugin che installate da <a href="/docs/it/discover-plugins#install-plugins"><code>/plugin</code></a> si attivano nella sessione corrente quando è sicuro farlo; il riepilogo dell'installazione segnala <code>Plugin is now active.</code> o vi dice di eseguire <code>/reload-plugins</code></div>

93 <div>Le <a href="/docs/it/agent-view#how-file-edits-are-isolated">sessioni in background</a> che hanno modificato il codice in un worktree ora eseguono il commit e il push prima di terminare, aprono una richiesta pull in bozza solo quando l'attività lo richiede, e seguono le istruzioni git nel vostro <code>CLAUDE.md</code></div>

94 <div>Il limite di 200 subagent per sessione viene rimosso, quindi le sessioni di lunga durata non rifiutano più i nuovi subagent; i limiti di <a href="/docs/it/sub-agents#concurrent-subagent-limit">concorrenza</a> e profondità si applicano ancora</div>

95 <div>Le impostazioni archiviate di un repository non possono più attivare <a href="/docs/it/remote-control#enable-remote-control-for-all-sessions">Remote Control auto-connect</a>; impostate <code>remoteControlAtStartup</code> nelle vostre impostazioni utente o gestite, e le impostazioni di progetto e locali possono solo disattivarla</div>

96 <div>L'<a href="/docs/it/worktrees#how-claude-code-enforces-isolation">isolamento dei worktree</a> ora blocca non solo le modifiche ai file ma anche i comandi Bash e i reindirizzamenti git che raggiungono il checkout principale, in ogni tipo di sessione e nei subagent della sessione</div>

97 <div>Un comando Bash non può più nascondere parte di sé dai controlli di autorizzazione, e il padding di tabulazione o Unicode invisibile non nasconde più parte di un comando dalla finestra di dialogo di approvazione</div>

98 <div>Gli hook auto-allow di PreToolUse non bypassano più le restrizioni degli strumenti nei compiti interni di Claude Code come riepiloghi e compattazione</div>

99 <div>L'anteprima di ricerca <a href="/docs/it/ultraplan">Ultraplan</a> viene rimossa, incluso il comando <code>/ultraplan</code> e la parola chiave <code>ultraplan</code>; utilizzate invece la modalità plan o Claude Code sul web</div>

100 </div>

101</div>

102

103[Changelog completo per v2.1.220–v2.1.224 →](/docs/en/changelog#2-1-220)

whats-new/2026-w33.md +87 −0 created

Details

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.

5# Settimana 33 · 10–14 agosto 2026

7> Claude Code Desktop continua automaticamente dopo il ripristino di un limite di utilizzo, la modalità fork è attivata per impostazione predefinita e le richieste di merge GitLab e i marketplace si uniscono a GitHub.

9<div className="digest-meta">

10 <span>Releases <a href="/docs/en/changelog#2-1-225">v2.1.225 → v2.1.233</a></span>

11 <span>3 funzionalità · 10–14 agosto</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Continuazione automatica dopo un limite di utilizzo su Desktop</span>

17 <span className="digest-feature-pill">Desktop</span>

18 </div>

20 <p className="digest-feature-lede">Quando raggiungi il limite di sessione nella scheda Code di Claude Code Desktop, la scheda del limite ora offre una casella di controllo <strong>Continua automaticamente quando i limiti si ripristinano</strong>. Selezionala e l'app Desktop ritenta il turno interrotto dopo il ripristino. La scheda mostra l'ora del nuovo tentativo. La scheda del limite settimanale non lo offre.</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/desktop-auto-continue.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=1937f489695feaea715e48ecfd7e62cd" data-path="images/whats-new/desktop-auto-continue.mp4" />

24 </Frame>

26 <p className="digest-feature-try">La prossima volta che appare una scheda di limite di sessione, seleziona <strong>Continua automaticamente quando i limiti si ripristinano</strong> e lascia la sessione aperta. La scheda mostra <code>Auto-resuming at</code> seguito dall'ora di ripristino e il turno riprende da solo una volta che il limite si ripristina.</p>

28 <a className="digest-feature-link" href="/docs/it/errors#youve-hit-your-session-limit">Cosa fare quando raggiungi un limite di utilizzo</a>

29</div>

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Modalità fork attivata per impostazione predefinita</span>

34 <span className="digest-feature-pill">v2.1.232</span>

35 </div>

37 <p className="digest-feature-lede">La modalità fork è ora attivata per impostazione predefinita nelle sessioni interattive. Claude può richiedere il tipo di subagent <code>fork</code>, che eredita la conversazione completa e la cache del prompt invece di iniziare da zero, quindi non devi rispiegare il contesto per un'attività secondaria. I subagent che Claude genera nelle sessioni interattive, a parte quelli che un collega del team di agenti genera, vengono eseguiti anche in background per impostazione predefinita.</p>

39 <p className="digest-feature-try">Avvia tu stesso un fork con un'attività che ha bisogno di tutto ciò che hai discusso finora:</p>

41 ```text Claude Code theme={null}

42 > /subtask draft unit tests for the parser changes so far

43 ```

45 <p className="digest-feature-try">Il fork appare nel pannello sotto il tuo prompt e il suo risultato arriva nella tua conversazione quando termina. Per disattivare la modalità fork, imposta <code>CLAUDE\_CODE\_FORK\_SUBAGENT=0</code>.</p>

47 <a className="digest-feature-link" href="/docs/it/sub-agents#turn-fork-mode-on-or-off">Attiva o disattiva la modalità fork</a>

48</div>

50<div className="digest-feature">

51 <div className="digest-feature-header">

52 <span className="digest-feature-title">Richieste di merge GitLab e marketplace</span>

53 <span className="digest-feature-pill">v2.1.232</span>

54 </div>

56 <p className="digest-feature-lede">I marketplace dei plugin clonano gli URL <code>gitlab.com</code> bare, inclusi i sottogruppi annidati. Su v2.1.233 o versioni successive, passa un URL di richiesta di merge GitLab a <code>--worktree</code> per creare un ramo da esso, e la visualizzazione <code>claude agents</code> etichetta le sessioni collegate a una richiesta di merge come <code>!N</code>. Claude Code inoltre oscura le famiglie di token GitLab come <code>glpat-</code> e <code>glrt-</code>, e protegge l'archivio di configurazione della CLI <code>glab</code> nello stesso modo in cui protegge <code>gh</code>.</p>

58 <p className="digest-feature-try">Avvia una sessione in un worktree creato da un ramo da una richiesta di merge:</p>

60 ```bash terminal theme={null}

61 claude --worktree https://gitlab.com/group/project/-/merge_requests/42

62 ```

64 <p className="digest-feature-try">Quando <code>origin</code> è su gitlab.com, Claude Code recupera <code>merge-requests/42/head</code> e apre la sessione su quel ramo nel suo worktree.</p>

66 <a className="digest-feature-link" href="/docs/it/worktrees#branch-from-a-pull-request">Crea un ramo worktree da una richiesta di pull o merge</a>

67</div>

69<div className="digest-wins">

70 <p className="digest-wins-title">Altri vantaggi</p>

72 <div className="digest-wins-grid">

73 <div>Digita <code>@</code> nel prompt per <a href="/docs/it/cross-session-messaging#message-another-session">menzionare un'altra sessione Claude</a> per nome, e Claude la messaggerizza direttamente con <code>SendMessage</code>; un nome semplice che corrisponde esattamente a una sessione live ora viene consegnato senza un passaggio di conferma</div>

74 <div>Le sessioni interattive su una macchina mantengono <a href="/docs/it/cross-session-messaging#see-which-sessions-claude-can-reach">nomi univoci</a>: se avvii o rinomini una sessione con un nome che un'altra sessione live già utilizza, Claude Code ti dà una variante <code>name-word-word</code> e te lo comunica</div>

75 <div>I marketplace dei plugin accettano <a href="/docs/it/plugin-marketplaces#command-sources">fonti <code>command</code></a>: un comando locale stampa la directory del plugin, che Claude Code ri-risolve ogni sessione e applica senza un riavvio</div>

76 <div>Su Linux e WSL, imposta <a href="/docs/it/tools-reference#memory-limit-on-linux-and-wsl"><code>CLAUDE\_CODE\_TOOL\_MEMORY\_LIMIT</code></a> a una dimensione come <code>4G</code> per limitare la memoria che i comandi dello strumento Bash e PowerShell possono utilizzare</div>

77 <div>Gli strumenti di tracciamento delle attività, come <code>TaskCreate</code>, <code>TaskUpdate</code> e <code>TodoWrite</code>, sono <a href="/docs/it/tools-reference#task-tool-availability">non più disponibili su Opus 4.8, Sonnet 5, Fable 5, Mythos 5 e modelli successivi in quelle famiglie</a>; imposta <code>CLAUDE\_CODE\_ENABLE\_TODO\_TOOLS=1</code> per riattivarli</div>

78 <div><a href="/docs/it/code-review#review-a-diff-locally"><code>/code-review</code></a> a livello di sforzo alto, xhigh e max ora viene eseguito in un agente di background come gli altri livelli</div>

79 <div><a href="/docs/it/discover-plugins#install-plugins"><code>/plugin install plugin\@marketplace</code></a> aggiorna prima il marketplace, quindi i plugin appena pubblicati si installano senza un aggiornamento manuale del marketplace</div>

80 <div>Le impostazioni accettano <a href="/docs/it/settings-reference#marketplace-key-aliases"><code>additionalMarketplaces</code> e <code>allowedMarketplaces</code></a> come alias per <code>extraKnownMarketplaces</code> e <code>strictKnownMarketplaces</code></div>

81 <div>Su modelli più recenti, Claude può <a href="/docs/it/tools-reference#write-tool-behavior">sovrascrivere un file esistente con lo strumento Write</a> senza leggerlo prima in questa sessione, corrispondendo alle regole dello strumento Edit; i modelli più vecchi richiedono la lettura</div>

82 <div>L'estensione VS Code può <a href="/docs/it/vs-code#organize-sessions-into-groups">organizzare l'elenco delle sessioni in gruppi</a>: fai clic con il pulsante destro del mouse per creare, rinominare o eliminare un gruppo, e Cmd/Ctrl- o Shift-click per spostare più sessioni contemporaneamente</div>

83 <div>Se la tua organizzazione instrada Claude Code attraverso un <a href="/docs/it/claude-apps-gateway-spend-limits">gateway di app Claude con limiti di spesa</a>, Claude Code mostra il periodo limite, l'ora di ripristino e il messaggio dell'operatore quando raggiungi il limite</div>

84 </div>

85</div>

87[Changelog completo per v2.1.225–v2.1.233 →](/docs/en/changelog#2-1-225)

whats-new/2026-w34.md +105 −0 created

Details

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.

5# Settimana 34 · 17–21 agosto 2026

7> Crea artboard UI modificabili con la skill /design, imposta lo stile di output Concise e avvia una sessione Claude Code sulla tua macchina dal tuo telefono.

9<div className="digest-meta">

10 <span>Rilasci <a href="/docs/en/changelog#2-1-234">v2.1.234 → v2.1.239</a></span>

11 <span>3 funzionalità · 17–21 agosto</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">/design</span>

17 <span className="digest-feature-pill">research preview</span>

18 </div>

20 <p className="digest-feature-lede">La skill <code>/design</code> porta il flusso di lavoro degli artboard di Claude Design nella CLI e in Claude Code Desktop, basato su artifact. Eseguila con un brief e Claude pubblica una canvas di artboard modificabili per la tua UI. Scegline uno, modificalo, quindi chiedi a Claude di implementarlo. Disponibile su Pro, Max, Team ed Enterprise. Richiede v2.1.234 o successiva.</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/design-skill.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=0b376a94227c14a4204af89c4c9fd7ac" data-path="images/whats-new/design-skill.mp4" />

24 </Frame>

26 <p className="digest-feature-try">Descrivi cosa vuoi progettare e lascia che Claude elabori le opzioni:</p>

28 ```text Claude Code theme={null}

29 > /design redesign the composer based on what people actually use it for

30 ```

32 <p className="digest-feature-try">Claude stampa un link alla canvas pubblicata. Aprila, scegli un artboard e dì a Claude quale opzione implementare.</p>

34 <a className="digest-feature-link" href="/docs/it/artifacts#availability">Dove gli artifact sono disponibili</a>

35</div>

37<div className="digest-feature">

38 <div className="digest-feature-header">

39 <span className="digest-feature-title">Stile di output Concise</span>

40 <span className="digest-feature-pill">v2.1.237</span>

41 </div>

43 <p className="digest-feature-lede">Concise è un nuovo stile di output integrato. Claude inizia con il risultato e salta il preambolo e la narrazione, mentre svolge il lavoro in modo altrettanto approfondito dello stile Default. Quando chiedi una spiegazione o più dettagli, Claude risponde completamente. I rapporti di errore, gli avvisi di sicurezza e le conferme per le azioni distruttive mantengono il loro contenuto completo.</p>

45 <Frame>

46 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/concise-output-style.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=dfb40ec8921ed1bc82eb629042a8ec17" data-path="images/whats-new/concise-output-style.mp4" />

47 </Frame>

49 <p className="digest-feature-try">Attivalo in <strong>Output style</strong> in <code>/config</code>, oppure impostalo nel tuo file di impostazioni:</p>

51 ```json ~/.claude/settings.json {2} theme={null}

52 {

53 "outputStyle": "Concise"

54 }

55 ```

57 <p className="digest-feature-try">Esegui <code>/clear</code> o avvia una nuova sessione, e le risposte di Claude inizieranno con il risultato.</p>

59 <a className="digest-feature-link" href="/docs/it/output-styles#built-in-output-styles">Stili di output integrati</a>

60</div>

62<div className="digest-feature">

63 <div className="digest-feature-header">

64 <span className="digest-feature-title">Avvia una sessione sulla tua macchina dal tuo telefono</span>

65 <span className="digest-feature-pill">mobile</span>

66 </div>

68 <p className="digest-feature-lede">Qualsiasi macchina che esegue <code>claude remote-control</code> ora appare come una scheda dispositivo nella parte superiore della scheda Code nell'app Claude. Remote Control è anche uscito dalla research preview.</p>

70 <Frame>

71 <img className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/remote-control-phone-start.jpg?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=9f0ebedab23aa0e1732cc37782573907" alt="La scheda Code nell'app mobile Claude con una sezione Dispositivi che mostra un MacBook connesso come scheda dispositivo sopra l'elenco delle sessioni" width="1206" height="895" data-path="images/whats-new/remote-control-phone-start.jpg" />

72 </Frame>

74 <p className="digest-feature-try">Avvia Remote Control sulla macchina che vuoi raggiungere, quindi apri la scheda Code sul tuo telefono:</p>

76 ```bash terminal theme={null}

77 claude remote-control

78 ```

80 <p className="digest-feature-try">La tua macchina appare come una scheda dispositivo nella parte superiore della scheda Code. Toccala per scegliere una directory e avviare una sessione lì.</p>

82 <a className="digest-feature-link" href="/docs/it/remote-control#start-a-remote-control-session">Avvia una sessione Remote Control</a>

83</div>

85<div className="digest-wins">

86 <p className="digest-wins-title">Altri vantaggi</p>

88 <div className="digest-wins-grid">

89 <div>Claude Code ora continua automaticamente la tua sessione quando un limite di utilizzo di claude.ai si ripristina; disattivalo dalla riga <strong>Continue automatically at usage limit</strong> in <code>/config</code></div>

90 <div>L'impostazione facoltativa <a href="/docs/it/interactive-mode#check-spelling-as-you-type"><code>spellcheck</code></a> sottolinea le parole scritte male nell'input del prompt mentre digiti, utilizzando il tuo <code>aspell</code>, <code>hunspell</code> o <code>ispell</code> installato</div>

91 <div>Su un ramo con una merge request GitLab aperta, con la CLI <code>glab</code> autenticata tramite <code>glab auth login</code>, il footer mostra un badge <a href="/docs/it/interactive-mode#gitlab-merge-requests"><code>MR !N</code></a> colorato a seconda che la merge request sia una bozza, aperta o unibile</div>

92 <div>Cambia il livello di sforzo dal tuo telefono o da claude.ai/code e <a href="/docs/it/remote-control#what-connected-devices-see">si applica alla sessione sulla tua macchina</a>; le sessioni Remote Control ospitate da Desktop o VS Code mostrano anche ai dispositivi connessi la modalità di autorizzazione corrente della sessione</div>

93 <div>Puoi aprire <a href="/docs/it/permissions#manage-permissions"><code>/permissions</code></a> o eseguire <code>/add-dir \<path></code> mentre Claude sta lavorando; i cambiamenti delle regole di autorizzazione si applicano al resto del turno corrente</div>

94 <div>Quando le attività in background mantengono un <a href="/docs/it/goal#background-work-defers-evaluation"><code>/goal</code></a> in attesa, Claude controlla dopo 30 minuti invece di aspettare indefinitamente e continua a controllare, a intervalli più lunghi mentre la sessione rimane inattiva; imposta <code>CLAUDE\_CODE\_GOAL\_CHECKIN\_MINUTES=0</code> per rinunciare</div>

95 <div>I tuoi prompt ora renderizzano markdown nella trascrizione, con blocchi di codice evidenziati, codice inline e elenchi, nello stesso modo in cui lo fanno le risposte</div>

96 <div>La nuova variabile di ambiente <a href="/docs/it/model-config#set-a-default-model-for-new-sessions"><code>ANTHROPIC\_DEFAULT\_MODEL</code></a> imposta il modello su cui iniziano le nuove sessioni; una scelta <code>/model</code> la sovrascrive comunque e persiste tra i riavvii</div>

97 <div>Con l'input <code>notify\_when\_idle</code> su <code>SendMessage</code>, Claude può chiedere a un'altra sessione Claude Code sulla stessa macchina di <a href="/docs/it/cross-session-messaging#get-a-notice-when-another-session-goes-idle">inviare un avviso quando successivamente diventa inattiva</a></div>

98 <div>Imposta <a href="/docs/it/interactive-mode#make-ctrl-w-delete-back-to-whitespace"><code>keybindingFlavor</code></a> su <code>"readline"</code> per fare in modo che <code>Ctrl+W</code> nel prompt elimini fino allo spazio bianco precedente, come fa Bash, invece di fermarsi alla punteggiatura come <code>/</code></div>

99 <div>Su Windows nativo, le tue sessioni Claude Code possono ora <a href="/docs/it/cross-session-messaging#availability">messaggiarsi l'una con l'altra</a> con <code>SendMessage</code> e trovarsi con <code>ListAgents</code>, come su macOS e Linux</div>

100 <div>I runner self-hosted accettano `--defer-shutdown-max-min`, che <a href="/docs/it/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal">continua a servire le sessioni allegate</a> per un numero impostato di minuti dopo SIGTERM</div>

101 <div>I runner self-hosted accettano `--proxy-authorization-command` o `--proxy-authorization-file` per fornire un header <code>Proxy-Authorization</code> fresco per <a href="/docs/it/self-hosted-environments-deploy#authenticate-to-an-egress-proxy">proxy di uscita che ne richiedono uno</a></div>

102 </div>

103</div>

104

105[Changelog completo per v2.1.234–v2.1.239 →](/docs/en/changelog#2-1-234)

workflows.md +45 −37

Details

96La vista di progresso mostra ogni fase con i suoi conteggi di agenti, totali di token e tempo trascorso. Il piè di pagina elenca il tasto per ogni azione:96La vista di progresso mostra ogni fase con i suoi conteggi di agenti, totali di token e tempo trascorso. Il piè di pagina elenca il tasto per ogni azione:

97 97

98| Tasto | Azione |98| Tasto | Azione |

~~99| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ |~~99| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `↑` / `↓` | Selezionare una fase o un agente |100| `↑` / `↓` | Selezionare una fase o un agente |

101| `Invio` o `→` | Approfondire la fase selezionata, quindi in un agente per leggere il suo prompt, le recenti chiamate di strumenti e il risultato |101| `Invio` o `→` | Approfondire la fase selezionata, quindi in un agente per leggere il suo prompt, le recenti chiamate di strumenti e il risultato. Nel dettaglio, `Invio` espande o comprime |

102| `Esc` o `←` | Tornare indietro di un livello. Nelle versioni da v2.1.203 a v2.1.205, `←` non è tornato indietro da una fase o un agente; usa `Esc` su quelle versioni |102| `Esc` o `←` | Tornare indietro di un livello. Nelle versioni da v2.1.203 a v2.1.205, `←` non è tornato indietro da una fase o un agente; usa `Esc` su quelle versioni |

103| `j` / `k` | Scorrere all'interno del dettaglio dell'agente quando trabocca |103| `j` / `k` | Scorrere all'interno del dettaglio dell'agente quando trabocca |

104| `f` | Filtrare l'elenco degli agenti nella fase selezionata per stato. Premi di nuovo per ciclare |104| `f` | Filtrare l'elenco degli agenti nella fase selezionata per stato. Premi di nuovo per ciclare |

107| `r` | Riavviare l'agente in esecuzione selezionato |107| `r` | Riavviare l'agente in esecuzione selezionato |

108| `s` | [Salvare](#save-the-workflow-for-reuse) lo script dell'esecuzione come comando |108| `s` | [Salvare](#save-the-workflow-for-reuse) lo script dell'esecuzione come comando |

109 109

110Il dettaglio dell'agente elenca il prompt dell'agente, le sue recenti chiamate di strumenti e il suo risultato. Ogni chiamata mostra il suo stato, ad esempio ancora in esecuzione o non riuscito. Quando l'agente mantiene un elenco di attività proprio, il dettaglio lo mostra anche, con lo stato di ogni attività.

111

112Premi `Invio` per espandere il dettaglio. Il prompt e il risultato vengono quindi visualizzati per intero, e ogni chiamata elencata mostra il suo input e l'inizio del suo risultato.

113

110<h2 id="have-claude-write-a-workflow">114<h2 id="have-claude-write-a-workflow">

111 Far scrivere a Claude un flusso di lavoro115 Far scrivere a Claude un flusso di lavoro

112</h2>116</h2>

169 173

170Con ultracode attivo, Claude decide quando un compito merita un flusso di lavoro. Una singola richiesta può trasformarsi in diversi flussi di lavoro di fila: uno per comprendere il codice, uno per fare il cambiamento e uno per verificarlo. Questo si applica a ogni compito nella sessione, quindi ogni richiesta usa più token e richiede più tempo rispetto ai livelli di sforzo inferiori.174Con ultracode attivo, Claude decide quando un compito merita un flusso di lavoro. Una singola richiesta può trasformarsi in diversi flussi di lavoro di fila: uno per comprendere il codice, uno per fare il cambiamento e uno per verificarlo. Questo si applica a ogni compito nella sessione, quindi ogni richiesta usa più token e richiede più tempo rispetto ai livelli di sforzo inferiori.

171 175

172`/effort ultracode` dura per la sessione corrente; per avere ogni sessione che inizi con esso, imposta l'impostazione [`ultracode`](/docs/it/settings-reference#ultracode). Torna indietro con `/effort high` quando ritorni al lavoro di routine. È disponibile su modelli che supportano `xhigh` [sforzo](/docs/it/model-config#adjust-effort-level); su altri modelli il menu `/effort` non lo offre.176`/effort ultracode` dura per la sessione corrente; per avere ogni sessione che inizi con esso, imposta l'impostazione [`ultracode`](/docs/it/settings-reference#ultracode). Torna indietro con `/effort high` quando ritorni al lavoro di routine. Il menu `/effort` lo offre solo [quando ultracode è disponibile](/docs/it/model-config#when-ultracode-is-available).

173 177

174<h3 id="approve-the-plan-before-it-runs">178<h3 id="approve-the-plan-before-it-runs">

175 Approvare il piano prima che venga eseguito179 Approvare il piano prima che venga eseguito

344 348

345Il corpo è JavaScript semplice con `await` di livello superiore. `agent()` genera un subagente, `pipeline()` ne esegue uno per elemento in un elenco, e `parallel()` esegue un insieme di attività di agente contemporaneamente e attende che tutte si completino.349Il corpo è JavaScript semplice con `await` di livello superiore. `agent()` genera un subagente, `pipeline()` ne esegue uno per elemento in un elenco, e `parallel()` esegue un insieme di attività di agente contemporaneamente e attende che tutte si completino.

346 350

347Una chiamata `agent()` si risolve in `null` se la interrompi a metà esecuzione o se raggiunge un errore API irrecuperabile. `pipeline()` mantiene quel `null` nell'array dei risultati, motivo per cui l'esempio termina con `.filter(Boolean)` per eliminare quelle voci.351Una chiamata `agent()` si risolve in `null` se la interrompi a metà esecuzione o se raggiunge un errore API irrecuperabile. In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il classificatore può bloccare una chiamata `agent()` prima che il subagente inizi. Una chiamata bloccata si risolve in `null` e viene visualizzata nella vista di avanzamento dell'esecuzione con il motivo. `pipeline()` mantiene ogni `null` nell'array dei risultati, motivo per cui l'esempio termina con `.filter(Boolean)` per eliminare quelle voci.

348 352

349Se passi uno `schema` su una chiamata `agent()`, quel subagente restituisce JSON corrispondente alla forma invece di prosa. Claude Code verifica lo schema prima di avviare il subagente: quando può provare che lo schema contraddice se stesso, la chiamata fallisce con un errore che nomina la contraddizione, e il subagente non viene mai avviato. Una contraddizione che può provare è una chiave `required` che `additionalProperties: false` esclude.353Se passi uno `schema` su una chiamata `agent()`, quel subagente restituisce JSON corrispondente alla forma invece di prosa. Claude Code verifica lo schema prima di avviare il subagente: quando può provare che lo schema contraddice se stesso, la chiamata fallisce con un errore che nomina la contraddizione, e il subagente non viene mai avviato. Una contraddizione che può provare è una chiave `required` che `additionalProperties: false` esclude.

350 354

409 Gestire le esecuzioni413 Gestire le esecuzioni

410</h2>414</h2>

411 415

412Una volta che un'esecuzione inizia, la gestisci dalla vista `/workflows`, o espandendo la sua riga di progresso nel pannello attività sotto la casella di input.416Una volta avviata un'esecuzione, la gestisci dalla vista `/workflows`, oppure espandendo la sua linea di progresso nel pannello attività sotto la casella di input.

413 417

414Quando fermi un'esecuzione, rimane nel pannello attività mentre uno qualsiasi dei processi dei suoi agenti è ancora in esecuzione. Se la fermi di nuovo, Claude Code invia nuovamente segnali a quei processi.418Quando interrompi un'esecuzione, rimane nel pannello attività finché uno qualsiasi dei processi dei suoi agenti è ancora in esecuzione. Se la interrompi di nuovo, Claude Code invia nuovamente i segnali a quei processi.

415 419

416<h3 id="resume-after-a-pause">420<h3 id="resume-after-a-pause">

417 Riprendere dopo una pausa421 Riprendere dopo una pausa

418</h3>422</h3>

419 423

420Riprendi un'esecuzione in pausa da `/workflows` selezionandola e premendo `p`. Per un'esecuzione che hai fermato, chiedi a Claude di riavviare il flusso di lavoro con lo stesso script. Se gli agenti dall'esecuzione fermata non sono ancora usciti, Claude Code rifiuta il riavvio finché non lo fanno, quindi una seconda copia di quegli agenti non può essere eseguita insieme a loro.424Riprendi un'esecuzione in pausa da `/workflows` selezionandola e premendo `p`. Per un'esecuzione che hai interrotto, chiedi a Claude di riavviare il workflow con lo stesso script. Se gli agenti dell'esecuzione interrotta non sono ancora usciti, Claude Code rifiuta il riavvio finché non lo fanno, in modo che una seconda copia di quegli agenti non possa essere eseguita insieme a loro.

421 425

422Claude Code riproduce l'esecuzione nell'ordine in cui gli agenti hanno iniziato, e ogni agente restituisce il suo risultato salvato o viene eseguito di nuovo:426Claude Code riproduce l'esecuzione nell'ordine in cui gli agenti sono stati avviati, e ogni agente restituisce il suo risultato salvato oppure viene eseguito di nuovo:

423 427

424* **Completato**: restituisce il suo risultato salvato. Il primo agente il cui prompt differisce dall'esecuzione precedente, perché hai modificato lo script o un agente precedente ha restituito qualcosa di diverso, viene eseguito di nuovo, così come ogni agente dopo di esso, anche quelli che hanno completato.428* **Completato**: restituisce il suo risultato salvato. Il primo agente il cui prompt differisce dall'esecuzione precedente, perché hai modificato lo script o un agente precedente ha restituito qualcosa di diverso, viene eseguito di nuovo, così come ogni agente dopo di esso, anche quelli che erano completati.

425* **Ancora in esecuzione quando hai fermato**: ricomincia da capo. Fermare l'intera esecuzione non conta alcun agente come fallito.429* **Ancora in esecuzione quando hai interrotto**: ricomincia. Interrompere l'intera esecuzione non conta alcun agente come non riuscito.

426* **Fallito**: viene eseguito di nuovo, così come ogni agente che ha iniziato dopo di esso, anche quelli che hanno completato. Fermare un solo agente, selezionandolo in [`/workflows`](#watch-the-run) e premendo `x`, conta come fallimento.430* **Non riuscito**: viene eseguito di nuovo, così come ogni agente che è stato avviato dopo di esso, anche quelli che erano completati. Interrompere un solo agente, selezionandolo in [`/workflows`](#watch-the-run) e premendo `x`, conta come non riuscito.

427 431

428Quest'ultimo caso significa che un fallimento nel mezzo di un fan-out riesegue il lavoro che era già terminato. Se uno script avvia A, B, C e D in quell'ordine e B fallisce, il riavvio restituisce A dalla cache ed esegue di nuovo B, C e D.432Quest'ultimo caso significa che un errore nel mezzo di un fan-out riesegue il lavoro che era già terminato. Se uno script avvia A, B, C e D in quell'ordine e B non riesce, il riavvio restituisce A dalla cache ed esegue di nuovo B, C e D.

429 433

430Puoi riprendere un'esecuzione all'interno della stessa sessione di Claude Code. Quello che accade a un flusso di lavoro in esecuzione quando lasci la sessione dipende da come la lasci:434Puoi riprendere un'esecuzione all'interno della stessa sessione di Claude Code. Quello che accade a un workflow in esecuzione quando lasci la sessione dipende da come la lasci:

431 435

432* Se [metti la sessione in background](/docs/it/agent-view#what-carries-over-when-you-background), Claude Code riproduce l'esecuzione allo stesso modo nella sessione in background e la continua.436* Se [metti la sessione in background](/docs/it/agent-view#what-carries-over-when-you-background), Claude Code riproduce l'esecuzione allo stesso modo nella sessione in background e la continua.

433* Se esci da Claude Code mentre un flusso di lavoro è in esecuzione e [agent view è attivato](/docs/it/agent-view#from-inside-a-session), la finestra di dialogo di uscita offre `Move to background and exit`, che trasporta l'esecuzione allo stesso modo. Se scegli invece `Exit and stop tasks`, o l'opzione non è offerta, l'esecuzione si ferma con la sessione. Claude Code mantiene i risultati salvati dell'esecuzione nella directory di quella sessione in `~/.claude/projects/`, quindi una sessione che riprendi con `claude --resume` può riprodurli quando chiedi a Claude di riavviare il flusso di lavoro, mentre una sessione che avvii da zero non ha nulla da riprodurre e avvia il flusso di lavoro da capo.437* Se esci da Claude Code mentre un workflow è in esecuzione e [agent view è attivo](/docs/it/agent-view#from-inside-a-session), la finestra di dialogo di uscita offre `Move to background and exit`, che trasporta l'esecuzione allo stesso modo. Se scegli invece `Exit and stop tasks`, o l'opzione non è offerta, l'esecuzione si interrompe con la sessione. Claude Code mantiene i risultati salvati dell'esecuzione nella directory di quella sessione in `~/.claude/projects/`, quindi una sessione che riprendi con `claude --resume` può riprodurli quando chiedi a Claude di riavviare il workflow. In una sessione che avvii da zero, Claude non ha un'esecuzione precedente da riavviare e avvia il workflow da capo come una nuova esecuzione.

438

439In una [sessione cloud](/docs/it/claude-code-on-the-web), Claude Code salva anche i risultati dell'esecuzione con la cronologia della conversazione della sessione, che sopravvive quando la VM della sessione viene recuperata. Quando [riapri una tale sessione](/docs/it/claude-code-on-the-web#environment-expired) e chiedi a Claude di riavviare il workflow, gli agenti completati restituiscono ancora i loro risultati salvati.

440

441Nelle sessioni locali e cloud allo stesso modo, quando Claude riavvia un'esecuzione precedente e Claude Code non riesce a trovare affatto i risultati salvati di quell'esecuzione, il riavvio non riesce con un errore `nothing to resume` invece di avviare l'esecuzione da capo da solo. Chiedi a Claude di avviare il workflow da capo come una nuova esecuzione.

434 442

435<h3 id="cost">443<h3 id="cost">

436 Costo444 Costo

437</h3>445</h3>

438 446

439Un flusso di lavoro genera molti agenti, quindi una singola esecuzione può usare significativamente più token rispetto al lavoro attraverso lo stesso compito in conversazione. Le esecuzioni contano verso l'utilizzo del tuo piano e i limiti di velocità come qualsiasi altra sessione.447Un workflow genera molti agenti, quindi una singola esecuzione può utilizzare significativamente più token rispetto al lavoro attraverso lo stesso compito in conversazione. Le esecuzioni contano verso l'utilizzo del tuo piano e i limiti di velocità come qualsiasi altra sessione.

440 448

441Per valutare la spesa prima di impegnarsi in un compito di grandi dimensioni, esegui il flusso di lavoro su una piccola porzione prima: una directory invece dell'intero repository, o una domanda ristretta invece di una ampia. La vista `/workflows` mostra l'utilizzo dei token di ogni agente mentre l'esecuzione progredisce, e puoi fermare l'esecuzione lì in qualsiasi momento, solitamente senza perdere il lavoro completato. [Riprendere dopo una pausa](#resume-after-a-pause) copre quello che un'esecuzione fermata mantiene. I [limiti degli agenti](#behavior-and-limits) del runtime limitano quanti agenti una singola esecuzione può generare, il che limita il costo di uno script fuori controllo. Per mantenere le esecuzioni a meno agenti, scegli la linea guida sulla dimensione `small` [](#set-a-size-guideline).449Per valutare la spesa prima di impegnarsi in un compito di grandi dimensioni, esegui il workflow su una piccola porzione per prima: una directory invece dell'intero repository, o una domanda ristretta invece di una ampia. La vista `/workflows` mostra l'utilizzo dei token di ogni agente mentre l'esecuzione progredisce, e puoi interrompere l'esecuzione lì in qualsiasi momento, solitamente senza perdere il lavoro completato. [Riprendere dopo una pausa](#resume-after-a-pause) copre quello che un'esecuzione interrotta mantiene. I [limiti degli agenti](#behavior-and-limits) del runtime limitano quanti agenti una singola esecuzione può generare, il che limita il costo di uno script fuori controllo. Per mantenere le esecuzioni a meno agenti, scegli la linea guida di dimensione `small` [](#set-a-size-guideline).

442 450

443Claude Code inoltre segnala un'esecuzione che cresce insolitamente. Quando un flusso di lavoro pianifica più di 25 agenti, o il suo totale di token previsto supera 1,5 milioni, la sua riga di progresso nel pannello attività sotto la casella di input mostra un avviso `Large workflow`. L'avviso ti indirizza a [`/workflows`](#watch-the-run), dove puoi fermare l'esecuzione.451Claude Code contrassegna anche un'esecuzione che cresce insolitamente grande. Quando un workflow pianifica più di 25 agenti, o il suo totale di token previsto supera 1,5 milioni, la sua linea di progresso nel pannello attività sotto la casella di input mostra un avviso `Large workflow`. L'avviso ti indirizza a [`/workflows`](#watch-the-run), dove puoi interrompere l'esecuzione.

444 452

445L'avviso è consultivo: non mette in pausa o limita l'esecuzione. Due impostazioni cambiano quando lo vedi:453L'avviso è consultivo: non mette in pausa o limita l'esecuzione. Due impostazioni cambiano quando lo vedi:

446 454

447* Se scegli una [linea guida sulla dimensione](#set-a-size-guideline) tu stesso, il numero di agenti della linea guida sostituisce la soglia di 25 agenti. La linea guida predefinita incorporata lascia la soglia a 25.455* Se scegli una [linea guida di dimensione](#set-a-size-guideline) tu stesso, il suo conteggio di agenti sostituisce la soglia di 25 agenti. La linea guida predefinita incorporata lascia la soglia a 25.

448* Le sessioni con [ultracode](#let-claude-decide-with-ultracode) attivato non mostrano l'avviso, perché attivare ultracode già ti consente di optare per esecuzioni di grandi dimensioni.456* Le sessioni con [ultracode](#let-claude-decide-with-ultracode) attivo non mostrano l'avviso, perché attivare ultracode già ti consente di optare per esecuzioni di grandi dimensioni.

449 457

450Claude Code sceglie il modello di ogni agente del flusso di lavoro nello stesso [ordine che usa per i subagenti](/docs/it/sub-agents#choose-a-model). Un modello che lo script nomina per una fase conta come il modello per invocazione in quell'ordine. Quando nient'altro ne assegna uno, l'agente viene eseguito sul modello della tua sessione.458Claude Code sceglie il modello di ogni agente del workflow nello stesso [ordine che utilizza per i subagenti](/docs/it/sub-agents#choose-a-model). Un modello che lo script nomina per una fase conta come il modello per invocazione in quell'ordine. Quando nient'altro ne assegna uno, l'agente viene eseguito sul modello della tua sessione.

451 459

452Per controllare il costo del modello:460Per controllare il costo del modello:

453 461

454* Controlla `/model` prima di un'esecuzione grande se di solito passi a un modello più piccolo per il lavoro di routine462* Controlla `/model` prima di un'esecuzione di grandi dimensioni se di solito passi a un modello più piccolo per il lavoro di routine

455* Chiedi a Claude di usare un modello più piccolo per le fasi che non hanno bisogno di quello più forte quando descrivi il compito463* Chiedi a Claude di utilizzare un modello più piccolo per le fasi che non hanno bisogno di quello più forte quando descrivi il compito

456 464

457Quando l'[allowlist `availableModels`](/docs/it/model-config#restrict-model-selection) della tua organizzazione blocca un modello che lo script richiede per un agente, quell'agente viene eseguito su un modello sostituito invece, seguendo le stesse [regole di sostituzione dei subagenti](/docs/it/sub-agents#choose-a-model). La vista di progresso dell'esecuzione in [`/workflows`](#watch-the-run) mostra un avviso che nomina sia i modelli richiesti che quelli sostituiti.465Quando la lista di autorizzazione [`availableModels`](/docs/it/model-config#restrict-model-selection) della tua organizzazione blocca un modello che lo script richiede per un agente, quell'agente viene eseguito su un modello sostituito invece, seguendo le stesse [regole di sostituzione dei subagenti](/docs/it/sub-agents#choose-a-model). La vista di progresso dell'esecuzione in [`/workflows`](#watch-the-run) mostra un avviso che nomina sia i modelli richiesti che quelli sostituiti.

458 466

459<h3 id="set-a-size-guideline">467<h3 id="set-a-size-guideline">

460 Imposta una linea guida sulla dimensione468 Impostare una linea guida di dimensione

461</h3>469</h3>

462 470

463Una linea guida sulla dimensione dice a Claude quanti agenti mirare quando scrive un flusso di lavoro dinamico. Claude Code invia la linea guida a Claude come consiglio, non come limite, quindi un prompt che richiede una scala diversa la sovrascrive comunque. Richiede Claude Code v2.1.202 o successivo.471Una linea guida di dimensione dice a Claude quanti agenti mirare quando scrive un workflow dinamico. Claude Code invia la linea guida a Claude come consiglio, non come limite, quindi un prompt che richiede una scala diversa la sostituisce comunque. Richiede Claude Code v2.1.202 o successivo.

464 472

465Ogni valore corrisponde a un numero di agenti:473Ogni valore corrisponde a un conteggio di agenti:

466 474

467| Valore | Numero di agenti a cui Claude mira |475| Valore | Conteggio di agenti a cui Claude mira |

468| :------------- | :-------------------------------------------------------------------- |476| :------------- | :------------------------------------------------------------ |

473 481

474Il valore predefinito è `medium`. Finché non scegli un valore, la riga `/config` mostra `medium (default)` e la riga `Running in background` del flusso di lavoro mostra `medium size (/config)`. Richiede Claude Code v2.1.219 o successivo; le versioni precedenti hanno come valore predefinito `unrestricted`.482L'impostazione predefinita è `medium`. Finché non scegli un valore, la riga `/config` mostra `medium (default)` e la linea `Running in background` del workflow mostra `medium size (/config)`. Richiede Claude Code v2.1.219 o successivo; le versioni precedenti hanno come impostazione predefinita `unrestricted`.

475 483

476Per cambiare la linea guida, scegli un valore per l'impostazione Dynamic workflow size in `/config`, o esegui `/config workflowSizeGuideline=small`. Su v2.1.219 e successivo, puoi anche impostare la chiave [`workflowSizeGuideline`](/docs/it/settings-reference#workflowsizeguideline) in qualsiasi file di impostazioni; quel valore ha la precedenza su `/config`, e Claude Code nasconde la riga `/config` mentre un file di impostazioni ne fornisce uno.484Per modificare la linea guida, scegli un valore per l'impostazione Dynamic workflow size in `/config`, oppure esegui `/config workflowSizeGuideline=small`. Su v2.1.219 e successivo, puoi anche impostare la chiave [`workflowSizeGuideline`](/docs/it/settings-reference#workflowsizeguideline) in qualsiasi file di impostazioni; quel valore ha la precedenza su `/config`, e Claude Code nasconde la riga `/config` mentre un file di impostazioni ne fornisce uno.

477 485

478Le modifiche hanno effetto al prompt successivo. I [limiti degli agenti del runtime](#behavior-and-limits) si applicano comunque indipendentemente dall'impostazione.486Le modifiche hanno effetto al prompt successivo. I [limiti degli agenti del runtime](#behavior-and-limits) si applicano comunque indipendentemente dall'impostazione.

479 487

480<h3 id="turn-workflows-off">488<h3 id="turn-workflows-off">

481 Disattivare i flussi di lavoro489 Disattivare i workflow

482</h3>490</h3>

483 491

484I flussi di lavoro sono disponibili nel CLI, nell'app Desktop, nelle estensioni IDE, [modalità non interattiva](/docs/it/headless) con `claude -p`, e nell'[Agent SDK](/docs/it/agent-sdk/overview). Le stesse impostazioni di disabilitazione si applicano su ogni superficie.492I workflow sono disponibili nella CLI, nell'app Desktop, nelle estensioni IDE, nella [modalità non interattiva](/docs/it/headless) con `claude -p`, e nell'[Agent SDK](/docs/it/agent-sdk/overview). Le stesse impostazioni di disabilitazione si applicano su ogni superficie.

485 493

486Per disattivare i flussi di lavoro per te:494Per disattivare i workflow per te stesso:

487 495

488* Attiva/disattiva Dynamic workflows in `/config`. Persiste tra le sessioni.496* Disattiva Dynamic workflows in `/config`. Persiste tra le sessioni.

489* Imposta `"disableWorkflows": true` in `~/.claude/settings.json`. Persiste tra le sessioni.497* Imposta `"disableWorkflows": true` in `~/.claude/settings.json`. Persiste tra le sessioni.

490* Imposta `CLAUDE_CODE_DISABLE_WORKFLOWS=1`. Letto all'avvio, quindi si applica ovunque lo imposti.498* Imposta `CLAUDE_CODE_DISABLE_WORKFLOWS=1`. Letto all'avvio, quindi si applica ovunque lo imposti.

491 499

492Per disattivare i flussi di lavoro per tutta la tua organizzazione, imposta `"disableWorkflows": true` in [impostazioni gestite](/docs/it/server-managed-settings), o usa l'interruttore sulla pagina [impostazioni amministratore di Claude Code](https://claude.ai/admin-settings/claude-code).500Per disattivare i workflow per l'intera organizzazione, imposta `"disableWorkflows": true` nelle [impostazioni gestite](/docs/it/server-managed-settings), oppure utilizza l'interruttore nella pagina [impostazioni admin di Claude Code](https://claude.ai/admin-settings/claude-code).

493 501

494Quando i flussi di lavoro sono disabilitati, i comandi di flusso di lavoro in bundle e la skill `/workflow-authoring` non sono disponibili, la parola chiave `ultracode` non attiva più un'esecuzione, e `ultracode` viene rimosso dal menu `/effort`.502Quando i workflow sono disabilitati, i comandi workflow in bundle e la skill `/workflow-authoring` non sono disponibili, la parola chiave `ultracode` non attiva più un'esecuzione, e `ultracode` viene rimosso dal menu `/effort`.

495 503

496<h2 id="related-resources">504<h2 id="related-resources">

497 Risorse correlate505 Risorse correlate

Documentation 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC