OpenEnv: 智体执行环境

一个用于创建、部署和使用隔离执行环境的端到端框架，专为智体强化学习训练设计，基于 Gymnasium 风格的简单 API 构建。

---

🚀 精选示例: 使用 torchforge（PyTorch 的智体强化学习框架）训练大语言模型玩二十一点：examples/grpo_blackjack/

🔥 从零到英雄教程: 来自我们 GPU 模式 讲座及其他黑客马拉松的端到端教程。

快速入门

安装 OpenEnv 核心包：

pip install openenv-core

安装一个环境客户端（例如 Echo）：

pip install git+https://huggingface.co/spaces/openenv/echo_env

然后使用该环境：

import asyncio
from echo_env import CallToolAction, EchoEnv

async def main():
    # 连接到正在运行的空间（异步上下文管理器）
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        # 重置环境
        result = await client.reset()
        print(result.observation.echoed_message)  # "Echo environment ready!"

        # 发送消息
        result = await client.step(
            CallToolAction(
                tool_name="echo_message",
                arguments={"message": "Hello, World!"},
            )
        )
        print(result.observation.result)  # "Hello, World!"
        print(result.reward)

asyncio.run(main())

同步使用同样支持，只需通过 .sync() 包装器即可：

from echo_env import CallToolAction, EchoEnv

# 使用 .sync() 进行同步上下文管理
with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
    result = client.reset()
    result = client.step(
        CallToolAction(
            tool_name="echo_message",
            arguments={"message": "Hello, World!"},
        )
    )
    print(result.observation.result)

如需详细的快速入门指南，请查看 文档页面。

OpenEnv 在合作平台上的应用：

• Lightning AI Studio
• TRL 示例
• Unsloth Google Colab
• ART 示例
• Oumi 示例

概述

OpenEnv 提供了一套标准接口，允许用户通过简单的 Gymnasium 风格 API——step()、reset()、state()——与智体执行环境进行交互。研究人员和强化学习框架开发者可以利用这些简单 API，在强化学习训练循环中与环境互动。

除了便于研究者和框架开发者使用外，我们还为环境创建者提供了工具，帮助他们构建更丰富的环境，并通过 HTTP 等常见协议发布，同时采用 Docker 等标准化技术进行封装。环境创建者可以借助 OpenEnv 框架，打造隔离、安全且易于部署和使用的环境。

OpenEnv 命令行工具 (openenv) 提供了初始化新环境并将其部署到 Hugging Face Spaces 的命令。

⚠️ 早期开发警告 OpenEnv 目前仍处于实验阶段。您可能会遇到一些 bug、功能不完整的情况，以及未来版本中可能发生变化的 API。项目欢迎提交 bug 修复，但为了确保协调一致，建议在开始工作之前先讨论任何重大变更。推荐您在问题追踪器中表明您的贡献意向，可以通过新建问题或认领现有问题来实现。

RFC 文档

以下是 OpenEnv 当前及历史上的 RFC 列表。RFC 是针对重大更改或功能的提案。请查阅并积极参与贡献！

• RFC 001：基础 API 和接口规范
• RFC 002：智能体发现环境工具的能力
• RFC 003：添加 MCP（模型上下文协议）支持
• RFC 004：为基于轨迹的评分添加延迟奖励支持
• RFC 005：集成智体 Harness

架构

组件概览

┌─────────────────────────────────────────────────────────┐
│                    客户端应用                   │
│  ┌────────────────┐              ┌──────────────────┐   │
│  │  EchoEnv       │              │  CodingEnv       │   │
│  │  (环境客户端)   │              │   (环境客户端)    │   │
│  └────────┬───────┘              └────────┬─────────┘   │
└───────────┼───────────────────────────────┼─────────────┘
            │ WebSocket                     │ WebSocket
            │ (重置、步骤、状态)          │
