logo Mr.Robota 具身智能学习手册
/
中文
Chapter 16: Damo Institute & Datawhale Online Team Learning

README 09: Feishu Control Desk Pet

After completing this chapter, readers should be able to use Feishu as the main entry point for OpenClaw, and control the status, mode, and board capabilities of MagicBox table pets through Feishu messages. The web frontend is no longer the only entry point; it can be retained as a backup option if necessary.

1. First, clarify two things

The Feishi capabilities of OpenClaw are divided into two layers.

The first layer consists of OpenClaw’s own gateway and robot plugins. It is responsible for sending Feishu messages to the local OpenClaw, and returning replies back to Feishu.

The second layer is the board-side capabilities, which are the magicboxctl set of commands. It is responsible for actually controlling lighting, voice, servos, button mappings, and the Demo.

This means that the “status reply” seen in Feishu is essentially still on the board, but OpenClaw has converted the results into Feishu messages.

II. Start the Feishu Gateway first

After installing the Lark plugin, if Gateway service missing appears in the log, it usually indicates that the plugin has been installed, but the gateway service has not started yet.

On the Windows computer where OpenClaw is installed, execute first:

powershellopenclaw gateway install
openclaw gateway
openclaw gateway status

If there are already scheduled tasks in the system, you can also start them directly:

powershellschtasks /Run /TN "OpenClaw Gateway"

If you want to continue watching the logs, you can run it again:

powershellopenclaw logs --follow

After confirming that the gateway is running and the Feishu robot has been configured, send a message in Feishu to test it.

If you have manually started the gateway at the front end, to restart it, just use:

powershellopenclaw gateway restart
  1. If you are using the foreground process running in the window, Ctrl+C will only stop the current foreground process; it will not clear the history sessions in Feishu, nor will it automatically split old sessions into new ones.
  2. Therefore, it is important to distinguish between two things:
  • openclaw gateway restart: Restart the gateway process
  • /reset: Clear the current session history in Feishu

If you want to restart a Lark conversation, send it in Lark first:

text/reset

If you want to start a new test session separately, you can also directly use a new sessionKey. For example:

text请把 sessionKey 设为 agent:main:test7。

II.1 If you want to directly query the board side

Some issues are not suitable to be resolved solely through Feishu. Especially when you need to verify board services, lighting, voice links, or button mappings, directly connecting to the board via SSH is faster.

Log in to the board first:

bashssh sunrise@192.168.127.10

If root privileges are required, switch to root:

bashsudo -s
# 或者
sudo su -

Board-side control is unified through:

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

Common board-end inspection commands also include:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl voice status
sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons show
sudo /userdata/magicclaw/runtime/bin/magicboxctl fan status

If you want to test the lighting immediately, you can directly execute it at the board end:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl led preset red
sudo /userdata/magicclaw/runtime/bin/magicboxctl led rgb 255 0 0

II.2 If Feishu wants to truly control the dashboard

To truly implement the actions defined in Feishu, one of the following two methods is usually required:

  1. OpenClaw has obtained the available board-side tools, which can directly call magicboxctl.
  2. When there are no board-side tools, first SSH to the board side, and then execute magicboxctl on the board side.

So when Lark replies to you, “I currently don’t have an available interface to control the MagicBox light effect,” don’t just ask, “Can it be done?” Instead, follow this approach:

First, SSH to the board:

bashssh sunrise@192.168.127.10

Execute the board command again:

bashsudo /userdata/magicclaw/runtime/bin/magicboxctl status
sudo /userdata/magicclaw/runtime/bin/magicboxctl led preset red
sudo /userdata/magicclaw/runtime/bin/magicboxctl led rgb 255 0 0
sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons show
sudo /userdata/magicclaw/runtime/bin/magicboxctl voice status
sudo /userdata/magicclaw/runtime/bin/magicboxctl servo both 10 50

The purpose of this path is to transform the “intent in Feishu” into “clear commands on the board”. Once the commands on the board are working properly, using tools from Feishu will be much smoother.

III. Common Commands That Can Be Used in Lark

The Feishu entry for OpenClaw is currently a “text command” and not a separate button panel. The most common built-in commands are:

text/status
/reset
/model

They are used for respectively:

  • /status: View the current session, model, and running status
  • /reset: Reset the current session
  • /model: View or switch models

If you want to use Feishu as the main control interface for your desk pet, it is recommended to write common needs in short sentences instead of thinking about how to click in the browser first. The following sentence patterns are more suitable for sending directly to Feishu:

  • 请返回当前板端状态。
  • 请告诉我当前时间。
  • 请列出当前技能。
  • 请启动双目模式。
  • 请启动手势模式。
  • 请启动完整语音对话。
  • 请执行 YOLO Demo。
  • 请把左键设为双目，中键设为手势，右键设为语音对话。
  • 请朗读一句：你好，我已经启动。
  • 请把左支撑角转到 15 度，右支撑角转到 45 度。
  • 请把四个灯全部设为红色。
  • 请把第1盏灯设为红色，第2盏灯设为绿色，第3盏灯设为蓝色，第4盏灯设为白色。
  • 请让灯光闪烁三次，颜色用蓝色。

The advantage of these short sentences is that readers don’t need to remember the underlying scripts; they only need to remember their goals. OpenClaw will convert them into board-side tool calls.

IV. If Feishu requires you to provide sessionKey

Sometimes, after you send a control request in Feishu, the robot will respond with “The current session does not have a board status” or “Please provide the sessionKey/device name first.” This is not due to a failure in the lighting command, but because this Feishu message has not been linked to a specific board session yet.

This type of hint usually appears in two situations:

  • You are starting a new Lark conversation; OpenClaw still doesn’t know which board it corresponds to.
  • You are using natural language, but the robot currently needs clear conversation keys to locate the target board end.

In such cases, just add a board identifier in Feishu directly. The most stable way to write it is:

text请把 sessionKey 设为 agent:main:test7，然后返回当前板端状态。

Or:

text请控制 agent:main:test7 这块板子，把四个灯都设为红色。

If you don’t want to remember the session key, at least clarify the “target board”, for example:

text请控制当前这块 MagicBox，把四个灯设为红色。

If the robot still asks for the sessionKey, it means it has not received clear target binding information. In this case, do not repeat the same lighting command; instead, complete the session key or panel name first, and then continue with the control instructions.

IV. How to reset the board status

If you just want to know how the desk pets are doing now, the best way is to have the Feishu robot return a brief summary, rather than reporting a bunch of underlying logs.

The summaries that are currently confirmed to be available on the board include:

  • Installation root directory
  • Current time
  • USB drive usage status
  • magicclaw.service status
  • magicclaw-buttons.service status
  • Dual-eye, gesture, voice, YOLO mode status
  • Voice link status
  • Volume status

In other words, when asking “current board status” in Feishu, the response should look like this:

  • Is the gateway online?
  • In what mode is the desk pet currently in?
  • Has the voice link been activated?
  • Are the lights and servos available?

If you need more detailed system metrics such as CPU, memory, and load, the current magicboxctl status does not treat them as default fields yet. You can add a dedicated skill for this requirement later, but do not mistakenly assume that it already supports these metrics.

If you plan to use Feishu as the main entry point, it is recommended to follow the order below.

  1. Start the OpenClaw gateway on Windows.
  2. Confirm that the robot is configured successfully in Feishu.
  3. Send /status first to ensure both the gateway and session are working properly.
  4. Then send a board-side summary request, such as 请返回当前板端状态。.
  5. Finally, send control commands, such as 请启动语音对话, 请执行双目模式, or 请调整舵机到打招呼姿态.

The advantage of doing this is that you can verify the link first, then verify the control, making it easier to locate the problem.

VI. Common Questions

1. Gateway service missing appears in the log

This indicates that you have only installed plugins, but the gateway has not been started. Execute first:

powershellopenclaw gateway install
openclaw gateway

Back to Feishu testing.

2. Robots can be received in Feishu, but there is no action on the board

First, confirm whether magicclaw.service and magicclaw-buttons.service at the board end are working properly, and then check if there are any corresponding skill or command mappings.

3. Just want to use Feishu and not need a web frontend anymore

Yes. Lark can be used as the main entry point, and the Lite web page can only be retained as a backup entry point.

4. Want to ask about CPU/memory/load

The current default command does not expose these metrics separately. It is recommended to first check the board summary; if system metrics are needed later, add a dedicated skill.

VII. Conclusion of this Chapter

If you want to use OpenClaw as the main entry point for a desk pet, the most reliable approach is not to focus on individual web pages first, but to start running the Feishu gateway and consolidate the common board capabilities into a few text commands.

In this way, readers only need to remember three things:

  1. The gateway must be activated.
  2. Short phrases or slash commands can be sent in Feishu.
  3. The actual “desk pet” actions are still performed by magicboxctl.