文章目录一、Pi 的安全设计哲学1.1 无内置沙箱：诚实的设计选择1.2 项目信任：输入加载防护1.3 安全边界总结二、项目信任机制详解2.1 触发信任提示的条件2.2 信任决策存储2.3 信任后的行为2.4 非交互模式下的项目信任2.5 默认项目信任行为三、容器化方案总览3.1 三种方案对比3.2 关键注意事项四、方案一：Gondolin 本地 Linux 微型虚拟机4.1 概述4.2 安装设置4.3 运行4.4 工作原理4.5 系统要求4.6 适用场景五、方案二：Docker 容器5.1 概述5.2 Dockerfile5.3 构建和运行5.4 关键配置说明5.5 安全变体5.6 适用场景六、方案三：OpenShell 沙箱6.1 概述6.2 配置网关6.3 在沙箱内启动 Pi6.4 远程网关的文件传输6.5 推理路由（凭证隔离）6.6 适用场景七、安全最佳实践清单7.1 处理不受信任的仓库7.2 扩展和包安全7.3 API Key 安全7.4 无人值守自动化安全7.5 遥测与隐私八、Shell 别名与环境变量安全8.1 Shell 别名8.2 会话环境变量8.3 进程检测九、报告安全问题9.1 正确的报告方式9.2 安全边界说明9.3 提示注入十、安全场景决策指南10.1 场景：个人项目，自己的代码10.2 场景：开源项目，审查 PR10.3 场景：完全陌生的仓库10.4 场景：CI/CD 自动化10.5 场景：企业环境，敏感代码十一、常见问题解答十二、总结一、Pi 的安全设计哲学在开始讨论具体的安全措施之前，理解 Pi 的安全设计哲学至关重要。Pi 的安全理念与大多数 AI 编程工具有着根本的不同。1.1 无内置沙箱：诚实的设计选择Pi不包含内置沙箱。这是一个故意的设计决策，而非遗漏。内置工具（read、write、edit、bash等）可以读取、写入、编辑文件和运行 shell 命令，权限与 Pi 进程完全相同。扩展是 TypeScript 模块，以相同权限运行。为什么不做内置沙箱？Pi 旨在操作本地源码树、调用项目工具链、与现有开发环境集成。在这种场景下，部分进程内沙箱容易被误解为安全边界，给用户虚假的安全感。Pi 的作者认为，权限系统在代理能够写入和运行代码的情况下，本质上是"安全剧场"（security theater）。核心观点：Pi 不假装提供它实际上无法提供的安全保障。它诚实地告诉你：如果你运行不受信任的代码，就需要真正的隔离——也就是容器或虚拟机。1.2 项目信任：输入加载防护项目信任（Project Trust）是 Pi 提供的唯一保护机制，但它的作用范围非常明确：它做什么：控制 Pi 是否加载项目本地设置、资源、包和扩展它不做什么：不限制模型在开始工作后要求工具执行的操作换句话说，项目信任只是一个输入加载防护——防止你打开一个陌生仓库时，仓库中的.pi目录静默地修改你的 Pi 配置或加载恶意扩展。它不能使不受信任的代码、提示或模型输出变得安全。1.3 安全边界总结机制保护范围不能保护的项目信任防止项目本地配置/扩展静默加载模型生成的代码、工具调用、Shell 命令容器化方案整个进程或工具执行的隔离容器内的操作仍然自由理解这一点是正确使用 Pi 安全功能的前提。二、项目信任机制详解2.1 触发信任提示的条件当当前工作目录中发现以下内容时，Pi 会触发项目信任提示：.pi/settings.json.pi/extensions、.pi/skills、.pi/prompts、.pi/themes.pi/SYSTEM.md或.pi/APPEND_SYSTEM.md当前目录或祖先目录中的项目.agents/skills空的.pi目录不计入。2.2 信任决策存储信任决策存储在~/.pi/agent/trust.json，按规范目录保存。最近的父路径决策优先于全局默认。2.3 信任后的行为信任项目后允许加载：.pi/settings.json.pi资源（扩展、技能、提示模板、主题、系统提示文件）通过项目设置配置的缺失项目包项目本地扩展和项目包管理的扩展拒绝信任则跳过受保护资源。注意：AGENTS.override.md、AGENTS.md、CLAUDE.md等上下文文件无论信任状态如何都会加载（除非禁用上下文加载）。2.4 非交互模式下的项目信任非交互模式（-p、--mode json、--mode rpc）不显示信任提示。使用以下标志覆盖单次运行的项目信任：pi-a-p"Review this code"# 信任项目pi-na-p"Review this code"# 不信任项目对应长选项：--approve/--no-approve2.5 默认项目信任行为通过settings.json设置默认行为：{"defaultProjectTrust":"ask"// "ask" | "always" | "never"}仅全局设置有效，项目设置中的此值无效。三、容器化方案总览对于不受信任的仓库、不打算密切监控的生成代码或无人值守自动化，你应该在容器化环境中运行 Pi。Pi 支持两种容器化模式：在隔离环境内运行整个pi进程在主机运行pi，将工具执行路由到隔离环境3.1 三种方案对比方案隔离内容适用场景复杂度Gondolin 扩展内置工具和!命令本地微 VM 隔离，认证保留在主机中等普通 Docker整个 pi 进程在本地容器中简单的本地隔离简单OpenShell整个 pi 进程在策略控制沙箱中本地或远程托管沙箱较高3.2 关键注意事项扩展在pi进程运行的地方执行。如果使用工具路由扩展运行主机 Pi，其他自定义扩展工具仍在主机上运行。绑定挂载读写模式时，容器内写入仍可修改主机文件。需要更强保护时使用只读挂载或复制文件进出沙箱。四、方案一：Gondolin 本地 Linux 微型虚拟机4.1 概述如今越来越多的 AI 智能代理会在无人人工审核的情况下执行生成的代码。这类代码往往需要网络访问权限与身份凭证，由此带来了数据泄露风险。Gondolin 是具备可编程网络与文件系统管控能力的本地 Linux 微型虚拟机。它作为 Pi 的扩展运行，将内置工具的执行路由到微 VM 中，而 Pi 本身和认证信息保留在主机上。Gondolin 将代码运行在轻量的本地 Linux 微型虚拟机中（默认后端为 QEMU，另有处于实验阶段的 krun 后端可供选用），同时 【极简编程智能体 Pi Agent】安全与容器化最佳实践：安全使用 AI 编程代理的完整指南
文章目录一、Pi 的安全设计哲学1.1 无内置沙箱：诚实的设计选择1.2 项目信任：输入加载防护1.3 安全边界总结二、项目信任机制详解2.1 触发信任提示的条件2.2 信任决策存储2.3 信任后的行为2.4 非交互模式下的项目信任2.5 默认项目信任行为三、容器化方案总览3.1 三种方案对比3.2 关键注意事项四、方案一：Gondolin 本地 Linux 微型虚拟机4.1 概述4.2 安装设置4.3 运行4.4 工作原理4.5 系统要求4.6 适用场景五、方案二：Docker 容器5.1 概述5.2 Dockerfile5.3 构建和运行5.4 关键配置说明5.5 安全变体5.6 适用场景六、方案三：OpenShell 沙箱6.1 概述6.2 配置网关6.3 在沙箱内启动 Pi6.4 远程网关的文件传输6.5 推理路由（凭证隔离）6.6 适用场景七、安全最佳实践清单7.1 处理不受信任的仓库7.2 扩展和包安全7.3 API Key 安全7.4 无人值守自动化安全7.5 遥测与隐私八、Shell 别名与环境变量安全8.1 Shell 别名8.2 会话环境变量8.3 进程检测九、报告安全问题9.1 正确的报告方式9.2 安全边界说明9.3 提示注入十、安全场景决策指南10.1 场景：个人项目，自己的代码10.2 场景：开源项目，审查 PR10.3 场景：完全陌生的仓库10.4 场景：CI/CD 自动化10.5 场景：企业环境，敏感代码十一、常见问题解答十二、总结一、Pi 的安全设计哲学在开始讨论具体的安全措施之前，理解 Pi 的安全设计哲学至关重要。Pi 的安全理念与大多数 AI 编程工具有着根本的不同。1.1 无内置沙箱：诚实的设计选择Pi不包含内置沙箱。这是一个故意的设计决策，而非遗漏。内置工具（read、write、edit、bash等）可以读取、写入、编辑文件和运行 shell 命令，权限与 Pi 进程完全相同。扩展是 TypeScript 模块，以相同权限运行。为什么不做内置沙箱？Pi 旨在操作本地源码树、调用项目工具链、与现有开发环境集成。在这种场景下，部分进程内沙箱容易被误解为安全边界，给用户虚假的安全感。Pi 的作者认为，权限系统在代理能够写入和运行代码的情况下，本质上是"安全剧场"（security theater）。核心观点：Pi 不假装提供它实际上无法提供的安全保障。它诚实地告诉你：如果你运行不受信任的代码，就需要真正的隔离——也就是容器或虚拟机。1.2 项目信任：输入加载防护项目信任（Project Trust）是 Pi 提供的唯一保护机制，但它的作用范围非常明确：它做什么：控制 Pi 是否加载项目本地设置、资源、包和扩展它不做什么：不限制模型在开始工作后要求工具执行的操作换句话说，项目信任只是一个输入加载防护——防止你打开一个陌生仓库时，仓库中的.pi目录静默地修改你的 Pi 配置或加载恶意扩展。它不能使不受信任的代码、提示或模型输出变得安全。1.3 安全边界总结机制保护范围不能保护的项目信任防止项目本地配置/扩展静默加载模型生成的代码、工具调用、Shell 命令容器化方案整个进程或工具执行的隔离容器内的操作仍然自由理解这一点是正确使用 Pi 安全功能的前提。二、项目信任机制详解2.1 触发信任提示的条件当当前工作目录中发现以下内容时，Pi 会触发项目信任提示：.pi/settings.json.pi/extensions、.pi/skills、.pi/prompts、.pi/themes.pi/SYSTEM.md或.pi/APPEND_SYSTEM.md当前目录或祖先目录中的项目.agents/skills空的.pi目录不计入。2.2 信任决策存储信任决策存储在~/.pi/agent/trust.json，按规范目录保存。最近的父路径决策优先于全局默认。2.3 信任后的行为信任项目后允许加载：.pi/settings.json.pi资源（扩展、技能、提示模板、主题、系统提示文件）通过项目设置配置的缺失项目包项目本地扩展和项目包管理的扩展拒绝信任则跳过受保护资源。注意：AGENTS.override.md、AGENTS.md、CLAUDE.md等上下文文件无论信任状态如何都会加载（除非禁用上下文加载）。2.4 非交互模式下的项目信任非交互模式（-p、--mode json、--mode rpc）不显示信任提示。使用以下标志覆盖单次运行的项目信任：pi-a-p"Review this code"# 信任项目pi-na-p"Review this code"# 不信任项目对应长选项：--approve/--no-approve2.5 默认项目信任行为通过settings.json设置默认行为：{"defaultProjectTrust":"ask"// "ask" | "always" | "never"}仅全局设置有效，项目设置中的此值无效。三、容器化方案总览对于不受信任的仓库、不打算密切监控的生成代码或无人值守自动化，你应该在容器化环境中运行 Pi。Pi 支持两种容器化模式：在隔离环境内运行整个pi进程在主机运行pi，将工具执行路由到隔离环境3.1 三种方案对比方案隔离内容适用场景复杂度Gondolin 扩展内置工具和!命令本地微 VM 隔离，认证保留在主机中等普通 Docker整个 pi 进程在本地容器中简单的本地隔离简单OpenShell整个 pi 进程在策略控制沙箱中本地或远程托管沙箱较高3.2 关键注意事项扩展在pi进程运行的地方执行。如果使用工具路由扩展运行主机 Pi，其他自定义扩展工具仍在主机上运行。绑定挂载读写模式时，容器内写入仍可修改主机文件。需要更强保护时使用只读挂载或复制文件进出沙箱。四、方案一：Gondolin 本地 Linux 微型虚拟机4.1 概述如今越来越多的 AI 智能代理会在无人人工审核的情况下执行生成的代码。这类代码往往需要网络访问权限与身份凭证，由此带来了数据泄露风险。Gondolin 是具备可编程网络与文件系统管控能力的本地 Linux 微型虚拟机。它作为 Pi 的扩展运行，将内置工具的执行路由到微 VM 中，而 Pi 本身和认证信息保留在主机上。Gondolin 将代码运行在轻量的本地 Linux 微型虚拟机中（默认后端为 QEMU，另有处于实验阶段的 krun 后端可供选用），同时