OpenHands

OpenHands（前身 OpenDevin）是目前开源世界里最接近「完整产品」的软件开发 agent 平台：有 Web UI、有 CLI、有云端托管版、有可编程的 SDK，底层跑在 MIT 协议下，2026 年中 GitHub star 数已超过 75K。它由 All Hands AI 公司维护，但治理上仍保持社区项目的形态——平台论文的 v3 版本（2025 年 4 月）署名作者超过 20 人，横跨 UIUC、CMU 和工业界。

这一页不做使用教程（文档站写得很全），而是回答三个工程师关心的问题：它的架构为什么长这样？CodeAct「动作即代码」的思想到底好在哪？以及它和一个学术血统的竞品 SWE-agent 在设计哲学上差在哪里。

一、从 OpenDevin 到 OpenHands：一场开源社区的反击

时间线值得记住，因为它是 2024 年 agent 热潮的一个缩影：

1. 2024 年 3 月，Cognition 发布 Devin，号称「第一个 AI 软件工程师」，但完全闭源、邀请制，社区一片「这东西我也能搓」的声音。
2. 2024 年 3 月（数周内），UIUC 博士生王星尧（Xingyao Wang）等人发起 OpenDevin 项目，作为 Devin 的开源复刻，GitHub star 数在头几周爆炸式增长，是当年增长最快的开源项目之一。
3. 2024 年内，项目更名 OpenHands，同期创始团队成立 All Hands AI 公司，CEO Robert Brennan（前 Google、Fairwinds 开源负责人），Graham Neubig（CMU 教授）任首席科学家，王星尧为联合创始人。
4. 2025 年 11 月，发布 OpenHands Software Agent SDK（论文 arXiv:2511.03690），对 agent 组件做了一次彻底重构（内部称 V1），把「平台」和「可嵌入 SDK」拆开。
5. 2026 年，仓库迁移到独立的 OpenHands GitHub 组织，主项目进入 1.x 版本周期（1.5.0 发布于 2026 年 3 月），SDK 独立发版（2026 年 7 月已迭代到 v1.31.x）。

数据速览（截至 2026 年 8 月）

• GitHub：75K+ stars、数千 forks；2025 年底统计累计下载超 400 万次
• 论文：OpenHands 平台论文（arXiv:2407.16741）、CodeAct 论文（arXiv:2402.01030，ICML 2024）、Agent SDK 论文（arXiv:2511.03690）
• 融资：种子轮 $5M（2024 年 9 月，Menlo Ventures 领投）；A 轮 $18.8M（2025 年 11 月，Madrona 领投）

它的定位用一句话概括：Devin 能做什么它基本都能做，而且你能看到每一行实现、换掉任何一个部件。这决定了它在两类人群里最受欢迎：想把 agent 部署在自己基础设施里的团队，以及想研究「开发 agent 到底怎么造」的工程师和研究者。

二、架构解剖：事件流、CodeAct 与沙箱运行时

OpenHands 平台论文（arXiv:2407.16741）把架构拆成三个基本构件：Agent 抽象、事件流（Event Stream）、Agent Runtime。理解这三块，就理解了整个系统。

                 ┌────────────────────────────────────┐
                 │            前端 / CLI / API         │
                 └──────────────┬─────────────────────┘
                                │ 用户消息
                 ┌──────────────▼─────────────────────┐
                 │         AgentController            │
                 │  状态机: RUNNING/AWAITING/ERROR... │
                 └──────────────┬─────────────────────┘
                                │ step()
┌───────────────────────────────┼───────────────────────────────┐
│                       Event Stream（append-only）              │
│  Action ──► 执行 ──► Observation ──► 追加进流 ──► 下一步决策    │
│  (CmdRun / IPythonRunCell / FileEdit / Browse / Message ...)  │
└───────────────┬───────────────────────────────┬───────────────┘
                │ 动作被分发到                   │
        ┌───────▼───────────────────────────────▼────────┐
        │            Agent Runtime（Docker 沙箱）          │
        │  bash session │ Jupyter kernel │ 浏览器 │ 文件系统│
        └─────────────────────────────────────────────────┘

事件流：一切皆是事件

OpenHands 没有「对话历史」，只有事件流。用户消息、agent 的思考、每一个动作（Action）、每一次执行结果（Observation）都是追加到同一条流里的事件。Agent 每走一步，拿到的输入就是事件流的一个视图，输出是一个新动作。

这个设计的回报在三个地方：

• 可回放、可调试。一次任务跑完，整条轨迹就是事件流本身，可以原样导出、逐条重放，这也是它做评测和 observability 的地基。
• 状态外置。Agent 本体几乎无状态，暂停、恢复、人机接力（人随时往流里插一条消息）都是自然操作。
• 多 agent 天然可组合。委派（delegation）就是父 agent 发出一个 AgentDelegateAction，子 agent 在同一套事件流语义下工作，结果以 Observation 返回。

V1 SDK 更进一步，把事件流做成了正式的 event sourcing 实现。SDK 论文里给出的生产数据结论是：相比 V0，V1 显著降低了「归因于系统本身」的失败率，而 event sourcing 的开销可以忽略——这是对「工程化抽象不会拖慢 agent」的一次实证。

CodeAct：统一的动作空间

默认的 CodeActAgent 不定义一堆 JSON function calling 工具，而是只给模型几个「像人一样工作」的能力：跑 bash 命令、在 Jupyter 里执行 Python 单元格、读写编辑文件、操作浏览器、给人发消息。模型通过写代码来调用这些能力。这是全平台最核心、也最有思想含量的设计，第三节单独展开。

运行时沙箱

所有动作都在一个按需拉起的 Docker 容器里执行：一个持久 bash session、一个 Jupyter IPython kernel、一个无头浏览器，挂载任务工作区。这带来两个工程上的必然结果：

• 安全边界清晰。Agent 有完整的 shell 权限，但爆炸半径被限制在容器内。沙箱不是可选项——让 LLM 生成的代码直接跑在宿主机上，等于把 rm -rf 的扳机交给一个会幻觉的系统，详见 Agent 安全。
• 环境即镜像。评测（如 SWE-bench）和企业部署复用同一套机制：把任务环境打包成 Docker 镜像，agent 进去干活。环境可复现性是 OpenHands 评测成绩可信度的重要来源。

微 agent（microagents）

注意「microagent」在 OpenHands 里有两个历史含义，别混淆：

• 论文语境：平台论文中的 micro-agent 指一类轻量、单一职责的 agent 实现——固定 prompt + 固定逻辑，完成一个窄任务（比如提交 PR、总结讨论），用来证明「不是所有任务都需要完整的 CodeAct 循环」。
• 当前产品语境：.openhands/microagents/ 目录下的 Markdown 文件，本质上是按需注入的领域知识——带触发关键词的知识文件（提到某个词才注入）和 repo 级常识文件（类似 AGENTS.md，见 writing-agents-md）。它们属于 context engineering 的范畴，不是独立运行的 agent。

一个典型的知识型 microagent 长这样，frontmatter 控制触发方式，正文就是注入的上下文：

---
name: project-conventions
triggers:          # 命中这些关键词时才注入，不常驻上下文
  - 测试
  - test
---

# 本仓库的测试约定
- 单测统一放 tests/unit/，用 pytest，禁止用 unittest
- 改完代码必须先跑 `make test-fast`，绿了才能提交
- fixtures 集中在 tests/conftest.py，不要在新文件里重复定义

这个机制值得借鉴的是它的惰性：知识只在相关时进入 context window，避免把整个团队 wiki 塞进系统提示。你自己做 agent 时，「按关键词/任务类型动态装配上下文」通常比「一个大而全的 system prompt」更省 token 也更准。

三、CodeAct 思想精讲：为什么「动作即代码」

CodeAct 出自 ICML 2024 论文《Executable Code Actions Elicit Better LLM Agents》（arXiv:2402.01030，王星尧等，UIUC + Apple），是 OpenHands 动作空间的理论来源，也是这两年最有实际影响力的 agent 设计思想之一。

问题：JSON 工具调用的两个天花板

主流 agent 框架让模型输出预定义格式的 JSON 或文本来调用工具（详见 工具与 MCP）。论文指出这种方式有两个结构性限制：

