> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

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

<Note>
  `CLAUDE_CODE_PROCESS_WRAPPER` требует Claude Code v2.1.208 или более поздней версии. Более ранние версии игнорируют переменную и запускают каждый процесс без обертки.
</Note>

<h2 id="what-the-launcher-covers">
  Что охватывает launcher
</h2>

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

* Фоновый сервис, который запускают `claude agents` и фоновые сеансы по требованию.
* Хост терминала и сеанс Claude Code внутри каждой строки agent view, включая теплые резервные сеансы, которые сервис держит в готовности.
* Сеансы, которые сервис перезапускает после обновления или сбоя.
* Перезапуск, который Claude Code выполняет сам по себе, чтобы завершить установку обновления, включая действие restart-for-update в agent view.

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

<h3 id="processes-that-start-outside-the-launcher">
  Процессы, которые запускаются вне launcher
</h3>

Три процесса никогда не запускаются через launcher:

* [Установленный фоновый сервис](/docs/ru/agent-view#the-supervisor-process): `launchd` или `systemd` запускает этот процесс из его файла unit. `/status` и `claude daemon status` предупреждают, когда это применяется, и сеансы, которые запускает сервис, все еще запускаются через launcher после перезагрузки сервиса с переменной в его параметрах.
* Сеанс, который вы запускаете сами в терминале, который работает так, как вы его вызвали. Чтобы охватить эти сеансы, поместите скрипт с именем `claude` в каталог, который находится раньше в `PATH`, который запускает ваш launcher с реальным бинарным файлом; не заменяйте управляемый symlink. Self-spawns не консультируют `PATH`, поэтому два launcher никогда не складываются.
* Первый процесс `claude-cli://` deep link, который обработчик протокола операционной системы запускает напрямую. Все, что этот сеанс запускает в фоне после этого, работает через launcher. Чтобы полностью закрыть этот путь, [предотвратите регистрацию обработчика](/docs/ru/deep-links#registration-and-supported-platforms) с помощью параметра `disableDeepLinkRegistration`.

<h3 id="helper-process-names-in-process-monitors">
  Имена вспомогательных процессов в мониторах процессов
</h3>

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

<h2 id="set-up-the-launcher">
  Настройка launcher
</h2>

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

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

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

    <Note>
      Если вы ранее заменили symlink `~/.local/bin/claude` на ваш launcher, восстановите исходный symlink в том же изменении. Замененный symlink заставляет первый обернутый сеанс запустить фоновый сервис через оба launcher одновременно, и это помещает установку во внешнее управляемое состояние: `/doctor` это сообщает, auto-update оставляет файл на месте, и очистка старых версий остается отключенной до тех пор, пока установщик снова не будет управлять этим путем.
    </Note>
  </Step>

  <Step title="Установите CLAUDE_CODE_PROCESS_WRAPPER в параметрах">
    Установите переменную в блоке `env` файла параметров, чтобы отсоединенный фоновый сервис наследовал ее. Простой `export` в shell недостаточно: фоновый сервис запускается по требованию, переживает вашу shell и никогда не перечитывает профили shell.

    Для одной машины добавьте это в `~/.claude/settings.json`. Чтобы развернуть его на каждой машине в вашей организации, поместите тот же блок в [managed settings](/docs/ru/permissions#managed-settings):

    ```json theme={null}
    {
      "env": {
        "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
      }
    }
    ```

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

    Параметры проекта и локальные параметры не могут установить эту переменную. Файл, зафиксированный в репозитории, не должен иметь возможность поместить бинарный файл перед каждым процессом Claude Code на машине, поэтому `CLAUDE_CODE_PROCESS_WRAPPER` в `.claude/settings.json` или `.claude/settings.local.json` игнорируется с предупреждением в [debug log](/docs/ru/troubleshooting).
  </Step>

  <Step title="Перезагрузите фоновый сервис и ваши сеансы">
    Работающий фоновый сервис и любые открытые сеансы `claude` читают переменную один раз при запуске, поэтому они продолжают запускать процессы без обертки до перезагрузки. Запустите `claude daemon stop --any`, чтобы остановить сервис по требованию; следующая команда, которая его нужна, например `claude agents`, запускает обернутый. [Установленный сервис](/docs/ru/agent-view#the-supervisor-process) принимает `claude daemon stop` без `--any`. Затем перезагрузите открытые сеансы `claude`.

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

  <Step title="Проверьте">
    Запустите `/status` в сеансе: запись Self-exec показывает разрешенную команду запуска и предупреждает, когда работающий фоновый сервис не совпадает с ней. `claude daemon status` выводит ту же информацию из shell, включая после того, как вы отмените установку переменной, когда `/status` больше не показывает запись.
  </Step>
</Steps>

<h2 id="the-launcher-contract">
  Контракт launcher
</h2>

Когда launcher не может работать, Claude Code отказывается запустить процесс вместо того, чтобы запустить его без обертки. На Windows [переменная игнорируется](#what-the-launcher-covers) и процессы запускаются без обертки. 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 дважды подряд перед первым байтом вывода, поэтому выполняйте медленную работу, такую как обмен единственным входом, лениво или из кэша.
  * Launcher, который работает далеко за пределами бюджета, рассматривается как застопоренный старт и перезагружается.
* **Допускайте вызов изнутри себя.** Claude Code применяет launcher к каждому вложенному self-spawn, поэтому launcher, который получает исключительный ресурс, должен обнаружить, что он его уже держит.
* **Не пишите в терминал перед запуском Claude Code.** Все, что напечатано перед `exec`, сообщается как причина сбоя, если сеанс умирает перед инициализацией.

<h3 id="format-of-the-claude_code_process_wrapper-value">
  Формат значения `CLAUDE_CODE_PROCESS_WRAPPER`
</h3>

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

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

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

Когда значение не может быть использовано, Claude Code отказывается запустить затронутый процесс и [сообщает причину](/docs/ru/errors#claude_code_process_wrapper-launcher-errors).

<h2 id="relationship-to-claude_code_shell_prefix">
  Отношение к `CLAUDE_CODE_SHELL_PREFIX`
</h2>

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

<h2 id="related-resources">
  Связанные ресурсы
</h2>

* [Agent view](/docs/ru/agent-view): фоновые сеансы и процесс supervisor, который охватывает launcher
* [Environment variables](/docs/ru/env-vars): запись справки `CLAUDE_CODE_PROCESS_WRAPPER`
* [Managed settings](/docs/ru/permissions#managed-settings): доставьте блок `env` по всему парку
* [Launcher error reference](/docs/ru/errors#claude_code_process_wrapper-launcher-errors): сообщения об отказе и способы восстановления