feishu-openclaw

飞书 × OpenClaw 保姆级配置指南 & 社区支持 让每个人都能用飞书轻松接入 OpenClaw（原 Clawdbot）。

📚 awesome-openclaw-usecases-zh — 装好了 OpenClaw，然后呢？

Skills 装了一堆，教程收藏了一堆，工具越来越多——但最缺的不是能力，而是经过国内适配和验证的场景。

39 个真实用例，含飞书、钉钉、企业微信、小红书等国内生态适配方案，每个都有完整步骤和可复制的提示词。

查看中文最佳用例合集 →

🆕 飞书官方开源 Lark CLI（2026.3.28）

飞书官方开源了 Lark CLI（MIT 协议）——让你的 AI Agent 直接操作飞书：搜文档、读妙记、查日历、发消息、操作多维表格…… 2500+ API，11 个业务领域，19 个 AI Agent Skills。

安装只需要告诉你的 Agent 一句话，你只需要点一个授权链接。

👉 Lark CLI 上手指南

📢 飞书官方插件上线（2026.3.6）

飞书团队正式推出了 OpenClaw 飞书官方插件。目前飞书接入 OpenClaw 共有三种插件方式：

(a) 飞书官方插件 — 飞书团队开发维护，支持以用户身份操作文档、日历、任务等
(b) OpenClaw 内置飞书插件 — OpenClaw 社区维护（@openclaw/feishu），OpenClaw ≥ 2026.2 已内置
(c) 本项目插件 — 本仓库早期开发的社区飞书插件（已停止更新，推荐迁移到 a 或 b）

👉 想了解飞书官方和 OpenClaw 内置插件的区别？ 看两个插件怎么选

👉 本项目插件的老用户？ 看如何迁移到飞书官方或 OpenClaw 内置插件

🚀 OpenCrew — 把你的 OpenClaw 变成一支 AI 团队

多个 Agent 各管各的领域，Slack 频道=岗位，经验自动沉淀。

3 个 Agent 起步 · 10 分钟部署 · 不用写代码

查看 GitHub →

🆕 飞书官方插件

飞书团队推出的 OpenClaw 官方插件，最大的不同是：以你的身份操作飞书（通过 OAuth 授权）。

这意味着 AI 不只是"聊天机器人"，而是能直接帮你写文档、建多维表格、约日程、管理任务——就像一个能操作飞书的数字分身。

👉 查看飞书官方插件安装指南

⚠️ OpenClaw 3.x 用户：官方安装工具 feishu-plugin-onboard 有版本检查 bug（#59），会误报版本过低。安装指南中已提供替代方式，直接 openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin 即可绕过。

📖 飞书团队的完整图文教程：OpenClaw 飞书官方插件上线 | 一文讲清功能、安装更新教程与常见问题

📊 飞书官方 vs OpenClaw 内置：怎么选？

两个插件不能同时使用（安装官方插件时会自动禁用内置插件）。

| 维度 | 飞书官方插件 | OpenClaw 内置插件 | |---|---|---| | 操作身份 | 以你本人身份（OAuth） | 以机器人身份 | | 消息 | 读取、发送、回复、搜索 | 读取、发送、回复 | | 文档 | 创建 + 编辑 + 读取 | 读取为主 | | 多维表格 | 完整操作（表、字段、记录、视图） | 基础读写 | | 日历日程 | ✅ 创建/查询/修改/搜索/忙闲查询 | ❌ | | 任务管理 | ✅ 创建/查询/更新/完成/子任务 | ❌ | | 知识库 | ✅ 完整读写 | ✅ 只读 | | 云盘 | ✅ 上传/下载 | ✅ 基础操作 | | 流式输出 | ✅ | ✅ | | 安装复杂度 | 需要额外安装 CLI 工具 + OAuth 授权 | OpenClaw 内置，openclaw channels add 即可 | | 维护方 | 飞书团队 | OpenClaw 社区 | | 问题反馈 | 飞书反馈群 | 本项目 Issues / Discord |

选择建议

选飞书官方插件，如果你：

想让 AI 帮你操作飞书（写文档、建表、约会议）
需要日历、任务管理等高级功能
想要以自己身份发消息（不是机器人名义）

选 OpenClaw 内置插件，如果你：

