Запуск Claude Code через корпоративный launcher

Маршрутизируйте процессы, которые Claude Code запускает из собственного бинарного файла, включая фоновый сервис и каждый сеанс agent view, через требуемый launcher с помощью CLAUDE_CODE_PROCESS_WRAPPER или параметра processWrapper.

Некоторые организации требуют, чтобы каждый процесс на рабочей станции запускался через обязательный launcher. Launcher применяет sandbox, сетевые элементы управления или внедрение учетных данных, от которых зависит позиция безопасности компании, и бинарный файл, который запускается без него, является нарушением политики.

CLAUDE_CODE_PROCESS_WRAPPER запускает каждый процесс, который Claude Code запускает из собственного бинарного файла, через ваш launcher: фоновый сервис, каждый сеанс, который он размещает в agent view, и перезапуски Claude Code после обновления. Установите его на абсолютный путь вашего launcher, и Claude Code запустит launcher с командой Claude Code в качестве его аргументов.

Launcher, который оборачивает команду claude в вашем PATH, не может достичь эти процессы, потому что они запускаются из прямого пути бинарного файла без поиска claude.

Что охватывает launcher

С установленным CLAUDE_CODE_PROCESS_WRAPPER Claude Code запускает каждый из следующих процессов через ваш launcher:

• Фоновый сервис, который запускают claude agents и фоновые сеансы по требованию.
• Хост терминала и сеанс Claude Code внутри каждой строки agent view, включая теплые резервные сеансы, которые сервис держит в готовности.
• Сеансы, которые сервис перезапускает после обновления или сбоя.
• Перезапуск, который Claude Code выполняет сам по себе, чтобы завершить установку обновления, включая действие restart-for-update в agent view.
• Процессы сеансов, которые запускает Remote Control. Требуется Claude Code v2.1.210 или позже.
• Сеансы товарищей в разделенной панели, которые запускает agent teams в tmux или iTerm2. Панели товарищей являются интерактивными, а не фоновыми процессами, но Claude Code запускает их из своего собственного бинарного файла, поэтому launcher охватывает их. Требуется Claude Code v2.1.210 или позже.

На Windows переменная игнорируется: контракт launcher зависит от exec, который Windows не поддерживает. Машина Windows с установленной переменной запускает каждый процесс без обертки и продолжает работать, и единственный сигнал — это предупреждение в debug log. Если ваша политика launcher охватывает Windows, переменная не удовлетворяет ее там: при планировании развертывания считайте машины Windows как без обертки.

Процессы, которые запускаются вне launcher

Следующие процессы не запускаются через launcher:

• Установленный фоновый сервис, чей unit был написан до того, как был настроен launcher: launchd или systemd запускает этот процесс из его файла unit. /status и claude daemon status предупреждают, когда запущенный сервис и настроенный launcher не совпадают, и сеансы, которые запускает сервис, все еще запускаются через launcher после перезагрузки сервиса с переменной в его параметрах.
• Сеанс, который вы запускаете сами в терминале, который работает так, как вы его вызвали. Чтобы охватить эти сеансы, поместите скрипт с именем claude в каталог, который находится раньше в PATH, который запускает ваш launcher с реальным бинарным файлом; не заменяйте управляемый symlink. Self-spawns не консультируют PATH, поэтому два launcher никогда не складываются.
• Первый процесс claude-cli:// deep link, который обработчик протокола операционной системы запускает напрямую. Все, что этот сеанс запускает в фоне после этого, работает через launcher. Чтобы полностью закрыть этот путь, предотвратите регистрацию обработчика с помощью параметра disableDeepLinkRegistration.
• Перезапуск, который выполняет --worktree в сочетании с --tmux: терминальный мультиплексер запускает эту панель, а не бинарный файл Claude Code.
• Хост native-messaging, который регистрирует Claude in Chrome: браузер запускает его, а не бинарный файл Claude Code.

Имена вспомогательных процессов в мониторах процессов

