# MuJoCo Menagerie 实操：加载 Unitree G1、查看关节与执行器并规划控制回路

> 原文链接：https://robotics.hellobike.com/tutorials/mujoco-menagerie-load-unitree-g1
> 频道：tutorials | 更新日期：2026-10-22 | 标签：MuJoCo, MuJoCo Menagerie, Unitree G1, MJCF, Python viewer
> 核心摘要：本文基于 MuJoCo Menagerie 与 MuJoCo Python 文档，整理 Unitree G1 的安装、仓库获取、MJCF 文件定位、viewer 加载入口、关节与执行器查看方式，以及控制回路接入模式。

# MuJoCo Menagerie 实操：加载 Unitree G1、查看关节与执行器并规划控制回路

> 本文依据以下官方文档整理：[raw.githubusercontent.com/google-deepmind/mujoco_menagerie/m](https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/README.md)、[raw.githubusercontent.com/google-deepmind/mujoco_menagerie/m](https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/unitree_g1/README.md)、[mujoco.readthedocs.io/en/stable/python.html](https://mujoco.readthedocs.io/en/stable/python.html)。命令与版本以文档当前版本为准。

## 前置条件

- Unitree G1 模型 Requires MuJoCo 2.3.4 or later.
- Python；MuJoCo native Python bindings distributed as the mujoco package on PyPI.
- mujoco-menagerie Python package，或本地克隆的 mujoco_menagerie 仓库。
- Unitree G1 MJCF 文件：g1.xml；带手版本：g1_with_hands.xml；MJX 场景：scene_mjx.xml。

## 1. 安装 MuJoCo Python bindings

MuJoCo 文档推荐通过 PyPI 安装 Python package。该 package 已包含 MuJoCo library，不需要单独下载或安装。先完成这一层依赖，后续才能使用 Python viewer 与底层 MuJoCo API。

```bash
pip install mujoco
```

## 2. 安装 MuJoCo Menagerie package

Menagerie 文档说明，Python package 是从 Python 使用 Menagerie 的最简单方式。每个模型第一次加载时会下载到 per-user cache，且 `mujoco-menagerie==2026.9.0` 会把每个模型固定到该 release。

```bash
pip install mujoco-menagerie
```

## 3. 克隆 Menagerie 仓库

如果希望直接查看模型目录、MJCF、assets、LICENSE、README.md 和 scene.xml，可以克隆仓库。Menagerie 的每个模型目录遵循相同结构，`<model>.xml` 描述模型，`scene.xml` 加入平面、光源和可能的其他对象。

```bash
git clone https://github.com/google-deepmind/mujoco_menagerie.git
```

## 4. 定位 Unitree G1 文件

Unitree G1 README 说明该 package 包含 G1 Humanoid Robot 的简化 MJCF 描述，来源于公开 MJCF description。G1 相关文件包括 `g1.xml`、`g1_with_hands.xml`，MJX 版本可通过 `scene_mjx.xml` 使用。

## 5. 用 viewer 加载 MJCF

MuJoCo Python package 提供 standalone app。文档给出的形式是通过 `--mjcf` 指定模型文件，启动后会 launches a visualization session for the specified model file。用于 G1 时，应选择文档中列出的 G1 MJCF 或 scene 文件。

```bash
python -m mujoco.viewer --mjcf=/path/to/some/mjcf.xml
```

## 6. 查看关节与执行器

Menagerie 约定 `<model>.xml` contains the MJCF definition of the model。Unitree G1 的 derivation steps 明确写到：Added joint position actuators (needs tuning)，并且同类编辑也应用到 `g1_with_hands.xml`。因此在 MJCF 中查看模型定义与执行器。

## 7. 确定第一个控制回路位置

MuJoCo viewer 有 managed viewer 与 passive viewer。managed viewer 适合 user code implemented as engine plugins or physics callbacks，并在 `mj_step` during 调用；passive viewer 不阻塞，脚本负责 timing and advancing the physics state。

## 验证是否跑通

确认 `pip install mujoco` 与 `pip install mujoco-menagerie` 完成；仓库中能定位 Unitree G1 的 `g1.xml`、`g1_with_hands.xml`、`scene_mjx.xml`；viewer 使用 `--mjcf` 可针对指定模型文件启动 visualization session；在 G1 MJCF 中可看到文档所述 joint position actuators。

## 文档里点名的注意事项

- Unitree G1 Requires MuJoCo 2.3.4 or later.
- `<model>.xml` solely describes the model；平面、光源和其他对象留给 `scene.xml`。
- Not all models have an MJX variant.
- Unitree G1 的 joint position actuators 标注为 needs tuning.
- Each model is downloaded the first time it is loaded, into a per-user cache.
- passive viewer 中 mouse-drag perturbations will not work unless the user explicitly synchronizes incoming events.

## 相关 SDK 条目

- [mujoco_menagerie](/sdks/google-deepmind-mujoco-menagerie)
- [mujoco](/sdks/google-deepmind-mujoco)

## 原始参考来源 (Sources)

- [raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/README.md](https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/README.md)
- [raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/unitree_g1/README.md](https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/unitree_g1/README.md)
- [mujoco.readthedocs.io/en/stable/python.html](https://mujoco.readthedocs.io/en/stable/python.html)