Claude Code 深度学习手册

主题

Permission Modes（权限模式） ​

Permission Modes 控制 Claude Code 在编辑文件、运行命令或发起网络请求前向你征求批准的频率，从「每步都问」到「完全不问」共 6 档。

你的真实情况 ​

你长期开 bypassPermissions（全局 defaultMode）——6 种模式里最放权的一档，权限弹窗和安全检查全跳过，工具调用立即执行。所以其余 5 种模式（default / acceptEdits / plan / auto / dontAsk）对你日常基本用不上。

几个仍与你相关的点：

  • 即便 bypass，rm -rf / 和 rm -rf ~ 仍会弹窗（熔断）；受保护目录（.git/.claude/.idea 等）写入仍拦。
  • 想临时收紧某个项目：在该项目 .claude/settings.json 写 "defaultMode": "default"，会压过你全局的 bypass（Project 层优先级高于 User 层）。
  • 想"少弹窗但保留安全检查"：用 auto（研究预览）比 bypass 更稳——它用分类器在后台拦危险操作，而不是全放。
  • 切换：Shift+Tab 循环。

bypass 下你唯一的硬闸是 hook（见「安全」「Hooks」节）。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

当 Claude 想编辑文件、运行 shell 命令或发起网络请求时，它会暂停并请求批准。Permission Modes 决定这个「暂停」发生得多频繁。共有 6 种模式：default、acceptEdits、plan、auto、dontAsk、bypassPermissions，每种在「便利」和「监督」之间做不同权衡。模式设定的是基线（baseline），可在其上叠加 permission rules（allow/ask/deny）来对具体工具做预批或拦截——唯一例外是 bypassPermissions，它完全跳过 permission 层。模式由界面控件设定（Shift+Tab 循环、CLI flag、settings），不是在对话里让 Claude 切换。

怎么工作 ​

  • 6 种模式各自「无需询问即可运行」的范围：default=仅读取；acceptEdits=读取+文件编辑+常见文件系统命令；plan=仅读取；auto=一切（带后台安全检查）；dontAsk=仅预批工具；bypassPermissions=一切。
  • CLI 中 Shift+Tab 循环顺序固定为 default → acceptEdits → plan；可选模式插在 plan 之后，顺序为 bypassPermissions 在前、auto 在后（两者都启用时会先经过 bypassPermissions 再到 auto）。
  • acceptEdits 不仅自动批准文件编辑，还自动批准 Bash 文件系统命令 mkdir/touch/rm/rmdir/mv/cp/sed；这些命令带安全环境变量前缀（如 LANG=C、NO_COLOR=1）或进程包装器（timeout/nice/nohup）时同样自动批准。仅限工作目录或 additionalDirectories 内的路径；范围外路径、protected paths 写入、其他所有 Bash 命令仍会询问。状态栏显示 ⏵⏵ accept edits on。
  • 启用 PowerShell tool 时，acceptEdits 还自动批准 Set-Content/Add-Content/Clear-Content/Remove-Item（含常见别名），同样受范围与 protected-path 规则约束。
  • plan 模式让 Claude 只研究并提出变更而不实际改源码：可读文件、跑 shell 探索、写计划，但不编辑源码；权限提示与 default 相同。可用 Shift+Tab 进入，或单条 prompt 前缀 /plan 仅对该条生效。
  • plan 计划就绪后提供的批准选项：Approve and start in auto mode / Approve and accept edits / Approve and review each edit manually / Keep planning with feedback / Refine with Ultraplan。批准会退出 plan 模式并切到对应权限模式开始编辑。Ctrl+G 可在默认文本编辑器打开计划直接编辑。批准计划还会按计划内容自动命名 session（除非已用 --name 或 /rename 命名）。
  • auto 模式由一个独立的 classifier model（分类器模型）在动作运行前审查，拦截超出你请求范围、指向未识别基础设施、或疑似被读到的恶意内容驱动的动作。auto 还会推动 Claude 持续工作、少停下来问澄清问题（但 prompt 或 skill 明确依赖时仍会问）。
  • auto classifier 决策顺序（第一个命中的步骤生效）：1) 命中你的 allow/deny 规则立即解析；2) 只读动作与工作目录内文件编辑自动批准（protected paths 写入除外）；3) 其余交给分类器；4) 分类器拦截则 Claude 收到原因并尝试替代方案。
  • 进入 auto 时会丢弃授予任意代码执行的宽泛 allow 规则：Bash() / PowerShell()、通配解释器如 Bash(python*)、包管理器 run 命令、Agent allow 规则；窄规则如 Bash(npm test) 保留；离开 auto 时被丢弃的规则恢复。
  • auto 分类器只能看到 user 消息、工具调用、CLAUDE.md 内容；tool results 被剥离，因此文件或网页里的恶意内容无法直接操纵它；另有服务端 probe 扫描进入的 tool results 并在 Claude 读取前标记可疑内容。
  • auto 对 subagent 在三个时点检查：1) 子代理启动前评估委派任务描述；2) 运行中每个动作按与父 session 相同规则过分类器，子代理 frontmatter 里的 permissionMode 被忽略；3) 完成时审查其完整动作历史，若 return check 发现问题则在子代理结果前置安全警告。
  • 在对话中陈述的边界（如「don't push」「wait until I review before deploying」）被分类器当作拦截信号，即使默认规则允许也拦截；边界一直生效直到你在后续消息解除，Claude 自己判断条件已满足不会解除。边界不存为规则，分类器每次检查从 transcript 重新读取，context compaction 移除该消息会导致边界丢失。
  • dontAsk 模式自动拒绝所有本会提示的工具调用；只有命中 permissions.allow 规则的动作和 read-only Bash 命令能执行；显式 ask 规则被拒绝而非提示——对 CI 完全非交互。
  • bypassPermissions 模式禁用权限提示和安全检查，工具调用立即执行；自 v2.1.126 起也包含 protected paths 写入（早期版本仍会提示）。针对文件系统根或家目录的删除（rm -rf / 和 rm -rf ~）仍会提示作为防模型出错的断路器。
  • Protected paths（受保护路径）在除 bypassPermissions 外的每种模式都不会被自动批准：default/acceptEdits/plan 下提示，auto 下走分类器，dontAsk 下拒绝，bypassPermissions 下允许。

