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.

Nell'app Claude Desktop, Claude Code è la scheda Code. L'app include anche la chat e Cowork, che gestisce Dispatch e il lavoro agentico più lungo. Questa pagina è il riferimento per la scheda Code.

[card] Scarica per macOS

Build universale per Intel e Apple Silicon

[card] Scarica per Windows

Per processori x64

[card] 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.

Avviare 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 viene eseguito Claude. Consulta la configurazione dell'ambiente.
  • Se una nuova sessione non mostra alcun 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 in cui lavora Claude.
  • Sessione cloud: seleziona i 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 della 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.

Scrivi il tuo compito e premi Enter per iniziare. Ogni sessione tiene traccia in modo indipendente del proprio contesto e delle proprie modifiche.

Lavorare con il codice

Fornisci a Claude il contesto giusto, controlla quanto fa in autonomia e rivedi ciò che ha modificato.

Usare la casella del prompt

Scrivi cosa vuoi che Claude faccia e premi Enter per inviare. Claude legge i file del tuo progetto, apporta modifiche ed esegue comandi in base alla tua modalità di permesso. Puoi reindirizzare Claude in qualsiasi momento: fai clic sul pulsante di stop per interromperlo immediatamente, oppure scrivi una correzione e premi Enter per inviarla senza fermare l'azione in corso. Claude legge la correzione non appena l'azione corrente termina e si adegua prima del passaggio successivo.

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

Accettare un prompt suggerito

Dopo la risposta di Claude, 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 tuoi costi API.

• Usa il suggerimento: premi Tab o Freccia destra per inserirlo nella casella del prompt, modificalo se vuoi, quindi premi Enter per inviarlo. Premere Enter 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.

Disattiva Prompt suggestions in Settings > Code o Settings > Claude Code per interrompere i suggerimenti. Ogni sessione smette di mostrarli la volta successiva che viene avviata o ripresa.

Aggiungere file e contesto ai prompt

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

• Menziona file con @: digita @ seguito da un nome 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 primo messaggio senza il file, quindi 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, oppure trascina i file direttamente nel prompt. È 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 fornire a Claude qualsiasi altro file dalla cartella della sessione, menzionalo con @.

Scegliere 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 personalmente ogni modifica, 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à scelta 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 chiamavano queste modalità Ask permissions, Auto accept edits e Plan mode.

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

[!TIP]

Avvia le attività complesse in Plan così Claude definisce un approccio prima di apportare modifiche. Una volta approvato il piano, passa ad Accept edits o Manual per eseguirlo. Consulta plan mode per saperne di più 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 Enterprise possono limitare le modalità di permesso disponibili. Consulta configurazione enterprise per i dettagli.

Disponibilità della modalità auto

La modalità auto è disponibile per 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 è disponibile anche per impostazione predefinita; consulta Modalità auto su Bedrock, Agent Platform o Foundry per i modelli supportati.

Visualizzare l'anteprima della tua app

Claude può avviare un server di sviluppo e aprirlo nel riquadro Browser per verificare le sue modifiche. Funziona sia per le app web frontend sia per i server backend: Claude può testare endpoint API, visualizzare i log del server e iterare sui 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 mostrare l'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 dispone degli strumenti del riquadro. Per vedere tu stesso l'app, inoltra la sua porta al tuo computer.

Se il riquadro Browser non è aperto dopo che Claude ha avviato 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
• Osservare Claude verificare automaticamente le proprie modifiche: acquisisce screenshot, ispeziona il DOM, fa clic sugli elementi, compila moduli e corregge i problemi che trova
• Avviare o arrestare i server, oppure arrestarli tutti insieme, dal menu Dev servers nell'intestazione del riquadro Browser
• Scegliere se il Browser conserva i cookie dopo la chiusura dell'app con Keep cookies nel menu ⋮ del riquadro Browser, così non devi accedere di nuovo durante lo sviluppo

Claude crea la configurazione iniziale del server in base al tuo progetto. Se la tua app usa un comando di sviluppo personalizzato, modifica .claude/launch.json in base alla tua configurazione. Consulta Configurare i 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 Settings > Code o Settings > Claude Code.

Navigare su siti esterni

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

La prima volta che fai clic su un link esterno nella chat, una finestra di dialogo chiede se i link devono aprirsi nel riquadro Browser o nel tuo browser predefinito. Per cambiare la 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 direttamente un link nel tuo browser predefinito.

Claude può leggere e interagire con le 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 sulle pagine esterne, come fare clic e digitare, in ogni modalità di permesso. Sono gli stessi classificatori usati dalla 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, si applica anche un controllo dell'allowlist dei domini prima che Claude navighi verso un nuovo sito.

Approvare le azioni di Claude su un sito

La prima volta che Claude agisce su un sito esterno, compare 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 Settings. Ogni sito richiede la propria approvazione, inclusi i sottodomini. I tuoi server di sviluppo locali e i file del progetto non richiedono approvazione, quindi la verifica automatica continua a funzionare senza richieste.

Anche su un sito approvato, Claude non acquista articoli, non crea account né aggira CAPTCHA senza il tuo intervento. La navigazione nel riquadro Browser usa lo stesso modello di sicurezza dell'estensione Claude in Chrome. Consulta Using Claude in Chrome safely per sapere come Claude gestisce i siti sensibili e le azioni rischiose.

Scegliere tra il Browser e l'estensione Chrome

Il riquadro Browser usa un profilo browser pulito, separato dal tuo browser personale, senza nessuno dei tuoi accessi salvati né della tua cronologia. Usalo per creare e testare la tua app e per i siti che non richiedono la tua identità. Quando vuoi che Claude agisca a tuo nome nelle sessioni in cui hai effettuato l'accesso, usa invece l'estensione Claude in Chrome, che condivide lo stato di accesso del tuo browser.

Limitare 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 questi elenchi per l'estensione, il Browser li rispetta automaticamente. Gli amministratori possono anche disattivare gli strumenti di Claude sulle pagine esterne con l'impostazione gestita browserExternalPageTools. Con gli strumenti disattivati, gli utenti possono comunque visitare siti esterni; gli strumenti di Claude non possono leggerli né 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 di sviluppo su localhost e le anteprime dei file continuano a funzionare. Usa browserExternalPageTools per consentire agli utenti di continuare a navigare su siti esterni senza gli strumenti di Claude, e disableBrowserExternalNavigation per bloccare i siti esterni sia per gli utenti sia per Claude.

Rivedere le modifiche con la vista diff

Dopo che Claude ha apportato modifiche al tuo codice, la vista diff ti permette di rivedere le modifiche file per file prima di creare una pull request. Per aprire la vista 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. Il diff di una sessione cloud rispetto al branch di base può omettere le modifiche non ancora inviate.

Per commentare righe specifiche, passa il mouse su una riga e fai clic sul + che compare accanto al numero di riga per aprire una casella di commento. Scrivi il tuo feedback e premi Enter per aggiungere il commento. Dopo aver aggiunto commenti a più righe, invia tutti i commenti insieme:

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

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

Fare la revisione del tuo codice

Per far rivedere a Claude le tue modifiche prima di fare il commit, inserisci /code-review nella casella del prompt. I risultati arrivano nella conversazione al termine della revisione.

Nelle sessioni locali, SSH e WSL, i risultati compaiono come una scheda Code review, raggruppati per file. Usa la scheda per intervenire:

• Fai clic su Walk through in diff per aprire la vista diff e scorrere i risultati uno alla volta. Un risultato presente nel diff corrente compare 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 quanto trovato dalla revisione. Per sapere cosa cerca /code-review e quali argomenti accetta, consulta Revisione locale con /code-review.

Monitorare lo stato della pull request

Per far correggere a Claude i controlli non superati, o per far eseguire a GitHub il merge della pull request, attiva Auto-fix o Merge when ready. Dopo che apri una pull request, questa compare 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 persone diverse 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 usi 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 repository GitHub
• Layout precedente: una volta che la sessione ha una pull request, fai clic su CI nella sua barra di stato.

Per archiviare automaticamente la sessione quando la PR viene unita con merge o chiusa, attiva l'archiviazione automatica in Settings > Code o Settings > Claude Code.

[!NOTE]

Il monitoraggio delle PR richiede che la GitHub CLI (gh) sia installata e autenticata sulla tua macchina. Se gh non è installata, Desktop ti chiede di installarla la prima volta che provi a creare una PR.

In una sessione SSH, configura git e gh sulla macchina remota prima di fare clic su Create PR, perché è lì che Claude esegue il push del branch ed esegue gh pr create. Installa tu stesso gh lì, perché Desktop non te lo chiede in una sessione SSH. Quindi verifica lì che git push funzioni e che gh auth status segnali 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.

Per aprire un altro pannello, fai clic sul relativo pulsante a icona nella barra del titolo della sessione. Passa il mouse sopra ciascun pulsante per vederne il nome, come Terminal, Changes per la vista diff, Browser e Files. Se il pannello che vuoi non ha un pulsante nella barra del titolo, selezionalo dal menu ⋮ accanto ai pulsanti:

• Quando la finestra è stretta: i pulsanti che non entrano si spostano nel menu
• Per i pannelli senza pulsante: pannelli come Background tasks e Plan vengono elencati non appena la sessione ha qualcosa da mostrare in quei pannelli

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, cosa sta eseguendo e il suo utilizzo del contesto. 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. 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: un sottomenu che copia il Absolute path, il Relative path o il Filename del file

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+Ctrl: premi Ctrl+Alt
• Cmd: premi Ctrl

Le scorciatoie che iniziano con Ctrl restano le stesse 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

Per vedere quanto è piena la finestra di contesto di questa sessione, individua il layout della tua scheda Code:

• Layout attuale: l'header della scheda Context nel pannello dei dettagli della sessione la mostra come percentuale. Apri la scheda per vedere cosa sta usando la finestra, per categoria.
• Layout precedente: fai clic sull'anello di utilizzo accanto al selettore di modello. Il suo popover mostra l'utilizzo della finestra di contesto.

In entrambi i layout, digita /context nella casella del prompt per stampare nella chat una suddivisione per categoria della finestra di contesto di questa sessione.

Entrambi i layout hanno l'anello di utilizzo accanto al selettore di modello. Fai clic su di esso per vedere l'utilizzo del piano, che è 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, Max o Ultra. Non è disponibile su piani Team o Enterprise. L'app Claude Desktop deve essere in esecuzione. Su macOS, l'utilizzo del computer richiede macOS 14 o versioni successive.

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, apri Impostazioni, quindi:

• Se il menu Impostazioni elenca Questo computer: vai a Questo computer > Sistema
• Altrimenti: vai a Funzionalità

In Utilizzo del computer, attiva Abilita l'utilizzo del computer:

• Windows: l'interruttore ha effetto immediatamente e la configurazione è completa
• macOS: continua al passaggio successivo

Se non vedi l'interruttore, conferma che sei su macOS o Windows con un piano Pro, Max o Ultra, 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.

In Impostazioni, la sezione Utilizzo del computer in cui hai attivato l'utilizzo del computer 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 passare da una sessione all'altra.

Puoi anche aprire una seconda sessione accanto alla sessione corrente o in una finestra separata:

• Affiancata: tieni premuto Option su macOS o Alt su Windows e fai clic su una sessione nella barra laterale, oppure fai clic con il pulsante destro sulla sessione e seleziona Open in, quindi Split view
• In una finestra separata: tieni premuto Cmd su macOS o Ctrl su Windows e fai clic su una sessione, oppure fai clic con il pulsante destro sulla sessione e seleziona Open in, quindi New window

Nella vista divisa, il riquadro che hai aperto o su cui hai fatto clic per ultimo ha il focus, e l'altro riquadro è attenuato. Per cambiare la sessione mostrata in un riquadro, fai clic in quel riquadro per dargli il focus, quindi fai clic su una sessione nella barra laterale. Per rimuovere dalla vista divisa la sessione con il focus, premi Cmd+Ctrl+W su macOS o Ctrl+Alt+W su Windows.

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. Con il layout attuale, attiva il pulsante Worktree nella riga sotto la casella del prompt.

• Con un provider di terze parti: se la riga sotto la casella del prompt mostra il controllo della cartella del progetto ma nessun pulsante Worktree, fai clic su quel controllo e attiva Worktree
• Come impostazione predefinita per un ambiente locale o SSH 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 > Code o Settings > Claude Code
• Sessioni SSH: imposta Worktree folder sulla connessione SSH

Puoi anche impostare un Branch prefix in Settings > Code o 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 delle sessioni richiede Git. La maggior parte dei Mac include Git per impostazione predefinita. Esegui git --version nel Terminale per verificarlo; se viene visualizzato un numero di versione, Git è installato. Se riscontri errori di Git, chiedi a Claude in 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 > Code o 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 tre 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.
• 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.

Avvia un'attività suggerita da Claude

Quando Claude nota qualcosa che vale la pena correggere al di fuori della tua attività corrente, suggerisce quel lavoro come attività. Nelle sessioni locali e SSH con il layout attuale, il suggerimento è una scheda nella chat, e i suoi pulsanti avviano l'attività oppure la mantengono in questa sessione:

• Start: avvia l'attività in un'altra sessione. Per impostazione predefinita l'attività viene eseguita nell'ambiente della sessione corrente. La scheda mostra quindi lo stato della sessione avviata, e la barra laterale elenca la sessione avviata sotto la sessione corrente.
• Do it here: invia l'attività alla sessione corrente come messaggio
• Options: rivedi o modifica impostazioni come l'ambiente, il modello, il worktree e i permessi prima di fare clic su Start
• Start all: quando la scheda elenca più attività, avvia ciascuna attività nella propria sessione senza attendere che un'attività termini prima di avviare la successiva

Nelle sessioni cloud, e nelle sessioni locali e SSH con il layout precedente, il suggerimento è una scheda Suggested task. Per avviare l'attività nel modo indicato dal pulsante principale della scheda, ad esempio Send to cloud o Start with worktree, fai clic su quel pulsante. Fai clic sulla freccia accanto al pulsante principale per altri modi di avviare l'attività, incluso Do it here.

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, usa un progetto: Claude avvia e traccia le sessioni per te da una sola conversazione. Crea un progetto descrive i passaggi.

[!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 > Code o 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 > Code o 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 si trova in Cowork. Invii un'attività a Dispatch e lui 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.

Segui una sessione avviata da Dispatch

La sessione avviata da Dispatch appare nella barra laterale della scheda Code insieme alle tue altre sessioni. Con il raggruppamento e l'ordinamento predefiniti della barra laterale, cerca la sessione più recente nel gruppo della cartella in cui viene eseguita. 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.

Configura Dispatch

• Piani: Dispatch richiede un piano Pro, Max o Ultra e non è disponibile sui piani Team o Enterprise
• Configurazione, accoppiamento e impostazioni di Dispatch: vedi l'articolo di aiuto di Dispatch

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 workflow riutilizzabili, personalizza il comportamento di Claude e configura server di anteprima. Per gestire connettori, skill e plugin in un unico posto, fai clic su Customize nella barra laterale. La scheda Cowork nell'app Desktop estrae le sue skill, i plugin e i 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, fai clic su Customize nella barra laterale e apri Connectors.

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:

[tab] 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
    }
  ]
}

[tab] 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
    }
  ]
}

[tab] 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 viene eseguito Claude e come ti connetti:

• Local: viene eseguito sulla tua macchina con accesso diretto ai tuoi file
• Cloud: viene eseguito per impostazione predefinita su un'infrastruttura gestita da Anthropic. Le sessioni continuano anche se chiudi l'app.
• SSH: viene eseguito su una macchina remota a cui ti connetti tramite SSH, come i tuoi 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, usando la sua toolchain Linux e i percorsi nativi

Creare un ambiente salvato

Un ambiente salvato è una voce nel selettore dell'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 lavora Claude. Gli ambienti locali e SSH salvati fanno parte del layout attuale, quindi se non li vedi, verifica quale layout hai e come ottenere quello attuale.

1. Apri la finestra di dialogo New environment

Apri il selettore dell'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 dell'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 dell'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.

Variabili d'ambiente nelle sessioni locali

Per impostare una variabile d'ambiente per una sessione locale, aggiungila a un ambiente locale salvato, quindi avvia una nuova sessione da quell'ambiente.

Variabili come PATH e CLAUDE_CONFIG_DIR hanno istruzioni specifiche:

Su macOS o Linux, se una variabile che hai impostato con export manca o ha un valore errato in un comando eseguito da Claude, consulta Variabile esportata mancante o errata nei comandi eseguiti da Claude.

Impostare variabili d'ambiente per le sessioni locali

Aggiungi le variabili a un ambiente locale salvato e avvia le tue sessioni da lì. Desktop imposta da sé alcune variabili, come API_TIMEOUT_MS, e per queste le tue sessioni ricevono il suo valore anziché il tuo.

[!NOTE]

Se una nuova sessione non mostra alcun ambiente sotto 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 di un ambiente locale

• Per creare un ambiente locale salvato: seleziona New environment in fondo al menu del selettore dell'ambiente, poi la scheda Local
• Per modificarne uno esistente: nel selettore dell'ambiente, passa il mouse su un ambiente salvato sotto Local e fai clic sull'icona a forma di ingranaggio per aprire Edit environment

2. Inserisci le variabili

Seleziona Environment variables, inserisci una riga KEY=value per ciascuna variabile 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 variabili d'ambiente per i dev server

Per fornire un segreto a un dev server senza inserirlo in un 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 variabili d'ambiente utente o di sistema
• Qualsiasi piattaforma: salvalo nell'editor dell'ambiente locale, se puoi 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 una riga KEY=value per ciascuna variabile e seleziona Save changes. Le variabili che salvi qui vengono archiviate 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.

Variabile esportata mancante o errata nei comandi eseguiti da Claude

Se un comando che Claude esegue su macOS o Linux non riceve una variabile che hai impostato con export in ~/.zshrc o ~/.bashrc, o ne riceve un valore errato, prova questi passaggi nell'ordine:

1. Avvia una nuova sessione

Chiedi a Claude di eseguire di nuovo il comando.

