Cấu hình permission

Claude Agent SDK cung cấp permission control để quản lý cách Claude dùng tool. Dùng permission mode và rule để định nghĩa những gì được phép tự động, và canUseTool callback để xử lý mọi thứ còn lại tại runtime.

Ghi chú

Trang này bao gồm permission mode và rule. Để xây interactive approval flow nơi người dùng approve hoặc deny tool request tại runtime, xem Xử lý approval và user input.

Permission được đánh giá như thế nào

Khi Claude yêu cầu một tool, SDK kiểm tra permission theo thứ tự này:

1. Hooks. Chạy hook trước tiên. Một hook có thể deny lời gọi hoàn toàn hoặc chuyển tiếp nó. Một hook trả về allow không bỏ qua các rule deny và ask bên dưới; những rule đó vẫn được đánh giá bất kể kết quả hook.

2. Deny rule. Kiểm tra deny rule (từ disallowed_tools và settings.json). Nếu một deny rule khớp, tool bị chặn, kể cả trong mode bypassPermissions. Deny rule dạng tên trần như Bash loại bỏ tool khỏi context của Claude trước khi bước đánh giá này bắt đầu, nên chỉ rule có scope như Bash(rm *) mới được kiểm tra ở bước này.

3. Ask rule. Kiểm tra ask rule từ settings.json. Nếu một ask rule khớp, lời gọi rơi xuống canUseTool callback của bạn để xác nhận, kể cả trong mode bypassPermissions.

   Tool cần tương tác người dùng hoạt động tương tự: AskUserQuestion và MCP tool mà server của nó đặt _meta["anthropic/requiresUserInteraction"] luôn rơi xuống callback, kể cả khi một allow rule khớp. Trong mode dontAsk cả hai trường hợp đều bị deny thay vì rơi xuống callback, vì mode đó không bao giờ hỏi. Annotation MCP này yêu cầu Claude Code v2.1.199 trở lên.

   Tool claude.ai connector mà tổ chức của bạn đặt thành ask cũng rời khỏi flow ở bước này. Mọi lời gọi đều rơi xuống callback, kể cả trong mode bypassPermissions và kể cả khi một allow rule khớp. Callback nhận reason Your organization requires approval for this tool. Trong mode dontAsk, lời gọi bị deny thay vì rơi xuống callback, vì mode đó không bao giờ hỏi.

4. Permission mode. Áp dụng permission mode đang active. bypassPermissions approve mọi thứ tới được bước này. acceptEdits approve các thao tác file. plan chuyển tool sửa file và tool ghi shell tới canUseTool callback của bạn bất kể allow rule, nên thao tác ghi không thể được tự động approve khi đang plan. Các mode khác rơi xuống bước tiếp theo.

5. Allow rule. Kiểm tra allow rule (từ allowed_tools và settings.json). Nếu một rule khớp, tool được approve.

6. canUseTool callback. Nếu không được giải quyết bởi bất kỳ bước nào ở trên, gọi canUseTool callback của bạn để đưa quyết định. Trong mode dontAsk, bước này bị bỏ qua và tool bị deny.

Kể từ v2.1.198, nếu bạn truyền một canUseTool callback mà thứ tự đánh giá này không bao giờ chạm tới được, TypeScript SDK phát một Node.js process warning một lần khi query được khởi tạo. Code của warning là CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Hai cấu hình kích hoạt nó:

• permissionMode: 'bypassPermissions', tự động approve mọi lời gọi tới được bước permission mode
• Mỗi entry allowedTools dạng tên trần như "Read", tự động approve toàn bộ tool đó trước khi callback được hỏi

Entry có specifier như Bash(ls *) và mode acceptEdits không kích hoạt warning này, và allow rule đến từ settings file thì không nhìn thấy được với check này.

Lắng nghe bằng process.on('warning', ...) và so khớp code để log hoặc bỏ qua nó. Để chặn mọi tool call bất kể mode và rule, dùng PreToolUse hook thay vào đó.

