Claude Codeのsettings.json設定ガイド — 置き場所・優先順位・主要キー

Claude Codeの settings.json は、起動時のモデル、承認なしで実行できる操作、読ませないファイル、環境変数、フックなどを決めるJSONファイルです。置き場所は4種類あり、同じキーが複数の場所にあれば優先順位の高い値が使われます。

結論を先に並べます。

• 自分だけの設定は ~/.claude/settings.json、チームで揃える設定は .claude/settings.json、プロジェクト内の個人設定は .claude/settings.local.json に書く
• 優先順位は高い順にmanaged、コマンドライン(--settings)、project local、shared project、user
• permissions.allow のような配列キーは、上書きでなく全ファイルの内容が合算される
• MCPサーバーは settings.json ではなく claude mcp add で登録し、~/.claude.json か .mcp.json に保存される

置き場所は4つ — どのファイルに書くか

Claude Codeをインストールしただけでは、設定ファイルは作られません。/config メニューでテーマなどを変えたとき ~/.claude/settings.json が、権限プロンプトで「Yes, and don't ask again」を選んだとき .claude/settings.local.json が自動で作られます。それ以外は自分で作ります。

~/.claude はホームディレクトリの .claude で、Windowsでは %USERPROFILE%\.claude です。CLAUDE_CONFIG_DIR を設定すると、設定・履歴・プラグインの保存先をそちらへ移せます。

Managedファイルの置き場所はOSごとに決まっています。

組織側の配布方法(MDM、サーバー管理設定など)はClaude Code組織管理ガイドで扱っています。

settings.local.jsonはgitに入るのか

.claude/settings.local.json をClaude Code自身が初めて書くとき、gitのグローバル除外ファイルに **/.claude/settings.local.json が追記されます。そのため、自分で .gitignore を書かなくてもコミットに混ざりません。仕組みの詳細はsettings.local.jsonがgitignoreなしで除外される仕組みにあります。

手で作ったファイルは、Claude Codeがまだ書き込んでいない間は除外されません。自分で .gitignore に足してください。

リポジトリのサブディレクトリで起動しても、このファイルはリポジトリのルートに作られます(v2.1.211以降)。ホームディレクトリがルートの場合や、Windowsでは .claude/settings.json と同じ場所に残ります。

~/.claude.jsonとの違い

~/.claude.json はClaude Code自身が書くファイルで、アカウント情報、MCPサーバーの設定、プロジェクトごとの信頼の記録、/config が書き込む一部のグローバル設定を持ちます。直接編集する必要はありません。settings.json と名前が似ていますが、別のファイルです。

優先順位 — 同じキーが複数あるとき

同じキーが複数の場所にあるときは、最も高い段で設定された値が使われます。高い順に5段です。

環境変数はこの5段に入りません。設定キーと対になる環境変数がある場合、どちらが効くかはキーごとに決まります。ANTHROPIC_MODEL をシェルでexportすると、どのファイルの model よりも優先されます。一方 ANTHROPIC_DEFAULT_MODEL は、どのファイルにも model がないときだけ使われます。

配列は上書きでなく合算される

permissions.allow のようなリストのキーは、複数のファイルにあれば結合されます。各ファイルが他のファイルの項目を消さずに足せます。

ただし、モデルまわりの fallbackModel、modelPicker、availableModels、modelSettings の4つは例外です。順序に意味があるものや、組織の制限を個人が足して崩せないものがあるため、単純な合算にはならず、キーごとの解決規則が決まっています。たとえば fallbackModel は、最も強い段が持つ値をそのまま使います。

permissions の deny は特に強く働きます。どのスコープであっても、deny に入った操作は他のスコープの allow で許可できません。ユーザー設定で Bash(git *) を許可し、プロジェクト設定で Bash(git push *) を deny にしていれば、git status は通り、git push は止まります。

ask と allow の関係には注意点があります。「Yes, and don't ask again」で保存された allow はlocalファイルに入りますが、プロジェクトやmanagedの ask ルールより強くはなりません。同じツールで確認が出続けるときは、この組み合わせを疑います。

