MuJoCo中Cassie双足机器人仿真库的部署、控制与强化学习实践

简介：面向机器人控制与仿真研究者的Cassie双足机器人MuJoCo仿真库资源，基于Agility Robotics官方开源仓库整理，专用于多关节接触动力学建模、行走与平衡控制算法验证。压缩包共62个文件、约1.47MB，以XML模型描述、STL网格、C/Python控制脚本及静态库为核心，覆盖模型定义、状态观测、接触参数配置、传感器仿真等关键环节，并包含噪声地形、深度图像、斜坡及有无重力等变体场景，便于开展多工况对比实验。已有388人学习浏览。借助完整的模型文件与示例代码，可快速搭建Cassie仿真环境，在此基础上进行PD/逆动力学控制、强化学习等策略开发，也可用于动态稳定性分析、故障模拟与硬件在环验证。压缩包内目录划分清晰，集成Makefile和跨语言接口，适合具备基础MuJoCo或机器人学知识的研究者与学生直接上手，是深入探索双足机器人仿真与控制的高价值参考资料。

1. MuJoCo 里的 Cassie 仿真包：为什么这份 zip 值得单独下载

Cassie 在双足控制里是一个很特殊的基准：执行器少、腿的拓扑结构清楚，但控制难度不低，关键是它带了很多工程细节——跟骨处的被动自由度、脚踝的弹簧刚度、还有髋关节的复杂内收外展布局。MuJoCo 官方模型仓库mujoco_menagerie把 Agility Robotics 的 Cassie 维护成agility_cassie子目录，但很多工程现场拿到的是一份Cassie机器人仿真库___下载.zip。这个包装里绝大多数情况不是可安装的 Python 库，而是一组 MJCF 描述文件加网格资源，入口通常是scene.xml。真正让工程师停在第一步的，往往是解包之后资源路径错位、MuJoCo 版本对不上，或者分不清qpos前面那 7 个量是浮动基座而不是关节角。这篇文章按“取包 → 装环境 → 加载 → 控制 → 接训练”的顺序走一遍，把索引、PD 参数和接触模型这几个容易翻车的位置单独拎出来。适合正在做双足强化学习或步态研究的工程师，也适合刚拿到 Cassie 仿真资源但被文件结构卡住的人。

2. 先拿到 Cassie 仿真库：Git 拉取、zip 解包与目录核对

2.1 用 mujoco_menagerie 官方仓库拉取完整模型

最省事的来源是 MuJoCo 的官方模型仓库，它按机器人厂商和机型分目录，Cassie 就在agility_cassie下面。浅克隆一份就够用，不需要拉全部历史：

cd ~/workspace git clone --depth 1 https://github.com/google-deepmind/mujoco_menagerie.git cd mujoco_menagerie/agility_cassie ls -l

--depth 1只抓最新快照，体积小得多。目录里你会看到scene.xml、robot.xml、robot_simple.xml以及assets这类资源目录。scene.xml是给仿真直接用的入口场景，里面通常已经include了机器人本体并摆好了地面；robot.xml适合被别的场景引用；robot_simple.xml是简化网格版本，渲染负载更低，但物理属性和力矩特性基本一致。

这里强调一个原则：MJCF 里的<mesh>、<texture>引用全部是相对路径，只要动了文件夹的层级关系，加载就会失败。所以拿到任何一份 Cassie 仿真库 zip，第一件事不是打开代码，而是保持解包后的目录结构原样。

2.2 从 zip 解包并保持资源路径完整

如果你拿到的确实是一个 zip 压缩包，常见做法是先在临时目录解包，再整体移动到工作区：

cd ~/workspace wget https://github.com/google-deepmind/mujoco_menagerie/archive/refs/heads/main.zip unzip main.zip mv mujoco_menagerie-main/agility_cassie cassie cd cassie

main.zip解压后第一层目录名通常带着分支名，比如mujoco_menagerie-main，里面才是各机器人子目录。把agility_cassie整个移到cassie之后，不要再把assets子目录单独拆出去。我见过不少报错是这么来的：只把scene.xml拷到新目录，运行时 XML 解析成功，紧接着抛LoadError，说某个.stl找不到。

2.3 目录结构核对：scene.xml、robot.xml 与资源文件夹

拿到 zip 后先对一遍文件清单，避免后来把时间浪费在“模型起不来”上。

