OpenHands：Cloud Mac 從「工具集合」到Agent 平台

過去兩週，我們在 Stack 連載裡把 L1 Runner（Fact）、L2 Ollama（Inference）、L4 MCP（Context） 一層層立起來。很多讀者回饋同一句話：「工具都接上了，但每天還是在手動串流程。」 Claude Code 能改 diff，MCP 能拉 GitHub 上下文，Runner 能在 push 後變綠——可「修完 issue #142 並提 PR」仍要人坐在終端機前盯 40 分鐘。

這就是 L5 · OpenHands 要回答的問題：不是再買一個 CLI，而是把 Cloud Mac 從工具集合升級成能自主跑完多步工程任務的 Agent 平台。本篇是 L5-Q01 · R1 · 系列 Hub：負責把讀者從「編碼工具」帶到「Agent 平台」認知層——講清 Workflow 層在 Stack 裡的位置、OpenHands vs Claude Code 為何不是替代關係、典型任務與 OpenHands self-hosted on macOS 架構；不含 Docker 安裝步驟（那是 L5-Q02 的 SEO 落地頁）。

「工具集合」陷阱：每個都好用，整條鏈仍靠人肉

典型一週現場（我們自己在客戶倉庫裡見過多次）：

1. 週一：用 Claude Code 改 API 層，MCP 拉 GitHub issue 列表，會話內一切順利。
2. 週二：同事用另一台機器 push，Runner 紅了——沒人把 Agent 的改動與 CI 腳本對齊（若未讀 L1 執行引擎，這裡會反覆踩坑）。
3. 週三：手動跑測試、改設定、再開 Claude Code 會話補檔案。
4. 週四：終於綠勾，但文件、遷移腳本、範例測試仍缺——因為「改程式」和「交付需求」被當成同一件事。

工具集合的特徵是：每一步都有最佳工具，但沒有一層對「整條需求」負責。 Agent 平台多出來的，是一個能自己拆任務、自己執行、自己根據失敗重試的 Workflow 層——OpenHands 就是 Stack 裡承擔這一層的開源選項（前身 OpenDevin 生態）。

Stack 語言：Workflow 與 Context / Diff / Fact

全系列統一記法：不用單向箭頭把 Workflow 畫成 Fact 的下游。Workflow（L5）是編排層，在任務週期內反覆消費 Context、產出 Diff、用 Fact 校驗，直到判定「需求完成」：

Cloud Mac AI Stack · 產出物關係（非呼叫順序）

  Workflow（L5 · OpenHands）
  ├── Context（L4 · MCP）          ← 讀 repo / issue / API
  ├── Diff（L3 · Claude Code 等）  ← 改程式 / 寫檔案
  └── Fact（L1 · Runner / 測試）   ← 跑 test / build / CI 訊號

Agent loop（Workflow 內部 · 可多次迭代）
       Diff  ↔  Fact
         ↑       ↓
      Observe → 再 Plan → 再 Execute …

四個產出物並列記憶：Context · Diff · Fact · Workflow（對應 MCP · 編碼層 · Runner · OpenHands）。Inference（L2 · Ollama）為可選，不畫進上圖，避免與 Agent loop 混淆。

Workflow 不是「又一個 CI job」，而是跨多步、可中斷可恢復的任務狀態機：在循環裡多次呼叫 Diff 與 Fact，直到 PR 可交付。Claude Code 擅長單輪 Diff；OpenHands 擅長無人值守地跑完整個 loop——前提是你已鋪好 Context 與 Fact。

OpenHands 一分鐘定位（不是百科）

OpenHands 是開源的自主軟體工程 Agent 平台：在沙盒環境（常見為 Docker）裡接收自然語言目標，自動完成規劃 → 寫程式/跑命令 → 讀輸出 → 除錯，並可對接 GitHub（issue、PR、CI 狀態）。在 Cloud Mac AI Stack 裡，它不替代 Claude Code 的結對體驗，也不替代 Runner 的客觀建置證明，而是在二者之上編排多步交付。

