🦞 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前置准备清单

准备项	要求	备注
服务器 / 本机	2核 4GB 内存以上	家庭宽带也可，无需公网IP
操作系统	Linux / macOS / Windows 均支持	Linux 推荐 Ubuntu 22.04
Node.js	v18.0.0 及以上	node -v 验证
飞书账号	飞书开放平台管理员权限	open.feishu.cn
AI 模型	任意支持的大模型	OpenAI / Claude / DeepSeek / Hunyuan 均可

⚠️

使用飞书 国际版（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 权限配置

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

权限标识符	说明	是否必须
im:message	接收消息	必须
im:message:send_as_bot	以机器人身份发送消息	必须
im:chat	获取群/会话信息	必须
im:chat:readonly	只读群信息	必须
contact:user.base:readonly	读取用户基本信息	必须
docx:document	读写飞书文档	进阶
bitable:app	操作多维表格	进阶
drive:drive	访问云空间文件	进阶

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核心配置参数详解

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

参数	类型	默认值	说明
enabled	boolean	true	启用或禁用飞书渠道
domain	string	"feishu"	国内版用 feishu，国际版用 lark
dmPolicy	string	"pairing"	pairing / allowlist / open / disabled
allowFrom	string[]	[]	白名单用户 Open ID 列表（ou_xxx 格式）
groupPolicy	string	"open"	群聊策略：open / allowlist / disabled
requireMention	boolean	true	群聊是否需要 @ 机器人才响应
streaming	boolean	true	启用流式卡片输出（类 ChatGPT 实时效果）
textChunkLimit	number	2000	单条消息最大字符数，超出自动分段
mediaMaxMb	number	30	媒体文件上传/下载最大 MB
historyLimit	number	50	作为上下文传入 AI 的历史消息条数

机器人内置命令

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

飞书输入框/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/ 目录（含对话历史和配置）

成本参考

项目	费用	备注
OpenClaw 本身	免费开源	MIT 协议
飞书开放平台	免费	企业版/个人版均可
云服务器（2核4G）	约 ¥40~80/月	腾讯云轻量、阿里云 ECS 均可
AI 模型调用	$5~20/月	轻度使用，按量计费

🎉 总结

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

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