Claude Code settings.jsonの場所と優先順位、効かない時の確認

Claude Codeのsettings.jsonは、~/.claude/settings.json（自分の全プロジェクト）、.claude/settings.json（チームで共有）、.claude/settings.local.json（自分だけ、このプロジェクトだけ）、組織が配布する管理設定を含む4つの設定場所に置けます。同じキーが複数の場所にあれば、管理設定 > 起動時の--settings > プロジェクトローカル > 共有プロジェクト > ユーザーの順で上にある値が使われます。ただしpermissions.allowのような配列は上書きではなく結合されます。書いたのに効かないときは、まず/statusで読み込まれたファイルを確認し、次にclaude doctorで却下された項目を見る、という順で切り分けます。

この記事では、この3点（置き場所、優先順位、効かないときの確認）を公式ドキュメントの記述に沿って説明します。permissionsのルール文法そのものや、hooks・MCPの設計は扱いません。

Claude Codeのsettings.jsonはどこに置くのか？

公式ドキュメントは、Claude Codeが読む設定ファイルを4つ挙げています。違いは「誰に効くか」です。

スコープ	ファイル	効く範囲	向いている内容
ユーザー	`~/.claude/settings.json`	このマシンの全プロジェクトの自分	テーマ、エディタモード、既定モデル、自分用の権限ルール
共有プロジェクト	`.claude/settings.json`	そのフォルダで作業する全員（gitならcommitして共有）	チームの権限、hooks、プラグイン、プロジェクトに必要な環境変数
プロジェクトローカル	`.claude/settings.local.json`	このプロジェクトの自分だけ	1プロジェクトだけの個人的な上書き、共有前の試し
管理設定	`managed-settings.json`ほか	組織が配布した全員	セキュリティポリシー、コンプライアンス要件

~/.claudeはホームディレクトリの.claudeフォルダ、頭に~が付かない.claudeはプロジェクト内の.claudeフォルダです。Windowsでは~/.claudeは%USERPROFILE%\.claudeを指します。

インストールしただけでは、設定ファイルはひとつも作られません。ユーザー設定は/configメニューでテーマなどを初めて変えたときに、プロジェクトローカル設定は権限確認で「Yes, and don’t ask again」を選んだときに、Claude Codeが自動で作ります。共有プロジェクト設定は、プロジェクトに無ければ自分で.claude/settings.jsonを作ります。

もうひとつ紛らわしいのが~/.claude.jsonです。こちらはClaude Codeが自分で書き込むファイルで、サインイン情報、MCPサーバーの設定、フォルダの信頼状態などを持っています。公式は編集不要としています。settings.jsonとは別物なので、設定を書く先として選ばないようにしてください。

settings.local.jsonはgitに入るのか

Claude Codeがgitリポジトリ内で.claude/settings.local.jsonを初めて書くとき、リポジトリがまだ無視していなければ、**/.claude/settings.local.jsonをグローバルのgit除外ファイルに追加します。そのためClaude Codeに作らせた場合はcommitに混ざりません。一方、自分の手でこのファイルを作った場合は、自分で.gitignoreに追加する必要があります。

サブディレクトリやworktreeで起動したとき

ローカル設定ファイルは、gitリポジトリのサブディレクトリで起動しても、リポジトリのルートで読み書きされます。worktreeではメインのチェックアウトのルートにあるファイルが使われます。

対して共有の.claude/settings.jsonは、セッションの作業ディレクトリから読まれます。リポジトリのルートにcommitした設定を使いたいなら、ルートでClaude Codeを起動します。サブディレクトリで起動して「チームの設定が効かない」と感じたときは、まずここを疑ってください。

同じキーを複数の場所に書いたら、どの値が使われるのか？

優先順位は、上ほど強い次の5段です。

管理設定（managed-settings.json、MDMポリシー、claude.aiコンソールのサーバー管理設定）
コマンドライン（起動時の--settingsで渡したJSON）
プロジェクトローカル（.claude/settings.local.json）
共有プロジェクト（.claude/settings.json）
ユーザー（~/.claude/settings.json）

管理設定のキーは、自分のファイルでも--settingsでも上書きできません。公式の例で言うと、チームの.claude/settings.jsonがspinnerTipsEnabledをtrueにしていて、自分はfalseにしたい場合、そのプロジェクトの.claude/settings.local.jsonに"spinnerTipsEnabled": falseを書けば、自分のセッションだけ戻せます。チームメイトの設定は変わりません。ローカルが共有より上にあるからです。

