第 10 章：权限与安全 — 精细化控制

⏱ 预计阅读 17 分钟 更新于 2026/5/16
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

在之前的章节中，我们已经掌握了 Claude Code 的核心工作流程。随着项目规模的增长，你可能希望对 Claude 可以执行的操作进行更精细的控制。Claude Code 提供了完整的权限管理系统，既保证了安全性和可控性，又通过智能配置减少了不必要的确认流程。

本章将深入讲解权限模型、交互式管理、Hook 机制以及安全最佳实践，帮助你构建符合团队需求的安全策略。

10.1 权限模型概述

Claude Code 的权限系统基于三条核心规则：

  • allow（自动批准）：工具调用直接通过，无需用户确认
  • ask（每次确认）：每次使用时都弹出确认提示
  • deny（直接拒绝）：工具调用被直接拦截，无法执行

配置文件位置

权限配置按优先级从高到低分为三个层级：

  1. 本地级：.claude/settings.local.json（优先级最高）
  2. 项目级：.claude/settings.json（项目共享配置）
  3. 用户级：~/.claude/settings.json（全局默认配置）

优先级机制允许你在项目级设置基础规则，在本地级进行个性化覆盖，实现灵活的安全策略。

权限模式

在 settings.json 中，可以通过 permissionMode 字段设置全局行为模式：

  • default：默认模式，根据权限规则决定是否询问
  • plan：规划模式，工具调用仅用于规划，不实际执行
  • acceptEdits：编辑接受模式，允许自动接受代码编辑建议
  • auto：自动模式，尽可能减少确认提示
  • dontAsk：无询问模式，执行工具前不询问（配合权限规则使用）
  • bypassPermissions：绕过权限模式，跳过权限检查（谨慎使用）

示例配置：

{
  "permissionMode": "default",
  "permissions": {
    "Bash": "ask",
    "Write": "allow",
    "Read": "allow"
  }
}

10.2 /permissions — 交互式权限管理

/permissions 命令（别名 /allowed-tools）提供了一个交互式界面，用于查看和管理权限规则。

命令语法

/permissions

功能说明

/permissions 命令启动一个交互式菜单，支持以下操作：

  • 按范围查看规则：用户级、项目级、本地级
  • 添加新权限规则
  • 删除现有权限规则
  • 管理工作目录
  • 查看最近的自动模式拒绝记录

实际使用示例

示例 1：启动权限管理界面

/permissions

进入交互菜单后，选择 "View rules by scope" 可以看到不同层级的权限规则分布。

示例 2：添加允许规则

在交互菜单中选择 "Add rule"，然后：

  1. 选择工具类型：Bash
  2. 选择权限级别：allow
  3. 输入模式匹配：git *

这将为所有以 git 开头的命令添加自动批准规则。

示例 3：删除规则

选择 "Remove rule"，然后从列表中选择要删除的规则，如 Write(allow *)。

注意事项和技巧

  • 权限模式匹配使用通配符语法：* 匹配任意字符，? 匹配单个字符
  • 常见权限语法示例：
    • Bash(git *)：所有 git 命令
    • Edit(*.ts)：所有 TypeScript 文件编辑
    • Write(.env)：.env 文件写入操作
    • Bash(rm -rf *)：所有危险删除命令
  • 使用更具体的匹配模式可以减少安全风险，例如用 Bash(git status) 替代 Bash(git *)
  • 定期查看自动模式拒绝记录，可以发现需要添加的权限规则

10.3 /hooks — 查看 Hook 配置

Hook 机制是 Claude Code 安全系统的核心组件，允许你在特定事件前后插入自定义逻辑。

命令语法

/hooks

功能说明

/hooks 命令是一个只读浏览器，用于查看所有已配置的 Hook 事件和配置。它展示：

  • Hook 事件类型和触发时机
  • 每个 Hook 的匹配条件和执行内容
  • Hook 的配置来源（用户/项目/本地/插件等）

Hook 事件分类

Hook 按触发时机分为三级：

  1. 会话级

    • SessionStart：会话开始时触发
    • SessionEnd：会话结束时触发

  2. 轮次级

    • UserPromptSubmit：用户提交提示词时触发
    • Stop：用户请求停止时触发

  3. 工具级

    • PreToolUse：工具调用前触发，可以阻止执行
    • PostToolUse：工具调用后触发，可以执行后续操作

Hook 类型

Hook 支持多种执行类型：

  • command：执行外部命令或脚本
  • http：发送 HTTP 请求
  • mcp_tool：调用 MCP 工具
  • prompt：向模型发送提示词
  • agent：调用子代理

实际使用示例

示例 1：查看所有 Hook 配置

/hooks

这将显示一个树状结构，按事件类型组织所有 Hook。

示例 2：查看特定事件的 Hook

在 /hooks 界面中，选择特定的事件类型（如 PreToolUse），可以看到该事件下配置的所有 Hook。

配置来源标记

Hook 配置可能来自多个来源，标记如下：

  • User：用户级配置（~/.claude/settings.json）
  • Project：项目级配置（.claude/settings.json）
  • Local：本地级配置（.claude/settings.local.json）
  • Plugin：插件提供的 Hook
  • Session：会话级临时配置
  • Built-in：内置 Hook

了解配置来源有助于调试和管理复杂的 Hook 策略。

10.4 编写你的第一个 Hook

Hook 通过 settings.json 中的 hooks 字段配置。每个 Hook 包含匹配条件（matcher）和执行逻辑（hooks）。

PreToolUse Hook 示例：阻止危险命令

下面这个 Hook 会在执行 rm -rf 命令前进行拦截检查：

配置文件：.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "if": "Bash(rm *)",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
        }]
      }
    ]
  }
}

Hook 脚本：.claude/hooks/block-rm.sh

#!/bin/bash

# 从 stdin 读取工具调用信息
TOOL_CALL=$(cat)

# 检查是否包含 rm -rf
if echo "$TOOL_CALL" | grep -q "rm -rf"; then
  # 阻止执行
  echo "拒绝执行：检测到危险的 rm -rf 命令"
  exit 2
fi

# 允许执行
exit 0

Hook 脚本通过退出码控制行为：

  • exit 0：允许工具执行
  • exit 1：跳过当前 Hook，继续检查下一个
  • exit 2：阻止工具执行

PostToolUse Hook 示例：自动代码检查

这个 Hook 会在写入 TypeScript 文件后自动运行 lint：

配置文件：.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "if": "Write(*.ts)",
          "command": "cd ${CLAUDE_PROJECT_DIR} && npm run lint -- ${WRITE_FILE_PATH}"
        }]
      }
    ]
  }
}

PostToolUse Hook 的特点是它不会阻止原始操作，而是在工具执行完成后添加额外行为。

Hook 环境变量

Hook 脚本可以使用以下环境变量：

  • ${CLAUDE_PROJECT_DIR}：项目根目录
  • ${CLAUDE_USER_DIR}：用户配置目录
  • ${WRITE_FILE_PATH}：Write 工具的目标文件路径
  • ${EDIT_FILE_PATH}：Edit 工具的目标文件路径
  • ${BASH_COMMAND}：Bash 工具的命令内容

这些变量让 Hook 可以根据具体操作上下文做出更智能的决策。

10.5 /fewer-permission-prompts — 减少权限弹窗

频繁的权限确认会打断工作流程，降低效率。/fewer-permission-prompts Skill 通过分析历史会话记录，自动生成常用只读操作的允许规则。

命令语法

/fewer-permission-prompts

功能说明

该 Skill 执行以下步骤：

  1. 扫描最近的会话记录，识别频繁使用的只读操作
  2. 按使用频率排序操作
  3. 生成优先级建议列表
  4. 将选定的规则写入 .claude/settings.json

实际使用示例

示例 1：生成权限允许列表

/fewer-permission-prompts

Skill 会分析历史记录并提示类似内容：

基于最近 10 个会话的分析，发现以下频繁使用的只读操作：

1. Read - 45 次
2. Bash(ls *) - 32 次
3. Bash(git status) - 28 次
4. Bash(git log) - 15 次
5. Bash(cat *) - 12 次

是否将这些操作添加到允许规则？(y/n)

确认后，这些规则会被自动添加到项目配置中。

注意事项和技巧

  • 该 Skill 只建议添加只读操作规则，不包含写操作
  • 生成的规则会被添加到项目级配置（.claude/settings.json）
  • 定期运行该 Skill 可以持续优化权限配置
  • 对于团队项目，建议在讨论后统一运行，避免个人配置差异
  • 运行前建议先备份现有配置，以防意外覆盖

10.6 /sandbox — 沙箱模式

沙箱模式在隔离环境中执行命令，提供额外的安全保护层。

命令语法

/sandbox

功能说明

沙箱模式的特点：

  • 在隔离的文件系统环境中运行
  • 限制网络访问
  • 限制系统调用范围
  • 提供可审计的操作日志

实际使用示例

示例 1：切换沙箱模式

/sandbox

系统会提示是否启用沙箱模式，确认后当前会话将在沙箱环境中运行。

注意事项和技巧

  • 沙箱模式仅在支持的平台上可用（Linux、macOS）
  • 沙箱模式可能会影响某些需要系统级权限的操作
  • 不建议在沙箱中运行需要构建或依赖安装的操作
  • 对于安全敏感的项目，建议默认启用沙箱模式

10.7 安全最佳实践

构建合理的权限和安全策略需要平衡安全性与效率。以下是推荐的最佳实践：

最小权限原则

  • 默认使用 ask 模式，只在明确需要时使用 allow
  • 避免使用过于宽泛的匹配模式，如 Bash(*) 或 Write(*)
  • 为不同项目设置不同的权限策略

配置层级选择

  • 用户级配置：适用于个人习惯和常用工具，如 Read(allow *)、Bash(git *)
  • 项目级配置：适用于项目特定的规则，如特定目录的 allow 规则
  • 本地级配置：适用于敏感开发环境或临时调试会话

敏感操作保护

  • 为危险操作添加 deny 规则：

    • Bash(deny rm -rf *)
    • Bash(deny git push --force)
    • Write(deny *.key)

  • 使用 Hook 进行二次检查：

    • PreToolUse Hook 验证命令参数
    • PostToolUse Hook 记录敏感操作日志

Hook 作为安全防护层

Hook 是灵活的安全机制，可以用于：

  • 命令白名单验证
  • 操作日志记录
  • 自动化质量检查
  • 集成外部安全工具

示例：集成外部安全扫描

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "http",
          "if": "Write(*.ts)",
          "url": "https://security-scanner.example.com/scan",
          "method": "POST",
          "body": "{\"file_path\": \"${WRITE_FILE_PATH}\"}"
        }]
      }
    ]
  }
}

团队协作建议

  • 将项目级 settings.json 纳入版本控制
  • 在团队文档中明确权限策略
  • 定期审查和更新权限规则
  • 使用 Pull Request 流程审查权限配置变更

10.8 动手做：配置安全策略

现在让我们为番茄钟项目配置一套实用的安全策略。

步骤 1：添加 Git 操作免确认规则

运行 /permissions 命令：

/permissions

选择 "Add rule"，然后：

  1. 工具类型：Bash
  2. 权限级别：allow
  3. 模式匹配：git *

这样所有 git 命令都不需要确认，提高日常开发效率。

步骤 2：创建 PostToolUse Hook

首先创建 Hook 目录：

mkdir -p .claude/hooks

创建 lint 检查脚本 .claude/hooks/lint-after-write.sh：

#!/bin/bash

FILE_PATH="$1"

# 只检查 TypeScript 文件
if [[ "$FILE_PATH" != *.ts ]]; then
  exit 0
fi

# 运行 lint
npm run lint -- "$FILE_PATH" 2>&1

添加执行权限：

chmod +x .claude/hooks/lint-after-write.sh

在 .claude/settings.json 中添加 Hook 配置：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "if": "Write(*.ts)",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-after-write.sh ${WRITE_FILE_PATH}"
        }]
      }
    ]
  }
}

步骤 3：生成常用操作允许列表

运行 /fewer-permission-prompts：

/fewer-permission-prompts

查看分析结果，确认将常见的只读操作添加到允许规则中。

步骤 4：验证 Hook 生效

让 Claude 修改一个 TypeScript 文件，例如：

修改 src/timer.ts，添加一个注释说明倒计时功能

观察 Hook 是否自动执行 lint 检查。你应该能在输出中看到 lint 的结果。

步骤 5：测试权限规则

尝试执行一个 git 命令：

运行 git status 查看当前分支状态

这个命令应该直接执行，不需要确认。

本章小结

本章深入探讨了 Claude Code 的权限与安全系统：

  1. 权限模型：allow/ask/deny 三级规则，支持多层级配置和多种权限模式
  2. 交互式管理：/permissions 命令提供了可视化的权限管理界面
  3. Hook 机制：通过 PreToolUse 和 PostToolUse Hook 实现细粒度的操作控制
  4. 自动化优化：/fewer-permission-prompts Skill 自动生成权限规则
  5. 沙箱模式：在隔离环境中执行命令，提供额外安全保护
  6. 最佳实践：遵循最小权限原则，合理使用配置层级，用 Hook 构建安全防护层

权限与安全配置是持续优化的过程。随着项目的演进，你应该定期审查和调整安全策略，确保在安全性和开发效率之间保持最佳平衡。

在下一章中，我们将学习如何扩展 Claude Code 的功能，通过插件和集成构建更强大的开发工作流。