OpenClaw 连接飞书完整指南：插件安装、配置与踩坑实录

摘要：本文详细梳理 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 这款插件，文档中提及的飞书插件需通过第三方渠道获取并安装。

解决方案

采用第三方开源插件完成安装，具体命令如下：

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

原因分析

1. 域名配置错误：飞书（中国版）与 Lark（国际版）是字节跳动旗下两款不同版本的产品，二者域名配置不同——飞书（中国版）对应的 domain 为 “feishu”，Lark（国际版）对应的 domain 为 “lark”，此处误将飞书配置为 Lark 的域名。
2. 配置结构错误：该插件要求账号配置需以 accounts 数组格式填写，而非直接在顶层进行配置，错误的结构导致系统无法识别账号信息。

正确的配置方式 ✅

需分三步完成配置，配置完成后重启网关使设置生效：

第一步：配置 accounts 数组（填写账号核心信息）

# 配置账号 ID（默认设为 default 即可）
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）
openclaw config set "channels.feishu.accounts[0].domain" "feishu"

# 关联已配置的账号（与第一步的账号 ID 保持一致）
openclaw config set "channels.feishu.account" "default"

第三步：重启 OpenClaw Gateway，使配置生效

openclaw gateway restart

问题三：飞书应用权限配置不足，导致功能异常

必要权限说明

要实现 OpenClaw 与飞书机器人的正常通信，需在飞书开放平台（open.feishu.cn/app）为应用开启以下权限，缺一不可：

• 机器人权限：获取以应用身份发送的消息、在群组内发送和接受消息
• 即时消息权限：发送消息
• 群组权限：获取群组信息

权限配置步骤

1. 登录飞书开放平台，进入「我的应用」页面，选择需要配置的企业内部应用；
2. 在应用后台左侧菜单栏中，点击「权限管理」；
3. 在权限搜索框中，分别搜索上述所需权限，点击「添加」；
4. 添加完成后，点击「申请权限」并提交审核；
5. 企业内部应用的权限申请通常会自动通过，无需人工审核，等待片刻即可生效。

最终完整配置示例

以下为 OpenClaw 连接飞书的完整配置文件（JSON 格式），可参考此结构核对自身配置：

{
  "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

上述链接中的群 ID 为：f7ftd1a0-50db-46b7-8e86-40a7b731a10a

第二步：执行发送消息命令

方式一：通过命令行发送

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: '大家好'
});

常见问题汇总表

问题现象	核心原因	解决方案
插件安装报 404 错误	官方飞书插件未在 npm 仓库发布	安装 GitHub 第三方开源插件：openclaw plugins install https://github.com/AlexAnys/openclaw-feishu
报错 Feishu account ‘default’ not configured	配置结构错误，未采用 accounts 数组格式	按要求配置 accounts.feishu[0] 数组，填写账号相关信息
报错 Invalid App Access Token	域名配置错误，混淆飞书与 Lark	将 domain 设为 “feishu”（飞书中国版），而非 “lark”
消息发送失败，无响应	飞书应用未开启必要权限	在飞书开放平台申请并开启机器人、即时消息、群组相关权限
配置修改后不生效	未重启 OpenClaw Gateway	执行命令：openclaw gateway restart

总结

OpenClaw 连接飞书机器人的核心要点的如下，掌握这些可有效避免大部分问题：

• 插件来源：放弃官方未发布的插件，选用 GitHub 第三方开源插件；
• 配置结构：严格按照 accounts 数组格式配置账号信息，避免顶层配置；
• 域名区分：明确飞书（中国版）域名为 “feishu”，切勿与 Lark 混淆；
• 权限保障：确保飞书应用开启所有必要权限，否则会导致功能异常；
• 配置生效：每次修改配置后，必须重启 OpenClaw Gateway，否则配置不生效。