General
確認 Use the WSL 2 based engine 已啟用。
本教學從安裝與最基本設定開始,逐步介紹 Workspace、模型連線、Agent、Tools、Skills 與 Multi-Agent。範例會依照下方輸入的模型自動更新,不綁定任何特定硬體或模型名稱。
openai/qwen3.8:27bhttps://api.gnnliao.com/v1本單元會同時使用 Windows PowerShell 與 WSL Ubuntu。每一組指令上方都會標明應該在哪個視窗執行;不要把 PowerShell 指令貼到 Ubuntu,也不要把 Ubuntu 指令貼到 PowerShell。
按 Windows 鍵搜尋 PowerShell → 右鍵 →「以系統管理員身分執行」。以下先在這個藍色或黑色 PowerShell 視窗操作。
wsl --install -d Ubuntu從 Windows 開始選單搜尋「Ubuntu」並開啟。看到類似 user@computer:~$ 的提示字元後,以下 Bash 指令才貼在這裡。
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv --versionuv tool install openhands --python 3.12
openhands --versionDocker Desktop 是 Windows 應用程式,不是在終端輸入的指令。安裝後開啟 Settings → General,確認使用 WSL 2 engine;再到 Resources → WSL Integration,啟用 Ubuntu。
確認 Use the WSL 2 based engine 已啟用。
開啟 Ubuntu 的整合,然後 Apply / Restart。
Docker Desktop 保持執行,再回到 Ubuntu 終端測試 Docker。
docker version
docker run --rm hello-world這一單元分成三個操作位置:Ubuntu / WSL 終端、瀏覽器中的 OpenHands 頁面,以及 OpenHands 的 Settings → LLM。請依照每段上方的「在哪裡操作」提示進行。
先建立專案資料夾。這不是 OpenHands 聊天輸入框,也不是 Windows PowerShell;請在 Ubuntu 視窗執行。
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。
保持目前位於 ~/projects/my-project,不要切回 PowerShell。從這個專案目錄啟動 OpenHands。
cd ~/projects/my-project
openhands serve --mount-cwdOpenHands Server 啟動後,打開 Chrome、Edge 或其他瀏覽器,在網址列輸入 http://localhost:3000。這一步不是在終端執行。
http://localhost:3000進入 OpenHands 網頁後開啟 Settings,找到 LLM 設定。模型名稱、Base URL 與 API Key 是填在這個設定畫面,不是貼到 Ubuntu 終端,也不是貼到聊天輸入框。
openai/qwen3.8:27bhttps://api.gnnliao.com/v1填入你的服務金鑰;若服務不要求則依 provider 設定如果本地模型是透過 Ollama、vLLM 或自己的 Gateway 提供 OpenAI-compatible API,這裡要填的是 OpenHands 所在環境能連到的 API 位址。首頁輸入的值只用來同步產生本教學範例,不會替你修改 OpenHands。
先讓一個 Project 對應一個清楚的工作根目錄。OpenHands 從該目錄啟動後,整個 Project 會映射成 Agent 看到的 /workspace。
現在才開始在 OpenHands 的聊天輸入框輸入 Prompt。這裡的文字不是 Terminal 指令,而是交給 Agent 執行的任務。
在瀏覽器中的 OpenHands 建立新對話,把下面整段 Prompt 貼進聊天輸入框後送出。不要把這段貼到 Ubuntu 終端。
請先執行 pwd 與 ls -la。
確認目前的工作目錄。
接著讀取 README.md,說明這個專案目前包含哪些內容。
不要修改任何檔案。這段 Prompt 是要求 Agent 自己使用 Terminal Tool。使用者不需要手動把 `pwd`、`ls -la` 再貼進 Ubuntu;應觀察 OpenHands 是否自行產生 Tool Call 並取得結果。
如果 OpenHands 網頁顯示 500、Conversation error 或 Agent 沒有正常工作,再回到啟動 OpenHands 的 Ubuntu 終端觀察輸出。後續 Unit 07 會介紹更完整的 logs 查法。
確認基本 OpenHands 正常後,再理解 Agent 系統的四個核心元件。
由模型、角色指令與可用能力共同形成,例如研究、實作或驗證角色。
Terminal、Browser、File Editor、Delegate 等真正可以產生動作的介面。
在需要時載入特定工作流程或專業方法,不需要全部塞進 Prompt。
Agent 真正能讀寫的專案環境,也是所有代理共享 evidence 的主要位置。
多代理的目的不是增加 Agent 數量,而是把研究、實作、驗證與決策責任分開。所有範例預設使用第一頁指定的本地模型。
負責拆解目標、委派任務與整合結果
delegateMODEL: openai/qwen3.8:27b負責外部研究、專案證據與假設形成
terminal / browser / invoke_skillMODEL: openai/qwen3.8:27b負責程式修改、實驗與技術驗證
terminal / file_editor / task_tracker / invoke_skillMODEL: openai/qwen3.8:27b獨立檢查 artifacts、metrics 與結果
terminalMODEL: openai/qwen3.8:27b---
name: coordinator
model: openai/qwen3.8:27b
tools:
- delegate
---
# Coordinator
Coordinate the task.
Delegate research, implementation, and evaluation.
Do not perform implementation work directly.---
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.---
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.---
name: evaluator
model: openai/qwen3.8:27b
tools:
- terminal
---
# Evaluator
Independently inspect artifacts and metrics.
Do not modify the implementation being evaluated.工具應依角色責任分配。權限越多不代表 Agent 越好,反而可能讓角色互相越界。
delegate維持純協調,不直接改檔。
browser_* / terminal / invoke_skill查來源與 evidence,但不負責實作。
terminal / file_editor / task_tracker / invoke_skill負責真正的工程工作。
terminal保持獨立,避免同時修改被評估內容。
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.當 Multi-Agent 出現問題時,應先判斷是模型連線、Workspace、Runtime、Tool schema,還是 Agent 設定。
檢查 API Key、Base URL 與 provider 設定。
確認 OpenHands 使用的 Model ID 與 API 實際提供的名稱一致。
確認啟動 OpenHands 前所在目錄,以及 --mount-cwd。
檢查是否仍存在舊路徑、舊 Prompt 或重複的 .agents。
查看 Agent Server logs;UI 顯示的外層錯誤不一定是真正 root cause。
Tool call 缺少必要 command,屬於 schema invocation 問題。
重新縮小 Tools,並在 Agent Markdown 中明確寫出 Do / Do Not。
C=$(docker ps --filter "name=oh-agent-server" --filter "status=running" --format '{{.Names}}' | head -1)
docker logs -f "$C"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.一套穩定的多代理系統,建立順序應是:環境 → 模型 → Workspace → Tool Calling → Agent Boundary → Multi-Agent → 驗證。
重新設定模型 ↑