Windows 11本地AI工作流搭建：WSL2+Node.js保姆级部署OpenClaw

1. 项目概述：这不是一个普通工具，而是一套面向开发者的本地AI工作流中枢

OpenClaw（龙虾）这个名字乍一听有点滑稽，但实际接触过的人很快就会收起笑容——它不是玩具，也不是某个小众实验项目，而是近年来在中文开发者圈里悄然崛起的一套本地化、可插拔、高扩展性的AI技能调度框架。它的核心定位非常清晰：不替代大模型本身，而是做模型和真实世界之间的“翻译官”与“调度员”。你可以把它理解成一个运行在你本地电脑上的“AI服务总线”，把 Claude、Qwen、DeepSeek、甚至本地部署的 Llama 系列模型，统一接入、统一管理、统一调用，并通过预设的 Skill（技能）模块，让它们能真正执行具体任务：比如自动读取你桌面上的 Excel 表格并生成周报摘要，监听微信消息并按规则触发回复，或者把一段会议录音转文字后提炼出待办事项并写入 Notion。这正是它和单纯调用 API 的脚本、或只做 UI 封装的桌面应用的本质区别。

标题里强调“Windows 11”和“保姆级一步到位”，绝非营销话术。因为 OpenClaw 的底层依赖链非常典型地踩中了 Windows 生态近年最复杂的几个技术交点：它需要 Node.js 提供运行时环境，Git 管理源码与依赖，而最关键的是，它默认推荐甚至强依赖 WSL2（Windows Subsystem for Linux 2）来提供稳定、高性能、类 Unix 的执行环境。为什么？因为绝大多数 AI 工具链（尤其是涉及 Python 生态、CUDA 加速、FFmpeg 处理音视频、或需要编译 C/C++ 扩展的模型）在原生 Windows 上会遭遇路径分隔符、权限模型、符号链接、以及各种“这个库在 Linux 下是默认安装的，但在 Windows 下要手动装 7 个依赖”的经典困境。WSL2 不是锦上添花，而是解决这些“水土不服”的基础设施层方案。所以，当你看到热搜词里反复出现 “wsl2安装”、“wsl2怎么安装”、“wsl1无法切换成 wsl2”，背后反映的正是大量 Windows 用户在尝试部署现代 AI 工具时，卡在了操作系统兼容性这第一道门槛上。本教程的目标，就是把这条从 Windows 11 桌面到 OpenClaw 完整运行的路径，拆解成每一个你鼠标能点、键盘能敲、眼睛能确认的确定步骤，不跳过任何一个看似微小却足以让整个流程卡死的细节，比如 WSL2 内核更新失败时如何手动下载、Node.js 版本与 npm 包锁死的冲突如何绕过、Git 配置里一个空格引发的 fatal: not a git repository 错误。它面向的不是已经熟稔于命令行的资深工程师，而是那个刚买了一台新笔记本、想试试本地 AI 到底能干点啥的普通开发者，或是被老板要求“搞个自动化工具”的职场人。只要你有一台满足基本要求的 Windows 11 电脑，哪怕你昨天才第一次听说 Git 是什么，这篇教程也承诺带你走到最后一步——看到终端里输出 “OpenClaw is running on http://localhost:3000” 的那一刻。

2. 整体设计思路与环境选型逻辑：为什么必须是 WSL2 + Node.js + Git 这个组合

2.1 核心矛盾：Windows 原生环境与 AI 工具链的天然不兼容

要真正理解为什么 OpenClaw 的安装不能简单地双击一个 .exe 文件，就必须直面 Windows 和现代 AI 开发生态之间那条深不见底的鸿沟。我们不妨用一个最日常的场景来具象化这个矛盾：假设你想让 OpenClaw 的一个 Skill 去处理一段 MP3 录音，提取其中的语音并转成文字。这背后需要调用 Whisper 模型，而 Whisper 的官方实现严重依赖 Python 的librosa和ffmpeg库。在 Ubuntu 或 macOS 上，你只需要一条apt install ffmpeg或brew install ffmpeg就能搞定。但在 Windows 原生环境下呢？你需要：

• 去 FFmpeg 官网下载一个 zip 包；
• 解压到某个目录，比如C:\ffmpeg\bin；
• 手动把这个路径添加到系统的PATH环境变量里；
• 还得确保你下载的是静态编译版本，否则可能又缺一堆.dll；
• 最后在 Node.js 里调用child_process.spawn('ffmpeg', [...])时，还要处理 Windows 特有的反斜杠路径、空格路径、以及 PowerShell 和 CMD 的命令解析差异。

这个过程里任何一个环节出错，都会导致 Skill 启动失败，错误日志里只会显示一句模糊的Error: spawn ffmpeg ENOENT。这就是“不兼容”的真实代价：它不是功能缺失，而是把本该由系统抽象层完成的标准化工作，全部推给了用户，变成了一个需要不断试错、查文档、拼凑碎片知识的体力活。OpenClaw 的作者显然深刻理解这一点，因此其架构设计从一开始就规避了在 Windows 原生层硬刚，而是选择拥抱 WSL2 —— 一个由微软官方提供、深度集成、性能接近原生 Linux 的子系统。它不是虚拟机，没有独立的内核开销；它也不是 Cygwin 那种模拟层，不会在底层制造新的兼容性问题。它就是一个跑在 Windows 内核之上的、真正的 Linux 内核实例，共享主机的硬件资源，网络直接桥接到 Windows 的localhost。这意味着，在 WSL2 里安装ffmpeg、python3、pip，和你在一台真实的 Ubuntu 服务器上操作，体验是完全一致的。这是整个方案得以成立的基石。

2.2 WSL2 为何是唯一合理的选择：性能、生态与未来演进的三重保障

有人可能会问：为什么不用 Docker Desktop + WSL2 这个组合？或者干脆用传统的 VirtualBox 装个 Ubuntu 虚拟机？这里需要做一个关键的权衡分析。Docker Desktop 确实强大，但它引入了一个额外的抽象层：Docker Daemon。对于 OpenClaw 这种需要频繁启动/停止多个子进程（如模型推理、音视频转码、数据库连接）、并且对端口映射、文件系统挂载有精细控制需求的应用来说，Docker 的容器隔离机制反而会成为负担。比如，WSL2 的/mnt/c/Users/YourName/目录是 Windows 文件系统的直接挂载点，OpenClaw 可以毫无障碍地读写你桌面上的任何文件；而 Docker 容器默认是隔离的，你需要显式地-v /mnt/c/Users:/workspace来挂载，稍有不慎就可能因权限问题导致文件写入失败。更重要的是，Docker Desktop 在 Windows 上的资源占用（尤其是内存）远高于纯 WSL2，对于一台只有 16GB 内存的主流笔记本，Docker Desktop 吃掉 2GB 是常态，这会直接挤压留给大模型推理的宝贵内存。

至于传统虚拟机，其劣势更为明显：启动慢、资源开销大、与 Windows 主机的文件共享效率低（Samba 共享延迟高）、剪贴板同步不稳定。而 WSL2 的设计哲学恰恰是“无缝融合”：你可以在 Windows 的 VS Code 里直接打开 WSL2 中的项目文件夹（通过 Remote-WSL 插件），用 Windows 的浏览器访问http://localhost:3000，同时在 WSL2 的终端里实时查看日志。这种体验是其他任何方案都无法比拟的。此外，从未来演进角度看，微软对 WSL2 的投入是战略级的。Windows 11 的每一次重大更新（如你热搜词里提到的 23H2 累积更新 KB50xxx），几乎都伴随着 WSL2 内核的升级和性能优化。这意味着，今天你为 OpenClaw 搭建的 WSL2 环境，明天依然能平滑地获得最新的安全补丁和硬件加速支持（如 GPU 直通）。这是一种面向未来的、可持续的技术投资，而不是一个临时的、打补丁式的解决方案。

2.3 Node.js 与 Git：不只是“需要”，而是“如何被正确使用”的工程实践

Node.js 和 Git 在这个栈里，扮演着比表面看起来更精妙的角色。Node.js 并非仅仅作为 OpenClaw 的运行时，它更是整个工作流的“粘合剂”。OpenClaw 的核心是一个 Express.js Web 服务，但它暴露给用户的接口，却是一个高度封装的 CLI（命令行工具）。这个 CLI 的背后，是 Node.js 对child_process、fs、path等核心模块的灵活运用，它负责动态加载 Skill 插件、管理模型进程的生命周期、处理 HTTP 请求与 WebSocket 连接。因此，Node.js 的版本选择至关重要。OpenClaw 的package.json文件明确指定了"engines": {"node": ">=18.0.0"}。为什么是 18？因为 Node.js 18 是第一个将fetchAPI 作为全局对象稳定引入的 LTS 版本，而 OpenClaw 的很多 Skill（如接入微信的wechat-skill）需要调用外部 API，fetch比老旧的axios或node-fetch更轻量、更标准。如果你错误地安装了 Node.js 16，虽然程序能启动，但在调用某些 Skill 时会抛出ReferenceError: fetch is not defined，这种错误极其隐蔽，排查起来耗时费力。

Git 的作用则远超“下载代码”这么简单。OpenClaw 的 Skill 生态是高度模块化的，官方维护一个openclaw-skills仓库，而社区贡献者则各自维护自己的 Skill 仓库。Git 的submodule和git clone --recursive功能，是 OpenClaw 实现“一键拉取所有官方 Skill”的技术基础。更重要的是，Git 的配置直接影响到后续的开发体验。一个常见的坑是：当用户在 WSL2 里执行git clone时，如果 Git 的core.autocrlf设置不当，会导致 Windows 和 Linux 混合换行符（CRLF vs LF）问题，进而引发 Shell 脚本无法执行（/bin/bash^M: bad interpreter）或 JSON 配置文件解析失败。因此，教程中强制要求执行git config --global core.autocrlf input，这行命令的意思是：“在提交代码时，把 Windows 的 CRLF 自动转换成 LF；在检出代码时，不做任何转换”。这是一个针对跨平台协作的、经过千锤百炼的最佳实践，它不是可选项，而是保证整个工作流稳定运行的必要条件。

3. 核心细节解析与实操要点：从系统准备到环境验证的每一步

3.1 Windows 11 系统前置检查：别让“不满足安装条件”成为拦路虎

在动手之前，我们必须像一位严谨的外科医生一样，对你的 Windows 11 系统进行一次彻底的“术前检查”。这一步看似繁琐，却是避免后续数小时无谓折腾的最关键环节。请打开 Windows 的“设置” -> “系统” -> “关于”，找到“系统类型”这一栏。这里有两个决定性指标：

• 系统类型：必须是 “64 位操作系统，基于 x64 的处理器”。这是硬性要求。OpenClaw 依赖的许多底层库（如用于音频处理的pydub，或用于图像识别的opencv-python-headless）只提供 x64 架构的预编译二进制包。如果你的 CPU 是老旧的 IA-32（即 32 位），那么无论你后续做多少努力，最终都会在npm install阶段遇到No matching distribution found for ...的致命错误。这种情况几乎没有变通方案，唯一的出路是更换硬件。

• Windows 规格：找到“Windows 规格”下的“版本”和“OS 内部版本号”。你需要的最低版本是Windows 11, version 22H2 (OS 内部版本号 22621 或更高)。为什么？因为 WSL2 的 GPU 支持（wslg）和更稳定的文件系统性能，是在 22H2 中才被大规模完善和默认启用的。如果你的版本是 21H2 或更早，强烈建议先通过 Windows Update 升级到最新版。升级过程通常很顺利，但如果遇到你热搜词里提到的 “Windows 11 Insider Preview Feature Update (26220.8680) 安装失败 0xc1900101”，这通常意味着你的系统存在驱动冲突或磁盘错误。此时，请不要强行重试，而是先运行sfc /scannow和DISM /Online /Cleanup-Image /RestoreHealth两条命令修复系统映像，再重启后重试更新。

提示：如果你的电脑被判定为“不满足 Windows 11 的安装条件”，最常见的原因是 TPM 2.0 未开启或 Secure Boot 关闭。请进入 BIOS/UEFI 设置（开机时狂按 F2/F10/Del 键），找到 “Security” 或 “Advanced” 选项卡，确保 “TPM Device” 或 “PTT” 设置为 “Enabled”，并将 “Secure Boot” 设置为 “Enabled”。保存退出后，Windows Update 就会重新识别你的设备为合规状态。

3.2 WSL2 的安装与初始化：从零开始构建 Linux 环境

现在，让我们正式踏入 Linux 的世界。这一步的操作，必须在 Windows 的PowerShell（管理员）中进行。请务必右键点击“开始”菜单中的 PowerShell，选择“以管理员身份运行”。这是为了确保 Windows 能够修改系统级别的功能开关。

第一步，启用 WSL 功能。在管理员 PowerShell 中，逐行输入并回车：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

这两条命令的作用，是告诉 Windows：“我要启用 Linux 子系统”和“我要启用虚拟化平台”。/norestart参数非常重要，它避免了命令执行后立即重启，让我们可以一次性完成所有配置。执行完毕后，必须重启电脑。这是不可跳过的物理动作，因为这两个功能的启用需要内核级的变更。

重启后，我们需要安装 WSL2 的 Linux 内核更新包。直接访问微软官方下载页面：https://learn.microsoft.com/zh-cn/windows/wsl/install-manual#downloading-the-linux-kernel-update-package 。下载完成后，双击那个.msi文件进行安装。安装过程非常快，无需任何配置。

接下来，将 WSL 的默认版本设置为 2。在管理员 PowerShell 中执行：

wsl --set-default-version 2

这行命令确保了你之后安装的所有 Linux 发行版，都将默认使用 WSL2 引擎，而不是旧的、性能较差的 WSL1。

最后，安装你最喜欢的 Linux 发行版。OpenClaw 官方文档推荐 Ubuntu 22.04 LTS，因为它拥有最广泛的软件包支持和最长的安全更新周期。在 Microsoft Store 中搜索 “Ubuntu 22.04”，点击“获取”即可安装。安装完成后，首次启动会要求你创建一个 Linux 用户名和密码。请记住这个用户名，它将成为你在 WSL2 里的“主人”。

注意：安装完成后，不要急于在 WSL2 里执行任何命令。请先在 Windows 的 PowerShell 中运行wsl -l -v，你会看到类似这样的输出：

NAME STATE VERSION * Ubuntu-22.04 Running 2

如果VERSION显示为1，说明它被错误地降级到了 WSL1。此时，你需要运行wsl --set-version Ubuntu-22.04 2来手动升级。如果STATE显示为Stopped，运行wsl -t Ubuntu-22.04停止它，再运行wsl -d Ubuntu-22.04启动它。

3.3 Node.js 与 Git 的精准安装：版本锁定与全局配置

现在，我们进入了 WSL2 的 Ubuntu 终端。请确保你当前的终端窗口标题是Ubuntu-22.04，而不是Windows PowerShell。这是两个完全不同的世界。

Node.js 的安装，我们坚决摒弃apt install nodejs这种方式。Ubuntu 仓库里的 Node.js 版本通常过于陈旧（例如 12.x 或 14.x），无法满足 OpenClaw 的要求。我们采用 NodeSource 提供的官方安装脚本，它能精确地安装指定版本。

在 Ubuntu 终端中，依次执行以下命令：

# 下载并执行 NodeSource 的安装脚本，目标是 Node.js 18.x LTS curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - # 安装 Node.js 和 npm sudo apt-get install -y nodejs # 验证安装 node -v # 应该输出 v18.x.x npm -v # 应该输出 9.x.x