2. Chiudi e riapri Desktop

Poi avvia una nuova sessione.

3. Controlla le variabili salvate

Se un comando riceve il valore errato, verifica se hai impostato la variabile anche in un ambiente salvato o nell'editor dell'ambiente locale. In tal caso, modifica lì il valore e avvia una nuova sessione.

4. Usa un ambiente salvato

Aggiungi la variabile a un ambiente locale salvato, poi avvia una nuova sessione da quell'ambiente. Per una variabile come PATH, CLAUDE_CONFIG_DIR o API_TIMEOUT_MS, segui invece le sue istruzioni specifiche.

Prima della v2.1.304, Claude Code non passa le variabili esportate ai comandi, quindi verifica quale versione esegue la sessione.

Variabili d'ambiente che Desktop imposta da sé

Se hai impostato API_TIMEOUT_MS o ANTHROPIC_BASE_URL e nelle tue sessioni locali non è cambiato nulla, è perché Desktop imposta da sé quelle 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 serve, perché Claude Code ignora quel valore in una sessione locale.

• API_TIMEOUT_MS: una sessione locale riceve 900000, cioè 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 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 così sull'API di Anthropic, tranne che 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 livello di 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 con un livello più alto, avviane una nuova con 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é è il ragionamento adattivo a controllare la profondità del ragionamento. Su Opus 4.6 e Sonnet 4.6, imposta CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING su 1 per usare un budget di ragionamento fisso; i modelli Fable, Sonnet 5 e successivi, Haiku 5.5 e Opus 4.7 e successivi usano sempre il ragionamento adattivo e non hanno una modalità a budget fisso.

Sessioni locali su dispositivi gestiti

Se la voce del tuo computer è disattivata in grigio nel selettore dell'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, appare 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.

Sessioni cloud

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

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

• Aggiungere un ambiente: seleziona New environment in fondo al menu del selettore, poi la scheda Cloud della finestra di dialogo New environment
• Modificare o archiviare uno dei tuoi ambienti: passa il mouse su di esso e fai clic sull'icona a forma di ingranaggio

Consulta Configurare gli ambienti cloud per i dettagli sulla configurazione dell'accesso alla rete e delle variabili d'ambiente.

Sessioni SSH

Le sessioni SSH ti permettono di eseguire Claude Code su una macchina remota usando l'app desktop come interfaccia. Questo è utile per lavorare con codebase che si trovano su VM cloud, dev container o server con hardware o dipendenze specifici.

[!NOTE]

Se usi Desktop con un provider di terze parti, le sessioni SSH richiedono una configurazione specifica. 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 mostra alcun 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 dell'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, il valore predefinito è 22, oppure viene usata la porta della tua configurazione SSH.
• SSH key (optional): percorso della tua chiave privata, ad esempio ~/.ssh/id_ed25519. Lascia vuoto per usare la tua configurazione SSH o l'agente SSH.
• Worktree folder: una cartella sulla macchina remota, ad esempio ~/worktrees, in cui le nuove sessioni creano i propri 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. La macchina e la cartella restano associate come ambiente salvato per le sessioni successive. Desktop lo seleziona per la nuova sessione, quindi scrivi la tua attività e premi Enter.

La macchina remota può eseguire Linux, macOS o Windows. Desktop installa automaticamente Claude Code sulla macchina remota la prima volta che ti connetti. Una volta connesse, le sessioni SSH supportano le modalità di permesso, i connettori, i plugin e i 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 inoltre soddisfare i requisiti di sistema di Claude Code. Su Linux, Claude Code richiede glibc 2.17 o successiva, oppure musl. Per vedere quale ha la macchina, esegui lì ldd --version. 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>.
• MaxSessions 1 sul server: per connetterti a un server il cui sshd_config imposta MaxSessions 1, esegui una di queste operazioni:
  • Il tuo computer esegue macOS o Linux: aggiorna a Claude Desktop v3.1623.0 o successiva
  • Il tuo computer esegue Windows: assicurati che Desktop si connetta tramite il client OpenSSH, perché il client SSH integrato di Desktop non può connettersi a quel server
  • Puoi modificare il server: aumenta MaxSessions, ad esempio al valore predefinito di OpenSSH, 10
• Accessi con MaxSessions 1: usa un accesso che funzioni senza prompt, ad esempio una chiave detenuta dal tuo agente SSH. Desktop accede almeno due volte ogni volta che si connette o si riconnette. Prevedi almeno un accesso in più per ogni scheda del terminale e per ogni sessione di Desktop in cui esegui comandi che iniziano con !. Non ne prevedere nessuno per i comandi eseguiti da Claude.
• Codici monouso con MaxSessions 1: se ogni accesso ti chiede qualcosa, come nel caso dei codici monouso, i comandi ! non riescono. Esegui invece quei comandi in una scheda del terminale, che mostra la richiesta nel proprio riquadro.
• Cartella di installazione: Desktop installa un programma helper 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 ciascun utente che si connette. Per il contenuto di 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 proprie richieste di rete da lì, quindi la macchina deve disporre dell'accesso alla rete richiesto da Claude Code. Se la macchina non può scaricare Claude Code, Desktop lo scarica sul tuo computer e lo carica. Le altre richieste di Claude Code partono comunque dalla macchina remota. Su una macchina remota Linux, se quelle richieste necessitano di un proxy, impostalo per le sessioni SSH.

Verificare la chiave host di una macchina remota

Una chiave host è la chiave che una macchina remota presenta per dimostrare quale macchina è, e un'impronta digitale (fingerprint) è una forma abbreviata di quella chiave. Quando consideri attendibile una chiave, il tuo computer la salva e si connette a qualunque cosa la presenti, senza chiedere di nuovo. Verifica una chiave prima di considerarla attendibile, perché qualcosa potrebbe intercettare la connessione.

Per prima cosa individua a quale macchina appartiene la chiave, in base a dove vedi l'impronta digitale:

• Desktop chiede Connect to <host> for the first time?, oppure hai selezionato Review new key: la macchina indicata da Desktop, <host>
• Desktop chiede Connect through <jump host> for the first time?: il jump host, ovvero la macchina attraverso cui passa la tua connessione, non la macchina che vuoi raggiungere
• ssh chiede o avvisa in un terminale: la macchina indicata dal suo messaggio, che potrebbe non essere quella che hai digitato

Ottieni l'impronta digitale propria di quella macchina dalla macchina stessa, non tramite la connessione che stai verificando:

• La macchina è gestita da qualcun altro: chiedi a quella persona l'impronta digitale della chiave host
• La gestisci tu ed esegue Linux o macOS: esegui ssh-keygen -lf /etc/ssh/ssh_host_<type>_key.pub su di essa, dalla sua console o tramite una connessione che già consideri attendibile. Per <type>, usa il tipo di chiave che Desktop o ssh mostra accanto all'impronta digitale, in minuscolo: ed25519 per ED25519 o ssh-ed25519.

Poi confronta l'impronta digitale della macchina con quella che ti è stata mostrata:

• Corrispondono: considera attendibile la chiave. Seleziona Trust and connect o Trust new key in Desktop, oppure rispondi yes nel terminale.
• Sono diverse, oppure non puoi verificare: non connetterti. Seleziona Cancel in Desktop, oppure rispondi no nel terminale. Se la macchina è gestita da qualcun altro, comunica a quella persona quale impronta digitale ti è stata mostrata.

Se sei arrivato qui da un passaggio di risoluzione dei problemi, torna a quel passaggio dopo l'uno o l'altro risultato.

Impostare un proxy o un certificato CA per le sessioni SSH

Se una macchina remota Linux raggiunge Internet tramite un proxy o necessita di un certificato CA, aggiungi le variabili del proxy e della 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.

In una sessione SSH, Claude Code non riceve le variabili da quei file, anche quando claude in un terminale su quella macchina le riceve. La sessione può quindi bloccarsi, oppure mostrare The connection from … to the API failed o Authentication failed, e accedere di nuovo non serve.

1. Aggiungi le variabili

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

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

2. Invia di nuovo il messaggio

Invia di nuovo il messaggio, perché una variabile che aggiungi o modifichi in quel file ha effetto entro pochi secondi. Avvia una nuova sessione se il problema persiste.

Trovare una variabile del proxy o della CA impostata altrove sulla macchina remota

Verifica se la macchina remota Linux imposta la variabile del proxy o della 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, ad esempio ~/.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 dell'helper, come nei primi due passaggi per rimuovere l'helper. Fallo quando nessuna attività è in esecuzione, perché in entrambi i casi il lavoro di Claude viene interrotto.

Usare la tua configurazione SSH

Puoi usare la tua configurazione SSH su macOS, Linux e Windows quando Desktop si connette tramite il client OpenSSH sul tuo computer:

• 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 successiva.

• Windows: quando Desktop si connette tramite il client OpenSSH, usa il tuo %USERPROFILE%\.ssh\config. Se usi un account Claude anziché un provider di terze parti, la connessione tramite il client OpenSSH richiede tutti questi requisiti:

  • Claude Desktop v2.2553.0 o successiva. Per trovare la tua versione, consulta Verificare la versione.
  • OpenSSH di Microsoft 9.4 o successiva
  • Desktop installato con i pulsanti di download in cima a questa pagina, perché Desktop dal Microsoft Store non si connette tramite il client OpenSSH

  Se non puoi soddisfare questi requisiti, oppure usi un provider di terze parti, consulta Connettersi su Windows senza il client OpenSSH.

