跳转到内容

权限与安全边界

Pi 的设计目标是直接操作本地代码库。理解它的权限模型,比记住任何快捷键都重要。

核心事实

Pi 没有内置操作系统沙箱。它继承启动进程的用户权限:

你的用户账号
│ 相同的文件、进程、网络与凭据权限
▼
Pi 进程
├── 内置工具:read / write / edit / bash / ...
├── MCP 服务:本地子进程或远程服务
└── 扩展与 Pi 包:普通 TypeScript/JavaScript 代码

因此,Pi 能做的事情通常和你在同一个终端中能做的事情相同。

项目信任不是沙箱

机制它控制什么它不控制什么
项目信任是否加载 .pi 设置、项目 MCP、扩展、技能、模板、主题和项目包模型调用工具后能读写哪些系统文件
工具 allowlist当前会话向模型暴露哪些 Pi 工具扩展代码或 shell 子进程的系统权限
容器、VM、微型 VM操作系统可见的文件、网络、进程和凭据业务逻辑是否正确

信任提示解决的是“这个仓库能否改变 Pi 的启动配置”,不是“Pi 能否修改这个仓库”。记成:信任管加载,不管权限。

AGENTS.override.md、AGENTS.md 和 CLAUDE.md 默认会作为上下文加载,即使项目没有被信任。Pi 还会在信任决策之前读取项目的 sessionDir 设置以确定会话位置。不要把不可信仓库中的指令文件当成安全内容。

推荐的本地工作方式

1. 从干净工作树开始

终端窗口
git status --short
git switch -c task/my-change

已有未提交修改时,先理解它们属于谁、是否可以被覆盖。

2. 第一个请求保持只读

先不要修改文件或执行安装命令。概览项目结构、检查命令和潜在风险。

这既验证环境,也让你看到 Pi 对项目的理解是否正确。

3. 明确允许范围

一个好的修改请求应包含:

  • 可以修改哪些文件或目录
  • 什么结果算完成
  • 必须运行哪些验证
  • 哪些动作明确禁止

例如:

只修改 docs/ 下的 Markdown,修复相对链接。
不要安装依赖或更改配置。完成后运行文档构建并汇报结果。

4. 独立检查结果

终端窗口
git status --short
git diff --check
git diff --cached --check
git diff
git diff --cached

状态为 ?? 的未跟踪文件要单独检查。再运行项目自己的测试、类型检查和构建。模型说“已完成”不是验证证据。

只选工具时别漏掉 MCP

Pi 1.5 中,--tools read,grep,find,ls 不会自动排除 MCP 工具。若本次不需要内置 MCP,可以使用:

终端窗口
pi --no-mcp --tools read,grep,find,ls

--no-mcp 不会禁用替代内置 MCP 的第三方扩展;--no-extensions 禁用自动发现和内置扩展,但显式 -e 仍可加载。全局扩展可能在启动时执行代码,工具过滤也不能限制它们。检查具体配置,并在高风险任务中使用真正的隔离环境。详见 MCP 工具范围。

什么时候必须使用隔离环境

下面任一情况成立时,优先使用容器、虚拟机、微型 VM 或策略沙箱:

  • 仓库来源不可信。
  • 任务需要运行未知安装脚本或二进制文件。
  • Pi 会无人值守运行较长时间。
  • 工作目录之外存在高价值凭据或私人文件。
  • 任务不需要公网,但宿主机默认可以访问公网。

隔离时遵循最小权限:

  • 只挂载任务所需目录。
  • 不要默认挂载 ~/.pi/agent。
  • 只传入必要、最好是短期的凭据。
  • 不需要网络时关闭网络。
  • 需要保护宿主文件时使用只读挂载或复制进出。

具体模式见 Pi Containerization。

凭据

Pi 可以从 /login 保存的认证、环境变量和 auth.json 读取凭据。建议:

  • 不在提示词中粘贴真实密钥。
  • 不把密钥写进版本控制。
  • 不让不可信扩展访问包含凭据的进程环境。
  • 分享或导出会话前检查内容。
  • 发现泄露后立即轮换,而不是只删除日志。

第三方扩展、MCP 与 Pi 包

扩展是与 Pi 同进程、同权限运行的代码;本地 MCP 服务是子进程,远程 MCP 服务可能操作其授权账户。Codemode 通过工具间接调用这些服务,并不会撤销已发生的副作用。安装或连接前检查:

  1. 发布者与仓库来源。
  2. 安装脚本和依赖。
  3. 是否读取文件、环境变量或网络。
  4. 最近维护状态与版本固定方式。

“功能只是一个主题或命令”并不意味着它没有代码执行权限。

在 Vue 或浏览器中集成 Pi

这份文档站使用 Vue 3,但 Pi CLI 本身运行在 Node.js 终端环境。如果你另外构建 Pi Web 客户端:

  • 不要把供应商 API Key 放进 VITE_*、客户端 .env 或浏览器存储。
  • 不要把 @earendil-works/pi-coding-agent CLI SDK 直接打进浏览器。
  • 浏览器侧可以使用面向 Web 的 pi-ai / pi-agent-core 能力,但生产请求应经过你控制的后端代理。
  • 后端必须负责认证、模型白名单、限流、审计和供应商密钥保管。

上游的浏览器打包检查证明核心包可以被 bundler 处理,不代表把供应商密钥暴露给浏览器是安全的。

最小安全检查表

  • 当前目录正确,工作树状态已确认。
  • 仓库与项目本地扩展可信。
  • 任务范围、禁止动作和完成标准已写清。
  • 高风险凭据没有暴露给任务环境。
  • 不可信或无人值守任务运行在隔离环境。
  • 修改由 git diff 和真实检查命令独立验证。

继续阅读: