1. OpenClaw 是什么以及为什么 Windows 部署会成为拦路虎OpenClaw 这个开源项目最近在开发者圈子里讨论度很高。简单说它是一个让 AI 直接操作电脑的个人助理框架你给它一个目标它会自己拆解任务、调用终端命令、读写文件、访问网页而不是像传统聊天机器人那样只动嘴不动手。整个项目跑在 Node.js 上天然跨平台但“能跑”和“跑得顺”是两码事尤其在 Windows 上。我为什么要在 Windows 上折腾它原因很实际我的日常主力机就是 Windows。我希望它能帮我整理文件、批量重命名、跑数据脚本、查日志这些在 macOS 上很顺的操作到了 Windows 上反而连安装都被卡住。折腾了两天踩了无数坑之后我把完整的部署链路整理出来希望能让后来的人少走弯路。先说核心结论OpenClaw 完全可以在 Windows 上运行得很顺畅但你必须理解它的三层架构和沙箱检测机制否则会被一连串环境报错劝退。这不是一个“下载双击安装”的软件而是一个需要自己搭配运行时的开发框架。适合这些读者参考卡在环境检查或日志报错的朋友、想接本地模型做离线使用的朋友、想搞懂 Skill 和 Windows Companion 配置的进阶玩家。1.1 核心组件Shell、Skills 与 Companions要理解 Windows 部署先得知道 OpenClaw 由三块构成Shell核心引擎负责对话循环、任务拆解、工具调用调度跑在 Node.js 运行时上Skills技能包每个技能包含一个 SKILL.md 描述文件和若干可执行脚本AI 会根据任务类型自动加载对应技能Companions平台伴侣把引擎能力暴露给具体操作系统例如 Windows Companion 提供托盘图标、本地端口监听和文件右键菜单集成。这三层里Shell 对运行环境的要求最严格。它启动时为了确保 AI 执行的命令不会破坏宿主机会检测 WSL2 和 Docker 是否可用以此决定沙箱策略。这就是很多 Windows 用户一启动就看到“无法安全验证 WSL2 环境”报错的根源。1.2 为什么 Windows 部署比 macOS 麻烦macOS 和 Linux 本身就是 Unix 系OpenClaw 的沙箱和脚本可以直接跑。Windows 不一样PowerShell 的语法体系、路径分隔符、环境变量机制都和 Bash 差异很大。OpenClaw 在 Windows 上的设计是主程序跑在 Windows 原生 Node.js 环境而 AI 要执行的命令默认放到 WSL2 的 Linux 子系统中运行从而复用大量 Bash 生态工具。所以 Windows 部署的本质不是“装一个软件”而是“搭一个让 Node.js 主程序和 WSL2 沙箱协同工作的混合环境”。我在实际部署中看到的大多数报错都来自这个混合环境某个环节没配对。从这一节开始后面每一步我都会给出具体命令和验证方法并且解释为什么要这么做。2. 部署前的环境地基Node.js、WSL2 与 Git2.1 Node.js 版本选择与安装细节OpenClaw 官方要求 Node.js 18 以上但我实测下来 18 的生态兼容性一般建议直接上 LTS 版本也就是 20.11 或 22.x。尽量别用官方标注为非 LTS 的“最新版”OpenClaw 安装依赖时可能编译原生模块非 LTS 版本容易踩坑。安装方式很简单去 Node.js 官网下载 Windows Installer.msi安装包一路下一步就行。注意两个容易被忽略的点安装向导里务必勾选 “Add to PATH”否则终端里找不到 node 命令安装完成后必须重新打开终端让 PATH 环境变量刷新。装完用下面三条命令验证node -v npm -v where.exe nodewhere.exe node能显示 node 的完整路径如果输出为空说明 PATH 配置有问题。我见过很多人在这一步卡住终端提示“node 不是内部或外部命令”十有八九是安装时没勾选 Add to PATH或者装完没重启终端。2.2 WSL2 是硬需求不是可选项OpenClaw 在 Windows 上执行命令时要靠 WSL2 提供沙箱环境。想跳过这一步直接运行是不行的最好别抱侥幸心理。现在安装 WSL2 已经很简洁用管理员身份打开 PowerShell执行wsl --install这个命令会自动安装 WSL2 内核和默认的 Ubuntu 发行版。装完重启电脑然后确认版本状态wsl --status wsl --version关键看默认版本是不是 2。如果系统里已有旧版 WSL1需要手动切换wsl --set-default-version 2进入 Ubuntu 子系统后先把基础环境更新一下sudo apt update sudo apt upgrade -y这一步很多人会跳过结果后面 OpenClaw 在沙箱里安装 Python 依赖时缺包报错反而更浪费时间。2.3 Git 与 Ollama 的提前准备OpenClaw 的 Skills 大多通过 Git 仓库拉取安装所以 Git 是必须的。Windows 侧装 Git for WindowsWSL2 里的 Ubuntu 一般自带 Git但为了主程序在 Windows 侧也能直接操作仓库建议两边都装避免路径识别问题。如果打算接本地模型做离线使用提前装好 Ollama Windows 版。全部准备完成后用这条清单做一次总验证检查项命令预期输出Node.jsnode -vv20.x 或更高npmnpm -v10.x 或更高Gitgit --versiongit version 2.xWSL2wsl --status默认版本 2、已安装发行版Ollamaollama --version具体的版本号5 条命令全部有输出地基才算打完。这个检查清单我在后面排查问题时反复使用建议直接收藏。3. 安装主程序与初始化从命令行到第一次对话3.1 用 npm 全局安装环境没问题后就可以装主程序了。推荐用 npm 全局安装这样任意目录都能直接调用 openclaw 命令具体包名以官方文档为准我这里用的是当前版本的命名npm install -g openclaw/openclaw国内网络环境下 npm 下载可能很慢可以先把 registry 切换到国内镜像源npm config set registry https://registry.npmmirror.com安装完成后验证版本openclaw --version能看到版本号说明安装成功。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Windows 上这个目录通常是%APPDATA%\npm可以在系统环境变量里手动加进去。3.2 初始化向导与关键决策首次使用建议先运行初始化openclaw init向导会引导你完成几件事选择默认模型提供商、填写 API Key、设定工作目录、选择沙箱策略。这个向导交互很友好但我建议在跑之前先想清楚一个问题主要用云端 API 还是本地模型这个决策影响后面不少配置。OpenClaw 的模型接入是按 Provider 组织的一个 Provider 对应一套模型服务配置在~/.openclaw/settings.json里。如果后面想切换改配置文件就行但一步到位的话明显更省事。3.3 用一个小任务验证全链路初始化完成后直接启动openclaw进入交互式 Shell 后别急着上复杂任务先问最简单的问题“列出当前目录下的所有文件”。这句话能验证三件事模型调用是否正常它能理解问题并给出回复工具调用是否正常日志里能看到它在实际执行ls或dir命令沙箱执行是否正常命令真正运行在 WSL2 环境里而不是报权限错误。这条链路通了OpenClaw 在 Windows 上的部署就算成功了大半。我建议再用一个稍复杂点的任务继续验证“创建一个临时目录在里面生成一个 hello.txt 文件内容写 hello openclaw然后读出来给我看”。如果文件读写、路径转换都没问题后面就可以放心用了。4. 模型接入双路线云端 API 与本地 Ollama4.1 云端 API 配置与上下文管理云端 API 是最快的入门方式。在~/.openclaw/settings.json里找到 models 配置段填入对应的 API Key 和模型名称。以 Anthropic Claude 为例配置大概是{ models: { provider: anthropic, model: claude-sonnet-4-5, apiKey: sk-xxxx } }不同提供商的字段名略有差异但思路一致。这里提醒一个容易被忽略的点云端 API 的费用和上下文长度直接相关。OpenClaw 这类 agent 框架会为了完成任务频繁调用工具每次工具结果都会占上下文所以长任务的 token 消耗比普通聊天高得多。建议在 settings 里设置合理的 maxTokens 上限避免一次失控调用烧掉大量配额。4.2 本地 Ollama 集成离线可用的关键本地模型路线适合数据敏感场景或者只是不想依赖云端。Ollama 装好后先在终端确认服务在跑ollama list有输出说明 Ollama 正常。OpenClaw 接 Ollama 的方式很简单Provider 选择openai-compatiblebaseUrl 指向 Ollama 的本地地址{ models: { provider: openai-compatible, baseUrl: http://localhost:11434/v1, model: qwen2.5:7b, apiKey: ollama } }Ollama 提供了 OpenAI 兼容接口所以走 openai-compatible 通道是最稳的。API Key 随便填一个占位符就行本地服务不校验。模型选择上个人体验是7B 量级的模型在日常文件操作、命令执行类任务上够用但复杂逻辑推理和多步骤任务会明显吃力有 16GB 以上显存的话直接上 14B 或 32B 量级的模型体验会好很多。注意 Ollama 的模型是运行时可拉取的如果显存不够模型会自动部分加载到内存速度会明显下降。4.3 双路线切换的实践经验我当前的做法是日常高频小任务走本地 Ollama涉及复杂推理和写长文时切换到云端 API。切换只需改 settings.json 里的默认 Provider然后重启 openclaw 进程。OpenClaw 也支持在对话中用指令临时切换模型但我在 Windows 上实测偶尔会触发上下文重置所以还是倾向于改配置重启简单可靠。5. Skill 技能系统安装现成技能与编写自定义技能5.1 技能目录与安装方式Skills 是 OpenClaw 最核心的扩展机制。一个技能就是一个目录目录里必须有 SKILL.md 描述文件以及若干脚本或资源配置。AI 会读取 SKILL.md学着按里面的步骤完成某一类任务。Windows 上技能的默认存放位置是%USERPROFILE%\.openclaw\skills也就是用户主目录下的.openclaw\skills。比如我放了一个pdf-summary技能路径就是%USERPROFILE%\.openclaw\skills\pdf-summary。安装现成技能通常用下面的命令openclaw skill install 仓库地址OpenClaw 官方和社区维护了一批技能仓库按名称安装即可。装完可以用openclaw skill list查看当前已安装的技能列表。这个命令在技能冲突排查时很有用建议常用。5.2 手写一个最简单的技能很多教程只教安装不教手写导致大家对技能机制的理解停留在表面。其实写一个技能并不难我给个最小可用的例子。在技能目录下新建file-organizer文件夹里面建一个 SKILL.md--- name: file-organizer description: 按照文件扩展名将指定目录中的文件分类移动到对应子文件夹。 --- ## 使用场景 当用户要求整理某个目录下的文件时使用本技能。 ## 执行步骤 1. 列出指定目录下所有文件识别扩展名。 2. 对每个扩展名建立对应子文件夹如 .pdf - PDF/。 3. 使用 mv 命令移动文件保留原文件名。 4. 汇总输出移动结果。就这么简单。SKILL.md 的 YAML 头里 name 是技能名description 是 AI 判断何时触发该技能的依据。下面正文就是给 AI 看的操作指南写得越具体AI 的执行就越靠谱。相比把所有逻辑塞进 prompt用 SKILL.md 管理更清晰也方便迭代。可以在 SKILL.md 同目录放一个skill.py或.sh脚本AI 会按指南决定是否调用它。技能目录支持放多文件AI 会自动根据上下文选择合适脚本。5.3 技能管理的最佳实践用了一段时间后我的体会是技能粒度宜小不宜大一个技能只解决一类明确的问题不要贪多。技能定义过大时AI 的判断准确率会下降。description 写清楚触发条件AI 靠 description 决定何时加载技能表述模糊会导致该用的时候没用、不该用的时候乱用。定期清理不用的技能技能太多会让 AI 在检索时产生干扰建议保持 10 个以内的活跃技能。6. Windows Companion配置方法与权限细节6.1 Companion 到底解决什么问题Companion 是 OpenClaw 连接操作系统的桥梁。以 Windows Companion 为例它提供三类能力系统托盘图标后台常驻方便快速查看运行状态和日志本地端口监听把 OpenClaw 的 API 暴露到 localhost便于其他程序调用文件右键菜单集成选中文件直接发送给 OpenClaw 处理。没有 CompanionOpenClaw 也能在终端里用但体验会差不少尤其是想做文件关联和后台常驻时。6.2 配置步骤先确认主程序已安装然后执行openclaw companion install windows安装完成后会生成一个配置文件通常是%USERPROFILE%\.openclaw\companions\windows.json里面主要配置端口号、开机自启、右键菜单选项等。我当前的配置片段{ port: 18789, autoStart: true, contextMenu: true, logLevel: info }配置完重启 Companion 服务。如果右键菜单没生效注销并重新登录一次 Windows 账户即可这个操作不少人都忘了。6.3 权限与安全注意事项Companion 的端口监听是双刃剑。它绑定在 localhost 上默认只有本机能访问这个没问题但要注意如果你配置了端口转发或者系统里有其他代理类软件风险就会增加。建议端口选择不常用的高位端口避免和其他服务冲突不要把 Companion 接口对外暴露定期查看日志确认没有异常调用。安全方面我踩过一个坑在公司电脑上装了 CompanionWindows Defender 防火墙弹窗询问是否允许网络访问我顺手点了“允许”结果把 localhost 监听理解成公网可访问了。后来赶紧去防火墙高级设置里把那条规则删掉只保留本机回环。这个细节不少教程都没提但真的很重要。7. 高频报错排查实录从 WSL 验证失败到端口占用7.1 “无法安全验证 WSL2 环境”的完整排查链路这是 Windows 部署 OpenClaw 时最常见也最劝退的报错。完整提示大意是openclaw 无法安全验证 WSL2 环境请在 PowerShell 中运行wsl --status检查并修复。很多朋友看到这个提示后运行了wsl --status发现一切正常但 OpenClaw 依然报错于是陷入迷茫。我当时的排查链路是这样的按顺序走基本能找到问题第一步确认 WSL 功能是否完整wsl --status正常输出会包含“默认版本: 2”和“默认分发版: Ubuntu”等信息。如果这里就提示没有安装任何发行版直接执行wsl --install -d Ubuntu补装。第二步确认默认版本是 2 而不是 1报错信息虽长很多时候原因却很简单——不是“没有 WSL”而是“WSL 版本不对”。执行wsl --set-default-version 2第三步进入发行版验证 Linux 侧命令可用wsl进入 Ubuntu 后执行echo test确认能正常返回。如果 WSL 子系统的初始化脚本卡住OpenClaw 检查时就会超时误判为环境不可用。第四步检查 OpenClaw 的日志这个是最多人遗漏的。OpenClaw 在启动时会做环境检测但报错信息有限真正的细节在日志里。Windows 上日志位置在%USERPROFILE%\.openclaw\logs\找到最新的日志文件搜索wsl关键字能看到它具体检查了哪些指标、哪一步失败。我那次排查就是因为日志里显示command timeout: wsl --version才发现 WSL 内核版本过老需要更新。第五步更新 WSL 内核老旧的 WSL 内核会导致检查命令执行超时。管理员 PowerShell 执行wsl --update更新后重启终端再运行 openclaw问题就解决了。这套链路下来90% 的 WSL2 验证报错都能定位。剩下 10% 可能是 Windows 版本过旧WSL2 本身的系统级功能缺失需要先更新 Windows。7.2 端口占用与管理员权限问题Companion 默认端口被占用是另一个高频问题。表现为启动 Companion 提示 bind 失败或者 openclaw 命令执行后立刻退出但没有明确报错。排查方式netstat -ano | findstr 18789如果看到已有进程占用要么换个端口要么找到对应进程结束它taskkill /PID 进程号 /F另外OpenClaw 某些命令比如安装 Companion 服务需要管理员权限。Windows 的权限机制比较特殊普通终端启动的进程即使本身是管理员组成员也不会自动获得提权。我的做法是在 Windows Terminal 里默认使用管理员配置启动 PowerShell省去每次右键“以管理员身份运行”的麻烦。报错现象常见原因快速处理启动报“无法安全验证 WSL2 环境”WSL 内核过旧、默认版本为 1、命令超时wsl --updatewsl --set-default-version 2Companion 端口绑定失败端口被占用netstat -ano | findstr 18789定位并结束进程启动即闪退Node 版本过老 / 配置文件 JSON 语法错误查看日志目录的最新日志定位7.3 闪退与日志定位启动闪退一般有两类原因一是 Node.js 版本不兼容二是配置文件解析失败。闪退往往没有对话式报错直接进程退出这时候只能看日志。查日志的顺序是打开%USERPROFILE%\.openclaw\logs\目录找到时间戳最新的文件按修改时间倒序看最后的错误堆栈大多数情况能直接看到是配置文件里哪个字段写错了。有一次我闪退是因为 settings.json 里写了个非法 JSON 字符中文字符串缺了引号。这种问题日志里会明确提示 JSON parse error定位很快。所以我建议每次改配置之前先把原文件备份一份改完用任意 JSON 校验工具验证一遍语法能省掉大半闪退问题。8. 跑通之后的进阶玩法与个人体会8.1 与 Docker Desktop 的配合OpenClaw 的完整沙箱能力还可以配合 Docker Desktop 使用让 AI 在隔离容器里执行更重量级的任务比如跑数据清洗脚本、启动测试数据库。安装 Docker Desktop 后OpenClaw 会自动检测 Docker 是否可用并在任务需要时选择容器环境。我在 Windows 上的经验是普通文件操作和命令行任务走 WSL2 沙箱就够了涉及环境隔离或安装第三方依赖的任务可以引导 AI 走 Docker。判断标准很简单——担心它把系统搞脏的操作一律让它进容器。需要注意Docker Desktop 和 WSL2 共用一套虚拟化基础设施如果 Windows 上虚拟化没开启BIOS 层面的 Hyper-V 被关闭会直接影响 WSL2 的启动连带 OpenClaw 的整体运行。排查时优先确认这个底层。8.2 内网与离线部署思路OpenClaw 跑通后我还做了内网服务器的私有化部署尝试。思路是内网服务器上装 Node.js 和 Ollama把同样的配置模板拷贝过去注册成系统服务让局域网内其他机器通过端口访问。这样整个团队可以共享一个部署实例模型和数据都留在内网不经过外部服务。需要注意的一点是内网部署时 Skills 目录和日志目录要统一规划好避免多用户并发时权限冲突。其实这一块不算复杂就是把单机部署的经验平移过去加上系统服务管理器的开机自启配置。8.3 一点真实体会OpenClaw 在 Windows 上能不能用好关键不在于安装命令而在于你愿不愿意理解它的环境模型。很多人一开始被“无法安全验证 WSL2 环境”吓退以为是自己运气不好其实只是没搞明白它需要的混合环境。我花了整整两天才想通这一点写这篇指南就是希望把这两天缩短成半小时。最后分享一个小技巧Windows 上不要直接用CtrlC中断 OpenClaw 的长任务这个操作偶尔会让沙箱里的子进程残留导致下次启动时环境检查异常。正确做法是在对话里输入/exit优雅退出如果进程已经卡死用任务管理器结束进程后再清掉 WSL 里的残留进程wsl --shutdown这个细节是我踩了两次坑才发现的。先写到这儿如果你在部署时遇到其他新问题欢迎在评论区把日志贴出来一起讨论。