指南
處理權限
在 Claude Agent SDK 中控制工具使用和權限
SDK 權限
SDK 權限
Claude Agent SDK 提供強大的權限控制，讓您可以管理 Claude 在您的應用程式中如何使用工具。
本指南涵蓋如何使用 canUseTool 回調、鉤子和 settings.json 權限規則來實現權限系統。如需完整的 API 文件，請參閱 TypeScript SDK 參考。
概述
概述
Claude Agent SDK 提供四種互補的方式來控制工具使用：
- 權限模式 - 影響所有工具的全域權限行為設定
- canUseTool 回調 - 針對其他規則未涵蓋的情況的執行時權限處理器
- 鉤子 - 使用自訂邏輯對每個工具執行進行細粒度控制
- 權限規則 (settings.json) - 具有整合 bash 命令解析的宣告式允許/拒絕規則
每種方法的使用案例：
- 權限模式 - 設定整體權限行為（規劃、自動接受編輯、繞過檢查）
canUseTool- 針對未涵蓋情況的動態批准，提示使用者權限- 鉤子 - 對所有工具執行的程式化控制
- 權限規則 - 具有智慧 bash 命令解析的靜態政策
權限流程圖
權限流程圖
%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
Start([工具請求]) --> PreHook(PreToolUse Hook)
PreHook -->| 允許 | Execute(執行工具)
PreHook -->| 拒絕 | Denied(拒絕)
PreHook -->| 詢問 | Callback(canUseTool 回調)
PreHook -->| 繼續 | Deny(檢查拒絕規則)
Deny -->| 符合 | Denied
Deny -->| 不符合 | Allow(檢查允許規則)
Allow -->| 符合 | Execute
Allow -->| 不符合 | Ask(檢查詢問規則)
Ask -->| 符合 | Callback
Ask -->| 不符合 | Mode{權限模式？}
Mode -->| bypassPermissions | Execute
Mode -->| 其他模式 | Callback
Callback -->| 允許 | Execute
Callback -->| 拒絕 | Denied
Denied --> DeniedResponse([回饋給代理])
Execute --> PostHook(PostToolUse Hook)
PostHook --> Done([工具回應])
style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919
style Denied fill:#BF4D43,color:#fff
style DeniedResponse fill:#BF4D43,color:#fff
style Execute fill:#DAAF91,color:#191919
style Done fill:#DAAF91,color:#191919
classDef hookClass fill:#CC785C,color:#fff
class PreHook,PostHook hookClass
classDef ruleClass fill:#EBDBBC,color:#191919
class Deny,Allow,Ask ruleClass
classDef modeClass fill:#A8DAEF,color:#191919
class Mode modeClass
classDef callbackClass fill:#D4A27F,color:#191919
class Callback callbackClass處理順序： PreToolUse Hook → 拒絕規則 → 允許規則 → 詢問規則 → 權限模式檢查 → canUseTool 回調 → PostToolUse Hook
權限模式
權限模式
權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 query() 時設定權限模式，或在串流會話期間動態更改它。
可用模式
可用模式
SDK 支援四種權限模式，每種都有不同的行為：
| 模式 | 描述 | 工具行為 |
|---|---|---|
default | 標準權限行為 | 適用正常權限檢查 |
plan | 規劃模式 - 不執行 | Claude 只能使用唯讀工具；在執行前呈現計劃 （SDK 目前不支援） |
acceptEdits | 自動接受檔案編輯 | 檔案編輯和檔案系統操作會自動批准 |
bypassPermissions | 繞過所有權限檢查 | 所有工具都不需權限提示即可執行（請謹慎使用） |
設定權限模式
設定權限模式
您可以透過兩種方式設定權限模式：
1. 初始配置
在建立查詢時設定模式：
import { query } from "@anthropic-ai/claude-agent-sdk";
const result = await query({
prompt: "幫我重構這段程式碼",
options: {
permissionMode: 'default' // 標準權限模式
}
});2. 動態模式變更（僅限串流）
在串流會話期間變更模式：
import { query } from "@anthropic-ai/claude-agent-sdk";
// 為串流輸入建立非同步產生器
async function* streamInput() {
yield {
type: 'user',
message: {
role: 'user',
content: "讓我們從預設權限開始"
}
};
// 稍後在對話中...
yield {
type: 'user',
message: {
role: 'user',
content: "現在讓我們加速開發"
}
};
}
const q = query({
prompt: streamInput(),
options: {
permissionMode: 'default' // 以預設模式開始
}
});
// 動態變更模式
await q.setPermissionMode('acceptEdits');
// 處理訊息
for await (const message of q) {
console.log(message);
}模式特定行為
模式特定行為
接受編輯模式 (acceptEdits)
在接受編輯模式中：
- 所有檔案編輯都會自動批准
- 檔案系統操作（mkdir、touch、rm 等）會自動批准
- 其他工具仍需要正常權限
- 當您信任 Claude 的編輯時可加速開發
- 適用於快速原型製作和迭代
自動批准的操作：
- 檔案編輯（Edit、Write 工具）
- Bash 檔案系統命令（mkdir、touch、rm、mv、cp）
- 檔案建立和刪除
繞過權限模式 (bypassPermissions)
在繞過權限模式中：
- 所有工具使用都會自動批准
- 不會出現權限提示
- 鉤子仍會執行（仍可阻止操作）
- 請極度謹慎使用 - Claude 擁有完整系統存取權限
- 建議僅在受控環境中使用
權限流程中的模式優先順序
權限流程中的模式優先順序
權限模式在權限流程中的特定點進行評估：
- 鉤子首先執行 - 可以允許、拒絕、詢問或繼續
- 檢查拒絕規則 - 無論模式如何都會阻止工具
- 檢查允許規則 - 如果符合則允許工具
- 檢查詢問規則 - 如果符合則提示權限
- 評估權限模式：
bypassPermissions模式 - 如果啟用，允許所有剩餘工具- 其他模式 - 延遲到
canUseTool回調
canUseTool回調 - 處理剩餘情況
這意味著：
- 鉤子始終可以控制工具使用，即使在
bypassPermissions模式中 - 明確的拒絕規則會覆蓋所有權限模式
- 詢問規則在權限模式之前評估
bypassPermissions模式會覆蓋未符合工具的canUseTool回調
最佳實踐
最佳實踐
- 使用預設模式 進行受控執行與正常權限檢查
- 使用 acceptEdits 模式 處理隔離的檔案或目錄
- 避免在生產環境或敏感資料系統中使用 bypassPermissions
- 結合模式與鉤子 進行細粒度控制
- 根據任務進度和信心動態切換模式
模式進展範例：
// 以預設模式開始進行受控執行
permissionMode: 'default'
// 切換到 acceptEdits 進行快速迭代
await q.setPermissionMode('acceptEdits')canUseTool
canUseTool
canUseTool 回調在呼叫 query 函數時作為選項傳遞。它接收工具名稱和輸入參數，並必須回傳決定 - 允許或拒絕。
當 Claude Code 會向使用者顯示權限提示時，canUseTool 會觸發，例如鉤子和權限規則未涵蓋且不在 acceptEdits 模式中。
以下是顯示如何實現互動式工具批准的完整範例：
import { query } from "@anthropic-ai/claude-agent-sdk";
async function promptForToolApproval(toolName: string, input: any) {
console.log("\n🔧 工具請求：");
console.log(` 工具：${toolName}`);
// 顯示工具參數
if (input && Object.keys(input).length > 0) {
console.log(" 參數：");
for (const [key, value] of Object.entries(input)) {
let displayValue = value;
if (typeof value === 'string' && value.length > 100) {
displayValue = value.substring(0, 100) + "...";
} else if (typeof value === 'object') {
displayValue = JSON.stringify(value, null, 2);
}
console.log(` ${key}: ${displayValue}`);
}
}
// 取得使用者批准（替換為您的 UI 邏輯）
const approved = await getUserApproval();
if (approved) {
console.log(" ✅ 已批准\n");
return {
behavior: "allow",
updatedInput: input
};
} else {
console.log(" ❌ 已拒絕\n");
return {
behavior: "deny",
message: "使用者拒絕此工具的權限"
};
}
}
// 使用權限回調
const result = await query({
prompt: "幫我分析這個程式碼庫",
options: {
canUseTool: async (toolName, input) => {
return promptForToolApproval(toolName, input);
}
}
});相關資源
相關資源