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

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

settings.jsonとは

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

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

配置場所と優先順位

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

優先順位は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

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*)"
    ]
  }
}

主要パターンの書き方:

設計原則:

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-4-7",
    "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-4-7"
}

主要選択肢:

• claude-opus-4-7:最高水準の推論深度、重い思考向き
• claude-sonnet-4-6:速度と品質のバランス、汎用デフォルト
• 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キーとして使われます。

その他の主要キー

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

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

<project>/.claude/settings.json は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 に秘密情報が混入していないか確認するのも保険として有効です。

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

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

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

Bash(npm:*) のようにprefixの後にコロンと * を必ず付ける表記が必要です。Bash(npm*) のような書き方では一致しません。正確なパターン書式はClaude Code権限完全ガイドを参照してください。

つまずき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の存在を組織管理者に確認します。

まとめ

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

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

具体的なpermissionsパターンはClaude Code権限完全ガイドで、MCPサーバー登録はClaude Code MCPサーバー完全ガイドで、HooksのEvent一覧はClaude Code Hooks完全ガイドで深掘りしています。

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