---
title: "权限系统"
description: "从完全自动到逐条审批——四种权限模式保护你的代码和系统安全。"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 权限系统

## 为什么需要权限控制

Peri 可以读写文件、执行 shell 命令、访问网络。权限系统让你控制 Peri 在什么情况下可以自主操作、什么时候必须等你确认。

权限系统由两部分组成：全局的**权限模式**决定审批的默认行为，**工具敏感度判定**（按工具名）决定哪些工具属于敏感操作、需要审批。

> **当前启动默认值**
>
> 无参数运行 <code>peri</code> 时，当前实现默认使用 <strong>Bypass</strong>。使用 <code>peri --permission-mode default</code> 才会以 Default 启动。权限模式只控制 Peri 内部是否询问，不是操作系统沙箱。

## 四种权限模式

| 模式 | CLI 值 | 行为 | 适用场景 |
|------|--------|------|---------|
| **Default** | `default` | 敏感工具逐个审批 | 新项目、敏感代码、需要精细掌控时 |
| **AcceptEdit** | `accept-edit` | 编辑类工具自动通过，其他敏感工具仍需审批 | 日常编码、快速迭代 |
| **AutoMode** | `auto-mode` | LLM 自动判断是否放行，不确定时回退到人工审批 | 长任务、减少打断 |
| **Bypass** | `bypass` | 跳过所有审批，全自动执行 | 已由外部机制隔离的临时环境 |

## 切换模式

启动时通过 CLI 参数指定：

```bash
peri --permission-mode default
# 或
peri --permission-mode accept-edit
# 或
peri --permission-mode auto-mode
# 或
peri --permission-mode bypass
```

运行中按 `Shift+Tab` 在 Default -> AcceptEdit -> AutoMode -> Bypass 之间循环切换。状态栏会显示当前模式。

> **Note**
>
> 便捷参数 `--dangerously-skip-permissions` 等价于 `--permission-mode bypass`（仅限沙箱环境）。

## HITL 审批

在需要审批的模式下，Peri 执行高危操作前会弹出审批窗口（HITL，Human-in-the-Loop）。审批在工具真正执行之前完成——如果被拒绝，Peri 会生成一个错误结果记录并继续，而不是跳过该工具。

审批窗口显示：
- 即将执行的操作（工具名、参数）
- 多个工具调用会合并为一次批量审批，不需要逐个确认

你可以按 `Enter` 批准本次调用，或按 `Esc` 拒绝。审批结果不会持久化为规则，每次调用都会重新询问。

## 哪些工具需要审批

Peri 按工具名判定是否敏感，与具体参数无关。默认需要审批的工具包括：

- **Bash**（shell 执行）
- **Write / Edit / folder_operations**（文件与目录操作）
- **Agent**（子代理委派）
- **WebFetch / WebSearch**（网络访问）
- **mcp__\***（所有 MCP 工具）
- **cron_register**（定时任务注册）
- 以 `delete_` / `rm_` 开头的删除类工具

其余工具（Read、Glob、Grep、AskUserQuestion、TodoWrite 等）默认直接放行。

不同权限模式下这些工具的审批行为：

- **Default**：敏感工具执行前都会弹窗审批。
- **AcceptEdit**：编辑类工具（Write、Edit、folder_operations）自动通过，其他敏感工具仍需审批。
- **AutoMode**：LLM 分类器根据工具名和参数判断放行（Allow）或拒绝（Deny），拿不准时（Unsure）回退到人工审批。
- **Bypass**：跳过所有审批。

> **Caution**
>
> **Bypass 模式会跳过 Peri 的工具审批**，包括删除类、网络类工具的审批。仅在有独立账号、容器或其他外部隔离的临时环境中使用；“运行在 CI”本身不代表环境安全。

## 权限模式选择指南

| 你的情况 | 推荐模式 |
|---------|---------|
| 第一次用 Peri，不熟悉它能做什么 | Default |
| 日常写代码，信任 Peri 的文件编辑 | AcceptEdit |
| 跑一个需要多轮的长任务，不想频繁打断 | AutoMode |
| 在独立账号或容器中，文件、网络和凭据都已由外层限制 | Bypass |

Source: https://konghayao.github.io/peri-cool/docs/features/permissions/index.mdx