名称： reachy-mini
描述： 通过 REST API 和 SSH 控制 Reachy Mini 机器人（由 Pollen Robotics / Hugging Face 开发）。适用于所有涉及 Reachy Mini 机器人的请求——移动头部、身体或天线；播放情绪或舞蹈；捕获相机快照；调整音量；管理应用；检查机器人状态；或任何物理机器人交互。该机器人具有 6 自由度头部、360° 身体旋转、两个可动画天线、广角相机（支持非中断式 WebRTC 快照）、4 麦克风阵列和扬声器。

Reachy Mini 机器人控制

快速开始

使用 CLI 脚本或 curl 控制机器人。脚本位于：

~/clawd/skills/reachy-mini/scripts/reachy.sh

通过 REACHY_HOST 环境变量或 --host 标志设置机器人 IP。默认：192.168.8.17。

常用命令

reachy.sh status                    # 守护进程状态、版本、IP
reachy.sh state                     # 完整的机器人状态
reachy.sh wake-up                   # 唤醒机器人
reachy.sh sleep                     # 使机器人进入睡眠
reachy.sh snap                      # 相机快照 → /tmp/reachy_snap.jpg
reachy.sh snap /path/to/photo.jpg   # 快照保存到自定义路径
reachy.sh play-emotion cheerful1    # 播放情绪动画
reachy.sh play-dance groovy_sway_and_roll  # 播放舞蹈动作
reachy.sh goto --head 0.2,0,0 --duration 1.5  # 点头向下
reachy.sh volume-set 70             # 设置扬声器音量
reachy.sh emotions                  # 列出所有情绪动画
reachy.sh dances                    # 列出所有舞蹈动作

环境变量

运动指南

头部控制 (6 自由度)

头部接受以弧度表示的俯仰、偏航、滚转：
- 俯仰 (向上/下看): -0.5 (上) 到 0.5 (下)
- 偏航 (向左/右看): -0.8 (右) 到 0.8 (左)
- 滚转 (侧向倾斜): -0.5 到 0.5

# 向上看
reachy.sh goto --head -0.3,0,0 --duration 1.0

# 向左看
reachy.sh goto --head 0,0.4,0 --duration 1.0

# 头部向右倾斜，略微向上看
reachy.sh goto --head -0.1,0,-0.3 --duration 1.5

# 回到中立位置
reachy.sh goto --head 0,0,0 --duration 1.0

身体旋转 (360°)

身体偏航，单位为弧度。0 = 向前，正数 = 左转，负数 = 右转。

reachy.sh goto --body 1.57 --duration 2.0   # 向左转 90°
reachy.sh goto --body -1.57 --duration 2.0  # 向右转 90°
reachy.sh goto --body 0 --duration 2.0      # 面向前方

天线

两个天线 [左, 右]，单位为弧度。范围约 -0.5 到 0.5。

reachy.sh goto --antennas 0.4,0.4 --duration 0.5    # 两者向上
reachy.sh goto --antennas -0.3,-0.3 --duration 0.5   # 两者向下
reachy.sh goto --antennas 0.4,-0.4 --duration 0.5    # 不对称

组合运动

# 向左看并同时向左转动身体，天线向上
reachy.sh goto --head 0,0.3,0 --body 0.5 --antennas 0.4,0.4 --duration 2.0

插值模式

使用 goto 命令时，可通过 --interp 指定：
- minjerk — 平滑、自然（默认）
- linear — 匀速
- ease — 缓入缓出
- cartoon — 弹性、夸张

情绪与舞蹈

播放情绪动画

80+ 个预录制的表情动画。根据上下文选择合适的情緒：

reachy.sh play-emotion curious1       # 好奇表情
reachy.sh play-emotion cheerful1      # 开心表情
reachy.sh play-emotion surprised1     # 惊讶反应
reachy.sh play-emotion thoughtful1    # 思考姿势
reachy.sh play-emotion welcoming1     # 欢迎手势
reachy.sh play-emotion yes1           # 点头表示“是”
reachy.sh play-emotion no1            # 摇头表示“否”

播放舞蹈动作

19 个舞蹈动作，适合娱乐或庆祝：

reachy.sh play-dance groovy_sway_and_roll
reachy.sh play-dance chicken_peck
reachy.sh play-dance dizzy_spin

完整列表

运行 reachy.sh emotions 或 reachy.sh dances 查看所有可用动作。

电机模式

运动前，电机必须处于 enabled 状态。使用 reachy.sh motors 检查。

reachy.sh motors-enable     # 启用（运动命令所需）
reachy.sh motors-disable    # 禁用（机器人变得松弛）
reachy.sh motors-gravity    # 重力补偿（可手动摆姿势）

音量控制

reachy.sh volume            # 当前扬声器音量
reachy.sh volume-set 50     # 设置扬声器音量为 50%
reachy.sh volume-test       # 播放测试音
reachy.sh mic-volume        # 麦克风音量级别
reachy.sh mic-volume-set 80 # 设置麦克风音量为 80%

