電腦一休眠，Agent 任務就停；本機又不確定會讀到哪些檔案。
最快解法：個人首次試用選桌面預覽版或 npx；要限制檔案邊界選 Docker；要常駐、共享或使用較強資源，就讓 Canvas 連接遠端後端。
OpenHands Agent Canvas 安裝不應只看「哪個按鈕最容易按」。你需要先分清楚三個位置：Canvas 是操作介面，後端負責接收任務，而真正執行程式與讀寫檔案的是活動後端所在的環境。官方截至 2026 年 9 月 6 日仍將 macOS、Windows 與 Linux 桌面應用程式標示為早期預覽；安裝命令、支援方式及版本狀態應以官方安裝頁為準。
你適合看這篇，如果你：
- 想快速完成第一次試用，但不熟悉 Node.js、npm 或 uv 環境。
- 需要限制 Agent 可讀寫的本機專案範圍，正在考慮 Docker。
- 正在替團隊規劃一個可持續執行、可恢復且方便共享的後端。
先按使用場景選方案
下表不是功能清單，而是把「Agent 在哪裡跑、能碰到什麼、停止後會怎樣」放在同一個決策面上。評分是部署決策評分，5 分代表更適合該列場景，不是官方效能測試。
| 使用場景 | 建議方案 | Agent 執行位置 | 可存取範圍 | 停止或斷線後的狀態 | 隔離／維運評分 |
|---|---|---|---|---|---|
| 第一次看介面、執行最小任務 | 桌面預覽版 | 桌面版連線的活動後端 | 由後端權限決定 | 前端關閉不等於後端任務保留 | 上手 5／隔離 2 |
| 已有 Node.js、想快速試跑 | npx | 本機或指定後端 | 取決於啟動位置及工作區 | 終端機結束可能中斷前端或服務 | 上手 4／隔離 2 |
| 固定專案目錄、需要可重建環境 | Docker | Docker 容器內的後端 | 僅限明確掛載的路徑，但仍受容器設定影響 | 使用卷可保留設定與專案資料 | 上手 3／隔離 4 |
| 長任務、跨裝置接續 | 遠端 VM／伺服器 | 獨立遠端主機 | 由遠端工作區、帳號和網路規則決定 | 可在後端持續，但須配置保活及恢復 | 上手 2／隔離 4 |
| 團隊共用與異質工具鏈 | 分池的遠端後端 | 按任務配置 Linux 或 macOS 環境 | 依團隊權限和工作區分隔 | 可集中管理任務、紀錄和環境 | 上手 2／維運 5 |
這個表格也說明了桌面版的真正優勢：它降低啟動步驟，不是自動增加執行隔離。Agent Canvas 的架構文件把用戶端、後端與執行環境分開描述，部署前應先核對官方架構說明，不要因為看到桌面視窗，就假設本機檔案已經被沙盒保護。
個人首次試用：先追求可驗證，不要先追求完整部署
若你的目標只是確認 Agent 能否接收任務、修改一個測試檔案並回報結果，桌面預覽版通常是最短路徑。你不需要先把所有團隊權限、反向代理和長期儲存都配置好；但你仍須知道它連到哪個後端，以及最小任務會在哪裡執行。
可依以下順序驗收：
- 由官方安裝頁取得目前的桌面預覽版方式，先確認你的作業系統仍在官方列出的支援範圍內。
- 開啟 Canvas 後，確認目前連線的後端端點或連線狀態；若畫面只顯示用戶端已啟動，不代表 Agent 後端已可用。
- 建立一個全新的測試目錄，只放入一個簡單程式檔和 README，不要直接選含有 SSH 金鑰、環境變數或客戶資料的工作區。
- 提交最小任務，例如要求 Agent 讀取 README、建立一個測試檔，再說明它實際修改了什麼。
- 關閉 Canvas 後重新開啟，確認工作區變更是否仍在；若任務中途關閉終端機或前端便消失，就把它視為非常駐方案。
- 檢查 Git 差異、檔案權限和產生的命令紀錄。能完成任務，不代表可以安全地把同一權限交給長期工作區。
如果你的電腦沒有 Node.js，桌面版的價值就在於少處理一層命令列前置工作；改用 npx 或 npm 時，則要按照Node.js 官方套件管理說明準備環境。不要自行猜測 Node.js 版本或把網路文章中的命令直接混用，因為 Agent Canvas 的安裝頁和發行版本可能改變啟動方式。若你在啟動階段遇到帳號、連線或環境設定問題，也可先查閱 SSHMac 的說明中心，把本機安裝問題與遠端服務問題分開排查。
提醒： 桌面應用程式是 Canvas 用戶端，不等於隔離執行環境。真正的風險取決於後端使用哪個作業系統帳號、掛載哪些資料夾，以及 Agent 能否執行具破壞性的命令。
本機專案與 Docker：檔案邊界比介面便利更重要
本機直接開啟工作區，最大的隱性成本不是安裝時間，而是權限繼承。若後端以你的使用者身分執行，Agent 可能看見超出專案需要的路徑；即使它目前只修改程式碼，也不能把「目前沒有讀取」當成「永遠不能讀取」。
Docker 適合這類需要明確界線的情況：你可把特定專案目錄掛載進容器，把設定或工作資料放入持久化卷，並以相同啟動流程重建環境。官方的Agent Canvas Docker 指南與Docker 卷儲存文件是設定掛載和資料保留時應優先核對的來源。
但容器不是完整租戶隔離。你仍要驗收：
- 容器內是否只能看到預期的專案目錄，而不是整個家目錄。
- 工作目錄是唯讀還是可寫；需要編譯、測試或產生檔案時，哪些路徑必須開放寫入。
- 設定、模型憑證與任務紀錄放在哪個卷；容器刪除後是否仍存在。
- Docker socket、特權模式、額外 Linux capability 和網路出口是否真的必要。
- 其他團隊成員能否透過同一憑證讀取不應共享的工作區。
Docker 官方安全文件指出，容器安全仍受守護程式、權限和主機配置影響；因此不要把「容器可啟動」直接等同於「程式碼已安全隔離」。
遠端後端：把休眠、斷線和恢復列入設計
當任務需要長時間執行，或你要在辦公室電腦、家中筆電之間接續工作，Canvas 前端與後端分離會比把所有東西綁在本機更合理。此時 Agent 在遠端 VM 或伺服器執行，工作區也位於遠端；你本機只負責開啟 Canvas、提交任務和查看結果。
遷移到遠端前，至少要完成五項檢查：
- 先在遠端主機建立專用使用者和工作目錄，不要直接沿用主機管理員帳號。
- 依官方VM 自託管部署說明啟動後端，確認服務可以在內部網路中連線。
- 配置任務保活、重啟策略及持久化資料，然後刻意關閉本機 Canvas，確認後端任務是否仍會繼續。
- 若需要從公網存取，加入認證、TLS、來源網路限制和最小暴露端口；不要把未驗證的後端直接暴露在公網。
- 以一個可中斷的測試任務驗收恢復：斷開本機網路後重新連線，檢查任務狀態、工作區變更和錯誤紀錄是否仍可追溯。
遠端後端不是單純「把本機搬到雲端」。它會新增憑證管理、頻寬、儲存、成本和網路故障等維運責任；只是對長任務與跨裝置使用而言，這些責任通常比電腦休眠造成的任務中斷更容易制度化。
團隊方案要拆開介面、後端與執行環境
團隊經常把「共用 Canvas」誤當成「共用一個後端」。實際上至少有三層需要分開決策：
- 共用介面： 成員是否可以使用相同的 Canvas 連線方式。
- 共用後端： 任務佇列、憑證、工作區和紀錄是否由同一套服務管理。
- 共用執行環境： Agent 是否真的在同一個檔案系統、同一組工具鏈和同一個權限範圍內工作。
一般 Linux 程式碼任務可以集中到一組可重建的環境；需要 Xcode、Apple SDK、簽署工具或其他 macOS 工具鏈的任務，則應按執行要求分到 macOS 環境，不要只因為 Canvas 介面相同，就假設兩邊可以互換。若你正在比較遠端 Mac 執行條件，可先參考 SSHMac 的遠端 Mac 使用入口，再按實際工具鏈、檔案傳輸和權限需求驗證。
團隊驗收應以三個問題為核心：成員能否只看到被授權的專案？任務中斷後誰能接手？新成員能否依固定設定重建相同環境？若三個答案都不清楚，先不要把桌面預覽版當作團隊平台。
用條件分支決定下一步
- 若你只想在個人電腦完成一次最小任務，則選桌面預覽版；若桌面版無法使用，回退到 npx 或 npm，並按官方頁面準備 Node.js。
- 若Agent 必須修改本地專案，而且你可以明確列出允許存取的目錄，則選 Docker；若專案需要大量本機硬體或特殊工具鏈，回退到受控的本機方案，但要先檢查權限。
- 若電腦會休眠、終端機不會長期開啟，或任務要跨裝置接續，則選遠端後端；若任務只需短時間互動，才保留本機執行。
- 若團隊需要共享任務與環境，則選遠端後端加分離工作區；若每個人有不同工具鏈，回退到按 Linux、macOS 等執行要求分池。
- 若要從公網連線，則先完成認證、TLS、網路限制和恢復測試；若只能靠公開端點加一組弱密碼，回退到私有網路或 VPN 方案。
FAQ：安裝前最容易忽略的五個判斷
OpenHands Agent Canvas 桌面版和 Docker，最主要的差異是什麼？
桌面版主要降低首次啟動門檻，Canvas 用戶端仍要連到活動中的後端，且不代表自動取得沙盒隔離。Docker 則可把後端和指定工作目錄放入可重建的容器，但掛載路徑、權限與持久化卷仍需由你明確設定；兩者不是單純的介面版本差異。
Agent Canvas Desktop App 需要先安裝 Node.js 嗎？
若你使用官方提供的桌面預覽版，通常不必把 Node.js 當作第一個前置步驟；若改用 npx 或 npm，則要依官方安裝頁準備相容的 Node.js 環境。桌面版減少的是啟動工作，不是把後端、模型憑證或專案權限一併自動配置好。
OpenHands 在本機安裝，怎樣判斷是否足夠安全？
先確認 Agent 實際在哪個後端執行，以及它能讀寫哪些路徑。本機直接啟動時，Agent 可能沿用你的使用者權限；如果專案含有憑證、個人資料或不可逆腳本，應改用限制掛載目錄的 Docker，並另外檢查容器權限與網路出口。
什麼情況下應該改用 Agent Canvas 遠端後端？
當任務需要跨裝置接續、長時間執行、團隊共同使用，或本機會休眠、終端機會關閉時，遠端後端通常更合適。你仍可在本機使用 Canvas 作為介面，但應為遠端主機配置認證、TLS、網路限制、持久化與任務恢復機制。
桌面版可以連線到團隊自託管的後端嗎？
可以把 Canvas 用戶端與活動後端分開判斷；是否能連線，取決於官方版本提供的後端設定、網路可達性與認證配置，而不是桌面程式本身。部署前先依官方連線文件驗證端點，再確認團隊成員的權限、工作區範圍及憑證不會被共用。
把方案從本機試用升級到可持續環境
桌面預覽版適合確認流程，卻有早期預覽、權限沿用和本機休眠等限制；直接 npm 或 npx 啟動則多一層 Node.js 維護，終端機結束時也可能影響操作；Docker 的檔案邊界較清楚，但仍要自行管理卷、主機安全和工具鏈。若你需要臨時算力、跨裝置接續，或想先驗證遠端 Agent 工作流，SSHMac 的遠端 Mac 環境會比把長任務綁在個人電腦更容易維持；涉及 Apple 工具鏈時，則應先核對 macOS 版本、SDK、簽署和檔案權限是否符合任務。
最後更新於 2026 年 9 月 6 日；資料核實自 Agent Canvas 官方安裝、架構、Docker／VM 後端文件及 1.16.0 發布說明。官方若改變桌面版預覽狀態、支援架構、安裝命令或後端連線方式，應重新按本文的最小任務與中斷恢復步驟驗收。