OpenClaw 接入飞书完整指南

飞书是 OpenClaw 最强大的接入渠道之一。配好之后，AI Agent 能直接在飞书群里回复消息、操作文档、管理知识库，还能主动推送重要信息。

这篇教程基于丰收工作室的实际部署经验，包含了官方文档没有的实战细节。

⚠️ 前置条件：

飞书企业账号（个人版无法创建自定义应用）
或使用飞书开放平台的测试企业
OpenClaw 已安装并运行

第一步：创建飞书自定义应用

1. 进入飞书开放平台

访问飞书开放平台，登录后进入「开发者后台」→「创建企业自建应用」。

2. 获取 App ID 和 App Secret

应用创建后，在「凭证与基础信息」页面找到：

1
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：

67
channels:
  feishu:
    appId: "cli_你的AppID"
    appSecret: "你的AppSecret"
    verificationToken: "飞书后台的验证Token"
    encryptKey: ""  # 可选，启用加密时填写
    
    # 多 App 场景（可选）
    accounts:
      main: "cli_主AppID"
      test: "cli_测试AppID"
可左右滑动查看完整代码

配置完成后重启 OpenClaw：

7
openclaw gateway restart
可左右滑动查看完整代码

第三步：发布应用

6. 创建版本并发布

⚠️ 这是最容易被忽略的步骤！

进入「版本管理与发布」：

点击「创建版本」
填写版本说明
提交审核（测试企业可直接发布）常见坑：应用未发布就开始测试 → 消息发不出去但也不报错，排查时很难发现问题。

7. 添加机器人到群聊

在飞书群里：

群设置 → 机器人 → 添加机器人
搜索你的应用名称
点击添加添加后，这个群的 chat_id 就是机器人的目标 ID。

第四步：测试消息发送

发送第一条消息

在 OpenClaw 中测试：

30
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 不同。

解决：

30
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 的飞书集成不只是发消息，还能操作文档和知识库。

读取飞书文档

30
feishu_doc({
  action: "read",
  doc_token: "BZfodeolcox9N3xQouqcOpwHnGh"
})
可左右滑动查看完整代码

创建文档并写入内容

30
feishu_doc({
  action: "create",
  title: "AI 生成的文档",
  folder_token: "QGVsfziW0lz5SIdC0alcSO4Wnne"
})

feishu_doc({
  action: "write",
  doc_token: "新文档的token",
  content: "# 标题\n\n这是内容"
})
可左右滑动查看完整代码

操作 Bitable 多维表格

30
// 获取表格元数据
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 中配置：

67
channels:
  feishu:
    accounts:
      dev: "cli_开发AppID"
      prod: "cli_生产AppID"
可左右滑动查看完整代码

发消息时指定 accountId：

30
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. 权限管理

创建文档后，默认只有创建者可见。如果需要分享：

30
// 使用 feishu-perm skill
feishu_perm({
  action: "grant",
  doc_token: "xxx",
  user_id: "ou_xxxxxxx",
  permission: "edit"
})
可左右滑动查看完整代码

总结

飞书接入的难点不在代码，在于：

权限配置容易漏 - 一次性配全，避免反复发布
open_id 是 App 维度的 - 多 App 场景最容易踩坑
应用必须发布 - 很多人跳过这步导致消息发不出去
Webhook 需要公网地址 - 内网部署需要配置穿透按这篇教程一步步来，你就能拥有一个在飞书自由操作的 AI Agent。

📝 勘误更新

关于事件订阅配置

原文错误：第二步中提到"飞书需要公网可访问的地址"

正确说明：飞书支持两种事件订阅方式：

Webhook 推送（需要公网地址）
长连接模式（本地化部署推荐）

无需公网域名
无需配置加密策略
使用官方 SDK 启动长连接客户端
连接成功后即可接收事件本地开发建议使用长连接模式，生产环境可选择 Webhook。

OpenClaw 接入飞书完整指南

OpenClaw 接入飞书完整指南

第一步：创建飞书自定义应用

1. 进入飞书开放平台

2. 获取 App ID 和 App Secret

3. 配置权限

第二步：配置事件订阅

4. 设置 Webhook 接收地址

5. OpenClaw 配置文件

第三步：发布应用

6. 创建版本并发布

7. 添加机器人到群聊

第四步：测试消息发送

发送第一条消息

常见报错 & 解决方案

🔴 错误码 99992361：open_id 跨 App

🔴 消息发出去但收不到回复

🔴 发群消息显示「机器人不在群里」

🟡 消息延迟高

进阶：文档与知识库操作

读取飞书文档

创建文档并写入内容

操作 Bitable 多维表格

实战技巧

1. 多 App 场景管理

2. 群组消息过滤

3. 文档同步策略

4. 权限管理

总结

相关资源

📝 勘误更新

关于事件订阅配置