我之前在一台 Windows 机器上折腾 OpenClaw第一反应就是直接在当前系统里跑结果依赖装到一半发现各种别扭后来换到 WSL2 里重来一遍反而一路顺畅。这个工具说实话对 Windows 用户并不算特别友好但也不是搞不定。网络上关于 OpenClaw 的部署教程多半只讲 LinuxWindows 用户基本属于自己摸索的状态。所以我把两条路线——原生安装和 WSL2 安装——都完整走了一遍把过程中踩过的坑、验证过的步骤、以及最后稳定运行的配置都记录下来。如果你也在 Windows 上部署 OpenClaw想知道到底选原生还是 WSL2、每一步怎么操作、遇到报错怎么排查这篇内容应该能帮你节省不少时间。我先把结论放在前面如果你只打算快速体验一下功能原生版够了如果你想把它当作长期运行的 Agent 服务并且要接本地模型或外部 ChannelWSL2 版本明显更稳。1. 部署前先想清楚原生和 WSL2 到底差在哪OpenClaw 的核心是一个基于 Node.js 的智能体编排框架它把 Agent 配置、渠道接入、会话管理等能力集成在一起。部署本身并不复杂复杂的是 Windows 环境的兼容性。在动手之前我建议你先花五分钟想清楚走哪条路线因为这两条路的坑完全不一样。1.1 原生部署与 WSL2 部署的选型逻辑原生部署简单理解就是直接在 Windows 上装 Node.js、拉代码、跑服务。这条路的好处是启动快、调试直观、不需要虚拟机层资源占用小。但它的问题也很现实OpenClaw 依赖的很多原生模块尤其是涉及文件监听、网络通信、进程管理的部分在 Windows 上的表现不如 Linux如果你要接本地大模型做推理很多工具链在 Windows 上的兼容性都更差另外 Windows 下路径反斜杠、权限模型、防火墙弹出框这些事会让一个本来很简单的问题变得很难排查。WSL2 则相当于在 Windows 里跑一个轻量级 Linux 虚拟机。因为 OpenClaw 本身就是按 Linux 环境设计的WSL2 里跑它的体验更接近官方文档的描述依赖安装、路径处理、后台服务管理都顺畅得多。代价就是你得额外学习一点 Linux 命令而且 WSL2 的文件系统 IO 性能在跨盘操作时会明显下降。我的建议是如果你只是想看看 OpenClaw 是什么、跑几个 Demo原生版可以如果打算让它稳定跑几天甚至几周直接 WSL2。我最终是把两条路都走了一遍下面我会把各自的步骤和问题都写清楚。1.2 版本要求与前置环境检查清单无论走哪条路有几个前置条件是一致的操作系统Windows 10 版本 2004 及以上或者 Windows 11。CPU 架构x64。ARM 版 Windows 我没测过不推荐直接用。内存至少 8GB如果要跑本地模型并同时运行 OpenClaw建议 16GB 以上。磁盘空间OpenClaw 本体加依赖大概需要 2GB 左右如果还要装模型按模型大小另算。软件层面原生部署需要 Node.js 18 或更高版本推荐 20 LTS包管理器可以用 npm 或 pnpm。WSL2 路线需要先安装 Ubuntu 发行版建议 22.04 或 24.04。提示Node.js 版本直接决定依赖能否安装成功。我用 Node 16 试过一次部分依赖直接报 engine 不匹配升到 20 就顺利了。别纠结直接用 LTS 版本。2. 原生 Windows 部署从环境准备到跑起第一个 Agent这条路本身不复杂但由于 Windows 的生态特性有几个环节必须处理得当。我会按实际操作的顺序来写包括每条命令的作用和为什么这样做。2.1 安装 Node.js 与包管理器先装 Node.js。我推荐用 nvm-windows 来管理 Node 版本而不是直接下载官方安装包。原因很简单OpenClaw 的依赖更新很快不同版本可能要求不同 Node 版本nvm 能让你随时切换避免以后重装。nvm-windows 的安装方式不展开了装完后用管理员权限打开 PowerShell执行nvm install 20 nvm use 20 node -v npm -v确认输出里 Node 是 v20.x。另外npm 安装依赖时下载速度可能不理想你可以在用户目录下新建.npmrc文件写入registryhttps://registry.npmmirror.com这是切换 npm 公共镜像源的标准做法只影响下载速度不影响依赖功能。设置完成后建议先执行npm config get registry确认配置生效。2.2 获取 OpenClaw 源码并安装依赖原生部署的方式我建议直接用 Git 拉取源码而不是下载 zip 压缩包。因为 OpenClaw 迭代很快用 Git 可以随时git pull更新到最新版省去反复下载的麻烦。git clone https://你的仓库地址/OpenClaw/OpenClaw.git cd OpenClaw npm install这里有两个常见问题需要提前说第一路径不能有中文和空格。Windows 下很多原生模块在处理带空格或中文的路径时会出问题表现是安装时莫名其妙报错启动时找不到文件。我直接把项目放到了D:\dev\openclaw下。第二npm install耗时可能很长中间如果出现gyp ERR!之类的报错多半是缺少编译环境。这时候需要安装 Visual Studio Build Tools勾选使用 C 的桌面开发组件然后重试安装。不过我在干净系统上装 OpenClaw 时没有遇到编译需求说明大部分依赖都有预编译二进制这一步可以等报了错再处理。2.3 启动前的配置与首次运行OpenClaw 支持多种 Channel启动前需要指定至少一个。如果你只想先在本地测试可以用内置的 CLI 模式不需要额外配置外部账号。node openclaw.js --channel cli如果一切正常你会看到类似下面的日志[openclaw] 已加载配置 [openclaw] 会话管理器已启动 [openclaw] Channel [cli] 已连接 [openclaw] Ready.到这里原生版就跑起来了。但我必须说这只是能跑离好用还有距离。我在原生版跑了两天测试后发现Windows 控制台窗口只要不小心碰到进程就断了而且把 PowerShell 窗口关了以后OpenClaw 跟着退出没有任何守护机制。这就是原生版最大的局限——缺少 Linux 下那种成熟的进程管理方式。2.4 原生版最容易踩的 Windows 专属坑上面是顺利的情况实际上新手大概率会遇到下面几个问题PowerShell 执行策略拦截。如果你用 PowerShell 启动脚本时提示因为在此系统上禁止运行脚本执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser杀毒软件拦截 Node 进程。Windows Defender 偶尔会把 OpenClaw 运行时生成的临时文件当成威胁。如果你发现日志里突然出现读写文件失败先去 Defender 的保护历史记录里看有没有拦截记录把项目目录加进白名单。换行符导致脚本异常。Windows 和 Linux 的换行符不同如果 Git 默认把代码里的 LF 转成了 CRLF某些 shell 脚本会无法执行。在项目目录里执行git config core.autocrlf false可以规避这个问题。3. WSL2 路线把 Ubuntu 变成你的部署底座如果你决定了走 WSL2那么原生版部署就当热身下面才是重点。WSL2 的部署流程我希望你按先装环境、再迁移存储、再配 GPU、最后部署服务这个顺序来不要跳步。3.1 启用 WSL2 并安装 Ubuntu 发行版Windows 11 和较新的 Windows 10 都支持一条命令直接完成wsl --install装完之后默认是 WSL2 内核发行版根据系统设置可能是 Ubuntu。如果想单独安装指定版本wsl --install -d Ubuntu-24.04装完后进入系统设置用户名和密码然后确认版本wsl -l -v如果输出显示版本是 1需要手动升级wsl --set-version 发行版名 2注意WSL 安装前需要确保 BIOS 里开启了虚拟化。如果你装完发现启动报Please enable the Virtual Machine Platform去 BIOS 找Intel VT-x或AMD SVM打开后重启。3.2 系统盘的 VHD 文件迁移这一步是很多人忽略的。WSL2 的 Ubuntu 默认把整个文件系统放在一个 VHD 虚拟磁盘里位置在C:\Users\用户名\AppData\Local\Packages\...\LocalState\。如果你在 WSL2 里装了很多依赖和模型这个文件会越来越大C 盘很容易爆。我第一次没管它跑了一次 Ollama 部署C 盘直接红了。所以要尽早迁移关闭所有 WSL 会话然后在 PowerShell 里执行wsl --shutdown。用管理员身份打开 PowerShell找到发行版的安装包路径。把整个LocalState目录移动到 D 盘比如D:\WSL\Ubuntu。通过wsl --import 名称 D:\WSL\Ubuntu 备份文件导入迁移后的系统。如果觉得导入导出麻烦也可以直接在安装后的 WSL 里定期做磁盘清理比如用sudo apt autoremove。但这治标不治本大模型、Docker 镜像这类东西很快又会塞满。我的建议是从一开始就让 WSL 的数据落在非系统盘别等满了再动。3.3 配置 .wslconfig 限制资源占用WSL2 默认会占用系统很大比例的内存和 CPU如果你同时还要在 Windows 侧跑别的应用需要手动限制。在C:\Users\用户名\.wslconfig写入[wsl2] memory8GB processors4 swap2GB配置完执行wsl --shutdown再进入 WSL 生效。这里有个实际感受不让 WSL 无限制吃内存Windows 主机这边的响应速度会明显好很多。3.4 GPU 支持与 CUDA 环境准备如果你打算让 OpenClaw 调用本地模型那么 GPU 支持就是 WSL2 路线相比原生版最重要的优势。Windows 上要跑 Linux 版 CUDA 工具链往往很麻烦但 WSL2 提供了完整的 GPU 直通能力。首先确认 Windows 侧已经安装了最新显卡驱动注意不需要在 Windows 里装全套 CUDA Toolkit只要驱动就行。然后进入 WSL2执行nvidia-smi如果能看到显卡信息说明直通成功。接着安装 CUDA Toolkit for WSLsudo apt update sudo apt install -y nvidia-cuda-toolkit安装完成后验证nvcc --version python3 -c import torch; print(torch.cuda.is_available())如果返回TrueGPU 没有问题了。如果显示False大概率是 PyTorch 装成了 CPU 版需要重新按 CUDA 版本安装对应的 PyTorch 包。4. WSL2 中部署 OpenClaw与原生版操作上的关键差异环境准备好之后在 WSL2 里部署 OpenClaw 本身不算难。但这里的每一步和原生版都有细微差别我会把差异点标出来。4.1 WSL2 中的 Node.js 与依赖安装进入 WSL2 后安装 Node.js 的方式建议用 nvmLinux 版而不是去官网下安装包curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20npm 镜像源的配置方式和原生版相同在~/.npmrc里写入镜像地址即可。另外WSL2 里安装依赖会更顺利因为很多原生模块在 Linux 下有现成的预编译版本。拉取代码并安装git clone 你的仓库地址 cd OpenClaw npm install4.2 文件系统权限与跨盘访问注意事项这是 WSL2 部署时最容易踩坑的地方。不要把 OpenClaw 项目放在/mnt/c/或/mnt/d/这种 Windows 挂载目录下一定要放到 Linux 文件系统内比如~/openclaw。原因是 WSL2 的跨文件系统 IO 性能很差。放在/mnt/d/下每次读文件都要经过 Windows 的文件系统驱动启动时间和依赖扫描时间会慢很多倍。项目放~/openclaw后访问速度接近原生 Linux 体验。如果想在 Windows 侧编辑代码可以访问\\wsl$\Ubuntu\home\用户名\openclaw路径这是 WSL2 提供的网络映射性能上对于编辑操作可以接受。4.3 使用 systemd 让 OpenClaw 稳定后台运行原生版最大的问题是没有守护机制WSL2 里解决这个问题的方式是启用 systemd。新版 WSL 默认启用了 systemd你可以检查一下ps -p 1 -o comm如果输出是systemd说明已经启用。如果没有在/etc/wsl.conf写入[boot] systemdtrue然后关闭 WSL 再重新进入。有了 systemd 就可以把 OpenClaw 注册为系统服务比如创建一个服务文件[Unit] DescriptionOpenClaw Agent Service Afternetwork.target [Service] Typesimple WorkingDirectory/home/用户名/openclaw ExecStart/usr/bin/node openclaw.js --channel cli Restarton-failure RestartSec10 [Install] WantedBymulti-user.target启用并启动服务sudo systemctl daemon-reexec sudo systemctl enable openclaw sudo systemctl start openclaw之后可以用systemctl status openclaw查看运行状态日志用journalctl -u openclaw -f实时跟踪。这套方案稳定运行一周没有掉线比原生版的裸进程方案强太多。4.4 时间同步问题一个容易被忽略的坑WSL2 虚拟机的时钟偶尔会和宿主机漂移。如果发现日志里出现证书验证失败、会话超时之类的怪异问题先检查时间date sudo hwclock -s时间不准会直接影响 OpenClaw 的会话文件时间戳和网络请求签名。我在 WSL2 里跑了两天后出现了一批奇怪的认证错误排查了半天最后发现是 WSL 的时钟慢了五分钟。5. 双版本横向对比与维护体验两条路我都跑了至少两天下面这个表格是我真实的对比感受对比项原生 WindowsWSL2部署耗时约 20 分钟含踩坑约 40 分钟含环境配置启动速度快秒级稍慢秒到三级文件扫描速度依赖 Native 模块一般在 Linux 文件系统内更快GPU 推理支持麻烦工具链不全顺畅CUDA 直通后台运行稳定性差窗口关闭即死好systemd 守护外部设备局域网访问直接可用需额外配置端口转发代码编辑体验Windows 工具直接可用需通过\\wsl$或远程工具系统资源控制难控制可用.wslconfig限制如果只是个人快速验证原生版其实够用如果打算把 OpenClaw 作为正式 Agent 长期运行我的结论很明确WSL2 是 Windows 用户唯一值得考虑的方案。说到外部设备访问如果你的 OpenClaw 要运行一个 Webhook 服务并且需要局域网内其他设备访问WSL2 默认只对 Windows 本机开放 localhost 转发其他设备访问不到。这时可以在 Windows PowerShell 里配置端口转发netsh interface portproxy add v4tov4 listenport3000 listenaddress0.0.0.0 connectport3000 connectaddressWSL的IPWSL 的 IP 可以通过hostname -I查看。注意这个 IP 重启后会变所以我一般会给 WSL 设置静态 IP 或用 WSL 的 mirrored 网络模式。6. 高频报错与排查手册session file locked、端口占用、中文路径最后这部分我整理一下部署和运行期间最常遇到的报错。每一个我都给出根因、排查链路、修复方案。6.1 session file locked最典型的运行期冲突我在测试时模拟并发任务遇到一个很典型的报错agent failed before reply: session file locked (timeout 60000ms)这个错误的根因是OpenClaw 使用本地文件来保存会话状态多个进程或进程内多个任务同时访问同一个 session 文件时文件锁无法在超时时间内获取。排查链路查看是否有多个 OpenClaw 进程在跑ps aux | grep openclaw。如果只有一个进程再查看是否有残留的锁文件。OpenClaw 项目里通常会在 session 目录下生成.lock文件。检查是不是有 Windows 侧的程序正占用该目录比如你正用记事本打开 session 文件。修复方法关闭所有重复实例只保留一个服务。删除已经陈旧的.lock文件。如果是因为并发请求太多导致的把任务并发数调低或者确认 OpenClaw 的并发配置是否合理。6.2 端口被占用启动时提示 address already in use如果启动时报EADDRINUSE说明端口被别的程序占了。排查方式Windows 原生版netstat -ano | findstr :3000 taskkill /PID 进程ID /FWSL2 里sudo lsof -i :3000有时候是上一个没退干净的残留进程有时候是 Windows 侧的占用了。注意如果你用了端口转发Windows 侧的监听也可能导致冲突先删掉 portproxy 规则再排查。6.3 中文路径或带空格的路径引发神秘报错这个在原生部署那节提过重复一下是因为它值得一个单独的提醒。任何跟路径相关的操作只要碰到中文或空格报错信息往往不是直接提示路径有问题而是五花八门的Invalid argument、ENOENT、EACCES。如果是 WSL2 路线/mnt/d/下有一个带空格的项目文件夹npm install大概率会失败。建议所有 Windows 部署 OpenClaw 的用户项目路径严格使用英文字母和数字不要用中文、空格、特殊字符。6.4 Channel 接入配置以 Microsoft Teams 为例OpenClaw 的 Channel 机制是它的核心功能之一部署时按需配置。如果你打算接入 Microsoft Teams需要注意OpenClaw 本身并不直接和 Teams 通信它通过 Bot Framework 协议接入需要先在 Azure 侧创建一个 Bot 资源获取 App ID、App Secret 和 Tenant ID然后把这些信息填入 OpenClaw 的配置文件。常见的错误是填错 App Secret 前缀或 Tenant ID 格式导致认证失败。日志里会显示unauthorized或401。这时候别急着改代码先检查三项信息是不是和 Azure 后台完全一致。6.5 本地模型接入Ollama 与 GPU 验证如果你要在 OpenClaw 里接本地模型最省事的方式是用 Ollama。WSL2 里安装curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7b然后用 Python 验证 CUDA 是否被正确识别这一步最容易出问题很多人nvidia-smi能显示显卡但torch.cuda.is_available()返回 False。原因是 PyTorch 默认安装的版本可能是 CPU 版这里需要按官方命令重新安装对应的 CUDA 版本。写在最后的体会双版本部署完成之后我现在的主力方案是 WSL2 systemd Ollama 的组合OpenClaw 作为常驻 Agent 服务。原生版我留着做快速功能验证毕竟启动快、改完代码马上能看到效果。给你的建议很简单如果你只是出于好奇原生版试一下无妨但如果你想把 OpenClaw 真正用起来从一开始就选 WSL2别走弯路。另外无论选哪条路项目路径别用中文、Node 用 20 LTS、npm 镜像提前配好这三个点做到位能避开一大半新手问题。OpenClaw 本身还在快速迭代把环境打稳后面升级和维护会轻松很多。
