settings.jsonの設定が効かない問題場所・優先順位・チェックリスト
Claude Codeのsettings.jsonが効かないときの原因を整理。設定ファイルの場所と優先順位、~/.claude.json との違い、/status と /doctor での確認方法を解説します。
公的機関・公式資料などの一次情報と照合して作成しています。このサイトについて
settings.jsonの設定が効かない問題とは
Claude Code の設定（settings.json）が、効いていないように見える原因は、大きく3つに分かれます。ファイルが読み込まれていない、想定と違う場所から読み込まれている、別の設定に上書きされている、です。公式のデバッグ手順にも、この3つが原因の大半であると書かれています。
この記事では、設定が効かないときの確認の順番と、見落としやすい落とし穴を整理します。設定の中身ではなく、「読み込まれているか」を確かめるための手順です。
基本（設定の場所と優先順位）
公式の説明によると、設定は管理者、ユーザー、プロジェクト、ローカルの範囲で統合されます。管理者の設定がある場合は最初に適用されます。残りは、近い範囲が広い範囲を上書きし、順番はローカル、プロジェクト、ユーザーです。コマンドラインの引数や環境変数も、さらに上書きする層になります。
| ファイル | 範囲 | 備考 |
|---|---|---|
~/.claude/settings.json |
ユーザー全体 | 権限、フック、環境変数（env）はここに書く |
プロジェクトの .claude/settings.json |
そのプロジェクト | 共有する設定 |
プロジェクトの .claude/settings.local.json |
自分だけのローカル | 上の2つより優先される |
~/.claude.json |
アプリの状態、画面の切り替え | 権限・フック・env を書く場所ではない |
特に注意したいのは、~/.claude.json と ~/.claude/settings.json が別のファイルだという点です。公式の表では、権限（permissions）、フック（hooks）、env を ~/.claude.json に書くと無視される、と明記されています。
具体例（効かない原因と直し方）
公式の「よくある原因」の表から、設定に関するものを選びました。
| 症状 | 原因 | 直し方 |
|---|---|---|
| 設定の値が無視される | settings.local.json に同じキーがある |
ローカルの設定が優先される。どちらかをそろえる |
| 全体に設定した権限やフックが無効 | ~/.claude.json に書いた |
~/.claude/settings.json に移す |
MCP サーバーが settings.json に書いても出ない |
settings.json は mcpServers を読まない |
プロジェクトの .mcp.json に書く、または claude mcp add --scope user を使う |
| フックが動かない | matcher が配列、小文字、別ファイルに定義 |
1つの文字列にする。複数を指定するときは縦線で区切る（下の例）。ツール名は大文字で始める（Bash、Edit など） |
| 値が一部しか効かない | 環境変数や引数が上書きしている | /status で、有効な設定の取得元を確認する |
フックの matcher で複数のツールを指定するときの書き方です。公式は縦線での区切りを案内しており、v2.1.191 以降はカンマ区切り（"Edit,Write"）も同じ意味になります。それより前の版では、カンマ区切りは何にも一致しません。
"matcher": "Edit|Write"
settings.jsonの設定が効かない問題の実践ステップ
claude doctor（端末）または/doctor（Claude Code 内）で、不正な設定ファイルを探す。/statusで、どの設定の取得元が有効か、管理設定が効いているかを確認する。- JSON の書き方を確認する。カンマの抜けや余分なカンマ、引用符の誤りがないかを見る。
- 書いた場所が、想定の範囲（ユーザー、プロジェクト、ローカル）か確認する。
- 同じキーが、別の範囲に書かれていないか確認する。
- 環境変数が、設定を上書きしていないか確認する。
- 切り分けのため、
claude --safe-modeで起動し、問題が消えるか確認する。
settings.jsonの設定が効かない問題の注意点
- 設定ファイルを編集すると、実行中のセッションにも、少しの時間のあとで反映されます。再起動は通常不要です。古い版（v2.1.257 より前）では、セッション開始後に作った
.claude/フォルダの編集は検出されませんでした。 - 組織の管理設定がある場合、それが優先され、ユーザー側の設定では変えられない項目があります。
/statusで確認できます。 - 設定ファイルの場所は、バージョンで変わる可能性があります。公式の
.claudeディレクトリの一覧を確認してください。 - 完全にまっさらな状態で試したいときは、環境変数
CLAUDE_CONFIG_DIRに空のフォルダを指定して起動します。
settings.jsonの設定が効かない問題でよくあるミス
- 設定を
~/.claude.jsonに書く。 - プロジェクトとユーザーの両方に同じ設定を書き、どちらが効くか混乱する。
- JSON の文法ミスで、ファイル全体が読み込まれていない。
- 環境変数で同じ設定が固定されているのに、ファイルを直し続ける。
settings.jsonの設定が効かない問題のチェックリスト
claude doctorで、設定ファイルのエラーを確認したか。/statusで、有効な設定の取得元を確認したか。- 書いたファイルが、正しいファイル（
settings.json）か確認したか。 - 範囲ごとの優先順位を理解したか。
--safe-modeで、切り分けを試したか。
settings.jsonの設定が効かない問題のFAQ（よくある質問）
Q. 設定を変えたら、再起動が必要ですか。
A. 通常は不要です。公式は、保存後に少し遅れて反映されると説明しています。反映されなければ、再起動を試してください。
Q. プロジェクトの設定をチームで共有できますか。
A. プロジェクトの .claude/settings.json は共有用の設定です。個人用は settings.local.json に書きます。
Q. どの設定が効いているか、一覧で見られますか。
A. /status で、有効な設定の取得元が分かります。権限は /permissions で、解決後のルールを確認できます。
筆者の見解（settings.jsonの設定が効かない問題）
私見では、設定が効かないときに最初に疑うべきは「中身」ではなく「どのファイルに書いたか」です。特に ~/.claude.json と ~/.claude/settings.json は名前が似ているため、取り違えは誰にでも起こりうると考えます。次に見落としやすいのが、自分用の settings.local.json や環境変数が、共有の設定を黙って上書きしているケースで、チームで同じ設定を使っているのに一人だけ挙動が違うときは、まずここを確かめる価値があります。/status で取得元を見て、それでも分からなければ --safe-mode や空の CLAUDE_CONFIG_DIR で比べる、という順で進めると、設定を手探りで書き換えるより短時間で原因に届くと考えます。
settings.jsonの設定が効かない問題の関連項目
- claude doctor と /doctor の使い方
- MCPサーバーが読み込まれないときの対処
- 許可確認（パーミッション）の設定
- Claude Codeのアップデート方法
- Claude Codeが重い・遅いときの対処
出典（一次情報）
本記事は一般的な情報の提供を目的としています。Claude Code の料金・利用上限・機能・エラーメッセージ・コマンドは頻繁に更新されるため、最新の内容は Anthropic の公式ドキュメントとお使いのバージョンで必ずご確認ください。契約・請求・セキュリティに関する判断は、公式サポートや社内の担当部門にご相談ください。「筆者の見解」は一つの考え方です。