Windows 上的零成本人形机器人仿真实录——环境搭建、模型建档、摆姿势、挥手动画，全程只需要 Python 和一份官方模型文件。

一、开发者离机器人最近的一步

启元 Q1 开始首批交付了，定价 19999 元起（2026 年 10 月 15 日，中国发展网）。发布会上的演示很精彩，社交媒体上的开箱视频也足够多，但对一个想动手的开发者来说，现实问题摆在面前：大部分人的桌子上没有这台机器人。 交付是分批的，体验店在少数几个城市，而"想写点东西跑跑看"的冲动是当下的。

没有真机，是不是就只能看视频流口水？倒也不是。我在启元官方的 AtomGit 上翻仓库时发现，他们把 Q1 的机器人描述模型直接放了出来——primebot/q1-urdf，一个叫"启元 Q1 V3.0 人形机器人完整 URDF 描述包"的仓库，里面有完整的 URDF、MJCF 和全部网格文件。这意味着一件事：配合开源物理引擎 MuJoCo，你在自己的 Windows 电脑上就能把这台机器人"跑"起来——加载模型、查看结构、摆姿势、做动画，全程不花一分钱，也不用碰 Ubuntu 和 ROS。

这条路的门槛有多低？低到只有一个命令：pip install mujoco。本文就是这条路的全程实录：从装环境到让 Q1 在 3D 窗口里持续挥手，每一步都可以照着复现，全部代码和成品我放在了 AtomGit（地址见文末）。

先说清楚这篇文章能给你什么：不是步态控制、不是强化学习训练——那些需要动力学模型和执行器定义，官方这份模型里没有（第六节会细说）。它能给你的是对一台人形机器人最本的认知：它有多少个关节、每个关节叫什么、能往哪个方向弯多少度、一个"挥手"背后是哪几个角度的组合。打个后端世界的比方：真机是生产环境，这份模型是全量的数据字典加上一套只读副本——你在只读副本上把表结构摸得滚瓜烂熟，等接入生产环境那天，字段名一个都不用重学。

这条路线适合谁？后端工程师——你会 Python 就够了，机器人侧的全部概念本文会就地补齐；学生和教学者——一台可以无限折腾的 3D 机器人，讲结构、讲坐标变换都是现成教具；以及所有"想入坑人形机器人但还没下决心"的观望者——先用零成本的方式确认自己是否真的对这个领域感兴趣，比直接下场买硬件理性得多。

二、三条仿真路线，和我的选择

打开 q1-urdf 仓库会看到，官方其实预留了好几条可视化路线。仓库里有 launch/display.launch 和 launch/gazebo.launch 两个启动文件——前者是经典的 ROS 三件套玩法（robot_state_publisher 发布机器人状态、joint_state_publisher_gui 提供一组关节滑条、RViz 负责渲染），你在网上见过的那种"拖滑条让机器人关节跟着动"的界面就是它；后者走 Gazebo 仿真器。如果你有一台 Ubuntu 机器、愿意装一套 ROS，官方路线是现成的。

三条路线的门道，一张图说清：

但我选了第三条：MuJoCo。三个理由，都很实际：

• 平台：ROS1 和 RViz 在 Windows 上基本没有可用的安装路径（ROS2 有 Windows 版，但这个仓库的 launch 文件是 catkin 格式，属于 ROS1 生态）；MuJoCo 则是 pip install 一行命令，Windows/macOS/Linux 全平台原生支持。
• 依赖：走 RViz 路线要装 ROS 发行版、配环境变量、处理 catkin 工作空间，首次搭建以小时计，而且系统版本和包版本之间的兼容问题能消耗掉一个下午；MuJoCo 装完是纯 Python 库，import 就能用，没有第二个依赖。
• 模型现成：仓库 xml/ 目录下直接提供了三个 MJCF 文件——MuJoCo 自己的模型格式，不需要我做任何格式转换，也不需要写一行解析代码。

顺便交代一下 ROS 那两条路为什么被我放下的细节：ROS1 已经停止积极开发（官方维护到 2025 年），新项目普遍在往 ROS2 迁，而启元自己的技能体系用的正是 ROS2 Humble——但这个模型仓库的 launch 文件偏偏是 ROS1 格式的。也就是说"官方自带的现成路线"其实是条遗留路线，要用得先自己动手翻译成 ROS2 的 launch 体系；而 Gazebo 虽然能做动力学仿真，但这份模型里没有执行器定义（第六节详述），进了 Gazebo 也主要是看模型。绕了一圈你会发现：想在 Windows 上快速"看到"这台机器人，MuJoCo 是阻力最小的那条。

