> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 权限

> 了解 Qoder CLI 的权限模式、规则配置和工具调用审批流程。

## 权限模式

权限模式决定了 Qoder 如何处理工具调用——每种模式在"自动化程度"和"安全宽松度"两个维度上定位不同。

| 模式 | 适用场景 | 行为 |
| :- | :- | :- |
| `default` | 常规交互式使用 | 安全读取和内部动作可自动执行；敏感操作请求确认。 |
| `accept_edits` | 日常编码任务 | 自动批准工作目录内的安全文件编辑。Shell 命令、外部动作和敏感路径仍走正常检查。 |
| `auto` | 自动化运行、Goal 执行 | 零弹窗。安全读取和工作区内编辑自动批准；风险动作被拒绝或交给 AI 分类器判断。 |
| `bypass_permissions` (YOLO) | 仅用于可信本地实验 | 跳过所有批准提示。所有工具调用自动放行。 |
| `dont_ask` | 必须不弹窗的 headless 流程 | 从不询问。任何原本需要询问的动作都会被拒绝。 |

### Plan 模式

Plan 是独立的**工作状态**（非权限策略），可与上述任意权限模式共存。通过 `/plan` 命令进入/退出（toggle）。进入后 Qoder 只读探索代码并输出方案，写入受限于计划文件。退出时可选择后续权限模式或直接进入 Goal 执行。

### Goal 模式

Goal 是自主执行状态。通过 `/goal set <目标>` 进入——自动切换到 `auto` 模式并锁定 Shift+Tab 切换，确保执行过程零打扰。Goal 可与 Plan 共存（先规划再执行）。使用 `/goal clear` 或 `/goal pause` 退出。

### 模式循环切换

在交互式会话中，按 **Shift+Tab** 在所有权限模式间循环切换。按 **Ctrl+Y** 可直达 YOLO 模式。

### 启动参数

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

```shell theme={null}
qodercli --permission-mode default
qodercli --permission-mode accept_edits
qodercli --permission-mode plan           # 兼容旧版本，实际转译为 default + 进入 Plan 工作状态
qodercli --permission-mode auto
qodercli --permission-mode bypass_permissions
qodercli --permission-mode yolo           # 等价于 bypass_permissions
qodercli --permission-mode dont_ask

# 快捷方式
qodercli --yolo                         # 等价于 --permission-mode bypass_permissions
qodercli --dangerously-skip-permissions # 同上
```

在交互式会话中，还可以通过 **Ctrl+Y** 快速切换到 YOLO 模式。

支持多种命名格式（大小写不敏感）：

| 标准值 (snake\_case) | camelCase | 别名 |
| :- | :- | :- |
| `accept_edits` | `acceptEdits` | — |
| `bypass_permissions` | `bypassPermissions` | `yolo`, `YOLO` |
| `dont_ask` | `dontAsk` | — |

示例：

```shell theme={null}
# 以下写法等价
qodercli --permission-mode bypass_permissions
qodercli --permission-mode bypassPermissions
qodercli --permission-mode yolo
qodercli --yolo
qodercli --dangerously-skip-permissions
```

非默认模式只会在可信目录中生效。如果当前目录未被信任，Qoder 会回退到 `default`。

## 权限如何决策

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

* **`allow`**：立即执行工具。
* **`ask`**：需要外部确认后才能执行。
* **`deny`**：阻止这次工具调用。

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

### 决策顺序

Qoder 按固定顺序评估权限：

1. 先检查 `deny` 规则——命中即拒绝。
2. 工具自身的安全检查（如危险命令检测、敏感路径检测）。
3. `ask` 规则——命中则标记为需要确认。
4. 工具级 `allow` 规则和模式带来的自动允许行为。
5. 如果最终结果仍是 `ask`，由运行环境决定如何消费。

宽泛 allow 规则并不等于所有动作都会静默执行——安全检查和 ask 规则优先级更高。

### 不同运行环境下 `ask` 的消费方式

| 运行环境 | `ask` 的归宿 | 说明 |
| :- | :- | :- |
| **TUI**（交互式终端） | 弹窗确认 | 用户在终端中选择允许/拒绝。 |
| **Headless**（`-p`/`--prompt`） | 自动拒绝 | 无人交互，`ask` 转为 `deny`。 |
| **SDK**（stdio 协议） | 发送 `canUseTool` 回调给宿主 | 宿主程序决定 allow/deny。 |
| **ACP**（IDE 集成） | 发送 `requestPermission` RPC 给 IDE | IDE 弹窗或自动决策。 |

Headless 模式（`-p`/`--prompt`）下，可以搭配权限模式使用：

```shell theme={null}
# Headless + accept_edits：文件编辑自动通过，Bash 被拒绝
qodercli -p "refactor the utils module" --permission-mode accept_edits

# Headless + bypass_permissions：全部放行（仅限可信场景）
qodercli -p "run the migration" --yolo

# Headless + 精确 allow 规则：只放行特定工具
qodercli -p "check status" --allowed-tools 'Read,Bash(git status)'
```

## 权限配置

### 配置来源（8 层优先级）

规则从多个来源合并，按优先级从低到高：

| 层级 | 来源 | 说明 |
| :- | :- | :- |
| 1 | `userSettings` | `~/.qoder/settings.json`（用户全局） |
| 2 | `projectSettings` | `<project>/.qoder/settings.json`（项目级，团队共享） |
| 3 | `localSettings` | `<project>/.qoder/settings.local.json`（本机个人，加入 `.gitignore`） |
| 4 | `flagSettings` | `--settings <path>` CLI 参数指定的文件 |
| 5 | `cliArg` | `--allowed-tools` / `--disallowed-tools` 命令行参数 |
| 6 | `command` | `/allow`、`/deny` 会话中命令 |
| 7 | `session` | 运行时临时规则（弹窗中“本次会话允许”） |

高优先级来源的规则覆盖低优先级。如果组织策略开启了 `allowManagedPermissionRulesOnly`，则只使用策略托管的规则。

**各来源的配置方式：**

* **层级 1-3（settings 文件）**：在对应路径的 JSON 文件中写入 `permissions.allow` / `permissions.deny` / `permissions.ask` 数组。`settings.local.json` 适合存放本机个人审批规则，建议加入 `.gitignore`。
* **层级 4（flagSettings）**：`qodercli --settings ./custom-settings.json`，指定额外的 settings 文件路径。该文件格式与标准 settings.json 相同。
* **层级 5（cliArg）**：通过 `--permission-mode`、`--allowed-tools`、`--disallowed-tools`、`--tools` 等命令行参数配置，仅作用于当前会话。
* **层级 6（command）**：会话中输入 `/allow Bash(npm test)` 或 `/deny WebFetch`，持久化到 `settings.local.json`。
* **层级 7（session）**：弹窗中选择“本次会话允许”产生的临时规则，进程退出后失效。

### 模式配置

**设置默认模式**——在 settings 中配置 `general.defaultPermissionMode`：

```json theme={null}
{
  "general": {
    "defaultPermissionMode": "accept_edits"
  }
}
```

支持的值：

| 值 | 行为 | 别名 |
| - | - | - |
| `default` | 每次操作都提示确认 | — |
| `accept_edits` | 自动批准文件编辑，Shell 命令仍需确认 | `acceptEdits` |
| `plan` | 只读模式（兼容旧版，实际转为 default + Plan 工作状态） | — |
| `auto` | AI 分类器评估操作安全性 | — |
| `bypass_permissions` | 跳过所有权限检查（YOLO） | `yolo`、`bypassPermissions` |
| `dont_ask` | 非交互模式，需要确认的操作直接拒绝 | `dontAsk` |

大小写不敏感，所有别名均可使用。

**禁用 YOLO 模式**——组织管理员可通过以下配置阻止用户进入 bypass\_permissions 模式：

```json theme={null}
{
  "security": {
    "disableYoloMode": true
  }
}
```

设置后，`--yolo`、`--permission-mode bypass_permissions` 和 Ctrl+Y 均不可用，Shift+Tab 循环也会跳过该模式。子 agent 声明 bypass 时也会被降级为 acceptEdits。

**禁用 Plan 模式**——如果不需要 Plan 工作流，可以关闭：

```json theme={null}
{
  "general": {
    "plan": {
      "enabled": false
    }
  }
}
```

设置后，`/plan` 命令不可用，`--permission-mode plan` 回退为 default，EnterPlanMode/ExitPlanMode 工具不注册。

**Auto 模式分类器配置**——可以通过自然语言规则引导 AI 分类器的判断倾向：

```json theme={null}
{
  "autoMode": {
    "allow": [
      "running npm/yarn/pnpm scripts defined in package.json",
      "creating or editing test files"
    ],
    "soft_deny": [
      "deleting files outside the test directory",
      "modifying CI/CD configuration"
    ],
    "environment": [
      "This is a Node.js monorepo with pnpm workspaces",
      "The project uses Vitest for testing"
    ]
  }
}
```

| 字段 | 作用 |
| :- | :- |
| `allow` | 分类器倾向于自动批准的操作描述 |
| `soft_deny` | 分类器倾向于拒绝的操作描述 |
| `environment` | 提供给分类器的环境上下文信息 |

这些规则是**软引导**——注入到分类器 prompt 作为参考，最终决策仍由 AI 分类器做出。出于安全考虑，`autoMode` 配置只从可信来源（用户全局 settings 和 localSettings）读取，项目 settings 被排除以防止恶意权限提升。

### 权限规则配置

规则按 `allow`、`ask` 和 `deny` 分组：

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

### 规则语法

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

使用规范工具名：`Read`、`Edit`、`Write`、`Bash`、`Grep`、`Glob`、`WebFetch`、`WebSearch`、`Agent`，以及 `mcp__github__create_issue` 这类 MCP 工具名。

如果内容中包含括号，需要转义：

```json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(python -c \"print\\(1\\)\")"
    ]
  }
}
```

`ToolName(*)` 等同于 `ToolName`（工具级规则）。

### 命令行覆盖

```shell theme={null}
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` 限制本次运行可用的内置工具集（未列出的工具会被拒绝）。

## 信任目录

Qoder 将启动时的当前工作目录（CWD）视为**主信任目录**。在信任目录内：

* 文件读取默认 allow
* 文件写入在 `accept_edits` 和 `auto` 模式下可自动批准
* 非默认权限模式（auto、bypass 等）才能生效

如果当前目录不被信任，Qoder 会强制回退到 `default` 模式。

### 扩展信任范围

通过 `--add-dir`、`/add-dir` 命令或 `permissions.additionalDirectories` 增加额外可信工作目录：

```shell theme={null}
qodercli --add-dir ../shared
```

```json theme={null}
{
  "permissions": {
    "additionalDirectories": ["../shared"]
  }
}
```

也可以在全局 settings 中配置 `permissions.trustDirectories` 将常用目录永久信任。

### 受保护路径

部分路径受到保护，因为编辑它们可能改变执行行为、凭据或工具行为。例如 `.git`、`.vscode`、`.idea`、`.husky`、大多数 `.qoder` 配置文件、`.bashrc`/`.zshrc` 等 shell 启动文件、Git 配置、`.mcp.json`、`.ripgreprc`。在常规交互式模式下，这些路径需要明确批准；在 `auto` 模式下会被拒绝。

## 文件访问规则

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

文件规则使用 gitignore 风格匹配。

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

示例：

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

## 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`。 |

示例：

```json theme={null}
{
  "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(*)` 这类宽泛规则。

## Web 和 MCP 规则

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

```json theme={null}
{
  "permissions": {
    "ask": [
      "WebFetch"
    ],
    "deny": [
      "WebSearch"
    ]
  }
}
```

MCP 工具使用完整限定名：

```text theme={null}
mcp__<server>__<tool>
```

支持的 MCP 模式包括：

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

示例：

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__context7__*"
    ],
    "ask": [
      "mcp__github__create_issue"
    ]
  }
}
```

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

```shell theme={null}
qodercli --allowed-mcp-server-names context7,github
```

## Hook 与权限

Qoder 的 Hook 系统在权限决策链路中有两个注入点，可以通过自定义脚本影响工具的允许/拒绝行为。

### 影响权限的 Hook 事件

| Hook 事件 | 触发时机 | 可产生的权限影响 | | |
| :- | :- | :- | - | - |
| `PreToolUse` | 工具执行前（权限检查阶段） | 可返回 \`permissionDecision: "allow" | "deny" | "ask"\` 直接覆盖权限管道结果 |
| `PermissionRequest` | 权限管道产出 `ask` 后、弹窗前 | 可返回 `decision.behavior` 为 `allow` 或 `deny`，代替用户交互 | | |

其他 Hook 事件（`PostToolUse`、`SessionStart`、`Stop` 等）不参与权限决策。

### PreToolUse Hook

在工具执行前触发。Hook 脚本可以检查工具名和参数，返回权限决策：

```json theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python ./scripts/check-bash-command.py"
          }
        ]
      }
    ]
  }
}
```

Hook 脚本通过 stdin 接收 JSON 输入（含 `tool_name`、`tool_input`、`session_id` 等），通过 stdout 输出 JSON 结果：

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Command blocked by security policy"
  }
}
```

`permissionDecision` 可选值：

* `"allow"`：跳过权限管道，直接批准
* `"deny"`：跳过权限管道，直接拒绝
* `"ask"`：继续走正常权限管道（默认行为）

### PermissionRequest Hook

在权限管道产出 `ask` 之后、弹窗/回调之前触发。适合用于自动化审批系统或外部通知（如 Slack/邮件提醒）：

```json theme={null}
{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ./scripts/auto-approve-safe-ops.js"
          }
        ]
      }
    ]
  }
}
```

输出格式：

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {},
      "updatedPermissions": []
    }
  }
}
```

### Hook 与权限模式的优先级

Hook 的权限决策优先级**高于**权限模式——即使在 `bypass_permissions` 模式下，PreToolUse Hook 返回 `deny` 仍然会阻止执行。这为组织级安全策略提供了不可绕过的拦截能力。

执行顺序：

1. Hook `PreToolUse` → 如果返回 allow/deny，短路
2. 权限管道（规则 + 模式 + 安全检查）
3. 如果结果是 `ask` → Hook `PermissionRequest` → 如果返回 allow/deny，短路
4. 最终由运行环境消费 `ask`（弹窗/deny/回调）