Claude Code settings.json 配置詳解：文件位置、優先級與常用示例

本文根據 Claude Code 官方文檔《Settings files and precedence》《All settings》《Example settings files》整理，核對日期 2026-10-07。設定項很多（官方參考頁列了上百個），本文只講最常用的部分。

適用於誰

• 想讓 Claude Code 預設用某個模型、預設用中文回覆、少彈幾次確認框的人；
• 團隊裏想統一權限、Hooks、插件配置的人；
• 改了 settings.json 卻不生效，搞不清是哪個文件覆蓋了它的人。

結論先說

1. Claude Code 讀 4 個設定文件：用戶級 ~/.claude/settings.json、項目共享 .claude/settings.json、項目本地 .claude/settings.local.json，以及組織下發的託管設定（managed）。
2. 同一個字段出現在多處時，優先級從高到低：託管設定 → 命令行參數 → 項目本地 → 項目共享 → 用戶級。
3. 列表類字段會合並，比如 permissions.allow 在幾個文件裏的規則會合在一起，而不是互相覆蓋。
4. 設定文件是嚴格 JSON：不能寫 // 註釋，不能有多餘的逗號，否則啟動時報 Settings Error。
5. 改完在會話裏運行 /status，看「Setting sources」一行確認讀到了哪些文件；claude doctor 會列出被拒絕的條目。

一、四個設定文件分別管什麼

幾點補充：

• ~/.claude 指你用戶目錄下的 .claude 文件夾；Windows 上是 %USERPROFILE%\.claude。不帶 ~ 的 .claude 指項目裏的文件夾。
• 安裝後不會自動生成任何設定文件。你在 /config 裏改主題等選項時，Claude Code 會創建 ~/.claude/settings.json；你在權限確認框裏選「Yes, and don't ask again」時，會創建 .claude/settings.local.json，並自動把它加入 git 的全局忽略。如果你手動創建 local 文件，要自己加進 .gitignore。
• 還有一個 ~/.claude.json，是 Claude Code 自己寫的：登入狀態、MCP 伺服器配置、各項目的信任記錄等，一般不需要手動改。

二、優先級：到底聽誰的

從高到低：

1. 託管設定：組織下發，個人的任何設定都覆蓋不了（少數安全相關字段允許更嚴格的個人值）；
2. 命令行參數：本次啟動時傳的，比如 --model、--settings；
3. 項目本地 .claude/settings.local.json；
4. 項目共享 .claude/settings.json；
5. 用戶級 ~/.claude/settings.json。

舉個官方的例子：你在用戶級關掉了轉圈時的小提示（"spinnerTipsEnabled": false），但團隊的 .claude/settings.json 寫了 true，那麼在這個項目裏提示會重新出現，其他項目不會——因為項目共享高於用戶級。想在這個項目裏也關掉，就在 .claude/settings.local.json 裏再寫一次 false。

環境變量不在這個層級裏，每個變量和設定字段的關係單獨規定：例如在 shell 裏導出的 ANTHROPIC_MODEL 會蓋過任何文件裏的 model。而寫在設定文件 env 塊裏的變量，按文件優先級處理，並且會覆蓋 shell 裏同名的變量。

列表合併：permissions.allow、permissions.deny 這類列表在多個文件裏會合並。所以項目裏 allow 了、你個人 deny 了，結果是被拒絕——deny 永遠先判定。

三、三種修改方式

1. /config 選單：會話裏運行 /config，在 Config 標籤裏改主題、編輯模式、詳細輸出等個人選項；也可以一句話直接改：/config theme=dark。注意它只列了一小部分常用項，不是 settings.json 的完整視圖；VS Code 聊天面板和桌面版不提供 /config。

2. 直接編輯文件：開頭加一行 $schema，VS Code、Cursor 等編輯器就能自動補全和校驗：

