OpenHands 1.33 教學：MCP 連線選擇與 Automation 驗收

1.32／1.33：先驗收選到的連線與儲存庫#

1.31：先確認 MCP 停在哪個階段#

1.31.0 於 2026-10-22 16<09> UTC 發布，台灣時間為 10 月 23 日 00<09>。升級後仍應核對實際部署的 Canvas 與 backend；只更新其中一個元件，不能直接宣稱整套能力已就緒。

PR #18780修正 Library 中只有 OAuth 選項的遠端 MCP 安裝。沒有其他可安裝選項時，改走 MCP 伺服器自己的 OAuth discovery 與動態 client registration；有其他可用選項的項目仍沿用原選項。這不表示任何 OAuth 服務都能自動註冊成功，伺服器仍須支援相應流程。完全沒有可用選項時，介面應顯示原因並停用 Install，而非留下無反應的按鈕。

PR #18816則將已取得授權 URL、卻沒有完成登入的失敗歸類為 authorization，提醒完成彈出視窗的登入。尚未進入授權流程的後端逾時仍保留 timeout；不能只看到新版訊息，就認定網路與 callback 一定正常。

在測試用 MCP 和最小權限帳號驗收時，依序保留這些結果：

1. Library 是否出現可用選項，Install 是否開啟預期服務的授權頁；沒有開啟時先查選項與彈出視窗阻擋，不要直接改 URL。
2. 刻意關閉未完成的授權視窗，確認回報「登入未完成」，沒有被當成安裝成功；再從安裝流程重新開始授權。
3. 完成授權後關閉並重開 MCP 頁面，確認伺服器仍列出，再以受控的唯讀工具呼叫驗證可用性。列在清單中與工具真正可用，需分別記錄。

OAuth 完成也不會自動改掉某個命名 Agent profile 的 MCP 選擇；若只有某份 profile 找不到工具，接著核對下方的 scope 與啟用清單。

編輯 Automation repository，要看後端能力再保存#

PR #18776指出，舊表單讀取錯誤的 repository 欄位，且更新時沒有送出 repository 清單。修正後可從保存的 preset metadata 讀回多個 repository，保留既有 branch 與 provider。

能顯示既有 repository，不代表這個部署能修改它。 只有服務宣告 repoUpdate，且 Automation 屬於支援的 prompt 或 plugin preset 時，表單才允許原址修改。其他情況應顯示唯讀清單；不要為了讓按鈕出現就重建正式排程或刪掉舊設定。PR 也明確指出 repository 更新依賴 Automation service 的配套變更，不能只看 Canvas 1.31 的版本字串。

用停用的測試 Automation 保存前，記下每個 URL、branch 與 provider。只改一項後保存，關閉 editor，從詳細頁重新打開，再從列表重新進入一次，比對兩條路徑都讀回同一份清單；這能找出保存後仍使用舊快取的情況。若少了一個 repository，先保留原紀錄與回應，不要用空清單再次保存。最後才在受控環境執行一次任務，確認 checkout 的來源與 ref；本文未執行這些步驟，表單讀回也不能代替實際 clone 驗收。

1.29：default 和命名 profile 的設定來源不同#

1.29.0 的實際發布時間是 2026-10-20 22<22> UTC，台灣時間為 10 月 21 日 06<22>。PR #18720在前面幾個 profile 編輯 PR 後合併，改掉早期 PR 截圖裡「default 請到全域頁面修改」的部分限制；讀新版行為時要以最後實作為準。

本機 OpenHands default 與部分全域頁面共用設定來源：Skills 頁面編輯它的 skills；它使用目前 active LLM profile，載入 MCP Servers 頁面已啟用的伺服器，並可使用所有 Secrets。其 Secrets 沒有逐項選擇器。ACP default 仍保留自己的 Secret 與 MCP scope，不能從名稱相同推論權限也相同。

命名 profile 則保存自己的行為與模型參照。新增 profile 會從 default 複製多項初始行為，複製不代表後續持續同步。Home 的 profile 與 LLM pill 可協助確認下一次啟動的組合；選了命名 profile 時，不應只看全域 active model 就認定會用那個模型。

