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
URL: http://YOUR_SERVER_IP:3000/webhook
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
→ https://open.larksuite.com
(International)*.feishu.cn
→ https://open.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 messagesim:message:send_as_bot
- Send messages as botim:resource
- Download message resources (images)
Documents (optional):
docx:document:readonly
- Read documentswiki:wiki:readonly
- Read wiki spacessheets:spreadsheet:readonly
- Read spreadsheetsbitable:bitable:readonly
- Read bitablesdrive: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 "https://xxx.larksuite.com/docx/TOKEN"
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 http://YOUR_IP:3000/health
- 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
# Check status
systemctl status lark-bridge
View logs
journalctl -u lark-bridge -f
Restart
systemctl restart lark-bridge
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