1. 动作空间受限：模型只能调用你预先定义好的工具，工具列表之外的组合能力为零。
2. 缺乏控制流和数据流：一次 JSON 调用就是一个原子的、无状态的工具调用。想「对 10 个文件各跑一次检查并汇总失败项」，你得来回交互 10 轮，中间结果全靠自然语言在上下文里搬运。

方案：让模型直接写可执行 Python

CodeAct 把 agent 对环境的全部动作统一为一段可执行 Python 代码。每轮交互：模型输出代码 → 解释器执行 → 执行结果（含报错）作为 observation 回来 → 模型据此修正或发出新动作。好处是层层叠加的：

• 控制流与数据流：for 循环批量处理、if 分支、把中间结果存进变量复用——一段代码顶 JSON 方案的十几轮交互。论文的例子：对一批输入依次调用多个工具并把前一个工具的输出喂给后一个，CodeAct 一个动作搞定。
• 白嫖整个软件生态：模型可以直接 import pandas、调 sklearn，不用你为每个任务手工封装工具。
• 自带调试反馈：Python 报错信息是给人类程序员设计的自然语言反馈，模型拿来做 self-debug 顺理成章。
• 对齐预训练分布：现代 LLM 在预训练里见过的代码远多于任何私有 JSON 调用格式，写代码是模型的「母语」，几乎零适配成本。

证据：不只是听起来合理

论文在 17 个开源与闭源模型上做了对照实验：

实验	对比	结果
API-Bank 原子调用	CodeAct vs JSON vs 文本格式	多数模型上 CodeAct 持平或更优，开源模型优势尤其明显（JSON 是开源模型的弱项）
M3ToolEval（82 个需多工具多轮组合的复杂任务）	同上	CodeAct 成功率最高提升 20 个百分点，所需交互轮数最多减少约 30%
同基准上的最强模型（GPT-4-1106）	CodeAct 74.4% vs 文本 53.7% vs JSON 52.4%	差距超过 20 个百分点

论文还顺手做了一件影响更深远的事：构建 7K 条 CodeAct 多轮交互轨迹的指令微调数据集 CodeActInstruct，训出 CodeActAgent（基于 Llama-2 7B / Mistral 7B），证明了「用代码当动作」这条路可以训进模型而不只是 prompt 出来。这直接启发了后来一批 agentic 微调工作。

一个值得记住的判断

CodeAct 的洞察在 2026 年已经成了行业共识：Claude Code 的 Bash 工具、各类「模型直接写 shell」的编程 agent，本质都是 CodeAct 思想。但要注意边界——它成立的前提是模型足够强且有沙箱。弱模型生成自由代码的错误率远高于受约束的 JSON；没有隔离环境时，自由代码执行是不可接受的风险。JSON function calling 在受控企业集成（权限审计、schema 校验）场景里仍然是对的答案。

四、评测表现：SWE-bench 上的 OpenHands

OpenHands 是 SWE-bench 生态里的常客，读它的成绩要注意三件事：用的是哪个基准版本、配的什么模型、是不是官方复现。

• SWE-bench Verified（500 题人工筛选版）是主战场。OpenHands 官方在 2025 年初报告的 CodeAct 方案成绩约为 53%——这个数字在社区复现中引发过争议（GitHub issue #10767 专门讨论默认配置复现不出该成绩的问题），是「benchmark 自报成绩要打折扣」的典型案例，方法论见 评测。
• 在 swebench.com 官方榜单上，OpenHands 后续条目持续提升：2025 年 8 月提交的条目达到 69.6%～71.8%。注意榜单成绩是「scaffold + 模型」的联合成绩，头部位置随新模型发布不断易主，看趋势比记数字有意义。
• 平台论文的横向对比更有信息量：论文在同一 runtime 上评测了 15 个基准（SWE-bench、WebArena、GPQA、HumanEvalFix 等），CodeActAgent 在绝大多数编码与浏览任务上是参评开源方案里最强的，这证明了平台的通用性而非单点刷榜。

读榜单的纪律

SWE-bench Verified 在 2025-2026 年经历了从 ~50% 到 80%+ 的冲刺，榜单前排已被前沿模型 + 重度调优的 scaffold 占据，分差进入统计噪声区间。用 OpenHands 选型时，别拿它一年前的榜单名次说事——scaffold 本身迭代极快，同样的 scaffold 换个模型可能差出 20 个点。正确姿势是用你自己的仓库和任务做小规模实测。

