Lark Integration

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
https://open.larksuite.com → Your App → Event Subscriptions
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 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:

1. Detected from post content or image message type

2. Downloaded via Lark API using message_id and image_key

3. Converted to base64

4. 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](https://open.larksuite.com/) (International)
• -[Feishu Developer Console](https://open.feishu.cn/) (China)
• -See references/api-formats.md for message format details
• -See references/setup-guide.md for step-by-step setup