Pi Agent 安全与项目信任
Pi Agent 以你当前用户的权限运行。
本章介绍项目信任机制、安全边界和容器化运行方案。
Pi Agent 的安全模型
Pi Agent 是一个本地编码代理——它用你启动时的用户权限运行，能读、写、编辑文件，以及执行 shell 命令。
这意味着：
- 它能访问你用户账户能访问的所有文件
- 它能执行的命令范围与你手动在终端中操作完全一致
- 它不内置沙盒隔离机制
这是有意为之的设计——Pi Agent 需要能调用项目工具链、运行测试、安装依赖，这些操作需要真实的系统权限。
Pi Agent 的设计哲学是：不提供「看似安全实则容易误解」的半成品沙盒。
真正的隔离应该来自操作系统层面或虚拟化/容器边界。
项目信任机制
项目信任（Project Trust）控制 Pi Agent 是否加载项目本地的配置和扩展。
它不是沙盒——它只控制启动时加载什么，不限制模型在对话中能做什么。
什么情况下会触发信任检查
当 Pi Agent 在项目目录中检测到以下任何内容时，会触发信任检查：
- .pi/settings.json（项目配置文件）
- .pi/extensions、.pi/skills、.pi/prompts、.pi/themes（项目资源目录）
- .pi/SYSTEM.md 或 .pi/APPEND_SYSTEM.md（项目系统提示词）
- .agents/skills（项目 Skills 目录）
仅有 .pi 空目录不会触发信任检查。
信任决策流程
Pi Agent 按固定的顺序判断要不要加载当前项目的资源。
- 检查 trust.json 中是否有已保存的决策（从当前目录向上查找）
- 如果有，使用已保存的决策
- 如果没有，遵循 defaultProjectTrust 设置的行为（默认：ask，即询问）
- 用户做出决策后可选择「记住」，写入 trust.json
信任决策按目录保存在全局 ~/.pi/agent/trust.json 中。
查找时沿父目录逐级匹配到该文件，找不到任何已保存的决策时才走 defaultProjectTrust 的逻辑。
首次进入未信任的项目时，界面会显示如下提示：
检测到项目本地配置 .pi/settings.json 是否信任此项目并加载其配置与扩展？(y/n/always/never)
提示文案与选项随版本可能不同，以实际界面为准。
项目信任只控制扩展、技能等受保护资源的加载。
AGENTS.md、CLAUDE.md 等上下文文件无论是否信任都会加载。
defaultProjectTrust 设置
这个配置项决定了无人确认时 Pi Agent 的默认选择，交互模式与非交互模式的表现并不相同。
| 值 | 交互模式行为 | 非交互模式行为 |
|---|---|---|
| "ask"（默认） | 弹出信任确认提示 | 不加载项目资源（行为同 "never"） |
| "always" | 自动信任 | 自动信任 |
| "never" | 自动拒绝 | 自动拒绝 |
配置方法：
实例
"defaultProjectTrust": "always"
}
也可以通过命令行参数覆盖单次行为：
# 本次运行信任项目 $ pi --approve $ pi -a # 本次运行不信任项目 $ pi --no-approve $ pi -na
使用 /trust 命令保存决策
在交互模式中，使用 /trust 命令可以随时保存对当前项目的信任决策：
/trust
这个命令会写入 ~/.pi/agent/trust.json，记录了按目录保存的信任决策。
/trust 保存的是当前的决定，但不会重载当前会话。
如果你修改了信任决策，需要重新启动 Pi Agent 才能使变更生效。
非交互模式的安全考量
在 Print 模式（-p）、JSON 模式（--mode json）和 RPC 模式（--mode rpc）下，Pi Agent 不会显示信任提示。
此时的行为完全取决于 defaultProjectTrust 设置：
- 设为 "ask" 或 "never"：项目资源被忽略
- 设为 "always"：项目资源被加载
使用 --approve 或 --no-approve 可以临时覆盖这个行为。
运行不受信任的代码
当你需要处理不受信任的仓库或自动化任务时，建议在容器或沙盒中运行 Pi Agent：
- 容器方式：将整个 pi 进程运行在 Docker 容器或 VM 中
- Gondolin 方式：主机运行 pi，将工具执行路由到 Gondolin 微 VM 中
- OpenShell 方式：整个 pi 进程运行在 NVIDIA 的策略控制沙盒中，通过网关创建沙盒
- 挂载控制：只挂载代理需要访问的工作目录
- 凭证管理：避免挂载主机 ~/.pi/agent/ 目录，传入最小权限的临时 API Key
- 网络隔离：如果任务不需要网络，限制容器的网络访问
- 结果审查：在将输出复制回受信任系统之前，审查 diff 和修改内容
Gondolin 是一个独立的开源微 VM 项目（本地 Linux 微 VM，需 QEMU 支持），Pi 通过示例扩展把内置工具执行路由进去。
OpenShell 通过 openshell sandbox create --from pi 创建沙盒，需要先注册并选中一个网关。
远程网关模式不会 bind-mount 本地目录，需要用上传下载命令在沙盒内外传文件，模型凭据可以留在沙盒外。
如果将主机工作目录以读写方式绑定挂载到容器中，容器内的写操作仍然会影响主机文件。
如果需要更严格的保护，使用只读挂载或将文件复制进出沙盒。
安全提示
下面按常见使用场景给出对应的安全建议，动手前先对照检查一遍。
| 场景 | 建议 |
|---|---|
| 审查第三方代码 | 在容器中运行，使用只读挂载 |
| 自动化 CI/CD | 使用临时凭证，限制工具白名单 |
| 团队共享配置 | 使用项目 .pi/settings.json，但不放入敏感信息 |
| 安装第三方扩展包 | 审查源码后再安装，扩展可以执行任意代码 |
| 安装第三方 Skills | 审查 SKILL.md 内容，Skills 可以指示模型执行任意操作 |