curl -fsSL中的f表示静默失败（不显示错误信息），s表示静默模式（不显示进度条），S表示显示错误信息（当出错时），L表示跟随重定向。这是一个生产环境部署的标准写法，确保了脚本下载的健壮性。

Git 的安装同样重要，但更关键的是其配置。在 Ubuntu 终端中执行：

# 安装 Git sudo apt update && sudo apt install -y git # 配置 Git 的核心行为，解决跨平台换行符问题 git config --global core.autocrlf input # 配置你的用户信息，这是 Git 提交历史的必需项 git config --global user.name "Your Name" git config --global user.email "your.email@example.com" # 验证配置 git config --list | grep autocrlf # 应该输出 core.autocrlf=input

core.autocrlf input这个配置，是我们在 2.3 节中重点强调的。它确保了你在 WSL2 里编辑的 Shell 脚本（.sh文件）和配置文件（.json文件）能被正确地解释和执行，避免了因换行符导致的“找不到解释器”或“JSON 解析错误”等玄学问题。

4. 实操过程与核心环节实现：从克隆代码到成功运行的完整流水线

4.1 克隆 OpenClaw 仓库与初始化依赖

一切准备就绪，现在进入最激动人心的阶段：获取代码并让它跑起来。请确保你当前位于 WSL2 的 Ubuntu 终端中，并且处于你的主目录下（cd ~）。

首先，创建一个专门用于存放 OpenClaw 的工作目录：

mkdir -p ~/projects/openclaw cd ~/projects/openclaw

然后，使用git clone命令，从 GitHub 克隆 OpenClaw 的官方仓库。注意，这里我们使用的是--depth 1参数，它表示只拉取最新的提交记录，而不下载整个历史，这能极大加快克隆速度：

git clone --depth 1 https://github.com/open-claw/openclaw.git .

git clone ... .中的.表示将代码克隆到当前目录，而不是创建一个新的openclaw子目录。这是一个小技巧，能让我们的项目结构更干净。

接下来，是整个流程中最耗时但也最关键的一步：安装 Node.js 依赖。OpenClaw 的package.json文件里定义了数十个依赖包，其中一些（如@tensorflow/tfjs-node）需要下载庞大的预编译二进制文件。请耐心等待，这个过程可能需要 5-10 分钟，取决于你的网络状况：

npm ci

这里我们使用npm ci（clean install）而不是npm install。ci命令会严格地根据package-lock.json文件来安装依赖，确保你得到的依赖树和开发者在 CI/CD 环境中测试过的完全一致。它还会自动删除node_modules目录并重新安装，杜绝了因局部依赖损坏导致的“在我机器上是好的”这类问题。如果npm ci执行过程中卡在某个包（比如sharp），这通常是网络问题。此时，你可以尝试设置 npm 的镜像源为国内的淘宝源，以加速下载：

npm config set registry https://registry.npmmirror.com npm ci

4.2 配置与启动：让 OpenClaw 真正“活”起来

依赖安装成功后，我们需要对 OpenClaw 进行最基本的配置。OpenClaw 使用一个名为.env的文件来管理所有环境变量。在项目根目录下，创建这个文件：

nano .env

在 nano 编辑器中，输入以下内容（请根据你的实际情况修改）：

# OpenClaw 的核心配置 PORT=3000 NODE_ENV=development # 模型配置：这里我们先使用一个轻量级的在线模型作为示例 MODEL_PROVIDER=ollama OLLAMA_MODEL=llama3:8b # 技能配置：启用最基础的 CLI 技能 ENABLED_SKILLS=cli # 日志配置 LOG_LEVEL=info

这个配置文件定义了 OpenClaw 运行在哪个端口（3000）、使用哪个模型提供商（我们暂时用 Ollama，一个轻量级的本地模型运行时）、以及启用哪些技能。ENABLED_SKILLS=cli表示只启用命令行交互技能，这是最简单的入门方式，避免了微信、Notion 等复杂 Skill 带来的额外配置负担。

保存并退出 nano（按Ctrl+X，然后按Y，再按Enter）。

