Tips & Tricks (更新: 2026/6/1)

Claude Code 权限配置完全指南 | settings.json·Hooks·allowlist 深度解析

全面解析 Claude Code 权限配置。allow/deny/ask 的使用场景、Hooks 自动化、环境专属 settings.json 以及实战配置模式，附完整可运行代码示例。

Claude Code 权限配置完全指南 | settings.json·Hooks·allowlist 深度解析

Claude Code 具备极为强大的文件操作和命令执行能力。权限配置（permissions） 正是安全驾驭这种能力的关键。让我们告别”随意使用”的状态，设计一个按预期精准运行的 Claude Code。

本文将结合可运行的代码，深入讲解 .claude/settings.json 的所有配置项、Hooks 实现模式，以及面向不同环境的权限设计方案。

权限配置总览

Claude Code 的权限通过 3 个层级 进行控制。

层级键值行为
允许allow无需确认对话框，自动执行
询问ask每次操作都需要用户确认
拒绝deny完全无法执行（以报错形式拦截）

配置应以官方的 settings.json 为中心。用户级配置放在 ~/.claude/settings.json，团队共享的项目配置放在 .claude/settings.json，个人覆盖配置放在 .claude/settings.local.json。~/.claude.json 仍可能保存 MCP 等状态，但权限规则的主要讨论对象应是 settings.json。

优先级（从高到低）：
Managed settings
    > 命令行参数
        > Local .claude/settings.local.json
            > Project .claude/settings.json
                > User ~/.claude/settings.json

permission rules 会跨 scope 合并，并按 deny -> ask -> allow 的顺序评估

settings.json 基本结构

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)"
    ]
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": []
  }
}

工具名称与模式语法

权限配置采用 “工具名称(参数模式)” 的格式书写。

主要工具列表

工具名称功能说明
Read文件读取
Write新建文件
Edit修改现有文件的局部内容
Bash执行 Shell 命令
Glob文件模式搜索
Grep内容搜索
WebFetch获取 URL 内容
Agent启动子代理

模式语法

"Read(**)"          // 允许读取所有文件
"Read(src/**)"      // 仅允许 src/ 目录下的文件
"Read(*.md)"        // 仅允许 .md 文件
"Bash(npm run *)"   // 仅允许以 npm run 开头的命令
"Bash(git *)"       // 允许所有 git 命令
"Bash(rm -rf *)"    // 拒绝 rm -rf

** 匹配包含目录在内的所有路径，* 匹配单个路径段。

实战配置模式

模式一：个人开发（相对宽松）

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm *)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git add*)",
      "Bash(node *)",
      "Bash(echo *)",
      "Bash(cat *)",
      "Bash(ls *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~*)",
      "Bash(git push --force *main*)",
      "Bash(git push --force *master*)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(rm *)"
    ]
  }
}

模式二：团队开发（安全优先）

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run typecheck)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git branch*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git push -f*)",
      "Bash(git reset --hard*)",
      "Bash(git rebase *main*)",
      "Bash(git rebase *master*)",
      "Bash(DROP *)",
      "Bash(TRUNCATE *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(git add*)",
      "Bash(npm install*)",
      "Bash(*deploy*)"
    ]
  }
}

模式三：生产环境（只读模式）

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git show*)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(ps *)",
      "Bash(df *)",
      "Bash(top *)"
    ],
    "deny": [
      "Write(**)",
      "Edit(**)",
      "Bash(git push*)",
      "Bash(git commit*)",
      "Bash(git reset*)",
      "Bash(rm *)",
      "Bash(mv *)",
      "Bash(*deploy*)",
      "Bash(*restart*)",
      "Bash(*kill *)"
    ],
    "ask": []
  }
}

在生产或接近生产的工作树中，应把这份配置作为当前 .claude/settings.json 使用，并用 claude --permission-mode plan 或预先批准好的 dontAsk 启动。相比用环境变量切换另一份 settings 文件，这种做法更贴近官方的 scope 与 permission mode 模型，也更容易被团队审查。

模式四：专用内容生成（本站所用方案）

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Write(site/src/content/**)",
      "Write(content/**)",
      "Edit(site/src/content/**)",
      "Edit(content/**)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(node scripts/*)",
      "Bash(QIITA_TOKEN=* node scripts/qiita-publish.mjs)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Edit(.env*)",
      "Read(.env*)"
    ],
    "ask": [
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(bash scripts/deploy.sh*)"
    ]
  }
}

核心要点是像 Write(site/src/content/**) 这样将写入权限限制在特定目录。

Hooks：在权限执行前后插入处理逻辑

Hooks 是一种在工具执行前后自动运行命令的机制，可用于安全检查和自动格式化。

PreToolUse：执行前钩子

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git add*)",
        "hooks": [{
          "type": "command",
          "command": "git diff --cached --name-only | grep -E '^\\.env' && echo '🚨 检测到 .env 文件被添加！' && exit 1 || exit 0"
        }]
      },
      {
        "matcher": "Bash(git commit*)",
        "hooks": [{
          "type": "command",
          "command": "node scripts/secret-scan.mjs"
        }]
      },
      {
        "matcher": "Bash(rm*)",
        "hooks": [{
          "type": "command",
          "command": "echo '⚠️ 检测到删除命令，5秒后执行。按 Ctrl+C 取消。' && sleep 5"
        }]
      }
    ]
  }
}

钩子命令返回退出码 1 时，工具执行将被阻断。这是最核心的要点。

PostToolUse：执行后钩子

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npx tsc --noEmit 2>&1 | head -20 || true"
        }]
      },
      {
        "matcher": "Bash(git commit*)",
        "hooks": [{
          "type": "command",
          "command": "git log --oneline -3"
        }]
      }
    ]
  }
}

PostToolUse 用于执行后的确认和副作用处理，例如编辑文件后自动运行类型检查，或 commit 后展示最近 3 条提交记录。

实用 Hooks 配方集锦

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(npm install*)",
        "hooks": [{
          "type": "command",
          "command": "echo '📦 即将添加依赖包，请确认 package.json。'"
        }]
      },
      {
        "matcher": "Bash(*deploy*)",
        "hooks": [{
          "type": "command",
          "command": "read -p '🚀 即将执行部署，是否继续？[y/N] ' ans && [ \"$ans\" = 'y' ] || exit 1"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)|Edit(*.ts)",
        "hooks": [{
          "type": "command",
          "command": "npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
        }]
      }
    ]
  }
}

权限模式：启动时指定权限级别

启动 claude 命令时也可以指定模式。

# 普通模式（遵循 settings.json）
claude

# 自动批准所有操作（危险！仅限受信任的环境）
claude --dangerously-skip-permissions

# 仅跳过特定操作
claude --allowedTools "Read,Grep,Glob"

# 非交互模式（用于 CI/CD）
claude -p "运行测试并报告结果" --dangerously-skip-permissions

--dangerously-skip-permissions 仅应用于 CI/CD 自动化或完全可控的自动化脚本，日常交互中应当避免使用。

2026 版：安全 permission budget 与团队审查

这里的 permission budget 不是官方功能名，而是“第一周允许 Claude Code 自动执行哪些操作”的运维边界。按 2026 年 6 月 1 日的官方 Docs，permission rules 按 deny -> ask -> allow 的顺序评估；PreToolUse hooks 可以增加运行时检查，但不能用 hook 的 allow 覆盖已经命中的 deny 或 ask。因此初始预算应优先考虑可回滚，而不是追求完全自动化。

最安全的起步 budget 很窄。allow 只放读取和验证：Read、Glob、Grep、git status、git diff、git log、npm run lint、npm run test。ask 放会改变意图的操作：Edit、Write、git add、git commit、git push、npm install、deploy 相关命令。deny 放不可逆或敏感操作：.env、secrets/**、rm -rf、git reset --hard、git push --force、curl | bash、wget | sh、生产数据库命令。bypassPermissions 只适合一次性容器、VM、devcontainer 等损坏也不会影响宿主机的环境。

团队使用时，把 .claude/settings.json 当作应用代码审查。每个 PR 都检查三点：allow 是否只包含重复执行也安全的命令，ask 是否覆盖了需要人类确认意图的写入、提交、发布操作，deny 是否覆盖了 secrets、强制 push、删除和生产操作。组织管理员还可以通过 server-managed settings 把 disableBypassPermissionsMode 与 disableAutoMode 设为 "disable"，再用 allowManagedPermissionRulesOnly 阻止用户或项目自行增加 permission rules。

危险的失败例是把 Bash(git *) 或 Bash(node *) 宽泛加入 allow，然后以为 Read(.env*) deny 就能保护秘密。官方文档说明，Read/Edit deny 能限制 Claude Code 内置文件工具和部分可识别的文件命令，但不能阻止任意 Node/Python 子进程自己打开文件。如果确实要保护 secrets，不要宽泛允许 Bash，还要结合 sandbox、操作系统文件权限和 PreToolUse 检查。

复旧流程也要提前写好。出现意外编辑时，先用 /permissions 查看生效规则和来源，再看 git diff。回滚时用 git restore -p 按 hunk 选择，未跟踪文件先用 git clean -n 预览。若秘密可能已经被读取或进入 transcript，只修改 .claude/settings.json 不够，还要轮换 token 或密钥。

如果要把本文落到真实仓库，先用 permission budget loop 和 permission audit checklist 做盘点。想要可复制的教材和模板，可以看 Claude Code 产品页；如果是团队导入、权限审查和安全 onboarding，走 咨询页面 会比单独猜规则更稳。

配置文件优先级与覆盖规则

当存在多个配置文件时：

~/.claude/settings.json     ← User（所有项目共用）
.claude/settings.json       ← Project（git 管理）
.claude/settings.local.json ← Local（个人覆盖，gitignore）
managed-settings.json       ← Managed（组织策略，最高优先级）

permission rules 会合并，并且 deny 总是先于 allow 评估

个人附加配置写入 .claude/settings.local.json 并加入 gitignore。为防止团队 deny 规则被个人配置覆盖，安全的设计原则是deny 规则仅写在 settings.json 中。

# 添加到 .gitignore
.claude/settings.local.json

五大常见陷阱

1. 通配符模式写错

// ❌ 这只匹配单个命令 "git"
"Bash(git)"

// ✅ 同时匹配 git 及其后续参数
"Bash(git *)"
"Bash(git*)"  // 不加空格也能工作，但显式加 * 更安全

2. 忘记 deny 优先于 ask

// 此配置下 Bash(rm -rf /tmp/test) 会被 deny 捕获并拦截
// 永远不会到达 ask
{
  "deny": ["Bash(rm -rf*)"],
  "ask": ["Bash(rm*)"]  // ← rm -rf 由 deny 处理
}

3. 忽视 Hooks 的退出码

# 若 PreToolUse 钩子命令始终返回 exit 0，
# 即使扫描失败也无法阻断执行

# ❌ 出错也会放行
"command": "node scan.mjs"

# ✅ 明确控制退出码
"command": "node scan.mjs || exit 1"

4. 不小心将 settings.json 加入 .gitignore

有些团队会误将本应共享的 settings.json 加入 .gitignore。正确做法是项目配置纳入 git 管理，只将 settings.local.json 加入 gitignore。

5. 忘记手动切换生产环境配置

# ❌ 用日常配置直接操作生产环境

# ✅ 生产操作前使用 plan mode，并确保该工作树的 .claude/settings.json 是生产安全配置
claude --permission-mode plan

注册别名可以有效防止遗忘：

# ~/.bashrc or ~/.zshrc
alias claude-prod='claude --permission-mode plan'

调试配置的方法

当不清楚”为何此命令被拦截”时：

# 查看当前配置
claude --print-settings 2>/dev/null || cat .claude/settings.json

# 查看匹配了哪条规则（verbose 模式）
claude --verbose -p "执行 git push"

总结：权限设计最佳实践

1. 首先确定 deny
   → 列出绝对不允许执行的命令
   → rm -rf、git push --force、DROP TABLE 是必须项

2. 其次配置 ask
   → 需要确认的写入类和部署类操作

3. 其余设为 allow
   → 读取类和 CI 类操作全部 allow，提升效率

4. 用 Hooks 实现安全自动化
   → 提交前扫描、编辑后自动类型检查

5. 按环境准备配置文件
   → settings.json（开发环境），settings.production.json（生产环境）

合理配置权限后，你将告别机械地点击确认按钮，真正专注于需要人工审查的操作。前期花 30 分钟做好设计，未来数百小时的工作都将更加安全可靠。

相关文章

参考资料

#claude-code #permissions #security #hooks #settings #configuration
免费

免费 PDF: Claude Code 速查表

输入邮箱即可获取一页 PDF，整理常用命令、审查习惯和安全工作流。

我们会妥善保护你的信息，不发送垃圾邮件。

把 Claude Code 变成真正能带来结果的工作流

先领取中文说明的免费 PDF，再进入英文商品页选择合适的教材。如果你需要团队落地、流程设计或内容变现支持，也可以直接咨询。

查看产品选择建议 先领取免费 PDF 查看咨询方案
Masa

关于作者

Masa

专注 Claude Code 实务流程、团队导入和内容转化的工程师。

相关文章