飞书 All-in-One 技能包

📦 开箱即用 | 经过完整验证 | 2026-03-04

本技能包整合了飞书消息收发的所有核心能力，经过实际测试验证，确保能够正常工作。

---

功能一览

功能	状态	说明
文字消息收发	✅	接收用户消息、主动推送文字
图片/文件发送

✅ | 支持本地文件、网络图片 |
| 语音转文字 | ✅ | 使用 faster-whisper |
| 互动卡片 | ✅ | 带按钮的交互卡片 |
| 卡片回调处理 | ✅ | 点击按钮自动处理 |

---

第一部分：飞书开放平台配置

1.1 创建应用

1. 1. 打开 飞书开放平台
2. 点击「创建应用」→「企业自建应用」
3. 填写应用名称（如 OpenClaw Bot）
4. 获取 App ID 和 App Secret

1.2 配置应用凭证

在应用详情页获取：

• - App ID: 如 cli_xxxxxxxx
• App Secret: 如 xxxxxxxx

1.3 配置权限

进入「权限管理」，添加以下权限：

权限名称	权限码	说明
获取应用基本信息	app:app.base:readonly	读取应用基本信息
发送消息

im:message:sendasbot | 以机器人身份发送消息 |
| 接收消息 | im:message:receive | 接收用户消息 |
| 上传图片和文件 | im:file:upload | 上传图片/文件 |
| 下载图片和文件 | im:file:download | 下载图片/文件 |
| 获取用户信息 | contact:user.base:readonly | 读取用户基本信息 |

1.4 配置事件与回调（关键！）

1. 1. 进入「事件与回调」
2. 订阅方式：选择「使用长连接接收事件/回调」
3. 订阅事件：

事件名称	事件码	说明
接收消息	im.message.receive_v1	接收用户发送的消息
卡片动作触发

im.card.action.trigger | 互动卡片按钮点击 |

1. 4. 接收地址：使用长连接模式无需配置公网地址

1.5 发布应用

1. 1. 在「版本管理与发布」中创建版本
2. 提交审核
3. 发布后，用户即可与机器人对话

---

第二部分：OpenClaw 配置

2.1 配置 openclaw.json

编辑 ~/.openclaw/openclaw.json，添加飞书配置：

json
{
channels: {
feishu: {
enabled: true,
appId: 你的App_ID,
appSecret: 你的App_Secret,
domain: feishu
}
}
}

2.2 配置 accounts（互动卡片必需）

json
{
channels: {
feishu: {
enabled: true,
appId: cli_xxxxxxxx,
appSecret: xxxxxxxx,
domain: feishu,
accounts: {
main: {
appId: cli_xxxxxxxx,
appSecret: xxxxxxxx
}
}
}
}
}

2.3 环境变量

在运行回调服务器前需要设置：

bash
export FEISHUAPPID=cli_xxxxxxxx
export FEISHUAPPSECRET=xxxxxxxx

---

第三部分：技能使用

3.1 文字消息

使用 OpenClaw 内置的 message 工具：

javascript
// 发送文字消息
await message({
action: send,
channel: feishu,
message: 你好，这是主动推送的消息,
target: ouxxxxxxxx // 用户 openid
});

3.2 发送图片/文件

javascript
// 发送本地图片
await message({
action: send,
channel: feishu,
message: 这是一张图片,
filePath: /path/to/image.png,
target: ou_xxxxxxxx
});

// 发送网络图片
await message({
action: send,
channel: feishu,
message: 网络图片,
media: https://example.com/image.png,
target: ou_xxxxxxxx
});

3.3 发送互动卡片

运行修改后的脚本：

bash

进入脚本目录

cd /path/to/skills/feishu-all-in-one/scripts

发送确认卡片（发给个人用户）

node send-card.js confirmation 消息内容 \ --chat-id ou_xxxxxxxx \ --receive-id-type open_id

发送投票卡片

node send-card.js poll 你喜欢哪个？ \ --options A,B,C \ --chat-id ou_xxxxxxxx \ --receive-id-type open_id

发送自定义卡片

node send-card.js custom \ --template examples/custom-card.json \ --chat-id ou_xxxxxxxx \ --receive-id-type open_id

关键参数：

• - --chat-id: 目标用户/群聊 ID
• --receive-id-type:

- open_id - 发给个人用户
- chat_id - 发给群聊
- user_id - 飞书用户 ID

3.4 启动卡片回调服务器

bash
cd /path/to/feishu-all-in-one/scripts

安装依赖（只需一次）

npm install

设置环境变量

export FEISHUAPPID=cli_xxxxxxxx export FEISHUAPPSECRET=xxxxxxxx

启动回调服务器

node card-callback-server.js &

回调服务器会：

1. 1. 长连接方式监听卡片点击事件
2. 自动处理按钮回调
3. 可选：向 Gateway 发送回调通知

3.5 语音转文字

安装 faster-whisper：

bash
python3.11 -m pip install faster-whisper

转写音频：

python
from faster_whisper import WhisperModel

model = WhisperModel(base, device=cpu, compute_type=int8)
segments, info = model.transcribe(/path/to/audio.ogg)

print(f语言: {info.language})
for segment in segments:
print(segment.text)

---

第四部分：脚本说明

4.1 send-card.js（已修复）

修复内容：

• - 支持 --receive-id-type open_id 参数
• 可以发给个人用户而不仅是群聊

完整用法：

bash

确认卡片

node send-card.js confirmation 确认删除吗？ \
--chat-id ou_xxxxxxxx \
--receive-id-type open_id

待办卡片

node send-card.js todo \ --chat-id ou_xxxxxxxx \ --receive-id-type open_id

投票卡片

node send-card.js poll 周末活动 \ --options 爬山,吃饭,看电影 \ --chat-id ou_xxxxxxxx \ --receive-id-type open_id

自定义卡片

node send-card.js custom \ --template /path/to/card.json \ --chat-id ou_xxxxxxxx \ --receive-id-type open_id

4.2 feishufilesender.py

发送本地文件到飞书：

bash
python3 scripts/feishufilesender.py \
--file /path/to/file.png \
--receive-id ou_xxxxxxxx \
--receive-id-type open_id

4.3 feishuproactivemessenger.py

主动发送文字消息：

bash
python3 scripts/feishuproactivemessenger.py \
--agent main \
--text 这是主动推送的消息 \
--receive-id ou_xxxxxxxx \
--receive-id-type open_id

---

第五部分：常见问题

Q1: 互动卡片发不出去，报错 invalid receive_id

原因：使用了 chat_id 类型发给个人用户
解决：添加 --receive-id-type open_id 参数

Q2: 点击卡片按钮没有反应

原因：回调服务器未启动
解决：
bash
export FEISHUAPPID=cli_xxx
export FEISHUAPPSECRET=xxx
node card-callback-server.js &

Q3: 主动消息发送失败

原因：用户未与机器人对话过（24小时限制）
解决：让用户先在飞书中给机器人发一条消息

Q4: 文件上传失败

原因：未配置应用凭证
解决