本页面向初次接触 ATOM01-Train 的开发者，目标是在本地 Linux 环境中完成从零依赖到成功运行第一段训练指令的完整通路。阅读完本文后，你将能够安装所有必要组件、验证环境注册状态，并启动第一个强化学习训练任务。如需了解各算法背后的设计思想，请参阅后续的 深入解析 章节；若已准备好训练完整策略，可跳转到 训练你的第一个策略。

技术栈与前置条件

ATOM01-Train 建立在 NVIDIA Isaac 生态之上，采用 Isaac Sim 5.1.0 作为物理模拟后端，Isaac Lab 2.3.2 提供环境编排与向量化接口，RSL-RL 3.3.0 作为策略学习框架。三者的版本兼容性直接决定了脚本能否正常启动，因此建议严格跟随下表所列版本进行安装。操作系统方面，仓库主要面向 Linux 64 位平台开发，Python 版本要求为 3.11。由于 Isaac Sim 对 GPU 驱动有明确依赖，请确保已安装支持 CUDA 的 NVIDIA 显卡及对应驱动。

Sources: README_CN.md

仓库结构与子模块关系

项目采用双模块隔离架构：robolab 负责机器人环境、任务定义与 Sim2Sim 部署脚本；rsl_rl 负责算法实现与训练管线。二者以 Git 子模块形式嵌入主仓库，这意味着克隆后必须额外执行子模块初始化才能获取完整代码。下图展示了仓库的顶层结构以及两个子模块的职责边界。

graph TD
    A[atom01_train 主仓库] --> B[robolab 子模块]
    A --> C[rsl_rl 子模块]
    B --> D[任务环境定义<br/>direct / manager_based]
    B --> E[训练与测试脚本<br/>scripts/rsl_rl]
    B --> F[Sim2Sim 部署<br/>scripts/mujoco]
    B --> G[机器人资产与运动数据<br/>data/]
    C --> H[PPO / AMP / Distillation 算法]
    C --> I[Runner 与网络模块]

主仓库本身没有额外的 Python 安装包定义，真正的依赖声明分布在两个子模块中。robolab/setup.py 声明了 MuJoCo 相关依赖与系统工具库，rsl_rl/pyproject.toml 声明了 PyTorch 生态与 ONNX 导出所需依赖。安装时必须分别进入两个子目录执行可编辑安装（pip install -e .），以便后续修改代码时无需重复安装。

Sources: .gitmodules, robolab/setup.py, rsl_rl/pyproject.toml

分步安装指南

下图展示了从裸机环境到跑通验证命令的完整流程。建议按顺序执行，并在每一步结束后检查提示信息，避免遗漏子模块初始化或 Isaac Lab 环境激活。

flowchart TD
    Start([开始]) --> A[安装 Isaac Lab<br/>推荐 conda 方式]
    A --> B[克隆 atom01_train<br/>独立于 IsaacLab 目录之外]
    B --> C[初始化子模块<br/>git submodule update --init --recursive]
    C --> D[安装 robolab<br/>cd robolab && pip install -e .]
    D --> E[安装 rsl_rl<br/>cd rsl_rl && pip install -e .]
    E --> F[验证环境注册<br/>python robolab/scripts/tools/list_envs.py]
    F --> G{输出环境列表?}
    G -->|是| H([安装完成])
    G -->|否| I[检查 Isaac Lab 与<br/>Python 解释器路径]

第一步：安装 Isaac Lab

ATOM01-Train 并不内置 Isaac Sim 或 Isaac Lab，而是依赖外部已安装的 Isaac Lab Python 环境。官方推荐使用 conda 安装，因为它能简化从终端调用 Python 脚本的过程，并且便于管理 isaaclab 虚拟环境。具体流程请参考 Isaac Lab 官方安装指南。安装完成后，请确保在后续所有步骤中都激活了该 conda 环境。

第二步：克隆主仓库

请在 IsaacLab 目录之外 执行克隆，避免路径嵌套导致模块导入异常。

git clone https://github.com/Roboparty/atom01_train.git
cd atom01_train

第三步：初始化子模块

由于 robolab 和 rsl_rl 以子模块形式托管，克隆后子模块目录默认为空，必须手动拉取。

git submodule update --init --recursive

第四步：安装 robolab

