Executar Claude Code atrás de um launcher corporativo

Rotear os processos que Claude Code inicia a partir de seu próprio binário, incluindo o serviço de fundo e cada sessão de visualização de agente, através de um launcher obrigatório com CLAUDE_CODE_PROCESS_WRAPPER ou a configuração processWrapper.

Algumas organizações exigem que cada processo em uma estação de trabalho seja iniciado através de um launcher obrigatório. O launcher aplica a sandbox, controles de rede ou injeção de credenciais das quais a postura de segurança da empresa depende, e um binário que inicia sem isso é uma violação de política.

CLAUDE_CODE_PROCESS_WRAPPER inicia cada processo que Claude Code lança a partir de seu próprio binário através do seu launcher: o serviço de fundo, cada sessão que hospeda em agent view, e os relançamentos do Claude Code após uma atualização. Defina-o como o caminho absoluto do seu launcher, e Claude Code executa o launcher com o comando Claude Code como seus argumentos.

Um launcher que envolve o comando claude no seu PATH não consegue alcançar esses processos, porque eles iniciam a partir do caminho direto do binário sem consultar claude.

O que o launcher cobre

Com CLAUDE_CODE_PROCESS_WRAPPER definido, Claude Code inicia cada um dos seguintes processos através do seu launcher:

• O serviço de fundo que claude agents e sessões de fundo iniciam sob demanda.
• O host do terminal e a sessão Claude Code dentro de cada linha de agent view, incluindo as sessões de espera quente que o serviço mantém prontas.
• Sessões que o serviço reinicia após uma atualização ou falha.
• O relançamento que Claude Code realiza de si mesmo para terminar de instalar uma atualização, incluindo a ação restart-for-update do agent view.
• Os processos de sessão que Remote Control inicia. Requer Claude Code v2.1.210 ou posterior.
• As sessões de teammate em split-pane que agent teams iniciam em tmux ou iTerm2. Os painéis de teammate são interativos em vez de processos de fundo, mas Claude Code os inicia a partir de seu próprio binário, então o launcher os cobre. Requer Claude Code v2.1.210 ou posterior.

No Windows, a variável é ignorada: o contrato do launcher depende de exec, que Windows não suporta. Uma máquina Windows com a variável definida executa cada processo sem envolvimento e continua funcionando, e o único sinal é um aviso no debug log. Se sua política de launcher cobre Windows, a variável não a satisfaz lá: conte máquinas Windows como sem envolvimento quando você planejar o lançamento.

Processos que iniciam fora do launcher

Os seguintes processos não iniciam através do launcher:

• Um serviço de fundo instalado cuja unidade foi escrita antes do launcher ser configurado: launchd ou systemd inicia esse processo a partir de seu arquivo de unidade. /status e claude daemon status avisam quando o serviço em execução e o launcher configurado não correspondem, e as sessões que o serviço gera ainda iniciam através do launcher uma vez que o serviço reinicia com a variável em suas configurações.
• Uma sessão que você inicia você mesmo em um terminal, que executa da forma como você a invocou. Para cobrir essas sessões, coloque um script chamado claude em um diretório anterior no PATH que executa seu launcher com o binário real; não substitua o symlink gerenciado. Self-spawns não consultam PATH, então os dois launchers nunca se empilham.
• O primeiro processo de um deep link claude-cli://, que o manipulador de protocolo do sistema operacional inicia diretamente. Tudo que essa sessão inicia em segundo plano depois executa através do launcher. Para fechar esse caminho completamente, impeça o registro do manipulador com a configuração disableDeepLinkRegistration.
• O relançamento que --worktree combinado com --tmux realiza: o multiplexador de terminal inicia esse painel, não o binário do Claude Code.
• O host de native-messaging que Claude in Chrome registra: o navegador o inicia, não o binário do Claude Code.

Nomes de processos auxiliares em monitores de processos

Com um launcher configurado, ps e Activity Monitor não mostram mais os rótulos claude bg-pty-host e claude bg-spare do Claude Code para os processos auxiliares de fundo, porque o exec do launcher reconstrói a lista de argumentos. Perder os rótulos é um efeito colateral, não ocultação: os processos são de outra forma inalterados, e Claude Code identifica seus próprios processos pelo caminho do binário, nunca pelo nome de exibição.

