夜雨聆风OpenHands 源码解析
第 1 讲：整体架构与定位
基于 master 分支源码 · 2026-07-28
一、OpenHands 是什么
OpenHands 的官方定位是 "The self-hosted developer control center for coding agents and automations" —— 自托管的开发者控制中心。
🔹 Python 3.12+ / FastAPI 后端 + React 前端
🔹 多 Agent 支持（ACP 协议）：OpenHands、Claude Code、Codex 等
🔹 多 Runtime 支持：Docker、K8s、远程 VM、本地
🔹 完整事件溯源 + 断点续跑
📦 源码仓库
https://github.com/All-Hands-AI/OpenHands
本地路径：~/Applications/OpenHands/ · 约 4 万行 Python
二、核心数据
| 指标 | 数据 |
|---|---|
| 提交数 | 18,706+ |
| Python 文件 | 234 个 |
| 代码行数 | 40,226 行 |
| Web 框架 | FastAPI |
| 前端 | React + Vite |
| 协议 | MIT |
三、整体架构
React Frontend (SPA)
/api/v1/* ←→ FastAPI Backend
13 个路由模块（conversation/sandbox/event/settings/secrets/user/git/webhook/mcp...）
Service 层（Conversation/Sandbox/Event/Config/JWT/DB）
Storage（PostgreSQL + FileStore: S3/GCS/Local）
Sandboxes（Docker / K8s / Remote / Local）
四、入口：app.py（86 行）
openhands/app_server/app.py 是整个后端的入口，结构清晰：
# app.py 第 54-72 行
app = FastAPI(
title='OpenHands',
description='OpenHands: Code Less, Make More',
version=get_version(),
lifespan=combine_lifespans(*lifespans),
routes=[Mount(path='/mcp', app=mcp_app)],
)
app.include_router(v1_router.router)
app.include_router(health_router)
if os.getenv('SERVE_FRONTEND') == 'true':
app.mount('/', SPAStaticFiles(...))关键设计：
🔹 combine_lifespans 合并 MCP 服务器和应用生命周期
🔹 三个中间件：CORS → CacheControl → RateLimit（10 req/s）
🔹 SPA 静态文件服务，非 API 路径回退到 index.html
五、13 个路由模块
所有 V1 API 挂载在 /api/v1，由 v1_router.py（37 行）组装：
router.include_router(event_router) # 事件
router.include_router(app_conversation_router) # 会话
router.include_router(sandbox_router) # 沙箱
router.include_router(settings_router) # 设置
router.include_router(secrets_router) # 密钥
router.include_router(user_router) # 用户
router.include_router(skills_router) # 技能
router.include_router(webhook_router) # Webhook
router.include_router(web_client_router) # Web 客户端
router.include_router(git_router) # Git 集成
router.include_router(config_router) # 配置六、核心目录
| 目录 | 职责 |
|---|---|
| app_conversation/ | 会话管理（创建/搜索/导出） |
| sandbox/ | 沙箱隔离（Docker/K8s/远程） |
| event/ | 事件溯源（日志/存储/持久化） |
| event_callback/ | Webhook 回调系统 |
| settings/ | LLM/Agent 配置管理 |
| services/ | 依赖注入/DB/JWT |
| mcp/ | MCP 协议服务器 |
| file_store/ | 文件存储（本地/S3/GCS） |
七、OpenHands vs Hermes vs OpenCode
| 特性 | OpenHands | Hermes | OpenCode |
|---|---|---|---|
| 定位 | Agent 控制中心 | AI 助手框架 | PR 驱动开发 |
| 部署 | 自托管 Web 应用 | CLI + 多渠道 | CLI + GitHub |
| 沙箱 | Docker/K8s/远程 | 本地终端 | GitHub Runner |
| 多 Agent | ✅ ACP 协议 | ✅ 委托系统 | ❌ |
| 事件溯源 | ✅ 完整实现 | ❌ | ❌ |
| 断点续跑 | ✅ 原生支持 | ✅ 会话持久化 | ❌ |
八、本系列学习路线
一、架构总览（第 1-3 讲）
🔹 第 1 讲：整体架构与定位 ← 本篇
🔹 第 2 讲：V0 → V1 → Agent Canvas 演进
🔹 第 3 讲：依赖注入与服务架构
二、核心引擎（第 4-8 讲）
🔹 沙箱隔离 / 事件溯源 / 断点续跑 / 会话管理 / 配置管理
三、重型任务（第 9-12 讲）
🔹 长任务调度 / Webhook / 密钥管理 / Git 集成
四、AI Agent 核心（第 13-17 讲）
🔹 Agent Server / LLM 抽象 / 工具系统 / 技能系统 / ACP Agent
五、企业级（第 18-20 讲）
🔹 企业版 / 遥测 / 部署与安全
← 系列首篇 | 下一篇：V0 → V1 → Agent Canvas 演进 →
📡 关注公众号「AI技术推荐官」
每天一篇深度源码解析，带你读懂 AI 工具的底层实现