如果你和我一样平时喜欢折腾各种开源 AI 工具那对 OpenClaw 这个名字应该不会太陌生。简单说它是一个开源的智能体运行框架可以理解成“本地版的 AI 操作员”你给它配置好模型、工具和记忆它就能帮你处理消息、操作文档、调用服务、执行自动化任务。我最初是在 Linux 服务器上跑的后来因为日常主力机是 Windows就想着把它也装到本机 Windows 环境里。结果一装就是小半天中间踩了 WSL2、Docker Desktop、Node.js 权限、端口占用这一连串的坑。这篇文章就是把我整个 Windows 安装使用 OpenClaw 的过程、原理和排错经验完整记录下来适合刚接触 OpenClaw、想在 Windows 上把它跑起来的开发者参考。哪怕你之前没用过 WSL跟着一步步来也能把环境搭起来。1. 先搞清楚 OpenClaw 是什么为什么在 Windows 上装它有点折腾1.1 它到底是干什么的OpenClaw 本质上是一个“智能体运行时”。它不像 ChatGPT 网页版那样你问一句它答一句而是把一个或多个大模型接进来再挂上各种工具让模型能主动去执行任务。比如你可以让 OpenClaw 去读一个目录下的所有 Markdown 文件、总结内容后生成报告可以让它调用本地 Elasticsearch 查询日志可以让它把任务整理成笔记写到 Obsidian 仓库里甚至可以配置定时任务让它每天自动处理消息。它和普通脚本最大的区别是“决策能力”。普通脚本是写死的流程OpenClaw 是模型根据当前输入、上下文、可用工具自己决定下一步调什么工具、怎么调。所以它不是代替你写代码而是代替你“操作”那些已经存在的服务和文件。在部署架构上OpenClaw 通常由一个核心服务加多个插件组成。核心服务负责消息路由、任务调度、模型调用插件负责接外部系统。官方支持的运行方式包括 Docker 容器和 Node.js 直接运行Windows 下最省心的路线就是“WSL2 里跑 Linux 环境或者 Windows 上直接用 Node.js 跑再配合 Docker Desktop 做服务依赖”。1.2 Windows 环境的真实处境OpenClaw 这个项目从设计之初就更偏向 Linux/macOS 环境。为什么因为它的大部分依赖工具比如 Docker、Redis、Elasticsearch都是 Linux 生态里最顺手的。在 Windows 上装这些东西也不是不行但你会遇到几个实实在在的问题WSL2 默认没启用或者安装了但内核版本不对导致各种“无法安全验证”之类的报错。Docker Desktop 在 Windows 上有时候要普通终端启动 daemon有时候又要在管理员终端启动权限不一致就会报错。Node.js 版本太旧或者 npm 脚本执行策略受限命令行一运行就闪退连错误信息都看不到。这些坑我在后面都会逐一展开。但先说结论Windows 上装 OpenClaw 完全可行只是需要按顺序把三块基础设施准备好。我建议的安装顺序是先 WSL2再 Docker Desktop再 Node.js最后才是 OpenClaw 本体。这个顺序千万别乱因为 OpenClaw 安装过程中可能会自动检测 Docker 和 Node 环境少了前面任何一个你都会被一堆莫名其妙的报错劝退。2. 装之前必须做好的三件事WSL2、Docker 和 Node.js2.1 先确认 WSL2 状态别一上来就装很多教程会直接让你打开 PowerShell 敲wsl --install但我不建议这么做。第一步应该是先检查当前系统的 WSL 状态因为很多人电脑里其实已经装了 WSL1 或者老版本内核直接覆盖安装反而会出现版本冲突。打开 PowerShell建议以普通用户身份不要用管理员后面解释原因运行wsl --status如果之前装过但状态不对你会看到类似“默认版本设置为 2”或者“WSL 未安装”的输出。继续看发行版情况wsl --list --verbose这个命令会列出你装了哪些 Linux 发行版以及每个发行版使用的 WSL 版本。如果列表为空说明还没装发行版如果显示版本是 1需要升级到 2。我建议直接执行一次完整更新wsl --updatewsl --update会从官方源拉最新内核解决很多内核签名和兼容性问题。执行完后重启电脑再跑wsl --status确认输出里包含“默认版本: 2”的字样。注意如果你在装 Linux 内核更新包时Windows 弹出“无法安全验证”或“Windows 无法验证此设备所需的驱动程序的数字签名”之类的提示多半是下载的更新包被系统拦截了。别硬装回到 PowerShell 再用wsl --update拉一遍或者去微软官方文档下载对应版本的内核更新包右键属性里勾选“解除锁定”再安装。WSL2 装好之后还要装一个发行版。一般用 Ubuntu 22.04 LTS 比较稳。在 PowerShell 里执行wsl --install -d Ubuntu-22.04第一次启动会让你设置 Linux 用户名和密码设置完先跑一下sudo apt update sudo apt upgrade -y把系统基础包更新一遍。这一步也很有必要因为后面 OpenClaw 的脚本在旧软件源环境下可能会缺少依赖。2.2 Docker Desktop 与 WSL2 后端的关系OpenClaw 的很多依赖服务比如模型推理网关、Elasticsearch、Redis我建议用 Docker 跑而不是直接在 Windows 里装原生版。原生版在 Windows 上的端口监听、文件权限、重启自启动都容易出问题而 Docker 容器配合 WSL2 后端体验要顺滑得多。Docker Desktop for Windows 安装时最关键的一个选项就是“Use WSL 2 based engine”。这个选项会默认把 Docker 的 daemon 跑在 WSL2 虚拟机里Windows 这边的docker命令只是客户端两者通过本地 socket 通信。安装完成后打开 Docker Desktop进入 Settings - General确认 WSL 2 based engine 是勾选状态。然后在 PowerShell 里跑docker version docker info如果能看到 Client 和 Server 两段信息说明 Docker daemon 正常工作。如果只有 Client 没有 Server或者提示“cannot connect to the Docker daemon”那大概率是 Docker Desktop 没启动成功或者 WSL 内核和 Docker 不兼容。很多朋友在这时候会遇到一个经典报错error: start the windows daemon from a non-elevated terminal; shared clients...这个问题的根源很常见你在管理员终端里启动过 Docker daemon或者 Docker Desktop 的服务启动账户和当前终端权限不一致然后你又在普通终端里执行docker命令客户端连不上 daemon。解决办法是关掉所有管理员权限的终端从普通终端重新启动 Docker Desktop再执行docker version。如果还不行就去 Windows 服务管理器里找到com.docker.service把启动类型改为“自动”确保它不是被禁用状态。2.3 Node.js 环境版本管理和 PowerShell 权限OpenClaw 的核心进程是 Node.js 写的所以 Node 环境是必须的。这里我强烈建议不要直接去官网下最新版而是先用 nvm-windows 做版本管理。原因很简单OpenClaw 这类框架对 Node 版本有要求太新的版本可能有一些原生模块编译不通过太旧的版本支持不了新语法。nvm 可以让你在不同项目间切换 Node 版本遇到版本不兼容时不用重新装系统。装完 nvm-windows 后在 PowerShell 里执行nvm install lts nvm use lts node -v npm -v这里有一个很坑的地方npm 全局安装或运行脚本时如果 PowerShell 执行策略受限命令会一闪而过或者在终端里直接闪退。运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令的作用是允许本地脚本运行但远程下载的脚本仍然需要签名。设置完以后再跑npm -v就不会闪退了。这个设置只对当前用户生效不会影响系统安全策略。提示如果你之前装过旧版 Node.js建议通过 nvm 安装后在项目目录里单独跑npm init避免全局缓存里的旧包影响 OpenClaw 的依赖解析。3. 正式安装 OpenClaw命令、配置和启动3.1 选择安装方式npm 全局包还是 npx 初始化OpenClaw 的安装方式在不同版本里略有不同以我实际部署时用的方式来说最主流的是通过 npm 全局安装 CLI 工具。打开 PowerShell执行npm install -g openclaw安装完成后验证命令是否存在openclaw --version如果你的 npm 全局 bin 路径没有加入系统 PATH这里会提示“命令不存在”。解决方法是把 npm 的全局路径加到 PATH 环境变量里。查看全局路径npm prefix -g然后把得到的路径加到系统环境变量 Path 中重启终端。如果你不想全局装也可以用npx openclaw init my-project这种方式会把 OpenClaw 装到当前项目的 node_modules 里适合想把配置和代码放在一起管理的场景。我个人还是建议全局装 CLI因为后面启动、查看日志、管理多项目都更直接。3.2 初始化配置模型接入和工具链挂载安装完成后接下来就是初始化项目。创建一个目录进去mkdir openclaw-lab cd openclaw-lab openclaw init这个命令会在当前目录下生成一个配置文件通常是openclaw.config.json或.env具体名称看版本。初始化过程中它会问你几个问题选择模型提供方本地模型比如 Ollama还是云 API配置模型名称和地址是否启用内置工具浏览器、文件系统、命令执行是否接入记忆插件这里我重点说一下模型配置。如果你本地有 Ollama并且已经拉取了qwen2.5:3b模型那配置可以写成{ model: { provider: ollama, name: qwen2.5:3b, baseUrl: http://localhost:11434 }, tools: { filesystem: true, shell: false, docker: true }, memory: { type: obsidian, vaultPath: D:/Notes } }需要注意baseUrl的地址不能写成127.0.0.1的情况要看 OpenClaw 运行在哪里。如果你的 OpenClaw 直接跑在 Windows 上那么localhost:11434没问题如果 OpenClaw 跑在 WSL2 里而 Ollama 跑在 Windows 宿主机上那地址要写成 WSL2 中访问宿主机的 IP比如http://172.x.x.x:11434具体情况要看wsl hostname -I的输出。shell: false是我刻意关掉的。因为 OpenClaw 如果具备直接执行 shell 命令的能力虽然很方便但风险也高。我一般只开启 filesystem 和 docker 这两个受控工具让模型能读写文件、操作容器但不会直接执行任意系统命令。3.3 启动服务与验证是否跑通配置完成后启动命令非常简单openclaw start启动后OpenClaw 会先加载模型连接、初始化记忆库、注册工具然后监听默认端口。我部署的版本默认监听在127.0.0.1:3100左右具体端口看日志输出。验证是否跑通的方法有几种看终端日志出现类似 “Model connected” 和 “Tool registry ready” 就说明核心服务起来了。打开浏览器访问http://127.0.0.1:3100如果是带 Web UI 的版本会看到一个管理界面。如果只有 API 服务可以发一个简单的 POST 请求测试。例如curl -X POST http://127.0.0.1:3100/api/chat -H Content-Type: application/json -d {\message\:\你好请用一句话介绍你自己\}如果返回了模型的回答说明整个链路已经通了。此时 OpenClaw 已经在 Windows 上正常工作后面就是慢慢加工具、调插件的事了。4. 实操过程中最常见的五个坑附排查思路4.1 WSL 状态异常与“无法安全验证”这个坑我估计一半以上的人都会踩。明明按照教程敲了wsl --install也看到 Ubuntu 图标了结果运行任何 WSL 命令都报错或者 Windows 直接弹“无法安全验证”的提示。我的排查思路很简单先看wsl --status如果输出里没有明确写“默认版本: 2”就先wsl --update再重启系统。如果重启后 Ubuntu 还是启动不了就在 PowerShell 里执行wsl --shutdown wsl --set-default-version 2 wsl --list --verbosewsl --shutdown这个命令很多人不知道它的作用是强制关闭所有 WSL 虚拟机。很多 WSL 相关的卡死问题一梭子这个命令就能解决因为它会把异常的虚拟化状态清掉下次启动时重新初始化。如果还不行去“启用或关闭 Windows 功能”里检查“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个选项是否都勾上了。这一步容易被忽略尤其是“虚拟机平台”没勾的话WSL2 根本无法工作但系统不一定给你明确报错。4.2 Docker daemon 启动失败与权限不一致Docker 的问题一般集中在两种情况。第一种是 Docker Desktop 图标一直转圈但docker version只显示客户端。这种情况多半是 WSL2 内核版本偏低Docker Desktop 的底层虚拟机起不来。解决方法是回到 WSL 终端执行uname -r如果内核版本号很旧运行sudo apt update sudo apt upgrade -y wsl --update第二种情况就是前面提到的error: start the windows daemon from a non-elevated terminal。我吃过这个亏。当时我在管理员 PowerShell 里启动过 Docker 服务后来又把 Docker Desktop 设置成开机自启结果普通终端里的docker命令一直连不上。最后我做的操作是退出 Docker Desktop。关闭所有管理员终端。从普通终端重新启动 Docker Desktop。等右下角图标变成稳定状态后再执行docker info。这样就好了。这个问题的本质是 Windows 上 Docker daemon 的启动会话和客户端会话不一致你只要保证“用哪个终端操作就用哪个终端启动 daemon”基本就能规避。4.3 端口被占用和脚本闪退OpenClaw 默认端口如果被占用启动时会直接报错退出。最常见的占用者就是 Elasticsearch、Redis 这些服务它们默认也占用 9200、6379 等端口而 OpenClaw 的控制台或 API 端口有时会被配置成类似的端口。如果启动日志提示端口被占用先找到占用进程netstat -ano | findstr :3100假设输出结果是TCP 127.0.0.1:3100 0.0.0.0:0 LISTENING 12345最后一列是 PID然后用taskkill /PID 12345 /F强制结束这个进程再重新启动 OpenClaw。但如果这个 PID 对应的是 Elasticsearch我建议不要直接 kill而是改 OpenClaw 的监听端口或者反过来改 Elasticsearch 的端口配置让两个服务共存。脚本闪退的问题常见于 npm 脚本在 Windows 上一闪而过。这多半是执行策略问题按照前面 2.3 节设置ExecutionPolicy就能解决。还有可能是 Node.js 路径里有中文或空格导致 npm 全局脚本找不到解释器。建议把 Node.js 安装路径统一到英文目录比如C:\dev\nodejs能少踩一半的坑。4.4 命令找不到和模型加载失败openclaw命令找不到除了 PATH 问题还有一个隐蔽原因npm 全局安装时权限不够实际装到了用户目录下的临时位置。这种情况建议卸载重装npm uninstall -g openclaw然后以普通用户终端重新安装不要用管理员权限。npm 在管理员和普通用户两种模式下全局路径可能会不一样混着用会导致命令时而存在时而不存在。模型加载失败一般看日志里的详细报错。最常见的两类一是qwen2.5:3b模型没下载完整Ollama 那边显示模型名称和配置不一致二是baseUrl不通。在 Windows 上调试时可以直接在 PowerShell 里先测试模型服务curl http://localhost:11434/api/tags如果返回 JSON 列表说明 Ollama 正常。如果连接失败则先排查 Ollama 是否设置成了仅监听 127.0.0.1还是监听所有网卡再结合 OpenClaw 运行环境确定用哪个地址。4.5 把高频问题整理成速查表下面这个表是我后来整理给自己团队用的遇到问题先对号入座能省不少时间。现象可能原因排查方向wsl 命令报错或无法安全验证WSL 内核/功能未开启wsl --update、检查 Windows 功能启动 Ubuntu 后闪退WSL 虚拟机状态异常wsl --shutdown后重启Docker 只有客户端没有服务端daemon 未启动或权限不一致用普通终端重启 Docker Desktop提示 start the windows daemon from non-elevated管理员终端与普通终端混用统一使用普通终端端口被占用其他服务抢占找到 PID 后 taskkill 或改端口openclaw 命令不存在PATH 未配置或安装目录异常npm prefix -g检查全局路径模型连接失败地址或模型名不对curl 测试模型服务 /api/tagsnpm 脚本一闪而过PowerShell 执行策略限制Set-ExecutionPolicy RemoteSigned5. 进阶玩法把 OpenClaw 接入本地模型、笔记库和中间件5.1 用 qwen2.5-3b 做本地推理很多人用 OpenClaw 的目的就是完全离线跑一个 AI 助手不想把私人数据发送到云端。这时候本地小模型就很重要。qwen2.5-3b 是性价比很高的选择参数量 3B显存要求不高CPU 也能跑但推理速度偏慢。在 Windows 上跑 qwen2.5-3b我建议通过 Ollama 管理。安装 Ollama 后拉取模型ollama pull qwen2.5:3b然后确认模型能正常对话ollama run qwen2.5:3b 你好OpenClaw 那边只要把 provider 配成ollama模型名写qwen2.5:3b就能把整个推理链路串起来。用 3B 模型跑复杂任务时模型能力会明显弱于大模型这是正常的。我的经验是OpenClaw 里的“决策”和“工具调用”这类逻辑尽量让模型少做长链路推理把复杂任务拆成多个小任务成功率会高很多。举个例子让 OpenClaw 同时做“读取文件 总结 写笔记”三个动作3B 模型经常会在某个环节丢上下文。但如果你把任务拆成两步先让它读文件并输出总结再让它把总结写入 Obsidian每一步单独触发效果会稳定不少。5.2 把 Obsidian 变成 OpenClaw 的长期记忆OpenClaw 有个很实用的功能是记忆系统。默认的记忆可能只存在本地数据库里但我更推荐把它指向 Obsidian 笔记库这样所有记忆都是 Markdown 文件你随时能用 Obsidian 打开查看、修改甚至手动干预。在配置文件的 memory 部分写memory: { type: obsidian, vaultPath: D:/ObsidianVault, maxResults: 10, recursive: true }这样 OpenClaw 在对话中遇到需要“回忆”的场景会检索指定的笔记目录把相关片段作为上下文注入。用久了你会发现这个机制其实是在不知不觉中给你维护一个“可检索的私人知识库”。比如你有了一些项目笔记OpenClaw 在处理新任务时如果和旧笔记内容相关它会自动翻阅笔记并引用之前的信息相当于拥有了跨会话的长期记忆。这里要提醒一下OpenClaw 对 Vault 的访问是双向的。它既能读也可能写。如果你不想让 AI 往笔记库乱写东西可以把 memory 配置成readonly: true或者在工具权限里关掉对笔记目录的写权限。我第一次就把“让 OpenClaw 自动整理周报”配置成向 vault 写文件结果它用了我的真实笔记目录写了一大堆杂乱的临时文件清理了半天。5.3 接入 Elasticsearch、Redis 和 Docker 服务OpenClaw 的价值在于它能调用你已有的基础设施。Windows 上最常见的组合是 Elasticsearch Redis Docker。Elasticsearch 可以当 OpenClaw 的“事实数据库”比如让它在回答问题时先查一次 ES再结合检索结果生成回答。启动 Elasticsearch 后把地址配到 OpenClaw 工具里docker run -d --name es-openclaw -p 9200:9200 -e discovery.typesingle-node docker.elastic.co/elasticsearch/elasticsearch:8.11.0然后在 OpenClaw 的工具配置里加上elasticsearch: { url: http://localhost:9200, indexPrefix: ai_ }Redis 则更适合做 OpenClaw 的短期状态存储。如果 OpenClaw 跑在分布式模式下多个节点之间共享会话状态、任务队列可以通过 Redis 打通。Windows 上临时调试用 Docker 跑一个 Redis 非常方便docker run -d --name redis-openclaw -p 6379:6379 redis:7-alpine至于 Docker 工具本身OpenClaw 可以配置成“允许模型管理容器”。这个功能很强大但也需要谨慎。我的习惯是只允许docker ps、docker logs这类只读操作不允许docker rm、docker exec这种破坏性操作。因为模型对系统状态的感知并不完整你无法保证它不会误删一个正在运行的数据库容器。配置里可以定义“命令白名单”docker: { enabled: true, allowedCommands: [ps, logs, inspect] }这样既保留了模型对容器状态的洞察能力又把风险控制在安全范围内。6. 写在最后一些个人建议这套 Windows 部署流程我前前后后完整跑了两遍才算理顺。第一遍几乎每个环节都出问题最主要的原因就是环境之间互相干扰WSL 版本混乱、Docker 权限不对、Node 版本太新、端口又被本地 Elasticsearch 占用。第二遍我严格按顺序来先wsl --update并重启再装 Docker Desktop然后配好 nvm 和 Node最后才初始化 OpenClaw结果一路顺畅半小时不到就全部跑通。如果让我给你一条最实用的建议那就是不要把 Windows 安装当作“在 Windows 上运行 Linux 程序”而是把它当作“用 Windows 管理一个 Linux 运行时环境”。所有跟 OpenClaw 相关的服务优先用 Docker 容器跑尽量避免在 Windows 原生安装一堆中间件。这样不仅隔离性好以后升级系统或者换电脑迁移成本也低得多。最后再分享一个小技巧OpenClaw 的配置文件和日志文件我习惯放到一个独立目录下比如D:\openclaw-data然后把 Docker 的数据卷也挂载到这个目录下。这样备份、迁移、清空重来都非常方便。如果你还在为它到底能不能在 Windows 上稳定运行而犹豫我的答案是能而且稳定。只要把环境基础打好OpenClaw 完全可以成为你日常自动化工作流里最顺手的一个本地智能体。