README 07：常见问题、验收方法与资料归档
到这一章为止，教程的主体内容已经覆盖了环境准备、有线连接、基础外设、视觉 Demo、语音链路和 OpenClaw 接入。最后这一章的任务，不再是新增一个功能点，而是帮助读者把前面各章真正稳定下来。换句话说，本章要解决的是两个问题：当某一步跑不通时，应该先查哪里；当全部跑通以后，应该怎样确认这套教程已经达到可复现、可长期保存的程度。
一、排障时不要一上来就重装，先判断问题在哪一层
Magicbox 教程里的问题，通常不会同时出在所有地方。更常见的情况，是某一层已经通了，另一层还没有通。因此，排障的第一原则不是盲目重装，而是先判断问题位于哪一层。对这套教程来说，大体可以分成五层：网络与登录层、外设与硬件层、ROS2 与算法节点层、模型与存储层，以及 OpenClaw 网关层。
如果连 ping 192.168.127.10 都不通，那就先不要去查语音模型路径；如果双目页面已经能出图，却只有手势动作不响应，那就应该优先回到手势节点和舵机控制链，而不是再回去重新刷镜像。教程越写得详细，读者越需要学会这种分层判断能力，否则会把每一个问题都当成“系统坏了”。
二、最常见的问题与处理顺序
下面这张表适合放在教程最后，读者在实操时可以直接对照检查。
| 现象 | 优先检查项 | 常见原因 | 建议处理方式 |
|---|---|---|---|
| 电脑无法登录开发板 | 有线网口 IP | 电脑仍在 DHCP，未切到 192.168.127.x 网段 |
先按第二章把电脑有线网卡设为静态 IP |
| 能 ping 通但 SSH 登录失败 | 账号与密码 | 用户名、密码或认证方式不匹配 | 先尝试 sunrise 用户，再检查密码或密钥配置 |
| 双目页面不出图 | 相机链路 | 相机接线、驱动或启动文件未正确运行 | 先确认相机输入，再确认 hobot_stereonet 启动日志 |
| 手势识别有结果但设备不动作 | 执行层 | 舵机控制节点未运行，或舵机脚本/占空比异常 | 先单独跑基础外设脚本，再回查 gesture_interaction |
| 语音无法识别 | 模型与音频设备 | ASR 模型缺失、麦克风设备号错误 | 检查 audio_io.launch.py 三条路径和 micphone_name |
| 识别正常但没有播报 | TTS 路径或话题 | /tts_text 无输出，或 TTS 模型目录错误 |
先查看 /tts_text，再检查 TTS 配置目录 |
| LLM 启动慢或直接失败 | 模型加载 | GGUF 文件未放到 /dev/shm，或模型路径错误 |
模型常驻放 U 盘，启动前复制到 /dev/shm |
| 整段粘贴启动命令失败，但逐条执行正常 | Shell 切换与环境继承 | sudo su - 切到新 shell 后，后续命令落在不同 shell，导致 source 和 ros2 launch 不在同一环境 |
不要把包含 sudo su - 的整段命令直接无脑粘贴；先单独进入 root，再粘贴后续命令，或改用 sudo bash -lc '...' 一次性执行 |
| OpenClaw 可执行但起不来 | Node 环境与状态目录 | Node < 22.12.0，或状态目录权限/路径不对 |
先查 node -v，再查 /userdata/magicclaw/state 权限与挂载 |
| 网页能连上但助手回复异常 | 前端渲染与会话历史 | 旧版前端把过程事件当成最终回复展示 | 强制刷新页面并换新会话键（如 agent:main:test3）再测 |
出现 exec denied: allowlist miss |
工具白名单路径 | allowlist 仍指向旧脚本路径 | 检查 /userdata/magicclaw/state/exec-approvals.json 是否指向 /userdata/magicclaw/runtime/bin/magicboxctl |
| OpenClaw 前台可运行，服务模式失效 | systemd 系统服务 | 服务未继承 U 盘环境变量或挂载未就绪 | 重点检查 magicclaw.service 与 magicclaw-runtime-mount 日志 |
这张表最重要的意义，不是列出所有故障，而是建立一种排查顺序。只要顺序对了，问题往往会很快收敛。
三、目前已经确认的项目级问题
除了常规排障，本项目在实际整理仓库和资料时，还已经确认了几个需要明确写入教程的项目级问题。
第一个问题来自 magicbox_audio_io 仓库。当前仓库克隆后，SenseVoiceGGUF/sense-voice-small-fp16.gguf 这个 LFS 大文件存在拉取失败的情况，因此教程不能把语音部分写成“克隆即可直接运行”，而必须显式要求读者手动准备 ASR 模型。
第二个问题来自官方语音文档中的仓库链接。页面中出现过 magicboxaudioio 这样的仓库地址，但当前已不可用。因此，教程正文应当统一回到本地已经验证存在的 magicbox_audio_io 仓库，不再让读者顺着旧链接走到失效页面。
第三个问题来自 OpenClaw 本身的运行环境要求。OpenClaw 的 package.json 明确要求 Node >= 22.12.0。这意味着只要板端 Node 版本不满足条件，OpenClaw 部署就不应该继续往下推进。把这一点前置检查清楚，比后面让读者在各种错误信息中反复试错更有效。
四、各章节自检要点
完成每一章后，先用可观察的结果做一次自检。不要只看命令是否执行完，而要确认设备、网页、终端日志或飞书入口是否出现了对应现象。
前两章的自检重点是网络与登录：电脑能稳定 ping 到开发板，能通过 SSH 登录，并能用普通用户配合 sudo 完成基础管理操作。第三章的自检重点是按钮、灯光、舵机和基础脚本均能独立响应。第四章需要看到双目页面持续输出，并确认手势可以稳定触发动作。第五章至少完成一轮“语音输入 -> LLM 回答 -> TTS 播报”闭环。第六章需要确认 OpenClaw Gateway 能以前台模式跑起来，WebChat 能访问，且至少能调用一次本地桥接脚本。
五、出现问题时最值得保留的日志与状态
出现问题时，最有价值的不是模糊描述，而是把对应层的日志和状态保存下来。这样才能快速判断问题发生在网络、ROS、模型、脚本入口还是 OpenClaw 服务层。
对 Magicbox 原生能力来说，最值得保留的是 ROS2 启动终端日志、模型路径配置、话题是否存在以及浏览器页面的截图。对 OpenClaw 来说，最值得保留的是 node -v、/userdata/magicclaw/state 目录结构、/userdata/magicclaw/magicclaw.env（脱敏后）和 sudo systemctl status magicclaw.service --no-pager 与 sudo journalctl -u magicclaw.service -n 200 --no-pager 的结果。
如果把这些材料都保留下来，排障会快很多，也能避免同一个问题在后续复现时重复定位。
六、资料归档为什么同样重要
教程一旦进入长期维护阶段，资料归档本身就是工程的一部分。前面已经把 Magicbox 和 OpenClaw 相关的关键页面与官方图片都放进了 assets 目录，这么做的目的，不只是为了离线查看，更是为了防止官方页面更新后，教程里出现失效链接、热链图片丢失或截图无法追溯来源的问题。
对本项目来说，最应当持续保持的归档习惯有三条。第一，外链文档尽量保存本地 HTML 版本。第二，教程里实际引用的图片尽量保存本地原图，而不是依赖网页热链。第三，实拍截图和实验日志要按照统一命名方式保存，避免后续找不到对应章节的现场证据。
把这些工作做好以后，整套教程就不再只是“当时能跑通的一次实验”，而会逐步变成一套可以复用、可以扩展、也可以持续更新的课程资料包。