json
{
  "$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 可能落後於最新版本，新字段出現校驗警告不一定代表寫錯。

3. 只對本次會話生效：

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

--settings 也可以傳一個 JSON 文件路徑。某些字段有專門的參數，如 --model、--effort。

什麼時候生效：Claude Code 會監視設定文件，permissions、hooks 等大多數改動儲存後立即生效，不用重啟。例外是 model、effortLevel 這類只在啟動時讀一次的字段，會話中途請用 /model、/effort 切換。

四、可複製的配置示例

個人配置（~/.claude/settings.json）

改寫自官方示例，並加了兩個國內用戶常用的字段：

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "language": "chinese",
  "theme": "light-daltonized",
  "spinnerTipsEnabled": false,
  "preferredNotifChannel": "terminal_bell",
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(git status)"
    ]
  },
  "autoUpdatesChannel": "stable",
  "cleanupPeriodDays": 30
}

團隊共享配置（.claude/settings.json，提交到倉庫）

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" }
        ]
      }
    ]
  },
  "env": {
    "MCP_TIMEOUT": "60000"
  },
  "plansDirectory": "./plans"
}

意思是：npm 腳本直接跑，推送前確認，密鑰文件不讓讀；每條 shell 命令執行前先過一遍倉庫裏的檢查腳本（Hook 寫法詳見本站《Claude Code Hooks 怎麼用：配置示例（完成通知、自動格式化、攔截危險命令）》）；把 MCP 啟動超時放寬到 60 秒；plan 模式生成的方案儲存到 ./plans。

提交團隊配置前，官方提醒的幾件事：

• 雲端會話也會讀它（雲端是從倉庫克隆開始的）；
• allow 規則要等每個人「信任這個文件夾」後才生效，deny 和 ask 規則則始終生效；
• 遙測相關的環境變量寫在項目文件裏會被忽略，要放到託管設定或個人設定裏；
• 權限規則按命令和路徑的字面匹配，Bash(git push *) 匹配不到 git -C . push，需要更嚴格就配合沙箱。

五、其他常用字段速查

attribution 取代了舊的 includeCoAuthoredBy，後者從 v2.0.62 起已棄用。完整字段請查官方《All settings》參考頁，每個字段都寫明瞭可放在哪些文件、預設值和對應的命令行參數 / 環境變量。

常見問題

Q：啟動時彈出「Settings Error」？

文件裏 JSON 寫錯了（最常見是加了註釋或多了逗號），或者某個值不被接受。對話框裏可以讓 Claude 幫你修、退出，或忽略這個文件繼續。只是個別條目有問題時顯示「Settings Warning」，那幾條會被跳過，其他照常生效。之後用 claude doctor 看具體錯誤。

Q：我設定的值被忽略了？

按優先級排查：是不是項目文件或託管設定裏也設了同一個字段；是不是 shell 裏導出了對應的環境變量；還有些字段在項目文件裏不生效，比如 defaultMode: "auto" 只認用戶級文件。

Q：/model 切換的模型下次還在嗎？

/model 會把選擇儲存為新會話的預設值；在選擇器裏按 s 則只對當前會話生效，不儲存。

Q：MCP 伺服器也寫在 settings.json 裏嗎？

不是。MCP 伺服器儲存在 ~/.claude.json（個人）和項目根目錄的 .mcp.json（團隊），詳見本站《Claude Code MCP 配置教學：claude mcp add、配置文件位置與常用 MCP》。

Q：~/.claude.json 壞了怎麼辦？

Claude Code 會把壞文件備份到 ~/.claude/backups/ 並詢問是手動修還是重置。它每次寫入前都會儲存備份，可以從 ~/.claude/backups/ 裏最近的 .claude.json.backup.<時間戳> 恢復。

參考資料

• Settings files and precedence（官方）：https://code.claude.com/docs/en/settings
• All settings（官方參考）：https://code.claude.com/docs/en/settings-reference
• Example settings files（官方）：https://code.claude.com/docs/en/settings-example
• Environment variables（官方）：https://code.claude.com/docs/en/env-vars