前阵子折腾了一整天终于把OpenClaw接进了飞书。最开始以为就是走个webhook转发的事结果先是WSL2环境验证失败后来又卡在事件订阅的回调超时上等真能收消息了机器人又半天不吭声。那感觉就是每一步都在给下一层的坑交学费。这篇把从环境搭建到最终跑通的完整过程整理出来不说虚的全是实际操作。OpenClaw简单说就是一个开源的AI Agent运行框架类似你自己搭一个能配工具、能挂技能的智能助手底盘。它可以接不同家的大模型也可以接本地Ollama还带一套Skill机制让模型能真正调用外部工具干活。飞书则是把这个Agent送进真实工作场景的入口同事在群里机器人机器人去查多维表格、回消息、发卡片、管待办整个链路极其自然。这篇文章写给谁一是已经部署了OpenClaw、想找一块正经试验场的用户二是公司里在飞书上想搞AI机器人但又不知道从哪入手的开发或运维同学。全文大概要花二十分钟读完照着做大约需要一两个小时。我的建议是别上来就整花活先把最基础的收消息和回消息跑通再往上加功能。1. 先搞清楚OpenClaw和飞书是怎么握手的1.1 OpenClaw到底是什么能干什么很多第一次接触OpenClaw的人第一反应是问它和Claude Code、Codex这类工具的区别。说简单点Claude Code这类东西是帮你写代码的AI终端而OpenClaw更像一个常驻的后台Agent服务你把大模型接进去给它挂上各种技能它就能7x24小时待命收到消息就思考、查数据、调工具、再回复。它不局限于写代码日常工作流里那些查一下汇总一下提醒我的事情都可以丢给它。它可以跑在什么环境下Windows上通常需要WSL2因为是Linux系工具链也可以直接在Linux服务器上跑树莓派那种小主机也行社区里甚至有人用Termux在安卓手机上装适合出门在外临时连一下的场景。模型侧它不挑食OpenAI兼容接口、Claude接口都能接本地模型则走Ollama。做飞书接入之前建议你先把它在一个终端里跑通至少验证问它一句它能答。1.2 为什么入口偏偏选飞书市面上能接的IM很多但飞书有个别家比不了的优势它不只是聊天工具还是一个完整的工作台。群聊里机器人只是最表层的东西往下还有多维表格、云文档、待办、日历、审批。Agent接到飞书上等于直接拥有了这些生产力工具的API它可以从多维表格里拉数据、把结果整理成卡片发回群里、再帮你创建待办这一整条链路是闭环的。另外一个现实因素飞书的机器人API做得相当规范。事件订阅支持Webhook和长连接两种模式有完整的权限体系、消息类型、富文本卡片。这意味着你不需要为每个功能自己发明轮子照着开放平台的文档来就行。唯一的问题是文档分散、术语多第一次上手容易懵这也是我写这篇指南的直接原因。1.3 整体架构一条消息是怎么走完的先看一条最简单的链路你在飞书里给机器人发了一句帮我查一下昨天的新增客户会发生什么飞书客户端 -- 飞书开放平台 -- 事件推送(长连接或Webhook) -- OpenClaw -- 调API发消息 -- OpenClaw调用大模型/Skill --用户消息先到飞书开放平台OpenClaw通过长连接或回调地址收到事件OpenClaw把正文交给大模型理解模型决定调用哪个Skill去查多维表格查到结果后OpenClaw再调用飞书API以机器人身份把答案发回对话。整个过程快的话两三秒慢的话取决于模型响应时间。这里有个很多新手会搞混的点OpenClaw和飞书不是直接连的中间必须经过飞书开放平台。所以你要做的其实就是两件事——让OpenClaw能收到飞书推送的事件让它能调用飞书API发消息。后面所有配置都围绕这两个目标展开。2. 环境准备先把OpenClaw这块地基打好2.1 Windows用户先把WSL2这块硬骨头啃下来OpenClaw在Windows上跑绝大多数情况要依赖WSL2。它需要一个完整的Linux用户态环境来做进程管理、脚本执行和技能隔离WSL2比WSL1在系统调用兼容性上强很多项目也默认要求2代版本。我这台机器第一次启动OpenClaw时直接弹了一个让人摸不着头脑的提示大意是无法安全验证WSL2环境请在PowerShell中运行wsl --status检查。我当时第一反应是怎么还验证不了的后来才明白OpenClaw启动时会主动检查WSL版本检测不到满足条件的2代环境就直接拒绝启动这是安全策略不是bug。遇到这个问题按这个顺序处理以管理员身份打开PowerShell运行wsl --status看输出里是否提示默认版本2如果没有说明你还在用旧版WSL甚至没装。运行wsl --update把WSL内核升级到最新版。这一步很关键很多验证失败其实就是内核太老。运行wsl --set-default-version 2把默认虚拟机版本设成2。运行wsl -l -v确认里边的发行版比如Ubuntu的版本列显示的是2如果是1用wsl --set-version Ubuntu 2转换这个过程可能要几分钟。全部搞定后再在PowerShell里跑wsl --status看到默认版本2回到OpenClaw重新启动这个报错就消失了。注意wsl --status和wsl -l -v是两个完全不同的命令前者看WSL整体的配置状态后者看具体装了哪些发行版以及各自版本。OpenClaw的报错提示里专门让你跑wsl --status因为它要检查的是全局默认配置不是某个发行版的版本号。2.2 Node.js与OpenClaw安装OpenClaw需要Node.js环境建议装LTS版本。直接去Node.js官网下载安装包Windows下就是一路下一步装完打开PowerShell验证node -v npm -v两个命令都有版本号输出就算成功。你要是之前装过旧版本建议卸干净再装新LTS省得后面出现各种莫名其妙的模块兼容问题。OpenClaw本身的安装有两种常见方式一种是用npm全局安装执行npm install -g openclaw另一种是用官方提供的一键安装脚本。不同版本命令可能略有差异装完后运行openclaw --version确认一下。我再强调一句很多报错都出在以为装好了但实际没装对上装完先跑版本命令这一步别跳过。首次使用建议跑一下openclaw init它会生成一个默认配置文件YAML格式。这个文件就是OpenClaw的总闸模型、技能、渠道都在里面配。2.3 算力从哪来只接API还是接Ollama我经常被人问OpenClaw是不是只能用API方式接算力不是。它支持两类模型接入方式一类是云厂商的API另一类是本地模型本地模型最常见的部署工具就是Ollama。如果走API你只需要在配置里填上base_url、api_key、model三个字段指向任意兼容OpenAI接口的服务即可非常省事。如果走Ollama先在本地装好Ollama然后拉模型ollama pull qwen2.5:14b拉完以后Ollama默认监听11434端口它同时提供一个/v1/chat/completions接口兼容OpenAI格式所以OpenClaw配置里指向http://localhost:11434就行模型名填你拉的那个。两种方案怎么选我的建议是日常对话、复杂推理任务用API模型聪明、速度快隐私敏感的数据整理、文本分类这类不追求创造力的任务丢给本地模型处理。很多人一上来就纠结必须全部本地化其实没必要混合用才是常态。考虑到飞书接入的场景往往是处理真实业务数据我更推荐API为主、本地为辅的组合。2.4 Windows Companion是什么要不要装如果你用的是Windows可能看到过OpenClaw Windows Companion这个组件。它的作用简单说就是给Agent一个操作Windows本地系统的手读剪贴板、模拟简单操作、管理本地文件之类的。对飞书接入来说它不是必需的因为飞书交互走的是网络API不依赖本地系统能力。但如果你想让Agent在飞书里帮你做一件需要操作电脑上某个软件才能完成的事那Companion就有用了。配置方式通常是下载Companion程序到Windows启动后它会生成一个本地连接地址或配对码把这段信息填到OpenClaw的配置里。注意Companion和OpenClaw最好在同一台机器或同一局域网内网络隔离会直接导致配对失败。我的建议是先不装把飞书链路跑通以后确实有需求了再补。3. 飞书开放平台创建你自己的机器人应用3.1 创建应用并开启机器人能力飞书侧的接入得先有个应用身份。打开飞书开放平台open.feishu.cn进开发者后台选择创建企业自建应用填上应用名称和图标创建完就进入应用详情页。这里要先理清一个概念飞书机器人分两种。一种是群里的自定义机器人只能通过Webhook向群内发消息不能收消息只能做单向通知另一种是应用机器人它是挂在应用下面的既能收用户消息也能主动发消息双向交互。我们要做的飞书Agent必须用后者——应用机器人。创建应用后在添加应用能力里找到机器人启用它。启用完你会在应用详情里看到机器人菜单点进去可以设置机器人的头像、名字。这个机器人就是用户能在飞书里搜索到、私聊或拉进群的那个人。3.2 权限配置哪些权限点必须开飞书应用默认所有API权限都是关闭的不配权限后面调接口只会报没有权限。这里整理一张最小权限表权限点作用是否必须im:message接收用户和群消息事件必须im:message:send_as_bot以机器人身份发送消息必须im:chat:readonly读取群基础信息群成员、群名称建议im:chat.member:readonly读取群成员列表按需bitable:app读写多维表格按需docs:doc操作云文档按需task:task创建和读取待办按需权限开好以后关键一步是发布版本。企业自建应用发布后需要管理员审核审核通过权限才真正生效。很多人的机器人明明配置了权限却还是报无权限十有八九是卡在这代码里开着权限但应用线上版本还是旧的。我建议直接在开发者后台创建版本时选择企业内发布审核通常很快个人测试环境也可以选启用沙箱模式先调试。3.3 事件订阅Webhook还是长连接这是整个接入里最容易让新手犯迷糊的地方。飞书把有人给机器人发了一条消息这件事封装成事件推送给你你有两种收事件的方式。第一种是Webhook模式也叫事件回调。你在开放平台配一个公网可达的URL飞书往这个URL上POST事件。本地开发机器没有公网地址要么自己有一台公网服务器或内网穿透工具把本地端口映射出去要么就折腾内网穿透。而且Webhook还有一个槛飞书要求你的服务必须在3秒内响应200否则算超时重试。本地冷启动慢非常容易触发。第二种是长连接模式也叫WebSocket模式。你的服务主动和飞书开放平台建立一个持久化的WebSocket连接事件通过连接直接推下来。不需要公网URL不需要内网穿透没有3秒超时问题。对绝大多数个人开发者和中小企业来说长连接都是最优解。我就是用的长连接省掉了公网服务器那一环。你在飞书开发者后台的事件订阅配置里选择使用长连接接收事件即可。OpenClaw侧只要支持WebSocket模式连上去连接一建立飞书后台状态栏就会显示服务在线。提示如果你的OpenClaw部署在服务器上且有固定公网IPWebhook模式也可以但第一次调试我还是建议用长连接。把能不能收到事件这个变量先排除掉后面排查问题会轻松很多。3.4 拿到四件关键凭证不管用哪种模式你都需要从飞书开发者后台拿到以下信息App ID应用唯一标识形如cli_开头。App Secret应用密钥调用API时用于换取tenant_access_token。Verification Token事件验证令牌校验事件来源。Encrypt Key加密密钥事件推送使用AES加密时解密用。App ID和App Secret在凭证与基础信息页面Verification Token和Encrypt Key在事件订阅页面Encrypt Key可以不启用但我建议启用加密多一层安全反正OpenClaw侧都支持自动解密。这四个值建议直接复制到一个临时文件里后面配OpenClaw要用。4. 核心对接让OpenClaw和飞书真正通信4.1 配置OpenClaw的飞书渠道OpenClaw这边的配置核心是在配置文件中启用飞书渠道并填入上一步拿到的凭证。不同版本配置文件格式可能略有差异但核心字段大差不差思路是一样的channels: feishu: enabled: true app_id: cli_xxxxxxxx app_secret: xxxxxxxxxxxxxxxx verification_token: xxxxxxxxxxxxxxxx encrypt_key: xxxxxxxxxxxxxxxx mode: websocket # websocket 或 webhook webhook_path: /feishu/event # 用 webhook 模式时填 group_at_only: true # 群里只响应 机器人的消息如果你用的OpenClaw版本里没有channels.feishu这个内置渠道段也别慌去技能市场找飞书适配的Skill或者用更通用的一招把飞书的事件订阅地址指向OpenClaw的通用Webhook入口再在OpenClaw里挂一个飞书消息处理器技能。核心逻辑都是一样OpenClaw收到飞书事件解析出消息文本交给大模型处理然后把回复发回飞书。配置完以后启动OpenClaw观察启动日志。如果看到类似Feishu channel connected或WebSocket connected的输出说明长连接建立成功飞书后台的事件订阅页面也会显示在线状态。这一步成功就说明链路通了三分之一。4.2 消息事件长什么样怎么解析在OpenClaw内部你无需太关心飞书事件的具体格式底层都已经帮你解析好了。但作为接入的人我建议你至少看懂最核心的事件结构否则遇到机器人收到消息但答非所问会很懵。飞书收到消息时推送的事件大致是这样的{ schema: 2.0, header: { event_type: im.message.receive_v1, event_id: evt_xxxxxxxx, app_id: cli_xxxxxxxx, token: xxxxxxxx }, event: { message: { message_id: om_xxxxxxxx, message_type: text, content: {\text\:\帮我查一下昨天的销售数据\}, chat_id: oc_xxxxxxxx }, sender: { sender_type: user, sender_id: {open_id: ou_xxxxxxxx} } } }你需要关注的就是几个字段event_type告诉你这是收到消息事件message.content里是消息正文注意它是JSON字符串需要解析一层message.chat_id是对话IDsender.sender_id.open_id是发送者ID。OpenClaw侧会把message.content解析好之后作为用户输入传给模型同时保留chat_id用于回复。4.3 私聊和群聊机器人的行为控制这是接入后最容易翻车的场景。机器人同时被私聊和拉进群如果你不区分场合它可能在群里把每条消息都回一遍所有人都难受。配置里那个group_at_only: true就是干这个的群聊中只处理有机器人的消息私聊中处理所有消息。群里用户机器人的时候事件里会带上mentions信息包含被的用户ID。OpenClaw的行为逻辑是这样的先判断是私聊还是群聊是群聊就检查有没有自己有才触发回复没有就直接忽略。如果你发现有人在群里了机器人但它没回优先检查两件事一是group_at_only是否被误设成false二是你的时候飞书是否成功把机器人识别进mention列表拉群时机器人必须在群里。4.4 主动发消息token的获取与缓存收消息只算一半发消息是另一半。OpenClaw向飞书发消息本质上就是调用飞书的消息API。第一步要换取一个tenant_access_tokencurl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id: cli_xxxxxxxx, app_secret: xxxxxxxx}响应里会有tenant_access_token和expire字段这个token有效期是7200秒也就是2小时。OpenClaw内部会自动帮你做缓存和续期你不需要每次发消息都重新换。但如果你自己在写调试脚本记住一定把token缓存起来2小时内复用别每次请求都换一次既慢又容易被限流。拿到token之后发一条文本消息长这样curl -s -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typeopen_id \ -H Authorization: Bearer t-xxxxxxxx \ -H Content-Type: application/json \ -d { receive_id: ou_xxxxxxxx, msg_type: text, content: {\text\:\你好我是OpenClaw机器人\} }receive_id_type可以是open_id、user_id、chat_id等对着不同标识类型。发到群里就用chat_id。这一步能通恭喜你双向通信已经彻底打通了。5. 进阶玩法表格、卡片与多维表格联动5.1 让机器人发送表格的几种姿势很多人搜飞书机器人发送表格其实真正想要的是让机器人发一个结构化的、看着像表格的消息。这里有三条路难度递增、效果也递增。最简单的是发富文本消息msg_type: post用文本列表的形式把信息列出来虽然不叫表格但阅读性尚可。中等方案是用交互卡片msg_type: interactive卡片的column_set组件能实现真正多列的效果配合表头行和内容行视觉上就是一个规整的表格。最高级的方案是让机器人直接创建一张多维表格或电子表格把数据写进去再发一个链接给用户。我推荐日常场景用交互卡片。原因很简单数据量不大时卡片一目了然且阅读体验最好数据量大了再引导用户点链接去看完整表格。这里给一个卡片表格的核心结构示例{ msg_type: interactive, card: { config: {wide_screen_mode: true}, header: { title: {tag: plain_text, content: 昨日销售汇总}, template: blue }, elements: [ { tag: column_set, flex_mode: none, background_style: grey, columns: [ { tag: column, width: weighted, weight: 1, elements: [{tag: plain_text, content: 区域}] }, { tag: column, width: weighted, weight: 1, elements: [{tag: plain_text, content: 销售额}] }, { tag: column, width: weighted, weight: 1, elements: [{tag: plain_text, content: 同比}] } ] } ] } }每一行数据再复制一个column_set放进去就能形成一个多行多列的表格卡片。OpenClaw的Skill可以把Markdown表格自动转换成这种卡片结构你在飞书里看到的体验就是Agent直接把一张表拍在你脸上。5.2 多维表格读写让Agent直接操作业务数据多维表格Base是飞书最大的杀手锏。它的本质是一个带API的在线数据库你可以让OpenClaw直接读写里面的记录。记录API的路径是GET/POST /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records其中app_token是某个多维表格文档的唯一标识就在文档URL里table_id是文档内某一个数据表的标识。OpenClaw通过Skill封装这些API之后你在飞书里跟它说把A组昨天没有跟进的客户都标成待跟进它就会去读取记录、筛选、更新状态字段全程你不用打开表格。这里要特别提醒权限操作多维表格需要提前在应用权限里开bitable:app并且发布版本生效。否则API会返回一个很常见的权限不足错误码。还有一点多维表格API的写操作是按记录逐条提交的批量更新时注意频率别一次性并发几百条容易被限流最好分批处理。至于很多人问的多维表格上下合并问题其实在Agent视角里合并就是三步查询出需要合并的行、按目标字段去重、把保留行的值更新到合并结果。你不用指望API给你一个一键合并按钮让Agent帮你把逻辑串起来才是它存在的意义。5.3 Skill扩展云文档抓取与网站嵌入OpenClaw的Skill机制是整个体系里最值得花时间研究的。一个Skill就是一个可复用的工具包飞书场景下建议优先找这几个多维表格操作、云文档读取、待办管理、消息卡片构造。Skill市场找得到现成的找不到也可以自己写本质就是给Agent描述清楚这个工具能干什么、参数是什么、怎么调用。被问得很多的另一个需求是怎么把飞书云文档内容嵌到自己网站上。正经做法有两种如果你的文档是公开分享的直接用iframe嵌入飞书文档是支持这种展示方式的iframe src你的飞书文档公开链接 width100% height600 frameborder0/iframe如果文档不想公开或者要更灵活的展示就换一种思路让OpenClaw通过云文档API把内容读取出来转成Markdown或HTML你再嵌进自己的页面。这本质上是内容搬运格式化只要API权限到位Agent能帮你定时同步甚至能做到文档更新、网站自动更新。这种Agent作为内容管道的玩法比手工复制粘贴优雅太多。6. 常见问题排查与避坑实录6.1 高频问题速查表问题现象最可能的原因解决方案OpenClaw启动提示无法安全验证WSL2环境WSL2默认版本未设置或内核过旧PowerShell执行wsl --update和wsl --set-default-version 2再跑wsl --status确认飞书后台显示服务在线但消息触发不回复权限未发布或group_at_only配置问题检查应用版本是否已发布群聊确认是否真的到了机器人发消息报权限错误im:message:send_as_bot权限未开或未生效开发者后台加权限重新发布版本事件推送一直超时重试Webhook响应超过3秒换长连接模式或在回调里先立刻返回200再异步处理收到的消息内容是转义后的JSONmessage.content本身就是JSON字符串解析一层JSON.parse再使用请求API报App 不存在或未启用App Secret填错或应用被平台停用核对凭证在开发者后台检查应用状态飞书客户端下载后连不上网络系统防火墙或安全软件拦截进程检查防火墙放行飞书重启客户端和网络不要随意修改系统DNS机器人回复速度很慢模型响应慢或API限流先确认大模型接口的延迟必要时换更快的小模型处理简单问题6.2 WSL2验证失败的处理全流程这个坑我值得专门展开讲因为搜索openclaw无法安全验证wsl2环境的人特别多。它的本质是OpenClaw在启动时做了一项安全预检查判断当前Windows环境是否符合运行要求。OpenClaw内部会调用wsl --status来读取配置如果解析到默认版本不是2或者WSL内核组件不完整就会拒绝启动。实战中最有效的修复路径是这样的先跑wsl --status看输出——如果提示你未安装用于Linux的Windows子系统内核直接wsl --update装内核装完重启终端如果显示默认版本1执行wsl --set-default-version 2如果你发现根本没有安装任何发行版用wsl --install -d Ubuntu装一个。全部完成后再跑wsl -l -v确认Ubuntu那行Version列是2至此再启动OpenClaw问题就消失了。这里有个容易被忽略的细节修改完WSL配置后一定要重启你的PowerShell或Terminal窗口让环境变量重新加载。很多人改完直接在旧窗口里跑以为没生效白白多试了半天。6.3 飞书开放平台异常的几种真面目报飞书开放平台异常时先别急着骂平台九成是应用配置自身的问题。我排查时习惯按这个顺序检查App ID和App Secret是否复制对了、应用是否因为长期无活动被停用、权限是否发布到了线上版本、是否错用了沙箱环境的凭证在正式环境。沙箱模式的App ID和正式模式的凭证是两套混用就会出现一个现象飞书后台看一切正常调API却各种报错。另一个隐蔽问题是企业自建应用的管理员审核状态。如果你的应用版本停留在待审核所有权限都是纸面上的。我建议在开发者后台把应用设为启用并确认版本状态显示已发布。企业内有管理员权限的话直接自己审核通过即可。6.4 消息丢失与事件推送超时长连接模式下一般不会丢消息但OpenClaw如果处理一条消息耗时过长飞书那侧会认为处理超时并触发重试。如果消息处理是不可幂等的比如插入了一条重复记录就需要你的事件处理器有去重机制按event_id做缓存判断重复事件直接忽略。OpenClaw在处理飞书消息时应该默认支持这个逻辑但你自己写Skill时千万记得这一点。Webhook模式下消息丢失更常见原因是回调地址不稳定或响应超时。飞书会对失败事件重试多次但如果你本地服务断断续续可能就丢了不少。这是我从一开始就坚持用长连接的另一个原因连接状态一断你能立刻从日志里看到不用等用户说没收到才后知后觉。6.5 调试三板斧接入过程中我给你一个自己一直在用的黄金排查顺序。第一看OpenClaw的日志报错信息里九成带着具体原因第二去飞书开发者后台的事件订阅页面看事件接收记录那里能看到推送历史、发送状态和错误详情第三用curl手动调一遍飞书API能直接复现问题是token过期、参数不对还是权限没通。手动调试时记得直接在PowerShell或终端里跑别写在代码里跑。因为代码会把异常吞掉而你手动跑curl能看到飞书返回的完整错误码和错误信息。飞书的错误码文档很全绝大多数问题对着错误码就能定位。最后再分享一个我在实际使用中的体会先跑通最小闭环再谈优化。很多人一上来就想着接多维表格、发复杂卡片、搞定时推送结果基础的消息收发都没验证好出了问题根本不知道是OpenClaw的问题、飞书的问题还是网络的问题。我自己的路径是先私聊机器人说一句话确认能收到回复再拉个群确认能触发然后才去加权限、接多维表格、写卡片模板。每一步都是一小块验证全部绿了才往后走。这套思路对任何接入类项目都适用也希望你少踩几个我踩过的坑。
前阵子折腾了一整天终于把OpenClaw接进了飞书。最开始以为就是走个webhook转发的事结果先是WSL2环境验证失败后来又卡在事件订阅的回调超时上等真能收消息了机器人又半天不吭声。那感觉就是每一步都在给下一层的坑交学费。这篇把从环境搭建到最终跑通的完整过程整理出来不说虚的全是实际操作。OpenClaw简单说就是一个开源的AI Agent运行框架类似你自己搭一个能配工具、能挂技能的智能助手底盘。它可以接不同家的大模型也可以接本地Ollama还带一套Skill机制让模型能真正调用外部工具干活。飞书则是把这个Agent送进真实工作场景的入口同事在群里机器人机器人去查多维表格、回消息、发卡片、管待办整个链路极其自然。这篇文章写给谁一是已经部署了OpenClaw、想找一块正经试验场的用户二是公司里在飞书上想搞AI机器人但又不知道从哪入手的开发或运维同学。全文大概要花二十分钟读完照着做大约需要一两个小时。我的建议是别上来就整花活先把最基础的收消息和回消息跑通再往上加功能。1. 先搞清楚OpenClaw和飞书是怎么握手的1.1 OpenClaw到底是什么能干什么很多第一次接触OpenClaw的人第一反应是问它和Claude Code、Codex这类工具的区别。说简单点Claude Code这类东西是帮你写代码的AI终端而OpenClaw更像一个常驻的后台Agent服务你把大模型接进去给它挂上各种技能它就能7x24小时待命收到消息就思考、查数据、调工具、再回复。它不局限于写代码日常工作流里那些查一下汇总一下提醒我的事情都可以丢给它。它可以跑在什么环境下Windows上通常需要WSL2因为是Linux系工具链也可以直接在Linux服务器上跑树莓派那种小主机也行社区里甚至有人用Termux在安卓手机上装适合出门在外临时连一下的场景。模型侧它不挑食OpenAI兼容接口、Claude接口都能接本地模型则走Ollama。做飞书接入之前建议你先把它在一个终端里跑通至少验证问它一句它能答。1.2 为什么入口偏偏选飞书市面上能接的IM很多但飞书有个别家比不了的优势它不只是聊天工具还是一个完整的工作台。群聊里机器人只是最表层的东西往下还有多维表格、云文档、待办、日历、审批。Agent接到飞书上等于直接拥有了这些生产力工具的API它可以从多维表格里拉数据、把结果整理成卡片发回群里、再帮你创建待办这一整条链路是闭环的。另外一个现实因素飞书的机器人API做得相当规范。事件订阅支持Webhook和长连接两种模式有完整的权限体系、消息类型、富文本卡片。这意味着你不需要为每个功能自己发明轮子照着开放平台的文档来就行。唯一的问题是文档分散、术语多第一次上手容易懵这也是我写这篇指南的直接原因。1.3 整体架构一条消息是怎么走完的先看一条最简单的链路你在飞书里给机器人发了一句帮我查一下昨天的新增客户会发生什么飞书客户端 -- 飞书开放平台 -- 事件推送(长连接或Webhook) -- OpenClaw -- 调API发消息 -- OpenClaw调用大模型/Skill --用户消息先到飞书开放平台OpenClaw通过长连接或回调地址收到事件OpenClaw把正文交给大模型理解模型决定调用哪个Skill去查多维表格查到结果后OpenClaw再调用飞书API以机器人身份把答案发回对话。整个过程快的话两三秒慢的话取决于模型响应时间。这里有个很多新手会搞混的点OpenClaw和飞书不是直接连的中间必须经过飞书开放平台。所以你要做的其实就是两件事——让OpenClaw能收到飞书推送的事件让它能调用飞书API发消息。后面所有配置都围绕这两个目标展开。2. 环境准备先把OpenClaw这块地基打好2.1 Windows用户先把WSL2这块硬骨头啃下来OpenClaw在Windows上跑绝大多数情况要依赖WSL2。它需要一个完整的Linux用户态环境来做进程管理、脚本执行和技能隔离WSL2比WSL1在系统调用兼容性上强很多项目也默认要求2代版本。我这台机器第一次启动OpenClaw时直接弹了一个让人摸不着头脑的提示大意是无法安全验证WSL2环境请在PowerShell中运行wsl --status检查。我当时第一反应是怎么还验证不了的后来才明白OpenClaw启动时会主动检查WSL版本检测不到满足条件的2代环境就直接拒绝启动这是安全策略不是bug。遇到这个问题按这个顺序处理以管理员身份打开PowerShell运行wsl --status看输出里是否提示默认版本2如果没有说明你还在用旧版WSL甚至没装。运行wsl --update把WSL内核升级到最新版。这一步很关键很多验证失败其实就是内核太老。运行wsl --set-default-version 2把默认虚拟机版本设成2。运行wsl -l -v确认里边的发行版比如Ubuntu的版本列显示的是2如果是1用wsl --set-version Ubuntu 2转换这个过程可能要几分钟。全部搞定后再在PowerShell里跑wsl --status看到默认版本2回到OpenClaw重新启动这个报错就消失了。注意wsl --status和wsl -l -v是两个完全不同的命令前者看WSL整体的配置状态后者看具体装了哪些发行版以及各自版本。OpenClaw的报错提示里专门让你跑wsl --status因为它要检查的是全局默认配置不是某个发行版的版本号。2.2 Node.js与OpenClaw安装OpenClaw需要Node.js环境建议装LTS版本。直接去Node.js官网下载安装包Windows下就是一路下一步装完打开PowerShell验证node -v npm -v两个命令都有版本号输出就算成功。你要是之前装过旧版本建议卸干净再装新LTS省得后面出现各种莫名其妙的模块兼容问题。OpenClaw本身的安装有两种常见方式一种是用npm全局安装执行npm install -g openclaw另一种是用官方提供的一键安装脚本。不同版本命令可能略有差异装完后运行openclaw --version确认一下。我再强调一句很多报错都出在以为装好了但实际没装对上装完先跑版本命令这一步别跳过。首次使用建议跑一下openclaw init它会生成一个默认配置文件YAML格式。这个文件就是OpenClaw的总闸模型、技能、渠道都在里面配。2.3 算力从哪来只接API还是接Ollama我经常被人问OpenClaw是不是只能用API方式接算力不是。它支持两类模型接入方式一类是云厂商的API另一类是本地模型本地模型最常见的部署工具就是Ollama。如果走API你只需要在配置里填上base_url、api_key、model三个字段指向任意兼容OpenAI接口的服务即可非常省事。如果走Ollama先在本地装好Ollama然后拉模型ollama pull qwen2.5:14b拉完以后Ollama默认监听11434端口它同时提供一个/v1/chat/completions接口兼容OpenAI格式所以OpenClaw配置里指向http://localhost:11434就行模型名填你拉的那个。两种方案怎么选我的建议是日常对话、复杂推理任务用API模型聪明、速度快隐私敏感的数据整理、文本分类这类不追求创造力的任务丢给本地模型处理。很多人一上来就纠结必须全部本地化其实没必要混合用才是常态。考虑到飞书接入的场景往往是处理真实业务数据我更推荐API为主、本地为辅的组合。2.4 Windows Companion是什么要不要装如果你用的是Windows可能看到过OpenClaw Windows Companion这个组件。它的作用简单说就是给Agent一个操作Windows本地系统的手读剪贴板、模拟简单操作、管理本地文件之类的。对飞书接入来说它不是必需的因为飞书交互走的是网络API不依赖本地系统能力。但如果你想让Agent在飞书里帮你做一件需要操作电脑上某个软件才能完成的事那Companion就有用了。配置方式通常是下载Companion程序到Windows启动后它会生成一个本地连接地址或配对码把这段信息填到OpenClaw的配置里。注意Companion和OpenClaw最好在同一台机器或同一局域网内网络隔离会直接导致配对失败。我的建议是先不装把飞书链路跑通以后确实有需求了再补。3. 飞书开放平台创建你自己的机器人应用3.1 创建应用并开启机器人能力飞书侧的接入得先有个应用身份。打开飞书开放平台open.feishu.cn进开发者后台选择创建企业自建应用填上应用名称和图标创建完就进入应用详情页。这里要先理清一个概念飞书机器人分两种。一种是群里的自定义机器人只能通过Webhook向群内发消息不能收消息只能做单向通知另一种是应用机器人它是挂在应用下面的既能收用户消息也能主动发消息双向交互。我们要做的飞书Agent必须用后者——应用机器人。创建应用后在添加应用能力里找到机器人启用它。启用完你会在应用详情里看到机器人菜单点进去可以设置机器人的头像、名字。这个机器人就是用户能在飞书里搜索到、私聊或拉进群的那个人。3.2 权限配置哪些权限点必须开飞书应用默认所有API权限都是关闭的不配权限后面调接口只会报没有权限。这里整理一张最小权限表权限点作用是否必须im:message接收用户和群消息事件必须im:message:send_as_bot以机器人身份发送消息必须im:chat:readonly读取群基础信息群成员、群名称建议im:chat.member:readonly读取群成员列表按需bitable:app读写多维表格按需docs:doc操作云文档按需task:task创建和读取待办按需权限开好以后关键一步是发布版本。企业自建应用发布后需要管理员审核审核通过权限才真正生效。很多人的机器人明明配置了权限却还是报无权限十有八九是卡在这代码里开着权限但应用线上版本还是旧的。我建议直接在开发者后台创建版本时选择企业内发布审核通常很快个人测试环境也可以选启用沙箱模式先调试。3.3 事件订阅Webhook还是长连接这是整个接入里最容易让新手犯迷糊的地方。飞书把有人给机器人发了一条消息这件事封装成事件推送给你你有两种收事件的方式。第一种是Webhook模式也叫事件回调。你在开放平台配一个公网可达的URL飞书往这个URL上POST事件。本地开发机器没有公网地址要么自己有一台公网服务器或内网穿透工具把本地端口映射出去要么就折腾内网穿透。而且Webhook还有一个槛飞书要求你的服务必须在3秒内响应200否则算超时重试。本地冷启动慢非常容易触发。第二种是长连接模式也叫WebSocket模式。你的服务主动和飞书开放平台建立一个持久化的WebSocket连接事件通过连接直接推下来。不需要公网URL不需要内网穿透没有3秒超时问题。对绝大多数个人开发者和中小企业来说长连接都是最优解。我就是用的长连接省掉了公网服务器那一环。你在飞书开发者后台的事件订阅配置里选择使用长连接接收事件即可。OpenClaw侧只要支持WebSocket模式连上去连接一建立飞书后台状态栏就会显示服务在线。提示如果你的OpenClaw部署在服务器上且有固定公网IPWebhook模式也可以但第一次调试我还是建议用长连接。把能不能收到事件这个变量先排除掉后面排查问题会轻松很多。3.4 拿到四件关键凭证不管用哪种模式你都需要从飞书开发者后台拿到以下信息App ID应用唯一标识形如cli_开头。App Secret应用密钥调用API时用于换取tenant_access_token。Verification Token事件验证令牌校验事件来源。Encrypt Key加密密钥事件推送使用AES加密时解密用。App ID和App Secret在凭证与基础信息页面Verification Token和Encrypt Key在事件订阅页面Encrypt Key可以不启用但我建议启用加密多一层安全反正OpenClaw侧都支持自动解密。这四个值建议直接复制到一个临时文件里后面配OpenClaw要用。4. 核心对接让OpenClaw和飞书真正通信4.1 配置OpenClaw的飞书渠道OpenClaw这边的配置核心是在配置文件中启用飞书渠道并填入上一步拿到的凭证。不同版本配置文件格式可能略有差异但核心字段大差不差思路是一样的channels: feishu: enabled: true app_id: cli_xxxxxxxx app_secret: xxxxxxxxxxxxxxxx verification_token: xxxxxxxxxxxxxxxx encrypt_key: xxxxxxxxxxxxxxxx mode: websocket # websocket 或 webhook webhook_path: /feishu/event # 用 webhook 模式时填 group_at_only: true # 群里只响应 机器人的消息如果你用的OpenClaw版本里没有channels.feishu这个内置渠道段也别慌去技能市场找飞书适配的Skill或者用更通用的一招把飞书的事件订阅地址指向OpenClaw的通用Webhook入口再在OpenClaw里挂一个飞书消息处理器技能。核心逻辑都是一样OpenClaw收到飞书事件解析出消息文本交给大模型处理然后把回复发回飞书。配置完以后启动OpenClaw观察启动日志。如果看到类似Feishu channel connected或WebSocket connected的输出说明长连接建立成功飞书后台的事件订阅页面也会显示在线状态。这一步成功就说明链路通了三分之一。4.2 消息事件长什么样怎么解析在OpenClaw内部你无需太关心飞书事件的具体格式底层都已经帮你解析好了。但作为接入的人我建议你至少看懂最核心的事件结构否则遇到机器人收到消息但答非所问会很懵。飞书收到消息时推送的事件大致是这样的{ schema: 2.0, header: { event_type: im.message.receive_v1, event_id: evt_xxxxxxxx, app_id: cli_xxxxxxxx, token: xxxxxxxx }, event: { message: { message_id: om_xxxxxxxx, message_type: text, content: {\text\:\帮我查一下昨天的销售数据\}, chat_id: oc_xxxxxxxx }, sender: { sender_type: user, sender_id: {open_id: ou_xxxxxxxx} } } }你需要关注的就是几个字段event_type告诉你这是收到消息事件message.content里是消息正文注意它是JSON字符串需要解析一层message.chat_id是对话IDsender.sender_id.open_id是发送者ID。OpenClaw侧会把message.content解析好之后作为用户输入传给模型同时保留chat_id用于回复。4.3 私聊和群聊机器人的行为控制这是接入后最容易翻车的场景。机器人同时被私聊和拉进群如果你不区分场合它可能在群里把每条消息都回一遍所有人都难受。配置里那个group_at_only: true就是干这个的群聊中只处理有机器人的消息私聊中处理所有消息。群里用户机器人的时候事件里会带上mentions信息包含被的用户ID。OpenClaw的行为逻辑是这样的先判断是私聊还是群聊是群聊就检查有没有自己有才触发回复没有就直接忽略。如果你发现有人在群里了机器人但它没回优先检查两件事一是group_at_only是否被误设成false二是你的时候飞书是否成功把机器人识别进mention列表拉群时机器人必须在群里。4.4 主动发消息token的获取与缓存收消息只算一半发消息是另一半。OpenClaw向飞书发消息本质上就是调用飞书的消息API。第一步要换取一个tenant_access_tokencurl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id: cli_xxxxxxxx, app_secret: xxxxxxxx}响应里会有tenant_access_token和expire字段这个token有效期是7200秒也就是2小时。OpenClaw内部会自动帮你做缓存和续期你不需要每次发消息都重新换。但如果你自己在写调试脚本记住一定把token缓存起来2小时内复用别每次请求都换一次既慢又容易被限流。拿到token之后发一条文本消息长这样curl -s -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typeopen_id \ -H Authorization: Bearer t-xxxxxxxx \ -H Content-Type: application/json \ -d { receive_id: ou_xxxxxxxx, msg_type: text, content: {\text\:\你好我是OpenClaw机器人\} }receive_id_type可以是open_id、user_id、chat_id等对着不同标识类型。发到群里就用chat_id。这一步能通恭喜你双向通信已经彻底打通了。5. 进阶玩法表格、卡片与多维表格联动5.1 让机器人发送表格的几种姿势很多人搜飞书机器人发送表格其实真正想要的是让机器人发一个结构化的、看着像表格的消息。这里有三条路难度递增、效果也递增。最简单的是发富文本消息msg_type: post用文本列表的形式把信息列出来虽然不叫表格但阅读性尚可。中等方案是用交互卡片msg_type: interactive卡片的column_set组件能实现真正多列的效果配合表头行和内容行视觉上就是一个规整的表格。最高级的方案是让机器人直接创建一张多维表格或电子表格把数据写进去再发一个链接给用户。我推荐日常场景用交互卡片。原因很简单数据量不大时卡片一目了然且阅读体验最好数据量大了再引导用户点链接去看完整表格。这里给一个卡片表格的核心结构示例{ msg_type: interactive, card: { config: {wide_screen_mode: true}, header: { title: {tag: plain_text, content: 昨日销售汇总}, template: blue }, elements: [ { tag: column_set, flex_mode: none, background_style: grey, columns: [ { tag: column, width: weighted, weight: 1, elements: [{tag: plain_text, content: 区域}] }, { tag: column, width: weighted, weight: 1, elements: [{tag: plain_text, content: 销售额}] }, { tag: column, width: weighted, weight: 1, elements: [{tag: plain_text, content: 同比}] } ] } ] } }每一行数据再复制一个column_set放进去就能形成一个多行多列的表格卡片。OpenClaw的Skill可以把Markdown表格自动转换成这种卡片结构你在飞书里看到的体验就是Agent直接把一张表拍在你脸上。5.2 多维表格读写让Agent直接操作业务数据多维表格Base是飞书最大的杀手锏。它的本质是一个带API的在线数据库你可以让OpenClaw直接读写里面的记录。记录API的路径是GET/POST /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records其中app_token是某个多维表格文档的唯一标识就在文档URL里table_id是文档内某一个数据表的标识。OpenClaw通过Skill封装这些API之后你在飞书里跟它说把A组昨天没有跟进的客户都标成待跟进它就会去读取记录、筛选、更新状态字段全程你不用打开表格。这里要特别提醒权限操作多维表格需要提前在应用权限里开bitable:app并且发布版本生效。否则API会返回一个很常见的权限不足错误码。还有一点多维表格API的写操作是按记录逐条提交的批量更新时注意频率别一次性并发几百条容易被限流最好分批处理。至于很多人问的多维表格上下合并问题其实在Agent视角里合并就是三步查询出需要合并的行、按目标字段去重、把保留行的值更新到合并结果。你不用指望API给你一个一键合并按钮让Agent帮你把逻辑串起来才是它存在的意义。5.3 Skill扩展云文档抓取与网站嵌入OpenClaw的Skill机制是整个体系里最值得花时间研究的。一个Skill就是一个可复用的工具包飞书场景下建议优先找这几个多维表格操作、云文档读取、待办管理、消息卡片构造。Skill市场找得到现成的找不到也可以自己写本质就是给Agent描述清楚这个工具能干什么、参数是什么、怎么调用。被问得很多的另一个需求是怎么把飞书云文档内容嵌到自己网站上。正经做法有两种如果你的文档是公开分享的直接用iframe嵌入飞书文档是支持这种展示方式的iframe src你的飞书文档公开链接 width100% height600 frameborder0/iframe如果文档不想公开或者要更灵活的展示就换一种思路让OpenClaw通过云文档API把内容读取出来转成Markdown或HTML你再嵌进自己的页面。这本质上是内容搬运格式化只要API权限到位Agent能帮你定时同步甚至能做到文档更新、网站自动更新。这种Agent作为内容管道的玩法比手工复制粘贴优雅太多。6. 常见问题排查与避坑实录6.1 高频问题速查表问题现象最可能的原因解决方案OpenClaw启动提示无法安全验证WSL2环境WSL2默认版本未设置或内核过旧PowerShell执行wsl --update和wsl --set-default-version 2再跑wsl --status确认飞书后台显示服务在线但消息触发不回复权限未发布或group_at_only配置问题检查应用版本是否已发布群聊确认是否真的到了机器人发消息报权限错误im:message:send_as_bot权限未开或未生效开发者后台加权限重新发布版本事件推送一直超时重试Webhook响应超过3秒换长连接模式或在回调里先立刻返回200再异步处理收到的消息内容是转义后的JSONmessage.content本身就是JSON字符串解析一层JSON.parse再使用请求API报App 不存在或未启用App Secret填错或应用被平台停用核对凭证在开发者后台检查应用状态飞书客户端下载后连不上网络系统防火墙或安全软件拦截进程检查防火墙放行飞书重启客户端和网络不要随意修改系统DNS机器人回复速度很慢模型响应慢或API限流先确认大模型接口的延迟必要时换更快的小模型处理简单问题6.2 WSL2验证失败的处理全流程这个坑我值得专门展开讲因为搜索openclaw无法安全验证wsl2环境的人特别多。它的本质是OpenClaw在启动时做了一项安全预检查判断当前Windows环境是否符合运行要求。OpenClaw内部会调用wsl --status来读取配置如果解析到默认版本不是2或者WSL内核组件不完整就会拒绝启动。实战中最有效的修复路径是这样的先跑wsl --status看输出——如果提示你未安装用于Linux的Windows子系统内核直接wsl --update装内核装完重启终端如果显示默认版本1执行wsl --set-default-version 2如果你发现根本没有安装任何发行版用wsl --install -d Ubuntu装一个。全部完成后再跑wsl -l -v确认Ubuntu那行Version列是2至此再启动OpenClaw问题就消失了。这里有个容易被忽略的细节修改完WSL配置后一定要重启你的PowerShell或Terminal窗口让环境变量重新加载。很多人改完直接在旧窗口里跑以为没生效白白多试了半天。6.3 飞书开放平台异常的几种真面目报飞书开放平台异常时先别急着骂平台九成是应用配置自身的问题。我排查时习惯按这个顺序检查App ID和App Secret是否复制对了、应用是否因为长期无活动被停用、权限是否发布到了线上版本、是否错用了沙箱环境的凭证在正式环境。沙箱模式的App ID和正式模式的凭证是两套混用就会出现一个现象飞书后台看一切正常调API却各种报错。另一个隐蔽问题是企业自建应用的管理员审核状态。如果你的应用版本停留在待审核所有权限都是纸面上的。我建议在开发者后台把应用设为启用并确认版本状态显示已发布。企业内有管理员权限的话直接自己审核通过即可。6.4 消息丢失与事件推送超时长连接模式下一般不会丢消息但OpenClaw如果处理一条消息耗时过长飞书那侧会认为处理超时并触发重试。如果消息处理是不可幂等的比如插入了一条重复记录就需要你的事件处理器有去重机制按event_id做缓存判断重复事件直接忽略。OpenClaw在处理飞书消息时应该默认支持这个逻辑但你自己写Skill时千万记得这一点。Webhook模式下消息丢失更常见原因是回调地址不稳定或响应超时。飞书会对失败事件重试多次但如果你本地服务断断续续可能就丢了不少。这是我从一开始就坚持用长连接的另一个原因连接状态一断你能立刻从日志里看到不用等用户说没收到才后知后觉。6.5 调试三板斧接入过程中我给你一个自己一直在用的黄金排查顺序。第一看OpenClaw的日志报错信息里九成带着具体原因第二去飞书开发者后台的事件订阅页面看事件接收记录那里能看到推送历史、发送状态和错误详情第三用curl手动调一遍飞书API能直接复现问题是token过期、参数不对还是权限没通。手动调试时记得直接在PowerShell或终端里跑别写在代码里跑。因为代码会把异常吞掉而你手动跑curl能看到飞书返回的完整错误码和错误信息。飞书的错误码文档很全绝大多数问题对着错误码就能定位。最后再分享一个我在实际使用中的体会先跑通最小闭环再谈优化。很多人一上来就想着接多维表格、发复杂卡片、搞定时推送结果基础的消息收发都没验证好出了问题根本不知道是OpenClaw的问题、飞书的问题还是网络的问题。我自己的路径是先私聊机器人说一句话确认能收到回复再拉个群确认能触发然后才去加权限、接多维表格、写卡片模板。每一步都是一小块验证全部绿了才往后走。这套思路对任何接入类项目都适用也希望你少踩几个我踩过的坑。
