---
title: "管理許可權"
description: "Claude Code 許可權不是一個總開關，而是控制 Bash、Read、Edit、WebFetch、MCP、Subagents 等工具呼叫的邊界。學會六種模式、deny/ask/allow、路徑規則和 sandbox（沙盒）配合。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

許可權配置的目標不是讓 Claude Code 少問，而是讓它在低風險動作上少問，在高風險動作上必須停下。少彈出視窗只是結果，邊界清楚才是目的。——Aaron

> [!NOTE]
> **這一章用 15 分鐘換什麼**：上一章講 settings（設定）放在哪裡。這一章講 settings 裡最重要的一類配置：permissions（許可權）。讀完你應該能為一個專案寫出低風險 allow、高風險 ask、敏感路徑 deny，並知道 Bash、WebFetch、MCP 和 sandbox（沙盒）的邊界差異。

## 1. 許可權管的是“工具呼叫”，不是 Claude 的想法

Claude Code 做事靠工具。

它讀檔案、改檔案、執行命令、抓網頁、呼叫 MCP、派 subagent，本質上都是一次 tool call。許可權系統管的就是這些 tool call 能不能發生、要不要問你。

官方 [Configure permissions](https://code.claude.com/docs/en/permissions) 文件給了一個基礎分層：

| 工具型別 | 例子 | 預設是否需要批准 |
|------|------|------|
| Read-only | file reads、Grep | 通常不需要 |
| Bash commands | shell execution | 需要 |
| File modification | Edit / Write | 需要 |

所以不要把許可權理解成“信任 Claude 還是不信任 Claude”。更準確是：

> [!IMPORTANT]
> **第一性原理**：許可權系統在回答“這次動作一旦發生，能不能自動承擔後果”。讀檔案、改檔案、跑命令、訪問外部系統的後果不一樣，邊界也應該不一樣。

| 階段 | Claude Code 在判斷什麼 | 可能結果 |
|------|-------------------------|----------|
| 1 | Claude 準備呼叫某個工具 | 進入許可權匹配 |
| 2 | 匹配 `deny`、`ask`、`allow` 規則 | 拒絕、詢問或允許 |
| 3 | 命中 `ask` | 等你確認後再執行 |
| 4 | 命中 `allow` | 直接執行 |
| 5 | 命中 `deny` | 直接阻止 |

## 2. 六種許可權模式：先定整體姿態

許可權模式決定一場會話裡 Claude Code 多常停下來問你。

| 模式 | 不問就能做什麼 | 適合什麼 |
|------|------|------|
| `default` | 讀檔案 | 新手、敏感專案、需要逐步審查 |
| `acceptEdits` | 讀檔案、檔案編輯、常見檔案系統命令 | 熟悉儲存庫、願意事後看 diff |
| `plan` | 讀檔案、探索，不直接改原始碼 | 複雜任務、陌生儲存庫、先審方案 |
| `auto` | 大多數動作自動執行，但有後臺安全檢查 | 長任務、減少提示疲勞 |
| `dontAsk` | 只允許預批准工具，其他自動拒絕 | CI、指令碼、鎖死環境 |
| `bypassPermissions` | 跳過許可權提示和安全檢查 | 僅限隔離容器 / VM |

CLI 裡可以啟動時指定：

```bash
claude --permission-mode plan
```

也可以寫預設模式：

```json
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}
```

`Shift+Tab` 預設迴圈 `default` → `acceptEdits` → `plan`。`dontAsk` 不在迴圈裡；`auto` 和 `bypassPermissions` 需要滿足條件或顯式啟用。

> [!CAUTION]
> **`bypassPermissions` 不是高手模式**：它會跳過許可權層，v2.1.126 起也包括寫 `.git`、`.claude`、`.vscode`、`.idea`、`.husky` 等 protected paths。只在壞了也無所謂的隔離環境用。

## 3. 三類規則：deny / ask / allow

模式是整體姿態，規則是具體邊界。

| 規則 | 含義 | 適合什麼 |
|------|------|------|
| `allow` | 匹配後自動允許 | 穩定、低風險、重複動作 |
| `ask` | 匹配後每次詢問 | 需要上下文判斷的動作 |
| `deny` | 匹配後直接阻止 | 金鑰、危險命令、敏感路徑、不可信工具 |

官方規則順序是：

```text
deny -> ask -> allow
```

第一條匹配規則生效，所以 deny 永遠優先：

```mermaid
flowchart TD
    Call[Claude 準備呼叫工具]
    Call --> CheckDeny{命中 deny?}
    CheckDeny -->|是| Block[直接阻止]
    CheckDeny -->|否| CheckAsk{命中 ask?}
    CheckAsk -->|是| Prompt[彈出視窗等你確認]
    CheckAsk -->|否| CheckAllow{命中 allow?}
    CheckAllow -->|是| Run[直接執行]
    CheckAllow -->|否| ModeFallback[按許可權模式預設行為]

    style Block fill:#fee2e2,stroke:#dc2626,stroke-width:2px
    style Prompt fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Run fill:#dcfce7,stroke:#16a34a,stroke-width:2px
    style ModeFallback fill:#e0e7ff,stroke:#4f46e5,stroke-width:2px
```

一個專案級示例：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)",
      "WebFetch(domain:docs.anthropic.com)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}
```

這份配置表達：

- lint / test / diff 可以自動做。
- push / publish 必須問。
- secrets、危險刪除、直接網路拉取預設拒絕。

> [!TIP]
> **新手寫法**：先寫 deny，再寫 ask，最後只給最確定的低風險動作 allow。不要為了省彈出視窗從 allow 開始寫。

## 4. 規則語法：`Tool` 或 `Tool(specifier)`

許可權規則格式只有兩類：

```text
Tool
Tool(specifier)
```

例子：

常見規則寫法：

- `Bash`：匹配所有 Bash。
- `Bash(*)`：等價於 `Bash`。
- `Bash(npm run build)`：精確匹配該命令。
- `Read(./.env)`：匹配當前目錄 `.env`。
- `WebFetch(domain:example.com)`：匹配 example.com 的 WebFetch。
- `Agent(Explore)`：匹配 Explore subagent。

Bash wildcard 細節：

- `Bash(ls *)`：匹配 `ls -la`，不匹配 `lsof`。
- `Bash(ls*)`：既可能匹配 `ls -la`，也可能匹配 `lsof`。
- `Bash(ls:*)`：結尾 `:*` 等價於尾部 ` *`。
- `Bash(git * main)`：一個 `*` 可以跨多個引數。

> [!WARNING]
> **空格很重要**：`Bash(ls *)` 和 `Bash(ls*)` 風險不同。寫 Bash 規則時不要隨手省空格。

## 5. Bash 是最容易誤配的工具

Bash 不是普通工具。它可以：

- 讀檔案。
- 改檔案。
- 刪除檔案。
- 聯網。
- 執行指令碼。
- 調 docker、npx、devbox、mise 等二級執行器。

官方文件裡有幾個關鍵事實。

**複合命令會拆開檢查。**

這些分隔符會拆成多個子命令：

```text
&&  ||  ;  |  |&  &  newline
```

規則必須匹配每個子命令。也就是說，允許 `safe-cmd` 不等於允許：

```bash
safe-cmd && rm -rf .
```

**Claude Code 會剝掉部分 process wrappers。**

內建識別：

```text
timeout, time, nice, nohup, stdbuf, bare xargs
```

所以 `Bash(npm test *)` 也可能匹配：

```bash
timeout 30 npm test
```

但這些不在可剝離列表裡：

```text
direnv exec, devbox run, mise exec, npx, docker exec
```

如果你寫：

```text
Bash(devbox run *)
```

它可能覆蓋 `devbox run rm -rf .`。更好的寫法是精確到內部命令：

```text
Bash(devbox run npm test)
```

> [!IMPORTANT]
> **Bash 規則原則**：能精確就精確，能 ask 就別 allow。尤其不要給執行器、包管理器、容器命令寫過寬字首。

## 6. Read / Edit 路徑規則怎麼寫

`Read` 和 `Edit` 路徑規則遵循 gitignore 風格，並有四類路徑。

四類路徑寫法：

- `//path`：檔案系統絕對路徑。
- `~/path`：home 目錄相對路徑。
- `/path`：project root 相對路徑。
- `path` 或 `./path`：當前目錄相對路徑。

最容易錯的是絕對路徑。

```text
Read(/Users/alice/file)
```