五、All Hands AI：公司与商业化的关系

OpenHands 采用的是教科书式的 open core 路径，但执行得比较克制：

• 核心全开源，MIT 协议。平台、SDK、runtime 都在开源仓库里，自托管不需要付任何许可费，只有你自己掏 LLM API 的钱。
• 商业化靠托管与企业版。OpenHands Cloud 提供免运维的托管版：个人版免费起步（注册送 $20 额度，支持自带 API key 或按成本价用平台供给的模型，不加价），并带 Slack、Jira、GitHub/GitLab/Bitbucket 集成；Team 和 Enterprise 档卖的是组织管控、SSO、私有部署和规模化管理——具体价格走销售洽谈。
• 公司给项目输血，项目给公司导流。A 轮 $18.8M（2025 年 11 月，Madrona 领投，Menlo Ventures 等跟投）主要用于 Cloud 产品和 SDK 的工程化。种子轮（2024 年 9 月，$5M，Menlo 领投）的投资人名单很有开源圈特色：Hugging Face 联创 Thom Wolf、PyTorch 作者 Soumith Chintala、Cloudera 联创 Jeff Hammerbacher 都在列。

对使用者来说，这个结构目前比较健康：MIT 核心 + 明确的公司输血渠道，比「先开源聚拢社区再改协议」的玩法可信。但有个细节值得留意——仓库中的 enterprise 目录是单独许可的，二次开发商用前看一眼 LICENSE 分布。

六、生态与二次开发价值

如果你想「站在巨人肩膀上造自己的 agent」，OpenHands 是 2026 年最合适的底座之一，原因有四：

1. SDK 把平台拆成了库

2025 年 11 月发布的 Software Agent SDK（OpenHands/software-agent-sdk）是关键转折。V1 之前，想复用 OpenHands 的能力基本得 fork 整个平台；SDK 把 agent、tool、runtime、事件流抽成独立 Python 包，论文里强调的最小 agent 实现「默认情况下只需几行代码」，同时保留了自定义工具、memory 管理、安全分析这些生产特性。和 OpenAI Agents SDK、Claude Agent SDK、Google ADK 相比，它的差异化在于原生集成沙箱执行、模型无关的多 LLM 路由（经 LiteLLM 支持 100+ 模型）、本地到远程的无缝执行迁移。用它写一个最小 agent 的样子：

# 基于 OpenHands Agent SDK 的最小示例（API 以软件包文档为准，随版本迭代较快）
from openhands.sdk import Agent, LLM, Conversation
from openhands.tools import BashTool, FileEditorTool

llm = LLM(model="anthropic/claude-sonnet-4-5")  # 经 LiteLLM 路由，换模型只改这一行
agent = Agent(llm=llm, tools=[BashTool(), FileEditorTool()])

# Conversation 封装了事件流：发消息、跑循环、拿事件历史
convo = Conversation(agent=agent, workspace="./my-project")
convo.send_message("修复 src/ 下所有失败的单元测试")
convo.run()

2. Runtime 可以单独用

即使你不要它的 agent，Docker 沙箱 runtime 本身就是个独立价值：很多团队拿它当「给自家 agent 用的安全执行环境」，省掉自建沙箱的大量脏活。

部署形态一览：OpenHands 在 2026 年提供了比多数同类项目更全的接入面，选底座前先想清楚走哪条：

形态	适合谁	代价
本地 GUI（自托管 Docker）	个人试用、小团队内网部署	要自己管镜像、模型 key 和升级
CLI / headless 模式	接入 CI、批量任务（如夜间自动修 issue）	无界面，交互能力弱
Python SDK（software-agent-sdk）	把 agent 能力嵌进自己的产品	版本迭代快，API 有 breaking change
OpenHands Cloud	不想运维、要 Slack/Jira 集成的团队	数据出域，企业合规需走 Enterprise 档

3. 评测基建开箱即用

SWE-bench、WebArena 等基准的评测 harness 内置在仓库里，环境镜像化、轨迹可导出。做 agent 研究或 evals 实践 时，这是现成的脚手架。

4. 社区活跃度是真的

