CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONとは — env統合を旧仕様に戻す環境変数

CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは、組織が配布する複数の管理設定ソースがenvブロックをキー単位で統合する挙動を止める環境変数です。有効にすると、最上位ソースのenvブロックだけを丸ごと適用するv2.1.223より前の挙動に戻ります。1を設定すると有効になります。v2.1.223以降で使え、これより前のバージョンでは指定しても意味を持ちません。

v2.1.223で何が変わったか

Claude Codeが読む管理設定のソースは、サーバー管理設定・MDMポリシー・managed-settings.jsonファイルの3種類です。複数のソースを同時に配布している組織では、これらが同じキーを設定していたときにどちらが勝つかというルールが必要になります。

v2.1.223より前は、envブロックはソース単位の「丸ごと適用」でした。優先順位が最も高いソースがenvを1つでも設定していれば、そのソースのenvブロックだけが丸ごと適用されました。優先順位が低いソースのenvは、最上位ソースが設定していないキーも含めて一切反映されません。

v2.1.223からはこれが変わり、envだけはキー単位でマージされるようになりました。最上位ソースがキーAを設定し、優先順位の低い別のソースがキーBを設定していれば、両方とも最終的な環境変数として反映されます。同じキーを複数のソースが設定している場合は、優先順位の高いソースの値が勝ちます。CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは、このキー単位マージを無効にして旧挙動へ戻すための変数です。

具体例で見る挙動の違い

サーバー管理設定(優先順位が高い)が次のenvを配布しているとします。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

同じ組織で、特定の端末にだけmanaged-settings.jsonファイル(優先順位が低い)を置き、別のキーを設定しています。

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

この2つが両方存在する端末で起動したとき、実際に反映される環境変数は次のように変わります。

既定の挙動では、サーバー管理設定がDISABLE_TELEMETRYというキーを設定していないため、下位ソースのその値がそのまま素通りして両方の環境変数が有効になります。CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1を起動環境に設定すると、サーバー管理設定のenvブロックだけが丸ごと適用の対象になります。managed-settings.json側にしか書かれていないDISABLE_TELEMETRYは完全に無視されます。同じキーを両方のソースが設定した場合はどちらの挙動でも最上位ソースの値が勝つ点は変わりません。

managedSourcesBehaviorを変えても、envの統合は止まらない

管理設定にはmanagedSourcesBehaviorという別のキーがあり、"first-wins"(既定)と"merge"のどちらかを選べます。多くの設定キーは、"first-wins"なら最上位ソースの値だけが効き、"merge"なら複数ソースの値が合成されます。

envはこの分岐に従いません。公式ドキュメントは、envが"first-wins"と"merge"のどちらの設定でも管理ソースをまたいでキー単位マージされると明記しています。つまりmanagedSourcesBehaviorを既定の"first-wins"のままにしておいても、envだけは複数ソースから合成された状態になります。「first-winsにしてあるからenvも1ソースだけが効くはず」という想定は成立しません。この誤解を避けたいなら、managedSourcesBehaviorではなくCLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONを触る必要があります。

managedSourcesBehaviorが対象にするほかのキーの種類と比べると、envの位置づけがはっきりします。

envだけが唯一「managedSourcesBehaviorの値に関わらず常にキー単位マージ」という行になっており、この表の中でも特殊な立ち位置です。既定の"first-wins"のもとでも、より上位のソースが何らかの管理設定キーを1つでも配布すると、下位のmanaged-settings.jsonファイルの扱いが変わります。寄与できるのは「すべての管理ソースから読み取られるキー」だけに切り替わります。envはこのキーに含まれているため、"first-wins"の既定設定であっても複数ソースのenvが合成される対象になります。

統合の対象は管理設定どうしだけ

Claude Codeが読む設定ファイルは4階層に分かれます。ユーザー設定(~/.claude/settings.json)・プロジェクト設定(.claude/settings.json、リポジトリにコミットして共有)・ローカル設定(.claude/settings.local.json、自分専用でgit管理対象外)、そして管理設定(サーバー管理設定 / MDMポリシー / managed-settings.jsonファイル)の4つです。

ユーザー・プロジェクト・ローカルの3つの間では、envはもともとキー単位で統合されています。同じキーを複数のファイルが設定していれば優先順位の高いファイルの値が勝ちます。異なるキーであればそれぞれの値がそのまま合成される、通常の設定ファイル優先順位(settings precedence)に従うだけです。ここにCLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは関与しません。