上位が下位を上書きできない例外

セキュリティに関わる一部のキーは、managedより下の段でも「より厳しい値」が尊重されます。たとえば permissions.blockReadsOutsideWorkingDirectories は、どのスコープでも true を置けばmanagedが false でも true が効きます。個人が自分を縛る方向の設定は、組織設定に邪魔されないということです。

書き方と反映のしかた

設定ファイルは厳密なJSONです。// コメントや末尾のカンマは構文エラーになり、次の起動時にSettings Errorとして報告されます。最小の例です。

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

$schema を書くと、VS Codeなどのエディタで補完と検証が効きます。スキーマは最新リリースに追いつかないことがあり、最近追加されたキーに警告が出ても、設定が無効とは限りません。

編集の反映と確認は、次の流れで進めます。

claude doctor

壊れたファイルの扱いは2段階です。user・project・localのどれかが不正なJSONなら、起動時にSettings Errorが出て、修正・終了・無視して続行の選択肢が示されます。個々のエントリだけが不正(形式の崩れた権限ルール、未知のフックイベント名)ならSettings Warningになり、その値だけが読み飛ばされます。

セッション中に /config で変えた値は、設定ファイルに書き込まれます。多くはユーザー設定、一部(Show tipsなど)はlocalファイルです。/config key=value で1項目だけ変えることもできます。詳細はconfigコマンドでkey=valueを直接変更する方法にまとめています。/config はターミナル版の機能で、VS Codeのチャットパネルとデスクトップアプリでは開きません。

1回だけ試したいときは、設定ファイルを触らずに起動引数で渡します。

claude --settings '{"model": "claude-opus-5-5"}'

主要キーの早見表

全キーの一覧は公式のsettings referenceにあります。ここでは最初に触ることが多いものを、置けるスコープとあわせて並べます。

project・localで効かないキーがあります。公式のsettings indexのScope列が User や Managed になっているキーは、リポジトリのファイルに書いてもチームには届きません。コミットしたのに同僚に反映されないときは、まずこの列を見ます。

permissions — 承認の出し方を決める

permissions は、allow(承認なしで実行)、ask(必ず確認)、deny(拒否)の3つのルール配列と、既定の権限モードを持ちます。

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "defaultMode": "acceptEdits"
  }
}

評価の順番は deny が最初、次に ask、最後に allow で、最初に一致したルールで決まります。ルールの具体性は関係ありません。

ルールの書き方の要点です。

末尾の * と :* は同じ意味で、Bash(ls:*) は Bash(ls *) と一致します。ただし :* が使えるのはパターンの末尾だけです。Bash(git:* push) のように途中に置くと、コロンは文字そのものとして扱われます。

