處理權限

在 Claude Agent SDK 中控制工具使用和權限

​

SDK 權限

Claude Agent SDK 提供強大的權限控制，讓您可以管理 Claude 在您的應用程式中如何使用工具。

本指南涵蓋如何使用 canUseTool 回調、鉤子和 settings.json 權限規則來實現權限系統。如需完整的 API 文件，請參閱 TypeScript SDK 參考。

​

概述

Claude Agent SDK 提供四種互補的方式來控制工具使用：

1. 權限模式 - 影響所有工具的全域權限行為設定
2. canUseTool 回調 - 針對其他規則未涵蓋的情況的執行時權限處理器
3. 鉤子 - 使用自訂邏輯對每個工具執行進行細粒度控制
4. 權限規則 (settings.json) - 具有整合 bash 命令解析的宣告式允許/拒絕規則

每種方法的使用案例：

• 權限模式 - 設定整體權限行為（規劃、自動接受編輯、繞過檢查）
• canUseTool - 針對未涵蓋情況的動態批准，提示使用者權限
• 鉤子 - 對所有工具執行的程式化控制
• 權限規則 - 具有智慧 bash 命令解析的靜態政策

​

權限流程圖

處理順序： PreToolUse Hook → 拒絕規則 → 允許規則 → 詢問規則 → 權限模式檢查 → canUseTool 回調 → PostToolUse Hook

​

權限模式

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

​

可用模式

SDK 支援四種權限模式，每種都有不同的行為：

模式	描述	工具行為
default	標準權限行為	適用正常權限檢查
plan	規劃模式 - 不執行	Claude 只能使用唯讀工具；在執行前呈現計劃 （SDK 目前不支援）
acceptEdits	自動接受檔案編輯	檔案編輯和檔案系統操作會自動批准
bypassPermissions	繞過所有權限檢查	所有工具都不需權限提示即可執行（請謹慎使用）

​

設定權限模式

您可以透過兩種方式設定權限模式：

​

1. 初始配置

在建立查詢時設定模式：

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = await query({
  prompt: "幫我重構這段程式碼",
  options: {
    permissionMode: 'default'  // 標準權限模式
  }
});

​

2. 動態模式變更（僅限串流）

在串流會話期間變更模式：

TypeScript

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 擁有完整系統存取權限
• 建議僅在受控環境中使用

​

權限流程中的模式優先順序

權限模式在權限流程中的特定點進行評估：

1. 鉤子首先執行 - 可以允許、拒絕、詢問或繼續
2. 檢查拒絕規則 - 無論模式如何都會阻止工具
3. 檢查允許規則 - 如果符合則允許工具
4. 檢查詢問規則 - 如果符合則提示權限
5. 評估權限模式：
   • bypassPermissions 模式 - 如果啟用，允許所有剩餘工具
   • 其他模式 - 延遲到 canUseTool 回調
6. canUseTool 回調 - 處理剩餘情況

這意味著：

• 鉤子始終可以控制工具使用，即使在 bypassPermissions 模式中
• 明確的拒絕規則會覆蓋所有權限模式
• 詢問規則在權限模式之前評估
• bypassPermissions 模式會覆蓋未符合工具的 canUseTool 回調

​

最佳實踐

1. 使用預設模式 進行受控執行與正常權限檢查
2. 使用 acceptEdits 模式 處理隔離的檔案或目錄
3. 避免在生產環境或敏感資料系統中使用 bypassPermissions
4. 結合模式與鉤子 進行細粒度控制
5. 根據任務進度和信心動態切換模式

模式進展範例：

// 以預設模式開始進行受控執行
permissionMode: 'default'

// 切換到 acceptEdits 進行快速迭代
await q.setPermissionMode('acceptEdits')

​

canUseTool

canUseTool 回調在呼叫 query 函數時作為選項傳遞。它接收工具名稱和輸入參數，並必須回傳決定 - 允許或拒絕。

當 Claude Code 會向使用者顯示權限提示時，canUseTool 會觸發，例如鉤子和權限規則未涵蓋且不在 acceptEdits 模式中。

以下是顯示如何實現互動式工具批准的完整範例：

TypeScript

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);
    }
  }
});

​

相關資源

• 鉤子指南 - 學習如何實現鉤子以對工具執行進行細粒度控制
• 設定：權限規則 - 配置具有 bash 命令解析的宣告式允許/拒絕規則