Claude Code settings.json 設定｜4スコープと権限・環境変数

settings.json とは何か

settings.json は Claude Code の挙動を制御する設定ファイルです。使用するモデル、応答言語、許可するコマンド、環境変数、フックなどを JSON 形式でまとめて指定でき、コマンドラインで毎回オプションを渡す代わりに恒久的なデフォルトを定義できます。

ポイントは「1つのファイル」ではなく、適用範囲(スコープ)の異なる複数の settings.json が階層的に重なって最終的な設定が決まる、という構造です。個人の好み・プロジェクト共通ルール・組織の強制ポリシーを別々のファイルに書き分けられるため、まずスコープを理解することが最短ルートになります。

出典: Claude Code の設定 - Claude Code Docs

4つのスコープと置き場所

設定ファイルは次の4スコープに分かれます。

1. User スコープ (~/.claude/settings.json): すべてのプロジェクトに共通で適用される個人用デフォルト。常用するモデルや language などをここに置きます。
2. Project スコープ (.claude/settings.json): リポジトリのコラボレーター全員に適用。git でコミットしてチーム共有するため、ツール許可や MCP 接続先などプロジェクト固有のルールを書きます。
3. Local スコープ (.claude/settings.local.json): そのリポジトリ内の自分だけに適用。gitignore 対象で、個人的な一時設定や検証用の許可を置きます。
4. Managed スコープ (組織配布の managed-settings.json 等): IT 部門がマシン全体・組織全体に展開する強制設定。

個人の好みは User、チームのルールは Project、コミットしたくない例外は Local、と置き分けるのが基本方針です。

スコープの優先順位

複数スコープで同じキーを指定した場合、次の優先順位(高いほど勝つ)で解決されます。

1. Managed(最優先・上書き不可)
2. コマンドライン引数(そのセッション限定)
3. Local(Project を上書き)
4. Project(User を上書き)
5. User(最も弱いデフォルト)

たとえば User で model を指定していても、Project 側で別モデルを指定すればプロジェクト内ではそちらが優先されます。組織が Managed で禁止したコマンドは、個人がどのスコープで許可を書いても解除できません。「効くはずの設定が効かない」ときは、上位スコープで上書きされていないかをこの順に確認します。

permissions で許可・禁止を制御する

permissions は Claude Code がどのツール・コマンドを実行できるかを allow(自動許可)・ask(都度確認)・deny(禁止)の3段階で制御するキーです。秘匿ファイルの読み取り禁止や、破壊的コマンドの遮断に使います。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../docs/"]
  }
}

ルールの書き方は次のとおりです。

• Bash: すべての Bash コマンド
• Bash(npm run *): npm run で始まるコマンド
• Read(./.env) / Edit(./src/**): 対象ファイルの読み取り・編集
• WebFetch(domain:example.com): 指定ドメインへのフェッチ
• mcp__github__get_*: MCP ツール(プレフィックスマッチ)

defaultMode は許可確認の既定挙動で、default(毎回確認)・acceptEdits(編集を自動承認)・plan(プランモード)・bypassPermissions(スキップ・非推奨)などを指定できます。.env や secrets/ を deny に入れておくと、機密の漏洩リスクを下げられます。

出典: Claude Code settings.json 解説 - Zenn(ryok)

model と env でモデル・環境変数を指定する

model で使用モデルを、env でセッションに渡す環境変数を指定します。

{
  "model": "claude-sonnet-4-6",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"],
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

model には claude-opus-4-8 や claude-sonnet-4-6 のようなモデル ID を指定します。env に書いた値はセッション起動時に環境変数として読み込まれるため、テレメトリ有効化やプロキシ設定などに使えます。重い作業は上位モデル、日常は軽量モデル、とプロジェクト単位で切り替える運用がしやすくなります。

hooks とその他の主要キー

hooks を使うと、ツール実行の前後など特定イベントで任意のコマンドを自動実行できます。整形・テスト・ガード処理を差し込む用途に向きます。

{
  "language": "japanese",
  "outputStyle": "Explanatory",
  "editorMode": "vim",
  "theme": "dark",
  "cleanupPeriodDays": 30,
  "includeCoAuthoredBy": true
}

よく使うキーは次のとおりです。

• language: 応答言語(japanese など)
• outputStyle: 回答スタイル
• editorMode: エディタ操作(vim など)
• cleanupPeriodDays: チャット履歴の保持日数
• includeCoAuthoredBy: コミットに Co-Authored-By を付与するか

出典: Claude Codeの設定(settings.json)完全ガイド - AI総合研究所

sandbox で実行環境を隔離する

sandbox を有効にすると、ファイル書き込みやネットワークアクセスを制限した隔離環境でコマンドを動かせます。許可ディレクトリのみ書き込み可、認証情報は読み取り禁止、といった粒度で安全に運用できます。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

permissions がツール単位の許可制御なのに対し、sandbox は OS レベルの隔離である点が違いです。両者を組み合わせると、誤操作や予期せぬアクセスの影響範囲を最小化できます。

設定の反映タイミング

設定はキーによって反映タイミングが異なります。permissions・hooks・apiKeyHelper・sandbox はファイル保存時にリアルタイムで再読み込みされ、再起動は不要です。一方で model・outputStyle・language などはセッションを起動し直したときに適用されます。「設定を変えたのに反映されない」と感じたら、まずこのタイミングの違いを疑い、必要なら Claude Code を再起動します。

環境変数による上書き

settings.json の値は環境変数で一時的に上書きできます。

• ANTHROPIC_MODEL: モデル選択(そのセッション限定)
• MAX_THINKING_TOKENS=0: 拡張思考を無効化
• DISABLE_AUTOUPDATER: 自動更新を無効化

CI やワンショットの検証では、ファイルを書き換えずに環境変数で挙動を切り替えるほうが安全です。恒久的なデフォルトは settings.json、その場限りの調整は環境変数、と使い分けるとよいでしょう。

出典: Claude Code の settings.json コピペですぐ使えるおすすめ設定まとめ - Qiita

まとめ:置き場所と優先順位を押さえる

settings.json 運用の要点は次の3つです。

1. スコープを分ける: 個人は User、チーム共有は Project、例外は Local。
2. 優先順位を理解する: Managed > CLI 引数 > Local > Project > User。効かない設定は上位の上書きを疑う。
3. permissions で守る: .env や secrets/ を deny、破壊的コマンドを ask/deny にして事故を防ぐ。

まずは ~/.claude/settings.json に model と language、プロジェクトの .claude/settings.json に permissions を書くところから始めれば、安全で再現性のある運用に乗せられます。