OpenHands 源码拆解:AI 怎么像工程师一样动手改仓库
过去一年,AI 编程最有用的方向不是陪聊,而是直接干活。
给它一个 issue。读仓库、找问题、改文件、跑测试、提交 PR。这一套流程跑下来,才接近真正的"软件工程 Agent"。
Devin 闭源。AutoGPT 更像实验项目。OpenHands 是少数同时做到高关注度、完整工程化和真正提 PR 的开源方案。
GitHub 主仓库目前有 84,555 stars。项目原名 OpenDevin,后来改名 OpenHands。仓库不是纯 Python 项目,而是 TypeScript + Python 双语言:Web 前端和交互层主要使用 TypeScript,Agent、Runtime、Controller 等后端核心在 Python。
它解决什么问题
普通代码补全只回答"这段代码怎么写"。Agent 要处理的是完整任务:
- 读取 issue 和仓库上下文
- 制定修改计划
- 搜索代码
- 编辑文件
- 执行 shell 命令
- 跑测试和 lint
- 检查 diff
- 生成 commit 或 PR
难点不在一次代码生成。
难点是每一步都可能出错。测试没通过怎么办?网络请求失败怎么办?改错文件怎么办?Agent 能不能观察结果,再决定下一步?
OpenHands 做的事情,就是把终端、文件系统和浏览器变成 Agent 可调用的工具。它不只生成代码,也负责执行和验证。
这也是它和 Cursor Agent、Copilot 的区别。后两者主要围绕编辑器工作。OpenHands 的目标更直接:让模型接管一个可运行、可隔离、可观察的开发环境。
和 Devin 比,它开源。
和 AutoGPT 比,它更工程化:有 Runtime、Controller、事件总线、SDK,也有 Docker 部署路径。
怎么用
最简单的使用方式,是本地启动 OpenHands:
docker run -d \
-p 3000:3000 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.openhands:/root/.openhands \
--name openhands \
ghcr.io/openhands/openhands:latest
然后打开 http://localhost:3000。
OpenHands 的宿主机负责 Web UI、API 和 Agent 控制。真正执行命令的代码默认放在另一个 Docker 沙箱里。
还有一种方式适合写自动化任务:使用 Python SDK。下面的代码是 SDK 调用形式的核心示例:
from openhands import OpenHandsAgent
agent = OpenHandsAgent(
llm_model="claude-3-5-sonnet",
workspace="./demo-project",
runtime="docker"
)
task = "修复 src/main.py 里的除零 bug,跑通 tests/ 下全部用例"
result = agent.run(task, max_steps=20)
print("状态:", result.status)
print("改动文件:", result.modified_files)
print("测试输出:", result.test_output)
这段代码表达了三件事:
workspace指向要操作的仓库。runtime="docker"指定执行环境。max_steps=20给 Agent 设置动作上限,避免无限循环。
SDK 的价值不只在"聊代码"。批处理、CI 辅助、内部任务队列,都可以把 Agent 接进去。
模型配置默认可走 Anthropic 或 OpenAI 云端 API。不接云 API 时,可以换 Ollama 或 vLLM,在本地跑模型。
需要注意版本差异。模型名和 SDK API 会随项目更新。部署前应以当前版本 README、示例和安装后的接口定义为准,不要只复制旧文章里的模型名称。
它怎么工作(架构)
OpenHands 的核心可以拆成三层。
Runtime:Agent 的手和脚
Runtime 是实际执行环境。
代码主要位于 openhands/runtime/。默认基于 Docker 隔离,给 Agent 提供三类基本能力:
- 执行 shell 命令
- 读写和编辑文件
- 操控浏览器
这三类原语已经能覆盖大部分开发任务。安装依赖、修改代码、启动服务、查看页面报错,都可以组合完成。
Runtime 也有多语言扩展方向,支持 Python、Node.js、Go 等项目。实际可用能力取决于 Runtime 类型和插件配置。
隔离是这一层最重要的设计。模型看到的是受限工作区。宿主机不应直接暴露给 Agent。
Agent:决定下一步做什么
Agent 控制器负责管理任务状态、规划、记忆和工具调用。
关键代码在 openhands/controller/agent/。
它不是收到一句提示词就直接生成答案,而是维护一条动作链:
- 观察当前仓库和任务状态。
- 选择一个工具。
- 传入参数并执行。
- 读取命令输出或报错。
- 更新计划,进入下一步。
典型 Agent 循环类似 ReAct:Reasoning 和 Acting 交替进行。每次动作前先判断,动作后读取反馈。
这也是 Agent 和脚本生成器的主要区别。脚本生成器只产出文本。Agent 会消费工具返回的真实结果。
OpenHands 还支持自定义 Action Space。开发者可以注册新工具,规定参数、返回值和执行方式,再把它交给 Agent。
比如加一个"查询内部 API 文档"的工具,或者加一个"查询生产错误日志"的动作。工具边界清楚以后,Agent 才有资格碰真实系统。
LLM:只负责推理
第三层是 LLM。
它理解 issue,分析 diff,决定调用哪个工具。但命令执行、文件写入和浏览器控制不直接发生在模型服务器里,而是在 Runtime 中完成。
这种拆分很重要。
如果把 shell、编辑器和浏览器全部塞进 Prompt,权限边界会变模糊。OpenHands 把它们做成受控工具。模型只能选择已注册的动作,Runtime 再执行动作。
事件总线:让过程可观察
Agent 的每一步动作和结果都作为事件流动。前端通过 WebSocket 接收更新。
你能看到:
- Agent 正在读哪个文件
- 执行了什么命令
- 命令是否失败
- 修改了哪些文件
- 测试输出是什么
- 当前处于规划、编码还是验证状态
这种可观察性不只为了演示。它能帮助开发者判断 Agent 是真的在修问题,还是已经陷入循环。
它哪里好 / 哪里不好
OpenHands 的优势很明确。
第一,完全开源。
项目采用 MIT 协议,可商用、可改源码、可自部署。不想被 Cursor 或 Copilot 绑死的小团队,可以把它当成内部 Agent 基础设施。
第二,沙箱隔离比较完整。
命令、文件编辑、浏览器操作都被放进 Runtime。模型不能随意碰到宿主机。
第三,可以扩展 Action Space。
内部构建系统、代码搜索服务、数据库查询工具,都能按受控接口接进去。
第四,有评测支撑。
OpenHands 在 SWE-bench Verified 上长期保持开源项目第一梯队。2024 年的大部分时间,它都是开源 Agent 中的领先方案。具体分数会随模型、提交版本和评测配置变化,不能把不同日期的结果直接混在一起比较。
问题也很现实。
本地部署吃资源。完整服务、模型和沙箱一起跑,对 CPU、内存、磁盘都不算轻。默认环境按至少 8GB 内存准备更稳妥。
云端 API 仍是主流路径。虽然支持 Ollama 和 vLLM,但小模型在长仓库理解、工具选择和失败恢复上容易退化。
国产模型适配还在追赶。OpenHands 官方配置通常优先考虑 Anthropic、OpenAI 等服务。中国网络环境下,使用 DeepSeek、通义千问等服务通常更稳定。
复杂多文件重构也容易卡循环。比如连续改错文件、测试依赖外部服务、命令不断超时。max_steps 只能限制损失,不能自动恢复错误计划。
我试了下
我用一个故意写错的 Python 项目做了小测试。目标很直接:修复除零问题,并通过 tests/ 下全部用例。
流程如下:
- 用 Docker 启动 OpenHands。
- 接入 Claude 3.5 Sonnet。
- 把仓库挂进工作区。
- 下发任务:定位除零 bug、修改代码并运行测试。
Agent 先搜索了 src/main.py,定位到除数为零的分支。
它没有直接提交。修改后执行 pytest,发现测试通过,又检查了 diff。
我设置的步骤上限是 20,实际没有跑满。
中途它尝试安装 requests。沙箱没有开放外网,安装失败。Agent 读取报错后,没有继续重试,而是改用 Python 标准库 urllib。最终测试通过,并生成本地 commit。
我又换 DeepSeek-V3 测了同一个任务。
结论有三点:
- 能完成。不是只能写代码示例。
- 速度明显更慢。同样的任务,耗时大约增加 40%。
- 简单修复没有失败。复杂重构时,模型稳定性仍不如 Claude 或 GPT-4o。
这不是严谨 benchmark,只是同一个容器、同一任务和同一步数上限下的体验对比。它能说明接入方式可行,不能当成模型排名。
中国用户最常踩的坑
Docker 镜像拉取慢,是第一个坑。
ghcr.io 镜像体积大,网络波动时很容易卡住。可以提前拉取固定版本,给 Docker Hub 配置镜像加速,并给 OpenHands 镜像设置明确 tag。
不要长期使用模糊的 latest。升级可能改变 Runtime 行为、API 参数和工具结果。
第二个坑是模型 API。
Anthropic、OpenAI 服务在部分国内网络环境下延迟高、连接不稳定。实测时换成 DeepSeek 或通义千问更稳。
模型名不要凭印象填写。以当前版本的模型配置页和代码为准。有些旧模型已经下线,有些服务需要单独兼容参数。
第三个坑是权限。
为了使用 Docker Runtime,常见启动方式会把宿主机的 Docker socket 挂进容器。方便,但权限很大。
生产环境不要直接照搬开发配置。应该限制容器权限,改用远程 Runtime,并给内部服务配置短期凭证。
第四个坑是工作区持久化。
默认沙箱不是永久工作区。容器重建或服务重启后,临时文件可能丢失。
需要保留代码时,挂载持久化 volume。还需要 commit、PR 和任务记录时,接外部 Git 服务或对象存储。
谁该用
OpenHands 适合三类人。
小团队。 想搭内部 AI 编程助手,又不想被 Cursor、Copilot 绑死。前提是有人维护 Docker、模型和内部工具。
Agent 工程师。 需要看 Runtime、Controller、工具协议和事件流源码。OpenHands 的代码比很多演示项目更接近生产系统。
评测研究者。 想跑 SWE-bench 类任务,或者测试不同模型的仓库级修复能力。它的 Runtime、Action Space 和事件记录都能用于实验。
不太适合三类人。
完全不想写配置的用户。 只想补全几行代码,Cursor 或 Copilot 更省事。
要求完全离线的人。 本地推理依赖 GPU、模型适配和较高的内存。国产硬件上的工具调用稳定性仍需单独调校。
处理敏感代码、又不愿配置隔离的人。 沙箱、volume、网络策略和凭证管理都需要自己确认。默认安全,不代表可以忽略部署环境。
如果只看"AI 能不能改仓库",OpenHands 已经证明可行。
真正决定效果的,仍是三件事:模型能否规划好,Runtime 是否足够可控,工具结果能否帮助 Agent 纠错。
它目前还不适合无监督运行关键业务。但对于想搭一套可修改、可观察、能接内部工具的工程 Agent,OpenHands 仍是开源项目里很值得拆开看的一个。