AI Agent

2026 OpenHands 沙箱怎麼部署,才能隔離 AI 編碼任務與 macOS 主機?

建議優先採用 OpenHands 官方支援的容器沙箱路徑,並且只掛載任務必需的工作目錄;這適合要修改程式碼、執行測試或處理不熟悉程式庫的情況,但容器不是絕對安全邊界,也不應預設開放 Docker socket 或主機憑證。若任務必須使用 Xcode 等 macOS 原生工具鏈,應將建置環境與 Agent 可存取的檔案權限分開規劃。

準備首次在 Mac 上部署 OpenHands 的開發者,可依本文逐步建立容器執行路徑。
需要隔離多個程式庫的工程團隊,可用獨立工作區、憑證與網路入口降低交叉存取風險。
負責 macOS 原生應用建置的技術主管,可據此判斷 Agent 沙箱與建置環境如何分工。

先選執行後端:容器或本機直接執行

部署前先確認 OpenHands 的 Agent 將在哪裡執行。直接在本機執行時,Agent 所處的信任邊界更接近目前使用者與主機檔案;採用 Docker 沙箱則可把任務執行環境放進容器,並透過掛載設定決定哪些主機資料夾可被看見。兩種路徑的權限範圍不同,不宜只因為介面能啟動,就把它們視為等價選項。

官方文件將沙箱模式與 Docker 沙箱分開說明;目前本機安裝路徑應依照OpenHands 官方本機安裝文件核對。文件中也可能看到標示為 V0 的舊版 Docker Runtime 說明,請勿把V0 執行方式直接當成目前通用設定。實際啟動指令、映像標籤與參數應以官方沙箱模式說明及Docker 沙箱文件為準。

可用以下條件決定執行方式:

  • 若 Agent 要修改程式碼、跑測試,或執行來源尚未充分檢查的專案腳本,選擇官方支援的 Docker 容器沙箱,並把可寫入範圍限制在專案工作區。
  • 若任務只需閱讀規格或參考資料,將相關目錄以唯讀方式掛載;不需要寫入的資料不應因操作方便而開放修改。
  • 若任務必須呼叫 Xcode 或其他 macOS 原生工具,將原生建置安排在具備該工具鏈的 macOS 環境,不要假設 Linux 容器能提供 macOS 建置能力。
  • 若工作流程確實需要 Agent 管理其他容器,先釐清 Docker daemon 權限與主機風險,再決定是否提供 socket;沒有明確需求就不要開放。

OpenHands 沙箱部署的工作區邊界

OpenHands 在 macOS 上使用 Docker 沙箱,並不代表 Agent 自動看不到主機檔案。容器能存取哪些資料,取決於啟動設定與掛載內容。Docker 的 bind mount 會把主機路徑提供給容器;若掛載目錄可寫,容器內的程式也可能修改或刪除其中檔案。Docker 文件說明了bind mount 的唯讀選項與存取行為。

部署前先準備專用專案資料夾,不要直接把家目錄、整個硬碟或包含私人資料的上層目錄交給 Agent。參考文件、規格與範例若不需修改,應與工作區分開,並在官方支援的設定方式中以唯讀模式掛載。工作區則只在確有程式碼修改需求時開放寫入。

執行方式 工作區與主機的關係 適合情境 主要限制
本機直接執行 權限取決於本機程序使用者與執行設定 受信任、權限需求明確的本機工作 不可假設 Agent 只會接觸目前專案
Docker 容器沙箱 依掛載與容器設定存取指定路徑 程式碼修改、測試及來源需審視的任務 可寫入的掛載資料仍可能被更改或刪除
macOS 原生建置環境 提供原生工具鏈,但不應與 Agent 權限混為一談 Xcode 或其他 macOS 專屬建置與測試 必須另外界定 Agent 如何提交及取得建置結果

部署前可先完成以下目錄檢查:

  • [ ] 建立專供本次任務使用的專案工作區,避免沿用包含私人設定檔的資料夾。
  • [ ] 列出 Agent 必須讀取與必須修改的路徑,分開規劃唯讀參考資料與可寫工作區。
  • [ ] 移除與任務無關的主機目錄掛載,尤其是憑證、私人金鑰、個人文件及其他程式庫。
  • [ ] 確認專案工作區的變更能透過版本控制或其他方式檢視、保存及回復。
  • [ ] 部署後核對容器實際看到的目錄,不以「容器正在執行」推定主機資料已受完整隔離。

macOS 上的 Docker 沙箱會看到哪些主機檔案?

答案不是固定的目錄清單,而是實際提供給容器的掛載與權限。若只掛載目前專案,Agent 的檔案操作範圍便可比掛載整個家目錄更窄;但只要專案目錄可寫,該目錄內的檔案仍可能被改動。唯讀掛載可以限制寫入,卻不會讓資料對容器不可見。

