設定權限

權限系統

在回答權限提示時新增評論

• Enter：提交您的答案並附加評論。如果您將欄位留空，Claude Code 會提交答案而不附加評論。
• Tab：關閉欄位而不回答。Claude Code 保留您輸入的文字，如果您使用該選項回答，仍會傳送它。
• Shift+Tab：在檔案權限提示上，例如 Edit 或 Write 權限提示，與 Tab 相同，會關閉欄位。在 v2.1.235 之前，在欄位內按 Shift+Tab 會改為選擇允許操作用於工作階段其餘部分的選項，因此 Claude Code 會核准該操作用於工作階段其餘部分並捨棄評論。

• 是：Claude Code 執行操作，然後在結果之後將您的評論傳送給 Claude。
• 否：Claude Code 將您的評論作為拒絕原因傳送給 Claude，Claude 繼續工作。如果您在主對話的權限提示上選擇否而沒有評論，Claude Code 會停止該回合。

管理權限

• Allow 規則讓 Claude Code 使用指定的工具，無需手動批准。
• Ask 規則在 Claude Code 嘗試使用指定工具時提示確認。
• Deny 規則防止 Claude Code 使用指定的工具。

權限模式

權限規則語法

符合工具的所有使用

使用指定符進行細粒度控制

按輸入參數進行符合

• 參數名稱必須是工具輸入的直接欄位，例如 Agent 工具上的 model。巢狀在物件或陣列內的欄位不可符合
• 每個規則命名一個參數。若要在 model 和 isolation 上設定閘道，請寫入兩個規則 Agent(model:opus) 和 Agent(isolation:worktree)，而不是在一個規則中組合它們
• 值支援 * 作為符合任何字元序列的萬用字元，因此 Agent(isolation:*) 符合任何明確的隔離值。沒有 * 時，符合是確切的
• 模型省略的參數永遠不會被符合，因此 Agent(model:*) 不符合留下 model 未設定的呼叫
• 值與 Claude 傳送的字面輸入進行比較，在任何正規化之前。Agent(model:opus) 符合別名 opus 但不符合完整模型 ID
• Skill(skill:<name>) 拒絕規則改為符合該技能在其任何名稱下，例如其別名或顯示名稱
• 使用 --verbose 執行以查看每個工具呼叫中的確切參數名稱和值
• 冒號周圍的空格被忽略

萬用字元模式

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

• * 代表其位置中的任何文字。 在 Bash(git * main) 中，它代表子命令，因此 Claude Code 符合每個 git 子命令和它之前的每個選項。這包括 -c，它使 git 執行您命名的程式。在 Bash(* --version) 中，* 代表程式，因此任何程式都符合。
• 末尾的 *（前面有空格）也符合裸命令。 Bash(ls *) 符合 ls，而 Bash(git log *) 符合 git log。這僅在尾部 * 是規則的唯一萬用字元時成立：Bash(* --help *) 符合 npm --help x 但不符合 npm --help。
• 尾部 * 前的空格是規則的一部分。 Bash(ls *) 在 ls 後需要空格，因此 lsof 不符合。Bash(ls*) 沒有空格，因此它也符合 lsof。

工具名稱萬用字元

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

特定工具的權限規則

Bash

複合命令

包裝器

Exec 包裝器與 find 動作

• Exec 包裝器：例如 watch、setsid、ionice 與 flock
• find：帶有會執行命令、刪除檔案或寫入檔案的動作，例如 -exec、-delete、-rm 或 -fprint，或帶有 -files0-from（它會從檔案讀取要搜尋的路徑）

Bash 規則不會比對的內容

唯讀命令

