当前可见 60% 的内容

第一章：开源界的“凤凰涅槃” —— 揭秘 OpenHands 的重构始末

大家好，我是无忆研习社（www.wuyi.wiki）的站长莫潇羽。

今天我们要聊的，是一个在 GitHub 上引发了巨大轰动的开源项目。如果你关注 AI 编程领域，你一定听说过 OpenDevin，也就是现在更名为 OpenHands 的项目。

就在前不久，这个拥有超过 6.4 万颗 Star（星标）的超级开源项目，做出了一个令所有人都瞠目结舌的决定——“推倒重来”。

是的，你没有听错。在软件工程领域，尤其是对于一个已经如此成功、拥有庞大用户群体的项目来说，全面重构（Refactoring）往往被视为“禁忌”。因为这意味着要暂停新功能的开发，要冒着引入新 Bug 的风险，甚至可能因为改动过大而导致社区的分裂。但是，OpenHands 的核心团队不仅做了，而且做得非常彻底。

这不仅仅是一次代码的更新，更像是一次 AI 程序员的“进化”。从最初的混乱无序，到现在的井井有条，OpenHands 的重构之路，其实就是 AI Agent 技术发展的一个缩影。

在本篇万字长文中，莫潇羽将带大家深入挖掘 OpenHands 重构背后的技术内幕。我们将剥开它华丽的外衣，去看看它的骨架、它的血液，以及它是如何通过这次“换血”手术，从一个略显笨拙的实验品，进化成一个强大、安全、高效的 AI 编程专家的。

无论你是资深的软件工程师，还是对 AI 技术充满好奇的技术爱好者，甚至是刚刚入门的小白，这篇文章都将为你揭开 AI Agent 系统设计的神秘面纱。

1.1 什么是 OpenHands？

在深入技术细节之前，我们先来给不熟悉的朋友做一个简单的科普。

OpenHands（原名 OpenDevin）是一个开源的 AI 软件工程师平台。简单来说，它就像是你雇佣的一个不知疲倦的、精通编程的数字化员工。

你可以给它下达指令，比如：“帮我写一个贪吃蛇游戏”、“帮我分析一下这个 GitHub 仓库的代码结构”，或者“帮我修复这个 Python 脚本里的 Bug”。

OpenHands 接到指令后，会通过以下步骤来工作：

观察（Observe）：它会像人类一样，查看当前的文件目录，阅读代码文件。
思考（Think）：利用接入的大语言模型（如 GPT-4, Claude 3.5 Sonnet 等）的大脑，分析任务需求，规划解决方案。
行动（Act）：它可以在一个安全的沙箱环境（Sandbox）中执行 Shell 命令，运行代码，甚至通过浏览器查阅资料。
循环（Loop）：如果遇到错误，它会根据报错信息自我修正，直到任务完成。

这就是一个典型的 AI Agent（智能体） 的工作流。而 OpenHands 则是目前开源社区中，在这个领域做得最出色、最活跃的项目之一。

1.2 为什么在这个时候选择“推倒重来”？

很多人可能会问：“既然已经有 6.4 万 Star 了，说明大家觉得挺好用的啊，为什么非要折腾呢？”

这就涉及到了软件开发中一个永恒的话题——技术债（Technical Debt）。

在 OpenDevin 刚刚诞生的时候，那是 AI 编程工具爆发的前夜。为了抢占先机，为了快速验证想法，团队的代码往往是“快”字当头。功能堆叠得非常快，今天加一个“网页浏览”功能，明天加一个“多文件编辑”功能。

这种快速迭代带来了早期的繁荣，但也埋下了深深的隐患。随着功能的增加，代码库变得越来越庞大，越来越难以维护。就像是一个原本只设计了一层的平房，硬生生被加盖到了十层楼，地基开始摇晃，墙壁开始出现裂缝。

莫潇羽在分析旧版本代码时，发现了几个明显的迹象：

牵一发而动全身：修改一个小小的 UI 逻辑，可能会导致后端的某个 Agent 逻辑崩溃。
调试如噩梦：当 Agent 陷入死循环或者报错时，开发者很难追踪到具体是哪一步出了问题，日志混乱不堪。
新人的叹息：想参与贡献的新开发者，面对复杂的代码逻辑，往往望而却步。

如果不进行重构，OpenHands 可能会止步于一个“有趣的玩具”，而无法成为真正的“生产力工具”。

于是，核心团队痛定思痛，决定进行一次彻底的“手术”。这次手术的目标不仅仅是修修补补，而是从架构层面进行重新的设计和定义。

1.3 本文的旅程

在接下来的章节中，我们将沿着 OpenHands 重构的轨迹，一起探索：

旧版本的四大致命伤：到底是什么阻碍了它的发展？
新架构的四大核心原则：什么样的设计才是好的 Agent 架构？
模块化与事件流：这是本次重构的技术灵魂，也是我们要重点剖析的部分。
实战与部署：莫潇羽将手把手教你在本地运行这个强大的工具。
未来展望：AI 程序员最终会取代人类吗？

请系好安全带，我们的 OpenHands 源码深度解析之旅，现在正式开始。

注：本文所有技术分析基于 OpenHands 最新开源代码及官方技术文档，旨在技术交流与分享。转载请注明出处：莫潇羽 @ 无忆研习社 (www.wuyi.wiki)

