設定權限 - Claude Code Docs

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

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

權限如何被評估

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

Hooks

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

拒絕規則

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

權限模式

應用活躍的權限模式。bypassPermissions 批准到達此步驟的所有內容。acceptEdits 批准檔案操作。其他模式會通過。

允許規則

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

canUseTool 回呼

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

本頁重點關注 允許和拒絕規則 以及 權限模式。對於其他步驟：

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` 呼叫會通過權限模式。

對於鎖定的代理程式，將 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` 或規則預先批准的內容都會被拒絕；`canUseTool` 永遠不會被呼叫
`acceptEdits`	自動接受檔案編輯	檔案編輯和檔案系統操作（`mkdir`、`rm`、`mv` 等）會自動被批准
`bypassPermissions`	繞過所有權限檢查	所有工具執行時無需權限提示（謹慎使用）
`plan`	規劃模式	唯讀工具執行；Claude 分析和規劃而不編輯您的原始檔案
`auto`（僅 TypeScript）	模型分類批准	模型分類器批准或拒絕每個工具呼叫。請參閱 Auto 模式以了解可用性

子代理程式繼承： 當父代理程式使用 bypassPermissions、acceptEdits 或 auto 時，所有子代理程式都會繼承該模式，且無法按子代理程式覆蓋。子代理程式可能有不同的系統提示和行為限制較少，因此繼承 bypassPermissions 會授予它們完整的自主系統存取權，無需任何核准提示。

設定權限模式

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

在查詢時
在串流期間

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

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

模式詳細資訊

接受編輯模式（`acceptEdits`）

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

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

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

不詢問模式（`dontAsk`）

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

繞過權限模式（`bypassPermissions`）

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

謹慎使用。Claude 在此模式下具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。allowed_tools 不會限制此模式。每個工具都會被批准，而不僅僅是您列出的工具。拒絕規則（disallowed_tools）、明確的 ask 規則和 hooks 會在模式檢查之前被評估，仍然可以阻止工具。

規劃模式（`plan`）

將 Claude 限制為唯讀工具。Claude 可以讀取檔案並執行唯讀 shell 命令來探索程式碼庫，但不編輯您的原始檔案。Claude 可能會使用 AskUserQuestion 在最終確定計畫之前澄清需求。請參閱處理核准和使用者輸入以處理這些提示。 使用時機： 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。

​權限如何被評估

​允許和拒絕規則

​權限模式

​可用模式

​設定權限模式

​模式詳細資訊

​接受編輯模式（acceptEdits）

​不詢問模式（dontAsk）

​繞過權限模式（bypassPermissions）

​規劃模式（plan）

​相關資源

權限如何被評估

允許和拒絕規則

權限模式

可用模式

設定權限模式

模式詳細資訊

接受編輯模式（`acceptEdits`）

不詢問模式（`dontAsk`）

繞過權限模式（`bypassPermissions`）

規劃模式（`plan`）

相關資源