OpenHands 教學：安裝、模型設定與故障排除
OpenHands 是一個開源的軟體開發 AI Agent。和只在編輯器裡補完程式碼的工具不同，它可以在工作環境中讀取檔案、修改程式碼、執行終端機指令，再根據測試結果繼續處理任務。
這篇 OpenHands 教學以 2026-07-20 查核的官方文件為準，帶你完成本機安裝、模型設定、第一個任務驗證，以及最常見的 Docker 與權限問題。舊版常見的 ghcr.io/all-hands-ai/... 映像路徑已經過時，本文不再沿用。
開始前先確認適不適合
OpenHands 比較適合能被明確驗證的開發工作，例如：
- 閱讀既有 repository 並修正一個可重現的錯誤
- 新增小型功能，同時執行專案原有測試
- 分析失敗 log、修改設定，再重新驗證
- 整理重複程式碼或補上測試案例
它不是「把一句需求交出去就一定能安全完成」的黑盒子。Agent 會執行指令並修改掛載進去的檔案，因此正式專案最好先建立 Git branch、確認工作目錄沒有未保存變更，並避免把 production 憑證放進可讀取範圍。
如果你正在調整其他 coding agent 的執行方式，可以先看 AI Agent 如何從口頭回答走到可驗證的執行迴圈。那篇的「先蒐證、再修改、最後驗證」同樣適用於 OpenHands。
OpenHands 本機安裝需求
官方目前推薦透過 CLI launcher 啟動本機 GUI。準備項目如下：
- Docker Desktop 或 Docker Engine 已安裝並正在執行
docker ps能在終端機正常完成- Python 3.12 以上版本
uv套件工具；OpenHands 的預設 MCP server 也會用到它- 一組可用的模型 API Key，或已設定好的本機模型端點
Windows 原生終端機目前不在官方支援範圍內，必須先安裝 WSL，並在 WSL 終端機裡執行 OpenHands 指令。Docker Desktop 也要啟用 WSL 2 engine 與對應 distribution 的整合。
掛載目錄代表 Agent 可以修改檔案後面的
--mount-cwd會把目前資料夾交給 OpenHands。先執行git status，確認你知道哪些檔案可能被更動；初次測試也可以建立一個不含敏感資料的空白專案。
用官方建議的 CLI launcher 安裝
先依 uv 官方安裝說明 安裝 uv，再安裝 OpenHands：
uv tool install openhands --python 3.12切換到準備交給 Agent 的專案目錄，啟動 GUI 並掛載目前目錄：
cd /path/to/your-projectopenhands serve --mount-cwdlauncher 會檢查 Docker、下載需要的映像並啟動服務。完成後用瀏覽器開啟：
http://localhost:3000如果目前只想看介面、不想讓 OpenHands 讀取專案，可以先執行：
openhands serve日後更新 launcher，可使用：
uv tool upgrade openhands --python 3.12官方也提供直接執行 Docker 映像的方式，但映像名稱、agent server tag 與版本會隨發行更新。若你需要固定版本或部署到共用環境，請直接使用文末的官方 Local GUI Setup 指令，不要複製舊文章裡的 all-hands-ai 映像。
設定模型與 API Key
第一次開啟 OpenHands 時會顯示設定視窗，也可以從右上角齒輪進入 Settings → LLM。基本設定依序填入：
- 選擇
LLM Provider。 - 選擇該供應商的
LLM Model。 - 貼上對應的
API Key。 - 按下
Save Changes。
OpenHands 官方文件目前列出 OpenHands、Anthropic、OpenAI 與 Mistral 等已驗證供應商。模型清單和推薦會變動，因此不要把網路文章裡的舊模型名稱當成固定答案；以設定頁當下提供的選項和官方模型文件為準。
如果供應商或模型不在基本選單裡，開啟 Advanced 後可以填入：
Custom Model：需要包含 LiteLLM 使用的 provider 前綴Base URL：自架或相容 API 的端點API Key：該端點使用的金鑰
API Key 與費用多數雲端模型需要另外計費。先在供應商後台設定用量上限，並避免把 Key 寫進 repository、提示內容或終端機紀錄。OpenHands Cloud 的登入與 LLM Key 也有自己的計費條件，不能把網站帳號等同於無限模型額度。
本機模型不是只填 Ollama 網址就完成
OpenHands 的 Agent 需要模型穩定使用工具、遵循格式，並保有足夠長的上下文。官方文件也提醒，多數本機模型可能出現回覆慢、工具呼叫失敗或 JSON 格式錯誤。
因此，本機模型適合願意自行處理硬體、context length 與相容端點的人。若只是第一次驗證 OpenHands，先用官方已驗證的雲端模型通常比較容易分辨「安裝問題」和「模型能力問題」。
執行第一個可驗證任務
不要一開始就叫 Agent 重構整個系統。先用一個小而可驗證的任務確認檔案讀寫、指令執行與模型連線都正常，例如：
先讀取這個專案的 README 與套件腳本，不要修改檔案。告訴我使用哪個套件管理器、可執行哪些測試，並列出你讀過的檔案。確認結果符合 repository 後，再交付一個限定範圍的修改：
建立 hello-openhands.txt，內容只有 OpenHands is ready。完成後讀回檔案，並執行 git diff -- hello-openhands.txt 回報結果。不要修改其他檔案。最後在自己的終端機驗證：
git status --shortgit diff這個流程可以同時確認四件事：OpenHands 能看到掛載目錄、模型能呼叫工具、Agent 能建立檔案，而且實際變更沒有超出要求。
OpenHands 常見問題排查
顯示 Launch docker client failed
先確認 Docker daemon 真的可用：
docker ps若這個指令本身失敗，先啟動或修復 Docker，再重開 OpenHands。使用 Docker Desktop 時，官方也建議檢查 Settings → Advanced 的預設 Docker socket 選項；部分環境還需要啟用 host networking。
第一個任務就出現 Permission Denied
先檢查 OpenHands 狀態目錄與掛載專案的擁有者：
ls -ld ~/.openhandsls -ld /path/to/your-project如果 ~/.openhands 意外屬於 root，優先把擁有者改回目前使用者，而不是直接把整個目錄開成所有人可寫：
sudo chown -R "$(id -un)":"$(id -gn)" ~/.openhands專案目錄也必須讓執行 OpenHands 的使用者有必要權限。修改前先確認路徑，不要對家目錄或不明目錄遞迴套用權限。
Windows 能開介面，但指令或連線異常
確認所有 OpenHands 指令都在 WSL distribution 裡執行，而不是 PowerShell 或 Windows Command Prompt；再回到 Docker Desktop 檢查 WSL 2 engine 和 distribution integration 是否開啟。
舊教學的 Docker 映像拉不到
OpenHands 的 GitHub 組織已從 All-Hands-AI 改為 OpenHands。舊的 Git remote 和 ghcr.io/all-hands-ai/ 映像參照都可能失效；以目前官方文件的 OpenHands/OpenHands repository 和新映像路徑為準。
OpenHands 像聊天機器人，不會操作檔案
依序確認：
- 啟動時是否使用
--mount-cwd，而且當時所在目錄正確。 - Agent 是否有讀取該目錄的權限。
- 模型是否為官方驗證或適合 Agent 工具呼叫的模型。
- 本機模型的 context length 是否足夠，是否持續出現工具格式錯誤。
若前三項都正常但仍反覆失敗，問題可能在模型能力或相容端點，不一定是 OpenHands 本身。
OpenHands CLI 的另一種使用方式
安裝 launcher 後，也可以直接在終端機執行互動式 CLI：
openhands loginopenhands第一次會引導登入 OpenHands Cloud 或手動設定模型。CLI 裡可用 Ctrl+P 打開 command palette、Esc 暫停 Agent、Ctrl+Q 或 /exit 離開；也可以直接帶入小型任務：
openhands -t "Read the test failure and explain the likely cause without editing files"GUI 適合看完整執行過程，CLI 則適合已經在終端機工作的開發者。兩者的重點都一樣：先限制範圍、要求驗證，再人工查看 diff。
如果你也在比較終端機 coding agent，可以接著看 OpenCode Go 的安裝與模型設定；兩篇文章分別著重 OpenHands 的隔離執行環境，以及 OpenCode 的終端機工作流。
結論
目前最穩定的 OpenHands 入門路徑，是準備好 Docker 與 uv，用 uv tool install openhands --python 3.12 安裝 launcher，再從專案目錄執行 openhands serve --mount-cwd。進入介面後設定模型與 API Key，先跑唯讀盤點，再用一個可回復的小檔案驗證工具呼叫和修改範圍。
舊版 OpenHands 教學最容易出錯的地方，是過時的 Docker image、Windows 原生執行方式，以及把本機模型設定簡化成一個環境變數。遇到問題時，先分開檢查 Docker、掛載權限、模型能力與 WSL，通常會比反覆重裝更快找到原因。
參考資料
回報錯字、失效連結，或告訴我你想看的延伸主題。