如何使用 AI OpenHands：设置、提示和实际工作流程实用指南
如果您曾希望有一位能干的开发人员可以 24/7 全天候与您结对编程，那么 AI OpenHands 就非常接近了。它是一个开源的 "AI 工程师"，可以读取您的代码仓库，编写代码，运行终端，浏览文档并进行迭代——就像一个学习迅速且不知疲倦地工作的初级开发人员。但是，只有正确设置它并学习如何引导它，才能发挥其强大功能。
本指南将逐步引导您如何使用 AI OpenHands——从安装到高级工作流程——以便您可以更有信心地更快地交付产品。
值得注意的是：OpenHands 由 All Hands 团队和社区积极开发。官方文档是您获取最新说明和提示的指路明灯。您还可以关注实践者提供的实践安装指南，他们记录了本地和 VM 设置。对于使用本地模型运行，文档也包括具体的指导。
什么是 AI OpenHands——以及为什么要使用它？
将 AI OpenHands 视为具有键盘的 AI 队友。与仅限聊天的助手不同，OpenHands 可以：
这使其非常适合执行诸如实现功能、修复错误、编写测试、创建文档、重构和现代化代码库之类的任务。无需处理提示和复制/粘贴，您可以给 OpenHands 一个目标，然后让它迭代，由您监督其操作。
快速入门：使用 OpenHands 的最快方法
有几种方法可以开始使用。您的选择取决于您是想使用云 LLM 还是在本地运行所有内容。
选项 A：使用云 LLM（最简单）
- 按照官方的“开始构建”和“入门”文档安装并运行该应用程序。您通常需要：
- 安装先决条件（Docker、Node、Python、Git，取决于路径）
- 为受支持的云模型提供 API 密钥（例如，OpenAI、Anthropic 或项目当时支持的其他模型）
此路径使您可以快速高效地工作，且计算开销最小。
选项 B：使用本地 LLM 运行 OpenHands
- 如果您希望将代码和提示保留在云端之外，或者想避免 API 费用，请使用官方文档中的本地 LLMs 指南。
- 设置兼容的本地模型（通过 Ollama 或当时支持的其他后端）
- 确保您的机器具有足够的 VRAM/CPU 和磁盘空间
选项 C：部署到 VM
- 如果您需要专用环境，实践者已经记录了如何在 VM 上启动 OpenHands 并在几分钟内构建应用程序。这对于希望获得稳定、共享的 AI 工程师实例的团队非常有用。
首次运行：项目设置和任务框架
当 OpenHands 可以看到您的代码时，它会发挥作用。首先：
- 运行或索引项目，以便 OpenHands 可以映射结构。
良好的任务框架示例：
- “使用基于令牌的电子邮件链接将用户密码重置添加到
auth 服务。使用现有的 mailer 模块。为令牌生成和过期添加单元测试。不要更改用户数据模式。”
为什么这行得通：
- 它命名了组件、范围、依赖项和边界。您越清楚，OpenHands 计划和执行得就越好。
如何为 OpenHands 编写有效的提示
将提示视为简洁的票证。最好的提示：
- 引用文件、模块或测试：“请参阅
auth/routes.py 和 tests/test_auth.py”
- 包括验收标准：“测试应通过：
pytest -k password_reset”
您可以重复使用的模板：
目标：<您希望构建或修复的内容>
上下文：<相关文件、已知约束、外部服务>
验收：<通过的样子：测试、端点、指标>
边界：<不要更改或避免的方法>
工具：<它可以运行的命令、脚本或数据源>
核心工作流程：计划 → 执行 → 验证 → 改进
OpenHands 通常会提出一个多步骤计划。以下是如何指导它：
- 尽早批准或调整其计划。推动它首先运行测试以确定基线故障。
- 如果它停滞不前，请添加更多上下文：文件名、堆栈跟踪或日志。
专业提示：鼓励小的 PR 大小的更改，而不是整体编辑。这有助于审查和回滚。
您可以复制的示例工作流程
1) 功能实现
- 提示：“将 CSV 导出添加到
orders 页面。使用服务器端分页，通过 text/csv 流式传输结果。在 OrdersTable.jsx 中添加 Export 按钮，并在 routes/orders.ts 中添加端点。包括分页和标头的测试。”
2) 调试失败的构建
- 提示：“CI 在 Node 20 上失败。修复
build.mjs 中的 ESM/CJS 导入错误。保留现有的汇总插件；更新配置和代码以通过 CI。”
- 要求 OpenHands 在本地复制 (
npm run build) 并提出最小差异。
3) 测试覆盖率和强化
- 提示：“将
payments/service.py 的覆盖率从 62% 提高到 85% 以上。为 retry_charge、refund、webhook_signature 添加单元测试。除非测试暴露了错误，否则不要修改业务逻辑。”
- 让 OpenHands 生成测试，运行它们并进行改进。
4) 文档和开发者体验
- 提示：“为此代码仓库创建一个
CONTRIBUTING.md 和 DEVELOPMENT.md。包括环境设置、脚本、测试命令和 PR 指南。”
防护措施：保持 OpenHands 有用且安全
- 目录范围：将其指向特定的代码仓库或目录，以避免在其他地方进行意外编辑。
- 文件保护：尽可能将配置文件或关键基础设施标记为只读。
- 命令审计：需要批准破坏性命令（例如，
rm -rf、数据库重置）。
- 机密卫生：切勿将 API 密钥粘贴到提示中。使用环境变量和屏蔽日志。
- 网络访问：如果启用了浏览，请对其进行沙盒化并记录出站调用。
本地与云模型：选择适合您的模型
请参阅官方的本地 LLMs 说明来配置模型后端和内存限制。
团队合作：在协作流程中使用 OpenHands
- 分支优先工作流程：让 OpenHands 创建一个功能分支并推送更改以进行 PR 审查。
- 提交卫生：要求它生成具有清晰消息和引用问题编号的原子提交。
- PR 模板：生成并强制执行 PR 模板，以便审查者了解更改的内容和原因。
- 代码所有者：与 CODEOWNERS 结合使用，将 AI 生成的 PR 路由到正确的审查者。
解决常见问题
- 它卡住或循环：缩小范围。要求它解释下一步。提供失败的测试。
- 混乱的差异：请求一个较小的、分阶段的计划——先进行测试，然后进行最小的代码更改。
- 在本地通过但在 CI 中失败：共享 CI 环境详细信息和日志；让它使用容器进行复制。
性能提示和强大功能
- 热启动上下文：要求它首先读取关键文件（
README、package.json、主要服务文件）。
- 给它脚本：提供一个
make test 或 npm run verify，以便它可以快速验证。
- 教授领域知识：提供一个简短的架构概述；它会在减少逻辑错误方面有所回报。
- 强制执行样式：指向
.eslintrc、.prettierrc、black/ruff 配置，以便它正确格式化。
- 使用检查点：在每个里程碑之后，要求提供摘要和后续步骤，以使其保持在正轨上。
真实场景：从错误报告到一小时内的补丁
- 情况：生产错误在
orders API 中丢弃未处理的 500 个畸形 JSON 有效负载。
- 您的提示：“在
orders POST 上重现畸形 JSON 的 500 错误。添加模式验证并返回 400 并提供错误详细信息。更新测试以覆盖畸形有效负载。”
节省的时间：您专注于影响分析和推出，而 OpenHands 处理了脚手架。
增强 OpenHands 的集成
- 测试运行器：pytest、Jest、Vites、JUnit
- 构建工具：Vite、Webpack、Rollup、Babel
- 包管理器：npm、pnpm、yarn、pip/poetry
- Linters/格式化程序：ESLint、Prettier、black、ruff
- 容器：Docker Compose 用于与 CI 的本地奇偶校验
通过标准化这些工具，OpenHands 可以更可靠地推理您的堆栈，并自动化更多的开发循环。
顺便说一句：将 Sider.AI 与 OpenHands 一起使用
相关性得分：8/10。如果您将 OpenHands 用作您的 AI 工程师，则值得将其与研究和起草副驾驶配对，以用于规范、PR 描述和文档。顺便说一句，Sider.AI 可以帮助您快速起草技术规范、总结 RFC 或将 OpenHands 运行日志转换为干净的变更日志和发行说明。这种组合减少了上下文切换：OpenHands 处理代码操作，而 Sider.AI 将结果转换为干净的、面向用户的文档。
安全性、隐私性和合规性清单
- 将机密信息保存在 env vars 中；切勿将密钥嵌入到提示中
- 像审查初级开发人员的 PR 一样审查每个 AI 生成的更改
- 固定工具链版本；避免在 lockfiles 中意外升级
- 如果使用云 LLMs，请与您的数据保留策略保持一致
何时不使用 OpenHands
您使用 OpenHands 的前 60 分钟：迷你剧本
- 第 10-20 分钟：连接您的代码仓库；要求它映射项目结构
- 第 20-35 分钟：定义一个小的、可测试的目标；批准其计划
- 第 35-50 分钟：让它实施和运行测试；根据需要进行推动
- 第 50-60 分钟：审查差异，改进并合并到功能分支中
关键链接和后续步骤
- OpenHands 的官方“开始构建”和使用文档：提示、快速入门和最佳实践。
- 本地 LLM 设置指南：完全在您的机器上配置和运行 OpenHands。
- 社区驱动的 VM 安装演练：真实的安装步骤和一个快速演示项目。
要点
- 使用防护措施和审查更改——像对待初级队友一样对待它。
- 与文档工具（例如，Sider.AI）配对，以加速规范和发行说明。
常见问题
Q1：如何快速安装和开始使用 AI OpenHands？
使用官方快速入门安装先决条件，插入受支持的 LLM（云或本地），然后启动 UI 以连接您的代码仓库。“开始构建”文档提供了带有设置提示的分步说明。
Q2：我可以使用本地 LLM 而不是云模型运行 OpenHands 吗？
是的。按照本地 LLMs 指南配置本地模型后端并调整上下文设置。这非常适合隐私敏感型项目或避免 API 成本。
Q3：提示 OpenHands 进行编码任务的最佳方法是什么？
像编写简洁的票证一样编写提示：定义目标，引用特定文件，设置边界，并包括验收标准。要求它创建或运行测试以验证进度。
Q4：AI OpenHands 可以安全地用于生产代码吗？
像对待初级开发人员一样对待它：使用分支保护、代码审查和 CI 来验证更改。为命令添加防护措施，并使机密信息远离提示。
Q5：OpenHands 与传统的代码助手相比如何？
与仅限聊天的工具不同，OpenHands 可以在您的代码仓库中运行命令、编辑文件和自主迭代。它专为端到端任务而构建，例如功能、调试和测试。
