OpenHands 1.18 教學：Agent Canvas、LLM profiles 與 workspace 排錯

OpenHands 1.17、1.18 有哪些值得注意的變更#

這兩個版本把重點從「能不能啟動 Agent」推進到「誰能管理 automation、每次執行使用哪個身份，以及不同工作階段要用哪個模型」。升級後先對照這張表，再回到自己的 workspace 做小任務驗證：

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

從 1.16 升到 1.18，先檢查四個地方#

升級後不要只看首頁能否開啟。用同一個低風險 workspace 驗證：

1. Provider 與 LLM profiles：在 Settings → LLM 確認 provider、model、Base URL 和 API Key，並列出可用 profile。官方文件目前允許最多 10 個 profile；新的設定會套用到新 conversation，舊 conversation 可能要重新啟動。
2. 切換模型的可觀察性：用 profile selector 或 /model 切換，確認切換後只影響後續 LLM call，conversation history、檔案和 task state 仍保留。若 Agent 使用 SwitchLLMTool，也要把成功或錯誤事件列入驗證。
3. Automation 身份與權限：建立可刪除或可停用的測試 automation，分別用 creator 和其他成員檢查 view、manage、edit 與 re-enable；同時記錄畫面顯示的執行身份，不要把 Cloud 帳號身份當成 automation 身份。
4. Workspace hooks、Skills 與 ACP：確認 conversation 開始時會自動載入哪些 hooks，列出需要的 Skills allow-list，對每個 ACP harness 做明確選擇。若是 self-hosted 環境，再確認 --disable-telemetry 是否符合你的部署政策。

Linux desktop、local Planner 和 Cloud settings 是不同工作流，不等於既有 Docker deployment 要立刻搬遷。團隊已用 container 固定版本與 workspace 的話，先維持原路徑升級；只有需要桌面體驗或 Cloud automation 的使用者，再於隔離目錄測試對應入口。

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

官方本機設定路徑需要：

• 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，可能需要重新啟動。儲存設定會建立或更新 LLM profile，最多可保留 10 個。進入對話後可用 profile selector 或 /model <profile-name> 切換；切換在下一次 LLM call 生效，不會重跑已完成的訊息。

1
/model
2
/model gpt-5.5-review

profile 名稱必須和實際儲存的名稱完全一致。若 local profile 在儲存時驗證失敗，先修正 API Key、model 或 backend 連線；不要把錯誤 profile 寫進自動化 prompt，期待 Agent 自己猜出正確名稱。

API Key 與費用

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

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

啟動後先在 Files view 查看 workspace path，確認它就是預期的 repository。chat 中的檔案路徑在 1.16 已可連到 Files drawer，但連結方便不代表路徑一定正確；仍要核對掛載根目錄，不要只看瀏覽器 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 驗證。

常見問題#