Claude Code 支援細粒度權限,讓您可以精確指定代理允許執行和不允許執行的操作。權限設定可以簽入版本控制並分發給組織中的所有開發人員,也可以由個別開發人員自訂。
權限系統
Claude Code 使用分層權限系統來平衡功能和安全性:
| 工具類型 | 範例 | 需要批准 | ”是,不要再問”行為 |
|---|
| 唯讀 | 檔案讀取、Grep | 否 | 不適用 |
| Bash 命令 | Shell 執行 | 是 | 每個專案目錄和命令永久有效 |
| 檔案修改 | Edit/Write 檔案 | 是 | 直到工作階段結束 |
管理權限
您可以使用 /permissions 檢視和管理 Claude Code 的工具權限。此 UI 列出所有權限規則及其來源的 settings.json 檔案。
- Allow 規則讓 Claude Code 使用指定的工具,無需手動批准。
- Ask 規則在 Claude Code 嘗試使用指定工具時提示確認。
- Deny 規則防止 Claude Code 使用指定的工具。
規則按順序評估:deny -> ask -> allow。第一個符合的規則獲勝,因此 deny 規則始終優先。
權限模式
Claude Code 支援多種權限模式來控制工具的批准方式。請參閱權限模式以了解何時使用每一種。在您的設定檔案中設定 defaultMode:
| 模式 | 描述 |
|---|
default | 標準行為:在首次使用每個工具時提示權限 |
acceptEdits | 自動接受工作階段的檔案編輯權限 |
plan | Plan Mode:Claude 可以分析但不能修改檔案或執行命令 |
auto | 自動批准工具呼叫,並進行背景安全檢查以驗證操作是否符合您的要求。目前為研究預覽版 |
dontAsk | 自動拒絕工具,除非透過 /permissions 或 permissions.allow 規則預先批准 |
bypassPermissions | 跳過權限提示,除了對受保護目錄的寫入(請參閱下方警告) |
bypassPermissions 模式會跳過權限提示。對 .git、.claude、.vscode 和 .idea 目錄的寫入仍會提示確認,以防止意外損壞儲存庫狀態和本機設定。對 .claude/commands、.claude/agents 和 .claude/skills 的寫入被豁免,不會提示,因為 Claude 在建立技能、子代理和命令時會定期寫入這些位置。僅在隔離環境(如容器或虛擬機)中使用此模式,其中 Claude Code 無法造成損害。管理員可以透過在受管理設定中將 disableBypassPermissionsMode 設定為 "disable" 來防止此模式。
若要防止 bypassPermissions 或 auto 模式被使用,請在任何設定檔案中將 permissions.disableBypassPermissionsMode 或 disableAutoMode 設定為 "disable"。這些在受管理設定中最有用,因為它們無法被覆蓋。
權限規則語法
權限規則遵循格式 Tool 或 Tool(specifier)。
符合工具的所有使用
若要符合工具的所有使用,請使用不帶括號的工具名稱:
| 規則 | 效果 |
|---|
Bash | 符合所有 Bash 命令 |
WebFetch | 符合所有網頁擷取請求 |
Read | 符合所有檔案讀取 |
Bash(*) 等同於 Bash 並符合所有 Bash 命令。
使用指定符進行細粒度控制
在括號中新增指定符以符合特定工具使用:
| 規則 | 效果 |
|---|
Bash(npm run build) | 符合確切命令 npm run build |
Read(./.env) | 符合讀取目前目錄中的 .env 檔案 |
WebFetch(domain:example.com) | 符合對 example.com 的擷取請求 |
萬用字元模式
Bash 規則支援使用 * 的 glob 模式。萬用字元可以出現在命令中的任何位置。此設定允許 npm 和 git commit 命令,同時阻止 git push:
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git commit *)",
"Bash(git * main)",
"Bash(* --version)",
"Bash(* --help *)"
],
"deny": [
"Bash(git push *)"
]
}
}
* 前的空格很重要:Bash(ls *) 符合 ls -la 但不符合 lsof,而 Bash(ls*) 兩者都符合。舊版 :* 後綴語法等同於 * 但已棄用。
工具特定的權限規則
Bash
Bash 權限規則支援使用 * 的萬用字元符合。萬用字元可以出現在命令中的任何位置,包括開頭、中間或結尾:
Bash(npm run build) 符合確切的 Bash 命令 npm run build
Bash(npm run test *) 符合以 npm run test 開頭的 Bash 命令
Bash(npm *) 符合任何以 npm 開頭的命令
Bash(* install) 符合任何以 install 結尾的命令
Bash(git * main) 符合命令如 git checkout main、git merge main
當 * 出現在末尾且前面有空格時(如 Bash(ls *)),它會強制執行字邊界,要求前綴後面跟著空格或字串結尾。例如,Bash(ls *) 符合 ls -la 但不符合 lsof。相比之下,Bash(ls*) 沒有空格會同時符合 ls -la 和 lsof,因為沒有字邊界限制。
Claude Code 知道 shell 運算子(如 &&),所以前綴符合規則如 Bash(safe-cmd *) 不會給它執行命令 safe-cmd && other-cmd 的權限。
當您使用”是,不要再問”批准複合命令時,Claude Code 會為每個需要批准的子命令儲存一個單獨的規則,而不是為完整複合字串儲存單一規則。例如,批准 git status && npm test 會為 npm test 儲存一個規則,因此未來的 npm test 呼叫會被識別,無論 && 前面是什麼。子命令如 cd 進入子目錄會為該路徑產生自己的 Read 規則。單一複合命令最多可能儲存 5 個規則。
嘗試限制命令引數的 Bash 權限模式很脆弱。例如,Bash(curl http://github.com/ *) 旨在將 curl 限制為 GitHub URL,但不會符合以下變化:
- URL 前的選項:
curl -X GET http://github.com/...
- 不同的協定:
curl https://github.com/...
- 重新導向:
curl -L http://bit.ly/xyz(重新導向到 github)
- 變數:
URL=http://github.com && curl $URL
- 額外空格:
curl http://github.com
為了更可靠的 URL 篩選,請考慮:
- 限制 Bash 網路工具:使用 deny 規則阻止
curl、wget 和類似命令,然後使用 WebFetch 工具搭配 WebFetch(domain:github.com) 權限以允許的網域
- 使用 PreToolUse hooks:實作一個 hook 來驗證 Bash 命令中的 URL 並阻止不允許的網域
- 透過 CLAUDE.md 指示 Claude Code 關於您允許的 curl 模式
請注意,單獨使用 WebFetch 不會防止網路存取。如果允許 Bash,Claude 仍然可以使用 curl、wget 或其他工具來存取任何 URL。
Read 和 Edit
Edit 規則適用於所有編輯檔案的內建工具。Claude 會盡力嘗試將 Read 規則應用於所有讀取檔案的內建工具,如 Grep 和 Glob。
Read 和 Edit deny 規則適用於 Claude 的內建檔案工具,不適用於 Bash 子程序。Read(./.env) deny 規則會阻止 Read 工具,但不會防止 Bash 中的 cat .env。為了進行作業系統級別的強制執行,以阻止所有程序存取路徑,請啟用沙箱。
Read 和 Edit 規則都遵循 gitignore 規格,具有四種不同的模式類型:
| 模式 | 意義 | 範例 | 符合 |
|---|
//path | 來自檔案系統根目錄的絕對路徑 | Read(//Users/alice/secrets/**) | /Users/alice/secrets/** |
~/path | 來自主目錄的路徑 | Read(~/Documents/*.pdf) | /Users/alice/Documents/*.pdf |
/path | 相對於專案根目錄的路徑 | Edit(/src/**/*.ts) | <project root>/src/**/*.ts |
path 或 ./path | 相對於目前目錄的路徑 | Read(*.env) | <cwd>/*.env |
像 /Users/alice/file 這樣的模式不是絕對路徑。它相對於專案根目錄。使用 //Users/alice/file 表示絕對路徑。
在 Windows 上,路徑在符合前會被正規化為 POSIX 形式。C:\Users\alice 變成 /c/Users/alice,所以使用 //c/**/.env 來符合該磁碟上任何位置的 .env 檔案。若要符合所有磁碟,請使用 //**/.env。
範例:
Edit(/docs/**): 編輯 <project>/docs/ 中的檔案(不是 /docs/ 也不是 <project>/.claude/docs/)
Read(~/.zshrc): 讀取您主目錄的 .zshrc
Edit(//tmp/scratch.txt): 編輯絕對路徑 /tmp/scratch.txt
Read(src/**): 從 <current-directory>/src/ 讀取
在 gitignore 模式中,* 符合單一目錄中的檔案,而 ** 遞迴符合目錄。若要允許所有檔案存取,請使用不帶括號的工具名稱:Read、Edit 或 Write。
WebFetch
WebFetch(domain:example.com) 符合對 example.com 的擷取請求
MCP
mcp__puppeteer 符合由 puppeteer 伺服器提供的任何工具(在 Claude Code 中設定的名稱)
mcp__puppeteer__* 萬用字元語法,也符合來自 puppeteer 伺服器的所有工具
mcp__puppeteer__puppeteer_navigate 符合由 puppeteer 伺服器提供的 puppeteer_navigate 工具
Agent(subagents)
使用 Agent(AgentName) 規則來控制 Claude 可以使用哪些 subagents:
Agent(Explore) 符合 Explore subagent
Agent(Plan) 符合 Plan subagent
Agent(my-custom-agent) 符合名為 my-custom-agent 的自訂 subagent
將這些規則新增到您設定中的 deny 陣列,或使用 --disallowedTools CLI 旗標來停用特定代理。若要停用 Explore 代理:
{
"permissions": {
"deny": ["Agent(Explore)"]
}
}
使用 hooks 擴展權限
Claude Code hooks 提供了一種方式來註冊自訂 shell 命令,以在執行時執行權限評估。當 Claude Code 進行工具呼叫時,PreToolUse hooks 在權限提示之前執行。hook 輸出可以拒絕工具呼叫、強制提示或跳過提示以讓呼叫繼續進行。
跳過提示不會繞過權限規則。Deny 和 ask 規則在 hook 返回 "allow" 後仍會被評估,因此符合的 deny 規則仍會阻止呼叫。這保留了管理權限中描述的 deny 優先順序,包括在受管理設定中設定的 deny 規則。
阻止 hook 也優先於 allow 規則。以代碼 2 退出的 hook 會在評估權限規則之前停止工具呼叫,因此即使 allow 規則會允許呼叫,該阻止也會適用。若要執行所有 Bash 命令而無需提示,除了您想要阻止的少數幾個,請將 "Bash" 新增到您的 allow 清單,並註冊一個 PreToolUse hook 來拒絕那些特定命令。請參閱阻止對受保護檔案的編輯以取得您可以調整的 hook 指令碼。
工作目錄
根據預設,Claude 可以存取啟動它的目錄中的檔案。您可以擴展此存取:
- 在啟動期間:使用
--add-dir <path> CLI 引數
- 在工作階段期間:使用
/add-dir 命令
- 持久設定:新增到設定檔案中的
additionalDirectories
其他目錄中的檔案遵循與原始工作目錄相同的權限規則:它們變成可讀的而無需提示,檔案編輯權限遵循目前的權限模式。
權限如何與沙箱互動
權限和沙箱是互補的安全層:
- 權限控制 Claude Code 可以使用哪些工具以及它可以存取哪些檔案或網域。它們適用於所有工具(Bash、Read、Edit、WebFetch、MCP 和其他)。
- 沙箱提供作業系統級別的強制執行,限制 Bash 工具的檔案系統和網路存取。它僅適用於 Bash 命令及其子程序。
使用兩者進行深度防禦:
- 權限 deny 規則阻止 Claude 甚至嘗試存取受限資源
- 沙箱限制防止 Bash 命令到達定義邊界外的資源,即使提示注入繞過 Claude 的決策制定
- 沙箱中的檔案系統限制使用 Read 和 Edit deny 規則,而不是單獨的沙箱設定
- 網路限制結合 WebFetch 權限規則與沙箱的
allowedDomains 清單
受管理設定
對於需要集中控制 Claude Code 設定的組織,管理員可以部署無法被使用者或專案設定覆蓋的受管理設定。這些原則設定遵循與一般設定檔案相同的格式,可以透過 MDM/OS 級別原則、受管理設定檔案或伺服器管理的設定傳遞。請參閱設定檔案以了解傳遞機制和檔案位置。
僅受管理的設定
某些設定僅在受管理設定中有效:
| 設定 | 描述 |
|---|
allowManagedPermissionRulesOnly | 當為 true 時,防止使用者和專案設定定義 allow、ask 或 deny 權限規則。僅套用受管理設定中的規則 |
allowManagedHooksOnly | 當為 true 時,防止載入使用者、專案和外掛 hooks。僅允許受管理 hooks 和 SDK hooks |
allowManagedMcpServersOnly | 當為 true 時,僅尊重受管理設定中的 allowedMcpServers。deniedMcpServers 仍然從所有來源合併。請參閱受管理 MCP 設定 |
blockedMarketplaces | 市場來源的封鎖清單。在下載前檢查被封鎖的來源,因此它們永遠不會接觸檔案系統。請參閱受管理市場限制 |
sandbox.network.allowManagedDomainsOnly | 當為 true 時,僅尊重來自受管理設定的 allowedDomains 和 WebFetch(domain:...) allow 規則。非允許的網域會自動被阻止,無需提示使用者。被拒絕的網域仍然從所有來源合併 |
sandbox.filesystem.allowManagedReadPathsOnly | 當為 true 時,僅尊重受管理設定中的 allowRead 路徑。來自使用者、專案和本機設定的 allowRead 項目會被忽略 |
strictKnownMarketplaces | 控制使用者可以新增哪些外掛市場。請參閱受管理市場限制 |
設定 auto mode 分類器
Auto mode 使用分類器模型來決定每個操作是否可以安全執行而無需提示。開箱即用,它僅信任工作目錄和(如果存在)目前儲存庫的遠端。推送到您公司的原始碼控制組織或寫入團隊雲端儲存桶等操作將被阻止為潛在的資料外洩。autoMode 設定區塊讓您告訴分類器您的組織信任哪些基礎設施。
分類器從使用者設定、.claude/settings.local.json 和受管理設定中讀取 autoMode。它不從 .claude/settings.json 中的共用專案設定讀取,因為簽入的儲存庫可能會注入自己的 allow 規則。
| 範圍 | 檔案 | 用於 |
|---|
| 一個開發人員 | ~/.claude/settings.json | 個人信任的基礎設施 |
| 一個專案,一個開發人員 | .claude/settings.local.json | 每個專案的信任儲存桶或服務,gitignored |
| 組織範圍 | 受管理設定 | 為所有開發人員強制執行的信任基礎設施 |
來自每個範圍的項目會被合併。開發人員可以使用個人項目擴展 environment、allow 和 soft_deny,但無法移除受管理設定提供的項目。因為 allow 規則在分類器內充當對 block 規則的例外,開發人員新增的 allow 項目可以覆蓋組織 soft_deny 項目:組合是加法的,不是硬原則邊界。如果您需要開發人員無法繞過的規則,請改用受管理設定中的 permissions.deny,它會在分類器被諮詢之前阻止操作。
定義信任的基礎設施
對於大多數組織,autoMode.environment 是您唯一需要設定的欄位。它告訴分類器哪些儲存庫、儲存桶和網域是信任的,而不涉及內建的 block 和 allow 規則。分類器使用 environment 來決定”外部”的含義:任何未列出的目的地都是潛在的外洩目標。
{
"autoMode": {
"environment": [
"Source control: github.example.com/acme-corp and all repos under it",
"Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
"Trusted internal domains: *.corp.example.com, api.internal.example.com",
"Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"
]
}
}
項目是散文,不是正規表達式或工具模式。分類器將它們讀作自然語言規則。以您向新工程師描述基礎設施的方式編寫它們。徹底的環境部分涵蓋:
- 組織:您的公司名稱以及 Claude Code 主要用於什麼,如軟體開發、基礎設施自動化或資料工程
- 原始碼控制:您的開發人員推送到的每個 GitHub、GitLab 或 Bitbucket 組織
- 雲端提供商和信任的儲存桶:Claude 應該能夠讀取和寫入的儲存桶名稱或前綴
- 信任的內部網域:您網路內的 API、儀表板和服務的主機名稱,如
*.internal.example.com
- 關鍵內部服務:CI、工件登錄、內部套件索引、事件工具
- 其他背景:受管制行業限制、多租戶基礎設施或影響分類器應將什麼視為風險的合規要求
有用的起始範本:填入括號欄位並移除不適用的任何行:
{
"autoMode": {
"environment": [
"Organization: {COMPANY_NAME}. Primary use: {PRIMARY_USE_CASE, e.g. software development, infrastructure automation}",
"Source control: {SOURCE_CONTROL, e.g. GitHub org github.example.com/acme-corp}",
"Cloud provider(s): {CLOUD_PROVIDERS, e.g. AWS, GCP, Azure}",
"Trusted cloud buckets: {TRUSTED_BUCKETS, e.g. s3://acme-builds, gs://acme-datasets}",
"Trusted internal domains: {TRUSTED_DOMAINS, e.g. *.internal.example.com, api.example.com}",
"Key internal services: {SERVICES, e.g. Jenkins at ci.example.com, Artifactory at artifacts.example.com}",
"Additional context: {EXTRA, e.g. regulated industry, multi-tenant infrastructure, compliance requirements}"
]
}
}
您提供的背景越具體,分類器就越能區分常規內部操作和外洩嘗試。
您不需要一次填入所有內容。合理的推出:從預設值開始,新增您的原始碼控制組織和關鍵內部服務,這解決了最常見的誤報,如推送到您自己的儲存庫。接下來新增信任的網域和雲端儲存桶。當出現阻止時填入其餘部分。
覆蓋 block 和 allow 規則
兩個額外的欄位讓您替換分類器的內建規則清單:autoMode.soft_deny 控制被阻止的內容,autoMode.allow 控制哪些例外適用。每個都是散文描述的陣列,讀作自然語言規則。
在分類器內,優先順序是:soft_deny 規則首先阻止,然後 allow 規則覆蓋為例外,然後明確的使用者意圖覆蓋兩者。如果使用者的訊息直接且具體地描述 Claude 即將採取的確切操作,分類器允許它,即使 soft_deny 規則符合。一般請求不計算:要求 Claude”清理儲存庫”不授權強制推送,但要求 Claude”強制推送此分支”則授權。
若要放寬:當預設值阻止您的管道已透過 PR 審查、CI 或暫存環境防護的內容時,從 soft_deny 移除規則,或當分類器重複標記預設例外不涵蓋的常規模式時新增到 allow。若要收緊:新增到 soft_deny 以應對預設值遺漏的特定於您環境的風險,或從 allow 移除以對 block 規則保持預設例外。在所有情況下,執行 claude auto-mode defaults 以取得完整的預設清單,然後複製和編輯:永遠不要從空清單開始。
{
"autoMode": {
"environment": [
"Source control: github.example.com/acme-corp and all repos under it"
],
"allow": [
"Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",
"Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"
],
"soft_deny": [
"Never run database migrations outside the migrations CLI, even against dev databases",
"Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow",
"...copy full default soft_deny list here first, then add your rules..."
]
}
}
設定 allow 或 soft_deny 會替換該部分的整個預設清單。如果您使用單一項目設定 soft_deny,每個內建 block 規則都會被丟棄:強制推送、資料外洩、curl | bash、生產部署和所有其他預設 block 規則變成允許。若要安全地自訂,執行 claude auto-mode defaults 以列印內建規則,將它們複製到您的設定檔案,然後根據您自己的管道和風險容限審查每個規則。僅移除您的基礎設施已減輕的風險的規則。
三個部分是獨立評估的,所以單獨設定 environment 會保留預設的 allow 和 soft_deny 清單。
檢查預設值和您的有效設定
因為設定 allow 或 soft_deny 會替換預設值,請透過複製完整的預設清單開始任何自訂。三個 CLI 子命令可幫助您檢查和驗證:
claude auto-mode defaults # the built-in environment, allow, and soft_deny rules
claude auto-mode config # what the classifier actually uses: your settings where set, defaults otherwise
claude auto-mode critique # get AI feedback on your custom allow and soft_deny rules
將 claude auto-mode defaults 的輸出儲存到檔案,編輯清單以符合您的原則,並將結果貼到您的設定檔案中。儲存後,執行 claude auto-mode config 以確認有效規則是您期望的。如果您已編寫自訂規則,claude auto-mode critique 會審查它們並標記模糊、冗餘或可能導致誤報的項目。
設定優先順序
權限規則遵循與所有其他 Claude Code 設定相同的設定優先順序:
- 受管理設定:無法被任何其他級別覆蓋,包括命令列引數
- 命令列引數:臨時工作階段覆蓋
- 本機專案設定 (
.claude/settings.local.json)
- 共用專案設定 (
.claude/settings.json)
- 使用者設定 (
~/.claude/settings.json)
如果工具在任何級別被拒絕,沒有其他級別可以允許它。例如,受管理設定 deny 無法被 --allowedTools 覆蓋,--disallowedTools 可以新增超出受管理設定定義的限制。
如果權限在使用者設定中被允許但在專案設定中被拒絕,專案設定優先,權限被阻止。
範例設定
此儲存庫包含常見部署情境的入門設定設定。使用這些作為起點並根據您的需求進行調整。
另請參閱