ClaudeCodeLab
Tips & Tricks

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

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

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

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

权限配置总览

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

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

配置写在 .claude/settings.json 中。放在项目根目录可通过 git 实现团队共享，放在 ~/.claude.json 则为全局配置。

优先级（从高到低）：
项目 .claude/settings.json
    > 全局 ~/.claude.json
        > 默认（全部为 ask）

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=.claude/settings.production.json claude 指定此配置。

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

{
  "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 自动化或完全可控的自动化脚本，日常交互中应当避免使用。

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

当存在多个配置文件时：

~/.claude.json              ← 全局（所有项目共享）
    +
.claude/settings.json       ← 项目级（git 管理）
    +
.claude/settings.local.json ← 个人覆盖（建议加入 gitignore）
    =
合并后的配置生效

个人附加配置写入 .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. 忘记手动切换生产环境配置

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

# ✅ 生产操作前明确切换配置
CLAUDE_SETTINGS=.claude/settings.production.json claude

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

# ~/.bashrc or ~/.zshrc
alias claude-prod='CLAUDE_SETTINGS=.claude/settings.production.json claude'

调试配置的方法

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

# 查看当前配置
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

让你的 Claude Code 工作流更上一层楼

50 个经过实战检验的提示词模板，现在就能复制粘贴到 Claude Code 中使用。

获取 50 个提示词模板 — $9.99 浏览更多文章
免费

免费 PDF：5 分钟看懂 Claude Code 速查表

只需留下邮箱，我们就会立即把这份 A4 一页速查表 PDF 发送给你。

我们会严格保护你的个人信息，绝不发送垃圾邮件。

Masa

本文作者

Masa

深度使用 Claude Code 的工程师。运营 claudecode-lab.com——一个涵盖 10 种语言、超过 2,000 页内容的科技媒体。

相关文章

相关产品

PROMPT 50
热销中 Gumroad

50 个实战 Claude Code 提示词模板

可直接复制粘贴的编码、代码审查与文档提示词，开箱即用。

$9.99 立即购买

查看全部产品

提示词合集、配置指南、技巧集等