Write(path)、Glob(path)、Grep(path) にパスを付けたルールは、書いても一致しません。編集の制御は Edit(docs/**)、検索や読み取りの制御は Read(docs/**) で書きます。

denyは万能ではない

Read(./.env) のdenyは、組み込みのファイルツールと、cat や sed のようにファイルを名指しするコマンドに効きます。grep -r pattern . のようにファイル名を出さない読み方や、任意のサブプロセスには効きません。OSレベルで止めたいときは、サンドボックスを有効にします。

Bash(curl *) のdenyも、コマンドの書かれ方を見ます。/usr/bin/curl や sh -c 'curl ...' は素通りします。

権限モードの置き場所

permissions.defaultMode には default、acceptEdits、plan、auto、dontAsk、bypassPermissions を指定できます。auto と bypassPermissions はプロジェクト設定とlocal設定からは効きません。ユーザー設定に書くか、--permission-mode で渡します。

共有の .claude/settings.json に書いた allow は、各メンバーがフォルダを信頼するまで有効になりません。deny と ask は信頼の前から効きます。警告の出方はWorkspace has not been trustedの警告が出る理由と対処にあります。

権限ルールを対話的に確かめるなら/permissionsコマンドが使えます。

env — 環境変数を全セッションに渡す

env に書いた変数は、すべてのセッションと、Claude Codeが起動するサブプロセスに渡ります。

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

シェルでexport済みの同名変数は、env の値で上書きされます。シェル側の値を打ち消したいときは、"" を設定します。空文字はプロバイダー選択では未設定として扱われます。

ここは実務で踏みやすい点です。

• プロジェクト・localの env に書けない変数がある: CLAUDE_CONFIG_DIR、HOME、TMPDIR、OpenTelemetryの送信先や内容に関わる変数などは、リポジトリの設定からは捨てられます。ユーザー設定、managed設定、シェルに置きます
• 反映のタイミングが違う: ユーザー設定の env は起動時に、プロジェクト・localの env の大半はフォルダを信頼したあとに効きます
• 平文で保存される: 値はそのまま設定ファイルに残り、すべてのサブプロセスに渡ります。認証情報は次節の apiKeyHelper を使います

変数の一覧は環境変数リファレンスにあります。複数のmanaged設定源の env を合算する挙動はCLAUDE_CODE_DISABLE_ADMIN_ENV_UNIONで扱っています。

modelとapiKeyHelper

model は新しいセッションの既定モデルです。エイリアスでも完全なIDでも書けます。

{
  "model": "claude-sonnet-5"
}

1回のセッションだけなら、--model が ANTHROPIC_MODEL より強く、どちらも model キーより強い順で効きます。managedの model も「出発点の既定値」で、固定するなら availableModels や deniedModels を使います。セッション中の切り替えは /model です。モデルの違いはClaudeモデル比較ガイドで比べています。

apiKeyHelper は、認証情報を標準出力に返すコマンドを登録します。保管庫から短命のトークンを取る使い方が想定されています。

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}

コマンドはシェル経由で実行され、結果は既定で5分間キャッシュされます。APIが401か403を返したときは、再実行されます。プロジェクト・localの設定に書いた場合、対話セッションでは信頼ダイアログを承認するまで実行されません。

hooks・statusLine・sandbox

この3つは、専用の記事があるため、設定上の書き方だけ押さえます。

hooks はイベントごとに、matcher と実行内容のグループを並べます。複数のファイルに書いた内容は合算され、managed設定のフックは他のファイルから消せません。ハンドラーの種類は command、prompt、agent、http、mcp_tool です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

イベントの一覧と終了コードの意味はHooks完全ガイドに、全部まとめています。

statusLine は、プロンプトの下に出す表示を作るコマンドです。type に "command" を指定し、padding や refreshInterval で調整します。表示項目の選び方はstatuslineの設定ガイドにあります。

sandbox は、Bashコマンドを隔離する設定です。sandbox.enabled の既定は false で、LinuxとWSL2では bubblewrap と socat が必要です。サンドボックスを起動できないとき、failIfUnavailable を立てていなければ、コマンドは隔離なしで実行されます。

{
  "sandbox": {
    "enabled": true,
    "filesystem": { "allowWrite": ["/tmp/build"] },
    "network": { "allowedDomains": ["registry.npmjs.org"] }
  }
}

その他の頻出キー

Gitの扱いを自分のルールで決めたいときは、includeGitInstructions で既定のGit指示の挿入を止められます。止め方はincludeGitInstructionsでGit指示の自動挿入を止めるで扱っています。

attribution は、コミットのトレーラーとPR本文の署名を変えます。commit、pr、sessionUrl を個別に指定でき、false を渡すと署名をすべて消せます(v2.1.281以降。古い版は false を拒否し、そのファイル全体を読み飛ばします)。旧キーの includeCoAuthoredBy は非推奨で、commit か pr を設定すると無視されます。

{
  "attribution": {
    "commit": "",
    "pr": "",
    "sessionUrl": false
  }
}

cleanupPeriodDays は、セッションの履歴などを残す日数です。既定は30日で、0 は検証エラーになります。長く残したいときは 3650 のような大きな値を使います。保持期間を過ぎたセッションは、/resume の一覧から消えます。

theme と editorMode は /config から変える種類の設定で、/config を通すとユーザー設定に書き込まれます。

MCPサーバーはsettings.jsonに書かない

古い解説には、settings.json に mcpServers を書く例が出てきます。公式のsettings referenceのキー一覧にはこのキーがなく、MCPサーバーの登録は claude mcp add が担います。保存先は次のとおりです。

settings.json に関わるのは、プロジェクトの .mcp.json にあるサーバーを承認する enableAllProjectMcpServers や enabledMcpjsonServers、組織が許可を絞る allowedMcpServers などの制御キーです。登録の手順はMCP設定ガイドを参照してください。~/.claude.json が壊れて起動できなくなったときの復旧はClaude Code configエラー「Could not read」の直し方にあります。

設定例 — 個人用とチーム用

公式の例をもとに、役割ごとに分けた形を示します。例示であり、推奨値の押しつけではありません。

個人用は ~/.claude/settings.json に置きます。

{
  "model": "claude-sonnet-5",
  "editorMode": "vim",
  "theme": "light-daltonized",
  "spinnerTipsEnabled": false,
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  },
  "autoUpdatesChannel": "stable",
  "cleanupPeriodDays": 20
}

チーム用はリポジトリの .claude/settings.json に置いてコミットします。

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  },
  "sandbox": { "enabled": true }
}

チームファイルには、コミット前に知っておきたい点が3つあります。

• 1リポジトリだけのクラウドセッションは、このファイルを読む
• allow は各メンバーがフォルダを信頼するまで効かず、deny と ask は最初から効く
• Bash(git push *) は git -C . push には一致しない。ルールはコマンドの書かれ方で照合される

Claudeに設定を書かせるときの頼み方

設定ファイルをClaude Codeに書かせるなら、書かせたあとに検証まで頼みます。

.claude/settings.json に、npm run 系は承認なし、git push は確認、.env の読み取りは拒否のルールを追加して。
保存後に claude doctor を実行し、拒否された項目がないか出力を読んで報告して。

JSONの構文ミスや未知のキーは claude doctor に出るため、Claudeが自分で出力を読んで直せます。settings.json を編集した直後はシェルでの確認が最も早い手段です。

設定が効かないときの切り分け

原因の探し方をさらに掘り下げた記事に、Claude Code設定が反映されない原因の探し方があります。

クラウドセッションでの扱い

クラウドセッションは別のマシンで動くため、読まれる設定が限られます。

よくある質問

settings.jsonとsettings.local.jsonはどう使い分けますか?

チームで揃えたい設定は settings.json に書いてコミットします。自分だけの上書きや、共有前の試験は settings.local.json に書きます。localのほうが優先順位は上で、チームの値を自分だけ変えられます。

グローバルな設定ファイルはどこにありますか?

~/.claude/settings.json です。Windowsでは %USERPROFILE%\.claude\settings.json になります。インストールだけでは作られず、/config で設定を変えたときなどに作成されます。

設定ファイルにコメントは書けますか?

書けません。// のコメントも末尾のカンマも構文エラーです。説明を残したいときは、$schema で補完を効かせたうえで、別のドキュメントに書きます。

設定を変えたら再起動が必要ですか?

permissions、hooks、apiKeyHelper などは、保存すれば実行中のセッションに反映されます。起動時に一度だけ読まれるキーは再起動が必要です。迷ったら /status と claude doctor で確かめます。

まとめ

settings.json の設計は、キーごとに「誰に効かせるか」を決めることです。自分だけならuserかlocal、チームならshared project、組織の強制ならmanagedに置きます。同じキーが重なったときは、managed、--settings、local、shared project、userの順に強く、配列は合算され、deny はどのスコープでも勝ちます。

効かないときは、/status で読まれたファイルを見て、claude doctor で拒否された項目を見る、の2手で大半は絞れます。MCPは別の保存先で管理されるため、settings.json に書いた記憶があるなら、一度見直す価値があります。