Feishu Group Chat Guide

Quick Start: Configure renderMode

⚠️ IMPORTANT: Set renderMode explicitly for stable message formatting

CODEBLOCK0

Why? The default "auto" mode causes unpredictable format switching (raw vs card), creating poor user experience.

Configuration:
CODEBLOCK1

Verify:

openclaw config get channels.feishu.renderMode

Prerequisites

1. 1. In a Feishu group - OpenClaw connected to Feishu
2. Configure renderMode - Set to "card" for consistent formatting
3. Know member IDs:

0. Message Format Stability

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

Recommended: renderMode: "card" for all production use.

1. Message Sending

⚠️ 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

Raw Mode (Plain Text)

When to use: Plain text messages, @ mentions

How to send:
CODEBLOCK3

@ Mention format:
CODEBLOCK4

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 `` CODEBLOCK5 <at id=ou_xxx></at> This is Card mode @ mention **Markdown content** renders correctly CODEBLOCK6 code ` | ✅ Supported | | Tables | | table | | ✅ Supported | **Not Supported in Card Mode**: | Style | Syntax | Status | |-------|--------|--------| | Blockquote | > quote | ❌ Not supported | | Inline code | code | ❌ Unstable | | Horizontal rule | --- | ❌ Not supported | | Complex nesting | Multiple 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) --- ## 2. Group Member Management ### ⚠️ 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): 1. Ask the human to @ mention the bot and send any message 2. When the message arrives, the system shows: [Feishu ocxxx:ouxxx timestamp] nickname: message content 3. The ouxxx is the sender's open_id **Bot App ID** (requires user to provide): 1. Go to Feishu Developer Console: https://open.feishu.cn/app 2. Click on the bot you want to view 3. In "Application Credentials" (应用凭证), copy the App ID (cli_xxx format) 4. @ mention the bot and send the App ID ### Maintain Member List Store member info in memory file: CODEBLOCK7 --- ## 3. @ Mention Tips ### @ Format Difference (Critical!) | Mode | @ Format | Example | |------|----------|---------| | Raw (message tool) | id="ID">nickname | id="ouxxx">kk | | Card (direct reply) | | xxx> | ### @ Different Target Types | @ Target | ID Type | Raw Format | Card Format | |----------|---------|------------|-------------| | Human | open_id (ou_xxx) | id="ouxxx">nickname | xxx> | | Bot | App ID (cli_xxx) | id="clixxx">botname | xxx> | | Everyone | "all" | id="all">everyone | | ### @ 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**: CODEBLOCK8 CODEBLOCK9 ### @ Everyone **Note**: Requires group permission (Group Settings > Group Management > Who can @everyone) CODEBLOCK10 CODEBLOCK11 ### Common @ Mistakes **Raw mode errors**: - @nickname - Plain text, no notification - @{nickname} - Plain text - - id attribute doesn't work in Raw mode **Card mode errors**: - id="ou_xxx">nickname - user_id attribute doesn't work in Card mode --- ## 4. Quick Reference ### Message Decision Tree CODEBLOCK12 ### @ Mention Decision Tree CODEBLOCK13 ### ID Format Reference | Type | Format | Example | |------|--------|---------| | Human open_id | ou_xxx | ou_example123abc | | Bot App ID | cli_xxx | cli_example456def | | Group chat_id | oc_xxx | oc_example789ghi | --- ## 5. Important Notes 1. **Card and Raw mode use different @ formats** - Wrong format = @ fails 2. **Bots MUST be @ mentioned to receive messages** - Humans don't need @ 3. **Bot-to-bot communication is NOT possible** - Bots can only receive messages from humans, not other bots 4. **message tool only sends Raw mode** - No Markdown rendering 5. **@everyone requires group permission** 6. **Avoid unsupported styles in Card mode** (blockquote, inline code, horizontal rule) --- ## 6. Configuration Reference ### renderMode Settings **Location:** OpenClaw config file or environment **Quick Setup:** CODEBLOCK14 **Environment-specific configurations:** **Development:** CODEBLOCK15 **Production:** CODEBLOCK16 ### Troubleshooting **Messages appear as raw markdown:** 1. Check: openclaw config get channels.feishu.renderMode 2. Set: openclaw config set channels.feishu.renderMode "card" 3. 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`