OpenHands Agent Canvas 安裝教學：四種裝法怎麼選、Windows 怎麼裝、哪些設定要先開

先看這段：預設裝法沒有沙箱

裝之前有兩件事要先知道，因為它們都是預設值，你不去改就會一直是這樣。

第一，用 npm、npx 或桌面版直接裝，agent 沒有被關起來。 官方 README 寫得很直白，這種裝法下 agent 可以存取你整台電腦的檔案。Agent Canvas 本身只是操作畫面，不負責隔離，要不要隔離取決於你選的執行方式。

第二，「危險動作先問你」預設是關的。 設定裡有一個 Confirmation mode，沒打開的話，agent 要跑什麼指令都不會先停下來問。

兩件事疊在一起，就是一個會自己跑指令、而且不會先問你的 agent，直接在你的電腦上工作。所以這篇的建議很簡單：第一次試用 Docker 版；真的要用 npm 或桌面版，裝好第一件事就是去把確認模式打開，後面「沙箱與權限」那段會講怎麼開。

如果你還不知道 OpenHands 是什麼，可以先看 OpenHands 入門介紹。

Agent Canvas 是什麼，跟舊版差在哪

Agent Canvas 是 OpenHands 在 2026 年 6 月推出的新介面，到 10 月 GitHub 主 repo 已經整個換成它的程式碼，目前版本是 1.25，狀態還標 beta。

你在網路上看到的舊教學，多半是這兩種：

uv tool install openhands 再執行 openhands serve，在瀏覽器開 localhost:3000。

用 docker.openhands.dev/openhands/openhands 這個映像檔跑。

這些都是舊版本機介面，官方已經標成 Legacy，進入維護模式，只修重大問題和漏洞、不加新功能。還能用，但新功能只會出現在 Agent Canvas，像是排程自動化、接 Claude Code 和 Codex 這些。

兩者也不能混著用。只裝了 Agent Canvas 的話，openhands serve 是跑不起來的。

四種裝法怎麼選

裝法	適合誰	有沒有隔離
桌面版	不想碰終端機的人	沒有
npm	已經有 Node.js、打算常用的人	沒有
npx	只想先開起來看看的人	沒有
Docker	第一次試、或要接真的專案的人	有，只看得到你掛進去的資料夾

桌面版最省事。到 OpenHands 的 GitHub Releases 頁面下載對應的安裝檔，Windows 是 OpenHands-Agent-Canvas-Setup-1.25.0.exe，macOS 是 OpenHands-Agent-Canvas-1.25.0-universal.dmg，Linux 有 .AppImage 和 .deb。安裝檔已經包好 Node.js 和 uv，不用另外裝。Windows 上可能會跳 SmartScreen 警告，那是因為新軟體還沒累積信任度，確認是從 OpenHands 官方 GitHub 下載的再按繼續。

npm 要先準備 Node.js 24 以上和 uv，然後：

npm install -g @openhands/agent-canvas
agent-canvas

啟動後在瀏覽器開 http://localhost:8000。要換 port 就加 --port，例如 agent-canvas --port 8080。

npx 不安裝，直接跑一次：

npx @openhands/agent-canvas

npm 和 npx 有一個共同點：關掉終端機，它就停了。只是想試試沒關係，但如果之後要讓它定時做事，就得放在一台一直開著的電腦上。

Docker 需要先裝好 Docker Desktop 並開著。它會把 agent 關在容器裡，只看得到你指定的專案資料夾，這也是我建議第一次試的方式。如果你還不熟 Docker，可以先看 Docker 是什麼。

Windows 實裝：用 PowerShell 就好

Windows 上 npm、npx、Docker 三種都能直接在 PowerShell 跑，不需要另外裝 WSL。

用 Docker 版的話，先在 PowerShell 建兩個資料夾，一個放設定、一個放專案：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openhands", "$env:USERPROFILE\projects" | Out-Null

接著啟動容器：

docker run -it --rm `
  -p 127.0.0.1:8000:8000 `
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true `
  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
  -v "$($env:USERPROFILE)\projects:/projects" `
  ghcr.io/openhands/agent-canvas:latest

幾個要注意的地方：

PowerShell 的換行符號是反引號（` ``），不是 macOS、Linux 教學裡的反斜線，直接複製別人的指令常常就卡在這裡。

127.0.0.1:8000:8000 這個寫法是讓只有你自己的電腦連得到。網路上有些教學寫 -p 8000:8000，那樣同一個網路裡的其他電腦也可能連進來，不建議。

Docker 版要開的網址是 `http://localhost:8000/canvas`，後面多一個 /canvas，只開 :8000 會看不到畫面。

你要讓 agent 處理的專案，要放進 使用者資料夾\projects 底下，容器裡只看得到這裡。

另外兩個 Windows 才會遇到的狀況：

想讓「每個對話各開一個獨立容器」（指令是 OH_CONVERSATION_RUNTIME=docker agent-canvas），這種進階用法在 Windows 上必須在 WSL 2 裡跑，PowerShell 不行。一般人用上面的單一容器就夠了。

解除安裝時如果出現 uv.exe 被占用、刪不掉，先把所有終端機視窗關掉再試一次。

第一次開起來：四步設定精靈

第一次打開會跳出設定精靈，總共四步，每一步都能先跳過：

