OpenHands 1.15 教學：安裝、模型設定與 workspace 排錯

OpenHands 1.15 有哪些值得注意的變更#

1.15.0 的變更會影響第一次設定和日常檢查，主要包括：

這些是產品功能與 bug fix，不代表 Agent 會自動安全地修改任何 repository。仍要用 Git branch、限定掛載目錄和可驗證的小任務控制變更範圍。

開始前的環境與安全邊界#

官方本機設定路徑需要：

• Docker Desktop 或 Docker Engine 正在執行，docker ps 能正常完成。
• Python 3.12 以上版本。
• uv 套件工具；預設 MCP server 也會使用它。
• 可用的模型 API Key，或已設定好的本機模型端點。

macOS 可以直接在終端機執行；Linux 依官方 Docker 環境準備。Windows 原生 PowerShell 和 Command Prompt 不是本文的執行入口，請先使用 WSL，再確認 Docker Desktop 已啟用 WSL 2 engine 和該 distribution 的整合。

在把 repository 交給 Agent 前，先建立 Git branch、執行 git status --short，並確認目前工作目錄沒有你不想被讀取或修改的憑證。第一次測試最好使用不含 secrets 的小型專案。

掛載目錄代表 Agent 可以修改檔案

--mount-cwd 會把目前所在的資料夾掛載給 OpenHands。它不是唯讀模式；請先確認目前路徑、Git 狀態和檔案權限，再啟動 Agent。

用官方 CLI launcher 安裝#

先依 uv 官方安裝說明 安裝 uv，再安裝 OpenHands：

1
uv tool install openhands --python 3.12

進入準備交給 Agent 的專案目錄，啟動 GUI：

1
cd /path/to/your-project
2
openhands serve --mount-cwd

CLI launcher 會檢查 Docker、拉取需要的映像並啟動 GUI server。完成後開啟：

1
http://localhost:3000

如果只想先確認介面，不希望 OpenHands 讀取目前專案，可以在不含敏感檔案的目錄執行：

1
openhands serve

日後更新 launcher：

1
uv tool upgrade openhands --python 3.12

官方也提供直接執行 Docker image 的方式，但 image、agent-server tag 和啟動參數會隨版本更新。第一次安裝優先使用 launcher；若要固定 image 或部署到共用環境，應以目前 Local setup 官方文件 的指令為準，不要複製舊文章中的 ghcr.io/all-hands-ai/ 路徑。

設定 LLM provider、model 與 API Key#

第一次開啟 OpenHands 時會看到設定流程，也可以進入 Settings → LLM。基本設定依序完成：

1. 在 LLM Provider 選擇供應商。
2. 在 LLM Model 選擇模型。
3. 填入 API Key。
4. 按下 Save Changes。

目前官方 LLM 文件列出 OpenHands、Anthropic、OpenAI 和 Mistral AI 等已驗證供應商。模型名稱、可用性和費用都會變動，請以設定頁當下的清單與供應商文件為準，不要把舊文章中的 model id 當成固定答案。

如果基本清單沒有你的端點，開啟 Advanced：

• Custom Model：依 LiteLLM provider 格式填入 provider prefix。
• Base URL：填入相容 API 或自架服務的端點。
• API Key：填入該端點的金鑰。

設定變更會套用到新的 conversation；官方文件提醒，舊 conversation 若要使用新的 LLM，可能需要重新啟動。1.15 的 provider-connections UI 適合用來檢查目前儲存的連線，但仍要確認 profile 沒有把 home LLM 選擇覆蓋掉。

API Key 與費用

雲端模型通常需要另外計費。先在供應商後台設定用量上限，不要把 Key 寫進 repository、prompt 或 shell history。OpenHands Cloud 的登入和模型額度也有自己的條件，不能把網站帳號當成無限 API 額度。

先確認 workspace path，再交付任務#

啟動後先在 Files view 查看 workspace path，確認它就是預期的 repository。這個 1.15 新增的資訊很適合抓出「在錯誤資料夾啟動」的問題；不要只看瀏覽器 URL 或對話標題。

第一個任務先要求唯讀盤點：

1
先讀取這個專案的 README 與套件腳本，不要修改檔案。
2
告訴我使用哪個套件管理器、可執行哪些測試，並列出你讀過的檔案。

確認 workspace、模型和工具呼叫都正常後，再交付一個小而可回復的修改：

1
建立 hello-openhands.txt，內容只有 OpenHands is ready。
2
完成後讀回檔案，並執行 git diff -- hello-openhands.txt 回報結果。
3
不要修改其他檔案。

最後回到自己的終端機驗證：

1
git status --short
2
git diff -- hello-openhands.txt

這個循序流程能確認四件事：Agent 看到正確目錄、模型能呼叫工具、檔案真的被建立，以及實際 diff 沒超出要求。若你同時使用多個 coding agent，可以先用 Git worktree 管理多個 AI coding agent 分離工作副本，降低互相覆蓋檔案的機會。

常見故障排除#

1
docker ps

1
ls -ld ~/.openhands
2
ls -ld /path/to/your-project

1
sudo chown -R "$(id -un)":"$(id -gn)" ~/.openhands

OpenHands CLI 的另一種入口#

安裝 launcher 後，也可以在終端機使用互動式 CLI：

1
openhands login
2
openhands

CLI 會引導登入 OpenHands Cloud 或設定模型；也可以直接帶入小型任務：

1
openhands -t "Read the test failure and explain the likely cause without editing files"

GUI 適合觀察完整執行過程，CLI 適合已經在終端機工作的開發者。兩者都應遵守同一個原則：先限制 workspace，要求 Agent 回報驗證，再人工查看 diff。

如果你正在比較終端機 coding agent，可以接著看 OpenCode Go 的安裝與模型設定；那篇討論另一種終端機工作流，這篇則聚焦 OpenHands 的 Docker 隔離、workspace 掛載和 Agent 驗證。

常見問題#