Feishu Chat

Quick Start: Configure renderMode

⚠️ IMPORTANT: Set renderMode explicitly for stable message formatting # Recommended configuration channels: feishu: renderMode: "card" # Always use card format Why? The default "auto" mode causes unpredictable format switching (raw vs card), creating poor user experience. Configuration: openclaw config set channels.feishu.renderMode "card" openclaw gateway restart Verify: openclaw config get channels.feishu.renderMode

Prerequisites

In a Feishu group - OpenClaw connected to Feishu Configure renderMode - Set to "card" for consistent formatting Know member IDs: Human: open_id (ou_xxx format) Bot: App ID (cli_xxx format)

The Problem: Raw vs Card Mixing

Without proper renderMode configuration, messages can inconsistently appear as: Raw text: Plain markdown source, no formatting Card format: Rendered markdown with syntax highlighting, tables, links

The Solution: Explicit renderMode

ModeBehaviorUse CaseautoDetects content, uses card for code/tables❌ Avoid - unpredictablerawAlways plain textSimple text-only responsescardAlways interactive card✅ Recommended - consistent Recommended: renderMode: "card" for all production use.

⚠️ CRITICAL: Only Use ONE Method

DO NOT use both direct reply and message tool for the same content! This will send two messages. Choose ONE: Plain text → message tool only Markdown → direct reply only

Two Methods

MethodToolRender ModeUse Casemessage toolmessageRaw (plain text)Plain text, @ mentionsDirect replySession replyCard (with Markdown)Markdown formatted messages

Raw Mode (Plain Text)

When to use: Plain text messages, @ mentions How to send: message({ action: "send", channel: "feishu", target: "oc_xxx", message: "Plain text content" }) @ Mention format: message({ action: "send", channel: "feishu", target: "oc_xxx", message: "<at user_id=\"ou_xxx\">nickname</at> Hello!" }) Raw Mode Limitations: ❌ No Markdown rendering (bold, italic, code blocks won't render) ❌ Tables won't render ❌ Links won't render ✅ @ mentions work correctly

Card Mode (Markdown)

When to use: Formatted messages with code blocks, tables, bold/italic text How to send: Direct reply in session with Markdown elements. Card Mode Triggers (any of these): Code blocks Tables | table | Bold **bold** Italic *italic* Strikethrough ~~text~~ Links [link](url) Headings # heading Lists - item or 1. item @ Mention format: <at id=ou_xxx></at> This is Card mode @ mention **Markdown content** renders correctly Supported in Card Mode: StyleSyntaxStatusBold**bold**✅ SupportedItalic*italic*✅ SupportedStrikethrough~~text~~✅ SupportedColor<font color='red'>text</font>✅ SupportedLinks[link](https://xxx)✅ SupportedHeadings# heading✅ SupportedLists- item or 1. item✅ SupportedCode blockscode✅ SupportedTables`table Not Supported in Card Mode: StyleSyntaxStatusBlockquote> quote❌ Not supportedInline code`code`❌ UnstableHorizontal rule---❌ Not supportedComplex nestingMultiple levels❌ Unstable Best Practice for Card Mode: Use **bold** for emphasis Use *italic* for light emphasis Use numbered lists 1. or bullet lists - Avoid ---, >, and inline code Keep formatting simple

Avoid Auto Mode

Problem: Auto mode can incorrectly choose between Raw and Card. Best Practice: Plain text → Use message tool (Raw mode) Markdown content → Direct reply (Card mode) Don't: Use message tool for Markdown (won't render) Use complex structures in Card mode (may trigger Raw incorrectly)

⚠️ Important: Bots Only See @ Mentioned Messages

Bots can only see messages that @ mention them! If a group member sends a message without @ mentioning the bot, the bot won't receive it. This means: To identify a human member's open_id, they must @ mention the bot and send a message The bot cannot see past messages where it wasn't mentioned

How to Get Member IDs

Human open_id (must @ mention bot): Ask the human to @ mention the bot and send any message When the message arrives, the system shows: [Feishu oc_xxx:ou_xxx timestamp] nickname: message content The ou_xxx is the sender's open_id Bot App ID (requires user to provide): Go to Feishu Developer Console: https://open.feishu.cn/app Click on the bot you want to view In "Application Credentials" (应用凭证), copy the App ID (cli_xxx format) @ mention the bot and send the App ID

Maintain Member List