这个 zip 的本质是“模型资产”，不是“Python 库”。把它与mujocopip 包的关系说清楚：mujoco提供物理引擎和 Python 绑定，Cassie 模型由这些 XML 加网格描述。两者缺一个都跑不起来，但它们是独立的。

2.4 用一行命令确认模型可加载

解压完成后，先做一个最小验证，再进入仿真：

python -c "import mujoco; m=mujoco.MjModel.from_xml_path('scene.xml'); print('joints', m.njnt, 'actuators', m.nu, 'geoms', m.ngeom)"

正常情况会打印出 Cassie 的全部关节数、执行器数和几何体数。值得留意的是nu，也就是电机数量，Cassie 每条腿 5 个驱动器，两条腿共 10 路；nq则要看模型版本里有没有把跟骨的被动自由度单独建成一个 hinge，所以不要靠“17 还是 19”这种硬编码记忆。正确习惯是打印后自己核对，后续所有控制代码都从actuator_trnid和jnt_qposadr动态取索引，而不是手写数字。

提示：data.qpos前 7 个量永远是浮动基座的位移加四元数，后面才是关节角。任何“从第 8 个开始每两个取一个”的写法都是在给自己埋雷。

3. 搭建 MuJoCo 并加载 Cassie 场景：Ubuntu 22.04、Windows 11 与 ROS 2 部署

3.1 最小安装：一条 pip 命令与两个系统依赖

MuJoCo 从 2.x 后期开始，官方 Python 包直接携带预编译的libmujoco.so和mujoco.dll，不再需要自己编译源码。安装步骤压缩到最小就是：

Ubuntu 22.04：

sudo apt update sudo apt install -y libgl1-mesa-glx libegl1-mesa libglfw3-dev pip install --upgrade mujoco

Windows 11：

pip install --upgrade mujoco

在 Ubuntu 上装libgl1-mesa-glx是为了补libGL.so.1，这是很多人在容器里碰到的第一个坑；libegl1-mesa负责 EGL 无头渲染；libglfw3-dev在你要用本地窗口时才会用到。如果你的系统已经升级到 Ubuntu 24.04，libgl1-mesa-glx的包名改成了libgl1，命令对应换一下即可。

3.2 用 launch_passive 把 Cassie 摆上窗口

加载 Cassie 并打开实时仿真窗口，最直接的是 MuJoCo 自带的 passive viewer：

import mujoco import mujoco.viewer model = mujoco.MjModel.from_xml_path("scene.xml") data = mujoco.MjData(model) with mujoco.viewer.launch_passive(model=model, data=data) as viewer: while viewer.is_running(): mujoco.mj_step(model, data) viewer.sync()

launch_passive用上下文管理器创建窗口，退出with块后自动释放资源。viewer.sync()负责把仿真画面同步到界面，但如果机器性能跟不上，画面会变慢，物理照常推进。这里有一个容易误判的点：mj_step只推进一个物理步，默认时间步长在 2ms 量级，也就是 500Hz；如果控制代码写在mj_step之前的同一个循环里，控制频率也等于物理频率。

3.3 无头服务器渲染：MUJOCO_GL 三档与 Renderer

很多训练任务跑在无显示器服务器上，launch_passive会直接失败。这时用环境变量切换渲染后端：

MUJOCO_GL=egl python cassie_demo.py MUJOCO_GL=glfw python cassie_demo.py

glfw需要窗口系统，适合本机调试；egl是无头服务器最常见的选项，依赖libegl1-mesa。旧版本里的osmesa属于软渲染，速度慢，新版本里也已逐渐边缘化。无头环境下需要保存图像，用mujoco.Renderer做离屏渲染：

renderer = mujoco.Renderer(model, height=480, width=640) mujoco.mj_forward(model, data) frame = renderer.render() # frame.shape == (480, 640, 3)

mujoco.mj_forward先做一次正向运动学，保证相机能看到正确的骨骼姿态；如果直接拿刚mj_resetData的data去渲染，也不会报错，但画出来的可能是初始堆叠状态。

3.4 ROS 2 接入：把 Cassie 的关节状态发布成 JointState

在 ROS 2 里接 MuJoCo，常见做法不是去找一个“MuJoCo 官方 ROS 包”，而是在仿真进程里开一个rclpy节点，把关节状态转成标准消息发出去。下面是最小的发布节点：

