OpenClaw飞书插件安装配置踩坑记录与避坑指南

前言

最近在集成OpenClaw与飞书机器人时，踩了不少坑，官方资料零散，社区方案也不够完善。最终跑通全流程后，决定把关键节点和避坑经验整理出来，帮助同样在探索这套工具链的开发者快速落地。

环境信息

• OpenClaw 版本: latest
• Node.js: v22.22.0
• 操作系统: Windows 11
• 飞书应用类型: 企业内部应用

问题一：官方飞书插件安装失败

现象

按照官方文档执行安装命令：

openclaw plugins install feishu

实际结果却是：

Error: Cannot find package '@openclaw/plugin-feishu'
npm ERR! 404 Not Found

原因分析

核心原因很明确：OpenClaw 官方 npm 仓库根本没有发布 @openclaw/plugin-feishu 这个包。文档里提到的飞书插件需要从其他渠道获取。

解决方案

社区已有开发者贡献了第三方开源插件，直接用 GitHub 地址安装即可：

openclaw plugins install https://github.com/AlexAnys/openclaw-feishu

安装完成后验证一下：

openclaw plugins list

如果列表中出现了 feishu，说明安装成功。

问题二：配置后机器人聊天口没有

这种情况通常需要先正确配置事件的长连接订阅模式，再重新发布应用才能生效。

现象

插件安装后，按照文档配置了 App ID 和 App Secret，但一发送消息就报错：

Feishu account 'default' not configured

飞书机器人端没有任何响应。

错误配置示例 ❌

最初这样配置，全是坑：

openclaw config set channels.feishu.app_id "cli_xxx"
openclaw config set channels.feishu.app_secret "xxx"
openclaw config set channels.feishu.domain "lark"  # 错误！应该是 feishu

原因分析

0. 域名混淆：飞书（Feishu）和 Lark 虽然同属字节跳动，但一个是国内版，一个是国际版，配置时必须区分。

   • 飞书（中国版）：domain = "feishu"
   • Lark（国际版）：domain = "lark"

1. 配置结构不匹配：插件要求使用 accounts 数组格式，不能直接把配置放在顶层。

正确的配置方式 ✅

第一步：配置 accounts 数组

# 配置账号 ID
openclaw config set "accounts.feishu[0].id" "default"
# 配置 App ID
openclaw config set "accounts.feishu[0].app_id" "cli_xxx"
# 配置 App Secret
openclaw config set "accounts.feishu[0].app_secret" "xxx"

第二步：配置 channels 引用

# 配置域名（注意是 feishu，不是 lark）
openclaw config set "channels.feishu.accounts[0].domain" "feishu"
# 配置账号引用
openclaw config set "channels.feishu.account" "default"

第三步：重启 Gateway

openclaw gateway restart

问题三：飞书应用权限配置

必要权限

在飞书开放平台（open.feishu.cn/app）需要开启以下权限：

0. 机器人权限

   • ✅ 机器人: 获取以应用身份发送的消息
   • ✅ 机器人: 在群组内发送和接受消息

1. 即时消息权限

   • ✅ 即时消息: 发送消息

2. 群组权限

   • ✅ 群组: 获取群组信息

配置步骤

0. 进入飞书开放平台 → 我的应用
1. 点击 权限管理
2. 搜索并添加上述权限
3. 点击 申请权限 并提交
4. 等待审核通过（企业应用通常自动过审）

最终完整配置

{
  "accounts": {
    "feishu": [
      {
        "id": "default",
        "app_id": "cli_xxx",
        "app_secret": "xxx"
      }
    ]
  },
  "channels": {
    "feishu": {
      "account": "default",
      "accounts": [
        {
          "id": "default",
          "domain": "feishu",
          "app_id": "cli_xxx",
          "app_secret": "xxx"
        }
      ]
    }
  }
}

测试发送消息

获取群聊 ID

群聊 ID 可以从飞书群链接中提取：

https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=f7ftd1a0-50db-46b7-8e86-40a7b731a10a

链接中的 f7ftd1a0-50db-46b7-8e86-40a7b731a10a 就是群 ID。

发送消息命令

命令行直接发送：

openclaw message send 
  --channel feishu 
  --target "chat:f7ftd1a0-50db-46b7-8e86-40a7b731a10a" 
  --message "大家好，这是测试消息！"

代码中调用：

await message.send({
  channel: 'feishu',
  target: 'chat:f7ftd1a0-50db-46b7-8e86-40a7b731a10a',
  message: '大家好'
});

常见问题汇总

总结

搞定飞书集成的五个关键点：

0. ✅ 插件来源：使用 GitHub 第三方插件替代官方未发布包
1. ✅ 配置结构：采用 accounts 数组格式，避免顶层乱塞
2. ✅ 域名精确：飞书不是 Lark，别混淆
3. ✅ 权限完备：该开的权限一个不能少
4. ✅ 重启生效：每次改完配置，执行 openclaw gateway restart

希望这篇实战记录能帮你少走弯路。遇到问题欢迎在评论区交流。

参考链接

• OpenClaw 官方文档
• 飞书开放平台
• openclaw-feishu 插件源码
• 飞书 API 文档

来源：互联网