顺便介绍一下 MuJoCo 本身：Multi-Joint dynamics with Contact，DeepMind 开源的多体动力学引擎（Apache 2.0 协议，GitHub: Google-DeepMind/mujoco），机器人学领域的常用工具，2022 年开源后成了学术界和工业界的标配之一。对这个名字陌生的话，只需要知道两件事：它是正经的、被大量论文引用的引擎，不是玩具；它的 Python 绑定质量很高，从加载模型到离屏渲染，API 设计得对应用开发者相当友好。

三、十分钟环境搭建

我的实测环境：Windows 11，Python 3.13.5，MuJoCo 3.16.0。安装就一行：

pip install mujoco

不放心的话，装完用一行命令验证（这也是后文所有脚本的基础）：

python -c "import mujoco; print(mujoco.__version__)"

装完即用：无需编译、无需配 GPU、无需注册任何账号。对被各种 SDK 安装折磨过的开发者来说，这种"装完真的能用"的体验本身就很治愈。

装完先别急着写代码，花一分钟做个自检——这是我的工程习惯，换来的是后面每一步出错时都能确定"问题不在我环境里"。我写了一个 00_env_check.py，打印三样东西：Python 版本、MuJoCo 版本、模型文件是否存在。三行都正常，后面的路就是通的：

这三行各有各的含义。Python 版本决定了 API 的可用面（MuJoCo 官方绑定要求 Python 3.9+，越新越好）；MuJoCo 版本要记下来，因为不同版本的渲染 API 细节有差异，遇到问题去搜答案时，版本号是你提问的前提；模型文件检查看似多余，实则是三行里最重要的——新手十有八九的第一次失败都栽在路径上。

说到路径，有两个坑要提前说，都是我实际踩过的：

坑一：中文路径。 MuJoCo 的模型解析器不认中文路径，模型文件放在 D:\资料\机器人\ 这种目录下会直接报错，报错信息还不会告诉你是路径的问题。建议照我做一个纯英文工作区（我用的是 D:\primebot_ws\），模型和脚本都放里面，一劳永逸。

坑二：不要设 MUJOCO_GL=egl。 网上不少教程为了在无显示器的服务器上渲染会设置这个环境变量，Windows 下设置了反而报错。保持默认（GLFW）就好——如果你从来没设过这个变量，那这条对你无效，忽略即可。

四、把官方模型拿回家

模型从 AtomGit 克隆：

git clone https://atomgit.com/primebot/q1-urdf.git

这个仓库的状态值得一提，几个数字都是我在仓库页面上实拍的（2026-10-21）：1 次提交、Star 1、Fork 0、累计下载 65 次——一个几乎还没被人翻过的宝库。更让我意外的是，它的 README 是空的。对一个官方放出来的模型仓库来说，这份"沉默"意味着上手只能靠自己对文件下功夫，也是我决定写这篇教程的直接原因之一。

克隆下来不到几十兆，目录结构分三块，各司其职：

• urdf/——三个 URDF 文件（含无碰撞版本和带测量点版本）。URDF（Unified Robot Description Format）是 ROS 生态通用的机器人描述格式，一台机器人有哪些连杆、连杆之间靠什么关节连接、关节轴向如何，全在这个 XML 里描述；
• meshes/——24 个 STL 网格文件，从骨盆到头颅，机器人的"皮肉"全在这里。STL 是三角面片网格格式，渲染引擎靠它画出外观；
• xml/——三个 MJCF 文件：q1_v3.xml、q1_v3_full_range.xml、q1_v3_mc.xml，这是 MuJoCo 用的。MJCF 是 MuJoCo 的原生格式，除了连杆和关节，还能携带限位、阻尼这些仿真参数，表达力比 URDF 更进一步。

一个格式是 ROS 生态的通用语，一个是 MuJoCo 的母语，仓库两个都给——等于官方把"格式翻译"的活儿提前干了，你按自己选的路线取用即可。这也是我判断这个仓库"诚意够"的原因之一：它不是只面向某一家仿真器的单向发布，而是把两条生态的入口都留好了。

三个 MJCF 我都加载对比过：关节数量、自由度、整机质量完全一致，差别在关节限位（range）的设置上。本文全部实操基于 q1_v3_mc.xml（实测用它跑通了全部流程），另外两个版本的差异留给读者自己 diff——顺带说一句，diff 两个机器人模型文件的关节限位，本身就是理解"这台机器人的设计者认为哪些动作该做、哪些不该做"的好练习。

