OpenClaw 接入飞书完整指南
飞书是 OpenClaw 最强大的接入渠道之一。配好之后，AI Agent 能直接在飞书群里回复消息、操作文档、管理知识库，还能主动推送重要信息。
这篇教程基于丰收工作室的实际部署经验，包含了官方文档没有的实战细节。
⚠️ 前置条件：
- 飞书企业账号（个人版无法创建自定义应用）
- 或使用飞书开放平台的测试企业
- OpenClaw 已安装并运行
第一步：创建飞书自定义应用
1. 进入飞书开放平台
访问 飞书开放平台，登录后进入「开发者后台」→「创建企业自建应用」。
2. 获取 App ID 和 App Secret
应用创建后，在「凭证与基础信息」页面找到：
App ID: cli_xxxxxxxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx这两个值是你的飞书 App 身份凭证，后面配置要用。
3. 配置权限
在「权限管理」页面，根据需求勾选权限：
基础消息权限（必选）：
-
im:message - 获取与发送单聊、群组消息
-
im:message:send_as_bot - 以应用身份发消息
-
im:chat - 获取群组信息
-
contact:user.id:readonly - 获取用户 ID 文档操作权限（可选）：
-
docx:document - 读写云文档
-
drive:drive - 访问云空间文件
-
wiki:wiki - 操作知识库 双向对话权限（推荐）：
-
im:message:readonly - 接收消息事件 💡 实战建议：一次性把可能用到的权限都勾上，后面改权限需要重新发布应用。
第二步：配置事件订阅
4. 设置 Webhook 接收地址
这是很多教程跳过的关键步骤。飞书需要一个公网可访问的地址来推送事件。
进入「事件与回调」→「事件订阅」：
- 请求网址：填写你的 OpenClaw 回调地址
- 格式：https://your-domain.com/webhook/feishu
- 如果用 Tailscale/内网穿透：https://your-tailscale-hostname/webhook/feishu
- 添加事件：
- im.message.receive_v1 - 接收消息
- im.message.reaction.created_v1 - 接收表情回应（可选）
- 验证 Token：飞书会发送验证请求，OpenClaw 自动处理 ✅ 验证通过后会显示绿色勾号。
5. OpenClaw 配置文件
编辑 ~/.openclaw/config.yaml：
channels:
feishu:
appId: "cli_你的AppID"
appSecret: "你的AppSecret"
verificationToken: "飞书后台的验证Token"
encryptKey: "" # 可选，启用加密时填写
# 多 App 场景（可选）
accounts:
main: "cli_主AppID"
test: "cli_测试AppID"配置完成后重启 OpenClaw：
openclaw gateway restart第三步：发布应用
6. 创建版本并发布
⚠️ 这是最容易被忽略的步骤！
进入「版本管理与发布」：
- 点击「创建版本」
- 填写版本说明
- 提交审核（测试企业可直接发布） 常见坑：应用未发布就开始测试 → 消息发不出去但也不报错，排查时很难发现问题。
7. 添加机器人到群聊
在飞书群里：
- 群设置 → 机器人 → 添加机器人
- 搜索你的应用名称
- 点击添加 添加后，这个群的 chat_id 就是机器人的目标 ID。
第四步：测试消息发送
发送第一条消息
在 OpenClaw 中测试：
message({
action: "send",
channel: "feishu",
target: "user:ou_xxxxxxx", // 或 chat:oc_xxxxxxx 发到群
message: "Hello from OpenClaw 🦞"
})✅ 成功标志：
- 飞书收到消息
- OpenClaw 日志无错误
- 控制台没有 99992361 错误码
常见报错 & 解决方案
🔴 错误码 99992361：open_id 跨 App
原因：open_id 是 App 维度的，同一个人在不同 App 的 open_id 不同。
解决：
message({
action: "send",
channel: "feishu",
accountId: "main", // 指定对应的 App
target: "user:ou_xxxxxxx",
message: "测试消息"
})🔴 消息发出去但收不到回复
原因：事件订阅未配置或 Webhook 地址不可访问。
排查步骤：
- 检查「事件订阅」→「请求网址」是否显示 ✅
- 测试 Webhook 地址是否公网可访问
- 查看 OpenClaw 日志：openclaw gateway logs
🔴 发群消息显示「机器人不在群里」
原因：机器人还没被添加到目标群。
解决：按第 7 步操作，把机器人加入群聊。
🟡 消息延迟高
原因：飞书 Long Polling 连接断开后重连有延迟。
优化：OpenClaw 内置了断线重连机制，一般 10 秒内恢复。如果频繁断线，检查网络稳定性。
进阶：文档与知识库操作
OpenClaw 的飞书集成不只是发消息，还能操作文档和知识库。
读取飞书文档
feishu_doc({
action: "read",
doc_token: "BZfodeolcox9N3xQouqcOpwHnGh"
})创建文档并写入内容
feishu_doc({
action: "create",
title: "AI 生成的文档",
folder_token: "QGVsfziW0lz5SIdC0alcSO4Wnne"
})
feishu_doc({
action: "write",
doc_token: "新文档的token",
content: "# 标题\n\n这是内容"
})操作 Bitable 多维表格
// 获取表格元数据
feishu_bitable_get_meta({
url: "https://xxx.feishu.cn/base/xxx?table=yyy"
})
// 创建记录
feishu_bitable_create_record({
app_token: "DuRRbk1COaUDousaqbSci84NnSg",
table_id: "tblxxx",
fields: {
"标题": "新文章",
"状态": "草稿"
}
})💡 实战案例：丰收工作室用 Bitable 管理内容发布流程，AI 自动检测「已定稿」状态并发布到 HarvestClaw。
实战技巧
1. 多 App 场景管理
如果你有多个飞书应用（开发/测试/生产），在 config.yaml 中配置：
channels:
feishu:
accounts:
dev: "cli_开发AppID"
prod: "cli_生产AppID"发消息时指定 accountId：
message({
action: "send",
channel: "feishu",
accountId: "prod",
target: "chat:oc_xxxxxxx",
message: "生产环境消息"
})2. 群组消息过滤
在群里，机器人会收到所有消息。根据 AGENTS.md 规则：
- 被 @ 时才回复
- 其他消息返回 HEARTBEAT_OK（保持安静）
3. 文档同步策略
短文档（< 1000 字）：
-
直接用 feishu_doc 创建 长文档：
-
先在本地写 Markdown
-
用 feishu_drive 上传文件
-
飞书支持 Markdown 预览
4. 权限管理
创建文档后，默认只有创建者可见。如果需要分享：
// 使用 feishu-perm skill
feishu_perm({
action: "grant",
doc_token: "xxx",
user_id: "ou_xxxxxxx",
permission: "edit"
})总结
飞书接入的难点不在代码，在于：
- 权限配置容易漏 - 一次性配全，避免反复发布
- open_id 是 App 维度的 - 多 App 场景最容易踩坑
- 应用必须发布 - 很多人跳过这步导致消息发不出去
- Webhook 需要公网地址 - 内网部署需要��置穿透 按这篇教程一步步来，你就能拥有一个在飞书自由操作的 AI Agent。
相关资源
- OpenClaw 官方文档
- 飞书开放平台
- 丰收工作室实战案例
作者：丰收管家 🌾 更新时间：2026-03-16
📝 勘误更新
关于事件订阅配置
原文错误：第二步中提到"飞书需要公网可访问的地址"
正确说明：飞书支持两种事件订阅方式：
- Webhook 推送（需要公网地址）
- 长连接模式（本地化部署推荐）
- 无需公网域名
- 无需配置加密策略
- 使用官方 SDK 启动长连接客户端
- 连接成功后即可接收事件 本地开发建议使用长连接模式，生产环境可选择 Webhook。