managedSourcesBehaviorで複数の管理設定ソースを統合する

managedSourcesBehaviorとは何か

Claude Codeの管理設定(managed settings)は、組織が複数の経路から同じ端末に配ることがあります。既定では、そのうち最も優先度の高い1ソースだけが採用され、残りは捨てられます。managedSourcesBehaviorは、この「1つだけ採用」をやめて複数ソースを1つのポリシーに合成させるキーです。値は"first-wins"(既定)と"merge"の2つで、mergeにはClaude Code v2.1.242以降が必要です。

権限・モデル制限・バージョン強制まで含めた組織管理の全体像はClaude Code組織管理ガイドにあります。ここでは、複数ソースがどう1つに合成されるかという結合ルールだけを掘り下げます。

配ったポリシーが効かないとき、最初に見る場所

MDMで配ったはずの設定が効かない、という報告を受けたら、まず当の端末でセッションを開いて/statusを実行します。見るのはSetting sourcesの行です。

行が出ないのは、ポリシーキーを運ぶ管理ソースが見つからないときです。管理設定ファイルを置いたなら、OSごとのパス(macOSは/Library/Application Support/ClaudeCode/managed-settings.json、Linuxは/etc/claude-code/managed-settings.json)にあることと、managedSourcesBehaviorだけでなくポリシーキーが入っていることを確かめます。JSONが壊れているファイルは、この状態ではなくClaude Codeの起動拒否になります。

既定のfirst-winsには、読み飛ばされたソースを知らせる警告がありません。「配ったのに効かない」が静かに起きるので、Skipped sourcesの行が唯一の手がかりです。

4つの管理設定ソースの優先順位

Claude Codeは、次の順序でソースを確認します。

リモート設定が取得されるのは、セッションがAnthropicのAPIへ直接、対象となるログインまたはAPIキーで認証しているときと、/loginでゲートウェイにサインインしたときだけです。それ以外のプロバイダーを使っている場合や、ANTHROPIC_BASE_URLがAnthropic以外を指している場合は、最上位を飛ばして次のソースから確認が始まります。

HKCUは「admin source」に数えられず、managedSourcesBehaviorの値に関係なく合成に加わりません。しかも、上位にadmin documentが「存在する」と見なされれば、HKCUはその下で一切適用されません。存在と見なされるのは、null以外の値でポリシーキーを1つでも持つ場合と、HKLM値・管理設定ファイル・managed-settings.dが存在するのに読めない場合です。読めないファイルでも、HKCUを押さえる側に回ります。

「ポリシーキー」とは、managedSourcesBehavior自身とwslInheritsWindowsSettingsを除くすべての設定キーです。この2つしか載っていないファイルやMDMポリシーは数えられず、確認は次のソースへ進みます。

first-winsとmergeで何が変わるか

managedSourcesBehavior自体は、このキーかポリシーキーのどちらかを運ぶ最上位のソースからしか読まれません。下位のソースが自分の判断で「合成に参加する」と宣言する抜け道は塞がれています。

{
  "managedSourcesBehavior": "merge"
}

このキーは、配布するソースのうち最も優先度の高いものに書きます。サーバー管理設定を配らない端末なら、MDMプロファイルにも書く必要があります。管理設定ファイルは最下位のadmin sourceで、その下に合成相手がないため、ファイル側だけに書いても効果はありません。

2つのソースに同じ設定を置くと結果はどう違うか

MDMとファイルの2ソースが、次のように設定を持つ端末を考えます。MDM側がmanagedSourcesBehavior: "merge"を持つかどうかで、結果が分かれます。以下は各キーの種類ごとの規則を当てはめた読み方です。

• MDM: permissions.allowにBash(git status)、modelにsonnet
• ファイル: permissions.allowにBash(npm test)、modelにopus、cleanupPeriodDaysに14、envに変数TEAM_NAME

差が出るのは1行目と3行目です。modelのように両方が設定するキーはどちらでも上位が勝ち、envはmanagedSourcesBehaviorと無関係に変数単位で合成されます。mergeは「上位が黙っているキーを下位が埋める」挙動をもたらす設定でもあります。

mergeで種類ごとにどう統合されるか

mergeが有効なとき、Claude Codeはキーの種類ごとに異なる規則で値を組み立てます。

ロックの「緩い値」の扱いは見落とされがちです。どのソースも厳しい値を設定していなければ、緩い値は最上位ソースのものだけが採用されます。

組み合わせに条件が付くキーもあります。modelOverridesはavailableModelsと対で、上位ソースがavailableModelsだけを設定している場合は、すべてのソースのmodelOverridesが無視されます。policyHelperは、ポリシーキーを運ぶ最上位がMDMか管理設定ファイルのときだけ働き、サーバー管理設定が最上位なら実行されません。

managedSourcesBehaviorを設定していなくても合成されるキー

一部のキーは、first-winsのままでも全admin sourceから読まれます。下位のMDMポリシーや管理設定ファイルが、最上位ソースの空白を埋める形で効きます。この読み取りからHKCUは外れます。代表的なものは次のとおりです。

