症狀： OpenHands 已經安裝成功，卻在真實專案驗收時卡在 Docker、並發或 Xcode。
最快解法： 單人低頻試用先放本機；只要需要多人並發、持續在線、遠端連線或隔離憑據，就優先使用獨立雲端 Mac。
官方本機設定文件把 4GB 記憶體列為執行 OpenHands 的最低建議值；這只是啟動與基本操作的門檻，不是多 Agent、大型專案或 Xcode 驗收的保證。(OpenHands 官方本機設定文件) 因此，判斷 OpenHands 自託管 Mac 的方案時，不應只看「能不能啟動」，而要看它能否在你的工作頻率、權限要求與驗收流程下穩定運作。
這篇適合三類讀者：想低成本體驗 OpenHands、但不確定本機是否適合長期運行的獨立開發者；需要為多人提供統一 Agent 環境的平台工程師；以及希望讓 Agent 修改並驗證 iOS、macOS 專案的 Apple 平台團隊。
先分清楚：安裝成功不等於驗收完成
最典型的失敗不是 OpenHands 啟動錯誤，而是以下流程：
- 在本機安裝 OpenHands 與 Docker Desktop。
- Agent 成功讀取 Git 儲存庫並修改 Swift 原始碼。
- Docker Runtime 可以執行一般 shell 命令。
- 到最後才發現環境沒有可用的 Xcode、Simulator、簽名憑證，或無法連接實體裝置。
- 團隊只能把修改內容搬到另一台 Mac，重新安裝依賴並手動驗收。
這種情況代表你部署的是「程式碼修改環境」，不是「Apple 專案交付環境」。Apple 官方文件指出，xcodebuild、simctl 與 devicectl 都屬於隨 Xcode 提供的命令列工具，而且必須先安裝 Xcode 並設定有效的開發者目錄。(Apple Xcode 命令列工具參考)
所以第一個判斷不是本機或雲端，而是：
- 只需要修改一般 Python、JavaScript、Go 或 Swift 原始碼：Docker Runtime 已可能足夠。
- 需要建置 iOS、macOS App：必須在有 Xcode 的 macOS 環境驗證。
- 需要簽名、封裝、Simulator 或實體裝置測試：Agent 執行節點與驗收節點不能分離到沒有交接規則的兩套環境。
本機 Mac 與雲端 Mac：先看負載，不要先看規格
本機部署的優點是啟動快、程式碼就在手邊，Docker 映像與依賴也容易保留在本地快取；缺點是 OpenHands 的工作會和你的編輯器、編譯器、瀏覽器及日常工作爭用同一台 Mac。
雲端 Mac 的優點不是「一定更快」，而是可以把長時間任務、遠端登入與團隊使用從個人工作機移開。缺點則是需要處理 SSH、網路延遲、權限、備份、映像版本與連線中斷。
| 決策維度 | 本機 Mac | 獨立雲端 Mac |
|---|---|---|
| 適合負載 | 單人、低頻、互動式任務 | 持續運行、排程任務、遠端工作 |
| 工作區 | 直接掛載本機儲存庫 | 需設計 Git、同步或遠端掛載 |
| 隔離範圍 | 失誤可能影響日常開發機 | 可將 Agent 與個人工作機分離 |
| 多人並發 | 容易共用同一組連接埠與快取 | 可按專案或團隊分配環境 |
| Apple 驗收 | 可直接使用本機 Xcode 與裝置 | 要先確認租用節點具備目標工具鏈 |
| 維護責任 | 你負責 Docker、更新與清理 | 你仍負責環境政策，但硬體不在辦公桌旁 |
| 遠端在線 | Mac 休眠或關機會中斷 | 適合長時間連線與背景任務 |
OpenHands 官方文件把 Docker 沙箱列為本機使用的建議方式，並說明可使用 --mount-cwd 或 SANDBOX_VOLUMES 將工作區掛載進沙箱。(OpenHands Docker 沙箱說明) 但掛載是便利功能，也是權限邊界：可寫入的目錄會讓 Agent 修改甚至刪除其中的檔案。
注意： Docker 隔離降低了 Agent 直接碰觸宿主機的風險，但不代表整台 Mac 已經變成安全沙箱。你仍須單獨檢查掛載目錄、Docker Socket、網路出口、SSH 金鑰、雲端憑證與環境變數。
Docker Runtime 的隔離邊界，不能只看容器名稱
OpenHands 的 Docker Runtime 會在容器中執行 Agent 動作，目標是讓任意程式碼不直接在宿主機上執行。官方架構文件也說明，Runtime 透過後端與動作執行伺服器溝通，並支援映像標籤、掛載與連接埠管理。(OpenHands Runtime 架構文件)
實際部署時，至少要檢查四個邊界：
第一，掛載目錄。
不要把整個家目錄、含有 SSH 金鑰的資料夾或公司的共用工作區以讀寫方式掛入。優先建立一次性的工作目錄，任務完成後刪除或重置。
第二，Docker Socket。
官方直接 Docker 啟動範例會掛載 /var/run/docker.sock，這是啟動沙箱所需的常見方式，但它同時使 OpenHands 能與 Docker 引擎互動。(OpenHands 本機啟動文件) 在個人試用與生產環境中，應分開評估 Socket 權限，而不是把「容器內執行」當成完整安全保證。
第三，網路存取。
Agent 可能需要下載依賴、查詢文件或存取 Git，但開放全部網路出口會增加供應鏈與資料外傳風險。官方舊版 Docker Runtime 文件提供綁定 127.0.0.1、指定連接埠與建立獨立 Docker 網路的做法，可作為自託管硬化時的檢查方向。(OpenHands Docker Runtime 網路設定說明)
第四，宿主機憑據。
不要把生產用 API Key、部署金鑰或可直接推送主分支的 Token 預設放進 Agent 環境。即使任務本身可信，依賴安裝腳本、第三方工具或被修改的程式碼仍可能讀取環境變數。
在本機部署時，上述錯誤可能影響你的日常工作機；在獨立雲端 Mac 上，則可以把工作區、登入帳號與生產憑據切割出去。這不是雲端天然更安全，而是故障半徑比較容易被管理。若你需要先確認遠端存取、帳號交接與使用流程，也可以參考 SSHMac 的繁體中文幫助中心。
第二步：用並發情境判斷環境，而不是用 Agent 數量猜測
「跑多個 Agent」不只代表啟動多個視窗。真正會衝突的是：
- 兩個任務同時寫入同一個工作區；
- 測試服務搶用相同連接埠；
- 不同分支共用未隔離的依賴目錄；
- 一個任務更新套件，另一個任務使用了不同版本；
- 多個 Agent 共用同一份 Git 憑據或暫存資料；
- 任務失敗後留下容器、快取與背景程序。
OpenHands 官方執行時架構支援自訂 Sandbox 映像，也會依照版本、鎖定雜湊與原始碼雜湊建立不同標籤，目的就是在可重現性與更新彈性之間取得平衡。(OpenHands 執行時架構與映像標籤) 這些機制可以減少重複安裝，但不能自動替你設計團隊級工作區隔離。
| 使用方式 | 常見問題 | 建議部署 | 編輯評分（決策權重，非效能實測） |
|---|---|---|---|
| 個人偶爾處理一個儲存庫 | 本機被短時間占用，任務中斷容易重跑 | 本機 Mac + Docker Runtime | 本機 4/5 |
| 個人每天執行長任務 | 睡眠、更新或重啟會中斷 Agent | 本機專用 Mac 或獨立雲端 Mac | 雲端 4/5 |
| 兩至三人共享 Agent | 工作區、連接埠與依賴容易互相影響 | 本地專機起步，逐步拆分遠端環境 | 混合 4/5 |
| 平台提供持續服務 | 需要權限、日誌、版本與遠端存取管理 | 獨立雲端 Mac 或多節點環境 | 雲端 5/5 |
| iOS/macOS 專案交付 | 必須驗證 Xcode、Simulator、簽名與裝置 | 有完整工具鏈的 Mac 節點 | Mac 驗收 5/5 |
若只有一位開發者、每天少量互動，直接在本機使用 OpenHands 通常合理；若任務會在你離開辦公桌後繼續執行，或團隊需要透過 SSH、瀏覽器與遠端桌面存取，就不應再把日常工作機視為唯一節點。
Apple 工具鏈是硬條件，不是部署後再補的細節
只修改 Swift 原始碼，和完成 Apple 專案驗收，是兩件不同的事。
Xcode 會根據 Scheme、Target、建置設定與執行目的地安排建置；iOS、iPadOS 等專案可在 Simulator 或連接的實體裝置上執行，macOS App 則可在目前的 Mac 上執行。(Apple 在模擬器或實體裝置上執行 App) Simulator 也不等同於實體裝置，Apple 明確提醒，若要確認實際行為，仍要在一個或多個實體裝置上測試。
因此，部署前請把驗收拆成三層：
- 原始碼層： Agent 能否讀取、修改、提交指定儲存庫。
- 建置層： 目標 Mac 是否能執行
xcodebuild，並找到正確 Scheme 與 SDK。 - 交付層： 是否具備 Simulator、實體裝置、Provisioning Profile、簽名憑證及必要權限。
Apple 文件指出，缺少有效的簽名憑證會造成建置錯誤；macOS 軟體若要發佈，還涉及 Archive、Export、簽名與公證流程。(Apple Xcode 建置設定參考) 所以，沒有 Xcode 的通用 Linux 或 Docker 環境可以協助產生程式碼，卻不能被當成完整的 Apple 驗收節點。
經驗： 如果你的流程要求「Agent 修改後直接產出可安裝的 iOS App」，請先在目標 Mac 上手動完成一次 Archive 與測試，再把同一套命令交給 OpenHands。否則你測到的只是安裝成功，不是交付成功。
第三步：把重建成本納入部署設計
OpenHands 的自訂 Sandbox 支援把額外的語言、系統套件與工具預先放入自訂映像。官方文件示範以 Debian 為基礎建立映像，再透過 SANDBOX_BASE_CONTAINER_IMAGE 指定它。(OpenHands 自訂 Sandbox 指南)
你可以用以下流程減少每次任務重建：
- 列出專案固定需要的語言、編譯器、套件管理器與 CLI 工具。
- 把不常變動的系統依賴寫入自訂 Dockerfile。
- 把應用程式依賴鎖定在 Lockfile，而不是每次使用最新版。
- 將可安全共用的快取放進命名卷，但不要把整個工作區與憑據一起共用。
- 為 OpenHands、Agent Server 與 Sandbox 映像保留可回退的版本標籤。
- 用一個真實儲存庫重新執行安裝、測試與提交，確認快取沒有掩蓋環境缺失。
本機的優勢在於快取通常已經存在，重跑任務比較方便；雲端環境的優勢則是可以建立標準映像，讓新成員或新節點依同一份設定啟動。對平台工程師而言，後者通常比「某位開發者的 Mac 剛好能跑」更容易維護。
實作驗收：先做短週期，再決定長期方案
建議你不要一開始就採購或固定長租，而是用同一個真實儲存庫做對照測試。
第一步：定義任務邊界。
指定一個可以回滾的分支，限制 Agent 可讀寫的目錄，並移除不必要的生產憑據。
第二步：驗證本機啟動。
依照 OpenHands 官方本機設定文件啟動，確認 Docker Desktop、工作區掛載、網頁介面與基本命令都正常。
第三步：記錄持續運行行為。
不要只記錄首次啟動；要觀察你鎖定螢幕、切換使用者、讓 Mac 進入睡眠或重啟 Docker 後，任務是否能恢復。這些是實際系統監控記錄，不應用想像的資源數字代替。
第四步：驗證隔離。
檢查 Agent 能讀到哪些檔案、能否存取不必要的網路服務、是否能看到宿主機環境變數，以及掛載目錄是否可以被意外刪除。
第五步：驗證並發。
至少建立兩個不同工作區，使用不同分支與測試連接埠，並同時執行一個安裝依賴、一個測試任務。若兩個任務互相影響，就不要以「再提醒 Agent 小心一點」當作解法。
第六步：驗證 Apple 工具鏈。
在有 Xcode 的目標 Mac 上執行建置、Simulator 測試、必要的簽名檢查；若流程涉及實體裝置，也要實際連線一次。通用容器能通過單元測試，不代表能完成這一層驗收。
第七步：比較維護責任。
把 Docker Desktop 更新、映像重建、憑據輪替、日誌保留、遠端連線與故障恢復列成清單。若這些工作已經超過你可接受的日常維護量，才有理由把任務移到獨立雲端 Mac。
需要安排遠端節點時，也應先確認服務條款、交付方式與帳號責任；SSHMac 的服務條款頁面可作為你檢查使用限制與責任範圍的入口。
最終選擇：本機、雲端，還是混合部署
你可以用這個簡化規則做最後判斷：
- 選本機 Mac： 只有一位使用者、任務低頻、能接受本機被占用，而且不需要長時間遠端在線。
- 選本機專用 Mac： 你想保留 Apple 工具鏈，但不希望 Agent 影響日常開發機；並發量仍然有限。
- 選獨立雲端 Mac： 需要多人共用、持續運行、遠端連線、權限隔離或可重複交付。
- 選混合方案： 一般程式碼修改放在標準化遠端環境，Apple 專案則交由具備 Xcode、Simulator、簽名與實體裝置條件的 Mac 節點驗收。
對多數獨立開發者而言，合理路徑是先在本機完成一次真實倉庫的短週期試跑；對小型團隊而言，則應在任務開始並行或需要夜間執行前，切換到獨立環境。若你還不確定應採用哪一種連線與交付方式，可先查看 SSHMac 的繁體中文幫助中心，再把驗收結果交給團隊討論。
FAQ：部署前最容易漏掉的四個判斷
OpenHands 可以直接部署在 Mac 上嗎？
可以。官方文件列出 macOS 與 Docker Desktop 的本機部署方式，OpenHands 也能透過 CLI 將目前工作目錄掛載到沙箱。不過，能啟動不代表適合長期運行；若你的 Mac 同時是日常開發機，還要評估本機被占用、睡眠中斷、檔案掛載與憑據暴露等風險。
OpenHands 本地部署和雲端部署，哪一種比較好？
低頻、單人、只修改一般程式碼時，本地部署通常較快開始；多人共用、需要持續在線、遠端存取或要隔離生產憑據時，獨立雲端 Mac 更合適。若涉及 iOS 或 macOS 專案，真正的判斷標準不是 OpenHands 能否修改 Swift，而是同一環境能否完成 Xcode 建置、模擬器測試與簽名驗收。
OpenHands 跑多個 Agent 需要什麼環境？
多個 Agent 不應只共用一個工作目錄與一個未管理的 Docker Runtime。至少要分開工作區、連接埠、依賴快取與權限範圍，並為每個任務保留可追蹤的日誌。獨立開發者可先用本機專用環境，小型團隊則應改用專機或遠端環境，避免互相覆寫檔案。
OpenHands 如何處理 iOS 和 macOS 專案？
OpenHands 可以協助修改 Swift、整理專案檔案與執行命令，但通用 Docker 沙箱不能取代完整的 macOS、Xcode、Simulator、簽名憑證與實體裝置驗收鏈路。部署前應在目標 Mac 上執行一次真實建置與測試；若 Agent 執行環境沒有可用 Xcode，就只能把它視為程式碼處理環境，而不是完整交付環境。
從目前方案轉到 Mac 方案，先算故障半徑
如果你目前把 OpenHands 長期放在日常本機上，真正的缺點通常不是首次安裝，而是本機被持續占用、睡眠或重啟造成任務中斷、多人共享時缺乏工作區隔離，以及生產憑據與個人檔案共處同一台裝置。若目前使用的是沒有完整 Xcode 工具鏈的通用環境，還會在最後的 Apple 驗收階段被迫搬移專案。
因此，若你只是偶爾試用，本機部署仍是合理選擇；若需要臨時算力、遠端在線、團隊協作或獨立的 Apple 驗收環境，使用 SSHMac 租用 Mac 會比把日常工作機硬改成長期 Agent 伺服器更容易控制。先用真實倉庫完成短週期驗收，再依並發量、在線時間與 Xcode 結果決定續用本機、固定雲端 Mac，或保留兩者的混合配置，通常比一開始按理論規格長期採購更穩妥。