1. 胡萝虎的博客首页
  2. AI

🔥 OpenClaw 官方飞书插件完整安装、配置与使用教程

诺多 • • AI

OpenClaw+feishu

OpenClaw 官方飞书（Feishu/Lark）插件可实现飞书机器人与 OpenClaw 深度集成，让你在飞书私信/群聊中直接调用 AI 能力，支持会话管理、模型切换、权限控制等核心功能。本教程基于 OpenClaw 官方规范，结合实际操作场景，从插件安装到飞书机器人测试落地，提供一步一操作的完整指南，适配国内飞书与国际版 Lark。

一、前置准备

  1. 已完成 OpenClaw 全新安装与初始化；
  2. OpenClaw 网关已正常运行（执行 openclaw gateway status 显示 running 即可）；
  3. 拥有飞书企业/组织账号，且具备飞书开放平台应用创建权限；
  4. 终端可正常执行 openclaw 命令，无任何报错（执行 openclaw status 验证）。

二、第一步：安装 OpenClaw 飞书官方插件

OpenClaw 提供原生插件安装命令，直接执行即可完成插件下载与注册，无需手动处理目录与依赖：

核心安装命令

# 官方标准插件安装命令（推荐）
openclaw plugins install @openclaw/feishu

安装验证

执行以下命令，若能看到 feishu 插件且无红色报错，说明安装成功：

# 查看已安装插件列表
openclaw plugins list

异常处理

若安装后提示「Cannot find module 'zod'」或依赖缺失，进入插件目录补装依赖即可：

# 进入飞书插件安装目录
cd ~/.openclaw/extensions/feishu
# 用 pnpm 安装所有依赖（OpenClaw 官方推荐，兼容无问题）
pnpm install
# 补装后重启网关
openclaw gateway restart

若提示「duplicate plugin id detected」（插件ID重复），删除内置重复目录即可：

# 删除 nvm 中内置的飞书扩展，彻底解决冲突
rm -rf /Users/你的用户名/.nvm/versions/node/当前node版本/lib/node_modules/openclaw/extensions/feishu
# 重启网关生效
openclaw gateway restart

三、第二步：飞书开放平台创建并配置企业应用

飞书机器人的核心凭证（App ID/Secret）、权限、事件订阅均需在飞书开放平台配置，是集成的关键步骤，需严格按以下流程操作（国内版与国际版操作一致，仅平台地址不同）。

2.1 进入飞书开放平台

2.2 创建企业应用

  1. 登录后点击页面右上角创建企业应用；
  2. 填写基础信息：应用名称（如「OpenClaw AI 助手」）、应用描述（如「OpenClaw 飞书集成机器人」），选择应用图标（可选）；
  3. 点击创建，进入应用配置主页面。

feishu

2.3 获取核心凭证（关键，妥善保管）

进入应用配置页的凭证与基础信息tab，复制以下两个核心参数（后续配置 OpenClaw 需用到）：

  • App ID：格式为 cli_xxx，应用唯一标识；
  • App Secret：应用密钥，切勿泄露给外部人员，丢失后需及时重置。

feishu

2.4 配置应用权限（批量导入，避免遗漏）

飞书机器人需要对应权限才能接收消息、发送回复、访问基础资源，采用批量导入方式配置最便捷：

  1. 进入应用配置页的权限管理tab，点击页面右侧批量导入；
  2. 粘贴以下 JSON 权限配置，点击导入，然后点击申请权限（企业内部应用通常自动通过）：
{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

feishu

2.5 启用机器人功能

  1. 进入应用配置页的应用能力 > 机器人tab；
  2. 点击启用机器人功能，填写机器人名称（如「OpenClaw 助手」，飞书中展示的机器人昵称）；
  3. 可按需上传机器人头像，保存配置。

feishu

2.6 配置事件订阅（保证机器人能接收消息）

事件订阅是飞书机器人接收消息的核心配置，需选择WebSocket 长连接方式，与 OpenClaw 网关联动：

前置检查（必做，否则配置无效）

执行以下命令，确保 OpenClaw 飞书渠道已添加、网关正常运行：

# 添加飞书渠道（若未添加）
openclaw channels add
# 执行后选择「feishu」，按提示临时输入App ID/Secret即可（后续可修改）
# 检查网关状态（必须为 running）
openclaw gateway status

具体配置步骤

  1. 进入应用配置页的事件订阅tab；
  2. 消息接收方式选择使用长连接接收事件(WebSocket)；
  3. 点击添加事件，搜索并选择 im.message.receive_v1（飞书消息接收核心事件，无此事件则机器人收不到消息）；
  4. 保存配置，飞书端事件订阅完成。

feishu

2.7 发布应用（企业内部应用自动批准）

飞书企业应用需发布后才能在组织内使用，步骤如下：

  1. 进入应用配置页的版本管理与发布tab；
  2. 点击创建版本，填写版本描述（如「v1.0 OpenClaw 集成」），点击保存；
  3. 点击提交审核，企业内部应用通常自动批准，无需人工审核；
  4. 审核通过后，点击发布，应用正式生效。

四、第三步：OpenClaw 端飞书渠道核心配置

完成飞书开放平台配置后，需在 OpenClaw 中完善飞书渠道的凭证与策略配置，提供3种配置方法，推荐使用向导配置（简单无错），高级用户可选择配置文件/环境变量方式。

方法一：向导配置（推荐，适合新手）

OpenClaw 提供交互式向导，全程按提示输入参数即可，无需手动编辑文件：

方式1：全新初始化向导（刚安装 OpenClaw 适用）

openclaw onboard

执行后按向导提示，选择飞书(feishu) 渠道，依次输入飞书开放平台获取的 App ID 和 App Secret，向导自动完成配置。

方式2：单独添加/配置飞书渠道（推荐，已安装 OpenClaw 适用）

# 核心命令，启动渠道配置向导
openclaw channels add

执行后流程：

  1. 终端会列出所有支持的渠道，输入feishu并回车；
  2. 按提示依次输入：飞书 App ID（cli_xxx）、App Secret（飞书开放平台复制的密钥）；
  3. 按需设置机器人名称（与飞书端机器人名称一致即可）；
  4. 回车确认，OpenClaw 自动保存配置并启用飞书渠道。

方法二：配置文件配置（适合高级用户，可自定义更多策略）

直接编辑 OpenClaw 核心配置文件 ~/.openclaw/openclaw.json，手动添加飞书渠道配置，可自定义私信/群聊策略：

编辑配置文件

# 用编辑器打开配置文件（如 vscode/nano）
code ~/.openclaw/openclaw.json

粘贴飞书配置节点

在配置文件中添加/修改 channels 节点，替换 appId 和 appSecret 为自己的参数，其余可默认：

{
  "channels": {
    "feishu": {
      "enabled": true,          // 启用飞书渠道
      "dmPolicy": "pairing",    // 私信策略：pairing（未知用户需配对）
      "groupPolicy": "open",    // 群聊策略：open（所有人可@机器人发言）
      "accounts": {
        "main": {
          "appId": "cli_xxx",   // 替换为你的飞书App ID
          "appSecret": "xxx",   // 替换为你的飞书App Secret
          "botName": "OpenClaw AI 助手" // 替换为你的机器人名称
        }
      }
      // 可选：私信允许列表，添加后仅指定用户可发私信
      // "allowFrom": ["飞书用户Open ID1", "飞书用户Open ID2"],
      // 可选：群聊允许列表，groupPolicy为allowlist时生效
      // "groupAllowFrom": ["飞书用户Open ID1"]
    }
  },
  // 保留OpenClaw原有配置（如gateway、plugins等），切勿删除
  "gateway": {
    "mode": "local",
    "auth": {
      "type": "token",
      "token": "你的网关认证token"
    }
  }
}

保存后重启网关

openclaw gateway restart

方法三：环境变量配置（适合服务器/容器部署）

通过设置系统环境变量配置飞书凭证，无需编辑配置文件，重启 OpenClaw 后自动生效：

# 临时配置（终端关闭后失效，适合测试）
export FEISHU_APP_ID="cli_xxx"       # 替换为你的飞书App ID
export FEISHU_APP_SECRET="xxx"       # 替换为你的飞书App Secret
export FEISHU_BOT_NAME="OpenClaw 助手" # 替换为你的机器人名称

# 永久配置（Mac/Linux 系统，写入~/.zshrc或~/.bashrc）
echo 'export FEISHU_APP_ID="cli_xxx"' >> ~/.zshrc
echo 'export FEISHU_APP_SECRET="xxx"' >> ~/.zshrc
source ~/.zshrc # 生效配置

配置完成后重启 OpenClaw 网关：

openclaw gateway restart

配置验证

执行以下命令，若 channels 部分显示 feishu 且 enabled: true，说明配置成功：

openclaw status

五、第四步：启动服务并测试飞书机器人

完成所有配置后，启动 OpenClaw 网关，即可在飞书中测试机器人功能，全程只需3步。

4.1 启动 OpenClaw 网关（核心，必须保持运行）

# 前台启动（终端保持打开，适合测试，可查看实时日志）
openclaw gateway

# 后台启动（适合生产使用，不占用终端）
nohup openclaw gateway > ~/.openclaw/gateway.log 2>&1 &

提示：后台启动后，可通过 tail -f ~/.openclaw/gateway.log 查看网关实时日志。

4.2 飞书中找到机器人并发送测试消息

  1. 打开飞书，在工作台中搜索你的机器人名称（如「OpenClaw 助手」），进入机器人私信界面；
  2. 也可将机器人添加到任意群聊，在群中@机器人发送消息；
  3. 发送第一条测试消息（如「你好」），机器人会回复配对码（因默认私信策略为 pairing，未知用户需配对后才能正常使用）。

feishu

4.3 批准配对（解除私信限制）

终端中执行以下命令，批准飞书机器人的配对码，完成后即可正常对话：

# 核心命令：openclaw pairing approve 渠道名 配对码
openclaw pairing approve feishu 你的配对码

openclaw

示例

若机器人回复配对码为 864219，则执行：

openclaw pairing approve feishu 864219

配对成功后，飞书中会收到「配对成功」的回复，此时即可正常与机器人对话、调用 AI 能力。
feishu

六、第五步：飞书机器人核心使用与权限控制

6.1 机器人内置命令（飞书中直接发送）

在飞书私信/群聊中@机器人，发送以下命令，可实现会话管理、模型切换等功能：

  • /status：查看 OpenClaw 机器人当前状态（网关是否运行、模型版本等）；
  • /reset：重置当前会话（清除历史对话记录，重新开始对话）；
  • /model：查看当前使用的 AI 模型，也可按需切换模型（如 /model claude-opus）。

6.2 私信权限控制（dmPolicy）

通过修改 OpenClaw 飞书渠道配置中的 dmPolicy，可控制机器人的私信访问权限，支持3种策略：

  1. pairing（默认）：未知用户发送消息后收到配对码，管理员批准后可正常使用，适合企业内部管控；
  2. open：允许所有飞书组织内用户发送私信，无需配对，适合开放场景；
  3. allowlist：仅 allowFrom 配置中的飞书用户可发送私信，其余用户无法访问，适合严格管控场景。

配置示例（allowlist 模式）

"feishu": {
  "enabled": true,
  "dmPolicy": "allowlist",
  "allowFrom": ["ou_xxxx1", "ou_xxxx2"], // 飞书用户Open ID
  "accounts": {
    "main": {
      "appId": "cli_xxx",
      "appSecret": "xxx"
    }
  }
}

6.3 群聊权限控制（groupPolicy）

通过修改 groupPolicy，可控制机器人在群聊中的使用权限，支持3种策略：

  1. open（默认）：允许群中所有用户@机器人发言，无限制；
  2. allowlist：仅 groupAllowFrom 配置中的用户@机器人才会回复，其余用户无响应；
  3. disabled：完全禁用群聊功能，机器人不接收任何群聊@消息。

配置示例（disabled 模式，禁用群聊）

"feishu": {
  "enabled": true,
  "dmPolicy": "pairing",
  "groupPolicy": "disabled", // 禁用群聊
  "accounts": {
    "main": {
      "appId": "cli_xxx",
      "appSecret": "xxx"
    }
  }
}

七、常用管理命令

日常使用中，可通过以下命令管理 OpenClaw 飞书插件与网关，高效排查问题、调整配置：

插件管理

# 查看飞书插件状态
openclaw plugins list
# 卸载飞书插件（如需重新安装）
openclaw plugins remove @openclaw/feishu
# 重新加载飞书插件（无需重启网关）
openclaw plugins load feishu

网关管理

# 查看网关实时状态
openclaw gateway status
# 重启网关（配置修改后必做）
openclaw gateway restart
# 停止网关
openclaw gateway stop

日志查看（故障排查核心）

# 实时查看所有日志（含飞书消息、网关运行、插件加载）
openclaw logs --follow
# 仅查看飞书渠道日志（精准排查机器人问题）
openclaw logs --follow channels.feishu

配对管理

# 批准配对码
openclaw pairing approve feishu <配对码>
# 查看所有待批准配对
openclaw pairing list
# 拒绝配对码
openclaw pairing reject feishu <配对码>

八、常见故障排查

若飞书机器人无响应、收不到消息或回复异常，按以下步骤排查，90%的问题可快速解决：

问题1：机器人不接收任何消息，飞书中发送无响应

排查步骤

  1. 检查 OpenClaw 网关是否运行：openclaw gateway status（必须为 running）；
  2. 检查飞书事件订阅是否配置 im.message.receive_v1 事件，且消息接收方式为 WebSocket；
  3. 检查飞书应用是否已发布并批准：飞书开放平台「版本管理与发布」是否为「已发布」状态；
  4. 检查飞书应用权限是否全部通过：飞书开放平台「权限管理」是否无未通过的权限；
  5. 查看实时日志：openclaw logs --follow channels.feishu，查看是否有连接错误、凭证错误。

问题2：机器人能接收消息，但提示「配对码」，批准后仍无响应

排查步骤

  1. 检查配对码是否输入正确：openclaw pairing list 查看待批准配对码，确认无输错；
  2. 检查飞书渠道配置是否启用：openclaw status 查看 channels.feishu.enabled 是否为 true；
  3. 重启网关：openclaw gateway restart，重新批准配对码。

问题3：群聊中@机器人无响应，私信正常

排查步骤

  1. 检查群聊策略：查看 openclaw.json 中 groupPolicy 是否为 disabled（禁用则无响应），改为 open 即可；
  2. 检查是否添加机器人到群聊：飞书群聊中需先将机器人「添加到群」，否则无法接收@消息；
  3. 检查群聊允许列表：若 groupPolicy 为 allowlist，确认发送消息的用户在 groupAllowFrom 中。

问题4：提示「App ID/Secret 错误」，日志显示认证失败

排查步骤

  1. 核对飞书凭证：飞书开放平台「凭证与基础信息」中的 App ID/Secret 与 OpenClaw 配置一致，无空格、输错；
  2. 检查飞书应用是否为「企业应用」：个人应用无法使用机器人功能，需重新创建企业应用；
  3. 重置 App Secret：若怀疑 Secret 泄露，在飞书开放平台重置 Secret，重新更新 OpenClaw 配置。

九、总结

OpenClaw 官方飞书插件的集成核心是**「飞书开放平台配置」+「OpenClaw 渠道联动」**，关键步骤可总结为3点：

  1. 插件安装：用 openclaw plugins install @openclaw/feishu 安装，补装依赖、删除重复目录避免冲突；
  2. 飞书配置：创建企业应用、获取凭证、配置权限/事件订阅、发布应用，核心是启用 im.message.receive_v1 事件；
  3. OpenClaw 配置：用 openclaw channels add 向导配置飞书凭证，启动网关后批准配对码，即可正常使用。

集成完成后，可按需调整私信/群聊权限策略，通过机器人内置命令管理会话，结合 openclaw logs 快速排查问题，实现飞书与 OpenClaw 的无缝联动，让团队在飞书中高效使用 AI 能力。

宝子们，如果你觉得这篇文章有用，记得给我点个赞，分享给更多小伙伴哦！下期想看什么，评论区告诉我！💖

高等精灵实验室

原创文章，作者：诺多，如若转载，请注明出处：https://www.huluohu.com/posts/2049/

赞 (0)
打赏 微信扫一扫 微信扫一扫 支付宝扫一扫 支付宝扫一扫
0 0

关于作者

诺多

诺多

655 文章
118 评论
0 粉丝
这个作者不懒，他正在折腾新玩意～
🦞 纯干货、无肥妞：Openclaw接入企微门槛略高，勾搭下飞书还是没啥难度的！
上一篇 2026年2月2日 08:00
🦞 我不是肥妞，我只是一份OpenClaw 企业微信插件安装与配置保姆级教程
下一篇 2026年2月7日 08:30

相关推荐

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注