┌───────────▼───────────────────────────────▼─────────────┐
│              Docker 容器（隔离）               │
│  ┌──────────────────────┐    ┌──────────────────────┐   │
│  │ FastAPI 服务器       │    │ FastAPI 服务器       │   │
│  │   EchoEnvironment    │    │ PythonCodeActEnv     │   │
│  │ (环境基础)           │    │ (环境基础)           │   │
│  └──────────────────────┘    └──────────────────────┘   │
└─────────────────────────────────────────────────────────┘

核心组件

1. Web 界面

OpenEnv 内置了一个用于交互式环境探索和调试的 Web 界面。该 Web 界面提供以下功能：

• 双面板布局：左侧为 HumanAgent 交互，右侧为状态观测
• 实时更新：基于 WebSocket 的实时更新，无需页面刷新
• 动态表单：根据环境的 Action 类型自动生成操作表单
• 操作历史：完整记录所有执行的操作及其结果

Web 界面会根据环境变量进行条件性启用：

• 本地开发：默认禁用，以实现轻量级开发
• 手动覆盖：通过设置 ENABLE_WEB_INTERFACE=true 来启用

使用 Web 界面的方法如下：

from openenv.core.env_server import create_web_interface_app
from your_env.models import YourAction, YourObservation
from your_env.server.your_environment import YourEnvironment

env = YourEnvironment()
app = create_web_interface_app(env, YourAction, YourObservation)

启用后，在浏览器中打开 http://localhost:8000/web 即可与环境进行交互。

2. 环境（服务器端）

用于实现环境逻辑的基类：

• reset()：初始化新 episode，返回初始 Observation
• step(action)：执行一个 Action，返回结果 Observation
• state()：访问 episode 元数据（包含 State、episode_id、step_count 等）

3. EnvClient（客户端）

用于环境通信的基类：

• 默认异步：所有操作均使用 async with 和 await
• 同步包装器：调用 .sync() 可获得用于同步使用的 SyncEnvClient
• 处理与环境服务器的 WebSocket 连接
• 包含在本地启动对应环境 Docker 容器的工具
• 类型安全的操作/观测解析

4. 容器提供商

负责管理容器部署：

• LocalDockerProvider：在本地 Docker 守护进程中运行容器
• KubernetesProvider：未来支持部署到 K8s 集群

5. 模型

类型安全的数据结构：

• Action：环境动作的基类
• Observation：环境观测的基类
• State：episode 状态跟踪
• StepResult：结合观测、奖励和完成标志

项目结构

针对环境创建者

使用 CLI 快速搭建新环境：

openenv init my_env

这将创建如下结构：

my_env/
├── .dockerignore        # Docker 构建排除文件
├── __init__.py           # 导出 YourAction、YourObservation、YourEnv
├── models.py             # 定义 Action、Observation、State 数据类
├── client.py             # 实现 YourEnv(EnvClient)
├── README.md             # 记录环境文档
├── openenv.yaml          # 环境清单文件
├── pyproject.toml        # 依赖项和包配置
├── outputs/              # 运行时输出（日志、评估） - 被 git 忽略
│   ├── logs/
│   └── evals/
└── server/
    ├── your_environment.py  # 实现 YourEnvironment(Environment)
    ├── app.py               # 创建 FastAPI 应用
    ├── requirements.txt     # Docker 构建所需的依赖项（可自动生成）
    └── Dockerfile           # 定义容器镜像

依赖管理

OpenEnv 使用 pyproject.toml 作为主要的依赖规范：

• 环境级别的 pyproject.toml：每个环境定义自己的依赖
• 根级别的 pyproject.toml：包含共享的核心依赖（fastapi、pydantic、uvicorn）
• 服务器的 requirements.txt：可从 pyproject.toml 自动生成，用于 Docker 构建

开发工作流：

# 以可编辑模式安装环境
cd my_env
pip install -e .

# 或使用 uv（更快）
uv pip install -e .

# 在本地无 Docker 运行服务器
uv run server --host 0.0.0.0 --port 8000

优势：

• ✅ 客户端扩展：可在本地修改客户端类，无需更改仓库
• ✅ 更好的依赖管理：清晰分离各个环境
• ✅ 灵活的工作流程：可根据不同场景使用 pip、uv 或 Docker
• ✅ CI/CD 就绪：自动化依赖生成和验证

有关构建环境的完整指南，请参阅 envs/README.md。

针对环境使用者

使用环境的步骤如下：

1. 安装客户端：pip install git+https://huggingface.co/spaces/openenv/echo-env
2. 导入：from echo_env import CallToolAction, EchoEnv
3. 使用异步（推荐）或同步 API：

异步（推荐）：

async with EchoEnv(base_url="...") as client:
    result = await client.reset()
    result = await client.step(action)

同步（通过 .sync() 包装器）：

with EchoEnv(base_url="...").sync() as client:
    result = client.reset()
    result = client.step(action)

示例脚本请参见 examples/ 目录。

CLI 命令

OpenEnv 的 CLI 提供了用于管理环境的命令：

• openenv init <env_name>：从模板初始化新环境
• openenv push [--repo-id <repo>] [--private]：将环境部署到 Hugging Face Spaces

快速入门

# 创建新环境
openenv init my_game_env

# 部署到 Hugging Face（如需，会提示登录）
cd my_game_env
openenv push

详细选项请参考：openenv init --help 和 openenv push --help。

设计原则

1. 关注点分离：清晰的客户端-服务器边界
2. 类型安全：强类型的动作、观测和状态
3. 容器隔离：每个环境运行在独立的容器中
4. 简单 API：最小化、直观的接口

开发

安装

# 克隆仓库
git clone https://github.com/meta-pytorch/OpenEnv.git
cd OpenEnv

# 以可编辑模式安装核心包
pip install -e .
# 或使用 uv（更快）
uv pip install -e .

运行测试

OpenEnv 采用模块化的依赖结构：核心包非常精简，而每个环境都有自己的依赖。这意味着部分测试需要特定于环境的包。

# 安装 pytest（运行测试所需）
uv pip install pytest

# 运行所有测试（跳过缺少依赖的测试）
PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short

# 运行特定测试文件
PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v

若要运行环境特定的测试，请先安装该环境的依赖：

# 示例：安装 coding_env 及其开发依赖（包括 smolagents + pytest）
uv pip install -e "envs/coding_env[dev]"

# 然后运行 coding_env 测试
PYTHONPATH=src:envs uv run pytest tests/envs/test_python_codeact_rewards.py -v

如果未安装所需依赖，测试将自动跳过。

要求

• Python 3.10+
• Docker Desktop 或 Docker 引擎
• FastAPI ≥ 0.104.0
• Uvicorn ≥ 0.24.0
• Requests ≥ 2.25.0
• 环境特定的依赖（例如，coding_env 需要 smolagents）

支持的强化学习工具

本项目的目标是支持广泛的开源和闭源工具，以帮助规范代理式强化学习社区。如果您有一个支持 OpenEnv 环境的项目，请提交一个 Pull Request，添加您的工具名称以及指向您文档的链接。

torchforge

请参阅 GRPO BlackJack 训练示例：examples/grpo_blackjack/

TRL

请参阅 TRL 示例，了解如何将 OpenEnv 环境与 GRPO 训练集成。

Unsloth

请参阅基于 gpt-oss 的 2048 游戏示例：Colab 笔记本

SkyRL

请参阅 SkyRL 示例，了解如何使用 SkyRL 在 OpenEnv 环境上进行训练。

ART

请参阅 ART 示例，了解如何使用 OpenEnv 环境通过 ART 训练模型。

Oumi

请参阅 Oumi 示例，了解如何使用 OpenEnv 环境通过 Oumi 训练模型。

示例环境

环境	描述
Echo 环境	将带有元数据的消息原样回显。非常适合测试 HTTP 服务器基础设施、学习框架基础知识以及验证容器部署。
Coding 环境	通过 smolagents 进行沙箱化的 Python 代码执行。捕获 stdout/stderr/退出码，支持持久化的剧集上下文，并提供详细的错误处理。
Chess 环境	拥有可配置对手且完全支持规则的国际象棋强化学习环境。
Atari 环境	经典的街机学习环境任务，用于强化学习基准测试。
FinRL 环境	金融市场模拟，用于算法交易实验。

