OpenHands Agent Canvas 遠端 VM 部署：2026 自托管教學

本地電腦一進入睡眠，OpenHands 長任務就中斷，重新連線後還要猜測工作目錄與執行狀態。

最快解法：把 OpenHands Agent Canvas 部署到獨立、可重建的遠端 VM，先用 SSH 隧道或私網驗收，再補上 API Key、TLS、進程保活與沙盒隔離；只有需要 Xcode 或其他 macOS 工具鏈時，才增加遠端 Mac。

這篇適合三類讀者：經常因筆記本休眠而失去長任務的獨立開發者、要替團隊提供共享 Agent 後端的平台與 DevOps 工程師，以及準備處理 macOS、Xcode 或跨平台建構工作的研發負責人。

最後更新於 2026 年 8 月 14 日；本文命令、架構與可公開存取方式已核對 OpenHands 官方自托管指南、官方 README 與 Agent Canvas 儲存庫。

先把執行邊界放對位置

OpenHands Agent Canvas 的前端不是執行 Agent 動作的地方。官方架構中，Canvas 負責介面、工作階段狀態與後端切換；真正讀寫檔案、執行 Shell 指令和連接網路的是 Agent Server。Automation backend 則處理排程或事件觸發的自動化工作。(github.com)

因此，你的主機至少可能承擔三種不同邊界：

1. 控制服務：提供 Canvas 介面、Agent Server 與自動化服務。
2. 程式建構環境：讓 Agent 讀取倉庫、安裝相依套件、執行測試與編譯。
3. 外部沙盒連線點：把高風險或不可信任的工作交給 Docker 沙盒或其他隔離環境。

個人開發機把三者混在一起，隱性成本不只是休眠中斷，還包括未提交檔案遺失、SSH 工作階段依賴、個人憑證被 Agent 讀取，以及不同專案共用同一個環境。獨立 VM 的優勢是可以重建、限縮權限、單獨備份，而且不會因你合上螢幕而停止。

一般 Linux 程式碼分析、Web 服務測試、後端建構，優先放在 Linux VM。Xcode、Apple SDK、模擬器、簽名和 macOS 原生測試，才應規劃遠端 Mac 節點。

第一階段只在私網跑通最小服務

官方自托管路徑使用 Node.js 與 uv 啟動完整堆疊。官方 README 目前列出的前置條件是 Node.js 22.12.x 或更新版本，以及 uv；Ubuntu 範例則先安裝 curl 和 git。(github.com)

在乾淨 VM 上，先完成以下步驟：

1. 更新系統套件，安裝 curl、git、Node.js 和 uv。
2. 以 SSH 登入，確認專案所在目錄與執行帳戶不是管理員帳戶。
3. 產生獨立 API Key：

export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32)

1. 啟動公開模式：

npx @openhands/agent-canvas --public

1. 不要立即開放公網，先建立 SSH 隧道：

ssh -N -L 8000:127.0.0.1:8000 user@your-vm

完成後在本機瀏覽器開啟 http://localhost:8000，先驗證四項證據：

• Canvas 介面可以載入；
• Agent Server 顯示在線；
• 指定倉庫可以讀取；
• 提交一個短任務後，事件、輸出和狀態能持續返回。

官方自托管架構會以本機的 ingress proxy 統一轉發前端、Agent Server 和 automation backend；文件列出的內部服務連接埠包括 8000、18000、18001 和 3001。這些不是你應直接暴露到公網的連接埠。(github.com)

用配置對比決定隔離程度

你不應只問「能否啟動」，而要先判斷 Agent 是否會接觸敏感資料。官方也明確提醒：直接執行時，Agent 能夠存取主機檔案系統、環境和網路；Docker 沙盒則把可存取範圍收窄到你掛載的專案目錄。(github.com)

表格中的評分是部署決策評估，不是官方效能測試；真正的風險取決於你掛載的目錄、可用憑證、網路規則及 Agent 所執行的任務。

首次任務完成後再做權限加固

第一次任務不要使用正式專案的全部權限。建立一個專用工作目錄，只把必要倉庫放入其中，並分開處理以下資料：

• LLM 或第三方服務的 API Key；
• Git 認證與 SSH 私鑰；
• 雲端供應商憑證；
• 內部網路連線資訊；
• .env、部署密鑰及正式環境設定。

LOCAL_BACKEND_API_KEY 應只存在服務環境或受限權限的設定檔，不要寫入公開倉庫、前端靜態檔案、Shell 歷史或一般使用者可讀的除錯日誌。啟用 --public 後，使用者需要在介面輸入金鑰，API 呼叫則會帶上相應的工作階段標頭；這是入口保護，不代表 Agent 已經完成沙盒隔離。(github.com)

接著做三組負面測試：

1. 讓 Agent 嘗試讀取工作目錄以外的檔案，確認是否被拒絕。
2. 使用錯誤 API Key 發送未授權請求，確認不會取得工作階段資料。
3. 讓 Agent 執行刪除、安裝或網路探測類指令，確認主機權限、容器邊界和日誌都有可追溯結果。

如果你使用 Docker 沙盒，仍要審查 PROJECTS_PATH 的掛載範圍。掛載整個家目錄會抵銷隔離價值；只掛載必要專案，並讓工作目錄與服務帳戶的檔案擁有者一致。

公網接入要同時完成 TLS 與保活

私網驗收通過後，才進入公開存取階段。官方指南的公開模式是由 nginx 接收 HTTPS，再轉發到主機本機的 ingress proxy；因此對外通常只需要讓反向代理處理 HTTPS，而不是直接公開 Agent Server 或 automation backend。(github.com)

上线前按以下順序處理：

1. 把網域解析到 VM，確認 DNS 已指向正確主機。
2. 防火牆只允許你的管理來源連入 SSH。
3. 由反向代理接收 443；若使用自動憑證流程，再按需要處理 80。
4. 將代理流量轉發到 127.0.0.1:8000。
5. 啟用長連線轉發，避免即時事件或 Socket 連線被代理提早切斷。
6. 確認 LOCAL_BACKEND_API_KEY 不會出現在代理存取日誌。
7. 設定 systemd、容器重啟策略或其他進程管理工具。

短期測試可以用 tmux：

tmux new-session -d -s canvas \
  'npx @openhands/agent-canvas --public'

長期服務則可使用 systemd，核心設定至少包含開機啟動、失敗後重啟及重啟間隔：

[Service]
Environment=LOCAL_BACKEND_API_KEY=請填入受限權限的金鑰
ExecStart=npx @openhands/agent-canvas --public
Restart=on-failure
RestartSec=5

驗收不應只看首頁能否開啟，還要測試即時事件連線、服務日誌輪轉、SSH 斷開後任務是否繼續、VM 重啟後服務是否自動恢復，以及 TLS 憑證續期是否成功。

把遠端後端加入本地 Canvas

如果你仍想在本地使用介面，可以把 VM 註冊成額外後端。官方流程是在本地 Canvas 的後端管理介面新增主機名稱、遠端 URL 和 Session API Key；若走 SSH 隧道，主機 URL 可指向本機的 http://localhost:8000，若已配置反向代理，則使用 HTTPS 網域。(github.com)

切換後，請用一個測試倉庫核對：

• 工作目錄是否位於遠端 VM，而不是本地路徑；
• Agent 設定和模型配置是否屬於正確後端；
• 任務記錄是否寫入預期環境；
• Git 分支、未提交檔案和相依套件是否一致。

後端切換不等於自動同步本地未提交程式碼。你需要先提交並推送 Git，或採用明確的檔案傳輸流程；否則你在本機看見的檔案，遠端 Agent 根本不一定讀得到。

如需進一步處理共享環境，可先參考 SSHMac 的幫助中心，再按團隊的連線與權限規範調整部署方式。

FAQ：部署前後最容易卡住的判斷

Agent Canvas 可以放在雲端伺服器嗎？

可以，但「可安裝」和「適合直接公開」是兩回事。雲端 VM 適合作為長期執行的 Agent Server，前提是先限制防火牆、只在本機綁定內部服務，再透過 SSH 隧道或 TLS 反向代理提供入口。首次測試不應跳過私網階段。

怎樣避免 SSH 斷線後任務停止？

SSH 只應是管理通道，不應是服務生命週期。tmux 適合快速驗證，正式環境應改用 systemd 或等效進程管理工具，並以 Restart=on-failure、開機啟動和日誌檢查確保服務恢復。最後要實際斷開 SSH，再觀察任務事件是否仍然返回。

Agent Server 要開哪些連接埠？

初次驗收只開受限來源的 SSH。Agent Canvas 官方自托管架構把內部服務放在本機連接埠，包含 ingress、Agent Server、automation backend 和靜態前端；正式公開時，應由反向代理接收 HTTPS，而不是把這些內部連接埠全部加入雲端防火牆。

甚麼工作才需要遠端 Mac？

只要建構流程需要 Xcode、Apple SDK、iOS 模擬器、簽名或 macOS 原生命令列工具，就應考慮遠端 Mac。單純的 Python、Node.js、Java、Go、Web 測試與一般後端工作，通常留在 Linux VM 更容易做版本固定、權限隔離和故障重建。

公網開放 Agent Canvas 的最低安全線是甚麼？

最低安全線包括獨立 API Key、public mode、網路防火牆、HTTPS、反向代理、受限工作目錄和可追溯日誌。若 Agent 能直接接觸正式憑證或整台主機，單靠登入頁並不足夠；你應改用 Docker 沙盒、專用帳戶或完全隔離的建構節點。

上線前用清單完成閉環驗收

以下清單要逐項勾選；未完成的項目不要直接進入團隊共用或正式倉庫：

• [ ] VM 可由你重建，且沒有依賴個人筆記本的本地檔案。
• [ ] 防火牆只允許受限 SSH、VPN 或必要的 HTTPS 來源。
• [ ] LOCAL_BACKEND_API_KEY 已獨立產生，未出現在公開檔案、前端或日誌。
• [ ] 首輪啟動已透過 SSH 隧道或私網完成。
• [ ] Canvas、Agent Server、倉庫讀取與任務事件均已驗證。
• [ ] Agent 只能存取指定工作目錄和必要環境變數。
• [ ] 已完成越權讀取、錯誤金鑰和危險命令測試。
• [ ] 反向代理已啟用 HTTPS，並正確轉發長連線。
• [ ] SSH 斷開後，任務仍能繼續執行。
• [ ] VM 重啟後，Agent Canvas 能自動恢復。
• [ ] 日誌輪轉、憑證續期和服務健康檢查已有負責人。
• [ ] 本地、遠端 VM 與專用建構節點的倉庫同步流程已寫清楚。
• [ ] 已用實際倉庫完成一次重啟恢復、並行任務與建構閉環。
• [ ] 只有在需要 Xcode 或 macOS 工具鏈時，才把任務路由到遠端 Mac。

目前方案與遠端 Mac 的取捨

如果你目前把 Agent Canvas 跑在個人電腦上，最明顯的問題是休眠會中斷長任務、個人憑證與 Agent 權限容易混在一起，而且同一台機器難以穩定承擔團隊共享工作。Linux VM 能先解決持續運行、重建和權限分層；但它無法取代 Xcode、Apple SDK、模擬器和 macOS 簽名環境。

因此，較合理的路線不是一開始就為所有任務配置 Mac，而是先完成最小 VM 部署，再按實際倉庫的工具鏈判斷。若你只需要遠端執行一般開發工作，Linux VM 已足夠；若你需要可持續運行的 Apple 建構節點，SSHMac 的遠端 Mac 環境會比把個人 Mac 長期留在辦公室、依賴睡眠設定或臨時遠端桌面更容易維持。你可以先從 SSHMac 的遠端環境入口 核對連線方式，再決定是否增加 macOS 節點，而不是把所有 Agent 任務一次搬過去。