• 具有可寫入旗標之命令的未加引號 glob：具有可寫入或可執行旗標的命令，例如 find、sort、sed 與 git，在出現未加引號的 glob 時會提示，因為 glob 可能展開成像 -delete 這樣的旗標。
• 指向其他 daemon 的 docker：當命令帶有選擇不同 daemon 的旗標時，例如 -H、--context，或 Podman 的 --url 與 --connection，docker 的唯讀形式會提示。
• 帶有開啟路徑旗標的 file：當 file 傳入 -m/--magic-file 或 -f/--files-from 時會提示，因為這些旗標會讓 file 開啟旗標值中所指定的路徑。
• 可能印出環境變數的 ps：當 ps 的某個引數可能作為 e 選項時會提示，例如 ps auxe 或 ps aux -e，因為該選項會印出程序的環境變數。ps aux 與 ps -ef 會不經提示即執行。對 ps aux -e 等帶連字號形式的檢查需要 Claude Code v2.1.290 或更新版本。
• 帶有查詢與顯示以外旗標的 which：當 which 傳入 -i/--read-alias 或 --read-functions 等旗標時會提示。which node 與 which -a node 會不經提示即執行。
• Windows 上的網路路徑：引數包含網路（UNC）路徑（例如 \\server\share\file）的命令會提示，因為存取網路路徑可能會將您的 Windows 憑證傳送給其所指定的主機。相同的檢查也適用於 PowerShell 工具命令。
• 寫入特殊 shell 變數：設定、取消設定或迴圈遍歷某些特殊 shell 變數（例如 PATH 或 IFS）的命令，即使命令的其餘部分為唯讀也會提示。
• 分析無法解析的命令：當 Claude Code 無法完整解析某個命令時，它會要求核准，而不是將該命令視為唯讀。超過 10,000 個字元的命令一律會提示，因為它們超出分析所能解析的範圍。

• cd 搭配 git：當 cd 切換到不同目錄時會提示，因為在新目錄中執行 git 可能會執行該目錄的 hook。目標解析為目前工作目錄的 cd 不會產生任何作用，也不會觸發提示。
• cd 搭配重新導向：當 Claude Code 無法判斷 cd 執行後重新導向目標會相對於哪個目錄解析時會提示。唯一重新導向目標為 /dev/null 的命令，例如 cd app; grep -r pattern . 2>/dev/null，不會提示，因為 /dev/null 不依賴工作目錄。

重新導向

• 輸出重新導向：對於 > file、>> file 或 2> file，檢查涵蓋您的 Edit 允許與拒絕規則、受保護路徑以及工作目錄。像 Bash(git commit *) 這樣的規則允許的是命令，而非目標。以 ~ 開頭或包含 glob 字元的目標需要您的核准。
• 輸入重新導向：對於 < file，檢查涵蓋您的 Read 允許與拒絕規則以及工作目錄。工作目錄外部的目標需要您的核准，除非有允許規則涵蓋它。包含 glob 模式的目標，或在同一命令中位於 cd 之後的相對路徑，即使有允許規則涵蓋也需要您的核准。Claude Code 在 v2.1.257 及更新版本中會檢查輸入目標。

PowerShell

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

Read 和 Edit

Read 與 Edit 規則涵蓋的範圍

• 圖片路徑：當您在終端機中將圖片路徑貼上或將圖片檔案拖曳到提示詞中，且規則比對到該路徑時，Claude Code 不會附加該圖片。如果貼上的內容中沒有其他圖片，該路徑會以文字形式保留在您的提示詞中。
• 目錄：Claude 收到的清單會省略規則比對到的檔案與目錄名稱。

Write(path)、Glob(path) 與 Grep(path) 規則不會比對

