Claude Codeのsettings.jsonが読み込まれない・反映されない原因を、公式ドキュメントとGitHub Issueの実例で整理した
settings.jsonは構文エラーが1つあるだけでファイル全体が丸ごとスキップされる。過去に報告された7件のGitHub Issueと公式ドキュメントの現在の挙動を照らし合わせ、症状別の原因切り分けと確認手順をまとめた。
エンジニアのゆとです。
settings.jsonを編集したのに/permissionsや/hooksで何も表示されない。エラーも出ない。ファイル自体は間違いなく保存されている——settings.jsonが「読み込まれない」ときの一番厄介なところは、大体の場合エラーメッセージが一切出ないことだと思う。原因を先に言うと、~/.claude/settings.json・.claude/settings.json・.claude/settings.local.jsonはJSONとして厳密にバリデーションされていて、末尾カンマ1つ、権限パターンの記法ミス1つでファイル全体が丸ごとスキップされる仕様になっている。
この挙動自体は今のところ公式ドキュメントに明記されている。ただ、そこに至るまでの間にanthropics/claude-codeのIssueには「設定は完全に正しいはずなのに反映されない」という報告が2025年7月から2026年4月まで断続的に上がっていて、原因もバラバラだった。この記事では、公式ドキュメントに書かれている現在の挙動と、過去に報告された具体的な不具合パターンを突き合わせて、症状別に整理する。
まず結論 — 症状別の原因早見表
| 症状 | 原因 | 状態 |
|---|---|---|
/permissionsや/hooksで設定が1件も表示されない | JSON構文エラー（末尾カンマ・カンマ抜け）でファイル全体が拒否される | 仕様どおり（現在は検知できる） |
| 権限ルールを1行追加したら他の設定まで丸ごと効かなくなった | 権限パターンの記法ミス（:抜けなど）で厳密バリデーションに落ちる | 仕様どおり |
| Bashコマンドを許可しただけなのに設定全体が壊れる | Claude Code自身が不正な形式のentryを書き込む自傷バグ | 既知のバグ報告（Issue #16301） |
JSONは正しいはずなのに/doctorが「壊れている」と言う | UTF-8 BOM付きで保存されている | 既知のバグ報告（Issue #9906） |
| Windows/VS Codeで起動直後にJSON parse errorが出続ける | 特定バージョン（2.0.62〜2.0.73）のパーサ不具合 | バージョン依存（アップデートで解消） |
| ファイルは読み込まれてるのに特定の設定だけ効かない | 上位スコープに同じキーがあって上書きされている（無視ではない） | 仕様どおり（優先順位表で確認） |
| 設定を書き換えたのにセッション中は反映されない | model・outputStyleなど「セッション開始時のみ読み込み」の項目 | 仕様どおり（再起動か/clearが必要） |
大前提 — Managed以外のスコープは「厳格」。寛容なのはManagedだけ
公式ドキュメントには、スコープによってバリデーションの厳しさが違うとはっきり書かれている。
Managed 設定は寛容に解析されます。managed 構成にスキーマ検証に失敗するエントリが含まれている場合、Claude Code はそのエントリを削除し、警告を記録し、残りのすべての有効なポリシーを強制します。単一のタイプミスが組織のポリシーの残りを無効にすることはできません。
この寛容さは managed 設定にのみ適用されます。ユーザー、プロジェクト、およびローカル設定ファイルは厳密なままです：検証に失敗するファイルは全体として拒否され、報告されます。
つまり、組織管理者が配るmanaged-settings.jsonは多少タイプミスがあっても該当エントリだけ落として残りは生かしてくれるのに、個人が触る~/.claude/settings.json・プロジェクトの.claude/settings.json・.claude/settings.local.jsonの3つは容赦がない。1箇所でも構文が壊れていれば、そのファイルに書いた設定は0件になる。権限ルールを10個書いていても、末尾カンマが1つ紛れ込んだ瞬間に10個とも消える。「一部だけ無視される」のではなく「ファイル単位で全滅する」という設計であることを、まず前提として押さえておく必要がある。
症状別に原因を切り分ける
パターン1: 構文エラー（末尾カンマ・カンマ抜け）でファイル全体が消える
最も報告数が多いのがこれ。Issue #2835では、リストの最後の要素の後ろにカンマを付けたまま保存したところ、.claude/settings.jsonが丸ごと無視され、まるでプロジェクトを初めてセットアップしたかのような挙動になったと報告されている。--debugフラグを付けても警告は出なかったという。
Issue #1506ではもう少し症状が悪く、カンマ抜けのようなJSON構文エラーがあると起動時にエラーが出るものの、その後は何を入力しても「Interaction interrupted by User」とだけ表示されて何も起きなくなる、という報告になっている。
Issue #24823はBedrock経由でClaude Codeを使っているユーザーからの要望で、認証設定が~/.claude/settings.jsonに書かれているケースで構文エラーがあると、エラーメッセージの代わりに「Anthropicアカウントにログインしてください」という誤解を招く画面が出てしまう、という内容だった。設定ミスなのに認証エラーに見えるぶん、原因にたどり着くまで余計に時間がかかる。
パターン2: 権限パターンの記法ミスで、その1行以外も道連れになる
Issue #12468は、JSONとしては壊れていないのに設定全体が拒否される珍しいパターン。"Bash(mkdir*)"のように、本来"Bash(mkdir:*)"と書くべきところの:を落として保存すると、権限パターンのバリデーションに失敗して、そのエントリだけでなくsettings.json全体が静かに拒否される。報告時点では、Claude Codeが前回キャッシュした設定を使い続けるか、設定なしで動くかのどちらかになり、失敗したことを示す表示は一切なかったという。
構文的には正しいJSONでもこのパターンで落ちることがあるので、「JSONバリデーターに通したから大丈夫」と判断するのは早い。権限パターンの書式（ツール名の後は:区切り）まで含めて確認する必要がある。
パターン3: Claude Code自身が壊れたentryを書き込む自傷バグ
Issue #16301は、ユーザーの入力ミスではなくClaude Code側の書き込み処理が原因だったパターン。ターミナルでBashコマンドの実行を許可すると、その許可ルールが.claude/settings.local.jsonに自動保存される仕組みになっているが、${device%%:*}のようなシェルのパラメータ展開を含むコマンドを許可すると、展開後の断片がそのまま壊れた形式のエントリとして書き込まれてしまう。結果、次回起動時に「Files with errors are skipped entirely」というエラーとともに設定ファイル全体がスキップされる。
自分で編集していないのに設定が壊れるという意味で一番気づきにくいパターンだと思う。心当たりがないのに急に権限設定が全部効かなくなったら、.claude/settings.local.jsonをエディタで開いて、末尾に見覚えのない断片的なエントリが増えていないか確認するのが早い。
パターン4: UTF-8 BOM付きで保存すると「壊れている」扱いになる
Issue #9906は、テキストエディタやツールがファイル保存時に自動でBOM（Byte Order Mark）を付与してしまうケース。ファイルの中身自体は完全に正しいJSONなのに、先頭にBOMが付いているせいで/doctorが「壊れたJSON」と判定してしまう。BOMは見た目には表示されないので、ファイルを目で見比べても違いが分からず、原因の特定に時間がかかりやすい。
Windowsのメモ帳や一部のエディタ設定は保存時にBOMを付与することがある。VSCodeであればエディタ右下のエンコーディング表示から「UTF-8 with BOM」になっていないか確認できる。
パターン5: Windows特有のJSON parse error（バージョン依存）
Issue #14442は、Windows 11のVS Code拡張で、バージョン2.0.62〜2.0.73の範囲において、OAuth認証は通るのにClaudeプロセスの起動時に一貫してJSON parse errorが発生するという報告。設定ファイルの中身に問題がなくても、パーサ側のバージョン依存バグで落ちるケースがあったことになる。心当たりのある構文ミスがどうしても見つからない場合は、症状の出ているバージョンをまず疑い、claude updateで最新化してから再現するかを確認したほうが早い。
今は「気づける」ようになっている——現在の公式仕様
上に挙げたIssueの多くは、「設定が拒否されたことに気づく手段が一切ない」という点が共通の不満だった。この点については、現在の公式ドキュメントでは改善後の挙動が明記されている。
インタラクティブセッションは起動時に無効なエントリをリストするダイアログを表示します。
-pを使用したヘッドレス実行はstderrにサマリーを出力します。claude doctorは各無効なエントリをそのソースとフィールドとともにリストします。
つまり今は、対話セッションなら起動時のダイアログ、-pのヘッドレス実行ならstderr出力、どちらでもなければclaude doctor（対話モード内では/doctor）を叩けば、少なくとも「無効なエントリがある」こと自体は検知できる。ただし検知できるのは「エントリが無効だった」という事実までで、Managed以外のスコープでは依然としてファイル単位で全滅する挙動そのものは変わっていない。「気づけるようになった」のであって「部分的に許容されるようになった」わけではない、という区別は持っておいたほうがいい。
Issue #44912は2026年4月に、VS Code版のドキュメントにこの「parse失敗時に権限ルールが丸ごと無効化される」という挙動そのものの説明が抜けている、というドキュメント不備の指摘として報告されている。挙動自体は実装されていても、ドキュメント側の追従が遅れることがある領域だと分かる。
実際に確認する手順
原因の見当がついたら、以下の順番で機械的に潰していくのが早い。
1. claude doctorでまず診断する
claude doctor対話セッション中なら/doctorでも同じ診断が走る。無効なエントリがあれば、ソースファイルとフィールド名付きで表示される。ここで何も出ないのに設定が反映されていないなら、原因は構文エラーではなく後述のスコープ上書きを疑う。
2. jqでJSON構文だけを先に確認する
jq . ~/.claude/settings.json
jq . .claude/settings.json
jq . .claude/settings.local.json構文エラーがあればjqが該当行を指摘して失敗する。claude doctorより軽くて速いので、まずこちらで機械的にふるいにかけてからclaude doctorに進むほうが効率がいい。jqが入っていない場合はbrew install jq（macOS）かapt-get install jq（Debian/Ubuntu）。
3. BOMの有無を確認する
head -c 3 ~/.claude/settings.json | xxd先頭3バイトがef bb bfならUTF-8 BOM付き。これが原因なら、BOMなしUTF-8で保存し直すか、以下のようにBOMだけ取り除く。
sed -i '1s/^\xef\xbb\xbf//' ~/.claude/settings.json4. 権限パターンの記法を目視でもう一度見る
jqはJSON構文としては正しいと判定するが、"Bash(mkdir*)"のような権限パターンの記法ミスまでは検出してくれない。ツール名の後ろが:区切りになっているか（Bash(mkdir:*)のように）を、allow/deny/askの全エントリで見直す。
「無視されてる」のではなく「上書きされてる」ケースとの切り分け
構文エラーもBOMもなく、claude doctorも何も報告してこないのに、特定の設定だけ効かないように見える場合は、そもそも設定ファイルの問題ではなく、上位スコープに同じキーが存在していて上書きされている可能性を疑ったほうがいい。公式ドキュメントに書かれている優先順位は次のとおり。
| 優先順位 | スコープ | 備考 |
|---|---|---|
| 1（最高） | Managed | 何によってもオーバーライドされない |
| 2 | コマンドライン引数 | 一時的なセッションオーバーライド |
| 3 | Local（settings.local.json） | プロジェクトとユーザー設定を上書き |
| 4 | Project（.claude/settings.json） | ユーザー設定を上書き |
| 5（最低） | User（~/.claude/settings.json） | 他に指定がない場合のみ適用 |
「プロジェクトのsettings.jsonに書いたはずの設定が効かない」という相談の多くは、.claude/settings.local.json（gitignore対象で見落としやすい）や組織のManaged設定に同じキーが存在していて、そちらが優先されているだけ、というオチだったりする。settings.local.jsonの中身を一度確認するのが早い。
もう1つ見落としやすいのが、編集してもセッション中に反映されない項目があるという点。
ほとんどのキーへの編集は再起動なしで実行中のセッションに適用されます。これには
permissions、hooks、およびapiKeyHelperなどの認証情報ヘルパーが含まれます。いくつかのキーはセッション開始時に1回読み込まれ、次の再起動時に適用されます：
model（セッション中に切り替えるには/modelを使用）、outputStyle（/clearまたは再起動時に再構築）
permissionsやhooksはファイルを保存すればほぼ即座に反映されるが、modelやoutputStyleはセッション開始時に1回しか読まれない。設定ファイルをいくら書き換えても、そのセッション内では反映されず、/clearか再起動が必要になる。これは不具合ではなく仕様なので、切り分けの最初の段階で候補から外しておくと無駄な調査が減る。
再発防止 — 壊れる前に検出する
構文エラーは一度直しても、手作業で編集を続ける限りまた発生する。以下のどれかを仕組みとして入れておくと再発頻度が下がる。
- VSCode/Cursorで
$schemaを先頭に置く:"$schema": "https://json.schemastore.org/claude-code-settings.json"を追加しておけば、エディタ側がリアルタイムで構文とキー名を検証してくれる。保存前に赤い波線で気づける。 - 保存前に
jqを通すエイリアスを作る:alias jsoncheck='jq . ~/.claude/settings.json && jq . .claude/settings.json'のように登録しておけば、編集直後に1コマンドで確認できる。 .claude/settings.jsonをコミットする前にpre-commit hookで検証する: チーム共有のプロジェクト設定は、CIやpre-commitでjq empty .claude/settings.jsonを走らせておけば、構文エラーのあるファイルがそもそもリポジトリに入らない。- BOM付きで保存されるエディタ設定を見直す: VSCodeなら
"files.encoding": "utf8"を明示しておけば、BOM付きで保存される事故を防げる。
FAQ
エラーは何も出ないのに設定が効いていない気がする。何から確認すればいい?
順番は、claude doctor（または/doctor）→ jqでのJSON構文チェック → 権限パターンの:区切り目視確認 → スコープの優先順位表、の4点セット。ここまでで大半の原因が特定できる。
.claude/settings.local.jsonを触っていないのに急に設定が壊れた
Bashコマンドの許可操作でClaude Code自身がこのファイルに自動書き込みしている。シェルのパラメータ展開を含むコマンドを許可した直後から壊れたなら、Issue #16301のパターンを疑い、該当ファイルの末尾に不審なエントリがないか確認する。
JSONバリデーターでは正常と出るのに/doctorが「壊れている」と言う
構文自体は正しくても、UTF-8 BOMが付いていると壊れている扱いになる。head -c 3 ファイル名 | xxdで先頭バイトを確認し、ef bb bfならBOM付き。
プロジェクトのsettings.jsonに書いた設定がどうしても反映されない
構文エラーがない場合は、.claude/settings.local.jsonや組織のManaged設定に同じキーがあって上書きされていないかを確認する。優先順位はLocal > Project > Userの順。
settings.jsonは「間違えたら教えてくれる」設計ではなく「間違えたら黙って消える」設計に近い。今はclaude doctorという診断コマンドがある分マシになったとはいえ、結局のところ壊れてから気づくより、$schemaとpre-commit hookで壊れる前に止める方が確実だと思う。
