运行时系统

相关源文件

• frontend/src/components/features/diff-viewer/file-diff-viewer.tsx
• openhands/core/config/sandbox_config.py
• openhands/events/nested_event_store.py
• openhands/runtime/action_execution_server.py
• openhands/runtime/base.py
• openhands/runtime/file_viewer_server.py
• openhands/runtime/impl/action_execution/action_execution_client.py
• openhands/runtime/impl/cli/cli_runtime.py
• openhands/runtime/impl/docker/docker_runtime.py
• openhands/runtime/impl/local/local_runtime.py
• openhands/runtime/impl/modal/modal_runtime.py
• openhands/runtime/impl/remote/remote_runtime.py
• openhands/runtime/impl/runloop/runloop_runtime.py
• openhands/runtime/plugins/agent_skills/utils/dependency.py
• openhands/runtime/utils/command.py
• openhands/runtime/utils/git_handler.py
• openhands/runtime/utils/log_streamer.py
• openhands/runtime/utils/memory_monitor.py
• openhands/runtime/utils/system.py
• openhands/server/__main__.py
• openhands/server/conversation_manager/docker_nested_conversation_manager.py
• tests/unit/test_git_handler.py
• tests/unit/test_git_handler_real.py
• tests/unit/test_log_streamer.py
• tests/unit/test_nested_event_store.py
• tests/unit/test_runtime_git_tokens.py

运行时系统为 OpenHands 代理的安全代码执行提供了沙箱执行环境。它实现了一个抽象层，允许代理在本地开发、容器化环境和云平台等多种部署场景下的隔离环境中执行 shell 命令、读写文件、浏览网页和运行代码。

有关特定运行时实现的信息，请参阅 运行时实现。有关沙箱环境中操作执行的详细信息，请参阅 操作执行服务器。有关运行时镜像构建和模板化，请参阅 运行时构建。

架构概述

运行时系统遵循客户端-服务器架构，其中 OpenHands 后端通过 HTTP API 与隔离的沙箱环境通信。每个运行时实现都提供安全隔离，同时为代理交互维护一致的接口。

运行时系统架构

来源：openhands/runtime/base.py92-121 openhands/runtime/impl/action_execution/action_execution_client.py59-95 openhands/runtime/action_execution_server.py166-214

运行时类层次结构

运行时系统使用继承来提供一致的接口，同时允许针对不同部署环境的专业化实现。

运行时继承结构

来源：openhands/runtime/base.py92-121 openhands/runtime/impl/action_execution/action_execution_client.py59-95 openhands/runtime/impl/docker/docker_runtime.py63-135 openhands/runtime/impl/remote/remote_runtime.py37-102

Action 执行流程

运行时系统实现了一个操作-观察模式，代理在该模式下发送要在沙箱环境中执行的操作，并接收包含结果的观察。

Action 执行流程

来源：openhands/runtime/impl/action_execution/action_execution_client.py269-331 openhands/runtime/action_execution_server.py384-439 openhands/runtime/utils/bash.py1-50

运行时实现

该系统支持多种运行时实现，以支持不同的部署场景和安全要求。

运行时	用例	隔离性	网络访问
DockerRuntime	生产部署	完全容器隔离	可配置
RemoteRuntime	云原生部署	远程沙箱隔离	API 控制
LocalRuntime	开发/测试	进程隔离	主机网络
CLIRuntime	直接执行	无隔离	完全主机访问
ModalRuntime	无服务器执行	Modal 沙箱隔离	托管

ActionExecutionClient 基类

使用基于 HTTP 的操作执行服务器的运行时实现继承自 ActionExecutionClient，它提供了

• 通过 HttpSession 进行的 HTTP 会话管理
• 通过 event_to_dict() 进行的操作序列化
• 通过 observation_from_dict() 进行的观察反序列化
• 文件传输操作（copy_from(), copy_to()）
• 健康检查（check_if_alive()）
• VSCode 集成（get_vscode_token()）

来源：openhands/runtime/impl/action_execution/action_execution_client.py66-95 openhands/runtime/impl/docker/docker_runtime.py63-135 openhands/runtime/impl/remote/remote_runtime.py37-102

关键接口和协议

运行时接口

基础 Runtime 类定义了所有实现必须提供的核心接口

ActionExecutionServer API

沙箱环境中运行的 ActionExecutionServer 公开 HTTP 端点

• POST /execute_action - 执行操作并返回观察结果
• GET /alive - 健康检查端点
• POST /list_files - 列出沙箱中的文件
• GET /download_files - 从沙箱下载文件
• POST /upload_file - 上传文件到沙箱
• GET /vscode/connection_token - 获取 VSCode 身份验证令牌

来源：openhands/runtime/base.py850-876 openhands/runtime/action_execution_server.py1-75

环境管理

运行时系统通过多种机制管理沙箱环境

环境变量

运行时使用以下项初始化环境

• 通过 _default_env_vars() 设置的默认沙箱环境变量
• 来自 config.sandbox.runtime_startup_env_vars 的用户提供环境变量
• 通过 ProviderHandler 设置的 Git 提供程序令牌
• 插件特定的环境变量

工作区配置

工作区挂载是通过以下项配置的

• config.workspace_mount_path - 主机目录路径
• config.workspace_mount_path_in_sandbox - 沙箱挂载点（通常是 /workspace）
• config.workspace_base - 工作区操作的基础目录

初始设置

setup_initial_env() 方法

1. 将环境变量添加到 bash 会话
2. 配置 IPython 环境以进行 Jupyter 集成
3. 设置 git 配置
4. 初始化插件环境

来源：openhands/runtime/base.py195-202 openhands/runtime/base.py230-304 openhands/core/config/sandbox_config.py6-119

插件系统

运行时系统支持插件架构以扩展功能

插件要求

插件通过 PluginRequirement 对象指定，该对象定义了

• 插件名称和版本要求
• 依赖关系和安装要求
• 配置参数

内置插件

常见的插件包括

• JupyterRequirement - IPython/Jupyter notebook 支持
• VSCodeRequirement - VSCode 服务器集成
• AgentSkillsRequirement - 附加代理功能
• BrowserRequirement - 网页浏览功能

插件初始化

ActionExecutionServer 在启动时初始化插件

1. 从运行时配置加载插件要求
2. 通过 plugin.initialize() 初始化每个插件
3. 设置插件特定的环境变量
4. 配置插件集成（例如，IPython 内核设置）

来源： openhands/runtime/plugins/__init__.py1-50 openhands/runtime/action_execution_server.py316-328 openhands/runtime/base.py154-157

安全考量

运行时系统实现了多项安全措施

沙箱隔离

• Docker 隔离：完全容器隔离，具有可配置的资源限制
• 远程沙箱：通过 API 控制的隔离远程环境访问
• 进程隔离：用于开发场景的本地进程隔离
• 无隔离：仅用于受信任环境的直接执行

网络控制

• 通过 use_host_network 设置配置网络访问
• 通过 runtime_binding_address 限制端口绑定
• 用于远程运行时通信的 API 密钥认证

文件系统保护

• 工作区目录挂载，具有读/写控制
• 路径验证，防止目录遍历
• 二进制文件检测，防止执行恶意文件

资源限制

• 通过 max_memory_gb 配置内存限制
• 操作执行超时控制
• 通过 Docker 运行时参数限制容器资源

来源： openhands/core/config/sandbox_config.py6-119 openhands/runtime/impl/docker/docker_runtime.py268-387 openhands/runtime/action_execution_server.py94-97