Claude Code settings.json 逆引き：3層の優先順位・permissions・hooks・env

Claude Code の settings.json で起きるトラブルの大半は「書き方」ではなく「どのファイルに書いたか」です。同じキーが5つの層で解決され、リストは結合、単一値は上位が勝ち、しかも ~/.claude.json という似た名前の別ファイルが存在します。この構造を先に押さえると、permissions hooks env のどれを触るときも迷いません。

この記事は公式 Settings / Settings reference / Permissions / Hooks guide / Debug your configuration の記述を根拠に、用途から逆引きできる形で主要キーを整理します。手元の Claude Code 2.1.261 で意図的に壊した設定ファイルに claude doctor を当てた出力も載せました。権限モードや sandbox の考え方は権限プロンプトを減らす記事、hooks と MCP を入れる前の安全設計はhooks導入前に決める安全境界に分けています。

3層＋2：ファイルの場所と優先順位

公式 settings ページの表です。個人開発で日常的に触るのは上の3つです。

.claude/settings.local.json は Claude Code が「Yes, and don’t ask again」の承認を保存する先でもあります。Claude Code が最初に書くときにグローバルの git excludes へ **/.claude/settings.local.json を追加するので、通常はコミットされません。手で作った場合は自分で .gitignore に入れる必要があります。

3つの注意点があります。

• リストは結合される。 permissions.allow を複数ファイルに書くと全部が有効になります。ただし fallbackModel（順序に意味がある）と availableModels（managed があればそれのみ）は例外です。
• 環境変数は層ではない。 ANTHROPIC_MODEL はどのファイルの model より優先、ANTHROPIC_DEFAULT_MODEL はどのファイルにも model が無いときだけ、というふうにキーごとに決まっています。settings 内の env ブロックは普通のキーとして上の層に従います。
• permissions.defaultMode の auto と bypassPermissions は project / local からは効かない。 v2.1.257 以降の仕様で、user か managed に書くか --permission-mode で渡します。

主要キー逆引き

permissions

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"],
    "additionalDirectories": ["../shared-lib"]
  }
}

ルールの書式は Tool または Tool(specifier) です。公式 permissions ページの要点を絞ると次の4つになります。

Bash は * の位置がすべて。 Bash(npm run *) は npm run build も npm run test --watch も裸の npm run も許可し、npm install は許可しません。末尾の *（スペース付き）は裸のコマンドにもマッチしますが、Bash(ls*)（スペースなし）は lsof にもマッチしてしまいます。Bash(git * main) のようにサブコマンドの前に * を置くと git -c core.fsmonitor=<script> diff main まで通るため、起動時に警告が出ます。:* 接尾辞（Bash(ls:*)）は末尾ワイルドカードの別表記で、末尾以外の : は文字として扱われます。

Read / Edit のパスは4形式。 //path は絶対パス、~/path はホーム、/path は設定ファイルの置き場に対する相対（project なら作業ディレクトリ、user なら ~/.claude/）、path / ./path はカレント相対です。user 設定に Read(/secrets/**) と書くと ~/.claude/secrets/** を指してしまうので、全プロジェクトに効かせたい deny は // か ~/ で書きます。Windows は C:\Users\alice が /c/Users/alice に正規化されるので、ドライブ全体なら //c/**/.env、全ドライブなら //**/.env です。

Read の deny は Edit / Write も塞ぐ（v2.1.208+）。 逆に Write(docs/**) や Glob(docs/**) のようなルールは受理されるが参照されず、起動時に警告が出ます。ファイル系は Read(...) と Edit(...) の2種類で書きます。

MCP は mcp__<server>__<tool>。 mcp__puppeteer でサーバー全体、mcp__puppeteer__* でも同じ、mcp__puppeteer__puppeteer_navigate で1ツール。allow のワイルドカードはサーバー名の後にしか置けません。WebFetch(domain:*.example.com) はサブドメイン全部を指しますが example.com 自体は含みません。

hooks

構造は「イベント名 → matcher（文字列）→ hooks 配列」の3段です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

公式 debug-your-config の「効かない」原因リストは具体的です。matcher を配列で書くとスキーマエラーでその設定ファイルの hooks が丸ごと捨てられる、"bash" と小文字にすると大文字小文字を区別するので一致しない、独立した hooks ファイルは読まれず settings.json の "hooks" キー配下にしか書けない、, 区切りは v2.1.191 以降でのみ | と同じ扱い。フック一覧は /hooks、発火の様子は claude --debug で追えます。終了コード 2 が「ブロック」で、stderr がモデルへのフィードバックになります。全部止めたいときは "disableAllHooks": true です。

env

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe",
    "USE_BUILTIN_RIPGREP": "0",
    "DISABLE_AUTOUPDATER": "1"
  }
}

値は文字列で書きます。シェルと settings の両方に同じ変数があれば settings 側が勝ちます（公式 env-vars ページ）。プロジェクトが要る環境変数をチームで揃えたいときは .claude/settings.json の env が向いています。MCP サーバー個別の環境変数は .mcp.json の各サーバー env に書くもので、ここではありません。

model / effortLevel / modelSettings

{
  "model": "claude-sonnet-5",
  "effortLevel": "high",
  "modelSettings": { "claude-opus-5": { "effort": "xhigh" } }
}

model はセッション開始時に一度だけ読まれるので、実行中の切り替えは /model です。/model で選んだ値は既定として保存され、s を押すと保存せずに切り替えます。--model と --effort はそのセッション限り。modelSettings のモデル別 effort は effortLevel より優先されます。

statusLine

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

スクリプトは stdin で JSON（model.display_name、context_window.used_percentage、cwd など）を受け取り、出力した文字列がそのまま表示されます。/statusline に希望を伝えると自動生成もできます。Windows は Git Bash 経由で動くため command のパスはスラッシュで書き、PowerShell スクリプトなら powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1 の形にします。

そのほか触る頻度が高いキー

• autoUpdatesChannel: "latest"（既定）/ "stable"。minimumVersion で下限を固定。詳細はアップデートが反映されない時の記事
• cleanupPeriodDays: セッション記録の保持日数。既定 30
• includeCoAuthoredBy / attribution: コミットや PR に付く署名の制御
• enableAllProjectMcpServers / enabledMcpjsonServers / disabledMcpjsonServers: .mcp.json のサーバー承認
• autoContinueAtUsageLimit: 使用上限で待って自動再開するか。false は /config autoContinueAtUsageLimit=false でも設定可
• alwaysThinkingEnabled / language / outputStyle / spinnerTipsEnabled: 表示と応答の好み
• apiKeyHelper / forceLoginMethod / forceLoginOrgUUID: 認証。個人ではまず使わない
• sandbox: OS レベルのファイル・ネットワーク制限。Windows ネイティブでは非対応

手元の ~/.claude/settings.json に実際に入っているキーは permissions model enabledPlugins extraKnownMarketplaces feedbackSurveyRate effortLevel autoUpdatesChannel tui skipDangerousModePermissionPrompt agentPushNotifEnabled skipAutoPermissionPrompt の11個でした。/config や /model が書き込んだものが混ざっているのが分かります。

用途別コピペ例

権限プロンプトを減らす（安全な範囲だけ）

.claude/settings.json に置いてチームで共有する想定です。設定の考え方は権限プロンプトを減らす記事に譲り、ここでは公式の書式に沿った最小形だけ示します。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

$schema を付けると VS Code などでキー名の補完と検証が効きます（公式は「スキーマは最新 CLI より遅れることがあるので、最近追加されたキーの警告は誤りとは限らない」と注記）。/permissions で対話的に追加したルールがどのファイルに保存されたかも同じ画面で確認できます。既存のセッション記録から allowlist の候補を自動抽出したいなら /fewer-permission-prompts が用意されています。

hooks で Prettier を走らせる

公式 hooks-guide の例そのままです。jq が必要です（Windows は Git Bash 上で jq が PATH にあること）。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Bash コマンドで書き換えられたファイルはこのフックの対象外なので、特定ファイルをどう変わっても整形したいなら FileChanged イベントを使います。成功時はセッションに何も表示されないため、「効いているか」はファイルを開いて確認するか claude --debug で見ます。

機密パスを deny する

ユーザー設定（~/.claude/settings.json）に置いて全プロジェクトに効かせる形です。前述のとおり、user 設定の /path は ~/.claude/ 相対になるので、相対形か // ~/ で書きます。

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Edit(package-lock.json)"
    ]
  }
}

Read(.env) は gitignore 意味論でカレント配下の任意の深さの .env に効きます。シンボリックリンク経由でも、リンク先が deny に当たれば拒否されます。ここまでで塞げないのはファイル名を指定しない読み取りで、確実に止めるには PreToolUse フックで終了コード 2 を返します。公式の protect-files.sh は tool_input.file_path を読み、Windows のバックスラッシュを / に正規化してからパターン照合し、該当すれば exit 2 する構成です。鍵やトークンをそもそも読ませない設計はAIエージェントに秘密情報を読ませないで3層に分けて扱っています。

壊れた設定の見つけ方

settings ファイルは strict JSON です。// コメントも末尾カンマも構文エラーで、対話セッション開始時に Settings Error ダイアログ（Claude に直させる・終了・無視して続行）が出ます。個々のエントリだけが不正な場合は Settings Warning で、その値だけ飛ばして残りは有効です。-p 実行ではダイアログが出ず黙って飛ばされるので、後から claude doctor で確認します。

実際に壊した例です。permissions.allow を配列ではなく文字列にし、hooks の matcher を配列にした .claude/settings.json を置いたディレクトリで claude doctor を実行しました。

Invalid settings
- <dir>\.claude\settings.json › hooks.PostToolUse.0: Invalid hook matcher (matcher: Invalid input); matcher ignored.
- <dir>\.claude\settings.json › permissions.allow: Expected array, but received undefined
  Suggested fix: Permission rules must be in an array. Format: ["Tool(specifier)"]. Examples: ["Bash(npm run build)", "Edit(docs/**)", "Read(~/.zshrc)"]. Use * for wildcards.

どのファイルのどのキーが、なぜ無効で、どう直すかまで出ます。ここまで親切なので、「効かない」と思ったらまず claude doctor です。

その次は /status です。Setting sources 行に読み込まれたファイル（User settings Project local settings など）が並び、managed があれば経路も出ます。どのファイルがどのキーを供給したかまでは出ないので、値が期待と違うときは上位層を疑います。/permissions は解決後の allow / deny を、/hooks は登録済みフックを表示します。

編集は再起動なしで反映されます。公式 settings ページによれば Claude Code は設定ファイルを監視し、permissions hooks apiKeyHelper の変更を実行中のセッションに適用します（ConfigChange フックも走ります）。例外は model と effortLevel / modelSettings で、これらは /model /effort で切り替えます。

それでも切り分かないときは、公式 debug-your-config の「クリーンな設定で比較する」手順です。claude --safe-mode で全カスタマイズ（CLAUDE.md、スキル、プラグイン、hooks、MCP）を無効にして再現するか見る。さらに CLAUDE_CONFIG_DIR を空ディレクトリに向ければ ~/.claude 配下を丸ごと迂回できます。

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

まとめ

• 5層（managed → --settings → local → project → user）で解決。リストは結合、単一値は上位が勝つ
• ~/.claude.json は Claude Code が自分で書く別ファイル。permissions hooks env はそこに書いても効かない
• Bash ルールは * の位置、ファイルルールは // ~/ / ./ の4形式、MCP は mcp__server__tool
• hooks の matcher は文字列。Bash(rm *) の deny は文字列一致なので、確実に止めるなら PreToolUse で exit 2
• 壊れたら claude doctor、読まれたファイルは /status、切り分けは --safe-mode と CLAUDE_CONFIG_DIR

MCP サーバー側の設定（.mcp.json と claude mcp add）は settings.json とは別系統です。繋がらないときはMCP 接続チェックリストを参照してください。