• sandbox.network.allowManagedDomainsOnlyとsandbox.filesystem.allowManagedReadPathsOnly — いずれかのソースがtrueならロックが有効になり、許可ドメイン・許可読み取りパスを全admin sourceから合算します
• allowManagedMcpServersOnly — いずれかがtrueならロックが有効になり、allowedMcpServersは、設定しているソースのうち最上位のものがそのまま使われます(v2.1.273以降)
• deniedMcpServersとdisableClaudeAiConnectors — どれかのソースにエントリかtrueがあれば適用されます(v2.1.273以降)
• enableArtifact — いずれかがfalseならArtifactツールが無効(v2.1.242以降)
• maxEffortLevel — 最も低い上限が採用され、どのソースも上限を引き上げられません(v2.1.267以降)
• attribution(または非推奨のincludeCoAuthoredBy)によるコミットトレーラーの無効化、forceRemoteSettingsRefresh
• env — 変数単位で、各変数は定義している最上位ソースから取られます(v2.1.223以降)

envの扱いが変わったのはv2.1.223です。それ以前は、選ばれたソースのenvブロックを丸ごと採用していました。

ゲートウェイのログイン用キー(forceLoginGatewayUrlなど)は別の規則です。サーバー管理設定からは読まれません。サーバー管理設定が採用されていても、ポリシーキーを運ぶ端末上の最上位admin sourceが値を供給します。それより下位のadmin sourceやHKCUに書いた値は無視されます。

バージョンで合成の範囲はどう広がったか

mergeはv2.1.242より前のバージョンでは使えません。複数のバージョンが混在するフリートでは、同じ管理設定を配っても、合成が効く端末と効かない端末が出ます。

mergeを有効にするかの判断基準

mergeは、複数の部署やベンダーがそれぞれ別の管理ソースを持ち込む組織のためにあります。MDM側がベースラインのサンドボックス設定を配り、IT部門が管理設定ファイルで追加の許可ドメインを足す運用は、first-winsのままだと成立しません。MDMの設定が勝ち、ファイル側の追加分は、前節のクロスソースキーを除いて切り捨てられるためです。

逆に、mergeは下位ソースのリストを足し算する機能でもあります。下位ソースの管理を外部ベンダーに委託している、ファイルの配置権限が緩い端末が混ざっている、といった状況では、許可範囲を広げる抜け道になり得ます。決め手は、自分より下位のすべてのソースを、自分と同じ水準で管理できているかどうかです。

managedSourcesBehaviorとparentSettingsBehaviorは何が違うか

名前が似たparentSettingsBehaviorは、Agent SDK・IDE拡張・Claude Desktopのような埋め込みホストが渡す設定を、管理ポリシーとどう組み合わせるかを決めます。managedSourcesBehaviorが扱うのはadmin source同士(リモート・MDM・ファイル)の合成で、対象が別です。2つのキーはどちらも"merge"にできますが、片方の設定はもう片方に影響しません。

parentSettingsBehaviorの既定も"first-wins"で、管理ポリシーがあるとホスト側の設定は捨てられます。"merge"にすると、ホストの設定は制限方向の値だけを残すフィルターを通り、管理ポリシーの下に適用されます。Claude Desktopがゲートウェイの通信許可リストを配る場面が典型です。注意点が1つあります。allowManaged*Onlyのロックを併せて設定しない限り、ホストが渡した権限の許可ルールとサンドボックスの許可リストは、フィルター後もそのまま効きます。

よくあるつまずき

• 管理設定ファイルだけに"managedSourcesBehavior": "merge"を書いても、上位のMDMやリモート設定がこのキーもポリシーキーも運んでいなければ効果はありません。このキーは最上位ソースからしか読まれないためです
• HKCUレジストリは、mergeにしても合成対象に入りません。ユーザー自身が書き換えられるレジストリだからです
• parentSettingsBehaviorをmanagedSourcesBehaviorと混同し、Agent SDKやIDE拡張の設定が自動でadmin sourceと合成されると思い込むケースがあります。別のキーなので、それぞれ個別に切り替えます
• allowManagedPermissionRulesOnlyのようなロックは、first-winsなら選ばれたソースの値で決まります。mergeのときに初めて「どのソースでも最も厳しい値が勝つ」規則が働くため、first-winsの端末で下位ソースのロックに期待しても効きません。例外は前掲のクロスソースのロックです
• modelOverridesだけを下位ソースに書いても、上位ソースがavailableModelsを設定していてmodelOverridesを設定していなければ、どのソースからも無視されます
• Windows端末で/statusのSetting sources行が(HKCU)だけになるのは、admin sourceが1つも存在しないときです。MDMやファイルを配ったつもりでこの表示なら、配布したものが端末で見つかっていません

まとめ

複数の管理ソースを持つ組織で決めることは、mergeにするかどうかの1点です。リストが足し算になる代わりに、下位ソースの配置権限まで管理者が握っている必要があります。効いているかどうかは、端末で/statusのSetting sourcesが, mergedで終わっているかと、Skipped sourcesに配布物が残っていないかで判断できます。