OpenClaw Feishu Channel Troubleshooting

Symptoms you may see

• Bot can be added, but it never replies in DM/group
• Message send API returns permission errors
• Gateway seems healthy, but channel is silent

Step 1: Confirm gateway is alive first

openclaw gateway status
openclaw gateway restart

If gateway is not healthy, solve this first. Channel debugging is meaningless if the core service is down.

Step 2: Check Feishu app scopes (most common root cause)

One of our real incidents was a missing scope: contact:contact.base:readonly. Without it, user/contact resolution can fail and message flow breaks.

feishu_app_scopes
# verify required scopes are granted, especially:
# - im:message
# - im:message:send_as_bot
# - contact:contact.base:readonly
# - contact:user.base:readonly

Step 3: Verify bot can reach current conversation

• In DM: ensure the bot is actually in the DM context (not only in workspace app list)
• In group: ensure bot is invited and allowed to post messages
• Use a simple plain-text test first, then test media/card

Step 4: End-to-end message test

message action=send channel=feishu message="ping from openclaw"

If this succeeds but complex messages fail, the issue is usually capability mismatch (card/media), not basic channel connectivity.

Step 5: If still failing, isolate by layers

1. Layer A (Gateway): status/restart/log errors
2. Layer B (Feishu app): scopes + app publish status
3. Layer C (Conversation target): DM/group reachability and permissions
4. Layer D (Payload): plain text works, card/media fails

Practical FAQ

Q1: Bot is online, why no reply?

Usually missing scope or wrong conversation target. Validate scope first, then test DM with plain text.

Q2: Which scope is often missed?

contact:contact.base:readonly is a frequent one in real deployments.

Q3: Why text works but image/card fails?

Feature capability mismatch or media permission limits. Test payload type separately.

Q4: Should I keep retrying when permission error appears?

No. Fix permission first. Retries won't bypass missing scopes.

Done criteria