工作区的组织方式也交代一下，方便你对照复现。我在 D:\primebot_ws\ 下建了两个目录：q1-urdf\ 是克隆来的官方仓库（只读，不改动官方文件），q1_sim_tutorial\ 是自己的教程项目，四个脚本加一个 README 全在里面，脚本里的模型路径统一用常量 XML_PATH 指向官方仓库——把"官方文件"和"自己的代码"分开放、用路径常量连接，是和所有"第三方库 + 业务代码"同构的组织方式，机器人这边没有任何特殊之处。

五、先建档：22 个关节都是谁

拿到任何一台新设备，我的习惯都是先看规格表再开机。对仿真模型也一样——写了个 01_model_card.py，把模型的结构信息读出来打了个"档案"：

几个关键数字值得展开讲讲：

整机质量 16.92 kg。这是模型里所有部件质量的总和，一个不到 17 公斤的人形机器人——作为对比，成年人大约 60-70 公斤。这个数字后面做真机部署评估、算功耗负载时都会有用。

关节总数 23，但电机是 22 个。 多出来的那个是浮动基座（freejoint）——它不代表任何电机，代表的是"整机在三维空间里的位置和姿态"（前后左右上下平移 + 三个旋转，6 个自由度）。真机上这 6 个自由度由双腿的实时平衡控制来"撑住"；在模型文件里，它就是一个让机器人能"挂"在虚拟空间中的锚点。

自由度 nq = 29：6 个基座自由度 + 22 个关节角，这就是 MuJoCo 里描述这台机器人姿态所需的全部数字。换个说法：给你 29 个数，你就能唯一确定这台机器人此刻"在哪、什么姿势"——这就是后面摆姿势的数学基础。

再看分部位的关节清单，模式非常清晰。左右腿各 6 个：髋部三轴（pitch 前后摆腿、roll 侧向开合、yaw 脚尖内外转）+ 膝单轴 + 踝两轴；左右臂各 4 个：肩三轴 + 肘单轴；腰 2 个（侧倾 + 转体）。翻一下限位表还能看出设计意图：膝关节只能往后弯 0 到 2.44 rad（约 140°）——和人一样，膝盖只许反向弯，不许正弯；腰的侧倾只有 ±0.26 rad（±15°）——腰是稳态核心，活动量小、稳定性优先；肩关节的限位则宽得多，俯仰方向接近整圈。没有手指关节——Q1 的手是整体造型，不分指。腿 12 个、臂 8 个、腰 2 个，22 个电机各管一个角度，这台机器人的全部运动能力就由这 22 个数字描述。

档案之外，还能顺手量一下"身高"。mj_forward() 重算运动学之后，模型里 27 个 body 的世界坐标全部就绪，读几个关键部位的高度：

bid = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_BODY, "head_link")
print(data.xpos[bid])   # 头部中心的 (x, y, z)

立正姿势下的实测结果：骨盆 0.419 米、躯干 0.549 米、肩部 0.724 米、头顶约 0.81 米、脚踝 0.04 米——一台桌面尺度的小型人形机器人，比多数人想象中的"人形"要小巧。这个数还可以和第一节官网产品页标称的身高 88 厘米对个账：实测头顶约 0.81 米，算上头顶造型件和站姿差异，量级完全吻合——模型文件和官网说的确实是同一台机器人，这两处信息来源互相印证过，用着放心。这个"量身高"的动作本身也是仿真里最常用的调试模式：怀疑某个部位位置不对时，直接打印它的坐标，比盯着渲染图猜靠谱得多。

六、一个重要发现：这是一台"没有肌肉"的机器人

读模型文件时我注意到三样东西不存在：没有 <actuator>（执行器/电机定义）、没有地板 geom、没有任何碰撞设置。你自己在 MuJoCo 窗口里也能印证——右侧的 Control 面板是空的，因为压根没有可控制的执行器：

这意味着 q1_v3_mc.xml 是一台纯运动学的"数字样机"：它精确描述了机器人的形状、连杆关系、关节轴向和限位，但不含"肌肉"——没有力矩输出、没有平衡控制器、没有物理交互。运动学和动力学的分工可以这样理解：运动学回答"给定每个关节的角度，身体各部分在哪"，这是纯几何计算，有唯一答案；动力学回答"给定受力，运动会怎样"，这要解微分方程，和质量、惯性、摩擦全挂钩。这份模型只保证前一半。

