工具权限策略

Mogick CLI 在 Agent 模式下通过工具网关对所有工具调用施加权限控制。运行时如何使用 /permissions 切换策略、审批卡片操作和执行流程见工具审批与权限策略。本页覆盖策略的详细定义和 config.json 中的逐工具配置。

四级权限

权限策略控制工具调用的确认策略，从严格只读到完全信任逐级放开。

策略	只读工具	文件写入	Shell	Git 修改	MCP	审批
`read`	放行	按工具配置	按工具配置	按工具配置	只读提示可放行	安全内置状态工具也可放行
`workspace`	放行	工作区内非删除写入放行	按工具配置	按工具配置	按工具配置	工作区外或删除类操作确认
`auto`	放行	工作区内非删除写入放行	依后备门禁	依后备门禁	依后备门禁	其余调用看 `_mogick_ask_permission`
`yolo`	放行	放行	放行	放行	放行	显式 `deny` 仍拒绝

read 放行只读工具，以及只修改 Mogick 内部会话状态的安全工具（例如 todo、plan、提问类工具）。它不是"所有非读取工具一律拒绝"的简单白名单，其他调用仍结合工具自身的 allow/ask/deny 配置处理。

workspace 自动放行工作区内非删除的 file.write / file.edit。工作区外写入、Shell、未知工具以及删除类操作仍需确认。工作区默认取当前 cwd 所在 Git 仓库根；不在 Git 仓库时取当前 cwd。

auto 是默认策略，继承只读、安全内置和工作区非删除写入的放行规则。其余调用以 _mogick_ask_permission 作为后备门禁。

yolo 自动放行本来需要确认的调用，TUI 状态栏显示红色徽章；配置中显式 deny 的工具仍然拒绝。

在非 yolo 策略下，file.delete、包含删除补丁的 file.edit，以及匹配删除命令的 shell.exec 始终请求确认。

选择策略时建议遵循最小权限原则：先用 read 或 workspace 完成任务中不需要特权操作的部分，必要时再临时切换到更高权限。

配置方式

权限控制分两层：--tool-call-permissions 和 TUI /permissions 控制当前会话的四级运行时策略（使用方式见工具审批与权限策略）；config.json 的 agents 控制各模式中单个工具的注册和默认执行级别。两者共同参与最终决策。

config.json

使用 agents.<mode>.tools.<tool> 对单个工具做细粒度控制：

json

{
  "agents": {
    "agent": {
      "tools": {
        "shell.exec": {
          "enabled": true,
          "permission": "ask"
        }
      }
    }
  }
}

字段	类型	取值	说明
`agents.<type>.tools.<tool>.enabled`	bool	`true` / `false`	是否注册该语义工具；省略时继承 preset
`agents.<type>.tools.<tool>.permission`	string	`allow` / `ask` / `deny`	执行权限；省略时继承 preset

agents 按层解析：项目配置中的同名 Agent、同名工具整体覆盖全局工具项；项目未声明的工具继续使用全局项，再回退到模式 preset。删除类硬门禁和 CLI 会话权限策略仍会参与最终决策。

Plan 模式

Plan 模式独立于权限策略运作。无论外层策略设为 auto 还是 yolo，该模式都不允许文件写入、Shell、MCP 或其他网络操作。进入 Agent 模式后，权限策略恢复为当前配置级别。

子代理权限边界

子代理的有效权限不会宽于父会话策略。运行时把父会话当前可调用工具、子代理描述符中的 allowedTools / deniedTools / readOnly 约束，以及工具网关权限检查合并成最终可执行工具集。内置子代理以只读探索和只读审查为主，不能写文件、执行 Shell 或递归创建子代理。

read、workspace、auto、yolo 是父会话的工具调用策略，不是子代理描述符里的四级配置。即使父会话处于 yolo，子代理仍会受到自身只读描述符和网关策略约束。每个子代理拥有独立的步骤数和工具调用次数预算，超出上限后自动终止。

工具权限策略 ​

四级权限 ​

配置方式 ​

config.json ​

Plan 模式 ​

子代理权限边界 ​

相关文档 ​