权限配置

Claude Code 使用精细的权限系统，让你可以精确控制 AI 可以访问什么、可以做什么。权限设置可以提交到版本库分发给整个团队，也可以由个人开发者定制。

权限层级

工具类型	示例	是否需要确认	"以后不再询问"的效果
只读操作	读取文件、Grep 搜索	否	无需设置
Bash 命令	Shell 执行	是	按项目目录和命令永久记住
文件修改	编辑/写入文件	是	当前会话内记住

管理权限

在 Claude Code 中运行 /permissions 可以查看和管理所有工具权限。界面显示所有权限规则及其来源的 settings.json 文件。

权限规则有三种类型：

• Allow（允许）：无需手动确认直接使用
• Ask（询问）：每次使用前弹出确认
• Deny（拒绝）：完全阻止使用

规则求值顺序：deny → ask → allow，第一个匹配的规则生效，所以 deny 规则优先级最高。

权限模式

在 settings.json 中设置 defaultMode：

模式	说明
default	标准模式：每种工具首次使用时询问
acceptEdits	自动接受本次会话的文件编辑权限
plan	计划模式：Claude 只能分析，不能修改文件或执行命令
dontAsk	除非通过 /permissions 或 allow 规则预先审批，否则自动拒绝
bypassPermissions	跳过权限提示（高危，见下方警告）

安全警告：bypassPermissions 模式会跳过所有权限提示。只有写入 .git、.claude、.vscode、.idea 目录时仍会提示，以防止破坏仓库状态。仅在容器或虚拟机等隔离环境中使用。管理员可在托管设置中设置 disableBypassPermissionsMode: "disable" 禁用此模式。

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

权限规则语法

规则格式为 工具名 或 工具名(指定器)。

匹配工具的所有用法

规则	效果
Bash	匹配所有 Bash 命令
WebFetch	匹配所有 Web 请求
Read	匹配所有文件读取

Bash(*) 等同于 Bash。

精细匹配

规则	效果
Bash(npm run build)	精确匹配 npm run build
Read(./.env)	匹配读取当前目录的 .env 文件
WebFetch(domain:example.com)	匹配对 example.com 的请求

通配符

Bash 规则支持 * 通配符，可以出现在命令的任意位置：

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

注意空格：Bash(ls *) 匹配 ls -la 但不匹配 lsof；Bash(ls*) 两者都匹配。

Claude Code 能识别 shell 运算符（如 &&），前缀匹配规则 Bash(safe-cmd *) 不会允许 safe-cmd && other-cmd 执行。

各工具的规则详解

Bash

支持 * 通配符，位置任意：

• Bash(npm run build) — 精确匹配
• Bash(npm run test *) — 前缀匹配
• Bash(npm *) — 所有 npm 开头的命令
• Bash(* install) — 所有以 install 结尾的命令
• Bash(git * main) — 匹配 git checkout main、git merge main 等

复合命令：批准含 && 的复合命令时，Claude Code 会为每个需要审批的子命令单独保存规则（最多 5 条）。

注意：尝试用 Bash 规则限制 URL 参数是不可靠的（路径变体、变量、多余空格等都可能绕过）。更好的做法是：

• 用 deny 规则阻断 curl、wget，再用 WebFetch(domain:xxx.com) 允许特定域名
• 用 PreToolUse Hook 验证 URL
• 在 CLAUDE.md 中说明允许的 curl 模式

Read 和 Edit

Edit 规则适用于所有内置文件编辑工具；Claude 会尽力将 Read 规则应用到 Grep、Glob 等读取工具。

警告：Read/Edit deny 规则只阻止 Claude 的内置文件工具，不阻止 Bash 子进程。Read(./.env) 可以阻止 Read 工具，但阻止不了 Bash 里的 cat .env。需要 OS 级别的限制时，请启用沙箱。

文件规则遵循 gitignore 规范，支持四种路径写法：