好奇"没有肌肉"会怎样的话，有个一分钟的实验你可以自己做：把 03_wave.py 里的循环体换成一次 mj_step() 调用——你会看到 Q1 开始下坠，穿过坐标原点一路掉进屏幕下方无穷远处，因为引擎按默认重力积分了运动方程，而模型既没有地板也没有能对抗重力的电机。玩完记得 Reset。

这不是缺陷，是分工。数字样机解决的是"长什么样、能动到哪"的问题——结构认知、姿态预览、限位验证、教学演示；而"怎么站得稳、怎么走起来"是动力学与控制问题，需要带执行器和控制器的完整模型。对本文的目标（零成本建立认知）来说，数字样机恰好是最高效的那把刀。把预期放在对的位置，是和仿真打交道的第一课。

七、摆第一个姿势：qpos 和一次小调试

MuJoCo 里，机器人的姿势就是一个向量：qpos。对这台机器人，它是 29 个数——前 7 个描述基座（3 个位置 + 4 个四元数姿态；用四元数而不是欧拉角，是为了避免万向锁问题，图形学的老话题了），后面 22 个依次是各关节的角度，单位弧度。摆姿势 = 改这 22 个数，然后调一次 mj_forward() 让引擎按新的关节角重算全身部件的位置姿态，渲染出来就是新姿势。

操作上还有个工程细节：qpos 是个裸数组，直接用下标改容易改错位置。正确的做法是先建一张"关节名 → 数组下标"的映射表，然后按名字赋值：

# 关节名 -> 在 qpos 向量中的起始下标（浮动基座占前 7 个，铰链各占 1 个）
ADR = {
    mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_JOINT, i): model.jnt_qposadr[i]
    for i in range(model.njnt)
}

def set_q(name: str, value_rad: float) -> None:
    """按名字设置某个铰链关节的角度（弧度）。"""
    data.qpos[ADR[name]] = value_rad

这就是"变量名代替魔法数字"的老原则，只是这里替你避开的是"改错关节"这种排查起来极其隐晦的事故。

姿势本身，第一坑马上就来了。我把所有关节设为 0（理论上的"标准站姿"），渲染出来一看——手臂是端在胸前的，像随时准备接什么东西。查了模型文件才明白：肩关节的连杆在建模时带了旋转偏置，"全零"并不是工程师直觉里的立正姿势。

修正办法是给肩关节 pitch 补一个固定角度。我试了 0.5、-0.5、1.2、-1.2 四个值对比渲染效果：0.5 时手臂已经垂到身侧但略僵，1.2 就甩到背后去了，最后定在 0.45 rad（约 26°），肘部再给 0.1 rad 的自然微屈——这就是脚本里的 STAND 姿势：

这个小调试其实暴露了和机器人打交道的一个日常：模型里的"零位"和你直觉里的"零位"未必是同一个零位。真机开发里这叫标定问题——每个关节的 0 度对应什么姿态，要看模型定义，不能靠猜。在仿真里踩一遍这个坑，成本是十分钟；在真机上踩，代价就大了。

八、挥手与加油：六个角度的组合

有了立正做底，摆任何姿势都变成了"选哪些关节、转多少弧度"的填空题。02_poses.py 里定义了三个姿势，一共只动了 6 个关节：

姿势	关节与角度（弧度）
挥手·帧A	右肩 roll -2.2、右肩 yaw 0.8、右肩 pitch 0.2、右肘 -0.4
挥手·帧B	右肩 roll -2.0、右肩 yaw -0.4、右肩 pitch 0.2、右肘 -0.8
加油	双肩 roll ±1.1、双肩 pitch -0.9、双肘 -0.85

一个提醒：表里的单位全是弧度。做机器人开发和做前端不一样，角度制几乎不出现，0.45 这种数字看多了自然有感觉，但起步阶段建议在脑子里装一个换算器：0.1 rad ≈ 5.7°，1 rad ≈ 57°。想打印完整限位表对照着调，两行代码就够：

for i in range(model.njnt):
    print(mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_JOINT, i),
          model.jnt_range[i])   # [下限, 上限]，弧度

挥手的两帧区别只在 yaw 和肘部——两帧连播，前臂就左右摆起来，这就是"挥手"的全部秘密：一个姿态序列。加油则是双臂对称举拳。四张渲染图：

