Feishu Group Chat Guide

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

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

---

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

Mode	Behavior	Use Case
auto	Detects content, uses card for code/tables	❌ Avoid - unpredictable
raw	Always plain text	Simple text-only responses
card	Always interactive card	✅ Recommended - consistent

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

Method	Tool	Render Mode	Use Case
message tool	message	Raw (plain text)	Plain text, @ mentions
Direct reply	Session reply	Card (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 - 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:

Style	Syntax	Status
Bold	**bold**	✅ Supported
Italic	*italic*	✅ Supported
Strikethrough	~~text~~	✅ Supported
Color	<font color='red'>text</font>	✅ Supported
Links	link	✅ Supported
Headings	# heading	✅ Supported
Lists	- item or 1. item	✅ Supported
Code blocks	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 oc_xxx:ou_xxx timestamp] nickname: message content
3. The ou_xxx 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:

## Group Members (oc_xxx)
### Humans
- nickname1: `ou_xxx`
- nickname2: `ou_xxx`

### AI Bots
- bot1: `cli_xxx` (must @ to receive messages)

---

3. @ Mention Tips

@ Format Difference (Critical!)

Mode	@ Format	Example
Raw (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

@ Target	ID Type	Raw Format	Card Format
Human	open_id (ou_xxx)	<at user_id="ou_xxx">nickname</at>	<at id=ou_xxx></at>
Bot	App 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

---

4. Quick Reference

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

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:

# 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: 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