Condenser／Verification 編輯 PR #18679、Model Router PR #18685及 Skills PR #18686提供 profile 層級控制。critic API key 仍是全域資料，不能因為每份 profile 能開關 verification，就推論每份都有自己的 critic key。Skills 的完整清單亦受 server catalog 與 backend 支援影響，Cloud 不應直接套用本機 Skills／Router 操作。

1.28 對話內 Secrets：先確認儲存與附加結果#

Secrets 請求 PR #18408建立 request_secret(name, reason)，讓 Agent 指出缺少的憑證與用途；後續 PR #18575把原先 modal 改成對話中的 inline card。兩項都列在 1.28.0 release，不應照最初 PR 把正式介面描述成一定彈出視窗。

這條 client tool 的初始適用範圍是本機 OpenHands-agent conversation，不能推論 ACP、Cloud 或任意第三方 harness 都有同一張卡片。設計會透過既有 Secrets 路徑保存與附加參照；回報給 Agent 的狀態可為 saved、not_saved 或 error，工具回報不包含原始憑證值。

可以用短效、低權限的測試憑證分開驗收：

1. 核對目前 backend、conversation、要求的 Secret 名稱與用途，透過 Secrets 表單輸入，不把值貼進聊天或問題回報。
2. 先測取消，確認 Agent 不會把缺少憑證的步驟宣告完成；不需要該憑證的工作可以另外進行。
3. 再測保存，區分「設定已保存」和「已附加到目前 conversation」。保存成功但附加失敗仍可能回報 error，不能只從 Settings 裡有項目就認定 session 已可使用。
4. 在預期的服務入口做一個無副作用的最小驗證，保留狀態與錯誤類型，避免保存或分享含 token 的完整 request／response。

如果同名 Secret 已存在，原始設計也允許直接附加，不一定再次詢問。想驗證取消路徑，應在隔離的測試範圍使用未存在的名稱；不要為了重現卡片刪除正式憑證。上述是依 PR 契約設計的驗收，本文沒有執行，亦不把「值不在回報訊息」解讀成工作中的 Agent 完全不能使用憑證。

切換 backend 後先讀回設定，再按保存#

PR #18401處理 Application settings 沿用另一個 backend 的快取表單值，進而可能把舊 Git 身分寫到目前 backend 的問題。這比模型選單看起來沒刷新更直接影響設定內容。

升級後先用測試 backend 做 A → B → A 切換，確認頁面顯示各自的 Git 身分；若有未儲存修改，也要確認沒有跟到另一個 backend。需要保存時，核對畫面標示的 backend／組織，成功後重新載入讀回，才能確認值落在正確位置。不要在混淆來源時反覆按 Save。

PR #18490另外調整設定請求的重試：一般 4xx 不再重送，408、429、5xx 與沒有 HTTP status 的網路錯誤仍有不同處理。遇到 422 應先修正輸入與讀取服務端錯誤，不要把「只送一次」當成連線故障，也不要自行把所有失敗都加成無限重試。

Automation 改排程：歷史測試通過不代表現在可保存#

既有 custom-script Automation 若曾上傳 bundle，編輯排程卻被要求補 setup script path，PR #18649修正的是編輯草稿遺失既有 bundle 資訊。這個修正不等於所有新建 Automation 都能省略原本必要的設定。

驗收時保留 Automation ID、原排程與既有 bundle 記錄，先只改一個排程欄位，確認保存請求成功，再重新開啟同一個 ID，讀回排程與 bundle。若 UI 阻擋、根本沒有送出 request，和 backend 收到請求後拒絕，是兩條不同的排錯路徑；不應先重建或刪除整個 Automation。

PR #18617則讓目前保存草稿的驗證錯誤優先於歷史測試狀態。之前的 Test passed 仍屬於當時輸入；改了 cron、workspace 或其他設定後，要重新確認目前有效性。對排程本身，還要分開查時區、下次執行時間與測試產物，不能從一枚綠色狀態推論整條流程都成立。

1.27.0 Docker 重啟迴圈：先比對缺少模組的錯誤#

