OpenHands 1.24 教學：Agent profile、Secrets 與 Docker 權限檢查

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

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 才建立可回復的小檔案：

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

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

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

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

常見故障排除#

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

常見問題#