主要用飞书做聊天入口，让 AI 回答问题、执行本地任务
不需要 AI 操作飞书文档/日历/任务
偏好更简单的安装流程（内置即用）

⚠️ 两种插件互斥，只能启用一个。 安装飞书官方插件时会自动禁用内置插件，反之亦然。如果两个都装了，会出现 duplicate plugin id 报错导致飞书功能不可用。遇到这种情况：
# 删除用户目录下的重复插件
rm -rf ~/.openclaw/extensions/feishu
openclaw gateway restart
如果想从内置切换到官方插件，见从 OpenClaw 内置插件迁移到飞书官方插件。

🚀 OpenClaw 内置插件教程（从零配置）

适用于：第一次使用 OpenClaw + 飞书的新用户，选择 OpenClaw 内置插件方案。前提：已安装 OpenClaw 并正常运行（openclaw gateway status 能看到状态）。预计耗时：15–20 分钟。

第一步：创建飞书应用（机器人）

打开飞书开放平台，用飞书账号登录
点击 创建企业自建应用
填写应用名称（随意，比如 "我的 AI 助手"）和描述
选一个图标（可以之后改）

第二步：启用机器人能力

进入你刚创建的应用：

左侧菜单找到 应用能力 > 机器人
开启机器人能力
给机器人起个名字

第三步：配置权限

左侧菜单进入 权限管理
点击 批量导入
粘贴以下 JSON（一键导入所有需要的权限）：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

第四步：配置事件订阅

⚠️ 这一步必须在 OpenClaw 网关启动后再做，否则保存会失败。先做第五、六步，回来再做这一步也可以。

左侧菜单进入 事件与回调 > 事件配置
请求方式选择：使用长连接接收事件（这是关键！不需要公网服务器）
添加事件：搜索 im.message.receive_v1（接收消息），勾选添加

第五步：记下凭证

在应用的 凭证与基础信息 页面，复制：

App ID（格式如 cli_xxxxxxxxx）
App Secret

❗ App Secret 很重要，请妥善保管，不要分享。

第六步：发布应用

左侧菜单 版本管理与发布
创建版本 → 填写版本说明 → 提交
等待审批（企业内部应用通常自动通过，几秒到几分钟）

第七步：在 OpenClaw 中配置飞书

OpenClaw ≥ 2026.2 已内置飞书插件，不需要额外安装，直接配置即可。

💡 如果你在首次 openclaw setup 时看到 "Install Feishu plugin?"，选择 "Download from npm" 即可进入配置流程。选了 "Skip" 也没关系，用下面的命令随时添加。

打开 终端（Terminal）：

# 1. 添加飞书渠道（交互式，跟着提示走）
openclaw channels add
# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret

# 2. 重启网关
openclaw gateway restart

# 3. 查看日志，确认连接成功
openclaw logs --follow

第八步：发消息测试

在飞书里搜索你的机器人名字，打开对话
发一条消息，比如"你好"
如果机器人回复了配对码，在终端运行：

openclaw pairing approve feishu <配对码>

授权后再发一条消息，收到正常回复 = 配置完成 🎉

回来补第四步：如果你先跳过了事件订阅，现在网关已启动，回到飞书开放平台把第四步做完，保存后重启网关（openclaw gateway restart）。

第九步（可选）：让机器人开机自启

openclaw gateway install

这样电脑重启后机器人也会自动上线。

🔄 从旧版迁移

适用于：之前使用本项目（独立桥接或 npm 插件）的老用户。两种方式任选其一，效果一样。

迁移前须知

✅ 你之前创建的飞书应用（机器人）可以继续用，不需要重新创建
✅ App ID 和 App Secret 不变
✅ 迁移后聊天记录不受影响（记录在飞书端）
⚠️ 迁移过程中机器人会短暂离线（几分钟）

方式一：通过 OpenClaw 升级（推荐，最省事）

如果你的 OpenClaw 版本 ≥ 2026.2，升级后官方飞书插件已经内置，只需要：

1. 升级 OpenClaw

openclaw update

升级完成后会自动重启网关。

2. 添加飞书渠道

openclaw channels add

选择 Feishu → 粘贴你的 App ID → 粘贴你的 App Secret。

App ID 和 App Secret 在哪？之前可能保存在 ~/.clawdbot/secrets/feishu_app_secret，可以 cat 查看。如果找不到，去飞书开放平台 → 你的应用 → 凭证与基础信息 重新复制。