配列は上書きされず結合される

ここが誤解されやすい点です。permissions.allowのような配列のキーを複数のファイルに書くと、Claude Codeは1つを選ぶのではなくリストを結合します。各ファイルは他のファイルの項目を消さずに、項目を足すことしかできません。

つまり、チームの共有設定にあるallowの項目を、自分のローカル設定で「消す」ことはできません。モデル関連のfallbackModel、modelPicker、availableModels、modelSettingsの4つだけは独自の規則に従います。たとえばfallbackModelは順序に意味があるため、定義している中で最も優先度の高いファイルの値がまるごと使われます。

混乱しやすいのは次のケースです。権限確認で「Yes, and don’t ask again」を選ぶと、そのallowルールはローカル設定に保存されます。しかしローカルのallowは、共有プロジェクトや管理設定にあるaskルールより強くありません。そのため、承認したのに同じツールで毎回確認が出る、という状況が起こります。CLIでの承認はローカルファイルにだけ書き込まれます。

環境変数はこの5段に入らない

シェルでexportした環境変数は、この優先順位の段には含まれません。どちらが勝つかは変数とキーの組ごとに決まっています。たとえばシェルのANTHROPIC_MODELはどのファイルのmodelキーよりも優先されますが、ANTHROPIC_DEFAULT_MODELはどのファイルもmodelを設定していないときだけ使われます。

一方、settings.jsonの中に書くenvブロックは普通のキーなので、上の5段に従います。envに書いた値は、全セッションとClaude Codeが起動する子プロセスに渡され、シェルの同名の変数を上書きします。値は設定ファイルに平文で残るので、APIの認証情報にはapiKeyHelperを使うよう公式は案内しています。

settings.jsonはどう書き始めればいいのか？

設定ファイルは厳密なJSON形式です。//のコメントや末尾のカンマは構文エラーになり、次回起動時に「Settings Error」として報告されます。

公式ドキュメントが示している最初の例は、lintとtestのコマンドを確認なしで実行させ、.envの読み取りを止める~/.claude/settings.jsonです。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

$schemaの行は公開されているJSONスキーマを指し、VS CodeやCursorなどJSONスキーマに対応したエディタで補完と検証が効くようになります。ただしスキーマは最新のCLIに遅れることがあるため、最近追加されたキーで警告が出ても、設定が不正とは限りません。

チームで共有する.claude/settings.jsonの公式例からpermissions部分を抜き出すと、npm run系を許可、git pushは確認、.envとsecretsフォルダの読み取りを拒否、という形です（公式例にはhooksなども含まれます）。

