Why Your OpenClaw Feishu Plugin Setup Fails on Windows (QR Codes, Conflicts & Uninstall Fixes)

高效码农

4 hours ago

OpenClaw Feishu Plugin Setup on Windows: Fix QR Code Scanning, Plugin Conflicts, and Uninstall Issues

Setting up OpenClaw with the Feishu (Lark) plugin on Windows looks straightforward on paper — a few commands and you’re done. In practice, you’ll likely hit several non-obvious failures: a QR code that refuses to scan, duplicate plugin registrations that silently break your bot, a Feishu channel stuck in OFF state, and an uninstall command that flat-out doesn’t exist.

This guide walks through each of these issues in the order you’re likely to encounter them, with exact commands and the reasoning behind every fix.

The QR Code Won’t Scan in CMD — Here’s Why

Short answer: Windows CMD doesn’t render terminal QR codes at a high enough resolution for phone cameras to read them. Switch to Cmder.

When you run npx -y @larksuite/openclaw-lark install, a QR code appears in the terminal for Feishu authentication. Point your phone at it and… nothing happens. Most people assume the problem is with their Feishu app, their App ID, or their network. It’s none of those.

The real culprit is Windows CMD (cmd.exe) itself. CMD uses a fixed character grid with low pixel density. The QR code it renders lacks the resolution that phone cameras need to reliably detect the positioning markers. PowerShell has the same limitation.

Fix 1 — Switch to Cmder (Recommended)

Cmder is a free, portable terminal emulator for Windows that renders characters at a higher density. The same QR code looks crisp enough to scan.

Download the Full version from https://cmder.app
Unzip and run Cmder.exe — no installation needed
Re-run the install command inside Cmder:

npx -y @larksuite/openclaw-lark install

Scan the QR code with the Feishu mobile app and authentication completes normally.

Fix 2 — Skip the QR Code Entirely

If you’d rather not change terminals, bypass the QR code step and install the plugin directly:

openclaw plugins install @larksuite/openclaw-lark

Then open the OpenClaw Dashboard at http://127.0.0.1:18789/ and complete the Feishu pairing from the web UI. No terminal QR code required.

Lesson learned: Silent failures — where something doesn’t work but nothing tells you why — are the hardest bugs to trace. The right first move isn’t to recheck configuration; it’s to change the environment and see if the symptom disappears. This QR code issue is a textbook example.

Understanding the Feishu Plugin Conflict

Short answer: OpenClaw’s built-in Feishu plugin and the official openclaw-lark plugin cannot run at the same time. Running both causes duplicate tool registration and broken behavior.

OpenClaw ships with a built-in Feishu integration. The official @larksuite/openclaw-lark package is a separate plugin maintained by the Feishu/Lark team. Both register the same tool IDs — feishu_chat, feishu_im_user_message, and others.

When both are active simultaneously, the startup log shows each tool registered twice:

feishu_chat: Registered feishu_chat, feishu_chat_members   ← built-in plugin
feishu_chat: Registered feishu_chat, feishu_chat_members   ← openclaw-lark

At best this causes unpredictable tool call behavior. At worst it triggers a duplicate plugin id error that takes the entire Feishu integration offline.

Which Plugin Should You Use?

	Built-in Feishu Plugin	`@larksuite/openclaw-lark`
Maintained by	OpenClaw team	Feishu / Lark official
Installation	Zero config, ships with OpenClaw	Manual install required
Feature coverage	IM, Calendar, Bitable, Drive, Wiki	Equivalent core feature set
Best for	Most users	Users who need official Feishu support

Pick one and disable the other. They are mutually exclusive.

Reading `openclaw status` Output Correctly

Short answer: The openclaw status output contains everything you need to diagnose Feishu integration problems — if you know which fields to look at.

Run openclaw status and you’ll see several sections. These are the ones that matter most for Feishu troubleshooting:

Gateway Reachability

Gateway  local · ws://127.0.0.1:18789 (local loopback) · unreachable (missing scope: operator.read)

unreachable combined with missing scope: operator.read means the Gateway lacks sufficient permissions for agent-to-agent communication. Fix it with:

openclaw gateway probe

Follow the output instructions to add the missing scope.

Feishu Channel State

| Feishu | OFF | OFF | disabled |

The Feishu channel is explicitly disabled. This is independent of whether the plugin is installed — a channel can be disabled even when the plugin is present. This needs to be turned on separately (see Section 5).

Duplicate Plugin Registration in Logs

If the same tool name appears twice in the startup log, you have both Feishu plugins running. Address this before anything else.

Security Audit Warnings

The status output ends with a security audit. Two warnings are worth acting on:

Permissive tool policy: The openclaw-lark plugin tools are accessible to agents handling potentially untrusted input. For agents in those contexts, set a minimal profile to restrict tool access.
Unpinned plugin version: The install record shows @larksuite/openclaw-lark without a version pin. For production environments, pin to a specific version like @larksuite/openclaw-lark@1.2.3 to avoid supply chain instability.

How to Uninstall `openclaw-lark` (The Command Doesn’t Exist Yet)

Short answer: openclaw plugins uninstall is not yet implemented. You’ll get a “Plugin not found” error. Uninstall requires manual steps.

This surprises a lot of people. Running:

openclaw plugins uninstall @larksuite/openclaw-lark

Returns: Plugin not found: @larksuite/openclaw-lark

This isn’t a path error or a name mismatch — the uninstall subcommand simply doesn’t exist in the current version. It’s a known gap in the CLI. Manual removal is the only option.

Full Manual Uninstall on Windows

Step 1 — Disable the plugin first

