如果你跟我一样主力机是Windows又喜欢折腾开源AI工具那这篇OpenClaw的Windows安装教程应该能帮你省下不少折腾时间。OpenClaw是一个把大语言模型接入日常工具链的开源项目装好之后可以在命令行、聊天软件、笔记工具里直接调起AI能力国内开发者用得比较多的场景是把它接到本地笔记库、企业IM或者配合本地模型做私有化助手。我在Windows 11上从零装了完整一遍把环境准备、核心安装、报错排查到进阶配置都梳理了一遍适合刚接触WSL和Docker的纯Windows用户也适合已经装到一半卡在各种报错里的朋友。1. 为什么Windows用户必须先过WSL2这道门槛1.1 OpenClaw的运行环境诉求很多人拿到安装教程第一反应是既然开箱即用那我直接下载个Windows安装包双击不就行了OpenClaw的实际运行环境比这复杂一些。它是基于Node.js开发的但启动脚本、依赖安装和部分功能组件都深度依赖Linux环境尤其是bash脚本和容器编排。Windows原生跑Node.js程序本身没问题但OpenClaw的动态依赖链里包含不少需要本地编译的原生模块在Windows上经常会出现node-gyp编译失败、Python环境缺失、C构建工具版本不对这类问题。我一开始也试过直接在Windows侧npm install报错一个接一个后来才意识到最省事的路径是走WSL2。WSL2Windows Subsystem for Linux 2本质上是Windows系统里跑一个轻量级虚拟机使用真正的Linux内核。OpenClaw的安装脚本可以在这个环境里以原生方式运行依赖安装、文件权限、Socket监听这些在Linux里天然支持的机制都能正常工作。这比在Windows上强行编译要舒服得多。1.2 为什么不推荐WSL1和传统虚拟机WSL1和WSL2虽然名字相近但实现原理完全不同。WSL1是通过系统调用转换层模拟Linux环境很多底层操作比如Docker容器、inotify文件监听、复杂网络配置会直接失败或者表现异常。OpenClaw的安装脚本里有一些对文件系统事件敏感的操作在WSL1上运行会出现脚本执行了一半就退出这种诡异问题。传统虚拟机比如VirtualBox、VMware虽然也能提供一个完整的Linux系统但资源开销大、启动慢而且目录共享、端口转发、剪贴板这类交互体验远不如WSL2顺滑。WSL2的启动只需要两三秒内存按需动态分配Windows和Linux两侧可以共享文件系统开发体验非常接近原生Linux。1.3 Docker Desktop与WSL2的配合关系OpenClaw在完整的部署模式下会用到Docker来编排辅助服务比如消息队列、数据库、网关组件。Docker Desktop在Windows上有一个专门的WSL2后端模式它会把Docker引擎直接跑在WSL2的发行版里而不是跑在Windows的Hyper-V虚拟机里。这样做的好处是同一套Linux内核可以被OpenClaw和Docker共享内存占用更小网络互通也更自然。这里要记住一个关键点Docker Desktop的WSL2后端必须和OpenClaw所在的WSL发行版打通。很多人装完Docker以后发现OpenClaw的容器起不来多半就是Docker设置里没有开启对应发行版的WSL集成后面第3章我会详细说这个配置项。2. WSL2、Docker、Node.js三件套的完整准备2.1 用管理员身份完成WSL2安装安装WSL2的第一步是用管理员身份打开PowerShell。这里说的管理员身份不是右键PowerShell选择以管理员身份运行这一步就完了而是确认窗口标题栏显示管理员标识。我见过有人用普通窗口执行后面的命令报错提示请求的操作需要提升其实就是这一步没做对。在管理员PowerShell中执行wsl --install这条命令会一次性安装WSL2所需的全部组件包括虚拟机平台、WSL2内核以及默认的Ubuntu发行版。安装完成后系统会提示重启电脑这一步一定要重启不能跳过。重启之后打开开始菜单你应该能看到新增的Ubuntu应用图标首次启动需要设置Linux用户名和密码。重启后回到PowerShell运行下面三条命令验证环境wsl --status wsl --list --verbose wsl --set-default-version 2wsl --status会显示当前WSL的默认版本和内核版本。如果看到默认版本2说明WSL2已经就位。wsl --list --verbose会列出已安装的发行版VERSION那一列显示2就是WSL2显示1就说明这个发行版还跑在WSL1上需要升级。如果你安装的是老版本的Ubuntu或者电脑上原本就有WSL1的发行版可以用下面的命令把指定发行版升级到WSL2wsl --set-version Ubuntu-22.04 2升级过程需要一两分钟期间尽量不要关闭窗口。2.2 Docker Desktop安装与WSL集成Docker Desktop是Windows上运行Docker最主流的方式。去Docker官网下载Windows版本安装包双击安装。安装过程中有一个是否使用WSL2后端的勾选项默认就是勾中的保持不动就好。安装完成后打开Docker Desktop进入Settings确认以下几项General标签页里Use the WSL 2 based engine必须处于勾选状态。Resources - WSL Integration里列出的发行版中至少要勾选你将要安装OpenClaw的那个Ubuntu发行版。如果没看到对应的发行版点一下右下角的Refresh或者重启Docker Desktop再来看。WSL Integration这个勾选特别容易漏。它的作用是把Docker命令直接注入到WSL发行版里这样你在Ubuntu终端里执行docker ps就能直接连上Docker引擎不需要每次手动指定Docker的Windows地址。在WSL终端里验证docker --version docker ps能正常输出版本号和空列表说明Docker已经可以从WSL侧访问。2.3 在WSL里准备Git和Node.js一些教程建议在Windows侧安装Git和Node.js我的实际体验是在WSL里再装一份反而省事。因为OpenClaw的安装和运行都在WSL内部依赖解析、PATH搜索、npm全局安装这一套流程在Linux侧是自洽的。Windows侧装Node反而可能导致命令混用后面排查起来更头疼。进入WSL终端后先装Gitsudo apt update sudo apt install git -y git --versionNode.js推荐用nvm管理而不是直接apt安装系统版本。nvm可以让你在多个Node版本之间自由切换OpenClaw对Node版本有明确要求如果以后升级OpenClaw发现版本不兼容用nvm切换很方便。安装nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash执行完成后关闭并重新打开WSL终端让nvm生效。然后安装Node.js 20 LTS版本nvm install 20 nvm use 20 node -v npm -v看到v20.x.x的版本输出环境准备就算完成了。如果你在安装nvm时遇到网络超时多试几次或者先确认系统能正常访问GitHub。这里有一个细节WSL里默认的npm镜像源是国内用户经常卡的环节。安装依赖时如果速度很慢可以把npm registry切换为国内镜像npm config set registry https://registry.npmmirror.com这个操作不会影响OpenClaw的功能只是让依赖下载更快。3. OpenClaw核心安装流程与初始化配置3.1 拉取OpenClaw源码到WSL环境就绪后在WSL终端里选择一个习惯的目录比如~/projects把OpenClaw官方仓库拉下来cd ~ mkdir projects cd projects git clone OpenClaw官方仓库地址 openclaw cd openclaw仓库地址以官方文档为准我不在文章里贴具体链接避免时效性问题。拉取完成后先看一眼目录结构确认根目录下有package.json和安装脚本文件。如果你看到的目录是空的或者缺少关键脚本文件多半是仓库包含子模块没有拉全执行git submodule update --init --recursive这个步骤很多人会漏掉直接导致后续安装脚本找不到组件。3.2 执行安装脚本OpenClaw的安装方式随版本迭代会有变化常规做法是进入仓库目录后执行官方提供的安装脚本可能是./install.sh也可能是npm run setup具体以你当前拉取到的版本为准。可以先用ls看看根目录里有哪些可执行脚本再决定怎么执行。ls -la如果看到install.sh这类文件chmod x install.sh ./install.sh脚本会自动安装npm依赖、生成初始配置目录、做环境自检。这个过程中终端会滚动大量输出你要留意有没有红色报错。常见的报错集中在网络下载失败和Node版本不兼容这两类。网络问题可以通过切换npm镜像缓解Node版本问题就用nvm切换一下比如OpenClaw要求Node 18以上就切换到20。3.3 初始化配置向导安装完成后OpenClaw会进入初始化向导或者生成一份配置文件。这个配置文件通常位于~/.openclaw/目录下文件名可能是config.json、config.yaml或settings.json具体以实际生成为准。配置向导一般会问几个问题API Key填写你使用的模型服务商提供的密钥。如果使用本地模型这里可以先填占位符后面在配置文件里改成本地服务地址。默认模型填写模型标识比如gpt-4o、qwen2.5:3b这类。服务端口默认3000或8080保持默认即可如果端口被占用再改。渠道类型OpenClaw支持命令行、聊天机器人、笔记软件等多种渠道按需选择。配置过程中有拿不准的选项就先选默认值OpenClaw允许之后随时改配置文件不要求在向导阶段全部确认清楚。3.4 启动服务并验证启动OpenClaw的方式通常是一条命令行指令比如npm start、npm run dev或者通过已安装的CLI命令直接启动。看到日志中出现类似server startedlistening on port字样说明核心服务已经起来了。验证分三步走在另一个WSL终端窗口里执行ps aux | grep openclaw确认进程在跑。浏览器访问http://localhost:端口能看到健康检查接口的输出或简单的Web页面。用OpenClaw提供的命令行交互模式发起一句简单对话确认模型能正常响应。如果第3步的对话内容迟迟没有返回先查模型接口是否连通。使用远程API的话可以直接用curl测试服务商的接口地址使用本地模型的话检查本地推理服务是否在监听。4. 卡住最多人的wsl -- status报错排查实录4.1 这个报错到底在说什么OpenClaw安装或启动时有一部分版本会在Windows侧做一次WSL环境检测如果脚本发现WSL环境不符预期会给出类似openclaw无法安全验证wsl2环境。请在powershell中运行wsl -- status的提示。这个报错本身不是OpenClaw程序的问题而是它在告诉你当前这台机器的WSL2环境没有达到它所期望的标准很可能是WSL默认版本还是1、内核组件没有更新或者Docker没有跟WSL正确打通。我遇到这个报错时第一个反应是检查OpenClaw的配置后来折腾半天发现跟配置毫无关系纯粹是WSL环境问题。所以遇到这个提示第一步永远是回到Windows侧查WSL而不是改OpenClaw设置。4.2 从wsl --status开始的完整排查链路下面是我实测过最有效的排查顺序每一步都有目的不要跳步。在Windows PowerShell里执行wsl --status看输出内容。正常状态下会显示默认版本为2、内核版本正常更新。如果显示默认版本1说明当前默认WSL版本不对执行wsl --set-default-version 2如果显示内核版本较旧或者提示WSL组件需要更新执行wsl --update更新完成后重启电脑。接着查看具体发行版的版本wsl --list --verbose输出结果里有一个VERSION列如果某个发行版显示1而OpenClaw又恰好装在这个发行版里那它检测WSL2环境自然不通过。用下面命令把它转成2wsl --set-version 发行版名称 2还有一种情况输出里能看到发行版但状态是Stopped。先启动它wsl -d Ubuntu进入发行版后再退出让它在后台保持运行。4.3 两个容易被忽略的深层原因如果WSL状态一切正常报错依然出现那就检查PowerShell执行策略。OpenClaw在Windows侧检测WSL2环境时可能会调用一段PowerShell脚本如果系统执行策略被设置成Restricted脚本会被拦截OpenClaw收到的是无法检测结果于是抛出安全验证失败。解决办法是管理员PowerShell里执行Set-ExecutionPolicy RemoteSigned选择是确认。另一个深层原因是PATH环境变量里找不到wsl.exe。这种情况比较少见但确实存在一般是因为安装了某些精简版系统或者WSL安装目录被手动改过。检查方法where.exe wsl如果提示找不到把C:\Windows\System32\WSL目录手动加入系统PATH。4.4 修复后的验证方法修复完以上任意一项都建议做一次完整验证。在PowerShell里重新执行wsl --status确认默认版本为2再在WSL终端里执行docker ps确认Docker连接正常最后回到OpenClaw安装脚本重新跑一遍。整个过程不需要重复下载依赖脚本会自动跳过已完成的部分。如果验证之后依然报错还有一个野路子把OpenClaw的安装过程完全放到WSL终端里执行绕过Windows侧的检测逻辑。既然OpenClaw本身就跑在WSL里Windows侧检测只是在安装阶段起校验作用运行阶段完全可以不依赖它。这是我测试下来最有效的兜底方案。5. 打通Teams、本地模型和Obsidian的进阶玩法5.1 接入Microsoft Teams让AI进入工作群基础安装跑通以后把OpenClaw接入Microsoft Teams是我觉得最值的一步因为它能把个人AI能力变成团队可用的工具。整体思路是在Azure门户里创建一个Bot应用注册拿到三个关键凭证Application (client) ID、Tenant ID、Client Secret然后把这些值填到OpenClaw的Teams渠道配置段。在Azure门户创建应用注册时要注意一下Teams机器人需要在应用程序权限里勾选Microsoft Graph API的相关权限同时配置一条消息收发端点指向OpenClaw提供的webhook地址。由于不同版本的OpenClaw配置格式会有差异具体字段名以官方文档为准但大体的映射关系是固定的client_id对应Application IDclient_secret对应在证书与机密页面生成的密钥tenant_id对应目录ID。这块是我踩坑最多的地方。Azure门户的菜单变化频繁有时候一个选项的名字改了位置挪了熟悉套路的人也得翻一会。我建议按顺序走先注册应用再生成client secret最后配置bot通道如果Teams里能搜到你的机器人但发消息没反应十有八九是端点地址配错或者OpenClaw的三方回调服务没有启动。5.2 用本地模型跑起私有化助手本地模型关联是另一个实用性很强的配置。我们以qwen2.5-3b为例先在WSL里装Ollama然后拉取模型curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b拉取完成后Ollama默认监听localhost:11434。在OpenClaw配置文件的模型部分把base_url指向http://localhost:11434/v1model写成qwen2.5:3bAPI Key随便填一个占位符即可因为Ollama本地接口不校验密钥。本地模型的好处是数据不出机器适合内部知识库和隐私要求高的场景。代价是响应速度和显存占用受硬件限制qwen2.5-3b在16G内存的机器上跑CPU推理也能接受但并发能力不如云端API。实测下来单轮问答的响应时间在5-10秒之间作为个人助手够用了。如果你想追求更好的中文理解效果可以把模型换成参数更大的版本比如qwen2.5-7b但建议先确认机器内存不低于16G否则Ollama可能会把系统内存吃光。5.3 让OpenClaw读取Obsidian笔记库连接Obsidian的核心是让OpenClaw能访问你的笔记目录。Obsidian本地库本质上就是一个包含大量markdown文件的文件夹OpenClaw侧的配置就是把笔记库路径挂载进来并设定读取规则。具体的配置项取决于OpenClaw当前版本的集成方式。有的版本支持在配置文件中直接指定一个notes_path字段有的版本需要通过插件系统桥接。在WSL里访问Windows侧的Obsidian库路径格式是/mnt/c/Users/你的用户名/Documents/MyNotes这样。首次挂载后可以让OpenClaw做一次索引把已有的markdown文件读一遍之后提问时就能引用笔记内容。这里有个小坑WSL访问Windows文件系统的IO速度比访问Linux原生目录慢笔记库文件特别多的话索引时间会很长。我的做法是把常用的笔记子目录单独软链到WSL的home目录下让OpenClaw直接读Linux侧路径速度会明显快一些。5.4 开机自启动与资源占用控制OpenClaw作为常驻服务Windows重启后需要手动启动很麻烦。最简单的做法是在WSL里写一个启动脚本然后用Windows任务计划程序调用。任务计划的触发器选计算机启动时操作设置为运行wsl -d Ubuntu -- bash -c cd ~/projects/openclaw npm start ~/openclaw.log 21注意日志文件重定向一定要写否则任务计划里的WSL窗口会一直挂着占用一个控制台会话。资源占用方面OpenClaw本身是Node.js进程内存占用一般300-500MB主要开销在启动时加载模型调用链和大依赖包。对8G内存的机器会有压力建议关闭桌面端不必要的常驻程序。如果WSL吃满内存可以在Windows侧设置C:\Users\用户名\.wslconfig文件来限制WSL的内存上限[wsl2] memory4GB swap2GB保存后重启WSL生效。这个限制只影响WSL内的程序Windows本体内存完全不受影响。写在最后的小体会我在整个安装过程中最大的感受是OpenClaw本身不难装难的是Windows上虚拟化环境的复杂组合。WSL2、Docker Desktop、Node.js、nvm这几样工具单独看都不难串在一起以后任何一个环节配置不对最后呈现出来的都是让人摸不着头脑的报错。所以如果你也卡在某个奇怪的环节我的建议是不要急着搜报错信息先把环境三件套重新检查一遍80%的问题都会浮出水面。配置好本地模型和Teams接入以后这个工具就成了我每天实际在用的基础设施投入的时间很值得。