Claude Code settings

一行要約

設定は managed → CLI 引数 → local → project → user の5層で解決され、permission ルールなどの配列はレイヤ間でマージ、スカラーは上位が勝つ。そしてほとんどの設定は再起動なしに反映される（model と outputStyle は例外）。

要点

スコープと優先順位

スコープ	場所	優先度
Managed	サーバ配信、plist/レジストリ、`managed-settings.json`	1（最高）
Command line	CLI フラグ	2
Local	`.claude/settings.local.json`	3
Project	`.claude/settings.json`	4
User	`~/.claude/settings.json`	5（最低）

上位スコープが下位を上書きする。 managed settings は（下の例外を除いて）上書きできない。--settings でも越えられない
managed の model はセッションの開始モデルを決めるだけで、/model で変えられる。 選べるモデルを縛るのは availableModels（/model・--model・自分の model キーのすべてを制約する）
permission ルールはスコープ間でマージされる。 それ以外の設定は優先順位に従う
環境変数はこの5層に入らない。 どちらが勝つかはキーと変数の組ごとに決まっている（ANTHROPIC_MODEL はどのファイルの model にも勝つが、ANTHROPIC_DEFAULT_MODEL はどのファイルも model を書いていないときだけ効く）
project の .claude/settings.json の allow ルールは workspace trust を要求する。 .claude/settings.local.json（自分のファイル）は要求しない
managed settings の不正なエントリは strip され、正当なポリシーは有効なまま（v2.1.169 以降）
Claude Code は **/.claude/settings.local.json をグローバルの git excludes に自動追加する

マージされない4つのキー

リストのキーは普通スコープ間でマージされるが、モデル関係の4つは違う。

キー	扱い
`fallbackModel`	順序に意味がある鎖なので、定義している最上位のファイルの値を丸ごと採る
`modelPicker`	行の並び＋置換フラグを持つので2つの出所からは決してマージしない。managed / `--settings` / user のうち最上位を採り、project と local は無視する（v2.1.242 以降）
`availableModels`	managed が定義していればそれをそのまま適用し、user / project / local の追加は無視する。managed 以外のスコープどうしは通常どおりマージ
`modelSettings`	モデル1つずつ、`effortLevel` と一緒に解決する

反映タイミング

ほとんどの設定はライブでリロードされる（permissions、hooks、apiKeyHelper などの資格情報ヘルパ）。セッション開始時に一度しか読まれないもの:

設定	代替手段
`model`	`/model` を使う（モデルごとに prompt cache が別なので、切り替え後の最初のリクエストは会話全体を読み直す）
`effortLevel` / `modelSettings`	`/effort` を使う

設定ファイルの変更ごとに ConfigChange hook が走る。 ただし MDM や claude.ai コンソールから届く managed settings は保存時ではなくスケジュールで届き、hook も走らない。

壊れた設定ファイル

表示	何が起きるか
Settings Error	user / project / local の JSON が壊れているか、値が schema に落ちた。対話セッションの冒頭でダイアログが出る
Settings Warning	個別のエントリだけが落ちた（不正な permission ルール、知らない hook イベント名など）。その値だけ飛ばして残りは効く
Configuration error	`~/.claude.json` が壊れた。`~/.claude/backups/` に退避され、直近5つの `.claude.json.backup.<timestamp>` から戻せる

-p ではダイアログが出ない。 壊れたファイルや値を黙って飛ばして続くので、設定が効かなかった -p の後は claude doctor で何が落ちたかを見る。

よく使う設定

キー	意味
`permissions.allow` / `permissions.deny`	許可 / 拒否のルール
`model`	主モデル
`env`	全セッションとサブプロセスに適用される環境変数
`hooks`	イベントで発火するハンドラ
`statusLine`	カスタムステータス行（hook が必要。起動時に一度だけ読まれる）
`outputStyle`	system prompt の一部。起動時に読まれる
`autoCompactWindow`	自動 compaction までの context サイズ（100k〜1M トークン）
`autoCompactEnabled`	上限接近時の自動 compaction（既定 `true`）
`cleanupPeriodDays`	N 日より古いセッションファイルを削除（既定 30）
`disableAllHooks`	全 hook とカスタムステータス行を無効化
`enabledPlugins`	managed settings で plugin を強制有効化