1.4 进化史：一个 AI 程序员的成长日记

OpenHands 的故事，其实就是 AI 编程技术发展的一个缩影。

莫潇羽整理了 OpenHands 几个关键版本的里程碑，让我们看看它是如何一步步长大的。

v0.1 - 混沌初开 (2024年初)

状态：原型机。
能力：只能进行简单的对话，偶尔能写出 Hello World。
特征：代码全部堆在一个文件里，甚至没有沙箱，直接在宿主机裸奔。

v0.3 - 探索期 (2024年中)

状态：引入 Docker 沙箱。
能力：开始具备文件读写能力，可以完成简单的 Python 脚本任务。
痛点：极其不稳定，经常出现 Agent 死循环或者沙箱无法启动的问题。

v0.6 - 转折点 (2024年末)

事件："The Great Refactor" (大重构) 开始。
改变：引入了 Event Stream 架构，前后端分离。
意义：虽然功能暂时减少了，但地基打牢了。这是 OpenHands 真正成为“生产力工具”的起点。

v0.9 - 成熟期 (现在)

状态：功能完备，性能强悍。
能力：支持多语言、多 Agent 协作、可视化浏览器操作。
标志：可以在 5 分钟内完成一个 Django 项目的升级，或者从零构建一个 React 网站。

回顾这段历史，我们不难发现：好的软件不是写出来的，而是“长”出来的。 OpenHands 的每一次迭代，都是对 AI 能力边界的一次探索。

第二章：旧版本的至暗时刻 —— 四大致命痛点深度剖析

在软件工程中，所有的重构都不是心血来潮。对于 OpenHands 来说，旧版本（v0.x）虽然积累了人气，但其内部的“技术债”已经到了崩溃边缘。

莫潇羽回顾 Commit 历史时发现，旧版本面临着四个足以扼杀项目的“致命问题”。

2.1 痛点一：架构的“意大利面条” (Spaghetti Code)

首要问题是紧耦合（Tight Coupling）。

在旧版本中，代码逻辑纠缠不清。想增加一个简单的“画图功能”，可能需要同时修改前端 UI、后端 WebSocket、Agent 核心逻辑甚至沙箱环境。

这种低内聚、高耦合的状态，直接导致了“牵一发而动全身”的维护噩梦，也让试图参与贡献的新开发者望而却步。

2.2 痛点二：性能的“隐形墙” (Performance Bottleneck)

第二个问题是同步阻塞（Synchronous Blocking）带来的性能瓶颈。

旧架构中，当 Agent 执行耗时命令（如编译大型项目）时，主线程会被锁死，无法响应任何心跳或中断指令。用户只能看着界面转圈，体验极差。

此外，前后端之间低效的全量状态同步，也让网络传输成为了瓶颈。

2.3 痛点三：安全的“达摩克利斯之剑” (Security Risks)

第三个问题是安全性（Security）。

旧版沙箱隔离不完善，Agent 权限过高（往往是 Root）。如果大模型产生幻觉执行 rm -rf /，或者试图读取宿主机的敏感文件，旧系统缺乏有效的拦截机制。

对于企业用户而言，这种“裸奔”的状态是绝对无法接受的。

2.4 痛点四：扩展性的“天花板” (Weak Scalability)

最后是可扩展性弱。

旧代码中充斥着针对特定模型的硬编码（Hard-coding）。集成新模型（如 Llama 3）或复用工具变得异常困难。这让 OpenHands 难以跟上 AI 技术日新月异的步伐。

莫潇羽的总结：

架构混乱、性能瓶颈、安全隐患、扩展受限。这四座大山压在 OpenHands 身上，让重构成为了一场不得不打的“自救之战”。

2.5 现场勘查：一段“屎山”代码的尸检报告

为了让大家更深刻地理解为什么要重构，莫潇羽翻出了 OpenDevin 早期版本的一段核心代码（已匿名化处理）。这段代码负责处理用户输入并执行 Shell 命令。

2.5.1 重构前：脆弱的“屎山” (Before)

请大家屏住呼吸，来看看这段“传世经典”：

# 旧版本 (Legacy) 伪代码
def handle_user_input(msg, user_id):
    # 全局变量满天飞
    global CURRENT_AGENT
    global DOCKER_CONTAINER

    if "run" in msg:
        # 直接字符串拼接，毫无安全性可言
        cmd = msg.split("run ")[1]

        # 阻塞式调用，如果命令跑10分钟，整个服务器就卡死10分钟
        output = DOCKER_CONTAINER.exec_run(cmd)

        # 硬编码的 Agent 逻辑
        if "error" in output:
            if CURRENT_AGENT == "GPT-4":
                 # 递归调用，极易栈溢出
                 return fix_error(output)
            else:
                 return "Error occurred"

    elif "edit" in msg:
        # 又是几十行 if-else 嵌套
        pass

尸检报告：

全局状态依赖：global CURRENT_AGENT 意味着这个系统同时只能服务一个用户。如果张三正在用，李四发个指令，张三的 Agent 就被李四篡改了。
同步阻塞：exec_run 是同步的。在执行 npm install 这种耗时命令时，整个后端线程被锁死，无法响应任何心跳包，导致前端经常误报“连接断开”。
脆弱的逻辑：通过字符串 if "error" in output 来判断是否出错是非常不靠谱的。因为很多正常的命令输出里也可能包含单词 "error"。

