# README 07: Common Questions, Acceptance Methods, and Documentation Archiving
Up to this chapter, the main content of the tutorial has covered environment preparation, wired connection, basic peripherals, visual demos, voice links, and OpenClaw integration. The task of this final chapter is not to add a new feature, but to help readers stabilize the previous chapters. In other words, this chapter aims to address two issues: when a step fails to run, where should one look first; and after all steps succeed, how can one confirm that the tutorial is reproducible and can be preserved over time.
1. Do not reinstall immediately during troubleshooting; first, determine where the problem lies.
Problems in the Magicbox tutorial usually do not appear everywhere simultaneously. More commonly, one layer may be resolved while another remains unresolved. Therefore, the first principle of troubleshooting is not to reinstall blindly, but to determine which layer the issue lies in first. For this tutorial, it can be roughly divided into five layers: network and login layer, peripherals and hardware layer, ROS2 and algorithm node layer, model and storage layer, and OpenClaw gateway layer.
If even ping 192.168.127.10 cannot be accessed, then there is no need to check the voice model path. If the dual-eye page can generate images, but only certain gestures do not respond, then the focus should be on the gesture nodes and the servo control chain, rather than trying to re-apply the image. The more detailed the tutorial, the more the reader needs to develop this hierarchical judgment ability; otherwise, they will treat every problem as a “system failure”.
II. Common Problems and Handling Order
This table is suitable to be placed at the end of the tutorial, allowing readers to check against it directly during practice.
| Phenomenon | Priority Check Items | Common Causes | Recommended Actions |
|---|---|---|---|
| Computer cannot log in to the development board | Wired network IP | Computer is still using DHCP and not switched to the 192.168.127.x range |
First, set the wired network card as a static IP according to Chapter 2 |
| Can ping, but SSH login fails | Account and password | Username, password, or authentication method mismatch | Try the sunrise user first, then check password or key configuration |
| No image appears on the dual-eye screen | Camera connection | Camera wiring, driver, or startup file not working properly | Verify camera input first, then check the hobot_stereonet startup log |
| Gesture recognition shows results but device does not move | Execution layer | Actuator control node not running, or actuator script/space ratio error | Run the basic peripheral script separately first, then review gesture_interaction |
| Voice cannot be recognized | Model and audio device | Missing ASR model, incorrect microphone device ID | Check the three paths in audio_io.launch.py and micphone_name |
| Recognition is normal but no announcement | TTS path or topic | /tts_text has no output, or TTS model directory error |
First, check /tts_text, then examine the TTS configuration directory |
| LLM starts slowly or fails directly | Model loading | GGUF file not placed in /dev/shm, or incorrect model path |
Keep the model on a USB drive and copy it to /dev/shm before startup |
| Entire command block fails to start, but individual commands work normally | Shell switch and environment inheritance | After switching to a new shell in sudo su -, subsequent commands run in a different shell, causing source and ros2 launch to be in different environments |
Do not directly paste the entire command containing sudo su -; enter root separately first, then paste the subsequent commands, or use sudo bash -lc '...' for one-time execution |
| OpenClaw is executable but does not start | Node environment and state directory | Node < 22.12.0, or incorrect permissions/path in state directory |
Check node -v, then check /userdata/magicclaw/state for permissions and mounting |
| Web page can be accessed but assistant response is abnormal | Front-end rendering and session history | Old front-end displays process events as final responses | Force refresh the page and start a new session (e.g., agent:main:test3) before testing again |
exec denied: allowlist miss appears |
Tool allowlist path | Allowlist still points to old script path | Check whether /userdata/magicclaw/state/exec-approvals.json points to /userdata/magicclaw/runtime/bin/magicboxctl |
| OpenClaw runs in foreground but service mode fails | systemd system service | Service does not inherit USB drive environment variables or mounting is not ready | Focus on checking magicclaw.service and magicclaw-runtime-mount logs |
The most important significance of this table is not to list all faults, but to establish a troubleshooting order. As long as the order is correct, problems often resolve quickly.
III. Project-level issues that have been confirmed
In addition to regular troubleshooting, during the actual organization of the warehouse and materials for this project, several item-level issues that need to be clearly written in tutorials have been identified.
The first issue comes from the magicbox_audio_io repository. After cloning the current repository, the SenseVoiceGGUF/sense-voice-small-fp16.gguf large LFS file fails to be fetched. Therefore, the tutorial cannot state that it can be run directly after cloning, but must explicitly require readers to prepare the ASR model manually.
The second issue arises from the repository link in the official voice document. The page contains a repository address like magicboxaudioio, but it is no longer available. Therefore, the tutorial text should return to the locally verified magicbox_audio_io repository, instead of having readers follow the outdated link to a non-functional page.
The third issue stems from the operational environment requirements of OpenClaw itself. The package.json in OpenClaw explicitly requires Node >= 22.12.0. This means that if the Node version at the board end does not meet the requirements, the deployment of OpenClaw should not proceed further. Clarifying this check upfront is more effective than having readers try repeatedly in various error messages later on.
IV. Key Points for Self-checks of Each Chapter
After completing each chapter, conduct a self-check using observable results. Don’t just check if the command was executed, but also ensure that corresponding phenomena occur in the device, web page, terminal log, or Feishu entry.
The key inspection points in the first two chapters are network and login: the computer can stablely ping to the development board, can log in via SSH, and can complete basic management operations with a regular user using sudo. The key inspection point in Chapter 3 is that buttons, lights, servos, and basic scripts can respond independently. In Chapter 4, continuous output on the dual-eye page must be observed, and it must be confirmed that gestures can stabley trigger actions. In Chapter 5, at least one closed loop of “voice input -> LLM response -> TTS announcement” must be completed. In Chapter 6, it is necessary to confirm that OpenClaw Gateway runs in the front-end mode, WebChat can access it, and at least one local bridge script is called.
5. Logs and Status That Are Most Valuable to Keep When Issues Occur
When problems occur, the most valuable thing is not a vague description, but saving the logs and status of the relevant layer. This allows for quick identification of whether the issue occurs in the network, ROS, model, script entry point, or OpenClaw service layer.
For the native capabilities of Magicbox, the most important to be retained are the ROS2 startup terminal logs, model path configuration, whether topics exist, and screenshots of browser pages. For OpenClaw, the most important to be retained are the directory structure of node -v and /userdata/magicclaw/state, /userdata/magicclaw/magicclaw.env(de-identified), and the results of sudo systemctl status magicclaw.service --no-pager and sudo journalctl -u magicclaw.service -n 200 --no-pager.
If these materials are retained, troubleshooting will be much faster, and the same issue can be avoided from being re-identified when it occurs again later.
VI. Why Data Archiving Is Also Important
Once the tutorial enters the long-term maintenance phase, archiving the materials becomes part of the project. Previously, all key pages and official images related to Magicbox and OpenClaw have been placed in the assets directory. The purpose is not only for offline viewing, but also to prevent invalid links, missing hotlink images, or inability to trace source of screenshots from appearing in the tutorial after the official pages are updated.
For this project, there are three key archiving practices that should be maintained consistently. First, try to save the local HTML version of external link documents. Second, keep the original images referenced in tutorials as local files instead of relying on hot links on web pages. Third, save real shot screenshots and experiment logs using a consistent naming format to avoid missing the corresponding evidence later on.
After completing these tasks, the entire tutorial will no longer be just “an experiment that worked at that time,” but will gradually become a reusable, expandable, and continuously updated course package.