事情得从上周说起。OpenClaw 已经在我 Windows 机器上跑了好几天命令行里问它问题、让它整理资料都挺顺手但每次都得切回终端窗口确实憋屈——白天在工位还好一离开电脑就彻底断了。后来我琢磨着给它接个飞书机器人让它住进飞书群同事一下就能用手机上也随时能问文件直接拖进会话里让它处理。想法很好实际折腾了一整天踩了一堆坑从 Windows 环境部署、飞书开放平台后台配置、事件订阅、消息收发到本地 Ollama 模型接入、手机 Termux 上跑全捋了一遍。这篇教程就是按我跑通的路径写的照着做别跳步骤基本能一次成功。1. 先搞清楚一件事OpenClaw 和飞书机器人之间到底怎么通信1.1 整体架构其实只有三层很多人一上来就急着装软件结果装完发现机器人和 OpenClaw 各说各话根本连不上。原因很简单你还没搞明白这三个角色各干什么。飞书机器人本质是飞书开放平台上创建的一个应用。它不是独立程序你的消息发到它那里它只是把消息转发给一个后台服务。OpenClaw真正干活的 Agent。它收到消息后调用模型做推理、调用工具执行操作再把结果吐给机器人去展示。模型OpenClaw 不负责思考和生成内容它只是一个调度器。你既可以用云厂商的 API 模型也可以用本地 Ollama 跑的模型这部分后面会专门说。用大白话讲飞书机器人是前台接待OpenClaw 是办公室里的执行人模型是执行人的脑子。前台接到客户问题转给执行人执行人想清楚再让前台回复。1.2 事件订阅选长连接还是 webhook这是新手最容易卡住的地方。飞书机器人接收消息有两种方式一种是你在开放平台后台填一个公网回调地址飞书把消息 POST 到这个地址上这叫 webhook 模式另一种是机器人主动和飞书服务器建立一条长连接WebSocket飞书有消息直接推过来这叫长连接模式。我的建议是个人开发、公司内网环境优先选长连接。原因很直接——webhook 模式要求你的 OpenClaw 进程能被公网访问到家里宽带没有公网 IP 的话还得搞内网穿透那一套既麻烦又不稳定。长连接模式是机器人主动往外连电脑只要能正常上网就行不需要任何公网端口。飞书开放平台在创建应用时也支持选择使用长连接接收事件非常省事。1.3 权限和安全边界飞书机器人不是开了就能随便收发消息的。你在后台必须给应用开权限常见的有im:message发送消息、im:message.p2p_msg:readonly读取单聊消息、im:message.group_at_msg:readonly读取群聊中 机器人的消息。这些权限不开后面消息要么收不到要么发不出去而且飞书报错提示往往很模糊容易让你误以为是代码问题。安全方面要注意一点App Secret和Encrypt Key等同于是机器人身份的钥匙谁拿到谁就能冒充你的机器人发消息。配置进 OpenClaw 的配置文件后这个文件不要提交到 Git 仓库也不要截图发群里。我见过不止一个人把 Secret 贴在飞书群里问为啥报错然后整组人都能用他的机器人发消息场面一度非常尴尬。2. 环境准备Node.js、WSL2 和那个报错的真正解法2.1 Node.js 版本别乱装OpenClaw 的核心跑在 Node.js 上这一步最不起眼但也最容易埋雷。去 Node.js 官网下载 LTS 版本就行我装的是 20.x实测很稳。装完之后在 PowerShell 里验证node -v npm -v如果你机器上原来装过旧版 Node建议先卸干净再装新的不然可能出现 npm 全局包路径混乱的问题。另外不要图省事直接装最新 Current 版有些依赖对最新版支持不及时装 OpenClaw 的时候容易编译报错。2.2 无法安全验证 WSL2 环境这个报错我帮你们趟过了很多网上的 OpenClaw 教程都要求先在 Windows 上配好 WSL2然后跑wsl --status检查环境。我最初就是在这里卡死的报错信息写得很吓人——OpenClaw 提示无法安全验证 SL2 环境让我在 PowerShell 里运行wsl --status。实际上这个问题 90% 不是 OpenClaw 的问题而是你的 WSL 压根没初始化好。排查步骤很简单wsl --status如果提示没有已安装的分发版或者版本是 WSL1那就需要升级wsl --update wsl --set-default-version 2然后安装一个分发版wsl --install -d Ubuntu-22.04装完之后重启一次终端再跑wsl --status看到默认版本2基本就稳了。这里分享一个实操心得OpenClaw 在 Windows 上检测 WSL2主要目的其实是确认它能调用 WSL 内部的一些命令工具。如果你只是想让飞书机器人跑基本对话不涉及文件系统跨 WSL 操作这个警告有时候不影响使用但保险起见还是配好因为后面一些 Skill 会依赖它。2.3 Ollama 要不要提前装如果你打算用本地模型这一步建议先装 Ollama。官网下载 Windows 版安装包装完它会在后台自动跑服务默认端口11434。验证方式ollama list能列出模型列表就说明服务正常。先拉一个模型备用我常用的是qwen2.5:7b尺寸和效果比较均衡ollama pull qwen2.5:7b如果你机器配置一般可以先装qwen2.5:3b跑飞书群里那些日常问答完全够用。这一步先装好第五章节配置的时候能省不少时间。3. 在 Windows 上安装并初始化 OpenClaw3.1 下载安装包还是用 npmOpenClaw 的安装方式有两种一种是从官方仓库的 releases 页面下载 Windows 安装包双击安装另一种是用 npm 全局安装核心 CLI。我的建议是新手直接下载安装包别折腾源码编译。我用的是这种方式下载的版本是 0.6.x安装完成后在 PowerShell 里执行openclaw --version能打印出版本号就说明装好了。如果你更习惯用包管理器也可以npm install -g openclaw两种方式本质一样选一种就行不用都装。3.2 初始化配置先让它在本地跑起来安装完先初始化一份配置。执行openclaw init它会生成一个配置文件通常在你的用户目录下的.openclaw/config.yaml不同版本文件名可能略有差异。第一次生成时里面内容很少不要太惊讶。这时候先配置一个模型让 OpenClaw 至少能自己说话。如果用云 API在配置文件里加model: provider: openai-compatible base_url: https://api.example.com/v1 api_key: sk-xxxxxxxx model_name: gpt-4o-mini如果你走本地 Ollama则是model: provider: ollama base_url: http://127.0.0.1:11434 model_name: qwen2.5:7b配置完保存然后在终端跑openclaw run如果看到模型正常加载、没有报错就说明 OpenClaw 本体已经活了。这一步的目的很简单先确认它自己会思考再考虑接入飞书。不然飞书都连好了结果模型没配对机器人就像个空壳一问三不知。3.3 Windows Companion 是什么要不要管如果你是 Windows 用户安装包里通常还会带一个叫 Windows Companion 的组件。我的理解是它负责 Agent 调用 Windows 桌面能力的配合部分比如系统托盘、剪贴板、本地通知这些。OpenClaw 默认会尝试连接它路径一般在配置文件里的companion节点。配置方式很简单companion: enabled: true host: 127.0.0.1 port: 8739如果你不需要 Agent 操作本机桌面可以先enabled: false不影响飞书功能。但如果你想让机器人帮你定时打开某个软件、读取剪贴板内容那这个必须开着。注意Companion 和 OpenClaw 主程序要放在同一台机器上因为它监听的是本地端口跨机器访问需要额外配置网络白名单一般没必要。4. 飞书开放平台后台配置创建一个真正的机器人4.1 创建企业自建应用登录飞书开放平台open.feishu.cn进入开发者后台点创建应用选企业自建应用。名字随便起我起的是得力助手图标随便传一个。创建完成后你会进入应用详情页这里就是整个机器人的大本营。这里有一个很多人忽略的点应用创建后默认是未发布状态只有你自己和少数测试成员能用。如果想让整个部门都能在搜索里找到它、在群里它需要走一遍发布审核流程。个人测试阶段用未发布完全够别急着发布等功能稳定了再说。4.2 添加机器人能力和事件订阅在应用详情页左侧菜单找到添加应用能力添加机器人。添加完成后应用就具备了一个机器人的基本身份。然后进入事件与回调页面这一步非常关键。订阅事件选择im.message.receive_v1接收消息这是机器人能不能收到用户消息的核心开关。如果你连的是长连接模式这里要选择使用长连接接收事件然后点保存。事件订阅这里有几个坑我一个个说如果你选了 webhook 模式必须填一个公网可达的地址并且要能在飞书的URL 验证环节返回challenge字段。OpenClaw 如果支持 webhook 模式一般会自动处理验证但前提是你的地址能通。长连接模式虽然不用填公网地址但要求你的应用开启长连接开关有些版本还在事件订阅旁边多一个连接方式选项别漏了。事件订阅列表里只加你真正需要的事件加多了会增加消息推送量也可能导致安全问题。4.3 获取凭证与安全设置保存完事件订阅去凭证与基础信息页面能看到两个关键东西App ID格式是cli_开头的一串字符相当于应用的用户名。App Secret相当于密码点重置可以重新生成。同时在事件与回调页面可以看到Verification Token和Encrypt Key。这四个值是 OpenClaw 和飞书对接的全部凭据。把它们记下来一会儿配置要用。安全设置上建议打开IP 白名单如果 OpenClaw 部署在固定 IP 的机器上并且把Encrypt Key开着。开启加密后所有事件消息都会用 AES 加密传输OpenClaw 需要配置相同的 Key 才能解密。多一层加密多一点安心代价只是配置时多填一个值值。5. 把 OpenClaw 和飞书机器人接起来5.1 配置 App ID、App Secret 和事件回调OpenClaw 的配置文件里一般有feishu或channels.feishu节点把刚才拿到的四个值填进去。下面是我这边能跑通的示例channels: feishu: enabled: true app_id: cli_xxxxxxxxxxxxxxxx app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx encrypt_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx verification_token: xxxxxxxxxxxxxxxx event_mode: websocket receive_event: im.message.receive_v1几点说明app_secret和encrypt_key如果填错最常见的表现是日志里能收到推送但解密失败报invalid signature或decrypt failed。别慌先检查这两个值是否和后台一致尤其注意复制的时候别多复制了空格或换行。event_mode必须是websocket如果你选 webhook则要改成webhook并额外配一个callback_url。我是长连接派所以全文按 websocket 走。如果你的 OpenClaw 版本配置项命名略有不同比如叫feishu_bot以你实际版本生成的模板为准字段含义是等价的。5.2 启动和联调第一次在飞书里收到回话配置保存后重启 OpenClawopenclaw run看到日志里有类似feishu bot connected或websocket connected的输出说明长连接已经建立。这时候打开飞书找到你的机器人给它发一句你好。正常的链路是消息发到飞书 → 飞书通过长连接推给 OpenClaw → OpenClaw 调模型思考 → 返回结果 → 飞书展示回复。我第一次跑通时机器人回了句你好呀有什么可以帮你那一刻真的有点小激动。如果你发消息后机器人毫无反应先不要怀疑代码先怀疑三点事件订阅没保存、长连接没连上、权限没开全。依次排查基本能定位。5.3 联调中最容易翻车的三个场景第一个是群聊场景。机器人默认不会响应群里所有消息只有在群里被 的时候才会收到事件除非你额外开通了读取全部群消息的权限不建议。测试时记得在群里 它不要干等它自己说话。第二个是消息超时。本地 7B 模型在 CPU 机器上推理可能要几十秒飞书那边如果等太久可能会认为是超时。实测下来OpenClaw 对长耗时任务会把正在处理的状态先回给用户或者通过异步方式处理体验还算能接受。如果你发现消息经常丢可以考虑换更小的模型或者把思考过程缩短。第三个是重复回复。有段时间我的机器人一句话回两遍排查了半天发现是我开了两个openclaw run进程两个进程都在收同一个长连接事件。记住长连接模式下一定只保留一个运行实例。这也是新手很容易犯的错——开着测试窗口忘了关又新开一个窗口跑。6. 实测场景让机器人在飞书里真正干点活6.1 文本对话与角色设定接好之后OpenClaw 在飞书里就是一个能对话的 Agent。你可以通过配置文件给 AI 设定人设让它在群里更符合你的工作场景。比如我给它设定的是擅长数据整理和写作的助手回复简洁直接这样它在飞书里的回复不会长篇大论刷屏。实际感受单聊模式下对话体验最好。因为群聊要每次都 它对话连贯性会差一些而且群成员都能看到内容有些涉及内部信息的提问不合适。我的建议是日常提问用单聊团队协作场景再拉进群里。6.2 让机器人发一张表格飞书机器人发送表格这个需求我猜很多人都会遇到毕竟工作里表格是刚需。OpenClaw 发表格基本有两条路第一条路让模型把数据整理成 Markdown 表格用交互卡片interactive card发出来。飞书对 Markdown 表格的渲染很漂亮直接就是一条带表格的卡片消息适用数据量不大的场景。我给机器人发一句把本周任务整理成表格它给我返回一张四列十几行的卡片表格群里看着特别正规。第二条路数据量大或者对方需要二次编辑时就让 OpenClaw 生成 CSV 或 XLSX 文件然后通过飞书文件上传接口发到会话里。飞书的上传接口是POST https://open.feishu.cn/open-apis/im/v1/files传参格式是表单数据file_type填streamfile_name填文件名file是文件内容。OpenClaw 内置的文件发送工具封装的就是这个接口你只需要在配置里允许它调用文件工具即可。实测发 CSV 文件给同事对方在飞书里能直接预览体验很好。6.3 和飞书多维表格的结合如果不想发文件还有一个进阶玩法让 OpenClaw 直接往飞书多维表格里写数据。你需要在开放平台额外开通多维表格的权限bitable:app并把表格的app_token和table_id配给它。这个适合做数据看板场景比如机器人每天自动把运行指标写入表格。不过这一步涉及的权限较多建议等基本功能跑稳之后再折腾。7. 更省算力的玩法接入本地 Ollama 模型7.1 OpenClaw 只能用 API 接算力吗——这是误会网上老有人问 OpenClaw 是不是只能通过 API 方式使用算力我最初也这么以为后来搞明白了OpenClaw 本身是 Agent 调度框架不内置模型所以它必须有一个模型来源。模型来源无非两类云端 API各家大模型厂商和本地推理Ollama、llama.cpp 这类。所以答案很明确不是只能用 API本地推理完全支持而且我推荐个人使用优先考虑本地。本地跑的好处是隐私性好消息不出你机器坏处是速度取决于硬件。我的主力机器是 16G 内存、无独立显卡的轻薄本跑qwen2.5:7b的 CPU 推理速度大约每秒 5-8 个 token对话短还好长文本会明显感觉到打字慢。后来换成qwen2.5:3b流畅度提升明显日常对话足够。7.2 在 OpenClaw 里配置 Ollama配置方式前面提到过展开说一下。首先确保 Ollama 在后台运行ollama serve然后 OpenClaw 配置里指定model: provider: ollama base_url: http://127.0.0.1:11434 model_name: qwen2.5:3b temperature: 0.7 max_tokens: 2048temperature控制随机性工作场景我一般调到 0.7 以下太放飞会经常给你编内容。max_tokens控制单次回复长度飞书场景 2048 够用太长卡片消息展示也很累。这里有一个经验如果你同时配了云 API 和本地 OllamaOpenClaw 一般支持按渠道或按任务分流。比如复杂任务走云 API日常闲聊走本地模型。不同版本配置方式可能不一样但思路是对的——能省则省。7.3 什么时候还是得用 API本地模型也有明显的天花板。让它整理内部文档、做格式转换、提取表格数据7B 模型完全够用但让它写复杂代码、做长文写作、处理逻辑链很长的推理任务本地小模型就容易一本正经地胡说八道。我的做法是飞书机器人默认走本地模型省成本真遇到复杂任务我在配置里单独指定一个云模型渠道手动切过去。顺带说一句如果你单位有内部部署的模型服务只要接口兼容 OpenAI 格式都可以通过openai-compatible方式接入 OpenClaw不一定非要用公网大厂 API。8. 进阶玩法Skills 扩展和手机 Termux 部署8.1 什么是 Skill怎么装Skill 是 OpenClaw 的可扩展能力包相当于给 Agent 装插件。装一个定时任务Skill它就能在飞书里说每天早上九点提醒我开会装一个网页搜索Skill它就能帮你查资料并把链接甩到群里。安装方式一般是把 Skill 放到 OpenClaw 的skills目录下然后在配置里启用。以官方仓库下载的 Skill 为例skills/ schedule/ manifest.yaml main.py web-search/ manifest.yaml main.py配置文件里加一行skills_enabled: [schedule, web-search]重启生效。这里必须提醒一句Skill 是有代码执行能力的别从不可信的第三方来源乱装。官方仓库和社区高星项目相对靠谱陌生人私传的 Skill 压缩包跑之前先打开代码看一眼这是最基本的自我保护。8.2 手机 Termux 上能不能装 OpenClaw这个问题我也试过。Termux 是安卓上的终端模拟器确实能装 OpenClaw但你要明白一件事手机端适合做管理入口和轻量对话不适合跑重活。手机上装 OpenClaw 主要分三步pkg update pkg upgrade pkg install nodejs-lts git python npm install -g openclaw openclaw init装完之后它和 Windows 上的几乎一样可以配置模型和飞书。但有两个现实问题一是安卓后台进程容易被系统回收锁屏一会 OpenClaw 就被杀了飞书机器人自然就失联二是手机网络切换WiFi 切流量可能导致长连接断开需要加自动重连机制。我的建议是主力还是放 Windows 或 Linux 机器上手机 Termux 只做应急查看和简单操作。让一台电脑 24 小时跑 OpenClaw手机作为飞书客户端来使用体验远好于在手机上直接跑。8.3 Windows Companion 的更多配置细节如果你想让 OpenClaw 能操作本机软件Windows Companion 值得认真配一下。除了前面说的enabled、host、portCompanion 一般还支持设置允许的自动化操作列表。我的经验是能不开的权限尽量不开能用 Skill 做的事不要让 Agent 直接点鼠标。因为自动化操作一旦失控比如它自己打开浏览器乱跳、误删文件代价可能比收益大得多。把 Companion 的能力限制在剪贴板读写、系统通知、打开白名单应用这三项对我足够用了。9. 踩坑记录与排查思路9.1 启动时报 WSL 相关错误如果你参考了某些教程启动时看到OpenClaw 无法安全验证 sl2 环境请在 PowerShell 中运行 wsl -- status按我之前说的跑一遍wsl --status看看是哪个环节没到位。常见情况有三种WSL 内核太旧wsl --update解决、没有默认分发版wsl --install -d Ubuntu-22.04解决、默认版本还是 1wsl --set-default-version 2解决。处理完重开一个 PowerShell 窗口再启动 OpenClaw别在旧窗口里重试因为 WSL 环境变量不会自动刷新。9.2 消息收不到先查事件订阅我记得有一次折腾到凌晨日志里什么错误都没有OpenClaw 也显示连接正常但飞书里发消息它就是不理人。后来才发现是事件订阅里im.message.receive_v1压根没保存上——后台页面有添加和保存两个按钮我只点了添加没点保存。这种低级错误非常典型排查顺序建议是检查开放平台后台事件与回调里的订阅列表确认事件在列表里。检查 OpenClaw 日志看有没有收到推送记录长连接模式下收到事件会打日志。检查机器人是否在群里有 单聊一般不用。检查权限列表是否包含读取消息相关权限。9.3 日志怎么看才不头大OpenClaw 的日志默认在用户目录下的.openclaw/logs/里按天滚动。排查问题时不要从头翻到尾直接用关键词过滤grep -i feishu ~/.openclaw/logs/xxx.log | tail -50重点关注几个关键词connected长连接状态、receive收到消息、send发出消息、error、timeout。我处理问题时的习惯是先在日志里确认收没收到再确认发没发出去就能快速把问题切到飞书侧还是 OpenClaw 侧。如果日志显示收到了但回复失败那大概率是模型接口或权限问题如果日志压根没收到那问题出在飞书后台配置。整套流程走下来最花时间的其实就是后台权限和事件订阅那几步代码层面反而很简单。我自己跑完之后的体会是飞书机器人 OpenClaw 本地模型这套组合最大的价值不是炫技而是把原本锁在终端里的 Agent 能力真正搬到了日常聊天工具里——同事在群里 一下就能用我在地铁上也能让它整理思路、查资料。最后分享一个小建议配置稳定之后给 OpenClaw 配一个开机自启服务Windows 上用计划任务或者 nssm 都行别再用手工窗口跑不然哪天重启电脑忘记拉起飞书里的人还得跑过来问你机器人怎么又死了。