最近我折腾完OpenClaw在Windows上的部署把飞书作为主要消息入口整体体验相当顺。这篇就把10分钟的搭建路径完整过一遍环境是Windows 11 Node.js 飞书自建应用本地模型和云端API都能接按步骤走基本不会卡壳。先说结论OpenClaw本身是一个开源的AI助手智能体框架它不依赖特定的云端服务而是把模型调用、消息渠道、技能扩展这些能力封装成插件化的模块。你可以在Windows上跑服务端通过飞书机器人跟它对话让它帮你查资料、整理信息、执行一些自动化任务。适合的人群很明确已经在用飞书办公、又不想把对话记录散落在各个网页端的人以及希望有一个能接本地模型的私人助手、但不想折腾复杂服务器的人。这篇教程不需要你有深厚的编程基础懂一点命令行就够。1. 项目概述与部署思路1.1 OpenClaw到底是什么能做什么OpenClaw本质上是一个“AI代理运行时”它做的事情可以用一句话概括把大语言模型接到真实的消息渠道和工具链上。也就是说你可以把它理解成一个中间层左边连着模型云端API或本地Ollama右边连着各种使用场景飞书、命令行、Web界面。它提供了消息收发、会话管理、技能调用、文件读写这些基础能力让模型不只是“聊天”而是能真正帮你处理实际事务。举例来说我把飞书机器人拉进一个群之后可以直接在群里发“帮我整理一下今天收到的需求文档提取重点”OpenClaw会调用文本处理技能读取文档内容再通过模型生成摘要最后把结果发回群里。再比如你可以在飞书私聊里让它“查一下某个目录下的文件清单”它会执行本地命令并把结果格式化返回。这些能力并不是模型自带的而是OpenClaw通过“技能”机制把它们串起来的。我最初关注这个项目是因为它支持多平台消息源包括Telegram、Discord、飞书等而且模型接入层做得比较干净想换模型只需要改配置不用改代码。对于Windows用户来说它不需要你把整个服务跑在虚拟机或远程服务器上本地直接起服务就能用这对个人使用场景非常友好。1.2 为什么选Windows飞书这个组合选择Windows作为部署环境主要是因为它覆盖了绝大多数普通用户的日常设备。很多人手头只有一台Windows笔记本没有Linux服务器也不想额外购买云主机那在Windows上本地跑OpenClaw就是最省事的方式。另一个原因是OpenClaw对Windows的原生支持做得不错Node.js跨平台消息渠道的连接走的是Webhook和WebSocket不依赖特定系统特性所以Windows下运行很稳定。选择飞书作为消息入口则是从实际使用场景出发的。飞书在国内办公场景覆盖率很高而且它的机器人机制比较完善支持事件订阅、发送消息、上传文件等能力。相比Telegram需要特殊网络环境飞书在局域网和公网环境下都能顺畅使用配置起来也不用额外处理网络问题。如果你所在团队本来就用飞书那把OpenClaw接入飞书后等于在团队协作工具里多了一个AI助手入口日常使用成本非常低。整体部署链路大概是这样的OpenClaw服务端在Windows上监听飞书事件回调飞书机器人收到用户消息后通过事件订阅推送给OpenClawOpenClaw将消息传给配置好的大模型处理拿到回复后再通过飞书API发回对话窗口。链路不算复杂关键点在于飞书应用配置和OpenClaw环境变量设置这两块。2. 环境准备与依赖安装2.1 Node.js版本选择与安装注意事项OpenClaw基于Node.js开发对版本有明确要求。按照项目文档的说明建议使用Node.js 20或更高版本我用的是20.11 LTS运行非常稳定。这里特别提示一下不要使用Node.js的奇数版本比如19、21这些非LTS版本有些依赖包在奇数版本上会出现兼容性问题排查起来很浪费时间。下载地址直接去Node.js官网选择“Prebuilt Installer”的Windows Installer.msi格式。安装时有一点需要留意安装向导里有一个“Add to PATH”的选项默认是勾选的务必保持勾选状态否则后续在PowerShell里执行node命令会提示“无法识别”。安装完成后打开一个新的PowerShell窗口执行node -v和npm -v两条命令确认版本。这里补充一个我踩过的坑如果你之前装过旧版Node.js建议先卸载干净再装新版因为旧版本残留的环境变量可能会导致新版本无法正常工作。另外安装完成后如果PowerShell还是识别不了node命令可以手动检查系统环境变量里有没有C:\Program Files\nodejs\这个路径没有就手动加上。2.2 WSL2与Docker是否需要安装网上很多教程会提到安装WSL2和Docker这是因为OpenClaw在某些运行模式下会调用Linux子系统的能力。但根据我的实际测试纯Windows环境下OpenClaw的核心功能已经可以正常运行所以WSL2和Docker并不是必选项而是可选项。什么时候需要装WSL2如果你计划使用一些依赖Linux环境的技能插件或者在Windows上需要同时运行Linux版本的工具那么建议装上WSL2。安装方式很简单以管理员身份打开PowerShell执行wsl --install然后重启电脑系统会自动完成Ubuntu子系统的安装。安装完成后在PowerShell里执行wsl --status如果显示的是“默认版本2”说明WSL2已经就绪。Docker的情况类似如果你不想在宿主机上直接跑服务而是希望通过容器方式隔离环境那么可以装Docker Desktop。但需要注意Docker Desktop在Windows上默认使用WSL2后端所以要先装WSL2才能正常运行。对于只想快速体验OpenClaw的用户我的建议是先不装WSL2和Docker用原生Node.js方式跑通核心功能之后再按需补充。2.3 获取OpenClaw源码与安装依赖获取OpenClaw源码最简单的方式是从GitHub克隆仓库。在你想存放项目的目录下比如D:\projects打开PowerShell执行以下命令git clone https://github.com/openclaw/openclaw.git cd openclaw npm installnpm install这一步会根据package.json下载所有依赖包耗时取决于网络情况一般在2到5分钟之间。安装完成后检查node_modules目录是否存在确认依赖安装成功。如果npm install过程中出现权限报错比如EACCES可以尝试在PowerShell中右键选择“以管理员身份运行”再执行一次。如果是网络超时导致的失败可以设置npm镜像源执行npm config set registry https://registry.npmmirror.com后再重新安装实测下载速度提升明显。依赖安装完成后项目根目录下会有一个.env.example文件这是环境变量模板。我们需要复制一份并重命名为.env然后开始配置。3. 飞书机器人接入配置3.1 创建飞书自建应用与启用机器人飞书机器人的创建在飞书开放平台上完成。打开飞书开放平台网站登录后进入“开发者后台”点击“创建企业自建应用”填写应用名称和描述名称建议包含“OpenClaw”关键词方便后续识别。应用创建成功后进入应用详情页。第一步是启用机器人能力在“应用能力”菜单下找到“机器人”点击启用按钮。这一步很关键只有启用了机器人能力这个应用才能收发消息。接下来需要记录两个核心凭证App ID和App Secret。在“凭证与基础信息”页面中可以看到这两个值先把它们复制到一个临时文本文件中后面配置OpenClaw环境变量时会用到。App ID是应用唯一标识App Secret是应用的密钥这两个值要妥善保管不要泄露到公开渠道。3.2 配置事件订阅与消息回调地址飞书机器人能够收到用户消息依赖事件订阅机制。开发者在飞书开放平台配置一个回调URL当用户给机器人发消息时飞书服务器会把消息事件推送到这个URL。OpenClaw会启动一个HTTP服务来接收这些事件所以我们把回调URL指向本机OpenClaw服务的地址。具体配置路径在飞书开放平台应用详情页中找到“事件订阅”菜单选择“使用订阅方式”中的“将事件发送至开发者服务器”然后在“请求地址”栏填入回调URL。如果你是在本地运行OpenClaw且没有公网IP那么需要使用内网穿透工具来暴露本地端口或者先使用飞书开放平台提供的“调试”功能来模拟事件推送。这里我踩过一个比较深的坑飞书对回调URL的校验很严格。你在保存事件订阅时飞书会往回调URL发送一个challenge验证请求OpenClaw需要正确响应这个请求才能通过校验。不过新版OpenClaw在启动后会默认处理这个逻辑你只需要确保回调URL能正常访问到本机的OpenClaw服务端口就行。在“事件订阅”菜单中还需要添加需要订阅的事件。要接收用户消息必须添加“接收消息”事件它的标识通常是im.message.receive_v1。添加完成后在“权限管理”中开通im:message和im:message:send_as_bot两个权限一个是读取消息一个是以机器人身份发送消息。3.3 OpenClaw环境变量中的飞书配置现在把前面拿到的凭证填入OpenClaw的.env文件。用编辑器打开.env找到飞书相关的配置项按以下格式填写# 飞书配置 FEISHU_APP_IDcli_xxxxxxxxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxx FEISHU_VERIFICATION_TOKENxxxxxxxxxxxxxxxx FEISHU_ENCRYPT_KEY其中FEISHU_VERIFICATION_TOKEN在飞书开放平台的“事件订阅”页面中可以找到如果你没有额外设置加密策略FEISHU_ENCRYPT_KEY留空即可。配置完成后保存文件然后启动OpenClaw服务飞书机器人就能接收消息了。这里有一个需要注意的细节OpenClaw的飞书适配器默认监听的端口是8080回调URL对应的是http://你的地址:8080/webhook/feishu。如果你在飞书开放平台配置的回调URL末尾路径与这个不一致会导致事件推送失败。我建议在配置回调URL时路径统一使用/webhook/feishu。4. 启动与模型接入4.1 启动OpenClaw服务在项目根目录下执行启动命令默认的启动方式如下npm run start如果看到类似Server is running on port 8080的日志输出说明服务已经启动成功。这里建议在启动前先检查一下.env中的模型配置是否已经填写完整否则服务虽然能启动但对话时会报错找不到模型。启动时会自动初始化数据库和技能目录Windows下首次启动可能会弹出防火墙提示记得勾选“允许访问”否则飞书服务器无法访问到本机端口。这一点容易被忽略我见过很多人在启动后虽然日志正常但飞书消息一直推不进来排查半天发现是防火墙拦截了端口。4.2 接入云端模型APIOpenClaw支持多种模型提供商最常见的两种是Anthropic Claude和OpenAI。在.env中模型相关配置如下# 模型提供商配置 LLM_PROVIDERanthropic ANTHROPIC_API_KEYsk-ant-xxxxxxxxxxxxxxxx CLAUDE_MODELclaude-sonnet-4-20250514这里的选择逻辑很直接如果你已经有Anthropic的API Key那直接用Claude模型它在复杂指令理解和工具调用方面表现最好如果还没有可以把LLM_PROVIDER改成openai填入OpenAI的API Key模型名填gpt-4o或gpt-4o-mini都可以。配置完成后重启服务使配置生效。需要特别说明的是模型API Key属于敏感信息不要在飞书群里直接展示.env内容。另外OpenClaw支持同时配置多个模型提供商通过对话中的命令切换模型这个我在后面的进阶部分会展开。4.3 接入本地模型Ollama Qwen如果你不想购买云端API额度或者对数据隐私有要求可以使用Ollama在本地跑开源模型。先安装Ollama客户端然后下载模型以Qwen2.5系列为例ollama pull qwen2.5:7b模型下载完成后Ollama默认启动在http://localhost:11434。接着在OpenClaw的.env中做如下配置LLM_PROVIDERollama OLLAMA_BASE_URLhttp://localhost:11434 OLLAMA_MODELqwen2.5:7b然后重启OpenClaw服务在飞书里发一条消息测试如果回复正常说明本地模型已经成功接入。本地模型的优势在于零成本、响应速度快缺点是能力上限比云端模型低一些复杂任务的处理效果会有差距。我的建议是日常简单任务用本地模型复杂分析切换到云端模型。4.4 在飞书里验证AI助手对话完成以上配置后在飞书中找到你创建的机器人发起私聊或拉入群聊。发送第一条测试消息比如“你好介绍一下你自己”正常情况下会在几秒内收到机器人的回复。如果消息发出后迟迟没有回应按以下顺序排查先看OpenClaw的终端日志有没有收到事件推送记录如果没有说明飞书回调没到检查回调URL和端口是否畅通如果有事件记录但报错把错误信息贴到搜索工具里查大多数情况下是权限没开或事件订阅类型不对。测试通过后可以尝试一些稍微复杂的指令比如“帮我计算25乘以17加3等于多少”看看模型是否具备基础数学能力。这一步的目的是验证模型调用链路是否完整因为有些时候消息收发是正常的但模型配置错误回复会报错或超时。5. 常见问题与排查技巧实录5.1 WSL2相关报错处理热词里提到的openclaw无法安全验证sl2环境。请在powershell中运行wsl-- status这个报错通常出现在系统检测到WSL2未正确安装或版本不对时。先按提示在PowerShell中执行wsl --status查看输出内容。如果提示WSL 1而不是WSL 2需要手动设置默认版本执行wsl --set-default-version 2。如果提示未安装适用于 Linux 的 Windows 子系统则执行wsl --install后重启电脑。还有一种特殊情况Windows系统版本较旧不支持WSL2这时需要更新系统到Windows 10 2004以上版本或Windows 11。这里我有一个实用建议如果你不需要用WSL2就不要让OpenClaw尝试调用它。检查.env里有没有类似USE_WSL2true的配置项如果有改成false就能跳过WSL2检测。5.2 Node.js版本与依赖安装失败依赖安装失败是最常见的启动前问题。npm install时报ERESOLVE错误通常是依赖版本冲突可以尝试在命令后面加--legacy-peer-deps参数npm install --legacy-peer-deps如果报错信息中出现node-gyp或python相关字样说明某些原生模块需要编译环境。解决办法是安装Windows Build Tools在PowerShell中执行npm install --global windows-build-tools。这个包比较大下载耗时较长耐心等待即可。启动时报Error: Cannot find module说明依赖缺失先执行npm install补齐依赖。如果确认依赖完整还是报错可以删除整个node_modules目录和package-lock.json文件重新执行npm install --legacy-peer-deps。5.3 飞书事件订阅回调失败飞书开放平台保存事件订阅时提示“URL校验失败”这个问题出现率很高。原因通常是回调URL无法从外网访问或者服务没有启动。先确认OpenClaw服务正在运行再用浏览器访问一下回调URL看是否能打开页面。如果打不开检查防火墙端口设置。如果没有公网IP本地服务无法被飞书服务器访问就需要内网穿透。这里我想提醒一下选择内网穿透工具时注意合规使用确保工具和用途符合相关规定。配置内网穿透后把飞书回调地址填成穿透工具提供的公网URL路径仍然指向/webhook/feishu。配置过程中如果反复出现校验失败飞书开放平台会自动在“事件订阅”页面标记错误原因比如“请求超时”“返回内容不匹配”等按提示逐项排查即可。5.4 Docker守护进程与端口占用如果你选择了Docker方式运行OpenClaw启动时可能会遇到error: start the windows daemon from a non-elevated terminal这类提示。这个报错的意思是Docker守护进程没有在管理员终端中启动解决办法是右键点击Docker Desktop图标选择“以管理员身份运行”然后重启服务。端口占用问题在Windows下也很常见尤其是8080端口。如果启动时提示Port 8080 is already in use需要先找到占用端口的进程并释放netstat -ano | findstr :8080 taskkill /PID 这里填PID /F第一行命令会列出占用8080端口的进程PID第二行强制结束该进程。执行完后再重新启动OpenClaw即可。如果你希望OpenClaw使用其他端口可以修改.env中的端口配置同时记得更新飞书回调URL中的端口号。6. 实测体验与进阶配置建议6.1 10分钟真的能完成吗按照我这边的实测从零开始到飞书机器人能正常对话在一切顺利的情况下确实可以在10分钟内完成。时间分配大概是下载安装Node.js约2分钟克隆项目加安装依赖约3分钟飞书开放平台创建配应用约3分钟启动服务加验证对话约2分钟。如果中途遇到问题10分钟肯定不够用。但不要着急第一次搭建本来就是熟悉流程的过程后面清理重建就会快很多。我建议第一次搭的时候先把飞书应用配置好再回头处理依赖安装这样两边可以并行思考不容易卡在同一个环节上。另外提一个效率技巧把.env文件里的配置项按“模型相关”“飞书相关”“技能相关”分组保存成模板下次重新部署的时候直接套用模板可以省去重新填写的时间。我自己的配置模板已经固化下来了换机器的时候十分钟内就能恢复完整环境。6.2 Skill机制与多模型切换OpenClaw的“技能”机制是它比较好用的功能之一。技能实际上是一些预定义的指令模板和工具函数模型可以根据对话内容自动调用。目前社区里有现成的技能库包括文档处理、网页抓取、时间管理、代码执行等场景。启用技能的方式很简单把技能文件放到项目的skills目录下重启服务后模型会在收到相关指令时自动加载。比如我想让OpenClaw支持“查询天气”下载一个天气查询技能包放到skills目录重启后在飞书里发“查一下今天北京天气”它会自动调用技能获取数据并格式化返回。多模型切换是我觉得OpenClaw做得比较顺手的地方。在对话中发送/model ollama可以切换到本地Ollama模型发送/model claude切回Claude模型。这个功能在需要对比不同模型输出效果时非常实用特别是当云端API临时不可用时一键切到本地模型不影响继续使用。6.3 飞书群聊场景与权限控制把OpenClaw机器人拉到飞书群里使用时建议先设置好群聊权限。在飞书群设置中可以将机器人设置为“仅管理员可”避免群里所有人都来调用AI导致资源浪费。如果机器人在群里对所有人可见最好在对话中约定一个触发前缀比如需要管理员发“AI”开头的消息才会响应。在OpenClaw侧也有权限控制的配置项。.env中有一个ALLOWED_USERS参数可以填写允许与该机器人交互的飞书用户ID列表多个ID用逗号分隔。配置后白名单以外的用户发消息给机器人会被自动忽略。对于企业场景这个配置是必选项能有效防止未授权使用。6.4 Windows开机自启与后台运行最后分享一个让OpenClaw在Windows上更省心的配置方式。如果你想让它像后台服务一样启动可以在PowerShell中创建计划任务设置计算机启动时自动运行OpenClaw启动命令。具体操作打开“任务计划程序”创建基本任务触发器选择“计算机启动时”操作选择“启动程序”程序填C:\Program Files\nodejs\node.exe参数填项目路径\dist\index.js或者根据你实际启动脚本填写起始目录填项目根目录。设置完成后每次开机OpenClaw都会自动在后台运行不需要手动开终端。我实际使用中遇到过一个问题计划任务运行的用户如果没有管理员权限可能会无法监听8080端口。解决方法是把计划任务设置为“不管用户是否登录都要运行”并勾选“使用最高权限运行”。设置完成后可以重启电脑验证一下是否自动生效。这个项目在Windows上的日常体验比我预想中稳定飞书作为消息入口也很贴合办公习惯。如果你有闲置的个人电脑或旧笔记本完全可以把它变成一台24小时在线的私人AI服务节点配合计划任务使用日常随手在飞书里就能调用AI能力。搭建过程中遇到具体问题按第五节的排查思路逐项处理基本都能顺利解决。