Cấu hình permissions

Claude Code hỗ trợ hệ thống permission (quyền hạn) chi tiết để bạn chỉ định chính xác agent được phép làm gì và không được làm gì. Bạn có thể commit cấu hình permission vào version control để chia sẻ với cả team, và mỗi developer vẫn có thể tuỳ chỉnh riêng.

Hệ thống permission

Claude Code dùng hệ thống permission phân tầng để cân bằng giữa sức mạnh và an toàn:

Loại tool	Ví dụ	Cần phê duyệt?	Hành vi “Yes, don’t ask again”
Read-only (chỉ đọc)	Đọc file, Grep	Không, trong phạm vi working directory và additional directories	N/A
Lệnh Bash	Thực thi shell	Có, trừ tập lệnh read-only có sẵn	Lưu vĩnh viễn theo repository + lệnh
Sửa file	Edit/write file	Có	Đến hết session

Khi bạn chọn “Yes, don’t ask again” và việc phê duyệt được lưu vĩnh viễn (như với lệnh Bash), Claude Code lưu rule vào .claude/settings.local.json tại root của git repository (đã resolve qua worktrees về checkout chính). Rule này áp dụng cho các session sau này ở bất kỳ đâu trong repository đó, kể cả session khởi động trong subdirectory hoặc worktree. Việc phê duyệt sửa file không được lưu vào file - như bảng trên, nó chỉ tồn tại đến hết session. Ngoài git repository, và khi repository root là home directory của bạn, Claude Code lưu rule trong thư mục bạn khởi động nó.

Tại prompt permission cho Bash hoặc PowerShell, nhấn Ctrl+E để xem giải thích về lệnh: nó làm gì, tại sao Claude chạy nó, và điều gì có thể sai - gắn nhãn Low risk, Med risk, hoặc High risk. Claude Code chỉ gửi lệnh và mô tả của Claude về lệnh gọi đó đến model để sinh giải thích khi bạn nhấn Ctrl+E, không phải mỗi lần hỏi. Hiện giải thích không chạy lệnh; nhấn Ctrl+E lần nữa để ẩn đi.

Để tắt shortcut này, đặt permissionExplainerEnabled thành false trong ~/.claude.json.

Quản lý permissions

Bạn có thể xem và quản lý permission của Claude Code bằng /permissions. UI này liệt kê tất cả permission rule và file settings.json mà mỗi rule đến từ đó.

• Allow - cho phép Claude Code dùng tool đó mà không cần phê duyệt thủ công.
• Ask - luôn hỏi xác nhận mỗi khi Claude Code thử dùng tool đó.
• Deny - chặn Claude Code dùng tool đó.

Rule được đánh giá theo thứ tự: deny, rồi ask, rồi allow. Rule khớp đầu tiên theo thứ tự đó quyết định kết quả - mức độ cụ thể của rule không thay đổi thứ tự này.

Một deny rule rộng như Bash(aws *) chặn mọi lệnh khớp, kể cả lệnh cũng khớp một allow rule cụ thể hơn như Bash(aws s3 ls) - vì vậy deny rule không thể có ngoại lệ allowlist. Nguyên tắc tương tự áp dụng giữa ask và allow: một ask rule khớp vẫn hỏi ngay cả khi có allow rule cụ thể hơn cũng khớp lệnh gọi đó.

Deny rule hành xử khác nhau tuỳ việc nó chỉ định tên tool hay chỉ scope một pattern trong tool. Tên tool trần như Bash loại bỏ hoàn toàn tool đó khỏi context của Claude - Claude không bao giờ thấy nó. Việc loại bỏ bằng tên trần áp dụng cho mọi tool trừ EndConversation: deny rule không thể loại bỏ nó trong khi vẫn còn tool khác, và ask rule không bao giờ hỏi về nó. Một rule có scope như Bash(rm *) vẫn giữ tool khả dụng nhưng chặn các lệnh gọi khớp khi Claude cố thực hiện.

Ghi chú

Permission rule được thực thi bởi Claude Code, không phải bởi model. Instruction trong prompt hoặc CLAUDE.md định hình những gì Claude cố làm, nhưng không thay đổi những gì Claude Code cho phép. Để cấp hoặc thu hồi quyền, dùng /permissions, các rule mô tả ở đây, một permission mode, hoặc PreToolUse hook.

Permission modes

Claude Code hỗ trợ nhiều permission mode kiểm soát cách nó phê duyệt tool call. Đặt defaultMode trong settings files:

Mode	Mô tả
default	Hành vi chuẩn: hỏi phê duyệt lần đầu dùng mỗi tool. Gắn nhãn Manual trong CLI, VS Code, JetBrains extension và desktop app; manual là alias tương đương.
acceptEdits	Tự động chấp nhận sửa file và các lệnh filesystem thông dụng (mkdir, touch, mv, cp) trong working directory hoặc additionalDirectories.
plan	Claude đọc file và chạy lệnh shell chỉ-đọc để khám phá nhưng không sửa source code; nếu auto mode khả dụng, các lệnh được classifier duyệt cũng chạy. Gắn nhãn Plan.
auto	Tự động phê duyệt tool call với kiểm tra an toàn nền, xác minh hành động khớp với yêu cầu của bạn.
dontAsk	Tự động từ chối tool trừ khi đã được duyệt trước qua /permissions hoặc permissions.allow rules. AskUserQuestion và các MCP tool đánh dấu requiresUserInteraction vẫn bị từ chối dù đã allow.
bypassPermissions	Bỏ qua prompt phê duyệt, trừ các trường hợp bị ép bởi ask rule tường minh, connector tool tổ chức đặt ask, và MCP tool đánh dấu requiresUserInteraction. Việc xoá root/home directory (rm -rf /) vẫn hỏi như một circuit breaker.

Chú ý

bypassPermissions bỏ qua prompt phê duyệt kể cả với việc ghi vào .git, .config/git, .claude, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn. Chỉ dùng mode này trong môi trường cô lập như container hoặc VM, nơi Claude Code không thể gây hại thật.

Để ngăn dùng bypassPermissions hoặc auto mode, đặt permissions.disableBypassPermissionsMode hoặc permissions.disableAutoMode thành "disable" trong bất kỳ settings file nào - hữu ích nhất khi đặt trong managed settings (nơi user không override được).

Cú pháp permission rule

Permission rule theo dạng Tool hoặc Tool(specifier).

Khớp mọi lượt dùng một tool

Bash      → khớp mọi lệnh Bash
WebFetch  → khớp mọi request web fetch
Read      → khớp mọi lượt đọc file

Bash(*) tương đương Bash. Ở dạng deny, cả hai đều loại bỏ tool khỏi context của Claude.

Dùng specifier để kiểm soát chi tiết

Rule	Hiệu ứng
Bash(npm run build)	Khớp chính xác lệnh npm run build
Read(./.env)	Khớp việc đọc file .env trong thư mục hiện tại
WebFetch(domain:example.com)	Khớp fetch request đến example.com

Khớp theo input parameter

Deny và ask rule có thể khớp một top-level input parameter trên bất kỳ tool nào bằng Tool(param:value):

Rule	Khớp
Agent(model:opus)	Agent call yêu cầu tier model Opus
Agent(isolation:worktree)	Agent call yêu cầu git worktree
Bash(run_in_background:true)	Bash call chạy nền

Một số quy tắc khớp param:

• Tên parameter phải là field trực tiếp của input tool (field lồng trong object/array không khớp được).
• Mỗi rule chỉ chỉ định một param - muốn gate cả model và isolation thì viết hai rule riêng.
• Giá trị hỗ trợ * làm wildcard.
• Param bị model bỏ qua thì không bao giờ khớp.
• Giá trị so khớp với input gốc Claude gửi, trước khi normalize.