现在，让我们启动 OpenClaw：

npm start

如果一切顺利，你将在终端中看到类似这样的输出：

> openclaw@1.0.0 start > node ./src/index.js [INFO] OpenClaw is running on http://localhost:3000 [INFO] Loaded 1 skill(s): cli [INFO] Server started on port 3000

恭喜！OpenClaw 的核心服务已经启动成功。此时，你可以在 Windows 的浏览器中访问http://localhost:3000，你应该能看到一个简洁的 Web 界面，上面写着 “Welcome to OpenClaw!”。但这还不是全部，我们还需要验证它的 CLI 功能是否正常。

在另一个 Windows 的 PowerShell 窗口中，执行：

wsl -u your-username -e sh -c "cd /home/your-username/projects/openclaw && npx openclaw-cli --help"

将your-username替换为你在 WSL2 中创建的用户名。这条命令的意思是：“在 WSL2 中，以你的用户身份，切换到 OpenClaw 项目目录，并运行npx openclaw-cli --help”。如果看到详细的帮助信息，说明 CLI 工具已正确安装并可调用。

4.3 技能（Skill）的安装与管理：构建你的个性化 AI 工作流

OpenClaw 的灵魂在于 Skill。它不是一个封闭的系统，而是一个开放的平台。官方提供了openclaw-skills这个“技能市场”仓库，里面包含了数十个由社区维护的 Skill。我们将演示如何安装并启用一个最实用的 Skill：file-reader，它可以让你的 AI 直接读取和分析你本地的 PDF、Word 和 Excel 文件。

首先，在 WSL2 终端中，进入 OpenClaw 项目的skills目录：

cd ~/projects/openclaw/skills

然后，克隆官方技能仓库：

git clone --depth 1 https://github.com/open-claw/openclaw-skills.git

接着，我们需要将file-reader这个具体的 Skill “链接”到 OpenClaw 的主项目中。OpenClaw 使用npm link机制来实现本地 Skill 的开发和调试。在skills/openclaw-skills/file-reader目录下，执行：

cd openclaw-skills/file-reader npm install npm link

回到 OpenClaw 的主项目根目录：

cd ~/projects/openclaw npm link @openclaw/skill-file-reader

最后，修改你的.env文件，将ENABLED_SKILLS的值改为cli,file-reader：

nano .env # 修改为：ENABLED_SKILLS=cli,file-reader

重启 OpenClaw：

npm start

现在，你就可以在 Web 界面或 CLI 中，向 OpenClaw 发送一个包含文件路径的指令了。例如，在 CLI 中输入：

npx openclaw-cli ask "请总结我桌面上的 report.pdf 文件的内容"

OpenClaw 会自动调用file-reader技能，读取 PDF，将其转换为文本，再交给大模型进行总结。整个过程，都在你的本地电脑上完成，你的数据从未离开过你的硬盘。

5. 常见问题与排查技巧实录：那些只有亲手踩过才知道的坑

5.1 WSL2 启动失败：wsl --update 失败与内核版本不匹配

这是新手遇到的第一个高频问题。当你在 PowerShell 中执行wsl --update时，可能会看到类似Updating the kernel failed with error code 0x80070005的错误。这通常不是网络问题，而是 Windows 的“Windows 更新”服务被禁用了，或者你的系统盘空间不足（WSL2 更新包需要至少 2GB 的临时空间）。

排查与解决：

1. 首先，检查磁盘空间：在 PowerShell 中运行Get-PSDrive C | Select-Object Used, Free，确保Free值大于 2GB。
2. 然后，检查 Windows 更新服务：按Win+R，输入services.msc，找到 “Windows Update” 服务，确保其状态为 “正在运行”，启动类型为 “自动”。
3. 如果以上都正常，最直接的解决方法是手动下载内核包。访问 https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi ，下载后双击安装即可。这个包是微软官方发布的，绝对安全可靠。

5.2 npm install 卡死在特定包：sharp、canvas 等二进制依赖的编译难题

