介绍
# Lark Integration
将飞书连接到 OpenClaw，以实现支持富内容的双向消息传递。
## 快速开始
```bash # 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 ```
## 架构
``` Lark App ──webhook──► Bridge (port 3000) ──WebSocket──► OpenClaw Gateway │ │ ◄────────── Reply ──────────────────┘ ```
## 支持的消息类型
| 类型 | 方向 | 格式 | |------|-----------|--------| | `text` | ↔ 双向 | 纯文本 | | `post` | → 接收 | 富文本（包含图片、链接） | | `image` | → 接收 | 单张图片 | | 回复 | ← 发送 | 文本（通过 feishu-card 技能发送卡片） |
## 平台检测
网桥会根据 URL 自动检测平台： - `*.larksuite.com` → `https://open.larksuite.com` (国际版) - `*.feishu.cn` → `https://open.feishu.cn` (中国版)
## 配置
### 环境变量
| 变量 | 必填 | 说明 | |----------|----------|-------------| | `FEISHU_APP_ID` | 是 | 飞书开发者后台中的应用 ID | | `FEISHU_APP_SECRET_PATH` | 否 | 密钥文件路径（默认：`~/.openclaw/secrets/feishu_app_secret`） | | `WEBHOOK_PORT` | 否 | Webhook 监听端口（默认：3000） | | `FEISHU_THINKING_THRESHOLD_MS` | 否 | 显示“思考中...”占位符前的延迟（默认：2500） | | `FEISHU_ENCRYPT_KEY` | 否 | 如果在飞书中启用了加密，则填写加密密钥 | | `OPENCLAW_AGENT_ID` | 否 | 消息路由到的 Agent（默认：main） |
### 飞书应用权限
在飞书开发者后台 → 权限管理 中启用以下权限：
**消息：** - `im:message` - 发送与接收消息 - `im:message:send_as_bot` - 以机器人身份发送消息 - `im:resource` - 下载消息资源（图片）
**文档（可选）：** - `docx:document:readonly` - 读取文档 - `wiki:wiki:readonly` - 读取知识库 - `sheets:spreadsheet:readonly` - 读取电子表格 - `bitable:bitable:readonly` - 读取多维表格 - `drive:drive:readonly` - 访问云盘文件
## 脚本
### bridge-webhook.mjs
主 Webhook 网桥。接收飞书事件，转发至 OpenClaw，并发送回复。
```bash FEISHU_APP_ID=cli_xxx node scripts/bridge-webhook.mjs ```
### setup-service.mjs
安装为 systemd 服务以实现开机自启：
```bash node scripts/setup-service.mjs # Creates /etc/systemd/system/lark-bridge.service ```
## 图片处理
消息中的图片处理流程如下： 1. 从 `post` 内容或 `image` 消息类型中检测 2. 使用 `message_id` 和 `image_key` 通过飞书 API 下载 3. 转换为 base64 4. 作为 `attachments` 参数发送至 OpenClaw 网关
```javascript attachments: [{ mimeType: "image/png", content: "<base64>" }] ```
## 群聊行为
在群聊中，网桥会在以下情况下响应： - 机器人被 @ 提及 - 消息以 `?` 或 `？` 结尾 - 消息包含触发词：help, please, why, how, what, 帮, 请, 分析 等 - 消息以机器人名称开头
否则，消息将被忽略以避免干扰。
## 读取文档
使用 `feishu-doc` 技能读取飞书文档：
```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` - 确认飞书控制台中的 Webhook 显示为“已验证” - 检查网桥日志：`journalctl -u lark-bridge -f`
### "must be string" 错误 - 网桥版本过旧 → 更新版本以使用 `attachments` 处理图片
### 未收到图片 - 缺少 `im:resource` 权限作用域 → 在飞书控制台中启用 - Token 过期 → 网桥会自动刷新，若卡住请重启
## 服务管理
```bash # Check status systemctl status lark-bridge
# View logs journalctl -u lark-bridge -f
# Restart systemctl restart lark-bridge ```
## 参考资料
- [Lark Developer Console](https://open.larksuite.com/) (国际版) - [Feishu Developer Console](https://open.feishu.cn/) (中国版) - 请参阅 `references/api-formats.md` 了解消息格式详情 - 请参阅 `references/setup-guide.md` 查看分步设置指南