Exécuter Claude Code via un lanceur d'entreprise

​

Ce que le lanceur couvre

• Le service d’arrière-plan que claude agents et les sessions d’arrière-plan démarrent à la demande.
• L’hôte terminal et la session Claude Code à l’intérieur de chaque ligne de vue agent, y compris les sessions de secours à chaud que le service maintient prêtes.
• Les sessions que le service redémarre après une mise à jour ou un plantage.
• Le relancement que Claude Code effectue de lui-même pour terminer l’installation d’une mise à jour, y compris l’action de redémarrage pour mise à jour de la vue agent.

​

Processus qui démarrent en dehors du lanceur

• Un service d’arrière-plan installé : launchd ou systemd démarre ce processus à partir de son fichier d’unité. /status et claude daemon status avertissent quand cela s’applique, et les sessions que le service génère démarrent toujours via le lanceur une fois que le service redémarre avec la variable dans ses paramètres.
• Une session que vous démarrez vous-même dans un terminal, qui s’exécute comme vous l’avez invoquée. Pour couvrir ces sessions, mettez un script nommé claude dans un répertoire plus tôt sur PATH qui exécute votre lanceur avec le vrai binaire ; ne remplacez pas le lien symbolique géré. Les auto-générations ne consultent pas PATH, donc les deux lanceurs ne s’empilent jamais.
• Le premier processus d’un lien profond claude-cli://, que le gestionnaire de protocole du système d’exploitation démarre directement. Tout ce que cette session démarre en arrière-plan par la suite s’exécute via le lanceur. Pour fermer complètement ce chemin, empêchez l’enregistrement du gestionnaire avec le paramètre disableDeepLinkRegistration.

​

Noms des processus d’aide dans les moniteurs de processus

​

Configurer le lanceur

#!/bin/sh
# Configuration de votre organisation : entrez dans le bac à sable, appliquez
# les contrôles réseau ou injectez les credentials.
exec "$@"

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

​

Le contrat du lanceur

• Terminez par exec "$@". Un lanceur qui crée un enfant et se termine laisse un processus Claude Code orphelin que le service d’arrière-plan ne peut pas suivre. La vue agent marque une telle session comme échouée avec un message nommant le lanceur, et le service récolte ce que le lanceur a laissé derrière.
• Ne réordonnez pas, n’absorbez pas et ne préparez pas les arguments. Le premier argument est le binaire Claude Code et tout ce qui suit est son argv.
• Passez chaque variable d’environnement héritée via exec. Ajouter des variables, comme les credentials injectées, est correct ; supprimer les héritées ne l’est pas.
  • Les jetons d’authentification par session, la sélection du modèle et du fournisseur, et CLAUDE_CODE_PROCESS_WRAPPER lui-même voyagent tous sur l’environnement hérité, donc un lanceur qui le reconstruit à partir d’une liste d’autorisation casse les sessions qu’il démarre, et /status signale une non-correspondance du lanceur.
  • Si le lanceur doit entrer dans un espace de noms ou un bac à sable qui réinitialise l’environnement, réexportez l’environnement hérité à l’intérieur verbatim.
• Atteignez exec en environ trois secondes chaque fois que le lanceur s’exécute. Une expédition d’arrière-plan à froid exécute le lanceur deux fois en série avant le premier octet de sortie, donc faites un travail lent comme un échange d’authentification unique paresseusement ou à partir d’un cache.
  • Un lanceur qui s’exécute bien au-delà du budget est traité comme un démarrage bloqué et redémarré.
• Tolérez d’être invoqué de l’intérieur de vous-même. Claude Code applique le lanceur à chaque auto-génération imbriquée, donc un lanceur qui acquiert une ressource exclusive doit détecter qu’il la détient déjà.
• N’écrivez pas sur le terminal avant que Claude Code ne démarre. Tout ce qui est imprimé avant le exec est signalé comme la cause du plantage si la session meurt avant l’initialisation.

​

Format de la valeur CLAUDE_CODE_PROCESS_WRAPPER

• L’espace blanc sépare les jetons, et les guillemets doubles groupent un jeton qui contient des espaces.
• Une valeur qui commence par [ est lue comme un tableau de chaînes JSON, comme ["/opt/corp/launcher", "--profile", "cc"].
• La syntaxe shell ne fonctionne pas : il n’y a pas d’expansion de variable ou de globbing, et un opérateur non cité comme ;, |, & ou $( est rejeté comme une erreur de configuration plutôt que réinterprété.

​

Relation avec CLAUDE_CODE_SHELL_PREFIX

​

Ressources connexes

• Vue agent : les sessions d’arrière-plan et le processus superviseur que le lanceur couvre
• Variables d’environnement : l’entrée de référence CLAUDE_CODE_PROCESS_WRAPPER
• Paramètres gérés : livrez le bloc env sur une flotte
• Référence d’erreur du lanceur : les messages de refus et comment récupérer