OpenHands 源码解析

Python 事件流架构、运行时沙箱与 Agent 控制器

  1. 第 1 讲：整体架构与定位 OpenHands 的官方定位是 "The self-hosted developer control center for coding agents and automations" —— 自托管的开发者控制中心。
  2. 第 2 讲：V0 → V1 → Agent Canvas 演进路线 OpenHands 经历了一次完整的架构重构。V0 的代码全部被标记为DEPRECATED，V1 是完全重写的新架构。
  3. 第 3 讲：依赖注入与服务架构（Injector 模式） OpenHands 是一个重型长任务 Agent——一次会话可能持续数小时甚至数天。这意味着：
  4. 第 4 讲：会话管理核心 (AppConversationService) 在 OpenHands 的 V1 架构中，会话（Conversation）是用户与 AI Agent 交互的核心载体。每一个会话从创建到销毁，贯穿了沙箱启动、仓库克隆、Skill 加载、Agent 初始化、事件回调等完整
  5. 第 5 讲：事件溯源系统 (Event Log + 3 Backends) 在 OpenHands V1 架构中，事件（Event）是会话中所有交互的唯一真相来源。用户的每一条消息、Agent 的每一次工具调用、沙箱的每一个输出片段——全部被序列化为 JSON 事件，持久化到不同的存储后端。
  6. 第 6 讲：沙箱生命周期 (Docker/K8s/Remote) OpenHands 的 Agent 不直接在宿主机上执行命令，而是运行在沙箱 (Sandbox) 中。沙箱提供隔离的执行环境，Agent 的所有文件系统操作、命令执行、代码编译都在沙箱内完成。
  7. 第 7 讲：Agent 类型与 ACP 协议 在 OpenHands 的架构演进中，Agent 从最初的单一 "OpenHands Agent" 逐渐扩展为支持多种智能体类型的双轨架构。第 7 讲我们将深入源码，理解 OpenHands 如何管理两种截然不同的 Ag
  8. 第 8 讲：Skill 系统 —— 从 .md 到 Agent 能力的管道 在 OpenHands 中，Skill 是一段以 Markdown 文件为载体、带 YAML frontmatter 的结构化知识，Agent 在运行时会加载这些文件作为"微代理"（microagent）指令。本质上它把
  9. 第 9 讲：用户认证与权限管理 🔹 OSS 模式（开源版）：单用户，无多租户，使用 DefaultUserAuth
  10. 第 10 讲：Webhook 与事件回调机制 OpenHands 的 agent-server（负责运行 AI Agent 的沙箱内服务）与 app-server（面向用户的管理服务）是两个独立进程。它们之间如何通信？答案是 Webhook + 事件回调。
  11. 第 11 讲：Git 集成与版本控制 OpenHands 不只是"AI 写代码"——它本质上是一个面向真实仓库的 AI 工程师。Git 集成是 OpenHands 的核心能力之一，贯穿了从仓库发现、克隆、分支管理到 PR 建议的完整链路。
  12. 第 12 讲：配置系统与多环境支持 OpenHands 的配置系统是一个分层架构，从环境变量到 Pydantic 模型，再到抽象存储接口，覆盖了从开发到生产、从 OSS 到 SaaS 的全部场景。本讲深入剖析配置加载链路、多环境适配策略以及设置管理的核心设
  13. 第 13 讲：数据库设计与 ORM 层 OpenHands 的数据库层是 V1 App Server 的核心基础设施。它同时支持PostgreSQL（生产环境）和 SQLite（本地开发），通过 SQLAlchemy 2.0 的 DeclarativeBase
  14. 第 14 讲：API 路由设计与中间件 OpenHands V1 的整个 Web 服务是一个 FastAPI 应用，入口在 openhands/app_server/app.py。这个文件只有 86 行，却包含了应用的完整骨架：
  15. 第 15 讲：错误处理与日志系统 OpenHands 是一个AI 软件工程平台，它管理 Docker/K8s 沙箱、处理 LLM API 调用、操作用户代码仓库。任何一个环节出错都可能造成数据丢失或安全泄露。因此它的错误处理和日志系统不只是一个"nice
  16. 第 16 讲：测试架构与 CI/CD OpenHands 的测试体系覆盖了后端 Python、前端 React/TypeScript、企业版模块、Docker 镜像构建以及发布流水线。整个仓库包含：
  17. 第 17 讲：性能优化与缓存策略 OpenHands 是一个面向企业级部署的 AI Agent 平台，每次会话涉及 LLM 调用、沙箱启动、事件回调、数据库读写等密集操作。在高并发场景下，性能瓶颈直接决定了系统能否支撑多用户同时使用。
  18. 第 18 讲：安全机制 — 密钥管理与沙箱隔离 🔹 密钥如何存储与传输 — SecretStr + JWE 加密 + SecretsStore 抽象
  19. 第 19 讲：插件系统与扩展点 OpenHands 的插件系统（Plugin System）是平台可扩展性的核心。它让管理员、组织和用户能够在不同层级注册外部插件市场（Marketplace），动态加载 Skill、Hook 和 MCP 工具——而无需
  20. 第 20 讲：总结与最佳实践 在过去的 19 讲中，我们从整体架构出发，逐一拆解了 OpenHands V1 的核心模块。第 20 讲——本系列的收官之作——不再引入新模块，而是站在全局视角，提炼出贯穿整个代码库的设计模式、最佳实践和架构决策背后的思