OpenHands vs Claude Code：為什麼兩者不是競爭關係

搜尋 OpenHands vs Claude Code 或 Claude Code alternative 的人，往往在問：能不能用一個換掉另一個？ 在 Cloud Mac AI Stack 裡，答案是不能也不該——它們處在不同層，產出物不同：

• Claude Code（L3） → 生產 Diff：結對編碼，你在場。
• OpenHands（L5） → 生產 Workflow：自主 agent，你定目標。

把 OpenHands 當成「另一個 Claude Code」會立刻踩坑：OpenHands 不擅長對齊你腦子裡模糊的產品直覺；Claude Code 也不擅長無人值守跑完 8 步 issue。正確姿勢是疊層使用——下午你用 Claude Code 啃硬骨頭，夜間讓 OpenHands agent 清 issue 佇列。

經驗法則（非合同）：你在 PR 裡能一句話說清改動意圖 → 用 Claude Code；你要說的是「把 issue 做完」→ 考慮 OpenHands。 大倉庫裡若已用 CodeGraph 建索引，結對層往往仍用 Claude Code；OpenHands 更適合接已模板化的後端任務。兩者共享 MCP Context 層，但不共享職責。

OpenHands 能做什麼任務？（搜尋使用者的第一問）

很多人搜 OpenHands agent 或 OpenHands github，真正想問的是：丟給它什麼活靠譜？ 下面是我們建議在有測試 + 有 CI 前提下優先嘗試的任務類型——也是 L5-Q02 教學會用的範例池：

不適合作為第一條 OpenHands 任務：無測試的大重構、UX 大改、需要業務審批的 schema 遷移、直接觸達生產金鑰。這些仍應留在 Claude Code 結對會話裡，由人把關後再交給 Runner 出 Fact。

OpenHands 的工作原理（How OpenHands Works）

搜 How OpenHands works、OpenHands architecture 或 OpenHands agent loop 的人，想搞清的不是 Docker 命令，而是：自主 agent 怎麼把一句話變成可 merge 的 PR？ OpenHands 的核心是四步循環——業界也常寫作 Plan → Execute → Observe → Debug：

OpenHands agent loop（概念 · 非單次流水線）

        ┌──────────┐
        │   Plan   │  ← Context
        └────┬─────┘
             ▼
        ┌──────────┐
        │ Execute  │  → Diff
        └────┬─────┘
             ▼
        ┌──────────┐
        │ Observe  │  ← Fact（test / build / CI）
        └────┬─────┘
             │
      未通過 │ 通過
             ▼
        ┌──────────┐        ┌─────────────┐
        │  Debug   │ ──────▶│ Workflow 完成│ → PR / 交付
        └────┬─────┘        └─────────────┘
             │
             └──── 回到 Plan 或 Execute（下一輪）

這與「裝一個更強的 Chat」完全不同：OpenHands architecture 的關鍵是有狀態的任務機——每一步的 Observe 結果都會寫進軌跡（trajectory），供下一輪 Plan 使用。上表裡的 Fix bug、Lint cleanup 等任務，本質都是同一 loop 的不同入口；差別只在 Plan 階段的目標句不同。下一步 真實任務回放 用一條 issue 把四步跑滿一輪；Docker 與 UI 設定見 L5-Q02。

先疊 L0–L4，再談 L5：否則 Agent 在沙盒裡自嗨

我們反對「第一天就裝 OpenHands」的堆工具路線。推薦順序與 L1 篇接入順序一致，並在 MCP 之後加 L5：

1. L0 — Cloud Mac 常駐 macOS 節點。
2. L1 — Runner：push → 綠/紅 可重複。
3. L2–L3 — 可選 Ollama + Claude Code，在 Fact 之上編碼。
4. L4 — MCP Hub + 權限模型：Agent 讀什麼、寫什麼可稽核。
5. L5 — OpenHands：多步 Workflow。

