Claude Media
Claude Code settings.json完全ガイド — 全設定項目とpermissions設計
Claude Code解説

Claude Code settings.json完全ガイド — 全設定項目とpermissions設計

Claude Codeのsettings.jsonはpermissions・env・MCP・Hooks・モデルを一括管理する中心設定です。配置場所別の優先順位、全項目スキーマ、allow/deny設計、秘密情報の管理を項目別に扱います。

読了目安 約20分

Claude Codeの settings.json はpermissions / env / MCP / Hooks / モデル設定を一括管理する中心的な設定ファイルです。配置場所別の優先順位、全項目のスキーマ、permissionsのallow / deny設計、秘密情報の管理までを項目別に扱います。

settings.jsonとは

Claude Codeは起動時に複数の settings.json ファイルを読み込み、マージして使用します。本ファイルにより、対話のたびに承認プロンプトが出ない自動化、危険操作のガード、MCPサーバー登録、Hooks設定が可能になります。

settings.json で扱える主要トピックは次のとおりです。

トピックキー用途
権限キーpermissions.allow / permissions.deny用途ツール実行を許可 / 拒否するパターン
環境変数キーenv用途Claude Codeセッション内で利用する環境変数
MCPキーmcpServers用途MCPサーバーの登録(stdio / SSE)
Hooksキーhooks用途イベント別のbashコマンド差込
モデルキーmodel用途デフォルトモデル(claude-opus-5 / claude-sonnet-5 / claude-haiku-4-5-20251001 等)
その他キーapiKeyHelper / cleanupPeriodDays / includeCoAuthoredBy用途APIキー取得スクリプト、履歴保持期間、コミット共著者付与

配置場所と優先順位

Claude Codeは次の4種類の settings.json を順にマージします(後勝ち = 上位優先)。

順位配置場所用途git管理
1配置場所~/.claude/settings.json用途個人グローバル設定(秘密情報含む)git管理❌(git ignore推奨)
2配置場所<project>/.claude/settings.json用途プロジェクト共有設定(チーム / OSSで公開)git管理✓
3配置場所<project>/.claude/settings.local.json用途プロジェクト個別設定(個人の好み)git管理❌(git ignore)
4配置場所enterprise managed settings用途組織管理者の強制設定git管理—

優先順位はenterprise > project local > project shared > user globalですが、permissions.allow / permissions.deny は全マージされます(片方のdenyが有効ならdeny)。

実運用のパターンは次のとおりです。

  • チームで共有したい設定 → <project>/.claude/settings.json(git管理)
  • 個人の好み / 秘密情報 → ~/.claude/settings.json または settings.local.json(git管理外)
  • モデル選択 / Hookの構成 → プロジェクトで揃えるならproject shared、個人で変えたいならlocal

4層のマージはどう決まるか

4つの settings.json は「読み込んで丸ごと上書き」ではなく、キーの種類ごとに違うルールで合成されます。ここを取り違えると、設定したはずの値が効かない事態につながります。合成のルールは大きく3系統に分かれます。

単一値のキー(model / cleanupPeriodDays / theme など)は後勝ちです。enterprise managed settingsが最優先で、次にproject local、project shared、user globalの順に弱まります。同じ model を複数の階層で指定すると、優先度の高い階層の値だけが残る形です。

permissions.allow と permissions.deny はこの後勝ちルールに従いません。全階層の和集合になり、どこか1つの階層で deny に入ったパターンは、別の階層で allow していても拒否されます。denyがallowより強い、という非対称なルールです。組織管理者が敷いた deny を個人設定で緩められないことを意味し、安全側に倒すための設計と読めます。

env と hooks はキー単位で足し合わされます。同名の環境変数は優先度の高い階層が勝ち、異なる名前は共存します。hooks はイベントとmatcherの組み合わせごとに登録が積み上がるため、user globalに置いたHookが全プロジェクトで走る点に注意します。