说个幕后：加油这个姿势我调了三版。第一版把肩 roll 拉满，双臂水平伸直，出来是个标准 T-pose——机器人味道太浓，不像"加油"；第二版想加屈肘，结果 pitch 和 roll 的方向搞拧了，前臂穿过肩膀直接插进了脑袋——穿模了；第三版把 pitch 反向压 0.9 再配 0.85 的屈肘，拳才举到了头侧。每一版的修改间隔不超过一分钟：改参数、跑脚本、看渲染图，典型的"小步快跑"工作流。

三个姿势调下来，有两条实用心得。第一，角度有边界：每个关节在模型里有 range 限位（比如右肩 roll 是 -2.79 到 0.09 rad），超界的值会被引擎截断——你想要的姿势出不来时，先查限位表再怀疑人生。这份限位表用 model.jnt_range 一行就能打出来，第四节提到的三个 MJCF 版本差异也正在这张表上。第二，姿势是调出来的：指望"算出"完美角度不现实，渲染-观察-修正的循环快得惊人，写前端调样式是这手感，调机器人姿势也是这手感。

02_poses.py 一口气渲染四张姿势图，连同前后脚本的完整输出在这里：

九、能拖拽的 3D 窗口：为什么它不摔

静态图看多了会腻，来点活的。03_wave.py 用 MuJoCo 的 launch_passive 打开一个原生 3D 窗口——鼠标拖拽旋转、滚轮缩放，窗口左上角还自带一个 Screenshot 按钮，Q1 站在里面持续挥手：

值得花三十秒认识一下窗口里的面板，它们是这个引擎送的原生调试工具。左侧自上而下是 File（里面有个 Screenshot 按钮，截这个窗口本身就用它，比系统截图干净）、Option（渲染选项）、Simulation（Pause/Reset 控制和仿真状态）；右侧是 Joint（展开后能看每个关节的实时数值）、Control 和 Equality——还记得第六节说的吗，这台模型没有执行器，所以 Control 面板永远是空的，这个"空"本身就是模型文件的诚实供述。

核心循环只有十几行，值得整段贴出来：

with mujoco.viewer.launch_passive(model, data) as viewer:
    t0 = time.time()
    while viewer.is_running():
        t = time.time() - t0
        pose = dict(STAND)
        pose["right_shoulder_yaw_joint"] = 0.2 + 0.6 * np.sin(2.5 * t)
        pose["right_elbow_joint"] = -0.55 + 0.25 * np.sin(2.5 * t)
        apply(pose)          # 改 qpos + mj_forward
        viewer.sync()        # 把新画面推给窗口
        time.sleep(0.02)     # ~50 FPS

这个窗口背后有个值得讲透的机制。launch_passive 打开窗口后，物理引擎并不会自动前进——只有你调用 mj_step() 时，物理世界才走一小步（模型里设的步长是 1 毫秒）。03_wave.py 从头到尾没有调用过一次 mj_step()，它的循环只做三件事：按正弦波改右肩和右肘的角度 → mj_forward() 重算位置 → sync() 把画面推给窗口。

没有 mj_step，就没有重力、没有惯性、没有摔倒——Q1 稳稳地"冻"在半空摆姿势，因为物理引擎根本没在运行。这就是运动学驱动和动力学仿真的区别：前者是"我直接告诉你每个关节在哪"，后者是"我告诉你力，你自己算会怎样"。前者稳定可控适合做演示和验证，后者才是研究步态和平衡的领地。理解了这一层，你就明白为什么这个窗口里的机器人永远不会累——也永远不会自己动一下。

挥手动画的驱动是两个正弦函数：yaw = 0.2 + 0.6·sin(2.5t)、elbow = -0.55 + 0.25·sin(2.5t)。正弦波让角度围绕中心值平滑往复，2.5 是角频率（约 0.4 秒一个来回）。想换成招手、比心、伸展运动？改这两个函数就行——动画就是姿势随时间的变化，这句话作为直觉够用了。

十、能干什么，不能干什么

冷静盘点这条零成本路线的能力边界——这部分比前面的教程更重要，因为它决定你拿这套东西去干什么。

能干的事，五件：

1. 结构认知——22 个关节的名字、轴向、限位，跑一遍本文脚本就能烂熟于心，这是后续一切开发的地基；
2. 姿态验证——设计一个交互姿势（比如"歪头"“摊手”），先在仿真里摆出来看合不合理、有没有穿模、够不够自然，把试错留在零成本阶段；
3. 动作序列草稿——把一组关键帧连起来循环播放，就是一段动作的预览，设计意图可以先在仿真里讲清楚；
4. 教学与分享——一个能拖拽旋转、按你的节奏挥手的 3D 机器人，比任何文档都直观，给学生或团队讲解机器人结构时它就是教具；
5. 技术铺垫——MuJoCo 的 API 是通用的，从摆姿势到读传感器、算逆运动学，底座是同一套，今天的代码就是明天的起点。

