Vai al contenuto principale
Un deep link è un URL claude-cli:// che apre Claude Code in una nuova finestra del terminale. L’URL può contenere una directory di lavoro e un prompt da precompilare. Il prompt viene inserito ma non inviato finché non premi Enter. Per fare in modo che i link si aprano su una macchina, invia prima un prompt in una sessione interattiva di Claude Code su quella macchina, così che Claude Code registri il suo gestore claude-cli://. Poiché un deep link è un URL, puoi inserirlo ovunque possa andare un link:
  • Un passaggio di un runbook per gli incidenti che apre il repository del servizio interessato con un prompt diagnostico
  • Un avviso di monitoraggio o una dashboard che rimanda a un prompt di indagine per una metrica specifica
  • Un README o una pagina wiki che apre il progetto con un prompt di onboarding
  • Una notifica di errore della CI che precompila il nome del job non riuscito
Questa pagina spiega come creare un link, incorporarlo in un runbook o attivarlo dalla shell e gestire o disabilitare la registrazione del gestore su ciascuna piattaforma. Il prefisso claude-cli:// è uno schema URL personalizzato che Claude Code registra presso il tuo sistema operativo, in modo simile a come i link mailto: aprono il tuo client di posta elettronica. Quando fai clic su un deep link:
  1. Il browser o l’app passa l’URL al tuo sistema operativo.
  2. Il sistema operativo riconosce il prefisso claude-cli:// e avvia Claude Code sul tuo computer.
  3. Si apre una nuova finestra del terminale con Claude Code in esecuzione nella directory specificata dal link e con il testo del prompt del link già presente nella casella di input.
  4. Leggi il prompt, lo modifichi se vuoi e premi Enter per inviarlo.
Il link stesso può essere ospitato ovunque, ma la sessione si apre sempre localmente sul computer su cui hai fatto clic. Consulta Registrazione e piattaforme supportate per sapere quale emulatore di terminale si apre su ciascun sistema operativo. La piattaforma che mostra il link deve consentire gli schemi URL personalizzati. Per sapere cosa fa GitHub con questi schemi e come aggirare il problema, consulta Il link viene visualizzato come testo semplice anziché essere cliccabile.

​
Cosa mostra una sessione avviata

Un deep link non esegue mai nulla da solo. Il link si limita a scegliere una directory e a compilare la casella del prompt. Se fai clic su un link da una pagina di cui non ti fidi, il prompt resta comunque inerte: nulla raggiunge il modello finché non leggi ciò che è stato inserito e premi Enter. Quando la sessione si apre, sotto la casella di input compare una riga di avviso con il testo Prompt from an external link, che rimane visibile finché non invii o cancelli il prompt. Per i prompt di oltre 1.000 caratteri, l’avviso include il numero di caratteri e ti invita a scorrere e rivedere il testo completo prima di premere Enter, poiché i prompt lunghi possono spingere le istruzioni fuori dallo schermo. Le regole di permesso, CLAUDE.md e le richieste di attendibilità per la directory selezionata si applicano allo stesso modo di qualsiasi altra sessione. Un deep link inizia con claude-cli://open, seguito da parametri di query facoltativi. La forma minima apre Claude Code nella tua directory home con un prompt vuoto:
Per provare un link senza inserirlo in una pagina, incollalo nella barra degli indirizzi del browser oppure aprilo dalla shell. Aggiungi parametri per controllare dove viene avviata la sessione e cosa contiene la casella del prompt: cwd e repo sono due modi per impostare la directory di lavoro. Se li passi entrambi, cwd ha la precedenza e repo viene ignorato, anche se il percorso cwd non esiste. Il link seguente punta a un repository chiamato acme/payments con un prompt diagnostico di due righe. Sostituisci acme/payments con lo slug owner/name del tuo repository quando crei il tuo link:
Facendo clic su di esso si apre una nuova finestra del terminale, Claude Code si avvia nel tuo clone locale di acme/payments e la casella del prompt viene compilata con il testo decodificato:
Puoi modificare il prompt prima di premere Enter per inviarlo. Consulta Scegliere tra cwd e repo per sapere come viene selezionato il percorso locale quando hai più clone o worktree.

​
Scegliere tra cwd e repo

Usa cwd quando tutti coloro che fanno clic sul link hanno il progetto nello stesso percorso assoluto, ad esempio in un devcontainer o in un’immagine VM standardizzati. Usa repo quando il link è condiviso e ogni persona clona il repository in una posizione diversa. Claude Code risolve lo slug in un percorso locale nel modo seguente:
  • repo apre il clone o il worktree del repository collegato in cui hai eseguito claude più di recente. Ogni volta che esegui claude in un repository Git, Claude Code registra il percorso di quella directory associandolo allo slug GitHub owner/name del repository. Claude Code tiene traccia separatamente di clone e worktree.
  • Il link non cambia il branch su cui è effettuato il checkout. La sessione si apre nello stato in cui si trova attualmente quella directory.
L’intestazione di benvenuto mostra quale percorso è stato scelto, così puoi verificare che si sia aperto il clone giusto.

​
Esempi

