Skip to Content
📖 教程📱 渠道接入飞书

接入飞书（Lark）

飞书（Lark）是字节跳动旗下的企业协作平台，在国内互联网和科技公司中使用非常广泛。OpenClaw 提供了官方飞书插件，使用 WebSocket 长连接模式 接入，无需公网 IP 或域名，配置简单、连接稳定。

本篇将手把手教你如何在飞书开放平台创建应用，并将其接入 OpenClaw。

一、飞书开放平台创建应用

1.1 注册并进入开放平台

  1. 访问 飞书开放平台 
  2. 使用你的飞书账号登录（需要有管理员或开发者权限）
  3. 点击 创建企业自建应用

1.2 创建应用

  1. 点击 创建自建应用
  2. 填写应用名称（如 OpenClaw AI）和描述
  3. 上传一个应用图标（可选，但推荐设置以便在聊天中识别）
  4. 创建完成后，你会进入应用管理页面

1.3 添加机器人能力

  1. 在应用管理页面，找到 添加应用能力
  2. 选择 机器人，点击添加
  3. 这一步会让你的应用具备接收和发送消息的能力

1.4 配置权限

在 权限管理 页面，申请以下权限：

  • im:message — 获取与发送单聊、群聊消息
  • im:message.group_at_msg — 接收群聊中 @ 机器人的消息
  • im:message.p2p_msg — 接收用户发给机器人的单聊消息
  • im:chat — 获取群组信息（可选，用于群聊上下文）

💡 提示： 申请权限后，需要企业管理员审批通过才能生效。如果你是企业管理员，可以直接自行批准。

1.5 配置事件订阅

  1. 进入 事件订阅 页面
  2. 选择 使用长连接方式接收事件（WebSocket 模式）
  3. 添加以下事件：
    • im.message.receive_v1 — 接收消息事件

⚠️ 重要： 一定要选择 长连接（WebSocket） 方式，而不是 HTTP 回调方式。OpenClaw 的飞书插件使用 WebSocket 模式，不需要你配置回调 URL。

1.6 发布应用

  1. 在 版本管理与发布 中创建一个版本
  2. 提交审核（企业自建应用通常自动通过或需要管理员审批）
  3. 发布后应用即可使用

二、获取 App ID 和 App Secret

在飞书开放平台的应用管理页面中：

  1. 进入你的应用
  2. 在 凭证与基础信息 页面，可以找到：
    • App ID：格式类似 cli_a1b2c3d4e5f67890
    • App Secret：一串随机字符串

这两个值就是 OpenClaw 连接飞书所需的全部凭证。

三、OpenClaw 配置

3.1 编辑配置文件

打开 ~/.openclaw/openclaw.json，在 channels 中添加飞书配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a1b2c3d4e5f67890",
      "appSecret": "your_app_secret_here"
    }
  }
}

这就是最简配置——只需要 appId 和 appSecret 两个字段。

3.2 重启 Gateway

配置完成后，重启 OpenClaw Gateway 使配置生效：

openclaw gateway restart

如果一切配置正确，你会在日志中看到飞书 WebSocket 连接成功的信息。

3.3 使用 onboard 向导（可选）

如果你还没有配置过 OpenClaw，也可以使用 onboard 向导来引导配置：

openclaw onboard

向导会自动检测已安装的渠道插件，并引导你输入飞书的 App ID 和 App Secret。

四、WebSocket 连接模式说明

OpenClaw 的飞书插件使用 WebSocket 长连接 方式与飞书服务器通信。相比传统的 HTTP 回调模式，WebSocket 有以下优势：

特性WebSocket 模式HTTP 回调模式
是否需要公网 IP❌ 不需要✅ 需要
是否需要域名❌ 不需要✅ 需要
是否需要 SSL 证书❌ 不需要✅ 需要
延迟极低低
防火墙友好✅ 出站连接❌ 需要入站端口
NAT 穿透✅ 自动❌ 需要配置

简单来说：WebSocket 模式让你可以在任何网络环境下运行 OpenClaw，包括家庭网络、公司内网、没有公网 IP 的云服务器等。OpenClaw 会主动连接飞书服务器，不需要飞书能访问到你的机器。

连接断开后，OpenClaw 会自动重连，保证消息不丢失。

五、群聊和单聊支持

5.1 单聊（私聊）

用户可以直接在飞书中搜索你的机器人应用，点击即可开始单聊对话。单聊消息会直接发送给 OpenClaw 处理。

单聊会话对应的 session key 为：agent:<agentId>:feishu:user:<userId>。

5.2 群聊

将机器人添加到飞书群组后，即可在群聊中使用。群聊中的默认行为：

  • 需要 @mention：在群聊中，用户需要 @机器人 才会触发 AI 回复
  • 机器人会自动读取群聊上下文，理解对话背景

群聊会话对应的 session key 为：agent:<agentId>:feishu:group:<chatId>。

将机器人添加到群聊的方法：

  1. 打开飞书群组
  2. 点击群设置 → 群机器人 → 添加机器人
  3. 搜索并选择你创建的应用
  4. 确认添加

六、注意事项和限制

6.1 企业管理员审批

飞书的企业自建应用需要管理员审批后才能使用。如果你不是管理员，需要联系管理员审批你的应用和权限申请。

6.2 消息格式

飞书支持富文本消息，但 OpenClaw 目前主要发送纯文本消息。代码块、链接等 Markdown 格式会根据飞书的支持情况自动转换。

6.3 消息大小限制

飞书单条消息有大小限制（约 150KB）。如果 AI 回复过长，可能需要分多条消息发送。

6.4 机器人可见范围

飞书机器人只能看到以下消息：

  • 单聊中用户发送的所有消息
  • 群聊中 @机器人 的消息（如果配置了 im.message.receive_v1 事件）

6.5 多租户 / 多企业

一个飞书应用只能在创建它的企业内使用。如果你需要在多个企业中使用，需要在每个企业分别创建应用。

6.6 调试技巧

如果遇到连接问题，可以查看 OpenClaw 日志：

# 查看最新日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
 
# 或者使用 gateway 查看状态
openclaw gateway status

常见问题：

  • 连接失败：检查 App ID 和 App Secret 是否正确
  • 收不到消息：检查事件订阅是否配置了 im.message.receive_v1，以及是否选择了 WebSocket 模式
  • 权限不足：检查应用权限是否已申请并通过审批

💬 有问题或建议？ 欢迎在下方评论区留言讨论。

Last updated on
WhatsApp / Telegram / Discord钉钉