設定權限

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

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

權限如何被評估

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

Hooks

首先執行 hooks。Hook 可以直接拒絕呼叫或將其傳遞。返回 allow 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。

拒絕規則

檢查 deny 規則（來自 disallowed_tools 和 settings.json）。如果拒絕規則符合，工具會被阻止，即使在 bypassPermissions 模式下也是如此。裸名稱拒絕規則（如 Bash）會在此評估開始前將工具從 Claude 的上下文中移除，因此只有範圍規則（如 Bash(rm *)）會在此步驟中被檢查。

詢問規則

檢查來自 settings.json 的 ask 規則。如果詢問規則符合，呼叫會傳遞到您的 canUseTool 回呼以進行確認，即使在 bypassPermissions 模式下也是如此。需要使用者互動的工具行為相同：AskUserQuestion 和 MCP 工具（其伺服器設定 _meta["anthropic/requiresUserInteraction"]）總是會傳遞到回呼，即使允許規則符合時也是如此。在 dontAsk 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。MCP 註解需要 Claude Code v2.1.199 或更新版本。claude.ai 連接器工具（您的組織已設定為 ask）也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 bypassPermissions 模式下，即使允許規則符合時也是如此。回呼會收到原因 Your organization requires approval for this tool。在 dontAsk 模式下，呼叫會被拒絕，因為該模式永遠不會提示。

權限模式

應用活躍的權限模式。bypassPermissions 批准到達此步驟的所有內容。acceptEdits 批准檔案操作。plan 將檔案編輯和 shell 寫入工具路由到您的 canUseTool 回呼，無論允許規則如何，因此在規劃時寫入操作無法自動批准。其他模式會通過。

允許規則

檢查 allow 規則（來自 allowed_tools 和 settings.json）。如果規則符合，工具會被批准。

canUseTool 回呼

如果上述任何步驟都未解決，請呼叫您的 canUseTool 回呼以做出決定。在 dontAsk 模式下，此步驟會被跳過，工具會被拒絕。

六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。

自 v2.1.198 起，如果您傳遞一個 canUseTool 回呼，而此評估順序永遠無法到達，TypeScript SDK 會在建構查詢時發出一次 Node.js 程序警告。警告的代碼是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。兩種配置會觸發它：

permissionMode: 'bypassPermissions'，它會自動批准到達權限模式步驟的每個呼叫
每個裸 allowedTools 項目，例如 "Read"，它會在諮詢回呼之前自動批准整個工具

具有指定符的項目（例如 Bash(ls *)）和 acceptEdits 模式不會觸發它，來自設定檔的允許規則對檢查不可見。使用 process.on('warning', ...) 進行監聽，並匹配代碼以記錄或抑制它。若要無論模式和規則如何都控制每個工具呼叫，請改用 PreToolUse hook。本頁重點關注 允許和拒絕規則 以及 權限模式。對於其他步驟：

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

允許和拒絕規則

allowed_tools 和 disallowed_tools（TypeScript：allowedTools / disallowedTools）將條目新增到上述評估流程中的允許和拒絕規則清單。允許規則只影響批准：未列在 allowed_tools 中的工具仍然可供 Claude 使用，並會通過權限模式。拒絕規則的行為取決於它們是命名工具還是在工具內限定模式。

選項	效果
`allowed_tools=["Read", "Grep"]`	`Read` 和 `Grep` 會自動批准。此處未列出的工具仍然存在，並會通過權限模式和 `canUseTool`。
`disallowed_tools=["Bash"]`	`Bash` 工具定義會從請求中移除。Claude 看不到該工具，無法嘗試使用它。
`disallowed_tools=["Bash(rm *)"]`	`Bash` 保持可用。符合 `rm *` 的呼叫在每個權限模式中都會被拒絕，包括 `bypassPermissions`。其他 `Bash` 呼叫會通過權限模式。
`disallowed_tools=["*"]`	每個工具定義都會從請求中移除。工具名稱萬用字元在拒絕規則中受支援：`""` 符合每個工具，`"mcp__"` 符合所有伺服器上的每個 MCP 工具。

