ChatGPT Pro 俱乐部
OpenClaw 飞书（Feishu/Lark）集成完全指南
OpenClaw 是一个强大的 AI Agent 框架，支持通过插件连接多种即时通讯平台。本文详细介绍如何将 OpenClaw 与飞书（国际版 Lark）进行集成，实现在飞书中与 AI 助手无缝对话。
目录
1. [前置准备](#前置准备)
2. [飞书应用创建与配置](#飞书应用创建与配置)
3. [安装 OpenClaw 飞书插件](#安装-openclaw-飞书插件)
4. [配置 OpenClaw](#配置-openclaw)
5. [高级功能配置](#高级功能配置)
6. [常见问题排查](#常见问题排查)
前置准备
系统要求
- **Node.js**: 22+ 版本（推荐使用 LTS）
- **OpenClaw**: 已安装并配置完成（2026.2+ 版本）
- **飞书账号**: 企业管理员权限（用于创建自建应用）
检查 OpenClaw 安装
```bash
openclaw --version
openclaw config list
```
确认 OpenClaw 正常运行后，继续下一步。
飞书应用创建与配置
第一步：创建自建应用
1. 访问 [飞书开放平台](https://open.feishu.cn)
2. 点击「创建企业自建应用」
3. 填写应用名称和描述
4. 上传应用图标（可选）
第二步：获取凭证
在应用的「凭证与基础信息」页面，记录以下信息：
- **App ID**: 以 `cli_` 开头，例如 `cli_a1b2c3d4e5f6g7h8`
- **App Secret**: 应用密钥，请妥善保管
第三步：配置 API 权限
在「权限管理」页面，申请并开通以下权限：
#### 消息功能（必需）
| 权限代码 | 权限名称 | 说明 |
|---------|---------|------|
| im:message | 获取与发送消息 | 核心消息功能 |
| im:message.p2p_msg:readonly | 读取私聊消息 | 接收用户私聊 |
| im:message.group_at_msg:readonly | 接收群组@消息 | 群聊中被@时响应 |
| im:message:send_as_bot | 以应用身份发消息 | 允许机器人回复 |
| im:resource | 上传下载媒体 | 处理图片、文件 |
#### 工具权限（可选，仅需只读）
如需使用云文档工具功能，申请以下只读权限：
| 权限代码 | 权限名称 |
|---------|---------|
| docx:document:readonly | 读取云文档 |
| drive:drive:readonly | 列举文件��和文件 |
| wiki:wiki:readonly | 访问知识库 |
| bitable:app:readonly | 读取多维表格 |
#### 工具权限（可选，需读写）
如需创建和编辑云文档，申请以下权限：
| 权限代码 | 权限名称 |
|---------|---------|
| docx:document + docx:document.block:convert | 创建/编辑云文档 |
| drive:drive | 创建文件夹、上传图片 |
| wiki:wiki | 创建/移动知识库节点 |
| bitable:app | 创建/更新多维表格 |
**提示**：初次配置建议先申请基础消息权限，待测试通过后再按需添加工具权限。
第四步：配置事件订阅 ⚠️
这是最容易遗漏的关键步骤！在「事件与回调」页面：
1. 连接模式：选择「长连接」（推荐）
2. 添加事件订阅：
- im.message.receive_v1（必需 - 接收消息）
- im.message.message_read_v1（可选 - 已读状态）
- im.chat.member.bot.added_v1（可选 - 机器人加入群聊）
- im.chat.member.bot.deleted_v1（可选 - 机器人离开群聊）
3. 保存并确认：确保事件权限已审批通过
**常见错误**：如果机器人无法接收消息，90% 是因为未正确配置事件订阅。
第五步：发布应用
1. 在「版本管理与发布」页面，创建版本
2. 填写��本说明
3. 提交审核或发布到测试环境
4. 确保应用状态为「已启用」
安装 OpenClaw 飞书插件
方法一：通过插件管理器安装（推荐）
```bash
openclaw plugins install @m1heng-clawd/feishu
```
方法二：手动下载安装（Windows 系统或网络受限）
如果遇到 spawn npm ENOENT 错误，使用手动安装：
```bash
下载插件包
curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
安装
openclaw plugins install ./feishu-0.1.3.tgz
```
验证安装
```bash
openclaw plugins list
```
输出应包含 @m1heng-clawd/feishu。
配置 OpenClaw
基础配置（命令行方式）
```bash
启用飞书通道
openclaw config set channels.feishu.enabled true
配置 App ID
openclaw config set channels.feishu.appId "cli_你的AppID"
配置 App Secret
openclaw config set channels.feishu.appSecret "你的AppSecret"
设置域名（国内版飞书）
openclaw config set channels.feishu.domain "feishu"
验证配置
openclaw config get channels.feishu
```
完整配置（YAML 方式）
编辑 ~/.openclaw/openclaw.yaml（或 ~/.clawdbot/clawdbot.json）：
```yaml
channels:
feishu:
enabled: true
appId: "cli_xxxxxxxxxxxxx"
appSecret: "your_app_secret_here"
# 域名配置
domain: "feishu" # 国内版飞书
# domain: "lark" # 国际版 Lark
# domain: "https://custom.feishu.cn" # 自定义域名
# 连接模式
connectionMode: "websocket" # 或 "webhook"
webhookPath: "/feishu/events" # Webhook 模式时的路径
# 访问控制
dmPolicy: "pairing" # 私聊策略: "open" | "pairing" | "allowlist"
groupPolicy: "allowlist" # 群聊策略: "open" | "allowlist" | "disabled"
requireMention: true # 群聊中是否需要@机器人
# 媒体设置
mediaMaxMb: 30 # 最大媒体文件大小（MB）
# 渲染模式
renderMode: "auto" # "auto" | "raw" | "card"
```
配置说明
#### 访问策略
- **dmPolicy**（私聊策略）
- open: 所有用户都可以私聊机器人
- pairing: 需要先配对（适合企业内部使用）
- allowlist: 仅允许名单内用户
- **groupPolicy**（群聊策略）
- open: 加入任何群聊
- allowlist: 仅加入指定群聊
- disabled: 禁用群聊功能
#### 渲染模式
- `auto`: 自动选择（代码/表格使用卡片，��他使用纯文本）
- `raw`: 始终使用纯文本（Markdown 表格转 ASCII）
- `card`: 始终使用交互式卡片（支持语法高亮）
重启 OpenClaw
```bash
openclaw gateway restart
或
openclaw daemon restart
```
验证连接
```bash
openclaw channels status
```
输出应显示 feishu 通道状态为 connected。
高级功能配置
动态 Agent 创建（多用户隔离）
为每个用户创建独立的工作空间和 Agent：
```yaml
channels:
feishu:
dmPolicy: "open"
dynamicAgentCreation:
enabled: true
workspaceTemplate: "~/workspaces/feishu-{agentId}"
agentDirTemplate: "~/.openclaw/agents/{agentId}/agent"
maxAgents: 100
session:
dmScope: "per-peer" # 每个用户独立会话
```
适用场景：
- 多租户 SaaS 服务
- 企业内部工具（不同部门隔离数据）
- 教育场景（每个学生独立环境）
云文档工具配置
#### 云空间（Drive）权限设置 ⚠️
飞书机器人没有「我的空间」根目录，必须手动共享文件夹：
1. 在飞书云空间创建文件夹
2. 右键文件夹 → 「共享与权限」
3. 搜索机器人名称
4. 授予「可编辑」或「可查看」权限
#### 知识库（Wiki���权限设置 ⚠️
API 权限不足以访问知识库，需要手动添加机器人：
1. 打开知识库 → 「设置」→ 「成员管理」
2. 点击「添加成员」→ 搜索机器人
3. 选择权限级别（编辑者/查看者）
#### 多维表格（Bitable）权限
同样需要通过「分享」按钮将表格共享给机器人。
自定义消息处理
编辑 ~/.openclaw/skills/custom-feishu.ts：
```typescript
export default {
triggers: ['飞书测试'],
async handle(message: Message) {
if (message.platform === 'feishu') {
// 自定义飞书消息处理逻辑
return {
content: '这是来自飞书的自定义回复',
cardMode: true,
};
}
},
};
```
常见问题排查
1. 机器人无法接收消息
症状：用户发送消息后，机器人无响应。
排查步骤：
1. 检查事件订阅配置（最常见原因）
```bash
# 查看 OpenClaw 日志
tail -f ~/.openclaw/gateway.log
```
2. 确认连接模式为「长连接」
3. 验证 im.message.receive_v1 事件已订阅
4. 检查应用是否已发布并启用
2. 403 Forbidden 错误
症状：机器人尝试发送消息时报 403 错误。
解决方案：
- 确认 `im:message:send_as_bot` 权限已申请并通过
- 检查 App Secret 是否正确配置
- 验证应用在飞书管理后台处于「已启用」状态
3. 无法找到机器人
症状：在飞书中搜索机器人名称无结果。
解决方案：
1. 确认应用已发布（至少发布到测试环境）
2. 检查「可用范围」设置，确保当前用户在范围内
3. 尝试通过应用管理后台的「添加到群聊」功能手动添加
4. 清除对话历史
发送命令：
```
/new
```
或重启 Agent：
```bash
openclaw agent restart
```
5. 调试模式
启用详细日志：
```bash
DEBUG=openclaw:feishu openclaw gateway run
```
查看完整日志输出以定位问题。
参考资源
官方文档
- [OpenClaw 官方文档](https://docs.openclaw.ai)
- [飞书开放平台](https://open.feishu.cn/document/)
- [Lark Open Platform](https://open.larksuite.com/)
GitHub 仓库
- [OpenClaw 主仓库](https://github.com/openclaw/openclaw)
- [@m1heng-clawd/feishu 插件](https://github.com/m1heng/clawdbot-feishu)
- [lekuduo/moltbot-lark-plugin](https://github.com/lekuduo/moltbot-lark-plugin)（旧版 Clawdbot 插件，供参考）
社区支持
- Discord: [OpenClaw 社区](https://discord.gg/openclaw)
- GitHub Issues: [提交问���](https://github.com/openclaw/openclaw/issues)
总结
通过本文的详细配置，你应该能够成功将 OpenClaw 与飞书集成。关键步骤回顾：
1. ✅ 创建飞书自建应用，获取 App ID 和 Secret
2. ✅ 配置必要的 API 权限
3. ✅ 配置事件订阅（最重要！）
4. ✅ 安装 OpenClaw 飞书插件
5. ✅ 配置 OpenClaw 并重启服务
6. ✅ 验证连接状态
如果遇到问题，优先检查：
- 事件订阅配置是否正确
- API 权限是否已审批
- App ID 和 Secret 是否填写正确
- 应用是否已发布并启用
祝你使用愉快！🎉
