README 06: OpenClaw Deployment, Integration, and Launch

After completing this chapter, readers should be able to accomplish three things on MagicBox. First, understand how the front-end and back-end processes automatically start after the machine restarts. Second, know what command to enter to manually start the service if it does not recover automatically. Third, know which address the web front-end should access, and which addresses are backend interfaces rather than front-end pages.

1. What to Check First After Restarting

After the machine restarts, don’t immediately open a browser. First, execute the following three commands in the terminal of the development board to ensure that the backend and button handlers are ready.

bashsudo systemctl status magicclaw.service --no-pager
sudo systemctl status magicclaw-buttons.service --no-pager
curl http://127.0.0.1:18789/health

Only when you see the following results indicates that the system has entered the operational state.

• magicclaw.service displays active (running).
• magicclaw-buttons.service displays active (running).
• The health check returns results similar to {"ok":true,"status":"live"}.

If this step fails, continue with the service first and then check the web page. Since the web page is just an access point, it will not function properly when the backend is not available.

II. How to manually start front-end and back-end after restarting

Under normal circumstances, these two services are set to start automatically upon boot by systemd. This means that they will start automatically after the machine restarts, without the need for manual command input each time.

If the service does not start after turning on the machine, you can directly execute the following set of commands manually.

bashsudo systemctl start magicclaw.service
sudo systemctl start magicclaw-buttons.service

If you want it to start automatically every time you boot the system in the future, simply execute this set of commands.

bashsudo systemctl enable magicclaw.service
sudo systemctl enable magicclaw-buttons.service

If you need to reload the configuration and restart the service, you can execute:

bashsudo systemctl daemon-reload
sudo systemctl restart magicclaw.service
sudo systemctl restart magicclaw-buttons.service

III. How to access the web front end

The currently stable and available web entry is:

texthttp://192.168.127.10:18789/

This address has now been used as the Lite front end provided in this tutorial. It is suitable for course demonstrations, web page control, and local network debugging.

If the browser automatically jumps to the old chat page, or device identity required appears on the old page, do not treat it as the main entry and keep refreshing repeatedly. The old page is a historical compatibility entry; this tutorial does not recommend using it as a daily operation entry.

Be careful with the two addresses below.

• http://192.168.127.10:18789/: Front-end entry for web pages, to be used first.
• http://127.0.0.1:18791/: Backend authentication interface; not the front-end page that is opened directly.

It is normal to directly open 18791 and return to Unauthorized, as it requiresBearer Token authentication, and it is not the front-end UI itself.

IV. What is the relationship between the three left, middle, and right buttons and web control?

In this chapter, the MagicClaw takeover key mode is used by default, instead of the original factory key mode.

• left: Left button when the device faces the user.
• middle: Middle button.
• right: Right button when the device faces the user.

The current three keys can be remapped to stereo, gesture, voice_chat, voice_asr, yolo, stop_all, and off actions.

View current mapping:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl buttons show

Write a set of default mappings:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl buttons set left stereo
sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons set middle gesture
sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons set right voice_chat

Simulated keys:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl buttons invoke right

5. Which commands should start the voice link first

voice say and voice prompt are not independent local reading commands; a voice connection must exist before they can operate.

Start the recognition base first:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice asr start

Check the status again:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice status

If you want to start the full conversation link, execute the following:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice chat start

It is meaningful to execute the following two commands after having voice_asr: running and voice_chat: running.

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice say "你好，这是板端朗读测试。"
sudo /userdata/magicclaw/runtime/bin/magicboxctl voice prompt "请只回答：测试通过。"

If the command gets stuck at Waiting for at least 1 matching subscription(s)..., it means there is no subscriber listening to the corresponding topic, not that the command is written incorrectly.

VI. How to Use the Actuator Commands

The servo commands do not rely on ROS; they can be executed directly.

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl servo set left 15
sudo /userdata/magicclaw/runtime/bin/magicboxctl servo set right 45
sudo /userdata/magicclaw/runtime/bin/magicboxctl servo greet 1

In this section, left and right refer to the left and right support angles when the device faces the user. In the current script, the left foot PWM pin is 32, and the right foot PWM pin is 33. The safe angle range should be maintained at 0-90, and 30 is recommended as the midpoint.

If there is no action after the command is executed, first check the permissions and GPIO usage, then check the hardware connections. Do not check ROS first.

VII. Common Issues

1. Page display device identity required

This usually appears on an old chat page because the gateway has not been started. Execute first:

bashcurl http://127.0.0.1:18789/health

If the health check is normal, simply use the home page http://192.168.127.10:18789/, and do not keep refreshing the old chat page repeatedly.

2. Page display Unauthorized

This is a normal response from the 18791 backend interface. This address is not a web front-end; do not treat it as an UI page to open.

3. voice say or voice prompt is waiting indefinitely

Execute first:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice status

Confirm whether voice_asr or voice_chat has been executed. If not, start the corresponding link first.

VIII. The final startup sequence in this chapter

If you only want to remember the shortest process, remember these four steps below.

1. Check the services after restarting:

bashsudo systemctl status magicclaw.service --no-pager
sudo systemctl status magicclaw-buttons.service --no-pager

2. If the service doesn’t start, start it manually:

bashsudo systemctl start magicclaw.service
sudo systemctl start magicclaw-buttons.service

3. Open the web frontend:

texthttp://192.168.127.10:18789/

4. Start the voice link only when speech is needed:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice chat start

9. If you want to change it to the main entrance of Feishu

If you decide later not to use the web front end as the main entry point, but instead use Feishu directly to control the desk pets, the startup order should be changed to “first run the Feishu gateway, then let Feishu messages drive the board capabilities”.

First, execute it on the Windows computer where OpenClaw is installed:

powershellopenclaw gateway install
openclaw gateway
openclaw gateway status

If a scheduled task has already been registered in the system, you can also use:

powershellschtasks /Run /TN "OpenClaw Gateway"

When Gateway service missing appears in the installation log, it usually means the plugin has been installed, but the gateway has not started yet. At this point, do not continue with the repeated scanning; first start the gateway process, and then return to Feishu for testing.

The most common text commands in Feishu are:

text/status
/reset
/model

/status is used to view the current session and running status, /reset is used to reset the current session, and /model is used to view or switch models. If you want to check the status of the desk pet itself, simply send natural language in Feishu, for example:

• 请返回当前板端状态。
• 请告诉我当前时间。
• 请列出当前技能。
• 请总结语音、按键、灯光、舵机和 Demo 的状态。

Whether you can directly see the CPU values in Feishu depends on whether you have added an onboard tool. Currently, this magicboxctl status only ensures that it returns information about the installation root directory, time, disk usage, service status, mode status, and volume summary, without including CPU as a default field. If you actually need CPU/memory/load later, it is recommended to add a separate skill or tool; do not assume it already exists as an existing capability.

If you plan to use Feishu as the main entry point, simply revert the Web Lite page to a backup entry point. This way, during course presentations, only the Feishu message flow can be retained, without relying on the browser page anymore.