Le sezioni seguenti mostrano due modi comuni di utilizzare un deep link: come link Markdown in un documento e come comando in uno script di shell o alias. Un deep link in un runbook offre a chiunque stia triaging un modo con un solo clic per iniziare a indagare nel repository corretto con un prompt preparato. La piattaforma che renderizza il runbook deve consentire schemi URL personalizzati. Il Markdown renderizzato da GitHub non consente claude-cli://, quindi un deep link in un README, problema o wiki di GitHub mostra solo la sua etichetta senza link cliccabile. Vedi la nota sulla risoluzione dei problemi per una soluzione alternativa. Il prompt fa parte dell’URL e deve essere codificato in URL. Per produrre il valore codificato, passa il testo del tuo prompt attraverso encodeURIComponent in una console del browser o in qualsiasi codificatore URL. L’esempio seguente aggiunge un punto di ingresso di indagine a un runbook di incidente per un servizio chiamato web-gateway:
Per utilizzarlo nel tuo runbook, sostituisci acme/web-gateway con lo slug del repository del tuo servizio. Prima che gli ingegneri facciano clic sul passaggio 2, devono aver inviato un prompt in una sessione interattiva di Claude Code sulla propria macchina e aperto Claude Code nel proprio clone locale. Puoi anche aprire un deep link da uno script di shell, alias o automazione piuttosto che facendo clic su di esso. Chiama il comando di apertura URL del tuo sistema operativo con il link come argomento. Questi comandi si basano sul gestore che Claude Code registra sulla macchina.
Il comando open integrato passa l’URL al gestore claude-cli:// registrato:
Se tutto va bene, si apre una nuova finestra di terminale con Claude Code in esecuzione e il prompt pre-compilato.

​
Registrazione e piattaforme supportate

Claude Code registra il gestore claude-cli:// con il tuo sistema operativo su macOS, Linux e Windows quando fai una di queste cose:
  • Invii qualsiasi cosa a una sessione interattiva di claude, come un messaggio o /help. Avviarne una senza inviare nulla non registra il gestore.
  • Avvii Claude Code nella vista agenti, ad esempio con claude agents, in una cartella che hai contrassegnato come attendibile
Non esegui un comando di installazione separato. La registrazione scrive solo in posizioni a livello di utente: Il gestore avvia Claude Code in un emulatore di terminale rilevato. Su macOS, Claude Code ricorda il terminale dalla tua sessione interattiva più recente e lo riutilizza, supportando iTerm2, Ghostty, kitty, Alacritty, WezTerm e Terminal.app. Su Linux onora la variabile di ambiente $TERMINAL, quindi x-terminal-emulator, quindi un elenco di emulatori comuni. Su Windows preferisce Windows Terminal, quindi PowerShell, quindi cmd.exe. Per impedire completamente la registrazione, imposta disableDeepLinkRegistration su "disable" in settings.json. Per applicare questo in tutta un’organizzazione in modo che gli utenti non possano riabilitarlo, impostalo invece in impostazioni gestite. L’impostazione disableDeepLinkRegistration di Claude Code riguarda solo i link claude-cli://.

​
Aprire una scheda VS Code invece di un terminale

L’estensione VS Code registra il suo gestore a vscode://anthropic.claude-code/open, che apre una scheda dell’editor Claude Code piuttosto che una finestra di terminale. Vedi Avviare una scheda VS Code da altri strumenti per i parametri di quell’URL.

​
Aprire una sessione di Claude Desktop su una connessione SSH

Claude Desktop gestisce autonomamente i propri link claude://. Per aprire una sessione Desktop su una macchina remota tramite SSH, consulta Aprire una sessione SSH da un link.

​
Risoluzione dei problemi

Il gestore probabilmente non è ancora registrato. In una sessione interattiva, la registrazione avviene quando invii qualcosa, non quando la sessione inizia. Avvia una sessione claude interattiva su quella macchina, invia un prompt qualsiasi, esci e riprova il link. Se sei su Linux senza un ambiente desktop, xdg-open potrebbe non avere nulla a cui inviare.

​
xdg-open non è trovato su Linux

Il comando xdg-open fa parte del pacchetto xdg-utils, che le immagini server minime, i container e le distribuzioni WSL spesso omettono. Installa xdg-utils con il gestore pacchetti della tua distribuzione, ad esempio sudo apt install xdg-utils, quindi esegui di nuovo il comando. Se il comando viene eseguito ma non si apre nulla, xdg-open potrebbe non avere un ambiente desktop a cui inviare; vedi Fare clic sul link non fa nulla.

​
Il link viene renderizzato come testo semplice invece di essere cliccabile

Alcuni renderer Markdown consentono solo link http e https e rimuovono altri schemi URL. GitHub lo fa nei README, nelle issue, nelle pull request e nei wiki: [label](claude-cli://...) viene renderizzato come label, senza link e con l’URL rimosso. Su queste piattaforme, metti il deep link in un blocco di codice in modo che i lettori possano vedere l’URL e incollarlo nella barra degli indirizzi del loro browser.

​
La sessione si apre nella mia home directory invece che nel repository

Il parametro repo risolve solo i clone che Claude Code ha già visto. Esegui claude all’interno del clone una volta in modo che Claude Code registri il suo percorso, o cambia il link per utilizzare cwd con un percorso assoluto. Su macOS, avvia claude nel tuo terminale preferito una volta e il prossimo deep link lo userà. Su Linux, imposta la variabile di ambiente $TERMINAL sul nome del comando dell’emulatore preferito. Su Windows, l’ordine è fisso: installa Windows Terminal se vuoi che i link si aprano lì invece di una finestra PowerShell o cmd.exe.

​
Ulteriori informazioni

Queste pagine coprono modi correlati per avviare o estendere le sessioni di Claude Code:
  • Skills: archivia un lungo prompt di runbook come /skill nel repository in modo che il parametro q del deep link debba solo nominarlo
  • Non-interactive mode: esegui Claude da uno script e cattura l’output senza aprire un terminale