• Write、NotebookEdit 或舊版 MultiEdit：使用 Edit(docs/**) 取代 Write(docs/**)。
• Glob 或 Grep：使用 Read(docs/**) 取代 Grep(docs/**)。作為詢問規則時，Read(docs/**) 會在 Claude 對符合的路徑呼叫 Grep 或 Glob 時提示，但當對其上層工作目錄的搜尋傳回符合的檔案時則不會提示。

路徑模式如何比對

模式錨定的位置

• Edit(/docs/**)：編輯 <primary working directory>/docs/ 中的內容，而不是 /docs/ 或 <primary working directory>/.claude/docs/
• Read(~/.zshrc)：讀取您家目錄的 .zshrc
• Edit(//tmp/scratch.txt)：編輯絕對路徑 /tmp/scratch.txt
• Read(src/**)：作為允許規則時，只讀取 <current-directory>/src/；作為拒絕或詢問規則時，會比對目前目錄下任何深度的 src 目錄

模式比對的深度

• 允許規則：Edit(src/**) 只比對 <cwd>/src 及其下的檔案。若要允許任何深度的目錄名稱，請撰寫 Edit(**/src/**)。
• 拒絕與詢問規則：Read(secrets/**) 會比對目前目錄下任何深度名為 secrets 的目錄，因此該規則也適用於巢狀的副本。

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js

特殊字元與 ! 否定

• 即使 ! 後面接著 /、~/ 或 //，Claude Code 仍會相對於目前目錄解讀 ! 模式，因此該模式無法影響以這些前綴錨定的規則。Read(!~/notes/public/**) 不會從 Read(~/notes/**) 中排除任何內容。
• 排除無法重新開放被規則整體封鎖之目錄內的檔案。在 Read(secrets/**) 與 Read(!secrets/public/**) 的情況下，Claude Code 仍會封鎖 secrets/public 以及 secrets 的其餘部分。

符號連結

規則如何比對經符號連結的路徑

• 允許規則：只有在請求的路徑與其解析後的檔案都符合時才會套用。透過允許目錄內、指向該目錄外部的符號連結所進行的讀取，不符合該規則。
• 拒絕規則：只要請求的路徑或其解析後的檔案任一符合就會套用。指向被拒絕檔案的符號連結本身也會被拒絕。例如，在允許 Read(./project/**) 且拒絕 Read(~/.ssh/**) 的情況下，位於 ./project/key 且指向 ~/.ssh/id_rsa 的符號連結會被封鎖：目標不符合允許規則，且符合拒絕規則。

經由符號連結的附件

• @ 提及：您在提示詞中提及的檔案或目錄。被拒絕的檔案不會在對話中留下任何內容，而目錄的清單會省略規則所涵蓋的名稱。
• 貼上的圖片：您在終端機中將其路徑貼上或拖曳到提示詞中的圖片
• 已變更的檔案：Claude Code 在磁碟上的檔案變更後重新讀取的檔案
• IDE 脈絡：已連線 IDE 共用的選取內容與開啟檔案脈絡

Referenced <path> (not read: could not be examined)

經由符號連結的寫入

• 解析至工作目錄外部：當請求的路徑位於您的工作目錄內，而其解析後的檔案不在其中時，該寫入在 acceptEdits 模式下不會被自動核准。在自動模式下，除非有允許規則核准該寫入，否則會提示您，而不是由分類器決定。提示會指明寫入所解析到的路徑。
• 解析至請求路徑未指名的受保護路徑：受保護路徑表格列出了每種權限模式下的結果，但在表格將寫入交由分類器處理之處，此類寫入會改為提示您。

無法解析或會變更的路徑

網路路徑

• 允許規則：規則不會預先核准該讀取，包括針對整個工具的規則，例如 Read
• PreToolUse hook：回傳 "allow" 的 hook 不會略過提示
• 自動模式：提示會交給您，而分類器不會決定該讀取

• Windows：將共用對應至磁碟機代號，並在啟動 Claude Code 時以 --add-dir 傳入該磁碟機，如工作目錄所述。對於對應至 Z: 的共用，請在 PowerShell 中執行 claude --add-dir Z:\。
• macOS 與 Linux：將共用掛載至本機路徑，例如 /mnt 或 /Volumes 下的目錄，並從該處讀取檔案，如工作目錄是網路路徑所述

WebFetch

• WebFetch(domain:example.com) 只比對對 example.com 的請求。若也要涵蓋 api.example.com 等子網域，請新增 WebFetch(domain:*.example.com) 規則
• WebFetch(domain:*.example.com) 會比對任何深度的子網域，例如 api.example.com 或 a.b.example.com，但不包括 example.com 本身
• WebFetch(domain:*) 會比對每個網域。它與不帶參數的 WebFetch 規則不同；請參閱允許或拒絕每次擷取

允許或拒絕每次擷取

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

MCP

• mcp__puppeteer 會比對 puppeteer 伺服器提供的任何工具
• mcp__puppeteer__* 使用萬用字元語法，同樣會比對 puppeteer 伺服器的所有工具
• mcp__puppeteer__puppeteer_navigate 會比對 puppeteer 伺服器提供的 puppeteer_navigate 工具

• 包含 . 或空格等字元的名稱：這些字元會變成 _，因此對於您設定為 my.server 的伺服器，請撰寫 mcp__my_server__*
• 由外掛提供的伺服器：<server> 採用外掛範圍形式，因此對於名為 my-plugin 之外掛中的 database-tools 伺服器，請撰寫 mcp__plugin_my-plugin_database-tools__*
• 包含 __ 或以 _ 結尾的 <server>：請以完整名稱撰寫萬用字元形式 mcp__<server>__*。對於名為 reports__v2 的伺服器，請撰寫 mcp__reports__v2__*。不帶參數的 mcp__reports__v2 與較短的 mcp__reports 作為允許規則時不會比對其工具，因為 Claude Code 會將兩者都解讀為名為 reports 之伺服器的規則。 不過，作為拒絕或詢問規則時，這兩個名稱也都會涵蓋 reports__v2 伺服器的每個工具。若只要涵蓋名為 reports 的伺服器，請以 mcp__reports__<tool> 形式為每個工具各撰寫一條規則，或重新命名其中一個伺服器。

Agent (subagents)

• Agent(Explore) 會比對 Explore subagent
• Agent(Plan) 會比對 Plan subagent
• Agent(my-custom-agent) 會比對名為 my-custom-agent 的自訂 subagent

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

Cd

使用 hooks 擴展權限

規則、hook 與 mod 之間的優先順序

• deny 規則拒絕的呼叫仍會被拒絕。
• ask 規則會提示的呼叫仍會提示您。
• PreToolUse hook 或 permissions.blockReadsOutsideWorkingDirectories 會提示的呼叫仍會提示您。
• PreToolUse hook 阻止的呼叫仍會被阻止，無論該 hook 來自哪個設定檔。
• 您的 --permission-prompt-tool 或 Agent SDK canUseTool 回呼會被詢問的呼叫，仍會交由該工具或回呼處理。

• 自動模式：mod 核准的呼叫會在沒有分類器檢查的情況下執行，除非 mod 無法繞過您的權限提示工具或 Agent SDK 權限回呼。在那種情況下，分類器會先檢查該呼叫。
• Plan mode：mod 無法核准非唯讀的呼叫，例如檔案編輯或會寫入的 shell 命令。
• dontAsk 模式：mod 可以核准除了該模式本身之外沒有其他機制會拒絕的呼叫。

plan mode 中的 hook 核准

工作目錄

• 在啟動期間：使用 --add-dir <path> CLI 引數
• 在工作階段期間：使用 /add-dir 命令
• 持久設定：新增到 settings files 中的 additionalDirectories

封鎖工作目錄外的檔案工具讀取和寫入

• permissions.blockReadsOutsideWorkingDirectories：檔案工具會拒絕讀取該處的檔案，但 Claude Code 本身需要的檔案除外。在自動模式中，Claude Code 會在 Claude 首次讀取工作目錄外的檔案時提供開啟它的選項。
• permissions.blockWritesOutsideWorkingDirectories：Write、Edit 和 NotebookEdit 工具會拒絕寫入該處，但 Claude Code 自己的某些檔案（例如計畫檔案）除外。此設定鍵不會限制 shell 命令、MCP 工具或 hook 執行的程式，因此請使用沙箱機制來限制 shell 命令的寫入位置。需要 Claude Code v2.1.314 或更新版本。

將工作階段移動到另一個目錄

• 其專案設定，包括其權限規則和 hooks
• 其 .mcp.json 伺服器，受限於與啟動時相同的伺服器核准，以及您在其中註冊的本機範圍 MCP 伺服器
• 其設定啟用的 plugins、其 skills 和其 subagents
• 其 env 值，套用在前一個目錄設定的環境變數之上，這些變數保持有效

其他目錄授予檔案存取權，而非設定

輸出風格、hooks 和本機設定的載入位置

• 使用者級別設定：將檔案放在 ~/.claude/agents/、~/.claude/output-styles/ 或 ~/.claude/settings.json 中，使其在每個專案中可用
• Plugins：將設定打包並分發為 plugin，供團隊安裝
• 從設定目錄啟動：從包含您想要的 .claude/ 設定的目錄執行 Claude Code

權限如何與沙箱互動

• 權限控制 Claude Code 可以使用哪些工具以及它可以存取哪些檔案或網域。它們適用於 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 規則無法阻止 EndConversation，而任何其他工具仍然存在。
• 沙箱提供作業系統級別的強制執行，限制 shell 命令的檔案系統和網路存取。它適用於 Bash、PowerShell 和 Monitor 工具命令及其子程序。

• 內容範圍的 ask 規則（如 Bash(git push *)）仍然強制提示
• 其他沙箱化命令也可能通過常規權限流程，如 Auto-allow mode 所述

受管理設定

設定優先順序

專案允許規則和工作區信任

• 在儲存庫中，Claude Code 會以 git 儲存庫根目錄作為信任的鍵，因此信任涵蓋整個儲存庫，除了任何巢狀在其中的 git 儲存庫（例如子模組）。在 worktree 中，它使用主簽出的根目錄，就像它對已儲存規則所做的一樣。
• 在儲存庫外，Claude Code 會以您啟動它的目錄作為信任的鍵，信任涵蓋該目錄的任何子目錄，除了巢狀在其中的 git 儲存庫（例如複製）。每個涵蓋的子目錄隨後都會計為一個您信任其父目錄的資料夾。
• 當您在家目錄中啟動時，Claude Code 只在目前工作階段內保持信任，不會將其寫入磁碟；請參閱額外保護措施說明。

當您的本機設定檔案需要信任時

• 在您的設定主目錄中： Claude Code 會立即套用該資料夾的 .claude/settings.local.json，無需執行 git。您的設定主目錄是您的家目錄，或是其 .claude 子目錄已被您設定為 CLAUDE_CONFIG_DIR 的目錄。如果該 CLAUDE_CONFIG_DIR 目錄位於 git 儲存庫內，且 Claude Code 改為將您的本機設定保留在儲存庫根目錄，它會像在其他地方一樣暫不套用這些規則。
• 其他任何地方： Claude Code 會像對待專案設定一樣暫不套用該檔案的規則。檢查執行後，Claude Code 會套用未追蹤檔案的規則，或位於任何 git 儲存庫外的目錄中的檔案的規則，即使您尚未信任該確切資料夾。

您信任資料夾前執行的內容

• 傳遞 --setting-sources user，或設定 SDK 的 settingSources 而不包含專案設定，以便 Claude Code 既不讀取專案的設定檔案也不讀取其 .mcp.json
• 使用 --bare 啟動，以便 Claude Code 不從專案讀取任何 hook、skill、自訂命令、subagent、外掛或 .mcp.json 伺服器。專案的 env 區塊和輔助程式（例如其設定檔案中的 awsAuthRefresh）仍然適用，Claude Code 只從 --settings 讀取 apiKeyHelper
• 傳遞 --settings '{"disableAllHooks": true}' 以關閉該執行的 hook。僅在您的使用者設定中設定它是不夠的，因為儲存庫的專案設定優先於您的設定，並且可以將其設定回 false
• 新增 disabledMcpjsonServers 項目以在每個工作階段類型中按名稱拒絕 .mcp.json 伺服器

範例設定

另請參閱

• 所有設定：每個設定鍵，包括權限鍵
• 設定自動模式：告訴自動模式分類器您的組織信任哪些基礎設施
• 沙箱隔離：Bash 命令的作業系統級別檔案系統和網路隔離
• 驗證：設定使用者對 Claude Code 的存取
• 安全性：安全防護措施和最佳實踐
• Hooks：自動化工作流程並擴展權限評估