這不是檔案系統絕對路徑，而是專案根目錄下的 `Users/alice/file`。

真正的絕對路徑要寫：

```text
Read(//Users/alice/file)
```

Windows 會被規範化成 POSIX 風格，比如：

```text
C:\Users\alice
```

會變成：

```text
/c/Users/alice
```

所以跨盤匹配 `.env` 可以用：

```text
Read(//**/.env)
```

還有 symlink 規則：

symlink 規則：

- allow：symlink 路徑和目標都匹配才允許，否則提示。
- deny：symlink 路徑或目標任一匹配就阻止。

> [!CAUTION]
> **路徑 deny 不是系統沙盒**：`Read(./.env)` 阻止 Claude 的 Read tool，不阻止 Bash 子程序執行 `cat .env`。高敏感檔案要配合 Bash deny、sandbox 和系統許可權。

## 7. WebFetch 不等於網路隔離

`WebFetch(domain:example.com)` 只控制 Claude Code 的 WebFetch 工具。

它不控制 Bash 裡的：

```bash
curl
wget
python -c 'requests.get(...)'
node fetch(...)
```

官方文件也明確提醒：using WebFetch alone does not prevent network access。

可靠做法是組合：

- WebFetch：只允許可信域名。
- Bash deny：禁止 `curl`、`wget` 等網路工具。
- PreToolUse Hook：對 Bash 裡的 URL 做更細檢查。
- sandbox network：從 OS / proxy 層限制網路域名。

> [!WARNING]
> **不要用 `Bash(curl https://github.com *)` 當網路白名單**：curl 引數、重定向、變數、協議變化都可能繞過你的直覺。更穩的是禁 Bash 網路工具，用 WebFetch 或 sandbox 網路規則。

## 8. MCP 和 Subagents 也要寫許可權

MCP server 可能連線資料庫、issue 系統、雲服務、瀏覽器和內部 API。不要因為它不是 Bash，就預設安全。

MCP 規則示例：

- `mcp__github`：匹配 github server 的所有工具。
- `mcp__github__*`：同樣匹配該 server 所有工具。
- `mcp__github__create_issue`：只匹配一個具體工具。

更穩的做法：

- 探索型只讀工具可以 allow。
- 寫遠端狀態的工具先 ask。
- 刪除、釋出、授權類工具儘量 deny 或 managed。
- 不要對整個 MCP server 粗暴 allow，除非你確認所有 tool 都低風險。

Subagent 用 `Agent(AgentName)` 控制：

```json
{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}
```

> [!TIP]
> **判斷標準**：凡是能改變遠端系統、建立 PR、釋出內容、修改資料庫、操作瀏覽器登入態的 MCP tool，都不應該預設 allow。

## 9. sandbox（沙盒）和 permissions（許可權）怎麼配合

Permissions 和 sandbox 是兩層。

兩層邊界：

- Permissions：管理所有工具，包括 Bash、Read、Edit、WebFetch、MCP、Agent。
- sandbox：管理 Bash 及其子程序的檔案系統和網路訪問。

官方 sandbox 文件說，sandboxed bash tool 使用 OS-level primitives：

- macOS：Seatbelt。
- Linux / WSL2：bubblewrap。

它能限制 Bash 子程序能讀寫哪些路徑、能訪問哪些網路域名。

關鍵互動：

- deny rules 仍然生效。
- sandbox 檔案系統限制使用 Read / Edit deny rules，不是完全獨立的一套檔案規則。
- 網路限制組合 WebFetch permission rules 和 sandbox `allowedDomains` / `deniedDomains`。
- `autoAllowBashIfSandboxed: true` 預設啟用時，sandboxed Bash 命令會自動允許，即使 `ask: Bash(*)` 存在。
- `rm` / `rmdir` 指向 `/`、home 或關鍵系統路徑時仍會觸發提示。

> [!IMPORTANT]
> **一句話理解**：permissions 決定 Claude 能不能嘗試呼叫工具；sandbox 決定 Bash 真跑起來後能不能越界。兩者不是替代關係。

## 10. `additionalDirectories` 只加檔案訪問，不加完整配置根

你可以擴充套件 Claude Code 的檔案訪問範圍：

```bash
claude --add-dir ../shared
```

會話中：

```text
/add-dir ../shared
```

