設定 Claude Code

你是 Claude Code 設定顧問。

【角色】
Claude Code 設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 想改的設定：___
- 適用範圍（全域 / 專案 / 本地）：___
- 現有設定：___
- 是否團隊共享：___
- 經驗水平：___

【工作流程】
1. 梳理設定層級
2. 把設定放到合適層
3. 說明優先順序
4. 標出常見衝突
5. 給驗證

【輸出規範】
▌一、設定層級
▌二、設定歸層
▌三、優先順序
▌四、衝突 + 驗證

【硬約束】
- 設定放對層級
- 敏感設定安全存放
- 改後驗證生效
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

Claude Code 設定的第一原則不是“這個開關怎麼寫”，而是“這條規則屬於誰”。個人偏好、團隊約定、本機路徑、企業策略放錯位置，後面所有排障都會變成猜。——翔宇

1. 不要把所有東西都塞進 settings.json

新手一看到“設定 Claude Code”，很容易想到一個檔案：

~/.claude/settings.json

然後把所有東西都寫進去：個人偏好、團隊規則、專案許可權、本機路徑、臨時實驗。

這會出問題。

假設你在個人 user settings 裡寫了：

{
  "permissions": {
    "allow": ["Bash(npm run *)"]
  }
}

這個規則會影響所有專案。個人練手專案沒問題，但生產儲存庫可能不應該自動放行所有 npm run。你以為只是給自己省一次確認，實際是把一個專案的信任邊界帶到了所有專案。

官方 Claude Code settings 文件把設定拆成多個 scope（作用域）。先決定歸屬，再寫設定。

2. 四個作用域：先問“誰應該擁有這條規則”

Claude Code 主要有四層設定作用域：

• Managed：server-managed、MDM / registry、系統級 managed-settings.json。影響組織或機器上的使用者，由 IT / 管理員下發。
• User：~/.claude/。影響目前使用者所有專案，不共享。
• Project：儲存庫裡的 .claude/。影響這個儲存庫所有協作者，應該提交到 git。
• Local：.claude/settings.local.json。隻影響目前儲存庫、目前機器、目前使用者，通常 gitignored。

對應到中文開發者的判斷：

• 個人主題、編輯器偏好、常用外掛：放 User。
• 團隊共同許可權、Hooks、MCP 結構、專案標準：放 Project。
• 本機路徑、臨時實驗、本地 credentials helper：放 Local。
• 企業安全策略、停用 bypass、統一登入要求：放 Managed。

3. 優先順序：誰能覆蓋誰

同一個設定在多個 scope 出現時，官方優先順序從高到低是：

比如：

• User 允許 Bash(npm run *)
• Project 拒絕 Bash(npm publish *)

最終 npm publish 仍然會被拒絕，因為 project 比 user 更具體，而且 deny 本身也是更強邊界。

4. 陣列不是替換，是合併

settings 裡很多欄位是陣列，比如：

• permissions.allow
• permissions.deny
• sandbox.filesystem.allowWrite
• availableModels
• allowedHttpHookUrls
• enabledPlugins

官方文件強調：陣列類設定跨 scope 是 concatenate and deduplicate，意思是拼接並去重，不是替換。

這很重要。

假設 managed 有：

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/opt/company-tools"]
    }
  }
}

user 又加：

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["~/.kube"]
    }
  }
}

最終不是二選一，而是兩個路徑都在最終設定裡。

這解釋了一個常見誤判：

{
  "permissions": {
    "allow": []
  }
}

空陣列通常不能“清空下層 allow”。你想阻斷某個能力，應寫明確 deny，或者讓管理員用 managed policy 約束。

5. 這些檔案分別管什麼

Claude Code 不是隻有一個設定檔。

常見物件的落點：

• Settings：User 用 ~/.claude/settings.json，Project 用 .claude/settings.json，Local 用 .claude/settings.local.json。
• Subagents：User 用 ~/.claude/agents/，Project 用 .claude/agents/；通常沒有 Local 目錄。
• MCP servers：User / local state 常見在 ~/.claude.json，Project server 用 .mcp.json。
• CLAUDE.md：User 可用 ~/.claude/CLAUDE.md，Project 用 CLAUDE.md 或 .claude/CLAUDE.md，Local 用 CLAUDE.local.md。
• Plugins：User、Project、Local 都跟隨對應 scope 的 settings 檔案。

另一個關鍵檔案是：

~/.claude.json

官方 settings 文件說明，它會儲存 OAuth session、user / local scope MCP 設定、per-project state、allowed tools、trust settings 和各種快取。

6. 一個新手可用的 settings.json

建議給 settings.json 加 schema，方便編輯器補全和校驗。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "autoUpdatesChannel": "stable"
}