2.5.2 重构后：优雅的事件流 (After)

再来看看新架构下，同样的逻辑是如何实现的：

# 新版本 (Refactored) 伪代码
class CodeActAgent(Agent):
    async def step(self, state: State) -> Action:
        # 1. 纯函数式思考，无副作用
        latest_event = state.history[-1]

        # 2. 类型安全的 Action 生成
        if isinstance(latest_event, ActionMessage):
             # 异步调用 LLM，不阻塞主线程
             response = await self.llm.acompletion(...)
             return ActionRunCode(command=response.content)

        return NullAction()

# 独立的 Runtime 模块处理执行
async def runtime_worker(event_stream):
    async for action in event_stream.subscribe():
        if isinstance(action, ActionRunCode):
            # 3. 沙箱隔离执行
            observation = await sandbox.execute(action.command)
            # 4. 结果回写到事件流
            event_stream.publish(observation)

优化亮点：

无全局变量：所有状态都封装在 State 对象中，天然支持多用户并发。
全异步 (Async/Await)：await 关键字确保了即使任务耗时再长，服务器也能响应其他请求。
类型安全：ActionRunCode 是一个 Pydantic 对象，拥有严格的字段校验。

正是这种脱胎换骨的变化，让 OpenHands 的性能提升了 300%。

第三章：秩序的重建 —— 新架构的核心设计哲学

面对旧版本的废墟，OpenHands 团队选择了最艰难的一条路：推倒重来。

在 OpenHands v0.6+ 的重构中，团队确立了四个核心原则。这四个原则，就像是新大厦的四根擎天柱。

3.1 核心原则一：模块化设计 (Modular Design)

“分而治之”是计算机科学中最古老的智慧。

新架构将系统拆分为了几个界限清晰的独立模块：

Frontend：展示层。
Backend：消息分发层。
Runtime：命令执行层。
Agent：大脑思考层。

这种解耦（Decoupling）让系统变得极其灵活。就像一个精密的乐高城市：

Agent 模块就像是市政厅，负责决策和规划。
Runtime 模块就像是工程队，只管干活（盖楼、修路），不问为什么。
Event Stream 则是连接两者的高速公路网，信息流在其中高速穿梭。

你可以随意替换掉“市政厅”（换个更聪明的模型），而不需要解散“工程队”。

3.2 核心原则二：性能优先 (Performance First)

为了解决“慢”的问题，新架构引入了异步事件驱动（Asynchronous Event-Driven）机制。

这就像是把一家餐厅从“只有一个服务员”变成了“自助点餐系统”。

旧模式：服务员（主线程）去厨房（沙箱）催菜，必须等菜做好了才能回来服务下一位客人。
新模式：客人（Agent）下单后，订单通过传送带（Event Bus）自动送达厨房。服务员永远在处理新请求，从不等待。

3.3 核心原则三：安全第一 (Security First)

在 AI 时代，安全是底线。

新版本引入了零信任架构（Zero Trust Architecture）。

注：零信任架构是一种安全概念，核心思想是“从不信任，始终验证”。即无论请求来自内部还是外部，都必须经过严格的身份验证和授权。

具体措施包括：

沙箱隔离：代码执行限制在 Docker 容器内。
权限分级：高危操作（如删文件）需用户手动批准（Human-in-the-loop）。
全链路加密：WebSocket 通信强制 HTTPS/WSS。

3.4 核心原则四：可扩展性强 (Extensibility)

新架构被设计成了插件化（Pluggable）的。

这意味着：

模型无关性：轻松切换 GPT-4, Claude 3 或 DeepSeek。
自定义 Agent：开发者可以像搭积木一样，编写特定功能的 Agent（如 SQL 专家、前端专家）并让它们协同工作。

莫潇羽的通俗解读：

旧版本的 OpenHands 像是一个功能折叠在一起的瑞士军刀，容易坏且难修。

新版本的 OpenHands 则是一座模块化的乐高城市。每一个模块都是独立的积木，既稳固又充满无限可能。

在下一章中，我们将深入这个“乐高城市”的内部，去看看它的核心子模块具体是如何协同工作的。

3.5 核心模块深潜：Runtime 的前世今生

既然我们把 OpenHands 比作乐高城市，那么 Runtime（运行时） 就是这座城市的“地下管网”。它是最不起眼，但也是最核心的基础设施。

莫潇羽在研读源码时发现，Runtime 模块的重构是这次 OpenHands 变身的关键。

3.5.1 旧时代的痛：Docker-in-Docker 的噩梦

在旧版本中，OpenHands 为了隔离环境，采用了一种简单粗暴的 Docker-in-Docker (DinD) 方案。

也就是在 OpenHands 的 Docker 容器里，再启动一个 Docker 守护进程。

这种方案有两个巨大的缺陷：

特权模式 (Privileged Mode)：DinD 需要开启特权模式，这相当于把宿主机的 Root 权限拱手相让。
文件系统性能极差：多层 OverlayFS 叠加，导致文件读写速度只有原生速度的 1/10。

3.5.2 新时代的解：Sandbox Runtime 接口