Trang này tập trung vào allow và deny rule và permission mode. Với các bước khác:

• Hooks: chạy code tuỳ biến để allow, deny, hoặc modify tool request. Xem Kiểm soát thực thi bằng hooks.
• canUseTool callback: prompt người dùng approve tại runtime, khi không bước nào trước đó giải quyết được lời gọi. Xem Xử lý approval và user input.

Allow và deny rule

allowed_tools và disallowed_tools (TypeScript: allowedTools / disallowedTools) thêm entry vào danh sách allow và deny rule trong flow đánh giá ở trên. Allow rule chỉ ảnh hưởng tới approval: một tool không nằm trong allowed_tools vẫn khả dụng với Claude và rơi xuống permission mode. Deny rule hoạt động khác nhau tuỳ vào việc nó chỉ đích danh một tool hay scope một pattern trong tool đó.

Option	Hiệu ứng
allowed_tools=["Read", "Grep"]	Read và Grep được tự động approve. Tool không có trong danh sách này vẫn tồn tại và rơi xuống permission mode và canUseTool.
disallowed_tools=["Bash"]	Định nghĩa tool Bash bị loại khỏi request. Claude không thấy tool này và không thể thử gọi nó.
disallowed_tools=["Bash(rm *)"]	Bash vẫn khả dụng. Lời gọi khớp rm * bị deny trong mọi permission mode, kể cả bypassPermissions. Lời gọi Bash khác rơi xuống permission mode.
disallowed_tools=["*"]	Mọi định nghĩa tool bị loại khỏi request. Glob cho tên tool được hỗ trợ trong deny rule: "*" khớp mọi tool và "mcp__*" khớp mọi MCP tool trên mọi server.

Allow rule chỉ chấp nhận tool-name glob sau một prefix mcp__<server>__ cố định. Phần server phải không có glob vì rule phải chỉ đích danh một server cụ thể bạn đã cấu hình: mcp__puppeteer__* khớp mọi tool từ server puppeteer, và mcp__github__get_* khớp các tool bắt đầu bằng get_ của nó. Một entry không được neo như allowed_tools=["*"] hoặc allowed_tools=["mcp__*"] bị bỏ qua kèm startup warning và không tự động approve gì cả.

Rule có scope cho Read và Edit nhận một path pattern. Rule Edit(path) chi phối mọi built-in tool ghi file, bao gồm cả Write và NotebookEdit; một rule Write(path) không bao giờ được match bởi các check permission file.

Dùng //path cho một absolute filesystem path: một deny rule Edit(//secrets/**) chặn ghi ở bất kỳ đâu dưới /secrets trên đĩa. Với một dấu slash đầu, Edit(/secrets/**) neo tại nguồn gốc của rule thay vào đó. Với rule truyền qua allowed_tools hoặc disallowed_tools, đó là working directory của session, nên rule này không chặn /secrets trên đĩa. Xem Rule Read và Edit để biết bốn dạng neo và cách rule từ settings file được resolve.

Chú ý

Tool được tự động approve không bao giờ chạm tới canUseTool. Một tool call được approve ở bất kỳ bước nào trước đó, bởi acceptEdits hay bypassPermissions, hoặc bởi một allow rule, bỏ qua canUseTool callback của bạn, nên các permission check bạn đặt ở đó bị bỏ qua âm thầm cho tool đó. AskUserQuestion, MCP tool đánh dấu _meta["anthropic/requiresUserInteraction"], và connector tool tổ chức của bạn đặt thành ask vẫn chạm tới callback, kể cả khi một allow rule khớp.

Độ bao phủ tuỳ vào dạng của entry: một tên trần như Read hoặc mcp__github__get_issue tự động approve mọi lời gọi tới tool đó, trong khi một rule có scope như Bash(ls *) chỉ tự động approve lời gọi khớp và các lời gọi Bash khác vẫn rơi xuống callback. Với các check cần chạy trên mọi tool call, dùng PreToolUse hook: hook chạy trước mọi bước khác, và một hook deny áp dụng kể cả trong mode bypassPermissions.

Với một agent bị khoá chặt, kết hợp allowedTools với permissionMode: "dontAsk". Tool có trong danh sách được approve, ngoại trừ các tool luôn-prompt trong Caution ở trên; mọi thứ khác bị deny thẳng thay vì prompt:

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

Chú ý

allowed_tools không giới hạn bypassPermissions. allowed_tools chỉ pre-approve các tool bạn liệt kê. Tool không có trong danh sách không được allow rule nào match và rơi xuống permission mode, nơi bypassPermissions approve chúng. Đặt allowed_tools=["Read"] cùng với permission_mode="bypassPermissions" vẫn approve mọi tool, bao gồm Bash, Write, và Edit. Nếu bạn cần bypassPermissions nhưng muốn chặn một số tool cụ thể, dùng disallowed_tools.

Bạn cũng có thể cấu hình allow, deny, và ask rule một cách khai báo trong .claude/settings.json. Các rule này được đọc khi setting source project được bật, mặc định là bật với các option query() mặc định. Nếu bạn đặt setting_sources (TypeScript: settingSources) tường minh, hãy bao gồm "project" để chúng áp dụng. Xem Permission settings để biết cú pháp rule.

Permission mode

Permission mode cung cấp kiểm soát toàn cục về cách Claude dùng tool. Bạn có thể đặt permission mode khi gọi query() hoặc thay đổi nó động trong lúc streaming session.

Các mode khả dụng

SDK hỗ trợ các permission mode sau:

Mode	Mô tả	Hành vi của tool
default	Hành vi permission chuẩn	Không tự động approve; tool không khớp rule nào kích hoạt canUseTool callback của bạn
dontAsk	Deny thay vì prompt	Bất cứ gì chưa được allowed_tools hoặc rule pre-approve đều bị deny; connector tool tổ chức của bạn đặt thành ask và tool cần tương tác người dùng đều bị deny kể cả khi đã pre-approve. canUseTool không bao giờ được gọi
acceptEdits	Tự động chấp nhận sửa file	Sửa file và thao tác filesystem (mkdir, rm, mv, v.v.) được tự động approve
bypassPermissions	Bỏ qua permission check	Tool chạy không có permission prompt, trừ tool khớp một ask rule tường minh, connector tool tổ chức của bạn đặt thành ask, và tool cần tương tác người dùng (dùng cẩn thận)
plan	Planning mode	Claude khám phá và lên plan mà không sửa source file của bạn; sửa file không bao giờ được tự động approve và prompt qua canUseTool callback của bạn
auto	Approval phân loại bởi model	Một model classifier approve hoặc deny permission prompt. Xem Auto mode để biết mức độ khả dụng

Chú ý

Subagent kế thừa mode: Subagent kế thừa permission mode của parent session. permissionMode trên AgentDefinition có thể override nó, trừ khi parent dùng bypassPermissions, acceptEdits, hoặc auto: các mode đó áp dụng cho mọi subagent và không thể override theo từng subagent.

Subagent có thể có system prompt khác và hành vi ít bị ràng buộc hơn agent chính của bạn, nên kế thừa bypassPermissions cấp cho chúng quyền truy cập hệ thống đầy đủ, tự động. Ask rule tường minh, connector tool tổ chức của bạn đặt thành ask, và tool cần tương tác người dùng vẫn buộc phải prompt.

Đặt permission mode

Bạn có thể đặt permission mode một lần khi bắt đầu một query, hoặc thay đổi nó động trong khi session đang active.

Tại thời điểm query

Truyền permission_mode (Python) hoặc permissionMode (TypeScript) khi tạo một query. Mode này áp dụng cho toàn bộ session trừ khi được thay đổi động.

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

Trong khi streaming

