管理許可權

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

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

Claude Code 做事靠工具。

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

官方 Configure permissions 文件給了一個基礎分層：

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

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

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

CLI 裡可以啟動時指定：

claude --permission-mode plan

也可以寫預設模式：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

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

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

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

官方規則順序是：

deny -> ask -> allow

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

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

一個專案級示例：

{
  "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、危險刪除、直接網路拉取預設拒絕。

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

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

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)：一個 * 可以跨多個引數。

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

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

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

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

複合命令會拆開檢查。

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

&&  ||  ;  |  |&  &  newline

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

safe-cmd && rm -rf .

Claude Code 會剝掉部分 process wrappers。

內建識別：

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

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

timeout 30 npm test

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

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

如果你寫：

Bash(devbox run *)

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

Bash(devbox run npm test)

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

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

四類路徑寫法：

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

最容易錯的是絕對路徑。

Read(/Users/alice/file)

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

真正的絕對路徑要寫：

Read(//Users/alice/file)

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

C:\Users\alice

會變成：

/c/Users/alice

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

Read(//**/.env)

還有 symlink 規則：

symlink 規則：

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

7. WebFetch 不等於網路隔離

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

它不控制 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 層限制網路域名。

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) 控制：

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

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 或關鍵系統路徑時仍會觸發提示。

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

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

claude --add-dir ../shared

會話中：

/add-dir ../shared

持久配置：

{
  "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：不會載入。

11. Managed policy：團隊安全底線

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

managed settings 可以強制：

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

示例：

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

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。

官方來源

• Configure permissions
• Choose a permission mode
• Sandboxing
• Security
• Claude Code settings

接下來去哪

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