Bạn không thể khớp field nội dung chính của tool theo cách này: command (Bash/PowerShell), file_path (Read/Edit/Write), path (Grep/Glob), notebook_path (NotebookEdit), url (WebFetch). Dùng Bash(rm *), Read(./path), hoặc WebFetch(domain:host) thay thế.

Wildcard pattern

Bash rule hỗ trợ glob pattern với * ở bất kỳ vị trí nào:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Khoảng trắng trước * có ý nghĩa: Bash(ls *) khớp ls -la nhưng không khớp lsof, còn Bash(ls*) khớp cả hai. Hậu tố :* tương đương với * ở cuối, nên Bash(ls:*) khớp giống Bash(ls *).

Wildcard trên tên tool

Deny và ask rule cũng chấp nhận glob pattern ở vị trí tên tool. "*" khớp mọi tool, "mcp__*" khớp mọi MCP tool từ mọi server:

{
  "permissions": {
    "deny": ["mcp__*"]
  }
}

Allow rule chỉ chấp nhận glob tên tool sau tiền tố literal mcp__<server>__ - phần server phải không chứa glob.

Rule theo từng loại tool

Bash

Bash permission rule hỗ trợ wildcard * ở bất kỳ vị trí nào trong lệnh.

Compound command (lệnh ghép): Claude Code nhận biết các shell operator (&&, ||, ;, |, |&, &, newline), nên rule như Bash(safe-cmd *) không tự động cấp quyền cho safe-cmd && other-cmd. Rule phải khớp từng subcommand độc lập.

Wrapper (bộ bọc): Claude Code tự tách một số wrapper cố định trước khi khớp rule - timeout, time, nice, nohup, stdbuf, cùng command/builtin/noglob (zsh) - nên rule Bash(npm test *) cũng khớp timeout 30 npm test. Danh sách này không cấu hình được. Các runner môi trường như direnv exec, devbox run, npx, docker exec không nằm trong danh sách này, nên rule như Bash(devbox run *) khớp bất cứ gì sau run, kể cả devbox run rm -rf . - hãy viết rule cụ thể bao gồm cả runner lẫn lệnh bên trong.

Read-only commands: Claude Code nhận diện sẵn một tập lệnh Bash chỉ-đọc và chạy không cần hỏi ở mọi mode - gồm ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, và các dạng chỉ-đọc của git. Tập này không cấu hình được; muốn yêu cầu hỏi cho một trong số này, thêm ask hoặc deny rule.

Chú ý

