SO-ARM101 是一套面向 LeRobot、模仿学习与具身智能开发的低成本开源机械臂。它能帮助开发者跑通“遥操作—数据采集—模型训练—真机推理”的完整流程，但第一次搭建时，环境版本、串口权限、供电、舵机 ID、相机配置和数据质量中的任何一个细节，都可能导致程序报错或机械臂行为异常。

本文汇总了用户最常遇到的问题，并结合 Seeed Studio 的完整教程给出更具体的排查方法。建议把本文当作快速诊断清单使用；涉及组装图片、完整命令、参数解释和最新版本说明时，请以 SO-ARM100 / SO-ARM101 × LeRobot 中文 Wiki 为准。

安全提醒：任何会驱动机械臂运动的操作开始前，请固定好机械臂，并清空周围 1 米范围内的人员、线缆、工具和易碎物品。插拔舵机线、USB 线或电源线之前，必须先断电。

一、开始排错前，先确认这 5 件事

很多“软件报错”最终其实来自接线、供电或版本不一致。正式排查前，建议先完成以下检查：

1. 使用教程验证过的代码仓库：按照 Wiki 克隆 https://github.com/Seeed-Projects/lerobot.git。LeRobot 上游更新较快，命令参数、数据格式或依赖可能发生变化，不建议把不同版本的教程和代码混用。
2. 确认机械臂型号和供电规格：SO-ARM101 Leader 使用 7.4 V 系列舵机；不同套件的 Follower 可能使用 7.4 V 或 12 V 舵机。接电前务必核对电源和舵机标签，错误电压可能造成舵机不工作，甚至损坏硬件。
3. 确认 USB 和外部电源都已连接：USB 负责通信，不负责为整条舵机总线供电。
4. 确认端口对应关系：Leader 和 Follower 会分别占用一个串口，不能只凭 ttyACM0 或 ttyACM1 猜测。使用 lerobot-find-port，按提示拔插 USB 来确认设备。
5. 先跑通校准和遥操作，再采集数据：如果遥操作本身会跑偏、抖动或断连，直接进入数据采集只会把硬件问题带进数据集。

二、串口存在，但 LeRobot 无法连接

症状

Could not connect on port "/dev/ttyACM0"

或者系统能够列出 /dev/ttyACM0，程序却无法打开它。

解决方法

先确认端口确实存在：

ls /dev/ttyACM*

然后识别 Leader 与 Follower 对应的真实端口：

lerobot-find-port

如果端口存在但没有访问权限，可以临时执行：

sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1

之后重新运行校准或遥操作命令。若重启后问题再次出现，可再考虑配置持久化的 udev 权限规则。

如果仍无法连接，请继续检查：

• 是否选错了 Leader / Follower 的端口；
• USB 线是否具备数据传输能力，而不是仅供电线；
• 驱动板是否已接外部电源；
• 是否有另一个程序正在占用串口；
• USB 接口或集线器是否稳定。

完整的端口识别和机械臂配置步骤可参考 Wiki 的舵机校准与组装章节。

三、设置舵机 ID 时找不到 gripper motor

症状

Motor 'gripper' was not found, Make sure it is connected

常见原因

• 夹爪舵机没有单独连接到驱动板；
• 三针通信线方向错误、松动或接触不良；
• 舵机未供电，或供电电压不正确；
• 总线上同时连接了多个尚未正确分配 ID 的舵机；
• 舵机 ID 或波特率曾被其他工具修改。

正确处理方式

运行 lerobot-setup-motors 时，严格按照终端提示操作。程序要求连接 gripper 时，应保证链路为：

电脑 → USB 数据线 → 舵机驱动板 → 三针线 → 夹爪舵机

此时夹爪舵机必须是唯一连接到驱动板的舵机。断电后重新插紧线缆，再通电并按 Enter。完成一个舵机后，再断电更换下一个舵机。

如果仍识别不到，可使用 Seeed Studio 的 SoARM 舵机调试工具教程 检查舵机、重新写入 ID，并将当前位置设置为中位值 2048。

四、出现 no status packet 或读取舵机位置失败

症状

ConnectionError: Failed to sync read 'Present_Position' on ids=[1,2,3,4,5,6]
[TxRxResult] There is no status packet!

这表示控制端发出了读取请求，但舵机总线没有返回完整响应。

推荐排查顺序

1. 看指示灯：哪个舵机不亮，优先检查它以及它前一级舵机之间的连接线，尤其留意关节 4 和 5 之间的短线。
2. 确认电源：检查适配器、DC 接头和驱动板电源，确认 Leader / Follower 没有接反电源。
3. 检查端口：双臂同时连接时，再用 lerobot-find-port 验证端口，避免把 Leader 的端口传给 Follower 配置。
4. 逐段缩小范围：断电后减少总线上的舵机数量，从单个舵机开始检查，再逐个接回。
5. 检查 ID 和波特率：确认 1–6 号 ID 没有重复或缺失，通信波特率与教程要求一致。

如果重接线后仍稳定复现，建议拍摄舵机指示灯和接线状态，并保存完整终端输出，提交给技术支持定位。