Con il client OpenSSH, inserisci un nome Host del tuo file di configurazione nel campo SSH host. Desktop usa quindi le impostazioni di quella voce Host, come HostName, User, IdentityFile, CertificateFile, ProxyJump e ProxyCommand.

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

• Versione del client su macOS e Linux: esegui ssh -V. Il client deve essere OpenSSH 7.6 o successivo.
• Versione del client su Windows: Desktop prova prima l'ssh presente nel tuo PATH, quindi esegui ssh -V. Il client è valido se l'output mostra OpenSSH_for_Windows_ e una versione 9.4 o successiva. Se non è valido, controlla le due cartelle che Desktop prova subito dopo: esegui .\ssh.exe -V in C:\Windows\System32\OpenSSH, poi in C:\Program Files\OpenSSH.
• Nessun client valido su Windows: aggiungi la funzionalità facoltativa OpenSSH Client in Windows e installa gli aggiornamenti di Windows in sospeso, oppure installa la build più recente di Microsoft. Poi chiudi e riapri Desktop. Per vedere se Desktop ha trovato un client OpenSSH utilizzabile, cerca in ssh.log Windows OpenSSH client: seguito da una versione, oppure no usable Windows OpenSSH client.
• Voce: su Windows, usa il client che ha superato la verifica della versione. Esegui ssh con il nome Host, ad esempio 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): con il client OpenSSH, Desktop offre il file di chiave che scegli in aggiunta all'IdentityFile della voce e alle chiavi nel tuo agente SSH. Su Windows, scegli una chiave in formato OpenSSH, perché ssh non legge un file .ppk di PuTTY.

Connettersi su Windows senza il client OpenSSH

Su Windows, ti connetti tramite il client SSH integrato di Desktop se il tuo computer non soddisfa i requisiti per il client OpenSSH. Con un provider di terze parti, ti connetti tramite il client integrato per impostazione predefinita, e il tuo amministratore può modificare questo comportamento. Per l'impostazione, consulta SSH remote sessions in Claude Desktop on 3P.

Con il client integrato, puoi comunque inserire un nome Host della tua configurazione SSH nel campo SSH host se il tuo PATH contiene un comando ssh, con queste limitazioni:

• Impostazioni dalla voce: Desktop prende HostName, User, Port e IdentityFile. Prende anche ProxyCommand se una shell sh è presente nel tuo PATH.
• SSH key (optional): lascia vuoto questo campo per mantenere l'IdentityFile della voce, perché un file di chiave che scegli qui sostituisce l'IdentityFile
• CertificateFile e ProxyJump: Desktop ignora CertificateFile, e la connessione non riesce se la voce imposta ProxyJump. Per usare una di queste impostazioni, connettiti tramite il client OpenSSH.

Raggiungere una macchina dietro un jump host

Per raggiungere una macchina dietro un jump host, detto 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.

Se il tuo amministratore limita gli host SSH, anche il jump host deve essere nell'elenco. Esegui ssh -G bastion.example.com in un terminale sul tuo computer e chiedi all'amministratore di consentire l'hostname che viene stampato.

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 accede la voce, non nel container.

1. Aggiungi la voce

Aggiungi la voce seguente alla fine del tuo ~/.ssh/config, oppure subito 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 resti la stessa quando ricompili l'immagine o ricrei il container
• Fornisci all'account indicato in User un modo per accedere, ad esempio 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. Chiedi all'amministratore di consentire in sshHostAllowlist l'hostname che viene stampato, qui devbox-container. Consentendo quel nome, consente tutto ciò a cui si connette 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 prompt, ad esempio una chiave detenuta 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 delle 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

Su macOS e Linux, per usare una tua variabile d'ambiente in un comando ProxyCommand o Match exec, esportala in un file di avvio della shell, ad esempio ~/.zshrc. Poi chiudi e riapri Desktop. All'avvio, Desktop legge ciò che esporta la tua shell di login e mantiene quei valori finché non lo chiudi.

Questo richiede Claude Desktop v2.37337.0 o successiva 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 alla AWS CLI anziché esportare variabili AWS_*.

Usare credenziali AWS in un ProxyCommand su macOS e Linux

Se imposti credenziali AWS temporanee in un file di avvio della shell, un ProxyCommand che esegue la 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 o AWS_PROFILE.

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

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

Questo esempio aggiunge un profilo chiamato corp che ottiene le credenziali da un programma helper:

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

• region: indica la regione AWS 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é la AWS CLI lo esegue a ogni connessione, incluse le riconnessioni mentre sei via.
• 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 connette 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 confermare, 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 sia il ConnectTimeout impostato. Non puoi aumentare questo limite, perché Desktop imposta da sé ServerAliveInterval e ServerAliveCountMax, e ssh chiude quindi un accesso in cui la macchina remota non invia nulla per quel tempo. Se invece è un jump host o un ProxyCommand ad attendere te, aumenta ConnectTimeout nella voce della macchina remota per coprire quel tempo.

Correggere un blocco Match host che applica solo Desktop

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 di 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 fare in modo che anche Desktop lo salti, aggiungi !originalhost devbox alla sua riga Match:

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

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

Impostazioni di forwarding 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 forwarding vengano applicate solo in alcuni casi, perché lì Desktop può avviare un ssh separato che le segue.

• Per raggiungere una porta sulla macchina remota: esegui tu il forwarding
• 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 con 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, ad esempio un dev server sulla porta 3000, esegui tu il forwarding della porta. In un terminale sul tuo computer, esegui ssh con -L e l'host a cui ti connetti, ad esempio 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 il forwarding TCP, controllato da AllowTcpForwarding nel sshd_config del server SSH.

Macchine remote Windows

Una macchina remota Windows richiede Claude Desktop v2.31226.0 o successiva.

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 vengono testate meno di quelle Linux. Prova il tuo lavoro lì prima di farvi affidamento.

Aspettati queste limitazioni, tra le altre, 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, ad esempio 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 da 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 tutte le macchine remote 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 doverti connettere prima di vedere i messaggi precedenti di una sessione
• Fork: se la shell del server SSH è cmd.exe o Windows PowerShell, puoi creare un 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 sulla macchina i programmi avviati da Claude Code, perché possono continuare a essere eseguiti. L'helper in background installato da Desktop 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 equivale alla sospensione. Un riavvio di Desktop o del computer, anche per un aggiornamento, equivale a una chiusura.

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

[!WARNING]

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

Il lavoro svolto fino a quel momento resta sulla macchina remota e puoi continuare con un messaggio quando torni.

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

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

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

• Dopo la sospensione o una perdita di rete: recuperi l'attività in esecuzione se il processo è ancora in esecuzione e Desktop può accedere senza prompt. In caso contrario, 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 chiudere. Se hai perso l'attività, invia un messaggio per continuare.

Quando torni e l'attività non è completata, controlla 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 anche una notifica potrebbe indicarlo. Desktop potrebbe aver bisogno che tu acceda.
• Errore di autenticazione: il token di accesso o la credenziale potrebbe essere scaduto. 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. Per impostazione predefinita, dopo che l'aggiornamento ha atteso 72 ore, il riavvio può avvenire durante l'attività se Desktop può ricollegarsi all'attività in seguito.
• Verifica prima di chiudere: non sempre recuperi l'attività in esecuzione dopo una chiusura o un riavvio, ad esempio dopo alcuni aggiornamenti di Desktop. Per i casi specifici, consulta Riaprire una sessione dopo aver chiuso Desktop.
• Su una versione precedente, lascia Desktop aperto: su Windows con Claude Desktop precedente alla v3.1623.0, non recuperi l'attività in esecuzione dopo che Desktop si chiude o si riavvia. Lo stesso vale con un provider di terze parti su macOS o Linux prima della v2.42304.0. In entrambi i casi, lascia Desktop aperto durante l'attività. Per trovare la tua versione, consulta Verificare la versione.
• Riduci le richieste: scegli una modalità di permesso, regole o hook che facciano attendere meno spesso l'attività
• 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 prompt. 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 molto dopo il momento in cui l'attività dovrebbe essere completata. Se l'attività non è finita e la sessione non mostra errori 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, oppure quando l'helper 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, ad esempio una proveniente dal 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 così 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 termina 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 porta un nuovo helper, Desktop sostituisce l'helper sulla macchina remota in una connessione successiva, il che può terminare un'attività ancora in esecuzione
• Assenze prolungate: su una macchina remota Linux o macOS, se Desktop non si connette per 30 giorni, l'helper 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 controlla ogni modifica ai file prima che Claude la esegua. Mentre Desktop è disconnesso, ogni modifica attende circa 30 secondi e poi non riesce. 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ò ancora chiamare i loro strumenti. I server da 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.

[accordion] 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 dal Microsoft Store, su un computer Windows senza OpenSSH di Microsoft 9.4 o successiva, 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, oppure ~/.claude
• Percorsi macOS: su una macchina remota macOS, il repository si trova in /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 prevede questo controllo, a meno che la tua organizzazione non limiti le cartelle che le sessioni possono usare.

Gestire le richieste che arrivano mentre sei via

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. Mantieni 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 ad attenderti, e per ricevere sue notizie mentre sei via, configura uno di questi elementi prima di andartene:

• 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 .claude/settings.json di un progetto, consulta Regole allow del progetto e attendibilità del workspace.
• 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 dell'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 tale azione o te la chiede, e l'attività attende quindi la tua risposta.

Riconnettersi dopo la 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 prompt, ad esempio con una chiave detenuta dal tuo agente SSH.

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

[accordion] 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 interrompono mentre sei via: 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 può 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 interrompere i tentativi, chiudi Desktop, il che può farti perdere l'attività in esecuzione.
• Interruzione lunga: Desktop rallenta fino a circa un tentativo ogni cinque minuti. Per riconnetterti prima, riprova nella sessione o invia un messaggio, che Desktop recapita non appena è connesso.
• Output mancante: mentre Desktop è disconnesso, l'helper 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 che chiudi Desktop, l'attività continua a essere eseguita sulla macchina remota, ma si interrompe 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, non ha bisogno di te o non raggiunge uno dei limiti.

• Desktop su Windows, attività avviata in una versione precedente alla v3.1623.0: non recuperi l'attività, anche se Desktop è stato aggiornato nel frattempo. Riavvia Desktop solo quando prevedi che l'attività sia completata, perché la sessione può aprirsi all'avvio di Desktop, e l'attività si interrompe quando la sessione si apre. Se non sai in quale versione hai avviato l'attività, attendi anche in questo caso finché non prevedi che sia completata.
• Provider di terze parti su macOS o Linux, attività avviata in una versione precedente alla v2.42304.0: non recuperi l'attività. Riavvia Desktop solo quando prevedi che l'attività sia completata.
• Qualsiasi altra attività: 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 l'attività si interrompe, la sessione può mostrare Restarting Claude Code on <host>… mentre Desktop avvia un nuovo processo. Perdi anche qualsiasi approvazione o domanda che ti stava attendendo. Se Claude non continua da solo, 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 quella conversazione sulla macchina remota. Claude Code non te lo impedisce, e entrambi i processi scrivono quindi 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 vanno 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 propri 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 dell'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, ad esempio ~/worktrees, e seleziona Save changes.

File e processi sulla macchina remota

Desktop installa un programma helper e Claude Code in ~/.claude/remote/ nella directory home di ciascun utente che si connette a una macchina remota Linux o macOS. L'helper non resta 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 farlo.

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:

• Helper: uno o più processi server per ogni computer che si connette
• Claude Code: i processi che l'helper avvia per le sessioni dell'utente, ciascuno da un file che prende il nome dalla sua versione, come 2.1.295-…

Desktop raggiunge l'helper attraverso la connessione SSH dell'utente, tramite il socket Unix rpc.sock nella cartella dell'helper sotto ~/.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 i casi in cui l'helper si arresta da solo, consulta Limiti mentre Desktop è disconnesso.

Per rimuovere l'helper 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 di Claude Code elencato da pgrep. Quando sono scomparsi dall'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 la sua chiusura, senza comparire nell'elenco di pgrep.

3. Elimina la cartella

Elimina ~/.claude/remote/. Per rimuovere i file propri 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 chiudi 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

L'helper 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 avviati da Claude Code, come i comandi della 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.

Se il server imposta MaxSessions 1, aspettati almeno due voci ogni volta che Desktop si connette o si riconnette. Aspettatene almeno un'altra per ogni scheda del terminale e per ogni sessione di Desktop in cui esegui comandi che iniziano con !.

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 i test della porta SSH eseguiti 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 subito, senza inviare nulla. Aspettati un test o diversi di seguito, ad esempio otto in circa due minuti.

Se nulla blocca o rifiuta gli indirizzi per tali connessioni, 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 rifiuta l'indirizzo e se fail2ban conta i test di Desktop.

Riconoscere un test nel log del server SSH

Confronta le righe del 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 vedere invece le righe dell'ultima colonna se il saluto 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 rifiuta 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 versioni successive possono scrivere una riga di questo tipo 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 solo pochi test.

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 quindi non applica nessuna delle sue penalità a quegli indirizzi, comprese 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 versione successiva ha bloccato un indirizzo da cui Desktop si connette, trova la modalità della tua jail in jail.conf, jail.local o sotto jail.d/:

• Una riga filter che indica una modalità tra parentesi quadre, come filter = sshd[mode=aggressive]: usa quella modalità.
• Solo la riga filter predefinita, 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à della tua 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 a causa dei test di Desktop, modifica una di due impostazioni della jail, ciascuna con un costo:

• mode: impostala su normal ovunque la tua 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 solo le altre modalità effettuano, ad esempio 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 quindi non conta nulla da quegli indirizzi, compresi gli accessi non riusciti.

Usare server MCP configurati sulla macchina remota

Per usare un server MCP da ~/.claude.json o dal .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 che quei server eseguono. Per i server da 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, una dashboard o una pagina wiki per aprire Desktop configurato per la macchina e la cartella giuste. Per le piattaforme che rimuovono tali link, consulta Il link viene visualizzato come testo semplice anziché essere cliccabile.

I link SSH richiedono Claude Desktop v2.110.0 o versione successiva.

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 da ~/.ssh/config funziona come ssh_host solo per le persone che hanno quella voce. Per corrispondere a 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 dal 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 dal link e non seleziona né apre una connessione con essi. Se una connessione SSH è già selezionata, la pagina di nuova sessione può comunque connettersi a essa da sola, 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 verifica cosa ha compilato:

• Prima di confermare: verifica l'host e la cartella.
• Prima di inviare: verifica 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 per te. Tratta il prompt come testo semplice, quindi un / o ! iniziale e una menzione di file con @ non agiscono come un comando o una 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 sulla connessione, cerca una di queste cause:

• Non hai effettuato l'accesso: accedi, poi apri di nuovo il link.
• È aperta un'altra finestra di dialogo: chiudila, poi 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 con il solo prompt.
• Le sessioni SSH sono disattivate: se il tuo amministratore imposta l'allowlist su un array vuoto, Desktop rifiuta i link SSH.

Creare una connessione SSH da un comando

Se uno strumento da riga di comando crea le tue macchine remote su richiesta, aggiungi il suo comando a sshHostCommands in ~/.claude/settings.json. Il selettore dell'ambiente elenca quindi un elemento che prende il nome dalla tua voce, come Create Dev box. Quando lo selezioni, Desktop esegue il comando sul tuo computer, salva l'host stampato dal comando come connessione SSH e si connette.

[!NOTE]

Le connessioni da un comando richiedono Claude Desktop v3.6556.0 o versione successiva su macOS o Linux, con accesso effettuato tramite un account Claude. Gli amministratori possono distribuire i comandi a un team.

Desktop esegue il comando solo quando crei la connessione o crei un'altra macchina, non ogni volta che ti connetti. Ogni voce è una connessione, che punta all'host che Desktop ha salvato per ultimo dal comando della voce.

[!WARNING]

Desktop non arresta né elimina le macchine. Ciascuna di queste continua a essere in esecuzione, e può continuare a costare denaro, finché non la elimini con il tuo strumento:

• Una macchina a cui una voce puntava prima che tu ne creassi un'altra
• Le macchine di una voce che hai rimosso dal file, o di cui hai modificato l'id
• Una macchina che il tuo comando ha creato senza che Desktop ne salvasse l'host, ad esempio in questi casi:
  • Il comando non riesce o esaurisce il tempo
  • Desktop non può usare l'host stampato, un'altra connessione lo usa già, o la tua organizzazione non lo consente
  • Mentre il comando è in esecuzione, lo annulli, rimuovi la sua voce, modifichi il suo command o id, o chiudi Desktop

L'esempio seguente aggiunge una connessione denominata Dev box. Se il file non esiste, crealo. Se contiene già delle impostazioni, aggiungi la chiave accanto a esse. Il comando acme-dev create rappresenta il tuo strumento, e ~/project è la cartella che Desktop seleziona su ogni macchina creata dal tuo comando:

{
  "sshHostCommands": [
    {
      "id": "devbox",
      "name": "Dev box",
      "command": "acme-dev create",
      "startDirectory": "~/project"
    }
  ]
}

Ogni voce accetta questi campi, e id, name e command sono obbligatori:

Per modificare o rimuovere la connessione, modifica la sua voce nel file, perché la finestra di dialogo della connessione SSH dell'app non si apre per essa. Non è necessario riavviare Desktop dopo aver modificato il file. Se la voce non compare o non puoi selezionarla, consulta Se un comando manca o è grigio.

Scrivere il comando

Desktop avvia il programma direttamente, senza shell e senza terminale:

• Programma: scrivi il suo nome, o il suo percorso completo a partire da /, senza spazi. Desktop cerca un nome semplice nel PATH esportato dalla tua shell di login. I percorsi relativi come ./acme-dev, i percorsi che iniziano con ~ e gli alias e le funzioni della shell non funzionano.
• Argomenti: separa gli argomenti semplici con spazi. Il comando può contenere solo spazi, lettere ASCII, cifre e i caratteri +,-./:=@_~, e nessuna parola può iniziare con ~.
• Script: se il comando richiede qualcos'altro, come virgolette, pipe, variabili o un URL con ? o &, inseriscilo in uno script. Rendi lo script eseguibile, inizialo con una riga #! e imposta command sul suo percorso completo, come /Users/you/bin/make-devbox. Su macOS, tieni lo script fuori dalle cartelle Documenti, Scrivania e Download, dove macOS può bloccarlo.
• Input: il programma non riceve input né terminale, quindi non può chiederti nulla lì. Se il tuo strumento ti fa accedere tramite un browser o una richiesta, accedi prima da un terminale, e di nuovo ogni volta che quell'accesso scade.
• Ambiente: il programma viene eseguito nella tua directory home con le variabili esportate dalla tua shell di login. Desktop le legge all'avvio, come fa per un ProxyCommand, quindi chiudi e riapri Desktop dopo averle modificate.
• Limite di tempo: Desktop arresta un programma che è ancora in esecuzione dopo 10 minuti. Il messaggio di avanzamento di Desktop non mostra l'output del programma. Per arrestare il programma prima, seleziona Cancel accanto a quel messaggio.

Il programma deve uscire con codice 0 e stampare solo l'host sullo standard output, in una di due forme:

• Una riga: host o user@host, scritto come per ssh_host in un link SSH. Per indicare una porta, usa la forma JSON.
• Un oggetto JSON: sshHost, e facoltativamente un sshPort numerico e una startDirectory che sostituisce quella della voce, come {"sshHost": "dev@devbox-1234.example.com", "sshPort": 2222}

Per vedere l'output che Desktop legge, esegui il comando in un terminale senza input e con lo standard output in un file:

acme-dev create < /dev/null > host.txt

Il file deve contenere solo l'host. Quando esegui questo test, il tuo strumento crea anche una macchina, quindi eliminala in seguito con il tuo strumento.

Se il tuo strumento stampa altre righe prima dell'host, come messaggi di avanzamento, racchiudilo in uno script che stampi solo l'host. Lo script seguente stampa l'ultima riga dell'output del tuo strumento. Se il tuo strumento non riesce, lo script esce con lo stesso codice, in modo che Desktop segnali l'errore:

#!/bin/bash
out=$(mktemp) || exit
trap 'rm -f "$out"' EXIT
acme-dev create > "$out" || exit
tail -n 1 "$out"

Se il comando non riesce, View details nel messaggio di Desktop mostra l'ultima riga che il comando ha scritto sullo standard error, se presente.

Connettersi a un nuovo host

Rispondi a due domande la prima volta che ti connetti a ogni nuovo host:

• Chiave host: con il controllo predefinito delle chiavi host di OpenSSH, verifica l'impronta digitale della chiave, poi scegli se connetterti. Per saltare la domanda, fai in modo che il tuo comando aggiunga la chiave a ~/.ssh/known_hosts prima di stampare l'host, usando una chiave che il tuo strumento ha ottenuto quando ha creato la macchina. Per una porta diversa dalla 22, quella riga inizia con [host]:port. Se il tuo strumento riutilizza i nomi host, rimuovi anche la riga della vecchia chiave.
• Cartella: scegli se ritieni attendibile la cartella che apri lì

Mantieni attivo il controllo delle chiavi host per questi host e mantieni un file known_hosts per essi. Se StrictHostKeyChecking è no o accept-new e anche UserKnownHostsFile è /dev/null o none, nulla registra la chiave. Quando il tuo strumento riutilizza poi un nome, puoi connetterti a una macchina diversa senza alcun avviso.

Un nome riutilizzato conta anche senza nessuno al computer, perché Desktop si connette a questi host da solo. Ad esempio, consegna un messaggio che hai inviato mentre l'host non era raggiungibile, una volta che l'host risponde. Anche con il controllo delle chiavi degli host attivo, il messaggio può raggiungere la nuova macchina con quel nome in questi casi, quindi smetti di usare una macchina prima che venga eliminata:

• Tu, il tuo comando o un altro programma avete aggiunto la nuova chiave a known_hosts o rimosso la riga della vecchia chiave, come fa il tuo comando se aggiunge chiavi degli host
• Le macchine del tuo strumento condividono una chiave dell'host
• Le macchine del tuo strumento condividono un'autorità di certificazione considerata attendibile da known_hosts
• Tu o il tuo amministratore avete impostato KnownHostsCommand o VerifyHostKeyDNS yes, quindi SSH accetta chiavi da fuori known_hosts

Creare un'altra macchina

Le tue sessioni sulle macchine precedenti continuano a funzionare dopo che selezioni Create another Dev box, e le nuove sessioni usano la nuova macchina. Seleziona l'elemento nel selettore dell'ambiente per creare una macchina nuova o per sostituirne una che non c'è più. Nella pagina di nuova sessione, lo offre anche il messaggio che indica che Desktop non riesce a raggiungere l'host.

• Sessioni sulle macchine precedenti: continuale dalla barra laterale, perché il selettore elenca la macchina attuale di Dev box e non quelle precedenti. Desktop può connettersi alle loro macchine da solo, ad esempio all'avvio di Desktop, quindi smetti di usare una macchina quando hai finito con essa.
• Un host sostituito prima di Claude Desktop v4.4212.0: quelle versioni mostrano Replace Dev box's host e smettono di connettersi all'host sostituito. Per continuare una sessione su quell'host, apri la sessione, seleziona Add SSH connection e salva la connessione che Desktop compila. Aggiorna Desktop prima di sostituire un altro host.
• Nuove sessioni su due macchine: aggiungi una seconda voce a sshHostCommands
• Un nuovo host che non risponde ancora: lascia aperta la pagina di nuova sessione fino a 10 minuti mentre continua a tentare di connettersi. Se l'host continua a non rispondere, seleziona Create another Dev box nel messaggio della pagina.
• Un'altra macchina poco dopo: dopo diverse esecuzioni del comando entro un'ora, conferma ogni esecuzione successiva nella finestra di dialogo che Desktop apre, che mostra il comando

Smettere di usare una macchina

Per impedire a Desktop di connettersi da solo a una macchina creata da un comando, archivia ogni sessione sulla macchina:

1. Trova le sessioni della macchina nella barra laterale. Il pannello dei dettagli di una sessione mostra l'host su cui viene eseguita.
2. Archivia ogni sessione e lasciala archiviata.
3. Se non hai creato un'altra macchina dalla stessa voce sshHostCommands da quando hai creato questa, creane una oppure rimuovi la voce. Fino ad allora, la macchina è la connessione salvata della voce, e Desktop può connettersi a essa quando apri la pagina di nuova sessione con quella connessione selezionata.
4. Elimina nell'app qualsiasi altra connessione SSH alla macchina, o rimuovi la sua voce sshConfigs.
5. Chiudi e riapri Desktop, il che chiude la sua connessione alla macchina e interrompe i suoi tentativi di raggiungerla.
6. Elimina la macchina con il tuo strumento.

Rimuovere una voce

Dopo che rimuovi una voce dal file delle impostazioni o ne modifichi l'id, le sessioni sulle sue macchine restano, quindi Desktop può ancora connettersi a quelle macchine. Può farlo senza nessuno al computer, ad esempio per ricollegarsi al processo in esecuzione di una sessione o per consegnare un messaggio in attesa di invio. Per impedirlo, archivia le sessioni, come descritto in Smettere di usare una macchina.

Se sei un amministratore e hai rimosso una voce gestita, anche le sessioni dei tuoi utenti restano, e ogni utente deve archiviare le proprie. Per bloccare tu stesso le macchine della voce, imposta un sshHostAllowlist che corrisponda agli host di cui i tuoi utenti hanno ancora bisogno e non ai nomi host delle macchine. Puoi farlo solo dove un pattern distingue le due cose.

Distribuire i comandi al tuo team

Per fornire una connessione al tuo team, imposta sshHostCommands nel file di impostazioni gestite di Claude Code o nella policy MDM su ogni computer, non nella policy di gestione dei dispositivi propria dell'app desktop. Gli utenti vedono le tue voci accanto alle proprie, e l'app non offre alcun modo per modificare o rimuovere una voce, né loro né tua.

Il seguente file di impostazioni gestite fornisce agli utenti una connessione denominata Dev box e disattiva le loro voci, insieme agli hook di Claude Code dalle impostazioni utente, di progetto e locali:

{
  "sshHostCommands": [
    {
      "id": "acme-devbox",
      "name": "Dev box",
      "command": "/usr/local/bin/acme-dev create"
    }
  ],
  "strictPluginOnlyCustomization": ["hooks"]
}

Prima di distribuire la chiave, definisci ciascuno di questi aspetti:

