Claude Code --setting-sourcesで読み込み元を指定する

--setting-sourcesと--settingsの役割

--setting-sourcesは、そのセッションで読み込む設定ファイルの種類をuser・project・localの中から絞り込むフラグです。--settingsは、設定ファイルへのパスか、インラインのJSON文字列そのものを渡し、同じキーがあればそのセッション限りでsettings.jsonの値を上書きするフラグです。どちらも実ファイルは一切書き換えません。

Claude Codeは通常起動時に、~/.claude/settings.json(user)、.claude/settings.json(project)、.claude/settings.local.json(local)、そして組織が配布するmanaged設定を読み込み、キーごとの優先順位で1つの設定に統合します。この2つのフラグは、その読み込みプロセスをコマンドラインから直接コントロールする手段です。

--setting-sourcesで読み込む範囲を絞る

指定できる値はuser・project・localの3つで、カンマ区切りで複数渡せます。

claude --setting-sources user,project

省略した場合は、これまでどおりuser・project・localのすべてが対象になります。managed設定はこの3つに含まれません。組織が配布するmanaged設定は、--setting-sourcesに何を指定しても常に読み込まれます。

なぜprojectだけを外したい場面があるのか。.claude/settings.jsonはリポジトリにコミットされ、そのプロジェクトで作業する人全員に配布されるファイルです。フックやMCPサーバーの設定もここに書けます。初めて開くリポジトリでは、project由来の設定を読み込まずに動作を確認したいことがあります。

claude --setting-sources user,local

--settingsでファイルを書き換えずに上書きする

--settingsは2通りの渡し方を受け付けます。1つはJSONファイルへのパス、もう1つはインラインのJSON文字列です。

claude --settings ./ci-overrides.json

claude --settings '{"model":"claude-opus-5"}'

ここで指定したキーは、そのセッションに限りsettings.jsonファイル群の同じキーより優先されます。指定しなかったキーは、通常どおりファイル側の値がそのまま使われます。ファイルを渡す場合は通常のファイルであること、かつ2MiB以下であることが条件です。上限を超えると起動そのものが止まります。原因の切り分け方はsettings 2MiBエラーの直し方にまとめてあります。

優先順位が具体的に効く例がフックです。project設定でフックを組んでいるリポジトリでも、そのフックを1回だけ止めて動作を確かめたいことがあります。

claude --settings '{"disableAllHooks": true}'

disableAllHooksはproject設定にもuser設定にも書けるキーですが、project設定の値がuser設定の値より優先されます。そこへさらに--settingsを重ねると、project設定・local設定の値より--settingsの値が優先されます。設定ファイルを一切編集せずに、1回の起動だけフックを止められます。

2つを組み合わせてCIや動作確認に使う

CIやテストでは、実行者個人のuser設定を巻き込みたくありません。projectだけを読み込み、足りないキーを--settingsで補う組み合わせが実務的です。

claude --setting-sources project --settings '{"permissions":{"defaultMode":"acceptEdits"}}' -p "run the test suite"

このコマンドは、実行者のuser設定・local設定を無視し、リポジトリのproject設定だけを土台にします。そのうえでpermissionsのdefaultModeだけをその場で上書きします。設定ファイルを一切書き換えないので、使い捨てのCIコンテナでも、手元の開発環境でも同じ結果になります。

claude agentsでも同じ--settingsが使える

--settingsは対話セッションの起動時だけでなく、並列で動くバックグラウンドセッションを一覧・操作するclaude agentsコマンドでも、トップレベルのclaudeコマンドと同じ形式で受け付けます。--add-dir・--plugin-dir・--mcp-configも同様です。エージェントビューを開くコマンド自体にも設定の上書きを渡せる、という位置付けです。

使い分け早見表

managed設定はどの指定でも常に読み込まれるため、表の「除外される設定」にはmanagedを含めていません。

除外の効果はキーごとに違う

--setting-sourcesで除外したソースの中身が、常にすべて無効になるとは限りません。サンドボックスの資格情報保護に関わるmaskエントリは、user設定・managed設定・--settingsからのみ有効で、project設定・local設定からはそもそも読み込まれない扱いです。除外の効果が及ぶ範囲はキーによって異なるため、機密情報に関わる設定は個別にsettings-referenceで確認するのが確実です。

