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 tutorial 会用的示例池：

不适合作为第一条 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（与下文案例里的 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 tutorial）：

# 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。