配置 Claude Code

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（作用域）裡。