Eseguire Claude Code dietro un launcher aziendale

​

Cosa copre il launcher

• Il servizio in background che claude agents e le sessioni in background avviano su richiesta.
• L’host del terminale e la sessione di Claude Code all’interno di ogni riga di agent view, incluse le sessioni di standby caldo che il servizio mantiene pronte.
• Le sessioni che il servizio riavvia dopo un aggiornamento o un crash.
• Il riavvio che Claude Code esegue di se stesso per completare l’installazione di un aggiornamento, inclusa l’azione restart-for-update di agent view.

​

Processi che si avviano al di fuori del launcher

• Un servizio in background installato: launchd o systemd avvia quel processo dal suo file di unità. /status e claude daemon status avvertono quando questo si applica, e le sessioni che il servizio genera si avviano comunque attraverso il launcher una volta che il servizio si riavvia con la variabile nelle sue impostazioni.
• Una sessione che avviate voi stessi in un terminale, che viene eseguita come l’avete invocata. Per coprire queste sessioni, mettete uno script denominato claude in una directory precedente su PATH che esegue il vostro launcher con il binario reale; non sostituite il symlink gestito. Gli auto-spawn non consultano PATH, quindi i due launcher non si impilano mai.
• Il primo processo di un deep link claude-cli://, che il gestore del protocollo del sistema operativo avvia direttamente. Tutto ciò che quella sessione avvia in background in seguito viene eseguito attraverso il launcher. Per chiudere completamente questo percorso, impedite la registrazione del gestore con l’impostazione disableDeepLinkRegistration.

​

Nomi dei processi helper nei monitor dei processi

​

Configurare il launcher

#!/bin/sh
# La configurazione della vostra organizzazione: entrare nella sandbox, applicare
# controlli di rete o iniettare credenziali.
exec "$@"

{
  "env": {
    "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
  }
}

​

Il contratto del launcher

• Terminare con exec "$@". Un launcher che crea un fork di un figlio e esce lascia un processo Claude Code orfano che il servizio in background non può tracciare. Agent view contrassegna tale sessione come non riuscita con un messaggio che nomina il launcher, e il servizio raccoglie ciò che il launcher ha lasciato indietro.
• Non riordinare, assorbire o anteporre argomenti. Il primo argomento è il binario di Claude Code e tutto ciò che segue è il suo argv.
• Passare ogni variabile di ambiente ereditata attraverso a exec. Aggiungere variabili, come credenziali iniettate, va bene; eliminare quelle ereditate no.
  • I token di autenticazione per sessione, la selezione del modello e del provider, e CLAUDE_CODE_PROCESS_WRAPPER stesso viaggiano tutti sull’ambiente ereditato, quindi un launcher che lo ricostruisce da un elenco di autorizzazione interrompe le sessioni che avvia, e /status segnala una mancata corrispondenza del launcher.
  • Se il launcher deve entrare in uno spazio dei nomi o in una sandbox che ripristina l’ambiente, ri-esportate l’ambiente ereditato all’interno di esso verbatim.
• Raggiungere exec entro circa tre secondi ogni volta che il launcher viene eseguito. Un dispatch in background a freddo esegue il launcher due volte in serie prima del primo byte di output, quindi fate il lavoro lento come uno scambio di single sign-on pigrizia o da una cache.
  • Un launcher che funziona molto oltre il budget viene trattato come un avvio bloccato e riavviato.
• Tollerare di essere invocato da dentro se stesso. Claude Code applica il launcher a ogni auto-spawn annidato, quindi un launcher che acquisisce una risorsa esclusiva deve rilevare che la detiene già.
• Non scrivere nel terminale prima che Claude Code si avvii. Qualsiasi cosa stampata prima dell’exec viene segnalata come causa del crash se la sessione muore prima dell’inizializzazione.

​

Formato del valore CLAUDE_CODE_PROCESS_WRAPPER

• Lo spazio bianco separa i token, e le virgolette doppie raggruppano un token che contiene spazi.
• Un valore che inizia con [ viene letto come un array di stringhe JSON, come ["/opt/corp/launcher", "--profile", "cc"].
• La sintassi di shell non funziona: non c’è espansione di variabili o globbing, e un operatore non quotato come ;, |, &, o $( viene rifiutato come errore di configurazione piuttosto che reinterpretato.

​

Relazione con CLAUDE_CODE_SHELL_PREFIX

​

Risorse correlate

• Agent view: le sessioni in background e il processo supervisore che il launcher copre
• Environment variables: la voce di riferimento CLAUDE_CODE_PROCESS_WRAPPER
• Managed settings: consegnare il blocco env in tutta una flotta
• Launcher error reference: i messaggi di rifiuto e come recuperare