Claude Code 权限设置指南：安全配置 settings.json

你只是想让 Claude Code 自动跑测试，却发现每条命令都会弹出确认。可如果直接放行整个 Bash，删除文件、hard reset，甚至 force push 也可能在没有确认的情况下执行。

权限设置不是“全部拦截”和“全部放行”二选一。更稳妥的起点是：读取和测试自动放行，修改前询问，密钥文件与破坏性命令始终拒绝。把这三层规则写进 .claude/settings.json 即可。

本文要点

规则按 deny → ask → allow 的顺序判断，也就是先拒绝、再询问、最后才是自动放行。
项目内读取默认无需确认。只把已经检查过的测试命令放进 allow，把编辑、外部访问和 push 放进 ask，把密钥与破坏性操作放进 deny。
Bash(git *) 范围过大，会覆盖 git reset --hard 和 git push --force，应按具体命令收窄。
只写 Read(.env) 无法完全阻止子进程读取文件。需要强隔离时，还要配合 sandbox 和操作系统权限。
保存设置后，用 /permissions 和 /status 确认实际生效的规则及其来源文件。

交给 Claude Code 的工作与必须人工判断的工作

交给 Claude Code	需要人工确认	始终拦截
搜索文件、查看 diff、运行测试	修改文件、commit、push、安装依赖	读取密钥、force push、hard reset、批量删除
`Read`、`Grep`、`git diff`	`Edit`、`git commit`、`npm install`	`.env`、`git push --force`、`git reset --hard`、`rm -rf`

无法轻易撤销、会向外部发送数据或会接触认证信息的操作，应放在 ask 或 deny，而不是直接 allow。

可直接使用的 settings.json

在项目根目录创建 .claude/settings.json，先使用下面这份偏保守的团队配置。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)"
    ],
    "ask": [
      "Edit",
      "WebFetch",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git clean *)",
      "Bash(git restore *)",
      "Bash(npm install *)",
      "Bash(npm uninstall *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/**)",
      "Edit(.env)",
      "Edit(.env.*)",
      "Edit(**/secrets/**)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)",
      "Bash(rm *)",
      "PowerShell(Remove-Item *)"
    ]
  }
}

这份配置只适用于你已经检查过 package.json scripts 的仓库。面对陌生仓库，应先把 allow 留空，确认测试脚本实际会执行什么，再逐条放行。Bash(npm test *) 同时匹配 npm test 与带参数的形式。

settings.json 应该放在哪里

类型	路径	用途
User	`~/.claude/settings.json`	适用于个人所有项目的通用设置
Project	`.claude/settings.json`	提交到 Git、供团队共享的标准
Local	`.claude/settings.local.json`	只在当前电脑使用的个人设置，不要提交到 Git
Managed	由管理员分发	组织内不可由项目覆盖的强制规则

优先级依次为 Managed、命令行、Local、Project、User。permissions.allow 这类数组会跨 scope 合并，并非由高优先级数组整体替换。无论 deny 写在哪个 scope，都会比 ask 与 allow 更早判断。团队共用规则可放在 Project；不可由成员修改的策略应放在 Managed。

如何理解 allow、ask 与 deny 的匹配方式

规则	含义
`Read`	匹配所有内置读取；项目内文件默认可读，通常无需裸 allow
`Bash(npm test)`	只精确匹配 `npm test`
`Bash(npm test *)`	匹配 `npm test` 及其后带参数的形式
`Bash(ls*)`	除了 `ls -la`，也可能匹配 `lsof`，范围过宽
`Read(//Users/me/secrets/**)`	匹配文件系统绝对路径
`Edit(/src/*/.ts)`	在 Project 设置中匹配项目 `src` 下的 TypeScript 文件
`WebFetch(domain:docs.anthropic.com)`	匹配访问指定域名的 WebFetch

Bash(git *) 同时可能覆盖 git push origin main 和 git reset --hard。安全命令应逐项写明，不要一次放行整个 Git 命令空间。

为什么仅靠 Read 与 Edit 保护不了所有密钥

Read 和 Edit 的路径规则使用类似 gitignore 的写法。

写法	基准位置	示例
`//path`	文件系统根目录	`Read(//Users/me/secrets/**)`
`~/path`	用户主目录	`Read(~/.ssh/**)`
`/path`	当前设置文件的基准位置	Project 设置中的 `Edit(/src/**)`
`path` 或 `./path`	当前工作目录	`Read(.env)`

开头只有一个斜杠并不表示文件系统绝对路径。Read(.env) 能约束 Claude Code 识别到的内置文件读取工具，但通过 Node.js、Python 或其他子进程间接读取文件属于另一条路径。

项目会接触认证信息时，还应配置 Claude Code sandbox，并在操作系统层限制访问。sandbox支持macOS、Linux与WSL2，不支持原生Windows；Windows用户应使用WSL2或隔离容器，并保留PowerShell deny。

3 个 Use case

Use case 1：个人开发只自动运行测试

输入： 源码、测试与 Git diff。输出： 修改建议和测试结果。人工确认： 编辑、安装依赖、commit、push。