import rclpy from rclpy.node import Node from sensor_msgs.msg import JointState import mujoco class CassieJointState(Node): def __init__(self): super().__init__('cassie_joint_state') self.pub = self.create_publisher(JointState, '/joint_states', 10) self.timer = self.create_timer(0.01, self.tick) self.model = mujoco.MjModel.from_xml_path('scene.xml') self.data = mujoco.MjData(self.model) self.jid = self.model.actuator_trnid[:, 0].copy() self.qidx = self.model.jnt_qposadr[self.jid] def tick(self): mujoco.mj_step(self.model, self.data) msg = JointState() msg.header.stamp = self.get_clock().now().to_msg() msg.name = [ mujoco.mj_id2name(self.model, mujoco.mjtObj.mjOBJ_JOINT, j) for j in self.jid ] msg.position = self.data.qpos[self.qidx].astype(float).tolist() self.pub.publish(msg)

这里 100Hz 的定时器控制发布频率，MuJoCo 的物理步依然按自身频率推进；如果希望仿真严格同步到 ROS 定时器，就把mj_step放到回调里并调整opt.timestep。actuator_trnid[:, 0]取每个执行器对应的关节编号，jnt_qposadr再映射到qpos下标，这样发布出去的关节顺序和名称严格对应，不会出现左右腿接反的问题。

3.5 安装时常见报错对照表

4. 控制 Cassie：关节索引、PD 参数与触地调参

4.1 先看懂 10 个执行器与 qpos 的关系

写控制器之前，先把执行器到关节的映射打印出来。这一步能避免后面大量“机器人在空中乱转”的问题。

import numpy as np import mujoco model = mujoco.MjModel.from_xml_path("scene.xml") data = mujoco.MjData(model) act_jid = model.actuator_trnid[:, 0].copy() qidx = model.jnt_qposadr[act_jid] didx = model.jnt_dofadr[act_jid] for i in range(model.nu): name = mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_JOINT, act_jid[i]) print(f"{i:2d} -> {name:16s} qpos[{qidx[i]}] qvel[{didx[i]}]")

actuator_trnid第一列保存的是默认transmission="joint"下的关节 ID；jnt_qposadr给出该关节在qpos里的下标，jnt_dofadr对应qvel里的速度下标。Cassie 的nu是 10，也就是每条腿 5 个电机：髋偏航、髋滚转、髋俯仰、膝、踝。注意跟骨的被动自由度通常不在执行器列表里，它由关节刚度和阻尼维持，这正是 Cassie 落地时看起来有缓冲的原因。

4.2 一个可直接落地的站立 PD 环

掌握索引之后，写一个位置 PD 控制器让 Cassie 站稳。这里假设data.qpos的初始值就是合理的站立构型：

kp = np.array([120., 120., 120., 200., 150.] * 2) kd = np.array([8., 8., 8., 16., 12.] * 2) q_des = data.qpos.copy() dq_des = np.zeros(model.nv) ctrl_min = model.actuator_ctrlrange[:, 0] ctrl_max = model.actuator_ctrlrange[:, 1] for step in range(1000): tau = kp * (q_des[qidx] - data.qpos[qidx]) + kd * (dq_des[didx] - data.qvel[didx]) data.ctrl[:] = np.clip(tau, ctrl_min, ctrl_max) mujoco.mj_step(model, data)

kp单位是 N·m/rad，kd是 N·m·s/rad。膝盖承受的动载荷比髋大，所以第二组200和16给膝和踝。np.clip这行必须保留：直接把超限力矩写进ctrl，多步之后数值积分会不稳定，表现是机器人突然“炸开”。

4.3 armature 的坑：为什么加了控制器仍然抖

如果 Cassie 在高频抖动，先用这行确认电机惯量：

print("armature:", model.dof_armature[didx])

armature是附加在自由度上的等效转子惯量。MuJoCo 里关节默认armature=0并不代表“无惯量”，而是关节本身的集中惯量只由body质量分布决定；对双足这种关节负载变化大的系统，PD 控制器很容易把转速推得过高。出现高频振铃时，优先考虑增加armature，而不是放大kd。MJCF 里通常在<joint>上直接写armature="0.05"这一类值，改完后重新from_xml_path加载即可。

4.4 触地瞬间：摩擦、solref 与 condim 的调整

Cassie 站立和走路时，脚底接触是主要力源。改接触参数要放在模型加载之后、mj_step之前：

