OpenAI Agents SDK Sandbox 2026：上線前怎麼驗收？

終端機裡的 SandboxAgent 範例明明成功，換到交付環境卻能讀到不該讀的檔案，任務中斷後也無法安全續跑。

最快的解法不是再跑一次成功案例，而是依序完成六類 OpenAI Agents SDK Sandbox 驗收：工作區契約、確定性編排測試、真實環境整合、權限隔離、狀態恢復，以及失敗回滾。

獲勝者：可重複建立、權限最小化並具備可回滾證據的驗收環境。 如果專案依賴 macOS 工具鏈、需要並行隔離測試，或必須在短期內集中回歸，才值得額外準備隔離的雲端 Mac；否則先在現有容器或託管沙箱完成邊界驗證，避免把環境搬遷誤當成安全驗收。

這篇適合三類讀者：

• 已跑通 SandboxAgent 範例，但還沒有建立上線門檻的開發者。
• 要驗證檔案讀寫、命令執行、網路與憑據邊界的平台工程師。
• 需要在本機、容器或雲端 Mac 之間安排測試環境的 AI 技術負責人。

先看失敗案例：成功執行不是放行證據

一個常見的交付事故是：開發者在本機建立了測試資料夾，Agent 能讀取輸入、執行命令、產出檔案，追蹤紀錄也顯示流程正常。到了試運行環境，卻出現三種問題：

• 工作目錄依賴本機殘留檔案，重新建立環境後找不到輸入。
• 執行身份繼承了過大的檔案或網路權限，能觸達工作區以外的內容。
• 任務被中斷後重新執行，重複覆寫已產出的檔案，或把上一個會話的檔案帶入新任務。

這些不是單純的模型輸出問題。它們分別涉及環境可重現性、執行邊界與狀態生命週期。官方文件目前將 Sandbox Agents 標示為 beta，API、預設設定和支援能力在正式可用前仍可能變動，因此驗收紀錄必須連同版本、設定和異常證據保存，而不能只截取一次成功畫面。官方 Sandbox Agents 快速開始文件 已提供目前的使用入口，正式放行仍應以實際版本重新核對。

第一階段：先於執行前凍結工作區契約

驗收的第一個時間點，不是 Agent 啟動，而是測試資料準備完成。先把工作區寫成可檢查的契約，至少要列出：

• Agent 可以讀取的目錄與檔案類型。
• 可以新增、修改或刪除的路徑。
• 必須拒絕的主機路徑、掛載目錄和外部儲存位置。
• 可用工具、命令、網路能力與環境變數。
• 任務完成後必須保留的產物，以及必須清理的暫存檔。

同時保存 Manifest、執行身份、能力工具和 SandboxRunConfig 的預期狀態。官方的 SandboxRunConfig 參考 可用來核對執行設定的欄位與邊界；這份設定應該成為測試基線，而不是藏在開發者個人機器上的隱性狀態。

OpenAI Agents SDK Sandbox 上線前要測試什麼？
先測試契約能否在空白環境中重建，再測試 Agent 是否只觸達契約允許的路徑。若測試需要手動補檔、修改權限或依賴個人環境變數，驗收應直接標記為阻斷，而不是進入下一階段。

驗收項目	放行證據	阻斷條件
工作區	新環境可依照版本化設定建立	依賴本機殘留檔案或手動修正
身份與權限	執行身份、掛載範圍和工具清單可追溯	權限來源不明或超出任務需要
設定基線	Manifest 與 SandboxRunConfig 已保存	每次執行使用不同的隱性預設
產物管理	輸入、輸出、暫存檔的去向明確	舊會話檔案可被新任務讀取

第二階段：用確定性測試拆開編排與沙箱

接著驗證的是 SDK 編排邏輯，而不是真實檔案系統。使用官方測試工具替代真實模型和沙箱執行，可固定工具回應，檢查工具參數、能力路由、錯誤分支、重試和最終輸出處理。Agents SDK 測試指南 說明了這類測試的用途；scripted_sandbox_session API 則可用來建立可預期的沙箱互動。

測試案例至少應包括：

• 正常工具呼叫：參數格式、工具順序與最終輸出正確。
• 命令失敗：Agent 是否停止、改走備援路徑或要求人工介入。
• 檔案不存在：是否回報明確錯誤，而不是自行猜測另一個路徑。
• 流程提前結束：是否清楚標記未完成產物，避免被誤認為成功。
• 重試分支：重試是否會重複執行不可逆操作。

