Claude Code --setting-sourcesで読み込み元を指定する
--setting-sourcesは読み込む設定ファイルの範囲を絞り、--settingsはファイルを書き換えずにその場でキーを上書きします。組み合わせ方と注意点を解説します。
--setting-sourcesと--settingsの役割
2つのフラグは、起動時の設定の扱いに別々の角度から手を入れます。どちらも設定ファイルの実体は書き換えません。
読む範囲を絞るか、値を上書きするか
--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つのフラグです。優先順位は高い順にmanaged、コマンドライン引数、local、project、userです。
初めて開くリポジトリで--setting-sourcesを使う
.claude/settings.jsonはリポジトリにコミットされ、作業する全員に配布されます。フックの設定もここに書けます。MCPサーバーの共有設定は、リポジトリ直下の.mcp.jsonに置かれます。初めて開く他人のリポジトリでは、project由来の設定を読まずに動きを見たい場面があります。
projectを外して起動し、中身を見てから通常起動へ戻す
- 1
projectを除いて起動する
user・localだけを読み込みます。
- 2
リポジトリの設定ファイルを読む
.claude/settings.jsonのフックと、.mcp.jsonのMCPサーバーの記述を、自分の目で確かめます。 - 3
問題なければ通常起動に戻す
フラグを外して起動し直します。
claude --setting-sources user,local値はカンマ区切りで複数渡せ、省略するとuser・project・localがすべて対象です。指定できるのはこの3つだけで、managed設定は指定の対象に含まれません。managedを指す値は用意されていないので、このフラグで組織のポリシーを一時的に外す使い方はできません。
渡せる値は3つだけ
v2.1.287で、存在しない値を渡して起動すると次のエラーで止まります。
Error processing --setting-sources: Invalid setting source: bogus. Valid options are: user, project, localclaude --helpの説明も1行です(v2.1.287)。
--setting-sources <sources> Comma-separated list of setting sources
to load (user, project, local).--settingsでファイルを書き換えずに上書きする
--settingsはJSONファイルへのパスと、インラインのJSON文字列の2通りを受け付けます。
claude --settings ./ci-overrides.jsonclaude --settings '{"model":"claude-opus-5"}'指定しなかったキーは、ファイル側の値がそのまま使われます。ファイルは通常のファイルで、2MiB以下という条件があります。上限を超えると、終了コード1で起動が止まります。
デバイス・FIFO・ソケットを指すと、次のエラーに続けてパスが表示されます。
Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))ディレクトリを指すとEISDIRの理由が付きます。どちらも起動時に終了コード1で止まります。2MiB超えの切り分けはsettings 2MiBエラーの直し方にあります。
permissions.allowのような配列のキーは、通常は置き換えではなく結合されます。--settingsでallowを1件足しても、ファイル側のallowは消えません。結合では他のファイルの要素が除かれないので、permissions.allowに空配列を渡してもファイル側のルールは消せません。そのソースごと外すなら--setting-sourcesです。
例外は、モデルに関する4つのキーです。fallbackModelは最高優先度の値を丸ごと採用し、modelPickerは最も優先度の高いソースの値を丸ごと採用します。availableModelsはmanagedが定義していればそのリストをそのまま適用し、modelSettingsも独自の規則に従います。たとえばmodelPickerはv2.1.242以降、project・localに書いても無視されます。
インラインJSONを渡すときは、コマンド全体をシングルクォートで囲み、JSON側だけダブルクォートにします。全体をダブルクォートにすると、シェルがJSON内の引用符を先に解釈して壊れます。
フックを1回だけ止める
project設定でフックを組んでいるリポジトリでも、設定ファイルを編集せずに1回だけ止められます。
claude --settings '{"disableAllHooks": true}'disableAllHooksは、フックに加えて、カスタムのステータスラインと@のファイル候補コマンドも同時に止めます。managed設定のフックは、managed設定側でしか止められません。
CIでは2つを組み合わせる
CIやテストでは、実行者個人のuser設定を巻き込みたくありません。projectだけを土台にして、足りないキーを--settingsで補います。
claude --setting-sources project --settings '{"permissions":{"defaultMode":"acceptEdits"}}' -p "run the test suite"user設定・local設定は無視され、リポジトリのproject設定だけが残ります。defaultModeはその場で上書きされます。設定ファイルは変わらないので、user・localの差は結果に入らなくなります。
claude -pやAgent SDKのセッションは承認の確認を出せないため、プロジェクトの.mcp.jsonのサーバーを確認なしで読み込みます。外す手段の1つが、--setting-sourcesでprojectを除くことです。
バックグラウンドや並列セッションにも引き継がれる
--setting-sourcesの絞り込みは、起動した本体のセッションだけで終わりません。一緒に動く別のセッションにも渡ります。
絞り込みが引き継がれる場面
バックグラウンド化したセッション
←や/bgでバックグラウンドに回したセッションが、起動時の--setting-sourcesをそのまま持ちます。v2.1.281より前は、全ソースを読み込んでいました。agent viewから起動するセッション
claude agentsは--settings・--setting-sources・--plugin-dirを自分自身に適用し、そこから起動するセッションにも渡します。エージェントチームのチームメイト
リードを
--setting-sourcesで起動すると、チームメイトも同じ範囲から読み込みます。分割ペイン表示のチームメイトは、v2.1.281より前は全ソースを読んでいました。--worktree --tmuxで起動するセッション
--worktree --tmuxで起動するセッションも、親の制限を持った状態で始まります。
この修正の対象には、SDKのsettingSourcesも含まれます。
claude agentsに渡すとき、フラグの置き場所には差があります。--settings・--setting-sources・--plugin-dirはagentsの前後どちらでも構いません。--add-dirと--mcp-configはagentsの後ろに置かないと、claude agents --jsonがunknown optionエラーになります。
Remote Controlでは位置の制約がもっと厳しくなります。--settingsや--setting-sourcesをremote-controlの前に置くと、そのフラグはRemote Controlが起動するセッションに届きません。黙って落とすことはせず、起動そのものを拒否します。表示は次のとおりです。
Error: `--settings` before `remote-control` is not carried over to the
sessions Remote Control starts, so Remote Control refuses to start
rather than drop it — remove it, and give Remote Control's own options
after the verb (see `claude remote-control --help`).使い分け早見表
| 指定値 | 読み込む設定 | 除外される設定 | 向いている場面 |
|---|---|---|---|
| 省略 | 読み込む設定user / project / localすべて | 除外される設定なし | 向いている場面通常の対話・開発 |
user,project,local | 読み込む設定user / project / localすべて | 除外される設定なし | 向いている場面挙動を明示したいスクリプト |
user,local | 読み込む設定user / local | 除外される設定project | 向いている場面初めて開くリポジトリの動作確認 |
project | 読み込む設定project | 除外される設定user / local | 向いている場面CIでリポジトリ側の設定だけを再現 |
除外しても効かないものがある
--setting-sourcesで除外したソースの中身が、常にすべて無効になるとは限りません。逆に、除外してもしなくても読まれるものもあります。
サンドボックスの資格情報保護にあるmaskエントリは、user設定・managed設定・--settingsからだけ有効です。project設定・local設定に書いても読み込まれません。機密情報に関わるキーは、settings-referenceのScope欄で個別に確かめるのが確実です。
VS Code拡張が開始する会話では、permissions.defaultModeについてuser・managed・--settingsの値だけを読みます。ターミナルとVS Codeで、同じキーが違う値を拾うことがあります。
~/.claude.jsonに保存されるキーは、--setting-sourcesの対象外です。IDEへの自動接続やdiffツールの選択などがこれに当たります。
逆に、コマンドサンドボックスのファイルシステム設定は--setting-sourcesの絞り込みに従います。除外したソースに書いたサンドボックスの許可・拒否は、そのセッションには入りません。
managed設定を配布している組織では、Claude Code組織管理ガイドにあるとおり、ユーザー側が上書きできないキーが多数あります。--settingsで渡したキーも、同じmanagedのキーは上書きできません。
より強く隔離したいときは--restricted
評価ハーネスが共有マシンでclaudeを動かし、そのマシンのuser設定・project設定を読ませたくない場面には、--restrictedがあります(v2.1.248以降)。managed設定と--settingsだけを読み込み、コマンド実行系のツールとWebFetchは--toolsで個別に指定しない限り外します。組み込みのファイル操作ツールは、作業ディレクトリの中に閉じ込めます。bypassPermissionsは拒否され、クラウドセッションも作れません。環境変数で渡す場合はCLAUDE_CODE_RESTRICTED=1でも同じ動作になるので、評価ハーネスのようにコマンドラインを組みにくい呼び出し元でも切り替えられます。
--setting-sourcesが「どのファイルを読むか」を選ぶのに対し、--restrictedは起動モードそのものを切り替えます。--helpには、MCPサーバーも外したい場合は--strict-mcp-configを足すとあります。
関連するフラグとSDKとの違い
保存済みの設定ファイルを変えず、そのセッションだけ挙動を変える点で、--permission-modeも同じ仲間です。
Agent SDKで同じことをするなら、settingSourcesオプションが対応します。CLIから都度指定する場面と、SDKからプログラムで制御する場面の違いはAgent SDK settingSourcesにあります。設定ファイル全体の構造やキー一覧はClaude Code設定ガイドが詳しいです。
まとめ
読む範囲を減らしたいなら--setting-sources、値を変えたいなら--settingsです。どちらを使っても、managed設定と~/.claude.jsonは外れません。