OPENHANDS / LOCAL MODEL / MULTI-AGENT開始教學 ↓
BEGINNER → ADVANCED

從本地模型開始,
建立自己的 OpenHands。

本教學從安裝與最基本設定開始,逐步介紹 Workspace、模型連線、Agent、Tools、Skills 與 Multi-Agent。範例會依照下方輸入的模型自動更新,不綁定任何特定硬體或模型名稱。

01
先設定教學中的本地模型輸入 Ollama 或 OpenAI-compatible API 實際提供的 Model ID。
教學將使用openai/qwen3.8:27bhttps://api.gnnliao.com/v1
設定只保存在此瀏覽器的 localStorage,不會傳送到教學網站伺服器。請勿在此輸入 API Key。
UNIT 01

安裝 OpenHands

本單元會同時使用 Windows PowerShell 與 WSL Ubuntu。每一組指令上方都會標明應該在哪個視窗執行;不要把 PowerShell 指令貼到 Ubuntu,也不要把 Ubuntu 指令貼到 PowerShell。

在哪裡操作Windows:PowerShell(系統管理員)

按 Windows 鍵搜尋 PowerShell → 右鍵 →「以系統管理員身分執行」。以下先在這個藍色或黑色 PowerShell 視窗操作。

Windows PowerShell(系統管理員)— 安裝 WSL 2 + Ubuntu
wsl --install -d Ubuntu
這一步完成後
若 Windows 要求重新開機,先重新啟動。之後從開始選單開啟「Ubuntu」。第一次啟動會要求建立 Linux 使用者名稱與密碼;輸入密碼時畫面不顯示字元是正常現象。
在哪裡操作Windows:Ubuntu / WSL 終端

從 Windows 開始選單搜尋「Ubuntu」並開啟。看到類似 user@computer:~$ 的提示字元後,以下 Bash 指令才貼在這裡。

Ubuntu / WSL — 安裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv --version
Ubuntu / WSL — 安裝 OpenHands CLI
uv tool install openhands --python 3.12
openhands --version
在哪裡操作Windows:Docker Desktop 圖形介面

Docker Desktop 是 Windows 應用程式,不是在終端輸入的指令。安裝後開啟 Settings → General,確認使用 WSL 2 engine;再到 Resources → WSL Integration,啟用 Ubuntu。

1

General

確認 Use the WSL 2 based engine 已啟用。

2

WSL Integration

開啟 Ubuntu 的整合,然後 Apply / Restart。

3

回 Ubuntu 驗證

Docker Desktop 保持執行,再回到 Ubuntu 終端測試 Docker。

Ubuntu / WSL — 驗證 Docker
docker version
docker run --rm hello-world
Unit 01 完成條件
在 Ubuntu 終端執行 `openhands --version` 與 `docker version` 都能正常回傳資訊。從下一單元開始,除非特別標示,OpenHands 指令都在 Ubuntu / WSL 終端執行。
UNIT 02

OpenHands 的基本設定

這一單元分成三個操作位置:Ubuntu / WSL 終端、瀏覽器中的 OpenHands 頁面,以及 OpenHands 的 Settings → LLM。請依照每段上方的「在哪裡操作」提示進行。

在哪裡操作① Ubuntu / WSL 終端

先建立專案資料夾。這不是 OpenHands 聊天輸入框,也不是 Windows PowerShell;請在 Ubuntu 視窗執行。

Ubuntu / WSL — 建立第一個 Project
mkdir -p ~/projects/my-project
cd ~/projects/my-project
printf '# My Project\n' > README.md
pwd
ls -la

`cd ~/projects/my-project` 代表先進入要交給 OpenHands 操作的專案。稍後使用 --mount-cwd 時,OpenHands 會把「目前所在資料夾」掛載到 Agent 的 Workspace。

在哪裡操作② 同一個 Ubuntu / WSL 終端

保持目前位於 ~/projects/my-project,不要切回 PowerShell。從這個專案目錄啟動 OpenHands。

Ubuntu / WSL — 從 Project 啟動 OpenHands
cd ~/projects/my-project
openhands serve --mount-cwd
啟動後不要關掉這個 Ubuntu 視窗
這個終端正在執行 OpenHands Server。讓它保持開啟。要停止 OpenHands 時才回到這個視窗按 `Ctrl+C`。
在哪裡操作③ Windows 網頁瀏覽器

OpenHands Server 啟動後,打開 Chrome、Edge 或其他瀏覽器,在網址列輸入 http://localhost:3000。這一步不是在終端執行。

瀏覽器網址列(不是 Terminal)
http://localhost:3000
在哪裡操作④ OpenHands 網頁 → Settings → LLM