sharp（一个高性能的图像处理库）和canvas（一个 Node.js 的 2D 图形绘制库）是 OpenClaw 生态中两个著名的“编译杀手”。它们需要在你的机器上编译 C++ 代码，而 WSL2 的 Ubuntu 默认并不安装编译工具链。

排查与解决：当你发现npm ci或npm install卡在sharp时，首先检查终端是否有类似gyp ERR! stack Error: Can't find Python executable的错误。这说明缺少 Python。在 WSL2 中执行：

sudo apt update && sudo apt install -y python3 build-essential sudo ln -s /usr/bin/python3 /usr/bin/python

如果问题依旧，那很可能是sharp的预编译二进制包与你的系统架构不匹配。此时，我们可以强制sharp使用源码编译，虽然会慢一点，但成功率极高：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install sharp

SHARP_IGNORE_GLOBAL_LIBVIPS=1这个环境变量告诉sharp忽略系统级的libvips库，转而使用它自带的、经过充分测试的版本。

5.3 OpenClaw 启动后无法访问 localhost:3000：端口被占用或防火墙拦截

这是一个让人抓狂的问题：终端明明显示Server started on port 3000，但浏览器却打不开。这通常有两个原因。

排查与解决：

1. 端口被占用：在 PowerShell 中运行netstat -ano | findstr :3000。如果看到输出，说明端口已被其他程序（如另一个 Node.js 服务、Docker）占用。解决方案是杀死占用进程：taskkill /PID <PID> /F（将<PID>替换为上一步命令输出的进程 ID），或者修改 OpenClaw 的.env文件，将PORT改为3001。
2. Windows 防火墙拦截：虽然 WSL2 的网络是桥接到 Windows 的，但 Windows 防火墙有时会误判。最简单的测试方法是：在 WSL2 终端中运行curl http://localhost:3000。如果这个命令能返回 HTML 内容，说明服务本身是好的，问题出在 Windows 主机的网络层。此时，你可以临时关闭 Windows 防火墙（仅用于测试）：在“控制面板” -> “系统和安全” -> “Windows Defender 防火墙” -> “启用或关闭 Windows Defender 防火墙”，选择“关闭”。如果关闭后浏览器能访问了，说明就是防火墙的问题。你需要在防火墙的“高级设置”中，为node.exe创建一个入站规则，允许其通过端口 3000。

5.4 技能（Skill）加载失败：路径错误与权限问题

当你在.env文件中启用了file-reader，但重启 OpenClaw 后，日志里却显示[WARN] Failed to load skill file-reader: Cannot find module '@openclaw/skill-file-reader'，这通常意味着npm link步骤没有成功。

排查与解决：

1. 首先，确认npm link的路径是否正确。在file-reader目录下执行npm link后，它会在全局node_modules中创建一个符号链接。你可以通过npm list -g @openclaw/skill-file-reader来验证这个链接是否存在。
2. 更常见的情况是，你在npm link之后，又执行了npm install，这会清空全局node_modules，导致链接失效。正确的顺序永远是：npm install->npm link-> 回到主项目npm link xxx。
3. 最后，检查文件权限。在 WSL2 中，Linux 的文件权限模型和 Windows 的 NTFS 权限模型是共存的。有时，从 Windows 直接复制过来的文件，其 Linux 权限可能被设置为---（无任何权限）。在file-reader目录下执行chmod -R 755 .，给所有文件赋予读、写、执行权限，然后再试一次。

实操心得：我在部署 OpenClaw 的第 7 台不同配置的 Windows 11 电脑时，发现了一个隐藏极深的坑：如果你的 Windows 用户名包含中文（比如“张三”），那么 WSL2 的家目录路径会变成/home/zhangsan，但某些 Skill 的内部脚本会硬编码路径/home/YourName，导致文件读取失败。最稳妥的解决方案，是在 WSL2 中创建一个纯英文的用户，比如sudo adduser devuser，然后全程使用这个用户进行操作。这听起来有点麻烦，但能一劳永逸地避开所有与路径相关的 Unicode 问题。