# 乐聚 Kuavo：kuavo-ros-opensource 编译、仿真与真机启动实操

> 原文链接：https://robotics.hellobike.com/tutorials/leju-kuavo-ros-quickstart
> 频道：tutorials | 更新日期：2026-10-22 | 标签：Kuavo, kuavo-ros-opensource, ROS, catkin, 仿真, 真机启动
> 核心摘要：本文按 kuavo-ros-opensource 文档整理从拉取仓库、确认 ROBOT_VERSION 和总质量，到 Docker/实机编译、仿真启动与真机校准运行的最小可执行流程。

# 乐聚 Kuavo：kuavo-ros-opensource 编译、仿真与真机启动实操

> 本文依据以下官方文档整理：[raw.githubusercontent.com/LejuRobotics/kuavo-ros-opensource/](https://raw.githubusercontent.com/LejuRobotics/kuavo-ros-opensource/master/readme.md)。命令与版本以文档当前版本为准。

## 前置条件

- 已确认使用 GitCode、Gitee 或 SSH 拉取 kuavo-ros-opensource 仓库
- 已确认机器人版本通过环境变量 $ROBOT_VERSION 设置，且需要和自己的机器人匹配
- 已确认机器人总质量写入 ~/.config/lejuconfig/TotalMassV${ROBOT_VERSION}
- 无机器人运行环境时，可使用 docker 环境进行编译和仿真使用
- kuavo 实机镜像如果较旧，需要手动安装一些依赖项
- 真机运行前需修改 src/kuavo_assets/config/kuavo_v$ROBOT_VERSION/kuavo.json 中 EndEffectorType

## 1. 1. 拉取 kuavo-ros-opensource 开源仓库

先获取源码。文档说明拉取开源仓库时默认为 master 分支；GitCode 为推荐方式，Gitee 和 SSH 为备用方式。按你的网络与权限选择其中一种即可。
```bash
## GitCode（推荐）
git clone https://gitcode.com/OpenLET/kuavo-ros-opensource.git

## Gitee（备用）
git clone https://gitee.com/leju-robot/kuavo-ros-opensource.git

## SSH
git clone git@gitee.com:leju-robot/kuavo-ros-opensource.git
```

## 2. 2. 确认 ROBOT_VERSION 与机器人总质量

机器人版本通过环境变量 `$ROBOT_VERSION` 设置，版本号涉及不同机器人模型、硬件设置等，需要和自己的机器人匹配。未设置时，可临时设置或写入终端配置文件。
```bash
echo $ROBOT_VERSION
export ROBOT_VERSION=45
echo 'export ROBOT_VERSION=45' >> ~/.bashrc 
```

## 3. 3. 在 Docker 环境中编译

没有机器人运行环境时，可使用 docker 环境进行编译和仿真。可下载已编译镜像并导入，或使用脚本进入容器；容器默认在 `/root/kuavo_ws`，内部默认使用 zsh。
```bash
wget https://kuavo.lejurobot.com/kuavo_research_editiion/docker_images/kuavo_opensource_mpc_wbc_img_v1.3.0.tar.gz
```
```bash
docker load -i kuavo_opensource_mpc_wbc_img_v1.3.0.tar.gz
```
```bash
./docker/run.sh
```
```bash
catkin config -DCMAKE_ASM_COMPILER=/usr/bin/as -DCMAKE_BUILD_TYPE=Release # Important! 
## -DCMAKE_ASM_COMPILER=/usr/bin/as 为配置了ccache必要操作，否则可能出现找不到编译器的情况
source installed/setup.zsh # 加载一些已经安装的ROS包依赖环境，包括硬件包等
catkin build humanoid_controllers #会编译所有依赖项
```

## 4. 4. 在实机环境中编译

kuavo 实机镜像如果较旧，先用文档提供的脚本安装依赖项。随后进入仓库目录，配置 Release 编译参数，加载已安装 ROS 包依赖环境，再编译控制器及依赖项。
```bash
## 提供了一个脚本用于快速在旧的kuavo实机镜像进行安装依赖
./docker/install_env_in_kuavoimg.sh
```
```bash
cd kuavo-ros-control #仓库目录
catkin config -DCMAKE_ASM_COMPILER=/usr/bin/as -DCMAKE_BUILD_TYPE=Release # Important! 
source installed/setup.bash # 加载一些已经安装的ROS包依赖环境，包括硬件包等
catkin build  humanoid_controllers
```

## 5. 5. 启动仿真运行

文档提供 mujoco、gazebo、isaac-sim 三类仿真启动方式。Docker 环境使用 `source devel/setup.zsh`，其他环境使用 `source devel/setup.bash`；轮臂机器人使用对应 wheel launch。
```bash
source devel/setup.bash # 如果使用docker环境，则使用source devel/setup.zsh
roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch # 启动控制器、mpc、wbc、mujoco仿真器
## 注：轮臂机器人请使用 
roslaunch humanoid_controllers load_kuavo_mujoco_sim_wheel.launch
```
```bash
catkin build humanoid_controllers gazebo_sim # 需要编译gazebo_sim包
source devel/setup.bash # 如果使用docker环境，则使用source devel/setup.zsh
roslaunch humanoid_controllers load_kuavo_gazebo_sim.launch # 启动控制器、mpc、wbc、gazebo仿真器
## 注：轮臂机器人请使用
roslaunch humanoid_controllers load_kuavo_gazebo_sim_wheel.launch
```
```bash
catkin build humanoid_controllers isaac_sim # 需要编译isaac_sim包
source devel/setup.bash # 如果使用docker环境，则使用source devel/setup.zsh
roslaunch humanoid_controllers load_kuavo_isaac_sim.launch  # 启动控制器、mpc、wbc、isaac_sim仿真器
```

## 6. 6. 配置并启动真机

运行实物前，修改 `src/kuavo_assets/config/kuavo_v$ROBOT_VERSION/kuavo.json` 中 EndEffectorType 为实物执行器类型。开机第一次需先在 cali 模式下运行一次，确认机器人姿态和位置正确。
```bash
source devel/setup.bash
roslaunch humanoid_controllers load_kuavo_real.launch cali:=true # 以校准模式启动
```
之后直接按 `o` 启动机器人，后续正常运行即可。
```bash
source devel/setup.bash
roslaunch humanoid_controllers load_kuavo_real.launch 
```

## 验证是否跑通

仿真运行时，相应 launch 会启动控制器、mpc、wbc 和 mujoco、gazebo 或 isaac_sim 仿真器。实物运行时，程序启动后机器人进入待站立阶段；确认无误并扶住机器人后按 `o`，机器人开始运动到站立状态，并开启反馈控制。

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

- 机器人版本需要通过环境变量 `$ROBOT_VERSION` 设置，版本号涉及不同机器人模型、硬件设置等，需要和自己的机器人匹配。
- 机器人总质量存储于 `~/.config/lejuconfig/TotalMassV${ROBOT_VERSION}`；每次修改总质量文件时，会自动删除缓存目录 `/var/ocs2/biped_v${ROBOT_VERSION}`，下一次运行时会自动重新编译 cppad 模型，大概 4 分钟。
- `-DCMAKE_ASM_COMPILER=/usr/bin/as` 为配置了 ccache 必要操作，否则可能出现找不到编译器的情况。
- 容器镜像内部默认使用 zsh，因此 Docker 环境加载时使用 `source installed/setup.zsh` 或 `source devel/setup.zsh`。
- 在运行实物之前，需要先修改 `src/kuavo_assets/config/kuavo_v$ROBOT_VERSION/kuavo.json` 中 EndEffectorType 为实物机器人的执行器类型。
- 没有多圈编码器记忆功能的版本，电机断电之后，开机都需要手动校准一次。
- 辅助校准中按 `w` 和 `s` 键时，请仔细确认运动方向正确，不要反方向调节，否则会触发电机的限位保护，程序退出。

## 相关 SDK 条目

- [kuavo-ros-opensource](/sdks/lejurobotics-kuavo-ros-opensource)

## 原始参考来源 (Sources)

- [raw.githubusercontent.com/LejuRobotics/kuavo-ros-opensource/master/readme.md](https://raw.githubusercontent.com/LejuRobotics/kuavo-ros-opensource/master/readme.md)