OpenClaw 接入飞书详细教程

文章目录

• [OpenClaw 接入飞书完整教程](#OpenClaw 接入飞书完整教程)
• • 前置条件
  • 整体流程
  • 第一步：创建飞书应用并获取凭证
  • 第二步：开启机器人能力
  • 第三步：配置权限
  • 第四步：配置事件订阅
  • 第五步：发布应用
  • 第六步：启用飞书插件
  • 第七步：配置飞书渠道
  • 第八步：与机器人完成配对
  • • 获取配对码
    • 在终端审批配对
  • 第九步：在群组中测试
  • • 添加机器人到群组
    • 验证回复
  • 常见问题排查
  • • [问题一：`openclaw plugins list` 中飞书显示 `disabled`](#问题一：openclaw plugins list 中飞书显示 disabled)
    • 问题二：配置渠道后收不到消息
    • 问题三：机器人回复内容为空或报错
    • 问题四：群聊中机器人响应所有消息，太吵
  • 日常管理命令速查
  • 总结

OpenClaw 接入飞书完整教程

OpenClaw 是一个开源、本地优先的 AI 代理网关，能让大模型在你的电脑/服务器上 7×24 小时运行，支持直接操作电脑、浏览网页、执行命令，还能无缝接入飞书、Telegram、Discord 等聊天平台。本文详细介绍接入飞书的完整配置流程。

---

前置条件

• OpenClaw 已安装（参考《OpenClaw (Clawdbot) 教程》）
• 拥有飞书账号，且具备创建自建应用的权限（企业版 / 个人版均可）

---

整体流程

飞书开放平台
─────────────────────────────────
① 创建企业自建应用，获取 App ID / App Secret
② 开启机器人能力
③ 配置权限（批量导入 JSON）
④ 配置事件订阅（WebSocket 长连接）
⑤ 发布应用

命令行
─────────────────────────────────
⑥ openclaw plugins enable feishu
⑦ openclaw channels add
⑧ openclaw pairing approve feishu <配对码>（配对）
⑨ 群组中 @ 机器人验证

---

第一步：创建飞书应用并获取凭证

1. 打开浏览器访问 飞书开放平台，使用飞书账号登录

2. 点击页面右上角 创建企业自建应用

3. 填写基本信息：

   字段	填写建议
   应用名称	AI-Bot（任意名称）
   应用描述	根据情况填写
   应用图标	上传任意图标，或使用默认

4. 点击 创建，进入应用详情页

5. 点击左侧导航 凭证与基础信息，记录以下两个值：

   字段	说明
   App ID	应用唯一标识，格式如 cli_xxxxxxxxxx
   App Secret	应用密钥，点击"复制"

重要：App Secret 类似密码，请勿泄露或提交到代码仓库。

---

第二步：开启机器人能力

1. 点击左侧导航 添加应用能力 → 机器人 → 添加；
2. 点击左侧导航 权限管理 ，进入下一步。

---

第三步：配置权限

1. 点击左侧导航 权限管理 → 批量导入/导出权限；
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",
      "cardkit:card:read",
      "cardkit:card: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"
    ]
  }
}

3. 确认权限列表无误后点击"申请开通" → "确认"。

---

第四步：配置事件订阅

1. 点击左侧导航 事件与回调 → 事件配置 → 订阅方式；

2. 订阅方式选择 长连接接收事件（WebSocket），点击保存；

   使用 WebSocket 长连接，无需配置公网 IP，本地运行即可接收飞书推送。

3. 点击 添加事件，依次添加以下四个事件：

   事件标识	说明
   im.message.receive_v1	接收消息
   im.message.message_read_v1	消息已读回执
   im.chat.member.bot.added_v1	机器人进群
   im.chat.member.bot.deleted_v1	机器人被移出群

   其他事件可根据需要订阅。

4. 添加无误后进入下一步。

---

第五步：发布应用

1. 点击左侧导航 版本管理与发布 → 创建版本；
2. 填写版本号（如 1.0.0）和发布说明（如 初始版本）；
3. 点击 保存 → 确认发布（按钮上方显示"本次发布免审，提交后自动通过并在线上生效"）。

个人自建应用可直接内测，无需等待审核即可在自己的飞书中使用。

---

第六步：启用飞书插件

飞书平台配置完成后，回到本机终端执行：

openclaw plugins enable feishu

执行后输出（部分）示例：

auto-load: openclaw-weixin (...). Set plugins.allow to explicit trusted ids.
Enabled plugin "feishu". Restart the gateway to apply.

出现 Enabled plugin "feishu". Restart the gateway to apply. 说明启用成功，配置已写入 openclaw.json（原文件自动备份为 .json.bak）。

关于 plugins.allow is empty 警告 ：这是提示你尚未配置插件白名单，系统发现的第三方插件（如已安装的 openclaw-weixin）可能会自动加载。如需精确控制，可在 openclaw.json 中设置 plugins.allow 为受信任的插件 ID 列表；如无特殊需求，忽略该警告即可。

