Pi Agent 沙箱教程：Docker、OpenShell 与 Gondolin 权限隔离怎么选

Pi Agent 的这个教程只处理标题中的具体任务。Pi 默认继承启动用户的文件、进程、网络和凭据权限；Docker、Gondolin 与 OpenShell 解决的是不同信任边界，不能只按安装难度选择。

下面所有操作都先放在测试仓库、测试账号或仅回环监听的服务中。命令中的域名、用户名、路径与密钥是占位符，执行前需要替换。

先画出 Pi 默认能访问的边界

这一节解决的是“先画出 Pi 默认能访问的边界”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

对 Pi Agent 而言，判断依据是：Pi 默认继承启动用户的文件、进程、网络和凭据权限；Docker、Gondolin 与 OpenShell 解决的是不同信任边界，不能只按安装难度选择。不要在这个阶段顺手打开更多权限。

1
2
3

whoami
Get-Location
Get-ChildItem Env: | Select-String -Pattern 'KEY|TOKEN'

执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。

三种隔离方案的差异表

按下面顺序处理：

1. 读取实际版本和当前配置。
2. 只改变与本节相关的一项设置。
3. 运行一个只读或可撤销的请求。
4. 检查日志、退出码和最终文件。
5. 失败时恢复刚才那一项修改。

1

docker version

这里的完成标准不是界面出现，而是“三种隔离方案的差异表”有可重复结果。

Docker 适合一次性仓库任务

1

docker run --rm -it -v ${PWD}:/workspace -w /workspace node:22 bash

表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。

只读挂载和可写挂载如何拆开

围绕“只读挂载和可写挂载如何拆开”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

1

docker run --rm -it -v ${PWD}:/workspace:ro -w /workspace node:22 bash

建议记录以下四项：

• 执行前的版本或 Git 提交。
• 实际输入，不记录秘密值。
• 可观察的输出、状态码或 diff。
• 恢复动作以及恢复后的复查结果。

如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。

把 Provider 密钥注入容器的风险

这一节解决的是“把 Provider 密钥注入容器的风险”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

对 Pi Agent 而言，判断依据是：Pi 默认继承启动用户的文件、进程、网络和凭据权限；Docker、Gondolin 与 OpenShell 解决的是不同信任边界，不能只按安装难度选择。不要在这个阶段顺手打开更多权限。

1

docker run --rm -it --env-file .env.agent node:22 bash

执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。

Gondolin 为什么保留主机认证

按下面顺序处理：

1. 读取实际版本和当前配置。
2. 只改变与本节相关的一项设置。
3. 运行一个只读或可撤销的请求。
4. 检查日志、退出码和最终文件。
5. 失败时恢复刚才那一项修改。

1

pi

这里的完成标准不是界面出现，而是“Gondolin 为什么保留主机认证”有可重复结果。

OpenShell 适合策略受控执行

1

pi

表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。

验证越权读取确实被拒绝

围绕“验证越权读取确实被拒绝”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

1

docker run --rm -v ${PWD}:/workspace:ro node:22 sh -lc 'touch /workspace/should-fail'

建议记录以下四项：

• 执行前的版本或 Git 提交。
• 实际输入，不记录秘密值。
• 可观察的输出、状态码或 diff。
• 恢复动作以及恢复后的复查结果。

如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。

限制出站网络而不是只关端口

这一节解决的是“限制出站网络而不是只关端口”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

对 Pi Agent 而言，判断依据是：Pi 默认继承启动用户的文件、进程、网络和凭据权限；Docker、Gondolin 与 OpenShell 解决的是不同信任边界，不能只按安装难度选择。不要在这个阶段顺手打开更多权限。

1

docker network ls

执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。

容器内 Git 身份与提交归属

按下面顺序处理：

1. 读取实际版本和当前配置。
2. 只改变与本节相关的一项设置。
3. 运行一个只读或可撤销的请求。
4. 检查日志、退出码和最终文件。
5. 失败时恢复刚才那一项修改。

1
2

git config user.name
git config user.email

这里的完成标准不是界面出现，而是“容器内 Git 身份与提交归属”有可重复结果。

任务结束后检查残留进程和文件

1
2

docker ps -a
git status --short

表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。

根据任务风险选择沙箱

围绕“根据任务风险选择沙箱”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

1

docker version

建议记录以下四项：

• 执行前的版本或 Git 提交。
• 实际输入，不记录秘密值。
• 可观察的输出、状态码或 diff。
• 恢复动作以及恢复后的复查结果。

如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。

只读挂载宿主 Git 仓库

这一节解决的是“只读挂载宿主 Git 仓库”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。

对 Pi Agent 而言，判断依据是：Pi 默认继承启动用户的文件、进程、网络和凭据权限；Docker、Gondolin 与 OpenShell 解决的是不同信任边界，不能只按安装难度选择。不要在这个阶段顺手打开更多权限。

1

docker run --rm -v ${PWD}:/workspace:ro node:22 ls -la /workspace

执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。

可写任务使用独立 Worktree

按下面顺序处理：

1. 读取实际版本和当前配置。
2. 只改变与本节相关的一项设置。
3. 运行一个只读或可撤销的请求。
4. 检查日志、退出码和最终文件。
5. 失败时恢复刚才那一项修改。

1

git worktree add ..\pi-task -b agent/pi-task

这里的完成标准不是界面出现，而是“可写任务使用独立 Worktree”有可重复结果。

验证断网容器无法访问公网

1

docker run --rm --network none node:22 node -e "fetch('https://example.com').catch(e=>console.log(e.code))"

表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。

销毁沙箱后检查宿主残留

围绕“销毁沙箱后检查宿主残留”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。

1
2

docker ps -a
git status --short

建议记录以下四项：

• 执行前的版本或 Git 提交。
• 实际输入，不记录秘密值。
• 可观察的输出、状态码或 diff。
• 恢复动作以及恢复后的复查结果。

如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。

Pi Agent 常见问题

是否可以跳过测试环境，直接把 Pi Agent 用到正式项目？

不建议。至少先完成一次最小成功请求、一次故意失败和一次恢复演练。

Pi Agent 命令能运行但结果不对，先查哪里？

先查输入范围、实际生效的配置和上游响应，再查模型总结。进程正常不代表业务结果正确。

如何避免 Pi Agent 的密钥或令牌进入 Git？

使用系统环境变量、Secret 管理或项目外配置文件，并在提交前搜索 diff。发现泄露后必须轮换密钥。

升级 Pi Agent 时最容易漏掉什么？

最容易漏掉配置格式、默认监听地址、权限范围和缓存兼容性。升级前保存版本与验证样本。

Pi Agent 验收问题

完成后应能回答下面的问题：

• 使用的是哪个确切版本？
• 哪些目录、端口、账号和外部服务可被访问？
• 成功结果如何回到原始数据或 Git diff？
• 上游失败时会报错、重试还是切换？
• 密钥是否可能出现在日志或历史记录？
• 如何在十分钟内回到修改前状态？

如果其中任何一项无法回答，Pi Agent 仍处于试用状态，不应扩大权限或接入生产自动化。