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

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

CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは、複数の管理設定ソースがenvを個別キーで統合する挙動を止め、v2.1.223より前の丸ごと適用に戻す環境変数です。

読了目安 約9分

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

v2.1.223の前後でenvの扱いはどう変わったか

Claude Codeが読む管理設定のソースは、優先順位の高い順にサーバー管理設定・MDMポリシー・managed-settings.jsonファイル・WindowsのHKCUレジストリの4つです。最後のHKCUは、上位に管理ドキュメントが無いときだけ使われる退避先です。ユーザー自身が書き換えられる領域なので、envの統合には加わりません。

くらべる

管理設定のenvが複数ソースにあるとき

丸ごと適用

v2.1.223より前

優先順位が最も高いソースのenvブロックだけが適用されます。下位ソースのenvは、最上位ソースが設定していないキーも含めて反映されません。

キー単位マージ

v2.1.223以降

変数ごとに、定義している最上位のソースの値が使われます。最上位が設定していないキーは、下位ソースの値で埋まります。

CLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは、右側のキー単位マージを止めて左側へ戻すための変数です。

具体例で見る挙動の違い

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

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

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

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

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

反映される環境変数v2.1.223以降(既定)CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1
ANTHROPIC_BASE_URL(最上位ソースが設定)v2.1.223以降(既定)反映されるCLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1反映される
DISABLE_TELEMETRY(下位ソースだけが設定)v2.1.223以降(既定)反映される(キー単位マージ)CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1反映されない(丸ごと適用)

DISABLE_TELEMETRYの行が分かれるのは、サーバー管理設定がこのキーを設定しておらず、下位ソースが唯一の供給元になるためです。同じキーを両方が設定した場合は、どちらの挙動でも最上位ソースの値が勝ちます。

サーバー管理設定が配るenvのうち、プロキシやベースURLの変数はユーザーの承認ダイアログの対象です。DISABLE_TELEMETRYを1で配る場合は、ダイアログなしで適用されます。

キャッシュ済みのサーバー値がサーバーの確認待ちで保留されている間も、端末側のenvは、サーバー管理設定が未設定の変数に限って適用されます。

キー単位マージの例外になる変数

すべての変数が単純にキー単位で合流するわけではありません。サーバー管理設定のドキュメントは、次の2つを例外として挙げています。

  • テレメトリのひとまとまり: OTEL_EXPORTER_OTLP_*系、OTEL_LOG_*系、OTEL_LOGS_EXPORTER、ENABLE_BETA_TRACING_DETAILED、BETA_TRACING_ENDPOINTは、いずれかを設定している最上位のソースに一括で従います
  • 認証キーと組になったルーティング変数: apiKeyHelperやotelHeadersHelperと一緒に配られたルーティング変数は、そのソースが選ばれたときだけ適用されます

前者は、あるソースの送信先と別のソースの認証情報が組み合わさることを避ける設計です。上の例のANTHROPIC_BASE_URLは、apiKeyHelperと組で配っていなければ通常のキー単位マージに従います。

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

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

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

キーの種類"merge"での統合方法例
リスト系"merge"での統合方法全ソースの項目を結合例permissions.allow
ロック系"merge"での統合方法最も厳格な値を採用例allowManagedPermissionRulesOnly
制限許可リスト系"merge"での統合方法最上位で設定されたリストをまるごと採用例availableModels
env"merge"での統合方法"first-wins"でも"merge"でもキー単位でマージ例env
その他大半のキー"merge"での統合方法最上位ソースが設定した値だけを採用例model

"first-wins"のもとで上位ソースが何らかの管理設定キーを1つでも配布すると、下位のmanaged-settings.jsonが寄与できるのは「すべての管理ソースから読み取られるキー」だけになります。envはこの中に含まれます。つまりenvを下位ソースから切り離す手段は、managedSourcesBehaviorではなくCLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONです。

この変数が触れる範囲と触れない範囲

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

ユーザー・プロジェクト・ローカルの3つの間では、envはもともとキー単位で統合されています。ここにCLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONは関与しません。

