Skip to main content
Algunas organizaciones requieren que cada proceso en una estación de trabajo se inicie a través de un lanzador obligatorio. El lanzador aplica la zona de pruebas, los controles de red o la inyección de credenciales en las que depende la postura de seguridad de la empresa, y un binario que se inicia sin ella es una violación de política. CLAUDE_CODE_PROCESS_WRAPPER inicia cada proceso que Claude Code lanza desde su propio binario a través de su lanzador: el servicio de fondo, cada sesión que aloja en vista de agente, y los relanzamientos de Claude Code después de una actualización. Establézcalo en la ruta absoluta de su lanzador, y Claude Code ejecuta el lanzador con el comando de Claude Code como sus argumentos. Un lanzador que envuelve el comando claude en su PATH no puede alcanzar estos procesos, porque se inician desde la ruta directa del binario sin buscar claude.
CLAUDE_CODE_PROCESS_WRAPPER requiere Claude Code v2.1.208 o posterior. Las versiones anteriores ignoran la variable e inician cada proceso sin envolver.

​
Qué cubre el lanzador

Con CLAUDE_CODE_PROCESS_WRAPPER establecido, Claude Code inicia cada uno de los siguientes procesos a través de su lanzador:
  • El servicio de fondo que claude agents y las sesiones de fondo inician bajo demanda.
  • El host de terminal y la sesión de Claude Code dentro de cada fila de vista de agente, incluidas las sesiones de espera en caliente que el servicio mantiene listas.
  • Las sesiones que el servicio reinicia después de una actualización o un bloqueo.
  • El relanzamiento que Claude Code realiza de sí mismo para terminar de instalar una actualización, incluida la acción de reinicio para actualización de la vista de agente.
En Windows, la variable se ignora: el contrato del lanzador depende de exec, que Windows no admite. Una máquina Windows con la variable establecida ejecuta cada proceso sin envolver y continúa funcionando, y la única señal es una advertencia en el registro de depuración. Si su política de lanzador cubre Windows, la variable no la satisface allí: cuente las máquinas Windows como sin envolver cuando planifique el despliegue.

​
Procesos que se inician fuera del lanzador

Tres procesos nunca se inician a través del lanzador:
  • Un servicio de fondo instalado: launchd o systemd inicia ese proceso desde su archivo de unidad. /status y claude daemon status advierten cuando esto se aplica, y las sesiones que el servicio genera aún se inician a través del lanzador una vez que el servicio se reinicia con la variable en su configuración.
  • Una sesión que usted inicia usted mismo en una terminal, que se ejecuta como la invocó. Para cubrir estas sesiones, coloque un script llamado claude en un directorio anterior en PATH que ejecute su lanzador con el binario real; no reemplace el enlace simbólico administrado. Los auto-generados no consultan PATH, por lo que los dos lanzadores nunca se apilan.
  • El primer proceso de un enlace profundo claude-cli://, que el controlador de protocolo del sistema operativo inicia directamente. Todo lo que esa sesión inicia en el fondo después se ejecuta a través del lanzador. Para cerrar completamente este camino, evite el registro del controlador con la configuración disableDeepLinkRegistration.

​
Nombres de procesos auxiliares en monitores de procesos

Con un lanzador configurado, ps y Activity Monitor muestran el nombre binario versionado para los procesos auxiliares de fondo en lugar de las etiquetas claude bg-pty-host y claude bg-spare de Claude Code, porque el exec del lanzador reconstruye la lista de argumentos. El cambio de nombre es un efecto secundario, no un ocultamiento: los procesos son de otra manera sin cambios, y Claude Code identifica sus propios procesos por ruta binaria, nunca por nombre de visualización.

​
Configurar el lanzador

1

Escribir el script del lanzador

Cree un script ejecutable en una ruta absoluta, como /opt/corp/launcher. Claude Code lo ejecuta con el comando completo de Claude Code como sus argumentos, y el script debe terminar llamando a exec "$@" para que se reemplace a sí mismo con Claude Code:
Hágalo ejecutable con chmod +x. La porción de configuración es lo que su lanzador debe hacer antes de que Claude Code se ejecute; el contrato del lanzador a continuación enumera las reglas que el script debe seguir.
Si anteriormente reemplazó el enlace simbólico ~/.local/bin/claude con su lanzador, restaure el enlace simbólico original en el mismo cambio. Un enlace simbólico reemplazado hace que la primera sesión envuelta inicie el servicio de fondo a través de ambos lanzadores a la vez, y coloca la instalación en un estado administrado externamente: /doctor lo reporta, la actualización automática deja el archivo en su lugar, y la limpieza de versiones antiguas permanece deshabilitada hasta que el instalador administre esa ruta nuevamente.
2

Establecer CLAUDE_CODE_PROCESS_WRAPPER en configuración

Establezca la variable en el bloque env de un archivo de configuración para que el servicio de fondo desacoplado la herede. Una export de shell no es suficiente: el servicio de fondo se inicia bajo demanda, sobrevive a su shell y nunca vuelve a leer perfiles de shell.Para una máquina, agréguelo a ~/.claude/settings.json. Para implementarlo en cada máquina de su organización, coloque el mismo bloque en configuración administrada:
Cuando más de una fuente establece la variable, el valor de configuración administrada anula tanto ~/.claude/settings.json como un valor exportado en el shell, por lo que los usuarios no pueden apuntar auto-generados a un lanzador diferente.La configuración de proyecto y local no puede establecer esta variable. Un archivo confirmado en un repositorio no debe poder poner un binario frente a cada proceso de Claude Code en la máquina, por lo que CLAUDE_CODE_PROCESS_WRAPPER en .claude/settings.json o .claude/settings.local.json se ignora, con una advertencia en el registro de depuración.
3

Reiniciar el servicio de fondo y sus sesiones

Un servicio de fondo en ejecución y cualquier sesión claude abierta leen la variable una vez al inicio, por lo que continúan lanzando procesos sin envolver hasta que se reinician. Ejecute claude daemon stop --any para detener el servicio bajo demanda; el siguiente comando que lo necesite, como claude agents, inicia uno envuelto. Un servicio instalado toma claude daemon stop sin --any. Luego reinicie sus sesiones claude abiertas.En máquinas que no puede reiniciar manualmente, la primera sesión iniciada después del empuje de configuración retira automáticamente un servicio bajo demanda sin envolver restante. Una máquina donde no se inicia ninguna sesión nueva mantiene su servicio sin envolver hasta que lo haga, y un servicio instalado siempre necesita el reinicio en este paso.
4

Verificar

Ejecute /status en una sesión: la entrada Self-exec muestra el comando de lanzamiento resuelto y advierte cuando el servicio de fondo en ejecución no coincide con él. claude daemon status imprime la misma información desde el shell, incluido después de que desestablezca la variable, cuando /status ya no muestra la entrada.

​
El contrato del lanzador

Cuando el lanzador no puede ejecutarse, Claude Code se niega a iniciar el proceso en lugar de iniciarlo sin envolver. En Windows, la variable se ignora y los procesos se inician sin envolver. Claude Code mantiene el script a estas reglas:
  • Terminar con exec "$@". Un lanzador que bifurca un hijo y sale deja un proceso de Claude Code huérfano que el servicio de fondo no puede rastrear. La vista de agente marca tal sesión como fallida con un mensaje que nombra el lanzador, y el servicio recoge lo que el lanzador dejó atrás.
  • No reordene, absorba o anteponga argumentos. El primer argumento es el binario de Claude Code y todo después de él es su argv.
  • Pase cada variable de entorno heredada a través de exec. Agregar variables, como credenciales inyectadas, está bien; descartar las heredadas no.
    • Los tokens de autenticación por sesión, la selección de modelo y proveedor, y CLAUDE_CODE_PROCESS_WRAPPER en sí viajan en el entorno heredado, por lo que un lanzador que lo reconstruye desde una lista de permitidos rompe las sesiones que inicia, y /status reporta una falta de coincidencia del lanzador.
    • Si el lanzador debe entrar en un espacio de nombres o zona de pruebas que reinicia el entorno, vuelva a exportar el entorno heredado dentro de él textualmente.
  • Alcance exec dentro de aproximadamente tres segundos cada vez que se ejecute el lanzador. Un envío de fondo frío ejecuta el lanzador dos veces en serie antes del primer byte de salida, así que haga trabajo lento como un intercambio de inicio de sesión único de manera perezosa o desde un caché.
    • Un lanzador que se ejecuta mucho más allá del presupuesto se trata como un inicio estancado y se reinicia.
  • Tolere ser invocado desde dentro de sí mismo. Claude Code aplica el lanzador a cada auto-generado anidado, por lo que un lanzador que adquiere un recurso exclusivo debe detectar que ya lo posee.
  • No escriba en la terminal antes de que Claude Code se inicie. Cualquier cosa impresa antes del exec se reporta como la causa del bloqueo si la sesión muere antes de inicializarse.

​
Formato del valor CLAUDE_CODE_PROCESS_WRAPPER

Para la mayoría de los lanzadores, el valor es solo la ruta absoluta del script, como /opt/corp/launcher. Para pasar argumentos de su lanzador, escríbalos después de la ruta. Claude Code analiza el valor como una lista de argumentos, no como un comando de shell:
  • El espacio en blanco separa tokens, y las comillas dobles agrupan un token que contiene espacios.
  • Un valor que comienza con [ se lee como una matriz de cadenas JSON, como ["/opt/corp/launcher", "--profile", "cc"].
  • La sintaxis de shell no funciona: no hay expansión de variables ni globbing, y un operador sin comillas como ;, |, &, o $( se rechaza como un error de configuración en lugar de reinterpretarse.
Cuando el valor no se puede usar, Claude Code se niega a iniciar el proceso afectado y reporta la razón.

​
Relación con CLAUDE_CODE_SHELL_PREFIX

CLAUDE_CODE_PROCESS_WRAPPER envuelve los propios procesos de Claude Code y pasa el comando como tokens argv separados para que el lanzador exec. CLAUDE_CODE_SHELL_PREFIX envuelve los comandos de shell que Claude Code ejecuta en su nombre, como llamadas de herramienta Bash, hooks, y los comandos que inician servidores MCP de stdio, y pasa cada uno como una única cadena entrecomillada de shell en $1 para que el contenedor vuelva a evaluar. Un lanzador escrito para uno no funciona como el otro.