新架构定义了一个抽象的 Runtime 接口：

class Runtime(ABC):
    @abstractmethod
    def run_action(self, action: Action) -> Observation:
        pass

    @abstractmethod
    def read_file(self, path: str) -> str:
        pass

这种设计让 OpenHands 彻底摆脱了对 Docker 的强依赖。目前主要实现是 DockerRuntime，但它采用的是 Docker-outside-of-Docker (DooD) 模式。

3.5.3 DooD 模式的精髓

在 DooD 模式下，OpenHands 容器并不自己运行 Docker Daemon，而是通过挂载 /var/run/docker.sock，借用宿主机的 Docker Daemon 来启动兄弟容器（Sandbox）。

这样做的好处是：

性能起飞：沙箱容器直接运行在宿主机内核上，没有任何中间层损耗。
资源复用：沙箱可以共享宿主机的镜像缓存，不需要每次都重新下载 Ubuntu 镜像。

此外，这个接口设计还为未来支持 Kubernetes Runtime 甚至 AWS Lambda Runtime 埋下了伏笔。或许在不久的将来，我们可以看到 OpenHands 指挥着成千上万个云端沙箱，同时进行大规模的软件构建。

3.6 架构哲学：单体 (Monolith) vs 微服务 (Microservices)

OpenHands 的重构，本质上是一次从单体架构向微服务化架构的演进。

3.6.1 为什么要拆？

在 v0.1 时代，OpenHands 是典型的“单体应用”。所有的逻辑——WebSocket 处理、LLM 调用、Docker 控制、文件读写——都挤在 server.py 这一个文件里。

这就好比一家小卖部，老板既要收银，又要理货，还要送外卖。生意好的时候，老板一个人根本忙不过来。

3.6.2 拆分后的新世界

现在的 OpenHands，更像是一个分工明确的现代化公司：

Frontend (前台)：只负责接待客户（用户），展示菜单（UI）。它不关心菜是怎么做的，只关心怎么把菜端上来。
Server (调度中心)：负责接收订单，派发任务。它知道哪个 Agent 擅长写 Python，哪个 Runtime 还有空闲资源。
Agent (专业技术员)：每个 Agent 都是一个独立的微服务。CodeActAgent 专注于写代码，BrowsingAgent 专注于上网查资料。它们之间通过标准的 Protocol 交流。
Sandbox (外包工厂)：所有的脏活累活（运行代码）都扔到这里做。工厂炸了（死循环）也没关系，直接推倒重建（重启容器）即可。

这种架构不仅提升了稳定性，更重要的是解放了开发者的生产力。如果你想改进 UI，你完全不需要去读后端那几万行代码；如果你想优化 Docker 启动速度，也不用担心会改坏前端的样式。

第四章：解剖麻雀 —— 新架构四大支柱深度详解

在上一章我们了解了宏观的设计哲学，现在让我们把镜头拉近，像外科医生一样，精准地解剖 OpenHands 新架构的内部构造。

根据官方的技术文档和重构说明，新版本的 OpenHands 架构被清晰地划分为了四个核心子模块。这四个模块各司其职，共同支撑起了 AI 程序员的强大能力。

4.1 支柱一：工具包 (Toolkit) —— Agent 的“瑞士军刀”

对于一个 AI Agent 来说，如果 LLM 是大脑，那么 Toolkit（工具包） 就是它的双手。没有工具，Agent 只能空谈，无法产生实际的代码。

在 OpenHands 的新架构中，工具不再是散落在各处的代码片段，而是被封装成了标准化的接口。

核心工具包括：

Command Line (Shell)：这是最强大的工具。Agent 可以通过它执行 ls, grep, python, npm 等任何 Linux 命令。新版工具包对 Shell 输出进行了实时流式捕获，确保 Agent 能看到命令执行过程中的每一行日志。
Editor (代码编辑器)：不同于简单的“覆盖写入”，新版的编辑器工具支持更精细的操作，如“替换第 10 到 20 行”、“在第 50 行插入代码”。这大大减少了 LLM 因为上下文过长而重写整个文件时的出错概率。
Browser (浏览器)：基于 Playwright 或 Selenium 封装。Agent 可以用它去 Google 搜索报错信息，甚至去 Stack Overflow 查找解决方案。

这些工具通过统一的 Action Interface 暴露给 Agent。这意味着，如果你想给 Agent 加一个“发邮件”的工具，只需要继承基类并实现 run() 方法即可。

4.2 支柱二：工具库 (Library) —— 巨人的肩膀

Library（工具库） 是 OpenHands 的后勤补给站。它封装了大量常用的第三方库和底层接口，旨在简化开发流程。

这里面包含了：

LLM 适配层：通过 litellm 等库，抹平了 OpenAI, Anthropic, Google Gemini 等不同模型 API 的差异。开发者调用 llm.completion() 时，无需关心底层是 HTTP 请求还是 gRPC。
Docker 客户端封装：为了让 Agent 能控制沙箱，Library 层封装了复杂的 Docker API。它负责容器的启动、停止、端口映射以及资源限制。
解析器 (Parsers)：负责解析 LLM 输出的文本，将其转化为结构化的 JSON 或 Action 对象。这是连接“自然语言”和“机器指令”的桥梁。

