最近OpenClaw在AI圈子里热度确实高很多人想把它跑起来当个人助理结果翻官方文档发现主要是Linux和macOS的玩法Windows用户只能绕路。我主力机就是Windows最后选择WSL2装Ubuntu把OpenClaw装好、飞书机器人接入也一并跑通了。本文会把这个从零到一的过程完整还原出来包括WSL2环境准备、OpenClaw本体安装、Ollama本地模型接入、飞书企业自建应用配置、长连接通道联调以及我实际踩过并且印象深刻的几个坑。不管你是第一次接触WSL2的新手还是想把OpenClaw接到飞书工作流里的老手都可以按着这套步骤走少折腾几小时。1. WSL2环境准备为什么我坚持用Ubuntu 24.04而不是Windows原生跑1.1 OpenClaw对Linux生态的依赖OpenClaw本质上是一个常驻的服务型AI代理框架它要长期监听消息、执行技能、调用外部工具这些行为都依赖Linux的进程模型、文件权限体系以及一套完整的容器运行环境。你可以把它理解成一只爪子下面还要挂很多小工具工具之间用文件系统和标准输入输出来协作这种设计在Linux下最顺手。Windows原生环境不是不能跑但会遇到很多离谱问题npm包里的原生模块在Windows上编译不过、路径分隔符带来的配置解析错误、Docker Desktop那层额外的Hyper-V虚拟化又经常把网络搞得乱七八糟。我之前试过直接在Windows上用Docker Desktop跑OpenClaw镜像倒是能拉下来但容器内的Linux路径和Windows文件系统映射之间总有一种割裂感日志里全是权限不对、fork失败这类报错。换到WSL2之后这些问题几乎全部消失。WSL2给的是一个完整的真实Linux内核且不是模拟层所以OpenClaw在Linux服务器上什么样在WSL2里就什么样。后面你要把这套东西迁移到云主机命令和配置可以原样照搬迁移成本几乎为零。1.2 三步把WSL2环境盘到位第一步是确认Windows版本和WSL功能状态。Windows 10 2004以上或者Windows 11都可以推荐直接用管理员身份的PowerShell运行wsl --install -d Ubuntu-24.04这个命令会自动开启需要的Windows功能并安装指定发行版。如果它提示需要重启就重启一次。装完之后用下面几个命令确认状态wsl --update wsl -l -v正常会看到Ubuntu-24.04状态的VERSION为2。如果你的版本还是1或者状态显示“正在安装”多半是Windows老版本不支持WSL2需要手动开启“适用于Linux的Windows子系统”和“虚拟机平台”两个功能再重启。这一步网上教程很多但要注意Windows 11的wsl --install装的是默认Ubuntu不一定是24.04所以把发行版参数显式写出来更稳妥。第二步是进系统后的基础优化。首次进入时系统默认源是国外源下载速度会很痛苦这也是热词里“wsl2下载慢”的来源。先换源再升级sudo sed -i s//.*archive.ubuntu.com//mirrors.aliyun.comg /etc/apt/sources.list sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git build-essential python3 python3-pip把基础编译工具装好后面装Node、原生模块、Python依赖的时候能省很多事。你如果喜欢清华源把mirrors.aliyun.com替换成mirrors.tuna.tsinghua.edu.cn就行。第三步是调优WSL2的资源配置。OpenClaw常驻运行还要带上Ollama这种本地模型服务内存会吃得很厉害。在Windows用户目录下新建一个.wslconfig文件写入[wsl2] memory8GB processors4 swap8GB然后wsl --shutdown再重新进系统生效。这里有个容易忽略的点WSL2默认内存上限是宿主机的一半你如果不指定跑大模型的时候很容易OOM导致OpenClaw异常退出。另外还要开启systemd支持在WSL2里编辑/etc/wsl.conf[boot] systemdtrue这样后面就可以用systemctl管理Docker和OpenClaw服务而不是每次登录都要手动启动进程。1.3 网络与时钟的隐藏问题WSL2走的是NAT网络默认DNS是自动生成的/etc/resolv.conf但Windows宿主机的DNS经常会在睡眠恢复后出现解析异常表现就是WSL里apt update偶尔报域名解析不了curl外网API也超时。这个坑非常隐蔽也很适合提前处理。比较干净的方式是关闭自动生成并固定DNS。在/etc/wsl.conf的[network]段加一行generateResolvConf false然后手动写/etc/resolv.confnameserver 223.5.5.5 nameserver 114.114.114.114注意设置完后重启WSL否则文件会被自动覆盖回来。另外还有一个和时钟相关的坑。WSL2在宿主机休眠后可能发生时钟漂移如果OpenClaw去请求LLM的API或者连飞书长连接签名校验会对时间戳做严格比对时间差几十秒就会直接鉴权失败。所以建议顺便开启systemd-timesyncd同步sudo timedatectl set-ntp true这些基础细节看着不起眼但都是影响后面OpenClaw稳定运行的关键前提。我把时间调好之后再连飞书长连接基本没断过。2. OpenClaw本体安装CLI和Docker Compose两条路径的实测选择2.1 先装运行时Node 20 LTS和DockerOpenClaw的官方CLI是基于Node.js生态的装之前先保证Node版本够新。我在WSL2里用的是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 -v确认。顺便把npm默认源切到国内镜像安装依赖会快很多npm config set registry https://registry.npmmirror.comDocker方面WSL2里直接用官方脚本装curl -fsSL https://get.docker.com | sh sudo systemctl enable docker --now由于前面开启了systemdDocker服务可以随系统启动自动拉起。如果你没开systemd就需要每次进WSL之后执行sudo service docker start比较容易漏所以我不太推荐那种方式。装好后用docker run hello-world验证一下。2.2 按官方CLI方式安装初始化OpenClaw的包名各版本可能会有调整建议以官方README为准。我自己用的安装命令是全局安装CLI工具npm install -g openclaw/cli安装完成后在工作目录初始化一个实例openclaw init assistant cd assistantinit之后会生成几样东西一个配置文件我当前版本是config.yaml早期版本可能是openclaw.toml、一个skills目录、一个logs目录。skills目录会留着放自定义技能后续给机器人加上发表格、查待办这些能力都会用到。装完我建议先跑一下openclaw doctor做环境自检。这个命令会检查Node版本、配置文件格式、API Key有没有配置、技能目录权限是否正常。如果自检通过再启动能省掉很多启动报错的排查时间。2.3 Docker Compose方式的取舍官方仓库里通常也会带一份docker-compose.yml里面除了OpenClaw服务可能还会包含数据库之类的依赖。如果你打算长期挂机跑推荐用Compose方式git clone https://github.com/你的仓库地址/openclaw.git cd openclaw docker compose up -dCompose的好处是依赖干净、升级方便换台机器直接docker compose up就全部拉起。缺点是调试不太直观日志要进容器里看改配置之后要重启整个容器栈。我的建议是先用CLI模式把整个链路跑通把飞书和模型都调好再切到Compose做常驻。CLI模式看到日志更直接报错也更容易定位。2.4 首次启动与LLM Provider配置首次启动前需要先配置大模型服务商。OpenClaw支持OpenAI兼容接口和本地Ollama。如果用云端API在.env文件里写入OPENAI_API_KEY你的密钥然后用openclaw start启动。第一次跑会看到控制台输出启动日志包括加载了几个skill、渠道有没有连上。如果看到类似“channels loaded”说明启动成功下面就要处理飞书渠道。如果暂时没有飞书也可以用CLI模式直接对话测试模型通不通openclaw chat输入“你好”模型有正常回复说明LLM链路已经通了。这一步尽量在接飞书之前验证否则后面集成时出现问题你很难分清是模型没配好还是飞书通道没配好。3. 本地模型接入把Ollama配好AI调用才算真正闭环3.1 为什么在WSL2里装Ollama我选择本机Ollama不只是为了省钱。外部API调用要依赖公网出口而WSL2的NAT网络在某些情况下访问公网并不稳定超时一次OpenClaw就会报错。本地模型就没有这个困扰数据不出本机请求延迟也低。热词里那么多“ollama部署openclaw”的搜索说明很多人都在走这条路至少说明这个方案可行度和可参考性都很高。Ollama在WSL2里安装很简单curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7b ollama serveollama serve会启动一个本地服务默认监听127.0.0.1:11434。我选了qwen2.5:7b这个模型理由是它对中文支持好并且工具调用能力在这个参数级别里算不错的。OpenClaw要执行技能、解析结构化输出模型太弱会很痛苦。3.2 在OpenClaw配置里指定本地模型在config.yaml中修改模型配置ai: provider: ollama base_url: http://127.0.0.1:11434 model: qwen2.5:7b context_length: 8192注意provider字段名不同版本可能不一样有的版本叫llm有的版本叫model_provider填的时候对照当前配置文件的注释看。配置完后重启OpenClaw再执行openclaw chat验证。如果请求超时先检查curl http://127.0.0.1:11434/api/tags能不能返回模型列表。如果这边通OpenClaw仍然超时就要去看OpenClaw日志里的完整错误信息通常是字段名写错了或者模型名对不上。3.3 显存与性能调整WSL2里用NVIDIA显卡跑Ollama需要Windows 11的GPU虚拟化支持。进WSL2后运行nvidia-smi如果能看到显卡信息说明GPU直通正常。如果看不到Ollama就会退回CPU模式7B模型也能跑就是响应慢一些群聊里体验会打折扣。这种情况下可以考虑换qwen2.5:3b或者把上下文长度调低一点。这里还有个参数值得注意环境变量OLLAMA_CONTEXT_LENGTH。默认是4096如果OpenClaw的技能输出较长很容易截断。我设置成了8192超出后会明显占更多显存根据自己的显卡显存大小来权衡。跑通之后OpenClaw就不依赖任何公网API整个链路在局域网内就能自闭环后面排查飞书问题的时候也少一个变量。4. 飞书开放平台配置企业自建应用的三步走与权限陷阱4.1 创建应用并拿到App ID和App Secret飞书接入是OpenClaw渠道配置必须的一环。先登录飞书开放平台路径是open.feishu.cn进入开发者后台然后创建企业自建应用。注意企业自建应用和商店应用的区别是自建应用只对本企业可见审批速度快个人折腾完全够用。创建时需要填应用名称和图标随后来到“凭证与基础信息”页面这里有两个关键信息App ID和App Secret。App Secret只有创建时完整显示一次之后只能重置所以拿到后立刻存到本地密码管理器里。这一步如果漏了后面OpenClaw连接飞书时只能反复报“auth failed”还没法直接看到原因。如果你所在企业没有开放开发者权限创建应用时可能会提示“请联系管理员开通”。个人使用的话用自己的企业试用版就行或者让IT管理员帮忙开一个沙箱企业。4.2 开启机器人和消息权限创建应用后进入“添加应用能力”把“机器人”能力打开。这一步不做后面OpenClaw连上飞书也没办法收发消息。接下来是权限配置。飞书开放平台的权限点非常多我只开了最基础的三个im:message:receive用于订阅接收消息事件im:message:send_as_bot允许机器人发消息im:chat:readonly用于读取群基础信息权限开通后在飞书后台会生效但很多企业配置里还要“发布版本”才能让权限真正作用到线上版本。企业自建应用通常秒过发布后记得在版本详情里确认机器人已启用。4.3 事件订阅一定要选长连接而不是Webhook这步是全流程里最容易做错的地方也是我把WSL2选为部署环境的核心理由。飞书开放平台的事件订阅方式主要有两种一种是传统的Webhook回调需要公网HTTPS地址另一种是长连接方式客户端主动和飞书建立WebSocket连接。对于WSL2环境来说完全没法选Webhook——WSL2在NAT后面没有公网地址要暴露端口还得在路由器上做端口映射非常麻烦。长连接就没这个问题客户端主动外联不需要公网入站端口。操作路径是在“事件与回调”页面订阅方式选择“使用长连接接收事件”确认后将“接收消息im.message.receive_v1”事件添加到订阅列表。之后只需要在代码里用飞书官方SDK建立长连接客户端就能实时收到群消息和私聊消息。这个模式的另一好处理顺带解决了开发调试问题不用配置HTTPS证书不用处理飞书回调时的URL验证也不用担心内网穿透服务不稳定。如果你看过其他教程让用feishu-webhook或者ngrok方案在WSL2场景下可以直接跳过。5. 把飞书通道接进OpenClaw长连接模式与配置文件逐字段解释5.1 配置文件结构channels段OpenClaw把各种即时通讯渠道统一抽象成了channels配置。以我一个版本的config.yaml为例飞书相关的配置段大概长这样channels: feishu: enabled: true app_id: cli_xxxxxxxxxx app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxx mode: websocket reconnect: true ack_mode: auto我逐个解释一下每个字段的意思。mode: websocket就是使用飞书长连接模式这个必须和飞书开发者后台的事件订阅方式保持一致否则连接会被拒。reconnect: true控制断线重连长连接在网络切换、休眠恢复后有概率断开自动重连非常关键。ack_mode: auto表示消息确认机制飞书推送事件后OpenClaw会返回ack如果没收到ack飞书会重试推送自动ack能避免消息被重复处理。如果你下载的版本配置文件里没有feishu字段就手动加上这一段并确认在文件的channels同级结构中不要嵌套到其他渠道下面。我之前就见过有人把飞书配置写进了telegram下导致启动时飞书根本没加载。5.2 启动观察连接日志配置好之后执行openclaw restart。正常情况日志里会看到类似“feishu channel connected”的输出然后每隔几分钟会有一次心跳日志。如果连接失败优先检查三件事App ID和App Secret是否填反飞书后台“长连接”是否真的启用权限点是否已经发布生效。可以多说一句飞书的App ID是一定以cli_开头的App Secret是一串很长的随机字符串。如果配置里看到两边值长得差不多八成是字段写错了。调试时把OpenClaw日志级别调成debug重启后能看到比较完整的推送事件内容对定位问题很有帮助。5.3 Skills扩展让机器人会“发表格”OpenClaw真正值钱的地方在skills。热词里经常有人搜“飞书机器人发送表格”“openclaw skill”正是因为这些技能可以让机器人不只是聊聊天而是真正做一些结构化输出。skills目录下每个技能通常是一个文件夹里面有一个描述文件和一个可执行脚本。描述文件告诉模型“这个技能在什么情况下触发、有什么参数”脚本负责真正干活。给飞书机器人加一个“发送表格”技能思路是机器人收到用户的意图技能脚本从数据源读取内容调用飞书API发送一条富文本卡片或消息并把数据格式化后呈现到群聊里。从技术形态上讲飞书本身支持消息卡片OpenClaw可以直接把卡片的JSON结构作为消息内容发送。我在实际使用中给机器人加了一个轻量技能用户说“把本周todo发成表格”它从每周计划中读取数据用Python生成一个二维数组然后通过飞书API的im:message接口以消息卡片发到群里。效果很直观原本需要写脚本或者手动整理的事在群里发一句话就完成。这个方向你可以根据自己的场景扩展比如接飞书多维表格、云文档同步甚至把热词里提到的“Lark Sync同步飞书云盘到Obsidian”做成一个技能让机器人定时拉取云盘文件并同步到本地笔记。6. 联调验证与四个常见故障的排查记录6.1 从飞书到AI再到飞书的完整链路验证飞书通道配好后先在一个测试群里把机器人拉进来然后机器人发送“你好”。正常情况下OpenClaw日志里会依次出现收到消息事件、调用模型、模型返回内容、发送消息成功、消息确认ack。看到这一串日志说明链路已经全通。接下来可以测一个复杂任务比如让机器人“计算23乘以37”。这个看似简单的任务包含了模型推理工具调用如果模型配置有问题这里就会暴露。然后测技能发一条“把今天的时间段整理成表格发到群里”看消息卡片有没有正确出现。飞书机器人发送表格这个能力实测下来最关键的是权限点im:message:send_as_bot没这个权限机器人会返回“操作被拒绝”。6.2 坑位1时钟漂移导致飞书签名鉴权失败现象是飞书长连接能建立但每隔几秒就断开日志里出现签名验证失败或时间戳错误。当时我看了半天配置最后用date命令一查发现WSL2的时间比宿主机晚了将近1分钟。飞书的WebSocket连接握手会校验客户端签名时间戳时间偏差超过一定范围直接拒绝连接。解决办法就是前面提到的开启systemd-timesyncd或者每次启动WSL后执行一次sudo hwclock -s。这个问题在Windows笔记本上特别容易触发因为睡眠唤醒会打断时间同步。6.3 坑位2DNS解析异常导致AI模型请求超时另一个很阴间的坑是飞书消息能收到但OpenClaw回复“调用LLM超时”。日志显示请求发出去了但没有响应。先用curl -I https://模型API域名测一下连通性如果超时大概率是DNS解析问题。WSL2自动生成的/etc/resolv.conf会指向Windows宿主机上的DNS而宿主机的DNS在多次网络切换后经常解析失败。按照第一节的方法固定DNS并关闭自动生成之后问题立刻消失。如果你用的是Ollama本地模型这个问题基本不存在因为请求走的是回环地址。6.4 坑位3机器人自我对话死循环有一次群里突然出现了大量机器人消息全是它自己在回复自己。原因是群里的另一个业务机器人发了一条消息OpenClaw也订阅了接收消息事件然后模型把这条消息当成了用户指令于是一来一回停不下来。解决方案是在配置里对消息来源做过滤只处理发送者为真实用户且explicitly本机器人的消息。飞书后台也有一个选项可以控制“机器人是否接收其他机器人的消息”关掉能从根本上解决大部分循环问题。如果OpenClaw配置中支持自定义过滤条件建议写清楚判断逻辑sender ! bot content has mention。这个坑在把机器人和业务群打通时几乎必踩早处理早安心。6.5 坑位4Windows重启后OpenClaw没有自动恢复WSL2的systemd不会随着Windows开机自动启动所以如果只是开了systemd重启Windows后OpenClaw不会自动拉起。我在WSL内配置了一个openclaw.service的systemd单元然后通过Windows的计划任务把下面这行命令设为开机执行wsl -d Ubuntu-24.04 -- systemctl start openclaw如果你不想折腾计划任务社区提到的“OpenClaw Windows Companion”工具也可用它能管理Windows下的OpenClaw实例但本质上还是需要在启动时拉起WSL。我个人更喜欢systemd的方案一来和云服务器部署习惯一致二来系统集成度更高日志可以直接用journalctl -u openclaw查看。这四个坑踩完之后这套组合的稳定性已经相当不错我连续跑了一周没有发生过一次断线。最后说点个人习惯。我把OpenClaw拉进了一个专门的“助手群”日常不打扰真有需求就在群里一下。这样能有效控制消息量也便于排查问题。OpenClaw接飞书这个组合目前对我来说已经成了日常工作流里不可缺的一环不只是聊天还承担了一些表格整理和文档同步的活。建议你在跑通基础消息后优先加一两个自己实际用得到的技能比如飞书多维表格查询或者云盘文件同步。至少对你来说从“能回复”到“能干一点活”是用这个项目最有意思的跨度。