权限 - Qoder

Qoder CLI 会在每次工具调用前做权限检查。权限结果只有三种：

allow：立即执行工具。
ask：在交互式会话中弹出确认。
deny：阻止这次工具调用。

权限适用于文件读取和编辑、Bash 命令、Web 抓取、MCP 工具、Subagent 以及其他内置工具。

权限模式

使用 --permission-mode 选择当前会话的默认行为。

qodercli --permission-mode default
qodercli --permission-mode accept_edits
qodercli --permission-mode plan
qodercli --permission-mode auto

模式	适用场景	行为
`default`	常规交互式使用	安全读取和内部动作可自动执行；敏感操作会请求确认。
`accept_edits`	日常编码任务	自动批准工作目录内的安全文件编辑。Shell 命令、外部动作和敏感路径仍会走正常检查。
`plan`	评审、排查和规划	保持偏规划的行为。Qoder 可以读取并分析项目；写入仍需要批准，除非是计划文件或显式规则允许。
`auto`	不希望弹出确认的自动化运行	不弹出确认，只返回允许或拒绝。安全读取工具和安全工作区编辑可自动批准；风险动作会被拒绝或在可用时交给分类器判断。
`bypass_permissions`	仅用于可信本地实验	跳过大多数批准提示。部分安全检查、危险 Shell 命令和需要用户交互的动作仍可能询问或拒绝。
`dont_ask`	必须不弹窗的 headless 流程	从不询问。任何原本需要询问的动作都会被拒绝。

也可以使用兼容的 camelCase 值，例如 acceptEdits、bypassPermissions 和 dontAsk。非默认模式只会在可信目录中生效。如果当前目录未被信任，Qoder 会回退到 default。bypass_permissions 也可能被安全设置禁用。

设置默认模式

如需持久默认值，在 settings 中配置 general.defaultPermissionMode。

{
  "general": {
    "defaultPermissionMode": "accept_edits"
  }
}

settings 中建议使用 default、accept_edits、plan 或 auto。如果确实需要在可信会话中使用 bypass 模式，请通过 --permission-mode bypass_permissions 启动。

Bypass 模式

--dangerously-skip-permissions 等价于 --permission-mode bypass_permissions。

qodercli --dangerously-skip-permissions

只在你信任当前工作区和任务时使用该模式。它不是对所有操作的无条件放行。

权限如何决策

Qoder 按固定顺序评估权限：

先检查 deny 规则。
在 auto 模式下，Qoder 必须直接得到 allow 或 deny，不会弹出审批提示。
ask 规则和工具自身的权限检查会先于宽泛 allow 规则执行。
安全检查仍可能中断宽泛规则或 bypass 模式。
再应用工具级 allow 规则和模式带来的自动允许行为。
如果在非交互式会话中结果仍是 ask，会转为 deny。

这意味着宽泛 allow 规则并不等于所有动作都会静默执行。例如危险 Shell 命令仍可能要求确认，可疑路径仍可能被阻止。

配置规则

持久规则写在 settings 文件中：

~/.qoder/settings.json
${project}/.qoder/settings.json
${project}/.qoder/settings.local.json

settings.local.json 用于本机个人审批，通常加入 .gitignore。团队共享规则通常放在项目 settings 中。规则按 allow、ask 和 deny 分组。

{
  "permissions": {
    "allow": [
      "Read(/src/**)",
      "Edit(/src/**)",
      "Bash(npm run test:*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "WebFetch"
    ],
    "deny": [
      "Read(*.pem)",
      "Bash(rm -rf:*)"
    ]
  }
}

如果组织策略开启了只允许 managed permission rules，则只会使用策略托管的规则。

规则语法

规则有以下形式：

形式	含义
`ToolName`	作用于整个工具。
`ToolName(content)`	作用于某个路径、命令、agent 类型，或工具支持的其他特定内容。
`*`	工具级匹配所有工具。

使用规范工具名，例如 Read、Edit、Write、Bash、Grep、Glob、WebFetch、WebSearch、Agent，以及 mcp__github__create_issue 这类 MCP 工具名。如果内容中包含括号，需要转义：

{
  "permissions": {
    "allow": [
      "Bash(python -c \"print\\(1\\)\")"
    ]
  }
}

ToolName(*) 会被视为工具级规则，等同于 ToolName。

文件访问规则

Qoder 将当前 workspace 视为主要工作目录。你可以通过 --add-dir、/add-dir 命令或 permissions.additionalDirectories 增加额外可信工作目录。

qodercli --add-dir ../shared

{
  "permissions": {
    "additionalDirectories": ["../shared"]
  }
}

带路径范围的读取规则使用 Read(...)。带路径范围的写入规则使用 Edit(...)；它覆盖 Edit、Write 和 NotebookEdit 的文件写入检查。某个路径上的 Edit(...) allow 规则也会隐含允许读取同一路径。文件规则使用 gitignore 风格匹配。

模式	含义
`/src/**`	基于规则来源根目录的路径。在 project/local settings 中相对于项目根目录；在 user settings 中相对于 home 目录。
`~/Documents/**`	基于 home 目录的路径。
`//tmp/data/**`	从系统 `/` 开始的绝对路径。绝对路径需要使用双斜杠。
`*.secret`	不带根目录的文件名模式，可在任意位置匹配。

示例：

{
  "permissions": {
    "allow": [
      "Read(/src/**)",
      "Edit(/src/**)",
      "Read(~/Documents/specs/**)"
    ],
    "ask": [
      "Edit(/package.json)",
      "Read(~/Downloads/**)"
    ],
    "deny": [
      "Read(*.pem)",
      "Edit(/.git/**)",
      "Edit(//etc/**)"
    ]
  }
}

工作目录内的读取默认允许，除非命中 deny 或 ask 规则。工作目录内的写入在 accept_edits 和 auto 模式下可自动批准，前提是路径安全。部分路径受到保护，因为编辑它们可能改变执行行为、凭据或工具行为。例如 .git、.vscode、.idea、.husky、大多数 .qoder 配置文件、.bashrc 和 .zshrc 等 shell 启动文件、Git 配置、.mcp.json、.ripgreprc。在常规交互式模式下，这些路径需要明确批准；在 auto 模式下会被拒绝，而不是弹出确认。

Bash 规则

Bash(...) 规则可以匹配精确命令、命令前缀或通配模式。

规则	匹配内容
`Bash(npm run build)`	精确匹配 `npm run build`。
`Bash(npm run test:*)`	匹配 `npm run test` 以及以 `npm run test` 开头的命令。
`Bash(git log *)`	使用 glob 风格通配匹配。
`Bash(git status)`	精确匹配 `git status`。

示例：

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log:*)",
      "Bash(npm run test:*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

Shell 匹配是保守的：

deny 和 ask 规则会穿透常见 wrapper 和环境变量前缀，因此 Bash(rm -rf:*) 仍能拦截被包装过的破坏性命令。
前缀和通配 allow 规则不会静默批准复合命令，除非每个顶层命令片段都能独立被允许。
部分可证明只读的 shell 命令，在 deny、ask 和路径检查之后可以被自动允许。
危险命令，例如破坏性删除或 force push，即使存在宽泛 allow 规则，也可能强制确认。在 auto 模式下，危险 Shell 命令会被拒绝。

除非你完全信任当前会话，否则避免使用 Bash 或 Bash(*) 这类宽泛规则。它们等同于在剩余安全检查之外，对整个 Shell 工具进行批准。

Web 和 MCP 规则

Web 工具可以用工具级规则控制。若所有 web fetch 都需要确认，用 ask；若某个会话或项目应禁用网络访问，用 deny。

{
  "permissions": {
    "ask": [
      "WebFetch"
    ],
    "deny": [
      "WebSearch"
    ]
  }
}

MCP 工具使用完整限定名：

mcp__<server>__<tool>

支持的 MCP 模式包括：

规则	含义
`mcp__github__create_issue`	单个 MCP 工具。
`mcp__github__*`	`github` MCP server 下的所有工具。
`mcp__github`	`github` MCP server 下的所有工具。
`mcp__*`	所有 MCP 工具。

示例：

{
  "permissions": {
    "allow": [
      "mcp__context7__*"
    ],
    "ask": [
      "mcp__github__create_issue"
    ]
  }
}

MCP server 配置也可以通过 alwaysAllow 为该 server 的工具设置自动允许。如果一次运行只想启用指定 MCP server，可以使用 --allowed-mcp-server-names。

qodercli --allowed-mcp-server-names context7,github

命令行覆盖

使用命令行参数配置一次性会话：

qodercli --permission-mode accept_edits
qodercli --allowed-tools 'Read,Grep,Bash(git status)'
qodercli --disallowed-tools 'Bash(rm -rf:*),mcp__github__delete_repo'
qodercli --tools 'Read,Grep,Edit'

--allowed-tools 和 --disallowed-tools 使用与 settings 相同的规则语法。--tools 用于限制本次运行可用的内置工具；未列出的内置工具会被拒绝。

非交互式会话

在 print mode、--prompt 和其他 headless 会话中，Qoder 无法显示审批提示。任何原本会返回 ask 的动作都会被拒绝，除非你选择了能允许该动作的模式或规则集。用于自动化时：

优先为所需工具、路径、命令和 MCP server 配置精确的 allow 规则。
如果自动化需要编辑可信工作目录内的文件，使用 accept_edits。
如果希望严格 fail-closed，使用 dont_ask。
只有在可信环境中确实需要宽泛工具执行时，才使用 bypass_permissions。

快速入门

用户指南

SDK

Cloud Agents

权限

权限模式

设置默认模式

Bypass 模式

权限如何决策

配置规则

规则语法

文件访问规则

Bash 规则

Web 和 MCP 规则

命令行覆盖

非交互式会话

快速入门

用户指南

SDK

Cloud Agents

Documentation Index

​权限模式

​设置默认模式

​Bypass 模式

​权限如何决策

​配置规则

​规则语法

​文件访问规则

​Bash 规则

​Web 和 MCP 规则

​命令行覆盖

​非交互式会话

权限模式

设置默认模式

Bypass 模式

权限如何决策

配置规则

规则语法

文件访问规则

Bash 规则

Web 和 MCP 规则

命令行覆盖

非交互式会话