OpenHands 1.38 教學：Automation Profile、匯入與 Runtime 驗收

1.38：Preset 沒有 Agent Profile 選單，先查服務能力#

v1.38.0納入 PR #19421，讓 prompt 與 plugin presets 可以選 Agent Profile。顯示條件是服務宣告 presetAgentProfiles；只有 agentProfiles 的服務仍保留 model picker。這能解釋「Canvas 已升到 1.38，preset 仍只能挑模型」的情況，無須先刪掉原排程重建。

選到 profile 後，model pill 會鎖到該 profile 的 LLM profile。建立請求送 agent_profile_id，編輯時送 model: null，避免舊模型覆寫 profile 的選擇。ACP profile 則顯示 ACP，由它自己的模型路徑處理。

可用一個停用的測試 preset 驗收：

1. 保存 Canvas、agent-server、Automation service 的實際版本與 capability 回應，只記需要的非敏感欄位。先分辨服務有沒有 presetAgentProfiles，再看 UI。
2. 選一個已有且工具範圍清楚的測試 profile，確認 model pill 鎖定。保存後重開，對照 profile ID 與 model 欄位；介面顯示與後端保存各自記錄。
3. 在可拋棄 workspace 手動執行一次小任務，檢查實際 conversation 的 launched profile、工具與模型來源。若只驗收了保存，紀錄就停在「保存通過」。
4. plugin preset 另跑一次自己的案例。PR 作者的執行證據主要是 prompt preset，共用表單與程式路徑仍不能代替每種部署的端到端驗收。

以上是 2026-11-11 的 release、PR 與 diff 檢閱，本文沒有建立 profile 或執行排程。PR 裡作者使用的 automation service 對照版本屬其測試環境，不應當成所有部署的最低版本承諾。

1.38：Script Automation 搬家，要一起帶 bundle#

同版 PR #19330修正 script automation 只匯出空 prompt、漏掉執行 bundle 的問題。新版 spec.script 包含 entrypoint、選用的 setup script path 和 base64 tarball；檔案 envelope version 仍是 1，因此只看 version 無法判斷舊 importer 能否讀這種 script 規格。

在來源匯出一份測試 script automation，先檢查 spec.script 與 entrypoint，再於目標 backend 匯入。預覽應顯示 Script 入口，建立後應是停用狀態；核對時區、trigger、實際檔案及執行依賴後，才在隔離 workspace 手動驗收。需要遷移 Secrets 或外部權限時另行核對，base64 只是編碼，不能提供保密性。

若來源拿不到 bundle，新版會報匯出錯誤；若目標仍回 spec.prompt: expected a non-empty string，先核對 importer 是否支援 script。保留來源和原排程，避免拿缺內容的匯出檔當成已驗證的備份。本文只檢閱匯出／解析與匯入差異，尚未跨 backend 搬移或驗證 tarball 完整性。

1.37：舊對話先等歷史回放，再判斷是不是空白#

v1.37.0納入 PR #19377，在 session replay 尚未結束時延後顯示空對話的起始建議。另有 PR #19400修正恢復標記的排序：針對沒有錨點的恢復事件，缺時區尾碼的歷史時間仍須按 UTC 比較。

驗收準備兩筆資料：一個有已知末則訊息的舊對話，以及一個確實空白的新對話。固定 backend 與工作區，用重新整理或重開分頁回到舊對話，等它載入後核對最後一則訊息與恢復標記的順序；再打開新對話，看起始建議是否在確認無歷史後出現。若舊對話一直沒載入，先記下 conversation ID、backend、Canvas 版本與連線狀態，再檢查歷史請求或 WebSocket 重連。畫面短暫空白和歷史資料無法讀回，需要不同證據。

1.37：子路徑首頁要測有無尾斜線#

Canvas 部署在例如 /canvas/ 時，PR #19406在瀏覽器初始化前把精確命中的 /canvas 改為 /canvas/，並保留 query string 與 fragment。這項修正要等瀏覽器收到並執行 Canvas 頁面才會生效。