进入子模块目录并执行可编辑安装。此步骤会同时安装 MuJoCo 3.3.3、psutil、joblib 等依赖，为后续的 Sim2Sim 与工具脚本做准备。

cd robolab
pip install -e .
cd ..

第五步：安装 rsl_rl

同样使用可编辑安装。该模块依赖 PyTorch 2.6.0+ 与 tensordict，若你的 Isaac Lab 环境已包含 PyTorch，则大多数情况下无需额外下载。

cd rsl_rl
pip install -e .
cd ..

第六步：验证安装

运行环境列表脚本，若输出包含以 Atom01 开头的多个任务名称，则说明扩展包注册成功。

python robolab/scripts/tools/list_envs.py

该脚本会启动一个 headless 的 Isaac Sim 实例，遍历所有注册到 gymnasium 的环境并打印成表格。初次运行时可能需要数分钟完成着色器编译，请耐心等待。

Sources: README_CN.md, robolab/scripts/tools/list_envs.py

已注册环境一览

验证通过后，你可以在输出中看到如下环境。下表总结了各环境名称、所属架构类型及适用场景，方便初学者根据目标选择正确的 --task 参数。

每个环境都在各自包的 __init__.py 中通过 gym.register 完成注册，并关联了对应的配置入口点（env_cfg_entry_point）与智能体配置入口点（rsl_rl_cfg_entry_point）。这意味着运行脚本时，--task 参数只需填写上表中的 id，Hydra 会自动解析并加载对应配置。

Sources: robolab/robolab/tasks/direct/base/init.py, robolab/robolab/tasks/direct/attn_enc/init.py, robolab/robolab/tasks/direct/interrupt/init.py, robolab/robolab/tasks/manager_based/amp/init.py, robolab/robolab/tasks/manager_based/beyondmimic/init.py

启动你的第一次训练

环境就绪后，只需一条命令即可启动训练。以下示例使用 Atom01-Flat 任务，开启 8192 个并行环境，以 headless 模式在后台运行，并通过 TensorBoard 记录日志。

python robolab/scripts/rsl_rl/train.py \
    --task=Atom01-Flat \
    --headless \
    --logger=tensorboard \
    --num_envs=8192

训练脚本的核心流程如下：首先通过 AppLauncher 启动 Isaac Sim，随后使用 hydra_task_config 根据 --task 与 --agent 解析环境与算法配置，接着用 gym.make 创建向量化环境并包裹为 RslRlVecEnvWrapper，最后根据配置中的 class_name 实例化 OnPolicyRunner、AMPRunner 或 DistillationRunner 并进入学习循环。所有日志、模型检查点和配置快照默认保存在 logs/rsl_rl/<experiment_name>/<timestamp>/ 目录下。

Sources: robolab/scripts/rsl_rl/train.py

训练参数速查

训练脚本 train.py 与测试脚本 play.py 共享一部分命令行参数，同时也各自具备专属参数。初学者最常修改的参数如下表所示。

完整的参数定义与更新逻辑可在 cli_args.py 中查看。若需要覆盖算法层面的超参数（如学习率、网络层数），建议直接修改对应任务 agents/ 目录下的配置类，而非通过命令行传入。

Sources: robolab/scripts/rsl_rl/cli_args.py

测试与模型回放

训练完成后，可使用 play.py 加载最新检查点并在可视化窗口中观察策略表现。该脚本会自动导出策略为 JIT 与 ONNX 格式，便于后续 Sim2Sim 部署。

python robolab/scripts/rsl_rl/play.py \
    --task=Atom01-Flat \
    --num_envs=1

常用测试参数包括 --plane（强制使用平地地形）、--push_robot（在运行中施加扰动）以及 --real-time（尽可能按真实时间步长渲染）。首次测试时建议保持 num_envs=1，以确保可视化界面流畅。

Sources: robolab/scripts/rsl_rl/play.py

下一步

至此，你已经完成了环境搭建、安装验证与首次训练启动。建议按照以下路径继续深入：

1. 若要理解项目目录组织与代码阅读顺序，请阅读 项目结构导读。
2. 若准备系统性地训练并调优第一个可部署策略，请阅读 训练你的第一个策略。
3. 若对 Sim2Sim 迁移到 MuJoCo 感兴趣，请阅读 策略测试与 Sim2Sim 部署。