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

managedSourcesBehaviorとは何か

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

権限・モデル制限・バージョン強制まで含めた組織管理全体はClaude Code組織管理ガイドにまとめています。本記事が扱うのは、そのうち複数ソースをどう1つに合成するかという結合ルールだけです。

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

managedSourcesBehaviorの挙動を理解するには、まず管理ソース(managed source)の優先順位を押さえる必要があります。Claude Codeは次の順序でソースを確認します。

リモート設定は、セッションがAnthropicのAPIに直接、対象となるログインまたはAPIキーで認証しているとき、または/loginでゲートウェイにサインインしたときにだけ取得されます。それ以外のプロバイダーを使っている、あるいはANTHROPIC_BASE_URLがAnthropic以外を指している場合は、この最上位ソースを飛ばして次のソースから確認が始まります。セルフホスト環境のランナーイメージでは、サーバー管理設定がポリシーキーを何も運ばなかったときに限り、ランナー内の管理設定ファイルも読みにいきます。

HKCUレジストリは「admin source」に数えられません。マージの対象は常に上位3つのソースだけで、HKCUはmanagedSourcesBehaviorの値に関係なく単独動作のフォールバックにとどまります。

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

「ポリシーキー」とは、managedSourcesBehavior自身とwslInheritsWindowsSettingsを除く、すべての設定キーを指します。デフォルトのfirst-winsでは、Claude Codeはポリシーキーを1つ以上運ぶ最も優先度の高いソースを採用し、それ以外のソースは(あとで扱うクロスソースキーを除いて)無視します。ポリシーキーを含まないソースは無視され、確認は次のソースへ進みます。

mergeにすると、ポリシーキーを運ぶすべての管理ソースがポリシーの合成に参加します。ただしmanagedSourcesBehavior自体は、このキーかポリシーキーのどちらかを運ぶ最高優先度のソースからしか読まれません。下位のソースが自分だけの判断で「マージに参加する」と宣言することはできない設計です。

{
  "managedSourcesBehavior": "merge"
}

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

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

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

見落とされやすいのは、mergeを有効にしても挙動が変わらないキーが残ることです。modelやcleanupPeriodDaysのような「その他のキー」は、mergeの有無にかかわらず最高優先度ソースの値がそのまま採用されます。apiKeyHelper・forceLoginOrgUUID・modelPicker・policyHelper・permissions.defaultMode・parentSettingsBehaviorも同様に、ポリシーキーを運ぶ最高優先度ソースだけから読まれ、下位ソースの値は最高優先度ソースがそのキーを未設定でも無視されます。mergeの効果が実際に表れるのは、リスト・ロック・MCPサーバー定義の3種類に限られます。

modelOverridesはavailableModelsと対になっており、上位ソースがavailableModelsを設定していてmodelOverridesを設定していない場合、modelOverridesは全ソースから無視されます。policyHelperは、ポリシーキーを運ぶ最高優先度ソースがMDMポリシーか管理設定ファイルのときだけ有効になり、サーバー管理設定が最高優先度ソースのときは実行されません。

managedSourcesBehaviorを設定していなくてもマージされるキーがある

ここまでの結合ルールはmanagedSourcesBehaviorの値に応じて切り替わりますが、一部のキーはfirst-winsのままでも常に全admin sourceから読まれます。代表例は次のとおりです。

• sandbox.network.allowManagedDomainsOnlyとsandbox.filesystem.allowManagedReadPathsOnly — いずれかのソースがtrueにすればロックが有効になり、ロックが効いている間は許可ドメイン・許可読み取りパスを全admin sourceから合算します
• enableArtifact — いずれかのソースがfalseにすればArtifactツールは無効(v2.1.242以降)
• maxEffortLevel — 複数ソースが上限を設定していれば、最も低い上限が採用される(v2.1.267以降)
• コミットトレーラーの無効化設定(attributionまたは非推奨のincludeCoAuthoredBy)
• forceRemoteSettingsRefresh
• env — 変数単位でソースをまたいで合成される(v2.1.223以降。それ以前は選ばれたソースのenvブロックを丸ごと採用)

これらは「クロスソースキー」と呼ばれ、managedSourcesBehaviorを"merge"にしていない組織でも、下位のMDMポリシーや管理設定ファイルが最高優先度ソースの空白を埋める形で効いてきます。

