去年我第一次在Windows上部署OpenClaw的时候前前后后折腾了不少时间。起初我以为装上核心包就能直接用结果各种环境报错接踵而至光是WSL和Docker Desktop的权限问题就花了好几个晚上最后把整条链路重新梳理了一遍才明白只要按顺序把几个前置环节准备到位Windows部署OpenClaw的难度完全在可控范围内。OpenClaw是一个能把本地大模型、文件系统、命令行以及Windows桌面操作串起来的AI Agent框架。说直白一点你给AI一句帮我把桌面截图归档它不只是回复一段文字而是真的去创建文件夹、移动文件、重命名文件。这篇保姆级部署教程会把从环境安装到首次运行要做的每一步、每一条检查命令、以及我实际踩过的坑都写出来适合第一次接触OpenClaw、想在Windows上部署AI Agent的读者也适合那些已经会用AI工具但对本地自动化还不太熟悉的朋友。1. 先把OpenClaw的工作方式捋清楚再谈部署1.1 它不是一个聊天窗口而是一套大脑手的系统很多人第一次接触OpenClaw会误以为它像ChatGPT网页版一样开个窗口就能问。实际不是这样。OpenClaw解决的是让大模型真正动手干活的问题这个定位决定了它的架构和部署方式都更复杂。我习惯把它拆成四个部分来理解大脑即大模型本身可以是本地模型如Qwen2.5也可以是在线模型的API工具层文件读写、终端命令、网页操作等能力OpenClaw会把它们注册成模型可以调用的工具执行载体OpenClaw的主程序跑在容器里这个容器是隔离的、可复现的方便管理依赖和权限桥接组件对接Windows本地的Companion让容器里的AI能操作你桌面上的真实应用这四个部分缺一不可。如果你只装了主程序而没有接模型它就没有大脑如果你有模型但Companion没配置对它能思考但动不了手。1.2 我实际用下来觉得最值得复刻的三个场景部署之前先说说它能干什么这样你才知道自己为什么要装。第一个是文件整理。我让它每周日扫描指定文件夹把带有截图字样的文件按月份移动到归档目录并加上日期前缀。这个任务如果手动做毫无技术含量但重复做很烦人。第二个是本地知识库问答。我把Obsidian笔记库接进去之后可以直接问上个月我记录过哪些关于Docker的问题它会去翻我的笔记然后回答而不是凭空瞎编。第三个是日常自动化操作。比如让AI帮我打开特定软件、读取某个窗口的内容、把结果写进日志文件。这类操作是AI Agent最典型的使用方式也是OpenClaw和普通聊天助手最大的区别。1.3 为什么Windows部署比Mac更折腾如果你用的是MacOpenClaw的部署会顺畅不少因为Mac本身是类Unix环境。但在Windows上主程序默认跑在Linux容器里而Windows和Linux的文件系统、路径规则、权限模型都不一样这中间必须靠WSL来搭桥。很多Windows用户死在第一步恰恰就是因为他们跳过了WSL这个地基直接装Docker和Node。所以本文第一节就先解决WSL和虚拟化的问题这一步踏实了后面基本能一路畅通。2. Windows地基工程WSL、虚拟化与版本检查2.1 WSL到底装好没有三条命令自己判断在Windows上部署OpenClaw我的建议是第一步先打开PowerShell,依次执行下面三条命令wsl --status wsl -l -v wsl --version这三条命令分别告诉你三件事WSL整体状态、当前装了哪些发行版以及它们各自的版本号、WSL自身版本。如果wsl --status输出里能看到默认版本2这样的字样说明WSL基本可用。如果提示你还没有安装任何发行版那就需要继续往下装。如果wsl -l -v显示有一个名为Ubuntu的发行版且VERSION列是2那就说明你已经有了一个合格的环境。我遇到过一种情况是wsl -l -v输出为空但Windows功能列表里明明勾选了适用于Linux的Windows子系统。这是因为只开启了功能却没有真正安装发行版。解决方式很简单在PowerShell里执行wsl --install -d Ubuntu系统会自动下载并安装Ubuntu。2.2 遇到无法安全验证这类报错的排查链路在部署OpenClaw的过程中可能会碰到安装脚本检查WSL环境时给出无法安全验证一类的提示。第一次看到这个报错确实容易慌但实际原因往往就藏在前面的检查命令里。我的排查顺序是这样的先执行wsl --status看状态是否正常。如果它提示某个部分异常先解决这个。如果状态显示正常但问题依旧执行wsl --shutdown再重新执行wsl --status。这个操作相当于把WSL重启一遍很管用。在Windows功能里确认适用于Linux的Windows子系统和虚拟机平台两个选项都已勾选勾选后需要重启电脑。如果还不行执行wsl --update更新WSL内核然后重启电脑。注意如果你是在虚拟机或云服务器里部署还需要确认宿主机开启了嵌套虚拟化。Windows物理机上一般默认开启但不少虚拟机环境默认关闭这一项经常被忽略。我见过不少人在这个环节反复重装Ubuntu其实就是没有检查虚拟化平台是否启用。方向错了怎么折腾都没用。2.3 装好Ubuntu之后我建议立刻做的三件事WSL装好Ubuntu之后不要急着装Docker先把下面三件事做完第一打开Ubuntu终端创建Linux用户名和密码。这个密码以后会经常用到建议记好。第二执行系统更新sudo apt update sudo apt upgrade -y这一步会拉取最新的软件包列表和更新后边安装各种依赖时能省很多事。第三确认Windows能访问到WSL的文件空间。在资源管理器地址栏输入\\wsl$\Ubuntu如果能看到home目录说明文件系统桥接正常。这个桥接关系到后边Docker容器和Windows工作区之间的文件互访是OpenClaw操作文件的关键路径。3. 环境四件套Node、OpenJDK、Docker的安装顺序与版本匹配3.1 先看一眼版本对照表OpenClaw本身以及它的很多辅助组件都依赖Node.js、OpenJDK和Docker。这三个软件版本不对后面会出各种莫名其妙的错。我整理了一张在实际部署中稳定运行的版本表软件推荐版本说明Node.js22.x LTS低于18版本在编译依赖时会报错OpenJDK21 LTS17也能跑但21在较新的组件里更稳Docker Desktop最新稳定版必须使用WSL 2后端WSL2.x 内核默认版本必须设置为2Ubuntu22.04 LTS或24.04 LTS与Docker Desktop集成最好安装顺序我建议为WSL优先其次Node.js再次OpenJDK最后Docker Desktop。为什么是这个顺序因为Docker Desktop在Windows上依赖WSL 2作为后端你先把WSL装好Docker安装时就能直接利用已有的WSL环境避免它自动配置时出岔子。3.2 Node.js和OpenJDK安装时容易忽略的细节Node.js去官网下载Windows安装包MSI文件安装时务必勾选Add to PATH。很多人在这一步图省事没勾结果新开终端输入node --version一片空白。如果忘记勾选也可以手动在系统环境变量里把Node的安装目录加进PATH。安装完Node.js后新开一个PowerShell窗口执行node --version npm --version两个命令都能输出版本号说明Node安装成功。OpenJDK我推荐用Temurin发行版同样选MSI安装包。安装结束后要在PowerShell里确认java --version如果提示找不到命令一般是JAVA_HOME没有配置。在系统环境变量里新建JAVA_HOME指向JDK实际安装路径再在Path里添加%JAVA_HOME%\bin新开终端再验证一次。3.3 Docker Desktop在Windows上最典型的权限坑Docker Desktop装好之后第一次启动时会要求你接受服务协议这一步必须在Windows图形桌面环境下操作。如果你是通过远程终端或者SSH会话操作会看到Docker Desktop无法正常启动的提示。最简单的做法是先远程桌面登录Windows把Docker Desktop完整启动一遍确认托盘图标稳定显示再回到终端操作。另外有个经常遇到的现象在以管理员身份运行的终端里执行Docker相关命令反而报“daemon连接失败”或者提示需要从非管理员终端启动共享客户端。这是因为Docker Desktop内部共享管道和客户端进程的权限层级要求一致。遇到这类问题就关闭管理员终端打开一个普通用户权限的PowerShell再跑命令。Docker启动后在PowerShell里执行docker version docker info确保客户端和服务器两端都有版本信息。如果只有客户端版本却看不到服务器版本说明Docker引擎还没完全启动等一两分钟再试。3.4 五条命令一键体检环境是否就绪不需要装完一个查一个直接用下面这组命令一起检查node --version java --version docker --version wsl --status wsl -l -v如果五条命令全部正常输出Windows端的环境准备就完成了。接下来可以正式安装OpenClaw主程序。4. 安装OpenClaw主程序初始化、配置与首次启动4.1 全局安装还是源码克隆我建议从哪里入手OpenClaw的迭代速度比较快安装方式在不同版本里可能略有差异。稳妥的做法是先到官方仓库的README页面复制当前推荐安装命令而不是直接照抄别人的旧教程。目前常见的有两种方式全局安装执行npm install -g openclaw适合只打算用默认配置快速跑起来的用户源码克隆把仓库克隆到本地然后执行npm install和初始化命令适合想研究源码或修改内置功能的用户我个人的建议是第一天先源码克隆。原因很实在出问题时你能直接看到源码里的报错位置搜索issue时也能带上具体版本号别人更容易帮你定位。全局安装虽然方便但出了问题像个黑盒排查起来反而慢。如果全局安装时npm提示找不到包名不要死磕直接换成仓库README里的最新安装命令。版本更新导致包名变动是常有的事。4.2 初始化向导里需要留意的三项配置安装完成后进入一个打算作为OpenClaw工作区的目录执行初始化命令。比如cd D:\openclaw-workspace openclaw init初始化向导会问一些配置项其中有三项要格外留意。第一工作区路径。默认可能就是当前目录但我建议单独建一个目录比如D:\openclaw-workspace。不要让AI一开始就拥有对整个磁盘的访问权独立工作区既能保护系统文件也方便后续清理。第二模型提供商的初始选择。如果你还没有任何模型的API先选本地模型。本地模型后面用Ollama搭成本低、速度快适合先把Agent链路跑通。第三API Key。配置本地模型时这个字段可以随便填一个占位值比如ollama。如果你填了空有些组件会在启动时反复校验这一项白白浪费时间。4.3 首次启动最容易卡住的三个位置初始化完成之后启动主程序openclaw start这个阶段最容易遇到三类问题第一类是端口被占用。OpenClaw启动时会监听某些端口如果Windows上已经有其他程序占用了会看到端口相关的报错。先用下面命令查一下占用情况netstat -ano | findstr :3000找到占用进程的PID后在任务管理器里结束它或者修改OpenClaw配置里的端口号。第二类是Docker容器启动失败。可以用docker logs查看具体容器的输出日志根据日志信息判断。常见原因还是Docker引擎没就绪回到第3章的体检命令再查一遍。第三类是WSL环境校验不通过。如果报错信息里带有WSL相关字样不要急着重装Ubuntu先在PowerShell执行wsl --shutdown wsl --status把WSL重启一遍很多时候就能恢复正常。5. 接上大模型本地Qwen2.5和在线API两条路线5.1 为什么我建议先接本地模型OpenClaw本质上需要一个能理解工具调用的大模型。我强烈建议第一次部署时先用本地模型把链路跑通而不是一上来就接在线API。原因在于排错。如果你同时面对网络问题、API鉴权问题、模型工具调用问题出了问题根本分不清是哪一环。而本地模型没有网络和鉴权这两层干扰一旦通了就说明OpenClaw自身链路没有问题。之后再换成在线API就只需要处理单一变量。5.2 用Ollama把Qwen2.5-3B跑起来在Windows上安装Ollama非常简单官网下载安装包安装完重新开一个PowerShell窗口。然后拉取模型ollama pull qwen2.5:3b拉取完成后启动服务ollama serve服务默认监听在11434端口。为了确认服务正常用curl请求一下本地的模型列表接口curl http://localhost:11434/v1/models能返回JSON数据说明Ollama已经就绪。为什么OpenClaw能和Ollama对接这么顺畅因为Ollama提供了一个和OpenAI接口格式兼容的本地端点。OpenClaw只需要按OpenAI兼容协议去调用地址换成http://localhost:11434/v1即可不需要额外开发适配层。在OpenClaw的配置文件里将大模型相关的部分改为{ llm: { provider: openai-compatible, baseUrl: http://localhost:11434/v1, model: qwen2.5:3b, apiKey: ollama } }修改配置文件后重启OpenClaw让配置生效。5.3 在线API服务怎么接通用思路同样适用如果你不满足于本地小模型想接入更强的在线API思路完全一样。前提是API服务商提供兼容OpenAI协议的接口。配置时改三个字段即可{ llm: { provider: openai-compatible, baseUrl: https://你的服务商地址/v1, model: 你的模型名, apiKey: 你的密钥 } }有一点建议在填进OpenClaw之前先用curl手动请求一次API确认网络连通和密钥有效。这样即使后面配置出问题你也能知道不是API服务的问题而是配置的问题。5.4 如何验证Agent真的开始动手模型接好之后给AI一个安全且容易验证的指令比如请在workspace目录下新建test_agent文件夹在里面创建README.md文件写入当前时间。如果这条指令执行成功说明整条链路已经打通模型理解指令、OpenClaw调用文件工具、容器映射Windows工作区、文件真实落盘。看日志时重点观察OpenClaw的调用记录。如果日志里出现了文件写入相关的工具调用记录说明AI确实在动手执行。如果日志显示AI只是自顾自地输出了一段文字而没有调用工具那大概率是模型本身不理解工具调用的格式。这时可以换一个稍微加大参数的模型或者在指令里明确告诉它请使用文件工具完成。6. Windows Companion与Obsidian配置真正把手伸进系统6.1 Companion和主程序是怎么分工的到了这一步AI已经有了大脑也能操作Docker容器里的文件了。但OpenClaw主程序跑在Linux容器里它接触不到你Windows桌面上的真实应用。想让AI真正接管Windows电脑还需要一个桥接组件Windows Companion。这个分工可以简单理解为主程序是大脑负责思考和决策Companion是手负责在Windows桌面上执行点击、输入、打开软件等物理操作。两者通过网络通信本地回环地址相连数据不经过公网。6.2 Companion配置的四个字段一个都不能漏配置Companion时主程序和Companion客户端两边都要填四个核心字段字段示例值说明Host127.0.0.1本地回环地址Port3578两边保持一致的端口号ShareKey一段随机长字符串通信密钥必须一致Namewindows-desktop给这台Windows设备起个名字在OpenClaw配置文件中找到Companion相关的段落companion: { host: 127.0.0.1, port: 3578, shareKey: 换成你自己的随机长字符串, name: windows-desktop }然后把同样的值填进Companion客户端。这里最常出现的问题就是两边有一个字段对不上结果客户端显示连接失败。还有一个容易忽略的细节Companion要用普通用户权限运行不要用管理员权限。以前遇到类似从非管理员终端启动共享客户端的提示大多是权限层级不统一导致的。统一用普通用户会话运行主程序和Companion就能避免这类问题。6.3 把Obsidian知识库接到OpenClaw里OpenClaw不仅操作文件和桌面还能对接Obsidian这类知识管理工具让AI在你自己积累的笔记基础上回答问题。在Obsidian里需要先安装一个名为Local REST API的社区插件启用后它会在本地启动一个HTTP服务默认端口是27123。插件会生成一个API Key复制留好。然后在OpenClaw配置文件中加入obsidian: { enabled: true, apiUrl: http://127.0.0.1:27123, apiKey: 你在插件里复制的Key }配置完成后重启OpenClaw确保Obsidian正在运行然后对AI说读取我的Obsidian笔记总结最近一周的待办事项。如果它能够引用你笔记里的具体内容这个集成就算成功了。注意这个API服务不要开启允许非本机访问的选项。Obsidian本地接口最好保持仅本机可见你的笔记数据就不应该暴露在局域网或公网上。6.4 权限边界不要一开始就把所有钥匙交出去说到让AI接管Windows电脑我必须多说一句刚上手时权限边界应该设得紧一点。AI Agent的自动化能力是双刃剑。它既然能创建文件也就有可能删除错误文件它既然能操作鼠标键盘也就有可能误点危险操作。我的做法是工作区限定在独立文件夹等AI行为稳定后再逐步扩大范围不要在配置里写死自动删除类的规则先让它执行只读或新建类操作ShareKey使用随机长字符串不要用123456这种弱口令在OpenClaw配置里检查Companion的控制权限按需只开放读取能力每次让它操作真实文件前先在测试目录里跑一遍同样的指令我在实际使用中最大的体会是与其说让AI接管电脑不如说让AI当实习生。实习生该有的权限给足不该有的边界也要设定清楚。一步一步验证过之后再放开手脚让它处理更复杂的任务。这套部署流程走通之后后续无论是换更大的模型、接入更多在线服务还是扩展Obsidian之外的自动化场景都已经有了一个稳定的底座。先跑通再优化最后逐步放权这是我认为最稳妥的OpenClaw使用节奏。