OpenHands：基于模型的开发智能体 本地

#具体来说，它能做什么

您用法语描述一项任务。它会检查代码仓库，制定计划，然后循环执行：运行命令、读取结果、修改文件、重新运行测试、查看失败信息、修正问题。这个循环本身就是产品的核心。它更像一个能使用终端的实习生，而不是自动补全工具。

由此带来几个后果。每次迭代都要在不断增长的上下文上完成一次完整生成：一项需要十个步骤的任务，就需要处理十个长提示词。而且，智能体会实际执行操作，而不只是提出建议，因此它的行动范围涵盖一切它能触及的对象——这解释了为什么沙箱属于设计的一部分，而不是一项设置。

#项目在 2026 年的情况：Agent Canvas

OpenHands最初发布时名为OpenDevin，后来才改为现名。该项目仓库由All Hands AI维护，以MIT许可证发布，2026年夏季在GitHub上的星标数超过89,000。项目的定位也有所扩展：它不再仅将自己定位为一个独立的自主智能体，而是“面向编程智能体和自动化任务的自托管控制中心”，能够通过同一个界面控制OpenHands、Claude Code、Codex或Gemini。

具体而言，这套产品已形成多个模块：Agent Canvas（控制界面）、用于构建自定义智能体的 Software Agent SDK、Agent Server，以及用于计划任务的自动化服务器。原有的独立本地界面已被弃用，转而采用这种模块化架构；此处所述本地用法的原理仍然相同——智能体在容器化沙箱中执行操作——但不同旧版文档中的组件名称和启动命令可能有所不同，包括那些至今有时仍以 OpenDevin 名称被索引的文档。

#直说模型要求

有两项能力比基准测试分数更重要：严格按照预期格式调用工具，以及在长上下文中保持稳定，因为智能体在每一步都会重新读取不断增长的历史记录。一个能根据提示词出色地编写函数的模型，在循环运行时却可能根本无法使用。在这类任务中，面向代码的模型通常优于同等规模的对话模型。

项目官方文档在 2026 年调整了推荐：现在建议将 Qwen3.6-35B-A3B 作为首个尝试的本地模型。这是一款专为智能体编程设计的 MoE（混合专家）模型，具有较大的上下文窗口，可通过 LM Studio、Ollama、vLLM 和 SGLang 使用。这里采用 MoE 的优势很直接：虽然总参数量达 350 亿，但每个 token 仅激活 30 亿参数，因此生成速度明显快于规模相近的稠密模型，而显存需求也更接近 14B 模型，而非 35B 稠密模型。

#本地运行

1. 01
   提供模型推理服务

   通过兼容 OpenAI API 的端点提供服务；如果使用 Ollama，应将 OLLAMA_CONTEXT_LENGTH 变量提高到至少 22,000（建议 32,768）。这一步常被跳过，而跳过它会导致智能体忘记自己的计划。
2. 02
   以容器化配置启动应用程序

   它需要一个容器引擎（Docker Desktop 或 Docker Engine）：智能体的 shell 运行在容器内，而不是您的宿主机上。
3. 03
   指向您的本地接入点

   使用一个占位 API 密钥（例如 local-llm），以及一个可从容器内访问的基础 URL——在 Docker Desktop 中，应使用 http://host.docker.internal:PORT/v1，而不是 localhost，因为 localhost 指向的是容器本身。只有当模型确实具备工具调用能力时，才声明支持工具调用。
4. 04
   仅挂载一个仓库

   最好使用一个用完即可丢弃的仓库克隆，并在一个可以放心删除的分支上操作。
5. 05
   从范围小且可验证的任务开始

   修复这个未通过的测试，添加这个参数，更新这项配置。然后再仔细检查 diff。

• 为模型提供支持长上下文的推理服务
• 让本地模型审查代码
• Cline：集成在编辑器中的编程智能体
• 用于搭建本地智能体的 QuelLLM 套件
• 官方文档：在 OpenHands 中使用本地模型
• OpenHands在GitHub上的官方仓库
• OpenHands（2026）独立评测

#任务的真实成本

智能体任务的开销并非一次模型调用，而是一连串调用。由于历史记录不断累积，每次调用的上下文都比前一次更长。对于需要十次迭代的任务，如果每一步平均向历史记录中增加 800 个 token，那么第十次调用甚至还没开始生成回答，就已经要重新读取数千个 token 的上下文。在本地计算时，每一轮读取提示词的时间（即“prefill”）都要加到生成时间上。这也解释了为什么在一个拥有 320 亿个参数的模型上运行的本地智能体，每项任务的耗时要以分钟计算，而不像常规文本补全那样以秒计算。

这就是无需支付 API 账单的代价：成本并没有消失，而是转移到了您的显卡和等待时间上。如果任务定义不清，导致智能体原地打转、反复迭代二十次，那么这种转移后的成本，无论是电费还是时间，很快就会比一次等效的 API 调用更高。

#一个具体示例，以帮助理解

以一个实际任务为例：“test_export_csv 测试从最近一次提交后开始失败，请修复它”。使用 320 亿参数级别的模型时，典型流程需要五到八次迭代：读取测试和失败信息、打开相关源文件、提出原因假设、修改、重新运行测试、读取新结果，并在必要时调整。每次迭代都会重新读取此前所有迭代的完整历史，因此上下文窗口至关重要：如果只有 8,000 个 token，智能体在三四步后就会跟不上思路，再次提出此前已排除的假设。

在 70 亿至 80 亿参数的模型上，同样的任务往往会以另一种方式失败：模型正确识别了测试，但重新运行测试的命令格式不对，或者模型修改了附近另一个名称相似的文件。这些不是设置错误——这是模型处理工具—结果—决策循环所要求的严格格式时的能力上限，无论系统提示词的质量如何。这也解释了为什么已公布的代码补全基准测试分数在这里没有多大预测价值：一个在生成独立函数时得分很高的模型，仍可能无法连贯地完成十次工具调用而不出错，因为这两种能力之间的相关性会随模型训练方式的不同而变化。

#安全性不是可选的

环境中不留任何敏感信息

智能体会读取自身的运行环境，并可能将其显示出来。

一个用完即可丢弃的分支，以及一份用于操作的仓库克隆

切勿使用您那份仍有修改尚未确认的工作副本。

网络访问受限

能够连接任意网络目标的智能体，可以将它读到的所有信息外传。

默认将所有获取的内容视为恶意内容

工单描述或 README 文件中可能包含针对智能体的指令：具体机制详见我们关于提示词注入的指南。

逐一审查每份 diff

« 测试通过 » 表示测试已通过，并不表示修改是正确的。

#什么时候助手比智能体更合适

总而言之，本地运行的 OpenHands 既不是玩具，也不是万能替代品：它适用于能够真正容纳至少 270 亿参数的模型及 32,000 个 token 上下文的机器，以及范围足够明确、只需自动化测试或快速复核就能判断结果的任务。如果硬件达不到这个门槛，打开文件并使用常规对话助手，仍会比一个不断循环却始终无法收敛的智能体更快、更可靠。

#FAQ