この変数が影響を及ぼすのは、サーバー管理設定・MDMポリシー・managed-settings.jsonファイルという管理設定の3ソースどうしの統合だけです。管理設定は組織の管理者が全社や特定の端末へ配布するもので、開発者本人が編集するユーザー設定・プロジェクト設定・ローカル設定とは別の層に位置します。開発者本人の設定ファイル間でenvがどう合成されるかを変えたい場合、この変数では対応できません。

設定のしかた

この変数は、Claude Codeを起動するシェルやプロセスの環境に設定します。

export CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1
claude

このガードが入っている理由は、この変数自身が制御している対象と同じ経路を使わせないためだと読めます。envブロックを経由して配布できてしまうと、統合対象になっているenvの一部として扱われてしまい、どのソースの値が最終的に効くのかという判定が循環します。起動時の環境という、管理設定の統合ロジックより手前の層に置くことで、この変数だけは統合ルールの外側に立てます。

どんな組織がこの変数を必要とするか

キー単位マージが困る典型的な場面は、優先順位の異なる複数の管理ソースを別々の目的で運用している組織です。たとえば、サーバー管理設定で全社共通のベースラインを配布しつつ、特定の端末だけmanaged-settings.jsonファイルでローカルな上書きを許可しているケースを考えます。

v2.1.223より前なら、サーバー管理設定がenvを1つでも設定していれば、managed-settings.json側のenvは無視されます。管理者は「サーバー管理設定さえenvを設定すれば、下位ソースのenvは無効化できる」という前提で運用を設計できました。

v2.1.223以降のキー単位マージでは、サーバー管理設定が設定していないキーについては、managed-settings.json側の値がそのまま素通りします。下位ソースのenvを完全に封じ込めたい場合、これは意図しない経路になり得ます。端末に配置されたmanaged-settings.jsonファイルが古くなっていたり、想定外の値を含んでいたりしても、サーバー管理設定が同じキーを明示的に上書きしない限り効いてしまうためです。CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1を起動環境に設定しておけば、この経路を塞ぎ、最上位ソースだけがenvの内容を決める体制に戻せます。

混在を避けたいenvの代表例は2種類あります。ANTHROPIC_BASE_URLのようにAPIリクエストの送信先そのものを切り替える変数と、CLAUDE_CODE_USE_BEDROCK・CLAUDE_CODE_USE_VERTEXのように利用するプロバイダーを切り替える変数です。これらは通信経路を丸ごと変えるため、どのソースが最終的な値を決めているかをセキュリティレビューの対象にしている組織もあります。キー単位マージのままだと、レビュー対象外の下位ソースが設定した値が、上位ソースの見落とし(単にそのキーを設定し忘れているだけ)によって素通りしてしまう余地が生まれます。

どのソースが統合対象になるか確認する方法

現在どのソースの設定が組み合わさって適用されているかは、セッション内で/statusを実行し、Setting sourcesの行を確認します。複数の管理ソースを配布している環境で、envが想定どおりの値になっているか疑わしいときは、まずここで実際に読み込まれているソースの構成を確認するのが手早い切り分けです。CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONを設定した前後で同じコマンドを実行してみます。意図した環境変数だけが残っているかを見比べれば、思わぬソースからの値が混ざっていないかを個別に検証できます。

まとめ

CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは、管理設定のenvブロックの挙動を戻す環境変数です。v2.1.223からキー単位でソースをまたいでマージされるようになった挙動を、最上位ソースの丸ごと適用というそれ以前の挙動へ戻します。既定の統合を止めたい管理者が最初につまずきやすいポイントは2つあります。managedSourcesBehaviorを"first-wins"に保っていてもenvの統合は止まらない点と、設定ファイルのenvブロック経由では反映されず起動環境に直接設定する必要がある点です。管理設定全体の構造や優先順位はClaude Code環境変数リファレンスで一覧できます。envのキー単位マージが導入された経緯はClaude Code v2.1.223、管理設定が壊れている場合の起動時の扱いはClaude Code v2.1.259で確認できます。ほかの環境変数によるオプトアウトの実例はDISABLE_TELEMETRYとはも参考になります。