• Dove inserire la chiave: se la tua policy MDM per Claude Code imposta già una chiave di policy, inseriscila lì. Altrimenti, inseriscila nel file di impostazioni gestite. Per impostazione predefinita, tale policy ha la precedenza sul file, e Desktop ignora quindi le voci nel file. Impostala sul computer anche dove si applicano le impostazioni gestite dal server: Desktop ignora la chiave lì, e nelle impostazioni di progetto e locali.
• L'id: se la voce sshHostCommands di un utente ha il tuo id, funziona solo la tua. Se qualsiasi altra connessione SSH lo ha, come una nei sshConfigs di un utente, la tua voce è grigia. Scegli un id che difficilmente gli utenti sceglierebbero.
• Il programma: indica il suo percorso completo, perché Desktop cerca un nome semplice nel PATH di ciascun utente. Il programma viene eseguito come l'utente, con le variabili esportate dalla sua shell di login.
• Le voci degli utenti: Desktop tratta la voce di un utente come un hook, perché entrambi eseguono un programma sul computer. Per consentire solo le tue voci, imposta strictPluginOnlyCustomization su ["hooks"], oppure aggiungi "hooks" al suo elenco. Blocchi anche gli hook di Claude Code dalle impostazioni utente, di progetto e locali, senza alcun modo per mantenerli. Se imposti invece quella chiave o allowManagedHooksOnly su true, blocchi di più, come indicato nella voce di ciascuna chiave.
• Ogni voce: per disattivare anche le tue voci, imposta disableAllHooks nelle impostazioni gestite. Se imposti disableDesktopLocalSessions, o un sshHostAllowlist che non consente alcun host, il selettore non elenca alcun elemento Create o Create another.
• Dove contano i blocchi: per queste voci, Desktop legge allowManagedHooksOnly, strictPluginOnlyCustomization e disableAllHooks dalle impostazioni gestite dal server e dal file o dalla policy del computer stesso, e applica il risultato più restrittivo. Ogni voce rimane grigia finché Desktop non ha verificato su claude.ai le impostazioni gestite dal server, anche se la tua organizzazione non ne ha.
• Host consentiti: se imposti sshHostAllowlist, assicurati che un pattern corrisponda a ogni nome host stampato dal tuo strumento, e ometti user@ dal pattern. Desktop verifica il nome stampato solo dopo che il comando è stato eseguito, quindi una macchina rifiutata dall'elenco esiste già, e l'utente deve eliminarla con il tuo strumento. A ogni connessione, deve corrispondere anche l'HostName risolto.

Dopo aver distribuito la chiave, riavvia Desktop su un computer di prova. Nel selettore dell'ambiente della scheda Code, cerca sotto SSH, oppure nella singola riga SSH. La tua voce compare come elemento Create, oppure come elemento grigio che indica il motivo quando ci passi sopra con il puntatore. Se manca, verifica dove hai inserito la chiave, poi i casi in Se un comando manca o è grigio.

Se un comando manca o è grigio

Il selettore dell'ambiente non elenca alcun elemento Create o Create another in questi casi:

• Il file: ~/.claude/settings.json contiene JSON non valido o un valore rifiutato dallo schema, hai scritto male la chiave, oppure l'hai inserita nelle impostazioni di un progetto. Correggi il file.
• Piattaforma e account: usi Windows, oppure un provider di terze parti anziché un account Claude. Aggiungi tu stesso ogni host come connessione SSH.
• Le impostazioni della tua organizzazione: il tuo amministratore ha disattivato le sessioni locali o le sessioni SSH. Chiedigli se puoi usare i comandi.
• Nessun programma ssh: Desktop non è riuscito ad avviare il client OpenSSH sul tuo computer. Installalo, o chiedi al tuo amministratore di consentirlo, poi riavvia Desktop.

Una voce che non puoi selezionare è grigia. Passaci sopra con il puntatore per vedere il motivo:

• Un errore nella voce: correggi il campo o il comando indicato dal messaggio. Se l'id è già in uso, assegnane un altro alla voce.
• Un file di impostazioni danneggiato: finché il tuo file di impostazioni è danneggiato, le voci del tuo amministratore potrebbero essere grigie, con un messaggio che indica il file. Correggi il file.
• Un nuovo host: Create another è grigio per un minuto dopo che Desktop ha salvato un host. Selezionalo dopo quel minuto. Prima di Claude Desktop v4.4212.0, Replace Dev box's host è grigio per 10 minuti.
• Gli hook sono disattivati o limitati: le tue voci funzionano solo dove possono essere eseguiti i tuoi hook. Rimuovi disableAllHooks dalle tue impostazioni, oppure chiedi al tuo amministratore.
• Le impostazioni sono ancora in caricamento: ogni voce è grigia finché Desktop non ha caricato le impostazioni gestite dal server della tua organizzazione, di solito pochi secondi dopo l'avvio. Se le voci rimangono grigie, verifica la tua connessione a claude.ai.

Preconfigurare le connessioni SSH per il tuo 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 dell'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 preconfigura 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 ~/.ssh/config di ciascuno sviluppatore imposta per l'host, oppure come il suo nome utente sul proprio computer.

Limitare gli host SSH a cui gli utenti possono connettersi

Gli amministratori possono limitare le sessioni SSH di Desktop a un insieme approvato di host impostando sshHostAllowlist nelle impostazioni gestite. Quando è impostata, gli utenti possono connettersi solo agli host il cui nome host risolto corrisponde a uno dei pattern. Impostala su un array vuoto per disattivare le sessioni SSH. La voce di riferimento di sshHostAllowlist spiega come un array vuoto si combina con gli elenchi in altre origini gestite.

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

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

[!WARNING]

Se la tua organizzazione fornisce impostazioni gestite dal server, imposta sshHostAllowlist lì. Per impostazione predefinita, Desktop legge la chiave solo dall'origine gestita con priorità più alta che fornisce una chiave di policy. Se quell'origine lascia la chiave non impostata, Desktop ignora un elenco 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 ciascun utente, nella policy MDM o nel file di impostazioni gestite con priorità più alta presente lì. Desktop recupera le impostazioni gestite dal server all'avvio e non ne conserva una copia nella cache, quindi finché un recupero non riesce si applica l'elenco della macchina.

I pattern non fanno distinzione tra maiuscole e minuscole. * corrisponde a qualsiasi host, e *.example.com corrisponde a example.com e a qualsiasi sottodominio. Qualsiasi altro valore è una corrispondenza esatta. Il controllo viene eseguito sul nome host dopo la risoluzione di ~/.ssh/config tramite ssh -G, quindi un alias Host è consentito purché il suo HostName risolto corrisponda. Anche i jump host di una sessione devono corrispondere.

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

Consentire i jump host

Aggiungi a sshHostAllowlist ogni jump host che Desktop verifica, tramite il suo HostName risolto. Aggiungi i jump host prima che gli utenti aggiornino a Claude Desktop v3.1623.0 o versione successiva, altrimenti non potranno connettersi attraverso di essi.

[!WARNING]

L'elenco ha un solo tipo di voce, quindi gli utenti possono anche avviare una sessione su qualsiasi host che elenchi. Elenca solo jump host su cui consentiresti agli utenti anche di eseguire sessioni.

Desktop verifica i jump host nel ProxyJump che il ~/.ssh/config dell'utente imposta per l'host della sessione, oppure in un ProxyCommand scritto come ssh -W %h:%p <host>. Se uno di quelli che verifica non è nell'elenco quando Desktop connette o riconnette una sessione, la connessione non riesce. Quando un utente avvia una sessione o invia un messaggio, i dettagli dell'errore riportano l'HostName di quel jump host, che è il nome da aggiungere:

SSH host "bastion.example.com" is not allowed by your organization's managed settings. It is a jump host on the way to "devbox".

Se il messaggio riporta managed settings on this computer, aggiungi il nome all'elenco sul computer dell'utente. Se manca più di un jump host, l'errore li indica uno alla volta. Per trovare tutti i nomi prima che gli utenti aggiornino, usa un terminale sul computer di un utente:

1. Trova il percorso

Esegui ssh -G con un host a cui gli utenti si connettono, come ssh -G devbox. Cerca una riga proxyjump, oppure una riga proxycommand scritta come ssh -W %h:%p <host>. Il comando conta comunque con una qualsiasi delle opzioni -l, -p, -J, -q, -v, -N, -T, -x o -a, e anche gli host dopo -J sono jump host. Se una riga proxycommand esegue un programma diverso da ssh, non aggiungere nulla per essa.

2. Cerca ogni jump host

Esegui ssh -G con ogni jump host presente su quella riga, senza alcun :port, e annota l'hostname che stampa. Se l'output per il primo jump host su quella riga contiene una riga di uno dei due tipi, ripeti questo passaggio con essa. Ignora una riga di questo tipo nell'output di un jump host successivo.

3. Aggiungi i nomi

Aggiungi ogni nome host, o un carattere jolly che lo copra, a sshHostAllowlist in ogni origine gestita in cui imposti un elenco. Poi chiedi agli utenti di chiudere e riaprire Desktop, perché recupera le impostazioni gestite dal server all'avvio.

Disattivare le sessioni locali e distribuire le 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 è destinata agli utenti che accedono con un account Claude. Con un provider di terze parti, le sessioni SSH sono disattivate per impostazione predefinita, e l'impostazione di 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 di Cowork o alle attività pianificate di Cowork
• Sessioni cloud: nessuna delle chiavi modifica la disponibilità delle sessioni cloud. Per disattivarle, usa l'impostazione Cloud sessions in Controlli della console di amministrazione.

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