模式	含义	示例	匹配
//path	从文件系统根的绝对路径	Read(//Users/alice/secrets/**)	/Users/alice/secrets/**
~/path	从家目录的路径	Read(~/Documents/*.pdf)	$HOME/Documents/*.pdf
/path	相对于项目根目录	Edit(/src/**/*.ts)	<项目根>/src/**/*.ts
path 或 ./path	相对于当前目录	Read(*.env)	<当前目录>/*.env

注意：/Users/alice/file 不是绝对路径，它是相对于项目根的路径！绝对路径需要写 //Users/alice/file。

常用示例：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ],
    "allow": [
      "Edit(/src/**)",
      "Read(~/.zshrc)"
    ]
  }
}

gitignore 通配符说明：* 匹配单个目录内的文件，** 跨目录递归匹配。允许所有文件访问时，直接用工具名不加括号：Read、Edit。

WebFetch

WebFetch(domain:example.com)    # 匹配对 example.com 的所有请求
WebFetch(domain:*.api.com)      # 通配符支持子域名

MCP 工具

mcp__puppeteer                      # puppeteer 服务器的任意工具
mcp__puppeteer__*                   # 通配符写法（等价）
mcp__puppeteer__puppeteer_navigate  # 特定工具

子代理（Agent）

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

支持 Agent(Explore)、Agent(Plan)、Agent(my-custom-agent) 等格式。

通过 Hooks 扩展权限

Hooks 提供了运行时的自定义权限评估方式。工具调用时，PreToolUse Hook 在权限提示前运行，可以阻止调用、强制询问，或允许直接执行。

注意：Hook 返回 allow 不会绕过 deny 和 ask 规则，它们仍然会被评估。阻止型 Hook（退出码 2）比 allow 规则优先级更高。

工作目录

默认情况下，Claude 只能访问启动目录下的文件。可以扩展：

# 启动时
claude --add-dir /path/to/extra

# 会话中
/add-dir /path/to/extra

或在 settings.json 中永久配置：

{
  "permissions": {
    "additionalDirectories": ["../docs/", "../shared/"]
  }
}

沙箱隔离

权限和沙箱是互补的安全层：

• 权限：控制 Claude 可以使用哪些工具、访问哪些文件或域名，适用于所有工具
• 沙箱：OS 级别的隔离，限制 Bash 工具的文件系统和网络访问，仅适用于 Bash 命令

同时使用可以获得纵深防御：

• 权限 deny 规则阻止 Claude 尝试访问受限资源
• 沙箱阻止 Bash 命令访问边界外的资源，即使发生提示词注入也安全

沙箱配置示例：

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowLocalBinding": true
    }
  }
}

详细配置见设置文档。

企业托管权限

管理员可以部署用户无法覆盖的托管设置。

仅托管设置中支持的选项

设置	说明
disableBypassPermissionsMode	设为 "disable" 禁止 bypassPermissions 模式
allowManagedPermissionRulesOnly	为 true 时禁止用户/项目自定义 allow/ask/deny 规则
allowManagedHooksOnly	为 true 时只允许托管 Hooks，禁止用户/项目 Hooks
allowManagedMcpServersOnly	为 true 时只允许托管 MCP 服务器白名单

权限优先级

1. 托管设置（最高）——任何其他级别都无法覆盖
2. 命令行参数——临时会话覆盖
3. 本地项目设置（.claude/settings.local.json）
4. 共享项目设置（.claude/settings.json）
5. 用户设置（~/.claude/settings.json，最低）

同一工具在任何级别被 deny，就不能在其他级别被 allow。例如用户设置里 allow 了，但项目设置里 deny 了，则结果是拒绝。

常用配置示例

只允许安全的 npm/git 命令

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm *)",
      "Bash(sudo *)",
      "WebFetch",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

团队共享配置（.claude/settings.json）

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm run *)",
      "Bash(bun run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Read(./.env)",
      "Read(./config/secrets.json)"
    ]
  }
}

相关资源

• 设置：完整配置参考
• Hooks：自动化权限验证
• MCP：连接外部工具