OpenHands 新手实战：开源版 Devin 如何读取项目、修改代码、运行测试？
写在前面：AI 编程 Agent 的分水岭，是能不能进入真实仓库
过去我们说 AI 写代码，很多时候指的是：
我问一个问题； AI 回一段代码； 我复制到项目里； 报错后再问。这种方式能提高效率，但它离真实工程开发还有距离。
真实开发不是只写一个函数，而是：
- 理解项目结构；
- 找到相关文件；
- 读配置；
- 修改代码；
- 运行测试；
- 根据报错再修；
- 控制改动范围；
- 输出可审查的结果。
OpenHands 这类项目瞄准的就是这个问题。
它不是一个简单聊天工具，而是一个 AI-driven development 平台。你可以把它理解成开源 AI 软件工程师的底座：有 CLI，有本地 GUI，有 SDK，也有云端和企业版方向。
一、OpenHands 是什么？
OpenHands 的项目标题很直接：
OpenHands: AI-Driven Development从官方 README 看，它提供了几种使用形态：
| 形态 | 说明 | 适合谁 |
|---|---|---|
| OpenHands Software Agent SDK | 可组合的 Python Agent 技术库 | 想二次开发 Agent 的开发者 |
| OpenHands CLI | 类似 Claude Code/Codex 的终端体验 | 喜欢命令行的开发者 |
| OpenHands Local GUI | 本地运行的可视化界面 | 想看 Agent 操作过程的新手 |
| OpenHands Cloud | 云端托管形态 | 想快速体验的人 |
| OpenHands Enterprise | 企业自托管和权限能力 | 大团队和企业场景 |
所以 OpenHands 不是单点工具，而是一套 AI 编程 Agent 体系。
二、它和 Codex/Claude Code 有什么区别？
很多人会问：
我已经有 Codex 或 Claude Code，还要看 OpenHands 吗？要看你的目标。
Codex CLI 和 Claude Code 更像直接面向开发者的终端 AI 编程工具。OpenHands 更像一个开放的 AI 软件开发平台，可以通过 CLI、GUI、SDK 和云端形态使用。
| 维度 | Codex/Claude Code | OpenHands |
|---|---|---|
| 入口 | 终端为主 | CLI、Local GUI、SDK、Cloud |
| 定位 | AI 编程助手 | AI-driven development 平台 |
| 可视化 | 取决于工具 | Local GUI 更直观 |
| 二次开发 | 有限制 | SDK 更适合研究和扩展 |
| 团队能力 | 取决于平台 | Cloud/Enterprise 提供多人和权限方向 |
| 新手体验 | 终端门槛略高 | GUI 更容易观察 Agent 行为 |
如果你关注“自己用 AI 改代码”，Codex/Claude Code 很直接。
如果你关注“如何构建或研究一个 AI 软件工程师系统”，OpenHands 更值得深入。
三、部署前准备
建议准备：
Git Docker Docker Compose 一个可用的大模型 API Key 一个用于测试的小型代码仓库为什么强调“小型代码仓库”？
因为第一次测试 AI Agent，最怕直接扔一个几十万行的生产项目。这样不仅上下文复杂，还容易让 AI 修改范围失控。
建议准备一个简单项目，比如：
- 一个 Todo API；
- 一个 Spring Boot 小模块；
- 一个 Vue 组件 Demo；
- 一个有测试的 Python 小项目；
- 一个故意制造小 bug 的示例仓库。
先用小项目验证 Agent 的工作方式，再考虑真实项目。
四、启动 OpenHands
OpenHands 支持多种方式。对于新手，建议优先体验 Local GUI，因为你能看到 Agent 的操作过程。
实际启动命令要以官方文档为准。常见 Docker 思路是：
gitclone https://github.com/OpenHands/OpenHands.gitcdOpenHandsdockercompose up-d然后查看服务：
dockercomposeps如果你使用官方推荐的一键命令或文档中的最新命令，以当前官方文档为准。
五、进入 Local GUI
启动完成后，在浏览器中打开对应地址。Local GUI 通常会提供一个类似开发工作台的界面：你可以输入任务，Agent 会读取项目、执行命令、修改文件或给出结果。
第一次进入不要急着让它改代码，建议先让它只读分析：
请只读分析当前项目，不要修改任何文件。请说明： 1. 项目技术栈； 2. 主要目录结构； 3. 启动方式； 4. 测试方式； 5. 可能适合新手修改的一个小任务。这一步的目标不是看它能不能写代码，而是看它是否理解项目。
六、实战任务：让 Agent 修一个小 bug
准备一个小任务，例如：
项目里有一个登录接口测试失败，请定位原因并修复。更好的提示词是：
当前项目有一个测试失败。请你按下面步骤执行： 1. 先查看项目结构； 2. 再运行测试； 3. 根据失败日志定位原因； 4. 只修改和失败测试直接相关的文件； 5. 修改前先说明计划； 6. 修改后重新运行测试； 7. 最后总结改动文件和原因。这个提示词比“帮我修 bug”稳得多。
它把 Agent 的工作流程限制在：
分析 → 运行 → 定位 → 计划 → 修改 → 验证 → 总结这也是 AI 编程 Agent 最应该被约束的地方。
七、如何判断一次 Agent 任务是否靠谱？
不要只看“它最后说完成了”。
要看这些指标：
| 指标 | 判断方式 |
|---|---|
| 是否理解需求 | 有没有先复述和拆解任务 |
| 是否控制范围 | 有没有只改相关文件 |
| 是否运行验证 | 有没有跑测试或构建 |
| 是否解释原因 | 有没有说明为什么这样改 |
| 是否可审查 | 有没有清楚列出 diff |
| 是否可回滚 | 改动是否集中、可还原 |
AI Agent 最危险的不是“不会写代码”，而是“看起来很会写，但改动不可控”。
所以每次任务都建议要求：
修改前给计划； 修改后跑测试； 最后列出文件清单； 不要自动提交； 不要自动部署。八、安全边界：不要让 Agent 直接碰生产环境
OpenHands 这类工具很强，但强能力也意味着强风险。
它可能：
- 读取文件；
- 执行命令；
- 修改代码；
- 安装依赖；
- 访问网络；
- 调用外部模型；
- 生成和运行脚本。
这就要求我们必须把环境隔离好。
建议：
- 使用测试仓库；
- 不挂载敏感目录；
- 不放生产
.env； - 不给生产数据库权限；
- 不让它自动部署；
- 所有改动人工审查；
- 重要项目先开分支；
- 复杂任务分步执行。
如果是在团队里试点，还应该补充：
- API Key 管理；
- 日志审计；
- 权限分级；
- 代码审查流程；
- 沙箱资源限制；
- 数据脱敏策略。
九、适合 OpenHands 的任务
适合：
- 新项目结构分析；
- 小 bug 修复；
- 测试失败定位；
- 文档补充；
- 简单重构前评估；
- 生成测试用例；
- 重复性代码改造；
- 依赖升级影响分析。
不适合一上来就做：
- 重构整个系统；
- 迁移完整技术栈；
- 自动改数据库结构；
- 自动部署生产；
- 自动处理安全漏洞并上线；
- 让 Agent 自己决定业务规则。
新手要记住：
AI Agent 不是权限越大越好； 是边界越清楚越好。十、和真实开发流程怎么结合？
推荐一个稳妥流程：
第一步：只读分析
请分析这个模块的职责，不要修改文件。第二步：定位问题
请运行测试并分析失败原因，不要修改文件。第三步：给修复计划
请给出最小修改方案，列出要改的文件。第四步：执行单步修改
只执行方案中的第一步，修改后停止。第五步：验证
运行相关测试，并总结结果。这个流程看起来比“全自动”慢，但更接近真实工程管理。因为真实项目里最贵的不是写代码，而是错误修改带来的返工和风险。
十一、常见问题
Q1：OpenHands 是 Devin 的完全替代吗？
不是。更准确地说，它是开源 AI-driven development 平台，体验上会让人联想到 Devin/Jules 这类软件工程 Agent，但产品形态、云端能力、企业能力、模型配置和稳定性边界都不同。
Q2：新手应该用 CLI 还是 Local GUI？
建议先用 Local GUI。因为你能看到 Agent 做了什么，更容易理解工作流。
Q3：可以直接接生产项目吗？
不建议。先用测试仓库和分支，确认权限、日志、改动范围、测试流程都可控。
Q4：它会不会乱改文件？
如果提示词没有约束、工作区权限过大、任务范围过宽，就有风险。所以要明确“先计划、再执行、每次只改小范围”。
Q5：企业能用吗？
可以研究，但要补上权限、审计、隔离、密钥管理、数据合规等要求。不要把个人试用方式直接搬到企业生产环境。
总结
OpenHands 值得关注，不是因为它能“自动写代码”这一个点，而是因为它把 AI 编程 Agent 的几个关键形态放到了一起：
- SDK；
- CLI；
- Local GUI；
- Cloud；
- Enterprise；
- Agent 执行环境；
- 项目级任务协作。
它适合用来研究和实践：
AI 如何进入真实代码仓库； AI 如何执行任务； AI 如何运行测试； AI 如何在可视化界面中展示过程； AI 如何被约束在安全边界内。新手建议路线：
本地 GUI 启动 ↓ 小项目只读分析 ↓ 运行一次测试 ↓ 修一个小 bug ↓ 查看 diff ↓ 人工审查 ↓ 再考虑复杂任务不要急着追求完全自动化。AI 编程 Agent 的正确打开方式，是先让它成为一个可观察、可审查、可验证的工程助手。