Часть 07: частые вопросы, методы проверки и архивация материалов
К этой главе основной текст учебника уже охватывает подготовку окружения, проводное подключение, базовую периферию, демонстрации компьютерного зрения, голосовую цепочку и подключение OpenClaw. Эта последняя глава не добавляет новую функцию. Её задача — помочь читателю довести уже пройденное до устойчивого состояния. Иными словами, глава отвечает на два вопроса: что делать, если какой-то шаг не работает, и как понять, что весь учебник доведён до воспроизводимого и долговременно сохраняемого состояния.
1. При сбое не переустанавливайте всё сразу: сначала определите слой
Проблемы в учебнике Magicbox обычно возникают не во всех местах одновременно. Чаще всего один слой уже работает, а другой ещё нет. Поэтому первый принцип отладки — не переустанавливать всё, а сначала понять, в каком слое проблема. Для этого учебника можно выделить пять слоёв: слой сети и входа, слой периферии и оборудования, слой ROS2 и узлов алгоритмов, слой моделей и хранения, а также слой шлюза OpenClaw.
Если даже ping 192.168.127.10 не проходит, не стоит сразу проверять путь к голосовой модели. Если страница бинокулярного зрения уже выводит изображение, а жесты распознаются, но устройство не двигается, нужно сначала вернуться к узлу жестов и к цепочке управления сервоприводами, а не перепрошивать образ. Чем подробнее написан учебник, тем важнее научиться такому послойному мышлению: иначе каждую проблему будешь воспринимать как «система сломана».
2. Наиболее частые проблемы и порядок их проверки
Таблица ниже предназначена для того, чтобы читатель мог сверяться с ней во время практики.
| Симптом | Что проверить в первую очередь | Частая причина | Что делать |
|---|---|---|---|
| Компьютер не входит на плату | 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 или путь к модели ошибочен | храните модель на USB и копируйте в /dev/shm перед запуском |
| Полная вставка команды запуска не работает, но по одной команде всё в порядке | смена оболочки и наследование окружения | после sudo su - команды выполняются в другой оболочке, и 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 | путь в списке разрешённых инструментов | в списке разрешённых ещё указан старый путь скрипта | проверьте, что /userdata/magicclaw/state/exec-approvals.json указывает на /userdata/magicclaw/runtime/bin/magicboxctl |
| Работает в переднем плане, но не работает в режиме службы | служба systemd | служба не получает переменные окружения с USB, либо монтирование не готово | в первую очередь проверьте журналы magicclaw.service и magicclaw-runtime-mount |
Главная ценность этой таблицы не в перечне всех сбоев, а в том, что она задаёт порядок проверки. Если порядок правильный, проблема обычно быстро сужается.
3. Проблемы уровня проекта, подтверждённые при работе
Кроме обычной отладки, при подготовке репозитория и материалов были выявлены несколько проблем уровня проекта, которые необходимо явно описать в учебнике.
Первая проблема связана с репозиторием magicbox_audio_io. После клонирования файл большой модели SenseVoiceGGUF/sense-voice-small-fp16.gguf, хранящийся через Git LFS, иногда не загружается. Поэтому в учебнике нельзя писать, что голосовая часть «работает сразу после клонирования»; читателю нужно явно предложить самостоятельно подготовить модель ASR.
Вторая проблема касается ссылок на репозитории в официальной голосовой документации. На странице иногда встречался адрес вида magicboxaudioio, который сейчас недоступен. Поэтому основной текст должен ссылаться на локальный и проверенный репозиторий magicbox_audio_io, а не отправлять читателя по устаревшим ссылкам.
Третья проблема связана с требованиями среды для самого OpenClaw. В package.json OpenClaw прямо указано Node >= 22.12.0. Если версия Node на плате не соответствует этому условию, развёртывание OpenClaw дальше продолжать не стоит. Такую предварительную проверку лучше выполнять в начале, а не разбираться с ошибками на последующих шагах.
4. Контрольные точки после каждой главы
После каждой главы проверяйте результат по наблюдаемым признакам. Не ограничивайтесь тем, что команда завершилась; убедитесь, что на устройстве, в браузере, в журнале терминала или во входе Feishu появилось ожидаемое явление.
Для первых двух глав проверка состоит в том, что компьютер стабильно пингует плату, входит по SSH и может с помощью обычного пользователя и sudo выполнять базовые административные действия. Для третьей главы — что кнопки, подсветка, сервоприводы и базовые скрипты независимо реагируют. Для четвёртой главы — что страница бинокулярного зрения непрерывно выводит данные и что жесты стабильно вызывают движения. Для пятой главы — что проведён хотя бы один полный цикл «голосовой ввод → ответ LLM → озвучивание». Для шестой — что шлюз OpenClaw Gateway запускается в переднем плане, открывается WebChat и хотя бы один раз вызывается локальный скрипт-мост.
5. Какие журналы и состояния стоит сохранять при сбое
Когда что-то ломается, ценны не описания вроде «не работает», а сохранённые журналы и состояния соответствующего слоя. Это позволяет быстро понять, где проблема: в сети, в 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.
Если эти материалы сохранены, отладка идёт гораздо быстрее, и та же проблема не придётся определять заново при повторном воспроизведении.
6. Почему архивирование материалов так же важно
Когда учебник переходит в стадию долгого сопровождения, архивация материалов становится частью инженерной работы. Выше все ключевые страницы и официальные изображения по Magicbox и OpenClaw сохранены в каталоге assets. Делается это не только для автономного просмотра: цель в том, чтобы после обновления официальных страниц в учебнике не появлялись нерабочие ссылки, пропавшие изображения или снимки без источника.
Для этого проекта стоит постоянно соблюдать три правила. Во-первых, внешние документы лучше сохранять в виде локальных HTML-копий. Во-вторых, изображения, которые реально используются в учебнике, нужно хранить как локальные оригиналы, а не полагаться на горячие ссылки на сайте. В-третьих, реальные снимки и журналы экспериментов следует сохранять по единой схеме имён, чтобы потом было легко найти подтверждение для каждой главы.
Если эти правила соблюдаются, учебник перестаёт быть «одним удачным экспериментом», а становится пакетом учебных материалов, который можно повторно использовать, расширять и постоянно обновлять.