​
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 鉤子 → 詢問規則 → 拒絕規則 → 權限模式檢查 → 允許規則 → canUseTool 回調 → PostToolUse 鉤子

​
權限模式

權限模式提供對 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、MultiEdit、Write 工具）
  • Bash 檔案系統命令（mkdir、touch、rm、mv、cp）
  • 檔案建立和刪除

​
繞過權限模式 (bypassPermissions)

在繞過權限模式中：
  • 所有工具使用都會自動批准
  • 不會出現權限提示
  • 鉤子仍會執行（仍可阻止操作）
  • 請極其謹慎使用 - Claude 擁有完整的系統存取權限
  • 僅建議在受控環境中使用

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

權限模式在權限流程中的特定點進行評估：
  1. 鉤子首先執行 - 可以覆蓋任何模式
  2. 檢查拒絕規則 - 無論模式如何都會阻止工具
  3. bypassPermissions 模式 - 如果啟用，允許所有剩餘工具
  4. 檢查允許規則
  5. 其他模式影響特定工具行為
  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 會觸發，例如鉤子和權限規則未涵蓋它且不在自動接受模式中。 以下是一個完整的範例，展示如何實現互動式工具批准： 
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);
    }
  }
});

​
使用鉤子進行工具控制

鉤子在各個階段提供對工具執行的程式化控制。鉤子會針對每個工具使用進行呼叫，讓您完全控制權限管道。

​
鉤子實現

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

const result = await query({
  prompt: "幫我重構這段程式碼",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`工具請求：${input.tool_name}`);
          
          // 自己解析和驗證工具輸入
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "危險命令已阻止"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`工具已完成：${input.tool_name}`);
          // 記錄或稽核工具結果
          return { continue: true };
        }]
      }]
    }
  }
});

​
與 canUseTool 的主要差異

  • 範圍：鉤子會針對所有工具使用進行呼叫；canUseTool 處理權限規則未涵蓋的情況
  • 控制：鉤子需要您自己解析和驗證輸入
  • 事件：鉤子支援多個事件（PreToolUse、PostToolUse 等）用於不同階段

​
使用權限規則 (settings.json)

settings.json 中的權限規則提供具有內建 bash 命令解析的聲明式控制。這些規則在呼叫 canUseTool 之前進行評估。有關設定配置的更多詳細資訊，請參閱 Claude Code 設定文件。

​
配置結構

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

​
規則語法

權限規則遵循模式：ToolName(pattern)
  • Bash 規則：使用前綴匹配（非正規表達式）。範例：Bash(npm:*) 匹配任何以 “npm” 開頭的命令
  • 檔案規則：支援 glob 模式。範例：Read(./src/**/*.ts) 匹配 src 中的 TypeScript 檔案
  • 僅工具規則：省略括號以控制整個工具。範例：WebFetch 阻止所有網路擷取
有關配置權限的更多資訊，請參閱配置權限。

​
與 SDK 一起使用

雖然規則尚無法在 SDK 中以程式化方式設定，但它們會從載入 SDK 的路徑中的 settings.json 檔案讀取。

​
權限評估順序

  1. 首先檢查拒絕規則 - 如果匹配，工具使用會被阻止
  2. 接著檢查允許規則 - 如果匹配，工具使用會被允許
  3. 檢查詢問規則 - 如果匹配，會提示使用者
  4. 針對任何剩餘情況呼叫 canUseTool 回調

​
Bash 命令解析

SDK 包含一個整合的 bash 解析器，能理解命令結構：
  • 處理管道、重新導向和命令替換
  • 識別危險模式，如 rm -rf 或 curl | sh
  • 支援萬用字元和前綴匹配
bash 模式如何運作的範例：
  • Bash(git:*) - 匹配任何 git 命令
  • Bash(npm run test) - 匹配確切命令
  • Bash(npm run test:*) - 匹配以 npm run test 開頭的 Bash 命令，如 npm run test anyFile.test.ts
有關配置權限的更多資訊，請參閱配置權限。

​
最佳實踐

  1. 從預設模式開始進行標準權限檢查
  2. 使用權限規則進行靜態策略，特別是 bash 命令（請參閱權限設定）
  3. 使用鉤子記錄、稽核或轉換所有工具使用（請參閱鉤子類型）
  4. 使用 canUseTool針對未涵蓋的情況進行動態決定（請參閱CanUseTool 類型）
  5. 透過結合模式、規則、鉤子和回調來分層防禦，適用於關鍵應用程式