验证是否启用成功：

openclaw plugins list

输出中 feishu 状态为 loaded 表示已启用，disabled 为未启用。

---

第七步：配置飞书渠道

执行以下命令启动配置向导：

openclaw channels add

按照向导依次操作：

步骤	提示内容	说明	选择 / 输入	备注
1	Configure chat channels now?	是否配置聊天渠道	Yes	方向键选中，回车确认
2	Select a channel	选择渠道名称	Feishu/Lark (飞书)	上下键选中，回车确认
2	How do you want to provide this App Secret?	输入凭证方式	Enter App Secret	输入凭证
3	Enter Feishu App Secret	输入飞书 App Secret	xxxxxxxxxxxx	粘贴第一步获取的 App Secret
4	Enter Feishu App ID	输入飞书 App ID	cli_xxxxxxxxxx	粘贴第一步获取的 App ID
5	Feishu connection mode	连接模式	WebSocket (default)	选择默认
6	Which Feishu domain?	选择飞书域名	Feishu (feishu.cn) - China	国内选择Feishu (feishu.cn) - China,国际选择Lark
7	Group chat policy	群聊策略	Open - respond in all groups (requires mention)	在所有群组中响应（需要@提及）
8	Select a channel	是否继续添加渠道	Finished (Done)	完成
9	Configure DM access policies now? (default: pairing)	是否配置私信访问策略	Yes
10	Feishu DM policy	私信策略	Pairing	需配对后才能私信
11	Add display names for these accounts? (optional)	是否为账号添加显示名称	No
12	Bind configured channel accounts to agents now?	是否立即绑定渠道账号到 Agent	No

配置完成后，在 OpenClaw 网页端"频道"选项中可以看到飞书渠道已启用。

---

第八步：与机器人完成配对

在上一步中，私信策略选择了 Pairing------只有完成配对的用户才能与机器人私信对话。

获取配对码

打开飞书，在聊天列表中找到刚创建的机器人，向其发送任意一条私信消息。机器人会回复包含配对码的消息，例如：

OpenClaw: access not configured.
Your Feishu user id: ***********
Pairing code:
HDHAHSDE
Ask the bot owner to approve with:
openclaw pairing approve feishu HDHAHSDE

在终端审批配对

保持 Gateway 运行，另开一个终端，执行：

openclaw pairing approve feishu <配对码>

示例：

openclaw pairing approve feishu HDHAHSDE

终端输出示例：

Approved feishu sender ********************.

出现 Approved feishu sender ... 即表示配对成功，该飞书账号可正常与机器人私信对话。

---

第九步：在群组中测试

添加机器人到群组

1. 打开飞书客户端，创建一个测试群或使用已有群组；
2. 进入群组设置 → 机器人 → 添加；
3. 搜索你的应用名称，点击 添加

验证回复

在群内 @ 机器人发送一条消息，机器人正常回复说明全流程已跑通：

@AI-Bot 介绍一下你自己

---

常见问题排查

问题一：openclaw plugins list 中飞书显示 disabled

解决 ：重新执行 openclaw plugins enable feishu，然后重启 Gateway。

问题二：配置渠道后收不到消息

排查：

1. 确认 Gateway 正在运行：openclaw gateway status
2. 确认事件订阅已添加 im.message.receive_v1 且使用 WebSocket 模式
3. 确认应用已发布，机器人已添加到群组
4. 查看日志：openclaw logs --channel feishu

问题三：机器人回复内容为空或报错

原因：通常是 AI 模型接口配置问题，与飞书无关。

openclaw logs --follow   # 查看详细日志
openclaw doctor          # 系统自诊断

问题四：群聊中机器人响应所有消息，太吵

解决 ：重新执行 openclaw channels add，在群聊策略步骤中选择 Allowlist，只在指定群组中响应。

---

日常管理命令速查

openclaw gateway                     # 启动 Gateway
openclaw gateway status              # 查看 Gateway 运行状态
openclaw gateway restart             # 重启 Gateway
openclaw plugins list                # 查看插件启用状态
openclaw plugins enable feishu       # 启用飞书插件
openclaw channels add                # 添加/重新配置渠道
openclaw logs --follow               # 实时查看全部日志
openclaw doctor                      # 系统自诊断

---

总结

1. 飞书开放平台：创建自建应用 → 开启机器人能力 → 批量导入权限 → 配置 WebSocket 事件订阅 → 发布应用；
2. 命令行 ：openclaw plugins enable feishu → openclaw channels add 填入凭证 → openclaw pairing approve feishu <配对码> 完成私信配对；
3. 新版使用 WebSocket 长连接接收事件，无需配置公网 IP 或 ngrok，本地即可完整跑通。