從新分頁直接打開 /canvas?probe=1#top，確認首頁能顯示、參數和 fragment 保留；再打開 /canvas/ 與一個有效的對話網址，確認深層路由沒有被首頁修正影響。如果第一個網址先在反向代理回 404，先查代理路由；若 HTML 已回傳卻無法初始化，再查 Canvas 版本與資源路徑。以上流程依 2026-11-10 版本與 PR 檢閱整理，未啟動 Canvas 或代理驗收。

1.35：記住 repository 後，送出前仍要核對 branch#

PR #19053將 Cloud 首頁 launcher 選擇的 repository、branch 與 provider，依 backend ID 保存在瀏覽器的 home-store。回首頁後可顯示上次選擇；這是該瀏覽器的本機保存，不能據此推定其他裝置或 profile 已同步。

1.35 的驗證 hook會檢查 provider 是否仍連接、branch 查詢是否成功，以及回傳清單是否有完全相同的 branch 名稱。失效選擇會清掉，查詢使用停用 toast 的設定；因此首頁選擇消失時，先查連線與 branch，暫時查詢失敗也可能是原因。

用無敏感資料的測試 repository 驗收：

1. 記錄 backend、provider、repo 與 branch，離開首頁再回來，確認選擇仍在；接著重新整理再檢查一次。
2. 切換另一個測試 backend，核對選擇依 backend 分開。回原 backend 後，送出前再次讀取 repo／branch；建立對話後從實際 workspace 的 Git 資訊比對。
3. 點選清除控制項，確認回到選取入口，重開頁面仍維持清除。Local backend 的同一控制項則清除目前 workspace 選擇。
4. 選擇意外消失時，檢查 provider 連接、查詢錯誤與 branch 是否存在，再重新選取。保留非敏感錯誤即可，直接編輯 storage 或重授權不應是第一個步驟。

背景驗證完成前，launcher 可能已顯示記住的選擇。PR 說明此時提交會帶入該 repository，若不可用則顯示錯誤；所以「畫面出現 repo」與「新對話確實使用正確 repo」要各留一份證據。尚未在本文環境建立對話或模擬斷線。

1.35：Files 下載先分 Local bytes 與 Cloud text#

PR #19076在 Files 工具列加入 Download。版本中的下載 hook對 Local fileserver 讀取檔案 bytes；Cloud 的這條路徑則以已解碼文字重建 Blob。Cloud 圖片、PDF 等缺少解碼文字的檔案，下載鈕會被隱藏，等待可保留 bytes 的傳輸支援。

驗收時準備一份 Markdown 和一份小型 PNG，內容使用測試資料：

• Local：Refresh 後各下載一次，用自己的外部終端機計算來源與下載檔的 SHA-256，確認檔名和 bytes。再改動測試文字檔、Refresh，檢查下載的是新內容。
• Cloud：先確認文字檔內容；若只有圖片／PDF 缺下載鈕，核對是否仍在這個傳輸限制內。文字能下載只證明文字路徑可用，二進位檔完整性仍需獨立驗證。
• 讀取失敗：先保留錯誤與檔案類型，確認目前部署是否已包含 Canvas 更新；檔案未載入或讀取失敗時，先恢復讀取再檢查下載。

以上是文件與原始碼檢閱後的驗收設計，沒有重做 PR 作者的實測。下載完成後仍需檢查檔案內容及敏感資訊；若要交給另一個 Agent 接手，附上版本、來源路徑和驗證結果，比只傳下載成功訊息更容易核對。

1.34：Runtime 預設值和這次啟動分開檢查#

PR #18436依本機 backend 的 server_info.available_conversation_runtimes 決定是否提供 Docker。開啟資料夾時可有 Local、Worktree、Docker；沒有資料夾時則沒有可供建立 Worktree 的 repository。Settings → Runtime 可以選預設模式，再顯示該模式的選項。

選擇順序是這次 launcher 明確選取的模式、Settings 預設值，最後才是瀏覽器記住的模式。不要只改 Settings 就假設已經改掉目前 launcher 的選擇，也不要把新對話預設值當成舊對話已完成遷移。