3. 补全飞书应用权限

官方插件支持图片、文件、流式输出等更多功能，需要在飞书开放平台补几个权限：

打开飞书开放平台 → 进入你的应用
进入 权限管理 → 点击 批量导入
粘贴以下内容一键导入：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

已有的权限会自动跳过，不会重复添加。

导入后 → 创建新版本 → 发布（让新权限生效）

4. 清理旧插件/桥接

# 移除旧的 npm 插件（如果装过）
openclaw plugins remove feishu-openclaw 2>/dev/null

# 停掉旧的桥接服务（如果用过独立桥接）
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null

# 重启网关
openclaw gateway restart

然后跳到下方验证确认一切正常。

方式二：不升级 OpenClaw，只加飞书

适用于不想整体升级 OpenClaw、只想加飞书的情况。

注意：OpenClaw ≥ 2026.2 已内置飞书插件，不需要 openclaw plugins install。直接配置即可。

1. 准备好你的飞书凭证

App ID：格式如 cli_xxxxxxxxx
App Secret

之前可能保存在 ~/.clawdbot/secrets/feishu_app_secret，可以 cat 查看。如果找不到，去飞书开放平台 → 你的应用 → 凭证与基础信息 重新复制。

2. 补全飞书应用权限

（同方式一的第 3 步，权限 JSON 一样，这里不重复粘贴——往上翻到方式一的权限 JSON 复制即可。）

飞书开放平台 → 你的应用 → 权限管理 → 批量导入 → 粘贴上方 JSON
导入后 → 创建新版本 → 发布

3. 配置飞书渠道

# 添加飞书渠道（交互式引导）
openclaw channels add
#    → 选择 Feishu
#    → 粘贴 App ID
#    → 粘贴 App Secret

# 移除旧的 npm 插件（如果装过）
openclaw plugins remove feishu-openclaw 2>/dev/null

# 停掉旧的桥接服务（如果用过独立桥接）
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist 2>/dev/null

# 重启网关
openclaw gateway restart

验证

# 查看日志，确认飞书连接成功
openclaw logs --follow

日志中看到类似 feishu ws connected 或 feishu provider ready 就说明连上了。

在飞书里给机器人发一条消息，正常收到回复 = 迁移完成 🎉

配对授权：如果机器人回复了一个配对码，在终端运行：
openclaw pairing approve feishu <配对码>
授权后就能正常对话了。这是一次性操作。

迁移后清理（可选）

稳定运行几天后，可以清理旧文件：

# 删除旧的 launchd 配置（桥接用户）
rm -f ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

# 旧的桥接项目文件夹可以归档或删除
# （建议先保留一段时间，确认没问题再删）

从 OpenClaw 内置插件迁移到飞书官方插件

如果你正在使用 OpenClaw 内置插件，想切换到飞书官方插件：

按照飞书官方插件安装指南执行安装
安装过程中会自动禁用 OpenClaw 内置飞书插件
完成 OAuth 授权后即可使用

如果想切回内置插件：卸载官方插件后重启网关，内置插件会自动恢复。

🔧 常见问题 & 排查清单

遇到问题先看这里。如果没找到答案，欢迎开 Issue。

没有消息发送框？（最常见）

这是因为事件订阅没有配置。JSON 批量导入权限不会自动配置事件订阅，需要手动添加：

飞书开放平台 → 你的应用 → 事件与回调
添加事件：im.message.receive_v1（接收消息 v2.0）
订阅方式：选择 「使用长连接接收事件」
版本管理 → 创建新版本 → 发布上线

⚠️ 配置事件订阅前，确保 OpenClaw Gateway 已启动，否则长连接验证会失败。

机器人完全没反应（收不到消息）

按顺序检查：

网关在运行吗？
```
openclaw gateway status
```
如果没运行：openclaw gateway restart
飞书应用发布了吗？ 去飞书开放平台 → 你的应用 → 版本管理，确认有已发布的版本
事件订阅配置了吗？
- 是否选了 "使用长连接接收事件"（不是 Webhook）
- 是否添加了事件 im.message.receive_v1
权限够吗？ 至少需要：im:message、im:message.p2p_msg:readonly、`im:message:sen

openclaw-feishu

Related Skills