Windows 上跑 OpenClaw 再接入飞书机器人这条路我前前后后折腾了两天踩了 WSL 环境、权限配置、长连接断开各种坑之后总算把整条链路跑通了。这篇文章就把我从零开始的操作过程完整记录一遍包括为什么这么选型、每一步怎么做的、遇到问题怎么排查给想在 Windows 工作机上跑 OpenClaw 并接入飞书的同学一份可以直接抄作业的参考。先说说我做完之后这套东西能干什么你可以在飞书里直接私聊机器人或者在群里 它OpenClaw 收到消息后能调用技能、查询数据、把结果回复到聊天里甚至可以把处理完的数据写进飞书多维表格。适合谁呢手头只有 Windows 办公机、但想让个人 AI 助理真正落到日常协作场景里的开发者、运维和产品同学。全文比较长建议先收藏再慢慢照着操作。1. 整体思路与方案选型动手之前先想清楚一个问题为什么要在 Windows 上部署 OpenClaw又为什么偏偏用飞书当入口这两个选择决定了后面所有步骤的走向。1.1 为什么选择 Windows 作为部署环境很多 AI 智能体框架的官方文档都默认 Linux 或 macOSWindows 用户上来就碰一鼻子灰。但现实中大量开发者的主力机就是 Windows特别是公司发的办公电脑跑 Linux 虚拟机又卡又麻烦。OpenClaw 这类个人智能体框架属于“轻量常驻服务”不需要 GPU也没有大数据量计算完全压得住 Windows 上的日常负载。我选 Windows 部署还有一层实际考量我平时的工作流都在 Windows 上Outlook、浏览器、各种办公软件全在这台机器上把 OpenClaw 装在本地意味着我可以直接在熟悉的系统里做调试不需要额外准备一台服务器。但要注意OpenClaw 的依赖链里有不少 Linux 生态组件比如原生 Node.js 模块、Shell 辅助脚本、Python 工具链。如果硬在 Windows 原生环境跑经常会遇到 PATH 冲突、node-gyp 编译失败、权限模型不一致这些幺蛾子。所以正确的做法是Windows 提供宿主环境真正跑 OpenClaw 的是 WSL2 里的 Linux 子系统。这也是整个部署方案里最关键的一个“架构决策”。1.2 为什么飞书是合适的接入渠道接入渠道这件事我对比过几类微信个人号机器人接口不开放、钉钉的开放平台也成熟但多维表格生态不如飞书顺手、Telegram 等海外渠道在国内办公场景不适用。飞书的优势很明确开放平台接口完善、机器人能力成熟、企业内已经大规模使用员工几乎不需要额外学习成本。更实用的是飞书的多维表格。智能体跑完任务之后如果能把结果直接写进多维表格就能顺便完成数据沉淀这对做报表、维护资产清单、管理任务进度这类场景是刚需。飞书机器人还能发消息卡片交互感比纯文本强很多OpenClaw 回传结果的时候可以不用干巴巴的纯文字。选飞书还有个现实原因飞书开放平台支持“长连接”模式接收事件机器人主动连上飞书服务器就行不需要给飞书提供一个公网 HTTPS 回调地址。对部署在公司内网或个人 Windows 电脑上的服务来说这个特性省掉了大量网络层面的麻烦。1.3 长连接 vs Webhook一次关键的架构取舍飞书开放平台的事件订阅有两种接收方式这里值得多说几句因为选错方案会给自己挖大坑。第一种是 Webhook 模式飞书把用户消息 POST 到你在开放平台配置的回调 URL 上飞书会先发送一个 URL 验证请求你需要正确响应 Challenge 才能通过校验。问题在于你的机器人服务必须有一个公网可达的 HTTPS 地址而个人电脑或内网服务器根本没有公网入口常规做法是再做一层内网穿透这就多了一个不稳定因素。第二种是长连接模式机器人服务主动向飞书开放平台发起一个 WebSocket 连接飞书的事件通过这个连接推下来。整个过程不需要任何公网地址也不存在 URL 验证问题。OpenClaw 所在的主机只要能正常访问外网就行防火墙策略也非常简单。我最终选了长连接事实证明这是整个项目里最省心的一个决定。后面配置的时候只需要拿到 App ID、App Secret打开事件订阅里的“使用长连接接收事件”开关把事件列表勾上服务起来后连接自动建立。第一次调试的时候我甚至没离开办公网就看到了消息进来体验相当顺滑。2. Windows 环境准备与 OpenClaw 安装选型定下来之后开始落地。这里先解决运行环境再装 OpenClaw 本体。环境部分多花点时间是值得的我见过太多人跳过 WSL 直接在 Windows 上裸跑最后全卡在依赖编译上。2.1 启用 WSL2 和 Windows TerminalWindows 10 2004 及以上版本或 Windows 11 我都试过流程基本一致。首先用管理员身份打开 PowerShell执行wsl --install这个命令会自动启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个功能下载并安装默认的 Linux 发行版通常是 Ubuntu然后提示重启电脑。如果你的系统比较老wsl --install可能提示命令不存在那就在“启用或关闭 Windows 功能”里手动勾选上述两个功能重启后再安装一个 Ubuntu 发行版。重启之后Ubuntu 首次启动会让你创建 Linux 用户名和密码这个用户名密码跟 Windows 账号无关别搞混。我建议顺手装一下 Windows Terminal微软商店里直接搜装完把 Ubuntu 和 PowerShell 都塞进一个窗口里切换调试的时候非常方便。安装完成后务必检查一下版本wsl --status wsl -l -vwsl --status会显示默认版本是不是 V2wsl -l -v会列出已安装发行版及版本号。如果显示的 Ubuntu 版本是 V1需要手动升级wsl --set-version Ubuntu V2这里有一个常见坑如果你运行wsl --status看到内核版本很老OpenClaw 启动时可能报“无法安全验证 WSL2 环境”解决方法很简单在 PowerShell 里执行wsl --update更新内核。这类问题都在本文第 5 部分有汇总。2.2 在 WSL 里安装 Node.js 和基础依赖OpenClaw 基于 Node.js 生态所以 WSL 里必须有一个干净可用的 Node 环境。这里有个容易犯的错误很多人图省事在 Windows 上装好 Node.js然后想在 WSL 里直接调用结果路径、权限、原生模块全乱套。我踩过这个坑之后明确告诉你在 WSL 里单独装一套 Linux 版本 Node.js一劳永逸。进入 WSL 终端在 Windows Terminal 里选择 Ubuntu 标签页先装 nvm 来管理 Node 版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v npm -vNode.js 版本我建议选 20 LTS当前 OpenClaw 的主流版本在这个版本下运行最稳。接下来安装编译工具链避免后面 npm 安装原生依赖时 node-gyp 直接罢工sudo apt update sudo apt install -y build-essential python3 git这些工具平时不起眼但等到某个 npm 包需要编译 C 扩展时缺了它们就会报一堆看不懂的错误。2.3 安装 OpenClaw 并完成初始化Node 环境就绪后用 npm 全局安装 OpenClawnpm install -g openclaw安装完成后先跑一下帮助命令确认当前版本支持的命令openclaw --help不同小版本的命令缩写可能有差异这一步能帮你少走弯路。然后执行初始化openclaw init初始化过程会在当前用户目录下生成配置文件夹核心是 config.yaml也可能叫 openclaw.yaml。这个文件就是 OpenClaw 的总开关里面会包含 channels、skills 之类的段落。channels 是接入渠道配置skills 是技能配置后面接飞书改的就是这里。初始化完成后可以先启动一次验证基础服务是否正常openclaw start看到服务正常监听、日志滚动没有报错说明 OpenClaw 本体已经就绪。把这个终端窗口留着后面改完配置重启它就行。需要注意如果启动时报 Node 版本过低或者模块编译错误大概率是 2.2 那步没做完整回头补上再重试。3. 飞书机器人创建与长连接配置OpenClaw 跑起来只是一个空壳真正让它变成“飞书里的一个能对话的机器人”需要在飞书开放平台创建应用、配权限、订阅事件再把这套凭证写进 OpenClaw 配置。3.1 在飞书开放平台创建企业自建应用打开飞书开放平台用飞书账号登录进入开发者后台点击“创建企业自建应用”。填一个应用名称和描述比如“OpenClaw 助理”创建完成后你会进入这个应用的管理后台。在“凭证与基础信息”页面里你能拿到两个关键凭证App ID形如cli_xxxxxxxx是应用的唯一标识。App Secret相当于应用的密码后面 OpenClaw 连飞书就靠这两个凭证。紧接着点击“添加应用能力”选择“机器人”。添加成功之后飞书侧的应用就有了机器人身份。注意这一步不会自动在通讯录里出现机器人你还得去“版本管理与发布”里创建一个版本并提交发布这个应用第一次发布通常需要企业管理员审核审核通过后机器人才能真正被同事搜索到。如果你用的是个人开发者租户发布流程很轻量基本是秒过。3.2 配置权限和事件订阅机器人要收发消息必须申请对应的权限。权限管理的逻辑是多申请几个用不到不影响运行少了却会直接报错。我这里开的是这几个核心权限im:message读取用户发给机器人的消息内容。im:message:send_as_bot以机器人身份发送消息。im:chat:readonly读取群信息用于群内 场景。im:resource下载用户发来的图片、文件资源。你可以在权限搜素框里逐个搜出来开通也可以直接搜权限名称的关键词。开通之后有些权限需要管理员审核等审核通过再继续。然后是事件订阅。在“事件与回调”页面里接收方式选“使用长连接接收事件”然后添加事件这里必须要订阅的就是im.message.receive_v1接收消息事件。这个事件覆盖了用户私聊机器人和在群里 机器人两种场景是整套接线的核心。如果你还想让 OpenClaw 处理文件、图片还可以订阅im.message.receive_v1下的资源类型或者额外订阅消息已读事件不过这属于后话第一版先保持最小集合。3.3 把飞书凭证写进 OpenClaw 配置回到 WSL打开 OpenClaw 的 config.yaml。找到 channels 段落我当时按如下格式新增飞书渠道配置channels: feishu: enabled: true appId: cli_xxxxxxxx appSecret: 你的AppSecret有些版本的 OpenClaw 里飞书渠道的 key 可能叫lark而不是feishu如果你改了配置后启动日志提示找不到渠道就在配置文件里用lark试试或者查一下当前版本的 channel 文档。另外如果你在飞书事件订阅里开启了加密还需要把 Encrypt Key 一并填进去我这边没有开启加密所以配置里就没写。保存配置后重启 OpenClawopenclaw restart启动日志里如果出现“feishu connection established”或类似字样说明长连接已经建立成功。这时候你去飞书搜索栏搜一下刚创建的应用机器人点进会话发一条“你好”正常情况下 OpenClaw 会在日志里打印收到消息的记录。如果没有任何反应先别急着怀疑配置去第 5 部分对照排查。4. 场景实操从基础对话到表格与多维表格机器人上线只是起点能不能真正干活的判断标准是“能不能把处理结果变成有用的输出”比如回消息、发表格、写多维表格。这一节我把几个高频实操场景完整走一遍。4.1 基础对话与技能触发OpenClaw 的消息处理逻辑大致是这样收到消息之后先做意图识别看这句消息是不是能触发某个技能能触发就执行技能并回传结果不能触发就走默认对话逻辑。所以你在飞书里测试的时候不一定要用自然语言长篇描述直接发技能名加参数往往最快。比如我配置了一个叫“status”的技能作用是查询 OpenClaw 当前状态那我就在飞书里直接发OpenClaw 机器人 statusOpenClaw 收到后执行对应技能并把输出作为消息内容回复在当前会话里。群聊场景下记得先把这个机器人拉进群然后 它。如果机器人没有回复优先检查是不是没订阅im.message.receive_v1或者权限没生效。这个环节最考验的就是耐心日志里能看到每一步的消息流转养成盯日志的习惯后面能省很多事。4.2 让机器人发送表格消息飞书机器人回消息不只有纯文本一种方式。做汇报、列数据时富文本和消息卡片比纯文本清楚得多。我当时在 OpenClaw 里写了一个技能调用飞书 API 发一条消息卡片卡片里用表格结构列了一组数据实测效果非常好。如果你要发送的是真正的表格文件比如 CSV 或 Excel 文件就需要走飞书的文件上传接口先调用上传文件接口拿到 file_key。再调用发送消息接口消息类型指定为 file带上 file_key。用飞书官方 Node.js SDK 会更方便我直接在技能代码里这样写import * as lark from larksuiteoapi/node-sdk; const client new lark.Client({ appId: process.env.FEISHU_APP_ID, appSecret: process.env.FEISHU_APP_SECRET, }); const res await client.im.message.create({ params: { receive_id_type: chat_id }, data: { receive_id: chatId, msg_type: file, content: JSON.stringify({ file_key: fileKey }), }, });关键点是receive_id_type和receive_id要配对。如果你拿到的是群 ID就用chat_id如果是用户的 Open ID就要在接口参数里改成open_id不然会报参数错误。这个细节我花了不少时间才定位到特意记在这里。4.3 把结果写进多维表格多维表格是飞书比普通即时通讯工具强出一个身位的地方。OpenClaw 跑完任务后把结构化数据直接写进多维表格后续再做筛选、分组、视图分享都行等于智能体的输出直接变成了团队可以协作的数据资产。具体做法是在开放平台权限管理里申请多维表格的相关权限然后在 OpenClaw 技能里调用多维表格 API。写入一条记录的接口大致形态如下POST /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records请求体是一个 JSON 结构字段名跟多维表格里的字段名一一对应。例如我建了一张“巡检记录表”字段有“日期”“机器名”“状态”写入代码就长这样await client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId, }, data: { fields: { 日期: new Date().toLocaleDateString(zh-CN), 机器名: hostName, 状态: status, }, }, });如果你是多维表格新手建议先在飞书里手建一张表把字段类型都确定好再用 API 测试写入。注意多维表格的字段类型很严格日期字段要传时间戳或标准日期字符串、数字字段不能传字符串否则接口会返回字段类型不匹配的错误。这些错误日志里都会写得很清楚照提示改就行。4.4 自定义技能把 OpenClaw 变成团队工具OpenClaw 最让我喜欢的地方就是技能扩展。一个技能的本质就是一个目录加一个执行脚本目录里放说明文件描述这个技能是干什么的、需要什么参数执行脚本就是真正干活的代码。假设我想让机器人支持“查天气”我就在 OpenClaw 的技能目录下新建一个文件夹里面两个文件SKILL.md 描述技能和参数run.js 负责调用天气 API 并返回结果。OpenClaw 会把消息内容里的技能名和参数提取出来跑完后把标准输出作为回复发回飞书。实际操作里我建议从最小技能开始写只接收一个参数返回一段静态文本跑通链路后再逐步加逻辑。因为技能文件和 OpenClaw 之间的参数解析、输出裁剪规则不同版本有差异小步迭代比一次写个大的然后反复 debug 要舒服得多。5. 常见问题与排查技巧实录这一节是我最想分享的部分因为整个搭建过程里大部分时间花在了“解决报错”而不是“写功能”上。下面这些坑我一个一个亲自踩过。5.1 高频报错排查速查表现象可能原因排查与解决OpenClaw 启动报“无法安全验证 WSL2 环境”WSL 内核版本过旧在 PowerShell 运行wsl --update刷新终端后重启 OpenClawnpm 安装依赖时 node-gyp 编译失败WSL 缺少编译工具链执行sudo apt install -y build-essential python3后重装依赖飞书机器人在线但收不到消息未订阅im.message.receive_v1事件进入开放平台事件订阅页添加该事件并发布新版本收到消息但机器人无法回复缺少发送消息权限确认已开通im:message:send_as_bot且版本已发布API 返回 receive_id 无效receive_id_type 与 receive_id 不匹配群聊场景用chat_id单聊场景用open_id长连接频繁断开网络抖动或心跳超时看日志里的连接错误码一般重新连接即可恢复配置了 feishu 但日志提示渠道不存在渠道 key 名称不匹配检查当前版本用的 key 是feishu还是lark以官方文档为准5.2 几个能救命的调试习惯第一个习惯是“每一步都验证”。WSL 装好先验证wsl --statusNode 装好先跑node -v飞书应用建好先到开放平台后台看凭证OpenClaw 配好先看日志。不要想着一次把所有事做完再统一验证那样出问题都不知道是哪一步的锅。第二个习惯是“多看日志少猜原因”。OpenClaw 启动时可以加上详细日志参数不同版本可能是--verbose或-d飞书侧配置有变更时也要及时看 openclaw 的启动日志。长连接模式下日志里会明确打印“连接建立”“收到事件”“发送消息失败”等状态几乎每个问题都能靠日志定位到根因。第三个习惯是“用最小配置跑通再叠加”。我第一次接入飞书就想着把表格、多维表格、技能全配齐结果出了三个问题叠加在一起排查起来痛不欲生。正确的路径是先只配置基本对话跑通消息收发再写一个最简单的文本回复技能确认无误后再做表格和多维表格集成。6. 接入后续的扩展玩法与个人经验整套链路稳定运行之后扩展空间比想象中大得多。这里列几个我觉得价值最高的方向以及一些个人习惯上的建议。6.1 从聊天机器人到自动化执行节点现在的 OpenClaw 对我来说已经不只是“聊天机器人”而是一个跑在 Windows 上的自动化执行节点。飞书的机器人消息只是触发入口真正干活的是技能背后的各种脚本和 API 调用。比如我可以让 OpenClaw 定时把多维表格里未完成的任务拉出来统计完之后在群里发一张汇总卡片。这就是“定时任务 多维表格 API 消息卡片”三件套的组合已经可以解决很多团队日报、周报、数据汇总的重复劳动。另一个方向是多机器人分身在飞书开放平台再创建一个新应用给同样的 OpenClaw 配不同身份一个负责日常问答一个负责数据查询再一个负责告警通知。飞书本身支持一个组织下有多个自建应用OpenClaw 这边只需要增加 channel 配置项即可逻辑解耦得很干净。6.2 我在实际使用中沉淀的几个操作习惯操作到后面我觉得有几个习惯真的能让你少走弯路第一配置文件的版本管理。OpenClaw 的配置文件和技能目录一定要纳入 Git 管理哪怕只是本地仓库。我踩过三次改了配置后回不去的坑养成每次改动前git commit的习惯之后再改出问题也能秒回退。第二飞书的“版本发布”不等于“配置生效”。每次在开放平台改了权限或事件订阅都要记得去“版本管理与发布”里更新版本并确认审核通过否则线上机器人拿到的还是旧配置。这个逻辑一开始很容易被忽略导致你明明配了权限却一直报错。第三别把所有逻辑塞进一个技能文件里。OpenClaw 跑复杂任务时一个技能里代码太多会让排查变得很痛苦。我现在的做法是技能脚本只做轻量编排真正干重活的逻辑单独放一个小模块技能脚本负责调用。这样出了问题可以明确区分是消息链路问题还是内部逻辑问题排查效率高很多。把 OpenClaw 接上飞书机器人之后最大的感受是“工作流里终于有了一块能自己定义拼装的积木”。你不用等某个 SaaS 厂商开发出你想要的功能自己写个技能、拖个表格、配条消息链路需求就跑起来了。这套东西后续扩展的深度基本上取决于你愿意投入多少时间去给它堆技能和场景。如果你也正在 Windows 上折腾 OpenClaw希望这篇记录能帮你少踩几个我踩过的坑。
Windows 上跑 OpenClaw 再接入飞书机器人这条路我前前后后折腾了两天踩了 WSL 环境、权限配置、长连接断开各种坑之后总算把整条链路跑通了。这篇文章就把我从零开始的操作过程完整记录一遍包括为什么这么选型、每一步怎么做的、遇到问题怎么排查给想在 Windows 工作机上跑 OpenClaw 并接入飞书的同学一份可以直接抄作业的参考。先说说我做完之后这套东西能干什么你可以在飞书里直接私聊机器人或者在群里 它OpenClaw 收到消息后能调用技能、查询数据、把结果回复到聊天里甚至可以把处理完的数据写进飞书多维表格。适合谁呢手头只有 Windows 办公机、但想让个人 AI 助理真正落到日常协作场景里的开发者、运维和产品同学。全文比较长建议先收藏再慢慢照着操作。1. 整体思路与方案选型动手之前先想清楚一个问题为什么要在 Windows 上部署 OpenClaw又为什么偏偏用飞书当入口这两个选择决定了后面所有步骤的走向。1.1 为什么选择 Windows 作为部署环境很多 AI 智能体框架的官方文档都默认 Linux 或 macOSWindows 用户上来就碰一鼻子灰。但现实中大量开发者的主力机就是 Windows特别是公司发的办公电脑跑 Linux 虚拟机又卡又麻烦。OpenClaw 这类个人智能体框架属于“轻量常驻服务”不需要 GPU也没有大数据量计算完全压得住 Windows 上的日常负载。我选 Windows 部署还有一层实际考量我平时的工作流都在 Windows 上Outlook、浏览器、各种办公软件全在这台机器上把 OpenClaw 装在本地意味着我可以直接在熟悉的系统里做调试不需要额外准备一台服务器。但要注意OpenClaw 的依赖链里有不少 Linux 生态组件比如原生 Node.js 模块、Shell 辅助脚本、Python 工具链。如果硬在 Windows 原生环境跑经常会遇到 PATH 冲突、node-gyp 编译失败、权限模型不一致这些幺蛾子。所以正确的做法是Windows 提供宿主环境真正跑 OpenClaw 的是 WSL2 里的 Linux 子系统。这也是整个部署方案里最关键的一个“架构决策”。1.2 为什么飞书是合适的接入渠道接入渠道这件事我对比过几类微信个人号机器人接口不开放、钉钉的开放平台也成熟但多维表格生态不如飞书顺手、Telegram 等海外渠道在国内办公场景不适用。飞书的优势很明确开放平台接口完善、机器人能力成熟、企业内已经大规模使用员工几乎不需要额外学习成本。更实用的是飞书的多维表格。智能体跑完任务之后如果能把结果直接写进多维表格就能顺便完成数据沉淀这对做报表、维护资产清单、管理任务进度这类场景是刚需。飞书机器人还能发消息卡片交互感比纯文本强很多OpenClaw 回传结果的时候可以不用干巴巴的纯文字。选飞书还有个现实原因飞书开放平台支持“长连接”模式接收事件机器人主动连上飞书服务器就行不需要给飞书提供一个公网 HTTPS 回调地址。对部署在公司内网或个人 Windows 电脑上的服务来说这个特性省掉了大量网络层面的麻烦。1.3 长连接 vs Webhook一次关键的架构取舍飞书开放平台的事件订阅有两种接收方式这里值得多说几句因为选错方案会给自己挖大坑。第一种是 Webhook 模式飞书把用户消息 POST 到你在开放平台配置的回调 URL 上飞书会先发送一个 URL 验证请求你需要正确响应 Challenge 才能通过校验。问题在于你的机器人服务必须有一个公网可达的 HTTPS 地址而个人电脑或内网服务器根本没有公网入口常规做法是再做一层内网穿透这就多了一个不稳定因素。第二种是长连接模式机器人服务主动向飞书开放平台发起一个 WebSocket 连接飞书的事件通过这个连接推下来。整个过程不需要任何公网地址也不存在 URL 验证问题。OpenClaw 所在的主机只要能正常访问外网就行防火墙策略也非常简单。我最终选了长连接事实证明这是整个项目里最省心的一个决定。后面配置的时候只需要拿到 App ID、App Secret打开事件订阅里的“使用长连接接收事件”开关把事件列表勾上服务起来后连接自动建立。第一次调试的时候我甚至没离开办公网就看到了消息进来体验相当顺滑。2. Windows 环境准备与 OpenClaw 安装选型定下来之后开始落地。这里先解决运行环境再装 OpenClaw 本体。环境部分多花点时间是值得的我见过太多人跳过 WSL 直接在 Windows 上裸跑最后全卡在依赖编译上。2.1 启用 WSL2 和 Windows TerminalWindows 10 2004 及以上版本或 Windows 11 我都试过流程基本一致。首先用管理员身份打开 PowerShell执行wsl --install这个命令会自动启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个功能下载并安装默认的 Linux 发行版通常是 Ubuntu然后提示重启电脑。如果你的系统比较老wsl --install可能提示命令不存在那就在“启用或关闭 Windows 功能”里手动勾选上述两个功能重启后再安装一个 Ubuntu 发行版。重启之后Ubuntu 首次启动会让你创建 Linux 用户名和密码这个用户名密码跟 Windows 账号无关别搞混。我建议顺手装一下 Windows Terminal微软商店里直接搜装完把 Ubuntu 和 PowerShell 都塞进一个窗口里切换调试的时候非常方便。安装完成后务必检查一下版本wsl --status wsl -l -vwsl --status会显示默认版本是不是 V2wsl -l -v会列出已安装发行版及版本号。如果显示的 Ubuntu 版本是 V1需要手动升级wsl --set-version Ubuntu V2这里有一个常见坑如果你运行wsl --status看到内核版本很老OpenClaw 启动时可能报“无法安全验证 WSL2 环境”解决方法很简单在 PowerShell 里执行wsl --update更新内核。这类问题都在本文第 5 部分有汇总。2.2 在 WSL 里安装 Node.js 和基础依赖OpenClaw 基于 Node.js 生态所以 WSL 里必须有一个干净可用的 Node 环境。这里有个容易犯的错误很多人图省事在 Windows 上装好 Node.js然后想在 WSL 里直接调用结果路径、权限、原生模块全乱套。我踩过这个坑之后明确告诉你在 WSL 里单独装一套 Linux 版本 Node.js一劳永逸。进入 WSL 终端在 Windows Terminal 里选择 Ubuntu 标签页先装 nvm 来管理 Node 版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v npm -vNode.js 版本我建议选 20 LTS当前 OpenClaw 的主流版本在这个版本下运行最稳。接下来安装编译工具链避免后面 npm 安装原生依赖时 node-gyp 直接罢工sudo apt update sudo apt install -y build-essential python3 git这些工具平时不起眼但等到某个 npm 包需要编译 C 扩展时缺了它们就会报一堆看不懂的错误。2.3 安装 OpenClaw 并完成初始化Node 环境就绪后用 npm 全局安装 OpenClawnpm install -g openclaw安装完成后先跑一下帮助命令确认当前版本支持的命令openclaw --help不同小版本的命令缩写可能有差异这一步能帮你少走弯路。然后执行初始化openclaw init初始化过程会在当前用户目录下生成配置文件夹核心是 config.yaml也可能叫 openclaw.yaml。这个文件就是 OpenClaw 的总开关里面会包含 channels、skills 之类的段落。channels 是接入渠道配置skills 是技能配置后面接飞书改的就是这里。初始化完成后可以先启动一次验证基础服务是否正常openclaw start看到服务正常监听、日志滚动没有报错说明 OpenClaw 本体已经就绪。把这个终端窗口留着后面改完配置重启它就行。需要注意如果启动时报 Node 版本过低或者模块编译错误大概率是 2.2 那步没做完整回头补上再重试。3. 飞书机器人创建与长连接配置OpenClaw 跑起来只是一个空壳真正让它变成“飞书里的一个能对话的机器人”需要在飞书开放平台创建应用、配权限、订阅事件再把这套凭证写进 OpenClaw 配置。3.1 在飞书开放平台创建企业自建应用打开飞书开放平台用飞书账号登录进入开发者后台点击“创建企业自建应用”。填一个应用名称和描述比如“OpenClaw 助理”创建完成后你会进入这个应用的管理后台。在“凭证与基础信息”页面里你能拿到两个关键凭证App ID形如cli_xxxxxxxx是应用的唯一标识。App Secret相当于应用的密码后面 OpenClaw 连飞书就靠这两个凭证。紧接着点击“添加应用能力”选择“机器人”。添加成功之后飞书侧的应用就有了机器人身份。注意这一步不会自动在通讯录里出现机器人你还得去“版本管理与发布”里创建一个版本并提交发布这个应用第一次发布通常需要企业管理员审核审核通过后机器人才能真正被同事搜索到。如果你用的是个人开发者租户发布流程很轻量基本是秒过。3.2 配置权限和事件订阅机器人要收发消息必须申请对应的权限。权限管理的逻辑是多申请几个用不到不影响运行少了却会直接报错。我这里开的是这几个核心权限im:message读取用户发给机器人的消息内容。im:message:send_as_bot以机器人身份发送消息。im:chat:readonly读取群信息用于群内 场景。im:resource下载用户发来的图片、文件资源。你可以在权限搜素框里逐个搜出来开通也可以直接搜权限名称的关键词。开通之后有些权限需要管理员审核等审核通过再继续。然后是事件订阅。在“事件与回调”页面里接收方式选“使用长连接接收事件”然后添加事件这里必须要订阅的就是im.message.receive_v1接收消息事件。这个事件覆盖了用户私聊机器人和在群里 机器人两种场景是整套接线的核心。如果你还想让 OpenClaw 处理文件、图片还可以订阅im.message.receive_v1下的资源类型或者额外订阅消息已读事件不过这属于后话第一版先保持最小集合。3.3 把飞书凭证写进 OpenClaw 配置回到 WSL打开 OpenClaw 的 config.yaml。找到 channels 段落我当时按如下格式新增飞书渠道配置channels: feishu: enabled: true appId: cli_xxxxxxxx appSecret: 你的AppSecret有些版本的 OpenClaw 里飞书渠道的 key 可能叫lark而不是feishu如果你改了配置后启动日志提示找不到渠道就在配置文件里用lark试试或者查一下当前版本的 channel 文档。另外如果你在飞书事件订阅里开启了加密还需要把 Encrypt Key 一并填进去我这边没有开启加密所以配置里就没写。保存配置后重启 OpenClawopenclaw restart启动日志里如果出现“feishu connection established”或类似字样说明长连接已经建立成功。这时候你去飞书搜索栏搜一下刚创建的应用机器人点进会话发一条“你好”正常情况下 OpenClaw 会在日志里打印收到消息的记录。如果没有任何反应先别急着怀疑配置去第 5 部分对照排查。4. 场景实操从基础对话到表格与多维表格机器人上线只是起点能不能真正干活的判断标准是“能不能把处理结果变成有用的输出”比如回消息、发表格、写多维表格。这一节我把几个高频实操场景完整走一遍。4.1 基础对话与技能触发OpenClaw 的消息处理逻辑大致是这样收到消息之后先做意图识别看这句消息是不是能触发某个技能能触发就执行技能并回传结果不能触发就走默认对话逻辑。所以你在飞书里测试的时候不一定要用自然语言长篇描述直接发技能名加参数往往最快。比如我配置了一个叫“status”的技能作用是查询 OpenClaw 当前状态那我就在飞书里直接发OpenClaw 机器人 statusOpenClaw 收到后执行对应技能并把输出作为消息内容回复在当前会话里。群聊场景下记得先把这个机器人拉进群然后 它。如果机器人没有回复优先检查是不是没订阅im.message.receive_v1或者权限没生效。这个环节最考验的就是耐心日志里能看到每一步的消息流转养成盯日志的习惯后面能省很多事。4.2 让机器人发送表格消息飞书机器人回消息不只有纯文本一种方式。做汇报、列数据时富文本和消息卡片比纯文本清楚得多。我当时在 OpenClaw 里写了一个技能调用飞书 API 发一条消息卡片卡片里用表格结构列了一组数据实测效果非常好。如果你要发送的是真正的表格文件比如 CSV 或 Excel 文件就需要走飞书的文件上传接口先调用上传文件接口拿到 file_key。再调用发送消息接口消息类型指定为 file带上 file_key。用飞书官方 Node.js SDK 会更方便我直接在技能代码里这样写import * as lark from larksuiteoapi/node-sdk; const client new lark.Client({ appId: process.env.FEISHU_APP_ID, appSecret: process.env.FEISHU_APP_SECRET, }); const res await client.im.message.create({ params: { receive_id_type: chat_id }, data: { receive_id: chatId, msg_type: file, content: JSON.stringify({ file_key: fileKey }), }, });关键点是receive_id_type和receive_id要配对。如果你拿到的是群 ID就用chat_id如果是用户的 Open ID就要在接口参数里改成open_id不然会报参数错误。这个细节我花了不少时间才定位到特意记在这里。4.3 把结果写进多维表格多维表格是飞书比普通即时通讯工具强出一个身位的地方。OpenClaw 跑完任务后把结构化数据直接写进多维表格后续再做筛选、分组、视图分享都行等于智能体的输出直接变成了团队可以协作的数据资产。具体做法是在开放平台权限管理里申请多维表格的相关权限然后在 OpenClaw 技能里调用多维表格 API。写入一条记录的接口大致形态如下POST /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records请求体是一个 JSON 结构字段名跟多维表格里的字段名一一对应。例如我建了一张“巡检记录表”字段有“日期”“机器名”“状态”写入代码就长这样await client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId, }, data: { fields: { 日期: new Date().toLocaleDateString(zh-CN), 机器名: hostName, 状态: status, }, }, });如果你是多维表格新手建议先在飞书里手建一张表把字段类型都确定好再用 API 测试写入。注意多维表格的字段类型很严格日期字段要传时间戳或标准日期字符串、数字字段不能传字符串否则接口会返回字段类型不匹配的错误。这些错误日志里都会写得很清楚照提示改就行。4.4 自定义技能把 OpenClaw 变成团队工具OpenClaw 最让我喜欢的地方就是技能扩展。一个技能的本质就是一个目录加一个执行脚本目录里放说明文件描述这个技能是干什么的、需要什么参数执行脚本就是真正干活的代码。假设我想让机器人支持“查天气”我就在 OpenClaw 的技能目录下新建一个文件夹里面两个文件SKILL.md 描述技能和参数run.js 负责调用天气 API 并返回结果。OpenClaw 会把消息内容里的技能名和参数提取出来跑完后把标准输出作为回复发回飞书。实际操作里我建议从最小技能开始写只接收一个参数返回一段静态文本跑通链路后再逐步加逻辑。因为技能文件和 OpenClaw 之间的参数解析、输出裁剪规则不同版本有差异小步迭代比一次写个大的然后反复 debug 要舒服得多。5. 常见问题与排查技巧实录这一节是我最想分享的部分因为整个搭建过程里大部分时间花在了“解决报错”而不是“写功能”上。下面这些坑我一个一个亲自踩过。5.1 高频报错排查速查表现象可能原因排查与解决OpenClaw 启动报“无法安全验证 WSL2 环境”WSL 内核版本过旧在 PowerShell 运行wsl --update刷新终端后重启 OpenClawnpm 安装依赖时 node-gyp 编译失败WSL 缺少编译工具链执行sudo apt install -y build-essential python3后重装依赖飞书机器人在线但收不到消息未订阅im.message.receive_v1事件进入开放平台事件订阅页添加该事件并发布新版本收到消息但机器人无法回复缺少发送消息权限确认已开通im:message:send_as_bot且版本已发布API 返回 receive_id 无效receive_id_type 与 receive_id 不匹配群聊场景用chat_id单聊场景用open_id长连接频繁断开网络抖动或心跳超时看日志里的连接错误码一般重新连接即可恢复配置了 feishu 但日志提示渠道不存在渠道 key 名称不匹配检查当前版本用的 key 是feishu还是lark以官方文档为准5.2 几个能救命的调试习惯第一个习惯是“每一步都验证”。WSL 装好先验证wsl --statusNode 装好先跑node -v飞书应用建好先到开放平台后台看凭证OpenClaw 配好先看日志。不要想着一次把所有事做完再统一验证那样出问题都不知道是哪一步的锅。第二个习惯是“多看日志少猜原因”。OpenClaw 启动时可以加上详细日志参数不同版本可能是--verbose或-d飞书侧配置有变更时也要及时看 openclaw 的启动日志。长连接模式下日志里会明确打印“连接建立”“收到事件”“发送消息失败”等状态几乎每个问题都能靠日志定位到根因。第三个习惯是“用最小配置跑通再叠加”。我第一次接入飞书就想着把表格、多维表格、技能全配齐结果出了三个问题叠加在一起排查起来痛不欲生。正确的路径是先只配置基本对话跑通消息收发再写一个最简单的文本回复技能确认无误后再做表格和多维表格集成。6. 接入后续的扩展玩法与个人经验整套链路稳定运行之后扩展空间比想象中大得多。这里列几个我觉得价值最高的方向以及一些个人习惯上的建议。6.1 从聊天机器人到自动化执行节点现在的 OpenClaw 对我来说已经不只是“聊天机器人”而是一个跑在 Windows 上的自动化执行节点。飞书的机器人消息只是触发入口真正干活的是技能背后的各种脚本和 API 调用。比如我可以让 OpenClaw 定时把多维表格里未完成的任务拉出来统计完之后在群里发一张汇总卡片。这就是“定时任务 多维表格 API 消息卡片”三件套的组合已经可以解决很多团队日报、周报、数据汇总的重复劳动。另一个方向是多机器人分身在飞书开放平台再创建一个新应用给同样的 OpenClaw 配不同身份一个负责日常问答一个负责数据查询再一个负责告警通知。飞书本身支持一个组织下有多个自建应用OpenClaw 这边只需要增加 channel 配置项即可逻辑解耦得很干净。6.2 我在实际使用中沉淀的几个操作习惯操作到后面我觉得有几个习惯真的能让你少走弯路第一配置文件的版本管理。OpenClaw 的配置文件和技能目录一定要纳入 Git 管理哪怕只是本地仓库。我踩过三次改了配置后回不去的坑养成每次改动前git commit的习惯之后再改出问题也能秒回退。第二飞书的“版本发布”不等于“配置生效”。每次在开放平台改了权限或事件订阅都要记得去“版本管理与发布”里更新版本并确认审核通过否则线上机器人拿到的还是旧配置。这个逻辑一开始很容易被忽略导致你明明配了权限却一直报错。第三别把所有逻辑塞进一个技能文件里。OpenClaw 跑复杂任务时一个技能里代码太多会让排查变得很痛苦。我现在的做法是技能脚本只做轻量编排真正干重活的逻辑单独放一个小模块技能脚本负责调用。这样出了问题可以明确区分是消息链路问题还是内部逻辑问题排查效率高很多。把 OpenClaw 接上飞书机器人之后最大的感受是“工作流里终于有了一块能自己定义拼装的积木”。你不用等某个 SaaS 厂商开发出你想要的功能自己写个技能、拖个表格、配条消息链路需求就跑起来了。这套东西后续扩展的深度基本上取决于你愿意投入多少时间去给它堆技能和场景。如果你也正在 Windows 上折腾 OpenClaw希望这篇记录能帮你少踩几个我踩过的坑。