应用管理

Reachy Mini 运行 HuggingFace Space 应用。通过以下命令管理：

reachy.sh apps              # 列出所有可用应用
reachy.sh apps-installed    # 仅列出已安装应用
reachy.sh app-status        # 查看当前运行的应用
reachy.sh app-start NAME    # 启动一个应用
reachy.sh app-stop          # 停止当前应用

重要：一次只能运行一个应用。启动新应用会停止当前应用。应用可能独占控制机器人——如果机器人无响应，请在发送手动运动命令前停止正在运行的应用。

相机快照

通过 WebRTC 从机器人相机（IMX708 广角）捕获 JPEG 照片——不会中断正在运行的守护进程。

reachy.sh snap                        # 保存到 /tmp/reachy_snap.jpg
reachy.sh snap /path/to/output.jpg    # 自定义输出路径

要求：需要 SSH 访问机器人（使用 sshpass + REACHY_SSH_PASS 环境变量，默认：root）。

工作原理：在机器人上使用 GStreamer 的 webrtcsrc 插件连接到守护进程的 WebRTC 信令服务器（端口 8443），捕获一帧 H264 解码后的图像，并保存为 JPEG。无需重启守护进程，不会干扰电机。

注意：机器人必须唤醒（头部抬起）才能获得有用的图像。如果处于睡眠状态，相机会朝向身体内部。请先运行 reachy.sh wake-up。

音频感知

reachy.sh doa               # 麦克风阵列的声源方向

返回以弧度表示的角度（0=左，π/2=前，π=右）和语音检测布尔值。

上下文反应（Clawdbot 集成）

使用 reachy-react.sh 根据心跳、定时任务或会话响应触发上下文相关的机器人行为。

~/clawd/skills/reachy-mini/scripts/reachy-react.sh

反应类型

reachy-react.sh ack           # 点头确认（收到请求）
reachy-react.sh success       # 愉快情绪（任务完成）
reachy-react.sh alert         # 惊讶 + 天线竖起（紧急邮件、警报）
reachy-react.sh remind        # 欢迎/好奇（会议提醒、待办事项）
reachy-react.sh idle          # 细微动画（心跳存在感）
reachy-react.sh morning       # 唤醒 + 问候（早间简报）
reachy-react.sh goodnight     # 困倦情绪 + 睡眠（夜间模式）
reachy-react.sh patrol        # 相机快照，打印图像路径
reachy-react.sh doa-track     # 将头部转向检测到的声源
reachy-react.sh celebrate     # 随机舞蹈（欢乐时刻）

使用 --bg 参数在后台运行（非阻塞）。

内置行为

• 静默时段 (22:00–06:29 ET)：除 morning、goodnight 和 patrol 外，所有反应都会被静默跳过。
• 自动唤醒：反应确保机器人在行动前处于唤醒状态（启动守护进程并在需要时唤醒）。
• 容错处理：如果机器人无法访问，反应会干净退出，不产生错误。

集成触发点

DOA（声源方向）跟踪

doa-track 反应使用机器人的 4 麦克风阵列检测语音方向，并将头部转向说话者。DOA 角度（0=左，π/2=前，π=右）被映射到头部偏航。仅在检测到活动语音时触发。

相机巡逻

patrol 反应捕获快照并打印图像路径。在心跳期间使用此功能定期检查房间。可结合图像分析来检测活动或变化。

直接 API 访问

对于 CLI 未涵盖的任何操作，使用 curl 或 raw 命令：

# 通过 raw 命令
reachy.sh raw GET /api/state/full
reachy.sh raw POST /api/move/goto '{"duration":1.0,"head_pose":{"pitch":0.2,"yaw":0,"roll":0}}'

# 直接通过 curl
curl -s http://192.168.8.17:8000/api/state/full | jq
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"duration":1.5,"head_pose":{"pitch":0,"yaw":0.3,"roll":0}}' \
  http://192.168.8.17:8000/api/move/goto

参考

完整的 API 端点列表、模式（GotoModelRequest、FullBodyTarget、XYZRPYPose）以及完整的情绪/舞蹈目录，请参阅 references/api-reference.md。

故障排除

• 机器人不动：检查 reachy.sh motors —— 必须为 enabled。运行 reachy.sh motors-enable。
• 无响应：检查 reachy.sh status。状态应为 running。如果不是，运行 reachy.sh reboot-daemon。
• 运动被忽略：可能有应用独占控制。请先运行 reachy.sh app-stop。
• 网络不可达：使用 ping $REACHY_HOST 验证机器人 IP。检查 reachy.sh wifi-status。
• 快照显示黑图：机器人可能处于睡眠状态（头部低下）。请先运行 reachy.sh wake-up。
• 快照因 SSH 错误失败：确保 sshpass 已安装且 REACHY_SSH_PASS 设置正确。