我是在一个周末的下午决定折腾 OpenClaw 的。起因很简单最近在整理一套本地 AI 工作流想把模型调用和各种小工具脚本收拢到一个框架里OpenClaw 这类项目刚好对上需求。一开始我图省事想在 Windows 上直接跑原生版结果还没走到启动那步就先被路径转义、bash 脚本不兼容、权限位识别不了这些事按在地上摩擦。换到 WSL 之后很多问题直接原地消失。这篇就是我装 WSL、配置 Linux 环境、部署 OpenClaw 的完整复盘把文档不会写的坑单独挑出来讲透。如果你也是 Windows 重度用户又刚好需要跑这类偏 Linux 生态的 AI 工程这篇应该能帮你省下一整个下午。1. 先说思路为什么是 WSL 而不是双系统1.1 OpenClaw 要的其实是 Linux 环境OpenClaw 表面上是一个 AI 代理管理框架但真正跑起来的时候需要的不只是“能执行命令”这么简单。它的核心能力来自技能skills也就是一堆预先写好的脚本这些脚本会用 bash 的进程管理、文件软链接、权限位控制等能力来跟操作系统打交道。Windows 的 cmd 和 PowerShell 不是不能写脚本但很多开源技能的编写前提是“存在 /bin/bash、存在 /usr/bin/python3、存在真正意义上的符号链接”。你在 Windows 里要去模拟这一套要么用兼容层要么就得忍受路径分隔符和权限模型导致的各种诡异 bug。我在原生版 OpenClaw 上遇到的第一个报错就是某个技能脚本执行符号链接操作时把目标路径里的反斜杠当成了转义字符最终的软链接根本不存在。所以问题的本质不在“OpenClaw 能不能支持 Windows”而在“它真正依赖的是一套完整的 Linux 运行环境”。WSL 2 直接把一个轻量级 Linux 内核放在 Windows 底下跑从这个角度看它其实就是为这类项目而生的。与其在 Windows 里对着报错修兼容性不如让项目在自己熟悉的环境里跑。1.2 WSL 2 比虚拟机强在哪里你可能想既然要 Linux 环境为什么不直接装 VMware 或者 VirtualBox我之前也这么想过后来发现虚拟机方案有一个致命问题资源开销。跑 AI 代理框架时经常同时要起 Python 服务、Node.js 服务还可能挂本地模型推理虚拟机把这些进程都塞在同一个 Guest OS 里内存和 CPU 的占用立刻飙升。而 WSL 2 使用轻量级工具通过虚拟化技术提供完整 Linux 内核但启动开销和内存占用都比完整虚拟机小得多而且可以直接读取 Windows 文件系统的内容不用来回切换 IP 地址。另一个很实际的好处是WSL 2 的发行版本质上就是一个文件夹你可以用wsl --export和wsl --import把它打包挪到别的盘甚至可以快速复制一份当作备份再继续折腾。虚拟机虽然也能做到但操作成本明显高一大截。1.3 谁适合这样装说点实在的。如果你只是想在 Windows 上简单体验一下 OpenClaw 的 Web 界面那原生版可能勉强够用前提是你能接受部分技能不可用但如果你打算认真玩技能、做二次开发或者想把它接进自己的自动化流程那 WSL 方案基本是绕不开的。我这次的目标很明确OpenClaw 跑通之后要能通过 Windows 侧的伴生程序Windows Companion做状态监控而且要用 Ollama 作为本地模型后端。这两个需求让我的安装路线基本定死先搭好 WSL 2再在 WSL 里装 OpenClaw最后把 Windows 和 WSL 的服务打通。接下来的内容就是这条完整路线。2. 基础环境搭建WSL 2 从零到能用的完整链路2.1 安装前的软硬件检查动手之前先做三件事能少走很多弯路。第一确认 Windows 版本。WSL 2 对系统版本有要求最好保持在最新的 Windows 11 或者较新的 Windows 10。你可以在 PowerShell 里执行winver查看只要是 21H2 之后的版本一般都没问题。第二确认 CPU 虚拟化已经开启。WSL 2 依赖虚拟化功能如果 BIOS 里把 Intel VT-x 或者 AMD-V 关掉了安装后会出现“WSL 2 需要启用虚拟机平台”这类报错。检查方法很简单任务管理器打开“性能”标签看“虚拟化”这一项是不是“已启用”。第三清理可能冲突的旧版方案。如果你之前装过 Docker Desktop 或者老版本 WSL建议先把它们清理干净免得内核组件冲突。我当时就是机器上残留了一个旧发行版导致wsl --install执行到一半自动回滚。2.2 wsl --install 到底做了什么现在的 Windows 安装 WSL 非常简单不再需要手动下载安装包。打开 PowerShell管理员模式直接输入wsl --install这条命令会自动帮你完成四件事启用“适用于 Linux 的 Windows 子系统”功能、启用“虚拟机平台”功能、下载并安装 WSL 2 内核、安装默认的 Ubuntu 发行版。这里有一个常见的误区命令默认安装的 Ubuntu 版本可能不是你想要的。如果你想装指定版本可以加参数比如wsl --install -d Ubuntu-22.04 wsl --install -d Debian查看当前可用的发行版列表用wsl --list --online装完之后系统会提示你重启。记得重启之后再打开终端因为内核和功能组件需要重新初始化一次。如果执行安装时发现下载速度极慢多半是网络环境对微软服务器不友好不要反复终止重试让它慢慢下完反而更稳。2.3 首次创建用户与换源重启后第一次启动 Ubuntu会进入一个让你创建用户名和密码的交互界面。注意这里的用户名不一定非要跟 Windows 用户名一致完全可以设置成claw或者dev这类简短的名字后面敲命令会少很多手滑的机会。密码方面我建议别设得太复杂因为 WSL 里你几乎每次sudo都要用到它。接下来最关键的一步是换源。默认的 Ubuntu 软件源服务器在国外国内网络环境下执行apt update经常慢到怀疑人生甚至直接超时。所谓“换源”就是把/etc/apt/sources.list或者 Ubuntu 新版本对应的/etc/apt/sources.list.d/ubuntu.sources里的服务器地址换成国内镜像地址。我习惯用清华或者阿里云的镜像操作不复杂先备份原文件再把archive.ubuntu.com全部替换为镜像域名最后执行sudo apt update sudo apt upgrade -y实测下来换源前后apt update的耗时差距非常明显从十几分钟缩到了半分钟以内。这个操作强烈建议在安装任何软件之前做否则你的基础工具链都可能带上缓慢的阴影。2.4 把发行版挪到 D 盘默认情况下 WSL 发行版放在 C 盘用户目录下面OpenClaw 项目动辄几个 GB再加上后续模型文件C 盘很快就扛不住。这里有两种办法。如果发行版还没怎么用可以干脆导出再导入wsl --export Ubuntu D:\wsl-ubuntu.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\OpenClawWSL\ D:\wsl-ubuntu.tar注意wsl --import之后默认会以 root 身份进入系统原来创建的用户需要手动在/etc/wsl.conf里配置或者重新分配权限。所以更简单的思路是在安装完 WSL 之后、还没有密集使用之前就完成这个操作。如果你安装的 WSL 版本支持也可以直接使用wsl --manage Ubuntu --move D:\OpenClawWSL\这个命令会原地迁移发行版目录文件系统里的用户配置和权限都能保住是我更推荐的方式。迁移完成之后别忘了执行一次wsl --shutdown再重新进入确保所有进程都从新位置加载。3. OpenClaw 安装与核心配置3.1 运行时准备Node.js 与 Python进入 WSL 的 Ubuntu 后先确认几个基础工具。OpenClaw 的常见运行依赖是 Node.js 和 Python 3两者缺一不可。我建议不要直接apt install nodejs因为 Ubuntu 自带的 Node 版本通常比较旧。更好的办法是通过 Node 官方源或者 nvm 安装。用户态安装 nvm 最省事curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18Python 方面Ubuntu 22.04 自带 Python 3.10够用。但要注意千万别把系统自带的python3换成别的版本后面很多系统脚本依赖它。如果需要更新版本的 Python可以用社区方案装但不要跟系统 Python 抢位置。这里额外提醒一句装 Node 的时候不要用 sudo。nvm 装的就是当前用户目录下的版本一旦你用真 root 装了一个全局 Node后面项目里的node_modules权限会变得非常混乱删也删不干净。3.2 拉取 OpenClaw 项目在 WSL 里进入你的工作目录比如/home/claw/projects然后克隆 OpenClaw 仓库git clone https://github.com/openclaw/openclaw.git cd openclaw这里有个细节克隆下来的项目默认分支可能是开发版如果你想要稳定版最好先git tag查看版本列表然后git checkout到具体的 tag。因为开发版经常会出现依赖变更我今天装的时候没问题不代表你明天装的时候没问题固定版本能减少变量。之后安装依赖。不同的语言组件可能各自有安装命令常规操作是这样npm install pip install -r requirements.txt如果项目里包含子模块比如技能仓库记得初始化git submodule init git submodule update我一开始就是因为漏了最后两步导致技能目录全空启动后始终找不到内置技能。这是新手最容易踩的坑建议把submodule status的输出看一遍确认里面不是空的再继续。3.3 核心配置文件 openclaw.json 解读安装完成后项目里通常会有一个示例配置文件比如openclaw.example.json。第一次启动前先复制成你的真实配置cp openclaw.example.json openclaw.json下面是我基于这套思路整理出的一个最小可用配置骨架。实际字段名以你拿到的项目文档为准但理解这些字段背后的逻辑比背参数更重要{ name: openclaw-main, runtime: { shell: /bin/bash, python: /usr/bin/python3, node: /usr/bin/node }, model: { provider: ollama, endpoint: http://127.0.0.1:11434, default_model: qwen2.5:7b }, skills_dir: /home/claw/projects/openclaw/skills, server: { host: 0.0.0.0, port: 8080, token: 换成你自己的令牌 }, windows_companion: { enabled: true, host: 127.0.0.1, port: 8787 } }runtime里指定的是各个解释器的绝对路径这样做是为了避免启动脚本因为环境变量差异跑到某个不存在的 Python 或 Node 上model这里我选的是 Ollama本地模型的好处是无需外部请求所有数据都留在自己机器里server.host我写成0.0.0.0是因为后面要从 Windows 侧访问 WSL 里的服务如果默认只监听127.0.0.1Windows 的浏览器很可能访问不到。3.4 第一个技能与验证配置完成后先做一次快速自检确认核心服务能起来。一般项目都会带一个状态命令类似./bin/openclaw doctor或者npm run doctor如果一切正常再启动主服务./bin/openclaw start第一次启动时OpenClaw 可能会自动扫描skills_dir下的技能目录并对每条技能做一次语法校验。如果里面有依赖 docker 或者依赖特定 GPU 的技能这里可能报一些警告别慌先记录下来回头逐个处理。看到“listening on 0.0.0.0:8080”这类日志后在 WSL 里用curl验证一下curl http://127.0.0.1:8080/health返回正常 JSON 就说明主体已经跑通了接下来再进 Windows 侧做最后的连通性验证。4. 实战踩坑六个问题还原现场与解决方法4.1 wsl --status 显示环境异常有段时间我每次打开 PowerShell 都会看到wsl --status提示基础环境不完整。这个提示一般有两种来源一种是 Windows 功能未完全启用另一种是 WSL 内核版本和发行版不匹配。我的解决办法是先在管理员 PowerShell 里确认两个关键功能是否开启dism.exe /online /get-featureinfo /featurename:Microsoft-Windows-Subsystem-Linux dism.exe /online /get-featureinfo /featurename:VirtualMachinePlatform如果显示状态是 Disabled就执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重启。更新 WSL 内核也可以顺手执行一下wsl --update实测下来这个组合拳能解决九成以上的状态异常问题。如果仍然异常看一眼 Windows 更新是不是有挂起状态有些功能开关需要系统更新配合才能完成初始化。4.2 WSL 端口被 Windows 防火墙拦截OpenClaw 在 WSL 内部跑起来了但是 Windows 浏览器死活打不开http://localhost:8080。这个坑很典型。原因是 WSL 2 的端口转发机制依赖于 Windows 防火墙规则。当你在 WSL 里监听0.0.0.0:8080时Windows 侧的 localhost 转发并不总是能自动放行。特别是网络配置文件被设成“公用网络”的时候防得更严。最简单的排查办法是在 PowerShell 里看端口是否真的在监听netstat -ano | findstr :8080如果确定服务已经监听却还是无法访问手动给防火墙加一条入站规则netsh advfirewall firewall add rule nameOpenClaw WSL dirin actionallow protocolTCP localport8080注意加规则之后如果服务端口号变了记得同步更新否则下次会在同样的问题上再翻车一次。另外不建议直接把防火墙关掉来图省事那是用安全换便利的亏本买卖。4.3 文件权限错乱WSL 和 Windows 之间跨文件系统读写时权限模型完全不同。把 OpenClaw 的项目目录放在 Windows 路径底下然后在 WSL 里执行脚本经常会出现permission denied或者奇怪的换行符报错。比如在 WSL 里访问/mnt/d/projects/openclaw你可能会发现所有文件的所有者显示成root而且chmod 755命令不生效。这是因为 drvfs 文件系统不认 Linux 的权限位。解决方案很简单项目必须放在 WSL 自己的文件系统里比如/home/claw/projects不要让 WSL 直接操作 Windows 盘符下的代码。克隆、配置、运行全在 WSL 内部完成Windows 侧只做浏览和文件传输。4.4 内存占用暴涨也许你也有同样的经验WSL 的内存占用看着一点点上涨重启完还占得老高。这是 WSL 2 的常见现象Linux 内核会把空闲内存用于文件缓存而 Windows 任务管理器会把这部分算成“已使用”看起来就很吓人。但如果你真的发现 OpenClaw 运行时内存长期被吃满多半是模型推理进程占了太多。尤其是用 Ollama 加载 7B 模型时默认的上下文长度或者并发设置如果没调好内存会直接冲上去。解决方法是给 WSL 设置内存上限。在用户目录下创建.wslconfig写入[wsl2] memory8GB swap4GB改完执行wsl --shutdown再重新进入。虽然这不是根治内存问题的办法但对日常使用足够友好。如果你有 32GB 内存也可以留 10GB 给 WSL前提是 Windows 侧你不能同时开太多大型软件。4.5 VS Code 里操作 WSL 连接问题我用 VS Code 打开 WSL 里的项目文件发现终端无法运行 git提示证书验证失败。这个问题的根源在于 VS Code 内部的 Git 环境变量没有正确继承 WSL 的配置。更稳妥的做法是彻底在 WSL 窗口里完成git config配置尤其是 user.name 和 user.email然后安装 VS Code 官方的 WSL 扩展并且始终从 WSL 终端里输入code .来启动工作区。这样 VS Code 才会以 WSL 环境的身份运行而不是以 Windows 原生身份去访问 WSL 文件。如果出现某个仓库报“无法安全验证”第一反应不是去关掉验证而是检查这个仓库的 remote URL 是不是写成了 https 而不是 ssh。把 remote 换成 ssh 地址再重新生成并配置密钥问题一般就消失了。直接选择“跳过验证”的后果是你后续每次推送都会被卡在凭证环节更麻烦。4.6 Windows 端口占用冲突有一次我启动 OpenClaw 一直提示端口被占用。在 Windows 侧找到占用进程netstat -ano | findstr :8080拿到 PID 之后在任务管理器里就能看到是哪个进程。如果你想快速释放端口可以用taskkill /PID 12345 /F但这里我想多提醒一句kill 只是一个临时措施。如果每次启动都被占最好直接把 OpenClaw 的监听端口换成不常用的比如 18080一劳永逸而不是每次都跟别的服务抢端口。特别是有些 Windows 服务会随机占用高端口用默认端口撞车的概率比想象中高。5. 把 OpenClaw 真正跑起来伴生程序、GPU 加速与自启动5.1 Windows Companion 配置OpenClaw 的 Windows Companion 通常是一个安装在 Windows 侧的小程序用来监控 WSL 里 OpenClaw 服务的状态或者提供系统托盘操作。它的配置核心就两个服务地址和令牌。由于 WSL 2 里的服务地址对 Windows 来说通常是localhost前提是网络模式默认的端口转发没问题配置时先填服务地址http://127.0.0.1:8080访问令牌跟 openclaw.json 里配置的 token 保持一致连接成功的标志是伴随程序窗口能显示技能数量、当前模型和最近任务记录。如果连接失败多半不是伴随程序的问题而是前面提到的防火墙、监听地址或者是令牌不匹配优先回去查这三项。我一开始的困惑是为什么 Windows 侧访问 localhost 就能进 WSL 的服务其实这是 WSL 2 默认的 localhost 转发机制在起作用只是它并不总是对非浏览器程序也有效。Companion 这类程序如果自带的 HTTP 客户端不认这个机制就需要你在防火墙里放行端口或者在伴生程序设置里跳过 localhost 直接填 Windows 分配的 WSL IP 地址。5.2 在 WSL 里启用 GPU 加速如果你本地有 NVIDIA 显卡并且要跑模型推理WSL 2 也支持通过 CUDA 调用 GPU。首先要确保 Windows 侧已经安装最新显卡驱动然后到 WSL 里安装 CUDA Toolkit 对应的 WSL 版本最后验证nvidia-smi能看到显卡信息就代表驱动链路正常。OpenClaw 如果对接 OllamaOllama 会自动检测 GPU并把模型加载到显存。这里一个最常见的错误是装了 CUDA 但没装运行时依赖推理速度没有明显提升此时需要回到依赖安装环节把缺失的库补上。在 WSL 环境里装 CUDA 需要注意一个问题不要从 Ubuntu 软件源里安装因为版本可能很旧且不匹配 NVIDIA 驱动。标准做法是去 NVIDIA 官网下载 WSL-Ubuntu 对应的安装包然后跟随提示安装。安装完成后重启 WSLnvidia-smi能正常输出你就成功了一大半。5.3 自启动方案WSL 本身并没有像 Windows“开机启动”那样简单直观的机制但思路很直接让 Windows 开机后自动拉起 WSL 并启动 OpenClaw。我常用的做法是使用任务计划程序。创建任务时设置触发器用户登录时操作启动wsl.exe参数-d Ubuntu -- /bin/bash -c cd /home/claw/projects/openclaw ./bin/openclaw start如果你希望 WSL 一直在后台跑还可以加--exec或者配合nohup。注意任务计划程序启动的进程默认可能不加载 bash 的 PATH 环境所以脚本里尽量写绝对路径否则进到 OpenClaw 目录后发现node、python3都不识别。还有一个容易忽略的问题任务计划程序如果设置了“不管用户是否登录都要运行”可能会导致 WSL 在隐藏会话里启动异常。建议设置成“只在用户登录时运行”这样至少能看到窗口和日志排查也方便。5.4 与 Docker 的整合不少 OpenClaw 技能依赖 Docker 环境。在 WSL 里直接装 Docker 引擎或者在 Windows 侧装 Docker Desktop 并启用 WSL 2 后端两者都可以。我个人的选择是直接在 WSL 的 Ubuntu 里安装 Docker 引擎因为这样容器的网络和 WSL 内的服务天然在同一网络空间端口映射配置更简单。安装很简单官方有一行注册 Docker 软件源的脚本装完执行sudo usermod -aG docker $USER newgrp docker docker run hello-world如果启动 Docker 守护进程时出现“start the windows daemon from a non-elevated terminal”之类的提示说明你很可能在 Windows 上误执行了 Linux 版命令或者 Docker Desktop 没有正确设置默认环境。回到 Docker Desktop 的 Settings 里把 Engine 切换到 WSL 后端即可。6. 给后来者的一批实操建议6.1 磁盘和内存分配的建议根据我这一轮的实测经验OpenClaw 加 Ollama 加一个 7B 模型内存占用在 6GB 到 8GB 之间比较正常。如果你的机器内存只有 16GB建议在.wslconfig里限制 WSL 上限为 8GB否则 Windows 侧会明显卡顿。磁盘方面建议给发行版预留至少 20GB 空间因为模型文件、依赖缓存、技能目录的体积都比想象中大。如果你跑多个模型或者打算做模型微调起步就得考虑 40GB 以上。WSL 的虚拟磁盘文件会动态增长但只增不减你要是删了很多大文件磁盘文件也不会自动缩小需要定期用wsl --compact或者通过磁盘管理工具手动压缩。6.2 升级和卸载的正确姿势WSL 里的发行版升级从来不是“直接重装”这么简单。wsl --unregister Ubuntu会删除整个文件系统你的配置、技能、模型全都没了。所以卸载前一定要先wsl --export备份。升级 OpenClaw 也是一样先备份 openclaw.json 和 skills 目录再拉代码、装依赖、检查变更日志最后用新版本覆盖旧目录。我吃过一次亏直接git pull然后启动新版迁移脚本不认识旧版本的配置字段整个配置被重置了。后来我养成了一个习惯任何升级前都把配置文件复制一份到 Windows 侧的备份目录成本低收益极高。6.3 安全底线OpenClaw 会监听本地端口意味着任何能访问这个端口的人都可能调用你的技能和模型。所以有两个底线必须守住一是给服务设置强令牌二是不需要外部访问时监听地址保持127.0.0.1而不是0.0.0.0。端口转发和远程访问属于要主动打开的能力不是默认就该有的。另外不要在 WSL 里用 root 账号跑日常服务。虽然 WSL 里 root 很方便但一旦某个技能脚本被输入内容诱导执行了危险命令root 权限会让风险放大很多。用普通用户跑服务需要特权时再sudo这才是安全且可控的使用方式。最后再分享一个我个人的实操体会如果你在 WSL 安装 OpenClaw 卡在某个奇怪的报错先别急着到处搜截图打开 PowerShell 执行wsl --status和wsl --version把两段输出看完百分之六十的问题都能定位到内核版本、功能开关和发行版状态这三类原因上。工具链越长环境越干净后面的排错就会越顺手。希望这篇踩坑记录能让你这一次安装比我少踩一半的坑。