OpenClaw 接入飞书集成指南

本教程将指导您完成 OpenClaw 与飞书的集成配置，使您能够在飞书中使用 OpenClaw 的功能。

前置条件

在开始集成之前，请确保满足以下条件：

  • OpenClaw 已安装并运行: 请先完成 Windows 或 Mac 平台的安装教程
  • 飞书企业账号: 需要拥有飞书企业版或旗舰版账号
  • 管理员权限: 需要飞书企业管理员权限以创建自建应用
  • 网络环境: OpenClaw 服务需要能被飞书服务器访问（公网 IP 或内网穿透）
  • OpenClaw 版本: v1.0.0 或更高版本

飞书应用配置

步骤 1: 创建飞书自建应用

  1. 登录 飞书开放平台
  2. 点击右上角 创建应用 按钮
  3. 选择 企业自建应用
  4. 填写应用信息：
    • 应用名称: OpenClaw 助手
    • 应用描述: OpenClaw 与飞书的集成应用
    • 应用图标: 上传 OpenClaw 图标

步骤 2: 配置应用权限

在应用管理页面，进入 权限管理 选项卡，开启以下权限：

  • im:message - 获取与发送消息
  • im:message.group_at_msg - 接收群聊 @ 消息
  • im:chat - 获取群组信息
  • contact:user.base - 获取用户基本信息

步骤 3: 配置事件订阅（长连接模式）

💡 2026 新特性: OpenClaw 使用飞书长连接模式，无需配置公网回调地址，本地部署也能直接使用。

  1. 进入 事件订阅 选项卡
  2. 不要填写请求地址（留空），选择长连接模式
  3. 添加以下事件订阅：
    • im.message.receive_v1 - 接收消息事件（v2.0）
    • im.chat.member.bot.added_v1 - 机器人进群事件
  4. 开启机器人能力（在"应用能力"中勾选）

⚠️ 重要: 请确保使用长连接模式，不要配置回调 URL。这是最常见的配置错误。

步骤 4: 获取应用凭证

在 凭证与基础信息 页面，记录以下信息（后续配置需要）：

  • App ID: 应用唯一标识
  • App Secret: 应用密钥
bash
# 示例（请替换为您的实际凭证）
App ID: cli_a1234567890ab
App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OpenClaw 配置

步骤 5: 配置 OpenClaw 飞书集成参数

使用 openclaw config 命令配置飞书凭证：

bash
openclaw config set channels.feishu.appId "cli_a1234567890ab"
openclaw config set channels.feishu.appSecret "your_app_secret_here"
openclaw config set channels.feishu.enable true

也可以直接编辑 ~/.openclaw/config.yaml：

yaml
channels:
  feishu:
    enable: true
    appId: "cli_a1234567890ab"
    appSecret: "your_app_secret_here"

步骤 6: 重启 OpenClaw

bash
openclaw restart

重启后 OpenClaw 会自动通过长连接模式连接飞书服务器。

集成步骤

步骤 7: 验证连接

由于使用长连接模式，无需配置公网地址或内网穿透。OpenClaw 会主动连接飞书服务器。

检查连接状态：

bash
openclaw status

如果飞书渠道显示"已连接"，说明长连接建立成功。

💡 提示: 长连接模式的优势是本地部署也能直接使用，无需公网 IP 或 ngrok 等内网穿透工具。

步骤 8: 发布飞书应用

  1. 在飞书开放平台，进入 版本管理与发布 页面
  2. 点击 创建版本
  3. 设置权限（至少勾选"获取用户发给机器人的消息"）
  4. 填写版本说明，提交发布
  5. 企业内部应用无需审核，直接发布即可

步骤 10: 在飞书中添加机器人

  1. 打开飞书客户端
  2. 进入目标群聊
  3. 点击群设置 → 机器人 → 添加机器人
  4. 搜索并添加 "OpenClaw 助手"

集成验证

完成所有配置后，按以下步骤验证集成是否成功：

  1. 在飞书群聊中 @OpenClaw 助手，发送测试消息：
text
@OpenClaw助手 你好
  1. 如果集成成功，机器人会回复确认消息
  2. 在 OpenClaw 管理后台查看集成状态：
bash
npm run integration-status

输出应显示飞书集成状态为 已连接。

  1. 检查 OpenClaw 日志确认消息接收正常：
bash
npm run logs -- --filter feishu

ClawHub 飞书 Skills

ClawHub 是 OpenClaw 的官方 Skills 商店（类似 npm），社区开发者在上面发布了多个飞书相关的 Skills，可以大幅简化飞书集成流程。以下是按下载量排序的热门飞书 Skills：

bash
# 安装 ClawHub CLI
npm i -g clawhub

# 搜索飞书相关 Skills
clawhub search "feishu"

feishu-bridge — 飞书 WebSocket 桥接

将飞书机器人通过本地 WebSocket 长连接桥接到 OpenClaw Gateway，无需公网 IP、域名或 ngrok。这是最常用的飞书集成方式。

核心功能：

  • 通过出站 WebSocket 连接飞书云端和 OpenClaw Gateway，无需开放入站端口
  • 自动将飞书聊天映射为 OpenClaw 会话（feishu:<chatId>）
  • 支持 macOS launchd 自动重启，保证服务稳定运行
  • 可自定义群聊响应规则（@提及、问号结尾等触发条件）
bash
# 安装
clawhub install feishu-bridge

# App Secret 安全存储（权限设为 600）
~/.clawdbot/secrets/feishu_app_secret

# 查看桥接日志
~/.clawdbot/logs/feishu-bridge.err.log

来源: clawhub.ai

lark-integration — Webhook 双向桥接

通过 Webhook 方式将飞书/Lark 连接到 OpenClaw，支持完整的富文本内容双向传输。与 feishu-bridge 不同，这个 Skill 使用 Webhook 模式，适合需要接收飞书回调的场景。

核心功能：

  • 在可配置端口上接收飞书 Webhook 回调
  • 通过 WebSocket 将事件转发到 OpenClaw Gateway
  • 支持文本、富文本（post）和图片消息的双向传输
  • 可配合 feishu-card Skill 发送交互式卡片回复
bash
clawhub install lark-integration

来源: clawhub.ai

feishu-doc — 飞书文档读写

提供对飞书知识库、文档、表格和多维表格的编程式读写访问。适合需要通过 OpenClaw 自动化管理飞书文档的场景。

核心功能：

  • 读取飞书 Wiki、Docs、Sheets、Bitable 内容并转换为 Markdown
  • 创建新文档、覆盖或追加 Markdown 内容
  • 支持块级操作（列出/获取/更新/删除文档块）
  • 自动解析飞书 Wiki URL
bash
clawhub install feishu-doc

来源: clawhub.ai

feishu-interactive-cards — 交互式卡片

创建并发送飞书交互式消息卡片（按钮、表单、投票、待办列表等），并通过长轮询回调服务器自动处理用户响应。

核心功能：

  • 发送包含按钮、表单、投票等交互元素的富卡片消息
  • 自动处理用户点击和表单提交的回调
  • 支持自定义 UI 布局
  • 内置长轮询回调服务器
bash
clawhub install feishu-interactive-cards

来源: clawhub.ai

feishu-sticker — 飞书表情贴纸

自动向飞书用户或群组发送图片贴纸，支持上传到飞书 CDN 并缓存 image_key。

核心功能：

  • 上传图片资源到飞书 CDN
  • 通过文件 MD5 缓存 image_key，避免重复上传
  • 优化媒体文件以提高传输效率
bash
clawhub install feishu-sticker

来源: clawhub.ai

feishu-api-docs — 飞书 API 文档查询

从 Apifox 镜像获取飞书开放平台 API 文档，提供可搜索的 API Schema。适合开发者在构建飞书集成时快速查找端点路径、请求/响应结构和参数详情。

核心功能：

  • 按关键词搜索飞书 API（如 "create document"、"im/v1/messages"）
  • 返回结构化的 JSON Schema，包含字段类型和示例
  • 支持离线访问飞书 API 文档
  • 可用于生成类型定义和 API 客户端代码
bash
clawhub install feishu-api-docs

来源: clawhub.ai

⚠️ 安全提醒

2026 年 2 月，ClawHub 上曾发现 341 个恶意 Skills（ClawHavoc 事件）。安装任何社区 Skill 前，请务必：

  1. 查看 Skill 的 SKILL.md 源码，检查是否有可疑的 Shell 命令或网络请求
  2. 优先选择 Star 数高、社区评价好的 Skills
  3. 在沙箱环境中先测试再部署到生产环境
  4. 定期检查 MEMORY.md 文件是否被篡改

更多信息请参考 ClawHub 官方安全指南。

常见问题

问题 1: Webhook 验证失败

症状: 在飞书开放平台点击验证按钮后显示失败。

解决方案:

  1. 确认 OpenClaw 服务正在运行
  2. 确认 Webhook URL 可以从公网访问：
bash
curl -X POST https://your-domain.com/api/feishu/webhook
  1. 检查 .env 中的 FEISHU_VERIFICATION_TOKEN 是否与飞书平台一致
  2. 查看 OpenClaw 日志排查错误：
bash
npm run logs -- --filter webhook

问题 2: 机器人不响应消息

症状: 在群聊中 @ 机器人后没有收到回复。

解决方案:

  1. 确认应用已发布且审核通过
  2. 确认机器人已被添加到群聊中
  3. 检查事件订阅是否正确配置了 im.message.receive_v1
  4. 查看 OpenClaw 日志确认是否收到了飞书的事件推送：
bash
npm run logs -- --filter feishu --level debug

问题 3: 权限不足错误

症状: OpenClaw 日志中出现 permission denied 或 scope not authorized 错误。

解决方案:

  1. 在飞书开放平台检查应用权限是否已全部开启
  2. 确认应用版本已发布（权限变更需要重新发布）
  3. 联系企业管理员确认应用已被授权使用

问题 4: 内网穿透连接不稳定

症状: 使用 ngrok 时 Webhook 偶尔收不到消息。

解决方案:

  1. 使用付费版 ngrok 获取固定域名
  2. 或者使用其他内网穿透工具（如 frp、cloudflared）：
bash
# 使用 cloudflared
cloudflared tunnel --url http://localhost:3000
  1. 生产环境建议部署到公网服务器，避免使用内网穿透

问题 5: App Secret 泄露处理

症状: 怀疑 App Secret 被泄露。

解决方案:

  1. 立即在飞书开放平台重置 App Secret
  2. 更新 OpenClaw 的 .env 配置文件中的 FEISHU_APP_SECRET
  3. 重启 OpenClaw 服务：
bash
npm run restart
  1. 检查应用日志，确认没有异常访问记录