• Store member info in memory file:
• ## Group Members (oc_xxx)
• ### Humans
• nickname1: `ou_xxx`
• nickname2: `ou_xxx`
• ### AI Bots
• bot1: `cli_xxx` (must @ to receive messages)

@ Format Difference (Critical!)

Mode@ FormatExampleRaw (message tool)<at user_id="ID">nickname</at><at user_id="ou_xxx">kk</at>Card (direct reply)<at id=ID></at><at id=ou_xxx></at>

@ Different Target Types

@ TargetID TypeRaw FormatCard FormatHumanopen_id (ou_xxx)<at user_id="ou_xxx">nickname</at><at id=ou_xxx></at>BotApp ID (cli_xxx)<at user_id="cli_xxx">botname</at><at id=cli_xxx></at>Everyone"all"<at user_id="all">everyone</at><at id=all></at>

@ Bot vs @ Human

Important difference: Bots: MUST be @ mentioned to receive messages! Without @, bots won't get notified Humans: Can see all group messages, @ not required ⚠️ Feishu Limitation: Bot-to-Bot Messages A bot CAN send messages and @ mention another bot But bots can only receive messages from human accounts Bots cannot receive messages from other bots Therefore, @ mentioning another bot will NOT notify that bot Practical implication: If you need to communicate with another bot, ask a human to send the message instead Bot-to-bot communication is not possible in Feishu groups Example - @ Bot: // Raw mode message({ action: "send", channel: "feishu", target: "oc_xxx", message: "<at user_id=\"cli_xxx\">botname</at> Please reply!" }) // Card mode <at id=cli_xxx></at> Please reply! **Markdown content**

@ Everyone

Note: Requires group permission (Group Settings > Group Management > Who can @everyone) // Raw mode message({ action: "send", channel: "feishu", target: "oc_xxx", message: "<at user_id=\"all\">everyone</at> Important announcement!" }) // Card mode <at id=all></at> Important announcement!

Common @ Mistakes

Raw mode errors: @nickname - Plain text, no notification @{nickname} - Plain text <at id="ou_xxx"></at> - id attribute doesn't work in Raw mode Card mode errors: <at user_id="ou_xxx">nickname</at> - user_id attribute doesn't work in Card mode

Message Decision Tree

Need to send message │ ├─ Plain text only? │ └─ YES → message tool (Raw mode) │ └─ Need Markdown? └─ YES → Direct reply (Card mode)

@ Mention Decision Tree

Need to @ mention │ ├─ Using message tool? │ └─ YES → <at user_id="ID">nickname</at> │ └─ Direct reply (Card mode)? └─ YES → <at id=ID></at>

ID Format Reference

TypeFormatExampleHuman open_idou_xxxou_example123abcBot App IDcli_xxxcli_example456defGroup chat_idoc_xxxoc_example789ghi

5. Important Notes

Card and Raw mode use different @ formats - Wrong format = @ fails Bots MUST be @ mentioned to receive messages - Humans don't need @ Bot-to-bot communication is NOT possible - Bots can only receive messages from humans, not other bots message tool only sends Raw mode - No Markdown rendering @everyone requires group permission Avoid unsupported styles in Card mode (blockquote, inline code, horizontal rule)

renderMode Settings

Location: OpenClaw config file or environment Quick Setup: # Set to card mode (recommended) openclaw config set channels.feishu.renderMode "card" openclaw gateway restart Environment-specific configurations: Development: channels: feishu: renderMode: "raw" # Easier debugging dmPolicy: "open" # Easier testing Production: channels: feishu: renderMode: "card" # Consistent formatting dmPolicy: "pairing" # Security requireMention: true # Avoid spam

Troubleshooting

Messages appear as raw markdown: Check: openclaw config get channels.feishu.renderMode Set: openclaw config set channels.feishu.renderMode "card" Restart: openclaw gateway restart Format switches between raw and card: Cause: Using renderMode: "auto" Fix: Change to "card" or "raw" explicitly Proactive messages not using card: Expected: Proactive messages (via message tool) always use plain text Workaround: Have user send a message first, then reply

Source

Tested on: OpenClaw Feishu integration Test date: 2026-02-27 ~ 2026-02-28 Source files: /home/admin/.openclaw/extensions/feishu/src/bot.ts /home/admin/.openclaw/extensions/feishu/src/reply-dispatcher.ts /home/admin/.openclaw/extensions/feishu/src/mention.ts /home/admin/.openclaw/extensions/feishu/src/send.ts