> ## 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 を実行する

> CLAUDE_CODE_PROCESS_WRAPPER または processWrapper 設定を使用して、Claude Code がそのバイナリから起動するプロセス（バックグラウンドサービスとすべてのエージェントビューセッションを含む）を必須ランチャーを通じてルーティングします。

一部の組織では、ワークステーション上のすべてのプロセスが必須ランチャーを通じて起動することを要求しています。ランチャーは、企業のセキュリティ体制が依存するサンドボックス、ネットワーク制御、または認証情報の注入を適用し、それなしで起動するバイナリはポリシー違反です。

`CLAUDE_CODE_PROCESS_WRAPPER` は、Claude Code がそのバイナリから起動するすべてのプロセスをランチャーを通じて起動します。[バックグラウンドサービス](/docs/ja/agent-view#the-supervisor-process)、[エージェントビュー](/docs/ja/agent-view)でそれがホストするすべてのセッション、および更新後の Claude Code の再起動が含まれます。ランチャーの絶対パスに設定すると、Claude Code はランチャーを実行し、Claude Code コマンドをその引数として渡します。

`PATH` 上の `claude` コマンドをラップするランチャーはこれらのプロセスに到達できません。これらのプロセスは `claude` を検索せずにバイナリの直接パスから起動するためです。

<Note>
  `CLAUDE_CODE_PROCESS_WRAPPER` には Claude Code v2.1.208 以降が必要です。以前のバージョンは変数を無視し、すべてのプロセスをラップなしで起動します。同等の [`processWrapper` 設定](/docs/ja/settings-reference#processwrapper)には v2.1.210 以降が必要です。以前のバージョンはそれを未知のキーとして無視し、ランチャーを適用せず、エラーを報告しません。

  どちらの形式を展開した後でも、[検証ステップ](#set-up-the-launcher)を使用して、実行中のバージョンがそれを適用していることを確認してください。
</Note>

<h2 id="what-the-launcher-covers">
  ランチャーがカバーするもの
</h2>

`CLAUDE_CODE_PROCESS_WRAPPER` が設定されている場合、Claude Code は以下の各プロセスをランチャーを通じて起動します。

* `claude agents` とバックグラウンドセッションがオンデマンドで起動するバックグラウンドサービス。
* すべてのエージェントビュー行内の Claude Code セッションとターミナルホスト（サービスが準備しておく温かいスタンバイセッションを含む）。
* 更新またはクラッシュ後にサービスが再生成するセッション。
* 更新のインストールを完了するために Claude Code が自身を再起動するプロセス（エージェントビューの更新用再起動アクションを含む）。
* [Remote Control](/docs/ja/remote-control) が起動するセッションプロセス。Claude Code v2.1.210 以降が必要です。
* [agent teams](/docs/ja/agent-teams) が tmux または iTerm2 で起動するスプリットペインティームメイトセッション。ティームメイトペインはバックグラウンドプロセスではなくインタラクティブですが、Claude Code が独自のバイナリから起動するため、ランチャーがカバーします。Claude Code v2.1.210 以降が必要です。

Windows では、変数は無視されます。ランチャーコントラクトは `exec` に依存しており、Windows はこれをサポートしていません。変数が設定されている Windows マシンはすべてのプロセスをラップなしで実行し、正常に動作します。唯一の信号は[デバッグログ](/docs/ja/troubleshooting)の警告です。ランチャーポリシーが Windows をカバーしている場合、変数はそこでそれを満たしません。ロールアウトを計画する際に Windows マシンをラップなしとしてカウントしてください。

<h3 id="processes-that-start-outside-the-launcher">
  ランチャーの外で起動するプロセス
</h3>

以下のプロセスはランチャーを通じて起動しません。

* ターミナルで自分で起動するセッション。これは呼び出し方法に関係なく実行されます。これらのセッションをカバーするには、`PATH` の前のディレクトリに `claude` という名前のスクリプトを配置し、ランチャーを実際のバイナリで実行します。管理されたシンボリックリンクを置き換えないでください。バックグラウンドサービスとそのセッションは `PATH` ルックアップなしで起動するため、2 つのランチャーはスタックしません。
* `claude-cli://` ディープリンクの最初のプロセス。オペレーティングシステムのプロトコルハンドラーが直接起動します。そのセッションがバックグラウンドで起動するすべてのものはランチャーを通じて実行されます。このパスを完全に閉じるには、`disableDeepLinkRegistration` 設定で[ハンドラー登録を防止](/docs/ja/deep-links#registration-and-supported-platforms)してください。
* `--worktree` と `--tmux` を組み合わせた再起動：ターミナルマルチプレクサーがそのペインを起動し、Claude Code のバイナリではありません。
* [Claude in Chrome](/docs/ja/chrome) が登録するネイティブメッセージングホスト：ブラウザーが起動し、Claude Code のバイナリではありません。

<h3 id="helper-process-names-in-process-monitors">
  プロセスモニターのヘルパープロセス名
</h3>

ランチャーが設定されている場合、`ps` と Activity Monitor は Claude Code の `claude bg-pty-host` と `claude bg-spare` ラベルをバックグラウンドヘルパープロセスに対して表示しなくなります。これはランチャーの `exec` が引数リストを再構築するためです。ラベルを失うことは隠蔽ではなく副作用です。プロセスはそれ以外は変更されず、Claude Code は表示名ではなくバイナリパスで独自のプロセスを識別します。

<h2 id="set-up-the-launcher">
  ランチャーをセットアップする
</h2>

<Steps>
  <Step title="ランチャースクリプトを作成する">
    `/opt/corp/launcher` などの絶対パスに実行可能スクリプトを作成します。Claude Code はそれを完全な Claude Code コマンドをその引数として実行し、スクリプトは `exec "$@"` を呼び出して終了し、自身を Claude Code に置き換える必要があります。

    ```bash theme={null}
    #!/bin/sh
    # Your organization's setup: enter the sandbox, apply
    # network controls, or inject credentials.
    exec "$@"
    ```

    `chmod +x` で実行可能にします。セットアップ部分は、Claude Code を実行する前にランチャーが実行する必要があることです。[下記のランチャーコントラクト](#the-launcher-contract)はスクリプトが従う必要があるルールをリストしています。

    <Note>
      以前に `~/.local/bin/claude` シンボリックリンクをランチャーで置き換えた場合は、同じ変更で元のシンボリックリンクを復元してください。置き換えられたシンボリックリンクにより、最初のラップされたセッションがバックグラウンドサービスを両方のランチャーを通じて同時に起動し、インストールを外部管理状態に置きます。`/doctor` がそれを報告し、自動更新はファイルをそのままにし、古いバージョンのクリーンアップはインストーラーが再びそのパスを管理するまで無効のままです。
    </Note>
  </Step>

  <Step title="設定で CLAUDE_CODE_PROCESS_WRAPPER を設定する">
    デタッチされたバックグラウンドサービスがそれを継承するように、設定ファイルの `env` ブロックで変数を設定します。シェル `export` では不十分です。バックグラウンドサービスはオンデマンドで起動し、シェルより長く存続し、シェルプロファイルを再読み込みしません。

    1 台のマシンの場合は、`~/.claude/settings.json` に追加します。組織内のすべてのマシンにデプロイするには、同じブロックを[管理設定](/docs/ja/managed-settings)に配置します。

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

    複数のソースが変数を設定する場合、管理設定値は `~/.claude/settings.json` とシェルでエクスポートされた値の両方をオーバーライドするため、ユーザーは自己生成を別のランチャーにポイントできません。

    [`processWrapper` 設定](/docs/ja/settings-reference#processwrapper)は名前付きのトップレベル設定キーと同じ値を持ちます。組織が設定を `env` ブロックではなく個別のキーとしてプッシュする場合に設定します。`processWrapper` 設定には Claude Code v2.1.210 以降が必要です。次の設定ファイルはキーを通じて同じランチャーを設定します。

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

    両方が設定されている場合、`CLAUDE_CODE_PROCESS_WRAPPER` が優先されます。

    `processWrapper` は名前付き設定であるため、[リモート管理設定](/docs/ja/managed-settings#delivery-mechanisms)を通じてそれを配信する組織は、[セキュリティ承認ダイアログ](/docs/ja/server-managed-settings#security-approval-dialogs)に管理者が提供した実行可能ファイルを実行する他の設定と一緒にリストされているのを見ます。

    プロジェクトおよびローカル設定はランチャーを設定できません。リポジトリにコミットされたファイルが、マシン上のすべての Claude Code プロセスの前にバイナリを配置できてはならないため、Claude Code は `.claude/settings.json` または `.claude/settings.local.json` の `CLAUDE_CODE_PROCESS_WRAPPER` を無視して[デバッグログ](/docs/ja/troubleshooting)に警告を記録し、これらのファイルから `processWrapper` キーを読み込むことはありません。
  </Step>

  <Step title="バックグラウンドサービスとセッションを再起動する">
    実行中のバックグラウンドサービスと開いている `claude` セッションは起動時に変数を 1 回読み込むため、再起動されるまでラップなしでプロセスを起動し続けます。`claude daemon stop --any` を実行してオンデマンドサービスを停止します。`claude agents` などそれを必要とする次のコマンドがラップされたものを起動します。その後、開いている `claude` セッションを再起動します。

    手動で再起動できないマシンでは、設定プッシュ後に起動された最初のセッションが残されたラップなしのオンデマンドサービスを自動的に廃止します。新しいセッションが起動しないマシンは、セッションが起動するまでラップなしのバックグラウンドサービスを保持します。
  </Step>

  <Step title="検証する">
    セッションで `/status` を実行します。Self-exec エントリは解決された起動コマンドを表示し、実行中のバックグラウンドサービスがそれと一致しない場合に警告します。`claude daemon status` は同じ情報をシェルから出力します。変数を設定解除して `/status` にエントリが表示されなくなった後でも出力されます。
  </Step>
</Steps>

<h2 id="the-launcher-contract">
  ランチャーコントラクト
</h2>

ランチャーが実行できない場合、Claude Code はプロセスをラップなしで起動する代わりに起動を拒否します。Windows では、[変数は無視され](#what-the-launcher-covers)、プロセスはラップなしで起動します。Claude Code はスクリプトをこれらのルールに保持します。

* **`exec "$@"` で終了する。** フォークして終了するランチャーは、バックグラウンドサービスが追跡できない孤立した Claude Code プロセスをバックグラウンドに残します。エージェントビューはそのようなセッションを失敗とマークし、ランチャーを名前で示すメッセージを表示し、サービスはランチャーが残したものを回収します。
* **引数を並べ替え、吸収、または前置しない。** 最初の引数は Claude Code バイナリで、その後のすべてはその argv です。
* **継承されたすべての環境変数を `exec` に渡す。** 注入された認証情報などの変数を追加することは問題ありませんが、継承されたものをドロップすることはできません。
  * セッションごとの認証トークン、モデルとプロバイダーの選択、および `CLAUDE_CODE_PROCESS_WRAPPER` 自体はすべて継承された環境で移動するため、許可リストから再構築するランチャーは起動するセッションを破壊し、`/status` はランチャーの不一致を報告します。
  * ランチャーが環境をリセットするネームスペースまたはサンドボックスに入る必要がある場合は、その内部で継承された環境を逐語的に再エクスポートします。
* **ランチャーが実行されるたびに約 3 秒以内に `exec` に到達する。** コールドバックグラウンドディスパッチは最初の出力バイトの前にランチャーを 2 回連続で実行するため、シングルサインオン交換などの遅い作業を遅延またはキャッシュから実行します。
* **自身の内部から呼び出されることに耐える。** Claude Code はすべてのネストされた自己生成にランチャーを適用するため、排他的リソースを取得するランチャーはそれが既に保持していることを検出する必要があります。
* **Claude Code が起動する前にターミナルに書き込まない。** `exec` の前に出力されたものはすべて、セッションが初期化前に終了した場合のクラッシュ原因として報告されます。
* **引数の表記方法に依存しない。** フラグの値は、独立した引数（`--flag value`）として渡される場合もあれば、フラグに結合された形（`--flag=value`）で渡される場合もあります。フラグがどちらの形式を使用するかは、バージョン間で変わる可能性があります。
* **ランチャーが起動したディレクトリから `exec` を実行する。** Claude Code は起動したディレクトリで作業するため、ディレクトリを変更するランチャーは誤ったプロジェクトでセッションを開始する可能性があります。ランチャーが作業ディレクトリをリセットするネームスペースまたはサンドボックスに入る必要がある場合は、`exec` の前に、その内部で起動時のディレクトリに戻ります。

<h3 id="format-of-the-launcher-value">
  ランチャー値の形式
</h3>

`CLAUDE_CODE_PROCESS_WRAPPER` と `processWrapper` 設定は同じ形式を使用します。ほとんどのランチャーでは、値はスクリプトの絶対パスです（`/opt/corp/launcher` など）。

ランチャーに独自の引数を渡すには、パスの後に記述します。Claude Code は値をシェルコマンドではなく引数リストとして解析します。

* 空白はトークンを区切り、二重引用符はスペースを含むトークンをグループ化します。
* `[` で始まる値は JSON 文字列配列として読み込まれます（`["/opt/corp/launcher", "--profile", "cc"]` など）。
* シェル構文は機能しません。変数展開またはグロビングはなく、`;`、`|`、`&`、`$(` などの引用符なしの演算子は再解釈ではなく設定エラーとして拒否されます。

値を使用できない場合、Claude Code は影響を受けるプロセスの起動を拒否し、[理由を報告](/docs/ja/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 トークンとしてランチャーに渡して `exec` します。[`CLAUDE_CODE_SHELL_PREFIX`](/docs/ja/env-vars) は Claude Code が代わりに実行するシェルコマンド（Bash ツール呼び出し、hooks、stdio MCP サーバーを起動するコマンドなど）をラップし、各コマンドを `$1` の単一のシェル引用文字列として渡して、ラッパーが再評価します。一方用に書かれたランチャーはもう一方として機能しません。

<h2 id="related-resources">
  関連リソース
</h2>

* [エージェントビュー](/docs/ja/agent-view)：ランチャーがカバーするバックグラウンドセッションとスーパーバイザープロセス
* [環境変数](/docs/ja/env-vars)：`CLAUDE_CODE_PROCESS_WRAPPER` リファレンスエントリ
* [管理設定](/docs/ja/permissions#managed-settings)：`env` ブロックをフリート全体に配信
* [ランチャーエラーリファレンス](/docs/ja/errors#claude_code_process_wrapper-launcher-errors)：拒否メッセージと復旧方法