不能干的事，四件：动力学仿真（没有执行器定义）、步态与平衡研究（没有控制器）、碰撞检测（没有碰撞体）、手指动作（没有手指关节）。这些不是 MuJoCo 的限制，是这份模型文件的边界——哪天官方放出带执行器的完整版，这条路线上的一切代码原样升级。

拿"姿态验证"举个完整的例子，你就明白这五件事的含金量了。假设我想给 Q1 设计一个"点头打招呼"的交互——直觉方案是点头。打开第五节的关节档案一查：模型里没有颈部关节，head_link 是直接固定在躯干上的，22 个电机里没有一个管头部。也就是说"点头"“摇头"这类靠脖子的交互，在这台机器人上压根没有物理基础。知道这个之后，方案自然换成"举手打招呼”——也就是第八节那个挥手姿势。这个从"直觉方案"到"可行方案"的修正，发生在写第一行真机代码之前，成本是查一次档案。仿真最贵的产出不是动画，是你提前被纠正的错误认知。

另外提一句官方工具的分工：启元自家的 PrimeConsole 客户端里也内置了 Q1 仿真，主打技能包的动作验证（官方界面明示只能仿真上肢动作）。和本文这条路线的定位不同——PrimeConsole 仿真是"验收"工具，面向的是打包好的技能；MuJoCo 这条路是"研究"工具，给你的是模型本身的完整访问权，想改哪个关节就改哪个。两条路线不冲突，工具箱里多一件趁手的家伙而已。

十一、部署路径：官方文档里的"下一站"

仿真教程一般会写"最后部署到真机"。这里我手头里没有真机 ，就没有继续做下一步

但部署路径本身是官方写明的，值得原样转述。启元技能包的官方 README 给出的真机运行方式是：在机器人侧的 ROS2 Humble 环境（source /opt/ros/humble/setup.bash）基础上，再 source Q1 SDK（v1.0.0.0，含 aimdk_msgs 消息定义）的环境，然后运行技能脚本；前置条件还包括打开开发者模式。也就是说，从本文的仿真到真机之间，隔着的是：一台真机、一份 Q1 SDK、一次开发者模式配置——路径是清晰的、文档化的，只是需要那台 19999 元的硬件。

把地图画到这里，剩下的路留给真机到位的那天。仿真里学到的关节名、角度限位、姿势参数，到真机上全部直接复用——模型是同一份，变高的只是赌注。

写在最后

整套实操的成本清单：环境搭建 10 分钟，模型下载 1 分钟，四个脚本共三百来行 Python，花费 0 元。产出是对一台人形机器人从"听说过"到"拆开看过"的跨越——你知道了它的 16.92 公斤怎么分布，22 个电机各管哪根骨头，膝盖为什么只能往后弯，一个挥手里藏着哪两个正弦函数。

给想复现的读者一条最短路径。

本文的四个脚本、README 和四张姿势参考图已经整理成完整仓库：https://gitcode.com/stubborn-stone/q1_sim_tutorial 

clone 下来即可跳过手敲。第一步，装环境、clone 官方仓库，跑 00_env_check 和 01_model_card 建立档案；第二步，跑 02_poses.py，然后改几个角度值重新渲染——故意超一次限位、故意调一个歪姿势，把边界摸出来，这比看十篇教程都有用；第三步，跑 03_wave.py，把正弦波的频率和幅度改成你自己的参数，看 Q1 用你的节奏挥手。三步走完，你就不再是对机器人一无所知的人了——手里多了一个可以随便折腾、永远不会坏、也永远不会嫌你烦的 Q1。

项目最终的样子如下——四个脚本就是正文的四个章节，外加一份 README 和渲染出的四张姿势图：

最后一句话写给还在观望的人：机器人开发的很多能力——读模型、查限位、算坐标、写控制循环——在真机到来之前就可以全部练好，它们不挑硬件，只挑你开始的时间。19999 元买的是那台会眨眼的硬件，而认知不用买。

人形机器人的热度还在涨，但热闹背后，真正拉开差距的是谁先动手建立了具体的认知。好在"动手"这件事的门槛，已经低到一条 pip 命令了。

启元机器人开发者社区：https://dev.primebot.com/