请在 meta-pytorch.org/OpenEnv/environments 浏览完整的社区环境目录。

社区支持与致谢

这是一个开放且以社区为中心的项目。如果您希望在此处添加您的名字，请提交一个 Pull Request，并标记 @jspisak 进行审核。非常感谢！！

支持者包括：Meta-PyTorch、Hugging Face、Scaler AI Labs、Patronus AI、Surge AI、LastMile AI、Unsloth AI、Reflection AI、vLLM、SkyRL（UC-Berkeley）、LightningAI、Axolotl AI、斯坦福规模化智能实验室、Mithril、OpenMined、Fleet AI、Halluminate、Turing、Scale AI、Scorecard……

同时，我们也想感谢 Farama Foundation 团队，因为 OpenEnv API 在很大程度上受到了贵团队在 Gymnasium 上所做工作的启发。干杯！

许可证

BSD 3-Clause 许可证（详见 LICENSE 文件）

OpenEnv 快速上手指南

OpenEnv 是一个用于创建、部署和使用隔离执行环境的端到端框架，专为智能体（Agentic）强化学习训练设计。它提供类似 Gymnasium 的简洁 API（reset, step, state），支持异步和同步调用。

环境准备

• 操作系统: Linux, macOS, Windows (需安装 Docker Desktop)
• Python 版本: Python 3.9+
• 前置依赖:
  • pip 或 uv (推荐，速度更快)
  • Docker: 用于运行隔离的环境容器（若仅作为客户端连接远程空间可暂不安装本地 Docker）
  • Node.js (可选): 若需开发或运行内置的 Web 调试界面

提示: 国内开发者建议使用国内镜像源加速安装（如清华源、阿里源）。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

1. 安装核心包

首先安装 OpenEnv 的核心库：

pip install openenv-core

2. 安装环境客户端

选择一个具体的环境客户端进行安装。以下以官方示例 EchoEnv 为例：

pip install git+https://huggingface.co/spaces/openenv/echo_env

注意: 如果直接访问 HuggingFace 较慢，可尝试先克隆仓库到本地再安装，或使用代理加速。

基本使用

OpenEnv 推荐使用 异步 (Async) 方式调用，同时也支持通过 .sync() 包装器进行同步调用。

方式一：异步使用（推荐）

这是最标准的用法，适用于高性能并发场景。

import asyncio
from echo_env import CallToolAction, EchoEnv

async def main():
    # 连接到正在运行的 Space (使用异步上下文管理器)
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        # 重置环境
        result = await client.reset()
        print(result.observation.echoed_message)  # 输出: "Echo environment ready!"

        # 发送动作
        result = await client.step(
            CallToolAction(
                tool_name="echo_message",
                arguments={"message": "Hello, World!"},
            )
        )
        print(result.observation.result)  # 输出: "Hello, World!"
        print(result.reward)

asyncio.run(main())

方式二：同步使用

如果你习惯同步编程风格，可以使用 .sync() 方法。

from echo_env import CallToolAction, EchoEnv

# 使用 .sync() 获取同步上下文管理器
with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
    result = client.reset()
    result = client.step(
        CallToolAction(
            tool_name="echo_message",
            arguments={"message": "Hello, World!"},
        )
    )
    print(result.observation.result)

进阶：创建你自己的环境

如果你想构建自己的智能体环境，可以使用 CLI 快速 scaffold 项目：

1. 初始化项目:

   openenv init my_custom_env
   

   这将生成包含 models.py (定义动作/观察), server/ (FastAPI 服务), client.py 等标准结构的文件夹。

2. 本地运行测试:

   cd my_custom_env
   pip install -e .
   uv run server --host 0.0.0.0 --port 8000
   

3. 部署到 Hugging Face Spaces:

   openenv push
   

更多详细文档请访问 OpenEnv 官方文档。