設定權限
使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理程式如何使用工具。
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 模式下也是如此。在 dontAsk 模式下，符合的詢問規則會被拒絕，因為該模式永遠不會提示。
權限模式
應用活躍的 權限模式。bypassPermissions 批准到達此步驟的所有內容。acceptEdits 批准檔案操作。plan 將檔案編輯和 shell 寫入工具路由到您的 canUseTool 回呼，無論允許規則如何，因此在規劃時寫入操作無法自動批准。其他模式會通過。
允許規則
檢查 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 呼叫會通過權限模式。 |
disallowed_tools=["*"] |
每個工具定義都會從請求中移除。工具名稱萬用字元在拒絕規則中受支援："*" 符合每個工具，"mcp__*" 符合所有伺服器上的每個 MCP 工具。 |
允許規則只在字面 mcp__<server>__ 前綴之後接受工具名稱萬用字元。伺服器段必須不含萬用字元，以便規則命名您設定的特定伺服器：mcp__puppeteer__* 符合來自 puppeteer 伺服器的每個工具，mcp__github__get_* 符合其 get_ 工具。未錨定的條目（如 allowed_tools=["*"] 或 allowed_tools=["mcp__*"]）會被忽略並顯示啟動警告，不會自動批准任何內容。
對於鎖定的代理程式，將 allowedTools 與 permissionMode: "dontAsk" 配對。列出的工具會被批准；其他任何工具都會被直接拒絕，而不是提示：
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};
您也可以在 .claude/settings.json 中宣告式地設定允許、拒絕和詢問規則。當啟用 project 設定來源時，這些規則會被讀取，預設 query() 選項就是這樣。如果您明確設定 setting_sources（TypeScript：settingSources），請包含 "project" 以便它們適用。請參閱 權限設定 以了解規則語法。
權限模式
權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 query() 時設定權限模式，或在串流會話期間動態更改它。
可用模式
SDK 支援這些權限模式：
| 模式 | 描述 | 工具行為 |
|---|---|---|
default |
標準權限行為 | 無自動批准；不符合的工具會觸發您的 canUseTool 回呼 |
dontAsk |
拒絕而不是提示 | 任何未被 allowed_tools 或規則預先批准的內容都會被拒絕；canUseTool 永遠不會被呼叫 |
acceptEdits |
自動接受檔案編輯 | 檔案編輯和檔案系統操作（mkdir、rm、mv 等）會自動被批准 |
bypassPermissions |
繞過權限檢查 | 工具執行時無需權限提示，除非明確的ask 規則符合（謹慎使用） |
plan |
規劃模式 | Claude 在不編輯您的原始檔案的情況下探索和規劃；檔案編輯永遠不會自動批准，並透過您的 canUseTool 回呼提示 |
auto（僅 TypeScript） |
模型分類批准 | 模型分類器批准或拒絕每個工具呼叫。請參閱 Auto 模式 以了解可用性 |
設定權限模式
您可以在開始查詢時設定一次權限模式，或在會話活躍時動態更改它。
在建立查詢時傳遞 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 執行的工具會正常執行。其他所有內容都會被拒絕，而不呼叫 canUseTool。
使用時機： 您想要為無頭代理程式提供固定的明確工具表面，並且更喜歡硬拒絕而不是無聲依賴 canUseTool 不存在。
繞過權限模式（`bypassPermissions`）
自動批准所有工具使用而無需提示。Hooks 仍然執行，如果需要可以阻止操作。
規劃模式（`plan`）
Claude 探索程式碼庫並產生計畫而不編輯您的原始檔案。唯讀工具在預設模式下執行。檔案編輯在規劃模式下永遠不會自動批准，即使允許規則符合。它們改為透過您的 canUseTool 回呼提示。Claude 可能會使用 AskUserQuestion 在最終確定計畫之前澄清需求。請參閱處理核准和使用者輸入以處理這些提示。
使用時機： 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。
相關資源
對於權限評估流程中的其他步驟：
- 處理核准和使用者輸入：互動式核准提示和澄清問題
- Hooks 指南：在代理程式生命週期中的關鍵點執行自訂程式碼
- 權限規則：
settings.json中的宣告式允許/拒絕規則