权限

权限模式

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

Plan 模式

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

Goal 模式

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

模式循环切换

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

启动参数

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

qoderclicn --permission-mode default
qoderclicn --permission-mode accept_edits
qoderclicn --permission-mode plan           # 兼容旧版本，实际转译为 default + 进入 Plan 工作状态
qoderclicn --permission-mode auto
qoderclicn --permission-mode bypass_permissions
qoderclicn --permission-mode yolo           # 等价于 bypass_permissions
qoderclicn --permission-mode dont_ask

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

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

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

示例：

# 以下写法等价
qoderclicn --permission-mode bypass_permissions
qoderclicn --permission-mode bypassPermissions
qoderclicn --permission-mode yolo
qoderclicn --yolo
qoderclicn --dangerously-skip-permissions

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

权限如何决策

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

• allow：立即执行工具。

• ask：需要外部确认后才能执行。

• deny：阻止这次工具调用。

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

决策顺序

Qoder CN CLI 按固定顺序评估权限：

1. 先检查 deny 规则——命中即拒绝。

2. 工具自身的安全检查（如危险命令检测、敏感路径检测）。

3. ask 规则——命中则标记为需要确认。

4. 工具级 allow 规则和模式带来的自动允许行为。

5. 如果最终结果仍是 ask，由运行环境决定如何消费。

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

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

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

# Headless + accept_edits：文件编辑自动通过，Bash 被拒绝
qoderclicn -p "refactor the utils module" --permission-mode accept_edits

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

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

权限配置

配置来源（8 层优先级）

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

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

各来源的配置方式：

• 层级 1-3（settings 文件）：在对应路径的 JSON 文件中写入 permissions.allow / permissions.deny / permissions.ask 数组。settings.local.json 适合存放本机个人审批规则，建议加入 .gitignore。

• 层级 4（flagSettings）：qoderclicn --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：

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

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

{
  "security": {
    "disableYoloMode": true
  }
}

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

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

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

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

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

{
  "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"
    ]
  }
}

这些规则是软引导——注入到分类器 prompt 作为参考，最终决策仍由 AI 分类器做出。出于安全考虑，autoMode 配置只从可信来源（用户全局 settings 和 localSettings）读取，项目 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:*)"
    ]
  }
}

规则语法

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

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

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

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

命令行覆盖

qoderclicn --allowed-tools 'Read,Grep,Bash(git status)'
qoderclicn --disallowed-tools 'Bash(rm -rf:*),mcp__github__delete_repo'
qoderclicn --tools 'Read,Grep,Edit'

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

信任目录

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

• 文件读取默认 allow

• 文件写入在 accept_edits 和 auto 模式下可自动批准

• 非默认权限模式（auto、bypass 等）才能生效

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

扩展信任范围

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

qoderclicn --add-dir ../shared

{
  "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 风格匹配。

示例：

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

Bash 规则

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

示例：

{
  "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。

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

MCP 工具使用完整限定名：

mcp__<server>__<tool>

支持的 MCP 模式包括：

示例：

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

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

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

Hook 与权限

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

影响权限的 Hook 事件

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

PreToolUse Hook

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

{
  "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 结果：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Command blocked by security policy"
  }
}

permissionDecision 可选值：

• "allow"：跳过权限管道，直接批准

• "deny"：跳过权限管道，直接拒绝

• "ask"：继续走正常权限管道（默认行为）

PermissionRequest Hook

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

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

输出格式：

{
  "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/回调）