進入 OpenHands 網頁後開啟 Settings,找到 LLM 設定。模型名稱、Base URL 與 API Key 是填在這個設定畫面,不是貼到 Ubuntu 終端,也不是貼到聊天輸入框。

MODEL / CUSTOM MODELopenai/qwen3.8:27b
BASE URLhttps://api.gnnliao.com/v1
API KEY填入你的服務金鑰;若服務不要求則依 provider 設定

如果本地模型是透過 Ollama、vLLM 或自己的 Gateway 提供 OpenAI-compatible API,這裡要填的是 OpenHands 所在環境能連到的 API 位址。首頁輸入的值只用來同步產生本教學範例,不會替你修改 OpenHands。

RECOMMENDED PROJECT STRUCTURE

建議的 Projects 資料結構

先讓一個 Project 對應一個清楚的工作根目錄。OpenHands 從該目錄啟動後,整個 Project 會映射成 Agent 看到的 /workspace。

my-project/├── .openhands/ # OpenHands 專案設定(若使用)├── .agents/│ ├── agents/ # 自訂 Agent 定義│ │ ├── coordinator.md│ │ ├── researcher.md│ │ ├── engineer.md│ │ └── evaluator.md│ └── skills/ # 專案自訂 Skills(選用)├── src/ # 主要程式碼├── tests/ # 測試├── docs/ # 設計與研究文件├── scripts/ # 啟動、訓練、自動化腳本├── data/ # 專案資料;大型資料可另外掛載├── README.md└── .gitignore
WSL HOST~/projects/my-project
--mount-cwd →
OPENHANDS/workspace
`.agents/` 放根目錄:避免同時存在 `project/.agents` 與根目錄 `.agents`。程式與代理設定分開:`src/` 是程式,`.agents/` 是 Agent/Skill 定義。從根目錄啟動:先 `cd ~/projects/my-project`,再執行 `openhands serve --mount-cwd`。
Ubuntu Project→--mount-cwd→/workspace→OpenHands Web UI→qwen3.8:27b
Unit 02 的核心概念
終端負責「建立 Project 與啟動 OpenHands」;瀏覽器負責「操作 OpenHands」;Settings → LLM 負責「設定模型」。這三個位置不要混在一起。
UNIT 03

第一次使用:確認 OpenHands 真的可以工作

現在才開始在 OpenHands 的聊天輸入框輸入 Prompt。這裡的文字不是 Terminal 指令,而是交給 Agent 執行的任務。

在哪裡操作OpenHands 網頁 → 新 Conversation → 聊天輸入框

在瀏覽器中的 OpenHands 建立新對話,把下面整段 Prompt 貼進聊天輸入框後送出。不要把這段貼到 Ubuntu 終端。

OpenHands 聊天輸入框 — 第一個測試 Prompt
請先執行 pwd 與 ls -la。
確認目前的工作目錄。
接著讀取 README.md,說明這個專案目前包含哪些內容。
不要修改任何檔案。

這段 Prompt 是要求 Agent 自己使用 Terminal Tool。使用者不需要手動把 `pwd`、`ls -la` 再貼進 Ubuntu;應觀察 OpenHands 是否自行產生 Tool Call 並取得結果。

在哪裡操作Ubuntu / WSL 終端(只有發生錯誤時)

如果 OpenHands 網頁顯示 500、Conversation error 或 Agent 沒有正常工作,再回到啟動 OpenHands 的 Ubuntu 終端觀察輸出。後續 Unit 07 會介紹更完整的 logs 查法。

先不要建立 Multi-Agent
只有當這個單 Agent 測試完全正常,才進入 Agent 架構與 Multi-Agent。否則模型連線、Workspace、Tool Calling 與代理設定的錯誤會混在一起。
UNIT 04

代理架構入門

確認基本 OpenHands 正常後,再理解 Agent 系統的四個核心元件。

AGENT

角色

由模型、角色指令與可用能力共同形成,例如研究、實作或驗證角色。

TOOL

動作能力

Terminal、Browser、File Editor、Delegate 等真正可以產生動作的介面。

SKILL

工作方法

在需要時載入特定工作流程或專業方法,不需要全部塞進 Prompt。

WORKSPACE

工作範圍

Agent 真正能讀寫的專案環境,也是所有代理共享 evidence 的主要位置。

USER提出目標
→
COORDINATOR拆解與委派
→
SUB-AGENTS研究 / 實作 / 驗證
→
WORKSPACE檔案與 evidence
UNIT 05

進階:建立 Multi-Agent

多代理的目的不是增加 Agent 數量,而是把研究、實作、驗證與決策責任分開。所有範例預設使用第一頁指定的本地模型。

Coordinator

