最近这段时间，OpenClaw 这个开源 AI 助手框架热度越来越高，不少人都想把它接到飞书里，在群聊中直接调教一个属于自己的 AI Agent。我花了一下午把 OpenClaw 和飞书完整打通，从 WSL2 环境检测、开放平台建应用、事件订阅，到机器人发文本、发多维表格记录，每一步都走了一遍，也踩了不少文档里没写明白的坑。这篇飞书配置指南不绕弯子，按真实操作顺序讲清楚每一步怎么点、参数怎么填、报错怎么查，适合手里有飞书企业账号、想在 WSL2 或 Linux 服务器上部署 OpenClaw 的开发者参考。
这其实就是你最需要知道的结论：OpenClaw 不是一个聊天 UI，而是一个 AI Agent 运行框架，飞书只是它的“遥控器”和“展示窗口”。你可以通过飞书消息让它查数据、改状态、跑脚本、总结文档，然后它再把结果以文本、卡片甚至多维表格的形式发回群里。下面按我的实操路径逐步展开。
1. 为什么选择在飞书里跑 OpenClaw
先说一个很多人没想清楚的问题：既然 OpenClaw 能在终端跑，为什么非要接飞书？我的答案是，飞书提供了 OpenClaw 最缺的三样东西：主动触达、移动端入口、多人协作界面。
1.1 OpenClaw 到底能做什么
OpenClaw 本质上是一个个人 AI 助手网关，把大模型能力、工具调用、知识库、自动化流程串在一起，再通过 IM 平台暴露给用户。我实际用到的能力包括：在群里 @ 机器人让它汇总当日待办、让它读取飞书文档生成摘要、让它根据多维表格内容更新任务状态、让它定时推送提醒。
传统做法是写一堆脚本、配 cron、再发到群里的 Webhook。OpenClaw 的价值在于把“理解指令—调度工具—返回结果”这一整条链路收敛到一个对话入口里。你不需要记住命令，直接说人话就行。
对于不熟悉命令行的产品经理或运营同学，这更是刚需。团队里非技术成员能在飞书里直接让机器人干活，不需要打开终端，不需要部署环境，权限也由开放平台统一管控。
1.2 飞书接入的三种方式和我的选择
飞书开放平台目前有几种常见接入路径，我列个表方便对照：
| 接入方式 | 交互方向 | 需要的条件 | 适合场景 |
|---|---|---|---|
| 自定义机器人 Webhook | 单向，只能发消息 | 群内添加，无需审核 | 告警推送、定时通知 |
| 企业自建应用 + 事件订阅（Webhook 回调） | 双向，能收能发 | 公网 HTTPS 回调地址 | 服务器部署、生产环境 |
| 企业自建应用 + 事件订阅（长连接模式） | 双向，能收能发 | 无需公网地址 | 个人开发、本地部署 |
我最推荐第三种：长连接模式。飞书开放平台支持 WebSocket 长连接接收事件，OpenClaw 启动后直接建立长连接通道，不需要给本地环境做公网映射，也不用申请域名和 HTTPS 证书。这一步能省掉大量网络层面的麻烦，尤其是公司网络策略比较严的时候。
如果你有云服务器，或者已经配置好了域名反代，那用第一种 Webhook 回调模式也可以，逻辑上多一个 HTTP 入口，排查链路会稍微复杂一点。核心还是先在本地把长连接跑通，再考虑迁移到服务器。
2. 搭建运行环境：先解决 WSL2 检测问题
OpenClaw 官方比较推荐的运行环境是 Linux，Windows 下一般配合 WSL2 使用。这一节最想提醒你的就是安装时那个经典报错：“无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl -- status”。我一开始也被这个提示卡了二十多分钟，其实原因不复杂，就是系统里 WSL2 的组件状态不满足检测条件。
2.1 “无法安全验证 WSL2 环境”到底怎么处理
先按这个顺序排查，基本能覆盖 90% 的情况：
第一步，以管理员身份打开 PowerShell，运行wsl -- status。注意命令中间是有空格的，别把wsl和--status连在一起。查看输出内容里是否有“默认版本：2”以及内核版本信息。如果命令本身提示无法识别，通常是 Windows 版本太旧或者 WSL 组件缺失，先运行wsl --update更新内核，再重试。
第二步，确认 Windows 功能里“适用于 Linux 的 Windows 子系统”和“虚拟机平台”都已勾选启用。改完之后必须重启电脑。很多情况下你执行一万遍wsl --update都没用，就是因为功能没开全，系统组件没生效。
第三步，如果wsl -l -v显示当前发行版的版本是 1，需要手动转换：wsl --set-version Ubuntu-22.04 2。这个过程会重新配置内核，耗时几分钟，耐心等它完成。
第四步，转换完成后回到 PowerShell，再次运行wsl -- status，确认一切正常，再重新执行 OpenClaw 的安装命令。
这个检测本质上是在确认底层容器环境稳定，避免后面 Node 进程运行到一半被 WSL 内核问题拖垮。我见过有人直接跳过检测，结果跑了几小时后消息链路莫名中断，排查到最后还是回到 WSL2 版本不匹配的问题上。环境检查这一步别图快。
2.2 安装 Ubuntu 与 Node.js
如果你还没有 WSL 发行版，直接执行wsl --install -d Ubuntu-22.04。安装完成后进入 Ubuntu 终端，先做一次系统更新：
sudo apt update && sudo apt upgrade -yNode.js 的安装我建议用 nvm，避免系统包版本混乱：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18 node -vOpenClaw 要求 Node.js 18 以上。实测用 20 LTS 没遇到兼容问题，用太新的版本比如 23 反而可能碰到某些依赖尚未适配的情况，所以建议锁 LTS。
2.3 安装 OpenClaw 初始化
Node 环境就绪后，执行全局安装：
npm install -g openclaw openclaw init初始化过程会生成配置目录~/.openclaw/，核心配置文件是config.yaml。运行openclaw --version可以确认安装版本。不同版本命令可能有细微差别，我这边的包管理命令以你实际下载的 README 为准，但整体流程一致。
启动命令是openclaw start，第一次启动可能会进入交互式配置向导，会让你选择模型、填写 API Key 等。你也可以直接编辑配置文件跳过向导，后面会说具体字段。
3. 飞书开放平台侧配置：创建机器人应用
环境准备好之后，接下来是飞书侧的工作。这一节每一步都跟权限和事件订阅挂钩，错一步后面就收不到消息。
3.1 创建企业自建应用并拿到凭据
用企业管理员账号登录飞书开放平台，进入“开发者后台”，点击“创建企业自建应用”。名称和描述随意，但建议写清楚是 AI 助手，方便后续管理员审核。创建成功后，在“凭证与基础信息”页面拿到两个关键参数：App ID 和 App Secret。
App ID 形如cli_xxxxxxxx，是应用唯一标识；App Secret 相当于密码，只展示一次，务必保存好，后续填到 OpenClaw 配置文件里。
接着在“应用能力”中添加“机器人”能力。添加后，应用就具备了一个飞书机器人身份，可以在群聊中被添加和被 @。
3.2 权限配置与发布版本
权限是整个接入里最容易出问题的一环。机器人能做什么，完全取决于你给它开了哪些权限。我建议先按最小集开通，跑通后再扩展：
| 权限标识 | 作用 |
|---|---|
im:message | 读取机器人接收到的消息 |
im:message.send | 以机器人身份发送消息 |
im:chat | 获取群聊基本信息 |
contact:user.base:readonly | 读取用户基础信息，用于识别发送者 |
bitable:app | 读写多维表格，用于发送表格和更新记录 |
drive:drive | 访问云文档，用于文档导出和摘要 |
在“权限管理”页面搜索并开通以上权限后，必须进入“版本管理与发布”页面，创建一个新版本并提交发布。注意：权限的变更只有在新版本发布后才会生效，这也是很多人改了权限却毫无变化的原因。
如果你的企业审核流程比较严格，可以先在“测试企业与人员”里添加自己为测试人员，这样个人测试时无需等待管理员审批。
3.3 事件订阅配置要点
进入“事件与回调”页面，这是连接的核心。这里需要做两件事：选择接收模式、订阅事件。
接收模式我强烈建议选“长连接”。选完之后页面会生成一个长连接地址，把地址复制下来备用。OpenClaw 启动后会用这个地址建立 WebSocket 连接，后台状态会显示“连接正常”。
事件订阅至少要添加两个事件：im.message.receive_v1（接收消息）和im.chat.member.bot.added_v1（机器人被拉进群）。保存前如果选择的是 Webhook 回调模式，飞书会发送一个 URL 验证请求，你的服务端必须正确响应 challenge 参数才能保存成功。
这里提供一个 Express 实现的最小回调接口参考：
const express = require('express'); const app = express(); app.use(express.json()); app.post('/openclaw/feishu/callback', (req, res) => { const { challenge, token, type } = req.body; if (token !== process.env.FEISHU_VERIFICATION_TOKEN) { return res.status(403).send('invalid token'); } if (type === 'url_verification') { return res.json({ challenge }); } console.log(JSON.stringify(req.body)); res.status(200).send('ok'); }); app.listen(9000);如果你配置了 Encrypt Key，飞书会把整个事件报文用 AES 加密，challenge 也在密文里，这时必须用 Encrypt Key 解出明文后再返回 challenge。解密算法是 AES-256-CBC，密钥取 Encrypt Key 的 MD5 值，手写很容易出错，建议直接用飞书官方 SDK 封装好的解密方法。
4. OpenClaw 连接飞书：配置与验证
飞书侧应用建好、证书拿到、事件订阅保存成功后，回到 OpenClaw 配置文件里把两边接起来。
4.1 配置文件怎么写
编辑~/.openclaw/config.yaml，加上飞书相关配置。我用的是长连接模式，配置大概长这样：
feishu: app_id: "cli_xxxxxxxx" app_secret: "xxxxxxxxxxxxxxxx" mode: websocket event_endpoint: "/openclaw/feishu/callback" verification_token: "xxxxxxxx" encrypt_key: "xxxxxxxx" port: 9000字段含义对照一下：app_id和app_secret来自开放平台“凭证与基础信息”；mode选择websocket就是长连接，选webhook就是回调模式；event_endpoint仅回调模式时使用，对应你在开放平台填的路径；verification_token和encrypt_key在“事件与回调”页面可以找到或自行设置。
模型部分的配置同样在这个文件里。如果你用云端模型，直接填 API Key：
model: provider: openai_compatible base_url: "https://api.example.com/v1" api_key: "sk-xxxxxxxx" model: "gpt-4o"4.2 启动与联调
运行openclaw start，观察启动日志。长连接模式下，日志里会出现飞书长连接已建立的相关提示，看到类似feishu websocket connected就说明链路通了。
回到飞书客户端，搜索你创建的应用名称，创建一个群聊把机器人拉进去，然后发一条消息并 @ 机器人。正常情况下机器人会通过大模型接口生成回复并发送到群里。
如果没有任何响应，不要急着怀疑代码，按顺序检查三件事：第一，事件订阅里是否添加了im.message.receive_v1；第二，应用版本是否已经发布且权限生效；第三，OpenClaw 日志里是否出现了收到的消息事件。80% 的问题出在这三处。
4.3 让机器人发送消息和表格
文本消息打通后，下一个常见需求是让机器人发送表格。这里有两种形态，我分别说。
第一种是把数据写入飞书多维表格。先在飞书里创建一张多维表格，打开表格后从 URL 中提取app_token，在表格页面左下角找到数据表 ID 作为table_id。然后通过飞书开放 API 添加记录：
// 先获取 tenant_access_token // POST /open-apis/auth/v3/tenant_access_token/internal // body: { "app_id": "...", "app_secret": "..." } const res = await fetch( `https://open.feishu.cn/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records`, { method: 'POST', headers: { 'Authorization': `Bearer ${tenantAccessToken}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ fields: { "任务": "准备周报", "状态": "进行中" } }) } );第二种形态是直接在聊天里发一个可视化表格卡片。飞书消息卡片支持table元素，OpenClaw 可以在工具调用里组装卡片 JSON，调用消息接口发送。效果比纯文本直观很多，适合把查询结果、日报汇总等结构化数据直接展示在群里。
我在实际使用中更倾向于把数据写入多维表格而不是发卡片，因为卡片是静态的，多维表格可以持续被更新、筛选、协作编辑，对 Agent 来说这就是一个天然的外部记忆和任务看板。
5. 模型接入与进阶联动
飞书通道打通后，OpenClaw 的能力边界就取决于你给它接了什么模型、什么工具。这里补充两个我实测过比较有价值的联动方向。
5.1 关联本地模型 qwen2.5-3b
如果企业内部数据不能出内网，或者你想省掉云端 API 费用，可以把 OpenClaw 的模型指向本地推理服务。我用 Ollama 跑过 Qwen2.5 系列，接入方式很简单：
ollama run qwen2.5:3b然后在 OpenClaw 配置里指向本地服务：
model: provider: openai_compatible base_url: "http://localhost:11434/v1" api_key: "ollama" model: "qwen2.5:3b"Ollama 的/v1接口兼容 OpenAI 格式，所以 OpenClaw 可以直接把它当云端 API 用，只是地址换成本机。
关于模型选型，我个人建议 3B 参数级别的模型用于简单问答和意图识别还行，但涉及工具调用、参数提取时容易漏字段。如果你要让机器人稳定操作飞书多维表格，至少用 7B 或 14B 级别，复杂任务拆解会更可靠。
5.2 把飞书多维表格当作 Agent 的记忆库
多维表格不只是展示工具，它非常适合做 Agent 的持久化记忆。OpenClaw 处理完任务后，可以把结论、状态、时间戳写回多维表格，这样团队成员可以在表格里人工修改、审核、补充信息，Agent 和人共用一个数据源。
具体实现上，你可以在 OpenClaw 的工具配置里加入一个“更新多维表格记录”的自定义工具，核心逻辑就是调用 bitable API。我实际跑的流程是：群里有人说“把任务 A 状态改为完成”，OpenClaw 解析出任务名和状态，调用 API 找到对应记录并更新字段，然后在群里回一句“已更新”。整个过程 2 秒内完成，比人工操作可靠得多。
顺带一提，Codex、Claude Code 这类命令行 Agent 也可以接入到同一个飞书机器人链路里。思路是让 OpenClaw 把收到的消息作为指令转给对应 CLI 执行，再把结果回传。这个玩法适合想把多个 Agent 统一收口到飞书的团队，等基础链路稳定后再尝试。
5.3 知识库与文档处理
如果你平时把笔记存在 Obsidian 本地库，可以通过 OpenClaw 的文件读取工具把 Markdown 文件作为上下文喂给模型，实现“问我的笔记”这类能力。飞书云文档也可以打通：通过云文档 API 导出文档内容，再交给模型做摘要或问答。
这几个方向本质上都是在丰富 Agent 的“手”和“眼睛”：飞书入口负责对话，多维表格负责数据，本地文件负责知识，云文档负责检索。每接一个工具，Agent 能独立完成的事情就多一件。
6. 常见问题与排查技巧实录
接入过程中我整理了一份高频问题速查表，基本覆盖了社区里出现频率最高的报错和异常：
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
| 安装时提示无法安全验证 WSL2 环境 | WSL2 内核未更新或版本为 1 | PowerShell 运行wsl -- status和wsl --update，确认功能已启用 |
| 飞书开放平台提示应用异常 | 权限未发布或版本未生效 | 重新创建版本并发布，等待 1-2 分钟 |
| 机器人收不到任何消息 | 未订阅im.message.receive_v1 | 在事件订阅中添加事件并保存 |
| 回调 URL 验证失败 | 没有正确返回 challenge 原文字段 | 检查接口逻辑；配置加密时先解密再返回 |
| 机器人无法发送表格记录 | 缺少 bitable 权限或应用未发布 | 权限管理里开通 bitable 相关权限，重新发布版本 |
| 长连接一直显示连接中 | 应用版本未生效或长连接地址未保存 | 在开放平台确认保存状态，重新发布应用版本 |
| 飞书客户端提示网络异常 | 本机出网策略、防火墙或账号网络受限 | 检查本机网络和企业网络策略，与机器人链路本身无关 |
6.1 三步定位法：把问题范围缩小
遇到问题先别乱试，按照“链路三段论”来定位：事件从飞书到 OpenClaw，再到模型响应，最后回到飞书。第一步看 OpenClaw 日志里有没有收到事件；第二步看飞书后台“事件与回调-事件投递记录”，确认平台是否成功推送；第三步看网络链路，长连接模式检查 WebSocket 是否稳定，回调模式检查地址是否可达。
这套方法能解决绝大多数“机器人没反应”的问题。如果 OpenClaw 日志里压根没有事件进来，问题一定出在飞书侧订阅或网络通道，而不是模型配置。
6.2 我的避坑心得
结合这次实战，我总结了几条对新手最有价值的经验。
第一，个人部署优先用长连接模式，不要在本地折腾公网回调。公网回调需要域名、HTTPS 证书、反向代理，还要考虑防火墙策略，链路一长排查就痛苦。长连接模式下 OpenClaw 主动连接飞书，配置最少，稳定度也够。
第二，权限变更一定要重新发布版本。我遇到过在权限管理里开了多维表格权限，但忘了发布新版本，导致机器人一直报无权限的错误，浪费了快半小时。
第三，安全习惯要养成。App Secret 和 Encrypt Key 属于敏感凭据，放进环境变量或者.env文件里，不要硬编码在配置文件中并提交到 Git 仓库。提交前检查.gitignore，防止把密钥带出去。
第四，OpenClaw 迭代速度比较快，升级大版本前备份~/.openclaw/目录。我见过有人升级后配置格式不兼容导致启动失败，备份了还能快速回滚。
第五，群聊场景下机器人必须被 @ 才会触发回复。如果你发现机器人对群消息不敏感，先检查是否 @ 了它，以及事件订阅里是否开启了消息接收。
写在最后
从我这次实测的路径来看，最顺的路线就是：先在 WSL2 里把 OpenClaw 环境跑通，飞书后台用长连接模式创建自建应用，先把文本消息链路打通，再逐步接上多维表格、本地模型和文档处理。每一步都验证通过后再往下走，你会发现整个接入过程其实是线性的，并没有想象中那么复杂。
最后再分享一个小技巧：遇到环境类报错时先深呼吸，百分之七八十都是 WSL2、Node 版本、应用版本三者不匹配导致的，不是代码问题。把版本信息收集齐，按序排查，基本都能解决。等基础链路稳定后，就可以把 OpenClaw 当真正的私人助理来用了，你有哪些好玩的联动玩法，欢迎回来一起交流。
