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 内置插件

📋 目录

• 🆕 Lark CLI（飞书官方开源 CLI）
• 飞书官方插件（安装指南）
• 飞书官方 vs OpenClaw 内置：怎么选？
• OpenClaw 内置插件教程（从零配置）
• 从旧版迁移
• 常见问题 & 排查清单（含 API 配额耗尽 排查）
• 进阶配置参考
• Lark（国际版）接入指南
• 更新日志
• 致社区
• 链接

🚀 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 内置：怎么选？

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

选择建议

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

• 想让 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 分钟。

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

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

第二步：启用机器人能力

进入你刚创建的应用：

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

第三步：配置权限

1. 左侧菜单进入 权限管理
2. 点击 批量导入
3. 粘贴以下 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 网关启动后再做，否则保存会失败。 先做第五、六步，回来再做这一步也可以。

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

第五步：记下凭证

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

• App ID（格式如 cli_xxxxxxxxx）
• App Secret

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

第六步：发布应用

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

第七步：在 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

第八步：发消息测试

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

openclaw pairing approve feishu <配对码>

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

回来补第四步：如果你先跳过了事件订阅，现在网关已启动，回到飞书开放平台把第四步做完，保存后重启网关（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. 补全飞书应用权限

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

1. 打开 飞书开放平台 → 进入你的应用
2. 进入 权限管理 → 点击 批量导入
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. 导入后 → 创建新版本 → 发布（让新权限生效）

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 复制即可。）

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

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 内置插件，想切换到飞书官方插件：

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

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

🔧 常见问题 & 排查清单

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

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

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

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

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

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

按顺序检查：

1. 网关在运行吗？

   openclaw gateway status
   

   如果没运行：openclaw gateway restart

2. 飞书应用发布了吗？ 去飞书开放平台 → 你的应用 → 版本管理，确认有已发布的版本

3. 事件订阅配置了吗？

   • 是否选了 "使用长连接接收事件"（不是 Webhook）
   • 是否添加了事件 im.message.receive_v1

4. 权限够吗？ 至少需要：im:message、im:message.p2p_msg:readonly、`im:message:sen