SpyBara
Go Premium

corporate-launcher.md 2026-10-09 23:02 UTC to 2026-10-10 22:01 UTC

This page contains 6 additions and 7 deletions.

2026
Thu 8 22:58 Sat 10 23:01

Запуск 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:

  • Сеанс, который вы запускаете сами в терминале, который работает так, как вы его вызвали. Чтобы охватить эти сеансы, поместите скрипт с именем claude в каталог, который находится раньше в PATH, который запускает ваш launcher с реальным бинарным файлом; не заменяйте управляемый symlink. Фоновые процессы не консультируют 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

1

Напишите скрипт launcher

Создайте исполняемый скрипт по абсолютному пути, например /opt/corp/launcher. Claude Code запускает его с полной командой Claude Code в качестве его аргументов, и скрипт должен заканчиваться вызовом exec "$@", чтобы он заменил себя на Claude Code:

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

Сделайте его исполняемым с помощью chmod +x. Часть настройки — это все, что должен сделать ваш launcher перед запуском Claude Code; контракт launcher ниже перечисляет правила, которым должен следовать скрипт.

2

Установите CLAUDE_CODE_PROCESS_WRAPPER в параметрах

Установите переменную в блоке env файла параметров, чтобы отсоединенный фоновый сервис наследовал ее. Простой export в shell недостаточно: фоновый сервис запускается по требованию, переживает вашу shell и никогда не перечитывает профили shell.

Для одной машины добавьте это в ~/.claude/settings.json. Чтобы развернуть его на каждой машине в вашей организации, поместите тот же блок в managed settings:

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

Когда более одного источника устанавливает переменную, значение managed settings переопределяет как ~/.claude/settings.json, так и значение, экспортированное в shell, поэтому пользователи не могут указывать self-spawns на другой launcher.

Параметр processWrapper содержит то же значение, что и именованный ключ верхнего уровня параметров. Установите его, когда ваша организация отправляет параметры как отдельные ключи, а не как блок env. Параметр processWrapper требует Claude Code v2.1.210 или более поздней версии. Следующий файл параметров устанавливает тот же launcher через ключ:

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

CLAUDE_CODE_PROCESS_WRAPPER имеет приоритет, когда установлены оба.

Поскольку processWrapper является именованным параметром, организация, которая доставляет его через remote managed settings, видит его в списке на диалоге одобрения безопасности рядом с другими параметрами, которые запускают исполняемые файлы, предоставленные администратором.

Настройки проекта и локальные настройки не могут задать launcher. Файл, зафиксированный в репозитории, не должен иметь возможности поместить бинарный файл перед каждым процессом Claude Code на машине, поэтому Claude Code игнорирует CLAUDE_CODE_PROCESS_WRAPPER в .claude/settings.json или .claude/settings.local.json с предупреждением в отладочном логе и никогда не читает ключ processWrapper из этих файлов.

3

Перезапустите фоновый сервис и ваши сессии

Работающий фоновый сервис и любые открытые сессии claude читают переменную один раз при запуске, поэтому они продолжают запускать процессы без обёртки до перезапуска. Выполните claude daemon stop --any, чтобы остановить сервис, работающий по требованию. Следующая команда, которой он нужен, например claude agents, запустит обёрнутый сервис. Затем перезапустите открытые сессии claude.

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

4

Проверьте

Выполните /status в сессии: запись Self-exec показывает разрешённую команду запуска и предупреждает, когда работающий фоновый сервис ей не соответствует. claude daemon status выводит ту же информацию из оболочки, в том числе после того, как вы удалите переменную, когда /status больше не показывает эту запись.

Контракт 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, сообщается как причина сбоя, если сеанс умирает перед инициализацией.
  • Не полагайтесь на то, как записаны аргументы. Значение флага может прийти как отдельный аргумент, --flag value, или вместе с флагом, --flag=value. Форма, которую использует флаг, может меняться от версии к версии.

Формат значения 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: сообщения об отказе и способы восстановления