AIGC标识 深入理解 Qoder CLI 权限模式：default / accept_edits / auto / YOLO / dont_ask 全面对比

深入理解 Qoder CLI 权限模式：default / accept_edits / auto / YOLO / dont_ask 全面对比

用 AI 命令行 Agent 写代码，本质上是在回答一个问题：「哪些操作我可以放心让它自己做？」Qoder CLI 用一套**权限模式（permission mode）**体系给出了分层答案。本文逐一拆解每种模式的行为边界、适用场景和切换方式，最后给出一张选型决策图。

目录

一、先建立心智模型：allow / ask / deny

不管处于哪种权限模式，Agent 每一次工具调用（读写文件、执行命令、访问外部服务）最终都只会得到三种结果之一：

结果 含义
allow 立即执行
ask 需要确认（弹窗问用户，或交给运行环境处理）
deny 直接阻止

权限模式做的事情，就是改变「哪些操作落入 ask」的边界。 模式越宽松，越多原本要问的操作变成自动放行；模式越严格，越多操作被拒绝或留给人确认。

理解了这个三角，后面所有模式都只是「边界画在哪里」的差异。

二、五种权限模式总览

官方定义的权限模式共 5 种：

模式 一句话定位 行为摘要
default 标准模式 安全读取和内部动作自动执行；敏感操作逐个弹窗确认
accept_edits 日常编码 自动批准工作目录内的安全文件编辑；Shell 命令等仍要确认
auto 无人值守自动化 零弹窗；风险动作被拒绝或交给 AI 分类器判断
bypass_permissions（YOLO） 可信本地实验 跳过所有批准提示，全放行（少量路径形状保护仍生效）
dont_ask 必须无弹窗的 headless 流程 从不询问；原本要问的操作直接拒绝

另外 --permission-mode plan 这个取值仍被接受，但 plan 严格来说是工作状态而非权限模式，详见第四节。

三、各模式详解

3.1 default：标准模式

qodercn --permission-mode default
  • 行为：安全的读取类操作和内部动作自动执行；涉及敏感操作（写文件、跑命令等）时逐个弹窗，由你决定允许还是拒绝。
  • 场景：常规交互式使用，想逐步把关每个动作。
  • 特点：它是 general.defaultPermissionMode 的默认值，也是唯一在不可信目录下不会被降级的模式——不信任的目录一律回退到 default。

3.2 accept_edits：信任改代码，但把关命令执行

qodercn --permission-mode accept_edits
  • 行为：工作目录内的安全文件编辑自动批准，不再弹窗；但 Shell 命令、外部动作、敏感路径（如 .git、shell 启动文件等受保护路径）仍走正常确认。
  • 场景：日常编码主力模式——你信任 Agent 修改代码，但 rm、git push 这类命令还想亲眼过一遍。
  • 注意：它的自动批准只覆盖「文件编辑」这一个维度，不会连带放行任何命令执行。

3.3 auto：零弹窗 + AI 分类器把关

qodercn --permission-mode auto


qodercn --permission-mode auto -s docker "运行测试并修复失败项"   # 搭配沙箱
  • 行为：
    • 安全读取、工作区内的编辑：自动批准，不走分类器；
    • 受保护路径（.git、.vscode、.husky、多数 .qoder 配置、.bashrc/.zshrc、.mcp.json 等）：直接拒绝；
    • 危险 Shell 命令（破坏性删除、force push 等）：直接拒绝；
    • 其余风险动作：交给 AI 分类器判断放行或拒绝。
  • 场景：自动化运行、无人值守的 Goal 执行。
  • 注意：「零弹窗」不等于「零风险」——风险动作会被拒，任务可能因此中断或绕路。

用 autoMode 软引导分类器

可以在用户级 settings.json 里用自然语言给分类器「打补丁」（注意 autoMode 是顶层键，不在 permissions 下）：

{


  "autoMode": {


    "allow": ["running npm/yarn/pnpm scripts defined in package.json"],


    "soft_deny": ["deleting files outside the test directory", "modifying CI/CD configuration"],


    "environment": ["This is a Node.js monorepo with pnpm workspaces"]


  }


}
  • allow：倾向自动批准的操作描述
  • soft_deny：倾向拒绝的操作描述
  • environment：提供给分类器的项目背景

两个关键性质：

  1. 软约束——这些描述只是注入分类器提示词的参考，最终决策仍由分类器做出；
  2. 只读可信来源——只从用户全局配置和本地配置读取，项目级 settings 被刻意排除，防止恶意仓库通过项目配置给自己提权。

3.4 bypass_permissions（YOLO）：全放行，仅限可信实验

以下写法完全等价：

qodercn --permission-mode bypass_permissions   # 或 bypassPermissions / yolo / YOLO


qodercn --yolo


qodercn --dangerously-skip-permissions

会话内还可按 Ctrl+Y 直达。

  • 行为：跳过所有批准提示。但仍有少量「路径形状」保护生效：
    • 网络位置路径（\\server\share、UNC、WebDAV、/net/<host>/…）的读写与 Shell 访问一律拒绝；
    • 易绕过的写法（交替数据流、8.3 短文件名、设备路径、保留设备名等）仍需显式批准。
  • 场景：官方定位非常明确——仅用于可信本地实验。
  • 组织管控：管理员可在 settings 中设置 "security": { "disableYoloMode": true } 全局禁用：设置后 --yolo 参数、Ctrl+Y 全部失效，Shift+Tab 循环会跳过 YOLO，子 Agent 声明 bypass 时会被降级为 accept_edits。

3.5 dont_ask：永不弹窗，问就是拒

qodercn --permission-mode dont_ask
  • 行为：从不询问。任何原本需要询问的操作直接拒绝（而不是弹窗）。
  • 场景：必须不弹窗的 headless 流程（CI、脚本）。
  • 注意：没用 --allowed-tools 或 permissions.allow 预先放行的操作会被拒，任务可能中途受阻——它适合配合精确的 allow 规则使用。

四、Plan：不是权限模式，而是工作状态

这是最容易被误解的一点：Plan 是一个独立的「工作状态」，可以和任意权限模式共存，而不是第六种权限模式。

  • 行为：进入 Plan 后，Agent 只读地探索代码（读取、搜索、分析），写入受限，产出集中在一份方案上；你可以对方案提意见让它迭代，确认后退出 Plan 才开始实际修改。即「先出计划，你批准后再执行」。
  • 进入/退出：会话内用 /plan 切换；启动时 --permission-mode plan 是兼容旧版的写法，实际转译为「默认权限模式 + 进入 Plan 状态」。
  • 可整体禁用：
{


  "general": { "plan": { "enabled": false } }


}

禁用后 /plan 不可用、--permission-mode plan 回退为 default、Plan 相关工具不再注册。

  • 推荐组合：先 Plan 确认方案，再用 Goal 让其自主执行——「先对齐意图，再放手执行」。

五、如何切换权限模式

途径 方式
启动参数 qodercn --permission-mode <值>，取值：default / plan / auto / bypass_permissions / accept_edits / dont_ask
命名格式 大小写不敏感；支持 snake_case、camelCase（acceptEdits、bypassPermissions、dontAsk）和别名（yolo）
快捷参数 --yolo / --dangerously-skip-permissions = bypass_permissions
会话内快捷键 Shift+Tab 在权限模式间循环切换；Ctrl+Y 直达 YOLO
配置文件 settings.json 中 "general": { "defaultPermissionMode": "accept_edits" }
环境变量 QODERCN_PERMISSION_MODE

注：官方文档没有公布 Shift+Tab 的具体循环顺序；如需确认，在会话里实际按一遍即可。文档中唯一明确的顺序性事实是：disableYoloMode: true 时循环会跳过 YOLO。

六、可信目录：非默认模式生效的前提

一个容易被忽略的硬性前提：

非默认权限模式（accept_edits、auto、YOLO、dont_ask）只在「可信目录」中生效；目录不被信任时，一律强制回退到 default。

可信目录相关机制：

  • 启动时的当前工作目录（CWD）成为主信任目录；
  • 扩展信任范围的方式：
    • qodercn --add-dir ../shared（会话级，可多次）
    • 会话内 /add-dir
    • permissions.additionalDirectories（settings）
    • permissions.trustDirectories（用户级永久信任，不会被项目级覆盖）
  • 在信任目录内：文件读取默认 allow；文件写入在 accept_edits 和 auto 下可自动批准。

配置示例：

{


  "permissions": {


    "trustDirectories": [


      "C:\\Users\\you\\projects\\main-repo"


    ]


  }


}

这就是为什么有时明明设了 --yolo 却仍然弹窗——先看目录是否被信任。

七、脚本与无人值守：ask 去哪儿了

交互模式下 ask 会弹窗，但在无人交互的环境里，ask 必须有归宿：

运行环境 ask 的处理
TUI（交互式） 弹窗，用户选择允许/拒绝
Headless（-p/--print） 自动拒绝（ask 转 deny）
SDK（stdio） 触发 canUseTool 回调，由宿主程序决定
ACP（IDE 集成） 发送 requestPermission RPC，IDE 弹窗或自动决策

官方 headless 示例：

# 编辑自动通过，Bash 命令被拒绝


qodercn -p "refactor the utils module" --permission-mode accept_edits




# 全部放行（仅限可信场景）


qodercn -p "run the migration" --yolo




# 不指定模式，用精确的 allow 规则放行个别工具


qodercn -p "check status" --allowed-tools 'Read,Bash(git status)'

可以看到 dont_ask 与 headless 的默认行为其实是同一哲学：无人可问时，宁可拒绝也不擅自行动。

八、权限决策顺序与 Hook 的「一票否决」

权限模式并非最终裁决者。每次工具调用的决策顺序是固定的：

  1. deny 规则命中 → 立即拒绝；
  2. 工具自身安全检查（危险命令、敏感路径）；
  3. ask 规则命中 → 转确认；
  4. 工具级 allow 规则与当前模式的自动允许；
  5. 仍为 ask → 交给运行环境消费（弹窗/拒绝/回调）。

注意：宽泛的 allow 规则压不过安全检查和 ask 规则。

更重要的是 Hook 的优先级：

  • PreToolUse Hook 返回 deny 时，即使处于 bypass_permissions（YOLO）模式也会阻止执行——这是组织级、不可被任何模式绕过的拦截点；
  • PermissionRequest Hook 可以在弹窗前代替用户做出 allow/deny 决策。

也就是说：权限模式决定「默认问不问」，而 deny 规则和 Hook 决定「无论如何都不能做」。

九、选型建议

一张决策图总结：

需要我逐步把关每个敏感操作？
 └─ 是 → default

只是想让改文件不弹窗，命令仍要确认？
 └─ 是 → accept_edits（日常编码推荐）

无人值守跑任务，接受风险动作被拒？
 └─ 是 → auto（可配 autoMode 引导 + 沙箱加固）

一次性脚本/CI，弹窗必须为零？
 └─ 是 → dont_ask + 精确 --allowed-tools

可信环境做本地实验，完全不想被打断？
 └─ 是 → --yolo（用完即走，别当日常）

大改动想先看方案？
 └─ 任意模式 + /plan

一个务实的渐进路线：平时 accept_edits，长任务 auto，脚本 dont_ask + allow 清单，--yolo 只在隔离环境里偶尔用。

十、总结

  • 权限的本质是 allow / ask / deny 三态，模式只是决定「ask 的边界」。
  • 五种模式从严到松大致为：dont_ask（问即拒）→ default（逐个问）→ accept_edits（编辑免问）→ auto（分类器代问）→ bypass_permissions（不问）。
  • plan 是工作状态而非权限模式，可与任意模式叠加。
  • 非默认模式只在可信目录生效；deny 规则和 PreToolUse Hook 的优先级凌驾于一切模式之上。
  • 无人值守时 ask 默认转为拒绝——这是 Qoder CLI 的安全底色：没人可问的时候，宁可不做。

参考：Qoder CLI 官方文档 —— Permissions、Plan Mode、Settings Reference、CLI Reference、Run in Scripts、Interface、Glossary（docs.qoder.cn）

posted on 2026-09-01 18:56  fox_charon  阅读(5)  评论(0)    收藏  举报

导航