1. 先想清楚OpenHands的定位它不是又一个代码补全工具1.1 从聊天生成代码到代理执行任务如果你和我一样过去一年里把各种AI编程工具都试过一圈大概率会有同感补全插件在写样板代码时很顺手聊天助手在解释概念、生成算法片段时也很惊艳但真要让它们把一个功能在项目里做出来基本还是得靠人自己动手。原因很简单——这类工具的产出是文本而软件开发真正耗时间的部分不是把代码想出来而是把代码放进项目里弄对文件放在哪、依赖怎么加、接口怎么接、测试怎么过这些需要在真实环境里反复试错。OpenHands这类代理式工具的出现正是为了补上最后这一公里。它不是一个对话框而是一个能真正进入你工作区的AI软件开发代理你给它一个任务描述它自己读取项目结构、查看代码、修改文件、执行命令、观察输出然后根据结果继续调整直到任务完成或你喊停。换句话说它干的活更像一个坐在你电脑前的实习生而不是一个只出主意的顾问。这一点决定了使用方式上的根本差异。对话式工具的核心操作是提问—复制—粘贴OpenHands的核心操作是下任务—观察—验收。你不再需要把上下文一点点喂给它因为它自己会去翻仓库你也不再需要手动执行它给的每一段代码因为它自己会在沙箱里跑。带来的新问题是你得学会信任边界和验收节奏这正是后面几节要展开的内容。1.2 观察-行动-验证的执行闭环OpenHands的工作方式可以浓缩成一个循环先观察再行动然后验证循环往复。举个例子你就明白了。假设你在一个Python项目里跑测试发现有一个用例挂了任务描述就是帮我修好这个失败的测试。过去用聊天助手你得自己先找出是哪个用例挂了、贴错误信息、然后把它给的补丁粘进去再跑一遍。OpenHands的路径完全不一样它会先进入工作区运行测试命令复现失败读取报错定位到具体文件和函数分析可能的原因修改代码再次运行测试如果通过了它自己知道收尾如果还有问题就继续看新的报错。整个过程中文件是你项目里真实存在的文件命令是你项目真实要跑的命令结果也是真实反馈给它的。这个闭环的意义在于它把生成代码和验证代码这两件事绑在了一起。代码正确与否不再靠人肉确认而是靠运行结果说话。这也是为什么OpenHands在处理修测试补功能排查报错这类有明确可验证结果的任务时特别靠谱因为Agent能自己判断做没做对。理解了这个闭环你就明白人和Agent的职责分工了人负责定义目标、划定边界、提供验收标准Agent负责在边界内想办法执行并自证结果。别指望它替你做产品决策也别事事都替它把步骤想好——那是把Agent当搜索框用浪费了它最强的能力。1.3 什么场景适合交给它什么场景别碰基于我用下来的体会适合交给OpenHands的场景有这些修Bug和修测试报错信息明确、验证方式明确是它的舒适区。实现有清晰需求的功能比如给CLI工具加一个参数把这段逻辑抽成独立的模块。探索陌生仓库让它帮你梳理项目结构、找到某个功能对应的代码位置。机械性改造批量重命名、统一代码风格、补充文档注释、生成单元测试。从零搭脚手架给定技术栈让它创建项目结构并跑通基础流程。不适合的场景也同样明显需求本身就模糊不清的任务Agent大概率会在错误的假设上一路跑远。需要主观审美判断的工作比如把界面做得更有质感没有客观验证标准很难收敛。高风险操作删库、改生产配置、动数据这些天生不该交给自动化工具。超过几个小时的长周期任务受上下文限制中途容易跑偏。下面这张表可以帮你快速判断一个任务该不该丢给它判断维度适合交给Agent建议人工处理目标是否明确有明确验收标准只有模糊方向验证是否客观跑命令、看输出即可需要主观判断改动范围限在特定模块内横跨多个系统风险等级可在沙箱中安全试错动数据、动生产一句话让Agent做能验证的事把要拍板的事留给自己。这个边界守住了OpenHands的效率优势才能发挥出来。2. 部署这关怎么过依赖、镜像与首次启动2.1 前置条件OpenHands的部署核心依赖是容器运行时这一点没得商量因为Agent需要的沙箱环境就是靠容器隔离出来的。你本机得有可用的Docker环境并且确保守护进程在运行。Linux和macOS上问题不大Windows下建议先把WSL2环境配好再谈后续否则文件挂载和Docker socket透传会有很多隐性坑。硬件方面内存建议至少8G16G以上体验会比较从容。原因在于除了主服务本身每次任务还会拉起一个沙箱容器大项目构建依赖时内存占用会明显上涨。CPU方面主流配置都够用真正的算力开销在模型服务那边不在本机。磁盘预留二三十G比较稳妥镜像和依赖缓存都会占空间。网络方面要提前想好两件事一是拉取镜像是否顺畅二是Agent在沙箱里安装依赖时能否访问到你需要的软件源。这两点我在第7节还会展开讲这里先记住一个原则宿主机能稳定访问什么源最好通过环境变量明确透传给沙箱别指望Agent自己碰运气。2.2 启动命令逐行拆解以我常用的一条启动命令为例先看整体docker run -it \ --name openhands \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $HOME/.config/openhands:/home/openhands/.config/openhands \ -v $HOME/workspace:/home/openhands/workspace \ -e LLM_API_KEYsk-你的密钥 \ -e LLM_MODEL你的模型标识 \ ghcr.io/openhands/openhands:main逐行拆开说参数作用说明-p 3000:3000端口映射启动后浏览器访问本机3000端口打开界面-v /var/run/docker.sock挂载Docker socket主服务需要通过它来创建和管理沙箱容器-v .../.config/openhands配置文件挂载让config.toml在容器内外保持一致-v .../workspace工作区挂载Agent能操作的文件目录对应你真实项目所在位置-e LLM_API_KEY模型密钥也可不设进界面后再填-e LLM_MODEL默认模型标识不设则启动后需要手动选择这里最容易忽略的是工作区挂载。容器里的/home/openhands/workspace对应你主机的某个真实目录Agent编辑的文件就是这个目录下的文件。建议单独建一个专门目录给Agent用而不是把整个$HOME挂进去——范围越大Agent误操作的可能面就越大这个习惯越早养成越好。镜像方面有两个概念要分清主服务镜像ghcr.io/openhands/openhands是前端、后端加控制逻辑沙箱运行时镜像则是在任务执行时动态拉起的负责真正跑命令。第一次创建任务时可能会触发沙箱镜像拉取稍等片刻是正常的别以为卡住了。2.3 首次启动后的自检清单服务起来后别急着丢大任务先花两分钟做一轮自检确认环境是通的浏览器打开http://localhost:3000能看到主界面且能正常新建会话。在设置里填入模型API密钥并选择模型确保能发起对话。新建一个会话给一个最简单的任务列出当前工作区里有哪些文件和目录。确认Agent的返回结果确实反映了工作区真实内容而不是猜的。再让它执行一条命令比如运行ls -la并把结果告诉我确认命令执行通道也通。这五步里只要任何一步卡住都说明某个环节没配对——密钥不对、socket没挂好、工作区路径不一致都属于部署期最常见的问题。自检通过之后再上真实任务你会少很多不知道是环境问题还是任务问题的困惑。3. 配置文件里的门道模型接入、工作区与执行上限3.1 配置的加载顺序与config.toml结构OpenHands的配置逻辑是环境变量优先、配置文件兜底、界面设置再叠加。换句话说你既可以在启动命令里用-e传环境变量也可以把所有参数写进一个config.toml两者效果等价但如果同时存在环境变量的优先级更高。建议的做法是密钥这类敏感信息走环境变量其它偏好参数写进配置文件。配置文件默认放在~/.config/openhands/config.toml一份典型的配置长这样[core] # Agent能操作的工作区目录 workspace_dir /home/openhands/workspace # 监听地址和端口 host 0.0.0.0 port 3000 [llm] # 模型标识不同服务商的格式不同按实际填写 model your-provider/your-model # API密钥建议用环境变量注入而不是写死在文件里 api_key sk-xxxxxx # 自定义接口地址使用兼容接口时配置 base_url https://api.example.com/v1 # 建议保持低温减少随机发挥 temperature 0.0 [agent] # 单个任务最大执行步数 max_iterations 100注意不同版本的配置键名会有细微出入以你安装版本的官方示例为准。我这边写的是当前主流版本的结构核心就是core、llm、agent三段。实际踩坑时最常见的错误是改了配置文件但服务没重启或者路径写错导致挂载目录对不上。改完配置一定要重启主服务并看启动日志确认配置被加载了。3.2 模型接入的几种写法接入模型这块是新手最容易懵的地方。简单说OpenHands通过一套统一的接口协议对接模型服务所以无论是大型厂商的托管API、本地部署的开源模型还是各种兼容网关只要能按这套协议提供接口都能接进来。第一种是直接用托管API。这种情况下你只需要填model和api_key接口地址用官方默认的就行export LLM_API_KEYsk-你的密钥 export LLM_MODEL你的模型标识第二种是本地模型服务。如果你的本机或内网机器上跑着一个开源模型服务那就需要指定base_url同时model填成该服务能识别的模型名[llm] model local-model-name api_key no-key-needed base_url http://127.0.0.1:8000/v1这里的api_key往往是占位符因为本地服务一般不做鉴权但协议层要求这个字段存在随便填一个即可。第三种是各类兼容网关或中转服务。很多服务商会提供统一的兼容接口把不同模型都收敛到同一个地址此时写法和第二种一模一样base_url指向网关地址model填写你实际要用的模型标识。好处是以后换模型只需要改model一个字段接口不用动。3.3 工作区范围与执行上限的意义配置里两个参数值得多说两句因为它们直接决定了Agent的活动半径和任务预算。workspace_dir是Agent的工作边界。它只能读写这个目录下的文件这既是功能限制也是安全保护。我见过有人把整个home目录挂进去结果Agent在某次重构时把不相关的配置文件也扫了一遍虽然后来没出大问题但那一刻确实后背发凉。更合理的做法是每个项目一个专用目录任务只针对当前目录展开。max_iterations是单个任务的最大执行步数默认通常是一百。每一步可以是一次文件编辑、一条命令执行或一次信息查询。你可以把它理解成给Agent的预算——任务太复杂、上下文太长、模型来回折腾都会快速消耗步数。步数上限设得太低任务容易半途而废设得太高又可能看着它在一个错误方向上反复打转白白烧token。我的经验是普通小任务用默认值就行大重构任务可以适当调高到150到200但如果一个任务跑到200步还没收敛大概率不是步数不够而是任务描述或模型选型出了问题这时候该做的是停下来重新梳理而不是继续加预算。4. Web界面和CLI两种使用姿势4.1 Web界面看Agent干活比听它汇报重要第一次打开Web界面的人往往会盯着左侧的聊天框把它当聊天机器人用这是最可惜的误用。OpenHands的界面价值在于可观察性——你能看到Agent每一步到底干了什么读哪个文件、改了什么内容、执行了什么命令、输出了什么结果全都有记录。界面上几个核心区域要搞清楚。主对话区是你下达任务和Agent汇报结论的地方但真正的过程信息在操作面板里文件编辑会显示diff命令执行会显示终端输出浏览器操作会有独立的浏览面板。我强烈建议前面几次使用都把Agent的每一步操作点开看一遍不是为了监视而是为了建立它通常怎么干活的直觉。有了这个直觉你才能在它走偏时第一时间发现而不是等它跑完才发现结果完全不对。还有一个实用技巧任务进行中如果发现Agent的理解有偏差不要干等着直接在对话区插话纠正。OpenHands支持在执行过程中接收新的指令你的一句这个文件的路径不对实际在src目录下往往能让它立刻调头省下大量试错成本。4.2 CLI模式适合自动化和批量任务Web界面适合人盯着干CLI则适合把任务交给流程。CLI的使用思路是前端能做的事命令行里都能做而且还能脚本化。比如你想跑一个一次性任务可以直接用类似下面的方式调用openhands start openhands resolve 给CLI工具新增一个--json参数输出JSON格式结果具体命令名称和参数在不同版本有差异先跑openhands --help看当前版本的子命令列表。CLI的优势在无人值守场景你可以把任务写进shell脚本让它在固定时间或特定事件触发时自动开跑甚至可以把执行结果输出到日志文件里事后统一查看。劣势也很明显——观察体验不如Web界面直观中途插入纠正指令也更麻烦。所以我的习惯是需要精细协作的任务用Web界面批量、重复、可标准化的任务用CLI。4.3 会话怎么管理才不乱会话机制值得认真对待。OpenHands的每个会话都是一个独立的上下文环境会话之间不共享Agent的记忆。这意味着两个问题第一跨会话的任务连续性需要你自己维护——新会话里Agent不知道上个会话聊了什么关键背景必须在任务描述里重新交代第二不同会话如果操作同一个工作区可能出现文件状态互相踩踏的情况。我的管理经验就三条。按任务开会话一个会话只解决一件事做完就结束不拖泥带水。工作区隔离并行的会话尽量用不同的工作目录避免同时改同一批文件。善用历史复盘界面里保留着历史会话记录任务结束后花几分钟回看Agent的执行路径能帮你总结出哪些任务描述方式最有效下次直接复用。5. 一次真实任务的完整轨迹复盘5.1 任务背景与验收标准纸上谈兵不如看一次真实执行。我用一个模拟项目X来演示那是一个Python写的命令行工具入口文件cli.py核心逻辑在runner.py带一个简单的参数解析。任务是给它新增一个参数支持输出JSON格式的结果。我来之前明确了验收标准这是整个任务里最重要的一步新增--json参数后程序输出合法JSON原来的默认文本输出格式完全不变相关测试能全部通过改动范围只限参数解析和输出格式化这两块核心计算逻辑不动。把验收标准写清楚再丢任务Agent的路径就非常清晰不会自由发挥。5.2 Agent的执行过程记录我把任务和验收标准一起发给Agent后它的执行路径大致是这样的第一步它不是直接找文件开改而是先列出工作区目录然后读入口文件cli.py和参数解析相关的代码段。这步看着笨其实很关键——它在建立对项目结构的基本认知避免后面改错文件。第二步它定位到参数解析的位置理解了现有参数的定义方式然后在旁边新增了--json选项并把输出格式化的逻辑抽了一个分支。这步的亮点是它复用了现有的输出函数而不是新造一套流程说明它确实读懂了代码结构。第三步它没有直接来汇报而是先运行了测试命令。测试跑挂了原因是它新增分支时有一个变量在特定路径下没定义。这时候它自己读报错信息定位到问题行补上了默认值再次运行测试直到全部通过。第四步它手动运行了一次带--json的命令把输出结果拿给终端验证了一遍确认是合法JSON最后才回来汇报并且附上了改动的文件清单和diff摘要。整条路径走下来大概花了十几分钟过程里有几次小波折但每一步它都能基于实际输出来修正自己没有出现过改了代码但不验证就直接交差的情况。和我预想中一致这也说明只要任务边界清楚、验收标准可执行主流模型驱动的Agent是能稳定完成这类工作的。5.3 人工review时看什么Agent交差不等于任务结束人工review这步必须保留。我的review清单是先看diff确认改动范围有没有越界有没有夹带与需求无关的修改。再看测试确认它报的全部通过是真实跑出来的而不是手动改的测试结果。最后自己手动复现一次验收命令用真实的数据跑一遍确认输出符合预期。这次任务的review里我发现一个问题Agent新增的JSON输出对某个特殊输入值会抛出异常因为那个值在原本的文本输出路径里有防御逻辑而它在JSON分支里漏掉了。这不是大问题我在对话区把场景描述给它说当输入为X时JSON输出应该和文本输出一样返回空结果而不是抛异常它重新改了一版这次就对了。这个例子很典型Agent能覆盖主路径但容易漏边界条件。人工review的价值就在这里——你不需要替它写代码但你需要替它想那些它没想到的输入和场景。把这个人审—返工的循环当成默认流程Agent的产出质量才会真正稳定。6. 进阶玩法约束行为、沉淀规范、接入Git工作流6.1 用任务描述和提示词约束Agent用得越久越发现任务描述的质量直接决定结果质量。同样一个需求两种写法效果天差地别。弱写法是只给目标帮我加个JSON输出功能。这种描述给了Agent太多自由发挥的空间它可能改了接口签名、动了核心逻辑甚至重写了整个输出模块。强写法则包含四个要素目标、约束、验收、禁区。比如目标新增--json参数输出JSON格式结果。约束只改参数解析和输出格式化相关代码保持核心计算逻辑不变。验收运行python cli.py --json输出合法JSON运行现有测试全部通过默认文本输出格式不变。禁区不要修改依赖文件不要动测试用例本身。这套写法本质上是把验收标准前置。Agent在执行时有了明确的自检依据它会在每个阶段拿这些标准对照自己的产出而不是埋头做到哪算哪。我用这个模板之后任务返工率下降了不止一半。6.2 Microagents把团队规范写成Agent能自动遵守的指令如果团队里多个开发者都在用OpenHands光靠每个人口头强调规范是不够的最好的做法是把规范固化到项目仓库里让Agent每次一进入工作区就自动读到。OpenHands的Microagents机制干的就是这件事。在项目根目录下建一个.openhands/microagents/目录里面放Markdown文件每个文件定义一类场景下的行为约束。文件头部写元信息正文写具体指令。比如test-rules.md可以约定所有改动必须运行标准测试命令测试命令是pytest tests/新增功能必须同时补测试。又比如commit-rules.md可以约定提交信息必须遵循规定格式提交前必须先运行lint。这个机制的价值在于Agent的指令不再是临时的而是跟着仓库走的。新成员clone项目后哪怕完全不熟悉团队约定交给OpenHands干活的产出也会自动符合规范。我甚至见过有团队把代码风格指南、目录结构约定、禁用API列表都写进了Microagents效果相当好。它相当于给Agent发了一本项目员工手册。6.3 对接Git工作流从Issue到分支再到合并请求再往上一个层级OpenHands可以和Git平台的工作流打通。典型节奏是你在平台上建一个任务单描述清楚需求和验收标准让Agent基于当前主线拉一个新分支在这个分支上完成改动并提交最后提交合并请求由人工进行code review。这个流程把Agent的产出纳入了正规的代码评审管道既享受了自动化效率又保留了人工把关环节。实际执行时要注意分支隔离很重要不要让Agent直接在主分支上乱改合并请求的描述要让它写清楚改动内容和验证结果方便review的人快速把握。人机协作的节奏应该是人负责分解任务、写清楚验收标准Agent负责干活和自证review的人负责挑刺和拍板。三个角色各司其职效率和安全才都能保住。我自己现在处理小到中型的改动基本都是这个流程需要人的不再是写代码本身而是判断这件事该不该做、做成什么样算好。7. 用顺手之后仍然绕不开的坑与排查思路7.1 沙箱里装依赖失败这个坑几乎人人会遇到。现象是Agent在宿主机上跑得好好的一进沙箱执行pip install就超时或者连不上软件源。原因在于沙箱是一个相对干净的环境网络策略和软件源配置不继承宿主机的设置。排查思路很简单先确认是不是网络问题——在沙箱里手动执行一次带--timeout和详细日志的安装命令看报错是DNS解析失败、连接超时还是403。确认是软件源不可达之后解决办法是把宿主机上可用的镜像源通过环境变量透传给沙箱比如docker run ... \ -e PIP_INDEX_URLhttps://你的镜像源地址/simple \ -e PIP_TRUSTED_HOST你的镜像源主机 \ ...这类环境变量在容器启动时就注入Agent在沙箱里执行安装命令时会自动读取。要特别提醒的是如果你改挂了新的环境变量一定要重启主服务再开新会话否则Agent拿到的还是旧配置。我当时就在这个细节上卡了近一个小时以为是镜像地址写错其实是服务没重启。7.2 做一半失忆上下文失控用OpenHands处理稍微大一点的任务时会遇到一个让人恼火的现象任务做到一半Agent开始不记得前面确定过的决策比如忘掉了某个文件路径、忘掉了之前排除过的方案甚至开始重复修改同一块代码。本质原因是上下文窗口有上限Agent的注意力被后续的大量日志和中间过程冲淡了。经验之谈三个应对策略最有效。第一把任务拆小一个大任务拆成几个有明确验收节点的小任务每个小任务新开一个会话。第二步把关键背景写进每个会话的任务描述开头不要指望Agent记得上个会话的事。第三在任务描述里主动要求它每完成一步先总结当前状态再继续下一步这能强制它把重要信息压缩进上下文的前部减少遗忘概率。还有一个判断标准如果任务执行步数已经过半但Agent还在探索阶段没开始动手改代码基本可以断定这个任务对它来说太大了应该停下来重新拆解而不是让它继续烧步数。7.3 模型强弱直接决定任务成败同一个任务用弱模型和强模型跑体验可能是天壤之别。弱模型在简单任务上没问题但一到需要多步推理、跨文件定位问题的场景就容易出现看起来很忙但方向全错的情况——读了一堆文件改了一堆代码结果越改越乱。强模型则更善于从全局理解项目结构少走弯路。这不是说弱模型不能用而是要对任务难度有清醒预期。处理简单脚本、写文档、做格式化这类任务弱模型够用且成本低。处理复杂仓库、多模块联调、疑难Bug排查这类任务老老实实上强模型。我自己的对比方法是同一个任务准备两个模型各跑一遍对比执行步数和结果质量几次之后心里就有数了哪些任务该用什么级别的模型一清二楚。7.4 Token消耗与成本控制经验Agent式工具的Token消耗比普通对话高出不少因为它要读文件、跑命令、看输出每一步都是成本。很多人第一次用完看账单会吓一跳这是正常现象但可以通过使用习惯来控制。我的成本控制经验就三条。第一控制工作区范围工作区里不要放无关文件Agent扫目录时就不会浪费Token在无关内容上。第二给足约束任务描述里写清楚只看哪些目录、不改哪些文件减少无效探索。第三及时验收止损任务目标达成后就停止别让它顺手优化别的——Agent的主动延伸常常是成本的无声黑洞。另外多轮人审—返工虽然看着麻烦但相比让Agent一口气闷头跑到底多数情况下反而更省。因为返工通常只针对局部修正而长跑失控后的清理成本往往是灾难级的。最后分享一个我个人的使用习惯凡是让OpenHands动手的任务我都会在任务描述末尾加一句完成后请列出所有改动文件清单和运行过的命令。这句话成本几乎为零但每次review时都能省大量时间——你不需要从头到尾翻执行日志只看清单就能快速定位到关键改动。用了这么久我最大的体会是OpenHands不是替你思考的工具而是替你把思考变成现实的手段思考这件事始终还得你自己来。
1. 先想清楚OpenHands的定位它不是又一个代码补全工具1.1 从聊天生成代码到代理执行任务如果你和我一样过去一年里把各种AI编程工具都试过一圈大概率会有同感补全插件在写样板代码时很顺手聊天助手在解释概念、生成算法片段时也很惊艳但真要让它们把一个功能在项目里做出来基本还是得靠人自己动手。原因很简单——这类工具的产出是文本而软件开发真正耗时间的部分不是把代码想出来而是把代码放进项目里弄对文件放在哪、依赖怎么加、接口怎么接、测试怎么过这些需要在真实环境里反复试错。OpenHands这类代理式工具的出现正是为了补上最后这一公里。它不是一个对话框而是一个能真正进入你工作区的AI软件开发代理你给它一个任务描述它自己读取项目结构、查看代码、修改文件、执行命令、观察输出然后根据结果继续调整直到任务完成或你喊停。换句话说它干的活更像一个坐在你电脑前的实习生而不是一个只出主意的顾问。这一点决定了使用方式上的根本差异。对话式工具的核心操作是提问—复制—粘贴OpenHands的核心操作是下任务—观察—验收。你不再需要把上下文一点点喂给它因为它自己会去翻仓库你也不再需要手动执行它给的每一段代码因为它自己会在沙箱里跑。带来的新问题是你得学会信任边界和验收节奏这正是后面几节要展开的内容。1.2 观察-行动-验证的执行闭环OpenHands的工作方式可以浓缩成一个循环先观察再行动然后验证循环往复。举个例子你就明白了。假设你在一个Python项目里跑测试发现有一个用例挂了任务描述就是帮我修好这个失败的测试。过去用聊天助手你得自己先找出是哪个用例挂了、贴错误信息、然后把它给的补丁粘进去再跑一遍。OpenHands的路径完全不一样它会先进入工作区运行测试命令复现失败读取报错定位到具体文件和函数分析可能的原因修改代码再次运行测试如果通过了它自己知道收尾如果还有问题就继续看新的报错。整个过程中文件是你项目里真实存在的文件命令是你项目真实要跑的命令结果也是真实反馈给它的。这个闭环的意义在于它把生成代码和验证代码这两件事绑在了一起。代码正确与否不再靠人肉确认而是靠运行结果说话。这也是为什么OpenHands在处理修测试补功能排查报错这类有明确可验证结果的任务时特别靠谱因为Agent能自己判断做没做对。理解了这个闭环你就明白人和Agent的职责分工了人负责定义目标、划定边界、提供验收标准Agent负责在边界内想办法执行并自证结果。别指望它替你做产品决策也别事事都替它把步骤想好——那是把Agent当搜索框用浪费了它最强的能力。1.3 什么场景适合交给它什么场景别碰基于我用下来的体会适合交给OpenHands的场景有这些修Bug和修测试报错信息明确、验证方式明确是它的舒适区。实现有清晰需求的功能比如给CLI工具加一个参数把这段逻辑抽成独立的模块。探索陌生仓库让它帮你梳理项目结构、找到某个功能对应的代码位置。机械性改造批量重命名、统一代码风格、补充文档注释、生成单元测试。从零搭脚手架给定技术栈让它创建项目结构并跑通基础流程。不适合的场景也同样明显需求本身就模糊不清的任务Agent大概率会在错误的假设上一路跑远。需要主观审美判断的工作比如把界面做得更有质感没有客观验证标准很难收敛。高风险操作删库、改生产配置、动数据这些天生不该交给自动化工具。超过几个小时的长周期任务受上下文限制中途容易跑偏。下面这张表可以帮你快速判断一个任务该不该丢给它判断维度适合交给Agent建议人工处理目标是否明确有明确验收标准只有模糊方向验证是否客观跑命令、看输出即可需要主观判断改动范围限在特定模块内横跨多个系统风险等级可在沙箱中安全试错动数据、动生产一句话让Agent做能验证的事把要拍板的事留给自己。这个边界守住了OpenHands的效率优势才能发挥出来。2. 部署这关怎么过依赖、镜像与首次启动2.1 前置条件OpenHands的部署核心依赖是容器运行时这一点没得商量因为Agent需要的沙箱环境就是靠容器隔离出来的。你本机得有可用的Docker环境并且确保守护进程在运行。Linux和macOS上问题不大Windows下建议先把WSL2环境配好再谈后续否则文件挂载和Docker socket透传会有很多隐性坑。硬件方面内存建议至少8G16G以上体验会比较从容。原因在于除了主服务本身每次任务还会拉起一个沙箱容器大项目构建依赖时内存占用会明显上涨。CPU方面主流配置都够用真正的算力开销在模型服务那边不在本机。磁盘预留二三十G比较稳妥镜像和依赖缓存都会占空间。网络方面要提前想好两件事一是拉取镜像是否顺畅二是Agent在沙箱里安装依赖时能否访问到你需要的软件源。这两点我在第7节还会展开讲这里先记住一个原则宿主机能稳定访问什么源最好通过环境变量明确透传给沙箱别指望Agent自己碰运气。2.2 启动命令逐行拆解以我常用的一条启动命令为例先看整体docker run -it \ --name openhands \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $HOME/.config/openhands:/home/openhands/.config/openhands \ -v $HOME/workspace:/home/openhands/workspace \ -e LLM_API_KEYsk-你的密钥 \ -e LLM_MODEL你的模型标识 \ ghcr.io/openhands/openhands:main逐行拆开说参数作用说明-p 3000:3000端口映射启动后浏览器访问本机3000端口打开界面-v /var/run/docker.sock挂载Docker socket主服务需要通过它来创建和管理沙箱容器-v .../.config/openhands配置文件挂载让config.toml在容器内外保持一致-v .../workspace工作区挂载Agent能操作的文件目录对应你真实项目所在位置-e LLM_API_KEY模型密钥也可不设进界面后再填-e LLM_MODEL默认模型标识不设则启动后需要手动选择这里最容易忽略的是工作区挂载。容器里的/home/openhands/workspace对应你主机的某个真实目录Agent编辑的文件就是这个目录下的文件。建议单独建一个专门目录给Agent用而不是把整个$HOME挂进去——范围越大Agent误操作的可能面就越大这个习惯越早养成越好。镜像方面有两个概念要分清主服务镜像ghcr.io/openhands/openhands是前端、后端加控制逻辑沙箱运行时镜像则是在任务执行时动态拉起的负责真正跑命令。第一次创建任务时可能会触发沙箱镜像拉取稍等片刻是正常的别以为卡住了。2.3 首次启动后的自检清单服务起来后别急着丢大任务先花两分钟做一轮自检确认环境是通的浏览器打开http://localhost:3000能看到主界面且能正常新建会话。在设置里填入模型API密钥并选择模型确保能发起对话。新建一个会话给一个最简单的任务列出当前工作区里有哪些文件和目录。确认Agent的返回结果确实反映了工作区真实内容而不是猜的。再让它执行一条命令比如运行ls -la并把结果告诉我确认命令执行通道也通。这五步里只要任何一步卡住都说明某个环节没配对——密钥不对、socket没挂好、工作区路径不一致都属于部署期最常见的问题。自检通过之后再上真实任务你会少很多不知道是环境问题还是任务问题的困惑。3. 配置文件里的门道模型接入、工作区与执行上限3.1 配置的加载顺序与config.toml结构OpenHands的配置逻辑是环境变量优先、配置文件兜底、界面设置再叠加。换句话说你既可以在启动命令里用-e传环境变量也可以把所有参数写进一个config.toml两者效果等价但如果同时存在环境变量的优先级更高。建议的做法是密钥这类敏感信息走环境变量其它偏好参数写进配置文件。配置文件默认放在~/.config/openhands/config.toml一份典型的配置长这样[core] # Agent能操作的工作区目录 workspace_dir /home/openhands/workspace # 监听地址和端口 host 0.0.0.0 port 3000 [llm] # 模型标识不同服务商的格式不同按实际填写 model your-provider/your-model # API密钥建议用环境变量注入而不是写死在文件里 api_key sk-xxxxxx # 自定义接口地址使用兼容接口时配置 base_url https://api.example.com/v1 # 建议保持低温减少随机发挥 temperature 0.0 [agent] # 单个任务最大执行步数 max_iterations 100注意不同版本的配置键名会有细微出入以你安装版本的官方示例为准。我这边写的是当前主流版本的结构核心就是core、llm、agent三段。实际踩坑时最常见的错误是改了配置文件但服务没重启或者路径写错导致挂载目录对不上。改完配置一定要重启主服务并看启动日志确认配置被加载了。3.2 模型接入的几种写法接入模型这块是新手最容易懵的地方。简单说OpenHands通过一套统一的接口协议对接模型服务所以无论是大型厂商的托管API、本地部署的开源模型还是各种兼容网关只要能按这套协议提供接口都能接进来。第一种是直接用托管API。这种情况下你只需要填model和api_key接口地址用官方默认的就行export LLM_API_KEYsk-你的密钥 export LLM_MODEL你的模型标识第二种是本地模型服务。如果你的本机或内网机器上跑着一个开源模型服务那就需要指定base_url同时model填成该服务能识别的模型名[llm] model local-model-name api_key no-key-needed base_url http://127.0.0.1:8000/v1这里的api_key往往是占位符因为本地服务一般不做鉴权但协议层要求这个字段存在随便填一个即可。第三种是各类兼容网关或中转服务。很多服务商会提供统一的兼容接口把不同模型都收敛到同一个地址此时写法和第二种一模一样base_url指向网关地址model填写你实际要用的模型标识。好处是以后换模型只需要改model一个字段接口不用动。3.3 工作区范围与执行上限的意义配置里两个参数值得多说两句因为它们直接决定了Agent的活动半径和任务预算。workspace_dir是Agent的工作边界。它只能读写这个目录下的文件这既是功能限制也是安全保护。我见过有人把整个home目录挂进去结果Agent在某次重构时把不相关的配置文件也扫了一遍虽然后来没出大问题但那一刻确实后背发凉。更合理的做法是每个项目一个专用目录任务只针对当前目录展开。max_iterations是单个任务的最大执行步数默认通常是一百。每一步可以是一次文件编辑、一条命令执行或一次信息查询。你可以把它理解成给Agent的预算——任务太复杂、上下文太长、模型来回折腾都会快速消耗步数。步数上限设得太低任务容易半途而废设得太高又可能看着它在一个错误方向上反复打转白白烧token。我的经验是普通小任务用默认值就行大重构任务可以适当调高到150到200但如果一个任务跑到200步还没收敛大概率不是步数不够而是任务描述或模型选型出了问题这时候该做的是停下来重新梳理而不是继续加预算。4. Web界面和CLI两种使用姿势4.1 Web界面看Agent干活比听它汇报重要第一次打开Web界面的人往往会盯着左侧的聊天框把它当聊天机器人用这是最可惜的误用。OpenHands的界面价值在于可观察性——你能看到Agent每一步到底干了什么读哪个文件、改了什么内容、执行了什么命令、输出了什么结果全都有记录。界面上几个核心区域要搞清楚。主对话区是你下达任务和Agent汇报结论的地方但真正的过程信息在操作面板里文件编辑会显示diff命令执行会显示终端输出浏览器操作会有独立的浏览面板。我强烈建议前面几次使用都把Agent的每一步操作点开看一遍不是为了监视而是为了建立它通常怎么干活的直觉。有了这个直觉你才能在它走偏时第一时间发现而不是等它跑完才发现结果完全不对。还有一个实用技巧任务进行中如果发现Agent的理解有偏差不要干等着直接在对话区插话纠正。OpenHands支持在执行过程中接收新的指令你的一句这个文件的路径不对实际在src目录下往往能让它立刻调头省下大量试错成本。4.2 CLI模式适合自动化和批量任务Web界面适合人盯着干CLI则适合把任务交给流程。CLI的使用思路是前端能做的事命令行里都能做而且还能脚本化。比如你想跑一个一次性任务可以直接用类似下面的方式调用openhands start openhands resolve 给CLI工具新增一个--json参数输出JSON格式结果具体命令名称和参数在不同版本有差异先跑openhands --help看当前版本的子命令列表。CLI的优势在无人值守场景你可以把任务写进shell脚本让它在固定时间或特定事件触发时自动开跑甚至可以把执行结果输出到日志文件里事后统一查看。劣势也很明显——观察体验不如Web界面直观中途插入纠正指令也更麻烦。所以我的习惯是需要精细协作的任务用Web界面批量、重复、可标准化的任务用CLI。4.3 会话怎么管理才不乱会话机制值得认真对待。OpenHands的每个会话都是一个独立的上下文环境会话之间不共享Agent的记忆。这意味着两个问题第一跨会话的任务连续性需要你自己维护——新会话里Agent不知道上个会话聊了什么关键背景必须在任务描述里重新交代第二不同会话如果操作同一个工作区可能出现文件状态互相踩踏的情况。我的管理经验就三条。按任务开会话一个会话只解决一件事做完就结束不拖泥带水。工作区隔离并行的会话尽量用不同的工作目录避免同时改同一批文件。善用历史复盘界面里保留着历史会话记录任务结束后花几分钟回看Agent的执行路径能帮你总结出哪些任务描述方式最有效下次直接复用。5. 一次真实任务的完整轨迹复盘5.1 任务背景与验收标准纸上谈兵不如看一次真实执行。我用一个模拟项目X来演示那是一个Python写的命令行工具入口文件cli.py核心逻辑在runner.py带一个简单的参数解析。任务是给它新增一个参数支持输出JSON格式的结果。我来之前明确了验收标准这是整个任务里最重要的一步新增--json参数后程序输出合法JSON原来的默认文本输出格式完全不变相关测试能全部通过改动范围只限参数解析和输出格式化这两块核心计算逻辑不动。把验收标准写清楚再丢任务Agent的路径就非常清晰不会自由发挥。5.2 Agent的执行过程记录我把任务和验收标准一起发给Agent后它的执行路径大致是这样的第一步它不是直接找文件开改而是先列出工作区目录然后读入口文件cli.py和参数解析相关的代码段。这步看着笨其实很关键——它在建立对项目结构的基本认知避免后面改错文件。第二步它定位到参数解析的位置理解了现有参数的定义方式然后在旁边新增了--json选项并把输出格式化的逻辑抽了一个分支。这步的亮点是它复用了现有的输出函数而不是新造一套流程说明它确实读懂了代码结构。第三步它没有直接来汇报而是先运行了测试命令。测试跑挂了原因是它新增分支时有一个变量在特定路径下没定义。这时候它自己读报错信息定位到问题行补上了默认值再次运行测试直到全部通过。第四步它手动运行了一次带--json的命令把输出结果拿给终端验证了一遍确认是合法JSON最后才回来汇报并且附上了改动的文件清单和diff摘要。整条路径走下来大概花了十几分钟过程里有几次小波折但每一步它都能基于实际输出来修正自己没有出现过改了代码但不验证就直接交差的情况。和我预想中一致这也说明只要任务边界清楚、验收标准可执行主流模型驱动的Agent是能稳定完成这类工作的。5.3 人工review时看什么Agent交差不等于任务结束人工review这步必须保留。我的review清单是先看diff确认改动范围有没有越界有没有夹带与需求无关的修改。再看测试确认它报的全部通过是真实跑出来的而不是手动改的测试结果。最后自己手动复现一次验收命令用真实的数据跑一遍确认输出符合预期。这次任务的review里我发现一个问题Agent新增的JSON输出对某个特殊输入值会抛出异常因为那个值在原本的文本输出路径里有防御逻辑而它在JSON分支里漏掉了。这不是大问题我在对话区把场景描述给它说当输入为X时JSON输出应该和文本输出一样返回空结果而不是抛异常它重新改了一版这次就对了。这个例子很典型Agent能覆盖主路径但容易漏边界条件。人工review的价值就在这里——你不需要替它写代码但你需要替它想那些它没想到的输入和场景。把这个人审—返工的循环当成默认流程Agent的产出质量才会真正稳定。6. 进阶玩法约束行为、沉淀规范、接入Git工作流6.1 用任务描述和提示词约束Agent用得越久越发现任务描述的质量直接决定结果质量。同样一个需求两种写法效果天差地别。弱写法是只给目标帮我加个JSON输出功能。这种描述给了Agent太多自由发挥的空间它可能改了接口签名、动了核心逻辑甚至重写了整个输出模块。强写法则包含四个要素目标、约束、验收、禁区。比如目标新增--json参数输出JSON格式结果。约束只改参数解析和输出格式化相关代码保持核心计算逻辑不变。验收运行python cli.py --json输出合法JSON运行现有测试全部通过默认文本输出格式不变。禁区不要修改依赖文件不要动测试用例本身。这套写法本质上是把验收标准前置。Agent在执行时有了明确的自检依据它会在每个阶段拿这些标准对照自己的产出而不是埋头做到哪算哪。我用这个模板之后任务返工率下降了不止一半。6.2 Microagents把团队规范写成Agent能自动遵守的指令如果团队里多个开发者都在用OpenHands光靠每个人口头强调规范是不够的最好的做法是把规范固化到项目仓库里让Agent每次一进入工作区就自动读到。OpenHands的Microagents机制干的就是这件事。在项目根目录下建一个.openhands/microagents/目录里面放Markdown文件每个文件定义一类场景下的行为约束。文件头部写元信息正文写具体指令。比如test-rules.md可以约定所有改动必须运行标准测试命令测试命令是pytest tests/新增功能必须同时补测试。又比如commit-rules.md可以约定提交信息必须遵循规定格式提交前必须先运行lint。这个机制的价值在于Agent的指令不再是临时的而是跟着仓库走的。新成员clone项目后哪怕完全不熟悉团队约定交给OpenHands干活的产出也会自动符合规范。我甚至见过有团队把代码风格指南、目录结构约定、禁用API列表都写进了Microagents效果相当好。它相当于给Agent发了一本项目员工手册。6.3 对接Git工作流从Issue到分支再到合并请求再往上一个层级OpenHands可以和Git平台的工作流打通。典型节奏是你在平台上建一个任务单描述清楚需求和验收标准让Agent基于当前主线拉一个新分支在这个分支上完成改动并提交最后提交合并请求由人工进行code review。这个流程把Agent的产出纳入了正规的代码评审管道既享受了自动化效率又保留了人工把关环节。实际执行时要注意分支隔离很重要不要让Agent直接在主分支上乱改合并请求的描述要让它写清楚改动内容和验证结果方便review的人快速把握。人机协作的节奏应该是人负责分解任务、写清楚验收标准Agent负责干活和自证review的人负责挑刺和拍板。三个角色各司其职效率和安全才都能保住。我自己现在处理小到中型的改动基本都是这个流程需要人的不再是写代码本身而是判断这件事该不该做、做成什么样算好。7. 用顺手之后仍然绕不开的坑与排查思路7.1 沙箱里装依赖失败这个坑几乎人人会遇到。现象是Agent在宿主机上跑得好好的一进沙箱执行pip install就超时或者连不上软件源。原因在于沙箱是一个相对干净的环境网络策略和软件源配置不继承宿主机的设置。排查思路很简单先确认是不是网络问题——在沙箱里手动执行一次带--timeout和详细日志的安装命令看报错是DNS解析失败、连接超时还是403。确认是软件源不可达之后解决办法是把宿主机上可用的镜像源通过环境变量透传给沙箱比如docker run ... \ -e PIP_INDEX_URLhttps://你的镜像源地址/simple \ -e PIP_TRUSTED_HOST你的镜像源主机 \ ...这类环境变量在容器启动时就注入Agent在沙箱里执行安装命令时会自动读取。要特别提醒的是如果你改挂了新的环境变量一定要重启主服务再开新会话否则Agent拿到的还是旧配置。我当时就在这个细节上卡了近一个小时以为是镜像地址写错其实是服务没重启。7.2 做一半失忆上下文失控用OpenHands处理稍微大一点的任务时会遇到一个让人恼火的现象任务做到一半Agent开始不记得前面确定过的决策比如忘掉了某个文件路径、忘掉了之前排除过的方案甚至开始重复修改同一块代码。本质原因是上下文窗口有上限Agent的注意力被后续的大量日志和中间过程冲淡了。经验之谈三个应对策略最有效。第一把任务拆小一个大任务拆成几个有明确验收节点的小任务每个小任务新开一个会话。第二步把关键背景写进每个会话的任务描述开头不要指望Agent记得上个会话的事。第三在任务描述里主动要求它每完成一步先总结当前状态再继续下一步这能强制它把重要信息压缩进上下文的前部减少遗忘概率。还有一个判断标准如果任务执行步数已经过半但Agent还在探索阶段没开始动手改代码基本可以断定这个任务对它来说太大了应该停下来重新拆解而不是让它继续烧步数。7.3 模型强弱直接决定任务成败同一个任务用弱模型和强模型跑体验可能是天壤之别。弱模型在简单任务上没问题但一到需要多步推理、跨文件定位问题的场景就容易出现看起来很忙但方向全错的情况——读了一堆文件改了一堆代码结果越改越乱。强模型则更善于从全局理解项目结构少走弯路。这不是说弱模型不能用而是要对任务难度有清醒预期。处理简单脚本、写文档、做格式化这类任务弱模型够用且成本低。处理复杂仓库、多模块联调、疑难Bug排查这类任务老老实实上强模型。我自己的对比方法是同一个任务准备两个模型各跑一遍对比执行步数和结果质量几次之后心里就有数了哪些任务该用什么级别的模型一清二楚。7.4 Token消耗与成本控制经验Agent式工具的Token消耗比普通对话高出不少因为它要读文件、跑命令、看输出每一步都是成本。很多人第一次用完看账单会吓一跳这是正常现象但可以通过使用习惯来控制。我的成本控制经验就三条。第一控制工作区范围工作区里不要放无关文件Agent扫目录时就不会浪费Token在无关内容上。第二给足约束任务描述里写清楚只看哪些目录、不改哪些文件减少无效探索。第三及时验收止损任务目标达成后就停止别让它顺手优化别的——Agent的主动延伸常常是成本的无声黑洞。另外多轮人审—返工虽然看着麻烦但相比让Agent一口气闷头跑到底多数情况下反而更省。因为返工通常只针对局部修正而长跑失控后的清理成本往往是灾难级的。最后分享一个我个人的使用习惯凡是让OpenHands动手的任务我都会在任务描述末尾加一句完成后请列出所有改动文件清单和运行过的命令。这句话成本几乎为零但每次review时都能省大量时间——你不需要从头到尾翻执行日志只看清单就能快速定位到关键改动。用了这么久我最大的体会是OpenHands不是替你思考的工具而是替你把思考变成现实的手段思考这件事始终还得你自己来。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
