Applicazione desktop

Sfrutta al massimo Claude Code Desktop: sessioni parallele con isolamento Git, layout dei pannelli drag-and-drop, terminale integrato e editor di file, chat laterali, utilizzo del computer, Dispatch sessioni dal tuo telefono, revisione visiva dei diff, anteprime delle app, monitoraggio dei PR, connettori e configurazione aziendale.

L'app Claude Desktop ha tre schede: Chat per le conversazioni, Cowork per Dispatch e lavoro agentico più lungo, e Code per lo sviluppo software. Questa pagina è il riferimento per la scheda Code.

Scarica per macOS

Build universale per Intel e Apple Silicon

Scarica per Windows

Per processori x64

Ottieni Claude per Linux (beta)

apt o .deb per Ubuntu e Debian

Per Windows ARM64, scarica l'installer ARM64. Su Linux, installa con apt; vedi Claude Desktop su Linux.

Dopo l'installazione, avvia Claude, accedi e fai clic sulla scheda Code. Per una procedura dettagliata della tua prima sessione, consulta la guida introduttiva.

Nella scheda Code, ogni conversazione è una sessione: ha la sua propria cronologia chat e cartella di progetto, indipendente da qualsiasi altra sessione. La barra laterale elenca le tue sessioni e ti consente di eseguirne diverse in parallelo. All'interno di una sessione puoi:

• Rivedere e commentare i diff, quindi monitorare il PR risultante attraverso CI
• Visualizzare in anteprima la tua app in esecuzione nel riquadro Browser mentre Claude verifica le sue stesse modifiche, e aprire siti esterni accanto ad esso
• Guardare Claude eseguire e testare la tua app iOS nel riquadro iOS Simulator
• Organizzare i pannelli per la chat, diff, browser, terminale e editor di file uno accanto all'altro
• Porre una domanda laterale che utilizza il contesto della sessione senza deviare da essa
• Consentire a Claude di controllare, messaggiare o archiviare le tue altre sessioni
• Connettere strumenti esterni come GitHub, Slack e Linear
• Consentire a Claude di aprire app e controllare il tuo schermo
• Eseguire sulla tua macchina, nel cloud, o su SSH

Per lavoro ricorrente pianificato, scorciatoie da tastiera, o invio di attività dal tuo telefono, consulta le pagine e le sezioni collegate. Se utilizzi già il CLI basato su terminale, consulta il confronto CLI per vedere cosa si trasferisce.

Avvia una sessione

Prima di inviare il tuo primo messaggio, scegli l'ambiente, la cartella del progetto, la modalità di permesso e il modello nella riga sotto la casella del prompt:

• Ambiente: usa il selettore dell'ambiente, il primo controllo della riga, per scegliere dove Claude viene eseguito. Vedi configurazione dell'ambiente.
  • Se una nuova sessione non ha il selettore dell'ambiente sotto la casella del prompt, segui i passaggi del layout precedente.
• Cartella del progetto: fai clic sul controllo della cartella del progetto, accanto al selettore dell'ambiente, per scegliere la cartella su cui Claude lavora.
  • Sessione cloud: seleziona dei repository invece di una cartella
  • Ambiente locale o SSH salvato: l'ambiente contiene già le sue cartelle, quindi la riga non mostra alcun controllo della cartella del progetto. Per cambiare le cartelle, modifica l'ambiente.
• Modalità di permesso: usa il selettore di modalità per scegliere quanta autonomia ha Claude. Puoi cambiare la modalità di permesso durante la sessione.
• Modello: scegli un modello dal selettore del modello verso l'estremità destra della riga. Puoi cambiare il modello durante la sessione.

Digita il tuo compito e premi Invio per iniziare. Ogni sessione traccia il suo proprio contesto e le modifiche in modo indipendente.

Lavora con il codice

Dai a Claude il contesto giusto, controlla quanto fa da solo e rivedi cosa ha cambiato.

Usa la casella del prompt

Digita quello che vuoi che Claude faccia e premi Invio per inviare. Claude legge i file del tuo progetto, apporta modifiche ed esegue comandi in base alla tua modalità di permesso. Puoi interrompere Claude in qualsiasi momento: fai clic sul pulsante di arresto per interrompere immediatamente, oppure digita una correzione e premi Invio per inviarla senza interrompere l'azione in corso. Claude legge la correzione non appena l'azione corrente si completa e si adatta prima del suo passo successivo.

Fai clic sul pulsante + accanto alla casella del prompt per allegati di file, skill, connettori e plugin.

Accetta un prompt suggerito

Dopo che Claude risponde, la scheda Code può mostrare un prompt successivo suggerito come testo grigio nella casella del prompt vuota. Claude Code genera ogni suggerimento dalla tua conversazione con una breve richiesta in background che viene conteggiata nei limiti di utilizzo del tuo piano o nei costi dell'API.

• Usa il suggerimento: premi Tab o Freccia destra per inserirlo nella casella del prompt, modificalo se vuoi, poi premi Invio per inviarlo. Premere Invio prima di accettare il suggerimento non lo invia.
• Scrivi il tuo prompt: inizia a digitare. Il suggerimento viene mostrato solo mentre la casella del prompt è vuota e non ha file allegati.

Vai su Impostazioni > Claude Code e disattiva Prompt suggestions sotto Sessions per interrompere i suggerimenti in ogni sessione a partire dalla prossima volta che viene avviata o ripresa.

Aggiungi file e contesto ai prompt

Per dare un file a Claude, menzionalo con @ o allegalo nella casella del prompt:

• @mention file: digita @ seguito da un nome di file per aggiungere un file al contesto della conversazione.
  • In una sessione cloud: @ può elencare i file solo dopo che hai inviato il tuo primo messaggio. Se @ non ne elenca nessuno, invia il tuo primo messaggio senza il file, poi menziona il file con @ nel messaggio successivo.
• Allega file: allega immagini, PDF e altri file al tuo prompt dal pulsante + accanto alla casella del prompt, o trascina e rilascia i file direttamente nel prompt. Questo è utile per condividere screenshot di bug, mockup di design o documenti di riferimento.
  • In una sessione WSL: se il menu + mostra Add image invece di Add files or photos, puoi allegare solo immagini. Per dare a Claude qualsiasi altro file dalla cartella della sessione, menzionalo con @.

Scegli una modalità di permesso

Le modalità di permesso controllano quanta autonomia ha Claude durante una sessione: se chiede prima di modificare file, eseguire comandi o entrambi. Puoi cambiare modalità di permesso in qualsiasi momento usando il selettore di modalità nella riga sotto la casella del prompt. Per approvare ogni modifica tu stesso, passa a Manual.

Per impostare una modalità predefinita per le nuove sessioni locali, aggiungi permissions.defaultMode al tuo file di impostazioni. L'app desktop legge gli stessi file di impostazioni della CLI. Una modalità che scegli nel selettore viene ricordata per cartella e ha la precedenza su defaultMode per quella cartella, tranne Plan, che si applica solo alla sessione corrente.

Le versioni precedenti della scheda Code etichettavano queste modalità Ask permissions, Auto accept edits e Plan mode.

La modalità di permesso dontAsk è disponibile solo nella CLI.

[!TIP]

Inizia compiti complessi in Plan in modo che Claude mappi un approccio prima di apportare modifiche. Una volta approvato il piano, passa a Accept edits o Manual per eseguirlo. Vedi esplora prima, poi pianifica, poi codifica per ulteriori informazioni su questo workflow.

Le sessioni cloud supportano Accept edits, Plan e Auto. Accept edits corrisponde alla modalità default: le sessioni cloud pre-approvano le modifiche ai file, quindi il selettore mostra Accept edits invece di Manual. Bypass permissions non è disponibile nelle sessioni cloud, incluse le sessioni in un ambiente self-hosted.

Gli amministratori aziendali possono limitare quali modalità di permesso sono disponibili. Vedi configurazione aziendale per i dettagli.

Disponibilità della modalità auto

La modalità auto è disponibile a tutti gli utenti sull'API Anthropic e richiede Claude Opus 4.6 o successivo, Sonnet 4.6 o successivo, Haiku 5.5 o un modello Fable. Gli amministratori dell'organizzazione possono disattivare la modalità auto con la chiave disableAutoMode nelle impostazioni gestite.

Nelle distribuzioni Enterprise che instradano Desktop verso Agent Platform di Google Cloud, la modalità auto è anche disponibile per impostazione predefinita; vedi Modalità auto su Bedrock, Agent Platform o Foundry per i modelli supportati.

Anteprima della tua app

Claude può avviare un server di sviluppo e aprirlo nel riquadro Browser per verificare le sue modifiche. Questo funziona per app web frontend così come per server backend: Claude può testare endpoint API, visualizzare log del server e iterare su problemi che trova. Nella maggior parte dei casi, Claude avvia il server automaticamente dopo aver modificato i file del progetto. Puoi anche chiedere a Claude di visualizzare un'anteprima in qualsiasi momento. Per impostazione predefinita, Claude verifica automaticamente le modifiche dopo ogni modifica.

In una sessione locale, fai clic su un percorso HTML, PDF o video nella chat per aprirlo nel riquadro Browser.

[!NOTE]

In una sessione SSH, Claude non può aprire la tua app nel riquadro Browser, perché lì non ha a disposizione gli strumenti del riquadro. Per vedere l'app tu stesso, inoltra la sua porta al tuo computer.

Se il riquadro Browser non è aperto dopo che Claude avvia un server in una sessione locale, fai clic su Open nella scheda del server nella chat.

Dal riquadro Browser, puoi:

• Interagire con la tua app in esecuzione direttamente nel riquadro Browser
• Guardare Claude verificare automaticamente le sue stesse modifiche: scatta screenshot, ispeziona il DOM, fa clic su elementi, compila moduli e corregge i problemi che trova
• Avviare o arrestare server, o arrestarli tutti contemporaneamente, dal menu Dev servers nell'intestazione del riquadro Browser
• Scegliere se il Browser mantiene i cookie dopo che esci dall'app con Keep cookies nel menu ⋮ del riquadro Browser, in modo da non dover effettuare di nuovo l'accesso durante lo sviluppo

Claude crea la configurazione iniziale del server in base al tuo progetto. Se la tua app utilizza un comando dev personalizzato, modifica .claude/launch.json per adattarlo alla tua configurazione. Vedi Configura server di anteprima per il riferimento completo.

Per cancellare i dati salvati del Browser, seleziona Clear browsing data nel menu ⋮ del riquadro Browser. Per disattivare completamente il Browser, disattiva Browser tools in Impostazioni > Claude Code.

Sfoglia siti esterni

Il riquadro Browser è un browser a schede, quindi puoi aprire documentazione, tracker di problemi o qualsiasi altro sito accanto alla tua app in esecuzione. Per aprire il Browser, premi Cmd+Maiusc+B su macOS o Ctrl+Maiusc+B su Windows, oppure fai clic su Browser nella barra del titolo della sessione. Puoi accedere ai siti nel riquadro, inclusi flussi di accesso popup come Google OAuth.

La prima volta che fai clic su un collegamento esterno nella chat, una finestra di dialogo chiede se i collegamenti devono aprirsi nel riquadro Browser o nel tuo browser predefinito. Per cambiare la tua scelta in seguito, usa Open links in built-in browser nel menu ⋮ del riquadro Browser. Cmd-clic su macOS o Ctrl-clic su Windows apre un collegamento direttamente nel tuo browser predefinito.

Claude può leggere e interagire con pagine esterne usando gli stessi strumenti che usa per verificare la tua app, con due controlli di sicurezza aggiuntivi:

• I classificatori di sicurezza esaminano le azioni di scrittura di Claude su pagine esterne, come fare clic e digitare, in ogni modalità di permesso. Questi sono gli stessi classificatori che usa la modalità auto, e quando segnalano un'azione, ricevi una richiesta di permesso indipendentemente dalla modalità.
• Nelle modalità di permesso diverse da Auto e Bypass permissions, un controllo dell'allowlist dei domini si applica anche prima che Claude navighi verso un nuovo sito.

Approva le azioni di Claude su un sito

La prima volta che Claude agisce su un sito esterno, appare una scheda di permesso e Claude attende la tua scelta: Allow once, Always allow o Deny. Allow once approva l'azione senza salvare nulla. Always allow salva l'approvazione per quel sito sul tuo dispositivo, e puoi revocarla in Impostazioni. Ogni sito ha bisogno della sua propria approvazione, inclusi i sottodomini. I tuoi server di sviluppo locali e i file del progetto non hanno bisogno di approvazione, quindi auto-verify continua a funzionare senza richieste di permesso.

Anche su un sito approvato, Claude non acquisterà articoli, creerà account o aggirerà CAPTCHA senza il tuo input. La navigazione nel riquadro Browser utilizza lo stesso modello di sicurezza dell'estensione Claude in Chrome. Vedi Utilizzo di Claude in Chrome in sicurezza per come Claude gestisce siti sensibili e azioni rischiose.

Scegli tra il Browser e l'estensione Chrome

Il riquadro Browser utilizza un profilo browser pulito, separato dal tuo browser personale, senza nessuno dei tuoi accessi salvati o cronologia. Usalo per costruire e testare la tua app e per siti che non hanno bisogno della tua identità. Quando vuoi che Claude agisca come te nelle tue sessioni di accesso, usa invece l'estensione Claude in Chrome, che condivide lo stato di accesso del tuo browser.

Limita la navigazione esterna per la tua organizzazione

Il Browser segue gli stessi controlli di allowlist e blocklist dei siti dell'estensione Claude in Chrome. Se la tua organizzazione ha già configurato quelle liste per l'estensione, il Browser le rispetta automaticamente. Gli amministratori possono anche disattivare gli strumenti di Claude su pagine esterne con l'impostazione gestita browserExternalPageTools. Con gli strumenti disabilitati, gli utenti possono ancora navigare verso siti esterni; gli strumenti di Claude non possono leggerli o agire su di essi.

Per disattivare completamente la navigazione esterna, imposta l'impostazione gestita disableBrowserExternalNavigation su true. Questo blocca tutta la navigazione esterna nel Browser, inclusi i siti nell'allowlist della tua organizzazione; i server dev localhost e le anteprime di file continuano a funzionare. Usa browserExternalPageTools per consentire agli utenti di continuare a sfogliare siti esterni senza gli strumenti di Claude, e disableBrowserExternalNavigation per bloccare i siti esterni sia per gli utenti che per Claude.

Rivedi le modifiche con la visualizzazione diff

Dopo che Claude apporta modifiche al tuo codice, la visualizzazione diff ti consente di rivedere le modifiche file per file prima di creare una pull request. Per aprire la visualizzazione diff, fai clic sui conteggi delle righe, come +12 -1, nella scheda Changes del pannello dei dettagli della sessione. Puoi anche fare clic su Changes nella barra del titolo della sessione.

Per commentare righe specifiche, fai clic su qualsiasi riga nel diff per aprire una casella di commento. Digita il tuo feedback e premi Invio per aggiungere il commento. Dopo aver aggiunto commenti a più righe, invia tutti i commenti contemporaneamente:

• macOS: premi Cmd+Invio
• Windows: premi Ctrl+Invio

Claude legge i tuoi commenti e apporta le modifiche richieste, che appaiono come un nuovo diff che puoi rivedere.

Rivedi il tuo codice

Per far rivedere a Claude le tue modifiche prima di eseguire il commit, inserisci /code-review nella casella del prompt. I risultati arrivano nella conversazione quando la revisione è completata.

Nelle sessioni locali, SSH e WSL, i risultati appaiono come una scheda Code review, raggruppati per file. Usa la scheda per agire su di essi:

• Fai clic su Walk through in diff per aprire la visualizzazione diff ed esaminare i risultati uno alla volta. Un risultato nel diff corrente appare alla sua riga, dove puoi fare clic su Fix this one o ignorarlo.
• Fai clic su Apply fixes per chiedere a Claude di correggere i risultati ancora aperti.

In qualsiasi sessione, puoi anche chiedere a Claude nella casella del prompt di correggere ciò che la revisione ha trovato. Per sapere cosa cerca /code-review e quali argomenti accetta, vedi Rivedi localmente con /code-review.

Monitora lo stato della pull request

Per far correggere a Claude i controlli non riusciti, o per far eseguire a GitHub il merge della pull request, attiva Auto-fix o Merge when ready. Dopo aver aperto una pull request, questa appare nella scheda Changes del pannello dei dettagli della sessione con lo stato dei suoi controlli CI. Apri il menu ⋮ accanto al suo titolo:

• Auto-fix: in una sessione locale, Claude gestisce anche i nuovi commenti di revisione lasciati da qualcuno diverso da te. L'autore del commento deve essere il proprietario del repository, un membro dell'organizzazione, un collaboratore o una GitHub App.
• Merge when ready: attiva l'auto-merge di GitHub per la PR. In una sessione locale, Desktop richiede uno squash merge a meno che il branch di base non utilizzi una merge queue.
  • Nelle sessioni SSH e WSL: Merge when ready è disabilitato, quindi attiva l'auto-merge per la pull request su GitHub
  • Se il repository non consente l'auto-merge: Merge when ready non si attiva, quindi abilita prima l'auto-merge nelle impostazioni del tuo repository GitHub
• Layout precedente: una volta che la sessione ha una pull request, fai clic su CI nella sua barra di stato.

Per archiviare la sessione automaticamente una volta che la PR viene sottoposta a merge o chiusa, attiva auto-archive in Impostazioni > Claude Code.

[!NOTE]

Il monitoraggio delle PR richiede che GitHub CLI (gh) sia installato e autenticato sulla tua macchina. Se gh non è installato, Desktop ti chiede di installarlo la prima volta che tenti di creare una PR.

In una sessione SSH, configura git e gh sulla macchina remota prima di fare clic su Create PR, perché Claude esegue lì il push del branch ed esegue gh pr create. Installa tu stesso gh lì, perché Desktop non te lo chiede in una sessione SSH. Poi verifica lì che git push funzioni e che gh auth status indichi che hai effettuato l'accesso.

Organizza il workspace