バージョンで機能がどう広がってきたか

managedSourcesBehavior自体はv2.1.242で初めて導入された機能です。それより前のバージョンが残るフリートでは、同じ管理設定ファイルを配っても古いクライアントは常にfirst-wins相当で動きます。段階的なロールアウト中は、この版差を前提に検証環境を分けておくのが安全です。

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

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

一方で、mergeは「下位ソースが持つリストを足し算する」機能でもあります。下位ソースの管理を外部ベンダーに委託している、あるいはファイルの配置権限が緩い端末が混ざっているなら、mergeは許可範囲を広げる抜け道になり得ます。判断基準は明確です。ランク付けで自分より下にあるすべてのソースを、自分と同じ水準で管理できているかどうかです。

managedSourcesBehaviorとparentSettingsBehaviorは何が違うか

似た名前のキーにparentSettingsBehaviorがあります。こちらはAgent SDKやIDE拡張、Claude Desktopのような埋め込みホストプロセスが渡す設定を、admin sourceの管理ポリシーとどう組み合わせるかを決めるキーです。managedSourcesBehaviorが扱うのは前節までのadmin source同士(リモート・MDM・ファイル)の合成で、対象がまったく別です。

parentSettingsBehaviorのデフォルトも"first-wins"で、この場合はホスト側の設定が管理ポリシーの存在下では捨てられます。"merge"にすると、ホスト側の設定は制限方向にしか働かないフィルターを通したうえで、管理ポリシーの下に適用されます。Claude Desktopがゲートウェイの通信許可リストを配る、といったケースがこのmergeの典型例です。2つのキーはどちらも"merge"にできますが、片方だけ設定しても他方には影響しません。

/statusで適用結果を確認する

どのソースが実際に採用されたかは、Claude Codeのセッション内で/statusを実行してSetting sourcesの行を読めば確認できます。

/status

Setting sourcesの末尾が, mergedで終わっていれば、その組織は複数の管理ソースを合成しています。(remote + file, merged)のような表示は、リモート設定と管理設定ファイルの両方が合成対象になったことを示します。逆に、配布したはずのソースが表示されない、またはSkipped sourcesという別の行にそのソースの名前が出ているなら、より優先度の高いソースがすでにポリシーキーを運んでいて、配布したソースは無視されています。Skipped sourcesの行はv2.1.242以降でのみ表示されます。

よくあるつまずき

• 管理設定ファイルだけに"managedSourcesBehavior": "merge"を書いても、上位のMDMやリモート設定がこのキーかポリシーキーのどちらも運んでいなければ効果を持ちません。このキーは常に最高優先度ソースからしか読まれないためです
• HKCUレジストリはmergeを有効にしてもマージ対象に入りません。ユーザー自身が書き換えられるレジストリだからです
• parentSettingsBehaviorをmanagedSourcesBehaviorと混同し、Agent SDKやIDE拡張からの設定が自動的にadmin sourceと合成されると思い込むケースがあります。2つは別のキーで、それぞれ個別に"merge"へ切り替える必要があります
• allowManagedPermissionRulesOnlyのようなロック系キーは、managedSourcesBehaviorをfirst-winsのままにしていても、どこかのソースが厳しい値を設定していれば常にそれが勝ちます。「first-winsだから緩いソースが勝つはず」という前提で検証すると、結果が食い違います
• modelOverridesだけを下位ソースに書いても、上位ソースがavailableModelsを設定していてmodelOverridesを設定していなければ、modelOverridesはどのソースからも無視されます

まとめ

managedSourcesBehaviorは、複数の管理設定ソースを1つのポリシーに合成するための切り替えキーで、既定値の"first-wins"から"merge"に変えるにはv2.1.242以降が必要です。mergeが実際に効くのはリスト・ロック・MCPサーバー定義の3種類のキーに限られ、modelのような単一値のキーは合成後も最高優先度ソースが勝ちます。envや一部のサンドボックスロックのようなクロスソースキーは、mergeを有効にしなくても常に全admin sourceから読まれる点も見落としやすいところです。有効にするかどうかは、ランク付けで自分より下にあるすべてのソースを自分と同じ水準で管理できているかで決まります。