Lark Integration

Connect Lark (Feishu) to OpenClaw for bidirectional messaging with full rich content support.

Quick Start

# 1. Set credentials
echo "FEISHU_APP_ID=cli_xxx" >> ~/.openclaw/workspace/.env
mkdir -p ~/.openclaw/secrets
echo "your_app_secret" > ~/.openclaw/secrets/feishu_app_secret

# 2. Start bridge
cd skills/lark-integration/scripts
node bridge-webhook.mjs

# 3. Configure Lark webhook URL in developer console
#  → Your App → Event Subscriptions
# URL:

Architecture

Lark App ──webhook──► Bridge (port 3000) ──WebSocket──► OpenClaw Gateway
                           │                                   │
                           ◄────────── Reply ──────────────────┘

Supported Message Types

Type

Direction

Format

text	↔ Both	Plain text
post	→ Receive	Rich text with images, links
image	→ Receive	Single image
Reply	← Send	Text (cards via feishu-card skill)

Platform Detection

The bridge auto-detects platform from URLs:

• *.larksuite.com → (International) - *.feishu.cn → (China)

Configuration

Environment Variables

Variable

Required

Description

FEISHU_APP_ID	Yes	App ID from Lark Developer Console
FEISHU_APP_SECRET_PATH	No	Path to secret file (default: ~/.openclaw/secrets/feishu_app_secret)
WEBHOOK_PORT	No	Webhook listen port (default: 3000)
FEISHU_THINKING_THRESHOLD_MS	No	Delay before "Thinking..." placeholder (default: 2500)
FEISHU_ENCRYPT_KEY	No	Encryption key if enabled in Lark
OPENCLAW_AGENT_ID	No	Agent to route messages to (default: main)

Lark App Permissions

Enable these scopes in Lark Developer Console → Permissions & Scopes:

Messaging:

• im:message - Send and receive messages


• im:message:send_as_bot - Send messages as bot


• im:resource - Download message resources (images)

Documents (optional):

• docx:document:readonly - Read documents


• wiki:wiki:readonly - Read wiki spaces


• sheets:spreadsheet:readonly - Read spreadsheets


• bitable:bitable:readonly - Read bitables


• drive:drive:readonly - Access drive files

Scripts

bridge-webhook.mjs

Main webhook bridge. Receives Lark events, forwards to OpenClaw, sends replies.

FEISHU_APP_ID=cli_xxx node scripts/bridge-webhook.mjs

setup-service.mjs

Install as systemd service for auto-start:

node scripts/setup-service.mjs
# Creates /etc/systemd/system/lark-bridge.service

Image Handling

Images in messages are:

Detected from post content or image message type

Downloaded via Lark API using message_id and image_key

Converted to base64

Sent to OpenClaw Gateway as attachments parameter

attachments: [{ mimeType: "image/png", content: "<base64>" }]

Group Chat Behavior

In group chats, the bridge responds when:

• Bot is @mentioned


• Message ends with ? or ？


• Message contains trigger words: help, please, why, how, what, 帮, 请, 分析, etc.


• Message starts with bot name

Otherwise, messages are ignored to avoid noise.

Reading Documents

Use the feishu-doc skill to read Lark documents:

node skills/feishu-doc/index.js fetch ""

Supported URL types:

• /docx/ - New documents


• /wiki/ - Wiki pages (auto-resolves to underlying doc)


• /sheets/ - Spreadsheets


• /base/ - Bitables (multi-dimensional tables)

Permission Note: Documents must be shared with the bot, or the bot must have tenant-wide read permission.

Troubleshooting

"forBidden" error when reading docs

• Document not shared with bot → Add bot as collaborator
• Missing scope → Enable docx:document:readonly in console

No messages received

• Check webhook URL is accessible: curl - Verify webhook in Lark console shows "Verified" - Check bridge logs: journalctl -u lark-bridge -f ### "must be string" error - Old bridge version → Update to use attachments for images ### Images not received - Missing im:resource scope → Enable in Lark console - Token expired → Bridge auto-refreshes, restart if stuck ## Service Management __CODE_BLOCK_6__ ## References - [Lark Developer Console]() (International) - [Feishu Developer Console]() (China) - See references/api-formats.md for message format details - See references/setup-guide.md` for step-by-step setup