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

docker version

這裡的完成標準不是介面出現，而是「三種隔離方案的差異表」有可重複結果。

Docker 適合一次性倉庫任務

要檢查的內容	合格表現	需要停止的信號
Docker 適合一次性倉庫任務	輸入和輸出範圍明確	自動擴大到其他項目或帳號
權限	只獲得完成任務所需權限	要求管理員權限或完整金鑰
日誌	能定位失敗且已經脫敏	出現 Token、Cookie 或私有正文
回退	能恢復上一步狀態	修改不可逆且沒有備份

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 密鑰注入容器的風險」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

1

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

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

Gondolin 為什麼要保留主機認證

按下面順序處理：

讀取實際版本和目前配置。
只改變與本節相關的一項設定。
執行一個唯讀或可撤銷的請求。
檢查日誌、退出碼和最終檔案。
失敗時恢復剛才那一項修改。

1

pi

這裡的完成標準不是介面出現，而是「Gondolin 為什麼保留主機認證」有可重複結果。

OpenShell 適合策略控制執行

要檢查的內容	合格表現	需要停止的信號
OpenShell 適合策略受控執行	輸入和輸出範圍明確	自動擴展到其他項目或帳號
權限	只獲得完成任務所需權限	要求管理員權限或完整金鑰
日誌	能定位失敗且已經脫敏	出現 Token、Cookie 或私有正文
回退	能恢復上一步狀態	修改不可逆且沒有備份

1

pi

表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。

驗證越權讀取確實被拒絕

圍繞著「驗證越權讀取確實被拒絕」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。

1

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

建議記錄以下四項：

執行前的版本或 Git 提交。
實際輸入，不記錄秘密值。
可觀察的輸出、狀態碼或 diff。
恢復動作以及恢復後的複查結果。

如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。

限制出站網路而不是只關端口

這一節解決的是「限制出站網路而不是只關連接埠」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

1

docker network ls

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

容器內 Git 身分與提交歸屬

按下面順序處理：

讀取實際版本和目前配置。
只改變與本節相關的一項設定。
執行一個唯讀或可撤銷的請求。
檢查日誌、退出碼和最終檔案。
失敗時恢復剛才那一項修改。

1
2


git config user.name
git config user.email

這裡的完成標準不是介面出現，而是「容器內 Git 身分與提交歸屬」有可重複結果。

任務結束後檢查殘留進程和文件

要檢查的內容	合格表現	需要停止的信號
任務結束後檢查殘留進程和文件	輸入和輸出範圍明確	自動擴大到其他項目或帳號
權限	只獲得完成任務所需權限	要求管理員權限或完整金鑰
日誌	能定位失敗且已經脫敏	出現 Token、Cookie 或私有正文
回退	能恢復上一步狀態	修改不可逆且沒有備份

1
2


docker ps -a
git status --short

表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。

根據任務風險選擇沙箱

圍繞「根據任務風險選擇沙箱」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。

1

docker version

建議記錄以下四項：

執行前的版本或 Git 提交。
實際輸入，不記錄秘密值。
可觀察的輸出、狀態碼或 diff。
恢復動作以及恢復後的複查結果。

如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。

只讀掛載宿主 Git 倉庫

這一節解決的是「只讀掛載宿主 Git 倉庫」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

1

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

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

可寫入任務使用獨立 Worktree

按下面順序處理：

讀取實際版本和目前配置。
只改變與本節相關的一項設定。
執行一個唯讀或可撤銷的請求。
檢查日誌、退出碼和最終檔案。
失敗時恢復剛才那一項修改。

1

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

這裡的完成標準不是介面出現，而是「可寫入任務使用獨立 Worktree」有可重複結果。

驗證斷網容器無法存取公網

要檢查的內容	合格表現	需要停止的信號
驗證斷網容器無法存取公網	輸入和輸出範圍明確	自動擴大到其他項目或帳號
權限	只獲得完成任務所需權限	要求管理員權限或完整金鑰
日誌	能定位失敗且已經脫敏	出現 Token、Cookie 或私有正文
回退	能恢復上一步狀態	修改不可逆且沒有備份

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 仍處於試用狀態，不應擴大權限或接取生產自動化。