Skip to main content
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.
CLAUDE_CODE_PROCESS_WRAPPER requer Claude Code v2.1.208 ou posterior. Versões anteriores ignoram a variável e iniciam cada processo sem envolvimento.

​
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.
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

Três processos nunca iniciam através do launcher:
  • Um serviço de fundo instalado: launchd ou systemd inicia esse processo a partir de seu arquivo de unidade. /status e claude daemon status avisam quando isso se aplica, 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.

​
Nomes de processos auxiliares em monitores de processos

Com um launcher configurado, ps e Activity Monitor mostram o nome do binário versionado para os processos auxiliares de fundo em vez dos rótulos claude bg-pty-host e claude bg-spare do Claude Code, porque o exec do launcher reconstrói a lista de argumentos. A renomeação é 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

1

Escreva o script do launcher

Crie um script executável em um caminho absoluto, como /opt/corp/launcher. Claude Code o executa com o comando Claude Code completo como seus argumentos, e o script deve terminar chamando exec "$@" para que se substitua pelo Claude Code:
Torne-o executável com chmod +x. A porção de configuração é o que seu launcher deve fazer antes de Claude Code executar; o contrato do launcher abaixo lista as regras que o script deve seguir.
Se você substituiu anteriormente o symlink ~/.local/bin/claude pelo seu launcher, restaure o symlink original na mesma mudança. Um symlink substituído faz a primeira sessão envolvida iniciar o serviço de fundo através de ambos os launchers de uma vez, e coloca a instalação em um estado gerenciado externamente: /doctor relata isso, auto-update deixa o arquivo no lugar, e limpeza de versões antigas permanece desabilitada até que o instalador gerencie esse caminho novamente.
2

Defina CLAUDE_CODE_PROCESS_WRAPPER nas configurações

Defina a variável no bloco env de um arquivo de configurações para que o serviço de fundo desanexado a herde. Um export de shell não é suficiente: o serviço de fundo inicia sob demanda, sobrevive ao seu shell, e nunca relê perfis de shell.Para uma máquina, adicione-o a ~/.claude/settings.json. Para implantá-lo em cada máquina da sua organização, coloque o mesmo bloco em managed settings:
Quando mais de uma fonte define a variável, o valor de managed settings substitui tanto ~/.claude/settings.json quanto um valor exportado no shell, para que os usuários não possam apontar self-spawns para um launcher diferente.Configurações de projeto e local não podem definir essa variável. Um arquivo confirmado em um repositório não deve ser capaz de colocar um binário na frente de cada processo Claude Code na máquina, então CLAUDE_CODE_PROCESS_WRAPPER em .claude/settings.json ou .claude/settings.local.json é ignorado, com um aviso no debug log.
3

Reinicie o serviço de fundo e suas sessões

Um serviço de fundo em execução e quaisquer sessões claude abertas leem a variável uma vez na inicialização, então continuam lançando processos sem envolvimento até serem reiniciados. Execute claude daemon stop --any para parar o serviço sob demanda; o próximo comando que o necessita, como claude agents, inicia um envolvido. Um serviço instalado leva claude daemon stop sem --any. Então reinicie suas sessões claude abertas.Em máquinas que você não pode reiniciar manualmente, a primeira sessão iniciada após o push de configurações aposenta um serviço sob demanda sem envolvimento restante automaticamente. Uma máquina onde nenhuma nova sessão inicia mantém seu serviço sem envolvimento até que uma o faça, e um serviço instalado sempre precisa do reinício nesta etapa.
4

Verifique

Execute /status em uma sessão: a entrada Self-exec mostra o comando de lançamento resolvido e avisa quando o serviço de fundo em execução não corresponde a ele. claude daemon status imprime as mesmas informações do shell, incluindo depois que você desdefine a variável, quando /status não mostra mais a entrada.

​
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.
    • Um launcher que executa muito além do orçamento é tratado como um início travado e reiniciado.
  • 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 CLAUDE_CODE_PROCESS_WRAPPER

Para a maioria dos launchers, o valor é apenas 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.