最近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.com@g' /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] memory=8GB processors=4 swap=8GB然后wsl --shutdown再重新进系统生效。这里有个容易忽略的点：WSL2默认内存上限是宿主机的一半，你如果不指定，跑大模型的时候很容易OOM，导致OpenClaw异常退出。另外还要开启systemd支持，在WSL2里编辑/etc/wsl.conf：
[boot] systemd=true这样后面就可以用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.conf：
nameserver 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和Docker
OpenClaw的官方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由于前面开启了systemd，Docker服务可以随系统启动自动拉起。如果你没开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 坑位2：DNS解析异常导致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 坑位4：Windows重启后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接飞书这个组合，目前对我来说已经成了日常工作流里不可缺的一环，不只是聊天，还承担了一些表格整理和文档同步的活。建议你在跑通基础消息后，优先加一两个自己实际用得到的技能，比如飞书多维表格查询或者云盘文件同步。至少对你来说，从“能回复”到“能干一点活”，是用这个项目最有意思的跨度。