La scheda Code è costruita attorno a pannelli che puoi organizzare in qualsiasi layout: chat, diff, browser, terminale, file, plan, tasks e subagent, insieme al Simulatore iOS su macOS. Trascina un pannello dal suo header per riposizionarlo, o trascina un bordo del pannello per ridimensionarlo. Premi Cmd+\ su macOS o Ctrl+\ su Windows per chiudere il pannello focalizzato. Fai clic su Terminal, Changes o Browser nella barra del titolo della sessione per aprire il pannello del terminale, del diff o Browser. Il menu ⋮ accanto a essi apre altri pannelli, come Files, e contiene quei pulsanti quando la finestra è troppo stretta per mostrarli.

Per lavorare su più schermi, estrai un pannello come il diff o il terminale in una finestra propria e riancoralo quando hai finito. Claude continua a lavorare nella finestra principale.

[!NOTE]

Il layout del pannello, il terminale, l'editor di file e le modalità di visualizzazione in questa sezione richiedono Claude Desktop v1.2581.0 o successivo. Apri Claude > Check for Updates… su macOS o Help > Check for Updates… su Windows per aggiornare.

Visualizza i dettagli della sessione

Il pannello dei dettagli della sessione è un insieme di schede accanto alla chat che mostrano dove viene eseguita la sessione, cosa ha modificato e cosa sta eseguendo. Il pannello appare dopo che avvii una sessione, purché la chat sia abbastanza larga da contenerlo.

Nascondi o mostra il pannello dei dettagli della sessione

Per nascondere o mostrare il pannello, fai clic su Hide session rail o Show session rail nella barra del titolo della sessione, oppure nel menu ⋮ della barra quando la finestra è stretta. Se ancora non vedi il pannello, verifica quale layout della scheda Code hai.

Esegui comandi nel terminale

Il terminale integrato ti consente di eseguire comandi insieme alla tua sessione senza passare a un'altra app. Fai clic su Terminal nella barra del titolo della sessione o premi Ctrl+` su macOS o Windows. Il terminale si apre nella directory di lavoro della tua sessione e condivide lo stesso ambiente di Claude, quindi comandi come npm test o git status vedono gli stessi file che Claude sta modificando. Per aprire una seconda scheda del terminale, fai clic su + nell'header del pannello del terminale o fai clic con il pulsante destro su una cartella nella chat per scegliere Open in terminal.

Se una sessione WSL non ha un terminale, consulta Se il terminale o i connettori non sono disponibili. Il terminale è disponibile nelle sessioni locali e SSH, con una limitazione sulle macchine remote Windows.

Apri e modifica file

Per aprire un file menzionato da Claude, fai clic sul suo percorso nella chat.

Per modificare tu stesso un file, usa il pannello file:

• Sessioni locali: puoi modificare i file all'interno della directory di lavoro della sessione, tranne alcuni di sola visualizzazione come .mcp.json e .claude/settings.json. Per modificarne uno, aprilo in un'altra app.
• Sessioni cloud, SSH e WSL: il pannello file è di sola visualizzazione, quindi chiedi a Claude di apportare le modifiche.

Salva le modifiche nel pannello file

Per impostazione predefinita, le modifiche nel pannello file vengono salvate automaticamente, quindi il pannello non mostra alcun pulsante Save. Per salvare tu stesso le modifiche, deseleziona Auto save nel menu ⋮ del pannello. Con Auto save disattivato, fai clic su Save dopo aver modificato un file per scrivere le modifiche, o su Cancel per annullarle.

Se il pannello avverte che il file è cambiato su disco, fai clic su Override per sovrascrivere la versione su disco con le tue modifiche, o su Discard per scartare le tue modifiche.

Apri file in altre app

Fai clic con il pulsante destro su qualsiasi percorso di file nella chat, nel visualizzatore diff o nel pannello file per aprire un menu di contesto:

• Attach as context: aggiungi il file al tuo prossimo prompt
• Open in: apri il file in un editor installato come VS Code, Cursor o Zed
• Show in Finder su macOS, Show in Explorer su Windows: apri la cartella contenente
• Copy path: copia il percorso assoluto negli appunti

Cambia modalità di visualizzazione

Le modalità di visualizzazione controllano quanti dettagli appaiono nella trascrizione della chat. Per cambiare modalità di visualizzazione, apri il menu della sessione dal cursore accanto al titolo della sessione e seleziona Transcript view, o premi Ctrl+O su macOS o Windows per scorrere tra loro. La modalità Thinking appare nel menu solo dopo che Claude ha prodotto ragionamento nella sessione che stai visualizzando.

Usa Thinking per seguire il ragionamento di Claude con le chiamate agli strumenti ancora compresse. Usa Verbose quando esegui il debug del motivo per cui Claude ha intrapreso una particolare azione. Le versioni di Claude Desktop precedenti a 1.46388.1 elencano anche una modalità Summary, e una sessione ancora impostata su Summary si apre in Normal una volta aggiornato.

Scorciatoie da tastiera

Premi Cmd+/ su macOS o Ctrl+/ su Windows per vedere tutte le scorciatoie disponibili nella scheda Code. La tabella in questa sezione mostra i tasti di macOS. Su Windows e Linux, sostituisci questi tasti:

• Cmd+Option: premi Alt
• Cmd: premi Ctrl

Il ciclo della sessione, l'interruttore del terminale e l'interruttore della modalità di visualizzazione usano Ctrl su ogni piattaforma.

Queste scorciatoie si applicano alla scheda Code. In Desktop, Shift+Tab non scorre le modalità di permesso come avviene nella modalità interattiva del terminale.

Controlla l'utilizzo

Fai clic sull'anello di utilizzo accanto al selettore di modello per vedere l'utilizzo della finestra di contesto corrente e l'utilizzo del piano per il periodo. L'utilizzo del contesto è per sessione; l'utilizzo del piano è condiviso su tutte le tue superfici Claude Code.

Lascia che Claude usi il tuo computer

L'utilizzo del computer consente a Claude di aprire le tue app, controllare lo schermo e lavorare direttamente sulla tua macchina come faresti tu. Chiedi a Claude di interagire con uno strumento desktop che non ha CLI, o automatizzare qualcosa che funziona solo tramite una GUI. Per eseguire e testare app iOS, Desktop apre il riquadro dedicato iOS Simulator invece di controllare lo schermo; il riquadro funziona senza abilitare l'utilizzo del computer.

[!NOTE]

L'utilizzo del computer è un'anteprima di ricerca su macOS e Windows che richiede un piano Pro o Max. Non è disponibile su piani Team o Enterprise. L'app Claude Desktop deve essere in esecuzione.

L'utilizzo del computer è disabilitato per impostazione predefinita. Abilitalo in Impostazioni prima che Claude possa controllare lo schermo. Su macOS, devi anche concedere i permessi di Accessibilità e Registrazione dello schermo.

Su macOS, l'utilizzo del computer può anche essere eseguito in background: Claude lavora nelle app che hai approvato mentre continui a lavorare.

[!WARNING]

A differenza dello strumento Bash sandbox, l'utilizzo del computer viene eseguito sul tuo desktop effettivo con accesso a tutto ciò che approvi. Claude controlla ogni azione e contrassegna potenziali iniezioni di prompt dal contenuto sullo schermo, ma il limite di fiducia è diverso. Vedi la guida alla sicurezza dell'utilizzo del computer per le best practice.

Quando si applica l'utilizzo del computer

Claude ha diversi modi per interagire con un'app o un servizio, e l'utilizzo del computer è il più ampio e lento. Prova prima lo strumento più preciso:

• Se hai un connettore per un servizio, Claude usa il connettore.
• Se l'attività è un comando shell, Claude usa Bash.
• Se l'attività è lavoro nel browser e hai Claude in Chrome configurato, Claude usa quello.
• Se l'attività è eseguire o testare un'app iOS, Claude usa il riquadro iOS Simulator, che non utilizza il controllo dello schermo.
• Se nessuno di questi si applica, Claude usa l'utilizzo del computer.

I livelli di accesso per app rafforzano questo: i browser sono limitati a sola visualizzazione, e i terminali e gli IDE a solo clic, indirizzando Claude verso lo strumento dedicato anche quando l'utilizzo del computer è attivo. Il controllo dello schermo è riservato a cose che nient'altro può raggiungere, come app native, pannelli di controllo hardware, o strumenti proprietari senza un'API.

Abilita l'utilizzo del computer

L'utilizzo del computer è disabilitato per impostazione predefinita. Se chiedi a Claude di fare qualcosa che ne ha bisogno mentre è disabilitato, Claude ti dice che potrebbe fare l'attività se abiliti l'utilizzo del computer in Impostazioni.

1. Aggiorna l'app desktop

Assicurati di avere l'ultima versione di Claude Desktop. Su macOS e Windows, scarica o aggiorna su claude.com/download; su Linux, aggiorna tramite il tuo gestore di pacchetti (istruzioni). Quindi riavvia l'app.

2. Attiva l'interruttore

Nell'app desktop, vai a Impostazioni > Questo computer > Sistema. In Utilizzo del computer, attiva Abilita l'utilizzo del computer. Su Windows, l'interruttore ha effetto immediatamente e la configurazione è completa. Su macOS, continua al passaggio successivo.

Se non vedi l'interruttore, conferma che sei su macOS o Windows con un piano Pro o Max, quindi aggiorna e riavvia l'app.

3. Concedi i permessi macOS

Su macOS, concedi due permessi di sistema prima che l'interruttore abbia effetto:

• Accessibilità: consente a Claude di fare clic, digitare e scorrere
• Registrazione dello schermo: consente a Claude di vedere cosa c'è sullo schermo

La pagina Impostazioni mostra lo stato attuale di ogni permesso. Se uno è negato, fai clic sul badge per aprire il riquadro Impostazioni di sistema pertinente.

Permessi delle app

La prima volta che Claude ha bisogno di usare un'app, appare un prompt nella tua sessione. Fai clic su Allow for this session o Deny. Le approvazioni durano per la sessione corrente, o 30 minuti nelle sessioni generate da Dispatch.

Il prompt mostra anche quale livello di controllo Claude ottiene per quell'app. Questi livelli sono fissi per categoria di app e non possono essere modificati:

Le app con ampia portata, come terminali, Finder o File Explorer, e Impostazioni di sistema o Impostazioni, mostrano un avviso aggiuntivo nel prompt in modo che tu sappia cosa approvare loro concede.

La sezione Utilizzo del computer in Impostazioni > Questo computer > Sistema include queste opzioni:

• Denied apps: aggiungi app qui per rifiutarle senza chiedere. Claude potrebbe comunque influenzare un'app negata indirettamente tramite azioni in un'app consentita, ma non può interagire direttamente con l'app negata.
• Unhide apps when Claude finishes: quando l'utilizzo del computer non è in esecuzione in background, Claude nasconde le tue altre finestre mentre lavora in modo che interagisca solo con l'app approvata. Quando Claude finisce, le finestre nascoste vengono ripristinate a meno che non disattivi questa impostazione.

Gestisci le sessioni

Ogni sessione è una conversazione indipendente con il suo proprio contesto e modifiche. Puoi eseguire più sessioni in parallelo, aprire chat laterali, lasciare che Claude controlli e messaggi le tue altre sessioni, inviare il lavoro al cloud, o lasciare che Dispatch avvii sessioni per te dal tuo telefono.

Lavora in parallelo con le sessioni

Fai clic su + New nella barra laterale, o premi Cmd+N su macOS o Ctrl+N su Windows, per lavorare su più compiti in parallelo. Premi Ctrl+Tab e Ctrl+Shift+Tab per scorrere le sessioni nella barra laterale.

Per visualizzare due sessioni contemporaneamente, tieni premuto Cmd su macOS o Ctrl su Windows e fai clic su una sessione nella barra laterale. La sessione si apre in un secondo riquadro accanto a quello che hai già aperto. Mentre la divisione è attiva, facendo clic su un'altra sessione della barra laterale si sostituisce il riquadro che ha il focus. Premi Cmd+\ su macOS o Ctrl+\ su Windows per chiudere il riquadro con focus e tornare a una singola sessione.

Esegui una sessione nel suo worktree

In un progetto che è un repository Git, attiva Worktree prima di avviare una sessione per eseguirla nel suo worktree Git, una copia isolata del progetto. Per impostazione predefinita, Worktree è disattivato e Claude lavora direttamente nella cartella del progetto. Fai clic sul controllo della cartella del progetto nella riga sotto la casella del prompt e attiva Worktree.

• Con un ambiente salvato: imposta Worktree quando crei o modifichi l'ambiente
• Layout precedente: seleziona la casella di controllo worktree accanto al nome del branch, sopra la casella del prompt

I worktree sono archiviati in <project-root>/.claude/worktrees/ per impostazione predefinita. Per archiviarli invece in una directory personalizzata:

• Sessioni locali: imposta Worktree location in Settings > Claude Code
• Sessioni SSH: imposta Worktree folder sulla connessione SSH

Puoi anche impostare un Branch prefix in Settings > Claude Code. Desktop lo antepone a ogni nome di branch worktree, il che è utile per mantenere organizzati i branch creati da Claude.

Per includere file gitignored come .env nei nuovi worktree, crea un file .worktreeinclude nella radice del tuo progetto. Vedi Cosa condividono i worktree con il checkout principale per sapere da dove una sessione worktree legge le impostazioni di progetto, gli hook e le skill.

[!NOTE]

L'isolamento della sessione richiede Git. La maggior parte dei Mac include Git per impostazione predefinita. Esegui git --version in Terminal per verificare; se stampa un numero di versione, Git è installato. Se riscontri errori Git, chiedi a Claude nella scheda Cowork di aiutarti a risolvere i problemi della tua configurazione.

Aggiungi cartelle a una sessione

Aggiungi le cartelle prima che la sessione si avvii o mentre è in esecuzione:

• Prima che si avvii una sessione locale: aggiungi le cartelle in Folders quando crei un ambiente salvato o ne modifichi uno, quindi avvia la sessione da quell'ambiente salvato.
• Mentre è in esecuzione una sessione locale o SSH: fai clic su + accanto alla casella del prompt e seleziona Add folder. Claude lavora direttamente in quella cartella, senza alcun worktree.

Archivia una sessione

Prima di archiviare una sessione il cui worktree contiene modifiche senza commit, consulta Conserva le modifiche senza commit quando una sessione viene archiviata. Per archiviare una sessione, passa il mouse sopra di essa nella barra laterale, apri il suo menu e seleziona Archive. La sessione viene spostata nelle tue sessioni archiviate.

Per fare in modo che le sessioni si archivino da sole quando viene eseguito il merge della loro pull request o quando questa viene chiusa, attiva Auto-archive after PR merge or close in Settings > Claude Code. Le sessioni cloud e le sessioni ancora in esecuzione non si archiviano da sole.

Conserva le modifiche senza commit quando una sessione viene archiviata

Puoi perdere le modifiche senza commit nel worktree di una sessione quando la sessione viene archiviata, quindi prima esegui il commit di ciò che vuoi conservare:

• Se Desktop ti chiede delle modifiche: seleziona Archive anyway per scartarle, oppure annulla ed esegui il loro commit
• Se le uniche modifiche sono file non tracciati: esegui il commit di quelli che vuoi conservare prima che venga eseguito il merge di una pull request aperta da Claude nella sessione, perché a quel punto Desktop può eliminarli senza chiedere
• In qualsiasi altro caso: il worktree resta su disco con le sue modifiche. Per una sessione locale, Desktop li rimuove entrambi circa 30 giorni dopo l'archiviazione della sessione o dopo l'ultima volta che la apri, a seconda di quale data sia successiva. Per conservare le modifiche, apri la sessione dalla scheda Archived e seleziona Unarchive

Organizza e trova le sessioni

Raggruppi, ordini e trovi le sessioni da un'icona nell'elenco delle sessioni della barra laterale:

• Layout attuale: passa il mouse su un'intestazione nell'elenco delle sessioni per mostrare l'icona Group and sort, quindi fai clic su di essa. Per trovare le sessioni archiviate, seleziona View all, l'ultima riga del menu, quindi apri la scheda Archived.
• Layout precedente: l'icona Filter è visibile senza passare il mouse. Fai clic su di essa per organizzare l'elenco con Group by o Sort by. Per mostrare le sessioni archiviate, seleziona Status, quindi Archived.

Per rinominare una sessione, aprila e fai clic sul titolo della sessione nella barra del titolo.

Controlla e libera il contesto

Per controllare l'utilizzo del contesto, vedi Controlla l'utilizzo. Quando il contesto si riempie, Claude riassume automaticamente la conversazione e continua a lavorare. Puoi anche digitare /compact per attivare la compattazione prima e liberare spazio di contesto. Vedi la finestra di contesto per i dettagli su come funziona la compattazione.

Ricevi una notifica quando una sessione termina

L'app desktop invia una notifica del sistema operativo quando una sessione Code termina un'attività e non stai visualizzando quella sessione. Per le sessioni che appartengono a un progetto, ricevi invece le notifiche del progetto.

Chiedi una domanda laterale senza deviare la sessione

Una chat laterale ti consente di chiedere a Claude una domanda che utilizza il contesto della tua sessione ma non aggiunge nulla di nuovo alla conversazione principale. Usala quando vuoi capire un pezzo di codice, verificare un'assunzione o esplorare un'idea senza sterzare la sessione fuori rotta.

Premi Cmd+; su macOS o Ctrl+; su Windows per aprire una chat laterale, o digita /btw nella casella del prompt. La chat laterale può leggere tutto nel thread principale fino a quel punto. Quando hai finito, chiudi la chat laterale e continua la sessione principale da dove l'hai lasciata.

Le chat laterali sono disponibili nelle sessioni locali, SSH e WSL. L'app desktop non salva le chat laterali su disco, quindi non puoi tornare a una dopo aver chiuso l'app.

Guarda le attività in background

Il pannello attività mostra il lavoro in background in esecuzione all'interno della sessione corrente: subagent, comandi shell in background e workflow dinamici. Quando la sessione ha del lavoro in background, apri il pannello con Background tasks nel menu ⋮ della barra del titolo.

Fai clic su qualsiasi voce per vedere il suo output nel pannello subagent o fermarlo. Per vedere cosa stanno facendo altre sessioni, usa la barra laterale, o chiedi a Claude di controllarle per te.

Lavora tra le sessioni

Claude può elencare le tue altre sessioni della scheda Code, leggere cosa ognuna ha fatto, e inviare messaggi tra di loro. Chiedi in linguaggio naturale: "quale sessione ha toccato il refactor dell'autenticazione?", "cosa ha concluso la sessione API?", o "dì alla sessione dei pagamenti che lo schema è cambiato".

Puoi anche chiedere a Claude di rinominare o archiviare una sessione. Ad esempio, chiedigli di archiviare le sessioni delle cui PR è stato eseguito il merge.

Attraverso questa superficie, Claude vede solo le sessioni che l'app desktop esegue da sola: locale, SSH, e sessioni WSL nella scheda Code. Claude non vede le sessioni cloud, o le sessioni che hai avviato dal CLI del terminale o dall'estensione VS Code, anche nei worktree dello stesso progetto, quindi con nove worktree del terminale aperti e due sessioni desktop, Claude che risponde in una di esse segnala l'altra sessione desktop. Claude non elenca mai la sessione da cui stai chiedendo. Per impostazione predefinita vede le 20 sessioni più recentemente attive e salta le sessioni archiviate a meno che non le chiedi. La messaggistica tra sessioni consente separatamente a Claude di inviare messaggi alle tue altre sessioni Claude Code, incluse le sessioni del terminale.

Quando Claude invia un messaggio a un'altra sessione attraverso questa superficie, Claude Code lo mostra lì come una scheda etichettata con il titolo della sessione di invio e un collegamento indietro, così puoi sempre dire da dove proviene un messaggio. Se la sessione ricevente è a metà di un'attività, Claude Code tiene il messaggio e Claude lo legge una volta che il lavoro corrente finisce. Claude che riceve può rispondere, e Claude Code consegna la risposta indietro attraverso questa superficie. Claude non può consegnare a una sessione archiviata, e ti dice quando un messaggio non passa.

Claude Code applica quattro comportamenti di sicurezza tra le sessioni:

• Ricevi una scheda di approvazione prima che Claude archivi una sessione, tranne in modalità Auto e in modalità Bypass permissions, in cui Claude può archiviare una sessione senza di essa. Per ricevere la richiesta, passa a Manual.
• Attraverso questa superficie, Claude non può inviare messaggi tra sessioni da una sessione che nessuno sta guardando, come un'esecuzione di attività pianificata, e non può consegnare messaggi in una.
• Claude Code controlla ogni messaggio da questa superficie rispetto ai controlli in entrata della sessione ricevente, anche quando la sessione ricevente non ha messaggistica tra sessioni stessa. Se imposti crossSessionInbound su refuse nella sessione ricevente, Claude Code scarta i messaggi da questa superficie. Claude Code segnala il rifiuto all'app desktop Claude. Prima della v2.1.234, Claude Code scartava ogni messaggio da questa superficie a una sessione ricevente senza messaggistica tra sessioni.
• Claude Code cita ogni messaggio in arrivo e lo attribuisce alla sessione che l'ha inviato, e Claude segue comunque le impostazioni di permesso proprie della sessione ricevente quando agisce su uno.

Claude può anche suggerire nuove sessioni. Quando nota qualcosa che vale la pena correggere che è fuori portata per l'attività corrente, offre il lavoro come una scheda di attività nella chat. Fai clic sulla scheda per avviare quel lavoro in una nuova sessione con il suo proprio worktree; Claude continua la tua sessione corrente senza interruzioni.

Esegui attività a lunga esecuzione nel cloud

Per grandi refactor, suite di test, migrazioni o altre attività a lunga esecuzione, seleziona un ambiente in Cloud nel selettore dell'ambiente quando avvii una sessione. Le sessioni cloud vengono eseguite sull'infrastruttura gestita da Anthropic per impostazione predefinita e continuano anche se chiudi l'app o spegni il computer. Torna indietro in qualsiasi momento per vedere i progressi o indirizzare Claude in una direzione diversa. Puoi anche monitorare le sessioni cloud da claude.ai/code o dall'app mobile Claude.

Le sessioni cloud supportano anche più repository. Scegli i repository:

• Layout attuale: nella riga sotto la casella del prompt, una volta selezionato un ambiente cloud.
• Layout precedente: sopra la casella del prompt. Per aggiungere un altro repository, fai clic su + accanto a quello selezionato.

Vedi Usa Claude Code nel cloud per ulteriori informazioni su come funzionano le sessioni cloud. Quando un corpo di lavoro ha bisogno di molte sessioni cloud, seleziona Projects nella barra laterale per creare un progetto, dove Claude avvia e traccia le sessioni per te da una conversazione.

[!NOTE]

Anche un'attività in una sessione SSH può continuare mentre Desktop è disconnesso, ma con un account Claude può interrompersi quando il suo accesso scade.

Continua su un'altra superficie

Per continuare una sessione altrove, apri il menu della sessione dalla freccia accanto al titolo della sessione o dalla riga della sessione nella barra laterale, quindi seleziona Open in:

• Seleziona Cloud per continuare la sessione come sessione cloud, con la tua conversazione trasferita sotto forma di riepilogo. Prima di confermare, la finestra di dialogo indica se vengono spostati anche i tuoi file e se questa sessione viene archiviata una volta che quella cloud è pronta. Non puoi spostare in questo modo una sessione eseguita tramite SSH o in WSL.
• Seleziona un editor installato o il tuo file manager per aprire lì la cartella della sessione su disco.

Controlla quali sessioni appaiono sugli altri tuoi dispositivi

Una sessione locale compare sugli altri tuoi dispositivi una volta che Remote Control la connette. Una sessione connessa appare nell'elenco delle sessioni su claude.ai/code e nelle app Claude sui dispositivi su cui hai effettuato l'accesso con il tuo account claude.ai.

Una sessione locale si connette quando attivi Remote Control per essa, oppure quando si connette automaticamente all'avvio:

• Lo attivi per quella sessione: con l'interruttore Remote Control della sessione, oppure digitando /remote-control nella sua casella del prompt.
• Si connette all'avvio: le nuove sessioni si connettono automaticamente mentre Connect new sessions to Remote Control è attivo in Settings > Claude Code. Se non hai mai modificato quell'impostazione, Desktop segue remoteControlAtStartup nelle tue impostazioni utente o nelle impostazioni gestite, quindi il valore predefinito della tua organizzazione.

Per vedere se una sessione è connessa, controlla l'interruttore Remote Control nella scheda Environment del suo pannello dei dettagli della sessione.

Per tenere le sessioni lontane dagli altri tuoi dispositivi, disattiva Remote Control al livello che ti serve:

• Una sessione: disattiva il suo interruttore Remote Control. In una sessione che si è connessa all'avvio, digitando /remote-control Remote Control resta attivo e viene mostrato Remote Control is already on. This session connected automatically when it started. Fai clic su Turn off in quella riga per disconnetterla.
• Nuove sessioni Desktop su questo computer: disattiva Connect new sessions to Remote Control in Settings > Claude Code. Se risulta già disattivato, attivalo e poi disattivalo in modo che Desktop salvi la tua scelta. Una volta salvata, ha la precedenza su remoteControlAtStartup e sui valori predefiniti.
• Qualsiasi sessione su questo computer, inclusa la CLI: imposta disableRemoteControl su true in ~/.claude/settings.json per impedire alle sessioni di connettersi. Una sessione che era già connessa quando hai salvato il file resta connessa finché non disattivi Remote Control per essa.

Per nascondere una sessione che appare già sugli altri tuoi dispositivi, archiviala in Desktop. Desktop archivia anche la copia Remote Control della sessione, così esce dall'elenco predefinito delle sessioni su quei dispositivi. Per visualizzarla o eliminarla lì, vedi Archivia le sessioni.

Sessioni da Dispatch

Dispatch è una conversazione persistente con Claude che vive nella scheda Cowork. Invii a Dispatch un'attività, e decide come gestirla.

Un'attività può finire come una sessione Code in due modi: chiedi direttamente una, come "apri una sessione Claude Code e correggi il bug di accesso", o Dispatch decide che l'attività è lavoro di sviluppo e ne genera una automaticamente. Le attività che tipicamente vengono indirizzate a Code includono correzione di bug, aggiornamento delle dipendenze, esecuzione di test o apertura di pull request. La ricerca, la modifica di documenti e il lavoro con fogli di calcolo rimangono in Cowork.

In entrambi i casi, la sessione Code appare nella barra laterale della scheda Code con un badge Dispatch. Ricevi una notifica push sul tuo telefono quando finisce o ha bisogno della tua approvazione.

Se hai l'utilizzo del computer abilitato, le sessioni Code generate da Dispatch possono usarlo anche. Le approvazioni delle app in quelle sessioni scadono dopo 30 minuti e vengono richieste di nuovo, piuttosto che durare l'intera sessione come le sessioni Code regolari.

Per la configurazione, l'accoppiamento e le impostazioni di Dispatch, vedi l'articolo di aiuto di Dispatch. Dispatch richiede un piano Pro o Max e non è disponibile su piani Team o Enterprise.

Dispatch è uno dei diversi modi per lavorare con Claude quando sei lontano dal tuo terminale. Per un confronto con le altre opzioni, vedi Piattaforme e integrazioni.

Estendi Claude Code

Connetti servizi esterni, aggiungi flussi di lavoro riutilizzabili, personalizza il comportamento di Claude e configura server di anteprima. Per gestire connettori, skills e plugin in un unico posto, fai clic su Customize nella barra laterale. La scheda Cowork nell'app Desktop estrae i suoi skills, plugin e connettori da questa configurazione Customize, che si sincronizza tramite il tuo account claude.ai, non dalla directory ~/.claude della CLI.

Claude Code carica anche gli skills e i plugin abilitati per il tuo account claude.ai nelle sessioni di terminale in cui accedi con lo stesso account. Vedi Skills synced from claude.ai e Plugins synced from claude.ai.

Connetti strumenti esterni

I connettori sono server MCP con un flusso di configurazione grafico.

Fai clic su + accanto alla casella del prompt, prima o durante la sessione, per aggiungere connettori in una sessione locale o SSH con un account Claude. Seleziona Add connectors per aprire la directory dei connettori. Se il menu mostra invece Connectors, selezionalo, poi seleziona Browse connectors.

[!NOTE]

Questi casi sono trattati in altre pagine:

• Connectors è disattivato in una sessione WSL: vedi Se il terminale o i connettori non sono disponibili
• Sessioni cloud: vedi Come i connettori raggiungono Claude Code

Una volta connesso, Claude può leggere il tuo calendario, inviare messaggi, creare problemi e interagire direttamente con i tuoi strumenti. Puoi chiedere a Claude quali connettori sono configurati nella tua sessione. Per gestire o disconnettere i connettori, vai a Settings > Connectors nell'app desktop.

Per le integrazioni non elencate in Connectors, aggiungi server MCP manualmente tramite file di impostazioni. Puoi anche creare connettori personalizzati.

Usa skills

Skills estendono quello che Claude può fare. Claude le carica automaticamente quando rilevante, o puoi invocarne una direttamente: digita / nella casella del prompt o fai clic sul pulsante + e seleziona Slash commands per sfogliare cosa è disponibile. Questo include comandi incorporati, le tue skill personalizzate, skill del progetto dal tuo codebase e skill da qualsiasi plugin installato. Selezionane uno e appare evidenziato nel campo di input. Digita il tuo compito dopo di esso e invia come al solito.

Puoi inviare un comando mentre Claude sta lavorando, come qualsiasi altro messaggio, e la sessione torna inattiva una volta che il turno finisce.

Le sessioni locali caricano le tue skill personali da ~/.claude/skills/. Una sessione SSH legge ~/.claude/skills/ dalla directory home dell'host remoto, non dalla tua macchina.

Le sessioni locali e cloud caricano anche gli skills abilitati per il tuo account claude.ai, tranne le sessioni locali quando la tua organizzazione imposta disableSideloadFlags. Le sessioni cloud li caricano invece di ~/.claude/skills/, come descrive Skills in Cowork and cloud sessions.

Installa plugin

Plugins sono pacchetti riutilizzabili che aggiungono skills, agent, hooks, MCP servers e configurazioni LSP a Claude Code. Puoi installare plugin dall'app desktop senza usare il terminale.

In una sessione locale o in una sessione SSH, fai clic su + accanto alla casella del prompt e seleziona Add plugins per aprire il browser dei plugin. Se il menu mostra invece Plugins, selezionalo, poi seleziona Browse plugins, oppure Manage plugins per abilitare, disabilitare o disinstallare plugin.

Puoi limitare i plugin al tuo account utente, a un progetto specifico o solo locali. Se la tua organizzazione gestisce i plugin centralmente, quei plugin sono disponibili nelle sessioni desktop nello stesso modo in cui lo sono nella CLI, tranne quelli che l'app desktop trattiene sotto disableSideloadFlags.

Il browser dei plugin non è disponibile nelle sessioni cloud e i plugin che installi dall'app desktop non sono disponibili per le sessioni cloud. Una sessione cloud inoltre non installa plugin che il file .claude/settings.json del repository dichiara, come spiega What carries over from your setup. I plugin non sono disponibili nelle sessioni WSL. Per il riferimento completo dei plugin inclusa la creazione dei tuoi plugin, vedi plugins.

Configura server di anteprima

Claude rileva automaticamente la tua configurazione del server di sviluppo e archivia la configurazione in .claude/launch.json alla radice della cartella che hai selezionato quando hai avviato la sessione. Preview utilizza questa cartella come directory di lavoro, quindi se hai selezionato una cartella padre, le sottocartelle con i loro stessi server di sviluppo non verranno rilevate automaticamente. Per lavorare con il server di una sottocartella, avvia una sessione in quella cartella direttamente o aggiungi una configurazione manualmente.

Per personalizzare come il tuo server si avvia, ad esempio per usare yarn dev invece di npm run dev o per cambiare la porta, modifica .claude/launch.json. Il file supporta JSON con commenti.

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Puoi definire più configurazioni per eseguire server diversi dallo stesso progetto, come un frontend e un'API. Vedi gli esempi di seguito.

Auto-verify changes

Quando autoVerify è abilitato, Claude verifica automaticamente le modifiche al codice dopo aver modificato i file. Scatta screenshot, controlla gli errori e conferma che le modifiche funzionano prima di completare la sua risposta.

Auto-verify è abilitato per impostazione predefinita. Disabilitalo per progetto aggiungendo "autoVerify": false a .claude/launch.json, o disattiva Auto-verify changes nel menu ⋮ del pannello Browser.

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Quando disabilitato, gli strumenti di anteprima sono ancora disponibili e puoi chiedere a Claude di verificare in qualsiasi momento. Auto-verify lo rende automatico dopo ogni modifica.

Configuration fields

Ogni voce nell'array configurations accetta i seguenti campi:

When to use program vs runtimeExecutable

Usa runtimeExecutable con runtimeArgs per avviare un server di sviluppo tramite un gestore di pacchetti. Ad esempio, "runtimeExecutable": "npm" con "runtimeArgs": ["run", "dev"] esegue npm run dev.

Usa program quando hai uno script autonomo che vuoi eseguire con node direttamente. Ad esempio, "program": "server.js" esegue node server.js. Passa flag aggiuntivi con args.

Open the preview at a specific URL

Per impostazione predefinita, l'anteprima apre http://localhost:<port>. Imposta url quando il tuo server ha bisogno di un indirizzo diverso. I casi comuni sono server che richiedono HTTPS locale, app che usano sottodomini *.localhost e app che ti accedono tramite un reindirizzamento.

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 8443,
      "url": "https://localhost:8443"
    }
  ]
}

Gli indirizzi localhost si aprono direttamente, esattamente come l'indirizzo della porta predefinita. Questo include localhost, qualsiasi sottodominio *.localhost, 127.0.0.1 e ::1. Per motivi di sicurezza, un url localhost deve essere solo l'origine del tuo server, senza percorso o query. La sua porta deve corrispondere alla porta della voce. Per mostrare una pagina specifica, chiedi a Claude di navigarvi dopo che l'anteprima si apre. Un url localhost con un percorso, query o porta non corrispondente viene segnalato come un errore di configurazione che nomina l'url e mostra la correzione.

Per qualsiasi altro indirizzo, Desktop chiede il tuo permesso la prima volta che l'anteprima lo apre, come quando navighi a un nuovo sito nell'anteprima. Gli indirizzi esterni possono includere percorsi. Scegli Always allow per saltare il prompt per quel sito in futuro. Le politiche organizzative che limitano i siti esterni nell'anteprima si applicano ancora.

Per visualizzare in anteprima un server che già esegui tu stesso, imposta url senza un comando. Claude allega l'anteprima al tuo server in esecuzione invece di avviarne uno:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "url": "https://app.localhost:3000"
    }
  ]
}

L'url deve essere http o https e non deve contenere un nome utente o una password.

Port conflicts

Il campo autoPort controlla cosa succede quando la tua porta preferita è già in uso:

• true: Claude trova e utilizza una porta libera automaticamente. Adatto per la maggior parte dei server di sviluppo.
• false: Claude fallisce con un errore. Usa questo quando il tuo server deve usare una porta specifica, come per i callback OAuth o gli allowlist CORS.
• Non impostato (predefinito): il tuo server ottiene la successiva porta libera, come con true, tranne nell'unico caso descritto di seguito. Prima di Claude Desktop v2.37337.0, Claude chiede invece se il server ha bisogno di quella porta esatta, quindi salva la tua risposta in launch.json.

Se la tua porta preferita è in uso e autoPort non è impostato, il tuo server rimane fermo quando si verificano tutte queste condizioni:

• Avvii il server tramite uno script npm, yarn, pnpm o bun.
• La tua porta preferita è codificata in modo fisso in quello script, oppure Claude non può ispezionare lo script.
• Non passi la porta in runtimeArgs.

In tal caso, libera la porta, rimuovi il valore codificato in modo fisso oppure modifica port in modo che corrisponda allo script. Impostare invece "autoPort": true funziona solo per uno script che legge PORT.

Fai in modo che il tuo server legga la sua porta dalla variabile d'ambiente PORT, che contiene la porta assegnata. Quando Claude sposta il tuo server su una porta diversa, riscrive anche un valore --port o -p in runtimeArgs in modo che corrisponda.