每周级的发版节奏、数百名贡献者、论文持续产出——平台论文 v3 记录的数据是超过 188 名贡献者、2100+ 次提交。对二次开发者，这意味着「你遇到的问题大概率有人踩过」。反过来也要有心理准备：迭代快意味着 API 漂移快，升级版本时 breaking change 是常态，锁版本是基本操作。

什么时候选 OpenHands 做底座

适合：要自托管、要换任意模型、要改 agent 内部行为、要把 agent 嵌入自己的产品。不适合：只想安安静静在终端里写代码（直接用 Claude Code 或 Cursor 更省心），或者只需要一个单文件 issue 修复脚本（SWE-agent/mini-SWE-agent 更轻）。

七、与 SWE-agent 的设计对比

OpenHands 和 SWE-agent 是开源 SWE agent 的两极，论文引用数也是这个领域的前两名。它们的差异不是「谁更强」，而是两种设计哲学的分歧：

维度	OpenHands	SWE-agent
出身与目标	复刻 Devin 的产品级平台，目标是「完整可用的 AI 开发者」	普林斯顿学术研究项目，目标是回答「什么接口让 LM 能解真实 issue」
核心抽象	事件流 + CodeAct：动作即代码，直接跑 bash/Python	ACI（Agent-Computer Interface）：为 LM 设计专用命令（open/edit/lint 等），像给人设计 UI 一样给模型设计接口
轨迹形态	事件流，支持委派、多 agent、人机随时介入	线性「思考-动作-观察」循环，刻意保持简单；mini-SWE-agent 更是砍到约 100 行、只用 bash
交互界面	Web GUI、CLI、VS Code、Cloud、SDK	命令行为主，研究导向
工程重量	重：Docker runtime、前端、服务端、SDK，部署有门槛	轻：单进程跑完一条轨迹，易复现、易改造
典型用户	想部署/嵌入/改造产品的工程团队	做 agent 研究、跑大规模评测实验的人

最有意思的分歧在动作空间。SWE-agent 的 ACI 论文论证的是：给模型一堆精心设计的专用命令，比给它原始 shell 更可靠——因为模型的 shell 知识 noisy，专用命令能收窄犯错面。CodeAct 论证的恰好相反：给模型自由代码执行，让控制流和生态库的能力完全释放，可靠性靠沙箱和报错反馈兜住。

谁对？2026 年回头看，答案是「都对了一部分，且市场在收敛」：

• 在强模型 + 有沙箱的前提下，CodeAct 路线明显占优，工业界产品（Claude Code、Codex 等）基本都倒向了「模型直接用 bash」；
• 但 ACI 的洞察——接口设计决定 agent 表现上限——被完整继承了下来：OpenHands 的文件编辑工具同样经历了多轮 ACI 式打磨（从自由 sed 到带行号校验的编辑器命令），纯裸 bash 解 SWE-bench 的 mini-SWE-agent 也证明了「简单接口 + 强模型」的下限可以很高。

真正的结论是：动作空间设计没有银弹，它是「模型能力 × 任务类型 × 安全约束」的函数。OpenHands 选择了自由度优先、用工程兜底；SWE-agent 选择了约束优先、用简单性兜底。想动手体验两种哲学，最省钱的方式是各跑一遍 SWE-bench 的几个实例、逐条读轨迹——这比读十篇对比文章都长见识，参见 自己动手造 Agent。

参考资料

• OpenHands: An Open Platform for AI Software Developers as Generalist Agents —— 平台论文，事件流 / Runtime / micro-agent 架构的权威出处
• Executable Code Actions Elicit Better LLM Agents (CodeAct) —— CodeAct 论文，ICML 2024，含 17 个模型的对照实验数据
• The OpenHands Software Agent SDK —— V1 SDK 重构的论文，含生产部署的可靠性数据
• OpenHands GitHub 仓库 —— 源码、release 与 issue 讨论（如 #10767 的 SWE-bench 复现争议）
• SWE-bench 官方榜单 —— OpenHands 各版本条目成绩的核对来源
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering —— ACI 设计哲学的原始论文，对比阅读用
• OpenHands, Aider, Continue — the Open-Source Coding-Agent Stack in 2026 —— 2026 年开源编码 agent 格局与 OpenHands 采纳度、融资数据的二手综述