看到这个标题点进来的朋友估计已经在Windows上折腾过不少智能体框架了。OpenClaw是社区里热度很高的一个开源智能体项目常被拿来和Claw这类个人助理做对比。简单说它是一套能连接大模型、浏览器、命令行工具和记忆库的智能体运行框架不是那种装完就能打开的聊天窗口。这篇文章围绕在Windows上部署OpenClaw的完整过程从WSL2环境、Docker、Node.js到模型接入、skill配置再到常见报错把能踩的坑提前替你踩一遍。只要照着走基本能在一台普通Windows电脑上把OpenClaw跑起来。1. 先搞清楚OpenClaw到底是个什么东西1.1 它到底能做什么为什么值得在Windows上折腾OpenClaw本质上是一个智能体运行时。它不绑定某一家大模型厂商而是通过配置把各种模型接进来然后给模型提供一堆可以操作的工具。举个例子你可以让它访问本地文件、执行Shell命令、调用浏览器完成网页操作还能把每次对话和任务记录持久化到数据库里下次启动时它还记得你之前说过什么。这一点比单纯开个网页聊天窗口要有价值得多。它比较核心的能力包括几块一是模型接入层支持OpenAI兼容API、Ollama本地模型、Anthropic风格接口等二是工具调用层社区叫它skill可以用YAML或JSON定义新的技能三是Companion一个浏览器扩展让智能体真正能看和点网页四是记忆存储默认用SQLite也可以接Postgres。这些能力组合起来你就能做一个半自动的数字助理而不是只能聊天的玩偶。在Windows上部署它的难点在于项目本身对Linux环境更友好很多原生依赖、示例脚本比如ROS2和Gazebo联动的rosclaw场景都是围绕Linux写的。所以Windows用户想跑起来核心思路不是硬刚原生Windows而是用WSL2搭一个轻量Linux环境把OpenClaw装在里面再让Windows这边的浏览器、Ollama等服务跟它互通。理解了这一层后面很多操作就不会觉得莫名其妙了。1.2 为什么绕不开WSL2这不是偷懒是省事我第一次接触这个项目时想当然地在Windows原生环境里装Node.js、克隆仓库、跑npm install结果在编译原生模块那一步就卡住了。原因很简单OpenClaw的依赖链里有不少包需要通过node-gyp调用gcc编译Windows上没有完整的Linux工具链就算装上VS Build Tools能过后续跑ROS2相关脚本时还是寸步难行。WSL2本质是一个轻量虚拟机但它和传统虚拟机不一样的是文件系统、端口、剪贴板都能和Windows互通。你可以在WSL2里跑Linux版Node.js在Windows浏览器里直接访问http://localhost:18789两边就像在同一台机器上一样。这种体验对于跑这种Linux优先的开源项目来说是最平滑的方案。还有个容易忽略的点文件IO性能。如果你把项目放在/mnt/c盘符下WSL2访问Windows文件系统会有明显的性能损耗npm install可能要慢好几倍。正确做法是把OpenClaw放在WSL2自己的文件系统里比如~/openclaw通过\wsl$路径或VS Code的WSL插件去编辑这才是效率最高的姿势。1.3 部署前的硬件和软件清单先别急着敲命令我建议按下面的配置核对一下自己的机器。独享内存是硬指标因为WSL2默认会吃一半物理内存再叠加Ollama这类本地模型服务8GB内存的机器会比较紧张16GB会从容很多。项目最低要求推荐配置备注CPU4核8核及以上编译npm依赖时差别很大内存8GB16GBWSL2默认占用50%可通过.wslconfig控制磁盘30GB可用SSD 50GB以上WSL2虚拟磁盘会持续膨胀Windows版本10 21H2以上Win11老版本WSL内核更新麻烦系统版本Windows 10/1164位ARM版会有额外坑不推荐软件方面你需要准备Windows Terminal强烈建议、WSL2内核、Ubuntu发行版22.04或24.04都行、Docker Desktop可选但官方示例常用它跑Postgres等附加服务、Node.js 20或22 LTS、Git。下面一节我们逐一搞定。注意OpenClaw迭代速度很快不同版本对Node版本要求可能有差异。装Node之前先去官方仓库看一眼package.json里的engines字段再决定版本能省掉很多奇怪报错。2. 环境准备把WSL2、Docker、Node.js一次配好2.1 WSL2安装与基础配置别跳过内核更新现在装WSL2比前几年省事多了。用管理员权限打开PowerShell或Windows Terminal执行wsl --install这条命令会默认安装Ubuntu并启用WSL2特性。装完重启电脑第一次进入Ubuntu时会让你设置用户名和密码。注意这个用户名会被记录在WSL的默认用户里后面使用wsl ~进入时用的就是它。然后检查一下当前WSL版本确保是2而不是1wsl --status wsl -l -v看到VERSION列是2就对了。如果你之前装过WSL1的发行版用wsl --set-version Ubuntu-22.04 2升级。很多人部署OpenClaw卡在openclaw无法安全验证或环境不全其实就是WSL2内核太旧或默认版本还是1导致的。进入WSL后可以放一个.wslconfig文件来限制资源占用。在Windows用户目录下新建C:\Users\你的用户名\.wslconfig内容可以参考[wsl2] memory8GB processors4 swap2GB localhostForwardingtrue改完在PowerShell里执行wsl --shutdown让它生效。这个文件强烈建议加不然WSL2默认会吃一半内存你开个浏览器加IDE机器直接卡成幻灯片。还有一个小技巧在/etc/wsl.conf里设置[automount] enabledtrue否则某些发行版默认不会自动挂载Windows磁盘。2.2 Docker Desktop的正确启动方式避免管理员权限Docker Desktop在OpenClaw部署里不是必需的但如果你想跑它示例里的Postgres、向量数据库或者完整的Web服务最好装上。安装包一路Next就行装完打开Settings在Resources - WSL Integration里勾选你的Ubuntu发行版。这样在WSL内直接敲docker命令就能用到Windows侧的Docker引擎不需要在WSL里再装一套Docker。这里有一个高频坑跟热词里出现的error: start the windows daemon from a non-elevated terminal; shared clients有关。新版Docker Desktop的设计理念是Windows的Docker daemon应当在普通用户级别的终端里启动而不是用以管理员身份运行的提权终端启动。如果你习惯性右键管理员模式开PowerShell再去执行docker命令反而会报这个错。正确姿势很简单从开始菜单正常打开Docker Desktop不带管理员权限等托盘图标变绿再用普通的Windows Terminal窗口跑docker version验证。WSL内也要确认你能连上docker ps能列出一个空表说明WSL和Docker Desktop已经打通。如果报错连不上daemon去Docker Desktop的Troubleshoot里点Restart绝大多数情况能解决。2.3 Node.js和Git的安装版本锁定很重要OpenClaw是基于Node.js和TypeScript的Node版本不对会直接导致启动闪退。我推荐用nvm管理Node版本在WSL里先装nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22如果你不想用nvm直接用NodeSource的apt源装也行。但nvm的优势是随时切换版本适合这种更新频繁的开源项目。装完确认一下node -v npm -vnpm的registry建议换成国内镜像不然装依赖时可能等到怀疑人生。在WSL里执行npm config set registry https://registry.npmmirror.comGit的安装一句话sudo apt install git。需要注意一个细节Windows下clone下来的项目换行符可能会被自动转成CRLF导致Linux下的脚本执行时报诡异的错误。在WSL里设置git config --global core.autocrlf input这样Git只会在提交时处理换行符checkout到WSL里不会乱改文件。另外如果你在Windows侧用VS Code编辑WSL文件推荐装Remote-WSL插件直接用Ctrl调出WSL终端省去来回切换的麻烦。3. OpenClaw安装与模型接入实操3.1 安装建议手动Clone而不是一键脚本OpenClaw提供了一键安装脚本社区里也有人在传。但我个人的建议是第一次部署别用一键脚本手动clone加install这样你能清楚地知道每一步到底做了什么遇到问题也方便排查。在WSL里执行cd ~ git clone https://github.com/openclaw/openclaw.git cd openclaw npm installnpm install这一步可能持续几分钟取决于网络和机器性能。装完先别急着启动先把配置文件准备好。项目目录下一般会有一个.env.example复制一份cp .env.example .env然后编辑.env关键配置项大概长这样AI_PROVIDERollama AI_MODELqwen2.5:3b OLLAMA_BASE_URLhttp://host.docker.internal:11434 GATEWAY_PORT18789 GATEWAY_HOST0.0.0.0 CLAW_DBsqlite://./clawdb/claw.db OPENCLAW_API_KEYyour_api_key_here你需要根据自己的情况替换。GATEWAY_PORT是OpenClaw Web控制台的端口默认18789。CLAW_DB是记忆存储位置本地单机用SQLite就够了。如果是跑官方示例里的完整架构可能还要配Postgres但新手上来先别加复杂度。提示如果你用Docker Desktop跑PostgresOpenClaw连接宿主机服务时要用host.docker.internal而不是localhost。因为OpenClaw跑在WSL2里WSL2内的localhost指向的是WSL2自身而host.docker.internal才会解析到Windows宿主机。3.2 连接大模型本地Ollama和API方式怎么选OpenClaw本身不带模型它需要接入一个能看到的大模型。两种主流接法一是接OpenAI兼容API二是接本地Ollama。接API的方式最省事在.env里把AI_PROVIDER改成对应配置填上你的API Key和Base URL就行。很多模型服务都提供OpenAI兼容端点填对地址就能用。这种方式的好处是模型能力强、响应快坏处是要联网、按量付费数据也会出本地。接Ollama的方式适合在意隐私、想免费跑的同学。先在Windows宿主机装Ollama拉一个模型比如ollama pull qwen2.5:3b这里说一下为什么热词里频繁出现qwen2.5-3b 关联到openclaw。因为3B参数量的大模型在普通电脑上就能跑显存或内存8GB左右就够很多人拿它做OpenClaw的入门模型。但你要知道3B模型的推理能力相对有限OpenClaw的一些复杂任务它可能理解不了适合先跑通流程真正干活建议换7B或14B。Ollama装好后默认只监听127.0.0.1而OpenClaw在WSL2里Windows侧的Ollama它直接访问不到。要做两件事一是设置环境变量让Ollama监听所有网卡setx OLLAMA_HOST 0.0.0.0重启Ollama然后在WSL里测试curl http://localhost:11434/api/tags不要在WSL里用localhost测那个localhost是WSL自己的。应该用你的Windows宿主机IP或host.docker.internal。测试通了再把.env里的OLLAMA_BASE_URL指向它。3.3 启动Gateway控制台验证部署是否成功配置完成后的启动命令很简单在OpenClaw项目目录里npm run gateway或根据版本不同可能是npx openclaw gateway start看到日志里出现gateway listening on 18789之类的输出就说明网关起来了。然后在Windows浏览器里打开http://localhost:18789能看到控制台界面说明WSL2的端口转发正常工作。如果页面打不开大概率是WSL2的镜像网络模式问题。较新版本的WSL支持在.wslconfig里加networkingModemirrored加上后wsl --shutdown重启端口互通会顺滑很多。这个改动对OpenClaw和Ollama的互通也有帮助。启动后建议先跟它随便聊两句问你现在是什么确认模型接入是否正常。如果它回答你说明整条链路已经通了。如果回答卡住或报错大多数情况下是Ollama地址配置不对或者模型没拉下来。这里强烈建议把日志打开——在Windows控制台里观察OpenClaw的输出错误信息会直接告诉你哪一步断了。4. skill系统与Companion配置4.1 skill机制怎么让智能体学会新技能OpenClaw的skill是它区别于很多AI壳子的核心设计。它不要求你写代码而是用自然语言加结构化描述就能给智能体增加一项技能。你可以把skill理解为给智能体的一套操作手册某种情况出现时按手册里的步骤执行。在OpenClaw项目目录里通常有个skills目录社区也维护了大量现成skill。一个skill文件一般是YAML或JSON格式大致长这样name: 查询磁盘空间 description: 当用户询问磁盘使用情况时执行df -h并解读输出 trigger: 查询磁盘|磁盘空间|磁盘使用 steps: - run: df -h - reply: 根据命令输出总结磁盘占用情况这里我简化了真实格式会有更多字段比如参数定义、前置条件、后置动作等。关键在于OpenClaw的调度器会根据大模型对用户意图的理解匹配到对应的skill然后执行里面定义的动作。这就是为什么社区里有人把OpenClaw玩成了个人自动化助理——你可以把日常一切重复操作封装成skill让智能体替你执行。写skill的时候要遵循小步快跑的原则先写一个最小可用版本试通了再逐步加复杂分支。别一上来想写个终极全能skill调试起来会让你崩溃。还有一点skill的名称和描述尽量明确因为大模型是靠语义匹配来找技能的描述越清晰命中率越高。4.2 Companion浏览器扩展配置让智能体操作网页Companion也叫OpenClaw Companion是官方出的浏览器扩展装上之后OpenClaw就能直接操作你当前打开的浏览器页面比如自动填表、点击按钮、抓取页面信息。配置它的大致流程是这样的先在浏览器扩展商店搜索OpenClaw Companion并安装。打开扩展的配置页填入你的Gateway地址http://localhost:18789。如果你的.env里设置了OPENCLAW_API_KEY这里也要填对应的Key。保存后扩展应该会显示已连接状态。这时候回到OpenClaw控制台你可以给它发一条指令比如帮我在当前页面找到所有价格超过100元的商品。它会通过Companion去读取页面的DOM结构然后执行操作。如果你的页面没有反应先检查两件事第一扩展是否在了普通浏览器窗口而不是隐私窗口第二Gateway地址是否填了https却用的是http协议。4.3 把qwen2.5-3b这类小模型接到OpenClaw上的效果评估很多搜ollama部署openclaw的朋友就是想让智能体跑在本地不依赖API。我实测下来3B模型跑起来确实轻快但这模型在OpenClaw里能不能做好工具调用是另外一回事。3B模型理解简单指令没问题比如查一下磁盘空间但让它处理多步任务、理解长上下文时容易想一出是一出。如果你的流程涉及多个skill串联建议换7B或14B量化版或者用API方式。我个人的配置习惯是日常调试用qwen2.5:3b因为响应快、不花钱真正跑正经任务时切到更大模型或云端API。切换方式很简单改.env里的AI_MODEL重启网关即可。这里有个小坑Ollama拉模型时的量化版本后缀比如qwen2.5:3b-instruct-q4_K_M不同参数下性能和占用差异很大。如果你内存有限优先选q4量化别盲目上fp16否则推理时内存会爆掉。5. 常见问题排查与避坑指南5.1 碰到无法安全验证和PowerShell执行策略限制这个报错要分两种场景看。第一种是你在Windows里运行某个下载来的脚本PowerShell提示无法安全验证或无法加载文件因为在此系统上禁止运行脚本。大多数情况下这不是文件本身有问题而是PowerShell的执行策略默认没有放开。你可以先看当前策略Get-ExecutionPolicy如果输出是Restricted用下面的命令放开当前用户维度的限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned的意思是本地脚本可以运行从网上下载的脚本需要有可信签名。这比直接设为Unrestricted要稳妥不建议为了省事把策略全部放开否则以后下载到恶意脚本时风险很大。第二种场景是下载安装包时浏览器或系统提示无法验证发行者。这种情况先别急着点仍要运行先核对文件哈希。在PowerShell里执行Get-FileHash ./下载的文件.exe -Algorithm SHA256然后去官方发布页比对SHA256值能对上再运行。这是Windows环境里最稳妥的习惯尤其是跑开源项目相关工具时能避免装到被篡改的包。5.2 Docker daemon的non-elevated terminal报错应该怎么破这是Docker Desktop新版引入的一个机制性变化。报错信息通常长这样error: start the windows daemon from a non-elevated terminal; shared clients...。原因我在前面提过新版Docker Desktop的Windows daemon设计为在非管理员权限下运行如果你用以管理员身份运行的终端去执行docker命令Docker会认为当前客户端环境不安全拒绝连接。解决思路非常直接所有docker相关操作都放在普通权限的Windows Terminal或WSL终端里执行。具体步骤是退出所有管理员权限的终端窗口。在Docker Desktop托盘图标上右键选择Quit彻底退出。从开始菜单正常启动Docker Desktop不要右键管理员运行。等图标变绿后再开普通终端执行docker version验证。如果Docker Desktop一直启动不起来可能是旧的用户态daemon进程没有清干净。打开任务管理器结束所有名为Docker Desktop的进程再重新启动通常就好了。这个问题在热词里出现频率很高本质上是用户习惯了出问题就管理员权限解决但Docker这个项目反着来需要你习惯正规的用户态运行方式。5.3 端口被占用18789、11434等怎么处理OpenClaw默认端口18789Ollama默认11434这两个是高频冲突点。如果你启动时发现端口被占用先查是谁占的。在Windows PowerShell里netstat -ano | findstr :18789这条命令会列出占用18789端口的进程PID然后看这个PID对应的进程tasklist | findstr 你的PID确认是对应进程后再决定要不要结束它taskkill /PID 你的PID /F注意netstat -ano里的-a是显示所有连接和监听端口-n是数字形式显示地址-o是显示进程ID。很多人只写netstat -ano不带findstr输出刷屏反而找不到关键信息。用findstr :端口号精准过滤是正解。杀掉进程后再启动OpenClaw或Ollama。如果是防火墙导致的访问不通去Windows安全中心的防火墙设置里放行对应端口。Windows安全日志里通常也会有拦截记录遇到连不通的问题可以先翻一下能省很多猜测时间。5.4 其他高频问题速查表问题现象常见原因快速解法启动网关立刻闪退Node版本不对或.env缺失nvm use 22检查.env是否完整npm install卡住或报错网络源慢、缺编译工具换npm镜像源sudo apt install build-essential python3连不上OllamaOllama只监听127.0.0.1设置OLLAMA_HOST0.0.0.0并重启服务Companion连不上Gateway地址协议不对或API Key错误检查http/https确认Key一致WSL2内存占用过高默认吃50%物理内存在.wslconfig里限制memory文件读写特别慢项目放在/mnt/c下把项目移到WSL2文件系统~/下浏览器控制没反应扩展未连接或页面无权限重启扩展确认在普通窗口使用git clone下来的脚本报换行错换行符被转成CRLFgit config --global core.autocrlf input再补充一个坑Windows脚本命令闪退的问题。如果你在Windows侧写的脚本一执行就闪退多半是脚本编码问题。Windows下的批处理或PowerShell脚本需要用UTF-8或ASCII编码保存如果带BOM或使用GBK编码的注释执行时容易莫名退出。用VS Code打开脚本文件右下角把编码切换成UTF-8再另存为无BOM格式基本可以解决。还有热词里提到的windows子系统和windows关闭端口号其实是一类问题很多人把WSL2和虚拟机混为一谈以为在WSL2里关端口就能影响Windows但实际上端口转发和防火墙规则都在Windows侧管理。理清这个边界排查问题会更快。写在最后一些个人习惯和建议我自己在Windows上部署OpenClaw的经验是先别追求大而全的功能把最基础的一条链路跑通——WSL2里启动网关、Ollama接上模型、控制台能对话——然后在此基础上逐步加skill和Companion。每加一个功能就重启验证一次不要攒一堆问题再一起排查那真的会让人崩溃。还有一点所有配置文件和skill文件最好纳入Git管理OpenClaw更新很频繁升级前先拉个分支跑通了再合别直接覆盖线上配置。如果你发现机器内存只有8GB我的建议是别装Docker Desktop直接在WSL2里跑Node网关加Ollama通常更省资源也更稳定。最后分享一个小技巧每次改完.env别忘记用wsl --shutdown再重启WSL有些环境变量只在WSL启动时加载一次不重启的话改了等于没改。