OpenSkillIndex← back to search
claude-codeopenclawautomation

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

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/boyangwang/lark-integration" ~/.claude/skills/openclaw-skills-lark-integration && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/boyangwang/lark-integration" ~/.openclaw/skills/openclaw-skills-lark-integration && rm -rf "$T"
manifest: skills/boyangwang/lark-integration/SKILL.md
tags
#messaging#webhook#integration#feishu#lark#automation
source content

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

TypeDirectionFormat
text
↔ BothPlain text
post
→ ReceiveRich text with images, links
image
→ ReceiveSingle image
Reply← SendText (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

VariableRequiredDescription
FEISHU_APP_ID
YesApp ID from Lark Developer Console
FEISHU_APP_SECRET_PATH
NoPath to secret file (default: 
~/.openclaw/secrets/feishu_app_secret
)
WEBHOOK_PORT
NoWebhook listen port (default: 3000)
FEISHU_THINKING_THRESHOLD_MS
NoDelay before "Thinking..." placeholder (default: 2500)
FEISHU_ENCRYPT_KEY
NoEncryption key if enabled in Lark
OPENCLAW_AGENT_ID
NoAgent 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