面によっても扱いが変わります。VS Code拡張が開始する会話では、permissions.defaultModeのような一部のキーについてproject設定・local設定を読まず、user設定・managed設定・--settingsの値だけを見る特別な扱いになっています。ターミナルから起動したセッションとVS Code拡張のセッションで同じキーが違う値を拾うことがある、という点は覚えておく価値があります。

managed設定を配布している組織では、Claude Code組織管理ガイドにあるとおり、ユーザー側は多くのキーをそもそも上書きできません。--setting-sourcesや--settingsと併用しても、その優先順位は変わりません。

もう1つ、範囲の外にあるものがあります。IDEへの自動接続やdiffツールの選択など、一部のキーはsettings.json系のファイルではなく~/.claude.jsonというグローバル設定ファイルに保存されます。--setting-sourcesが絞り込むのはuser・project・local・managedという4つの設定ファイル群であり、~/.claude.jsonはその外にあるため、--setting-sources projectのようにほかを除外しても、そこに保存されたキーはいつもどおり読み込まれます。

より強く隔離したいときは--restricted

評価ハーネスが共有マシンでclaudeを動かし、そのマシンのuser設定・project設定を一切読ませたくない場面には、--restrictedフラグが用意されています(Claude Code v2.1.248以降)。managed設定と--settingsだけを読み込み、コマンド実行系のツールとWebFetchを--toolsで個別に指定しない限り外し、組み込みのファイル操作ツールも作業ディレクトリの中に閉じ込めます。bypassPermissionsは拒否され、クラウドセッションの作成もできません。--setting-sourcesが「どのファイルを読むか」を選ぶフラグであるのに対し、--restrictedは起動モードそのものを切り替えるフラグで、--toolsのような他のフラグと組み合わせて使う設計です。

よくあるつまずき

--setting-sourcesに渡せる値はuser・project・localの3つだけです。managed設定を含めたり除いたりする値は用意されていません。組織のポリシーを一時的に外す手段として使おうとしても、この仕組みでは実現しません。

--settingsにインラインJSONを渡すときは、シェルのクォートに注意が必要です。JSON側もダブルクォートを使うため、コマンド全体をダブルクォートで囲むと、シェルがJSON内のダブルクォートを先に解釈して壊れます。コマンド全体をシングルクォートで囲み、JSON側だけダブルクォートを使うのが安全です。

セッション単位フラグとしての位置付け

--setting-sourcesと--settingsには、対応する環境変数がありません。envキーで設定できる大半のキーとは違い、毎回起動時に明示しない限り効果は残りません。似た性格のフラグに--permission-modeがあります。どちらも保存済みの設定ファイルは変えず、そのセッションだけ挙動を変えるという共通点を持ちます。

Agent SDKで同じことをしたい場合は、settingSourcesオプションが対応します。CLIから都度指定したい場面と、SDK経由でプログラムから制御したい場面の違いはAgent SDK settingSourcesで扱っています。設定ファイル全体の構造やキー一覧はClaude Code設定ガイドが詳しいです。

対話中心の設定から、起動時に指定する設定へ

--setting-sourcesと--settingsが扱っているのは、どちらも「起動時に何を読み込むか」です。/configのようなセッション内コマンドが個人の常用設定を積み上げていく仕組みだとすれば、この2つのフラグは、その積み上げをその場で解除・上書きする側の仕組みです。CIランナーや評価ハーネス、複数のリポジトリを行き来する開発者にとっては、後者の比重が増えています。設定ファイルを都度書き換えずに済むぶん、起動コマンド自体が「この実行で何を保証したいか」を語るようになる、という変化と言えそうです。

まとめ

--setting-sourcesはuser・project・localのどれを読み込むかを絞り込み、--settingsはファイルかインラインJSONでその場限りの上書きを加えます。managed設定はどちらの指定からも独立して常に読み込まれ、mask設定のように除外の効果が及ばないキーもあります。設定ファイルを恒久的に変えたくない検証、他人のリポジトリを初めて開くとき、CIで再現性を保ちたいときに使う組み合わせです。