Lark Integration

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).

Security Scan

The skill largely looks like a legitimate Lark/Feishu→OpenClaw webhook bridge, but there are multiple inconsistencies and undeclared accesses (local OpenClaw config, secret files, platform/installer mismatches) that warrant caution before installing.

Purpose & Capability

The code and SKILL.md implement a webhook bridge between Lark/Feishu and an OpenClaw gateway — this matches the skill name/description. However, the registry metadata claims no required environment variables or config paths while the runtime explicitly requires FEISHU_APP_ID and a secret file, and reads an OpenClaw config file (to obtain a gateway auth token). The bridge legitimately needs a Feishu app id/secret and the gateway token, but those were not declared in the registry metadata — an incoherence that reduces transparency.

Instruction Scope

Runtime instructions and scripts read local secret files (~/.openclaw/secrets/feishu_app_secret by default) and a local OpenClaw config (~/.openclaw/openclaw.json or legacy ~/.clawdbot/clawdbot.json) to obtain gateway.auth.token. The bridge sends message text and base64-encoded image attachments to a local OpenClaw WebSocket gateway. The SKILL.md also shows both systemd and launchd service installation examples but the provided setup script actually generates a macOS launchd plist — inconsistent instructions. These behaviors are broadly within the announced purpose but access to other local config files and writing service files are significant actions that should be expected and explicitly declared.

Install Mechanism

No formal install spec; this is primarily an instruction-only skill with included Node scripts. package.json lists two reasonable public npm dependencies (@larksuiteoapi/node-sdk and ws). No downloads from arbitrary URLs or obfuscated code. Installing as a service (systemd/launchd) writes files into system/user locations — expected for a bridge but requires administrative/user consent.

Credentials

The skill requires sensitive secrets: FEISHU_APP_ID and the Feishu app secret file, and it reads OpenClaw's local config to get the gateway.auth.token. Those are proportionate to a bridge but they were not declared in the registry metadata (no required envs/config paths listed). The code also looks for legacy ~/.clawdbot/clawdbot.json, meaning it will access other skill/system config locations. Access to another component's token (GATEWAY_TOKEN) is powerful: it lets the bridge act with OpenClaw operator scopes and send messages into agents.

Persistence & Privilege

The skill includes scripts and explicit instructions to install the bridge as a persistent service (systemd example in docs and a macOS launchd generator in setup-service.mjs). The registry flags do not mark the skill 'always: true'; autonomous invocation is allowed (default). Creating systemd/launchd entries and writing logs to home or /etc are expected for a long-running bridge but elevate persistence and should be performed deliberately by the administrator.

Scan Findings in Context

[no_pre_scan_signals] unexpected: Static pre-scan reported no injection signals; this does not imply safety. The code does perform local file reads (secrets/config) and network calls (Lark APIs, local WebSocket). Those behaviors are expected for a webhook bridge but were not declared in the registry metadata.

What to consider before installing

Before installing: (1) Be aware this bridge will read your Feishu/Lark app secret file and your OpenClaw config (to get the gateway auth token). If you don't want the skill to access your OpenClaw gateway token, do not install it. (2) The registry metadata omitted required env/config declarations — verify FEISHU_APP_ID and the secret path are set intentionally and stored securely. (3) The scripts can install a persistent service (systemd or launchd). Only install as a service if you control the host and accept a long-running process that can route messages into your OpenClaw agents. (4) The code appears to use open.larksuite.com for API calls; confirm it supports your Feishu (feishu.cn) tenant before trusting it. (5) If you decide to proceed, review the two included scripts line-by-line and run them in an isolated/test environment first (or run the bridge manually rather than installing the service) so you can confirm which files are read/written and that tokens are not leaked to unexpected endpoints.

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 (International)
• Feishu Developer Console (China)
• See references/api-formats.md for message format details
• See references/setup-guide.md for step-by-step setup