架构

系统概览

OpenHands构建为一个分布式系统，在前端、后端服务、代理编排和运行时执行环境之间具有清晰的分离。该系统支持从本地开发到容器化生产部署的多种部署选项。

系统架构

来源

前端层

前端是一个运行在3000端口的React应用程序，为OpenHands提供了主要的用户界面。它包括聊天界面、文件浏览器、设置面板和开发工具集成。

前端架构

来源

后端服务

后端使用FastAPI构建，提供REST API端点和通过Socket.IO的WebSocket通信。它负责会话管理、对话持久化以及协调代理操作。

后端服务架构

来源

代理系统架构

代理系统实现了一个事件驱动的架构，用户输入通过代理控制器流向AI代理，AI代理生成将在沙盒运行时环境中执行的操作。

智能体执行流程

来源

配置和设置管理

OpenHands采用分层配置系统，支持具有清晰优先级的多个源。配置通过TOML文件、环境变量和运行时设置API进行管理。

配置系统架构

来源

开发与部署架构

OpenHands支持多种部署场景，从本地开发到容器化生产环境。构建系统使用Poetry管理Python依赖，使用npm管理前端包。

构建和部署管道

来源

API 与数据流架构

系统同时提供用于无状态操作的REST API和用于实时代理交互的WebSocket通信。文件操作、对话和设置通过专用的API端点进行管理。

API与通信流

来源

依赖管理

OpenHands使用Poetry进行Python依赖管理，使用npm进行前端依赖管理。该系统支持多种可选的依赖组，适用于不同的用例，如开发、测试、评估和运行时环境。

组件	依赖管理器	配置文件	关键依赖项
后端	Poetry	`pyproject.toml`	FastAPI, litellm, docker, aiohttp
前端	npm	`frontend/package.json`	React, Socket.IO, TanStack Query
运行时	Poetry	`pyproject.toml`	jupyterlab, notebook, flake8
评估	Poetry	`pyproject.toml`	streamlit, matplotlib, swebench
开发	Poetry + npm	两个文件	ruff, mypy, pre-commit, eslint

按层划分的关键依赖项

FastAPI 后端：fastapi, uvicorn, python-socketio, sse-starlette
LLM 集成：litellm, anthropic, google-generativeai, openai
代理系统：browsergym-core, tenacity, jinja2
运行时：docker, e2b, pexpect, modal, runloop-api-client
前端：react, socket.io-client, @reduxjs/toolkit, axios

来源

系统通信流

以下序列图展示了一个典型的用户交互如何流经OpenHands系统，从前端请求到代理执行和响应。

用户交互序列

来源

运行模式

OpenHands可以根据用户的需求，在几种不同的模式下运行。

Web UI 模式：主要模式，具有完整的图形界面
CLI 模式：用于终端交互的交互式命令行界面
无头模式：用于脚本和自动化的非交互式模式
GitHub Action 模式：由GitHub事件触发的自动化操作

来源

部署选项

OpenHands支持多种部署选项，从本地开发到容器化部署。

来源

错误处理和恢复

OpenHands implements a robust error handling system to manage failures in different components of the system.

来源

This architecture document provides a comprehensive overview of the OpenHands system, focusing on the key components and their interactions. For more detailed information about specific subsystems, refer to the related wiki pages linked at the beginning of this document.

架构