五、校准时报 Magnitude exceeds 2047，或机械臂角度异常

症状

Magnitude 30841 exceeds 2047 (max for sign_bit_index=11)

也可能表现为校准时 MAX 数值达到上万、遥操作跑偏或关节突然向错误方向运动。

处理方法

先停止程序，将机械臂断电后重新上电，再尝试校准。如果问题仍存在：

1. 断电后把各关节手动移动到组装教程所示的行程中位附近；
2. 对异常舵机重新执行中位校准，当前位置应设置为 2048；
3. 检查舵机 ID、型号和减速比是否与关节位置对应；
4. 删除或放弃旧校准结果，重新进行整臂校准。

当终端提示：

Press ENTER to use provided calibration file ... or type 'c' and press ENTER to run calibration

输入 c 并按 Enter，会重新校准；直接按 Enter 则会继续使用已有校准数据。已经出现跑偏或角度异常时，不要沿用旧文件。

注意：编码值在 4095 与 0 之间回绕不一定代表硬件损坏，重新完成中位校准通常可以消除异常。

六、遥操作跑偏、不动、抖动或夹爪到极限后断连

遥操作跑偏或完全不动

按以下顺序检查：

1. 重新进行舵机中位校准和整臂校准；
2. 检查 Leader / Follower 供电和串口是否对应；
3. 确认没有误运行舵机初始化脚本，导致已有 ID 被改写；
4. 对照 SO-ARM100 / SO-ARM101 型号表，确认 Leader 前三个关节使用了正确的减速比配置。

运动抖动或推理一卡一卡

先区分问题发生在哪个阶段：

• 遥操作也抖动：优先检查机械结构、供电、舵机参数和通信；
• 遥操作流畅，模型推理才卡顿：优先检查算力、推理频率、摄像头分辨率和动作队列。

模型推理阶段可尝试异步推理，并从以下参数开始调整：

• actions_per_chunk=50
• chunk_size_threshold=0.5
• aggregate_fn_name=weighted_average

如果动作队列频繁触底，可增大 actions_per_chunk 或 chunk_size_threshold，也可以降低执行 FPS、摄像头分辨率或帧率。详细原理和完整命令见 Wiki 的异步推理章节。

夹爪到极限位置后断连

避免让夹爪长时间顶住机械极限，可降低夹爪力矩或缩小控制范围。如果频繁复现，再检查舵机固件、供电和夹爪舵机状态。

七、ffmpeg 报 No valid stream found

症状

No valid stream found in input file. Is -1 of the desired media type?

先确认当前环境实际调用的是哪个 ffmpeg：

which ffmpeg
ffmpeg -version
ffmpeg -encoders

然后在 LeRobot 的 conda 环境中安装 Wiki 验证过的版本：

conda install ffmpeg=7.1.1 -c conda-forge

安装后重新打开终端、激活同一个 conda 环境，再确认 which ffmpeg 指向该环境中的可执行文件。不要让系统 ffmpeg、conda ffmpeg 和其他 Python 环境互相混用。

八、相机找不到、超时或只有一路画面

Orbbec 提示 No Orbbec camera found

这通常不是相机损坏，而是配置中的序列号与当前设备不一致。运行：

lerobot-find-cameras orbbec

找到实际序列号后，更新配置中的 serial_number_or_name。

Orbbec 等待帧超时

如果增加 USBFS 缓存后仍超时：

1. 停止程序；
2. 重新插拔相机；
3. 尽量直连电脑的高速 USB 接口，避免不稳定的无源 Hub；
4. 重新运行相机检测，再运行遥操作或采集命令。

RealSense 在 macOS 报 failed to set power state

可以尝试以 sudo 运行同一检测命令，但 RealSense 在 macOS 上的稳定性有限，真机采集建议优先使用 Linux。

双摄像头采集时，Rerun 只显示一路

这不一定是硬件问题。在 Rerun 左侧栏中右键，添加新的摄像头视图，并把第二路图像拖入对应视图即可。

九、数据采集时方向键或 ESC 没反应

右箭头用于结束当前 episode 或开始下一条，左箭头用于重录，Esc 用于退出。如果按键完全没有响应，可尝试降低 pynput 版本：

pip install pynput==1.6.8

Linux 用户还需确认 $DISPLAY 已正确设置，并且命令运行在能够接收桌面键盘事件的图形会话中。通过纯 SSH、容器或无桌面环境运行时，键盘监听可能无法正常工作。

在开始大量采集前，建议先录制 2–3 个测试 episode，确认：

• 两路摄像头都被正确保存；
• 关节动作与视频时间同步；
• 能够结束、重录和退出；
• 回放动作安全且与示范一致。

十、训练时报 stack(): ... must be tuple of Tensors, not Column

症状

TypeError: stack(): argument 'tensors' (position 1) must be tuple of Tensors, not Column

这通常与 datasets 版本不兼容有关，可在当前 LeRobot 环境中安装教程验证过的版本：

pip install datasets==2.19

安装后记录依赖版本，避免后续执行无约束升级导致环境再次变化。若仍报错，请确认代码仓库、数据集格式和训练命令来自同一版本的教程。

十一、模型训练了很久，真机效果仍然不好

训练效果差时，不要只盯着 loss 或盲目增加训练步数。建议按下面的优先级排查。

1. 先检查数据质量

• 是否包含失败、碰撞、停顿或明显抖动的 episode；
• 每条示范是否从相近的初始状态开始；
• 相机是否发生移动、自动对焦或曝光突变；
• 目标物是否始终位于有效视野内；
• 示范动作是否足够稳定、简洁和一致。

2. 再增加数据多样性

简单抓取任务可先采集约 40–50 组数据，并覆盖不同物体位置。若成功率不高，优先增加有效数据，并适度改变位置、光照和背景。不要直接混用别人采集的数据集，因为相机位置、机械臂校准和场景差异会显著影响效果。

3. 最后再调训练与推理

ACT 可作为新手的首个基线。社区经验中，简单任务约 4 万步、50 组高质量数据通常能够看到效果；具体时间取决于 GPU。若 loss 没有明显下降，可以增加训练步数；如果离线结果正常但真机动作间歇卡顿，则应优先检查同步/异步推理设置和本地算力。

训练和评估的完整命令、ACT/SmolVLA/π0/GR00T 等策略入口，请查看 Wiki 的训练与评估章节。

十二、一定要用 Jetson 或高端 GPU 吗？

不一定。

• 组装、校准、遥操作和数据采集：满足教程要求的 Ubuntu 电脑即可完成，不强制使用 Jetson。
• 本地训练：建议使用 NVIDIA GPU。ACT 等较小策略更容易入门；更大的 VLA 模型通常需要更多显存或云端算力。
• 边缘部署：Jetson 适合希望把推理部署到机械臂附近、没有合适 Ubuntu + NVIDIA GPU 主机，或希望减少环境配置工作量的用户。

Windows、WSL 和虚拟机可能遇到 USB 透传、串口权限和实时性问题。若目标是稳定完成真机数据采集，优先选择原生 Ubuntu 环境。

十三、SO-ARM101 怎么选？购买前要注意什么？

SO-ARM101 适合希望低成本跑通 LeRobot 模仿学习流程、学习具身智能或开展教学与原型验证的用户。购买时重点考虑：

• 散件还是组装版：散件适合希望学习舵机配置和机械结构的用户；组装版能跳过大部分机械装配步骤，但仍需完成软件环境与整臂校准。
• Standard 还是 Pro：不同版本的 Follower 舵机与供电可能不同，收到套件后应以实际标签和产品说明为准。
• 是否需要摄像头：模仿学习建议准备稳定的 USB 摄像头视角；腕部可使用 32 × 32 mm UVC 模组，全局视角普通 USB 摄像头即可。
• 是否自己打印结构件：Motor Kit 通常不包含 3D 打印结构件和相机，购买前要核对包装清单。

如果你希望直接开始 SO-ARM101 的遥操作、数据采集与模仿学习，可查看套件：

• SO-ARM101 Pro Servo Motor Kit（适合自行打印结构件）
• SO-ARM101 Pro Assembled Kit（组装版）
• SO-101 Imitation Learning Kit（机械臂、相机与第三视角相机支架）

十四、一张快速诊断表

现象	优先检查	常用解决办法
串口存在但无法连接	权限、端口是否选对	lerobot-find-port，再执行 sudo chmod 666 /dev/ttyACM*
找不到 gripper motor	单舵机连接、三针线、供电	只连接目标舵机，断电重插，检查 ID/波特率
no status packet	电源、总线线缆、舵机 ID	从不亮的舵机和前一级线缆开始逐段检查
Magnitude exceeds 2047	中位值、旧校准文件	断电重启，重新做中位校准和整臂校准
No valid stream found	ffmpeg 版本和路径	安装 ffmpeg=7.1.1，确认 which ffmpeg
相机找不到	序列号、USB 连接	lerobot-find-cameras，更新配置并重新插拔
采集按键无响应	pynput、$DISPLAY	安装 pynput==1.6.8，在图形会话运行
训练 Column 报错	datasets 版本	安装 datasets==2.19
推理一卡一卡	算力、FPS、动作队列	使用异步推理，降低图像负载并调整 chunk 参数
训练后成功率低	数据质量与多样性	清理异常 episode，补充不同位置和光照的数据

结语：按“硬件—通信—校准—数据—模型”的顺序排查

SO-ARM101 的大多数问题都可以沿着一条固定路径定位：

供电与接线 → USB 端口与权限 → 舵机 ID/中位 → 整臂校准 → 遥操作
→ 相机 → 数据集 → 训练环境 → 真机推理

如果前一环没有稳定通过，不建议直接跳到后一环。完整组装图、命令参数、相机配置、数据采集、训练与评估示例，以及持续更新的 FAQ，均可在 Seeed Studio SO-ARM100 / SO-ARM101 × LeRobot 中文 Wiki 中查看。