因此,限制 OpenHands 只掛載目前專案目錄時,應從工作區準備開始:確認專案資料夾沒有混放不相關資料,再按官方 Docker 沙箱設定文件配置掛載。不要複製來源不明的舊版參數,也不要只靠任務提示要求 Agent「不要碰其他檔案」;提示文字不是主機端的權限控制。

還要分清幾個邊界:OpenHands Agent 容器是任務執行環境;Docker 管理 socket 是通往 Docker daemon 的控制入口;macOS 主機仍持有本機檔案與系統資源;macOS 原生建置環境則負責需要 Apple 工具鏈的工作。這些角色不可混稱為同一個「沙箱」。

收緊服務入口與 Docker socket 權限

服務可以在本機正常開啟,不代表應對整個網路公開。設定 OpenHands 管理介面時,先依官方本機安裝流程核對監聽位址與連接埠發布方式;需要本機操作的情況,應避免把開發介面無意間暴露給不需要存取的網路。Docker 官方說明了連接埠發布與主機位址綁定,應按實際部署環境檢查發布設定,而非照搬通用範例。

Docker socket 的作用是讓用戶端向 Docker daemon 發出管理請求。提供此入口不是單純「讓容器更方便」:取得 daemon 控制能力的程序可能進一步建立或管理容器,並擴大其對主機資源的影響範圍。Docker 文件特別說明了保護 daemon 存取的重要性。因此,若任務只是修改專案與執行測試,除非官方流程或任務需求明確要求,否則不要將 socket 掛入 Agent 容器。

部署完成後,逐項核對管理介面的可達範圍、容器的掛載清單,以及是否出現 Docker socket。發現多餘入口時,先停止服務並修正設定,再進行任何需要私有程式碼或主機檔案的工作。

首次任務的憑證與連線驗證

模型服務憑證、程式碼平台憑證與工作區寫入權限是不同的授權項目,不應因為 Agent 需要其中一項,就一併提供其他權限。涉及私有程式庫或外部 API 時,應建立專供該任務使用、權限範圍符合需求的憑證;參考程式碼平台的 API 憑證安全建議,並預先規劃如何讓憑證到期或撤銷。

容器隔離不會自動阻止 Agent 使用已交付給它的密鑰、連接外部服務,或運用使用者明確授予的權限。憑證不應放進不必要的專案檔案,也不應長期沿用一次性任務的授權。若任務結束或懷疑憑證曾被不當使用,應按既定流程撤銷並重新簽發,而不是只刪除本機設定檔。

首次執行時,選一個沒有敏感資料的小型程式碼任務,沿部署鏈路檢查:

  • [ ] 確認管理介面只在預期的本機或網路範圍內可存取。
  • [ ] 確認 OpenHands 使用的是目前官方文件支援的執行路徑,而不是誤套 V0 範例。
  • [ ] 確認容器能讀取指定專案,且只有任務需要的路徑具備寫入權限。
  • [ ] 讓 Agent 執行範圍有限的讀取、修改與測試工作,檢查輸出及實際變更位置。
  • [ ] 檢查容器停止後的檔案狀態,並確認沒有未規劃的主機目錄或 Docker 能力。

任務收尾與原生建置分工

完成任務後,先保存需要的程式碼變更並檢查差異,再停止或清理任務執行環境。依團隊流程移除臨時掛載與設定,並撤銷不再需要的任務憑證。一次性環境不應因為下次啟動方便,就長期保留為預設信任環境。

若任務包含 Xcode 建置或 macOS 原生測試,應把 Agent 可修改的工作區與原生建置環境分開管理:Agent 在受限工作區產生或修改程式碼,建置環境依明確流程取得待建置內容與回傳結果。Apple 的App Sandbox 文件描述的是 macOS 應用程式及其授權能力相關機制,不能據此推論 Docker 容器、一般命令列程序與 App Sandbox 具有相同邊界。

Docker 沙箱適合把程式碼任務與主機檔案權限分開規劃,但它不能代替 macOS 原生工具鏈;直接在日常 Mac 上執行 Agent,則會增加主機目錄誤授權與環境殘留的管理負擔。若只在特定任務需要 Xcode 或其他 macOS 原生工具,將容器 Agent 與專用 Mac 執行環境分工,通常比要求單一容器同時負責隔離與原生建置更清楚。可先參閱 KuzCloud 的服務入口及KuzCloud 說明中心,了解服務與使用方式,再評估是否需要租用 Mac 處理原生建置;這是建置環境的安排,不是 OpenHands 容器沙箱的額外安全保證。

為 OpenHands 配置專屬遠端 Mac

以 KuzCloud 獨占的 Mac mini M4 運行遠端開發工作,讓 AI 編碼任務與日常使用的 Mac 分開。

透過 SSH 或 VNC 連線,依需求安裝 Docker 與開發工具,工作環境由您自行掌控。