for name in ("foot_left", "foot_right"): gid = mujoco.mj_name2id(model, mujoco.mjtGeom.mjOBJ_GEOM, name) if gid >= 0: model.geom_friction[gid] = [1.0, 0.005, 0.0001] model.geom_solref[gid] = [0.004, 1.0] model.geom_condim[gid] = 3

geom_friction三个值分别对应滑动、滚动、扭转摩擦；双足机器人脚底滑动摩擦给 0.8~1.2 比较常见。solref的第一个值是接触响应时间常数，0.004 配合 2ms 的timestep大约是两步收敛，既有弹性又不会弹起。condim=3表示使用摩擦锥模型，比 4 更稳定；如果你发现 Cassie 走着走着侧向滑出去，先查的就是这里。

4.5 索引写错的表现：free joint 和 joint 混在一起

很多人第一次控制 Cassie，会直接把qpos的某个区间当成关节角。问题是qpos前 7 个量是浮动基座的位置和四元数，不在任何执行器的控制范围内。正确的做法永远是：从actuator_trnid拿关节 ID，从jnt_qposadr拿qpos下标，从jnt_dofadr拿速度下标。这三张表打印出来贴在手边，比任何“第 8 个到第 17 个”的硬编码都可靠。

5. 把 Cassie 仿真库接到训练与验证链路上

5.1 做成最小 RL 训练环境的骨架

Cassie 最常见的用途还是没有腿的步态策略训练。最小环境框架可以这么写：

class CassieEnv: def __init__(self, xml_path="scene.xml"): self.model = mujoco.MjModel.from_xml_path(xml_path) self.data = mujoco.MjData(self.model) self.qidx = self.model.jnt_qposadr[self.model.actuator_trnid[:, 0]] self.didx = self.model.jnt_dofadr[self.model.actuator_trnid[:, 0]] def reset(self): mujoco.mj_resetData(self.model, self.data) return self._obs() def step(self, action): ctrl_max = self.model.actuator_ctrlrange[:, 1] self.data.ctrl[:] = np.clip(action, -1.0, 1.0) * ctrl_max mujoco.mj_step(self.model, self.data) done = self.data.body("pelvis").xpos[2] < 0.5 return self._obs(), self._reward(), done, {} def _obs(self): return np.concatenate([ self.data.qpos[self.qidx], self.data.qvel[self.didx], ])

这个骨架没有奖励函数和终止逻辑以外的任何修饰，但训练跑起来需要记住两点：第一，done不能只看仿真时间，要加骨盆高度阈值，否则机器人摔倒后继续累积无效样本；第二，观测里必须包含足够的速度信息，单靠qpos学出来的策略会有明显延迟。action先做归一化再乘ctrlrange，是 RL 策略输出和 MuJoCo 执行器单位之间的标准换算方式。

5.2 一个快速验证技巧：用正弦扰动检查相位滞后

在把完整训练搬上来之前，可以用单关节正弦跟踪检验控制环的动态：

jid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_JOINT, "hip_pitch_left") act_id = int(np.where(act_jid == jid)[0][0]) qj = model.jnt_qposadr[jid] dj = model.jnt_dofadr[jid] freq, amp = 1.0, 0.05 while data.time < 10.0: ref = amp * np.sin(2 * np.pi * freq * data.time) data.ctrl[act_id] = 150.0 * (ref - data.qpos[qj]) - 12.0 * data.qvel[dj] mujoco.mj_step(model, data)

如果data.qpos[qj]跟踪正弦的相位滞后明显超过理论预期，说明kd给得不够，或者物理步长太大。这个测试只动一个关节，能快速定位是哪组参数的问题，而不必每次跑完整条腿。

5.3 回灌真机前：关节符号与坐标约定先对齐

MuJoCo 里的关节正方向由 MJCF 的<axis>决定，真机 SDK 里的正方向未必一致。常见做法不是直接比较关节角度，而是先对比data.xpos的脚踝和骨盆位置与真机运动学计算结果；如果位置一致而角度不一致，就是符号约定问题。另一点是在模型里选一个脚底site，用site_xpos当作触地参考，这样训练阶段的接触判断和真机足底压力计能对得上。把这几张索引表和符号约定整理清楚，Cassie 仿真库才算真正接到你的工作流里。

本文还有配套的精品资源，点击获取