权限系统

为什么需要权限控制

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

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

四种权限模式

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

切换模式

启动时通过 CLI 参数指定：

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

还有两个便捷参数：--approve 等价于 --permission-mode default；--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 模式会跳过所有权限检查，包括删除类、网络类工具的审批。仅在完全受控的环境中使用——比如 CI/CD pipeline 或 Docker 容器。

权限模式选择指南

你的情况	推荐模式
第一次用 Peri，不熟悉它能做什么	Default
日常写代码，信任 Peri 的文件编辑	AcceptEdit
跑一个需要多轮的长任务，不想频繁打断	AutoMode
在 CI 或 Docker 里跑，环境完全隔离	Bypass