4.3 支柱三：工作区 (Workspace) —— 虚拟的练兵场

Workspace（工作区） 是 OpenHands 为 Agent 划定的一块专属领地。

在旧版本中，Agent 直接操作宿主机文件系统，这是非常危险的。而在新架构中，Workspace 是一个被严格隔离的虚拟环境。

文件系统映射：通过 Docker Volume 技术，将宿主机的某个特定目录（如 ./workspace）挂载到容器内部。Agent 在容器里看到的 /workspace 就是这个目录，但它无法访问宿主机的其他目录（如 /etc 或 C:\Windows）。
状态持久化：Workspace 不仅保存代码文件，还负责保存当前的会话状态（Session State）。这意味着即使服务器重启，Agent 依然记得它上次改到了哪一行代码，任务进度不会丢失。

4.4 支柱四：服务器 (Server) —— 智慧的中枢

最后是 Server（服务器），它是整个系统的指挥塔。

OpenHands 的后端采用 Python FastAPI 框架重写，专注于处理高并发的请求分发。

Server 的主要职责包括：

连接管理：维护前端与后端的 WebSocket 长连接。
事件分发：当 Agent 发出一个 Action 时，Server 负责将其路由到 Runtime；当 Runtime 返回 Observation 时，Server 负责将其推送到前端。
资源调度：当有多个用户同时使用时，Server 负责为每个用户分配独立的 Session 和沙箱容器，实现多租户隔离。

技术图解：

我们可以把这四个模块的工作流想象成一个精密的流水线：

Server 接收到用户的需求：“帮我写个爬虫”。
Server 唤醒 Workspace 中的 Agent。
Agent 从 Toolkit 中拿出“浏览器”和“编辑器”。
Agent 借助 Library 中的 LLM 接口进行思考。
Agent 在 Workspace 的安全沙箱中写代码、运行测试。
最终结果通过 Server 反馈给用户。

这种清晰的职责划分，正是 OpenHands 能够从“混乱”走向“有序”的关键所在。而在这一切的背后，还有一个更底层的机制在驱动着数据的流动，那就是——事件流。

4.5 黑科技揭秘：Workspace 是如何“骗”过 Agent 的？

在 OpenHands 中，Agent 总是认为自己拥有整个操作系统的控制权。它愉快地在 /workspace 目录下创建文件、删除文件。

但实际上，这只是 OpenHands 施展的一个障眼法。

4.5.1 Docker Volume 的魔术

我们在启动命令里用到了这个参数：

-v $WORKSPACE_BASE:/opt/workspace_base

这行命令在宿主机（你的电脑）和 Docker 容器（Agent 的世界）之间建立了一条时空隧道。

宿主机视角：

你的 C:\Users\...\Desktop\workspace 文件夹里，存放着真实的代码文件。你可以用 VS Code 打开它，甚至用记事本修改它。

容器视角：

在 Agent 看来，/opt/workspace_base 是它唯一的领地。OpenHands 的 Runtime 会监控这个目录。

4.5.2 实时同步机制

当你在本地用 VS Code 修改了一个文件并保存时：

操作系统 发出 FileChanged 事件。
Docker 瞬间将变更同步到容器内的 /opt/workspace_base。
OpenHands Runtime（如果开启了文件监听）会检测到这个变化。
Agent 在下一次读取文件时，读到的就是最新的内容。

反之亦然。当 Agent 在容器里执行 echo "hello" > test.txt：

容器内文件系统发生变更。
Docker 将变更写回宿主机的硬盘。
你桌面上的文件夹里立刻多出了一个 test.txt。

这种机制极其巧妙地解决了“人机协作”的问题。你和 Agent 可以同时修改同一个项目，就像两个程序员在用同一台电脑结对编程一样，互不干扰，却又实时同步。

4.5.3 权限的结界

为了防止 Agent “越狱”，OpenHands 在启动容器时做了严格的限制：

User Namespace Remapping：容器里的 root 用户，在宿主机上只是一个普通用户。这意味着即使 Agent 在容器里执行 rm -rf /，它也删不掉你宿主机的系统文件。
Network Isolation：默认情况下，容器只能访问公网，无法访问宿主机的局域网（除非你显式开启 host.docker.internal）。

这层层的结界，确保了 OpenHands 既是一个强大的生产力工具，又是一个绝对安全的沙盒。

第五章：系统的脉搏 —— 事件流与类型安全机制

如果说四大支柱构成了 OpenHands 的躯体，那么 Event Stream（事件流） 就是流淌在其中的血液，而 Type Safety（类型安全） 则是免疫系统，时刻保护着系统的健康。

这一章，莫潇羽将带大家深入代码层面，看看这两个机制是如何从根本上改变 OpenHands 的运行方式的。

5.1 事件驱动：从“同步阻塞”到“异步响应”

旧版本的 OpenHands 往往采用线性的执行逻辑：A 调用 B，B 调用 C，C 返回结果给 B，B 再返回给 A。这种紧耦合的调用链在复杂的 Agent 交互中非常脆弱。

新版本引入了基于 Event Sourcing（事件溯源） 的架构。

在 OpenHands 中，一切皆事件。

用户发送的消息是一个事件 (MessageEvent)。
Agent 决定运行代码是一个事件 (ActionRunCode)。
代码运行的输出结果是一个事件 (ObservationRunCode)。
任务完成是一个事件 (StateChangedEvent)。

系统核心维护着一个无限循环的 Event Loop（事件循环）。让我们看一段简化版的 Python 伪代码，来理解它的工作原理：

async def event_loop(agent, runtime, event_stream):
    """
    OpenHands 核心事件循环逻辑示意
    """
    while True:
        # 1. 获取当前最新的事件（比如用户的输入，或者上一步的执行结果）
        latest_event = event_stream.get_latest()

        # 2. Agent 观察：根据历史事件流，决定下一步做什么
        # Agent 不直接调用 Runtime，而是生成一个 Action 对象
        action = await agent.step(latest_event)

        if not action:
            break # 任务结束

        # 3. 将 Action 投递到事件流中
        event_stream.add(action)

        # 4. Runtime 执行：监听事件流，发现有新的 Action
        # Runtime 在沙箱中执行命令，并生成 Observation
        observation = await runtime.run_action(action)

        # 5. 将结果反馈回事件流
        event_stream.add(observation)

        # 6. 前端 UI 监听到新事件，自动刷新界面
        await notify_frontend(action, observation)

这种设计的威力在于：

可回溯性 (Time Travel)：由于所有的操作都被记录在 event_stream 中，我们可以随时“倒带”。比如 Agent 犯了个错，我们可以把状态回滚到 5 分钟前，删除错误的事件，让 Agent 重新尝试。这对于调试 AI 的逻辑错误简直是神器。
解耦：Agent 不需要知道 Runtime 是 Docker 还是 Kubernetes，它只管发出 Action。Runtime 也不需要知道是谁发的命令，它只管执行并返回 Observation。

5.2 类型安全：给代码穿上防弹衣

在 Python 这种动态语言中，类型错误（Type Error）是开发者的噩梦。对于一个拥有数万行代码的大型项目，如果缺乏类型约束，重构就是一场灾难。

OpenHands 的新版本全面引入了 Type Safety（类型安全） 机制，主要依赖 Python 的 Pydantic 库和 TypeScript 的静态类型检查。

5.2.1 强类型的事件定义

每一个事件都有严格的 Schema 定义。这意味着，如果开发者（或者 AI 模型）试图构造一个格式错误的事件，系统在运行前就会报错，而不是等到执行时才崩溃。

来看看 OpenHands 中定义 Action 的代码示例：

from pydantic import BaseModel, Field
from typing import Literal

class Action(BaseModel):
    """所有动作的基类"""
    source: str = "agent"

class ActionRunCode(Action):
    """运行代码的动作定义"""
    action: Literal["run"] = "run"
    command: str = Field(..., description="要执行的 Shell 命令")
    blocking: bool = Field(False, description="是否阻塞执行")

    # 验证逻辑：确保命令不为空
    @validator("command")
    def check_command_not_empty(cls, v):
        if not v.strip():
            raise ValueError("Command cannot be empty")
        return v

# 使用示例
try:
    # 这种写法是合法的
    valid_action = ActionRunCode(command="ls -la")

    # 这种写法会直接抛出 ValidationError，因为缺少必要字段
    invalid_action = ActionRunCode(blocking=True) 
except Exception as e:
    print(f"类型检查拦截了错误: {e}")

5.2.2 前后端的类型契约

在前端 TypeScript 代码中，同样定义了对应的接口。这保证了后端发出的数据结构，前端一定能正确解析。

// 前端类型定义 (TypeScript)
interface ActionRunCode {
    action: 'run';
    command: string;
    blocking: boolean;
}

function handleAction(action: ActionRunCode) {
    // 编译器会确保 action 对象一定有 command 属性
    console.log("Executing:", action.command); 
}

通过这种端到端（End-to-End）的类型安全，OpenHands 极大地减少了“运行时错误”。就像是给整个系统穿上了一层防弹衣，无论是人类开发者写出的 Bug，还是 LLM 产生的幻觉数据，都会被类型检查机制无情地拦截在系统核心之外。

这种严谨的工程实践，正是 OpenHands 能够从“玩具”进化为“工具”的重要标志。

5.3 硬核解密：事件流日志逐行分析

为了让大家更直观地理解 OpenHands 是如何思考的，莫潇羽从后台抓取了一段真实的事件日志（Event Log）。

这段日志记录了用户让 OpenHands “创建一个 Python 脚本打印 Hello World” 的全过程。让我们像侦探一样，逐行分析这段数据。

5.3.1 第一步：用户指令 (ActionMessage)

{
  "id": "evt_001",
  "timestamp": "2024-05-20T10:00:00Z",
  "source": "user",
  "action": "message",
  "args": {
    "content": "请帮我写一个 hello.py，里面打印 Hello World"
  }
}

这是事件的起点。source 为 user，表明这是人类发出的指令。

5.3.2 第二步：Agent 思考 (NullAction -> ActionRunCode)

Agent 收到消息后，LLM 进行了一番推理（Thinking），然后决定执行命令。

{
  "id": "evt_002",
  "timestamp": "2024-05-20T10:00:02Z",
  "source": "agent",
  "action": "run",
  "args": {
    "command": "echo 'print(\"Hello World\")' > hello.py",
    "blocking": true
  }
}

