先说说我把OpenClaw接到飞书这件事。当时群里有同事在晒各种AI助手自动回消息我第一反应是这些多半要依赖云端平台数据全都过一遍第三方多少有点不踏实。后来看到OpenClaw这个开源项目本地就能跑还能通过“渠道”把同一套Agent能力接到飞书、钉钉、Discord这些IM上我就决定在Windows开发机上先搭一套试试。OpenClaw本质上是一个开源的AI Agent运行时负责调度模型、执行技能、管理多轮对话而飞书机器人则是它的“前台窗口”。整条链路跑通之后你在飞书里发一句话消息通过飞书开放平台来到本地OpenClaw服务服务调用模型推理、触发技能再把结果推回飞书会话里整个过程都是实时双向的。这篇文章适合三类人一是想在团队内部快速验证AI机器人、又不想把代码和数据送出去的开发者二是刚接触智能体框架、被各种部署概念绕晕的新手三是已经在用OpenClaw但卡在飞书接入细节上的折腾党。我会把Windows环境下从零部署OpenClaw、创建飞书自建应用、配置事件订阅、联调对话、发送表格消息这一整条链路都过一遍还会把WSL2环境校验、长连接回调、消息收不到这类高频坑单独拎出来讲。文章里的命令和配置都是我在实际环境里跑过的合理操作参数也给了具体的例子照着抄基本能成。1. 开工前先搞明白OpenClaw和飞书机器人怎么配合1.1 OpenClaw到底是个什么东西OpenClaw是一个开源的AI Agent框架核心思路是把“大脑”和“手脚”分开。大脑是模型可以接OpenAI、Claude这类云模型也可以接Ollama拉的本地模型手脚是环境能力包括执行命令、读写文件、调用API、操作浏览器等。而它和普通脚本最大的区别在于它有一套完整的会话上下文管理和技能调度机制用户说一句话框架判断需要调用哪些能力、按什么顺序执行、中间出错怎么恢复。打个比方普通脚本像是自动售货机你投币它就出饮料流程是固定的OpenClaw更像是一个柜台后的店员你跟他说“帮我整理一下这周的报销单并把汇总发到群里”他会自己规划步骤、调工具、最后给你交付结果。这套设计决定了它特别适合当IM机器人——因为在飞书里用户的需求永远是自然语言表述的机器人必须能理解意图并拆解任务。1.2 为什么要走飞书而不是直接命令行有人可能会问OpenClaw本地跑得好好的直接在终端里对话不就行了为什么非要接飞书我实际用下来的体会是命令行适合开发者验证飞书适合让机器人真正进入工作流。飞书机器人可以进群、可以被、可以发消息卡片和表格还能结合审批流、日程、云文档这些企业场景。比如你在通勤路上用手机给机器人发一条“下午三点的会议帮我拟一份议题提纲”它就能调本地服务把提纲算好发到群里这比坐在电脑前开终端方便太多。从部署架构上看飞书和OpenClaw之间是解耦的。飞书负责消息的收发和展示OpenClaw负责逻辑和工具执行两者通过HTTPS回调或者长连接通信。这样设计的好处是未来你哪怕把OpenClaw从Windows搬到云服务器或者换掉模型后端飞书侧根本不用动用户也无感知。1.3 整体链路与消息流把整条消息流拆开看大概是下面这个顺序用户在飞书里给机器人发消息或者群里机器人。飞书开放平台根据你配置的事件订阅方式把消息事件推给OpenClaw。OpenClaw收到事件后进入对话管理模块带上历史上下文一起发给模型。模型返回文本或触发技能调用比如查数据库、生成表格。OpenClaw把最终结果包装成飞书消息格式发回会话。这里面有两个关键选择。第一飞书的推送方式是长连接还是Webhook回调。本地开发强烈建议用长连接因为不需要公网地址也不用折腾内网穿透Webhook回调适合机器人部署在云端服务器时使用。第二机器人的消息内容是纯文本还是消息卡片。纯文本简单直接但表格、按钮、富文本这些复杂内容必须用卡片或特殊消息类型。这两点后面都会详细展开。2. 环境准备Windows下把OpenClaw跑起来2.1 先解决WSL2环境的坑如果你在Windows上安装或启动OpenClaw时遇到类似“无法安全验证WSL2环境请在PowerShell中运行wsl --status解决报告的问题”的报错不要慌这是OpenClaw的运行时依赖Linux环境导致的。OpenClaw的很多工具执行、文件操作底层用的是Linux指令集所以在Windows上官方推荐跑在WSL2里面启动时会主动检查WSL2内核和发行版状态。一旦检查不通过它宁可拦下来也不让你带病启动避免后续出现各种诡异的行为。先打开PowerShell建议以管理员身份依次执行这几步wsl --status wsl --update wsl --set-default-version 2wsl --status会告诉你当前默认版本是WSL 1还是WSL 2以及内核是否正常。如果显示没有安装内核或者版本是1就执行wsl --update更新内核再用wsl --set-default-version 2把默认版本切到2。这里有个细节WSL 1和WSL 2对OpenClaw来说差别很大WSL 1没有完整的Linux内核某些系统调用会出问题所以必须确保是WSL 2。检查完毕之后安装一个发行版。我建议装Ubuntu 22.04 LTS直接在Microsoft Store搜“Ubuntu 22.04.3 LTS”安装即可。装完以后打开Ubuntu终端设置一个用户名密码然后确认Linux侧的基础环境wsl -l -v输出里应该看到你的Ubuntu发行版并且VERSION列是2。到这里WSL2环境才算真正就绪。还有一个容易被忽略的点如果电脑的BIOS里虚拟化没开启WSL2会直接起不来报错信息往往是“请启用虚拟机平台”。这种问题只能进BIOS把Intel VT-x或者AMD SVM打开Windows功能里还要勾选“虚拟机平台”和“适用于Linux的Windows子系统”。2.2 安装Node.js版本选择与验证OpenClaw的CLI是Node.js写的所以要先把Node.js环境装好。这里我吃过亏一开始图省事装了最新版Node结果某个依赖包不兼容折腾了半天。后来规规矩矩用LTS版本一次过。建议直接到Node.js官网下载LTS版本的Windows安装包现在LTS版本一般是20.x或者22.x具体以官网为准。安装的时候有一个选项容易被忽略“Add to PATH”。如果安装时没勾上后面在命令行里执行node -v会提示找不到命令。装完之后重新开一个终端窗口验证一下node -v npm -v两条命令能正常输出版本号说明Node和npm都就绪了。如果node -v有输出但npm -v没有大概率是PATH环境变量里npm的路径没配好去“系统环境变量-Path”里检查一下npm的安装目录是否在列表里。另外国内网络环境下npm默认源经常很慢安装OpenClaw这种依赖很多的包容易卡在sill idealTree这种阶段。我的做法是把npm源切到国内镜像执行完再切回来或者保持镜像源都行不影响使用npm config set registry https://registry.npmmirror.com切完之后npm config get registry确认一下输出的是镜像地址。这一步不是必选项但能显著减少安装时间。2.3 用npm安装OpenClaw CLI环境就绪之后安装OpenClaw本体。OpenClaw提供官方CLI工具通过npm全局安装npm install -g openclaw安装过程会输出一长串依赖包信息耐心等它跑完。如果中途报错十有八九是网络问题或者权限问题。Windows上如果是权限问题把PowerShell以管理员身份打开再装一次如果是网络问题切换镜像源后重新装。装完验证一下openclaw --version能输出版本号就说明CLI安装成功。接下来初始化一个工作目录一般叫“companion”或者“agent”之类的名字看个人习惯openclaw init mybot cd mybotopenclaw init会在当前目录生成一套标准的项目结构包括配置文件、技能目录、日志目录等。进入项目目录后可以执行openclaw run先跑一个默认实例确认本地Agent能正常对话再往下接飞书。这里提醒一句第一次运行的时候OpenClaw会引导你配置模型后端也就是填API Key或者选择本地模型服务。如果还没有云模型的Key可以先跳过等接了Ollama之后再补。2.4 Windows Companion什么时候需要它热搜词里很多人问“OpenClaw Windows Companion怎么配置”这里专门说一下。OpenClaw本身跑在WSL2/Linux环境里但有些能力天然属于Windows侧比如操作Windows桌面应用、读写Windows磁盘上的文件、调用Windows上的浏览器。这些能力是通过Companion组件提供的它本质上是一个运行在Windows侧的辅助服务和WSL2里的OpenClaw主进程通过本地网络通信。安装OpenClaw时Companion组件一般会一起装上。启动方式是openclaw companion启动后终端会显示一个配对码或者链接在OpenClaw主进程的配置里把搭档地址和配对码填进去两边就能握手。配置参数通常长这样{ companion: { enabled: true, host: 127.0.0.1, port: 3456 } }如果你的场景只是把OpenClaw作为飞书机器人让它回消息、查资料、生成表格我建议先不要开Companion少一个变量排查问题也简单。等核心链路通了再逐步增加桌面自动化能力。我的经验是功能边界越清晰调试越爽快。3. 飞书侧从零创建一个能收发消息的机器人3.1 创建企业自建应用飞书机器人的载体是“应用”。打开飞书开放平台用企业管理员账号登录进入开发者后台点击“创建企业自建应用”。应用名称建议取一个容易识别的比如“本地助理”描述里写清楚用途。创建之后进入应用详情页第一件事是启用“机器人”能力在“应用能力-机器人”选项卡里点击启用。这里有个容易掉坑的地方创建出来的应用默认是“测试中”状态只有应用添加的管理员和开发者能看到。你在调试阶段可以先用这个状态跑通流程但要让团队其他人也能用必须创建一个版本并提交发布。发布流程是在“版本管理与发布”里创建版本填写版本号、更新说明然后提交审核。企业内部应用一般审核很快甚至管理员可以直接通过。创建完应用后记下两个关键凭证App ID和App Secret。这两个值在“凭证与基础信息”页面可以看到。App Secret比较敏感飞书支持重置万一泄露了就重置一次。这两个凭证后面配置OpenClaw时要用。3.2 配置权限与安全机器人要收消息、发消息必须申请对应的权限。在“权限管理”页面搜索并开通以下常用权限权限名称权限CODE用途读取用户发给机器人的单聊消息im:message接收单聊消息获取与发送单聊、群组消息im:message:send_as_bot机器人发消息获取群组信息im:chat:readonly读取群聊基础信息读取群消息im:message.group_msg接收群里机器人的消息权限开通之后如果要发布版本这些权限会跟随版本一起提交审核。注意只是“开通”还不够必须发布版本后权限才真正生效。我在调试时遇到过明明权限都开了机器人还是收不到消息折腾半天发现是旧版本还在生效新权限没发出去。安全设置方面飞书开放平台提供事件订阅的加密配置。如果你用的是长连接模式建议开启“加密”设置一个Encrypt Key所有推送的事件内容都会加密OpenClaw侧配置相同的Key才能解密。另外还有Verification Token用于校验事件来源合法性。这两个值不用背配置OpenClaw时从飞书后台复制粘贴即可。3.3 事件订阅选长连接还是Webhook这是飞书机器人接入里最关键的一个选择。事件订阅负责把“用户给机器人发了消息”这个事件推送到你的服务端。飞书支持两种方式长连接飞书服务器主动维持一条与本地服务的WebSocket连接事件实时通过这条连接推送过来。优势是本地开发时不需要公网IP不需要内网穿透也不用在服务器上配SSL证书。Webhook回调你把一个公网HTTPS地址填到飞书后台飞书把事件POST到这个地址。优势是适合生产环境部署但本地开发必须先解决公网可达问题。OpenClaw接入飞书时两种都支持。我的建议非常明确本地调试阶段用长连接OpenClaw启动后会主动连上飞书的网关飞书后台只需要配置好事件类型不需要填回调地址。长连接模式的好处是断线会自动重连省去一堆网络问题。等之后把OpenClaw迁到云服务器上再切到Webhook模式也不迟。在飞书后台配置事件订阅时选择“长连接”作为接收方式然后添加事件。机器人收消息需要添加这两个事件im.message.receive_v1接收消息事件单聊和群里机器人都走这个。im.chat.member.bot.added_v1机器人被拉入群的事件可选但建议加上。添加完事件后飞书会要求设置Encrypt Key和Verification Token。可以顺手生成一个Encrypt Key保存好。到这里飞书侧的前置配置就基本结束了。4. OpenClaw接入飞书配置与联调4.1 在OpenClaw中启用飞书渠道OpenClaw把接入的IM平台抽象成“渠道”。配置飞书渠道有两种方式一种是编辑项目根目录的配置文件另一种是设置环境变量。我推荐两种结合用敏感信息用环境变量非敏感结构配置放文件。先看配置文件方式。在OpenClaw项目目录下找到配置文件一般是openclaw.json或者config.yaml具体要看init生成的类型在渠道配置段加入飞书{ channels: { feishu: { enabled: true, appId: your_app_id, appSecret: your_app_secret, encryptKey: your_encrypt_key, verificationToken: your_verification_token, mode: websocket } } }其中appId和appSecret来自飞书后台“凭证与基础信息”encryptKey和verificationToken来自“事件订阅”页面mode设置为websocket表示长连接模式。如果你不想把密钥写进文件可以改用环境变量。在启动OpenClaw的终端里先导出变量再启动服务export FEISHU_APP_IDyour_app_id export FEISHU_APP_SECRETyour_app_secret export FEISHU_ENCRYPT_KEYyour_encrypt_key export FEISHU_VERIFICATION_TOKENyour_verification_token openclaw run环境变量的优先级一般高于配置文件里的同名参数所以如果发现文件里配了但没生效检查一下是不是环境变量把配置覆盖了。我踩过的坑是改了配置文件但没重启服务OpenClaw的配置是启动时加载的运行中修改不会热更新。4.2 启动服务并完成第一次对话配置完成之后在项目目录下启动OpenClawopenclaw run日志里如果能看到类似“feishu channel connected”或者“websocket connected”的输出说明长连接已经建立成功。这个时候打开飞书找到你的机器人应用给它发一条“你好”正常情况下会在几秒内收到回复。如果第一次对话就成功恭喜你已经完成了OpenClaw接入飞书的最核心链路。如果没收到回复先别慌按下面的顺序排查先看OpenClaw的终端日志有没有收到消息事件的打印再看飞书后台的事件订阅有没有显示“推送成功”最后看应用是否处于“可用”状态有没有发布成功。大多数第一次接入失败都逃不过这三个环节。这里有个细节单聊测试时机器人回复你是没问题的但如果你想在群里测试必须先把机器人拉到群里并且用户要在群里它。飞书对于群里消息的触发是有要求的不机器人机器人是收不到消息的。这个行为不是OpenClaw的限制是飞书平台的规则。4.3 进阶让机器人发送表格热搜词里有“飞书机器人发送表格”这个需求在实际工作中非常常见。设想一个场景你跟机器人说“帮我把这三个月的销售数据整理成表格”它通过技能生成了结构化的数据现在要把它以表格形式发到飞书里。这里有两种做法。做法一发送Markdown表格。如果你的OpenClaw技能输出的是Markdown并且飞书渠道支持Markdown渲染部分消息类型支持可以把表格直接放进消息文本里| 月份 | 销售额 | 环比 | | --- | --- | --- | | 1月 | 100万 | - | | 2月 | 120万 | 20% | | 3月 | 150万 | 25% |做法二用飞书富文本post消息。飞书的消息接口支持post类型里面可以定义多行文本和链接但严格来说它不支持原生表格结构只能通过文本排版把表格“画”出来。如果你的数据量不大用等宽字体对齐效果也还行。OpenClaw如果内置了飞书消息卡片生成能力还可以用interactive卡片在卡片里嵌入更丰富的布局。我的实际建议是数据量小、追求简单用Markdown表格数据量大、需要整齐对齐优先让技能生成CSV或Excel文件然后通过飞书机器人上传文件发送。飞书机器人可以调用上传文件接口把生成的.csv或.xlsx发送到会话里用户点击即可下载。这个方案的体验最好实现也不复杂。4.4 把机器人接入群聊与触发单聊跑通之后把机器人拉进工作群里才是真正的日常使用形态。操作步骤是打开飞书群聊设置添加机器人选择你创建的应用。机器人进群后默认不会响应所有消息必须被才行。OpenClaw对触发的处理是自动的飞书推送的消息事件里带有“是否机器人”的标记框架解析后只处理了机器人的消息。如果群里有人发普通消息就算内容里包含了“帮我查一下”OpenClaw也不会响应这是正确的行为避免机器人在群里过度打扰。不过我遇到过另一个问题群里好几个人同时机器人OpenClaw默认是串行处理的消息会排队。如果群里有大量消息风暴回复延迟会很严重。解决方案是在OpenClaw的配置里开启并发处理或者限制每个用户的消息频率。具体参数根据项目版本不同有差异但一般都有类似maxConcurrentConversations或者perUserRateLimit的配置项。5. 常见问题与排查技巧实录5.1 “无法安全验证WSL2环境”怎么破这是Windows用户最常见的拦路虎报错原文通常类似于“openclaw无法安全验证WSL2环境请在PowerShell中运行wsl --status解决报告的问题”。这个问题的根源就是OpenClaw启动时执行了WSL健康检查而系统返回了异常状态。我总结了一套从快到慢的排查顺序。第一步在PowerShell里执行wsl --status看输出里有没有“默认版本2”。如果显示默认版本是1执行wsl --set-default-version 2。如果提示“请启用虚拟机平台”去“控制面板-程序和功能-启用或关闭Windows功能”勾选“虚拟机平台”和“适用于Linux的Windows子系统”然后重启电脑。第二步确认发行版本身正常wsl -l -v如果发行版列表为空说明你只装了WSL内核但没装任何Linux发行版去Microsoft Store安装Ubuntu。如果发行版存在但状态是Stopped先执行wsl --set-version 发行版名 2把它切换到WSL2。第三步重启WSL服务。这一步很多人不知道当WSL状态异常时执行以下命令可以彻底重启wsl --shutdown然后重新打开Ubuntu终端。整套流程走完再启动OpenClaw这个报错基本就消失了。我的经验是90%的“无法安全验证WSL2环境”问题出在WSL内核版本太旧执行wsl --update后重启一次就能解决。5.2 收不到消息事件订阅与权限的坑收不到消息是接入飞书后最让人抓狂的问题。表面的现象是飞书里给机器人发了消息OpenClaw日志里什么都没有。这时按从外到内的顺序排查。先看飞书后台“事件订阅”页面。如果用的是长连接这里会显示“连接状态在线/离线”。如果显示离线说明OpenClaw和飞书网关之间的长连接断了检查OpenClaw进程是否还活着、日志里有没有报错、飞书后台的Encrypt Key是否和配置一致。如果连接状态在线但收不到消息看“开发配置-事件订阅”里有没有添加im.message.receive_v1事件。很多人在这一步漏掉了事件订阅光配了权限没订阅事件机器人自然收不到消息。这里补一个要点权限和事件要同时满足。权限控制的是机器人能不能读写消息事件订阅控制的是飞书要不要把消息推给你两者缺一不可。最后看应用版本。如果应用没有发布或者发布的是旧版本新加的权限和事件根本不会生效。去“版本管理与发布”里确认最新版本状态是“已发布”。发布之后等一两分钟再测试飞书配置变更有时会有短暂的生效延迟。5.3 消息乱码与加密配置错误如果你收到的消息是一串乱码或者OpenClaw报“解密失败”之类的错大概率是Encrypt Key配置不一致。飞书的事件订阅如果开启了加密推送的每个事件内容都是密文OpenClaw需要用同一个Key解密。这里的经典错误是飞书后台重新生成了Encrypt Key但OpenClaw配置文件里还是旧值。或者反过来配置文件里填了Verification Token但飞书后台加密开关没开导致两边握手协议不匹配。还有一个容易忽略的细节Encrypt Key在飞书后台是“查看”还是“重新生成”要搞清楚。有些后台页面只显示遮罩后的Key你复制的是密文展示值而不是真实值。解决方法是点击“查看”获取明文再复制。Verification Token同理。我的习惯是配置完成后在OpenClaw启动日志里确认一行“feishu channel verified”看到这行再去做发消息测试。5.4 服务常驻与开机自启本地开发时可以手动在终端里跑openclaw run但真正想让它长期提供服务就得考虑进程守护。Windows上我推荐两种方式。方式一用pm2。pm2是Node生态的进程管理器可以守护OpenClaw进程崩溃自动重启还能查看日志。安装和启动npm install -g pm2 pm2 start openclaw --name openclaw-bot -- run pm2 save pm2 startuppm2 startup会生成一个开机自启脚本Windows上配合“启动文件夹”或者任务计划程序来执行。这个方案的优点是日志管理方便pm2 logs openclaw-bot直接看输出。方式二用Windows任务计划程序。创建一个基本任务触发器选“计算机启动时”操作选“启动程序”程序填powershell.exe参数填启动OpenClaw的命令。这个方案简单直接但没有崩溃重启能力进程死了不会自动拉起。我个人在Windows上用的是pm2在云服务器上则直接用systemd。不同平台的守护方案不一样但核心目标一致让OpenClaw在后台稳定跑别让飞书那边断连。6. 扩展玩法Skill与本地模型接入6.1 Skill让机器人掌握自定义能力OpenClaw的“技能”机制是它区别于普通聊天机器人的关键。一个Skill可以理解为封装好的一个能力单元包含触发条件、执行逻辑、返回格式。你可以给机器人加一个“查询天气”技能它就能在对话中调用天气API加一个“汇总日报”技能它就能定时把工作群里的消息汇总成文档。在OpenClaw项目目录下一般有个skills目录每个子目录就是一个技能。技能的典型结构包括一个描述文件和一个执行脚本。开发技能时可以先用简单的方式写一个脚本读取输入参数把固定的逻辑跑一遍返回结果。框架会在对话中根据用户请求自动匹配技能并把技能输出拼进模型回复里。写技能时要注意一点技能返回的内容最好是结构化的比如JSON。模型拿到结构化数据再根据用户的语言习惯组织成自然语言回复效果远好于让技能返回一大段已经排好版的文本。我在做表格发送功能时技能返回的是JSON数组然后由渠道层负责把数组渲染成Markdown表格逻辑清晰多了。6.2 本地模型Ollama不烧API也能跑热搜词里有“ollama部署openclaw”说明很多人希望完全本地化运行不依赖云API。OpenClaw支持通过Ollama接入本地模型。先在WSL2里安装Ollamacurl -fsSL https://ollama.com/install.sh | sh然后拉取一个合适的模型比如通义千问系列ollama pull qwen2.5:7b ollama serveOllama默认监听127.0.0.1:11434。OpenClaw配置模型后端时选择Ollama填上地址和模型名{ model: { provider: ollama, model: qwen2.5:7b, baseUrl: http://127.0.0.1:11434 } }本地模型的好处是数据不出门、离线可用、没有API费用但推理速度和质量跟云模型比还是有差距。小模型跑复杂任务容易“一本正经地胡说八道”技能调度也会变迟钝。我的建议是聊天、问答、简单信息整理用本地模型涉及技能调用、多步骤任务时切到云模型。OpenClaw一般支持按场景配置多个模型正好利用这个能力做分流。6.3 手机端与多端访问的补充有人问“怎么在手机上装OpenClaw”我的看法是把OpenClaw装手机上不是重点重点是通过飞书随时随地访问机器人。手机端装OpenClaw要用Termux这类终端模拟器在Android上跑Linux环境过程繁琐而且性能受限实际意义不大。更好的架构是OpenClaw跑在你的一台常开设备开发机、NAS、云服务器上手机只装飞书客户端。这样你在地铁上用手机发消息机器人照样能响应。移动端要解决的从来不是“把Agent装进口袋”而是“让Agent随时在线”。如果你确实想在安卓手机上实验在Termux里安装Node.js后同样可以执行npm install -g openclaw但后续配置和权限适配会比较折腾而且手机息屏后进程可能被系统杀掉。长期使用不建议这个方案。我自己在把OpenClaw接入飞书之后最大的改变不是省了多少操作而是重新理解了“机器人”的边界终端里的Agent是我一个人的工具接上飞书之后它变成了团队协作的一部分。现在团队里有人需要跑个临时数据统计直接在群里机器人不用再找我开电脑跑脚本。文章里所有命令和配置都基于我本地环境的实际操作你照着做大概率一遍通如果卡在某个环境细节上回到第5章对着排查表逐项过。最后再分享一个小经验调试阶段尽量保持最小配置先让“飞书消息进来-模型回复-消息回去”这条最短链路跑通再逐步加技能、加本地模型、加Companion。链路越短出问题时定位越快这个原则适用于所有接入类项目。