Examples

Queste configurazioni mostrano configurazioni comuni per diversi tipi di progetto:

Next.js

Questa configurazione esegue un'app Next.js usando Yarn sulla porta 3000:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev"],
      "port": 3000
    }
  ]
}

Multiple servers

Per un monorepo con un frontend e un server API, definisci più configurazioni. Il frontend usa autoPort: true in modo che scelga una porta libera se 3000 è occupata, mentre il server API richiede la porta 8080 esattamente:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "apps/web",
      "port": 3000,
      "autoPort": true
    },
    {
      "name": "api",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start"],
      "cwd": "server",
      "port": 8080,
      "env": { "NODE_ENV": "development" },
      "autoPort": false
    }
  ]
}

Node.js script

Per eseguire uno script Node.js direttamente invece di usare un comando del gestore di pacchetti, usa il campo program:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "server",
      "program": "server.js",
      "args": ["--verbose"],
      "port": 4000
    }
  ]
}

Configurazione dell'ambiente

L'ambiente che scegli quando avvii una sessione determina dove Claude viene eseguito e come ti connetti:

• Local: viene eseguito sulla tua macchina con accesso diretto ai tuoi file
• Cloud: viene eseguito sull'infrastruttura gestita da Anthropic per impostazione predefinita. Le sessioni continuano anche se chiudi l'app.
• SSH: viene eseguito su una macchina remota a cui ti connetti tramite SSH, come i tuoi stessi server, VM cloud o dev container. Un'attività in esecuzione può proseguire mentre Desktop è disconnesso, ma con un account Claude può interrompersi quando il suo accesso scade.
• WSL (Windows): viene eseguito all'interno di una distribuzione WSL 2 sulla tua macchina, utilizzando la sua toolchain Linux e i percorsi nativi

Creare un ambiente salvato

Un ambiente salvato è una voce nel selettore di ambiente che registra dove viene eseguito Claude, così puoi avviare lì le sessioni successive. Un ambiente locale o SSH contiene anche le cartelle in cui Claude lavora. Gli ambienti locali e SSH salvati richiedono Claude Desktop v2.37337.0 o successiva.

1. Apri la finestra di dialogo New environment

Apri il selettore di ambiente sotto la casella del prompt e seleziona New environment in fondo al suo menu.

2. Scegli dove viene eseguito Claude

Seleziona la scheda Local, SSH o Cloud e compila il modulo in quella scheda. Nella scheda SSH, scegli una connessione e una cartella sulla macchina remota.

3. Salva l'ambiente

Seleziona Create environment, oppure Add environment nella scheda Cloud.

Ambienti che Desktop crea per te

Se il selettore di ambiente elenca ambienti locali o SSH che non hai creato, li ha creati Desktop per te. La prima volta che apri la scheda Code nel layout attuale, Desktop crea fino a otto ambienti. Gli ambienti derivano dalle cartelle locali e SSH che hai usato di più nell'ultimo mese. Puoi modificarli o eliminarli.

Usare, modificare o rimuovere un ambiente salvato

Trova la voce dell'ambiente nel selettore di ambiente:

• Avviare una sessione: seleziona la voce.
• Modificare o eliminare: passa il mouse sulla voce e fai clic sull'icona a forma di ingranaggio. Per eliminare un ambiente locale o SSH, fai clic su Delete environment in Edit environment.
• Archiviare ambienti cloud: consulta Archiviare un ambiente.

Local sessions

L'app desktop non sempre eredita il tuo ambiente shell completo. Su macOS, quando avvii l'app dal Dock o dal Finder, legge il tuo profilo shell, come ~/.zshrc o ~/.bashrc, per fornire a Claude Code il PATH e un insieme fisso di variabili di Claude Code, ma non le altre variabili che esporti lì. Su Windows, l'app eredita le variabili d'ambiente utente e di sistema ma non legge i profili PowerShell.

Impostare le variabili d'ambiente per le sessioni locali

Aggiungi le variabili a un ambiente locale salvato e avvia le tue sessioni da esso. Desktop imposta alcune variabili da sé, come API_TIMEOUT_MS, e le tue sessioni ricevono il suo valore per quelle al posto del tuo.

[!NOTE]

Se il tuo selettore di ambiente si trova sopra la casella del prompt, hai il layout precedente, che non prevede ambienti locali salvati. Usa invece l'editor dell'ambiente locale.

1. Apri il modulo dell'ambiente

Apri New environment o Edit environment.

2. Inserisci le variabili

Seleziona Environment variables, inserisci un KEY=value per riga e seleziona Done.

3. Salva l'ambiente

Seleziona Create environment o Save.

Solo le sessioni che avvii da quell'ambiente ricevono le variabili.

Per impostare una variabile per ogni sessione locale, aggiungila alla chiave env nel tuo file ~/.claude/settings.json. Claude Code ignora il valore se quella variabile è già presente nell'ambiente con cui Desktop avvia la sessione. Consulta variabili d'ambiente per l'elenco completo delle variabili supportate.

Impostare le variabili d'ambiente per i dev server

Per fornire un segreto a un dev server senza eseguirne il commit in launch.json, impostalo in uno di questi punti, poi riavvia Desktop:

• macOS e Linux: esportalo nel profilo della tua shell
• Windows: aggiungilo alle tue variabili d'ambiente utente o di sistema
• Qualsiasi piattaforma: salvalo nell'editor dell'ambiente locale, se riesci ad aprirlo

I dev server non ricevono le variabili che aggiungi a un ambiente salvato o a ~/.claude/settings.json.

Usare l'editor dell'ambiente locale

Per aprire l'editor dell'ambiente locale, fai clic sull'icona a forma di ingranaggio sulla voce del tuo computer, non su quella di un ambiente salvato:

• Selettore sotto la casella del prompt: passa il mouse sulla voce del tuo computer, la prima sotto Local. Se compare un'icona a forma di ingranaggio, fai clic su di essa. In caso contrario, l'editor non è disponibile, quindi imposta la variabile per le sessioni locali o per i dev server in un altro modo.
• Selettore sopra la casella del prompt: passa il mouse su Local e fai clic sull'icona a forma di ingranaggio

Inserisci un KEY=value per riga e seleziona Save changes. Le variabili che salvi qui vengono memorizzate crittografate sulla tua macchina. Le sessioni locali le ricevono, tranne qualsiasi variabile che Desktop imposta da sé, come API_TIMEOUT_MS. Riavvia Desktop per fornire le tue variabili ai dev server.

Variabili d'ambiente che Desktop imposta da sé

Se hai impostato API_TIMEOUT_MS o ANTHROPIC_BASE_URL e non è cambiato nulla nelle tue sessioni locali, è perché Desktop imposta da sé queste variabili, tra le altre. Una sessione locale riceve il valore di Desktop sia che tu abbia impostato il tuo nel profilo della shell, nelle variabili utente o di sistema di Windows, nell'editor dell'ambiente locale o in un ambiente salvato. Spostare il tuo valore in un file di impostazioni non aiuta, perché Claude Code ignora quel valore in una sessione locale.

• API_TIMEOUT_MS: una sessione locale riceve 900000, ovvero 15 minuti. Per un timeout più lungo, installa la CLI di Claude Code e usala al posto di Desktop. Imposta la variabile nella tua shell ed esegui claude nel tuo terminale.
• ANTHROPIC_BASE_URL: una sessione locale riceve l'host API di Anthropic quando hai effettuato l'accesso con un account Claude. Per usare un gateway, configura invece la configurazione di inferenza di terze parti di Desktop.

Disattivare il ragionamento esteso

Il ragionamento esteso è abilitato per impostazione predefinita, il che migliora le prestazioni nelle attività di ragionamento complesse ma usa token aggiuntivi. Per disattivarlo, imposta MAX_THINKING_TOKENS su 0 in un ambiente locale salvato o nell'editor dell'ambiente locale. Il ragionamento si disattiva quindi sull'API di Anthropic, tranne su Opus 5.5, Sonnet 5.5, Haiku 5.5 e sui modelli Fable, che usano sempre il ragionamento esteso.

Su Opus 5, seleziona anche un effort high o inferiore prima di avviare la sessione. Nel layout attuale, apri il selettore del modello e seleziona un livello sotto Effort. Se hai avviato la sessione a un livello più alto, avviane una nuova a high o inferiore.

Budget di ragionamento fissi

Sui modelli con ragionamento adattivo, Claude Code ignora il numero in sé in un valore positivo di MAX_THINKING_TOKENS, perché è invece il ragionamento adattivo a controllare la profondità del ragionamento. Su Opus 4.6 e Sonnet 4.6, imposta CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING a 1 per usare un budget di ragionamento fisso; i modelli Fable, Sonnet 5 e versioni successive, Haiku 5.5, e Opus 4.7 e versioni successive utilizzano sempre il ragionamento adattivo e non hanno una modalità di budget fisso.

Local sessions on managed devices

Se la voce del tuo computer è disattivata nel selettore di ambiente, con il tooltip Disabled by your organization, il tuo amministratore ha disattivato le sessioni locali. Su Windows la voce WSL, la cui disponibilità sui dispositivi gestiti è regolata separatamente, viene disattivata allo stesso modo.

Le nuove sessioni usano per impostazione predefinita la prima connessione SSH, se ne è configurata una. Se provi a continuare una sessione locale esistente, Desktop mostra un messaggio che indica che le sessioni locali non sono disponibili su questo dispositivo. Gli ambienti locali salvati mostrano questo errore quando ne selezioni uno: Couldn’t switch environments: the Local environment isn’t available anymore. Scegli invece un ambiente SSH o cloud, oppure contatta il tuo team IT.

Cloud sessions

Le sessioni cloud continuano in background anche se chiudi l'app. L'utilizzo conta verso i limiti del tuo piano di abbonamento senza costi di calcolo separati.

Per aggiungere, modificare o archiviare un ambiente cloud, apri il selettore di ambiente:

• Aggiungere un ambiente: seleziona New environment in fondo al menu del selettore, poi la scheda Cloud della finestra di dialogo New environment
• Edit or archive one of your own environments: passa il mouse su di esso e fai clic sull'icona dell'ingranaggio

Vedi Configure cloud environments per i dettagli sulla configurazione dell'accesso alla rete e delle variabili di ambiente.

Sessioni SSH

Le sessioni SSH ti consentono di eseguire Claude Code su una macchina remota mentre usi l'app desktop come tua interfaccia. Questo è utile per lavorare con codebase che vivono su VM cloud, dev container o server con hardware o dipendenze specifiche.

[!NOTE]

Se usi Desktop con un provider di terze parti, le sessioni SSH richiedono una configurazione a parte. Consulta SSH remote sessions in Claude Desktop on 3P.

Aggiungi una connessione SSH nella finestra di dialogo New environment, poi avvia una sessione su quella connessione. Se una nuova sessione non ha un selettore di ambiente sotto la casella del prompt, hai il layout precedente. Consulta Verificare quale layout hai.

1. Apri la finestra di dialogo New environment

Prima di avviare una sessione, apri il selettore di ambiente sotto la casella del prompt e seleziona New environment in fondo al suo menu.

2. Aggiungi la connessione

Nella scheda SSH della finestra di dialogo New environment, apri l'elenco Host, seleziona Add SSH connection… e compila i dettagli della connessione:

• Name: un'etichetta descrittiva per questa connessione.
• SSH host: user@hostname o un host definito in ~/.ssh/config.
• SSH port: se lasciato vuoto usa 22 come valore predefinito, oppure usa la porta della tua configurazione SSH.
• SSH key (optional): percorso della tua chiave privata, come ~/.ssh/id_ed25519. Lascia vuoto per usare la tua configurazione SSH o il tuo agente SSH.
• Worktree folder: una cartella sulla macchina remota, come ~/worktrees, in cui le nuove sessioni creano i loro worktree. Lascia vuoto per usare il valore predefinito della macchina remota.

Poi seleziona Add SSH connection.

3. Avvia una sessione sulla connessione

Seleziona una cartella sulla macchina remota e fai clic su Create environment. Mantieni la macchina e la cartella insieme come ambiente salvato per le sessioni successive. Desktop lo seleziona per la nuova sessione, quindi digita la tua attività e premi Invio.

La macchina remota può eseguire Linux, macOS o Windows. Desktop installa Claude Code sulla macchina remota automaticamente la prima volta che ti connetti. Una volta connesso, le sessioni SSH supportano modalità di permesso, connettori, plugin e server MCP.

Requisiti della macchina remota per le sessioni SSH

Una macchina remota Linux o macOS richiede un processore supportato, un server SSH con SFTP, una cartella di installazione non montata con noexec, una shell funzionante e l'accesso alla rete. Verifica ciascun requisito prima di connetterti, oppure quando una connessione non riesce dopo l'accesso:

• Sistema: un processore x86_64 o arm64. La macchina deve anche soddisfare i requisiti di sistema di Claude Code. Su Linux, Claude Code richiede glibc 2.17 o versioni successive, oppure musl. Per vedere quale dei due ha la macchina, esegui ldd --version su di essa. Su una distribuzione basata su musl come Alpine Linux, installa anche i pacchetti di cui Claude Code ha bisogno.
• SFTP: il server SSH deve offrire il sottosistema SFTP, che viene attivato da una riga Subsystem sftp nel suo sshd_config. Per verificarlo, connettiti allo stesso host e alla stessa porta con sftp in un terminale sul tuo computer. Un server funzionante mostra il prompt sftp>.
• Sessioni per connessione: Desktop su macOS e Linux apre diverse sessioni su una sola connessione SSH. Se il sshd_config del server imposta MaxSessions 1, aumenta il valore, ad esempio al valore predefinito di OpenSSH, cioè 10.
• Cartella di installazione: Desktop installa un programma di supporto e Claude Code in ~/.claude/remote/ nella tua directory home. Li esegue da lì, quindi quella cartella non può trovarsi su un file system montato con noexec. Prevedi circa 1 GB di spazio su disco nella directory home di ogni utente che si connette. Per sapere cosa contiene quella cartella, consulta File e processi sulla macchina remota.
• Shell: la shell impostata per il tuo account sulla macchina remota deve eseguire i comandi inviati tramite SSH, come fanno Bash, Zsh e sh
• Rete: Claude Code viene eseguito sulla macchina remota ed effettua le sue richieste di rete da lì, quindi la macchina necessita dell'accesso alla rete richiesto da Claude Code. Se la macchina non riesce a scaricare Claude Code, Desktop lo scarica sul tuo computer e lo carica sulla macchina. Le altre richieste di Claude Code partono comunque dalla macchina remota. Su una macchina remota Linux, se quelle richieste richiedono un proxy, impostalo per le sessioni SSH.

Impostare un proxy o un certificato CA per le sessioni SSH

Se una macchina remota Linux raggiunge internet tramite un proxy o ha bisogno di un certificato CA, aggiungi le variabili per proxy e CA sotto env in ~/.claude/settings.json su quella macchina. Aggiungile anche se le esporti già in ~/.profile, ~/.bash_profile, ~/.zprofile o ~/.zshrc su quella macchina.

Una sessione SSH non le ottiene da quei file, anche quando claude in un terminale su quella macchina le ottiene. La sessione può quindi bloccarsi, oppure mostrare The connection from … to the API failed o Authentication failed, e accedere di nuovo non aiuta.

1. Aggiungi le variabili

Per il file CA, usa NODE_EXTRA_CA_CERTS, perché Claude Code non considera attendibile una CA proveniente da SSL_CERT_FILE in ~/.claude/settings.json. Questo esempio imposta un proxy e un file CA:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
  }
}

2. Invia di nuovo il tuo messaggio

Invia di nuovo il tuo messaggio, perché una variabile che aggiungi o modifichi in quel file ha effetto entro pochi secondi. Se non riesce ancora, avvia una nuova sessione.

Trovare una variabile di proxy o CA impostata altrove sulla macchina remota

Verifica se la macchina remota Linux imposta la variabile di proxy o CA altrove, perché le sessioni usano quel valore e ignorano quello presente in qualsiasi file di impostazioni:

1. Elenca le variabili impostate dalla macchina remota

In un terminale sul tuo computer, esegui ssh devbox env, con il tuo host.

2. Modifica la variabile dove è impostata

Se l'elenco contiene la variabile, modificala nel file che la imposta, come ~/.zshenv, /etc/environment o ~/.bashrc sulla macchina remota.

3. Fornisci il nuovo valore alle sessioni

Riavvia la macchina remota, oppure chiudi Desktop e termina i processi del programma di supporto, come nei primi due passaggi per rimuovere il programma di supporto. Fallo quando nessuna attività è in esecuzione, perché in entrambi i casi il lavoro di Claude viene interrotto.

Usare la tua configurazione SSH su macOS e Linux

Su macOS e Linux, Desktop si connette eseguendo il client OpenSSH sul tuo computer, quindi usa il tuo ~/.ssh/config. La connessione tramite il client OpenSSH richiede Claude Desktop v1.37937.0 o versioni successive. Inserisci un nome Host di quel file nel campo SSH host per usare le impostazioni della sua voce, come HostName, User, IdentityFile, CertificateFile, ProxyJump e ProxyCommand.

Prima di aggiungere la connessione, controlla il client e la voce in un terminale sul tuo computer:

• Versione del client: esegui ssh -V. Il client deve essere OpenSSH 7.6 o versioni successive.
• Voce: esegui ssh con il nome Host, come ssh devbox. Se non riesce, correggi prima la voce.

Puoi lasciare vuoti i campi SSH port e SSH key (optional). Se ne compili uno, Desktop lo usa insieme alla voce:

• SSH port: un valore qui sovrascrive il Port della voce
• SSH key (optional): Desktop offre il file di chiave che scegli in aggiunta all'IdentityFile della voce e alle chiavi nel tuo agente SSH

Raggiungere una macchina dietro un jump host

Per raggiungere una macchina dietro un jump host, chiamato anche bastion, imposta ProxyJump o ProxyCommand nella voce. La voce seguente raggiunge devbox.internal.example.com tramite bastion.example.com:

Host devbox
  HostName devbox.internal.example.com
  User alice
  ProxyJump bastion.example.com

Inserisci devbox nel campo SSH host.

