Reachy Mini 开源桌面机器人保姆级教程：从装包到第一行控制代码的完整指南
【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini
如果你想在周末就拥有一台会转头、会摆天线、还能和你聊天的桌面机器人，Reachy Mini 这个开源项目几乎是最省心的起点。它提供一套完整的 SDK，让你可以用几行 Python 或网页应用控制机器人的头部运动、摄像头、麦克风与扬声器，还能一键接入大语言模型。下面这份教程面向零基础新手，带你理清它"是什么、为什么值得玩、怎么最快跑起来"，并附上常见坑位的排查方法。
为什么这台桌面机器人值得新手入手？
很多人对机器人项目的第一印象是：电机贵、板子难、代码玄学。Reachy Mini 恰好把这三道门槛都拆平了——它是为"会写点代码的爱好者"设计的开源平台，机械结构可以 3D 打印，软硬件全部开放，甚至连调试文档都写成了手把手的 Notebook。
更妙的是它的三档难度设计：
| 平台 | 连接方式 | 适合人群 | 硬件门槛 |
|---|---|---|---|
| Reachy Mini（无线版） | WiFi + 内置电池，独立运行 | 想要完整"桌面伙伴"体验的人 | 需树莓派 CM4 + 电池 |
| Reachy Mini Lite | USB 连电脑 | 想先在电脑上开发的玩家 | 只需一台电脑 |
| Simulation（模拟版） | 本地 MuJoCo 仿真 | 完全没买硬件、只想先写代码的人 | 零硬件 |
没买硬件也别慌：官方仿真模式可以直接在本地起一个 3D 虚拟机器人，所有 SDK 代码原样可用。这意味着你可以今天就把代码逻辑跑通，等硬件到货后无缝切换，这一点新手很容易忽略。
核心亮点解密：它到底凭什么这么灵活？
六自由度头部：斯图尔特平台带来的"活人感"
Reachy Mini 最抓眼球的，是那个能上下点头、左右歪头、还能微微前倾的头部。秘密在于头部内部装了一台小型斯图尔特平台（Stewart Platform）——六个电机协同拉伸，把头部当作动平台，同时实现 3 个方向平移 + 3 个方向旋转。
对新手来说你不需要去推导逆运动学，SDK 内部已经封装好了：你只说"头抬高 10 毫米、歪 15 度"，机器人自己算出六个电机各自该走多少。
全身 9 个智能电机 + 完整感知套件
硬件配置相当能打：
- 底部底座：1 个高扭矩关节电机，负责身体旋转
- 头部：6 个 XL330 系列智能电机驱动斯图尔特平台
- 天线：2 个小型电机，专门用来"比心"和"歪头杀"
- 感知：120° 广角 1200 万像素摄像头 + 4 麦克风阵列（可声源定位）+ 5W 扬声器 + IMU 惯性传感器
全部电子元器件（电池管理、电机驱动、摄像头排线）都集成在定制 PCB 上，官方还给了这张电子系统图，组装时照着认即可：
想深挖细节可以看 硬件规格文档，里面有完整的电机型号和接口说明。
零基础快速上手：最快三条路跑通你的机器人
第一步：五分钟装好 SDK
推荐先装 uv（包管理工具，装应用能快 10 倍以上），然后安装 SDK 并创建虚拟环境。无线版用户装好reachy-mini，纯模拟体验则加上[mujoco]扩展：
pip install "reachy-mini[mujoco]" # 或 uv pip install "reachy-mini[mujoco]"第二步：让"大脑"先醒过来（Daemon）
机器人背后跑着一个叫Daemon的后台服务，负责和电机、传感器打交道。它是所有代码能生效的前提：
- 无线版：机器人开机即自动运行，确保电脑和机器人同一局域网
- Lite 版：终端执行
reachy-mini-daemon - 模拟版：终端执行
reachy-mini-daemon --sim，随即弹出 3D 窗口
验证方法很简单：浏览器打开 Daemon 的 API 文档页，能看到 SDK 接口文档就说明服务活着。
第三步：你的第一段控制代码
新建hello.py，粘贴下面这几行，运行python hello.py——天线左右摇摆的那一刻，就算正式入门了：
from reachy_mini import ReachyMini from reachy_mini.utils import create_head_pose with ReachyMini() as mini: mini.goto_target(antennas=[0.5, -0.5], duration=0.5) # 天线左歪 mini.goto_target(antennas=[-0.5, 0.5], duration=0.5) # 天线右歪 mini.goto_target(head=create_head_pose(z=10, roll=15, degrees=True, mm=True), duration=1.0) # 抬头 + 歪头代码之外，日常使用更推荐Reachy Mini Control桌面应用：装应用、看状态、调参数都在图形界面里完成，新手期可以完全不碰终端。想系统学的话，教程 Notebook 目录 按"连接 → 运动 → 摄像头 → 音频"的顺序排好了四节课；示例脚本目录 里则有看人脸追踪、体感控制、TTS 说话等现成可运行的 demo。
进阶拓展与避坑指南
把机器人变成 AI 应用平台
真正好玩的阶段在这里：SDK 支持接入 LLM 做自然对话，也支持写网页版应用——浏览器通过 WebRTC 直接驱动机器人，用户零安装。这意味着你写的 App 发给朋友，打开一个网页就能玩。相关路径：
- AI 集成文档：接大模型、发布应用
- JavaScript SDK 指南：浏览器应用开发
- 应用开发文档：创建、测试、发布全流程
如果你用 AI 编程助手写代码，仓库里的 AGENTS.md 是专门写给 AI 的"施工手册"，直接丢给它就能开工。
新手高频坑位排查表
| 现象 | 大概率原因 | 快速解法 |
|---|---|---|
| 代码连不上机器人 | Daemon 没启动 | 先跑reachy-mini-daemon，再开浏览器确认 API 文档页 |
| 机器人无响应 | 电脑与机器人不同网段 | 无线版必须同一 WiFi；Lite 版检查 USB 线 |
| 电机没全部识别 | 电机接线/配置缺失 | 运行src/reachy_mini/tools/scan_motors.py扫描排查 |
| 模拟窗口打不开（macOS） | MuJoCo 需要专用启动器 | 改用mjpython -m reachy_mini.daemon.app.main --sim |
| 装包冲突（macOS + uv） | uv 与 MuJoCo 兼容性问题 | 换pip直接安装 |
完整的排查清单在 故障排除文档，电机诊断还有专门的 电机诊断指南。
核心代码想读懂吗？
| 想了解 | 去哪看 |
|---|---|
| SDK 主入口 | src/reachy_mini/reachy_mini.py |
| 运动控制（goto、录制回放） | src/reachy_mini/motion/ |
| 摄像头 / 音频管线 | src/reachy_mini/media/ |
| 运动学算法（解析法 + 神经网络） | src/reachy_mini/kinematics/ |
| 仿真场景（MuJoCo 模型） | src/reachy_mini/descriptions/reachy_mini/mjcf/ |
想玩更花的，还可以给仿真场景加道具（--scene minimal会摆上苹果、羊角面包和橡皮鸭），或者参考 运动哲学文档 理解为什么官方强调"动作要软、要慢、要有呼吸感"。
总结与展望
回头看看这趟旅程：三档平台任选、一个 Daemon 服务、几行代码，你就已经摸到开源机器人的门了。Reachy Mini 的价值不止于"组装一台机器人"——它把运动控制、多传感器融合、AI 应用分发整条链路都摊开在你面前，代码全开放，你想改天线动作曲线还是加个新传感器，仓库里都有位置。
给下一步的你留三个小任务：跑通examples/head_tracking.py让人脸追踪起来；用 JS SDK 写一个"点按钮歪头"的网页应用；最后把应用发布到社区，让别人的浏览器也能指挥你的机器人。
想动手拉取完整源码（含 SDK、示例与文档）：
git clone https://gitcode.com/GitHub_Trending/re/reachy_mini你的桌面机器人故事，就从今天第一行goto_target开始。
【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
