設定權限

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

Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義自動允許的內容，以及使用 canUseTool callback 來在執行時處理其他所有情況。

權限如何被評估

[!NOTE]

如果您載入包含 mod 的外掛，請參閱 mod 的決定在規則與 hook 之間的位置。

當 Claude 請求一個工具時，Claude Code 會在以下步驟檢查該呼叫。每個步驟都可以決定該呼叫、將其傳送到您的 canUseTool 回呼，或將其傳遞下去：

1. Hooks

執行 hook。hook 可以直接拒絕該呼叫，或將其傳遞下去。傳回 allow 的 hook 不會略過拒絕規則和詢問規則步驟，無論 hook 結果為何，這些步驟都會被評估。

返回 allow 的 PreToolUse hook 也無法核准目標被 Claude Code 識別為關鍵路徑的 rm 或 rmdir 命令，例如 rm -rf ~。關於該 allow 在 plan mode 中的作用，請參閱 plan mode 中的 hook 核准。

2. 拒絕規則

如果來自 disallowed_tools 或來自 SDK 載入的設定檔的拒絕規則匹配，呼叫會被拒絕，且不會呼叫 canUseTool。即使在 bypassPermissions 模式下，以及即使 hook 返回了 allow，呼叫也會以這種方式被拒絕。

在 TypeScript SDK 中，如果您將自訂工具的 permission_policy 設定為 always_deny，對該工具的呼叫會在此步驟被拒絕。

3. 詢問規則

檢查來自 settings.json 的 ask 規則。如果詢問規則匹配，呼叫會傳遞到您的 canUseTool 回呼 以進行確認，即使在 bypassPermissions 模式下也是如此。

需要使用者互動的工具行為相同。AskUserQuestion 以及其伺服器設定了 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具會傳遞到回呼，即使當 allow 規則匹配時也是如此。在 dontAsk 模式下，兩種情況都會改為被拒絕，因為該模式會將每個提示轉為拒絕。MCP 註解需要 Claude Code v2.1.199 或更新版本。

您的組織設定為 ask 的 claude.ai connector 工具也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 bypassPermissions 模式下，即使當 allow 規則匹配時也是如此。回呼會收到原因 Your organization requires approval for this tool。在 dontAsk 模式下，呼叫會被拒絕，因為該模式永遠不會提示。

在 TypeScript SDK 中，如果您將自訂工具的 permission_policy 設定為 always_ask，任何 allow 規則都不會核准其呼叫，即使是 allowedTools 條目也不會。在 dontAsk 模式下，Claude Code 會拒絕這些呼叫；而在 auto、plan 或 bypassPermissions 模式下，它可以在您的回呼執行之前核准它們。

4. 權限模式

應用活躍的 權限模式：

• 在 bypassPermissions 模式下，Claude Code 會核准到達此步驟的每個呼叫，除非它屬於任何模式都不會自動核准的動作。關於其中哪些動作會傳送到您的 canUseTool 回呼，請參閱 Bypass permissions 模式。
• 在 acceptEdits 模式下，Claude Code 核准 接受編輯模式 下列出的檔案操作。
• 在 plan 模式下，部分呼叫會到達您的回呼，而當自動模式可用時，其他呼叫則會改為交由其分類器處理。如需更多資訊，請參閱 Plan mode。
• 在 default 和 dontAsk 模式下，呼叫會繼續進入 allow 規則。
• 關於 auto 模式，請參閱自動模式。

5. 允許規則

檢查 allow 規則（來自 allowed_tools 和 settings.json）。如果規則匹配，工具會被核准。工具自行核准的呼叫也會在此步驟解決，無需規則：例如在您的工作目錄內的檔案讀取或 唯讀 Bash 命令。

經識別的關鍵路徑移除不會被 allow 規則核准，而被標記為 Dangerous rm operation not ruled out 的命令也不會被 Bash 或 Bash(*) 規則核准。它們是否隨後到達您的回呼取決於權限模式：例如在 auto 模式的 Agent SDK 工作階段中，Claude Code 預設會拒絕它們而不呼叫它。關鍵路徑模式表列出了每個模式對它們的處理方式。

Allow 規則不會核准從 網路路徑 進行的讀取。

6. canUseTool 回呼