先使用上面的最小配置，让编辑继续留在 ask。某个只读或测试命令经过多次使用并确认安全后，再单独移到 allow。

Use case 2：团队统一拦截危险命令

输入： 允许的命令与禁止操作清单。输出： 由 Git 管理的团队设置。人工确认： 新增 deny 和临时例外。

在 Project 设置中拒绝 .env、force push 与 hard reset。若某条规则不允许项目成员自行修改，应把它移到 Managed settings。

Use case 3：只调查生产仓库，不做修改

输入： 故障日志与 Git 历史。输出： 原因候选和修复计划。人工确认： 编辑、部署以及任何外部传输。

启动时选择 Plan Mode。

claude --permission-mode plan

如果调查后确实需要写入，先切换到工作分支或隔离环境，再批准修改。

4 个具体失败案例

错误做法	原因	修复方法
allow `Bash(git *)`	同一模式也覆盖push与hard reset	只放行已经确认副作用的具体命令
deny `Bash(aws *)` 后再allow `Bash(aws s3 ls)`	deny → ask → allow，规则更具体也不能形成例外	缩小deny范围，或把安全操作放到独立命令入口
把 `Read(.env)` 当作系统级隔离	任意Node.js、Python子进程不受内置Read/Edit规则完全约束	配合sandbox的 `denyRead` 或credentials设置
删除Local allow后命令仍能运行	User、Project、Local中的权限数组会合并	用 `/permissions` 查规则来源，用 `/status` 查已加载scope

更多事故模式见Claude Code安全失败案例，完整部署检查见安全最佳实践。

如何选择 permission mode

模式	适用场景	注意事项
`default`	第一次接触的仓库	需要时会弹出确认
`acceptEdits`	已经理解修改范围的开发任务	编辑和常见文件操作可能自动获批
`plan`	调查、设计、生产故障的只读分析	不修改源码
`auto`	使用后台安全判断的任务	分类器判断操作是否符合请求，仍需显式deny
`dontAsk`	无人值守地运行已预先批准的操作	未被批准的操作不会询问，而是直接拒绝
`bypassPermissions`	可以随时销毁的容器或虚拟机	不要在普通电脑或生产环境使用

sandbox.autoAllowBashIfSandboxed 默认是 true。sandbox内可能跳过裸 Bash ask，但 Bash(git push *) 这类带内容的ask、显式deny和Plan Mode限制仍然生效。

Pitfall：用一个 Hook 弥补过宽的 allow

如果先放行整个 Bash，再指望 PreToolUse hook 拦截危险命令，那么 hook 放错位置、执行失败或匹配遗漏，都会直接破坏唯一的安全边界。

原因： allow 范围过大，一个 hook 被迫承担全部拦截责任。

修正方法： 先写 deny 和范围明确的 allow，再把 hook 作为动态判断的额外一层。deny 与 ask 的优先级高于 hook 返回的 allow 结果。

可复制的配置检查脚本

下面的脚本会确认 .claude/settings.json 是合法 JSON，并检查四条最低限度的 deny 是否存在。

// scripts/check-claude-permissions.mjs
import { readFileSync } from "node:fs";

const path = ".claude/settings.json";
const settings = JSON.parse(readFileSync(path, "utf8"));
const deny = new Set(settings.permissions?.deny ?? []);
const required = [
  "Read(.env)",
  "Edit(.env)",
  "Bash(git push --force *)",
  "Bash(git reset --hard *)",
  "Bash(rm *)",
  "PowerShell(Remove-Item *)",
];

const missing = required.filter((rule) => !deny.has(rule));
if (missing.length > 0) {
  console.error(`缺少以下 deny 规则：${missing.join(", ")}`);
  process.exit(1);
}

console.log("Claude Code 权限最低限度检查：OK");

node scripts/check-claude-permissions.mjs

这不是完整的安全证明。它只负责在 CI 中发现最低限度的 deny 被意外删除。

设置没有生效时的排查顺序

用 /permissions 查看当前规则以及每条规则的来源文件。
用 /status 查看已经加载的设置层级。
重新检查 Bash(ls *) 与 Bash(ls*)、/path 与 //path 这类空格和路径锚点差异。
检查 sandbox 自动放行，以及更高 scope 中的 deny 或 ask。
不要把团队规则只留在临时 CLI 参数中，应写回 .claude/settings.json。

总结

第一步是在 .claude/settings.json 中放入最小配置，再用 /permissions 确认结果。

只把检查过的测试放进 allow，编辑与外部操作放进 ask，密钥与破坏性操作放进 deny。之后只逐项增加在你的项目里验证过的安全命令。

官方资料

实际测试结果

2026 年 7 月 22 日，我们用 JSON.parse 解析了十种语言中的JSON，并在临时项目中运行Node.js检查脚本。六条必需deny都存在时exit code为0；删除 Bash(git reset --hard *) 后为1，并列出缺失规则。这只能发现配置漂移，不能证明策略绝对安全。请在自己的环境中用 /permissions 与 /status 核对。