第一步，選 agent。 預設是 OpenHands 自己的 agent，也可以選 Claude Code、Codex 或 Gemini CLI。第一次建議用預設的，想接別家 agent 可以之後再看 OpenHands 接 Claude Code、Codex 的教學。

第二步，確認後端有連上。 預設位址是 http://127.0.0.1:8000，看到「You're connected!」就代表沒問題，通常不用改。

第三步，接模型。 可以自帶 API key（Anthropic、OpenAI、Google 都行），也可以填 OpenHands Cloud 的 key 用官方提供的模型。官方目前推薦的是 Claude 系、GPT 系最新的大模型。想接本機的 Ollama 或 LM Studio 也可以，但官方自己提醒，本機模型常常不會正確使用工具，用起來會像普通聊天機器人，第一次不建議。

第四步，選一個自動化範本。 例如 GitHub PR 審查、repo 監控、Slack 站會摘要。第一次建議先跳過，等你熟悉 agent 怎麼做事之後，再看 OpenHands 自動化教學。

精靈走完，側邊欄會有一個 Getting Started 清單帶你繼續，不需要的話可以在 Settings > Application 關掉。

要開始第一個對話之前，先點 Open Workspace 選專案資料夾。Docker 版只能選 projects 底下的資料夾。

沙箱與權限：這幾個設定先處理

裝好、還沒開始用之前，花五分鐘處理這幾件事。

打開確認模式。 到 Settings > Verification，把 Confirmation mode 打開。打開後還要選一個 Security analyzer：

選 llm（預設）：由 AI 判斷哪些動作有風險，只有它覺得高風險的才會停下來問你。

選 none：每一個動作都要你按確認，比較煩，但最保險。

第一次用、又不是在 Docker 裡跑，我會選 none，先看清楚它到底會做哪些事，熟了再改回 llm。

不要讓別台電腦連進來。 npm 和 npx 版預設只開給自己的電腦，啟動參數裡有 --host 0.0.0.0 或 --public 這類選項，那是開給整個網路的，沒有特別需求不要加。

API key 放在 Secrets。 要給 agent 用的 GitHub token、各種 API key，放在 Settings > Secrets 統一管理，不要直接貼進對話裡。給 GitHub 的 token 用 fine-grained 類型，只勾你要開放的 repo。

設定存在哪裡要知道。 設定、密鑰和對話紀錄都存在使用者資料夾的 .openhands 裡。解除安裝 Agent Canvas 不會刪掉這個資料夾，要清乾淨得自己刪。

想更完整地檢查一個開源 AI 工具安不安全，可以參考開源 AI 工具安全檢查清單。

舊版使用者怎麼搬過來

如果你之前用 openhands serve 或舊的 Docker 映像檔，好消息是不太需要手動搬。

官方的說法是，Agent Canvas 會從同一個 .openhands 資料夾讀取大部分的設定和舊對話。照上面任一種方式裝好 Agent Canvas，打開之後檢查一下模型設定和 API key 有沒有帶過來就好。

舊版不用急著刪。官方說舊的本機介面會繼續維護，直到 Agent Canvas 有完整的隔離沙箱為止，目前沒有給具體日期。舊 CLI 的終端機介面，官方只承諾維護到 2026 年 10 月 1 日，之後隨時可能停止更新，還在用的話可以趁現在換。

確認新版的設定和對話都帶過來、用起來沒問題之後，舊版就可以停掉了。

裝好之後先做什麼

開一個測試專案，或是你不怕被改壞的練習 repo，放進 projects 資料夾，給它一個小任務，例如「讀一下這個專案，告訴我它在做什麼」，再試「幫我補一個簡單的測試」。

過程中看它跑了哪些指令、改了哪些檔案。確認模式開著的話，每次它要動手你都會看到，這是最快建立判斷感的方式。

模型先用便宜的，並且到模型供應商的後台設好用量上限。agent 會自己來回跑很多輪，帳單長得比聊天快很多，想知道大概會花多少，可以看 AI coding agent 一個月會燒多少錢。

我會這樣建議

如果你只想知道 Agent Canvas 好不好用，用 Docker 版、開確認模式、拿測試專案跑一個下午，就能判斷它適不適合你。

桌面版和 npm 版不是不能用，而是它們把「要不要隔離」這個決定交給你，而預設值剛好是最寬鬆的那個。用之前把確認模式打開，就能擋掉大部分意外。

等你確定它對你有幫助，再去研究自動化和接 Claude Code 這些進階功能，那時候你會比較清楚自己要它做什麼、不要它碰什麼。

資料來源

本文依 OpenHands 官方文件與 GitHub 整理，Agent Canvas 目前還在 beta，裝法、檔名與設定位置更新很快，安裝前請再確認官方頁面。

https://github.com/OpenHands/OpenHands
https://github.com/OpenHands/OpenHands/blob/main/README.windows.md
https://github.com/OpenHands/OpenHands/releases
https://docs.openhands.dev/openhands/usage/agent-canvas/setup
https://docs.openhands.dev/openhands/usage/agent-canvas/first-time-setup
https://docs.openhands.dev/openhands/usage/agent-canvas/customize-and-settings
https://docs.openhands.dev/openhands/usage/agent-canvas/troubleshooting
https://github.com/OpenHands/docs/issues/657