這一階段的優點是快、可重跑、容易定位錯誤。缺點也很明確：它不能證明真實檔案權限、程序生命週期、網路邊界或隔離機制有效。

提醒： 確定性測試通過，只代表「編排在預期輸入下做出預期決定」。它不能替代真實沙箱整合測試，也不能替代生產式隔離驗證。

第三階段：在真實沙箱中核對環境一致性

當編排測試通過後，才把代表性任務放進真實沙箱。這時要固定目標交付環境的依賴、目錄結構、執行方式和清理流程，並把結果與第一階段的契約逐項比對。

可用以下方式判斷：

• 命令是否存在，版本是否符合專案鎖定條件。
• 工作目錄是否與預期一致。
• 輸出檔案的擁有者、權限、格式和位置是否正確。
• 重新建立工作區後，任務能否取得相同的必要輸入。
• 冷啟動、連續執行和並行任務是否出現不同的狀態污染。

這裡不應把其他系統的容器結果直接當成 macOS 驗收結果。凡是依賴 macOS 專屬工具鏈、簽名流程、系統元件或特定檔案行為的任務，都要在真實 Mac 環境重測。這不是因為 Mac 必然更快，而是執行邊界本身不同。

本地通過的 Agent 沙箱為什麼上線後失敗？
最常見的原因是本機帶有未寫入設定的依賴：個人憑據、預先安裝的命令、可寫入的暫存目錄，或上一個任務留下的檔案。若本地、容器和託管客戶端使用不同的 Manifest、掛載方式或執行身份，成功結果就沒有可移植性。

測試層級	可證明的事情	不能證明的事情
確定性編排	工具參數、路由、錯誤分支與輸出處理	真實檔案、程序和權限隔離
真實沙箱整合	依賴、目錄、命令與產物能否重現	生產流量下的全面安全性
生產式隔離	執行身份、網路、憑據和高風險操作邊界	未測試版本的未來行為

若需要把測試結果保留成可追蹤事件，應同步保存執行設定、工具呼叫、錯誤和產物雜湊。官方 Tracing 文件 可作為追蹤欄位和事件檢查的依據，但追蹤本身不是隔離證明；能看到一次越權，和能阻止越權，是兩件不同的事。

第四階段：高權限操作前驗證隔離邊界

檔案讀寫和命令執行一旦涉及刪除、覆蓋、外發資料或修改系統，就必須單獨設計拒絕或審批路徑。驗收時不要只問「命令能否成功」，還要問「不應成功的命令是否確實失敗」。

SandboxAgent 怎麼驗證檔案和命令權限？
建立允許、拒絕和需要審批的三組案例。允許案例只碰觸契約內的目錄；拒絕案例嘗試讀取工作區外檔案、寫入唯讀位置、使用未列出的命令或送出未授權資料；審批案例則確認沒有審批時任務會停在安全狀態。每次結果都要保存命令、執行身份、目標路徑和錯誤回應。

驗證重點包括：

• 掛載目錄是否按唯讀需求設計，而非預設全部可寫。
• 網路能力是否必要，環境變數是否含有不應進入沙箱的憑據。
• 外部儲存和主機路徑是否超出工作區邊界。
• 高風險命令被拒絕後，Agent 是否仍會用變形命令繞過規則。
• 清理失敗時，是否能停止後續任務並隔離殘留資料。

本地客戶端只能代表本地客戶端的權限狀態，不能等同安全隔離環境。生產式任務應另外驗證容器或託管執行邊界，並明確記錄哪些能力由平台保證、哪些只是由 Agent 提示詞約束。

第五階段：用中斷測試驗證快照與續跑

完整成功路徑最容易通過，也最不能說明恢復能力。長任務進入試運行後，應主動在不同階段中斷，檢查會話狀態、快照或已保存工作區能否按設計恢復。

Agent 沙箱如何測試快照恢復和任務續跑？
先在產生中間產物後中斷，再從保存狀態恢復。檢查已完成的高風險操作不會被重複執行，未完成步驟仍有清楚標記，且新會話不會讀到舊任務的非預期檔案。若恢復結果與首次執行不一致，應把任務標記為不可恢復，直接重新建立環境，而不是讓 Agent 自行猜測缺失狀態。

中斷情境	應保存的證據	不合格結果
工具執行前中斷	會話狀態與待執行步驟	恢復後跳過必要檢查
產物寫入後中斷	產物清單、版本與寫入狀態	恢復後重複覆蓋或產生副本
網路或外部服務失敗	錯誤分類與重試狀態	無限重試或誤判成功
清理階段中斷	殘留檔案與清理結果	殘留資料流入下一個會話

這個階段同時回答可恢復性與隔離性問題：恢復的是哪一份狀態，誰能讀取它，恢復後使用的權限是否仍然最小。若答案無法由紀錄重建，便沒有足夠的放行證據。

第六階段：把結果分成通過、補測與阻斷

最終決策不應只有「成功」或「失敗」。建議將每個測試結果分為三類：

• 通過：證據完整，結果符合契約，可進入下一個階段。
• 需補測：存在環境差異或證據缺口，但尚未證明越權或資料遺失。
• 阻斷：出現越權存取、敏感資訊暴露、環境無法重現、恢復不一致，或沒有失敗回滾路徑。

以下清單可直接交給開發、平台和安全負責人共同簽核：

• [ ] 工作區契約已版本化，並能在乾淨環境重建。
• [ ] Manifest、SandboxRunConfig、執行身份和工具清單已保存。
• [ ] 正常、命令失敗、檔案不存在及提前結束路徑均完成確定性測試。
• [ ] 真實沙箱已核對依賴、工作目錄、檔案權限和輸出產物。
• [ ] 本機、容器或託管環境的差異已記錄，未把其中一者結果冒充全部環境。
• [ ] 網路、環境變數、外部儲存和主機路徑均完成邊界測試。
• [ ] 刪除、覆蓋、外發資料和高風險命令具備拒絕或審批路徑。
• [ ] 中斷後能確認會話狀態、快照或工作區的恢復結果。
• [ ] 恢復不會重複高風險操作，也不會帶入舊任務檔案。
• [ ] 清理失敗、恢復失敗和環境不一致均有終止及重新建立規則。
• [ ] 測試配置版本、執行紀錄、異常與負責人已歸檔。

什麼情況才值得準備獨立的雲端 Mac？

哪些 Sandbox 測試需要獨立 Mac 環境？
需要驗證 macOS 專屬工具鏈、簽名流程、系統元件或實際 Mac 檔案行為時，應使用真實 Mac。若團隊需要多個隔離工作區並行回歸，或在短期試運行期間集中重建環境，獨立的雲端 Mac 也較容易把測試節點與開發者日常機器分開。

反過來，若任務只驗證與作業系統無關的編排邏輯，先用確定性測試和既有沙箱即可。若專案是長期、穩定且高負載的固定工作，購置或長期維護專屬機器可能比租賃更適合；若必須接觸實體 USB、特殊周邊或本地硬體，雲端 Mac 也不是完整替代方案。

條件	優先選擇	理由
只驗證工具路由和錯誤分支	確定性測試	不必引入真實環境變數
需要檢查容器或託管隔離	獨立沙箱	可驗證身份、掛載與網路邊界
依賴 macOS 工具鏈或簽名流程	真實 Mac	其他系統結果不能代替
短期集中回歸、多人並行	隔離的雲端 Mac	減少共用工作區和本機狀態污染
長期固定重負載或實體周邊	自有設備或專用環境	租賃彈性不一定符合持續需求

若需要安排臨時驗證節點，可先查看 ProxyMac 的繁體中文幫助頁，確認連線、交付和使用限制，再依實際任務週期對照 ProxyMac 的方案資訊。重點不是把所有測試搬上雲，而是只把 macOS 依賴、並行隔離和環境重建這些真正需要的部分獨立出來。

經驗提醒： 截至 2026 年 8 月 26 日，官方文件仍將 Sandbox Agents 標示為 beta；本文的驗收結論應在版本、API 或支援能力變更時重新核對官方文件，而不應視為永久不變的部署承諾。官方 Sandbox 概念與生命週期說明 為目前復核依據。

目前方案若只是開發者本機，常見缺點是權限與檔案殘留難以追蹤、多人並行時工作區容易互相污染，而且 macOS 依賴無法由其他系統的測試結果代替。若改用共用容器，又可能遇到環境版本不一致、恢復證據不足和高風險操作回滾困難。對於短期集中回歸、需要真實 macOS 工具鏈或必須隔離多個任務的團隊，租用 ProxyMac 的雲端 Mac 會比直接把個人開發環境推進生產更容易控制；但交付前仍應依本文清單重建工作區、重測權限與續跑，不應把租到設備本身當成驗收完成。