指南

設定權限

使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理如何使用工具。

Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義哪些操作可以自動允許，並使用 canUseTool 回呼在執行時處理其他所有情況。

本頁涵蓋權限模式和規則。若要建立互動式核准流程，讓使用者在執行時核准或拒絕工具請求，請參閱處理核准和使用者輸入。

權限如何被評估

當 Claude 請求使用工具時，SDK 會按以下順序檢查權限：

Hooks
首先執行 hooks，它可以允許、拒絕或繼續到下一步
權限規則
按以下順序檢查在 settings.json 中定義的規則：首先是 deny 規則（無論其他規則如何都會阻擋），然後是 allow 規則（如果匹配則允許），最後是 ask 規則（提示要求核准）。這些宣告式規則讓您無需撰寫程式碼即可預先核准、阻擋或要求核准特定工具。
權限模式
套用啟用中的權限模式（bypassPermissions、acceptEdits、dontAsk 等）
canUseTool 回呼
如果規則或模式未解決，則呼叫您的 canUseTool 回呼來做出決定

本頁重點介紹權限模式（步驟 3），即控制預設行為的靜態設定。關於其他步驟：

Hooks：執行自訂程式碼來允許、拒絕或修改工具請求。請參閱使用 hooks 控制執行。
權限規則：在 settings.json 中設定宣告式允許/拒絕規則。請參閱權限設定。
canUseTool 回呼：在執行時提示使用者核准。請參閱處理核准和使用者輸入。

權限模式

權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 query() 時設定權限模式，或在串流會話期間動態變更。

可用模式

SDK 支援以下權限模式：

模式	描述	工具行為
`default`	標準權限行為	無自動核准；未匹配的工具會觸發您的 `canUseTool` 回呼
`acceptEdits`	自動接受檔案編輯	檔案編輯和檔案系統操作（`mkdir`、`rm`、`mv` 等）會自動核准
`bypassPermissions`	繞過所有權限檢查	所有工具無需權限提示即可執行（請謹慎使用）
`plan`	規劃模式	不執行工具；Claude 進行規劃但不做出變更

子代理繼承：使用 bypassPermissions 時，所有子代理都會繼承此模式且無法覆寫。子代理可能具有不同的系統提示詞和比主代理更少的行為限制。啟用 bypassPermissions 會授予它們完整的、自主的系統存取權限，且不會有任何核准提示。

設定權限模式

您可以在啟動查詢時設定一次權限模式，或在會話啟用期間動態變更。

模式詳情

接受編輯模式（`acceptEdits`）

自動核准檔案操作，讓 Claude 可以在不提示的情況下編輯程式碼。其他工具（如非檔案系統操作的 Bash 命令）仍需要正常權限。

自動核准的操作：

檔案編輯（Edit、Write 工具）
檔案系統命令：mkdir、touch、rm、mv、cp

**使用時機：**您信任 Claude 的編輯並希望更快速地迭代，例如在原型開發期間或在隔離目錄中工作時。

繞過權限模式（`bypassPermissions`）

自動核准所有工具使用，無需提示。Hooks 仍會執行，並可在需要時阻擋操作。

請極度謹慎使用。在此模式下，Claude 擁有完整的系統存取權限。僅在您信任所有可能操作的受控環境中使用。

規劃模式（`plan`）

完全阻止工具執行。Claude 可以分析程式碼並建立計劃，但無法進行變更。Claude 可能會使用 AskUserQuestion 在最終確定計劃之前釐清需求。請參閱處理核准和使用者輸入以了解如何處理這些提示。

**使用時機：**您希望 Claude 提出變更建議但不執行它們，例如在程式碼審查期間或當您需要在變更執行前先核准時。

設定權限

使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理如何使用工具。

本頁涵蓋權限模式和規則。若要建立互動式核准流程，讓使用者在執行時核准或拒絕工具請求，請參閱處理核准和使用者輸入。

權限如何被評估

當 Claude 請求使用工具時，SDK 會按以下順序檢查權限：

Hooks
首先執行 hooks，它可以允許、拒絕或繼續到下一步
權限規則
按以下順序檢查在 settings.json 中定義的規則：首先是 deny 規則（無論其他規則如何都會阻擋），然後是 allow 規則（如果匹配則允許），最後是 ask 規則（提示要求核准）。這些宣告式規則讓您無需撰寫程式碼即可預先核准、阻擋或要求核准特定工具。
權限模式
套用啟用中的權限模式（bypassPermissions、acceptEdits、dontAsk 等）
canUseTool 回呼
如果規則或模式未解決，則呼叫您的 canUseTool 回呼來做出決定

本頁重點介紹權限模式（步驟 3），即控制預設行為的靜態設定。關於其他步驟：

Hooks：執行自訂程式碼來允許、拒絕或修改工具請求。請參閱使用 hooks 控制執行。
權限規則：在 settings.json 中設定宣告式允許/拒絕規則。請參閱權限設定。
canUseTool 回呼：在執行時提示使用者核准。請參閱處理核准和使用者輸入。

權限模式

權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 query() 時設定權限模式，或在串流會話期間動態變更。

可用模式

SDK 支援以下權限模式：

模式	描述	工具行為
`default`	標準權限行為	無自動核准；未匹配的工具會觸發您的 `canUseTool` 回呼
`acceptEdits`	自動接受檔案編輯	檔案編輯和檔案系統操作（`mkdir`、`rm`、`mv` 等）會自動核准
`bypassPermissions`	繞過所有權限檢查	所有工具無需權限提示即可執行（請謹慎使用）
`plan`	規劃模式	不執行工具；Claude 進行規劃但不做出變更

設定權限模式

您可以在啟動查詢時設定一次權限模式，或在會話啟用期間動態變更。

模式詳情

接受編輯模式（`acceptEdits`）

自動核准檔案操作，讓 Claude 可以在不提示的情況下編輯程式碼。其他工具（如非檔案系統操作的 Bash 命令）仍需要正常權限。

自動核准的操作：

檔案編輯（Edit、Write 工具）
檔案系統命令：mkdir、touch、rm、mv、cp

**使用時機：**您信任 Claude 的編輯並希望更快速地迭代，例如在原型開發期間或在隔離目錄中工作時。

繞過權限模式（`bypassPermissions`）

自動核准所有工具使用，無需提示。Hooks 仍會執行，並可在需要時阻擋操作。

請極度謹慎使用。在此模式下，Claude 擁有完整的系統存取權限。僅在您信任所有可能操作的受控環境中使用。

規劃模式（`plan`）

**使用時機：**您希望 Claude 提出變更建議但不執行它們，例如在程式碼審查期間或當您需要在變更執行前先核准時。

設定權限

權限如何被評估

權限模式

可用模式

設定權限模式

模式詳情

接受編輯模式（`acceptEdits`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）

相關資源

設定權限

權限如何被評估

權限模式

可用模式

設定權限模式

模式詳情

接受編輯模式（`acceptEdits`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）

相關資源

權限如何被評估

權限模式

可用模式

設定權限模式

模式詳情

接受編輯模式（acceptEdits）

繞過權限模式（bypassPermissions）

規劃模式（plan）

相關資源

權限如何被評估

權限模式

可用模式

設定權限模式

模式詳情

接受編輯模式（acceptEdits）

繞過權限模式（bypassPermissions）

規劃模式（plan）

相關資源

接受編輯模式（`acceptEdits`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）

接受編輯模式（`acceptEdits`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）