Lark Integration

Connect Lark (Feishu) to OpenClaw for bidirectional messaging with full rich content support.

Quick Start

CODEBLOCK0

Architecture

CODEBLOCK1

Supported Message Types

Type	Direction	Format
INLINECODE0	↔ Both	Plain text
INLINECODE1

Platform Detection

The bridge auto-detects platform from URLs:

- *.larksuite.com → https://open.larksuite.com (International)
INLINECODE5 → https://open.feishu.cn (China)

Configuration

Environment Variables

Variable	Required	Description
INLINECODE7	Yes	App ID from Lark Developer Console
INLINECODE8

Lark App Permissions

Enable these scopes in Lark Developer Console → Permissions & Scopes:

Messaging:

- im:message - Send and receive messages
INLINECODE15 - Send messages as bot
INLINECODE16 - Download message resources (images)

Documents (optional):

- docx:document:readonly - Read documents
INLINECODE18 - Read wiki spaces
INLINECODE19 - Read spreadsheets
INLINECODE20 - Read bitables
INLINECODE21 - Access drive files

Scripts

bridge-webhook.mjs

Main webhook bridge. Receives Lark events, forwards to OpenClaw, sends replies.

CODEBLOCK2

setup-service.mjs

Install as systemd service for auto-start:

CODEBLOCK3

Image Handling

Images in messages are:

1. Detected from post content or image message type
Downloaded via Lark API using message_id and INLINECODE25
Converted to base64
Sent to OpenClaw Gateway as attachments parameter

CODEBLOCK4

Group Chat Behavior

In group chats, the bridge responds when:

- Bot is @mentioned
Message ends with ? or INLINECODE28
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:

CODEBLOCK5

Supported URL types:

- /docx/ - New documents
INLINECODE31 - Wiki pages (auto-resolves to underlying doc)
INLINECODE32 - Spreadsheets
INLINECODE33 - 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: INLINECODE35
Verify webhook in Lark console shows "Verified"
Check bridge logs: INLINECODE36

"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

CODEBLOCK6

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

Lark 集成

将 Lark（飞书）连接到 OpenClaw，实现支持完整富内容的双向消息传递。

快速开始

bash

1. 设置凭证

echo FEISHUAPPID=cli_xxx >> ~/.openclaw/workspace/.env
mkdir -p ~/.openclaw/secrets
echo yourappsecret > ~/.openclaw/secrets/feishuappsecret

2. 启动桥接服务

cd skills/lark-integration/scripts node bridge-webhook.mjs

3. 在开发者控制台配置 Lark Webhook URL

https://open.larksuite.com → 你的应用 → 事件订阅

URL: http://YOURSERVERIP:3000/webhook

架构

Lark 应用 ──webhook──► 桥接服务 (端口 3000) ──WebSocket──► OpenClaw 网关
│ │
◄────────── 回复 ──────────────────┘

支持的消息类型

类型	方向	格式
text	↔ 双向	纯文本
post

→ 接收 | 富文本（含图片、链接） | | image | → 接收 | 单张图片 | | 回复 | ← 发送 | 文本（通过 feishu-card 技能发送卡片） |

平台检测

桥接服务会根据 URL 自动检测平台：

- .larksuite.com → https://open.larksuite.com（国际版）
.feishu.cn → https://open.feishu.cn（中国版）

配置

环境变量

变量	必填	说明
FEISHUAPPID	是	Lark 开发者控制台中的应用 ID
FEISHUAPPSECRETPATH

Lark 应用权限

在 Lark 开发者控制台 → 权限与作用域中启用以下范围：

消息：

- im:message - 发送和接收消息
im:message:sendasbot - 以机器人身份发送消息
im:resource - 下载消息资源（图片）

文档（可选）：

- docx:document:readonly - 读取文档
wiki:wiki:readonly - 读取知识库空间
sheets:spreadsheet:readonly - 读取电子表格
bitable:bitable:readonly - 读取多维表格
drive:drive:readonly - 访问云盘文件

脚本

bridge-webhook.mjs

主 Webhook 桥接服务。接收 Lark 事件，转发到 OpenClaw，发送回复。

bash
FEISHUAPPID=cli_xxx node scripts/bridge-webhook.mjs

setup-service.mjs

安装为 systemd 服务以实现自动启动：

bash
node scripts/setup-service.mjs

创建 /etc/systemd/system/lark-bridge.service

图片处理

消息中的图片处理流程：

1. 从 post 内容或 image 消息类型中检测
通过 Lark API 使用 messageid 和 imagekey 下载
转换为 base64
作为 attachments 参数发送到 OpenClaw 网关

javascript
attachments: [{ mimeType: image/png, content: }]

群聊行为

在群聊中，桥接服务在以下情况会回复：

- 机器人被 @提及
消息以 ? 或？结尾
消息包含触发词：help、please、why、how、what、帮、请、分析等
消息以机器人名称开头

否则，消息将被忽略以避免干扰。

读取文档

使用 feishu-doc 技能读取 Lark 文档：

bash
node skills/feishu-doc/index.js fetch https://xxx.larksuite.com/docx/TOKEN

支持的 URL 类型：

- /docx/ - 新文档
/wiki/ - 知识库页面（自动解析为底层文档）
/sheets/ - 电子表格
/base/ - 多维表格

权限说明： 文档必须与机器人共享，或者机器人必须拥有租户级读取权限。

故障排除

读取文档时出现 forBidden 错误

- 文档未与机器人共享 → 将机器人添加为协作者
缺少权限范围 → 在控制台中启用 docx:document:readonly

未收到消息

- 检查 Webhook URL 是否可访问：curl http://YOUR_IP:3000/health
验证 Lark 控制台中的 Webhook 显示已验证
检查桥接服务日志：journalctl -u lark-bridge -f

must be string 错误

- 桥接服务版本过旧 → 更新以使用 attachments 处理图片

未收到图片

- 缺少 im:resource 权限范围 → 在 Lark 控制台中启用
Token 过期 → 桥接服务会自动刷新，如果卡住请重启

服务管理

bash

检查状态

systemctl status lark-bridge

查看日志

journalctl -u lark-bridge -f

重启

systemctl restart lark-bridge

参考

- Lark 开发者控制台（国际版）
飞书开发者控制台（中国版）
查看 references/api-formats.md 了解消息格式详情
查看 references/setup-guide.md 了解分步设置指南

lark-integration飞书集成