С настроенным launcher ps и Activity Monitor больше не показывают метки Claude Code claude bg-pty-host и claude bg-spare для фоновых вспомогательных процессов, потому что exec launcher перестраивает список аргументов. Потеря меток является побочным эффектом, а не скрытием: процессы в остальном не изменены, и Claude Code идентифицирует свои собственные процессы по пути бинарного файла, никогда по отображаемому имени.

Настройка launcher

#!/bin/sh
# Настройка вашей организации: введите sandbox, примените
# сетевые элементы управления или внедрите учетные данные.
exec "$@"

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

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

Контракт launcher

Когда launcher не может работать, Claude Code отказывается запустить процесс вместо того, чтобы запустить его без обертки. На Windows переменная игнорируется и процессы запускаются без обертки. Claude Code придерживается скрипта этих правил:

• Заканчивайте с exec "$@". Launcher, который разветвляет дочерний процесс и выходит, оставляет сиротский процесс Claude Code, который фоновый сервис не может отследить. Agent view отмечает такой сеанс как неудачный с сообщением, называющим launcher, и сервис собирает то, что launcher оставил позади.
• Не переупорядочивайте, не поглощайте и не добавляйте аргументы в начало. Первый аргумент — это бинарный файл Claude Code, и все после него — это его argv.
• Передайте каждую унаследованную переменную окружения через exec. Добавление переменных, таких как внедренные учетные данные, хорошо; отбрасывание унаследованных — нет.
  • Токены аутентификации для каждого сеанса, выбор модели и поставщика, и сам CLAUDE_CODE_PROCESS_WRAPPER все путешествуют в унаследованной среде, поэтому launcher, который перестраивает ее из списка разрешений, нарушает сеансы, которые он запускает, и /status сообщает о несоответствии launcher.
  • Если launcher должен войти в пространство имен или sandbox, который сбрасывает окружение, повторно экспортируйте унаследованное окружение внутри него дословно.
• Достигните exec примерно за три секунды каждый раз, когда запускается launcher. Холодная фоновая отправка запускает launcher дважды подряд перед первым байтом вывода, поэтому выполняйте медленную работу, такую как обмен единственным входом, лениво или из кэша.
• Допускайте вызов изнутри себя. Claude Code применяет launcher к каждому вложенному self-spawn, поэтому launcher, который получает исключительный ресурс, должен обнаружить, что он его уже держит.
• Не пишите в терминал перед запуском Claude Code. Все, что напечатано перед exec, сообщается как причина сбоя, если сеанс умирает перед инициализацией.

Формат значения launcher

CLAUDE_CODE_PROCESS_WRAPPER и параметр processWrapper принимают одинаковый формат. Для большинства launcher значение — это просто абсолютный путь скрипта, например /opt/corp/launcher.

Чтобы передать вашему launcher его собственные аргументы, напишите их после пути. Claude Code анализирует значение как список аргументов, а не команду shell:

• Пробелы разделяют токены, а двойные кавычки группируют токен, содержащий пробелы.
• Значение, которое начинается с [, читается как массив строк JSON, например ["/opt/corp/launcher", "--profile", "cc"].
• Синтаксис shell не работает: нет расширения переменных или глобализации, и неквотированный оператор, такой как ;, |, & или $(, отклоняется как ошибка конфигурации, а не переинтерпретируется.

Когда значение не может быть использовано, Claude Code отказывается запустить затронутый процесс и сообщает причину.

Отношение к `CLAUDE_CODE_SHELL_PREFIX`

CLAUDE_CODE_PROCESS_WRAPPER оборачивает собственные процессы Claude Code и передает команду через отдельные токены argv для launcher в exec. CLAUDE_CODE_SHELL_PREFIX оборачивает команды shell, которые Claude Code запускает от вашего имени, такие как вызовы инструмента Bash, hooks и команды, которые запускают серверы stdio MCP, и передает каждую как одну строку в кавычках shell в $1 для обертки для переоценки. Launcher, написанный для одного, не работает как другой.

Связанные ресурсы

• Agent view: фоновые сеансы и процесс supervisor, который охватывает launcher
• Environment variables: запись справки CLAUDE_CODE_PROCESS_WRAPPER
• Managed settings: доставьте блок env по всему парку
• Launcher error reference: сообщения об отказе и способы восстановления