managed settings を下から上書きできる例外

セッションを「締める」方向の値は、本来 managed を越えられないスコープからでも通る。

キー	通る値
`disableClaudeAiConnectors` / `isolatePeerMachines`	どのスコープからでも `true`
`enableArtifact`	どのスコープからでも `false`（`disableArtifact: true` も）。一度切ると何をしても戻らない（v2.1.242 以降）
`remoteControlAtStartup`	`.claude/settings.json` か `.claude/settings.local.json` からの `false`（`true` は無視）
`crossSessionInbound`	project / local からのより厳しい値（`accept` < `hold` < `refuse`）
`useAutoModeDuringPlan` / `syncClaudeAiSkills` / `syncClaudeAiPlugins`	managed / `--settings` / user / local からの `false`（`.claude/settings.json` の `false` は無視）
`maxEffortLevel`	どのスコープからでも、より低い上限（最も低いものが効く。v2.1.267 以降）

共有ファイルに書いても届かないもの

リポジトリのファイルでは無視されるキーがある。 設定索引の Scope 欄が User, local, or managed / User or managed / Managed / Global config のものがそれ（Global config は ~/.claude.json からのみ）
信頼を待つキーがある。 permissions.allow、permissions.additionalDirectories、extraKnownMarketplaces、ほとんどの env は、各自がそのフォルダを信頼するまで効かない。deny と ask はすぐ効く
permissions.defaultMode の auto と bypassPermissions は project / local からは効かない（user か managed に書くか、--permission-mode を渡す。v2.1.257 より前は bypassPermissions がどのファイルからでも効いた）
「次回から確認しない」で保存される allow ルールは local に入る。 local の allow は project や managed の ask ルールに勝てないので、同じツールでまた聞かれる

cloud セッションに届く設定

	届くか
`.claude/settings.json`（共有）	届く（クローンの一部だから）。ただし複数リポジトリのセッションでは `enabledPlugins` と `extraKnownMarketplaces` のキーだけが読まれ、permission・hook・`env` は読まれない（しかもその2つが宣言する plugin と marketplace も、cloud セッションでは読み込まれない）
`~/.claude/settings.json` / `.claude/settings.local.json`	届かない（どちらも手元に残る）
managed settings	端末の `managed-settings.json` や MDM プロファイルは届かない。組織の server-managed settings は届く（どのクラウドセッションが受け取るかは model-config の surface coverage の表）
`/config`	値を変えず、claude.ai の設定画面を開く。変えるなら環境変数か、リポジトリの `.claude/settings.json` にコミットする

設定の操作

/config              # タブ付きの設定 UI
/config key=value    # 単一項目の変更（v2.1.181+）
/status              # 有効な設定がロードされているか確認
/doctor              # 解決後の設定と、strip されたエントリを見る

そのまま使える具体例

lint とテストのコマンドを確認なしで走らせ、.env を読ませない ~/.claude/settings.json の例（$schema を書いておくと、JSON schema に対応したエディタで補完と検証が効く。ただし schema は最新の CLI より遅れることがあるので、最近ドキュメントに載ったキーへの警告は設定が壊れている意味ではない）:

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

設定ファイルは厳密な JSON で、// のコメントや末尾のカンマは構文エラーになる。保存したら /status で読み込まれたかを確かめる。env のテレメトリのエクスポート変数は、project / local の設定からは一部の「切る」値を除いて効かない。

設定が効かないときの調べ方:

/status     # ロードされているか
/doctor     # どのスコープの値が勝っているか、strip されたエントリはあるか

原典で言及されている関連文書

permissions — permission ルールの構文と、スコープをまたぐ deny の優先
permission-modes — defaultMode
hooks-guide / hooks — hooks キー
memory — claudeMdExcludes、autoMemoryEnabled、autoMemoryDirectory
context-window — autoCompactWindow の受け付ける値と上書き順
costs — 環境変数によるコスト制御
large-codebases — worktree.sparsePaths、additionalDirectories
env-vars — 環境変数の完全な一覧
cli-reference — CLI フラグ

ai-docs

エクスプローラー