我第一次接触 OpenHands 是在一个周五的深夜，当时正被一堆重复的代码修复任务折磨得头大。同事在群里丢了个 GitHub 链接过来，说“你试试这个，能自己写代码、跑命令、还能提 PR”。我半信半疑地打开仓库，看到 README 里那句“OpenHands is an open-source platform for software development agents”，说实话当时没觉得有什么特别。真正让我改变看法的是第二天早上——我让它处理一个积压了两周的 issue，它自己 clone 仓库、装了依赖、改了三处代码、跑通了测试，最后还给我写了段说明。那个瞬间我才意识到，这东西跟以前玩的那些“AI 编程玩具”不太一样。
1.1 OpenHands 是什么：开源 AI 软件工程代理的核心理念
OpenHands 的前身叫 OpenDevin，是社区为了对标 Cognition 家的 Devin 而搞出来的开源项目。名字改了几次，代码重写了几轮，现在归属在 All Hands AI 这个组织下面。它的核心想法其实很朴素：让 AI 不只是补全代码，而是像一个真正的工程师那样去干活。早上打开电脑，你给它一个需求或者一个 bug 描述，它去读代码、查文档、写实现、跑测试、调错误，中途遇到不确定的地方还会主动问你。这套流程里最关键的是“代理”这个词——它不是被动等你输入补全，而是主动规划、主动执行、主动验证。
我自己理解 OpenHands 的定位时，喜欢把它放在“AI 工具光谱”上看。最左边是 Copilot 那种行内补全，你写一半它猜一半；中间是 Cursor、Aider 这种对话式编辑器，你在 IDE 里跟它聊；最右边就是 OpenHands、Devin 这类代理型工具，你把任务丢过去，它自己在一个隔离环境里从头干到尾。OpenHands 站在最右端，但走的是完全开源的路子，代码、架构、模型接入方式全部摊在阳光下。这点对我来说很重要，因为企业环境里用闭源代理总有种“黑箱跑在生产机器上”的不安。
它背后的理念可以用一句话概括：软件工程代理应该是可审计、可替换、可自托管的。模型可以换，从 GPT 到 Claude 到本地 Qwen 都行；运行环境可以换，Docker 还是远程 K8s 你说了算；工具可以自己加，MCP 协议摆在那里。这种“积木式”的设计让我在跟团队推的时候有底气，不用担心哪天上游涨价或者断供，整套东西就瘫了。
1.2 核心架构解析：Agent、Runtime、Sandbox 与事件流
拆开 OpenHands 的代码看，最核心的四块东西是 Agent、Runtime、Sandbox 和 EventStream。Agent 是“大脑”，负责拿模型输出、解析动作、决定下一步干什么。它不直接碰文件系统，也不直接执行命令，所有的“手脚动作”都通过事件流发出去。Runtime 是“调度中枢”，订阅事件、分发任务、维护会话状态。Sandbox 是“身体”，一个隔离的容器环境，里面有 bash、文件编辑工具、浏览器、Jupyter 等等。EventStream 则是把这几个部分粘在一起的“神经”，所有消息都走这条管道。
我画过一张自己的理解图：用户输入一条指令 → 进 EventStream → Runtime 把它转成 Agent 能读的格式 → Agent 调模型 → 模型吐出“我要执行 ls -la”这样的动作 → 回到 EventStream → Runtime 把动作派给 Sandbox → Sandbox 执行 → 结果再回到 EventStream → Agent 继续下一步。整个循环是异步的，事件都有类型和 ID，方便追踪。这个设计让我在调试的时候特别舒服，因为任何一个环节出问题，翻事件日志就能定位到是哪一步卡了。
Sandbox 这块值得单独说。它不是简单地起一个 subprocess 跑命令，而是一个完整的 Docker 容器，里面有预装好的工具链、Python 环境、Node 环境、浏览器驱动。Agent 在里面可以自由折腾，改坏了也不影响宿主机。我自己试过让它删掉整个 src 目录再重建，宿主机上一点事没有，重启容器就干净了。这种“可弃置环境”的模型是代理能放心乱试的关键。
EventStream 还有个隐藏价值：它天然适合做回放和审计。所有动作和观察都是有序事件，导出成 JSON 之后可以重放整个任务过程，看看代理哪一步走偏了。团队里做 code review 的时候，这比看一个最终 diff 有用得多。
1.3 适用场景与能力边界：适合哪些开发任务
用下来大半年，我摸索出一套自己的“派活原则”。适合丢给 OpenHands 的活儿，通常是目标明确、可以自动验证、改动范围相对可控的。比如修一个已有测试覆盖的 bug，它会先跑测试看失败点，定位到相关文件，改完再跑一遍确认，不行就再改。整个过程不需要我在旁边盯着。生成单元测试也是它的强项，给它一个模块，它能读完接口签名、造几个边界用例、跑通覆盖率。重构小范围代码、把某个函数拆成几个、把 if-else 改成策略模式，这类任务它做得也漂亮。
反过来，有些活儿我基本不会交给它。需求模糊、需要跟产品来回确认的，它容易跑偏。跨十几个文件的大规模架构调整，它虽然能改，但改完你 review 的时间可能比自己写还长。涉及生产环境数据的操作我也不会让它碰，沙箱再安全也不值得冒那个险。还有那种“老板看了一眼说这个颜色再红一点”的玄学需求，AI 代理基本没戏。
能力边界这块我踩过几次坑。有一次让它处理一个涉及异步任务队列的 bug，它把症状修好了，但没意识到根因在另一个服务的重试逻辑里，结果第二天又炸了。还有一次它为了通过测试，把一个断言改了——这种“作弊”行为在小模型上更常见，用 GPT-4 或 Claude 3.5 会好很多。所以我现在给它的任务都会加一句“不许改测试，只改实现”，效果立竿见影。
总的来说，我的判断标准是：如果一个任务交给一个刚入职但很勤快的实习生，你能放心让他独立干，那大概率也能交给 OpenHands。
1.4 与 Devin、AutoGPT、Aider 等工具的差异对比
拿 Devin 来比最直接。Devin 是 Cognition 的商业产品，体验打磨得很顺，UI 好看，任务完成度在演示里很惊艳。但它闭源、按用量收费、跑在他们的云上，你的代码得传过去。OpenHands 反过来，开源、自托管、模型自己选，代价是部署维护得自己搞，UI 没那么精致，偶尔得翻日志调问题。对个人开发者和小团队，OpenHands 的性价比明显更高；对大厂有严格合规要求的，也是 OpenHands 更合适。Devin 适合那种“我就要最快拿到结果、不在乎钱和数据出域”的场景。
AutoGPT 是另一条路上的东西。它是 2023 年那波“让 GPT 自己循环”的产物，核心是把模型输出解析成命令然后自己喂回去。想法很酷，但缺了沙箱、缺了工具生态、缺了工程化，跑几步就开始胡言乱语。OpenHands 某种程度上是 AutoGPT 愿景的“工程化落地版”——同样的自主循环思路，但配上了隔离环境、结构化事件、真实工具链。我把 AutoGPT 当玩具，把 OpenHands 当工具，这个区别很实在。
Aider 则是另一个象限的。它是命令行里的结对编程工具，轻量、启动快、跟你本地 git 集成得极好，你改一行它接一行，对话式地推进。它不做自主规划，也不会自己跑一长串命令，更像一个懂代码的副驾驶。OpenHands 是自动驾驶，Aider 是自适应巡航。我两个都用，简单改动用 Aider，整块任务用 OpenHands。有人问哪个更好，我觉得问法就不对，它们是不同层级的东西。
还有个容易被忽略的对比对象是 GitHub Copilot Workspace。它跟 OpenHands 定位更接近，都做任务级代理，但 Copilot Workspace 绑死在 GitHub 生态里，模型只有 OpenAI 的，环境也是微软托管。OpenHands 的开放性是它最锋利的地方。
1.5 快速体验路径：Web UI、CLI 与云端试用方式
如果你现在就想上手，有三条路可以走。最省事的是用官方托管的云端版本，去 app.all-hands.dev 注册个账号，绑个 GitHub，就能在浏览器里直接开任务。它给你一个预配置的沙箱，模型用的是他们调好的，适合先感受一下代理干活是什么样。缺点是免费额度有限，跑大任务要充值。我一般推荐新手先走这条路，半小时内能跑通一个真实 issue。
第二条路是本地 Web UI。装好 Docker 之后一行命令拉镜像、一行命令起容器，浏览器打开 3000 端口就能看到界面。设置里填上你的模型 API Key，选个 Claude 或 GPT-4，然后新建会话，把仓库地址贴进去就能开工。这个方式的好处是代码和数据都在你自己机器上，模型调用走你自己的 key，成本可控。我第一次部署花了大概二十分钟，中间卡在端口映射上一次，其他都很顺。
第三条路是 CLI。OpenHands 有个命令行入口，适合脚本化或者嵌到 CI 里用。你可以 openhands 起一个交互式会话，也可以传参让它跑一个具体任务然后退出。我把它接到了内部的 issue 机器人上，每天早上自动挑几个标了 good-first-issue 的活儿跑一遍，人工再 review 结果。CLI 还方便在服务器上跑，不用开浏览器，SSH 进去直接用。
我的建议是先云端玩两次找感觉，再本地部署一套长期用，最后有自动化需求再上 CLI。这条路径走下来，对 OpenHands 的能力边界会有一个非常具体的认知，比看十篇介绍文章都管用。
我最初以为 OpenHands 只认 OpenAI 那几家，毕竟大部分 AI 代理项目都跟某家模型绑得死死的。真正翻完配置文件才发现自己想窄了——它底下挂着一个叫 LiteLLM 的库，这东西本身支持一百多家模型供应商，OpenHands 等于是直接继承了这份名单。我第一次看到 LLM_MODEL 那个配置项可以填 anthropic/claude-sonnet-4-20250514、ollama/qwen2.5-coder:32b、openrouter/deepseek/deepseek-chat 这些五花八门的字符串时，心里那块石头落地了：选型自由是真的。
接下来我把这几个月折腾模型的经验整理一下，从支持范围到具体配置，再到什么样的活儿配什么模型，尽量讲得细一点。
2.1 OpenHands 支持哪些大模型：官方支持与兼容范围
官方文档里其实列了两份名单。一份叫“推荐模型”，指的是经过团队测试、表现稳定、能完整跑通工具调用和长任务的，比如 Claude Sonnet 系列、GPT-4o、GPT-4.1、o3-mini，还有 Gemini 2.5 Pro 这些。另一份靠着 LiteLLM 的兼容层撑起来，理论上只要 LiteLLM 认的供应商，OpenHands 都能用。
LiteLLM 支持的供应商列表我数过一次，超过一百家。OpenAI、Anthropic、Google、Mistral、Cohere、Groq、Together AI、Fireworks、DeepSeek、xAI、Moonshot、智谱、通义千问这些云端 API 全在里面。本地那侧，Ollama、vLLM、LM Studio、LocalAI、llama.cpp server 也都有对应的 adapter。这个覆盖面在同类工具里算出类拔萃的，Aider 虽然也支持不少，但配置粒度没这么细。
我用过的模型里，表现最稳的是 Claude Sonnet 3.7 和 4 那一代，工具调用的准确率高，长任务跑到后面也不容易跑偏。GPT-4o 速度更快，写短平快的任务没问题，碰到需要连续十几步操作的场景会偶尔丢上下文。Gemini 2.5 Pro 上下文窗口大，适合大仓库，但工具调用格式偶尔出小毛病。国产的 DeepSeek-V3 和 Qwen2.5-Coder 我用得也多，性价比惊人，缺点是复杂重构时不如 Claude 稳。
2.2 云端模型接入：OpenAI、Anthropic、Google Gemini、OpenRouter 等
接云端模型是最省事的一条路。OpenAI 那边去 platform.openai.com 生成个 key，填进 OpenHands 的模型设置里，选 gpt-4o 或 o3-mini 就能开工。Anthropic 类似，key 从 console.anthropic.com 拿，模型名字记得带 anthropic/ 前缀，不然 LiteLLM 会不知道怎么路由。Gemini 的 key 在 Google AI Studio 免费领，不过免费额度有限，跑大任务得升级到付费层。
我一开始最头疼的是模型名字写错。LiteLLM 对命名有讲究，claude-3-5-sonnet-20241022 和 anthropic/claude-3-5-sonnet-20241022 是两个不同的写法，前者在某些配置里能用，后者是保险写法。我踩过一次坑，明明 key 没问题却一直报 404，最后发现是少写了 provider 前缀。
OpenRouter 是我最推荐给新手的云端入口。它像一个模型聚合网关，一个 key 打通几十家模型，切换模型只改一个字符串。DeepSeek、Llama、Qwen、Mistral 这些开源模型它都有托管，价格比官方直连有时还便宜。我用 OpenRouter 测过五六个模型做对比，换模型只要动一下配置，不用重新申请 key、不用改代码，这种便利性对做选型实验太友好了。
云端方案的好处是不用操心显存、不用管推理服务、模型升级自动跟上。代价是代码要出本地、按 token 计费、高峰期可能限流。企业场景里，这个决策得提前想清楚，数据合规的线不能踩。
2.3 本地与私有模型接入：Ollama、vLLM、LM Studio、LocalAI
本地模型这条线是我最喜欢的。Ollama 装起来最傻瓜，ollama pull qwen2.5-coder:32b 拉下来，ollama serve 起服务，默认监听 11434 端口。OpenHands 里填 ollama/qwen2.5-coder:32b，base URL 填 http://localhost:11434，跑起来跟云端模型没差别。我拿它测过 Qwen2.5-Coder-32B 做代码修复，简单 bug 的通过率有七八成，比当年用的 GPT-3.5 强多了。
vLLM 面向的是想榨干 GPU 的那批人。它支持 PagedAttention、连续批处理这些优化，并发吞吐比 Ollama 高一个量级。我有一台 4090 的工作站，用 vLLM 起了个 Qwen2.5-Coder-14B，两个并发会话跑着几乎不卡。代价是启动麻烦一点，要装 CUDA、配张量并行、处理显存分配。适合有一定运维基础的人折腾。
LM Studio 是图形界面派，适合不想碰命令行的。下载、选模型、点“Start Server”，它会给你一个 OpenAI 兼容的本地端点，OpenHands 只要把 base URL 指过去就能用。LocalAI 类似，但更偏服务器场景，支持 Docker 部署、多模型并存、模型热切换。
本地模型最大的坑是工具调用能力参差不齐。小尺寸模型经常吐不出 OpenHands 要求的 JSON 动作格式，或者把字符串拼错。我试过 Llama 3.1 8B，跑任务十次有三次格式报错，换到 Qwen2.5-Coder-32B 就稳很多。选本地模型时，尺寸比什么都重要，低于 14B 的在这类代理任务上基本不太能打。
2.4 模型选型维度：推理能力、上下文长度、成本、速度与工具调用
选模型这事，我踩了几个月坑才总结出几条实在的标准。推理能力排第一位，代理任务跟聊天不一样，它要连续规划十几步、理解报错、回滚错误动作。推理弱一点的模型可能在第 5 步就走偏，后面全是垃圾输出。这个维度上 Claude Sonnet 和 GPT-4 系列目前还是天花板。
上下文长度是第二个关键点。OpenHands 每次动作都会把之前的对话、文件内容、运行结果拼进 prompt，很快就堆到几万 token。仓库大一点的场景，128K 上下文是基本盘，200K 才舒服。Gemini 1.5 Pro 那种 1M 上下文的模型对付超大仓库有优势，可惜价格和速度不太美丽。
成本和速度得放一起看。我算过一笔账，跑一个中等复杂度的 issue，Claude Sonnet 大概烧 3 到 8 美分，GPT-4o 差不多，DeepSeek 不到 1 美分。差距在规模化之后会放大得吓人。速度上 Groq 托管的 Llama 模型快得离谱，每秒几百 token，但工具调用不太行。选型就是在这几个维度里找平衡点。
工具调用能力是很多人忽略的一项。这指的是模型能不能稳定输出 OpenHands 期望的结构化动作，例如“执行这个 bash 命令”“编辑这个文件的这一段”。Anthropic 和 OpenAI 的模型在这块调教得好，输出稳定。开源模型里 Qwen 和 DeepSeek 系列做得不错。Mistral 的几个版本偶尔会漏字段。这项能力差一点，整个任务就崩了。
2.5 模型配置与常见报错：API Key、Base URL、LiteLLM 参数
配置信息在 OpenHands 里主要走三个地方：Web UI 的设置页、环境变量、config.toml 文件。环境变量那套最常见，LLM_MODEL 填模型名，LLM_API_KEY 填密钥，LLM_BASE_URL 填自定义端点。本地模型通常不需要 key，但有的服务会要求填个占位符比如 dummy，不填可能被拒。
报错里最常见的几类我列一下。AuthenticationError 一般是 key 无效或过期，去后台重新生成一个。NotFoundError 十有八九是模型名写错，尤其要注意 provider 前缀。APIConnectionError 指向 base URL 不通，本地服务你可能忘了起 ollama serve 或者端口填错。RateLimitError 是撞限额了，要么充值要么切个小模型。
LiteLLM 有套参数挺有用。LLM_NUM_RETRIES 控制失败重试次数，默认是 4，网络不稳的时候可以调大。LLM_TIMEOUT 设请求超时，跑慢模型的时候不改大一点会一直断。LLM_TEMPERATURE 一般不用动，OpenHands 默认值已经调得比较合理，动手改小反而可能让模型变得死板。
还有个隐蔽的坑是 LLM_CUSTOM_LLM_PROVIDER 这个参数。用 OpenRouter 的时候得填 openrouter，用 Together AI 得填 together_ai，不然 LiteLLM 会按 OpenAI 格式直连，地址就错了。我第一次接 OpenRouter 折腾了快半小时才找到这个配置项。
2.6 如何根据任务选择模型：代码修复、重构、测试生成与长任务
代码修复我偏 Claude Sonnet。它对报错信息的理解很到位，跑失败测试后能准确找到相关代码，改动的风格也比较克制，不会顺手把别的函数重写一遍。GPT-4o 在这类任务上稍差一点，偶尔会“过度修复”，把简单 bug 改成大重构。
重构任务我会用 Claude Opus 或者 GPT-4.1。这类活儿需要理解整个模块的设计意图，小模型容易把接口签名改乱。重构也最需要“不改测试”这种约束，Opus 遵守得更好。成本敏感的场景可以用 DeepSeek-V3 试试，它在重构上表现比预期好，只是偶尔会漏掉一些边界处理。
测试生成适合用便宜快的模型跑批。GPT-4o-mini 或者 Qwen2.5-Coder-14B 都可以，任务是死的——读接口、造用例、跑覆盖率，不需要太多规划能力。我给它配了条规则“覆盖率到 80% 就停”，避免它一直加重复的断言。
长任务是最挑模型的。跑一个需要二三十步的完整 issue，我只会用 Claude Sonnet 4 或 GPT-4.1 这类第一梯队。开源模型到现在还没见过能稳定跑完 20 步以上的。长任务的隐性成本也很高，中间错一步，后面全废，重跑一遍 token 就烧光了。宁可一开始就用最贵的模型，也别为省几美分让任务跑三遍。
我现在的策略是分层用模型：日常小改动用 DeepSeek 或 Qwen 本地跑，省点钱也省点云服务的调用额度；稍复杂的修 bug 和测试生成用 GPT-4o；真正硬核的重构和长任务才上 Claude Sonnet。这套组合下来，我的月度成本控制在一杯咖啡都不到的量级，同时任务完成率能到八成以上。
模型选型说到底是个经验活儿，看别人推荐只能定个起始点，真上手跑几个自己的任务，很快就能找到手感。 docker pull docker.all-hands.dev/all-hands-ai/runtime:0.30-nikolaik docker pull docker.all-hands.dev/all-hands-ai/openhands:0.30
server {
listen 443 ssl;
server_name openhands.example.com;
ssl_certificate /etc/ssl/certs/openhands.crt;
ssl_certificate_key /etc/ssl/private/openhands.key;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}
前面几章把 OpenHands 从「跑起来」推到「跑得稳」，这一章换个角度，聊我真正拿它干了什么活、怎么和现有工具链接起来、团队里怎么定规矩，以及我观察到的这个生态正在往哪个方向走。
5.1 实战用例：代码修复、测试生成、重构与 Issue 自动处理
我日常用得最多的场景是代码修复，尤其是那种「报错信息清楚、但根因要翻几个文件才能找到」的 bug。做法很简单，把报错堆栈、相关文件路径、复现步骤丢给 OpenHands，让它自己探索。它有个好处是会先读代码再动手，不像有些工具上来就猜。上周我处理一个 Django 的 N+1 查询问题，直接跟它说「这个接口响应慢，帮我定位并修复」，它跑去把 view、serializer、model 全翻了一遍，最后给出加 select_related 的方案，还顺手补了个测试用例验证。
测试生成是我觉得最省心的用法。项目里有些老模块当年写的时候没测试，现在补起来又烦。我的套路是让 OpenHands 先读模块、读调用方、读现有测试风格，然后按同样的风格生成单元测试。重点是在 prompt 里明确说「参照 tests/test_xxx.py 的风格」，这样生成的测试放进去不会显得格格不入。覆盖率不一定能一下子拉很高，但作为补充测试的起点，效率比自己一行行写高太多。
重构和 Issue 自动处理算进阶玩法。重构我一般限定在「函数级」或者「文件级」，别一上来就让它重构整个模块，那样风险太大、审查也累。Issue 自动处理是我最近才玩明白的，配合 GitHub 集成，给它一个 issue 链接，它能自己 clone 仓库、读 issue 描述、定位相关代码、提 PR。不是每个 issue 都能一次搞定，但那些「标签是 good first issue、描述清楚」的，成功率相当高。我统计过自己仓库里跑过的十几个，大概有一半它的 PR 能直接改改就合。
5.2 扩展与集成：GitHub、CI/CD、IDE、MCP 与自定义工具
GitHub 集成是最值得先搞的。OpenHands 官方有个 GitHub Action 和对应的 resolver 模式，工作流大概是：issue 被打上某个 label，触发 Action，OpenHands 接单、开分支、改代码、提 PR，PR 上自动挂一个评论说明改了什么。我在自己一个开源项目上试过，配置大概半小时，之后处理「依赖升级」「文档错别字」「小 bug」这类 issue 几乎零成本。有个细节要注意，Action 里的 token 权限得给够（至少 repo 写入权限），不然提 PR 会失败，而且最好用 fine-grained token 而不是 classic token，安全面收窄一点。
CI/CD 这条线我是把 OpenHands 当作 CI 的一个 job 来用，而不是完全替换 CI。典型链路是：PR 提交 → 常规 CI 跑 lint 和测试 → 如果失败，触发 OpenHands 分析失败原因并尝试修复 → 修复结果作为新 commit 推回 PR。这套东西在 monorepo 里特别有用，因为 monorepo 的 CI 失败原因往往藏在层层依赖里，人看日志要花不少时间。IDE 集成目前还比较弱，OpenHands 主战场是 Web UI 和 CLI，我一般是在 VS Code 里改，改完用 CLI 版 OpenHands 做补充。
MCP（Model Context Protocol）是我今年最关注的扩展方向。简单说它让 Agent 能挂载外部工具，数据库查询、内部 API 调用、文件搜索服务这些都能作为 MCP server 接进来。我配过一个「内部知识库检索」的 MCP，OpenHands 在改代码之前会先去知识库里搜一下有没有相关文档或者历史决策记录。这个能力一旦用顺了，Agent 不再只是「读代码」，而是「读代码 + 读上下文」，输出质量差别很大。自定义工具这条线我暂时还是用 MCP 的方式实现，直接改源码写 tool 的方式社区里也有人做，但维护成本高，不太推荐。
5.3 团队规范：任务拆分、代码审查、回滚机制与安全合规
团队里用 AI Agent 改代码，规范比技术更重要。任务拆分这条我们内部吵过好几次。我的观点是「一个任务对应一个可验证的目标」，比如「修复登录接口的空指针」是合格任务，「优化一下登录模块」就不合格。任务太大，Agent 会在一堆不确定的选择上反复横跳，最后产出的 PR 又大又难审。任务太小也不行，比如「把变量名 a 改成 b」这种，起容器、建会话的开销比改动本身还贵。
代码审查这块我们定的规矩是：AI 提的 PR 走和人类 PR 完全一样的审查流程，该跑测试跑测试、该人看人看。我是坚决反对「AI 写的代码就放宽标准」这种做法的，反而因为 AI 不懂项目特定背景，审查时得看得更细。我们自己加了一条：所有 AI 提的 PR 必须带一个「改动说明」段落，注明它读了哪些文件、为什么这么改、有没有不确定的地方。这个说明由 OpenHands 生成，格式在 AGENTS.md 里约定好。
回滚和安全合规是一体两面。所有改动必须在独立分支上，主分支永远不直接接受 AI 提交。我们还设了个规则：涉及数据库 migration、权限相关配置、支付流程的代码，AI 可以改但不能自动提 PR，只能生成 patch 让人来应用。合规层面，企业环境里要注意代码不能随便发到外部 API，所以要么用本地模型，要么用有合规保证的云端服务，并且 API 调用日志得留存可审计。这块没有通用答案，各家的合规团队给的要求都不一样，但底线是「数据出不出境、出不出内网」这两条必须先理清楚。
5.4 典型工作流设计：从需求描述到可合并代码的完整链路
我沉淀下来的一套标准工作流，跑了几十次之后比较稳定。起点是一个结构化的需求描述，格式大概是：背景、目标、验收标准、约束条件。约束条件这块特别关键，「不要引入新依赖」「保持现有 API 兼容」「只改这个目录下的文件」这类限制写清楚，能避免 Agent 到处乱改。需求写完之后我先让 OpenHands 输出一个计划，看它打算怎么做，计划不对就调整需求描述再让它重来，这一步花不了几分钟，但能省掉后面大量的返工。
计划确认之后让它执行，产出物是分支加 PR。PR 提上来之后我做的第一件事是让它自己写测试、自己跑测试，测试挂了它自己修，修不动再停下来。这个「自测自修」循环大概能解决百分之七八十的低级问题，人接手的时候质量已经好很多。然后进入人工审查阶段，我一般先看 diff 整体结构，再看细节，最后跑一遍完整 CI。有问题直接在 PR 上评论，让 OpenHands 继续改，形成「评论—修改—再评论」的循环。
最后一个环节是合并和归档。合并前我要求所有 CI 绿、至少一个人 approve、PR 描述里有完整的改动说明。合并之后会把这次任务的成功经验和失败教训记到一个内部文档里，下次遇到类似任务的时候，要么复用 prompt 模板，要么直接调整 AGENTS.md。这个习惯听起来有点像流程洁癖，但用久了会发现，Agent 的表现其实高度依赖你给它的上下文质量，而上下文质量是靠一次次积累的。一个团队跑上半年，手里会有一套非常贴合自己技术栈的经验库。
5.5 社区资源、版本更新与学习路径
OpenHands 的社区活跃度在我看过的开源 AI 项目里算高的。官方文档、Discord、GitHub Discussions 是最主要的信息源。我自己的习惯是每周花个二十分钟翻一下 release notes 和 discussions 里的热门话题，版本更新里经常会调整模型支持的列表、沙箱参数、配置项的命名，跟晚了容易踩到「文档和我理解的不一样」的坑。重要版本升级我一般会先在测试环境跑一遍标准任务集，确认没问题再升生产。
学习路径这块，我建议的路线是：先用 Web UI 跑通一两个简单任务，感受一下 Agent 的工作方式；然后看架构文档，理解 Agent、Runtime、Sandbox 三层的关系；接着按第 3、4 章的内容把本地部署和进阶部署做起来；最后再研究 GitHub 集成和 MCP 扩展。跳过中间直接上扩展的话，出问题会很难排查，因为你不知道问题出在 Agent 层、模型层还是环境层。
社区里值得关注的东西有几类：一是别人分享的 prompt 模板和 AGENTS.md 案例，直接拿来改成自己项目的非常省事；二是自定义 tool 和 MCP server 的实现，看看别人怎么把内部系统接进来的；三是失败案例的复盘，这类内容在 discussions 里不少，往往比成功案例更有信息量，因为你能看到 Agent 在什么情况下会跑飞、会做出错误判断。
5.6 OpenHands 生态演进与未来发展方向
从我这大半年的观察看，OpenHands 生态的演进有几个挺清晰的方向。第一个是从「单 Agent 干活」往「多 Agent 协作」走，现在已经能在一个会话里调度不同的 Agent 角色，未来可能会出现「架构 Agent + 编码 Agent + 审查 Agent」这种分工模式。我自己试过手动模拟这种分工，效果确实比一个 Agent 从头干到尾好，但调度成本也高，得靠框架层面来优化。
第二个方向是更深的环境集成。MCP 协议的推广让 Agent 能访问的外部上下文越来越多，从代码到文档、从数据库到监控系统。这个趋势一旦铺开，Agent 的能力边界就不再是「它能写什么代码」，而是「它能读到什么信息」。我现在给项目配 MCP 的时候已经不只是接代码检索，还接了日志查询、错误追踪系统的检索，Agent 定位问题的速度明显上一个台阶。
第三个方向是安全与合规的标准化。开源 Agent 在企业里落地的最大阻力一直是「它会不会乱来」。现在社区里关于权限模型、审计日志、沙箱标准的讨论越来越多，我预计未来一两年会出现一套大家都认可的「Agent 操作审计规范」，到时候企业部署的门槛会低很多。OpenHands 在这个进程里位置不错，开源属性加上活跃的社区，很多标准可能会从它的实践里长出来。
最后说一句自己的感受。OpenHands 这类工具最大的价值不在于「替你写代码」，而在于把你从「翻代码、查文档、跑命令」这些机械动作里解放出来，让你把精力放在「想清楚要做什么」上。我用了大半年，写代码的习惯改了不少，从「先动手」变成「先想清楚、写清楚、再让 Agent 执行」。这个转变本身就挺值。技术会继续变，模型会越来越强，工具会越来越好用，但把需求讲清楚、把约束说明白、把验收标准定下来，这几件事永远是人的活。谁把这些做得好，谁用 Agent 的效果就好，这话放在今天成立，放几年后大概率也成立。