管理設定の内側にも、この変数が届かない合流があります。ファイルベースの管理設定はmanaged-settings.jsonとmanaged-settings.d/内の*.jsonをアルファベット順に重ねて読み、envのようなネストしたブロックはキーごとに統合します。ファイルの置き場所は、macOSが/Library/Application Support/ClaudeCode/、LinuxとWSLが/etc/claude-code/、WindowsがC:\Program Files\ClaudeCode\です。これは1つのソースの中の話なので、この変数は管理ソースの間の統合を止めるものなので、止まるのは別のソースどうし、つまりサーバー管理設定・MDMポリシー・ファイルの間の統合だけです。開発者本人の設定ファイル間のenvの合成を変えたい場合、この変数では対応できません。

設定のしかた

この変数は、Claude Codeを起動するシェルやプロセスの環境に設定します。v2.1.223以降であることは、先にバージョンで確かめられます。

claude --version
# 2.1.289 (Claude Code)
export CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1
claude

下位ソースのenvを封じたい組織で起きること

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

v2.1.223より前は、サーバー管理設定がenvを配るだけで、managed-settings.json側のenvは丸ごと封じられました。

v2.1.223以降は、端末に置かれたファイルが古い、あるいは想定外の値を含んでいても、サーバー管理設定が同じキーを上書きしない限り効きます。CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1を起動環境に置けば、最上位ソースだけがenvの内容を決める旧来の構成に戻ります。

混在を避けたい代表例は2種類あります。ANTHROPIC_BASE_URLのようにAPIリクエストの送信先を切り替える変数と、CLAUDE_CODE_USE_BEDROCK・CLAUDE_CODE_USE_VERTEXのように利用するプロバイダーを切り替える変数です。最終値を決めるソースを1つに絞りたいなら、旧挙動のほうが対応関係を追いやすくなります。

想定外のenvが効いているときの切り分け

手順

どのソースが効いているかを調べる

  1. 1

    `/status`のSetting sourcesを読む

    セッション内で/statusを実行します。Enterprise managed settingsの横の括弧に、選ばれたソースが出ます。(remote)がサーバー管理設定、(plist)や(HKLM)がMDMまたはOSのポリシー、(file)がmanaged-settings.jsonです。ほかに、managed-settings.d/だけなら(drop-ins)、両方なら(file + drop-ins)と出ます。(HKCU)はユーザーが書き込める退避先のレジストリ、(parent process)は埋め込み元のホストが制限的な設定を渡した状態、(helper)は選ばれたMDMまたはファイルのソースが指定したpolicyHelperです。

  2. 2

    `, merged`の表示に注意する

    (remote + file, merged)のように, mergedで終わる表示は、managedSourcesBehaviorを"merge"にした組織でソースが合成されていることを示します。この表示にファイルが出てこなくても、下位ソースがenvの変数だけを供給している場合があります。

  3. 3

    `Skipped sources`を確認する

    選ばれなかった管理ソースがあると、Skipped sourcesの行にその名前が出ます。ポリシーが端末に届いていないのか、届いたうえで上位に上書きされたのかを見分けられます。この行はv2.1.242以降で表示されます。

  4. 4

    旧挙動で再現するか試す

    CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1を付けて起動し直し、想定外の変数が消えるかを見ます。消えれば、原因は下位ソースのenvの合流です。

/statusが示すのはソースの構成で、個々の変数の値ではありません。Setting sourcesの行そのものが出ないときは、ポリシーのキーを届けるソースが端末で見つかっていません。claude doctorは破棄された項目を一覧します。サーバー管理設定で配った場合、claude doctorは取得結果も報告します。

まとめ

下位ソースのenvを封じる運用なら、managedSourcesBehaviorではなくCLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONを、設定ファイルの外の起動環境に置きます。逆に、複数ソースを意図して合流させている組織では、この変数を入れずに/statusで構成を確かめるだけで足ります。

環境変数の用途別の一覧と、効かないときの切り分けはClaude Code環境変数リファレンスで扱っています。envのキー単位マージが導入された経緯はClaude Code v2.1.223、管理設定が壊れている場合の起動時の扱いはClaude Code v2.1.259で確認できます。ほかの環境変数によるオプトアウトの実例はDISABLE_TELEMETRYとはも参考になります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →