# Claude Code权限六模式：安全到极速全实战 ## 概述 Claude Code提供了六种权限模式（default、acceptEdits、plan、auto、dontAsk、bypassPermissions），构成了从"每步确认"到"全自动运行"的完整安全光谱。本教程将逐个拆解每种模式的内部机制、搭配settings.json的allow/deny规则引擎，帮你找到安全与效率的精确平衡点。适合所有使用Claude Code的开发者，无论你是第一天安装还是已经用了半年。 ## 前置条件 - 已安装Claude Code（`npm install -g @anthropic-ai/claude-code`） - 拥有Anthropic API key或Claude Pro/Max订阅 - 基本终端操作能力 - 一个Git仓库用于练习 --- ## 一、权限系统全景：为什么需要六种模式 Claude Code是一个能读文件、写文件、执行Shell命令的AI编码助手。每一步操作都可能修改你的代码库，甚至删除关键文件。权限系统的核心问题是：**你愿意给AI多大的自由度？** ### 1.1 安全光谱 ``` 严格 ←————————————————————————→ 自由 default → acceptEdits → plan → auto → dontAsk → bypassPermissions ``` 六种模式并非简单的"开/关"二选一，而是一个渐变光谱： | 模式 | 读操作 | 文件编辑 | Shell命令 | 适用场景 | |------|--------|----------|-----------|----------| | **default** | 自动 | 逐个确认 | 逐个确认 | 日常开发 | | **acceptEdits** | 自动 | 自动通过 | 逐个确认 | 频繁重构 | | **plan** | 自动 | 逐个确认 | 禁止执行 | 代码审查 | | **auto** | 自动 | AI分类决策 | AI分类决策 | 高信任环境 | | **dontAsk** | 自动 | 自动通过 | 自动通过 | CI/CD流水线 | | **bypassPermissions** | 全部自动 | 全部自动 | 全部自动 | 容器化隔离环境 | ### 1.2 切换方式 在交互式会话中，按 **Shift+Tab** 即可循环切换模式： ``` default → acceptEdits → plan → auto → dontAsk → (循环回 default) ``` 底部状态栏会实时显示当前模式名称。也可以通过命令行参数直接指定： ```bash claude # 默认 default 模式 claude --permission-mode auto # 直接启动 auto 模式 claude -p "任务" --permission-mode dontAsk # 非交互模式指定权限 ``` --- ## 二、六种模式逐个拆解 ### 2.1 Default模式：安全第一 **行为**：Claude Code执行任何写操作（Edit、Write）或Shell命令（Bash）前，都会弹出确认提示。读操作（Read、Glob、Grep）自动通过。 **典型交互**： ``` Claude wants to edit src/index.ts: ┌─────────────────────────────────────┐ │ Allow Edit to src/index.ts? [y/n] │ └─────────────────────────────────────┘ ``` **最佳使用场景**： - 刚接手一个不熟悉的项目 - 处理生产环境代码 - 学习Claude Code的第一周 **实操建议**：在default模式下，你可以观察到Claude Code打算做什么，从而建立对其行为的直觉。这是学习阶段最好的模式。 ### 2.2 AcceptEdits模式：专注编码 **行为**：文件编辑操作自动通过，Shell命令仍需逐个确认。 **为什么这种模式很实用**：Claude Code在一次任务中可能进行20-30次文件编辑（读取、分析、修改多个文件）。如果每次都确认，你会被弹窗淹没。AcceptEdits模式承认一个事实——文件编辑通常是低风险的（有Git兜底），而Shell命令的风险更高。 **启用方式**： ```bash # 方式1：Shift+Tab切换到acceptEdits # 方式2：命令行参数 claude --permission-mode acceptEdits ``` **实操建议**：先确保你的工作在Git分支上，这样即使Claude Code做了意料之外的编辑，`git diff` 和 `git checkout` 可以轻松回退。 ### 2.3 Plan模式：只看不改 **行为**：Claude Code可以读取任何文件，但所有写操作和Shell命令都需要确认。实际上，在plan模式下Claude Code会倾向于生成方案而非直接执行。 **最佳使用场景**： - 代码审查（"帮我看看这个模块有没有问题"） - 架构分析（"分析这个项目的依赖关系"） - 学习别人的代码库 **关键细节**：plan模式下Claude Code的回复风格会改变。它会更倾向于给出详细的分析报告和改进建议，而不是直接动手改代码。 ### 2.4 Auto模式：AI裁判 **行为**：Claude Code使用内置分类器（classifier）自动判断每个操作是否安全。低风险操作自动通过，高风险操作仍会提示。 **分类器的判断逻辑**（基于公开文档推断）： - 读取项目内文件 → 自动通过 - 编辑非关键文件（README、测试） → 自动通过 - 编辑核心文件（入口文件、配置） → 可能提示 - 执行 `npm test` → 自动通过 - 执行 `rm -rf`、`git push` → 一定会提示 - 访问外部网络 → 一定会提示 **最佳使用场景**： - 信任Claude Code的判断能力 - 处理自己的个人项目 - 需要快速迭代的原型开发 ```bash claude --permission-mode auto ``` ### 2.5 DontAsk模式：静默执行 **行为**：所有操作自动通过，不弹出任何确认提示。Claude Code会自行决定执行所有读写和Shell命令。 **关键区别**：dontAsk和bypassPermissions看起来行为相似，但有一个重要差异——dontAsk模式下，Claude Code仍然**遵守settings.json中的allow/deny规则**。如果某个操作被deny规则阻止，它仍然不会执行。 **最佳使用场景**： - CI/CD流水线中的自动化任务 - 非交互式批量处理（`claude -p` 模式） - 确定性高的重复任务 ```bash # CI/CD中的典型用法 claude -p "运行测试并修复所有失败的用例" --permission-mode dontAsk ``` **安全警告**：使用dontAsk模式前，务必配置好settings.json的deny规则，至少禁止以下操作： ```json { "deny": [ "Bash(rm -rf *)", "Bash(git push *)", "Bash(git reset --hard *)", "Read(.env*)", "Edit(.env*)" ] } ``` ### 2.6 BypassPermissions模式：完全信任 **行为**：跳过所有权限检查，Claude Code拥有与你当前用户相同的完整权限。这通常被称为"YOLO模式"。 **启用方式**： ```bash claude --dangerously-skip-permissions ``` 注意这个标志的名字——"dangerously"不是随便加的。 **唯一推荐的安全用法**：在完全隔离的容器环境中运行： ```bash # Docker中的安全用法 docker run -it --rm \ -v $(pwd):/workspace \ node:20 \ bash -c "npm install -g @anthropic-ai/claude-code && \ cd /workspace && \ claude --dangerously-skip-permissions -p '任务描述'" ``` **绝对不要**： - 在生产环境机器上使用 - 在包含未提交工作的Git仓库中使用 - 在包含敏感信息的目录中使用 --- ## 三、Settings.json：权限的底层引擎 六种模式只是预设行为，真正的精细控制在于settings.json中的allow/deny规则。理解这一层，你才能真正做到"恰到好处"的权限管理。 ### 3.1 配置文件的五个层级 Claude Code的配置遵循层级覆盖机制——高层级覆盖低层级： ``` 企业管理策略 (managed) ↓ 覆盖 用户全局配置 (~/.claude/settings.json) ↓ 覆盖 项目团队配置 (.claude/settings.json) ↓ 覆盖 项目本地配置 (.claude/settings.local.json) ↓ 覆盖 命令行参数 (--allow / --deny) ``` | 层级 | 文件位置 | 作用域 | 提交到Git | |------|----------|--------|-----------| | 企业管理 | 系统级配置 | 全公司 | N/A | | 用户全局 | `~/.claude/settings.json` | 当前用户所有项目 | 否 | | 项目团队 | `.claude/settings.json` | 当前项目，团队共享 | 是 | | 项目本地 | `.claude/settings.local.json` | 当前项目，仅个人 | 否（加入.gitignore） | | 命令行 | `--allow` / `--deny` | 当前会话 | N/A | ### 3.2 Allow/Deny规则语法 规则由三部分组成：`ToolName(pattern)`，其中pattern支持通配符。 **工具名称列表**： | 工具名 | 控制范围 | |--------|----------| | `Bash` | Shell命令执行 | | `Read` | 读取文件 | | `Edit` | 编辑已有文件 | | `Write` | 创建新文件 | | `WebFetch` | 网络请求 | | `WebSearch` | 网络搜索 | **Bash规则——按命令模式匹配**： ```json { "allow": [ "Bash(npm test)", "Bash(npm run *)", "Bash(git status)", "Bash(git diff *)", "Bash(git log *)", "Bash(ls *)", "Bash(cat *)", "Bash(python *)", "Bash(make *)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force *)", "Bash(git reset --hard *)", "Bash(sudo *)", "Bash(curl * | bash)", "Bash(chmod 777 *)" ] } ``` **文件规则——按路径模式匹配**： ```json { "allow": [ "Edit(src/**)", "Edit(tests/**)", "Read(**)" ], "deny": [ "Edit(.env*)", "Edit(*.secret*)", "Edit(production.*)", "Write(/etc/*)", "Read(/etc/shadow)" ] } ``` ### 3.3 规则评估逻辑 当Claude Code想要执行某个操作时，评估顺序如下： ``` 1. 检查 deny 规则 → 匹配则拒绝 2. 检查 allow 规则 → 匹配则通过 3. 都不匹配 → 根据当前权限模式决定（提示/通过/拒绝） ``` **deny优先原则**：即使同时匹配了allow和deny，deny胜出。这是安全设计的基本原则。 ```mermaid flowchart TD A[Claude Code请求操作] --> B{匹配deny规则?} B -->|是| C[拒绝执行] B -->|否| D{匹配allow规则?} D -->|是| E[自动通过] D -->|否| F{当前权限模式?} F -->|default/plan| G[弹出确认提示] F -->|acceptEdits| H[编辑自动通过
命令弹出提示] F -->|auto| I[AI分类器判断] F -->|dontAsk| J[自动通过] F -->|bypassPermissions| K[跳过所有检查] ``` --- ## 四、实战案例：为三种典型场景配置权限 ### 4.1 场景一：个人开源项目——平衡效率与安全 **目标**：允许Claude Code自由编辑源码和测试，但禁止修改配置文件和执行危险Shell命令。 创建 `.claude/settings.json`： ```json { "allow": [ "Bash(npm *)", "Bash(npx *)", "Bash(git status)", "Bash(git diff *)", "Bash(git add *)", "Bash(git commit *)", "Bash(git log *)", "Bash(node *)", "Bash(tsc *)", "Bash(eslint *)", "Bash(prettier *)", "Edit(src/**)", "Edit(tests/**)", "Edit(docs/**)", "Write(src/**)", "Write(tests/**)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force *)", "Bash(sudo *)", "Bash(npm publish *)", "Edit(package.json)", "Edit(tsconfig.json)", "Edit(.github/**)", "Edit(.env*)" ] } ``` **运行方式**：使用 `acceptEdits` 模式。 ```bash claude --permission-mode acceptEdits ``` 这样Claude Code可以自由修改源码和测试文件，但想改package.json时会弹出确认，想执行`rm -rf`会被直接拒绝。 ### 4.2 场景二：团队项目——严格的协作控制 **目标**：团队所有成员共享同一套权限规则，防止Claude Code意外修改关键基础设施文件。 项目根目录 `.claude/settings.json`（提交到Git）： ```json { "allow": [ "Bash(npm run lint)", "Bash(npm run test*)", "Bash(npm run build*)", "Bash(npm run format)", "Bash(git status)", "Bash(git diff *)", "Bash(git log *)", "Bash(git branch *)", "Bash(git checkout *)", "Bash(npx jest *)", "Bash(npx tsc --noEmit)", "Edit(src/**)", "Edit(tests/**)", "Edit(*.md)", "Read(**)" ], "deny": [ "Bash(rm *)", "Bash(git push *)", "Bash(git merge *)", "Bash(git rebase *)", "Bash(sudo *)", "Bash(docker *)", "Bash(kubectl *)", "Edit(.env*)", "Edit(terraform/**)", "Edit(.github/workflows/**)", "Edit(docker-compose.*)", "Edit(Dockerfile*)", "Edit(package.json)", "Edit(package-lock.json)", "Edit(.claude/**)", "Write(.env*)", "Write(.github/**)" ] } ``` 个人本地覆盖 `.claude/settings.local.json`（不提交到Git）： ```json { "allow": [ "Bash(npm run dev*)", "Bash(docker compose up*)", "Bash(git push origin *)" ] } ``` **运行方式**：默认使用 `default` 模式，团队成员通过Shift+Tab按需调整。 ```mermaid flowchart LR subgraph 团队共享配置 A[.claude/settings.json] end subgraph 个人本地配置 B[.claude/settings.local.json] end subgraph 运行时 C[default模式
+ allow/deny引擎] end A --> C B --> C C --> D{Claude Code请求操作} D --> E[deny规则检查] E --> F[allow规则检查] F --> G[模式行为决策] ``` ### 4.3 场景三：CI/CD自动化——零人工干预 **目标**：在GitHub Actions中运行Claude Code，自动修复代码问题，零人工干预。 GitHub Actions工作流 `.github/workflows/claude-auto-fix.yml`： ```yaml name: Claude Auto Fix on: issues: types: [labeled] workflow_dispatch: jobs: auto-fix: runs-on: ubuntu-latest permissions: contents: write pull-requests: write steps: - uses: actions/checkout@v4 with: token: ${{ secrets.GITHUB_TOKEN }} - name: Setup Claude Code env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: npm install -g @anthropic-ai/claude-code - name: Run Claude Code env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | claude -p "读取issue #${{ github.event.issue.number }}的描述，修复相关问题，创建新分支并提交PR" \ --permission-mode dontAsk \ --allowedTools "Edit(src/**)" "Edit(tests/**)" "Bash(npm run *)" "Bash(git *)" "Read(**)" \ --deny "Bash(git push --force *)" "Bash(rm *)" ``` **关键安全措施**： 1. 使用 `dontAsk` 而非 `bypassPermissions`——仍受规则约束 2. 通过 `--allowedTools` 精确限定可用工具 3. CI环境本身是隔离的（每次运行是全新容器） 4. 使用最小权限的GITHUB_TOKEN --- ## 五、进阶技巧：权限与其他功能的组合 ### 5.1 权限模式 + Hooks Hooks是Claude Code的另一层安全机制，可以在工具执行前后运行自定义Shell脚本。与权限模式组合使用，可以实现更精细的控制。 `.claude/settings.json`： ```json { "hooks": { "preToolUse": [ { "matcher": "Bash", "command": "python3 scripts/check-dangerous-commands.py" } ], "postToolUse": [ { "matcher": "Edit", "command": "python3 scripts/log-edits.py" } ] } } ``` `scripts/check-dangerous-commands.py` 的逻辑： 1. 读取Claude Code即将执行的命令（通过环境变量） 2. 检查命令是否匹配危险模式（如 `DROP TABLE`、`rm -rf /`） 3. 匹配则返回退出码1阻止执行，不匹配则返回0放行 **组合策略**： - settings.json的deny规则 → 静态模式匹配（快速、确定性） - Hooks脚本 → 动态逻辑判断（灵活、可编程） - 权限模式 → 控制未匹配规则时的默认行为 ```mermaid flowchart TD A[操作请求] --> B{deny规则匹配?} B -->|是| C[拒绝] B -->|否| D{allow规则匹配?} D -->|是| E{preToolUse Hook} E -->|通过| F[执行操作] E -->|阻止| G[Hook拒绝] D -->|否| H{权限模式决策} H --> I{preToolUse Hook} I -->|通过| F I -->|阻止| G F --> J[postToolUse Hook] J --> K[记录日志/后处理] ``` ### 5.2 按项目类型选择权限策略 不同类型的项目需要不同的权限策略： | 项目类型 | 推荐模式 | 关键allow规则 | 关键deny规则 | |----------|----------|---------------|--------------| | 个人脚本项目 | acceptEdits | `Bash(python *)` `Bash(pip *)` | `Bash(rm -rf *)` | | 前端SPA | acceptEdits | `Bash(npm *)` `Bash(npx *)` | `Edit(.env*)` `Bash(npm publish)` | | 后端API | default | `Bash(go *)` `Bash(cargo *)` | `Edit(prod.*)` `Bash(sudo *)` | | 基础设施代码 | plan | `Bash(terraform plan)` | `Bash(terraform apply *)` | | 机器学习 | acceptEdits | `Bash(python *)` `Bash(jupyter *)` | `Edit(.env*)` `Bash(rm data/**)` | | 文档网站 | auto | `Edit(docs/**)` `Bash(npm run build)` | `Edit(src/**)` | ### 5.3 命令行快速配置 除了编辑settings.json文件，Claude Code还支持通过命令行参数进行一次性配置： ```bash # 允许特定操作 claude --allow "Bash(npm test)" --allow "Edit(src/**)" # 拒绝特定操作 claude --deny "Bash(rm *)" --deny "Edit(.env*)" # 组合使用 claude --permission-mode acceptEdits \ --allow "Bash(npm run *)" \ --deny "Bash(npm publish)" \ --deny "Edit(.env*)" ``` 这种方式适合临时调整，不修改任何配置文件。 --- ## 六、常见问题与排错 ### Q1：Shift+Tab切换没反应？ 可能原因：终端模拟器拦截了Shift+Tab快捷键。 - **iTerm2**：检查 Preferences → Profiles → Keys → 是否有冲突绑定 - **VS Code终端**：在设置中搜索 `terminal.integrated.commandsToSkipShell` - **tmux**：需要在 `~/.tmux.conf` 中添加 `bind -n Shift-Tab send-keys Shift-Tab` 替代方案：直接在对话中输入 `/permission` 查看和切换模式。 ### Q2：deny规则没生效？ 检查以下常见问题： 1. **路径格式**：规则使用相对路径（相对于项目根目录），不以 `/` 开头 2. **通配符**：`*` 匹配单层路径，`**` 匹配多层路径 3. **层级覆盖**：你的deny可能在项目本地配置中，但allow在全局配置中，allow覆盖了deny 4. **工具名大小写**：必须精确——`Bash`、`Edit`、`Read`（不是 `bash`、`edit`） ### Q3：auto模式的分类器行为不符合预期？ auto模式的分类器基于操作的风险评估，但你无法直接配置分类器的逻辑。如果auto模式的行为不理想： - 使用settings.json的allow/deny规则覆盖分类器决策 - 切换到acceptEdits或dontAsk模式获得确定性行为 - 使用Hooks进行自定义风险评估 ### Q4：CI/CD中dontAsk模式报错？ 确保： 1. 环境变量 `ANTHROPIC_API_KEY` 已正确设置 2. 使用 `-p` 参数提供非交互式任务描述 3. 设置 `--output-format stream-json` 获取结构化输出 4. 配置了合理的deny规则作为安全网 ```bash claude -p "修复所有TypeScript编译错误" \ --permission-mode dontAsk \ --output-format stream-json \ --deny "Bash(rm *)" "Bash(git push --force *)" ``` --- ## 七、权限决策流程图 将所有内容整合为一个完整的决策流程： ```mermaid flowchart TD Start[开始Claude Code会话] --> Q1{项目类型?} Q1 -->|个人项目/学习| Q2{是否熟悉Claude Code?} Q1 -->|团队项目| Q3{是否CI/CD环境?} Q1 -->|生产环境/基础设施| Plan[plan模式
+ 严格deny规则] Q2 -->|不熟悉| Default[default模式
观察AI行为] Q2 -->|熟悉| AcceptEdits[acceptEdits模式
+ 基础deny规则] Q3 -->|是| DontAsk[dontAsk模式
+ 精确allow规则
+ 完整deny规则] Q3 -->|否| Q4{信任等级?} Q4 -->|高信任| Auto[auto模式
+ 关键deny规则] Q4 -->|低信任| Default2[default模式
+ 完整deny规则] Default --> Config1[配置deny规则:
rm -rf, git push --force, sudo] AcceptEdits --> Config2[配置deny规则:
rm -rf, .env*, package.json] DontAsk --> Config3[配置allow规则:
仅允许必要操作] Plan --> Config4[配置deny规则:
所有写操作和Shell命令] Auto --> Config5[配置deny规则:
生产环境文件, 敏感操作] Default2 --> Config6[配置完整deny列表] Config1 --> Run[开始编码] Config2 --> Run Config3 --> Run Config4 --> Run Config5 --> Run Config6 --> Run ``` --- ## 八、实战练习：构建你的权限配置模板 完成以下练习，检验你对权限系统的理解： ### 练习1：基础配置 为一个Node.js项目创建settings.json，要求： - 允许 `npm test`、`npm run build`、`npm run lint` - 允许编辑 `src/` 和 `tests/` 目录下的所有文件 - 拒绝修改 `.env` 文件 - 拒绝执行 `rm -rf` 和 `sudo` - 使用 acceptEdits 模式 ### 练习2：进阶配置 为一个Python + Terraform混合项目创建分层配置： - 团队共享层：允许所有读取，拒绝修改Terraform文件 - 个人本地层：允许运行本地开发服务器 - 使用 default 模式，但Terraform文件即使在allow中也应被拒绝 ### 练习3：CI/CD配置 编写一个GitHub Actions工作流： - 在PR创建时自动运行 - Claude Code检查代码风格并自动修复 - 使用 dontAsk 模式 - 只允许修改 `src/` 目录下的 `.py` 文件 - 自动提交修复并推送 --- ## 延伸阅读 - [Claude Code官方权限文档](https://code.claude.com/docs/en/permissions) — 权限规则的权威参考 - [Claude Code权限模式选择指南](https://code.claude.com/docs/en/permission-modes) — 六种模式的官方说明 - [Claude Code设置参考](https://code.claude.com/docs/en/settings) — settings.json完整配置项 - [Claude Code最佳实践](https://code.claude.com/docs/en/best-practices) — 官方推荐的工作流程 - [Taming Claude YOLO Mode with Safety Hooks](https://www.agentic-engineer.com/blog/2025-10-13-taming-claude-yolo-mode) — Hooks安全实践 --- ## 参考来源 1. [Choose a permission mode - Claude Code Docs](https://code.claude.com/docs/en/permission-modes) — Anthropic官方六种权限模式文档 2. [Claude Code Permission Modes: Complete Guide to 6 Modes](https://smartscope.blog/en/generative-ai/claude/claude-code-permission-overview/) — 六种模式的深度对比分析 3. [Claude Code permission modes: which one should your CI use?](https://backgroundclaude.com/blog/permission-modes) — CI/CD场景下的权限模式选择策略 4. [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) — allow/deny规则语法和配置方法 5. [Lock Down Claude Code With 5 Permission Patterns](https://dev.to/klement_gunndu/lock-down-claude-code-with-5-permission-patterns-4gcn) — 五种权限锁定模式的实战案例 --- *训练营适用性评估*：本教程适合"AI编码工具实战训练营"的基础模块（Day 1-2），建议教学时长2小时（1小时讲解 + 1小时动手练习）。学员需在安全环境中完成三个练习题，验证权限配置的正确性。 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。