CLAUDE_CODE_PROCESS_WRAPPER は、Claude Code がそのバイナリから起動するすべてのプロセスをランチャーを通じて実行します。バックグラウンドサービス、エージェントビューでホストするすべてのセッション、および更新後の Claude Code の再起動が含まれます。ランチャーの絶対パスに設定すると、Claude Code はランチャーを実行し、Claude Code コマンドをその引数として渡します。
PATH 上の claude コマンドをラップするランチャーはこれらのプロセスに到達できません。これらのプロセスは claude を検索せずにバイナリの直接パスから起動するためです。
CLAUDE_CODE_PROCESS_WRAPPER には Claude Code v2.1.208 以降が必要です。以前のバージョンは変数を無視し、すべてのプロセスをラップなしで起動します。ランチャーがカバーするもの
CLAUDE_CODE_PROCESS_WRAPPER が設定されている場合、Claude Code は以下の各プロセスをランチャーを通じて起動します。
claude agentsとバックグラウンドセッションがオンデマンドで起動するバックグラウンドサービス。- すべてのエージェントビュー行内の Claude Code セッションとターミナルホスト（サービスが準備しておく温かいスタンバイセッションを含む）。
- 更新またはクラッシュ後にサービスが再生成するセッション。
- 更新のインストールを完了するために Claude Code が自身を再起動するプロセス（エージェントビューの更新用再起動アクションを含む）。
exec に依存しており、Windows はこれをサポートしていません。変数が設定されている Windows マシンはすべてのプロセスをラップなしで実行し、正常に動作します。唯一の信号はデバッグログの警告です。ランチャーポリシーが Windows をカバーしている場合、変数はそこでそれを満たしません。ロールアウトを計画する際に Windows マシンをラップなしとしてカウントしてください。
ランチャーの外で起動するプロセス
3 つのプロセスはランチャーを通じて起動しません。- インストール済みバックグラウンドサービス：
launchdまたはsystemdがそのプロセスをユニットファイルから起動します。これが適用される場合、/statusとclaude daemon statusが警告を表示し、サービスが変数をその設定で再起動すると、サービスが生成するセッションはランチャーを通じて起動します。 - ターミナルで自分で起動するセッション。これは呼び出し方法に関係なく実行されます。これらのセッションをカバーするには、
PATHの前のディレクトリにclaudeという名前のスクリプトを配置し、ランチャーを実際のバイナリで実行します。管理されたシンボリックリンクを置き換えないでください。自己生成はPATHを参照しないため、2 つのランチャーはスタックしません。 claude-cli://ディープリンクの最初のプロセス。オペレーティングシステムのプロトコルハンドラーが直接起動します。そのセッションがバックグラウンドで起動するすべてのものはランチャーを通じて実行されます。このパスを完全に閉じるには、disableDeepLinkRegistration設定でハンドラー登録を防止してください。
プロセスモニターのヘルパープロセス名
ランチャーが設定されている場合、ps と Activity Monitor は Claude Code の claude bg-pty-host と claude bg-spare ラベルの代わりに、バックグラウンドヘルパープロセスのバージョン付きバイナリ名を表示します。これはランチャーの exec が引数リストを再構築するためです。名前変更は隠蔽ではなく副作用です。プロセスはそれ以外は変更されず、Claude Code は表示名ではなくバイナリパスで独自のプロセスを識別します。
ランチャーをセットアップする
1
ランチャースクリプトを作成する
/opt/corp/launcher などの絶対パスに実行可能スクリプトを作成します。Claude Code はそれを完全な Claude Code コマンドをその引数として実行し、スクリプトは exec "$@" を呼び出して終了し、自身を Claude Code に置き換える必要があります。chmod +x で実行可能にします。セットアップ部分は、Claude Code を実行する前にランチャーが実行する必要があることです。下記のランチャーコントラクトはスクリプトが従う必要があるルールをリストしています。以前に
~/.local/bin/claude シンボリックリンクをランチャーで置き換えた場合は、同じ変更で元のシンボリックリンクを復元してください。置き換えられたシンボリックリンクにより、最初のラップされたセッションがバックグラウンドサービスを両方のランチャーを通じて同時に起動し、インストールを外部管理状態に置きます。/doctor がそれを報告し、自動更新はファイルをそのままにし、古いバージョンのクリーンアップはインストーラーが再びそのパスを管理するまで無効のままです。2
設定で CLAUDE_CODE_PROCESS_WRAPPER を設定する
デタッチされたバックグラウンドサービスがそれを継承するように、設定ファイルの 複数のソースが変数を設定する場合、管理設定値は
env ブロックで変数を設定します。シェル export では不十分です。バックグラウンドサービスはオンデマンドで起動し、シェルより長く存続し、シェルプロファイルを再読み込みしません。1 台のマシンの場合は、~/.claude/settings.json に追加します。組織内のすべてのマシンにデプロイするには、同じブロックを管理設定に配置します。~/.claude/settings.json とシェルでエクスポートされた値の両方をオーバーライドするため、ユーザーは自己生成を別のランチャーにポイントできません。プロジェクトおよびローカル設定はこの変数を設定できません。リポジトリにコミットされたファイルは、マシン上のすべての Claude Code プロセスの前にバイナリを配置できないため、.claude/settings.json または .claude/settings.local.json の CLAUDE_CODE_PROCESS_WRAPPER は無視され、デバッグログに警告が表示されます。3
バックグラウンドサービスとセッションを再起動する
実行中のバックグラウンドサービスと開いている
claude セッションは起動時に変数を 1 回読み込むため、再起動されるまでラップなしでプロセスを起動し続けます。claude daemon stop --any を実行してオンデマンドサービスを停止します。claude agents などそれを必要とする次のコマンドがラップされたものを起動します。インストール済みサービスは --any なしで claude daemon stop を実行します。その後、開いている claude セッションを再起動します。手動で再起動できないマシンでは、設定プッシュ後に起動された最初のセッションが残されたラップなしのオンデマンドサービスを自動的に廃止します。新しいセッションが起動しないマシンは、セッションが起動するまでラップなしのサービスを保持し、インストール済みサービスは常にこのステップで再起動が必要です。4
検証する
セッションで
/status を実行します。Self-exec エントリは解決された起動コマンドを表示し、実行中のバックグラウンドサービスがそれと一致しない場合に警告します。claude daemon status はシェルから同じ情報を出力します。変数を設定解除した後も含めて、/status はエントリを表示しなくなります。ランチャーコントラクト
ランチャーが実行できない場合、Claude Code はプロセスをラップなしで起動する代わりに起動を拒否します。Windows では、変数は無視され、プロセスはラップなしで起動します。Claude Code はスクリプトをこれらのルールに保持します。exec "$@"で終了する。 フォークして終了するランチャーは、バックグラウンドサービスが追跡できない孤立した Claude Code プロセスを残します。エージェントビューはそのようなセッションを失敗とマークし、ランチャーを名前で示すメッセージを表示し、サービスはランチャーが残したものを回収します。- 引数を並べ替え、吸収、または前置しない。 最初の引数は Claude Code バイナリで、その後のすべてはその argv です。
- 継承されたすべての環境変数を
execに渡す。 注入された認証情報などの変数を追加することは問題ありませんが、継承されたものをドロップすることはできません。- セッションごとの認証トークン、モデルとプロバイダーの選択、および
CLAUDE_CODE_PROCESS_WRAPPER自体はすべて継承された環境で移動するため、許可リストから再構築するランチャーは起動するセッションを破壊し、/statusはランチャーの不一致を報告します。 - ランチャーが環境をリセットするネームスペースまたはサンドボックスに入る必要がある場合は、その内部で継承された環境を逐語的に再エクスポートします。
- セッションごとの認証トークン、モデルとプロバイダーの選択、および
- ランチャーが実行されるたびに約 3 秒以内に
execに到達する。 コールドバックグラウンドディスパッチは最初の出力バイトの前にランチャーを 2 回連続で実行するため、シングルサインオン交換などの遅い作業を遅延または キャッシュから実行します。- 予算をはるかに超えて実行するランチャーは停止した起動として扱われ、再起動されます。
- 自身の内部から呼び出されることに耐える。 Claude Code はすべてのネストされた自己生成にランチャーを適用するため、排他的リソースを取得するランチャーはそれが既に保持していることを検出する必要があります。
- Claude Code が起動する前にターミナルに書き込まない。
execの前に出力されたものはすべて、セッションが初期化前に終了した場合のクラッシュ原因として報告されます。
CLAUDE_CODE_PROCESS_WRAPPER 値の形式
ほとんどのランチャーでは、値はスクリプトの絶対パスです（/opt/corp/launcher など）。
ランチャーに独自の引数を渡すには、パスの後に記述します。Claude Code は値をシェルコマンドではなく引数リストとして解析します。
- 空白はトークンを区切り、二重引用符はスペースを含むトークンをグループ化します。
[で始まる値は JSON 文字列配列として読み込まれます（["/opt/corp/launcher", "--profile", "cc"]など）。- シェル構文は機能しません。変数展開またはグロビングはなく、
;、|、&、$(などの引用符なしの演算子は再解釈ではなく設定エラーとして拒否されます。
CLAUDE_CODE_SHELL_PREFIX との関係
CLAUDE_CODE_PROCESS_WRAPPER は Claude Code 独自のプロセスをラップし、コマンドを分離された argv トークンとしてランチャーに渡して exec します。CLAUDE_CODE_SHELL_PREFIX は Claude Code が代わりに実行するシェルコマンド（Bash ツール呼び出し、hooks、stdio MCP サーバーを起動するコマンドなど）をラップし、各コマンドを $1 の単一のシェル引用文字列として渡して、ラッパーが再評価します。一方用に書かれたランチャーはもう一方として機能しません。
関連リソース
- エージェントビュー：ランチャーがカバーするバックグラウンドセッションとスーパーバイザープロセス
- 環境変数：
CLAUDE_CODE_PROCESS_WRAPPERリファレンスエントリ - 管理設定：
envブロックをフリート全体に配信 - ランチャーエラーリファレンス：拒否メッセージと復旧方法