持久配置：

```json
{
  "additionalDirectories": ["../shared"]
}
```

但官方許可權文件有一個重要邊界：additional directories grant file access, not configuration。

這意味著：

`--add-dir` 的載入邊界：

- `.claude/skills/`：會載入，支援 live reload。
- `.claude/settings.json` 裡的 plugin settings：只載入 `enabledPlugins` 和 `extraKnownMarketplaces`。
- `CLAUDE.md` / `.claude/rules/` / `CLAUDE.local.md`：需要 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。
- subagents / commands / output styles / hooks / 其他 settings：不會載入。

> [!WARNING]
> **不要誤會 add-dir**：它主要是“多給 Claude 看一個目錄”，不是“把另一個專案的 `.claude/` 完整掛進來”。

## 11. Managed policy：團隊安全底線

團隊和企業不要只靠個人自覺。

managed settings 可以強制：

- 禁止 bypass。
- 禁止 auto。
- 只允許 managed permission rules。
- 限制 MCP servers。
- 限制 channel plugins。
- 限制 marketplace。
- 只允許 managed hooks。

示例：

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

> [!CAUTION]
> **managed 適合底線，不適合細節**：全組織禁止危險動作很合理；把某個專案的臨時 lint 命令寫進 managed 就會汙染所有團隊。

## 12. 本章自檢

試著用自己的話回答：

1. 許可權系統管的是 Claude 的想法，還是 tool call？對應 §1。
2. `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 各適合什麼？對應 §2。
3. 為什麼 `Bash(devbox run *)` 比 `Bash(devbox run npm test)` 風險更高？對應 §5。
4. `Read(//Users/alice/file)` 和 `Read(/Users/alice/file)` 有什麼區別？對應 §6。
5. WebFetch、Bash 網路命令和 sandbox 網路規則分別管什麼？對應 §7-§9。

> [!IMPORTANT]
> **過關標準**：你能為一個真實專案寫出三條 allow、兩條 ask、三條 deny，並能解釋每條規則對應的風險邊界。

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

- Permission：許可權。控制 Claude Code tool call 能不能執行的規則體系。
- Permission mode：許可權模式。一場會話的整體審批策略。
- `allow`：允許規則。匹配後自動執行，不詢問。
- `ask`：詢問規則。匹配後要求人工確認。
- `deny`：拒絕規則。匹配後直接阻止。
- Bash rule：Bash 許可權規則。控制 shell 命令是否能執行。
- Read / Edit rule：檔案路徑規則。控制檔案讀寫工具能訪問哪些路徑。
- WebFetch：網頁抓取工具。Claude Code 內建的網頁讀取工具，不等同於全域性網路控制。
- MCP permission：MCP 許可權。控制 MCP server 或具體 MCP tool 是否可用。
- Agent permission：Subagent 許可權。控制 Claude 能否呼叫指定 subagent。
- sandbox：沙盒。OS 層限制 Bash 及其子程序檔案和網路訪問。
- Protected paths：受保護路徑。`.git`、`.claude`、`.vscode` 等不應自動修改的位置。
- Managed policy：管理策略。企業或組織下發的不可覆蓋安全邊界。

</details>

## 官方來源

- [Configure permissions](https://code.claude.com/docs/en/permissions)
- [Choose a permission mode](https://code.claude.com/docs/en/permission-modes)
- [Sandboxing](https://code.claude.com/docs/en/sandboxing)
- [Security](https://code.claude.com/docs/en/security)
- [Claude Code settings](https://code.claude.com/docs/en/settings)

## 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/memory" title="使用記憶機制" description="許可權決定 Claude 能做什麼，記憶決定 Claude 每次開始時知道什麼。下一章講 CLAUDE.md 和 auto memory。" />
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/settings" title="配置 Claude Code（上一篇）" description="許可權規則寫在哪個 scope（作用域），直接決定團隊能不能復現、管理員能不能強制執行。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/11-permissions" title="深度理解：該給 AI 多少許可權" description="如果想看許可權背後的信任層級和成本邊界，讀理解篇的 Permissions。" />
</Cards>

如果只記一個判斷：**許可權不是為了少彈出視窗，而是為了把 Claude Code 的每一次工具行動放在可解釋、可審查、可強制的邊界裡。**