負責拆解目標、委派任務與整合結果

delegateMODEL: openai/qwen3.8:27b
Researcher

負責外部研究、專案證據與假設形成

terminal / browser / invoke_skillMODEL: openai/qwen3.8:27b
Engineer

負責程式修改、實驗與技術驗證

terminal / file_editor / task_tracker / invoke_skillMODEL: openai/qwen3.8:27b
Evaluator

獨立檢查 artifacts、metrics 與結果

terminalMODEL: openai/qwen3.8:27b
.agents/agents/coordinator.md
---
name: coordinator
model: openai/qwen3.8:27b
tools:
  - delegate
---

# Coordinator
Coordinate the task.
Delegate research, implementation, and evaluation.
Do not perform implementation work directly.
.agents/agents/researcher.md
---
name: researcher
model: openai/qwen3.8:27b
tools:
  - terminal
  - browser_navigate
  - browser_get_content
  - invoke_skill
---

# Researcher
Collect evidence from the workspace and authoritative external sources.
Separate observed evidence, inference, and hypothesis.
Do not modify project code.
.agents/agents/engineer.md
---
name: engineer
model: openai/qwen3.8:27b
tools:
  - terminal
  - file_editor
  - task_tracker
  - invoke_skill
---

# Engineer
Implement controlled changes and verify them.
Do not silently redefine the research objective.
.agents/agents/evaluator.md
---
name: evaluator
model: openai/qwen3.8:27b
tools:
  - terminal
---

# Evaluator
Independently inspect artifacts and metrics.
Do not modify the implementation being evaluated.
模型配置可以再進階
入門階段可讓四個角色使用同一個本地模型。熟悉後,再依硬體與模型特性替不同角色建立獨立 LLM Profile。
UNIT 06

Tools 與 Skills:建立清楚的能力邊界

工具應依角色責任分配。權限越多不代表 Agent 越好,反而可能讓角色互相越界。

角色建議能力設計理由
Coordinatordelegate

維持純協調,不直接改檔。

Researcherbrowser_* / terminal / invoke_skill

查來源與 evidence,但不負責實作。

Engineerterminal / file_editor / task_tracker / invoke_skill

負責真正的工程工作。

Evaluatorterminal

保持獨立,避免同時修改被評估內容。

Skill 使用原則
Use invoke_skill only when an installed skill materially improves the current task.

Prefer the minimum necessary set.
Do not invoke skills merely because they are available.
Skill 與 Tool 不相同
Tool 是執行能力;Skill 是可按需載入的工作方法。即使安裝很多 Skill,也不需要把全部 Skill 說明寫入每個 Agent Prompt。
UNIT 07

除錯、常見錯誤與最終驗證

當 Multi-Agent 出現問題時,應先判斷是模型連線、Workspace、Runtime、Tool schema,還是 Agent 設定。

401 / Invalid API key

檢查 API Key、Base URL 與 provider 設定。

Model not found

確認 OpenHands 使用的 Model ID 與 API 實際提供的名稱一致。

看不到專案

確認啟動 OpenHands 前所在目錄,以及 --mount-cwd。

出現 /workspace/project

檢查是否仍存在舊路徑、舊 Prompt 或重複的 .agents。

500 Conversation error

查看 Agent Server logs;UI 顯示的外層錯誤不一定是真正 root cause。

terminal command Field required

Tool call 缺少必要 command,屬於 schema invocation 問題。

角色互相越界

重新縮小 Tools,並在 Agent Markdown 中明確寫出 Do / Do Not。

Agent Server Logs
C=$(docker ps --filter "name=oh-agent-server" --filter "status=running" --format '{{.Names}}' | head -1)
docker logs -f "$C"
Multi-Agent 最終驗證
Run one minimal multi-agent verification cycle.

Researcher:
- inspect the workspace
- identify one existing file
- use one authoritative external source
- do not modify files

Coordinator:
- summarize the evidence
- delegate one harmless implementation task

Engineer:
- create a temporary file containing exactly ENGINEER_OK
- read it back

Evaluator:
- independently verify the file and exact content
- do not modify anything

Coordinator:
- report whether every role respected its boundary

Do not run training.
Do not modify datasets.
Do not modify .agents.
正式使用前的完成條件
單 Agent 基礎測試正常、四個角色都能被正確委派、Workspace 一致、Tools 沒有越界,再開始真正的長時間自主任務。
FROM INSTALLATION TO MULTI-AGENT

先建立可靠的 OpenHands,再增加代理複雜度。

一套穩定的多代理系統,建立順序應是:環境 → 模型 → Workspace → Tool Calling → Agent Boundary → Multi-Agent → 驗證。

重新設定模型 ↑