怎么配置 / 用法 ​

设默认模式（用户/项目 settings 的 permissions.defaultMode）： { "permissions": { "defaultMode": "acceptEdits" } } plan 作项目默认写在 .claude/settings.json：{ "permissions": { "defaultMode": "plan" } }

启动时用 flag：claude --permission-mode plan（也支持 acceptEdits/dontAsk/bypassPermissions）。 非交互：--permission-mode 与 -p 同用（/en/headless）。 Remote Control 启动主机设起始模式：claude remote-control --permission-mode acceptEdits

bypassPermissions 启用 flag：--permission-mode bypassPermissions / --dangerously-skip-permissions（等价）/ --allow-dangerously-skip-permissions（仅把模式加入循环但不激活）。 管理员锁定：managed settings 里 permissions.disableAutoMode = "disable" 禁 auto；permissions.disableBypassPermissionsMode = "disable" 禁 bypass。 VS Code：claudeCode.initialPermissionMode（不接受 auto）；auto 须改用 ~/.claude/settings.json 的 defaultMode。 查看 auto 默认规则：claude auto-mode defaults。auto 受信基础设施配置：autoMode.environment 设置（/en/auto-mode-config）。

什么时候用 ​

  • default：起步、敏感工作，逐个动作审查。
  • acceptEdits：迭代你正在审查的代码，事后用编辑器或 git diff 看变更而非逐条内联批准。
  • plan：改动前先探索代码库；想让 Claude 研究并提计划但不碰源码。
  • auto：长任务、降低 prompt 疲劳，且你信任大方向时——但不要当作敏感操作免审查的替代（research preview，降提示不保证安全）。
  • dontAsk：锁定的 CI 流水线或受限环境，预先定义好 Claude 能做什么。
  • bypassPermissions：仅限隔离环境（容器、VM、无网络 dev container）；对 prompt injection 无防护。需无提示的后台安全检查时改用 auto。
  • 想要更强自主行为同时保留权限提示：设 Proactive output style 而非 auto。

限制 / 坑 ​

  • 除 bypassPermissions 外所有模式都永不自动批准对 protected paths 的写入。
  • auto 模式要求 Claude Code v2.1.83 或更高。
  • auto 仅在账户满足全部要求时可用：Team/Enterprise 需管理员在 admin settings 启用；模型须 Opus 4.6+ 或 Sonnet 4.6（Sonnet 4.5、Opus 4.5、Haiku、claude-3 均不支持）；Provider 仅 Anthropic API（Bedrock/Vertex/Foundry 不支持）。报「auto mode unavailable」表示某项要求未满足，非临时故障。
  • auto 拦截阈值：连续拦截 3 次 或 累计 20 次则 auto 暂停、恢复提示；阈值不可配置；任一被允许动作重置连续计数，累计计数持续整个 session、仅在触发其自身上限回退时重置。
  • 非交互模式（-p）下反复拦截会中止 session，因为无人可提示。
  • defaultMode:"auto" 在 .claude/settings.json 或 .claude/settings.local.json 中被忽略（仓库不能给自己授 auto），须放到 ~/.claude/settings.json；project/local settings 的 defaultMode:"auto" 也被忽略。
  • bypassPermissions 不能从未带启用 flag 启动的 session 进入，须用 flag 重启。
  • Linux/macOS 上以 root 或 sudo 运行时 Claude Code 拒绝以 bypassPermissions 启动，报：--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons（在识别到的 sandbox 内自动跳过该检查）。
  • auto 中对话陈述的边界不存为规则，context compaction 删掉该消息会使边界丢失；要硬保证须加 deny rule。
  • VS Code 的 claudeCode.initialPermissionMode 不接受 auto；JetBrains 在 IDE 终端跑，切换方式同 CLI。
  • Web/mobile：Cloud sessions 仅 Auto accept edits + Plan mode；Remote Control sessions 仅 Ask permissions + Auto accept edits + Plan mode；两者都没有 Auto 和 Bypass permissions。
  • bypassPermissions 完全跳过 permission 层，叠加的 permission rules 在该模式下不生效。

