1. 先搞清楚OpenClaw是什么再决定怎么装1.1 它本质上是一个“AI管家”消息网关先别急着敲命令。很多人看到“OpenClaw本地安装部署”这个标题就直接去clone仓库了结果装到一半发现这玩意儿跟自己想的不太一样又卸载重来。我建议你先花三分钟理解OpenClaw的定位这对后面所有配置都有帮助。OpenClaw是一个开源AI助理框架核心作用可以理解成“消息网关”它把各种大模型APIOpenAI、Anthropic、阿里云通义、本地Ollama等接到各种交互入口上比如终端聊天、网页控制台、Microsoft Teams、Obsidian、Telegram等。你在这头发消息OpenClaw负责决定用哪个模型、带什么上下文、调用哪些工具再把结果送回那头。所以它不是一个“聊天软件”也不是单纯的SDK更不是某个大模型的官方客户端。它更像一个中间层所有消息先进来经过OpenClaw统一调度再分发到模型和工具。这也是为什么很多人刚开始部署时觉得“装完了不知道能干吗”——因为OpenClaw默认就是一个空壳框架你需要给它配置模型、配置平台接入它才真正跑起来。想清楚这一点你再看接下来的安装步骤就会明白每一步是在干什么。1.2 为什么要在Windows上部署三个典型场景理论上OpenClaw跑在Linux服务器上最省事但Windows本地部署的需求其实非常普遍我总结下来主要是三种情况前端开发环境在Windows模型服务在远程你在Windows上写代码想把OpenClaw作为本地调试工具没必要为这个专门租一台Linux服务器。团队协作工具需要AI机器人公司内部用的Microsoft Teams、飞书等想在现有Windows机器上跑一个AI bot先验证效果再考虑上线。本地模型玩家用Ollama跑qwen2.5、Llama等开源模型想通过OpenClaw把本地模型接入统一入口。这种玩法通常是WindowsGPU为主力机自然希望在Windows上部署。还有一个很现实的原因很多时候你只是想“先跑起来看看”并不是要立刻上生产。本地部署门槛低、拆了重装也方便拿来学习和验证最合适。1.3 部署方案怎么选WSL2 vs Docker vs 纯Windows在正式开始之前我先把这个关键决策讲透。OpenClaw对Windows的支持主要有三条路我实测下来的感受如下方案上手难度稳定性适用场景WSL2内安装中等高主力推荐开发和长期运行都合适Docker Desktop较高高需要隔离依赖、多服务编排时纯Windows原生低低仅临时测试不建议认真使用先说纯Windows原生。你确实可以在Windows上装Node.js然后直接跑OpenClaw但实际用起来会发现各种别扭文件路径分隔符、权限模型、部分依赖的原生模块编译都有可能在Windows环境出问题。我不建议把OpenClaw的主运行环境放在纯Windows上不是说不行而是你的时间不值得浪费在跟环境搏斗上。WSL2是目前最均衡的方案。OpenClaw在Linux环境下的表现最符合预期而且WSL2的启动成本很低不需要单独开虚拟机。你从Windows Terminal里直接进WSL2跟用Linux服务器几乎没有区别。Docker方案适合你已经有一套Docker使用习惯、或者需要把OpenClaw和数据库、其他插件服务一起编排的场景。但Docker Desktop在Windows上的资源占用偏高而且进入Docker容器调试不如直接进WSL2调命令方便。所以我的建议是初次部署选WSL2以后要正式做服务编排再迁移到Docker这个顺序最平滑。2. Windows部署前的环境准备这几样先装好2.1 启用WSL2并确认系统状态这一步做不好后面全是坑。在Windows上装WSL2有多条路径但最省事的是用管理员身份打开PowerShell直接执行wsl --install这个命令会自动启用Windows虚拟化平台组件、下载并安装WSL2内核然后默认安装Ubuntu发行版。装完后系统会提示重启必须重启别跳过。重启之后先别急着装东西用下面两条命令确认环境状态wsl --status wsl --version如果你看到类似“适用于 Linux 的 Windows 子系统”的状态信息并且版本号大于等于2说明WSL2已经就位。这里有一个很典型的坑很多人的WSL装了但默认版本是1OpenClaw跑起来性能会有明显问题后面我会在排查章节详细讲。你可以用下面的命令强制设置默认版本wsl --set-default-version 2进入Ubuntu之后第一步先把系统软件源更新一下sudo apt update sudo apt upgrade -y然后确认一下Ubuntu版本建议使用22.04或24.04lsb_release -a2.2 Node.js与包管理器的版本选择OpenClaw是基于Node.js/TypeScript开发的所以Node.js版本直接决定你能不能装成功。我建议用Node.js 20 LTS或22 LTS太老的版本会导致依赖解析失败太新的版本有时候个别原生模块还没跟上。在WSL2的Ubuntu里我推荐用nvm来装Node.js这样切换版本方便不至于因为某个项目需要不同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看到输出类似v20.x.x就说明装好了。有人会问为什么不直接用apt装因为apt源的Node.js版本通常滞后而且锁定系统全局版本后面想升级或切换比较麻烦。nvm装在用户目录下随时可以切换更灵活。2.3 Git安装与Windows Terminal配合OpenClaw源码托管在Git仓库安装官方推荐的方式就是git clone不是下载zip包。zip包缺少.git历史记录后续想更新或者切换到特定版本都会受限。在Ubuntu里直接装sudo apt install git -y git --versionWindows侧我强烈建议把Windows Terminal用起来它比传统cmd和PowerShell窗口的体验好太多多标签、配色方案、WSL2入口都集成在一起。你平时开发时开三个标签页一个跑OpenClaw服务一个跑日志查看一个留着敲命令效率完全不一样。3. OpenClaw核心安装与初始化分步讲解3.1 获取源码为什么推荐git clone环境准备就绪之后进入正式的部署环节。先选一个工作目录我习惯放~/apps下mkdir -p ~/apps cd ~/apps git clone https://github.com/OpenClaw/OpenClaw.git cd OpenClaw git checkout 稳定的版本号或分支关于checkout这一步很多人会忽略。OpenClaw迭代速度很快有时主干分支上会有未完全稳定的新功能直接跑可能遇到奇怪的问题。我建议看官方仓库的Releases页面选一个最近的release tag来安装比如git tag -l | tail -20 git checkout v1.x.x这样你就固定在一个已知稳定的版本上后续如果官方修复了关键bug再主动升级避免被主干分支的“惊喜”打断。3.2 安装依赖npm install的前前后后进入项目目录后安装依赖npm install如果是第一次跑这个过程会比较久要耐心等。我这里要提两个注意事项。第一不建议用cnpm。cnpm虽然在国内安装速度快但它会改变依赖的下载方式和目录结构OpenClaw这种对依赖完整性敏感的项目用了cnpm容易出现“模块找不到”的玄学问题。如果默认registry下载速度太慢可以只切换registry源npm config set registry https://registry.npmmirror.com装完之后如果还想恢复官方源再set回去就行。这是最干净的做法。第二安装完成后一定要看一眼有没有error级别的输出。不用管warning但只要有error就先解决再往下走。有一些error是网络超时导致的重新执行npm install就好。如果是权限问题看看是不是用了root用户。在WSL2的Ubuntu里直接用默认用户别动不动sudosudo跑npm install反而容易出现目录权限归属混乱。3.3 初始化配置模型接入是重头戏依赖装完之后项目目录里会有一个.env.example文件这是OpenClaw的配置模板。你需要复制一份并编辑你自己的配置cp .env.example .env nano .env这个文件里最关键的是模型配置。OpenClaw支持多种模型提供商本质上它们大多是OpenAI兼容API所以你只需要改几个核心字段OPENAI_API_KEY、模型名称、API Base URL。举个例子如果你用OpenAI官方的API配置类似这样OPENAI_API_KEYsk-你的key OPENAI_BASE_URLhttps://api.openai.com/v1 OPENAI_MODELgpt-4o-mini如果你用的是国内可访问的模型服务比如阿里云百炼、DeepSeek、Moonshot等它们的API大多数兼容OpenAI格式你只需要把OPENAI_BASE_URL换成对应服务商的地址再把模型名改成对应的型号即可。这可能是整个配置过程中最容易卡住的地方。OpenClaw官方文档里默认写的是OpenAI但实际使用中接口兼容的模型都可以接入甚至效果可能更好。我的建议是先用你手上现有的API key跑通不要为了“特定的某个模型”死磕。先跑通再优化模型。3.4 首次启动与验证配置完成后先执行一次构建不同版本的OpenClaw构建命令可能略有差异通常npm脚本里有build相关项npm run build构建完成且没有报错后启动服务npm start首次启动时日志会输出很多初始化信息。我标记几个你要关注的点是否成功读取.env配置模型API是否能正常连通控制台或仪表盘监听在哪个端口如果你配置了Web控制台启动完成后在Windows浏览器里访问http://localhost:指定端口应该能看到OpenClaw的管理界面。在WSL2里跑的服务Windows浏览器直接访问localhost就能通WSL2默认的网络转发机制已经处理好了不需要额外配置。如果看到一个欢迎页面、能通过界面发消息并收到AI回复恭喜你——本地部署已经成功了接下来才进入真正好玩的部分。4. Windows上最容易踩的坑从安装到运行的完整排错链路4.1 “无法安全验证”的常见来源SmartScreen与脚本执行策略热搜词里出现“无法安全验证”的情况我之前也遇到过。Windows在运行未签名的脚本或程序时会弹出“Windows已保护你的电脑”——这就是SmartScreen过滤。它跟OpenClaw本身没关系纯粹是Windows的安全机制对新鲜脚本的默认警惕。有两种情况会触发你下载了某些安装脚本或压缩包里的.ps1、.bat文件直接双击运行时触发SmartScreen。你在PowerShell里执行某些脚本时执行策略限制了脚本运行。第一种情况解决方法是确认文件来源可信之后在文件上右键选择“属性”如果底部有“解除锁定”勾选勾上再运行。如果不行就在SmartScreen弹窗里点“更多信息-仍要运行”。第二种情况直接用管理员PowerShell调整执行策略Set-ExecutionPolicy RemoteSigned这个策略允许运行本地脚本只对来自网络的未签名脚本做限制在使用上比较平衡。值得说明的是真正在WSL2里运行OpenClaw不受PowerShell执行策略影响这个坑主要出现在Windows侧辅助脚本、后续配置自动化脚本的时候。4.2 “sl2环境”与WSL2状态异常最常见的安装拦路虎热搜词里有一条很典型“sl2环境。请在powershell中运行wsl -- status”。这明显是安装OpenClaw过程中某个脚本检测WSL2环境时给出的提示。它本质上是在说当前没有运行在WSL2环境里或者WSL2本身没启用成功。出现这种情况一般有三种可能一是WSL2内核组件没装全。对一些较老的Windows版本wsl --install可能不会自动安装完整内核需要去官方文档手动下载WSL2内核更新包。二是版本本身不支持WSL2。Windows 10较旧的版本、Windows 11早期版本都曾有过奇怪的问题。最快的自查方式是打开PowerShell执行wsl --status看输出的版本信息。如果明确看到Default Version: 1就得先执行wsl --set-default-version 2。三是BIOS里的虚拟化功能没开。如果wsl --status提示Hyper-V相关错误多半是Intel VT-x或AMD-V在BIOS里被禁用了去BIOS里开启并重启。这个问题的判断顺序我跟你讲清楚你按顺序查就不会冤枉系统# 第一步看WSL整体状态 wsl --status # 第二步确认默认版本是不是2 wsl --set-default-version 2 # 第三步重新打开Ubuntu确认当前发行版的WSL版本 wsl -l -v第三步输出的表格里如果VERSION列是2就说明你的Ubuntu确实跑在WSL2上。如果显示1用下面的命令迁移wsl --set-version Ubuntu 2迁移过程可能要几分钟完成后重新进Ubuntu再跑OpenClaw就正常了。4.3 脚本闪退与日志查看另一个高频问题“Windows脚本命令闪退”多数发生在你从Windows侧直接运行一些辅助脚本比如双击一个start.bat窗口一闪而过什么都没留下。闪退的原因很简单脚本执行到一半报错而窗口没来得及显示错误信息就关了。处理方式是别双击在终端里手动执行让错误信息留在屏幕里cd 你的脚本目录 start.bat或者用PowerShell执行后通过pause保持窗口cmd /k start.bat这样就能看到真正的报错输出再对症解决。OpenClaw本身启动后如果遇到未捕获的异常也会表现为进程退出。这种时候别急着重跑先看看日志。OpenClaw会把运行日志写到~/.openclaw/logs或项目内部的logs目录下用tail -f实时盯日志tail -f ~/.openclaw/logs/combined.log很多启动失败其实只是某个API key没配对、某个端口被占用日志里白纸黑字写得很清楚。4.4 端口占用与进程清理说到端口占用这是Windows本地部署另一个常见问题。OpenClaw默认会监听几个端口如果之前有别的服务占用了启动就会失败。Windows下查找占用情况netstat -ano | findstr :3000如果看到有进程占用根据最后的PID号杀掉再重启服务taskkill /PID 12345 /F在WSL2里也可以用Linux侧的工具查看和杀掉sudo lsof -i :3000 kill -9 pid端口这块的经验是优先改OpenClaw自己的端口配置而不是杀系统的关键进程。有些端口是Windows系统服务的强行杀掉可能导致系统不稳定。5. 把OpenClaw接入日常工作流Teams、Obsidian与本地大模型5.1 接入Microsoft Teams让AI出现在团队协作里部署跑通只是第一步真正让OpenClaw产生价值的是接入你日常在用的工具。团队协作场景里Microsoft Teams是最常见的接入对象。OpenClaw接入Teams的思路是它作为一个bot身份加入团队频道团队成员在聊天里它它就会基于配置的模型能力返回回复。这个场景适合做技术答疑、日常信息查询、内容总结等。接入Teams需要在Azure门户创建一个Bot注册拿到App ID和密码然后填到OpenClaw配置里再在Teams后台把bot添加到你的团队。具体步骤如下在Azure门户中创建一个新的Bot Services资源。获取Microsoft App ID和Client Secret。把这两个值填到OpenClaw的.env里对应TEAMS_APP_ID和TEAMS_APP_PASSWORD。在Teams管理后台把bot应用添加到团队中。接入成功后在Teams里找到对应的bot发一条消息测试如果它能正常回复就说明链路通了。这个功能最适合的用法是配置一个专门的知识库模型让团队成员问问题、让bot引用知识库内容作答效率提升非常明显。5.2 接入Obsidian让AI参与笔记处理如果你和我一样用Obsidian管理笔记那OpenClaw接Obsidian之后带来的体验提升非常大。Obsidian的笔记是纯Markdown文件OpenClaw可以直接读取、解析、生成内容。实际接入方式通常不需要复杂配置OpenClaw把Obsidian vault当成本地文件目录来处理你告诉它vault路径它就能读取笔记内容回答问题时基于你的笔记库给出答案反过来也可以让它根据笔记素材生成结构化文档。我自己最常用的场景是每周五下午让OpenClaw读取我这周所有的工作笔记自动生成一份周报草稿再人工微调一下。这个流程原来要花半小时现在五分钟搞定而且由于素材都来自我自己的笔记内容准确性有保障。配置方式很简单在.env里指定vault路径例如OBSIDIAN_VAULT_PATH/mnt/c/Users/你的用户名/Documents/我的知识库注意在WSL2里访问Windows文件系统要用/mnt/c/前缀。另外要提醒一下大知识库首次扫描会比较慢可以只给OpenClaw指定一个子目录作为工作范围没必要把全库都喂给它。5.3 关联本地qwen2.5-3b模型实现纯本地推理现在很多人关注的一个玩法是把OpenClaw和本地推理模型串起来比如通过Ollama跑qwen2.5-3b完全本地部署。好处很直接不依赖外部API、数据完全留在本地、没有调用费用。具体做法分两步。第一步在WSL2里先装Ollamacurl -fsSL https://ollama.com/install.sh | sh ollama run qwen2.5:3b这个命令会拉取qwen2.5-3b模型并启动一个对话测试。确认本地模型能正常工作后再把它接入OpenClaw。第二步在OpenClaw的配置里把该模型的API Base URL指向本地Ollama服务。Ollama本身的API端口默认在11434而且它提供了OpenAI兼容的接口路径配置如下OPENAI_BASE_URLhttp://localhost:11434/v1 OPENAI_API_KEYollama OPENAI_MODELqwen2.5:3b只要你使用的模型服务商提供OpenAI兼容API配置方式都大同小异。区别只在Base URL和模型名。要说明的是qwen2.5-3b这个量级的模型单机推理速度和流畅度取决于你的机器配置。CPU推理可用但偏慢有NVIDIA GPU且装了CUDA环境会好很多。即使3b模型不如GPT-4系列在复杂任务上表现好但用于摘要、分类、日常问答等简单场景已经足够而且胜在数据不出门、零成本。6. 个人实测心得与后续扩展建议我在Windows上部署OpenClaw前后折腾了一周这里分享几个比较个人的体会。先把“最小可用闭环”跑通再谈花活。我第一次部署时一上来就想同时配好Teams、Obsidian、多个模型结果发现问题太多哪个都没调好排查起来特别乱。如果你也是第一次部署我建议这个顺序裸跑OpenClaw、连一个OpenAI兼容API、在终端里对话测试、启动Web控制台、接入一个平台工具。每一步都验证成功后再走下一步。WSL2和Windows之间的文件共享越简单越好。在WSL2里操作Windows文件比如Obsidian vault路径在/mnt/c/读写速度比Linux原生目录慢不少。如果只是偶尔读没问题但如果OpenClaw要频繁操作大量Windows目录文件建议把相关数据文件迁到WSL2原生目录下性能差距还是很明显的。日志才是最好的老师。几乎我遇到的所有问题日志里都写了原因。遇到报错先看日志别急着搜社区。有一半的问题都是API key配错、端口被占、模型名写错日志第一行就能告诉你答案。后面如果你想把OpenClaw用得更深还可以考虑把它和知识库工具结合起来做语义检索或者把多个模型配置成路由让不同类型的问题走不同的模型。本质上OpenClaw就是一个中枢你想接什么、让AI帮你做什么都取决于你的想象力和配置功底。先跑起来后面的一切都好说。