OpenClaw 接入飞书完整教程10分钟搭建专属 AI 助手

🦞 OpenClaw × 飞书 · 2026 最新教程

零代码配置 · WebSocket 长连接 · 流式卡片输出 · 支持文档/多维表格自动化
完整踩坑记录，小白也能跑通

📅 2026-03-15⏱ 阅读约 12 分钟

📑 文章目录

1. 为什么选 OpenClaw 接入飞书？
2. 前置准备清单
3. 第一步：创建飞书自建应用
4. 第二步：配置权限 & 事件订阅
5. 第三步：安装 OpenClaw & 添加飞书渠道
6. 第四步：启动网关 & 验证连接
7. 核心配置参数详解
8. 进阶玩法：文档 / 多维表格 / 定时任务
9. 踩坑记录 & 解决方案
10. 生产环境加固建议

1为什么选 OpenClaw 接入飞书？

OpenClaw（网友戏称"小龙虾"）是 2025 年末至 2026 年初迅速出圈的开源本地 AI 智能体网关。 它的核心定位是：让大模型在你的电脑或服务器上 7×24 小时运行，并能无缝接入主流 IM 平台。 与飞书结合后，你可以在公司聊天窗口里直接召唤一个具备文档读写、多维表格操作、网页浏览能力的 AI 同事。

❌ 传统方式（从零开发飞书Bot）

• 需要自己实现 OAuth2 鉴权
• 手动管理 Token 刷新逻辑
• 事件去重、上下文存储全靠自己
• 开发周期 1~2 周起步
• 需要公网 IP + SSL 证书

✅ OpenClaw 接入（本文方案）

• 内置 OAuth2、Token 刷新、去重
• WebSocket 长连接，无需公网 IP
• 对话上下文自动管理
• 配置到运行仅需约 10 分钟
• 内置飞书文档/多维表格工具

💡

OpenClaw vs WorkBuddy：两者技能生态完全兼容。WorkBuddy 是腾讯基于 OpenClaw 架构推出的商业版，更适合企业开箱即用； OpenClaw 则完全开源自托管，适合个人开发者和有定制需求的团队。本文以 OpenClaw 为主，WorkBuddy 用户也可参考。

2前置准备清单

⚠️

使用飞书国际版（Lark）的同学：飞书与 Lark 协议相同，但 API 域名不同，配置时选择domain: "lark"即可，其余步骤完全一致。

3第一步：创建飞书自建应用

在飞书开放平台创建一个企业自建应用，相当于注册你的 AI 机器人身份。

1

进入飞书开放平台浏览器访问https://open.feishu.cn/app，使用管理员账号登录，点击「创建企业自建应用」。

2

填写应用信息应用名称建议起一个有辨识度的名字，如「AI 工作助手」，上传一个头像图标（PNG，建议 240×240px）。

3

复制凭证信息进入「凭证与基本信息」页面，复制并妥善保存App ID（格式：cli_xxxxxxxxxxxx）和App Secret。 这两个值将在第五步配置 OpenClaw 时用到。

4

启用机器人能力进入「应用能力」→「机器人」，点击「开启机器人能力」，填写机器人名称和简介描述。

✅

此时你已完成了"注册机器人"这一步。App ID 和 App Secret 就是机器人的身份证，后续所有 API 调用都依赖它们。

4第二步：配置权限 & 事件订阅

4.1 权限配置

在「权限管理」页，搜索并开通以下权限。权限分为必须和进阶两档：

4.2 事件订阅（关键步骤）

OpenClaw 默认使用WebSocket 长连接接收消息，这是最推荐的方式，无需公网 IP。

1

进入「事件订阅」页面在「请求网址」处，选择「使用长连接接收事件」（即 WebSocket 模式，非 HTTP 回调）。

2

添加事件搜索并添加事件im.message.receive_v1（接收消息）。如需文件处理，还需添加im.message.message_read_v1。

🔌

WebSocket 长连接的优势：Gateway 主动向飞书服务器发起 WebSocket 连接，消息实时推送。 与 HTTP Webhook 相比，无需配置公网域名和 SSL 证书，特别适合 NAT/防火墙环境后的自托管部署。

4.3 提交应用发布

进入「版本管理与发布」，创建第一个版本并提交审批。企业自建应用通常管理员可直接审批通过。

⚠️

常见坑：应用必须发布并审批通过后，机器人才能正常工作。很多同学配好了权限却忘记发布，导致长时间收不到消息。

5第三步：安装 OpenClaw & 添加飞书渠道

5.1 安装 OpenClaw

通过 npm 全局安装（需 Node.js 18+）：

bash# 全局安装 npm install -g openclaw # 验证安装 openclaw --version

5.2 安装飞书插件

OpenClaw 的飞书支持以插件形式提供，单独安装：

bashopenclaw plugins install @openclaw/feishu

5.3 方式一：命令行向导添加渠道（推荐新手）

bashopenclaw channels add # 交互提示： # ? Select channel type: › Feishu # ? App ID: cli_xxxxxxxxxx # ? App Secret: xxxxxxxxxxxxxxxx # ? Bot display name: AI 工作助手 # ✓ Channel "feishu-main" added successfully

5.4 方式二：手动编辑配置文件

配置文件位于~/.openclaw/openclaw.json，在channels字段下添加：

json{ "channels": { "feishu": { "enabled": true, "domain": "feishu", "dmPolicy": "pairing", "groupPolicy": "open", "requireMention": true, "streaming": true, "accounts": { "main": { "appId": "cli_你的AppID", "appSecret": "你的AppSecret", "botName": "AI 工作助手" } }, "historyLimit": 50 } } }

🔐

生产环境建议将appSecret通过环境变量注入，避免明文写入配置文件："appSecret": "$FEISHU_APP_SECRET"

6第四步：启动网关 & 验证连接

6.1 启动 Gateway

bash# 前台启动（调试用） openclaw gateway # 后台启动（生产用） openclaw gateway & # 查看连接状态 openclaw gateway status

启动成功后，终端会输出类似以下内容：

log✓ Gateway started ✓ Feishu WebSocket connected (account: main) ✓ Listening for events...

6.2 首次配对（私聊）

默认私聊策略为pairing，首次向机器人发私信时，飞书会提示一个 6 位配对码，在终端执行批准命令：

bashopenclaw pairing approve feishu XXXXXX # 批准后查看配对列表 openclaw pairing list feishu

💡

如果是个人使用，可将dmPolicy改为"open"跳过配对步骤。企业场景建议保持"pairing"或"allowlist"以控制访问权限。

6.3 群聊测试

将机器人添加到飞书群组，发送消息时@机器人名即可触发响应（requireMention: true时）。AI 的回复会以飞书交互卡片形式实时流式输出，体验接近 ChatGPT。

用户发消息

→

飞书开放平台

→

WebSocket推送

→

OpenClaw Gateway

→

AI 模型处理

→

卡片流式回复

7核心配置参数详解

以下是飞书渠道的完整配置参数，方便对照调整：

机器人内置命令

在飞书聊天框中直接发送以下命令，无需代码即可控制机器人：

飞书输入框/status → 查看机器人当前状态 /reset → 清空当前对话上下文 /model → 切换使用的 AI 模型 /help → 查看所有可用命令

8进阶玩法：文档 / 多维表格 / 定时任务

完成基础连接后，以下进阶场景能大幅提升办公自动化价值：

📄

读写飞书文档

让 AI 搜索知识库、更新周报文档、自动生成会议纪要

📊

操作多维表格

自然语言增删查改表格记录，无需手动打开表格

⏰

定时任务推送

每日自动发送日报/周报摘要到群聊，解放双手

🌐

网页内容摘要

发一个链接，AI 自动抓取并提炼核心要点

🔀

多 Agent 路由

不同群组路由到不同 AI 角色（客服/研发/运营）

📎

文件解析

直接发送 PDF/Word/Excel，AI 智能提取关键信息

示例：读取飞书多维表格记录

首先确保已开通bitable:app权限，并将应用添加为多维表格的协作者，然后在飞书直接发指令：

飞书消息@AI工作助手 帮我查一下「任务跟踪表」里状态是"进行中"的所有任务

OpenClaw 会自动调用飞书 Bitable API，查询后以消息卡片形式展示结果，全程无需代码。

示例：定时日报推送（需配合 Cron）

bash# 在服务器上设置 cron，每天早上9点推送 crontab -e # 加入以下行： 0 9 * * 1-5 openclaw run --task "生成今日工作计划并发送到[群组ID]"

9踩坑记录 & 解决方案

以下是配置过程中的高频坑位，帮你节省排查时间：

🚧 坑1：应用发布后机器人仍无响应

检查项：①应用版本是否已审批通过；②事件订阅是否选择了「长连接」而非 HTTP 回调；③是否添加了im.message.receive_v1事件。

✅ 解决：进入「版本管理」确认审批状态为"已上线"，同时运行openclaw logs --follow查看实时连接日志。

🚧 坑2：文档/多维表格权限报错 403

开通了docx:document或bitable:app权限，但 AI 仍无法读取文档。

✅ 解决：权限只是"允许调用 API"，还需要在具体文档/表格中手动将应用添加为协作者（点击共享 → 添加成员，搜索应用名）。

🚧 坑3：多维表格写入字段类型报错

创建记录时报field value type mismatch。

✅ 解决：人员字段传[{id: "ou_xxx"}]数组，日期字段传 Unix 毫秒时间戳，单选字段传选项的文字内容而非 ID。

🚧 坑4：消息重复推送

AI 回复了两条相同内容。

✅ 解决：OpenClaw 内置消息去重，但如果同时运行了多个 Gateway 实例，会导致重复处理。确保同一 AppID 只对应一个 Gateway 实例。

🚧 坑5：Token 过期导致偶发失败

运行一段时间后出现鉴权错误。

✅ 解决：OpenClaw 会自动刷新 Token，但如果服务器时钟偏差超过 5 分钟会导致刷新失败。运行ntpdate -u pool.ntp.org同步服务器时间即可。

🛠

万能排查命令：openclaw logs --follow可以实时查看所有事件和错误，90% 的问题看日志就能定位。

10生产环境加固建议

进程守护（Linux systemd）

bash# 创建 systemd 服务 sudo nano /etc/systemd/system/openclaw.service

ini[Unit] Description=OpenClaw AI Gateway After=network.target [Service] Type=simple User=ubuntu ExecStart=/usr/local/bin/openclaw gateway Restart=on-failure RestartSec=10 Environment=FEISHU_APP_SECRET=你的密钥 [Install] WantedBy=multi-user.target

bashsudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw

安全加固要点

• 🔑appSecret通过环境变量注入，不写入配置文件
• 🔒 服务器仅开放必要端口（如 SSH 22），关闭 OpenClaw 无需对外暴露的端口
• 👥dmPolicy使用allowlist精确控制可用人员
• 📊 定期查看openclaw logs排查异常调用
• 💾 定期备份~/.openclaw/目录（含对话历史和配置）

成本参考

🎉 总结

通过以上 4 个步骤，你已经完成了 OpenClaw 与飞书的完整集成： 从飞书自建应用创建，到 WebSocket 长连接配置，再到流式卡片回复—— 整个过程无需公网 IP，无需写一行代码，10 分钟内就能让一个能操作文档、 读写多维表格、自动化任务的 AI 助手在飞书上 7×24 小时陪你工作。

接下来，不妨试试在SOUL.md中给 AI 定制专属人格， 或在AGENTS.md中配置工作流，让它真正成为你团队里不可缺少的"数字同事"。