OpenClaw 飞书插件完整配置指南｜流式卡片 + 页脚耗时一篇搞定

📌 导读：本文记录 OpenClaw 官方 openclaw-lark 插件的完整配置流程，从权限设置到回调配置，手把手教你启用流式输出、页脚耗时、卡片交互等高级功能。

01 插件安装

1.1 安装官方插件

1
openclaw plugins install @larksuite/openclaw-lark

1.2 禁用旧版插件 ⚠️

重要：旧版 feishu 插件与官方 openclaw-lark 不能同时启用，否则功能会失效！

1
2
3
4
5
# 禁用旧版 feishu 插件openclaw config set plugins.entries.feishu.enabled false# 确保 openclaw-lark 启用openclaw config set plugins.entries.openclaw-lark.enabled true

1.3 清理旧插件（可选）

1
openclaw plugins allow remove feishu-execution-monitor

02 飞书开放平台配置

2.1 创建企业自建应用

1. 1. 访问 飞书开放平台
2. 2. 创建企业自建应用
3. 3. 记录 App ID 和 App Secret（后续配置要用）

2.2 配置权限 Scope 🔐

在应用的「权限管理」中，必须添加以下权限才能使用流式卡片功能：

📋 应用权限（tenant）共 19 项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
contact:contact.base:readonlydocx:document:readonlyim:chat:readim:chat:updateim:message.group_at_msg:readonlyim:message.p2p_msg:readonlyim:message.pins:readim:message.pins:write_onlyim:message.reactions:readim:message.reactions:write_onlyim:message:readonlyim:message:recallim:message:send_as_botim:message:send_multi_usersim:message:send_sys_msgim:message:updateim:resourceapplication:application:self_managecardkit:card:writecardkit:card:read

📋 用户权限（user）共 60+ 项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
contact:user.employee_id:readonlyoffline_accessbase:app:copybase:field:createbase:field:deletebase:field:readbase:field:updatebase:record:createbase:record:deletebase:record:retrievebase:record:updatebase:table:createbase:table:deletebase:table:readbase:table:updatebase:view:readbase:view:write_onlybase:app:createbase:app:updatebase:app:readsheets:spreadsheet.meta:readsheets:spreadsheet:readsheets:spreadsheet:createsheets:spreadsheet:write_onlydocs:document:exportdocs:document.media:uploadboard:whiteboard:node:createboard:whiteboard:node:readcalendar:calendar:readcalendar:calendar.event:createcalendar:calendar.event:deletecalendar:calendar.event:readcalendar:calendar.event:replycalendar:calendar.event:updatecalendar:calendar.free_busy:readcontact:contact.base:readonlycontact:user.base:readonlycontact:user:searchdocs:document.comment:createdocs:document.comment:readdocs:document.comment:updatedocs:document.media:downloaddocs:document:copydocx:document:createdocx:document:readonlydocx:document:write_onlydrive:drive.metadata:readonlydrive:file:downloaddrive:file:uploadim:chat.members:readim:chat:readim:messageim:message.group_msg:get_as_userim:message.p2p_msg:get_as_userim:message:readonlysearch:docs:readsearch:messagespace:document:deletespace:document:movespace:document:retrievetask:comment:readtask:comment:writetask:task:readtask:task:writetask:task:writeonlytask:tasklist:readtask:tasklist:writewiki:node:copywiki:node:createwiki:node:movewiki:node:readwiki:node:retrievewiki:space:readwiki:space:retrievewiki:space:write_only

2.3 配置事件订阅 🔔

在「事件订阅」中，必须订阅以下 4 个事件：

2.4 配置回调 URL 🌐

1. 1. 进入「事件订阅」页面
2. 2. 点击「添加事件接收网址」
3. 3. 填写格式：https://<your-domain>:<port>/api/feishu/event

💡 注意：回调地址必须能被飞书服务器访问（需要公网 IP 或内网穿透）

2.5 配置加密密钥 🔑

在「事件订阅」页面：

1. 1. 生成 Encrypt Key（加密密钥）
2. 2. 生成 Verification Token（验证令牌）
3. 3. 将两者复制到 OpenClaw 配置中

2.6 配置卡片回调 🃏

在「卡片功能」或「回调配置」页面，配置卡片交互回调：

配置步骤：