硬事实速查（35 条） ​

  • 6 种模式：default、acceptEdits、plan、auto、dontAsk、bypassPermissions。
  • 各模式无需询问范围：default=Reads only；acceptEdits=Reads + file edits + 常见 filesystem 命令；plan=Reads only；auto=Everything + background safety checks；dontAsk=仅 pre-approved tools；bypassPermissions=Everything。
  • Shift+Tab 默认循环：default → acceptEdits → plan；状态栏显示当前模式。
  • 可选模式插在 plan 之后，bypassPermissions 在前、auto 在后。
  • acceptEdits 自动批准的 Bash 命令：mkdir、touch、rm、rmdir、mv、cp、sed。
  • acceptEdits 允许的安全前缀/包装器：LANG=C、NO_COLOR=1、timeout、nice、nohup。
  • acceptEdits + PowerShell tool 自动批准：Set-Content、Add-Content、Clear-Content、Remove-Item（含别名）。
  • acceptEdits 自动批准范围限工作目录或 additionalDirectories 内。
  • acceptEdits 状态栏：⏵⏵ accept edits on。
  • plan 进入：Shift+Tab 或单条 prompt 前缀 /plan；再按 Shift+Tab 离开不批准计划。
  • plan 批准选项：Approve and start in auto mode / Approve and accept edits / Approve and review each edit manually / Keep planning with feedback / Refine with Ultraplan。
  • plan 中 Ctrl+G 在默认文本编辑器打开计划编辑；启用 showClearContextOnPlanAccept 时各批准选项还提供先清理 planning context。
  • auto 需 Claude Code v2.1.83+。
  • auto 支持模型：Claude Opus 4.6+ 或 Sonnet 4.6；不支持 Sonnet 4.5、Opus 4.5、Haiku、claude-3。
  • auto 仅 Anthropic API；不支持 Bedrock、Vertex、Foundry。
  • auto 管理员锁定：permissions.disableAutoMode = "disable"（managed settings）。
  • auto 进入时丢弃的宽规则：Bash()、PowerShell()、Bash(python*) 类通配解释器、包管理器 run 命令、Agent allow 规则；保留 Bash(npm test) 类窄规则；离开时恢复。
  • auto 默认拦截：curl | bash 类下载执行代码、发敏感数据到外部端点、生产 deploy/migration、云存储大规模删除、授予 IAM/repo 权限、改共享基础设施、不可逆销毁 session 前已存在的文件、force push 或直接 push main。
  • auto 默认允许：工作目录本地文件操作、安装 lock/manifest 声明的依赖、读 .env 并把凭证发给匹配的 API、只读 HTTP 请求、push 到起始分支或 Claude 创建的分支。
  • auto 回退阈值：连续 3 次 或 累计 20 次拦截则暂停 auto，阈值不可配置。
  • auto 被拒动作出现在 /permissions 的 Recently denied 标签，按 r 可手动批准重试。
  • auto 命令：claude auto-mode defaults 查看完整规则；autoMode.environment 配置受信基础设施。
  • dontAsk 设定：claude --permission-mode dontAsk；从不出现在 Shift+Tab 循环；仅 permissions.allow 规则动作和 read-only Bash 命令可执行，显式 ask 规则被拒。
  • bypassPermissions 自 v2.1.126 起也包含 protected paths 写入（早期版本会提示）。
  • bypassPermissions 启用 flag：--permission-mode bypassPermissions、--dangerously-skip-permissions（等价）、--allow-dangerously-skip-permissions（加入循环不激活）。
  • bypassPermissions 管理员锁定：permissions.disableBypassPermissionsMode = "disable"。
  • rm -rf / 和 rm -rf ~ 在 bypassPermissions 下仍提示作为断路器。
  • root/sudo 下拒绝 bypassPermissions 启动，报错：--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons。
  • Protected directories：.git、.vscode、.idea、.husky、.cargo、.claude（例外 .claude/commands、.claude/agents、.claude/skills、.claude/worktrees）。
  • Protected files：.gitconfig、.gitmodules、.bashrc、.bash_profile、.zshrc、.zprofile、.profile、.ripgreprc、.mcp.json、.claude.json。
  • settings 字段：permissions.defaultMode；VS Code 字段：claudeCode.initialPermissionMode（不接受 auto）。
  • defaultMode:"auto" 仅 ~/.claude/settings.json 生效，project/local settings 被忽略。
  • VS Code UI 标签映射：Ask before edits=default、Edit automatically=acceptEdits、Plan mode=plan、Auto mode=auto、Bypass permissions=bypassPermissions。
  • Remote Control 启动：claude remote-control --permission-mode acceptEdits。
  • 相关页面：/en/permissions、/en/auto-mode-config、/en/hooks（PreToolUse、PermissionRequest）、/en/ultraplan、/en/sandboxing、/en/headless。

官方出处：https://code.claude.com/docs/en/permission-modes