Raggiungere un container su una macchina remota

Per eseguire una sessione all'interno di un container che non pubblica alcuna porta SSH, raggiungilo con un ProxyCommand, perché Desktop non esegue il RemoteCommand della voce a cui ti connetti. Se la tua voce usa RemoteCommand per entrare nel container, la sessione viene eseguita sulla macchina a cui la voce accede, non nel container.

1. Aggiungi la voce

Aggiungi la voce seguente alla fine del tuo ~/.ssh/config, oppure direttamente sopra la tua prima voce Host * se ne hai una. Sostituisci il container Docker devbox, il suo utente dev e la macchina build.example.com con i tuoi. Il comando della voce avvia un server SSH all'interno del container per ogni connessione:

Host devbox-container
  User dev
  ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i

2. Prepara il container

• Installa il server OpenSSH, con una chiave host che rimanga la stessa quando ricompili l'immagine o ricrei il container
• Fornisci all'account indicato in User un modo per accedere, come un file authorized_keys
• Verifica che il container soddisfi i requisiti della macchina remota

3. Controlla l'allowlist

Se il tuo amministratore limita gli host SSH, esegui ssh -G devbox-container in un terminale sul tuo computer. Chiedigli di consentire in sshHostAllowlist l'hostname che stampa, in questo caso devbox-container. Quando consente quel nome, consente qualunque destinazione a cui si connetta il ProxyCommand della tua voce.

4. Testa la voce, poi connettiti

Esegui ssh devbox-container in un terminale sul tuo computer. Correggi ciò che segnala ed eseguilo di nuovo finché non apre una shell nel container senza chiederti nulla:

• Se ssh chiede una password, una passphrase o un codice: passa a un accesso che funzioni senza richieste, come una chiave conservata dal tuo agente SSH
• Se ssh segnala Cannot execute command-line and remote command. o Bad packet length: rimuovi RemoteCommand e RequestTTY dalla tua voce per build.example.com. Dopodiché, ssh build.example.com in un terminale sul tuo computer apre una shell su quella macchina, non nel container.
• Se ssh segnala Connection closed by UNKNOWN port 65535: esegui ssh build.example.com docker exec devbox /usr/sbin/sshd -t nello stesso terminale.
  • Se stampa Missing privilege separation directory: /run/sshd, crea quella cartella nel container.
  • Se stampa no hostkeys available e il container ha chiavi host, aggiungi -u root dopo exec in questo comando e nella voce.

Poi inserisci devbox-container nel campo SSH host.

Usare variabili della tua shell in un ProxyCommand

Per usare una tua variabile d'ambiente in un comando ProxyCommand o Match exec, esportala in un file di avvio della shell, come ~/.zshrc, quindi chiudi e riapri Desktop. All'avvio, Desktop legge ciò che la tua shell di login esporta e conserva quei valori finché non lo chiudi.

Questo richiede Claude Desktop v2.37337.0 o versioni successive e un comando env che accetti -0, cosa che puoi verificare eseguendo env -0 in un terminale sul tuo computer.

[!NOTE]

Se la tua shell imposta credenziali AWS temporanee, fornisci un profilo all'AWS CLI invece di esportare variabili AWS_*.

Usare credenziali AWS in un ProxyCommand

Se imposti credenziali AWS temporanee in un file di avvio della shell, un ProxyCommand che esegue l'AWS CLI può connettersi in un terminale e non riuscire in Desktop. Quando la tua shell esporta AWS_SESSION_TOKEN, AWS_SECURITY_TOKEN o AWS_CREDENTIAL_EXPIRATION, ssh e il tuo ProxyCommand in Desktop non ricevono le credenziali AWS della shell, AWS_REGION né AWS_PROFILE.

Se l'AWS CLI non ha un'altra fonte per una regione o per le credenziali, non riesce con You must specify a region o Unable to locate credentials. Per connetterti da Desktop, fornisci all'AWS CLI un profilo che legge da ~/.aws/config:

1. Aggiungi un profilo con una regione e una fonte di credenziali

Questo esempio aggiunge un profilo denominato corp che ottiene le sue credenziali da un programma di supporto:

[profile corp]
region = us-east-1
credential_process = /full/path/to/your-credential-helper

• region: indica la AWS Region delle macchine a cui ti connetti
• credential_process: indica il percorso completo di un programma che stampa le credenziali nel formato JSON documentato da AWS. Scegli un programma che non richieda alcun input da parte tua, perché l'AWS CLI lo esegue a ogni connessione, incluse le riconnessioni mentre sei assente.
• IAM Identity Center: aggiungi le impostazioni IAM Identity Center del profilo al posto di credential_process. Esegui aws sso login --profile corp in un terminale prima di connetterti, e di nuovo quando quell'accesso scade.

2. Indica il profilo nel ProxyCommand

Questo esempio aggiunge --profile al comando documentato da AWS per Session Manager:

Host i-*
  ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

3. Connettiti di nuovo

Esegui ssh con l'host in un terminale per confermare che la voce si connetta ancora lì, poi connettiti da Desktop.

Aumentare il timeout della connessione SSH

Se la tua configurazione SSH non imposta alcun ConnectTimeout per l'host, Desktop concede a ssh 30 secondi per connettersi. Tramite un jump host o un ProxyCommand, quel tempo include il tempo necessario al percorso per connettersi. Se il tuo percorso richiede più tempo, aggiungi un valore più alto alla voce:

Host devbox
  HostName devbox.internal.example.com
  User alice
  ProxyJump bastion.example.com
  ConnectTimeout 120

ssh usa il primo valore che trova per un host, quindi mantieni la voce sopra qualsiasi voce Host * che imposti ConnectTimeout. Per verificarlo, esegui ssh -G devbox in un terminale sul tuo computer. Il suo output include connecttimeout 120. Dopo aver modificato il valore, chiudi e riapri Desktop.

Se la macchina remota stessa attende un'approvazione sul tuo telefono, approva entro 45 secondi, qualunque ConnectTimeout tu imposti. Non puoi aumentare questo limite, perché Desktop imposta autonomamente ServerAliveInterval e ServerAliveCountMax, e ssh chiude quindi un accesso in cui la macchina remota non invia nulla per quel lasso di tempo. Se invece è un jump host o un ProxyCommand ad attenderti, aumenta ConnectTimeout nella voce della macchina remota per coprire quel tempo.

Correggere un blocco Match host che solo Desktop applica

Se Desktop usa un'impostazione che ssh devbox in un terminale non usa, cerca un blocco Match host sopra la riga HostName della voce. In un terminale, ssh legge un blocco in quella posizione prima della riga HostName, quindi confronta il blocco con devbox. Desktop passa a ssh il valore HostName sulla riga di comando, quindi ssh confronta il blocco con quel valore.

Per verificarlo, esegui ssh -G in un terminale sul tuo computer con i valori HostName e User della voce sulla riga di comando, come fa Desktop:

ssh -G -o HostName=devbox.internal.example.com -l alice devbox

Confronta l'output con quello di ssh -G devbox. Se le impostazioni del blocco, come proxycommand, compaiono solo nel primo output, il blocco ha effetto solo in Desktop. Per far sì che anche Desktop lo salti, aggiungi !originalhost devbox alla sua riga Match:

Match host *.internal.example.com !originalhost devbox

Per verificarlo, esegui di nuovo il primo comando. Le impostazioni del blocco non compaiono più nel suo output.

Impostazioni di inoltro che Desktop lascia disattivate

Nella sua connessione alla macchina remota, Desktop lascia disattivati ForwardAgent, ForwardX11, LocalForward, RemoteForward, DynamicForward e Tunnel, anche dove la tua configurazione SSH li attiva. Nel terminale o in un comando !, aspettati che le tue impostazioni di inoltro si applichino solo a volte, perché lì Desktop può avviare un ssh separato che le segue.

• Per raggiungere una porta sulla macchina remota: inoltrala tu stesso
• Per usare le tue chiavi dalla macchina remota: configura una credenziale sulla macchina remota stessa, ad esempio per git push

Per evitare che Desktop inoltri il tuo agente SSH o una porta, esegui ssh -G devbox in un terminale sul tuo computer. Poi eseguilo di nuovo come può eseguirlo Desktop, con i valori hostname e user che stampa, come in ssh -G -o HostName=devbox.internal.example.com -l alice devbox. Il secondo output può mostrare impostazioni di un blocco Match che il primo salta.

Cerca in entrambi gli output una riga forwardagent che indichi un valore diverso da no, e righe che iniziano con localforward, remoteforward o dynamicforward. Se ne trovi una, rimuovi quell'impostazione dalla tua configurazione SSH. Fai lo stesso per un host che il tuo ProxyCommand raggiunge con ssh.

Raggiungere una porta sulla macchina remota

Per aprire un server in esecuzione sulla macchina remota, come un server di sviluppo sulla porta 3000, inoltra tu stesso la porta. In un terminale sul tuo computer, esegui ssh con -L e l'host a cui ti connetti, come devbox:

ssh -N -L 3000:localhost:3000 devbox

Se hai compilato SSH port o SSH key (optional) nella connessione, aggiungi -p o -i con lo stesso valore. Lascia quel comando in esecuzione e apri http://localhost:3000 in un browser sul tuo computer per raggiungere la porta 3000 della macchina remota. Se ssh stampa open failed: administratively prohibited, chiedi all'amministratore della macchina di consentire l'inoltro TCP, controllato da AllowTcpForwarding nel sshd_config del server SSH.

Macchine remote Windows

Una macchina remota Windows richiede Claude Desktop v2.31226.0 o versioni successive.

Usa OpenSSH Server di Microsoft. La macchina può essere x64 o ARM64. La shell avviata dal server SSH può essere cmd.exe, Windows PowerShell 5.1 o Git Bash.

Le macchine remote Windows sono testate meno di quelle Linux. Prova il tuo lavoro su di esse prima di farci affidamento.

Aspettati questi limiti, tra gli altri, su una macchina remota Windows:

• Terminale: il terminale non si apre in una sessione la cui cartella è un percorso Windows, come C:/projects/app
• Sandbox: lì Claude Code viene eseguito su Windows nativo, dove esegue i comandi senza sandbox. Consulta dove viene eseguita la sandbox.
• Plugin: Desktop non copia un plugin che contiene un nome di file o cartella che Windows non può memorizzare, come un nome con :. La sessione elenca i plugin che Desktop ha escluso.
• Server MCP: su alcune macchine remote Windows, le chiamate di Claude ai server MCP di claude_desktop_config.json passano attraverso Desktop, quindi Claude non può chiamare i loro strumenti mentre Desktop è disconnesso. Prima di Claude Desktop v2.37337.0, questo vale su ogni macchina remota Windows.
• Worktree: i worktree vengono creati in <project-root>/.claude/worktrees/. Se scegli un'altra cartella, Desktop la ignora.
• Messaggi precedenti: se la shell del server SSH è cmd.exe o Windows PowerShell, potresti dover connetterti prima di vedere i messaggi precedenti di una sessione
• Fork: se la shell del server SSH è cmd.exe o Windows PowerShell, puoi fare il fork di una sessione solo dal suo primo messaggio
• Esecuzione durante la disconnessione: un'attività continua a essere eseguita mentre Desktop è disconnesso solo se il server SSH consente a un programma di sopravvivere alla connessione che lo ha avviato. Per scoprirlo, testa la macchina remota.
• Processi residui: al termine di una sessione, controlla la macchina alla ricerca di programmi avviati da Claude Code, perché possono continuare a essere eseguiti. Il programma di supporto in background che Desktop installa non si arresta da solo lì.

Mantenere un'attività in esecuzione mentre Desktop è disconnesso

Se il tuo computer va in sospensione, perdi la connessione di rete o chiudi Desktop, l'attività prosegue finché non termina, non ha bisogno di te o non raggiunge uno dei limiti. Chiudere il coperchio conta come sospensione. Un riavvio di Desktop o del tuo computer, anche per un aggiornamento, conta come chiusura.

Claude Code viene eseguito come processo sulla macchina remota, sotto un programma di supporto in background che Desktop installa lì, quindi non ha bisogno della tua connessione SSH per continuare a essere eseguito. Il comportamento descritto in questa sezione richiede Claude Desktop v2.31226.0 o versioni successive.

[!WARNING]

Se accedi a Desktop con un account Claude, non contare sul fatto che un'attività venga eseguita per tutta la notte. Desktop rinnova quell'accesso per l'attività solo mentre Desktop è in esecuzione e connesso, quindi l'accesso dell'attività può scadere dopo che ti disconnetti, e l'attività a quel punto si interrompe. Il tempo rimanente al momento della disconnessione varia, e può essere di pochi minuti.

Il lavoro svolto fino a quel momento rimane sulla macchina remota e puoi continuare con un messaggio al tuo ritorno.

Se l'attività deve essere eseguita per tutta la notte:

• Mantieni il tuo computer attivo e online, con il coperchio aperto e Desktop in esecuzione
• Usa un accesso che funzioni senza richieste, come una chiave conservata dal tuo agente SSH, per la macchina remota e per qualsiasi jump host lungo il percorso. Desktop potrà quindi riconnettersi da solo dopo un'interruzione.

Per un'attività che deve essere eseguita mentre il tuo computer è in sospensione o spento, avvia invece una sessione cloud.

• Dopo una sospensione o una perdita di rete: recuperi l'attività in esecuzione se il processo è ancora in esecuzione e Desktop può accedere senza richieste. Se non può, invia un messaggio.
• Dopo una chiusura: l'attività continua a essere eseguita, ma la perdi quando la sessione si riapre, a meno che Desktop non possa ricollegarsi al suo processo. Verifica quando Desktop può ricollegarsi prima di chiuderlo. Se hai perso l'attività, invia un messaggio per continuare.

Quando torni e l'attività non è terminata, verifica se c'è un avviso che Desktop non riesce a riconnettersi, un errore di autenticazione o una richiesta in attesa:

• Desktop non riesce a riconnettersi: la sessione indica il motivo, e potrebbe farlo anche una notifica. Desktop potrebbe aver bisogno che tu acceda.
• Errore di autenticazione: il token di accesso o la credenziale potrebbero essere scaduti. Con un account Claude, invia un messaggio per continuare. Con un provider di terze parti, consulta SSH remote sessions in Claude Desktop on 3P.
• Richiesta in attesa: rispondi
• Nessuno di questi: invia un messaggio per continuare

Preparare un'attività lunga

• Aggiorna prima: aggiorna Desktop prima di avviare un'attività lunga. Su macOS e Windows, Desktop può riavviarsi da solo per installare un aggiornamento che ha scaricato. Quel riavvio attende mentre Claude sta lavorando a un'attività SSH. Su macOS con un account Claude, per impostazione predefinita il riavvio può comunque procedere una volta che l'aggiornamento ha atteso 72 ore.
• Non chiudere su Windows, o prima della v2.42304.0 con un provider di terze parti: dopo una chiusura in quei casi perdi l'attività in esecuzione, quindi lascia Desktop aperto durante l'attività. In qualsiasi altro caso, consulta cosa ritrovi prima di chiuderlo.
• Riduci le richieste: scegli una modalità di permesso, regole o hook che facciano sì che l'attività ti attenda meno spesso
• Controlla il jump host: se il tuo jump host chiede un accesso, ad esempio una notifica push su un telefono, passa a un accesso che funzioni senza richieste. Altrimenti Desktop può inviare un'altra notifica push ogni volta che tenta di riconnettersi.
• Testa la macchina remota: avvia un'attività breve, chiudi Desktop mentre l'attività è ancora in esecuzione e riapri la sessione ben dopo il momento in cui l'attività dovrebbe essere terminata. Se l'attività non è terminata e la sessione non mostra alcun errore di autenticazione, controlla sulla macchina remota cosa può terminare un'attività.
• Tieni i comandi fuori dal terminale di Desktop: se la macchina remota disconnette i terminali inattivi, esegui i tuoi comandi da un accesso SSH esterno a Desktop

Limiti mentre Desktop è disconnesso

Un'attività che lasci in esecuzione può terminare quando il suo accesso scade, quando la macchina remota la termina, o quando il programma di supporto si arresta o viene sostituito:

• Token di accesso o credenziale: con un account Claude, l'attività si interrompe con un errore di autenticazione quando il token scade. Con un provider di terze parti, lo stesso vale per una credenziale che scade, come una proveniente da single sign-on o da un credential helper. Consulta SSH remote sessions in Claude Desktop on 3P. Con un account Claude, mantieni Desktop in esecuzione e connesso in modo che possa rinnovare l'accesso.
• La macchina remota: se la macchina remota si riavvia, o termina i tuoi processi quando la connessione SSH si chiude, l'attività in esecuzione termina. Nulla la riavvia mentre Desktop è disconnesso. Le macchine Linux in cui KillUserProcesses di systemd-logind è yes e si applica al tuo utente terminano i tuoi processi in questo modo. Per mantenere un'attività in esecuzione lì, chiedi all'amministratore di escludere il tuo utente, ad esempio con KillExcludeUsers.
• Terminali inattivi: alcune macchine remote Linux disconnettono un terminale in cui nessuno digita per un tempo prestabilito (StopIdleSessionSec di systemd-logind). Con Desktop su macOS o Linux, il terminale di una sessione e i comandi ! condividono per impostazione predefinita la connessione SSH di Desktop. Quella disconnessione chiude quindi la connessione mentre Desktop è connesso, e l'attività in esecuzione può terminare con essa. Chiudere il riquadro del terminale non lo impedisce, quindi tieni i comandi fuori da quel terminale.
• Aggiornamenti di Desktop: se un aggiornamento introduce un nuovo programma di supporto, Desktop sostituisce il programma di supporto sulla macchina remota in una connessione successiva, il che può terminare un'attività ancora in esecuzione
• Assenze lunghe: su una macchina remota Linux o macOS, se Desktop non si connette per 30 giorni, il programma di supporto si arresta e termina ogni processo Claude Code in esecuzione sotto di esso. Connettiti prima di allora.

Le modifiche ai file e alcuni strumenti possono non riuscire mentre Desktop è disconnesso. Se l'attività ne ha bisogno, mantieni Desktop connesso:

• Worktree: in una sessione che usa un worktree, Desktop verifica ogni modifica ai file prima che Claude la apporti. Mentre Desktop è disconnesso, ogni modifica attende circa 30 secondi e poi fallisce. I comandi della shell vengono comunque eseguiti. Su una macchina remota Linux o macOS, le modifiche possono continuare a funzionare. Se non sei sicuro, avvia la sessione senza un worktree.
• Restrizioni sulle cartelle: se la tua organizzazione limita le cartelle che le sessioni possono usare, Desktop controlla ogni lettura, ricerca e modifica di file, con o senza un worktree. Mentre Desktop è disconnesso, ciascuna attende fino a 10 minuti e poi non riesce.
• Connettori: i connettori e gli altri strumenti forniti da Desktop passano attraverso Desktop, quindi mentre è disconnesso ogni chiamata non riesce dopo circa 30 secondi
• Workflow: Desktop controlla ogni nuovo workflow prima che venga avviato, quindi mentre Desktop è disconnesso un nuovo workflow attende fino a 10 minuti e poi non riesce
• Server MCP: i server MCP che Claude Code avvia sulla macchina remota non passano attraverso Desktop, quindi Claude può comunque chiamare i loro strumenti. I server di claude_desktop_config.json rientrano tra questi solo se Desktop non usa il suo client SSH integrato. Altrimenti, e su alcune macchine remote Windows, Claude non può chiamare i loro strumenti mentre Desktop è disconnesso.

Quando le modifiche in un worktree continuano a funzionare

Su una macchina remota Linux o macOS, il controllo non passa attraverso Desktop, quindi le modifiche all'interno del worktree continuano a funzionare mentre Desktop è disconnesso. Prima di Claude Desktop v2.37337.0, questo vale solo su una macchina remota Linux.

Le modifiche non riescono comunque in alcuni casi, tra cui questi:

• Client SSH integrato: Desktop lo usa, ad esempio in un'installazione da Microsoft Store, su un computer Windows senza OpenSSH 9.4 o versioni successive di Microsoft, oppure per impostazione predefinita su Windows con un provider di terze parti
• Posizione del repository: il repository è la tua directory home, una cartella al di sopra di essa o ~/.claude
• Percorsi macOS: su una macchina remota macOS, il repository si trova sotto /Volumes, oppure un nome di cartella nel percorso del repository o del worktree contiene un ~ o un carattere non ASCII
• Restrizioni sulle cartelle: la tua organizzazione limita le cartelle che le sessioni possono usare
• Launcher aziendale: prima di Claude Desktop v2.37337.0, accedi con un account Claude e la tua organizzazione avvia Claude Code sulla macchina remota tramite un launcher aziendale

Una sessione senza worktree non ha questo controllo, a meno che la tua organizzazione non limiti le cartelle che le sessioni possono usare.

Gestire le richieste che arrivano mentre sei assente

Se Claude ha bisogno della tua approvazione o ti fa una domanda mentre Desktop è disconnesso, Claude attende sulla macchina remota. L'attesa non ha un limite di tempo proprio. Quando Desktop si ricollega al processo, ti mostra la richiesta. Se invece Desktop avvia un nuovo processo, perdi la richiesta.

Se una richiesta che ti attendeva non c'è più quando torni, una causa è che Desktop si è riavviato da solo, ad esempio per installare un aggiornamento. Conservi una richiesta attraverso un riavvio solo se Desktop può ricollegarsi al processo, quindi verifica quando Desktop può ricollegarsi prima di lasciare un'attività in esecuzione.

Se perdi una richiesta, invia un messaggio per continuare.

Per ridurre la frequenza con cui un'attività si ferma per attenderti, e per ricevere sue notizie mentre sei assente, configura uno di questi elementi prima di allontanarti:

• Modalità auto: scegli la modalità auto se è disponibile per te. Dopo blocchi ripetuti, ti viene chiesto di nuovo.
• Regole di autorizzazione: nel tuo file di impostazioni utente sulla macchina remota, ~/.claude/settings.json, aggiungi regole allow per i comandi di cui l'attività ha bisogno. Se la tua organizzazione accetta regole di permesso solo dalle impostazioni gestite, chiedi al tuo amministratore di aggiungerle alle impostazioni gestite che raggiungono la macchina remota. Per le regole allow nel file .claude/settings.json di un progetto, consulta Project allow rules and workspace trust.
• Un hook che risponde: configura un hook PermissionRequest in ~/.claude/settings.json sulla macchina remota per consentire o negare le richieste al posto tuo
• Un hook che ti avvisa: configura un hook Notification con il matcher permission_prompt nello stesso file per inviarti un messaggio quando una richiesta è in attesa
• Un hook che ti dice quando Claude ha finito: configura un hook Stop nello stesso file per inviarti un messaggio quando Claude ha finito di rispondere. Non viene eseguito quando un errore API termina il turno. Per quel caso, configura un hook StopFailure.

Se la tua organizzazione esegue solo hook gestiti, chiedi al tuo amministratore di aggiungere l'hook alle impostazioni gestite che raggiungono la macchina remota.

Claude Code non approva automaticamente alcune azioni in nessuna modalità di permesso, incluso Bypass permissions. A seconda della modalità di permesso, Claude Code nega un'azione di questo tipo o te la chiede, e l'attività attende quindi la tua risposta.

Riconnettersi dopo una sospensione o una perdita di rete

Se Desktop non si è riconnesso quando torni, invia un messaggio nella sessione. Desktop si riconnette da solo solo dove può accedere senza richieste, ad esempio con una chiave conservata dal tuo agente SSH.

• Password memorizzata: anche una password che lasci memorizzare a Desktop funziona senza richieste, ma per un'assenza lunga preferisci una chiave conservata dal tuo agente SSH. Se gli accessi con quella password si interrompono o si bloccano, Desktop può smettere di riconnettersi e attenderti.
• Qualsiasi altra richiesta: se la macchina remota chiede qualcos'altro, come un codice monouso, puoi ricevere una notifica sul tuo computer. Fai clic sulla notifica, o invia un messaggio nella sessione, e Desktop mostra la richiesta.

Se un jump host chiede un accesso, l'interruzione è lunga, manca dell'output o il processo non c'è più

• Jump host, le notifiche push si fermano mentre sei assente: questo può accadere con Desktop su macOS o Linux quando nessuno risponde alla richiesta di accesso di un jump host, ad esempio una notifica push su un telefono. Desktop smette quindi di riconnettersi mentre nessuno è al tuo computer. Quando sblocchi o usi il computer, puoi ricevere un'altra notifica push, perché Desktop può riprovare. Dopo tre tentativi senza risposta attende finché non riprovi o invii un messaggio.
• Jump host, le notifiche push continuano ad arrivare: dove Desktop non riesce a capire che nessuno risponde, come con Desktop su Windows, continua a tentare finché ha un processo a cui ricollegarsi, che quel processo sia ancora in esecuzione o meno. Puoi ricevere un'altra notifica push a ogni tentativo. Per fermare i tentativi, chiudi Desktop, il che può farti perdere l'attività in esecuzione.
• Interruzione lunga: Desktop rallenta a circa un tentativo ogni cinque minuti. Per riconnetterti prima, riprova nella sessione o invia un messaggio, che Desktop recapita una volta connesso.
• Output mancante: mentre Desktop è disconnesso, il programma di supporto conserva l'output più recente di Claude Code di ogni sessione in un buffer da 16 MiB e scarta l'output più vecchio. Dopo che Desktop si è riconnesso, la sessione può mostrare Loading recent output from <host>…. Se Desktop non riesce a caricare tutto l'output, vedi la riga Some output produced while you were disconnected may be missing here. La riga non significa che l'attività si sia interrotta.
• Processo non più presente: il processo è terminato mentre Desktop era disconnesso, come quando la macchina remota si riavvia. Desktop può quindi avviarne uno nuovo dalla cronologia salvata della conversazione e dire a Claude di continuare l'attività. Se l'attività resta ferma, invia un messaggio. Con un provider di terze parti, aggiorna a Claude Desktop v2.42304.0 o successiva, perché le versioni precedenti non continuano mai l'attività da sole.

Riaprire una sessione dopo aver chiuso Desktop

Dopo aver chiuso Desktop, l'attività continua a essere eseguita sulla macchina remota, ma si ferma quando la sessione si riapre, a meno che Desktop non possa ricollegarsi al suo processo. Mentre Desktop è chiuso, l'attività viene eseguita finché non termina, ha bisogno di te o raggiunge uno dei limiti.

• Desktop su Windows: non ritrovi l'attività in esecuzione, perché Desktop non si ricollega mai dopo una chiusura. Riavvia Desktop solo quando prevedi che l'attività sia terminata, perché la sessione può aprirsi all'avvio di Desktop.
• Provider di terze parti, attività da una versione precedente: se hai avviato l'attività in una versione di Desktop precedente alla v2.42304.0, non la ritrovi nemmeno su macOS o Linux. Riavvia Desktop solo quando prevedi che l'attività sia terminata.
• Qualsiasi altra attività, con Desktop su macOS o Linux: avvia Desktop e apri la sessione, e l'attività prosegue se Desktop si ricollega. Non sempre può ricollegarsi, ad esempio dopo alcuni aggiornamenti di Desktop, quindi aggiorna prima di un'attività lunga.

Quando Desktop non può ricollegarsi, perdi anche qualsiasi approvazione o domanda che ti stava attendendo. Se l'attività non continua da sola, invia un messaggio e Claude continua dalla cronologia salvata della conversazione.

Per i deploy di terze parti, consulta SSH remote sessions in Claude Desktop on 3P.

[!WARNING]

Mentre il processo Claude Code di una conversazione è ancora in esecuzione, non eseguire claude --resume per essa sulla macchina remota. Claude Code non te lo impedisce, e a quel punto entrambi i processi scrivono nella stessa conversazione. Se non sei sicuro, aggiungi --fork-session, che continua in una copia della conversazione, ma entrambi i processi lavorano comunque sugli stessi file.

Scegliere dove vengono creati i worktree delle sessioni SSH

A meno che la tua organizzazione non limiti le cartelle che le sessioni possono usare, le nuove sessioni SSH creano i loro worktree nella prima di queste posizioni che risulta impostata:

1. Worktree folder nella connessione SSH
2. worktree.location in ~/.claude/settings.json sulla macchina remota
3. <project-root>/.claude/worktrees/, il valore predefinito

Ogni progetto ottiene una propria sottocartella nella cartella che imposti, quindi con ~/worktrees il percorso di un worktree è ~/worktrees/<project>-<id>/<worktree-name>. Se la cartella che imposti si trova all'interno del progetto, Desktop la ignora per quel progetto e usa il valore predefinito. Su una macchina remota Windows, Desktop usa sempre il valore predefinito.

Impostare la cartella dei worktree su una connessione esistente

Imposta Worktree folder nelle impostazioni di una connessione che hai aggiunto in precedenza o di una gestita dalla tua organizzazione. Il campo richiede Claude Desktop v1.44121.0 o successiva. Se la tua organizzazione limita le cartelle che le sessioni possono usare, Desktop nasconde il campo e mantiene i worktree all'interno del progetto.

1. Trova la connessione

Apri il selettore di ambiente e trova la connessione sotto SSH.

2. Apri le impostazioni della connessione

Passa il mouse sulla connessione e fai clic sull'icona a forma di ingranaggio. Se la finestra di dialogo che si apre mostra Edit connection… accanto a Host, seleziona Edit connection….

3. Imposta la cartella

In Worktree folder, inserisci una cartella sulla macchina remota, come ~/worktrees, e seleziona Save changes.

File e processi sulla macchina remota

Desktop installa un programma di supporto e Claude Code in ~/.claude/remote/ nella directory home di ogni utente che si connette a una macchina remota Linux o macOS. Il programma di supporto non è in ascolto su alcuna porta di rete, ma Claude Code e i programmi che avvia, come i server MCP e i server di sviluppo, possono esserlo.

Per elencare i processi di un utente, esegui pgrep -fl "$HOME/.claude/remote/" sulla macchina remota come quell'utente, oppure con la directory home dell'utente al posto di $HOME:

• Programma di supporto: uno o più processi server per ogni computer che si connette
• Claude Code: i processi che il programma di supporto avvia per le sessioni dell'utente, ciascuno da un file che porta il nome della sua versione, come 2.1.295-…

Desktop raggiunge il programma di supporto tramite la connessione SSH dell'utente, attraverso il socket Unix rpc.sock nella cartella del programma di supporto in ~/.claude/remote/run/. A parte root, gli altri utenti della macchina non possono connettersi a quel socket, perché ha modalità 600 e la sua cartella ha modalità 700.

Per sapere quando il programma di supporto si arresta da solo, consulta Limiti mentre Desktop è disconnesso.

Per rimuovere il programma di supporto e Claude Code per un utente:

1. Chiudi Desktop

Chiudi Desktop su ogni computer da cui l'utente si connette. Desktop installa di nuovo entrambi i programmi alla connessione successiva, e può riconnettersi da solo.

2. Termina i processi

Dopo aver effettuato l'accesso come quell'utente sulla macchina remota, esegui kill con l'ID di ogni processo Claude Code elencato da pgrep. Quando non compaiono più nell'elenco, esegui kill con l'ID di ogni processo server. Se termini prima un processo server, un comando che Claude Code sta eseguendo può continuare a essere eseguito.

Poi elenca i processi rimanenti dell'utente, ad esempio con ps -u "$(id -un)" -f, e termina quelli che riconosci come avviati da Claude Code. I programmi che ha lasciato in background possono continuare a essere eseguiti dopo che è terminato, senza comparire nell'elenco di pgrep.

3. Elimina la cartella

Elimina ~/.claude/remote/. Per rimuovere i file di Claude Code in ~/.claude/ e ~/.claude.json, consulta Rimuovere i file di configurazione.

Terminare il processo di una sessione

Per terminare il processo di Claude Code di una sessione, archivia la sessione in Desktop mentre Desktop è connesso alla macchina remota. Il processo continua a essere eseguito dopo che la sua attività è terminata e dopo che esci da Desktop.

Prima di archiviare una sessione il cui worktree ha modifiche non sottoposte a commit, consulta Conservare le modifiche non sottoposte a commit quando una sessione viene archiviata.

Vedere con quale utente vengono eseguiti i processi

Il programma di supporto e Claude Code vengono eseguiti come l'utente con cui Desktop accede tramite SSH. Installarli e avviarli non richiede sudo. Per verificare l'utente, esegui ps -o user= -p sulla macchina remota con un ID di processo elencato da pgrep.

Anche i programmi che Claude Code avvia, come i comandi shell e i server MCP, vengono avviati come quell'utente. Esamina i diritti di quell'utente sulla macchina remota, comprese le sue regole sudo, come faresti per una persona che esegue comandi lì.

Vedere chi si è connesso alla macchina remota

Per scoprire chi si è connesso a una macchina remota, leggi il log del server SSH su quella macchina, dove un accesso da Desktop appare come uno da un terminale. Con Desktop su macOS o Linux, aspettati una voce ogni volta che Desktop si connette, non una per ogni sessione.

Non troverai le connessioni SSH di Desktop nelle metriche ed eventi di Claude Code. Per scoprire da essi su quale macchina remota è stata eseguita una sessione SSH, consulta Attribuire la telemetria alle sessioni SSH di Desktop. Per il registro delle connessioni tenuto da Desktop stesso, consulta Ottenere i log di Desktop per un problema SSH.

Connessioni che si chiudono prima dell'accesso

Se il log del server SSH mostra connessioni che si chiudono prima di qualsiasi accesso, possono essere test della porta SSH effettuati da Desktop. Desktop verifica se una macchina risponde, ad esempio dopo che una connessione a essa non è riuscita. Apre una connessione alla porta e la chiude immediatamente, senza inviare nulla. Aspettati un test o diversi di fila, ad esempio otto in circa due minuti.

Se nulla blocca o rifiuta gli indirizzi per connessioni di questo tipo, non devi fare nulla riguardo ai test di Desktop. Se un indirizzo da cui Desktop si connette viene rifiutato o bloccato, verifica se è il server SSH stesso a rifiutare l'indirizzo e se fail2ban conta i test di Desktop.

Riconoscere un test nel log del server SSH

Confronta le righe nel tuo log con quelle che un server OpenSSH su Linux scrive per un test con il LogLevel predefinito, nella riga corrispondente alla versione del tuo server. Puoi invece vedere le righe dell'ultima colonna se il messaggio di benvenuto del server arriva prima che Desktop chiuda la connessione:

Altri programmi che aprono la porta e la chiudono possono lasciare le stesse righe. Dove una riga contiene un indirizzo, verifica che sia uno da cui si connette un computer con Desktop.

Le righe delle versioni da 8.0 a 8.2 non contengono un indirizzo. Per ottenerne uno, imposta LogLevel VERBOSE in sshd_config ed esegui sshd -T | grep -i loglevel come root. Se stampa loglevel VERBOSE, ricarica il server SSH. Poi cerca una riga con Connection from 203.0.113.7 port 51234 prima della riga del test.

Verificare se è il server SSH stesso a rifiutare l'indirizzo

Se le connessioni vengono rifiutate da un indirizzo condiviso da molti computer con Desktop, cerca nel log del server SSH una riga che termina come questa:

drop connection #0 from [203.0.113.7]:51234 on [192.0.2.10]:22 penalty: connections without attempting authentication

Con il LogLevel predefinito, OpenSSH 9.8 e successivi possono scrivere una riga del genere quando rifiutano un indirizzo per connessioni che si sono chiuse senza tentare l'accesso, come fanno i test di Desktop. Con le impostazioni predefinite, non vedi una riga del genere dopo pochi test soltanto.

Per evitare il rifiuto, imposta PerSourcePenaltyExemptList in sshd_config sugli indirizzi da cui le persone si connettono, ad esempio PerSourcePenaltyExemptList 203.0.113.7. Il server non applica quindi nessuna delle sue penalità a quegli indirizzi, incluse quelle per gli accessi non riusciti. Per verificare il file, esegui sshd -T | grep -i persourcepenalt come root. Se stampa il tuo elenco, ricarica il server SSH.

Verificare se fail2ban conta i test di Desktop

