Claude Code の設定：settings.json の場所・優先順位・主要キーと確認手順

Claude Code の設定は settings.json に書くが、置き場所はユーザー・プロジェクト・ローカル・managed の4系統に分かれ、同じキーが複数にあれば優先順位で採用値が決まる。各ファイルの場所と優先順位、配列のマージ、主要キー、設定が効かないときの確認手順を公式ドキュメントに沿って整理する。

設定ファイルは4つのスコープに分かれる

Claude Code が読む設定ファイルは4種類で、それぞれに「誰に効くか」というスコープがある。以下は 2026 年 9 月時点の公式ドキュメント（Settings files and precedence）に基づく。

`~/.claude` は Windows では `%USERPROFILE%\.claude` を指す。インストールしただけではどの設定ファイルも作られず、ユーザー設定は `/config` でテーマなどを変えたとき、ローカル設定は権限プロンプトで「Yes, and don't ask again」を選んだときに Claude Code 自身が初めて書き出す。

managed のファイル版は OS ごとのシステムディレクトリに置かれる。macOS は `/Library/Application Support/ClaudeCode/`、Linux と WSL は `/etc/claude-code/`、Windows は `C:\Program Files\ClaudeCode\` で、旧来の `C:\ProgramData\ClaudeCode\` は読まれない。ほかに MDM・OS ポリシーや、claude.ai 管理コンソールからの server-managed settings でも届く。

紛らわしいのが `~/.claude.json` という5つ目のファイルだ。サインイン情報や MCP サーバー構成、プロジェクトごとの信頼状態、`/config` が書くグローバル設定キーを持つファイルで、公式は `permissions`・`hooks`・`env` をここに書いても効かないとしている。

優先順位は managed が頂点で、ユーザー設定が最下位

同じキーが複数の場所にあるとき、Claude Code はそのキーを設定している階層のうち、いちばん上の階層の値を使う。優先度の高い順に次の5段だ。

1. Managed settings（組織の配布） 2. コマンドライン引数（`claude --settings` など、そのセッション限り） 3. Project local（`.claude/settings.local.json`） 4. Shared project（`.claude/settings.json`） 5. User（`~/.claude/settings.json`）

ローカルが共有プロジェクトより上にあるため、チームが決めた値を自分だけ変えたいならローカルファイルに同じキーを書けばよい（配列のキーは次節のとおり結合される）。公式の例では、ユーザー設定で `spinnerTipsEnabled` を `false` にしても、チームの `.claude/settings.json` が `true` ならそのプロジェクトではヒントが出る。ローカル設定に次の内容を書けば、自分のセッションだけ元に戻る。

{
  "spinnerTipsEnabled": false
}

一方、managed に対してはこの逃げ道が効かない。公式は **managed のキーは `--settings` で渡しても上書きできない** としており、`--model` のようなフラグも組織が許可したモデルの中からしか選べない。

では環境変数はどこに入るのか。公式は「環境変数はこの階層の一段ではない」とし、同じ挙動を変える変数とキーの組ごとに優先関係が決まると説明する。たとえばシェルで export した `ANTHROPIC_MODEL` はどのファイルの `model` よりも優先されるが、`ANTHROPIC_DEFAULT_MODEL` はどのファイルも `model` を設定していないときにしか使われない。設定ファイル内の `env` ブロックは普通のキーとして5段の順位に従い、同じ変数をシェルでも export していれば、多くのセッションではファイル側の値が使われる。

例外もある。セッションを制限する方向の値に限り、managed が逆の値を設定していても下位の値を採用するキーが少数ある。`disableClaudeAiConnectors` の `true` がその一例だ。

配列のキーは上書きではなくマージされる

`permissions.allow` のような配列のキーを複数のファイルに書くと、Claude Code はどれか1つを選ばずにリストを結合する。各ファイルはほかのファイルのエントリを消さずに追加だけできる、というのが公式の説明だ。`hooks` もファイル間でマージされ、managed 由来の hooks はほかのファイルから取り除けない。

ただし `fallbackModel`・`modelPicker`・`availableModels`・`modelSettings` の4キーは、モデルのリストやモデル単位のエントリを持つため、それぞれ独自の規則で解決される。モデル関連の設定を複数ファイルに書く場合は、設定リファレンスの各項目を確認したい。

`enabledPlugins` も直感と食い違いやすい。プロジェクト設定がユーザー設定より上位なので、`~/.claude/settings.json` で `false` にしても、プロジェクトが有効にしたプラグインは止まらない。自分のマシンだけで外すなら `.claude/settings.local.json` に `false` を書く、と公式は案内している。

よく使う主要キー

設定リファレンス（All settings）から、個人・チームの設定で使いどころのあるキーを抜き出した。既定値はリファレンスの記載どおりで、「未設定」は unset を指す。

`cleanupPeriodDays` に `0` を入れると検証エラーになる。`attribution` は v2.0.62 で `includeCoAuthoredBy` を置き換えたキーだ。`language` は値を検証せずそのまま Claude に渡すため、綴りを誤ってもエラーにならない。

書くときにつまずきやすいのは JSON の書式である。設定ファイルは厳格な JSON として扱われ、コメントや末尾カンマは構文エラーとなり、次回起動時に Settings Error として報告される。

// NG: コメントと末尾カンマで Settings Error になる
{
  "language": "japanese",
  "cleanupPeriodDays": 90,
}

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "language": "japanese",
  "cleanupPeriodDays": 90
}

2つ目が OK 例だ。`$schema` を書くと、JSON スキーマ対応のエディタで補完と入力時の検証が効く。ただしスキーマは最新 CLI に遅れることがあり、新しいキーで警告が出ても設定が不正とは限らないと公式は注記している。

反映のタイミングと一時的な上書き

Claude Code は設定ファイルを監視しており、`permissions` や `hooks` の編集は再起動なしで実行中のセッションに反映される。例外は起動時に一度だけ読むキーで、`model` や `effortLevel` を書き換えても実行中のセッションには届かない。途中で変えるなら `/model` や `/effort` を使う。

続きを読むには

無料でアカウント作成

CCHub は Claude Code 開発者のための日本語コミュニティです。