如果先前的步驟都未解決該請求，請呼叫您的 canUseTool 回呼 以獲得決定。在 dontAsk 模式下，此步驟會被跳過，工具會被拒絕，不過您安裝的 mod 仍可核准部分此類呼叫。

在 TypeScript SDK 中，如果您設定了 permissionPrompts: 'none'，您的回呼在此步驟不會被呼叫。PermissionRequest hook 仍然有機會決定，如果它不決定，Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。

如果您在 TypeScript SDK 期望評估順序在諮詢回呼之前自動批准呼叫的設定中傳遞 canUseTool 回呼，SDK 會在構造查詢時發出一次 Node.js 程序警告。警告的代碼是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。兩個設定會觸發它：

• permissionMode: 'bypassPermissions'：警告文字以 canUseTool will not be invoked: permissionMode 'bypassPermissions' 開頭。工具呼叫會在諮詢 canUseTool 之前被核准，因此您的回呼只會針對少數呼叫執行，例如 Bypass permissions 模式下列出的呼叫。若也要檢查已核准的呼叫，請將回呼的檢查放在 PreToolUse hook 中
• 僅為工具名稱的 allowedTools 條目，例如 "Read"：警告會在 canUseTool will not be invoked for: 之後列出每個此類條目。對所列工具的呼叫會在諮詢 canUseTool 之前被核准，但 allow 規則永遠不會核准的呼叫除外。若要讓您的回呼針對所列工具中需要核准的呼叫執行，請從 allowedTools 中移除該工具的條目

具有指定符的條目（如 Bash(ls *)）和 acceptEdits 模式不會觸發它，來自設定檔的 allow 規則對檢查不可見。

此警告不會阻擋任何呼叫，也不會變更任何選項。如果您的回呼已經會收到您想檢查的每個呼叫，請維持設定不變。若要記錄此警告，請使用 process.on('warning', ...) 進行監聽並匹配 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED 代碼。

此頁面重點關注 allow 和 deny 規則 以及 權限模式。對於其他步驟：

• Hooks： 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 使用 hooks 控制執行。
• canUseTool 回呼： 在執行時提示使用者批准，當沒有較早的步驟解決呼叫時。請參閱 處理批准和使用者輸入。

允許和拒絕規則

當您設定 allowedTools 和 disallowedTools（TypeScript）或 allowed_tools 和 disallowed_tools（Python）時，Claude Code 會將其項目新增到權限評估流程中的允許和拒絕規則清單。任何未列在 allowed_tools 中的其他工具仍可供 Claude 使用，對其進行的需要核准的呼叫會進入權限模式。

允許規則僅在字面 mcp__<server>__ 前綴之後接受工具名稱萬用字元。伺服器段必須無萬用字元，以便規則命名您設定的特定伺服器：mcp__puppeteer__* 符合來自 puppeteer 伺服器的每個工具，mcp__github__get_* 符合其 get_ 工具。未錨定的項目（如 allowed_tools=["*"] 或 allowed_tools=["mcp__*"]）會被忽略，不會自動核准任何內容。

[!WARNING]

自動批准的工具永遠不會到達 canUseTool。 在任何較早步驟中批准的工具呼叫，透過 acceptEdits 或 bypassPermissions，或透過允許規則，會跳過您的 canUseTool 回呼，因此您在那裡放置的權限檢查會被該工具無聲地繞過。

如果對 allowed_tools 中某個工具的呼叫仍會到達您的 canUseTool 回呼，或在 dontAsk 模式中遭到拒絕，請檢查它們是否為從網路路徑讀取，或屬於下列呼叫。沒有任何允許規則會核准這些呼叫。在永不提示的 dontAsk 模式中，Claude Code 會拒絕這些呼叫而不呼叫 canUseTool；在其他權限模式中，請依各項目的說明處理：

• AskUserQuestion、標記為 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具，以及您的組織設定為 ask 的連接器工具：在回呼中回應它們。處理釐清問題說明如何回應 AskUserQuestion，而連接器呼叫抵達時會附帶原因 Your organization requires approval for this tool

• 您的應用程式標記為 always_ask 的自訂工具：在回呼中決定該呼叫。若要停止這些呼叫抵達，請在工作階段中途變更政策。在 auto、plan 和 bypassPermissions 模式中，該呼叫也可能在回呼之前就被核准，相關情況列於可核准 always_ask 呼叫的權限模式

• 經辨識的 rm 和 rmdir 關鍵路徑移除：在 default、acceptEdits 和 bypassPermissions 模式中，請在回呼中允許或拒絕該移除，此時 decisionReason 會以 Dangerous rm 開頭。關於 auto 和 plan 模式，請參閱各權限模式中的關鍵路徑移除

• 裸名稱：像 Read 或 mcp__github__get_issue 這樣的項目會自動核准對該工具的每個呼叫，但任何模式都不自動核准的動作和從網路路徑讀取除外。

• 限定規則：像 Bash(npm test *) 這樣的項目會自動核准符合的呼叫，其他需要核准的 Bash 呼叫會進入權限模式。

若要檢查由允許規則、acceptEdits 或 bypassPermissions 核准的呼叫，請使用 PreToolUse hook，它也會針對這些呼叫執行。hook 拒絕即使在 bypassPermissions 模式中也適用。

對於鎖定的代理，將 allowedTools 與 permissionMode: "dontAsk" 配對：

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

列出的 Read、Glob 和 Grep 呼叫會被核准，但任何模式都不自動核准的動作和從網路路徑讀取除外。其他每個原本會提示的呼叫則會被拒絕，不過您安裝的 mod 仍可核准其中部分呼叫。

在 default 模式中不需要核准的呼叫無論您是否列出都會執行。這些呼叫包括唯讀 Bash 命令、不在執行前詢問的工具（如 Agent），以及工作目錄內的檔案讀取。若要對 Claude 完全隱藏某個內建工具，而非拒絕其呼叫，請將其裸名稱新增到 disallowedTools。

[!WARNING]

allowed_tools 不限制 bypassPermissions。 allowed_tools 預先核准您列出的工具。在 bypassPermissions 模式中，Claude Code 會核准對未列出工具的呼叫，除非該呼叫屬於任何模式都不自動核准的動作。

如果您將 allowed_tools=["Read"] 與 permission_mode="bypassPermissions" 一起設定，Claude Code 仍會核准對 Bash、Write 和 Edit 等工具的呼叫。如果您需要 bypassPermissions 但想要阻止特定工具，請使用 disallowed_tools。關於在此模式中仍會到達您 canUseTool 回呼的呼叫，請參閱略過權限模式。

您也可以在 .claude/settings.json 中以宣告方式設定允許、拒絕和詢問規則。當啟用 project 設定來源時會讀取這些規則，預設 query() 選項就是這樣。如果您明確設定 setting_sources（TypeScript：settingSources），請包含 "project" 以便它們適用。請參閱權限設定以了解規則語法。

關於專案 .claude/settings.json 中的允許規則何時適用，請參閱專案允許規則與工作區信任。

規則中的路徑模式

Read 和 Edit 的限定規則採用路徑模式。Edit(path) 規則管理所有寫入檔案的內建工具，包括 Write 和 NotebookEdit，因此請將其中任何一個工具的路徑規則寫成 Edit(path)。如果您將路徑規則寫成 Write(path) 或 NotebookEdit(path)，它不會符合任何呼叫，也不會產生任何效果。

在 allowed_tools 和 disallowed_tools 中，以 // 開頭表示絕對路徑，或以單個 / 開頭表示工作階段工作目錄內的路徑：

• //path：使用 Edit(//secrets/**) 的拒絕規則時，Claude Code 會阻止 Claude 的檔案工具以及tee 和 > file 重新導向等 Bash 命令寫入磁碟上 /secrets 之下的位置。Claude 執行且自行開啟檔案的指令碼仍可寫入 /secrets 之下。若要由作業系統強制執行，請參閱設定沙箱化的 Bash 工具。
• /path：Edit(/secrets/**) 符合工作目錄內的 secrets 目錄。

關於路徑模式的其他開頭方式，請參閱讀取和編輯規則。

權限模式

權限模式可全域控制 Claude 使用工具的方式。您可以在呼叫 query() 時設定權限模式，或在串流工作階段期間動態變更。

使用 Claude Code v2.1.302 或更新版本時，除非您設定了權限模式，或應用程式從其設定檔中的 permissions.defaultMode 取得權限模式，否則應用程式會以 default 模式啟動。在 default 模式下，Claude Code 會拒絕任何需要核准的工具呼叫，除非您透過 allow 規則、hook、canUseTool 回呼或權限提示工具核准該呼叫。如果工具呼叫遭到拒絕，請參閱在 claude -p 和 Agent SDK 執行中工具呼叫遭到拒絕。

可用模式

SDK 支援以下權限模式：

[!WARNING]

Subagent 繼承： 如果您的主要工作階段處於 plan mode，即使 subagent 的 AgentDefinition 設定了 permissionMode: "acceptEdits"，該 subagent 仍會在 plan mode 中執行。該 subagent 對您原始檔的 Edit 和 Write 呼叫仍會送往您的 canUseTool 回呼。Plan mode 對您定義的 subagent 同樣有效，因此將工作交給 subagent 並不能繞過先審查計劃的步驟。

Subagent 會從主要工作階段繼承 plan、acceptEdits、auto 或 bypassPermissions；而在 default 或 dontAsk 模式的主要工作階段下，subagent 會以您設定的模式執行。即便如此，Claude Code 永遠不會套用 "bypassPermissions" 值，且只有在該 subagent 可使用自動模式時才會套用 "auto" 值。bypassPermissions 例外需要 Claude Code v2.1.267 或更新版本。

Subagent 可能具有不同的系統提示詞，且行為限制比您的主要 agent 更少，因此繼承 bypassPermissions 會授予它們完整、自主的系統存取權。任何模式都不會自動核准的動作仍然適用。

設定權限模式

您可以在開始查詢時設定一次權限模式，也可以在工作階段進行中動態變更。

[tab] 查詢時

在建立查詢時傳入 permission_mode（Python）或 permissionMode（TypeScript）。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Help me refactor this code",
        options=ClaudeAgentOptions(
            permission_mode="default",  # Set the mode here
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

[tab] 串流期間

呼叫 set_permission_mode()（Python）或 setPermissionMode()（TypeScript）即可在工作階段中途變更模式。新模式會立即對所有後續的工具請求生效。這讓您可以從嚴格的限制開始，隨著信任建立再逐步放寬權限，例如在審查 Claude 的初步做法後切換至 acceptEdits。

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

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

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

模式詳細資訊

Accept edits 模式（acceptEdits）

自動核准檔案操作，讓 Claude 無需提示即可編輯程式碼。其他工具（例如非檔案系統操作的 Bash 命令）仍需一般權限。

自動核准的操作：

• 使用 Edit、Write 和 NotebookEdit 工具進行的檔案編輯
• 檔案系統命令：mkdir、touch、rm、rmdir、mv、cp、sed

兩者都適用於工作目錄或您新增之目錄內的路徑。在 Python 中，使用 add_dirs 新增目錄；在 TypeScript 中，則使用 additionalDirectories。在 acceptEdits 模式下，當 Claude 進行以下操作時，Claude Code 不會自動核准該請求：

• 處理該範圍之外的路徑
• 寫入受保護的路徑
• 使用 rm 或 rmdir 移除 Claude Code 識別為關鍵路徑的路徑
• 執行帶有選項、glob，或 timeout 5、LANG=C 等前綴的 touch

適用時機： 您信任 Claude 的編輯並希望加快反覆開發的速度，例如在製作原型期間或在隔離的目錄中工作時。

Don't ask 模式（dontAsk）

將任何權限提示轉換為拒絕，且不會呼叫 canUseTool，不過您安裝的 mod 仍可核准其中部分呼叫。由 allowed_tools、settings.json allow 規則或 hook 預先核准的工具會正常執行。在 default 模式下不需要核准的呼叫也會正常執行，例如讀取您工作目錄內的檔案以及對 Agent 的呼叫。

以下呼叫即使符合 allow 規則也會被拒絕：

• 您的組織設為 ask 的連接器工具
• 需要使用者互動的工具，例如 AskUserQuestion，以及其伺服器設定了 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具
• 您的應用程式將其 permission_policy 設為 always_ask 的自訂工具
• 從網路路徑讀取
• 經識別的關鍵路徑移除

如果您的 PreToolUse hook 對經識別的關鍵路徑移除、從網路路徑讀取，或對標記為 always_ask 之工具的呼叫傳回 allow，該呼叫仍會被拒絕。識別這些移除操作的檢查可能會遺漏某些命令。

適用時機： 您執行 headless agent，並希望對每個原本會提示的呼叫直接拒絕。

Bypass permissions 模式（bypassPermissions）

無需提示即自動核准工具使用，但任何模式都不會自動核准的動作除外。Hook 仍會執行，並可在必要時封鎖操作。在 Linux 和 macOS 上，若不在受認可的沙箱中，無論是以 root 身分或透過 sudo，Claude Code 都會拒絕以此模式啟動，且查詢會在第一個回合之前失敗。

[!WARNING]

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

allowed_tools 不會限制此模式，對您未列出之工具的呼叫也會被核准。以下控制措施仍然適用：

• Deny 規則、明確的 ask 規則和 hook 會在模式檢查之前進行評估，且仍可封鎖工具。
• 您的組織設為 ask 的連接器工具、需要使用者互動的工具、經識別的關鍵路徑移除，以及被標記為 Dangerous rm operation not ruled out 的 Bash 命令，仍會交由您的 canUseTool 回呼處理。識別關鍵路徑移除的檢查可能會遺漏某些命令，且您可以關閉關鍵路徑移除提示。在雲端工作階段之外，對您的應用程式標記為 always_ask 之自訂工具的呼叫也會交由該回呼處理。
• 跨工作階段訊息傳遞防護措施仍然適用。

Plan mode（plan）

Claude 會探索程式碼庫並產生計劃。在規劃期間，使用 Claude 的檔案工具對受保護的路徑以外所做的編輯會送達您的 canUseTool 回呼，即使符合 allow 規則或 PreToolUse hook 傳回 allow 也一樣。AskUserQuestion 呼叫也會送達您的回呼，即使有 allow 規則指名該工具也一樣。

當可使用自動模式時，若沒有 allow 規則核准下列呼叫，Claude Code 會在規劃期間將其送往自動模式的分類器審查，而非送往您的回呼：

• Shell 命令
• 網頁擷取
• 網頁搜尋
• 對其伺服器標記為唯讀之 MCP 工具的呼叫

此審查預設為開啟。若要關閉，請在您傳給 query() 的 settings 選項中，或在您的使用者設定中，將 useAutoModeDuringPlan 設為 false。審查關閉時，網頁搜尋以及對標記為唯讀之 MCP 工具的呼叫會送達您的回呼。

對於 shell 命令和網頁擷取，下表列出每個呼叫是否會送達您的回呼：

如需了解分類器連續拒絕多個呼叫後會發生的情況，請參閱重複封鎖閾值。

[!NOTE]

在 TypeScript SDK 中，如果您將 allowDangerouslySkipPermissions: true 與 permissionMode: 'plan' 一起設定，檔案編輯仍會送達您的 canUseTool 回呼。若要之後使用 setPermissionMode() 將以 plan mode 啟動的工作階段切換為 bypassPermissions，您需要從一開始就設定 allowDangerouslySkipPermissions。

適用時機： 您希望 Claude 先產生計劃，例如在程式碼審查期間或進行大型變更之前。

自動模式（auto）

分類器模型會在 shell 命令和網路請求等動作執行之前進行審查，並對其審查的每個動作予以允許或封鎖。如需自動模式所需的模型與供應商，以及其評估動作的順序，請參閱使用自動模式消除權限提示。

如果您使用 set_model()、setModel() 或 applyFlagSettings()，將處於自動模式的工作階段切換至自動模式不支援的模型，工作階段會變更為 default 模式：

• 您會看到的內容：一則 subtype 為 status、且 permissionMode 設為 "default" 的 system 訊息，TypeScript SDK 將其型別定義為 SDKStatusMessage。從此之後，需要核准且不符合任何 allow 規則的呼叫會送達您的 canUseTool 回呼。
• 若要回到自動模式：切換至受支援的模型，然後呼叫 set_permission_mode("auto") 或 setPermissionMode("auto")。如果您將模型切換回來但未進行該呼叫，工作階段會維持在 default 模式。當不受支援的模型處於作用中時，該呼叫會失敗並顯示 Cannot set permission mode to auto: auto mode unavailable for this model。

在呼叫 set_model()、setModel() 或 applyFlagSettings() 之後變更為 default 模式的行為，需要 Claude Code v2.1.299 或更新版本。

相關資源

如需了解權限評估流程中的其他步驟：

• 處理核准和使用者輸入：互動式核准提示和澄清問題
• Hooks 指南：在代理程式生命週期中的關鍵點執行自訂程式碼
• 權限規則：settings.json 中的宣告式允許/拒絕規則