Claude Code 的 settings.json 完整解析：每個欄位都說清楚

這篇文章整合了之前多篇文章的設定知識。如果你想深入某個主題： 📖 Claude Code 權限控管：settings.local.json 📖 Claude Code Hooks 實戰 📖 Claude Code MCP Server

🎯 前言

Claude Code 的設定分散在多篇文章中——權限在一篇、Hooks 在一篇、MCP 在另一篇。每次要查一個設定，要翻好幾篇。

這篇把所有設定集中在一個地方，當作查表用。

📂 設定檔的位置與優先級

三個層級

層級檔案路徑提交 git？用途
全域（User）~/.claude/settings.json不提交個人在所有專案的預設值
專案（Project）.claude/settings.json提交團隊共用的專案設定
本地（Local）.claude/settings.local.json不提交個人在此專案的覆蓋設定

另外還有企業管理層（Managed），由 IT 部署，優先級最高：

  • macOS：/Library/Application Support/ClaudeCode/managed-settings.json
  • Linux/WSL：/etc/claude-code/managed-settings.json
  • Windows：C:\Program Files\ClaudeCode\managed-settings.json

優先級（由高到低）

Managed（企業管理）
  ↓ 覆蓋
Local（.claude/settings.local.json）
  ↓ 覆蓋
Project（.claude/settings.json）
  ↓ 覆蓋
User（~/.claude/settings.json）

合併規則

值的類型合併方式
純量（string、boolean、number）高優先級直接覆蓋低優先級
陣列（permissions.allow 等）合併（concatenate + 去重），不是覆蓋

陣列合併的意思是：如果 User 設定了 allow: ["Bash(git *)"]，Project 設定了 allow: ["Bash(npm *)"]，最終 allow 清單是兩者合併。

🔑 permissions：權限控管

{
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(npm run *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Read(./.env)"
    ],
    "defaultMode": "default",
    "additionalDirectories": ["../shared-lib/"]
  }
}

規則語法