Se fail2ban 0.10.5 o successivo ha bloccato un indirizzo da cui Desktop si connette, trova la modalità del tuo jail in jail.conf, jail.local o in jail.d/:

• Una riga filter che indica una modalità tra parentesi quadre, come filter = sshd[mode=aggressive]: usa quella modalità.
• Solo la riga filter standard, con [mode=%(mode)s]: usa la riga mode, oppure normal se non ce n'è una.

Se la modalità è normal, fail2ban non conta le righe dei test di Desktop, quindi cerca un'altra causa del blocco.

Per un'altra modalità, copia le righe dal tuo log in un file sulla macchina remota. Copia ogni riga per intero, dalla data alla fine, ed entrambe le righe quando un test ne lascia due. Esegui lì fail2ban-regex con il file e la modalità del tuo jail, ad esempio aggressive:

fail2ban-regex -o ip lines.log "sshd[mode=aggressive]"

Per ogni errore che fail2ban conta, il comando stampa l'indirizzo su una riga a sé, come 203.0.113.7. In tal caso, evita un blocco. Se non stampa nulla, fail2ban non conta nessuna di quelle righe in quella modalità, quindi cerca un'altra causa del blocco.

Evitare un blocco da parte di fail2ban

Per impedire a fail2ban di bloccare un indirizzo per i test di Desktop, modifica una delle due impostazioni del jail, ciascuna con un costo:

• mode: impostala su normal ovunque il tuo jail la imposti, in una riga mode o tra le parentesi quadre di una riga come filter = sshd[mode=aggressive]. Rinunci a ogni conteggio che fanno solo le altre modalità, ad esempio quello dei client che si connettono e se ne vanno senza tentare l'accesso.
• ignoreip: impostala sugli indirizzi da cui le persone si connettono, ad esempio ignoreip = 203.0.113.7. fail2ban non conta quindi nulla da quegli indirizzi, inclusi gli accessi non riusciti.

Usare i server MCP configurati sulla macchina remota

Per usare un server MCP di ~/.claude.json o del .mcp.json di un progetto in una sessione SSH, configuralo in quei file sulla macchina remota. Claude Code avvia lì i loro server stdio, quindi installa sulla macchina remota i comandi eseguiti da quei server. Per i server di claude_desktop_config.json, consulta Limiti mentre Desktop è disconnesso.

Aprire una sessione SSH da un link

Un link claude://code/new apre la pagina di nuova sessione di Desktop e può indicare una connessione SSH. Inserisci un link di questo tipo in un runbook, in una dashboard o in una pagina wiki per aprire Desktop già configurato per la macchina e la cartella giuste. Per le piattaforme che rimuovono questi link, consulta Il link viene visualizzato come testo normale invece di essere cliccabile.

I link SSH richiedono Claude Desktop v2.110.0 o versioni successive.

Il link seguente indica l'utente dev su build.example.com, la porta 2222 e la cartella /srv/payments, e compila un prompt:

claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

Un link SSH accetta questi parametri, e solo ssh_host è obbligatorio:

Un alias di ~/.ssh/config funziona come ssh_host solo per chi ha quella voce. Per far corrispondere una connessione che le persone hanno già, assegna al link lo stesso utente, host e porta di quella connessione.

Quando apri il link, Desktop ti chiede di confermare prima di selezionare la connessione:

• Una connessione che hai già: se host, utente e porta corrispondono a una delle tue connessioni, Desktop ti chiede se usarla e ti mostra il nome e l'host della connessione, e la cartella se il link ne indica una.
• Una nuova connessione: altrimenti Desktop apre la finestra di dialogo per aggiungere una connessione SSH. Quando aggiungi la connessione, Desktop ti chiede se connetterti prima di salvare qualsiasi cosa e ti mostra l'host del link, e la porta e la cartella se il link le indica.

Finché non confermi, Desktop non salva l'host, la porta o la cartella del link, e non seleziona né apre una connessione con essi. Se è già selezionata una connessione SSH, la pagina di nuova sessione può comunque connettersi a essa autonomamente, come fa senza un link, anche quando il link indica lo stesso host. Un link non può contenere un file di chiave, una password o un comando.

Chiunque può scrivere un link, quindi controlla cosa ha compilato:

• Prima di confermare: controlla l'host e la cartella.
• Prima di inviare: controlla il prompt e l'ambiente selezionato.

Desktop compila il prompt quando il link si apre, al posto di qualsiasi testo che non hai inviato, e non lo invia mai al posto tuo. Tratta il prompt come testo normale, quindi una / o un ! iniziali e una menzione di file con @ non agiscono come comando o menzione. Se annulli, il prompt rimane nella casella e l'ambiente che avevi selezionato non cambia.

Un link non aggira sshHostAllowlist. Desktop controlla l'allowlist quando si connette.

Se il link apre Desktop senza una finestra di dialogo relativa alla connessione, verifica una di queste cause:

• Hai effettuato la disconnessione: accedi, quindi apri di nuovo il link.
• È aperta un'altra finestra di dialogo: chiudila, quindi apri di nuovo il link.
• Il link non è valido: Desktop mostra un messaggio che indica cosa correggere e non compila il prompt.
• Desktop è precedente alla v2.110.0: le versioni precedenti ignorano i parametri SSH e aprono la pagina di nuova sessione solo con il prompt.
• Le sessioni SSH sono disattivate: se il tuo amministratore imposta l'allowlist su un array vuoto, Desktop rifiuta i link SSH.

Pre-configure SSH connections for your team

Gli amministratori possono distribuire connessioni SSH ai membri del team impostando sshConfigs nelle impostazioni gestite.

• Cosa vedono gli utenti: le connessioni definite in questo modo compaiono automaticamente nel selettore di ambiente di ciascun utente.
• Cosa possono modificare gli utenti: gli utenti possono selezionare una connessione gestita e impostare la propria Worktree folder per essa. Non possono modificarne gli altri campi né eliminarla nell'app.

L'esempio seguente pre-configura una singola connessione:

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519"
    }
  ]
}

Ogni voce richiede id, name e sshHost. I campi sshPort e sshIdentityFile sono facoltativi. Gli utenti possono anche aggiungere sshConfigs al proprio ~/.claude/settings.json.

Se ometti user@ da sshHost, Desktop si connette come lo User che il file ~/.ssh/config di ciascuno sviluppatore imposta per l'host, oppure, in mancanza di questo, con il nome utente dello sviluppatore sul proprio computer.

Restrict which SSH hosts users can connect to

Gli amministratori possono limitare le sessioni SSH di Desktop a un insieme approvato di host impostando sshHostAllowlist nelle impostazioni gestite. Quando impostato, gli utenti possono connettersi solo a host il cui nome host risolto corrisponde a uno dei modelli. Impostalo su un array vuoto per disabilitare le sessioni SSH. La voce di riferimento di sshHostAllowlist spiega come un array vuoto si combina con gli elenchi presenti in altre fonti gestite.

L'esempio seguente consente connessioni a qualsiasi host sotto devboxes.example.com e a un singolo host bastion denominato:

{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}

[!WARNING]

Se la tua organizzazione distribuisce impostazioni gestite dal server, imposta sshHostAllowlist lì. Per impostazione predefinita, Desktop legge la chiave solo dalla fonte gestita con priorità più alta che distribuisce una chiave di policy. Se quella fonte lascia la chiave non impostata, Desktop ignora un elenco presente in una policy MDM o in un file di impostazioni gestite con priorità inferiore e tratta la chiave come non impostata. Desktop non mostra alcun avviso.

Mantieni inoltre lo stesso elenco sulla macchina di ogni utente, nella policy MDM o nel file di impostazioni gestite con priorità più alta su quella macchina. Desktop recupera le impostazioni gestite dal server all'avvio e non conserva alcuna copia nella cache, quindi finché un recupero non riesce si applica l'elenco della macchina.

I modelli sono case-insensitive. * corrisponde a qualsiasi host, e *.example.com corrisponde a example.com e a qualsiasi sottodominio. Tutto il resto è una corrispondenza esatta. Il controllo viene eseguito sul nome host dopo la risoluzione di ~/.ssh/config tramite ssh -G, quindi gli alias Host e le voci ProxyCommand/ProxyJump sono consentiti purché il HostName risolto corrisponda.

sshHostAllowlist viene letto solo dalle impostazioni gestite; i valori nelle impostazioni utente o progetto vengono ignorati. Solo l'app Claude Desktop onora questa impostazione; la CLI Claude Code e le estensioni IDE non la leggono, e non limita i comandi ssh eseguiti tramite lo strumento Bash. Governa a quali host l'app Desktop si connette, non l'uscita di rete, quindi abbinalo ai controlli di rete della tua organizzazione o zero-trust se hai bisogno di un confine rigido.

Disattivare le sessioni locali e distribuire connessioni SSH

Per disattivare le sessioni locali e limitare le sessioni SSH agli host che scegli, distribuisci insieme disableDesktopLocalSessions, sshConfigs e sshHostAllowlist.

[!NOTE]

Questa configurazione è pensata per gli utenti che accedono con un account Claude. Con un provider di terze parti, le sessioni SSH sono disattivate per impostazione predefinita e impostare sshHostAllowlist può attivarle. Leggi SSH remote sessions in Claude Desktop on 3P prima di distribuire queste chiavi.

L'esempio seguente disattiva le sessioni locali, aggiunge una connessione e limita le sessioni SSH all'host di quella connessione:

{
  "disableDesktopLocalSessions": true,
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "dev.example.com"
    }
  ],
  "sshHostAllowlist": ["dev.example.com"]
}

Le chiavi si applicano all'app desktop. Lasciano invariati gli altri modi di eseguire Claude Code, come la CLI, Cowork e le sessioni cloud:

• La CLI: nessuna delle chiavi impedisce a uno sviluppatore di eseguire la CLI di Claude Code sul proprio computer
• Cowork: nessuna delle chiavi si applica alle sessioni Cowork o alle attività pianificate di Cowork
• Sessioni cloud: nessuna delle chiavi cambia la disponibilità delle sessioni cloud. Per disattivarle, usa l'impostazione Cloud sessions in Admin console controls.

Quando adatti l'esempio, controlla i nomi host, la versione di Desktop e i permessi del file:

• Nomi host: assicurati che un modello in sshHostAllowlist corrisponda al nome host di ciascuna voce di sshConfigs, senza user@, altrimenti gli sviluppatori non potranno connettersi. Per sapere come Desktop confronta un nome host, consulta Restrict which SSH hosts users can connect to.
• Versione: disableDesktopLocalSessions richiede Claude Desktop v1.37937.0 o versioni successive
• Permessi del file: assicurati che l'account di ogni sviluppatore sul computer possa leggere il file di impostazioni gestite. Desktop non applica le chiavi presenti in un file che l'account non può leggere, e anche Claude Code si avvia senza di esse.

Inserisci le tre chiavi in un'unica fonte gestita, quella con priorità più alta tra quelle che distribuisci. Se distribuisci impostazioni gestite dal server, mantieni anche una copia delle tre chiavi nella policy MDM o nel file di impostazioni gestite con priorità più alta su ciascun computer. Desktop recupera le impostazioni gestite dal server all'avvio e la copia sul computer si applica finché un recupero non riesce.

Per verificare che le impostazioni vengano applicate, controlla il computer di uno sviluppatore:

1. Controlla il selettore di ambiente

Chiudi e riapri Desktop, poi apri il selettore di ambiente. Le impostazioni sono applicate se mostra:

• La voce relativa a quel computer, in grigio
• Shared Dev VM sotto SSH. Se non è elencata lì, fai clic sulla singola riga SSH, oppure su More alla fine del gruppo.

Se la voce relativa al computer è ancora disponibile, verifica queste cause:

• Versione di Desktop: aggiorna Desktop se è precedente alla v1.37937.0.
• File delle impostazioni gestite: assicurati che il file sia un JSON valido.
• Fonte gestita: assicurati che il computer legga la fonte gestita che contiene le chiavi.

2. Aggiungi un host che non è nell'allowlist

Aggiungi una connessione SSH con un hostname che non è nell'allowlist, come other.example.com. Desktop salva la connessione ma rifiuta di connettersi, e indica che le impostazioni della tua organizzazione non consentono la connessione.

Configurazione aziendale

Le organizzazioni su piani Team o Enterprise possono gestire il comportamento dell'app desktop tramite controlli della console di amministrazione, file di impostazioni gestiti e criteri di gestione dei dispositivi.

Controlli della console di amministrazione

Queste impostazioni sono configurate tramite la console delle impostazioni di amministrazione:

• Desktop: controlla se gli utenti della tua organizzazione possono accedere a Claude Code nell'app desktop
• Cloud sessions: abilita o disabilita le sessioni cloud per la tua organizzazione
• Remote Control: abilita o disabilita Remote Control per la tua organizzazione

Nelle organizzazioni Enterprise con HIPAA abilitato, l'interruttore Desktop è disattivato per impostazione predefinita e un Owner può attivarlo. L'applicazione della configurazione HIPAA lo disattiva, anche se era attivo, quindi un Owner deve riattivarlo in seguito. Anche Cloud sessions e Remote Control sono disattivati per impostazione predefinita, e un Owner non può attivarli una volta che all'organizzazione è stata applicata la configurazione HIPAA.

[!NOTE]

Il modulo OpenTelemetry per Cowork sotto Monitoring nelle impostazioni di Data and privacy della console di amministrazione si applica solo alle sessioni Cowork. In una sessione Cowork su questa macchina, l'app desktop passa quel collector a Claude Code come variabili d'ambiente OTEL_*, quindi il modulo ha effetto anche se Claude Code in quella sessione non recupera mai le impostazioni della console di amministrazione.

Per esportare la telemetria dalle sessioni della scheda Code, imposta CLAUDE_CODE_ENABLE_TELEMETRY e le variabili OTEL_* nel blocco env delle tue impostazioni gestite di Claude Code, come mostrato in configurazione dell'amministratore per il monitoraggio. Le sessioni locali, cloud e SSH leggono ciascuna impostazioni gestite da fonti diverse. Per gli host che una sessione cloud può raggiungere, vedi accesso alla rete. Per il service.name che le sessioni della scheda Code segnalano, vedi informazioni sul servizio.

Per scoprire su quale macchina remota è stata eseguita una sessione SSH, vedi Attribuire la telemetria alle sessioni SSH di Desktop.

Impostazioni gestite

Le impostazioni gestite sovrascrivono le impostazioni del progetto e dell'utente e si applicano alle sessioni Claude Code in Desktop. Puoi impostare queste chiavi nel file impostazioni gestite della tua organizzazione o inviarle in remoto tramite la console di amministrazione.

Quali impostazioni gestite raggiungono una sessione Desktop dipende da dove quella sessione viene eseguita. Le restrizioni del modello come availableModels vengono applicate nelle sessioni Claude Code di Desktop nello stesso modo che nel CLI del terminale; vedi copertura della superficie.

• Sessioni locali su questa macchina: un file di impostazioni gestite distribuito su disco si applica. Le impostazioni gestite inviate in remoto tramite la console di amministrazione raggiungono anche queste sessioni sull'API di Anthropic quando la sessione si autentica con un accesso idoneo, seguendo la stessa precedenza delle impostazioni del CLI del terminale.
• Sessioni cloud: ricevono impostazioni gestite dal server; i file distribuiti su dispositivo non le raggiungono, perché vengono eseguite su VM gestite da Anthropic. Le sessioni instradate a un ambiente self-hosted leggono anche il file di impostazioni gestite nell'immagine del runner. Come Claude Code combina le fonti gestite dice quando quel file si applica.
• Sessioni SSH: la sessione legge il file di impostazioni gestite dall'host remoto. Desktop stesso legge sshConfigs, sshHostAllowlist, disableSshSavedPasswords e disableDesktopLocalSessions sulla macchina locale. Se fornisci più di una fonte gestita, le legge da una sola per impostazione predefinita.
• Sessioni Cowork: in una sessione Cowork su questa macchina, Claude Code non recupera mai le impostazioni della console di amministrazione, anche quando l'utente accede con un account Team o Enterprise, e legge la politica distribuita sulla macchina a meno che la tua configurazione di Claude Desktop non imposti requireCoworkFullVmSandbox. Le sessioni Cowork remote non ricevono nessuna delle due. Vedi dove e quando una politica si applica per sapere quali file di dispositivo raggiungono Cowork, e regole di permesso MCP per come le regole Bash e WebFetch si applicano agli strumenti di Cowork.

Nelle sessioni locali e SSH, l'app desktop fornisce i connettori claude.ai connessi di ogni utente a Claude Code direttamente. Nessuna impostazione MCP o managed-mcp.json raggiunge quei connettori, indipendentemente dalla fonte di impostazioni o dalla posizione del file che usi. Per bloccare gli strumenti di un connettore in queste sessioni, usa i controlli degli strumenti del connettore della tua organizzazione. Come i connettori raggiungono Claude Code mostra quali impostazioni governano i connettori in ogni tipo di sessione.

permissions.disableBypassPermissionsMode e disableAutoMode funzionano anche nelle impostazioni dell'utente e del progetto, ma metterli nelle impostazioni gestite impedisce agli utenti di sovrascriverli.

Per le chiavi di permesso, plugin e consegna che solo una fonte gestita può impostare, vedi Chiavi che solo le impostazioni gestite possono impostare.

Criteri di gestione dei dispositivi

I team IT possono gestire l'app desktop tramite MDM su macOS, criteri di gruppo su Windows o un file di criteri su Linux. I criteri disponibili includono l'abilitazione o la disabilitazione della funzione Claude Code, il controllo degli aggiornamenti automatici su macOS e Windows e l'impostazione di un URL di distribuzione personalizzato.

• macOS: configura tramite il dominio di preferenza com.anthropic.claudefordesktop usando strumenti come Jamf o Kandji
• Windows: configura tramite il registro in SOFTWARE\Policies\Claude
• Linux: configura tramite un file di proprietà di root in /etc/claude-desktop/managed-settings.json, che contiene le chiavi dei criteri come oggetto JSON. Desktop rifiuta il file se chiunque diverso da root può scrivere su di esso o sulla sua cartella. È un file diverso dal file di impostazioni gestite di Claude Code.

Requisiti di accesso alla rete

Desktop carica il suo codice applicativo e il contenuto dell'utente dagli host CDN di Anthropic.

anthropic.com
*.anthropic.com
claude.ai
*.claude.ai
claude.com
*.claude.com
claude.app
*.claude.app
*.claudeusercontent.com
*.claudemcpcontent.com

Il traffico è HTTPS sulla porta 443 a meno che non configuri una porta personalizzata per OTLP, un gateway LLM o un server MCP.

Per i server proxy, autorità di certificazione personalizzate, mTLS e i domini di cui ha bisogno il CLI standalone, vedi configurazione della rete.

Per ridurre il numero di wildcard del firewall, consenti invece questi host Anthropic. Alcuni sottodomini vengono generati dinamicamente e devono rimanere wildcard.

anthropic.com
api.anthropic.com
a-api.anthropic.com
a-cdn.anthropic.com
s-cdn.anthropic.com
assets-proxy.anthropic.com
claude.ai
a.claude.ai
assets.claude.ai
downloads.claude.ai
*.livepreview.claude.ai
claude.com
platform.claude.com
*.livepreview.claude.app
*.claudeusercontent.com
*.claudemcpcontent.com

Se la tua organizzazione ha IP allowlisting abilitato per Claude, instrada bridge.claudeusercontent.com attraverso lo stesso egresso proxy di claude.ai e api.anthropic.com. Se non puoi instradarlo in quel modo, aggiungi l'indirizzo di egresso che il tuo proxy utilizza per quell'host all'allowlist IP della tua organizzazione, ma solo quando quell'indirizzo è dedicato alla tua organizzazione: un intervallo di egresso proxy condiviso ammette anche gli altri clienti del fornitore proxy.

Anthropic controlla le connessioni a quell'host rispetto all'allowlist IP della tua organizzazione utilizzando l'indirizzo da cui arrivano. Se il tuo proxy invia il traffico per esso attraverso un indirizzo che non è in quell'allowlist, Claude in Chrome e altre funzionalità che si connettono attraverso il bridge smettono di funzionare mentre il resto dell'app continua a funzionare.

Un artefatto che carica un carattere da Google Fonts richiede anche fonts.googleapis.com e fonts.gstatic.com. Entrambi gli host sono facoltativi. Se li blocchi, gli artefatti vengono renderizzati in caratteri di fallback. Blocca con un rifiuto veloce piuttosto che un drop silenzioso in modo che la richiesta di carattere fallisca immediatamente invece di ritardare il primo rendering della pagina.

Gli artefatti possono anche caricare librerie JavaScript, come React o un pacchetto di grafici, da cdnjs.cloudflare.com, cdn.jsdelivr.net, cdn.tailwindcss.com, code.jquery.com e unpkg.com, e da nessun altro host esterno. Se blocchi quegli host, le parti di un artefatto che dipendono da una libreria non funzionano, e a differenza di un carattere bloccato, una libreria bloccata non ha fallback. Blocca con un rifiuto veloce anche qui, in modo che una richiesta di libreria bloccata fallisca subito piuttosto che rimanere in sospeso fino al timeout.

Autenticazione e SSO

Le organizzazioni Team e Enterprise possono richiedere SSO per tutti gli utenti. Vedi autenticazione per i dettagli a livello di piano e Configurazione di SSO per la configurazione SAML; la configurazione OIDC è coperta nella Guida dell'amministratore aziendale di Claude.

Gestione dei dati

Claude Code elabora il tuo codice localmente nelle sessioni locali, o nelle sessioni cloud sull'infrastruttura gestita da Anthropic, a meno che la tua organizzazione non le indirizzi a un ambiente self-hosted. Le sessioni cloud, incluse in un ambiente self-hosted, inviano conversazioni e contesto del codice all'API di Anthropic per l'elaborazione; le sessioni locali e SSH le inviano a qualunque fornitore di modello configura la tua distribuzione, l'API di Anthropic per impostazione predefinita. Vedi gestione dei dati per i dettagli sulla conservazione dei dati, la privacy e la conformità.

Distribuzione

Desktop può essere distribuito tramite strumenti di distribuzione aziendale:

• macOS: distribuisci tramite MDM come Jamf o Kandji usando il programma di installazione .dmg
• Windows: distribuisci tramite il pacchetto MSIX. Vedi Distribuisci Claude Desktop per Windows per le opzioni di distribuzione aziendale inclusa l'installazione silenziosa

Per i domini da inserire nell'allowlist del firewall, vedi requisiti di accesso alla rete sopra. Per le impostazioni proxy, le autorità di certificazione personalizzate e i gateway LLM, vedi configurazione della rete.

Per il riferimento completo della configurazione aziendale, vedi la guida alla configurazione aziendale.

Provieni dalla CLI?

Se usi già la CLI di Claude Code, Desktop esegue lo stesso motore sottostante con un'interfaccia grafica. Puoi eseguire entrambi contemporaneamente sulla stessa macchina, anche sullo stesso progetto. Ognuno mantiene il proprio elenco di sessioni, e puoi portare una sessione CLI in Desktop. Condividono configurazione e memoria del progetto tramite file CLAUDE.md.

Per spostare una sessione CLI in Desktop, esegui /desktop nel terminale. Claude salva la tua sessione e l'apre nell'app desktop, quindi esce dalla CLI. Questo comando è disponibile su macOS e Windows x64 quando sei connesso con un abbonamento Claude. Non è disponibile con autenticazione tramite chiave API o su Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry.

Dalla tua shell, claude --desktop apre Desktop direttamente senza avviare una sessione di terminale. Richiede Claude Code v2.1.285 o successivo e ha gli stessi requisiti di piattaforma e accesso di /desktop. Senza altri argomenti, apre Desktop nella directory corrente. Per aprire una sessione CLI esistente in Desktop, aggiungi --continue per la conversazione più recente in questa directory, o --resume con l'ID della sessione che /status mostra:

claude --desktop --resume <session-id>

Claude Code stampa Opening session <session-id> in Claude Desktop, la sessione si apre nell'app e il comando esce. Un nome di sessione non funziona al posto dell'ID. Claude Code non sposta una sessione che è aperta in un altro terminale o ancora in esecuzione in background. Se Claude Desktop non è installato, il comando stampa un link di download ed esce.

Puoi anche riprendere una sessione CLI da Desktop con /resume. Il comando è disponibile nelle sessioni locali, non in SSH, WSL o sessioni cloud.

Per continuare una sessione di terminale in Desktop:

1. Chiudi la sessione nel terminale.
2. Nella casella del prompt di Desktop, digita /resume. Desktop elenca le sessioni che hai avviato dalla CLI su questo computer. Cerca per titolo, cartella o branch, e visualizza in anteprima dove ognuna si è fermata.
3. Seleziona la sessione. Continua nell'app con la sua conversazione completa e il contesto.

Desktop continua la stessa sessione piuttosto che una copia, quindi claude --resume nel terminale la trova ancora dopo.

[!TIP]

Quando usare Desktop vs CLI: usa Desktop quando vuoi gestire sessioni parallele in una finestra, organizzare pannelli uno accanto all'altro, o rivedere le modifiche visivamente. Usa la CLI quando hai bisogno di scripting, automazione, o preferisci un workflow da terminale.

Equivalenti dei flag CLI

Questa tabella mostra l'equivalente dell'app desktop per i flag CLI comuni. I flag non elencati non hanno equivalente desktop perché sono progettati per scripting o automazione.

Configurazione condivisa

Desktop e CLI leggono gli stessi file di configurazione, quindi la tua configurazione viene trasferita:

• I file CLAUDE.md e CLAUDE.local.md nel tuo progetto vengono utilizzati da entrambi
• I server MCP configurati in ~/.claude.json o .mcp.json funzionano in entrambi
• Gli hook e le skill definiti nelle impostazioni si applicano a entrambi
• Le impostazioni in ~/.claude.json e ~/.claude/settings.json sono condivise. Le regole di permesso, gli strumenti consentiti e altre impostazioni in settings.json si applicano alle sessioni Desktop.
• Modelli: gli stessi modelli sono disponibili in entrambi. In Desktop, seleziona il modello dal selettore del modello nella riga sotto la casella del prompt. Puoi cambiare il modello durante una sessione dallo stesso selettore.

Server MCP dall'app desktop chat Claude

L'app Desktop carica i server MCP da claude_desktop_config.json nelle sessioni locali della scheda Code, insieme ai server da ~/.claude.json e .mcp.json. Un server definito in claude_desktop_config.json è disponibile sia nella superficie desktop chat sia nelle sessioni locali della scheda Code.

Se definisci lo stesso nome di server in claude_desktop_config.json e in ~/.claude.json o .mcp.json, la scheda Code nelle sessioni locali si connette una volta e utilizza la definizione di claude_desktop_config.json.

L'app inoltre ri-consegna i server stdio da ~/.claude.json alla CLI incorporata nelle sessioni locali. Quando il livello superiore di ~/.claude.json (ambito utente) e .mcp.json definiscono lo stesso nome di server stdio, la scheda Code utilizza la definizione di ~/.claude.json, divergendo dalla gerarchia di ambito della CLI.

[!NOTE]

La CLI standalone non legge claude_desktop_config.json. Su macOS e WSL, esegui claude mcp add-from-claude-desktop per copiare questi server in ~/.claude.json. Vedi Importa server MCP da Claude Desktop per il flusso di importazione e le opzioni di ambito.

Confronto delle funzionalità

Questa tabella confronta le capacità principali tra CLI e Desktop. Per un elenco completo dei flag CLI, vedi il riferimento CLI.

Cosa non è disponibile in Desktop

Le seguenti funzionalità non sono disponibili in Desktop, tranne dove diversamente indicato:

• Provider di terze parti: Desktop si connette all'API di Anthropic per impostazione predefinita. Per instradare Desktop attraverso un gateway, o per eseguire la scheda Code su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry o un gateway LLM self-hosted, segui i link nella riga Provider di terze parti.
• Linux (beta): Computer Use non è ancora disponibile nell'app desktop Linux. Vedi Claude Desktop su Linux.
• Suggerimenti di codice inline: Desktop non fornisce suggerimenti in stile autocomplete. Funziona tramite prompt conversazionali e modifiche di codice esplicite, e può suggerirti il prossimo prompt dopo che Claude ha risposto.
• Team di agenti: team coordinati, dove Claude come team lead assegna compiti ai compagni di squadra da un elenco di compiti condiviso, sono disponibili nella CLI, non in Desktop. Per il lavoro multi-agente all'interno di una sessione, usa i workflow dinamici, che vengono eseguiti in Desktop; Claude può anche inviare messaggi alle tue altre sessioni e gestirle direttamente.
• Comandi terminal-dialog: i comandi integrati che aprono un pannello interattivo nel terminale si comportano diversamente nella scheda Code. Modifica direttamente i file di impostazioni per gestire le regole di permesso e la configurazione, oppure esegui i comandi dalla CLI standalone.
  • I comandi senza forma di argomento, come /permissions, rispondono con isn't available in this environment.
  • /config apre Impostazioni → Claude Code. Il testo dopo il comando viene ignorato, quindi /config theme=dark non imposta il tema.

Troubleshooting

Le sezioni di seguito coprono i problemi specifici dell'app desktop. Per gli errori API di runtime che appaiono nella chat come API Error: 500, 529 Overloaded, 429 o Prompt is too long, vedi il riferimento degli errori.

Check your version

Per vedere quale versione dell'app desktop stai eseguendo:

• macOS: fai clic su Claude nella barra dei menu, quindi About Claude
• Windows: fai clic su Help, quindi About Claude

Fai clic sul numero di versione per copiarlo negli appunti.

Versione di Claude Code nella scheda Code

Per vedere quale versione di Claude Code esegue una sessione, digita /status in una sessione locale nella scheda Code e leggi la riga Claude Code, che mostra una versione come 2.1.286.

Per ottenere una versione più recente per le sessioni locali, apri Claude > Check for Updates… su macOS o Help > Check for Updates… su Windows, quindi avvia una nuova sessione.

In una sessione locale, la scheda Code esegue una propria copia di Claude Code, che ha un proprio numero di versione. L'app desktop scarica e aggiorna quella copia, quindi può differire dal comando claude nel tuo terminale, e aggiornarne una non aggiorna l'altra.

Verifica quale layout hai

Se una nuova sessione non ha il selettore dell'ambiente sotto la casella del prompt, hai il layout precedente:

• Desktop precedente alla v2.37337.0: aggiorna per ottenere il layout attuale. Seleziona Claude > Check for Updates… su macOS o Help > Check for Updates… su Windows.
• Provider di terze parti: mantieni il layout precedente, quindi non c'è nulla da fare.

Nel layout precedente, scegli l'ambiente e la cartella del progetto sopra la casella del prompt, e la modalità di permesso e il modello nella riga sottostante. Il layout precedente non dispone del pannello dei dettagli della sessione e degli ambienti locali e SSH salvati.

403 or authentication errors in the Code tab

Se vedi Error 403: Forbidden o altri errori di autenticazione quando usi la scheda Code:

1. Esci e accedi di nuovo dal menu dell'app. Questo è il fix più comune.
2. Verifica di avere un abbonamento a pagamento attivo: Pro, Max, Team o Enterprise.
3. Se la CLI funziona ma Desktop no, esci completamente dall'app desktop, non solo chiudere la finestra, quindi riapri e accedi di nuovo.
4. Controlla la tua connessione Internet e le impostazioni del proxy.

Blank or stuck screen on launch

Se l'app si apre ma mostra una schermata vuota o non reattiva:

1. Riavvia l'app.
2. Controlla gli aggiornamenti in sospeso. Su macOS e Windows l'app si aggiorna automaticamente al lancio; su Linux, aggiorna tramite apt come descritto in Claude Desktop on Linux.
3. Su una rete gestita, conferma che il tuo firewall consente gli host CDN nei requisiti di accesso alla rete.
4. Su Windows, controlla Event Viewer per i log di crash sotto Windows Logs → Application.

"Failed to load session"

Se vedi Failed to load session, la cartella selezionata potrebbe non esistere più, un repository Git potrebbe richiedere Git LFS che non è installato, o i permessi dei file potrebbero impedire l'accesso. Prova a selezionare una cartella diversa o riavvia l'app.

Session not finding installed tools

Se Claude non riesce a trovare strumenti come npm, node o altri comandi CLI, verifica che gli strumenti funzionino nel tuo terminale regolare, controlla che il tuo profilo shell configuri correttamente PATH e riavvia l'app desktop per ricaricare le variabili di ambiente.

Git and Git LFS errors

Le sessioni che vengono eseguite nel loro proprio worktree hanno bisogno di Git. Se vedi "Git is required," installa Git, o Git for Windows su Windows, e riprova. Su Windows, le versioni di Claude Desktop precedenti a 1.49585.0 chiedevano Git prima di avviare qualsiasi sessione locale; se vedi quel prompt e non stai usando worktrees, aggiorna l'app.

Se vedi "Git LFS is required by this repository but is not installed," installa Git LFS da git-lfs.com, esegui git lfs install e riavvia l'app.

MCP servers not working on Windows

Se gli interruttori del server MCP non rispondono o i server non riescono a connettersi su Windows, controlla che il server sia configurato correttamente nelle tue impostazioni, riavvia l'app, verifica che il processo del server sia in esecuzione in Task Manager e rivedi i log del server per gli errori di connessione.

La connessione SSH non riesce dopo l'accesso

Trova il titolo della scheda, o il codice alla fine del messaggio di errore, in questa tabella, quindi fai ciò che indica l'ultima colonna. Per vedere il messaggio, seleziona View details sulla scheda dell'errore.

Per qualsiasi altro messaggio, controlla i requisiti della macchina remota.

Ottieni i log di Desktop per un problema SSH

Ottieni ssh.log, il log in cui Desktop registra le sue connessioni SSH, in un file zip dei log di Desktop che salvi dal menu Help. Per salvarlo, apri Help > Troubleshooting e seleziona la voce per il tuo sistema:

• macOS: Show Logs in Finder
• Windows: Show Logs in File Explorer
• Linux: Show Logs in File Manager

Esamina i file prima di inviarli, perché possono includere nomi e altri dettagli dal tuo ambiente. <host> e <user> indicano nomi che Desktop ha sostituito. Desktop non sostituisce tutti i nomi, e un nome di host o di utente SSH può comunque apparire così com'è scritto. Se invii il file zip a qualcuno, indica quale host non è riuscito e quando, perché i log potrebbero non nominarlo.

Il file zip non contiene il log del programma helper che Desktop installa sulla macchina remota. Per ottenere anche quel log, copia remote-server.log dalla cartella dell'helper sotto ~/.claude/remote/run/ nella directory home dell'utente che si è connesso. Esamina anche quel file prima di inviarlo.

App won't quit

• macOS: premi Cmd+Q. Se l'app non risponde, usa Force Quit con Cmd+Option+Esc, seleziona Claude e fai clic su Force Quit.
• Windows: usa Task Manager con Ctrl+Shift+Esc per terminare il processo Claude.

Windows-specific issues

• PATH not updated after install: apri una nuova finestra di terminale. Gli aggiornamenti di PATH si applicano solo alle nuove sessioni di terminale.
• Concurrent installation error: se vedi un errore su un'altra installazione in corso ma non ce n'è una, prova a eseguire il programma di installazione come Amministratore.

"Branch doesn't exist yet" when opening in CLI

Le sessioni cloud possono creare branch che non esistono sulla tua macchina locale. Fai clic sul nome del branch nella sessione e seleziona Copy branch name, quindi recuperalo localmente:

git fetch origin <branch-name>
git checkout <branch-name>

Still stuck?

• Apri Help → Get Support nell'app desktop, o visita il centro di supporto Claude direttamente
• Per i problemi che si riproducono anche nella CLI claude standalone, cerca o segnala un bug su GitHub Issues

Quando segnali un problema, includi la versione dell'app desktop, il tuo sistema operativo, il messaggio di errore esatto e i log pertinenti. Su macOS, controlla Console.app. Su Windows, controlla Event Viewer → Windows Logs → Application. Rivedi gli estratti dei log prima di pubblicarli in un problema pubblico; possono includere percorsi di file e altri dettagli dal tuo ambiente.