Gọi set_permission_mode() (Python) hoặc setPermissionMode() (TypeScript) để thay đổi mode giữa session. Mode mới có hiệu lực ngay lập tức cho mọi tool request tiếp theo. Điều này cho phép bạn bắt đầu chặt chẽ rồi nới lỏng permission khi độ tin cậy tăng lên, ví dụ chuyển sang acceptEdits sau khi review cách tiếp cận ban đầu của Claude.

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

Chi tiết từng mode

Accept edits mode (acceptEdits)

Tự động approve thao tác file để Claude có thể sửa code mà không cần prompt. Tool khác (như lệnh Bash không phải thao tác filesystem) vẫn cần permission bình thường.

Thao tác được tự động approve:

• Sửa file (tool Edit, Write)
• Lệnh filesystem: mkdir, touch, rm, rmdir, mv, cp, sed

Cả hai chỉ áp dụng cho path bên trong working directory hoặc additionalDirectories. Path bên ngoài phạm vi đó và ghi vào path được bảo vệ vẫn prompt.

Dùng khi: bạn tin tưởng các sửa đổi của Claude và muốn lặp nhanh hơn, ví dụ khi đang prototype hoặc làm việc trong một thư mục cô lập.

Don’t ask mode (dontAsk)

Chuyển mọi permission prompt thành deny. Tool được pre-approve bởi allowed_tools, allow rule trong settings.json, hoặc một hook vẫn chạy bình thường. Connector tool tổ chức của bạn đặt thành ask và tool cần tương tác người dùng bị deny kể cả khi một allow rule khớp. Mọi thứ khác bị deny mà không gọi canUseTool.

Dùng khi: bạn muốn một tool surface cố định, tường minh cho một headless agent và ưu tiên hard deny hơn là dựa ngầm vào việc canUseTool không tồn tại.

Bypass permissions mode (bypassPermissions)

Tự động approve mọi lần dùng tool mà không prompt. Hook vẫn thực thi và có thể chặn thao tác nếu cần.

Chú ý

Dùng hết sức cẩn thận. Claude có quyền truy cập hệ thống đầy đủ trong mode này. Chỉ dùng trong môi trường có kiểm soát nơi bạn tin tưởng mọi thao tác có thể xảy ra.

allowed_tools không giới hạn mode này. Mọi tool đều được approve, không chỉ những tool bạn liệt kê. Deny rule (disallowed_tools), ask rule tường minh, và hook được đánh giá trước bước kiểm tra mode và vẫn có thể chặn một tool. Connector tool tổ chức của bạn đặt thành ask và tool cần tương tác người dùng vẫn rơi xuống canUseTool callback của bạn.

Plan mode (plan)

Claude khám phá codebase và tạo một plan mà không sửa source file của bạn. Tool chỉ đọc chạy như trong default mode.

Sửa file không bao giờ được tự động approve trong plan mode, kể cả khi một allow rule khớp. Chúng prompt qua canUseTool callback của bạn thay vào đó. Trên Claude Code v2.1.212 trở lên, lệnh shell sửa file, như touch và rm, cũng chạm tới canUseTool callback của bạn theo cách tương tự.

Claude có thể dùng AskUserQuestion để làm rõ yêu cầu trước khi hoàn thiện plan. Xem Xử lý approval và user input để xử lý các prompt này.

Dùng khi: bạn muốn Claude đề xuất thay đổi mà không thực thi chúng, ví dụ khi code review hoặc khi bạn cần approve thay đổi trước khi chúng được thực hiện.

Tài nguyên liên quan

Với các bước khác trong flow đánh giá permission:

• Xử lý approval và user input: approval prompt tương tác và câu hỏi làm rõ
• Hướng dẫn Hooks: chạy code tuỳ biến tại các điểm chính trong vòng đời agent
• Permission rules: rule allow/deny khai báo trong settings.json

Nguồn

Dịch và biên soạn từ Configure permissions.