{
  "permissions": {
    "allow": [
      "Bash(npm run *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

ルールは書かれたとおりのコマンドとパスに一致します。公式は、Bash(git push *)がgit -C . pushには一致しないと注意しています。また、公式の例はどれも推奨の基準値ではなく、形を見せるための例だと明記されています。ルールの書き方の詳細はClaude Codeの権限モード、何から設定すべきかはClaude Codeのおすすめ設定に分けています。

/configとの関係

/configのConfigタブに出るのは、テーマ、エディタモード、詳細出力など一部の個人設定だけで、全キーではありません。多くの項目は~/.claude/settings.jsonに保存されます。/configはターミナル版の機能で、VS Codeのチャットパネルやデスクトップアプリでは開かないため、そちらでは設定ファイルを直接編集します。

1回だけ別の設定で起動するには？

ファイルを変えずに試したいときは、起動時に--settingsでJSONを渡します。インラインのJSONでも、ファイルのパスでも構いません。公式の例は、既定モデルを変えずに1セッションだけOpusで起動するコマンドです。

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

--settingsはユーザー、プロジェクト、ローカルの各ファイルより上、管理設定より下に入ります。そのセッション限りで、どのファイルにも書き込みません。--modelのようにキー専用のフラグや、ANTHROPIC_MODELのような対応する環境変数で1セッションだけ上書きする方法もあります。CLIの他のフラグはClaude Code CLIの使い方を参照してください。

書き換えた設定はいつ反映されるのか？

Claude Codeは設定ファイルを監視していて、変更されると読み直します。permissions、hooks、apiKeyHelperを含め、ほとんどの編集は再起動なしで実行中のセッションに反映されます。

例外は、セッション開始時に一度だけ読むキーです。よく触るものではmodelと、effortLevel・modelSettingsがこれにあたります。セッションの途中で変えたいときは、ファイルを書き換えるのではなく/modelや/effortを使います。

設定が効かないときは何をどの順で確認するか？

公式が示す切り分けの起点は/statusです。

Claude Code内で/statusを実行し、StatusタブのSetting sources行を見る。User settingsやProject local settingsのように、このセッションの読み込み結果が一覧として並ぶ。書いたファイルが無ければ、置き場所や起動したディレクトリ（共有設定は作業ディレクトリから読まれる）を見直す
ファイルは読まれているのに値が効かないなら、claude doctorで却下された項目を確認する。Setting sourcesは読んだファイルを示すだけで、どのキーがどのファイル由来かまでは出ない
それでも分からなければ、上位の段（管理設定や--settings）が同じキーを設定していないか、段とは別に効く環境変数やフラグが上書きしていないかを見る

なお/statusと/configは同じダイアログの別タブで、Configタブはsettings.jsonの中身を表示するものではありません。

壊れたファイルはどう扱われるか

JSONの記述ミスやスキーマに合わない値があると、対話セッションの開始時に知らされます。ファイル全体の問題は「Settings Error」で、Claudeの助けを借りて直す、終了する、壊れた設定なしで続ける、を選ぶダイアログが出ます。不正な権限ルールや未知のhookイベント名など個別の項目だけの問題は「Settings Warning」で、その項目だけ飛ばし、残りは有効なままです。

-pでの実行ではダイアログが出ず、管理設定の文書が解析できない場合を除いて、壊れた部分を飛ばして続行します。-pで設定が無視されたと感じたら、claude doctorで何が捨てられたかを確認します。

よくある原因

公式のトラブルシューティングから、該当しやすいものを挙げます。

リポジトリのファイルでは効かないキーを書いている。 設定リファレンスのScope列がUserやManaged、Global configなどのキーは、共有の.claude/settings.jsonからは適用されません（リポジトリのファイルからでもオフにできる一部のキーを除く）。permissions.defaultModeのautoとbypassPermissionsも、プロジェクト設定やローカル設定からは効きません。ユーザー設定か管理設定に書くか、1セッションなら--permission-modeを使います
フォルダの信頼待ち。 permissions.allow、permissions.additionalDirectories、extraKnownMarketplaces、多くのenvの値は、各メンバーがフォルダを信頼するまで適用されません。denyとaskはすぐに適用されます。commitしたのにチームメイトに効かない場合はここを確認します
envに書けない変数を書いている。 プロジェクト設定とローカル設定では、CLAUDE_CONFIG_DIRやHOME、TMPDIRなど、リポジトリに決めさせるべきでない変数は、テレメトリーをオフにする一部の値を除いて捨てられます。警告はclaude --debugで確認できます
ユーザー設定ファイルに書き込めない。 別のツールが生成している、読み取り専用のコピーへのリンクになっている、といった場合、/modelなどで保存した変更はそのセッション限りで消えます

組織の管理設定が効いているかどうかも、/statusのSetting sources行で確認できます。管理設定で決まっているキーは自分では変えられないので、変更が必要なら管理者に相談します。組織としての配布方法はClaude Codeの企業向けセキュリティで扱っています。

公式ドキュメントで変わりうる点

ここまでの内容は、2026年10月18日時点のClaude Code公式ドキュメント（Settings files and precedence、Example settings files、settings reference）の記述に基づいています。設定キーの一覧や、例外扱いになるキー、バージョン条件は更新が続いている部分です。特定のキーを使うときは、そのキーの設定リファレンスの項目でScope（書ける場所）と既定値を確認してください。

hooksの書き方はClaude Code hooks、MCPサーバーの設定はClaude Code MCP、CLAUDE.mdに書く指示との使い分けはCLAUDE.mdの書き方にまとめています。

settings.jsonを自分の環境で試しながら、権限やhooksの運用まで学びたい方には、月額1,980円から参加できるNO WAVEの学習コミュニティ「AI駆動ラボ」があります。