• Nomi host: assicurati che un pattern in sshHostAllowlist corrisponda al nome host di ogni voce sshConfigs, senza user@, altrimenti gli sviluppatori non potranno connettersi. Aggiungi anche un pattern che corrisponda a ogni jump host che Desktop verifica lungo il percorso. Per come Desktop confronta un nome host, consulta Limitare gli host SSH a cui gli utenti possono connettersi.
• Versione: disableDesktopLocalSessions richiede Claude Desktop v1.37937.0 o versione successiva
• Permessi del file: assicurati che l'account di ciascuno sviluppatore sul computer possa leggere il file di impostazioni gestite. Desktop non applica le chiavi 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 origine gestita, quella con priorità più alta tra quelle che fornisci. Se fornisci impostazioni gestite dal server, conserva anche una copia delle tre chiavi nella policy MDM o nel file di impostazioni gestite con priorità più alta su ogni computer. Desktop recupera le impostazioni gestite dal server all'avvio, e la copia sul computer si applica finché un recupero non riesce.

Per confermare che le impostazioni sono applicate, controlla il computer di uno sviluppatore:

1. Controlla il selettore dell'ambiente

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

• La voce per 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 per il computer è ancora disponibile, verifica queste cause:

• Versione di Desktop: aggiorna Desktop se è precedente alla v1.37937.0.
• File di impostazioni gestite: assicurati che il file sia JSON valido.
• Origine gestita: assicurati che il computer legga l'origine gestita che contiene le chiavi.

2. Aggiungi un host che non è nell'allowlist

Aggiungi una connessione SSH con un nome host 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, salvo diversa indicazione nella riga di una chiave.

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.

Limita l'accesso alla tua organizzazione

Per limitare quali organizzazioni claude.ai possono accedere a Claude Desktop, imposta forceLoginOrgUUID nel criterio di Claude Desktop.

La chiave richiede Claude Desktop v1.2581.0 o successivo.

Su Linux, un file di criteri che imposta solo questa chiave è il seguente:

{
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Sostituisci il segnaposto con l'ID della tua organizzazione claude.ai, mostrato nelle impostazioni di amministrazione di claude.ai. È lo stesso ID accettato dall'impostazione forceLoginOrgUUID di Claude Code. Per esempi per macOS e Windows che impostano questa chiave, vedi Distribuisci il criterio di Claude Desktop nella guida di Cowork per le organizzazioni pronte per HIPAA.

[!WARNING]

Controlla il valore di forceLoginOrgUUID prima di distribuirlo. Se l'ID non è quello della tua organizzazione, le persone della tua organizzazione non possono usare Claude Desktop a meno che non appartengano anche a un'organizzazione con quell'ID. Per risolvere, distribuisci l'ID corretto e chiedi loro di riavviare Claude Desktop.

Se imposti forceLoginMethod e forceLoginOrgUUID nelle impostazioni gestite di Claude Code, non modifichi la schermata di accesso di Claude Desktop.

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
sso.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 > Code o Impostazioni > Claude Code.

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 mostra l'ambiente sopra la casella del prompt anziché sotto, 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 con sessioni sul tuo computer: il layout attuale richiede Claude Desktop v3.1623.0 o successiva, quindi verifica la tua versione. Per aggiornare, seleziona Claude > Check for Updates… su macOS o Help > Check for Updates… su Windows. Se la tua organizzazione disattiva gli aggiornamenti automatici, Check for Updates… è nascosto, quindi chiedi al tuo amministratore la v3.1623.0 o successiva.
• Provider di terze parti con sessioni sull'infrastruttura della tua organizzazione: il layout attuale richiede Claude Desktop v4.29.0 o successiva, quindi verifica la tua versione. Se hai una versione precedente, chiedi al tuo amministratore la v4.29.0 o successiva. Se non sai dove vengono eseguite le tue sessioni, chiedi al tuo amministratore.

Nel layout precedente, scegli l'ambiente ed eventuali cartelle del progetto o repository 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, Ultra, 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.

SSH host key verification failed

Ciascuno di questi messaggi significa che Desktop ha rifiutato una chiave host:

• SSH host key verification failed o Host denied (verification failed) sotto View details su una scheda Couldn't connect to <host>
• Connection failed: Host key changed or not trusted accanto alla casella del prompt o dopo Test connection
• <host>'s host key is not trusted o <host>'s host key has changed su una sessione disconnessa

Desktop di solito rifiuta una chiave perché differisce da quella salvata sul tuo computer, oppure perché non è salvata alcuna chiave per quella macchina. Una macchina ricostruita o reinstallata di solito presenta una nuova chiave, e lo stesso vale per qualcosa che intercetta la connessione. Controlla la chiave prima di connetterti di nuovo, partendo da ciò che Desktop mostra insieme al messaggio:

• Sei su Windows e Desktop dice Connection failed: Host key changed or not trusted: per prima cosa escludi un client OpenSSH mancante
• Desktop ti dice di impostare UserKnownHostsFile: in ~/.ssh/config, impostalo su ~/.ssh/known_hosts, quindi controlla la chiave da un terminale
• Vedi un pulsante Review new key: selezionalo e confronta l'impronta digitale che Desktop mostra con quella della macchina stessa. Se corrispondono, seleziona Trust new key per sostituire la chiave salvata. Altrimenti seleziona Cancel.
• Non vedi alcun pulsante Review new key, Desktop mostra Couldn't show the new key, oppure Desktop rifiuta di nuovo la chiave dopo Trust new key: controlla la chiave da un terminale

Controlla la chiave host da un terminale

Esegui ssh <SSH host> sul tuo computer, con il valore SSH host della tua connessione SSH in Desktop. Aggiungi -p <SSH port> se la connessione ha un valore SSH port. Su Windows, usa PowerShell, perché Desktop non si connette con l'ssh di Git Bash o WSL. Se PowerShell non trova ssh, installa il client OpenSSH di Microsoft.

Annota quale macchina ssh nomina nel suo messaggio, che può essere un jump host e non <SSH host>, quindi segui il caso corrispondente:

• ssh chiede se continuare la connessione: confronta l'impronta digitale che mostra con quella della macchina stessa. Rispondi yes solo se corrispondono.
• ssh avvisa che la chiave host è cambiata: confronta l'impronta digitale dell'avviso con quella della macchina stessa. Solo se corrispondono, elimina la riga indicata da Offending <type> key in <file>:<line> ed esegui di nuovo ssh. Se ssh avvisa di nuovo riguardo a un'altra riga, confronta, elimina ed esegui di nuovo come prima.
• ssh rifiuta una chiave che non conosce, senza chiedere: ottieni la riga known_hosts di quella macchina da chi la gestisce, non tramite la connessione che stai verificando. Aggiungi la riga al tuo file known_hosts, con il nome indicato nel messaggio di ssh come nome host, ed esegui di nuovo ssh.
• ssh procede con l'accesso senza chiederti nulla sulla chiave host: non digitare ancora una password. Controlla le chiavi di cui ssh si fida già.

Una volta che ssh accetta una chiave che hai controllato o aggiunto, riprova in Desktop. Se Desktop rifiuta di nuovo la chiave, vedi Ottieni i log di Desktop per un problema SSH.

Controlla le chiavi di cui ssh si fida già

Esegui di nuovo lo stesso comando ssh aggiungendo -v -S none. Nel suo output, una riga Server host key: mostra un'impronta digitale, e la riga Host '<name>' is known successiva nomina la macchina a cui appartiene. Confronta ogni impronta digitale che trovi con quella della macchina stessa.

• Un jump host non ha alcuna riga Server host key:: esegui anche ssh -v -S none <jump host> e confronta quell'impronta digitale allo stesso modo.
• Un'impronta digitale non corrisponde, o non puoi verificarla: non connetterti di nuovo. Rimuovi la chiave salvata: sotto Host '<name>' is known, la riga Found key in <file>:<line> nomina il file che la contiene. Esegui ssh-keygen -R "<name>" -f <file>. Se conservi le chiavi host in più di un file, rimuovi la chiave da ciascuno. Se non puoi modificare un file, avvisa chi gestisce il tuo computer.
• Tutte le impronte digitali corrispondono: riprova in Desktop. Se Desktop rifiuta di nuovo la chiave, vedi Ottieni i log di Desktop per un problema SSH.

Chiave host SSH rifiutata su Windows senza un client OpenSSH

Su Windows senza un client OpenSSH, Desktop rifiuta anche una chiave host corretta, con Connection failed: Host key changed or not trusted. Ha bisogno del client per cercare le chiavi salvate. Per vedere se ne hai uno, esegui ssh in PowerShell. Se PowerShell non riconosce ssh, installa il client OpenSSH di Microsoft e riavvia Desktop.

Quindi connettiti di nuovo. Se Desktop chiede se connettersi per la prima volta, controlla la chiave host della macchina prima di considerarla attendibile. Se Desktop rifiuta ancora la chiave, segui gli altri casi sotto SSH host key verification failed.

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.