1. 1. 进入飞书开放平台应用的「卡片功能」页面
2. 2. 找到「卡片回调配置」或「交互地址」
3. 3. 填写回调地址：https://<your-domain>:<port>/api/feishu/card
4. 4. 保存配置

💡 注意：卡片回调与消息回调是两个独立地址，不要混淆

03 OpenClaw 配置

3.1 完整配置结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{  "channels": {    "feishu": {      "enabled":true,      "streaming":true,      "footer": {        "elapsed":true,        "status":true      },      "threadSession":true,      "appId": "cli_xxxxxxxxxxxxx",      "appSecret": "xxxxxxxxxxxxxxxxxxxx",      "encryptKey": "xxxxxxxxxxxxxx",      "verificationToken": "xxxxxxxxxxxxxx",      "domain": "feishu",      "connectionMode": "websocket",      "accounts": {        "default": {          "appId": "cli_xxxxxxxxxxxxx",          "appSecret": "xxxxxxxxxxxxxxxxxxxx"        }      }    }  },  "plugins": {    "entries": {      "feishu": { "enabled":false },      "openclaw-lark": { "enabled":true }    }  }}

3.2 关键配置项说明

3.3 命令行配置（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 启用频道openclaw config set channels.feishu.enabled true# 配置凭证（顶层）openclaw config set channels.feishu.appId "cli_xxx"openclaw config set channels.feishu.appSecret "xxx"# 启用流式输出openclaw config set channels.feishu.streaming true# 启用页脚耗时openclaw config set channels.feishu.footer.elapsed true# 启用页脚状态openclaw config set channels.feishu.footer.status true# 启用线程会话openclaw config set channels.feishu.threadSession true# 配置账户凭证openclaw config set channels.feishu.accounts.default.appId "cli_xxx"openclaw config set channels.feishu.accounts.default.appSecret "xxx"# 禁用旧版插件openclaw config set plugins.entries.feishu.enabled false

04 启动与验证

4.1 重启网关服务

1
2
# 完全重启openclaw gateway restart

4.2 检查服务状态

1
openclaw status

预期输出：

1
│ Feishu   │ ON      │ OK     │ configured

4.3 功能验证清单 ✅

在飞书中向机器人发送消息，逐项验证：

• •消息响应：机器人正常回复
• •卡片格式：消息以卡片形式展示
• •流式输出：文字逐段显示，非一次性出现
• •页脚耗时：显示「耗时 X.Xs」
• •页脚状态：显示「已完成」/「出错」/「已停止」

05 常见问题排查

❌ 问题 1：流式输出不生效

原因：旧版 feishu 插件仍在运行

解决：

1
2
openclaw config set plugins.entries.feishu.enabled falseopenclaw gateway restart

❌ 问题 2：页脚不显示耗时/状态

原因 1：配置路径错误（如写成 footer.elapsedTime）

解决：确保配置路径正确

1
2
3
4
"footer": {  "elapsed":true,  "status":true}

原因 2：streaming 未启用

解决：

1
openclaw config set channels.feishu.streaming true

❌ 问题 3：凭证配置后仍显示未配置

原因：只配置了 accounts.default，缺少顶层配置

解决：同时配置顶层和账户级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "channels": {    "feishu": {      "appId": "cli_xxx",      "appSecret": "xxx",      "accounts": {        "default": {          "appId": "cli_xxx",          "appSecret": "xxx"        }      }    }  }}

❌ 问题 4：收不到消息回调

检查清单：

1. 1. 飞书开放平台是否启用 im.message.receive_v1 事件
2. 2. 回调 URL 是否可公网访问
3. 3. Encrypt Key 和 Verification Token 是否正确
4. 4. 网关日志是否有回调记录

查看日志：

1
tail -f ~/Library/Logs/openclaw/gateway.log

06 配置备份

备份配置

1
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

从备份恢复

1
2
cp ~/.openclaw/openclaw.json.bak.YYYYMMDD ~/.openclaw/openclaw.jsonopenclaw gateway restart

07 关键配置总结

成功启用官方飞书插件的 7 个关键配置：

⚠️ 缺一不可，任一配置缺失都会导致功能异常

参考资料

• • OpenClaw 官方飞书插件文档
• • 飞书开放平台
• • openclaw-lark npm 包