注意这里的 command。Agent 并没有打开编辑器，而是聪明地使用 echo 重定向命令直接创建文件。这比打开编辑器输入要快得多。这就是 AI 独特的“计算机直觉”。

5.3.3 第三步：执行反馈 (Observation)

Runtime（沙箱）执行完命令后，返回了一个观察结果。

{
  "id": "evt_003",
  "timestamp": "2024-05-20T10:00:03Z",
  "source": "sandbox",
  "observation": "run",
  "content": "",
  "extras": {
    "exit_code": 0
  }
}

exit_code: 0 表示命令执行成功。content 为空是因为 echo 命令本身没有输出。

5.3.4 第四步：验证结果 (ActionRunCode)

Agent 并没有就此停止，它非常严谨地决定运行一下这个脚本，以确保它是工作的。

{
  "id": "evt_004",
  "timestamp": "2024-05-20T10:00:04Z",
  "source": "agent",
  "action": "run",
  "args": {
    "command": "python3 hello.py"
  }
}

5.3.5 第五步：验证通过 (Observation)

{
  "id": "evt_005",
  "timestamp": "2024-05-20T10:00:05Z",
  "source": "sandbox",
  "observation": "run",
  "content": "Hello World\n",
  "extras": {
    "exit_code": 0
  }
}

看到了预期的输出 "Hello World"。

5.3.6 第六步：任务完成 (ActionMessage)

最后，Agent 向用户汇报结果。

{
  "id": "evt_006",
  "timestamp": "2024-05-20T10:00:06Z",
  "source": "agent",
  "action": "message",
  "args": {
    "content": "搞定！我已经创建了 hello.py 并验证通过了。"
  }
}

莫潇羽的分析：

通过这段日志，我们可以清晰地看到 OpenHands 的 "Think-Act-Observe" 循环。每一个 JSON 对象都是这个庞大机器中的一个齿轮。正是这些齿轮的精密咬合，才实现了 AI 程序员的魔法。

第六章：实战指南 —— 把你的 AI 员工领回家

讲了这么多理论，相信很多朋友已经跃跃欲试了。莫潇羽常说：“纸上得来终觉浅，绝知此事要躬行。”

OpenHands 的安装其实非常简单，因为它极其依赖 Docker 技术。这意味着你不需要在本地安装乱七八糟的 Python 依赖库，也不用担心把自己的电脑环境搞乱。

本章节将手把手教你在本地电脑（Windows/Mac/Linux）上部署一套 OpenHands 环境。

6.1 环境准备：磨刀不误砍柴工

在开始之前，请确保你的电脑满足以下条件：

操作系统：推荐 Linux (Ubuntu 20.04+) 或 macOS。Windows 用户强烈建议使用 WSL2 (Windows Subsystem for Linux)。
Docker：这是必须的。OpenHands 的沙箱环境完全运行在 Docker 容器中。

官方下载地址：https://www.docker.com/products/docker-desktop/
安装完成后，打开终端输入 docker --version，确保能看到版本号。

API Key：你需要一个大模型的 API 密钥。推荐使用 OpenAI (GPT-4o) 或 Anthropic (Claude 3.5 Sonnet)。这两个模型在编程任务上的表现目前是最顶尖的。

6.2 极速启动：Docker 一键运行

OpenHands 官方提供了一个极其方便的 Docker 启动命令。打开你的终端（Windows 用户请打开 WSL 终端），执行以下步骤。

第一步：创建工作目录

我们需要在本地创建一个文件夹，用来存放 OpenHands 生成的代码。

# 在当前目录下创建一个名为 workspace 的文件夹
mkdir workspace
export WORKSPACE_BASE=$(pwd)/workspace

第二步：运行启动命令

请直接复制以下命令（注意将 YOUR_API_KEY 替换为你真实的 API Key，比如 sk-xxxx）：

docker run -it \
    --pull=always \
    -e SANDBOX_USER_ID=$(id -u) \
    -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
    -v $WORKSPACE_BASE:/opt/workspace_base \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    ghcr.io/all-hands-ai/openhands:0.9

命令详解（莫潇羽的小贴士）：

--pull=always: 每次启动都尝试拉取最新版本，保证你用的是最新的代码。
-e SANDBOX_USER_ID=$(id -u): 让容器内的用户 ID 和你当前用户一致，避免生成的文件你没有权限修改。
-v $WORKSPACE_BASE:/opt/workspace_base: 关键参数！这实现了“挂载”。容器里写的代码，会实时出现在你电脑的 workspace 文件夹里。
-v /var/run/docker.sock:/var/run/docker.sock: 这是一个“套娃”操作。让 OpenHands 容器能够控制你宿主机的 Docker，以便它能启动子容器（沙箱）。
-p 3000:3000: 映射端口。启动后，你在浏览器访问 http://localhost:3000 就能看到界面。

6.3 进阶配置：自定义模型与代理

如果你想更细致地配置 OpenHands，比如使用国内的 DeepSeek 模型，或者配置 HTTP 代理，可以通过 config.toml 文件来实现。

在工作目录下创建一个 config.toml 文件：

[core]
workspace_base = "./workspace"
debug = true  # 开启调试日志