openclaw plugins disable openclaw-lark

Step 2 — Edit the config file to remove the plugin record

Open this file in any text editor:

%USERPROFILE%\.openclaw\openclaw.json

Find and delete both of these entries:

// Under plugins.entries — delete:
"openclaw-lark": { ... }

// Under plugins.installs — delete:
"openclaw-lark": "@larksuite/openclaw-lark"

Save the file.

Step 3 — Delete the plugin directory

rmdir /s /q "%USERPROFILE%\.openclaw\extensions\openclaw-lark"

Step 4 — Restart the Gateway

openclaw gateway restart

Step 5 — Verify removal

openclaw status

Confirm that the openclaw-lark warning no longer appears in the security audit section and the plugin is absent from the plugin list.

Personal reflection: A missing uninstall command is the kind of gap that disproportionately affects users who followed the official install docs — because those are exactly the people who will try to undo what the docs told them to do. Until this is implemented, the manual steps above are the only path.

Re-enabling the Built-in Feishu Plugin After Uninstall

Short answer: Removing openclaw-lark doesn’t automatically re-enable the built-in Feishu plugin. You need to turn it on explicitly.

After completing the uninstall steps above, the Feishu channel will still show as OFF. Run these three commands to restore full functionality:

openclaw plugins enable feishu
openclaw gateway restart
openclaw status

After the restart, the Feishu row in the Channels table should show ON. Your bot should be able to send and receive messages again.

Why `openclaw config set feishu.enabled true` Throws an Error

Short answer: feishu is not a valid top-level config key. The Feishu channel is controlled through the plugin system, not through config set.

If you try:

openclaw config set feishu.enabled true

You get:

Error: Config validation failed: <root>: Unrecognized key: "feishu"

The config schema doesn’t have a top-level feishu namespace. Channel enable/disable state lives in the plugin system. The correct command is:

openclaw plugins enable feishu    # enable built-in plugin
openclaw plugins disable feishu   # disable built-in plugin

Complete Setup Checklists

Path A — Using the Official `openclaw-lark` Plugin

# 1. Open Cmder (not CMD) to avoid QR code rendering issues

# 2. Install the official plugin
npx -y @larksuite/openclaw-lark install

# 3. Disable the built-in Feishu plugin to prevent conflicts
openclaw plugins disable feishu

# 4. Restart the Gateway
openclaw gateway restart

# 5. Confirm status
openclaw status

Path B — Using the Built-in Feishu Plugin

# 1. Manually uninstall openclaw-lark (follow Section 4 above)

# 2. Enable the built-in plugin
openclaw plugins enable feishu

# 3. Restart the Gateway
openclaw gateway restart

# 4. Check Gateway reachability
openclaw gateway probe

# 5. Confirm status
openclaw status

Quick Reference Table

Problem	Root Cause	Fix
QR code won’t scan in CMD	CMD renders characters at too low a resolution	Switch to Cmder, or skip QR code with `plugins install`
Same tool registered twice in logs	Both Feishu plugins running simultaneously	Disable one: `plugins disable feishu` or `plugins disable openclaw-lark`
Feishu Channel shows OFF	Channel explicitly disabled	`openclaw plugins enable feishu`
`plugins uninstall` returns “Plugin not found”	The uninstall subcommand doesn’t exist yet	Manual removal: edit config file + delete directory
`config set feishu.enabled` throws error	`feishu` is not a valid config key	Use `plugins enable feishu` instead
Gateway shows `unreachable`	Missing `operator.read` scope	Run `openclaw gateway probe` and follow instructions

FAQ

Q: Does installing @larksuite/openclaw-lark automatically disable the built-in Feishu plugin?

No. Both plugins remain active unless you explicitly disable one. You must run openclaw plugins disable feishu after installing openclaw-lark to prevent conflicts.

Q: Why does openclaw plugins uninstall not work?

The uninstall subcommand has not been implemented in the current version of the OpenClaw CLI. Removing a plugin requires manually editing %USERPROFILE%\.openclaw\openclaw.json and deleting the plugin directory.

Q: The Feishu channel shows OFF even though the plugin is installed. What’s wrong?

A disabled channel is separate from an installed plugin. Run openclaw plugins enable feishu followed by openclaw gateway restart. If the channel still shows OFF after that, check the startup log for duplicate tool registrations indicating a plugin conflict.

Q: The Gateway shows unreachable but everything seems to work locally. Is this a problem?

For local-only use (loopback), the impact is minimal. However, if you’re exposing the control UI through a reverse proxy or running multi-node setups, unreachable will break inter-node communication. Run openclaw gateway probe to identify and fix the specific issue.

Q: Is there a risk to leaving the openclaw-lark version unpinned?

Yes, especially in production. An unpinned install record means each reinstall may pull a different version. Pin to a specific version — for example @larksuite/openclaw-lark@1.2.3 — by editing the install record in openclaw.json or reinstalling with the version specified.

Q: Do I need to restart the entire system when switching between Feishu plugins?

No. A Gateway restart is sufficient: openclaw gateway restart. Plugin changes take effect after the Gateway process reloads.

Q: The QR code still won’t scan even in Cmder. What now?

Skip the QR code entirely. Run openclaw plugins install @larksuite/openclaw-lark to install without scanning, then complete Feishu authorization from the Dashboard web UI at http://127.0.0.1:18789/. The web UI handles authentication without relying on terminal rendering.

Q: Can I run both Feishu plugins at the same time if I need features from both?

No. The two plugins share the same tool IDs and cannot coexist. Running both simultaneously causes duplicate plugin id errors and breaks Feishu functionality entirely. Choose one and disable the other.