允許規則只在字面 mcp__<server>__ 前綴之後接受工具名稱萬用字元。伺服器段必須不含萬用字元，以便規則命名您設定的特定伺服器：mcp__puppeteer__* 符合來自 puppeteer 伺服器的每個工具，mcp__github__get_* 符合其 get_ 工具。未錨定的條目（如 allowed_tools=["*"] 或 allowed_tools=["mcp__*"]）會被忽略並顯示啟動警告，不會自動批准任何內容。 Read 和 Edit 的限定規則採用路徑模式。Edit(path) 規則管理所有寫入檔案的內建工具，包括 Write 和 NotebookEdit；Write(path) 規則永遠不會被檔案權限檢查符合。使用 //path 表示絕對檔案系統路徑：Edit(//secrets/**) 的拒絕規則會阻止在磁碟上 /secrets 下任何位置的寫入。使用單個前導斜線，Edit(/secrets/**) 會在規則的來源處錨定。對於通過 allowed_tools 或 disallowed_tools 傳遞的規則，這表示工作階段的工作目錄，因此規則不會阻止磁碟上的 /secrets。請參閱 Read 和 Edit 規則以了解四種錨定形式以及來自設定檔案的規則如何解析。

自動批准的工具永遠不會到達 canUseTool。 在任何較早步驟中批准的工具呼叫，由 acceptEdits 或 bypassPermissions 或允許規則批准，會跳過您的 canUseTool 回呼，因此您在那裡放置的權限檢查會被該工具無聲地略過。AskUserQuestion、標記為 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具，以及連接器工具您的組織設定為 ask 仍會到達回呼，即使允許規則符合時也是如此。涵蓋範圍取決於條目的形式：像 Read 或 mcp__github__get_issue 這樣的裸名稱會自動批准對該工具的每個呼叫，而像 Bash(ls *) 這樣的限定規則只會自動批准符合的呼叫，其他 Bash 呼叫仍會通過回呼。對於必須在每個工具呼叫上執行的檢查，請使用 PreToolUse hook：hook 在每個其他步驟之前執行，hook 拒絕甚至在 bypassPermissions 模式中也適用。

對於鎖定的代理程式，將 allowedTools 與 permissionMode: "dontAsk" 配對。列出的工具會被批准，除了上述警告中的始終提示工具外；其他任何工具都會被直接拒絕，而不是提示：

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

allowed_tools 不會限制 bypassPermissions。 allowed_tools 只會預先批准您列出的工具。未列出的工具不會被任何允許規則符合，並會通過權限模式，其中 bypassPermissions 會批准它們。將 allowed_tools=["Read"] 與 permission_mode="bypassPermissions" 一起設定仍然會批准每個工具，包括 Bash、Write 和 Edit。如果您需要 bypassPermissions 但想要阻止特定工具，請使用 disallowed_tools。

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

權限模式

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

可用模式

SDK 支援這些權限模式：

模式	描述	工具行為
`default`	標準權限行為	無自動批准；不符合的工具會觸發您的 `canUseTool` 回呼
`dontAsk`	拒絕而不是提示	任何未被 `allowed_tools` 或規則預先批准的內容都會被拒絕；連接器工具您的組織設定為 `ask`和需要使用者互動的工具即使您已預先批准它們也會被拒絕。`canUseTool` 永遠不會被呼叫
`acceptEdits`	自動接受檔案編輯	檔案編輯和檔案系統操作（`mkdir`、`rm`、`mv` 等）會自動被批准
`bypassPermissions`	繞過權限檢查	工具執行時無需權限提示，除了明確的`ask` 規則符合的工具、連接器工具您的組織設定為 `ask`和需要使用者互動的工具（謹慎使用）
`plan`	規劃模式	Claude 在不編輯您的原始檔案的情況下探索和規劃；檔案編輯永遠不會自動批准，並透過您的 `canUseTool` 回呼提示
`auto`	模型分類批准	模型分類器批准或拒絕每個工具呼叫。請參閱 Auto 模式以了解可用性