Bash permission pattern cố ràng buộc argument của lệnh khá mong manh. Ví dụ Bash(curl http://github.com/ *) định giới hạn curl vào URL GitHub, nhưng không khớp các biến thể như đổi protocol, redirect, hay dùng biến shell. Để lọc URL đáng tin cậy hơn: chặn curl/wget bằng deny rule và dùng WebFetch với WebFetch(domain:...), hoặc dùng PreToolUse hook.

PowerShell

Cấu trúc rule giống Bash. Alias thông dụng được canonical hoá trước khi khớp (rule viết cho tên cmdlet cũng khớp alias của nó, ví dụ Get-ChildItem khớp gci, ls, dir). Matching không phân biệt hoa thường.

Read và Edit

Edit rule áp dụng cho mọi built-in tool sửa file. Claude cố gắng áp Read rule cho mọi tool đọc file như Grep, Glob, @file mention, và context IDE chia sẻ.

Read và Edit rule dùng cú pháp pattern kiểu gitignore với bốn loại pattern:

Pattern	Ý nghĩa	Ví dụ	Khớp
//path	Đường dẫn tuyệt đối từ filesystem root	Read(//Users/alice/secrets/**)	/Users/alice/secrets/**
~/path	Đường dẫn từ home directory	Read(~/Documents/*.pdf)	/Users/alice/Documents/*.pdf
/path	Đường dẫn tương đối với nguồn settings	Edit(/src/**/*.ts)	<project root>/src/**/*.ts trong project settings
path hoặc ./path	Đường dẫn tương đối với thư mục hiện tại	Read(*.env)	<cwd>/*.env

Chú ý

Pattern như /Users/alice/file không phải absolute path - dấu / đầu tiên chỉ neo tại nguồn settings, không phải filesystem root. Dùng //Users/alice/file cho absolute path thật.

Rule có một segment thư mục đơn (như src/**) khớp ở độ sâu khác nhau tuỳ loại rule: allow rule chỉ khớp tại <cwd>/src, còn deny/ask rule khớp thư mục src ở bất kỳ độ sâu nào.

Khi Claude truy cập symlink, permission rule kiểm tra cả hai đường dẫn: chính symlink và target nó trỏ tới. Allow rule cần cả hai đều khớp; deny rule chặn nếu một trong hai khớp.

WebFetch

WebFetch(domain:example.com) khớp request đến example.com. WebFetch(domain:*.example.com) khớp mọi subdomain ở bất kỳ độ sâu. Matching không phân biệt hoa thường.

MCP

mcp__puppeteer khớp mọi tool từ server puppeteer. mcp__puppeteer__puppeteer_navigate khớp một tool cụ thể.

Agent (subagents)

Dùng Agent(AgentName) để kiểm soát subagent nào Claude được dùng, ví dụ chặn Explore agent:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Cd

Cd rule kiểm soát lệnh /cd được di chuyển tới thư mục nào. Cd không phải tool model gọi được - chỉ áp dụng khi bạn tự chạy /cd.

Mở rộng permission bằng hooks

Hooks cho phép đăng ký lệnh shell tuỳ chỉnh để đánh giá permission lúc runtime. Khi Claude Code thực hiện tool call, PreToolUse hook chạy trước prompt phê duyệt (trừ EndConversation). Output của hook có thể từ chối tool call, ép hỏi, hoặc bỏ qua prompt để cho phép chạy tiếp.

Quyết định của hook không bỏ qua permission rule: Claude Code vẫn đánh giá deny/ask rule bất kể hook trả về gì. Một hook chặn (exit code 2) ưu tiên hơn cả allow rule.

Working directories

Mặc định Claude có quyền truy cập file trong thư mục bạn khởi động nó. Mở rộng bằng:

• Lúc khởi động: cờ --add-dir <path>
• Trong session: lệnh /add-dir
• Cấu hình lâu dài: thêm vào additionalDirectories trong settings files

Để đổi working directory chính của session (thay vì thêm), dùng /cd.

Managed settings

Với tổ chức cần kiểm soát tập trung, quản trị viên có thể triển khai managed settings không thể bị user hoặc project settings ghi đè. Các setting này theo cùng format với settings file thường và có thể triển khai qua MDM/OS-level policy, managed settings file, hoặc server-managed settings.

Một số setting chỉ đọc từ managed settings (đặt trong user/project settings không có tác dụng) - ví dụ allowManagedPermissionRulesOnly, allowManagedMcpServersOnly, strictKnownMarketplaces, sandbox.network.allowManagedDomainsOnly… Xem chi tiết trong Settings và tài liệu gốc.

Thứ tự ưu tiên settings

1. Managed settings - không thể bị override bởi cấp nào khác, kể cả CLI argument.
2. Command line arguments - override tạm thời cho session.
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

Nếu một tool bị deny ở bất kỳ cấp nào, không cấp nào khác cho phép được. Điều này cũng áp dụng chéo scope: nếu user settings allow còn project settings deny, deny sẽ thắng.

Project allow rules và workspace trust

permissions.allow và permissions.additionalDirectories trong .claude/settings.json của project cấp thêm năng lực, nên Claude Code chỉ áp dụng chúng sau khi bạn chấp nhận workspace trust dialog cho workspace đó. Trước đó, Claude Code đọc rule nhưng không áp dụng. deny và ask rule không bị ảnh hưởng vì chúng chỉ giới hạn thêm.

Ví dụ cấu hình

Repository claude-code/examples/settings có sẵn cấu hình mẫu cho các kịch bản triển khai phổ biến.

Nguồn

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