OHOpenHands
INSTALLATION GUIDEapi.gnnliao.com
WINDOWS · WSL · DOCKER

從零開始安裝
OpenHands。

給第一次接觸容器與本地 AI 的使用者。照著 9 個步驟依序操作，就能建立專案、讓 OpenHands 讀取本機檔案，並連上 GNNLiao API。

Windows→WSL 2→Docker→OpenHands→Project
開始之前

你需要準備什麼？

  • Windows 10 版本 2004 以上，或 Windows 11
  • 可安裝程式的系統管理員權限
  • 至少 4GB RAM 與約 5GB 可用磁碟空間
  • 管理員提供的 GNNLiao API Key
INSTALLATION GUIDE

Windows：完整安裝步驟

每一步完成後再往下。標示「補充說明」的內容可以先略過。

01

開啟系統管理員 PowerShell

按 Windows 鍵，搜尋 PowerShell，右鍵選擇「以系統管理員身分執行」。

確認 Windows 版本
winver
＋找不到系統管理員選項？

也可以在開始按鈕上按右鍵，選擇「終端機（系統管理員）」；跳出權限詢問時按「是」。

02

安裝 WSL 2 與 Ubuntu

WSL 讓 Windows 裡可以執行 Linux。OpenHands 的 Windows 指令必須在 WSL 的 Ubuntu 終端內執行。

在系統管理員 PowerShell 執行
wsl --install -d Ubuntu
安裝完成後重新啟動電腦。第一次開啟 Ubuntu 時，請建立 Linux 使用者名稱與密碼；輸入密碼時畫面不會顯示字元，這是正常的。
重開機後，在 PowerShell 確認
wsl --version
wsl --list --verbose
＋如果顯示 WSL 不是第 2 版
COMMAND
wsl --set-default-version 2
wsl --set-version Ubuntu 2

轉換需要幾分鐘。完成後再次執行 wsl --list --verbose，確認 Ubuntu 的 VERSION 是 2。

03

安裝並設定 Docker Desktop

Docker 是 OpenHands 執行 Agent Sandbox 的容器環境。先在 Windows 安裝 Docker Desktop，再把它連進 Ubuntu。

  1. 下載並安裝 Docker Desktop。
  2. 開啟 Docker Desktop → Settings → General。
  3. 勾選 Use the WSL 2 based engine。
  4. 前往 Resources → WSL Integration。
  5. 開啟 Ubuntu 的整合，按 Apply & restart。
在 Ubuntu 終端測試
docker version
docker run --rm hello-world
＋Launch docker client failed / docker 找不到

先確認 Docker Desktop 左下角顯示 Engine running，再重新開啟 Ubuntu。如果仍失敗，回到 WSL Integration 關閉再開啟 Ubuntu 整合。

04

在 Ubuntu 安裝 uv

uv 是官方推薦的 Python 工具管理器，用來隔離並安裝 OpenHands CLI。後續指令都在 Ubuntu 終端執行。

Ubuntu / Bash
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv --version
＋執行 uv 時顯示 command not found

關閉 Ubuntu 終端再打開，或重新執行 source $HOME/.local/bin/env。安裝腳本最後也會顯示正確的環境載入指令。

05

安裝 OpenHands CLI

使用 Python 3.12 安裝。完成後先確認 openhands 指令存在。

Ubuntu / Bash
uv tool install openhands --python 3.12
openhands --version
＋升級或重新安裝 OpenHands
COMMAND
uv tool upgrade openhands
# 若環境損壞
uv tool uninstall openhands
uv tool install openhands --python 3.12
06

建立你的第一個 Project

Project 就是一個本機資料夾。OpenHands 只會取得你明確掛載的資料夾，不會自動看到整台電腦。

建立範例專案
mkdir -p ~/projects/my-first-project
cd ~/projects/my-first-project
printf '# My First Project
' > README.md
pwd
ls -la
看到路徑類似 /home/你的使用者/projects/my-first-project 與 README.md 就完成了。
＋我要使用 Windows 的既有資料夾

Windows 的 C 槽在 WSL 裡位於 /mnt/c。例如：

COMMAND
cd /mnt/c/Users/YOUR_WINDOWS_NAME/Documents
mkdir my-openhands-project
cd my-openhands-project

若大量安裝套件或操作 Git，放在 ~/projects 通常效能較好。

07

從 Project 目錄啟動 OpenHands

先 cd 進專案，再加上 --mount-cwd。這一步會把目前資料夾掛載到 Sandbox 裡的 /workspace。

在專案目錄執行
cd ~/projects/my-first-project
openhands serve --mount-cwd
等待終端顯示服務已啟動，再用瀏覽器開啟 http://localhost:3000。
＋為什麼一定要 --mount-cwd？

Docker 容器預設看不到主機檔案。--mount-cwd 會將目前目錄掛載成可讀寫的 /workspace。如果在錯誤的目錄啟動，OpenHands 就會看到錯誤的 Project。

＋如何停止與重新啟動？

回到正在執行 OpenHands 的 Ubuntu 終端，按 Ctrl+C 停止。重新進入 Project 目錄，再執行同一個 openhands serve --mount-cwd 即可。

08

在 Application 加入 GNNLiao LLM

第一次進入 OpenHands 會看到模型設定；之後也可以從 Settings → LLM 修改。

  1. 開啟 OpenHands Application。
  2. 前往 Settings → LLM。
  3. 點選或開啟 Advanced。
  4. Custom Model 填入：openai/qwen3.8:27b
  5. Base URL 填入：https://api.gnnliao.com/v1
  6. API Key 填入管理員提供的個人金鑰。
  7. 按 Save Settings / Save Changes。
CUSTOM MODELopenai/qwen3.8:27b
BASE URLhttps://api.gnnliao.com/v1
API KEY向管理員索取
＋為什麼模型名稱要加 openai/？

OpenHands 透過 LiteLLM 將這個端點當作 OpenAI-compatible API。openai/ 是 provider 前綴，後面才是伺服器提供的模型 ID。

＋API Key 安全提醒

API Key 等同使用權限。不要放進 Project、Git、README、截圖或公開對話。若不小心外洩，立即請管理員撤銷並更換。

09

建立對話並確認 Project 可用

建立新的 Conversation，先要求 Agent 查看工作目錄與 README，再進行真正的開發任務。

在 OpenHands 對話框輸入
請先執行 pwd 與 ls -la，確認目前 workspace，
再讀取 README.md，告訴我這個 project 裡有哪些檔案。
＋API 連線或模型錯誤怎麼查？
  • 401 / Invalid API key：重新向管理員確認金鑰，貼上時不要包含空白。
  • Model not found：確認完整名稱是 openai/qwen3.8:27b。
  • Connection refused：確認 Base URL 是 HTTPS 且包含 /v1。
  • 像普通聊天、沒有操作檔案：先確認 Project 已用 --mount-cwd 啟動，再檢查模型的 tool calling 相容性。
READY TO BUILD

安裝完成。

下一次使用只需要開啟 Docker Desktop、進入 Project 目錄，再執行 openhands serve --mount-cwd。

每天啟動時
cd ~/projects/my-first-project
openhands serve --mount-cwd