設定權限

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

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

權限如何被評估

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

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

• permissionMode: 'bypassPermissions'，它自動批准到達權限模式步驟的每個呼叫，除了 任何模式都不自動批准的操作
• 每個裸 allowedTools 條目，例如 "Read"，它在諮詢回呼之前自動批准整個工具，除了 任何模式都不自動批准的操作

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

使用 process.on('warning', ...) 進行監聽並匹配代碼以記錄或抑制它。要無論模式和規則如何都控制每個工具呼叫，請改用 PreToolUse hook。

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

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

允許和拒絕規則

allowed_tools 和 disallowed_tools（TypeScript：allowedTools / disallowedTools）在上述評估流程中新增允許和拒絕規則清單的項目。如果您在 allowed_tools 中命名其中一個任務追蹤工具，Claude Code 也會選擇加入該工作階段。任何未列在 allowed_tools 中的其他工具仍可供 Claude 使用，對其進行的需要批准的呼叫會進入權限模式。拒絕規則的行為取決於它們是命名工具還是在工具內限定模式。

允許規則僅在字面 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。請參閱讀取和編輯規則以了解四種錨定形式以及來自設定檔的規則如何解析。

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

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

列出的工具會被批准，除了任何模式都不自動批准的動作，以及每個其他會提示的呼叫都會被拒絕。在 default 模式中不需要批准的呼叫會執行，無論您是否列出它們，例如唯讀 Bash 命令、不在執行前詢問的工具（如 Agent），以及工作目錄內的檔案讀取。要將工具完全置於 Claude 的範圍之外，請將其裸名稱新增到 disallowedTools。

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

權限模式

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

可用模式

SDK 支援這些權限模式：

設定權限模式

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

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

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 內的路徑。在 acceptEdits 模式中，當 Claude 執行以下操作時，Claude Code 不會自動核准請求：

• 在該範圍外的路徑上工作
• 寫入受保護的路徑
• 使用 rm 或 rmdir 移除關鍵路徑

使用時機： 您信任 Claude 的編輯並想要更快的迭代，例如在原型設計期間或在隔離目錄中工作時。

不要詢問模式（`dontAsk`）

將任何權限提示轉換為拒絕，而不呼叫 canUseTool。由 allowed_tools、settings.json 允許規則或鉤子預先核准的工具會正常執行，在 default 模式中不需要核准的呼叫也會執行，例如在您的工作目錄內的檔案讀取和對 Agent 的呼叫。您的組織設定為 ask 的連接器工具、需要使用者互動的工具，以及針對關鍵路徑的 rm 和 rmdir 移除即使符合允許規則也會被拒絕。PreToolUse 鉤子允許也不會清除關鍵路徑移除。

使用時機： 您想要為無頭代理提供固定、明確的工具表面，並偏好硬拒絕而非無聲依賴 canUseTool 不存在。

略過權限模式（`bypassPermissions`）

自動核准工具使用而不提示，除了下面警告中列出的情況。鉤子仍然執行，如果需要可以阻止操作。

規劃模式（`plan`）

Claude 探索程式碼庫並產生計畫，而不編輯您的原始檔案。唯讀工具的執行方式與在 default 權限模式中相同。

在規劃模式中，檔案編輯永遠不會自動被核准，即使符合允許規則。它們會改為透過您的 canUseTool 回呼提示。在 Claude Code v2.1.212 或更新版本上，修改檔案的 shell 命令（例如 touch 和 rm）會以相同方式到達您的 canUseTool 回呼。

如果您在 permissionMode: 'plan' 旁邊設定 allowDangerouslySkipPermissions: true，檔案編輯和修改檔案的 shell 命令仍然會到達您的 canUseTool 回呼。此選項讓您稍後可以使用 setPermissionMode() 切換到 bypassPermissions。

Claude 可能會使用 AskUserQuestion 在最終確定計畫之前澄清需求。請參閱處理核准和使用者輸入以處理這些提示。

使用時機： 您想要 Claude 提議變更而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。

相關資源

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

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