[llm]
model = "openai/gpt-4o" # 或者 "anthropic/claude-3-5-sonnet-20240620"
api_key = "sk-..."
base_url = "https://api.openai.com/v1" # 如果用代理，这里填代理地址

[agent]
name = "CodeActAgent" # 推荐使用 CodeActAgent，它的编程能力最强

然后在启动 Docker 时，把这个配置文件挂载进去：

-v $(pwd)/config.toml:/app/config.toml

6.4 本地开发与远程部署模式

OpenHands 的新架构支持两种运行模式的无缝切换：

本地模式 (Local Mode)：

也就是我们上面演示的。Server 和 Agent 都运行在你的笔记本上。
优点：零延迟，完全掌控数据。
缺点：占用本地内存和 CPU，运行大型任务时电脑可能会发烫。

远程模式 (Remote Mode)：

你可以把 OpenHands 部署在公司的一台高性能服务器（比如 64核 128G 内存）上。
然后通过本地浏览器访问服务器的 IP 地址（如 http://192.168.1.100:3000）。
优点：利用服务器的强大算力，不占用本地资源；支持团队多人协作，共享同一个 Workspace。

得益于前后端分离的架构，这种迁移不需要修改任何一行代码。你只需要在服务器上运行 Docker 命令，然后在本地浏览器打开网页即可。

6.5 遇到问题？常见排查指南

在安装过程中，90% 的问题都集中在 Docker 网络和 LLM 连接上。莫潇羽为你准备了急救包：

情况一：Docker 启动失败或界面打不开

现象：终端报错 bind: address already in use 或浏览器访问 localhost:3000 白屏。
对策：检查端口占用。尝试修改映射端口为 -p 3001:3000。如果是 Windows，确保 Docker Desktop 正在运行且 WSL2 状态正常。

情况二：LLM 连接超时或报错

现象：Agent 刚开始工作就报 ConnectionError 或 API Key Invalid。
对策：

检查 config.toml 中的 base_url 是否正确。
如果使用本地 Ollama，确保加上了 --add-host host.docker.internal:host-gateway 参数，并将地址设为 http://host.docker.internal:11434。
国内用户请检查是否配置了正确的 API 代理地址。

更多疑难杂症，请翻阅本文末尾的 《附录：避坑指南 (FAQ)》 章节。

实战小结：

安装 OpenHands 并不复杂，关键在于理解 Docker 的挂载机制。一旦环境搭建好，你就拥有了一个 24 小时待命的超级程序员。试着让它帮你写一个贪吃蛇游戏，或者分析一段你看不懂的源码，你会被它的能力震惊的。

6.6 进阶玩法：解锁本地 LLM 与自定义沙箱

如果你觉得调用 GPT-4 API 太贵，或者你需要在一个无法访问公网的机房里运行 OpenHands，那么这一节内容绝对能帮到你。

我们将介绍如何利用 Ollama 运行本地大模型，以及如何为 Agent 定制一个专属的开发环境。

6.6.1 零成本方案：接入本地 Ollama

Ollama 是目前最流行的本地大模型运行工具。它可以让你在笔记本上轻松运行 Llama 3, Mistral, Qwen 等开源模型。

步骤一：安装并启动 Ollama

去 Ollama 官网下载安装包。安装完成后，在终端运行：

ollama run llama3

确保你能和它对话。

步骤二：配置 OpenHands 连接 Ollama

OpenHands 默认运行在 Docker 容器里，而 Ollama 运行在宿主机上。因此，我们需要让容器能访问到宿主机的网络。

修改 config.toml：

[llm]
model = "ollama/llama3"
base_url = "http://host.docker.internal:11434" # 关键！指向宿主机的 Ollama 服务
api_key = "ollama" # 随便填，不为空即可

实测对比：本地 LLM vs 云端 GPT-4

很多朋友关心本地模型到底能不能打。莫潇羽做了一组简单的对比测试：

任务类型	本地 Llama 3 (8B)	云端 GPT-4o	评价
Python Hello World	✅ 完美	✅ 完美	简单任务无差异
SQL 查询编写	✅ 准确	✅ 准确	结构化任务表现良好
Django 项目升级	❌ 经常改错文件	✅ 一次成功	复杂上下文理解是短板
速度	🚀 飞快 (50 tok/s)	⚡ 较快 (20 tok/s)	本地推理无网络延迟
隐私	🔒 数据不出本地	☁️ 需上传云端	敏感项目首选本地

结论：对于简单的脚本编写、Bug 修复，本地 Llama 3 完全够用且速度极快。但涉及多文件架构重构等复杂任务，GPT-4 依然是不可替代的王者。

6.6.2 高性价比方案：接入 DeepSeek (深度求索)

如果你追求 GPT-4 级别的编程能力，但又不想支付昂贵的美金，国产之光 DeepSeek Coder V2 是目前最佳的选择。它的 API 价格仅为 GPT-4 的几十分之一。

在 config.toml 中添加：

[llm]
model = "openai/deepsee

🔒

该内容仅对更高等级社区用户开放
请谨慎解锁时效性强且发布日期较早的文章
单篇解锁后若未显示全文请刷新页面

您当前：游客 · 可见 60% 内容 · 升级至 注册用户 可见 70%

👀

游客

可见 60%

✓ 当前

注册用户

可见 70%

社区精英

可见 100%

社区守护