Lark Integration

---

name: lark-integration

description: Connect Lark (Feishu) messaging to OpenClaw via webhook bridge. Supports text, rich text (post), and image messages bidirectionally. Use when setting up Lark/Feishu as a messaging channel, receiving messages with images, sending replies back to Lark, reading Lark documents/wikis/bitables, or troubleshooting Lark integration issues. Covers both Lark International (larksuite.com) and China Feishu (feishu.cn).

---

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

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

**Documents (optional):**

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:

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:

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

Troubleshooting

"forBidden" error when reading docs

No messages received

"must be string" error

Images not received

Service Management

# Check status
systemctl status lark-bridge

# View logs
journalctl -u lark-bridge -f

# Restart
systemctl restart lark-bridge

References