缺 L1 時，OpenHands 可以技術上跑通並開 PR，但團隊無法判斷 merge 風險——這和「Claude Code SSH 全綠、Actions 全紅」是同一類組織事故。缺 L4 權限層時，自主 Agent 的 token 暴露面會放大，見 MCP 安全 spec。

真實任務回放：Plan → Execute → Observe → Debug 跑滿一輪

下面是我們用 OpenHands 在沙盒 fork上回放的一類任務（數字為示意）。可對照 工作原理 裡的 agent loop 逐步匹配：

目標：修復 issue #218「匯出 CSV 缺 UTF-8 BOM」

  ① 讀 issue + 相關 src/export/*.ts     ~2 min · Context（MCP/Git）
  ② 產生 6 步計畫                       ~1 min · Plan
  ③ 改 4 個檔案 + 新增 1 個測試         ~8 min · Execute
  ④ 跑 pnpm test → 失敗（快照不匹配）   ~3 min · Observe · Fact
  ⑤ 讀日誌 → 再改 2 個檔案              ~5 min · Debug → 再 Execute
  ⑥ 再跑測試 → 綠                       ~3 min
  ⑦ 開 PR，鏈 issue                     ~1 min · Workflow 交付

合計約 23 分鐘 wall time · 人工僅：批准目標 + 最終 merge review

注意第 ④ 步（Observe）：測試失敗不是災難，而是 agent loop 的輸入。 結對工具裡你往往當場改；OpenHands 要靠 Observe → Debug 把 Fact 餵回下一輪 Execute。若倉庫沒有穩定測試命令（L1 未固化），Observe 無訊號，loop 容易空轉——這又是先 Runner、後 OpenHands 的原因。

觸發側的概念設定（非安裝教學，僅說明與 GitHub 的銜接方式）：

# 概念：issue 標籤觸發自主任務（偽程式碼 · 實際以 OpenHands 整合設定為準）
on:
  issues:
    types: [labeled]
if: github.event.label.name == 'agent:openhands'
run: |
  openhands run \
    --repo "${{ github.repository }}" \
    --issue "${{ github.event.issue.number }}" \
    --max-iterations 40 \
    --sandbox docker

Runner · OpenClaw · OpenHands：三個名字，三種腳

這是 L5 篇被問得最多的三角關係：

OpenClaw 不會替你做架構決策——它回答「何時跑、跑完怎麼通知」；OpenHands 不會替 Runner 簽名 iOS 包——它產出的是可 review 的 PR 與步驟日誌。三者可疊在同一台 Cloud Mac 上，但職責不要寫進同一篇 runbook。

OpenHands 在 Cloud Mac 上的典型架構（self-hosted · Docker · macOS）

搜 OpenHands Mac、OpenHands macOS、OpenHands self-hosted 或 OpenHands Docker 的工程師，通常要一張可落地的拓撲——不是安裝步驟，而是「元件放哪」。我們在 Apple Silicon Cloud Mac 上推薦的最小生產形態如下：

OpenHands self-hosted on macOS（Cloud Mac · L0 底座）

  GitHub（issues / webhooks / PR）
           │
           ▼
  ┌─────────────────────────────────────┐
  │  Cloud Mac · macOS · Apple Silicon   │
  │  ┌─────────────┐  ┌───────────────┐  │
  │  │ OpenHands   │  │ Claude Code   │  │  L5 Workflow + L3 Diff（可同機）
  │  │ (Docker)    │  │ (SSH/終端機)  │  │
  │  └──────┬──────┘  └───────────────┘  │
  │         │ sandbox workspace           │
  │         ▼                             │
  │  ┌─────────────┐  ┌───────────────┐  │
  │  │ MCP Servers │  │ Ollama (可選) │  │  L4 Context · L2 Inference
  │  └─────────────┘  └───────────────┘  │
  │         │ git push                    │
  │         ▼                             │
  │  ┌─────────────────────────────────┐  │
  │  │ GitHub Runner (self-hosted)     │  │  L1 Fact
  │  └─────────────────────────────────┘  │
  └─────────────────────────────────────┘

為什麼 Workflow 層放在 Cloud Mac，而不是筆電？

• 時長 — OpenHands agent 任務常跑 30–90 分鐘；筆電合蓋即斷。
• OpenHands Docker — 沙盒依賴穩定 daemon；Cloud Mac 24/7 常駐更合適。
• 與 Runner 同棧 — Agent 改完 → 同一 macOS 節點 Runner 驗證，減少「SSH 綠、Actions 紅」。
• ABI 一致 — iOS / macOS 目標倉庫在 Apple Silicon 上跑沙盒與 CI，比 Linux VPS 上硬套 Docker 更少驚喜。

最小 OpenHands Docker 啟動形態（概念片段，完整 docker compose 與 env 見 L5-Q02 教學）：

# Cloud Mac 上 · OpenHands self-hosted（示意）
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.9
docker run -d --name openhands \
  -e SANDBOX_USER_ID=$(id -u) \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.openhands:/.openhands \
  -p 3000:3000 \
  docker.all-hands.dev/all-hands-ai/openhands:0.9

L5 Agent Stack 推薦規格：從 Workflow 到該租哪台 Cloud Mac

讀完架構，下一個自然問題是：Workflow 層該配什麼機器？ 下面是我們按真實疊載給出的選型表（非合同 SLA，用於縮短決策時間）：

這條鏈路就是商業敘事裡的 Workflow → Cloud Mac → 規格：先確認你要的是 L5 能力，再選能穩住 Docker +（可選）Ollama + Runner 的節點，而不是反過來先租機器再堆工具。

適用與不適用：說清邊界比吹 Agent 更重要

腳本與小服務：是；強合規生產寫入：否。 這與 blog 戰略裡對 OpenHands 的定位一致——它是工程加速器，不是免責的「自動 DevOps」。

決策：你的 Cloud Mac 該升級為 Agent 平台嗎？

做完下面自檢，命中左列 ≥3 條再投入 L5；否則先把 L1/L4 補齊更划算。

結論（決策，不是總結）： OpenHands 的價值不在於「更聰明的 Chat」，而在於 Cloud Mac 從工具集合變成對需求負責的平台——但前提是 Fact（Runner）與 Context/權限（MCP）已立住。否則你只是把手動串流程，換成自動串流程，組織仍不敢 merge。

L5 專題連載：從決策到第一條自主任務

接 L6 閉環前，建議至少完成 ②：沒有可複製的 OpenHands tutorial，Hub 仍缺落地頁。全棧地圖在 L6-Q01；系列將從「AI Tool Stack」演進為「AI Engineering Platform」，L6-Q05 Agent Governance 補最後一環。

常見問題

How OpenHands works / agent loop 是什麼？
Plan → Execute → Observe → Debug 四步循環，消費 Context、產出 Diff、用 Fact 校驗；見 工作原理。

OpenHands vs Claude Code — 選哪個？
不是二選一。Diff 用 Claude Code，多步 issue 用 OpenHands；見 OpenHands vs Claude Code。

OpenHands tutorial / 怎麼安裝？
本篇是 Hub，不含逐步安裝。Docker + 第一條 issue→PR 見 L5-Q02（計畫 6/14 發布）。

OpenHands 能在 Mac 上 self-hosted 嗎？
可以。推薦 Cloud Mac 常駐 macOS + Docker 沙盒；架構見 典型架構。

沒有 Runner 可以直接上 OpenHands 嗎？
能跑，不建議。先 立 L1。

和 OpenClaw 呢？
編排 vs 自主工程；見 三角分工 與 OpenClaw 手記。

該租什麼規格？
見 L5 Agent Stack 推薦規格；僅 OpenHands 可 M4 16GB，疊 Claude Code 或 Ollama 7B 建議 24GB。