1. 项目概述为什么要把 OpenClaw 接进飞书1.1 这个项目到底解决了什么问题先说结论OpenClaw 是一个开源 AI Agent 框架飞书是接口入口真正干活的是一整套可编排的 Agent 链路。做这个事的起因很简单。我自己平时用飞书办公群聊、文档、审批、日历都泡在里面。前一阵想做一个“群聊里的 AI 秘书”能在群里被 之后自动查文档、写纪要、整理表格、触发定时任务。市面上很多现成机器人要么收费要么封闭要么只能做问答没法让我自己编排工具链。于是我把目光转向开源方案OpenClaw。刚开始我查资料的时候发现网上大量教程都在讲“怎么装 OpenClaw”但很少有人讲清楚“装完之后怎么让它真正被飞书用户用起来”。很多教程止步于命令行里跑通一个 demo实战价值不大。所以我这篇博文的重点不是教你怎么敲安装命令而是完整讲一遍“让 AI 住进飞书”的工程化过程从环境准备、飞书应用创建到 OpenClaw 与飞书的双向联动再到技能编排和线上排障。适合谁看一是想在公司或团队内部署 AI 助手的开发者和运维二是已经在用飞书、希望把 AI 能力揉进日常协作的产品和运营三是刚接触 Agent 框架、想找一个完整落地案例的新手。我默认你有一台能跑 Linux 或 WSL 的电脑会基本命令行操作知道 Python 和 Node.js 大概是什么。其实不知道也没关系每一步我都会拆开讲。1.2 技术选型与整体架构整个系统的角色分配是这样的OpenClaw核心调度中枢负责接收消息、调用大模型、执行技能、管理记忆。飞书机器人用户侧的交互入口负责把消息转成事件推送给 OpenClaw再拿 OpenClaw 的回复发回群里。大模型 API推理引擎。OpenClaw 本身不内置模型需要接一个推理服务比如 OpenAI 兼容接口、本地 Ollama、Qwen 系列等。在群里被 之后消息会先到飞书服务器飞书通过事件订阅把 JSON 推给你的服务地址OpenClaw 解析并交给 Agent 逻辑处理后再通过飞书开放 API 发送回复。这就是我最终跑通的核心链路。如果你之前玩过微信公众号开发或者钉钉机器人会发现这套事件回调模型似曾相识——区别在于飞书对加密和鉴权的处理更细后面会专门讲。关于版本和部署环境我选的是 Windows WSL2 Ubuntu 22.04。你可能会问为什么不在 Windows 原生环境跑因为 OpenClaw 的依赖链里有不少 Linux 生态的包原生 Windows 下跑容易碰到编译器和 PATH 的破事WSL2 是兼容性最好的妥协方案。当然如果你有一台 Linux 服务器直接在上面部署会更省心。我这里把 WSL 相关的坑也一并写了因为很多人在第一步就挂在 WSL 上。2. 环境准备与基础部署把 OpenClaw 先跑起来2.1 WSL2 环境搭建与常见报错网上关于 OpenClaw 安装报错最多的一个关键词是 “OpenClaw 无法安全验证”报错原文大概是这样的Windows PowerShell 无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status 检查当前环境。我第一次遇到这个提示也懵了一下。它的本质是安装器调用wsl --status来检查 Linux 子系统状态但系统里没有启用“适用于 Linux 的 Windows 子系统”功能或者内核版本太旧导致命令返回异常。解决办法是先用管理员权限 PowerShell 执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重启系统再去微软商店装 Ubuntu 22.04。装完之后在 PowerShell 里执行wsl --status如果能看到 “默认版本: 2” 这样的信息说明 WSL2 环境正常。如果显示 WSL 1需要执行wsl --set-version Ubuntu-22.04 2手动升级。这里有个实操心得不要在 CMD 里直接敲wsl进入旧发行版之后又升级内核容易出现文件系统层面的玄学问题。最稳妥的流程是商店装 Ubuntu - 启动一次完成 Linux 用户初始化 - 在 PowerShell 里升级到 WSL2 - 重启。我踩过一次坑升级完进去发现 /etc/wsl.conf 没生成后面不少配置都要重做。2.2 Node.js 与 OpenClaw 的安装步骤OpenClaw 官方推荐先装 Node.js 18。这里有个很容易混乱的点你是用 Windows 的 node 还是 WSL 里的 node我的建议是全部操作在 WSL 的 Linux 环境里做不要混着用。否则你很可能在 Windows 侧安装了 node但 OpenClaw 的服务跑在 Linux 侧两边 PATH 不互通调试的时候会疯掉。进入 WSL 后先安装 NodeSource 源里的 Node.js 20 LTScurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs验证一下node -v npm -v然后安装 OpenClaw。我用的安装方式是 npm 全局安装sudo npm install -g openclaw安装完成后可以先初始化一个工作目录mkdir ~/openclaw-workspace cd ~/openclaw-workspace openclaw initinit会生成项目配置、目录结构和一个默认的 agent 配置模板。如果你在 init 过程中遇到权限报错多半是 npm 全局路径的问题。网上有个偏方是把 npm 前缀改到用户目录但我实测下来更省事的方法是直接在命令前加 sudo。缺点是之后你跑openclaw start可能要加 sudo因为日志目录的属主变了。更优雅的做法是初始化完目录后立刻chown给当前用户sudo chown -R $(whoami) ~/openclaw-workspace sudo chown -R $(whoami) /usr/lib/node_modules/openclaw这样后续就不用一直提 sudo 提权。2.3 大模型接口配置为什么必须有一个可用的 LLM APIOpenClaw 本身不产生智能它需要接一个大模型。官方默认支持 OpenAI 兼容协议所以你可以接 OpenAI、DeepSeek、通义千问的 OpenAI 兼容端点也可以用 Ollama 拉起本地模型。我建议新手先接一个云端 API因为本地模型在效果和稳定性上参差不齐。后面我实际用的是 Qwen 通义千问的 OpenAI 兼容接口把 base URL 和 API Key 填进 OpenClaw 的.env配置文件。示例OPENAI_API_KEY你的key OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_MODELqwen-plus很多人在这一步又卡住明明填了 key但跑起来还是报 401。原因是 OpenClaw 的配置项里可能要求同时设置OPENAI_MODEL没设的话默认走 gpt-4而这个模型在兼容端点里不存在于是鉴权直接失败。注意看一下配置文件里的默认 model 字段把它改成你的兼容端点实际支持的名字。跑通验证命令openclaw start --interactive如果能在命令行里和 Agent 对话成功说明基础链路已经 OK。接下来才是重头戏把飞书接进来。3. 飞书侧准备从零创建一个能对话的机器人3.1 飞书开放平台应用创建与权限配置打开飞书开放平台后台创建企业自建应用。应用创建后有两个关键信息要留下来App ID和App Secret。这俩就是机器人在飞书世界的身份证和密码。然后需要给应用添加机器人能力在“添加应用能力”里找到“机器人”启用。启用之后你的应用才能在群聊里以机器人身份出现。飞书的权限模型比较细这里建议一次性把常用权限勾上免得后面调试时动不动就报 no permissionim:message读取消息im:message.group_at_msg读取群组中 机器人的消息im:message.group_msg读取群组中所有消息im:chat读取群信息contact:user.base:readonly读取用户基本信息申请权限之后在企业后台需要管理员审核个人赛博环境里如果你自己就是管理员直接后台点通过就行。一个很容易疏忽的点如果你的机器人想要主动给某个群发消息而不是只能被动回复需要在服务端获取 tenant access token而且应用的“可用范围”里要包含目标群所在的租户。这个后面发送消息的时候再展开。3.2 事件订阅与回调地址配置飞书机器人收到消息后需要一个地方把消息推送给你。这个地方就是“事件订阅”。在应用后台打开“事件订阅”配置请求地址。这个地址必须是你公网可访问的 HTTPS 端点飞书只接受 443 端口的回调。问题来了本地开发环境没有公网 IP 怎么办我用的方案是内网穿透工具把本地端口映射到公网域名。这一步务必注意飞书要求 HTTPS不能是纯 HTTP。如果你没有现成的公网配置也可以先用飞书的“调试平台”临时获取回调消息。在事件订阅里需要添加监听事件。我加了这三个im.message.receive_v1接收消息im.message.message_read_v1消息已读chat.group.member.added_v1机器人被拉入群其中最关键的是第一个。添加之后飞书会让你填写“事件请求地址”并验证。验证的逻辑是飞书向你的回调地址发送一个challenge请求你的服务需要原样返回challenge字段值才算验证通过。如果你在这一步收到 “url 请求失败” 或者验证不通过大概率原因有三个内网穿透服务的域名不是 HTTPS回调接口没有正确处理challenge服务端代码里做了鉴权签名校验但把飞书第一次的验证请求也当成普通业务请求拦截了。3.3 加密方式与安全校验机制飞书的事件订阅支持两种模式明文模式和加密模式。官方默认推荐加密模式也就是在配置回调地址时可以设置 Encrypt Key 和 Verification Token。我的建议是本地调试期先选明文模式跑通之后再切加密模式。为什么因为加密模式下飞书推送的 payload 是 AES 加密过的字符串一旦你的解密代码写错日志里全是乱码排查问题非常痛苦。明文模式下你可以直接在回调服务里 console.log 打日志看到原始 JSON 结构后再去适配加密解析。但正式要上线加密模式逃不掉。飞书用的加密方案是 AES-256-GCM官方提供了多种语言的加解密示例。这里有个要点解密后的 JSON 里除了业务字段还有一个token字段你需要拿它和配置里的 Verification Token 比对防止有人伪造请求。我把回调服务的核心代码贴一下Node.js 版。这里使用飞书官方 SDK 会减少很多弯路const lark require(larksuiteoapi/node-sdk); const client new lark.Client({ appId: process.env.FEISHU_APP_ID, appSecret: process.env.FEISHU_APP_SECRET, }); app.post(/webhook/feishu, async (req, res) { const body req.body; // 飞书验证服务器时需要原样返回 challenge if (body.challenge) { return res.json({ challenge: body.challenge }); } // 判断事件类型 if (body.header.event_type im.message.receive_v1) { const event body.event; console.log(收到消息:, event.message.content); // 交给 OpenClaw 处理 } res.json({ code: 0 }); });这个回调服务起着“翻译官”的作用把飞书的 HTTP 事件转成 OpenClaw 能理解的消息再把 OpenClaw 的回复转成飞书接口要求的 JSON。很多教程在这里直接贴一段完整代码但不说为什么这么设计我后面第三章会专门拆解这段链路的细节。4. 打通链路OpenClaw 与飞书机器人的双向联动4.1 消息接收从飞书事件到 Agent 输入飞书推过来的消息内容是一个 JSON 字符串。比如群聊里有人 了机器人飞书推送的event.message.content是一个文本 JSON结构长这样{ text: _user_1 帮我查一下今天下午的会议安排 }注意content字段是字符串内部又是一层 JSON所以你需要JSON.parse之后再取text字段。要到这一步你得先搞清楚消息里 的那一串_user_1是什么。飞书的 在文本里是_user_1这样的占位符需要把event.message.mentions数组里的key映射为真实用户名。如果你想做“被 才响应”的逻辑就必须检查 mentions 里是否包含机器人的 open_id否则不处理。我这里就把回调服务里的筛选逻辑写清楚const mentions event.message.mentions || []; const botId event.message.chat_id; // 实际判断用 app_id 更准确 const isMentionBot mentions.some(item item.id.opensaki 或 某种标识);实际判断时可以用event.message.mentions里每个 mention 的id.open_id和机器人的 open_id 做比对。初期调试也可以不判断先所有消息都回复验证通了再加约束。4.2 消息发送用 tenant_access_token 调 API 发回群聊OpenClaw 处理完用户的输入之后会把结果返回给你。然后你调用飞书的“发送消息”接口把结果发回群聊。这个接口需要带tenant_access_token。获取 tenant_access_token 的代码const tokenRes await client.auth.tenantAccessToken.internal.create({ data: { app_id: process.env.FEISHU_APP_ID, app_secret: process.env.FEISHU_APP_SECRET, }, }); const token tokenRes.data.tenant_access_token;注意tenant_access_token的有效期是 2 小时缓存起来复用不要每次发消息都重新请求。不然高并发场景下飞书会限流你的 token 接口。发送文本消息的接口大致是await client.im.message.create({ params: { receive_id_type: chat_id }, data: { receive_id: chatId, msg_type: text, content: JSON.stringify({ text: replyText }), }, });这里chatId就是事件里的event.message.chat_id。如果你是想主动给某个群发消息需要先用“获取群信息”接口拿到chat_id或者通过机器人所在群的群 ID 硬编码。4.3 Skills 编排OpenClaw 的“灵魂”OpenClaw 真正厉害的地方不是“能聊天”而是“能调用工具”。在 OpenClaw 里每个工具叫一个 skill。一个 skill 可以做很多事情比如查数据库调外部 HTTP API读文件执行 shell 脚本发飞书消息。skill 的配置一般写在skills目录下。每个 skill 由一个描述文件和一个脚本组成。OpenClaw 会在 Agent 判断需要时自动加载对应 skill。我举一个实际写过的“查飞书日历” skill当用户在群里问“明天的会议”Agent 会调用 skill这个 skill 内部调用飞书日历 API把返回的时间、标题、参会人汇总成一段自然语言回复再发到群里。编排 skill 有个很重要的原则每个 skill 只干一件事且输入输出要标准化。不要贪多写一个大而全的 skill出问题的时候很难定位。4.4 端到端调试我实际跑通的完整过程我把整个链路串一遍方便你对照复现在飞书群里 机器人说“你好”飞书服务端推送im.message.receive_v1事件到你的回调地址回调服务解析消息发现有 机器人转给 OpenClaw 的本地接口OpenClaw 把消息交给大模型大模型返回一个文本回复OpenClaw 把回复通过回调服务写回飞书群聊。我在本地用内网穿透工具暴露回调服务到公网然后在一个测试群里发消息。第一次调试时消息发出去了但回调服务没收到任何推送。打开内网穿透日志一看发现飞书请求的路径是/webhook/feishu但我服务里监听的是/webhook。改好路径后飞书提示“url 验证成功”。然后我发了一句“你好”等了大概 3 秒群里出现机器人回复“你好我是你的飞书 AI 助手。”那一刻我意识到这事的难点不在 AI 模型而在“把一堆组件粘起来”的系统工程。5. 生产环节的硬骨头表格、文件与定时任务的实现5.1 飞书机器人发送表格卡片不用图片也能发结构化数据群里最常见的需求之一是把结构化数据以表格形式发出来。飞书支持通过interactive消息类型发送卡片卡片里可以承载表格、按钮、链接等多类元素。这里的关键点是OpenClaw 返回的内容通常是一段 Markdown 或者纯文本你想要它自动转成结构化卡片需要写一个“格式化器”。我写了一个简单的表格格式化器当 OpenClaw 的输出包含|分隔的行时自动识别为表格数据转成飞书 card JSON。飞书卡片表格的 JSON 骨架大致如下{ config: { wide_screen_mode: true }, header: { title: { tag: plain_text, content: 数据报表 }, template: blue }, elements: [ { tag: div, text: { tag: lark_md, content: **日报汇总**\n| 日期 | 完成数 |\n| --- | --- |\n| 12-11 | 47 | } } ] }这个做法简单但很实用不依赖复杂的卡片构建器把 Markdown 表格塞进lark_md文本块里飞书会渲染成好看的表格。这里有个坑飞书卡片里lark_md的表格渲染要求文本必须符合 Markdown 表格语法且不能有空行。你从 OpenClaw 拿到回复后最好做一下清洗去掉多余的空格和空行。5.2 多媒体消息图片、文件与语音处理如果你的场景需要机器人发图片或文件飞书支持msg_typeimage、msg_typefile等类型。图片形式是先把图片上传到飞书得到image_key再发送消息引用。上传接口await client.im.image.create({ data: fs.readFileSync(path/to.png), });返回参数里有image_key。然后await client.im.message.create({ data: { receive_id: chatId, msg_type: image, content: JSON.stringify({ image_key: key }), }, });语音同理先上传 audio再发msg_typeaudio。我实际做的场景是OpenClaw 把一段日报文字转成语音文件发到群里。用到的语音合成接口是云厂商的 TTS生成的 mp3 转成飞书支持的格式后上传。5.3 定时任务让机器人在固定时间主动汇报飞书机器人主动发消息并不一定需要收到事件。你完全可以在 OpenClaw 里写一个定时调度器比如每天早上 9 点读取待办清单打包成消息发到目标群。实现方式有两种在 OpenClaw 内部使用 cron 或类似机制定时触发 skill。在回调服务外面套一层定时函数直接调用飞书发送 API。我更推荐第二种因为它是和 OpenClaw 解耦的就算 Agent 挂了定时推送至少还能走最近一次缓存的模板数据。定时任务要特别注意时区配置否则你会遇到机器人在凌晨三点发早安消息的场景。飞书 API 默认用 UTC 时间你需要自行转换到本地时区。5.4 内网穿透与 HTTPS 的细节再来聊聊内网穿透。我用的是常见的内网穿透工具比如 frp 或者 cloudflare tunnel。注意选择支持 HTTPS 的产品或配置。Cloudflare Tunnel 可以直接提供 HTTPS 域名不需要自己上传 SSL 证书配置也最简单。我把回调服务跑在本地 3000 端口openclaw start -p 3000然后 cloudflared tunnel 把公网域名映射到localhost:3000即可。飞书后台填写公网域名。实际生产中我更推荐直接买一台便宜的云服务器用 Nginx 反向代理到本地的 OpenClaw 服务。内网穿透适合开发调试云服务器部署适合稳定生产。飞书对回调响应超时比较敏感如果回调服务处理超过几秒不返回飞书会重试或者丢弃消息。所以我的回调服务里业务逻辑一律异步处理先立刻返回code:0给飞书真正的处理放到异步队列里。这一点非常重要能避免大量重复推送。6. 常见问题与排障手册我踩过的坑不能白踩6.1 OpenClaw 启动异常从启动失败到日志分析启动失败最常见的三种现象进程启动几秒后自动退出端口被占用输出一堆红色报错但不知道从哪查起。第一件事永远别看令人绝望的报错第一行直接看完整堆栈尾部。如果是EADDRINUSE说明端口被占用换个端口启动即可。如果是MODULE_NOT_FOUND大概率是安装不完整建议删掉node_modules重装。如果是TypeError之类先确认 Node.js 版本是否符合要求。6.2 飞书回调验签失败与加密解密问题飞书回调验签失败的排查顺序确认回调地址能被公网访问确认回调逻辑对challenge请求返回了正确格式确认验证 token 和 encrypt key 没填错如果开启加密模式确认 AES 解密用的是否和官方 SDK 一致。我见过一个特别蠢的坑用明文模式调试时一切正常切到加密模式后忘了更新回调服务的解密代码导致所有消息都是乱码。建议加密模式改动代码时先在本地打印解密前的原始字符串和官方示例对比。6.3 消息不回复与超时重试原因分析用户发了消息机器人没反应。可能的原因有很多我按发生频率排序回调服务处理超时飞书已经重试但服务端幂等没做好事件被标记为处理失败mentions 判断出错机器人没被识别为被 的对象应用权限不足读取消息失败OpenClaw 内部调用大模型 API 超时Agent 没有返回结果。处理超时是重灾区。我的回调服务里用了一个简单的消息队列收到事件后马上落库并返回 200后台 worker 再处理。这样飞书的 HTTP 请求快速完成不再重试。同时落库的 event_id 可以用于幂等去重防止重复处理。6.4 权限不足与可用范围问题排查飞书开放平台有一个非常容易忽略的点应用可用范围。如果你的应用没有设置“可用范围”覆盖到你所在的群那么机器人即使在群里也收不到消息事件。排查方法是在飞书开放平台后台进入应用的“权限管理”找到“可用范围”确认包含你测试的公司或部门。如果范围是空的那你在群里 机器人后台事件订阅面板里看不到任何推送记录。6.5 一个很常见的域名问题端口 80/443 被占用云服务器部署时经常遇到 80 和 443 端口被系统服务占用的问题。我的建议是不要让 OpenClaw 直接监听 443而是监听内部端口用 Nginx 做 HTTPS 终止。Nginx 配置里加一段server { listen 443 ssl; server_name your.domain.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; } }这样飞书请求先进 Nginx再转发到 OpenClaw。好处是不用改 OpenClaw 的端口配置坏处是多了一层代理如果你要调试 WebSocket 长连接会比较麻烦。OpenClaw 和飞书之间是短连接 Webhook所以不影响。7. 实操心得与扩展建议到了这一节我不打算再铺开讲技术细节反而想分享一下我在这套系统上线的几个真实体验。第一先跑通最小闭环再谈功能扩展。很多人的做法是一开始就想把日历、表格、文档、语音全接上结果每个模块都在半路夭折。我建议你第一次只做“群里 机器人 - 得到文本回复”这一个最小闭环。这个闭环跑通之后后面的功能只是往 OpenClaw 的 skills 目录里加文件的事。第二给自己留一张“逃生舱”。生产环境里大模型 API 一定会抖动OpenClaw 也可能会崩。我会写一个简单的兜底逻辑如果大模型调用连续失败三次机器人回复“服务暂时不可用”然后把错误日志推送到自己的告警群。没有兜底的机器人在上线第二天就会让你在群里社死。第三善用 OpenClaw 的日志系统。它的日志默认打印到控制台但我建议开启文件输出然后定期做日志切割。排查问题时最贵的资源是时间日志齐全能帮你大幅缩短定位链路。第四机器人的人格设定其实很重要。不要直接让大模型裸奔给 OpenClaw 配一个 system prompt。我的机器人在飞书群里的语气是“简洁、专业、不高冷”每次输出不超过三句话还要带一个可执行的下一步。设定人格不是玄学而是让 Agent 输出更符合团队协作场景的约束条件。最后聊聊扩展方向。这套架构接飞书只是起点。同一套 OpenClaw 实例只需要写适配器就能接到企业微信、钉钉、Slack。我已经在规划让机器人自动把群里的讨论整理成周报再通过定时任务发到文档。这个方向的实际价值是它不再是一个“聊天机器人”而是一套正在参与团队知识流转的协作组件。如果你跟着这篇博文跑通了最小闭环接下来就是你自己发挥想象力的时候了。我在实践过程中踩过的最大一个坑是过于迷信“开箱即用”。开源框架只给了你发动机怎么把它装成能跑的汽车还得自己动手。希望这篇实战记录能帮你省掉一些我看文档看到怀疑人生的时间。