具体例で考えます。user globalで Bash(git:*) をallow、project sharedで Bash(git push:*) をdenyした場合、git status は許可されますが git push は拒否されます。競合したらdenyが勝つためです。「個人的にはgit操作を広く許可したいが、チームの共有設定でpushだけは承認必須にしたい」という運用がこれで成立します。設定が思ったとおりに動かないときは、まずこの3系統のどれに当たるキーかを確かめると原因を絞り込めます。

permissions設計 — allow / denyの使い分け

permissions.allow / permissions.deny は、ツール実行の許可 / 拒否パターンを正規表現的に指定します。

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm test)",
      "Bash(npm run build)",
      "Read(./**)",
      "Edit(./media/content/**/*.mdx)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(./**/.env*)",
      "Write(./**/.env*)"
    ]
  }
}

許可 / 拒否の二択に加えて、実行前に毎回確認する中間段の permissions.ask もあります。3つのリストは deny → ask → allow の順に評価され、deny に一致すれば即拒否、ask に一致すれば都度確認、どちらにも該当せず allow に一致すれば承認なしで実行します。危険とまでは言えないが実行前に一目確認したい操作を ask に置く、という設計ができます。

主要パターンの書き方:

表記意味
Bash(<command>)意味ワイルドカードなしは完全一致。部分一致にしたいときは末尾に * または :* を付ける
Bash(<prefix>:*)意味<prefix> で始まるすべてのbash実行を許可 / 拒否
Read(<glob>)意味Read toolで <glob> パターンに一致するファイルを許可
Edit(<glob>)意味Edit toolで <glob> パターンに一致するファイルを許可
Write(<glob>)意味Write toolで <glob> パターンに一致するファイルを許可

設計原則:

  1. denyを優先:危険操作(rm -rf / sudo / .env 編集 等)をdenyで機械的にガード
  2. allowは最小限に:本当に承認なしに実行してよい操作だけをallowに追加
  3. Bash全許可は避ける:Bash(*) をallowすると危険コマンドもバイパスされる
  4. 個別コマンドはallow、危険プレフィックスはdeny:Bash(npm test) はallow、Bash(rm -rf:*) はdeny

承認なしに動かしたい操作はallow、絶対やらせたくない操作はdenyで。両方をバランスよく使うのが安定設計です。

env — 環境変数の管理

Claude Codeセッション内で利用する環境変数を env で指定できます。

{
  "env": {
    "ANTHROPIC_MODEL": "claude-opus-5",
    "NODE_ENV": "development",
    "CLAUDE_CODE_OAUTH_TOKEN": "...",
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
  }
}

主用途:

  • APIキー / アクセストークンの注入(秘密情報は ~/.claude/settings.json 側に)
  • モデル指定の上書き(ANTHROPIC_MODEL)
  • 開発 / 本番環境の切替

注意点:

  • <project>/.claude/settings.json(git管理)に秘密情報を書かないこと
  • 秘密情報は必ず ~/.claude/settings.json(git管理外)に分離
  • 大規模プロジェクトでは apiKeyHelper(後述)で外部secret managerから動的取得する設計が安全

mcpServers — MCPサーバー登録

MCPプロトコルでクライアントを拡張する設定です。詳細はClaude Code MCPサーバー完全ガイドで扱っています。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

複数MCPサーバーを並列登録すれば、Claudeが用途に応じて呼び分けます。

hooks — Hook登録

イベント別のbashコマンド差込です。詳細はClaude Code Hooks完全ガイドで扱っています。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "..." }
        ]
      }
    ]
  }
}

9種類のEvent(PreToolUse / PostToolUse / UserPromptSubmit / SessionStart / SessionEnd / Stop / SubagentStop / Notification / PreCompact)から選択できます。

model — デフォルトモデル

セッション開始時に使うデフォルトモデルを指定できます。

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

主要選択肢:

  • claude-opus-5:最高水準の推論深度
  • claude-sonnet-5:速度と品質のバランス、汎用デフォルト
  • claude-haiku-4-5-20251001:高速・軽量タスク向き

セッション中は /model コマンドで切替も可能です。詳細はClaudeモデル比較完全ガイドを参照してください。

apiKeyHelper — 動的なAPIキー取得

apiKeyHelper はコマンドでAPIキーを動的取得する仕組みです。1Password / AWS Secrets Manager / Vault等の外部secret manager経由でAPIキーを取得し、settings.json に平文で書かない設計が可能です。

{
  "apiKeyHelper": "op read 'op://Private/Anthropic API/credential'"
}

このコマンドの標準出力がAPIキーとして使われます。

その他の主要キー

キー役割デフォルト
cleanupPeriodDays役割履歴 / キャッシュの保持日数デフォルト30日(最小1日)
includeCoAuthoredBy役割コミットメッセージにCo-Authored-Byを付与デフォルト既定で有効なことが多い
theme役割UIテーマ(dark / light等)デフォルト環境により異なるため公式の設定一覧で確認
editorMode役割エディタ操作モード(vim / normal)デフォルトnormal

theme / editorMode のようなUI系設定は /config コマンドで対話的に変更でき、内部的に settings.json を書き換えます。

秘密情報の管理ベストプラクティス

<project>/.claude/settings.json はgit管理されるため、秘密情報を絶対に書いてはいけません。理由は、いったんgit履歴に入った秘密情報が後から完全には消せないことにあります。ファイルから削除して新しいcommitを積んでも、過去のcommitやリモートのフォーク、CIのログ、ローカルのreflogに値は残り続けます。公開リポジトリなら第三者のクローンにも複製されます。APIキーやトークンは「1度でもpushされたら失効させて再発行する」のが前提になり、ファイル削除だけでは回収できません。

だからこそ、秘密情報は最初からgit管理外の階層に置く設計が要になります。次の階層構造で管理するのが推奨です。

~/.claude/settings.json                  # 個人の API キー / 秘密情報(git 管理外)
<project>/.claude/settings.json          # チーム共有(permissions / Hooks / MCP の構成 / モデル指定)
<project>/.claude/settings.local.json    # プロジェクト個別の個人設定(git 管理外)

秘密情報を分離する具体策:

  1. プロジェクト共有settingsには env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${env.GITHUB_PERSONAL_ACCESS_TOKEN}" } のように環境変数参照
  2. ユーザーグローバルsettingsに実際の値を持たせる
  3. または apiKeyHelper で外部secret managerから取得

git push前に必ず git diff で <project>/.claude/settings.json に秘密情報が混入していないか確認するのも保険として有効です。

apiKeyHelper はこの分離を運用へ落とし込む仕組みです。settings.jsonにキーの文字列を書く代わりに、キーを取り出すコマンドを書きます。呼び出しのたびにコマンドの標準出力が読まれるため、1Password / AWS Secrets Manager / Vaultのようなsecret managerで一元管理し、失効やローテーションをsettings.jsonの外で完結できます。チーム全員が同じ共有settingsを使いながら、各自のキーは各自のsecret managerから供給する、という形も組めます。settings.jsonに平文の値が一切残らないため、うっかりcommitする事故そのものが起きにくくなるのが利点です。

どの設定をどのファイルに置くか

設定を1つ追加するとき最初に決めるのは「値を置く階層」です。判断は2つの問いに落とせます。1つ目は「チーム全員で揃えたい設定か、自分だけの好みか」。2つ目は「秘密情報を含むか」。この2軸で置き場所はほぼ一意に決まります。

設定の性質置き場所
チーム共通の権限 / MCP / Hook置き場所project shared(git管理)
個人の好み(テーマ / エディタ / 個別allow)置き場所settings.local(git管理外)
秘密情報(APIキー / トークン)置き場所user globalまたは外部secret manager
組織で強制するルール置き場所enterprise managed settings

チームで揃えたい非秘密の設定、たとえばpermissionsの共通ルールやプロジェクト固有のMCPサーバー、CIと同じ検証を走らせるHookはproject sharedに置き、レビュー対象にします。自分だけの好み、たとえばエディタ操作モードやテーマ、個人的に許可したいコマンドはsettings.localに置いてgit管理から外します。秘密情報はプロジェクトをまたいで共通なので、user globalか外部secret managerに寄せるのが自然です。

迷いやすいのがモデル指定とHookの置き場所です。チームで同じモデルに揃えたいならproject shared、案件ごとに個人で変えたいならsettings.localが向きます。Hookも同じで、全員に同じ検証を走らせたいならproject shared、手元の実験段階なら影響範囲を絞るためsettings.localに置く、という切り分けになります。

よくあるつまずきと回避策

settings.json運用で踏みやすい落とし穴を6件集めました。

つまずき1:permissionsが効かない

Bash(npm*) のように書くと語境界がないため、意図より広く一致します(npm で始まる別コマンドまで拾ってしまいます)。語境界付きの前方一致にしたいときは Bash(npm:*) または Bash(npm *) と書きます。:* の接尾辞は末尾ワイルドカードと等価な書き方です。正確なパターン書式は前述の「permissions設計 — allow / denyの使い分け」を見直してください。

つまずき2:プロジェクトsettingsを編集したら他の人が動かなくなった

<project>/.claude/settings.json はチーム全員に影響します。permissions / Hooks / model等を変更するときはPRでレビューを通すか、影響範囲を確認してからmergeします。「自分だけ変えたい」設定は settings.local.json に書きます。

つまずき3:秘密情報をgit commitしてしまう

<project>/.claude/settings.json を git add する前に、env フィールドにAPIキー / トークンが混入していないか必ず確認します。pre-commit hookで grep -rE '(token|secret|key|password)\s*[:=]' .claude/settings.json を走らせるのが安全です。

つまずき4:複数プロジェクトで個人グローバル設定が干渉

~/.claude/settings.json の mcpServers / hooks はすべてのプロジェクトに適用されます。特定プロジェクトでだけ動かしたいMCPはproject settingsに置きます。

つまずき5:/config で変更した内容が反映されない

/config は settings.json を書き換えますが、書き換え後にセッションリロードが必要なケースがあります。/restart またはClaude Codeを再起動して反映を確認します。

つまずき6:Enterprise管理の設定で上書きされる

組織管理者が設定したenterprise managed settingsは個人設定で上書きできません。「設定を変えても効果がない」と感じたらenterprise managed settingsの存在を組織管理者に確認します。

チーム導入で設定をどう育てるか

settings.jsonは一度に完成させるものではなく、運用しながら育てる対象と考えると無理がありません。permissions / env / MCP / Hooks / modelは互いに関係し合うため、最初から全部を盛り込むと、どの設定が原因で承認が出たり処理が止まったりしているのか切り分けにくくなります。

出発点はpermissionsとmodelの最小構成です。まず承認なしで回してよいコマンドをallowに並べ、危険操作をdenyで固めます。ここが安定したらMCPサーバーを足し、外部ツール連携を広げます。チーム全員が同じ検証を踏む段階になったらHookを加えます。段階を分けておくと、変更のたびに挙動の変化を追いやすくなるのが利点です。

チーム導入では、project sharedをPRレビューの対象に含めるやり方が効いてきます。permissionsの緩和やHookの追加は全員の実行環境を変えるため、コード変更と同じ重みでレビューする価値があります。個人が試したい設定はsettings.localで各自が抱え、効果が確認できたものだけをproject sharedへ引き上げる流れにすると、共有設定が壊れにくくなります。settings.jsonをチームの資産として少しずつ厚くしていく、という向き合い方が長続きします。

まとめ

Claude Codeの settings.json はpermissions / env / MCP / Hooks / モデル設定を統合する中心的な設定ファイルです。設計判断の軸は次の3つです。

  1. 秘密情報はユーザーグローバル、共有設定はプロジェクト:git管理範囲を明確に分離
  2. permissionsはdenyを優先、allowは最小限:危険操作の機械的ガード
  3. /config で対話的に編集、構造化変更は手動でjson編集:用途で使い分ける

MCPサーバー登録はClaude Code MCPサーバー完全ガイドで、HooksのEvent一覧はClaude Code Hooks完全ガイドで深掘りしています。

settings.jsonは最初の導入コストはありますが、いったん整備するとセッション開始時のセットアップが自動化され、長期的に大きな摩擦削減になります。最小構成(permissions + model指定)から始めて、運用しながらHooks / MCPを追加していく形が安定して育てやすいでしょう。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →