OpenClaw Troubleshooting Checklist: 4 Pitfalls to Avoid in Feishu Agent Config

If you successfully linked your Feishu custom app with OpenClaw following my previous group chat config tutorial, congratulations! However, during real-world deployments, numerous trivial yet fatal issues can cause your bots to play dead, fail to communicate, or crash the service.

To save you a sleepless night, I’ve compiled the 4 must-know pitfalls I encountered while configuring the setup.

---

Pitfall 1: Forgetting to "Restart the Gateway"

The Symptom: Everything looks perfect, parameters have been triple-checked, yet the bot completely ignores you in the group chat.

The Cause & Solution: No matter how small your configuration change is (whether you edited openclaw.json, added an API read permission in Feishu, or just uploaded a new app icon), you must reload the gateway service for it to latch onto the new hooks!

Run this golden restart command in your terminal:

openclaw gateway restart

Always follow up with a status check to ensure your channels show green lights:

openclaw gateway status

Only when it explicitly returns Feishu: ON | OK and correctly counts your accounts 1/1 can you consider the reload successful.

Pitfall 2: TUI Fatal Error due to Duplicate Feishu Plugins

The Symptom: Upon starting OpenClaw via the TUI or checking status, red text screams a "Fatal Error: Duplicate Feishu plugin found".

The Cause & Solution: OpenClaw installs its core extension packages in the user directory by default. It's highly likely you have two copies of the same logic:

1. ~/.openclaw/extensions/feishu (This is the core working package that must be kept).
2. The demo modules sitting in the extends folder of the downloaded source code.

The Fix: Keep the first one located in your user directory. Boldly delete (or zip backup) the duplicate source package found within your project installation directory.

Pitfall 3: Assuming the "Onboard" Command is Mandatory

Many beginners are misled into believing they must run openclaw onboard to register configurations whenever they touch any service.

In reality, onboard is just an interactive CLI wizard designed to be beginner-friendly. Because configuring enterprise address books and multi-dimensional webhooks involves mapping complex identifiers, manually editing the openclaw.json directly via VS Code is far more straightforward and flexible. Once edited, the system parses it immediately. You do NOT need to run the Onboard flow again.

Pitfall 4: Neglecting to Click "Release" on the Feishu Dashboard

The Symptom: You updated message-read scopes and configured webpage events in the Feishu developer console. You even restarted your local gateway. But you still aren't receiving callbacks!

The Cause & Solution: Feishu enforces strict security protocols for custom enterprise apps. Any addition or deletion of permissions does not immediately apply to the live production version.

You must consistently navigate to the left-hand menu, select Version Management & Release, click Create Version, and submit an Request Release. Only when that version tag turns to a crisp green "Published" will those new permissions actually take effect in your chatbot ecosystem.

---

If you cross-check these four pillars, your digital OpenClaw employees should run effortlessly in the cloud and across your group chats. Feel free to reach out via my website if you encounter more peculiar bugs!