先在不含敏感資料的測試 workspace 驗收：

1. 記下 Canvas、agent-server 版本和 backend，檢查回報的 runtime 能力。1.34 的版本設定將 minimumAgentServer 設為 1.57.0；升級時仍要核對實際配套，不只看產品標題。
2. 在 Settings 選 Docker，保存後重開確認值；接著在 Home 檢查這次 launcher 的選擇，再建立全新 conversation。將明確切成 Local 的另一個新對話作為對照。
3. 在自己的外部終端機核對產生的容器、實際工作目錄、掛載與生效的 CPU／記憶體設定。Agent 自述「在 Docker 中」和 launcher 標籤，都不能代替這些執行證據。只讀回自己設定的非敏感值，不匯出整份環境變數。
4. 使用另一個不支援 Docker 的受控 backend 時，確認能力回應後不再提供 Docker；若設定仍記著舊 Docker 預設，檢查 Local fallback 提示。先核對再啟動，不要在正式工作區刻意破壞 Docker 來測試 fallback。

Runtime 頁的容器資源選項不涵蓋 image、閒置停止、儲存保留和磁碟預算等 server 全域政策。若問題是容器生命週期或映像，應查 agent-server 的設定，不能期待改 CPU 欄位順便改掉它們。PR 也記載 selectable 模式下 planner conversation 與開發腳本 host alias 仍有 server-wide runtime 限制；需要這些路徑時要另行驗收。

本節只完成文件與原始碼查核，沒有實際建立對話、驗證資源限制或測試 fallback。升級驗收需同時保留「選了什麼」和「實際在哪裡執行」兩份證據；若問題是不同 Agent 同時改同一個 repository，可搭配 Git worktree 工作流程，但 worktree 本身不提供 Docker 隔離。

1.34：Automation 標籤不見，先檢查 manifest 與服務配套#

同版的 PR #18767加入 Automation 標籤顯示、篩選與建立者編輯。但這個 PR 是 Canvas 介面實作，明確依賴 Automation service 和 extensions manifest；只看到 1.34 的版本字串，不能保證部署已有篩選器。

先分開看三項證據：Automation 回應是否有 tags、manifest 是否宣告 tag filter 與選用的 endpoints.tags，以及服務是否能回傳標籤選項並處理 ?tag=。缺少相關支援時，介面可維持舊行為；先核對正式配套版本，不要直接修改安裝目錄裡的 manifest 來強迫按鈕出現。

標籤規則原始碼將 Software Factory 正規化為 software-factory。這套規則不是任意中文分類輸入框；例如底線形式的 q3_release 不符合該版格式。可見標籤也不代表可編輯：介面與服務將編輯限制在 Automation 建立者，組織成員身分本身不夠。

用停用、可拋棄的測試 Automation 驗收，避免把分類操作混進正式任務執行：

1. 記錄原有標籤完整清單與目前 backend。以建立者新增 Nightly Checks，確認畫面顯示正規化後的 nightly-checks，再保存；保存送出的是整份標籤清單，不是只追加一個字串，因此要確認原有標籤沒有意外消失。
2. 關閉詳細頁再重新開啟，比對清單；接著回列表選該標籤篩選，確認找到這份 Automation。標籤 pill 可見、清單保存成功與篩選結果正確，分別記錄。
3. 若有既有的非建立者測試帳號，以其開啟同一份測試項目，確認只讀顯示。不要為了測試另外擴大正式帳號權限，也不要把隱藏編輯鈕當成後端授權已獨立驗證。
4. 任何步驟失敗時，保留非敏感的版本、欄位是否存在與錯誤，先查配套與回應；不要用空清單覆寫，也不要重建原本仍在工作的排程。

這是文件與原始碼查核後的驗收流程，本文沒有保存標籤、測試授權或執行排程。標籤是整理與查找線索；改標籤本身不能證明排程時區、觸發條件或實際任務執行正確。

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

常見問題#