简介#
1. 概览#
本节介绍 UFO 的功能、两个代码分支和环境配置。完成本节后，你可以下载示例数据，并在单卡上跑通一次快速训练。
1.1 UFO 能做什么#
| 工作流 | 做什么 | 见 |
|---|---|---|
| Motion Data | 导入机器人动作数据，生成训练用的数据清单，按比例混合多个数据源 | 第 2 节 |
| Training | 用 FB 或 TeCH 预训练行为空间和全身控制策略 | 第 3 节 |
| Inference & Export | 用动作跟踪、目标到达、奖励三种方式调用策略，导出 ONNX | 第 4 节 |
| Deployment | 在 MuJoCo 中验证，部署到实机，用 PICO 遥操作 | 第 5 节 |
| New Robot | 为新机器人生成配置并训练（实验性） | 第 6 节 |
1.2 两个分支#
UFO 的代码分在两个分支，用途不同，不要互相合并：
| 分支 | 用途 | 运行在 |
|---|---|---|
main |
训练、数据导入、推理、ONNX 导出 | 带 NVIDIA GPU 的 Linux 训练机 |
deploy |
MuJoCo 仿真验证、实机部署、PICO 遥操作 | 工作站，以及机器人的机载计算单元 |
1.3 当前支持范围#
| 功能 | 状态 |
|---|---|
| 默认机器人训练 | 支持，测试最充分 |
| 动作数据格式 | RobotState CSV / NPZ、ufo_pkl |
| 多数据源混合 | 支持 |
| 动作跟踪推理 | 支持，按机器人配置运行 |
| 目标到达推理 | 支持；新机器人需要自备目标姿态文件 |
| 奖励推理 | 默认机器人支持全部默认任务；新机器人目前主要支持移动和转向类任务 |
| 实机部署与遥操作 | 使用 deploy 分支 |
| 自动动作重映射 | 不支持，需先用 hhtools 等工具重映射 |
| 同一个模型用于不同机器人 | 不支持 |
1.4 系统要求#
| 项目 | main（训练） |
deploy（部署） |
|---|---|---|
| 操作系统 | Linux | 工作站：Linux；机器人：机载计算单元 |
| Python | 3.10（由 uv 管理） | 3.10（工作站用 Conda，机器人用 venv） |
| GPU | NVIDIA GPU；快速测试单卡即可，正式训练示例使用 8 卡 | 可选，用于实时计算隐变量 z |
| 主要依赖 | MJLab 1.4.0、MuJoCo 3.8、PyTorch 2.7 | MuJoCo、ONNX Runtime、pyzmq |
据 UFO 技术报告，FB 在 8 张 H200 上训练约 6 小时，8 张 RTX 4090 也可以训练。
1.5 安装（main 分支）#
克隆仓库：
git clone https://github.com/Roboparty/UFO.git
cd UFO安装 uv：
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env安装项目环境：
uv sync可选：W&B 日志。 如需在 Weights & Biases 中查看训练曲线，先登录，然后在训练命令中加入 --use-wandb --wandb-run-name <名称>：
uv run wandb login
export WANDB_ENTITY=your_entity # 可选1.6 下载示例数据#
动作数据不放在 Git 仓库中。下载默认的 LaFAN 示例数据：
bash scripts/download_data.sh脚本会从 Hugging Face 下载两个文件，并校验 SHA-256：
| 文件 | 用途 |
|---|---|
humanoidverse/data/lafan_29dof_10s-clipped.pkl |
训练用，动作切成约 10 秒的片段 |
humanoidverse/data/lafan_29dof.pkl |
推理用，完整动作序列 |
1.7 跑通快速测试#
./run_train.sh \
--agent fb \
--data-manifest configs/data/example_mix.yaml \
--gpu-ids single \
--smoke \
--work-dir /tmp/ufo_smoke--smoke 使用 16 个并行环境、2048 步，不连接 W&B，用来确认环境和数据都能正常加载，不代表训练效果。
1.8 输出目录#
训练和推理的结果都写在 --work-dir 指定的目录中：
<work-dir>/
├── checkpoint/ # 最新的模型，每隔一段步数覆盖保存
│ ├── config.json
│ ├── train_status.json
│ └── buffers/ # 回放池，奖励推理需要用到
├── tracking_inference/ # 动作跟踪推理的结果和导出的 ONNX
├── goal_inference/ # 目标到达推理的结果
└── reward_inference/ # 奖励推理的结果run_train.sh 还会根据 --work-dir 自动建立一个 cache/ 目录（例如 runs/ufo_fb 对应仓库下的 cache/），存放 uv、PyTorch、Triton、Warp 等的缓存；也可以用环境变量 UFO_CACHE_DIR 指定位置。
2. 动作数据#
本节把机器人动作数据导入 UFO，生成训练用的数据清单，并介绍如何按比例混合多个数据源。
注意 UFO 不做动作重映射。人体动作或其他机器人的动作，需要先用 hhtools、GMR 或自己的重映射流程，转换成目标机器人的关节轨迹，再导入 UFO。
2.1 支持的格式#
UFO 推荐的导入格式是 RobotState：每一帧包含根部位置 root_pos、根部朝向 root_quat 和各关节角 dof_pos，再加上帧率 fps 或时间列 time。
| 格式名 | 内容 | 适用 |
|---|---|---|
robot_state_csv |
RobotState 的 CSV 文件 | 新数据集，推荐 |
robot_state_npz |
RobotState 的 NPZ 文件 | 新数据集，推荐 |
ufo_pkl |
已经转换好的 UFO 内部格式 | UFO 工具或现有流程生成的数据，例如示例数据 |
CSV 的列： 无表头时，依次为根部位置（x, y, z）、根部四元数（x, y, z, w），然后是各关节角，顺序与 MuJoCo XML 中受控关节的顺序一致；最前面可以加一列时间。有表头时，可以在数据清单中用 columns 指定每一项对应哪些列（见 configs/data/example_robot_state_auto_build.yaml）。
2.2 检查数据#
导入前，先检查数据和机器人配置是否匹配：
uv run python -m humanoidverse.tools.data_inspect \
--robot configs/robots/<机器人>.yaml \
--source "/path/to/motions/*.csv" \
--format robot_state_csv \
--fps 50--robot 填 configs/robots/ 下对应机器人的配置文件；新机器人的配置按第 6 节生成。
2.3 生成数据清单#
uv run python -m humanoidverse.tools.data_build \
--robot configs/robots/<机器人>.yaml \
--source "/path/to/motions/*.csv" \
--format robot_state_csv \
--name my_motion \
--fps 50 \
--clip-seconds 10 \
--out configs/data/my_motion_auto_build.yaml \
--rebuild-cache这一步会生成：
数据清单 YAML（
--out指定的位置），训练和推理都通过它读取数据；完整动作的 pkl，用于推理；
切成约 10 秒片段的 pkl，用于训练。
2.4 混合多个数据源#
数据清单可以列出多个数据源，并给每个数据源设置采样权重：
datasets:
- name: lafan
format: ufo_pkl
train_path: /path/to/lafan_29dof_10s-clipped.pkl
inference_path: /path/to/lafan_29dof.pkl
weight: 0.95
- name: cartwheel
format: ufo_pkl
train_path: /path/to/cartwheel_near10s.pkl
inference_path: /path/to/cartwheel_near10s.pkl
weight: 0.05数据源之间 按权重固定比例采样；每个数据源内部 优先采样策略跟踪失败的动作。
这适合在保持基础动作分布的同时，注入少量稀有的高难度技能，例如用 5% 的侧手翻数据教会策略侧手翻。
train_path用于训练，inference_path用于推理。注入侧手翻这类动作时，可以在训练命令中加上
--cartwheel-aux-safe，它会去掉与行走相关的接触和脚型惩罚，并减小动作变化率惩罚。
也可以不写清单，直接在训练命令中给出多个文件和权重：--data-path a.pkl b.pkl --data-mix-weights 0.95 0.05。
注意
每个数据源的名称必须唯一；权重必须是非负的有限数，且总和大于 0。
RobotState 导入不会重新采样帧率，请保证
--fps与数据实际一致。目前只支持转动关节（hinge）。
3. 训练#
本节用 FB 或 TeCH 训练策略。训练在 main 分支上进行，由 run_train.sh 启动。
3.1 FB 与 TeCH#
| FB | TeCH | |
|---|---|---|
| 来源 | 复现并改进 BFM-Zero | RoboParty Lab 提出 |
| 思路 | 估计“按某个 z 执行下去，将来会到达哪些状态”，策略选择让到达目标最多的动作 | 让隐空间中的距离对应到达所需的步数，离目标更近就给正奖励 |
| 能做的推理 | 动作跟踪、目标到达、奖励推理 | 动作跟踪、目标到达 |
| 隐变量更新间隔默认值 | 每 100 步 | 每 10 步 |
TeCH 在早期版本中叫 TLDR，--agent tldr 仍可使用，但会提示已弃用。
3.2 训练命令#
FB：
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
./run_train.sh \
--agent fb \
--gpu-ids all \
--num-envs 1024 \
--num-env-steps 192000000 \
--work-dir runs/ufo_fb \
--data-path humanoidverse/data/lafan_29dof_10s-clipped.pkl \
--update-z-every-step 100 \
--buffer-size 5120000TeCH：
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
./run_train.sh \
--agent tech \
--gpu-ids all \
--num-envs 1024 \
--num-env-steps 192000000 \
--work-dir runs/ufo_tech \
--data-path humanoidverse/data/lafan_29dof_10s-clipped.pkl \
--update-z-every-step 10 \
--buffer-size 5120000使用自己的数据时，把 --data-path 换成 --data-manifest <清单路径>。
3.3 默认参数#
| 参数 | 默认值 | 说明 |
|---|---|---|
--num-envs |
1024 | 每张 GPU 的并行环境数 |
--num-env-steps |
192,000,000 | 所有 GPU 合计的环境步数 |
--checkpoint-every-steps |
3,200,000 | 每隔多少步保存一次模型 |
--buffer-size |
5,120,000 | 每张 GPU 的回放池容量 |
--update-z-every-step |
FB 100 / TeCH 10 | 每隔多少步重新采样一次隐变量 z |
--data-path |
humanoidverse/data/lafan_29dof_10s-clipped.pkl |
训练数据 |
--work-dir |
runs/ufo |
输出目录 |
3.4 常用参数#
| 参数 | 作用 |
|---|---|
--gpu-ids |
single（单卡）、all（CUDA_VISIBLE_DEVICES 中的全部 GPU），或逗号分隔的编号 |
--data-manifest |
使用数据清单，不能与 --data-path 同时使用 |
--rebuild-motion-cache |
重新生成数据清单对应的动作缓存 |
--robot-config |
机器人配置，默认使用仓库自带的配置；适配新机器人时使用（见第 6 节） |
--num-agent-updates |
每次更新的优化步数。改变每卡环境数做对比实验时，2048 个环境用 32、4096 个环境用 64，可与默认 1024 个环境的更新密度对齐 |
--disable-dr / --disable-obs-noise |
关闭域随机化 / 观测噪声 |
--lr-scale / --clip-grad-norm |
调整 FB 的学习率 / 开启梯度裁剪（TeCH 不使用） |
--cartwheel-aux-safe |
注入侧手翻等技能时使用（见 2.4 节） |
--seed |
随机种子，默认 4728 |
--use-wandb / --wandb-run-name |
开启 W&B 日志 |
--smoke |
快速测试 |
3.5 训练过程中保存什么#
模型保存在 <work-dir>/checkpoint/，每隔 --checkpoint-every-steps 步覆盖一次，同时保存回放池（checkpoint/buffers/）。奖励推理需要从回放池中采样状态，所以不要删除这个目录。
4. 推理 & 导出#
本节用训练好的模型做三种推理，并导出部署用的 ONNX。三种推理对应三种给出任务的方式：
| 推理方式 | 任务怎么给 | 入口 |
|---|---|---|
| 动作跟踪 | 一段参考动作 | humanoidverse.tracking_inference |
| 目标到达 | 一组目标姿态 | humanoidverse.goal_inference |
| 奖励推理 | 一个奖励函数，例如“向前走 0.7 m/s” | humanoidverse.reward_inference |
三种推理都在 MuJoCo 中运行，可以用 --save-mp4 保存视频；--disable-dr 和 --disable-obs-noise 用于关闭随机化和观测噪声，便于观察策略本身的表现。
4.1 动作跟踪#
CUDA_VISIBLE_DEVICES=0 \
uv run python -m humanoidverse.tracking_inference \
--model-folder runs/ufo_fb \
--data-path humanoidverse/data/lafan_29dof.pkl \
--device cuda:0 \
--headless \
--save-mp4 \
--motion-list 0请使用完整的动作序列（例如
lafan_29dof.pkl），不要使用训练用的 10 秒片段。--motion-list指定要跟踪的动作编号，可以一次给多个。使用数据清单时，改用
--data-manifest <清单> --dataset <数据源名称>。--max-steps可以限制回放的帧数，用于快速预览。
结果写入 <model-folder>/tracking_inference/：
| 文件 | 内容 |
|---|---|
tracking_<编号>.mp4 |
参考动作与策略执行的并排视频 |
zs_<编号>.pkl |
这段动作对应的隐变量 z 序列，部署时可直接使用 |
<模型名>.onnx、<模型名>.meta.json |
策略 ONNX 及其说明（机器人、受控关节、输入输出维度等） |
backward_encoder.onnx |
把目标状态编码成 z 的网络，实时遥操作时需要（模型不支持时跳过） |
动作跟踪默认会导出 ONNX；不需要时加 --export-onnx false。
4.2 目标到达#
CUDA_VISIBLE_DEVICES=0 \
uv run python -m humanoidverse.goal_inference \
--model-folder runs/ufo_fb \
--device cuda:0 \
--headless \
--disable-dr \
--disable-obs-noise \
--save-mp4策略在一个回合内依次到达一组目标姿态，默认每 100 步换一个目标（
--goal-switch-interval），回合长度 2100 步（--episode-len）。默认机器人使用仓库自带的目标姿态文件；其他机器人需要用
--goal-json提供自己的目标姿态文件，不同机器人之间不能通用。结果写入
<model-folder>/goal_inference/，包括goal_reaching.pkl和视频。
4.3 奖励推理#
CUDA_VISIBLE_DEVICES=0 \
uv run python -m humanoidverse.reward_inference \
--model-folder runs/ufo_fb \
--device cuda:0 \
--headless \
--disable-dr \
--disable-obs-noise \
--buffer-rank 0 \
--num-samples 150000 \
--save-mp4奖励推理从训练时保存的回放池中采样状态（默认 15 万个），用奖励函数给这些状态打分，从而算出对应的 z。所以需要训练目录中的
checkpoint/buffers/；也可以用--buffer-path指定回放池位置。默认的任务包括原地站立、各方向行走、转向、举手、下蹲等；用
--tasks可以只跑其中一部分，例如move-ego-0-0.7。只想计算 z、不生成视频时，加
--skip-rollouts。结果写入
<model-folder>/reward_inference/，包括reward_locomotion.pkl和每个任务的视频。
注意 新机器人目前只支持移动和转向类任务（
move-ego-*、rotate-z-*）。举手、下蹲、坐地等任务依赖默认机器人的身体语义定义，会直接报错。
4.4 导出 ONNX#
目标到达和奖励推理默认不导出 ONNX，需要时加 --export-onnx。导出的策略 ONNX 中，输入划分由模型自身推导；附带的 JSON 记录了机器人名称、配置路径、XML 路径、受控关节、各输入维度、z 维度和输出动作维度。
注意 导出的 ONNX 与训练它的机器人、动作维度和观测维度绑定，不能用于其他机器人。
5. 部署#
本节使用 deploy 分支，在 MuJoCo 中验证策略，再部署到实机，并用 PICO 遥操作。deploy 分支只负责运行，不做训练；每款机器人需要专属的部署配置，下文用 <机器人> 表示机器人名。
5.1 部署方式#
| 方式 | 做什么 | 运行在 |
|---|---|---|
| Sim2Sim | 在 MuJoCo 中跟踪离线动作，或执行目标、奖励任务 | 工作站 |
| 遥操作 Sim2Sim | PICO 实时动作 → 重映射 → 实时计算 z → MuJoCo 中的策略 | 工作站 |
| Sim2Real | 在实机上跟踪离线动作 | 机器人机载计算单元 |
| 机载 PICO 遥操作（推荐） | PICO 直接连接机器人，重映射、实时 z 和策略都在机器人上运行 | 机器人机载计算单元 |
| 分体遥操作（高级） | 重映射和实时 z 在工作站，策略在机器人上，通过网络传输 z | 工作站 + 机器人 |
第一次在新机器、新模型或新遥操作环境上运行时，请按这个顺序推进：
工作站上的 Sim2Sim；
工作站上的遥操作 Sim2Sim；
机器人吊起或有支撑时的 Sim2Real；
机载 PICO 遥操作：先只观察实时 z 和机器人状态，不启用策略；
用遥控器依次进入站立、启用策略、开始跟踪，并测试重置和停止；
故意断开 PICO、XRoboToolkit 或网络，确认看门狗会停止策略输出。
5.2 安装工作站环境#
git clone --branch deploy --single-branch https://github.com/Roboparty/UFO.git UFO-Deploy
cd UFO-Deploy
export UFO_ROOT=$PWD
conda create -n ufo-deploy python=3.10 -y
conda activate ufo-deploy
pip install -r requirements/runtime.txt策略推理默认使用 CPU。需要 GPU 时，安装与 CUDA 匹配的 onnxruntime-gpu，并在 config/policy/<机器人>_policy.yaml 中设置 onnx_providers。
PICO 遥操作需要另一个环境 ufo-teleop，以及 XRoboToolkit 服务和 xrobotoolkit_sdk，安装步骤见 deploy 分支的 scripts/teleop/README.md。
5.3 下载发布的模型#
模型文件较大，不放在 Git 中，放在 model/<机器人>_policy/ 下（发布模型的下载命令见 deploy 分支 README 的 Model Files 一节）。下载后的目录应为：
model/<机器人>_policy/
├── exported/
│ ├── FBcprAuxModel.onnx # 策略
│ └── backward_encoder.onnx # 把目标状态编码成 z
├── tracking_inference_mjlab/*.pkl # 动作跟踪用的 z 序列
├── reward_inference_mjlab/*.pkl # 奖励任务的 z
├── goal_inference_mjlab/*.pkl # 目标姿态的 z
└── release_manifest.yaml # 文件清单与校验值下载后，按 README 中的脚本核对 release_manifest.yaml 中的 SHA-256。
注意 策略、编码器、z 文件和部署代码是作为一个整体验证发布的。不要把旧版本的模型文件和最新的部署代码混用，除非明确标注了兼容。
5.4 Sim2Sim#
终端 A，启动 MuJoCo：
cd "$UFO_ROOT" && conda activate ufo-deploy
python -m sim_env.base_sim \
--robot_config ./config/robot/<机器人>.yaml \
--scene_config ./config/scene/<机器人>.yaml终端 B，启动策略：
cd "$UFO_ROOT" && conda activate ufo-deploy
python rl_policy/ufo_policy.py \
--robot_config config/robot/<机器人>.yaml \
--policy_config config/policy/<机器人>_policy.yaml \
--model_path model/<机器人>_policy/exported/FBcprAuxModel.onnx \
--task config/exp/tracking/tracking.yaml--task 决定执行什么任务：config/exp/tracking/tracking.yaml（跟踪离线动作）、config/exp/goal/goal.yaml（目标到达）、config/exp/reward/locomotion.yaml（奖励任务）。
在策略终端中用键盘控制：
| 按键 | 作用 |
|---|---|
i |
插值到默认站立姿态 |
] |
启用策略输出 |
[ |
开始跟踪动作 |
p |
把跟踪动作重置到停止帧 |
o |
停止策略输出，保持当前关节位置 |
n |
切换到下一个奖励或目标的 z |
5.5 遥操作 Sim2Sim#
在工作站上开四个终端，依次启动：
| 终端 | 环境 | 启动 | 作用 |
|---|---|---|---|
| A | ufo-deploy |
python -m sim_env.base_sim ...（同 5.4） |
MuJoCo |
| B | ufo-teleop |
scripts/teleop/teleop_pose_50hz.sh |
接收 PICO 数据并重映射成机器人姿态 |
| C | ufo-deploy |
python scripts/realtime/realtime_z_server.py ... |
用 backward_encoder.onnx 实时把姿态编码成 z |
| D | ufo-deploy |
python rl_policy/ufo_policy.py ... --task config/exp/tracking/teleop.yaml |
订阅实时 z 并运行策略 |
终端 C 的完整参数见 deploy 分支 README 的 Teleop Sim2Sim 一节；没有安装 CUDA 版 ONNX Runtime 时，把 --device cuda 改成 --device cpu。
实时 z 默认处于“冻结”状态。策略准备好后，按 PICO 右手 A 键开始跟随；左手 X 键冻结当前的 z。
5.6 准备机器人#
在机器人的机载计算单元上需要：
| 依赖 | 说明 |
|---|---|
| Python 3.10 venv | 安装 requirements/runtime.txt |
| 底层控制绑定 | 机器人的底层控制 Python 绑定，必须与 Python 版本和 CPU 架构匹配 |
| CycloneDDS | DDS 运行时 |
| 网卡 | 在 config/robot/<机器人>_real.yaml 中填写底层 DDS 网卡名（用 ip -br addr 查看） |
| 模型文件 | 与工作站相同的 model/<机器人>_policy/ |
| PICO 遥操作（可选） | requirements/teleop.txt、XRoboToolkit 无头服务、xrobotoolkit_sdk |
用 rsync 把工作站上的仓库和模型同步到机器人。之后在机器人上：
确认机载计算单元的 CPU 核心全部在线：
cat /sys/devices/system/cpu/online；运行不驱动电机的预检：
ONBOARD_PY=<venv 路径>/bin/python \ scripts/onboard/run_preflight_suite.sh --profile ordinary
5.7 Sim2Real#
在机器人上，设置 CycloneDDS 和底层控制绑定的环境变量后（见 deploy 分支 README），启动策略：
UFO_REAL_ROBOT_OK=1 python rl_policy/ufo_policy.py \
--robot_config config/robot/<机器人>_real.yaml \
--policy_config config/policy/<机器人>_policy.yaml \
--model_path model/<机器人>_policy/exported/FBcprAuxModel.onnx \
--task config/exp/tracking/tracking.yamlUFO_REAL_ROBOT_OK=1 是实机控制的确认开关，只在即将控制真机时设置。
用机器人遥控器操作（具体按键以机器人的部署配置为准）：
| 操作 | 作用 |
|---|---|
| 进入站立 | 插值到默认站立姿态（50 Hz 下约 10 秒） |
| 启用策略 | 启用策略输出 |
| 开始跟踪 | 开始跟踪动作 |
| 重置 | 把跟踪动作重置到停止帧 |
| 停止 | 停止策略输出，保持当前关节位置 |
| 切换 z | 切换到下一个奖励或目标的 z |
紧急情况请使用物理急停。
5.8 机载 PICO 遥操作#
PICO 直接连接机器人，所有程序都在机器人的机载计算单元上运行：
PICO → XRoboToolkit 服务 → 重映射成机器人姿态 → 实时计算 z → UFO 策略 → 机器人启动 XRoboToolkit 服务，并在 PICO 应用中把目标 IP 设为机器人的 IP。
机器人终端 A，启动姿态桥接：
scripts/teleop/teleop_pose_50hz_onboard.sh机器人终端 B，启动实时 z：
Z_PY=<venv 路径>/bin/python scripts/realtime/run_realtime_z_server_onboard.sh机器人终端 C，启动订阅实时 z 的策略（需设置
UFO_REAL_ROBOT_OK=1，启动脚本见 deploy 分支 README）。
两个手柄的分工：
| 设备 | 按键 | 作用 |
|---|---|---|
| 机器人遥控器 | 对应按键 | 站立 / 启用策略 / 开始跟踪 / 重置参考 |
| 机器人遥控器 | 停止键 | 全局停止锁：按住时策略和跟踪都停止；松开后需先松开其他键，再重新启用 |
| PICO | 右手 A | 开始或恢复跟随实时动作 |
| PICO | 左手 X | 冻结当前的 z |
PICO 按键只控制参考动作，不能启用策略、解除停止锁，也不能代替物理急停。
安全机制： 遥操作数据过期或无效时，实时 z 服务停止发布；策略在 ctx_zmq_timeout_ms（默认 200 ms）内收不到有效的 256 维 z，就会停止输出；最终的关节目标会按机器人的关节速度上限限幅。
分体遥操作（重映射和实时 z 在工作站）的配置见 deploy 分支 README 的 5B 一节。
5.9 实机安全检查清单#
启用策略前，逐项确认：
-[ ] 物理急停可以够到，并已测试；
-[ ] 第一次运行时，机器人吊起或有支撑；
-[ ] 机载计算单元的 CPU 核心全部在线；
-[ ] 两个 ONNX 都能在机器人上加载；
-[ ] <机器人>_real.yaml 中的网卡名正确；
-[ ] Sim2Sim 和遥操作 Sim2Sim 都已通过；
-[ ] 已测试遥控器的全局停止锁；
-[ ] 已通过断开 PICO、XRoboToolkit 或网络，测试实时 z 看门狗；
-[ ] 只在即将控制真机时才设置 UFO_REAL_ROBOT_OK=1。
注意 发布模型附带的 MP4 只是仿真回放，不能证明实机安全。目前已验证的是普通 Sim2Real 和机载 PICO 遥操作在实机上能够运行；系统性的故障注入、长时间自由行走和冲击限制测试还没有完成。
5.10 端口#
| 端口 | 方向 | 用途 |
|---|---|---|
| 28701 / 28702 | 实时 z 服务 ↔ 姿态桥接 | 请求和返回姿态 |
| 28703 | 姿态桥接 → 实时 z 服务 | PICO 按键 |
| 28711 | 实时 z 服务 → 策略 | 实时 z；机载时为 127.0.0.1，分体时为工作站 IP |
| 8080 | 浏览器 → 重映射查看器 | 可选，仅调试时使用 |
6. 新建机器人#
本节为新机器人生成配置并开始训练。这条路线是实验性的：仓库自带的默认机器人配置测试最充分，新机器人通常还需要调整控制器、奖励、接触和终止条件。
6.1 需要准备#
目标机器人的 MuJoCo XML；
可选的对应 URDF；
已经重映射到目标机器人的 RobotState 动作数据（见第 2 节）。
6.2 生成配置草稿#
uv run python -m humanoidverse.tools.robot_inspect \
--xml /path/to/robot.xml \
--urdf /path/to/robot.urdf \
--name my_robot \
--out configs/robots/my_robot.yaml \
--hydra-out humanoidverse/config/robot/my_robot/my_robot_auto.yaml工具从 XML 中提取身体名称、受控关节顺序、动作维度、关节范围和浮动基座。XML 是关节顺序和动作布局的唯一依据。
URDF 是可选的辅助信息，用来补充力矩、速度、阻尼、摩擦等硬件参数；两者的关节限位冲突时，默认以 XML 为准。XML 和 URDF 的关节名不一致时，用
--urdf-joint-name-map指定对应关系。加上
--hydra-out时，会同时生成训练环境所需的 Hydra 机器人配置。
6.3 人工检查配置#
生成的配置标记为草稿（review_status: draft），其中的语义字段是启发式猜测。正式训练前，至少检查：
基座（
base_body）、脚（feet）、手（hands）、关键身体部位（key_bodies）；受控关节顺序、初始姿态；
PD 增益、执行器限制；
接触身体，以及与奖励、终止条件相关的字段。
6.4 导入数据并快速训练#
按 2.2 和 2.3 节，把 --robot 换成新机器人的配置，检查并导入数据。然后快速测试：
./run_train.sh \
--agent fb \
--robot-config configs/robots/my_robot.yaml \
--data-manifest configs/data/my_motion_auto_build.yaml \
--gpu-ids single \
--smoke \
--work-dir /tmp/ufo_smoke_my_robot数据清单中写了 robot_config 时，可以省略 --robot-config；两者都写时，UFO 会检查它们是否指向同一台机器人。快速测试通过后，再去掉 --smoke，设置 GPU 和训练参数正式训练。