格式範例說明
ToolBash匹配該工具的所有操作
Tool(pattern)Bash(git *)匹配符合 pattern 的操作
Tool(path)Read(./.env)匹配特定檔案路徑
Tool(path/**)Edit(./src/**)匹配目錄下所有檔案
mcp__server__toolmcp__github__create_issue匹配 MCP 工具

評估順序

deny → ask → allow

deny 優先。如果同時匹配 deny 和 allow，deny 贏。

defaultMode 選項

模式說明
default預設，危險操作需要確認
acceptEdits自動接受檔案編輯
plan進入 Plan Mode
auto自動模式，大部分操作自動執行
bypassPermissions跳過所有權限檢查（危險）

🔧 hooks：事件驅動自動化

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/check.sh",
            "timeout": 30,
            "statusMessage": "檢查中..."
          }
        ]
      }
    ]
  }
}

事件類型速查

工具相關（最常用）：

事件時機可阻擋？matcher
PreToolUse工具執行前✅ exit 2工具名稱
PostToolUse工具執行後❌工具名稱
PermissionRequest權限對話框出現前✅工具名稱

Session 相關：

事件時機可阻擋？matcher
SessionStartSession 開始/恢復❌startup、resume、clear、compact
SessionEndSession 結束❌clear、resume、logout 等
StopClaude 結束回答✅—
UserPromptSubmit使用者送出 prompt✅—

其他實用事件：

事件時機matcher
NotificationClaude 發通知permission_prompt、idle_prompt 等
FileChanged監控的檔案變更檔名（basename）
SubagentStopSubagent 完成agent 類型
PreCompact / PostCompactContext 壓縮前/後manual、auto

Hook handler 類型

type用途必要欄位
command執行 shell 指令command
httpPOST 到 URLurl
prompt單輪 LLM 判斷prompt
agent多輪 subagentprompt

共用欄位

欄位說明預設值
timeout超時秒數command: 600, http/prompt: 30, agent: 60
if精細過濾（權限規則語法）—
statusMessage自訂 spinner 文字—
async背景執行，不阻擋false
shell指定 shell"bash" 或 "powershell"

Exit code

Code效果
0成功，stdout 解析為 JSON
2阻擋操作，stderr 回饋給 Claude
其他非阻擋錯誤，繼續執行

🌐 MCP：外部資料來源

MCP 設定不在 settings.json，而是在獨立的檔案中：

位置檔案範圍
個人~/.claude.json當前專案或全域
專案.mcp.json（專案根目錄）團隊共用
{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"],
      "env": { "DB_DSN": "${DB_DSN}" }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

在 settings.json 中控制 MCP

欄位用途
enableAllProjectMcpServers自動信任 .mcp.json 中的所有 server
enabledMcpjsonServers信任 .mcp.json 中的指定 server
disabledMcpjsonServers拒絕 .mcp.json 中的指定 server
allowedMcpServers（Managed）允許的 server 白名單
deniedMcpServers（Managed）拒絕的 server 黑名單

🛡️ sandbox：沙盒隔離

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "filesystem": {
      "allowWrite": ["./dist/", "./tmp/"],
      "denyWrite": ["./.env", "./secrets/"],
      "denyRead": ["./secrets/"]
    },
    "network": {
      "allowedDomains": ["*.npmjs.org", "api.github.com"],
      "allowLocalBinding": true
    }
  }
}

檔案系統

欄位說明
filesystem.allowWrite額外允許寫入的路徑
filesystem.denyWrite禁止寫入的路徑
filesystem.denyRead禁止讀取的路徑
filesystem.allowRead在 denyRead 範圍內重新允許讀取

路徑前綴：/ 絕對路徑、~/ 家目錄、./ 專案相對路徑。

網路

欄位說明
network.allowedDomains允許連線的網域（支援 * 萬用字元）
network.allowLocalBinding允許綁定 localhost port（macOS）
network.allowAllUnixSockets允許所有 Unix socket 連線

🔤 env：環境變數

{
  "env": {
    "NODE_ENV": "development",
    "DB_HOST": "localhost",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

env 中設定的環境變數會套用到每個 session。常用的環境變數：

模型相關

變數說明
ANTHROPIC_MODEL預設模型
CLAUDE_CODE_SUBAGENT_MODELSubagent 使用的模型
MAX_THINKING_TOKENS思考 token 上限
CLAUDE_CODE_EFFORT_LEVEL努力程度：low、medium、high

Context 相關

變數說明
CLAUDE_AUTOCOMPACT_PCT_OVERRIDEContext 自動壓縮的百分比閾值
DISABLE_AUTO_COMPACT停用自動壓縮

輸出相關

變數說明
CLAUDE_CODE_MAX_OUTPUT_TOKENS輸出 token 上限
BASH_MAX_OUTPUT_LENGTHBash 輸出長度上限
BASH_DEFAULT_TIMEOUT_MSBash 預設超時（毫秒）

遙測與除錯

變數說明
DISABLE_TELEMETRY停用匿名使用統計
DISABLE_ERROR_REPORTING停用錯誤回報

⚙️ 其他常用設定

模型

{
  "model": "claude-sonnet-4-6"
}

接受別名（sonnet、opus、haiku）或完整 model ID。

歸屬標記

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

設成空字串可以隱藏 commit 和 PR 中的 Claude 歸屬標記。

語言

{
  "language": "traditional-chinese"
}

設定 Claude 回覆的偏好語言。

Worktree

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".venv"],
    "sparsePaths": ["src/", "tests/"]
  }
}

控制 worktree 隔離時的行為——哪些目錄 symlink、哪些目錄 sparse checkout。

UI 相關

欄位說明
prefersReducedMotion減少動畫（無障礙）
showThinkingSummaries顯示思考摘要
spinnerTipsEnabled顯示 spinner 提示
voiceEnabled啟用語音輸入

自動模式

{
  "autoMode": {
    "environment": ["這是一個可信任的 repo，可以安全執行 npm 指令"],
    "allow": ["Bash(npm *)"]
  }
}

控制 Auto Mode 的分類器行為。environment 提供額外上下文，allow 指定自動允許的規則。

📋 我的實際設定

全域設定（~/.claude/settings.json）

所有專案共用的個人偏好：

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  },
  "attribution": {
    "commit": "",
    "pr": ""
  },
  "language": "traditional-chinese",
  "prefersReducedMotion": true
}

專案設定（.claude/settings.json）

團隊共用的規則：

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/protect_files.sh",
            "statusMessage": "檢查檔案保護規則..."
          }
        ]
      }
    ]
  }
}

本地覆蓋（.claude/settings.local.json）

我個人在這個專案的額外限制：

{
  "permissions": {
    "allow": [
      "Bash(dir:*)"
    ]
  },
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('Claude Code 需要你的注意')\"",
            "shell": "powershell"
          }
        ]
      }
    ]
  }
}

💡 設定建議

新手起步

如果你剛開始用 Claude Code，先從最少的設定開始：

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

用幾天後，根據你的經驗逐步新增 allow 和 hooks。

團隊協作

設定放哪裡
專案的建置/測試指令允許清單.claude/settings.json（提交 git）
個人的權限偏好.claude/settings.local.json（不提交）
所有專案的通用規則~/.claude/settings.json
桌面通知等個人化 hook.claude/settings.local.json

除錯設定問題

如果不確定某個設定是否生效，在 Claude Code 中問：

你：目前的 settings 有哪些 allow 和 deny 規則？

Claude 會讀取所有層級的設定檔並告訴你合併後的結果。

🎉 結語

Claude Code 的設定系統設計得很合理：

  • 三層覆蓋：全域 → 專案 → 本地，各有各的用途
  • 陣列合併：低層級的 allow/deny 不會被覆蓋，只會被補充
  • 關注點分離：permissions 管權限、hooks 管自動化、MCP 管外部連接、sandbox 管隔離

不需要一次搞懂所有設定。大多數人只需要 permissions 和 hooks 就能涵蓋 90% 的需求。其他設定在你碰到具體問題時再來查這篇就好。

📎 相關文章：