官方修正 PR #18343記錄，1.27.0 的 static-server.mjs 需要 MARS web bridge，但 Dockerfile 漏了它及相依模組。只補一個 mars-web-bridge.mjs 仍會缺少其他本機模組與 ws 套件；v1.27.1 Dockerfile已加入相關 COPY。

這個已知問題以 ghcr.io/openhands/agent-canvas:1.27.0 為範圍，不代表所有 OpenHands launcher、Local GUI 或 Docker 啟動失敗都出自同一原因。先在原本管理 container 的主機檢查，將 YOUR_CONTAINER 換成自己的 container 名稱：

1
docker inspect --format '{{.Config.Image}} {{.Image}} {{.State.Status}} {{.RestartCount}}' YOUR_CONTAINER
2
docker logs --tail 100 YOUR_CONTAINER

這兩行是供讀者執行的唯讀診斷，本文未對實際 container 執行。第一行同時保留建立 container 時的 image 名稱與實際 image ID；latest 是浮動標籤，不能單靠這個字判斷正在跑哪個 build。第二行要比對模組路徑，分享 log 前先移除敏感資料。

確認符合此症狀後，先保存原本的掛載、啟動參數與資料備份，再透過既有部署方式換到已修正的 1.27.1 image。不要把手動複製單一模組當成完整修復，也不要刪除持久化資料來消除重啟紀錄。

新 container 啟動後，核對三層結果：

1. 實際 image ID 已變更，log 沒有相同缺檔錯誤，RestartCount 不再持續增加。
2. 在自己的映射位址檢查 /health 與 Canvas 介面；官方 smoke test使用 health 回應及持續存活檢查，單次 container 顯示 Running 不夠。
3. 用無敏感資料的 workspace 執行一個可核對產物的任務，再確認原有 Automation。health 通過只驗證服務入口，不能代替模型、Secrets 或任務驗收。

這是依官方修正設計的驗收流程；PR 裡的 Docker 結果是維護者提供的證據，不是本文的本機測試。

ACP 顯示 Agent default 時，檢查實際模型來源#

1.27.0 的模型探索修正 PR #18131讓 ACP 清單來自 agent，而非 Canvas 自己硬編碼。Agent default 儲存的是 acp_model: null，表示讓 agent 決定模型，不是固定的通用 model ID。

本機 backend 可在開始 conversation 前探索模型；清單與 backend、Secret scope 有關。舊 agent-server、探索失敗或 Cloud 路徑可能使用先前記住的清單，因此「選單列得到」仍不等於目前帳號能成功呼叫。現有 conversation 應以它回報的模型為準，不能拿全域 Settings 的模型欄位當作執行證據。

驗收時先記錄 backend 與 profile 允許的 Secrets，等待探索結果，再開一個新 conversation，核對該 session 回報的模型及一次簡單任務結果。如果更換登入或 Secret scope 後選單不同，先查來源與登入錯誤，不要直接手填別的供應商 model ID。

OpenCode／Pi preset PR #17758另有 local-only 邊界：1.27.0 的內建入口限本機 backend，不能推論 OpenHands Cloud 也支援相同 harness。Pi 的模型依 credential 決定；OpenCode 的 credential 欄位可略過，也不表示付費模型已取得使用資格。若問題是 OpenCode Go 本身的訂閱與 provider，可對照 OpenCode Go 的模型與呼叫檢查，並另外核對 OpenHands 的 ACP session。

1.26 的 Successful 要搭配任務結果看#

Automation 狀態修正 PR #17682調整完成 run 的顯示規則：缺少 task outcome 的 status 時，以成功標章顯示，仍保留 outcome_summary；明確提供但無法辨識的 status 字串，繼續顯示 Needs review。這是在減少舊版或不完整 finish response 的誤報，沒有替任務產物增加驗證。

升級後用一個無敏感資料、能明確檢查結果的測試任務驗收，例如要求 Agent 列出指定範例檔的三個欄位：

1. 記錄 backend、Automation ID、run ID 與執行時間，確認看到的是本次 run。
2. 對照執行狀態與 outcome summary；摘要說「完成」仍要打開產物，核對三個欄位是否存在且正確。
3. 遇到 Needs review，先讀明確的 outcome 與錯誤內容；遇到 Successful 卻沒有產物，保留該 run 的 log 再查任務流程，不能只改通知設定。

這三項是供讀者執行的驗收流程，本文未派送 Automation。官方 PR 也指出，其當時的 live SDK 要求 finish response 有 status，因此 summary-only 相容案例是在前端測試邊界驗證；不能據此要求目前 backend 發出同樣的省略欄位 payload。

1.21 到 1.29：先確認自己使用哪一種執行路徑#

v1.25 批次新增 profile，先核對 connection#

批次模型 PR 提供一次新增多個 LLM profile 的入口；後續 connection PR 讓新增的 profile 可以綁定 provider connection。這兩條路徑需要不同驗收：

• 選擇匹配的 connection：確認它屬於預期的供應商、帳號與 Base URL，再新增少量模型。建立後先做無敏感資料的最小呼叫，確認帳務與連線來源正確。
• 選擇 No connection (keyless)：新增的是沒有 connection 綁定的 profile，後續仍須補齊憑證或可用的連線設定。不要把「建立成功」解讀成「可以呼叫模型」。
• 從某個 connection 的選單開啟批次新增：官方 PR 描述這條入口會預選載入的模型；送出前應取消不需要的項目。從一般 provider 選擇器進入時則不預選，避免直接碰到帳號 profile 數量限制。

先建立一個模型、測完再增加，比一次選整份目錄容易確認問題屬於 profile、憑證或服務端限制。若批次過程有失敗，回到 profile 清單確認哪些已建立，不要直接重送全批造成重複名稱。

第一個 Router 建立後，檢查首次訊息開關#

Router 開關 PR 新增 Run on first message，需有 active router 才有作用。後續 PR 在 router 數量從零變成一時自動開啟；之後新增 router 不會再覆寫開關。不能只從最初 PR 的「預設關閉」推論第一次建立後仍維持關閉。

如果你希望固定模型，建立 router 後先關閉該選項；希望自動選模型，則用新 conversation 驗證第一則訊息的事件與實際切換結果。建議記下：

1. 執行 backend、active router 與開關狀態，重新載入設定頁確認有保存。
2. 路由選到的 profile，以及它綁定的 connection；不要只看聊天標題或預設模型名稱。
3. 用同一個無副作用任務比較開關開啟與關閉後的兩個新 conversation。

官方開關 PR 指出 Cloud GUI 的設定欄位與預載資料尚有適用限制；本文沒有驗證 v1.25 在每個 cloud 部署的行為。雲端使用者應確認當前 backend 的支援與事件結果，不能將本機設定頁存在當成所有 launch 路徑都會路由的證據。

v1.24 升級時要驗證的三個邊界#

Release note 只列出功能名稱，升級後仍應確認它套用在哪個 backend，以及實際使用者能看到什麼：

1. 切換 backend 或組織後重新看訂閱狀態與模型清單：v1.24 將 OpenAI 訂閱狀態與模型查詢的快取 key 加上 backend ID 和組織 ID。若你同時使用本機與雲端 backend，分別切換兩邊，再確認顯示的帳號和模型目錄沒有沿用前一個選擇的快取資料。這是用來驗證前端顯示，不代表 API 金鑰或訂閱已在兩個 backend 間共用。
2. 從 Automation 活動紀錄打開分享對話：官方 PR 描述的是已登入的同一組織成員透過 cloud backend 開啟唯讀 conversation；畫面沒有輸入框。用 Automation owner 和同組織另一位已登入成員確認檢視方式，再檢查對話是否可讀。唯讀檢視描述的是 conversation 頁面，不應推論成 Automation 執行本身沒有寫入權限。
3. 確認分組資料夾整批切換只影響目前可見項目：在 Conversations 使用 workspace 分組時，標題可收合或展開所有可見資料夾；篩選掉的資料夾保留原本狀態。切到時間排序或沒有資料夾的畫面時，標題仍是一般標籤，不是整批操作按鈕。

這三項查核把「畫面已更新」拆成資料快取、雲端讀取權限和側欄狀態，避免把某一個 UI 結果誤當成另一個 backend 的設定或權限證明。

