让桌面的机器人朝你点头：Reachy Mini 开源表情机器人完整上手指南

让桌面的机器人朝你点头：Reachy Mini 开源表情机器人完整上手指南

【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini

深夜十二点，书桌上的小机器人突然转动头部，用摄像头"看"了你一眼，然后缓缓竖起一侧天线——像一只好奇的小动物在等你陪它玩。这不是科幻电影桥段，而是开源表情机器人Reachy Mini每天都能带给你的瞬间。作为一款面向开发者与 AI 爱好者的开源机器人，它用 6 自由度头部、可动天线和完整的 Python/JavaScript SDK，把"有温度的人机交互"变成了一行行可以亲手运行的代码。

无论你手上有没有实体硬件，这篇文章都会带你从零开始：先让模拟器里的机器人动起来，再深入它的运动控制、感知能力和 AI 集成，最后附上避坑指南——全程可直接照做。

为什么桌面机器人需要"表情"？

传统机器人给你的印象可能是：机械臂、示教器、冷冰冰的坐标指令。它们擅长精确，却不擅长"沟通"。

Reachy Mini 想解决的是另一个问题：当机器人离你只有三十厘米时，它如何让你觉得它是一个"伙伴"而不是一台设备？答案藏在三处设计里：

• 6 自由度斯图尔特平台头部：不是简单的一两个舵机转头，而是通过 6 根连杆协同驱动，能做出细腻的点头、歪头、注视轨迹，像人类颈部那样自然。
• 一对会"说话"的天线：天线不只是通信硬件，更是情绪器官——开心时竖起，困惑时左右摇摆，和头部姿态一起构成肢体语言。
• 完整的多模态感知：120° 广角摄像头、4 麦克风阵列（支持声源定位）、扬声器、无线版还带 IMU 惯性传感器，让机器人能"看见、听见、回应"。

一句话总结它的与众不同：它把机器人从"执行器"变成了"表达者"，而且这一切完全开源。

没有硬件也能玩：三分钟跑通模拟器

好消息是：你不必先买机器人才能开始写代码。项目内置了基于 MuJoCo 的物理仿真环境，行为和真实 Lite 版完全一致，开发完代码再上真机，几乎零迁移成本。

先准备环境（Python 3.10 - 3.12，推荐 3.12；建议安装uv这个快速的 Python 包管理器），然后安装带仿真支持的 SDK：

git clone https://gitcode.com/GitHub_Trending/re/reachy_mini cd reachy_mini uv venv reachy_mini_env --python 3.12 source reachy_mini_env/bin/activate uv pip install "reachy-mini[mujoco]"

如果你用的是 macOS，仿真请用mjpython -m reachy_mini.daemon.app.main --sim代替下面的命令——MuJoCo 在 macOS 上需要专门的启动器。

启动仿真 daemon（后台服务，负责与"硬件"通信，必须保持运行）：

reachy-mini-daemon --sim --scene minimal

一个 3D 窗口会弹出，里面是站在桌子上的 Reachy Mini，桌上还摆了苹果、羊角面包和小鸭子（--scene minimal的效果；默认empty场景只有机器人本体）。鼠标拖拽旋转视角，滚轮缩放。

接下来新建一个hello.py，写入你的第一段控制代码：

from reachy_mini import ReachyMini from reachy_mini.utils import create_head_pose with ReachyMini() as mini: print("Connected to simulation!") # 抬头并歪一下头 mini.goto_target( head=create_head_pose(z=20, roll=10, mm=True, degrees=True), duration=1.0 ) # 摆动天线 mini.goto_target(antennas=[0.6, -0.6], duration=0.3) mini.goto_target(antennas=[-0.6, 0.6], duration=0.3) # 回到初始姿态 mini.goto_target(head=create_head_pose(), antennas=[0, 0], duration=1.0)

运行python hello.py，看 3D 窗口里的小机器人点头、晃天线——你的第一段机器人代码就这么跑通了。

深入拆解：三个最值得玩的核心能力

模拟器跑通后，让我们看看 SDK 真正的深度。以下三个能力几乎覆盖了所有有趣应用的基础。

1. 运动控制：goto_target与set_target

运动是 Reachy Mini 的灵魂，SDK 提供两种粒度：

• goto_target：平滑插值。从一个姿态平滑运动到另一个姿态，适合编排"动作"。支持 4 种插值方法：linear（线性）、minjerk（最小加加速度，默认，最平滑）、ease_in_out（缓入缓出）、cartoon（卡通感弹性）。
• set_target：瞬时控制。跳过插值直接下发目标，适合高频控制——比如跟着手柄、实时轨迹或你的挥手动作。

import numpy as np from reachy_mini import ReachyMini from reachy_mini.utils import create_head_pose with ReachyMini() as mini: # 同时控制头部、天线、机身偏航 mini.goto_target( head=create_head_pose(z=10, mm=True), # 头部上移 10mm antennas=np.deg2rad([45, 45]), # 两根天线向外张开 body_yaw=np.deg2rad(30), # 机身转 30° duration=2.0, # 2 秒内完成 method="minjerk" # 平滑加减速 )

理解坐标系能帮你少踩很多坑：头部指令基于头部坐标系（位于头部基座），而look_at_world类指令基于世界坐标系（固定在机器人底座）。动手前先想清楚"相对于谁"，就不会出现"转头方向反了"的困惑。

2. 感知：看、听、追踪

Reachy Mini 的"五官"全部可以通过 SDK 一行行调用：

with ReachyMini(media_backend="default") as mini: # 取一帧摄像头画面（numpy 数组，shape=(高,宽,3)，uint8） frame = mini.media.get_frame() # 开启头部追踪：机器人会盯着离它最近的人脸（瞄准鼻子） mini.start_head_tracking() face = mini.get_tracked_face() # detected, x, y 范围 [-1,1], roll mini.stop_head_tracking()

音频同样直接：start_recording()后通过get_audio_sample()拿到 16kHz 双声道数据，push_audio_sample()播放；get_DoA()还能返回声源方向（0 表示左侧，π/2 表示正前方）。无线版额外提供 IMU 数据——加速度、角速度、四元数、温度，随时可取。

小技巧：start_head_tracking(weight=1.0)的 weight 参数可以混合"追踪"与"你的应用动作"——1.0 时头部完全由追踪接管，0.0 时暂停检测释放 CPU，非常适合在对话应用的每个回合间低成本切换。

3. 记录与回放动作

想让机器人学会一套"舞蹈"？可以手动掰动机器人（进入顺滑模式）或下发指令，然后录下来：

with ReachyMini() as mini: mini.start_recording() # ... 机器人动起来 ... recorded_data = mini.stop_recording() # 保存，之后可回放

录制、回放、配乐（动作+音频同步播放）都内置支持，甚至可以在浏览器端用 JavaScript SDK 上传一段 WAV 让机器人在本地时钟上播放——动作与声音共用一个时钟，不会出现音画不同步。

把 AI 装进机器人：从对话到手势跟随

Reachy Mini 最"上瘾"的地方在于 AI 集成几乎零阻力，因为它深度绑定 Hugging Face 生态。

思路一：对话机器人。官方提供了参考实现，把语音活动检测（VAD）+ 大语言模型（LLM）+ 语音合成（TTS）串成完整对话链路。机器人听到你说话 → 大模型生成回复 → 扬声器说出答案 → 同时配合点头、歪头、天线动作，把"说话"变成"交流"。

思路二：手势跟随。社区有 Hand Tracker 应用，机器人会实时追踪你的手部移动——你挥手它转头，你画圈它盯着圈看。

思路三：纯浏览器应用。项目提供了 JavaScript SDK（@pollen-robotics/reachy-mini-sdk），配合 WebRTC，你可以写出零安装的网页应用：用户打开一个链接就能在浏览器里远程操控真实机器人、看实时视频流，完全不用装任何软件。官方推荐的 App 发布方式是部署成 Hugging Face Space，分享给任何人。

想用 AI 编码助手（Claude Code、Codex、Copilot 等）快速开发？项目根目录的AGENTS.md就是给智能体看的"上手手册"，把你的 App 需求粘贴给助手，让它先读这份文件，它就知道该用什么 SDK 模式、有什么最佳实践了。

从模拟到真机：常见问题避坑指南

在社区里转一圈，下面这些问题出现频率最高，先替你排掉：

另外记住一条铁律：daemon 终端不能关——它一停，所有 SDK 代码立刻失联。验证 daemon 是否就绪，浏览器打开http://localhost:8000/docs（Lite/仿真）或http://reachy-mini.local:8000/docs（无线版），能看到 API 文档页面就说明一切正常。

生态与未来：开源社区在做什么

Reachy Mini 的吸引力不止于技术本身，更在于它已经长出了一个活跃的生态：

• 应用商店模式：机器人自带"应用商店"，基于 Hugging Face Spaces 一键安装——对话、收音机、手势追踪等 App 开箱即用，你也可以发布自己的。
• 双 SDK + 完整文档：Python SDK 负责脚本与控制循环，JavaScript SDK 负责浏览器端零安装应用，配合 Jupyter 教程笔记本（覆盖连接、运动、摄像头、音频）和examples/目录下 17 个示例，学习路径非常清晰。
• 开源许可友好：软件采用 Apache 2.0，硬件设计文件采用 CC BY-SA-NC，3D 打印件、控制软件全部开放——想改机械结构？想加传感器？想自定义行为？都欢迎。

社区的路线图指向更丰富的传感器集成、更强的云服务（远程控制与数据同步）和教育套件扩展，第三方配件生态也在鼓励开发者共建。

现在就开始：你的第一个动作

如果你还没装环境，今天的行动计划是：

1. 装好uv与 Python 3.12，按安装指南完成 SDK 安装；
2. 克隆仓库（git clone https://gitcode.com/GitHub_Trending/re/reachy_mini），先跑reachy-mini-daemon --sim打开模拟器；
3. 运行上面的hello.py，看着小机器人朝你点头、晃天线；
4. 然后去examples/目录挑一个感兴趣的示例——比如head_tracking.py让它盯着你看，或者sound_tts.py让它开口说话；
5. 有真机了再对照平台指南（无线版或 Lite 版）完成组装与联网，把同一段代码无缝迁移过去。

从模拟器里第一次点头，到真机上陪你聊天，Reachy Mini 的魅力在于：它把"机器人"从遥不可及的专业设备，变成了你书桌上可以亲手编程、看着它一点点"长出性格"的伙伴。创造的过程永远比结果更迷人——今天就让它的天线，为你竖起来。

【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini