最近这段时间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 官方比较推荐的运行环境是 LinuxWindows 下一般配合 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 Keymodel: provider: openai_compatible base_url: https://api.example.com/v1 api_key: sk-xxxxxxxx model: gpt-4o4.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:3bOllama 的/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 内核未更新或版本为 1PowerShell 运行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 当真正的私人助理来用了你有哪些好玩的联动玩法欢迎回来一起交流。