Release notes 列出功能名稱，沒有替每個部署環境提供可通用的 Docker server 設定值。若你要設定遠端 workspace 或 cloud MCP，請先確認所用 backend 的管理文件和實際權限，不要直接複製本機 GUI 的 Docker 指令。

Agent profile、Secrets 與 Automation 的 1.20 更新#

這些變更不是「建立 profile 後就自動安全」。profile、Docker、automation 和 workspace 是四個互相影響但不能互相代替的邊界；要用小任務逐一驗證。

用 Agent profile、Secrets 與 Automation 的驗證順序#

不要先把所有既有 automation 切到新版本。建議依序做：

1. 記錄目前 OpenHands、CLI launcher、agent-server、automation 與 Docker image 版本。
2. 列出現有 LLM profile、可用 Secrets、MCP server、workspace mount 與 automation owner。
3. 建立一個只含測試資料的 workspace，先執行不修改檔案的任務。
4. 建立或複製一個低權限 Agent profile，只選取該任務需要的 Secret。
5. 在新的 conversation 檢查 Docker runtime 設定與實際 workspace path，再測試最小寫入任務。
6. 最後才讓一個可停用的 automation 使用已儲存 profile，確認 task outcome、權限錯誤與執行身份。

如果舊 conversation 還像在使用舊模型或舊設定，不要只看 profile 名稱；重新啟動 conversation，並從事件、設定頁與實際模型呼叫確認。這篇文章的版本資訊是 release 與文件查核，不是本機執行紀錄。

安裝 CLI launcher 與啟動 GUI#

官方目前的本機 launcher 流程需要 Python 3.12 以上、uv 與可用的 Docker 環境。先依 uv 安裝文件 完成 uv，再安裝 OpenHands：

1
uv tool install openhands --python 3.12

進入準備交給 Agent 的專案目錄，從該目錄啟動並掛載目前 workspace：

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

完成後開啟：

1
http://localhost:3000

第一次只想確認介面與 Docker 是否可用，可以在不含敏感檔案的測試目錄執行 openhands serve。不要為了方便把整個家目錄掛載給 Agent；--mount-cwd 不是唯讀模式，掛載範圍內的檔案可能被讀取或修改。

這個指令啟動本機 GUI server，並把目前目錄掛載給 Docker conversation；它和新版 CLI 的互動式 terminal mode 是不同路徑。若要固定 Docker image、agent-server tag 或啟動參數，請依目前的 OpenHands Local setup 文件 為準。舊教學中的 all-hands-ai image 路徑或單一 image tag 不一定能和目前 launcher 組合。

建立 LLM profile，先限制 Secrets 再談模型#

開啟 OpenHands 後到 Settings → LLM 設定 provider、model、Base URL 與 API Key。實際可用模型、名稱與費用會隨供應商和方案變動，請以目前設定頁與 provider 文件為準，不要把文章中的 model id 當成永久答案。

建議 profile 以任務或權限命名，例如：

1
docs-readonly
2
repo-test-with-registry
3
release-maintainer

建立 profile 時用「這個任務真的需要什麼」反推 Secret 範圍：

• 只讀文件任務不應取得 repository write token、production credential 或發布金鑰。
• 需要安裝相依套件的任務，先判斷是否真的需要 registry token；能用公開套件就不要附帶私有憑證。
• 需要 Git push 或部署的任務，將它分成另一個明確 profile，並讓執行者知道該 profile 有外部副作用。
• 測試 profile 要檢查 ambient environment 是否被意外帶入，不要只在設定頁看到 Secret 名稱就判定隔離成功。

儲存後，在新的 conversation 以最小任務驗證：

1
先讀取 README 與套件腳本，不要修改檔案。
2
回報目前 workspace 的絕對路徑、使用的 Agent profile、可用工具與你沒有取得的權限。

如果 profile 有 MCP server 範圍，也要逐一確認只連到任務需要的 server。profile 能限制 Secret，不代表 MCP server 或掛載的檔案會自動變成最小權限。

Docker conversation runtime 要檢查哪些設定#

1.20 的 Docker conversation runtime settings forwarding 對可重現性有幫助，但「設定能被傳遞」不等於設定內容適合所有任務。建立 conversation 後檢查：

1. Image 與版本：記錄實際 image、agent-server 與 launcher 版本，避免只看 UI 顯示的產品版本。
2. Workspace mount：確認 container 內的專案路徑對應到預期的 host workspace，沒有意外掛載上層目錄。
3. 環境變數與 Secrets：區分一般設定、短期 token 與高敏感憑證；不要把 Secret 用明文寫進 prompt、Dockerfile 或 repository。
4. 網路與資源：任務若不需要外網，先關閉或限制；檢查 CPU、記憶體與 timeout，避免失敗只顯示成模型無回應。
5. 可回復性：先在 branch 或 worktree 執行，再以外部終端機查看 git status --short 與 diff。

若你需要同時讓多個 coding agent 工作，可以先看 Git worktree 管理多個 AI coding agent。分開 worktree 不能取代 Secret 或 container 權限檢查，但能降低互相覆蓋檔案的機會。

Automation 如何使用已儲存 profile#

升級後不要假設 automation 會自動沿用你最近一次手動對話的 profile。建立或編輯 automation 時，明確選擇已儲存的 Agent profile，再檢查：

• automation 的 owner、view／manage／edit／re-enable 權限。
• 實際選用的 model、Agent profile、MCP server 與 Secret allow-list。
• automation 執行時的 workspace、branch、container image 與 Docker runtime。
• 成功、失敗、取消、停用與重新啟用的 task outcome 是否清楚。
• 失敗後誰可以重新啟用，是否會把停用原因或敏感錯誤暴露給不需要的人。

第一次測試用可刪除或可停用的 automation，內容只做唯讀盤點：

1
列出目前 workspace 的 README、套件管理器與可執行測試。
2
不要修改檔案、不要安裝套件、不要連線到外部服務。
3
回報使用的 profile、workspace 路徑與 task outcome。

確認結果後，再增加一個能由 Git diff 驗證的小修改。不要用 production deploy、刪檔或旋轉憑證當第一個排程測試。

Workspace 與 Agent 權限的基本邊界#

在把 repository 交給 OpenHands 前，先在自己的終端機執行：

1
git status --short
2
git branch --show-current
3
docker ps

接著確認目前目錄沒有不想被讀取的 .env、SSH key、cloud credential 或未提交的敏感 diff。第一個 task 先要求唯讀。第二個 task 之前確認 hello-openhands.txt 不存在，檔名已有資料就換成你確認可用的新名稱；保留原始 git status --short，再要求建立可回復的小檔案：

1
建立 hello-openhands.txt，內容只有 OpenHands is ready。
2
完成後讀回檔案，執行 git status --short -- hello-openhands.txt，且不要修改其他檔案。

最後回到外部終端機驗證：

1
git status --short
2
git status --short -- hello-openhands.txt
3
cat -- hello-openhands.txt

若 hello-openhands.txt 是新的 untracked 檔案，普通 git diff -- hello-openhands.txt 可能沒有輸出；這不表示 Agent 沒有寫入。Git diff 文件 的一般工作區 diff 比較 tracked 檔案與 index，尚未加入 index 的新檔必須另外讀回。

驗收時應看到 ?? hello-openhands.txt，讀回內容也必須符合要求；若沒有出現在 status，先用 git check-ignore -v -- hello-openhands.txt 檢查 ignore 規則。整份 status 還要與開始前比較，確認沒有額外變更。

已追蹤檔案的未 stage 修改則用 git diff -- <檔案>；已 stage 的內容用 git diff --cached -- <檔案>。這項驗收不要求為了看 diff 先 stage，也不要把 workspace 原本的修改一起納入 Agent 成果。這裡的 Git 行為已在獨立暫存 repository 驗證；OpenHands runtime 與模型工具呼叫沒有在本次執行。

這個流程能分別確認 Agent 看到的目錄、模型工具呼叫、檔案寫入與實際內容。看到「任務完成」不等於檔案、branch 與 profile 都符合預期。

常見故障排除#

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

常見問題#