---
title: "配置 Claude Code"
description: "Claude Code 配置不是隻改一個 settings.json。先分清 managed、user、project、local 四個作用域，再決定許可權、環境變數、Hooks、MCP、外掛和記憶放哪裡。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

> [!NOTE]
> **這一章用 14 分鐘換什麼**：入門章節已經完成安裝、登入和平臺選擇。現在進入核心能力第一章：settings（設定）。讀完你應該能判斷一條配置該放 user、project、local 還是 managed，並知道怎麼驗證它真的生效。

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

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

```text
~/.claude/settings.json
```

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

這會出問題。

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

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

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

> [!IMPORTANT]
> **第一性原理**：settings（設定）不是“配置寫在哪裡都行”，而是用 scope（作用域）把“個人、專案、機器、組織”的責任邊界分開。

官方 [Claude Code settings](https://code.claude.com/docs/en/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。

> [!TIP]
> **一句話判斷**：別人 clone 這個儲存庫後也應該遵守，就放 project；只有你自己用，就放 user 或 local；任何人都不許繞過，就放 managed。

| 判斷問題 | 放置位置 |
|----------|----------|
| 組織強制、任何人都不能覆蓋 | Managed |
| 團隊協作者都要一致 | Project |
| 本機路徑、臨時實驗、個人憑據 helper | Local |
| 當前使用者所有專案都要用 | User |
| 不確定、還在試驗 | Local |

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

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

| 優先順序 | 來源 | 含義 |
|:-:|------|------|
| 1 | Managed | 最高，不能被使用者、專案或命令列覆蓋 |
| 2 | Command line arguments | 本次會話臨時覆蓋 |
| 3 | Local project settings | 當前機器當前儲存庫 |
| 4 | Shared project settings | 儲存庫共享配置 |
| 5 | User settings | 使用者全域性預設 |

比如：

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

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

> [!WARNING]
> **不要用 user scope 對抗 project / managed**：如果專案或組織已經禁了某個行為，你改自己的 `~/.claude/settings.json` 不會讓它重新生效。

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

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

- `permissions.allow`
- `permissions.deny`
- `sandbox.filesystem.allowWrite`
- `availableModels`
- `allowedHttpHookUrls`
- `enabledPlugins`

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

這很重要。

假設 managed 有：

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

user 又加：

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

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

這解釋了一個常見誤判：

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

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

> [!IMPORTANT]
> **一句話記住**：陣列配置會合並；想禁止，用 deny 或 managed policy，不要幻想空陣列能擦掉別的 scope。

## 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 檔案。

另一個關鍵檔案是：

```text
~/.claude.json
```

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

> [!CAUTION]
> **不要把 `~/.claude.json` 當普通專案配置**：它含有會話、信任狀態和快取。團隊共享配置應該進儲存庫的 `.claude/` 或 `.mcp.json`，不是複製你的全域性狀態檔案。

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

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

```json
{
  "$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"
}
```

這個例子表達三層意思：

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

> [!TIP]
> **schema 只幫你發現格式問題**：官方 schema 可能滯後於最新 CLI 欄位。最近新增的欄位被編輯器標紅，不一定代表 Claude Code 不支援。

## 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，不提交。

> [!IMPORTANT]
> **邊界**：settings 管 Claude Code 行為開關；`CLAUDE.md` 管專案說明；Skill 管可複用流程；MCP 管外部工具連線。不要把它們都塞進一個 JSON。

## 8. 敏感檔案怎麼處理

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

常見寫法：

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

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

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

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

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

> [!WARNING]
> **不要把 deny 當沙盒**：`Read(./.env)` 能防 Claude 直接讀，不等於所有命令程序都讀不到。高敏感專案要同時考慮 sandbox 和系統許可權。

## 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：

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

> [!CAUTION]
> **Managed 是組織邊界，不是個人偏好**：一旦放到 managed，普通使用者和專案都不能覆蓋。不要把會隨專案變化的規則寫成全組織策略。

## 10. 怎麼確認配置生效

不要靠猜。

先看：

```text
/status
```

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

許可權問題看：

```text
/permissions
```

記憶和規則問題看：

```text
/memory
```

安裝和環境健康看：

```bash
claude doctor
```

配置排障順序：

<Steps>

<Step>
### `/status` 看 settings 檔案是否真的被載入
不要憑感覺。先確認 source 列表裡出現你改的那個檔案，再討論欄位是不是寫對。
</Step>

<Step>
### 檢查 JSON 結構
JSON 語法錯誤（多/少逗號、引號不閉合）會讓整個檔案被忽略；schema 紅線只是提醒，未必是真錯。
</Step>

<Step>
### 看 scope 和優先順序
你改的是 user，但 project 或 managed 已經寫了同名規則就會覆蓋。優先順序：managed > 命令列 > local > project > user。
</Step>

<Step>
### 檢查陣列合並
`permissions.allow` / `sandbox.allowWrite` / `enabledPlugins` 等陣列跨 scope 是拼接去重，不是替換。空陣列通常清不掉低優先順序。
</Step>

<Step>
### 按能力繼續定位
許可權相關 → `/permissions`；記憶相關 → `/memory`；安裝/環境相關 → `claude doctor`。
</Step>

<Step>
### 重開 session 驗證
某些欄位（如 `defaultMode`、`autoUpdatesChannel`）只在新會話生效。改完先 exit 再 `claude` 進。
</Step>

</Steps>

> [!TIP]
> **排障口訣**：先確認檔案被載入，再確認誰覆蓋誰，最後才看具體欄位是不是寫錯。

## 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。

> [!IMPORTANT]
> **過關標準**：你能拿一條真實配置，判斷它應該放 user、project、local 還是 managed，並能用 `/status` 解釋它為什麼生效或沒生效。

<details id="glossary">
<summary><b>本篇術語速查表</b></summary>

- Settings：設定。控制 Claude Code 行為的層級配置。
- Scope：作用域。配置歸屬和生效範圍。
- Managed：管理員配置。組織或機器級強制策略，不能被覆蓋。
- User：使用者配置。當前使用者所有專案的預設配置。
- Project：專案配置。儲存庫共享配置，應該提交給團隊。
- Local：本地配置。當前儲存庫當前機器私有配置，不提交。
- Precedence：優先順序。多個 scope（作用域）同時存在時誰覆蓋誰。
- Array merge：陣列合並。陣列欄位跨 scope 拼接去重，不是替換。
- `~/.claude.json`：全域性狀態檔案。儲存 OAuth、MCP user/local、project state 和快取。
- `CLAUDE.md`：專案說明檔案。存放專案規則、偏好和長期上下文。
- Managed policy：管理策略。企業級強制約束，如停用 bypass 或限制 marketplace。
- JSON schema：JSON 模式。給編輯器補全和校驗 settings 的 schema。

</details>

## 官方來源

- [Claude Code settings](https://code.claude.com/docs/en/settings)
- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config)
- [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory)
- [Configure permissions](https://code.claude.com/docs/en/permissions)

## 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/permissions" title="管理許可權" description="Settings 裡最常用、也最容易出風險的是 permissions（許可權）。下一章專門講 allow、ask、deny 和許可權模式。" />
  <Card href="/zh-Hant/docs/claude-code/official/00-getting-started/platforms" title="選擇平臺與整合（上一篇）" description="不同入口會影響配置在哪裡生效。CLI、Desktop、Web、Remote Control 的邊界要先分清。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/11-permissions" title="深度理解：許可權怎麼管" description="如果想看更完整的許可權心智模型，可以先讀理解篇的 Permissions。" />
</Cards>

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