子代理程式繼承： 當父代理程式使用 bypassPermissions、acceptEdits 或 auto 時，所有子代理程式都會繼承該模式，且無法按子代理程式覆蓋。子代理程式可能有不同的系統提示和行為限制較少，因此繼承 bypassPermissions 會授予它們完整的自主系統存取權。明確的ask 規則、連接器工具您的組織設定為 ask和需要使用者互動的工具仍然會強制提示。

設定權限模式

您可以在開始查詢時設定一次權限模式，或在會話活躍時動態更改它。

在查詢時
在串流期間

在建立查詢時傳遞 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();

呼叫 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();

模式詳細資訊

接受編輯模式（`acceptEdits`）

自動批准檔案操作，以便 Claude 可以編輯程式碼而無需提示。其他工具（例如不是檔案系統操作的 Bash 命令）仍然需要正常權限。 自動批准的操作：

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

兩者都只適用於工作目錄或 additionalDirectories 內的路徑。該範圍外的路徑和對受保護路徑的寫入仍然會提示。 使用時機： 您信任 Claude 的編輯並想要更快的迭代，例如在原型設計期間或在隔離目錄中工作時。

不詢問模式（`dontAsk`）

將任何權限提示轉換為拒絕。由 allowed_tools、settings.json 允許規則或作為 hook 執行的工具會正常執行。連接器工具您的組織設定為 ask和需要使用者互動的工具即使允許規則符合也會被拒絕。其他所有內容都會被拒絕，而不呼叫 canUseTool。 使用時機： 您想要為無頭代理程式提供固定的明確工具表面，並且更喜歡硬拒絕而不是無聲依賴 canUseTool 不存在。

繞過權限模式（`bypassPermissions`）

自動批准所有工具使用而無需提示。Hooks 仍然執行，如果需要可以阻止操作。

謹慎使用。Claude 在此模式下具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。allowed_tools 不會限制此模式。每個工具都會被批准，而不僅僅是您列出的工具。拒絕規則（disallowed_tools）、明確的 ask 規則和 hooks 會在模式檢查之前被評估，仍然可以阻止工具。連接器工具您的組織設定為 ask和需要使用者互動的工具仍然會透過您的 canUseTool 回呼進行。

規劃模式（`plan`）

Claude 探索程式碼庫並產生計畫而不編輯您的原始檔案。唯讀工具在預設模式下執行。檔案編輯在規劃模式下永遠不會自動批准，即使允許規則符合。它們改為透過您的 canUseTool 回呼提示。Claude 可能會使用 AskUserQuestion 在最終確定計畫之前澄清需求。請參閱處理核准和使用者輸入以處理這些提示。 使用時機： 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。對於權限評估流程中的其他步驟：

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

Agent SDK

核心概念

輸入和輸出

使用工具擴充

自訂行為

控制與可觀測性

部署

SDK 參考資料

權限如何被評估

允許和拒絕規則

權限模式

可用模式

設定權限模式

模式詳細資訊

接受編輯模式（`acceptEdits`）

不詢問模式（`dontAsk`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）

​權限如何被評估

​允許和拒絕規則

​權限模式

​可用模式

​設定權限模式

​模式詳細資訊

​接受編輯模式（acceptEdits）

​不詢問模式（dontAsk）

​繞過權限模式（bypassPermissions）

​規劃模式（plan）

​相關資源

權限如何被評估

允許和拒絕規則

權限模式

可用模式

設定權限模式

模式詳細資訊

接受編輯模式（`acceptEdits`）

不詢問模式（`dontAsk`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）

相關資源