Configure o launcher

#!/bin/sh
# Configuração da sua organização: entre na sandbox, aplique
# controles de rede ou injete credenciais.
exec "$@"

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

{
"processWrapper": "/opt/corp/launcher"
}

O contrato do launcher

Quando o launcher não consegue executar, Claude Code recusa iniciar o processo em vez de iniciá-lo sem envolvimento. No Windows, a variável é ignorada e os processos iniciam sem envolvimento. Claude Code mantém o script a essas regras:

• Termine com exec "$@". Um launcher que bifurca um filho e sai deixa um processo Claude Code órfão que o serviço de fundo não consegue rastrear. Agent view marca tal sessão como falha com uma mensagem nomeando o launcher, e o serviço colhe o que o launcher deixou para trás.
• Não reordene, absorva ou antecipe argumentos. O primeiro argumento é o binário Claude Code e tudo depois dele é seu argv.
• Passe cada variável de ambiente herdada através para exec. Adicionar variáveis, como credenciais injetadas, é bom; descartar as herdadas não é.
  • Os tokens de autenticação por sessão, a seleção de modelo e provedor, e CLAUDE_CODE_PROCESS_WRAPPER em si viajam no ambiente herdado, então um launcher que o reconstrói a partir de uma lista de permissões quebra as sessões que inicia, e /status relata uma incompatibilidade de launcher.
  • Se o launcher deve entrar em um namespace ou sandbox que redefine o ambiente, re-exporte o ambiente herdado dentro dele verbatim.
• Alcance exec dentro de cerca de três segundos cada vez que o launcher executa. Uma expedição de fundo fria executa o launcher duas vezes em série antes do primeiro byte de saída, então faça trabalho lento como uma troca de single sign-on preguiçosamente ou a partir de um cache.
• Tolere ser invocado de dentro de si mesmo. Claude Code aplica o launcher a cada self-spawn aninhado, então um launcher que adquire um recurso exclusivo deve detectar que já o mantém.
• Não escreva no terminal antes de Claude Code iniciar. Qualquer coisa impressa antes do exec é relatada como a causa do crash se a sessão morrer antes de inicializar.

Formato do valor do launcher

CLAUDE_CODE_PROCESS_WRAPPER e a configuração processWrapper usam o mesmo formato. Para a maioria dos launchers, o valor é o caminho absoluto do script, como /opt/corp/launcher.

Para passar argumentos do seu launcher, escreva-os após o caminho. Claude Code analisa o valor como uma lista de argumentos, não um comando de shell:

• Espaço em branco separa tokens, e aspas duplas agrupam um token que contém espaços.
• Um valor que começa com [ é lido como um array de string JSON, como ["/opt/corp/launcher", "--profile", "cc"].
• Sintaxe de shell não funciona: não há expansão de variável ou globbing, e um operador sem aspas como ;, |, &, ou $( é rejeitado como um erro de configuração em vez de reinterpretado.

Quando o valor não pode ser usado, Claude Code recusa iniciar o processo afetado e relata o motivo.

Relação com `CLAUDE_CODE_SHELL_PREFIX`

CLAUDE_CODE_PROCESS_WRAPPER envolve os próprios processos do Claude Code e passa o comando através como tokens argv separados para o launcher fazer exec. CLAUDE_CODE_SHELL_PREFIX envolve os comandos de shell que Claude Code executa em seu nome, como chamadas de ferramenta Bash, hooks, e os comandos que iniciam servidores MCP stdio, e passa cada um como uma única string com aspas de shell em $1 para o wrapper reavaliar. Um launcher escrito para um não funciona como o outro.

Recursos relacionados

• Agent view: as sessões de fundo e processo supervisor que o launcher cobre
• Environment variables: a entrada de referência CLAUDE_CODE_PROCESS_WRAPPER
• Managed settings: entregar o bloco env em toda uma frota
• Launcher error reference: as mensagens de recusa e como se recuperar