這個例子表達三層意思：

• 常規開發驗證命令可以放行。
• 推送和釋出要問。
• 金鑰和高風險刪除直接拒絕。

7. settings.json 適合管什麼

常見設定可以分成幾組。

適合放進 settings 的內容：

• 許可權：permissions.allow、permissions.ask、permissions.deny、defaultMode。
• 環境變數：env。
• 沙盒：sandbox.filesystem、網路規則。
• Hooks：hooks、allowedHttpHookUrls、httpHookAllowedEnvVars。
• 外掛：enabledPlugins、extraKnownMarketplaces、strictKnownMarketplaces。
• 模型：model、availableModels、effortLevel。
• 更新：autoUpdatesChannel、minimumVersion。
• 登入約束：forceLoginMethod、forceLoginOrgUUID。
• 體驗：language、editorMode、defaultShell、cleanupPeriodDays。

但它不應該承載所有東西。

不適合塞進 settings 的內容：

• 專案長期規則：寫 CLAUDE.md 更適合。
• MCP project server：寫 .mcp.json 更清晰。
• 大段工作流說明：做 Skill。
• 金鑰正文：用系統憑據、CI secret、vault 或環境變數。
• 臨時路徑：用 local，不提交。

8. 敏感檔案怎麼處理

官方文件建議用 permissions.deny 阻止讀取敏感檔案。

常見寫法：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./credentials/**)"
    ]
  }
}

但這只是 Claude Code 工具層的限制。

如果你允許 Bash，子程序仍可能透過 shell 讀取檔案。比如一個指令碼、測試或第三方工具可能自己讀取 .env。

敏感檔案治理至少有四層：

• permissions.deny：阻止 Claude 的 Read / Edit 等工具直接訪問。
• Bash 許可權規則：限制危險命令。
• Sandbox：作業系統層限制 Bash 子程序讀寫。
• 系統檔案許可權：從根上限制誰能讀。

9. Managed settings：組織級強制策略

個人使用者可以先跳過這一節，但團隊和企業必須懂。

Managed settings 常見下發方式：

• Server-managed settings：Claude.ai admin console 下發。
• macOS MDM：com.anthropic.claudecode managed preferences domain。
• Windows policy：HKLM\SOFTWARE\Policies\ClaudeCode。
• 檔案式 macOS：/Library/Application Support/ClaudeCode/。
• 檔案式 Linux / WSL：/etc/claude-code/。
• 檔案式 Windows：C:\Program Files\ClaudeCode\。

Managed 適合強制：

• 停用 bypass permissions。
• 限制登入組織。
• 限制可用模型。
• 限制 MCP server。
• 限制外掛 marketplace。
• 只允許 managed permission rules。
• 只允許 managed hooks。

例如組織級禁止讀 secrets：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}

10. 怎麼確認設定生效

不要靠猜。

先看：

/status

它會顯示目前載入的 settings source、認證方式和關鍵狀態。如果某個 settings 檔案 JSON 錯誤，也能在這裡暴露。

許可權問題看：

/permissions

記憶和規則問題看：

/memory

安裝和環境健康看：

claude doctor

設定排障順序：

11. 常見坑

• 團隊規則寫進 user：只有你生效，別人復現不了。應放 project。
• 本機路徑寫進 project：別人 clone 後失效。應放 local。
• 金鑰寫進 settings：可能洩露到儲存庫或記錄。應放憑據系統 / secret。
• 用空陣列想清掉別的 scope（作用域）：結果仍然合併。應使用 deny 或 managed。
• 不看 /status：容易誤判設定沒生效。先看 source。
• 忽略 managed：反覆改 user 也無效。找管理員或看 policy。
• 把專案規則全寫 JSON：難讀、難維護。寫 CLAUDE.md。
• 共享 ~/.claude.json：會洩露會話和狀態。只共享專案檔案。

12. 本章自檢

試著用自己的話回答：

1. 為什麼寫設定前要先判斷這條規則屬於誰？對應 §1-§2。
2. managed、local、project、user 的優先順序是什麼？對應 §3。
3. 為什麼空陣列通常不能清掉低優先順序 scope 的 allow？對應 §4。
4. .claude/settings.json、.mcp.json、CLAUDE.md 分別適合放什麼？對應 §5-§7。
5. 為什麼 permissions.deny 不能替代 sandbox？對應 §8。

官方來源

• Claude Code settings
• Debug your configuration
• Server-managed settings
• Explore the .claude directory
• Configure permissions

接下來去哪

如果只記一個判斷：設定不是把所有開關寫進一個 JSON，而是把個人、團隊、本機和組織邊界寫到正確的 scope（作用域）裡。