当前位置：首页 > news >正文

Windows下OpenClaw安装实战：Node.js 24与npm环境配置全指南

news 2026/7/17 10:33:38

1. 这不是“又一个AI工具安装教程”，而是一份专为Windows用户打磨的OpenClaw实战手记

我从去年底开始接触OpenClaw，最初也是从网上零散的视频和碎片化文档里摸索。真正让我下定决心系统梳理这套流程的，是连续三次在客户现场部署失败——不是因为OpenClaw本身有问题，而是卡在了Windows环境下那些看似微小、实则致命的环节：PowerShell执行策略报错、npm全局路径未注入PATH、Node版本与OpenClaw官方要求错位、甚至只是中文系统区域设置导致的时区解析异常。这些坑，90%的教程都一笔带过，但对刚打开命令行的新手来说，就是一道跨不过去的墙。

OpenClaw本质上是一个面向开发者与技术型用户的智能代理运行时平台，它不直接提供大模型能力，而是像一个“智能插件底盘”，让你能快速接入Claude、Ollama、本地Llama.cpp服务，甚至自定义HTTP API作为技能节点。它的核心价值在于可组合性与可调试性——你可以把一个PDF解析、一个Excel数据清洗、一个邮件自动归档，全部拆解成独立技能（Skill），再用YAML编排成工作流。这决定了它天然适合需要稳定、可控、可审计AI能力的中小团队，而不是追求“一键生成PPT”的泛C端用户。

所以这篇内容，不讲概念，不堆术语，只聚焦一件事：如何在一台干净的Windows电脑上，从零开始，稳稳当当地跑起OpenClaw，并让它真正开始干活。我会把Node.js安装、npm配置、PowerShell策略绕过、环境变量修复、OpenClaw首次启动验证、基础技能调用，全部拆成你能在自己电脑上逐条敲、逐条验证的步骤。所有命令都标注了预期输出、常见错误提示和对应解法，连CMD和PowerShell窗口该用哪个、管理员权限要不要开、中文路径能不能用，都给你标清楚。这不是教科书，这是我在客户机房、在同事笔记本、在我自己那台老ThinkPad上，反复重装、反复验证后留下的操作日志。

关键词已经非常明确：OpenClaw、Node.js、npm、Windows。它们不是孤立的名词，而是一条环环相扣的链路——Node是引擎，npm是燃料输送系统，Windows是承载这台引擎的底盘，而OpenClaw，就是你最终要驾驶的那辆车。任何一个环节松动，车都开不起来。接下来的内容，就是帮你拧紧每一颗螺丝。

2. 安装思路与方案选型：为什么放弃“一键安装包”，坚持手动配置Node生态

2.1 OpenClaw对运行时的硬性要求与Windows的现实约束

OpenClaw官方文档白纸黑字写着：“Requires Node 22.19 or newer. Node 24 is the default and recommended runtime”。这句话背后藏着两个关键信息点，也是我们整个安装策略的起点。

第一，“22.19或更新”意味着它不兼容Node 20及更早的LTS版本。很多教程还在推荐下载Node官网的“LTS”安装包，殊不知那个版本号是20.x，装上去第一步node -v就报错。我见过太多人卡在这一步，反复卸载重装，最后发现是版本号看错了。Node的版本命名规则本身就容易混淆：官网首页的“Recommended For Most Users”是LTS版（当前是20.13.1），而“Latest Features”才是Current版（当前是22.14.0）。OpenClaw要的是22.19+，这就意味着我们必须跳过LTS，直奔Current，或者更稳妥地，选择Node 24.x——它不仅是官方推荐，更是CI/CD流水线默认使用的版本，意味着它的稳定性、兼容性和社区支持度，是经过大规模验证的。

第二，“Windows”这个平台带来了独有的约束。Linux和macOS用户习惯用curl、brew、apt，命令行世界相对纯净。而Windows用户面对的是三套并行的命令环境：CMD、PowerShell、Git Bash；两套权限模型：标准用户与管理员；以及一套顽固的执行策略（Execution Policy）。其中最典型的，就是你在PowerShell里输入npm install -g openclaw，立刻弹出的红色报错：

npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。 所在位置 行:1 字符:1 + npm install -g openclaw + ~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : SecurityError: (:) []，PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess

这个报错，99%的初学者会把它当成“npm坏了”，然后去搜“npm安装失败”，结果越搜越偏。其实它根本不是npm的问题，而是PowerShell出于安全考虑，默认禁止执行任何本地脚本（包括npm.ps1这个由Node.js安装器自带的封装脚本）。解决方案不是重装npm，而是调整PowerShell的执行策略。但这里又有个陷阱：很多人会直接搜到Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，这确实能解决问题，但它只对当前用户生效。如果你后续用管理员身份打开PowerShell，或者在某些IDE（如VS Code）的集成终端里启动，策略又会失效。所以我们的方案必须覆盖所有常见场景。

2.2 为什么放弃winget/choco，坚持官网安装+手动PATH配置

网络热词里频繁出现winget install OpenJS.NodeJS.LTS和choco install nodejs-lts，看起来很“现代化”。但我在实际部署中发现，这两个方案在Windows上存在三个隐性风险：

其一，版本滞后性。winget源和Chocolatey源的更新速度，永远慢于Node.js官网。当你在winget里执行winget search nodejs，返回的最新版本可能还是22.12.0，而OpenClaw要求的是22.19+。你得等源同步，或者手动指定版本号，这反而增加了复杂度。

其二，安装路径不可控。winget默认会把Node安装到C:\Program Files\OpenJS\nodejs\，而Chocolatey则可能装到C:\ProgramData\chocolatey\lib\nodejs\tools\。这两个路径都包含空格和特殊字符（Program Files、ProgramData），在某些老旧的批处理脚本或环境变量解析中，会引发意料之外的路径截断错误。我自己就遇到过一次，npm prefix -g返回的路径里，Program Files被截成了Program，导致后续所有全局命令都找不到。

其三，PATH注入的不确定性。winget和choco在安装完成后，理论上会自动把node.exe和npm.cmd的路径加入系统PATH。但这个过程并非100%可靠。尤其是在多用户环境、或者之前手动安装过Node的机器上，PATH变量可能被污染、重复或顺序错乱。openclaw: command not found这个高频报错，80%的原因就是PATH里压根没有npm的bin目录。

因此，我的方案是：从Node.js官网下载.msi安装包，全程使用图形化向导安装，但在最后一步，主动取消勾选“Automatically install the necessary tools”（即npm）选项，改为手动验证并配置npm。这样做的好处是：安装路径清晰可控（默认C:\Program Files\nodejs\），版本精准无误（直接选24.x），且我们能完全掌控PATH的写入时机和内容。这听起来比“一键安装”麻烦，但换来的是100%的可预测性和可复现性——对于需要给客户部署、或者在公司内网批量安装的场景，这点确定性，远比省下那30秒点击时间重要得多。

2.3 npm镜像源切换：不是“锦上添花”，而是国内网络环境下的生存必需

另一个被严重低估的环节，是npm的镜像源。npm install -g openclaw这个命令，背后是npm客户端向https://registry.npmjs.org发起HTTPS请求，下载数十个依赖包。在国内公共网络环境下，这个域名的DNS解析和TCP连接建立，经常遭遇超时或间歇性中断。你看到的npm WARN deprecated、npm ERR! network timeout，绝大多数时候，跟你的网络带宽无关，而是npm官方源的访问质量不稳定。

淘宝NPM镜像（https://registry.npmmirror.com）是目前最成熟、最稳定的替代方案。它不是简单的“缓存”，而是通过全量同步+CDN分发，将全球npm包的下载速度提升到毫秒级。切换镜像源的操作，只需要一条命令：

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

但这里有个关键细节：这条命令修改的是当前用户的.npmrc配置文件。如果你之前用管理员权限安装过Node，或者在不同用户账户下操作过，.npmrc文件的位置可能有多个（C:\Users\<用户名>\.npmrc和C:\Program Files\nodejs\node_modules\npm\npmrc）。我们必须确保修改的是当前登录用户的配置，否则命令会静默失败。因此，在执行切换命令前，我一定会先确认当前用户上下文，并用npm config list来验证registry字段是否已更新。

此外，热词里还提到了npm warn using --force recommended protections disabled.。这通常发生在你试图用--force参数强制安装某个有冲突的包时。它不是一个错误，而是一个安全警告，提醒你正在绕过npm的依赖树校验。在OpenClaw安装过程中，我们应尽量避免使用--force，因为OpenClaw的依赖关系是经过严格测试的，强行覆盖可能导致运行时行为异常。如果遇到peer dependency警告，正确的做法是检查Node版本是否匹配，而不是加--force。

3. 核心细节解析与实操要点：从Node安装到OpenClaw首次启动的每一步

3.1 Node.js 24.x安装：图形化向导里的关键三步

请务必打开Node.js官网（https://nodejs.org），找到“Current”标签页，下载node-v24.x.x-x64.msi安装包（截至2024年中，最新稳定版是24.7.0）。不要下载LTS版，也不要下载zip压缩包。.msi是Windows标准安装程序，它能正确处理注册表项、服务依赖和系统路径。

双击运行安装包后，你会看到标准的向导界面。前三步（许可协议、安装路径、组件选择）是重点：

许可协议页：勾选“I accept the terms in the License Agreement”，这是必选项，不勾选无法继续。
安装路径页：保持默认的C:\Program Files\nodejs\。虽然路径含空格，但这是微软官方推荐的软件安装位置，Node.js自身对此做了充分适配。不要改成C:\nodejs之类的自定义路径，除非你有非常特殊的权限管理需求。改路径并不会解决后续问题，反而可能引入新的路径解析bug。
组件选择页：这是最关键的一步。默认勾选了“Automatically install the necessary tools”，这个选项会尝试为你安装Python、Visual Studio Build Tools等编译环境。请务必取消勾选此项。OpenClaw是一个纯JavaScript项目，它所有的依赖都是预编译好的二进制包（.node文件），完全不需要本地编译。勾选它不仅会拖慢安装速度，还可能因为你的系统缺少VC++运行库而报错，把简单问题复杂化。

完成安装后，不要立刻关闭向导。在最后的“Ready to Install”页面，点击“Install”按钮前，请勾选左下角的“Automatically launch the Node.js command prompt after installation”（自动在安装后启动Node.js命令提示符）。这个小勾选，能帮你立刻验证安装是否成功，省去手动找CMD或PowerShell的步骤。

安装完成后，向导会自动打开一个黑色的CMD窗口。此时，输入以下三条命令，逐一验证：

node -v npm -v where node

预期输出应该是：

node -v返回v24.x.x（例如v24.7.0）
npm -v返回10.x.x（例如10.8.2，npm 10是Node 24的标配）
where node返回C:\Program Files\nodejs\node.exe

如果这三行都正确，说明Node和npm的基础安装已经成功。如果where node报错“INFO: Could not find files for the given pattern”，那说明安装程序没有正确将C:\Program Files\nodejs\写入系统PATH。这时你需要手动添加：右键“此电脑”→“属性”→“高级系统设置”→“环境变量”，在“系统变量”中找到Path，点击“编辑”，新建一行，粘贴C:\Program Files\nodejs\，然后一路确定。之后，必须关闭并重新打开所有CMD/PowerShell窗口，让新PATH生效。

提示：where命令是Windows原生命令，比which更可靠。它能准确告诉你系统在PATH中找到的第一个node.exe的位置。这是排查“命令找不到”类问题的黄金指令。

3.2 PowerShell执行策略绕过：安全与可用的平衡点

现在，打开一个新的PowerShell窗口（不是CMD，是PowerShell，图标是蓝色的）。输入npm -v，如果看到熟悉的红色报错，恭喜你，遇到了Windows最经典的“安全策略墙”。

这个问题的根源，在于PowerShell的ExecutionPolicy（执行策略）。它不是病毒防护软件，而是PowerShell内置的一套脚本执行控制机制，目的是防止恶意脚本自动运行。npm.ps1是一个PowerShell脚本，它被设计用来包装npm.cmd，提供更好的错误提示和参数解析。但默认策略Restricted，禁止了所有本地脚本的执行。

解决方案不是禁用安全策略，而是将其调整为一个既安全又可用的级别。我们选择RemoteSigned，这是微软官方文档推荐的、适用于开发者的策略。它允许你运行本地编写的脚本，但要求从互联网下载的脚本必须带有有效的数字签名。

执行以下命令（必须以管理员身份运行PowerShell）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

解释一下参数：

RemoteSigned：策略名称，表示“本地脚本可运行，远程脚本需签名”。
-Scope CurrentUser：作用域为“当前用户”。这是关键！它只修改你个人账户的策略，不影响其他用户，也不需要管理员密码（在非管理员账户下也能执行）。
-Force：强制执行，跳过确认提示。

执行完后，关闭这个PowerShell窗口，再打开一个新的（普通用户权限即可）。再次输入npm -v，这次应该能正常返回版本号了。

注意：如果你在VS Code里使用集成终端，它默认启动的是PowerShell。有时即使你在外部PowerShell里设置了策略，VS Code的终端可能还是旧的。这时，可以在VS Code的终端里，先执行Get-ExecutionPolicy -List，查看CurrentUser这一行的值是否为RemoteSigned。如果不是，就在VS Code的终端里，用上面的命令再执行一遍。这是VS Code的一个已知行为，不是bug。

3.3 npm全局路径与PATH环境变量的终极修复

openclaw: command not found，这是OpenClaw安装过程中，仅次于PowerShell报错的第二大拦路虎。它的本质，是npm的全局安装目录（global bin directory）没有被添加到系统的PATH环境变量中。

npm在全局安装一个包（如npm install -g openclaw）时，不会把openclaw.cmd放到C:\Program Files\nodejs\下面，而是放到一个独立的、用户专属的目录里。这个目录的位置，由npm prefix -g命令决定。

在PowerShell中执行：

npm prefix -g

在一台干净的Windows机器上，它通常会返回类似这样的路径：

C:\Users\<你的用户名>\AppData\Roaming\npm

这个路径，就是npm存放所有全局可执行文件（.cmd）的地方。而openclaw命令，就是一个名为openclaw.cmd的批处理文件，就躺在这个目录里。

现在，我们需要把这个路径，手动加到你的PATH环境变量中。步骤如下：

右键“此电脑”→“属性”→“高级系统设置”→“环境变量”。
在“用户变量”区域，找到名为Path的变量，选中它，点击“编辑”。
点击“新建”，然后精确粘贴上一步npm prefix -g命令返回的完整路径（例如C:\Users\zhangsan\AppData\Roaming\npm）。
点击“确定”保存所有更改。

做完这一步，至关重要：关闭你正在使用的所有命令行窗口（CMD、PowerShell、VS Code终端），然后重新打开一个新的PowerShell窗口。在新窗口里，执行：

$env:Path -split ';' | Select-String "AppData"

这条命令会搜索当前PATH变量中，是否包含了AppData字符串。如果返回了你刚才粘贴的路径，说明添加成功。最后，再执行一次npm -v，确认一切正常。

实操心得：我曾经在一个客户的Windows Server上，发现npm prefix -g返回的路径是C:\Users\Administrator\AppData\Roaming\npm，但我在“系统变量”的Path里添加了它，却依然openclaw: command not found。后来才发现，那位管理员是用普通用户登录的，而npm prefix -g在不同用户下返回的路径是不同的。所以，永远用当前登录用户的npm prefix -g结果，去修改当前用户的Path变量。这是Windows多用户环境下的铁律。

3.4 OpenClaw安装与首次启动：从命令到可交互界面

万事俱备，现在可以安装OpenClaw了。在全新的PowerShell窗口中，执行：

npm install -g openclaw

这个命令会从npm镜像源下载OpenClaw及其所有依赖。根据你的网络状况，耗时大约1-3分钟。期间你会看到大量fetching、extracting、linking的日志滚动。只要没有出现红色的ERR!，就可以耐心等待。

安装完成后，执行：

openclaw --version

如果返回类似openclaw/1.2.3 win32-x64 node-v24.7.0的字符串，恭喜，OpenClaw的CLI（命令行界面）已经成功安装并可调用。

但这只是第一步。OpenClaw的核心，是一个Web UI（用户界面），你需要启动它才能真正使用。执行：

openclaw start

几秒钟后，你应该会看到类似这样的输出：

[INFO] Starting OpenClaw server... [INFO] Server listening on http://localhost:3000 [INFO] Opening browser...

然后，你的默认浏览器会自动打开http://localhost:3000这个地址。如果浏览器没有自动打开，或者打不开，别慌，这是非常常见的现象。原因通常是：

浏览器被设置为“始终在后台运行”，新标签页没有获得焦点。
公司防火墙或安全软件拦截了本地回环地址（localhost）的访问。

此时，手动在浏览器地址栏输入http://127.0.0.1:3000，效果完全一样。localhost和127.0.0.1是等价的，但有些软件对localhost的解析更敏感。

进入Web UI后，你会看到一个简洁的仪表盘。左侧是导航栏，包含“Dashboard”、“Agents”、“Skills”、“Models”等。第一次启动时，“Skills”列表是空的，因为还没有任何技能被加载。这就是OpenClaw的设计哲学：它不预装任何功能，所有能力都来自你主动添加的“技能”。

注意：openclaw start命令启动的服务，默认只监听localhost，这意味着它只能在本机访问，无法被局域网内的其他电脑访问。如果你想让同事也能通过IP地址访问你的OpenClaw（例如http://192.168.1.100:3000），你需要在启动时加上--host 0.0.0.0参数：
openclaw start --host 0.0.0.0
但请注意，这样做会暴露你的OpenClaw服务到整个局域网，务必确保你的电脑有基本的防火墙保护，或者只在可信的内网环境中使用。

4. 实操过程与核心环节实现：部署一个真实可用的“天气查询”技能

4.1 技能（Skill）的概念与OpenClaw的技能架构

在OpenClaw里，“技能”不是指一个AI模型，而是一个可独立部署、可单独调用、可组合编排的功能单元。它可以是一个调用第三方API的HTTP请求，可以是一个读取本地文件的脚本，也可以是一个运行Python代码的沙盒。OpenClaw本身不关心技能内部怎么实现，它只关心技能对外暴露的“接口”——也就是一个标准化的YAML描述文件。

一个技能文件（.skill.yml）通常包含四个核心部分：

name: 技能的唯一标识名，也是你在CLI中调用它的名字。
description: 技能的简短描述，用于UI展示。
input: 定义技能接收的输入参数，包括参数名、类型（string, number, boolean）、是否必填、默认值等。
output: 定义技能返回的输出结构。
action: 技能的执行逻辑，可以是http（发起HTTP请求）、script（执行本地脚本）、command（执行系统命令）等。

理解这一点至关重要。很多新手以为安装完OpenClaw就能直接“对话”，但实际上，OpenClaw是一个“底盘”，你需要给它装上“轮子”（技能），它才能跑起来。而“天气查询”这个例子，完美诠释了如何从零开始，构建一个最基础、但也最实用的技能。

4.2 创建第一个技能：基于OpenWeatherMap API的天气查询

我们选择OpenWeatherMap（https://openweathermap.org/api）作为数据源，因为它免费、稳定、文档清晰，且有全球覆盖的气象数据。

第一步：注册一个免费API Key。访问https://home.openweathermap.org/users/sign_up，用邮箱注册一个账号。注册完成后，进入API keys页面，你会看到一个Default key，形如a1b2c3d4e5f678901234567890abcdef。复制这个Key，它将是我们调用API的凭证。

第二步：创建技能文件夹和YAML文件。在你的电脑上，创建一个新文件夹，例如C:\openclaw-skills\weather。在这个文件夹里，新建一个文本文件，命名为weather.skill.yml。

第三步：编写YAML文件内容。用记事本或VS Code打开weather.skill.yml，输入以下内容：

name: weather description: Get current weather information for a city. input: city: type: string description: The name of the city (e.g., "Beijing", "New York"). required: true units: type: string description: Temperature units. Use "metric" for Celsius, "imperial" for Fahrenheit. default: "metric" output: temperature: type: number description: Current temperature in the specified units. description: type: string description: Weather condition description (e.g., "clear sky", "light rain"). humidity: type: number description: Current humidity percentage. action: http: url: "https://api.openweathermap.org/data/2.5/weather" method: GET query: q: "{{ input.city }}" appid: "a1b2c3d4e5f678901234567890abcdef" # 替换为你自己的Key units: "{{ input.units }}" response: json: temperature: "main.temp" description: "weather.0.description" humidity: "main.humidity"

这个YAML文件定义了一个名为weather的技能。它接收两个输入：city（城市名）和units（单位），并返回三个输出：温度、天气描述和湿度。action.http部分告诉OpenClaw，当这个技能被调用时，需要向OpenWeatherMap的API发起一个GET请求，并将响应中的特定JSON字段，映射到我们定义的输出字段上。

提示：YAML格式对缩进极其敏感。input、output、action必须顶格写，它们下面的子项（如city、temperature）必须用两个空格缩进。千万不要用Tab键，一定要用空格。VS Code的YAML插件会自动帮你检查语法，强烈建议安装。

4.3 在OpenClaw中加载并测试技能

技能文件写好后，我们需要告诉OpenClaw去哪里找它。OpenClaw有一个约定：所有技能文件，必须放在一个统一的“技能仓库”（Skill Hub）目录下。默认情况下，这个目录是C:\Users\<你的用户名>\.openclaw\skills。

但手动把文件拷贝过去太麻烦。OpenClaw提供了一个更优雅的方式：符号链接（Symbolic Link）。

在PowerShell中，执行以下命令（请将路径替换为你实际创建的路径）：

# 首先，确保OpenClaw服务已停止 openclaw stop # 然后，创建符号链接 cmd /c "mklink /D C:\Users\zhangsan\.openclaw\skills C:\openclaw-skills"

mklink /D是Windows的命令，用于创建目录符号链接。它相当于在.openclaw\skills这个位置，放了一个指向你真实技能文件夹的“快捷方式”。这样，无论你把技能文件放在哪里，OpenClaw都能通过这个链接找到它们。

执行完后，重新启动OpenClaw：

openclaw start

稍等几秒，刷新你的浏览器http://localhost:3000。点击左侧导航栏的“Skills”，你应该能看到一个名为weather的技能，状态显示为“Active”。

现在，点击weather技能右侧的“Test”按钮。在弹出的测试面板里，输入：

city:Shanghai
units:metric

点击“Run Test”。几秒钟后，你应该会看到一个JSON格式的响应，里面包含了上海的实时温度、天气描述和湿度。如果一切顺利，说明你的第一个技能已经成功部署并可以工作了。

实操心得：我第一次做这个测试时，返回了一个404错误。排查了很久，发现是YAML文件里的appid字段，我复制Key的时候，末尾多了一个空格。YAML解析器会把它当作字符串的一部分，导致API请求失败。所以，复制API Key时，一定要仔细检查前后有没有多余的空格或换行符。这是一个非常隐蔽、但极其常见的错误。

4.4 将技能集成到Agent工作流：让AI“主动”调用它

技能本身是被动的，只有被调用时才执行。而OpenClaw的“Agent”（智能体），则是主动的决策者。我们可以创建一个Agent，让它在用户提问时，自动判断是否需要调用weather技能。

在OpenClaw Web UI中，点击“Agents” → “Create New Agent”。填写：

Name:Weather Assistant
Description:An agent that can answer questions about current weather.

在“Prompt”（提示词）编辑框里，输入以下内容：

You are a helpful weather assistant. Your job is to answer user questions about the current weather in any city. If the user asks for the weather in a specific city, you must use the 'weather' skill to get the data. Do not make up weather information. The 'weather' skill requires two inputs: - 'city': the name of the city (e.g., "Beijing", "Tokyo") - 'units': either "metric" (for Celsius) or "imperial" (for Fahrenheit). Default to "metric". After getting the weather data, summarize it in a friendly, concise way for the user.

保存后，点击“Chat”标签页，开始与这个Agent对话。试着输入：“今天北京的天气怎么样？”

如果一切配置正确，Agent会先调用weather技能，获取北京的天气数据，然后将结果整理成自然语言回复你。这个过程，就是OpenClaw最核心的价值体现：将一个简单的HTTP API，无缝地、可解释地、可审计地，集成到了AI的推理链条中。

5. 常见问题与排查技巧实录：一份来自真实战场的故障速查手册

5.1 “npm : 无法将‘npm’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”

这个报错，和前面提到的PowerShell执行策略报错，是两个完全不同的问题。前者是npm.ps1脚本被禁止执行，后者是系统根本找不到npm这个命令。

排查思路：

首先，确认Node.js是否真的安装成功。在CMD中执行where node，看是否能返回路径。
如果where node成功，但where npm失败，说明npm没有被正确安装或PATH没有包含npm的bin目录。
执行npm prefix -g，得到全局路径（如C:\Users\zhangsan\AppData\Roaming\npm）。
检查这个路径下是否存在npm.cmd文件。如果没有，说明npm安装损坏，需要重装Node.js。
如果npm.cmd存在，但where npm还是找不到，那一定是PATH里没有这个路径。回到“环境变量”设置，确认C:\Users\zhangsan\AppData\Roaming\npm是否已添加。

终极解决方案：如果以上步骤都无效，最彻底的办法是：卸载Node.js，然后在安装向导的“Custom Setup”（自定义设置）页面，勾选“Add to PATH”和“Add to Windows Registry”，再重新安装。这会强制安装程序将C:\Program Files\nodejs\和C:\Users\zhangsan\AppData\Roaming\npm都写入PATH。

5.2 “Error installing 24.16.0: node.js v24.16.0 is not yet released or is not available”

这个报错，通常出现在你试图用nvm-windows（Node Version Manager）安装一个尚不存在的Node版本时。nvm-windows的版本列表，是通过抓取Node.js官网的发布页面生成的。如果官网还没发布24.16.0，而nvm的缓存里已经有了这个版本号，就会出现这个错误。

解决方案：

更新nvm-windows的版本列表：在PowerShell中执行nvm list available，它会自动从官网拉取最新的可用版本列表。
然后，再执行nvm install 24.16.0。
如果问题依旧，说明24.16.0确实还未发布。此时，你应该安装当前最新的稳定版，比如nvm install 24.7.0。

注意：nvm-windows是一个非常有用的工具，但它在Windows上的稳定性，不如macOS/Linux上的nvm。对于生产环境部署，我更推荐直接使用官网安装包，因为它的行为是100%可预测的。nvm更适合开发者在本地进行多版本快速切换。

5.3 OpenClaw Web UI打不开，或显示空白页

这是一个典型的前端资源加载失败问题。OpenClaw的Web UI是一个单页应用（SPA），它依赖localhost:3000这个地址来加载index.html和一系列JavaScript文件。

排查步骤：

首先，在浏览器地址栏，直接访问http://localhost:3000/index.html。如果这个页面能打开，说明服务是正常的，问题出在前端路由上。
打开浏览器的开发者工具（F12），切换到“Network”（网络）标签页，然后刷新页面。观察所有请求的状态码。如果看到大量404（未找到）错误，特别是对/static/js/main.*.js这类文件的请求，说明OpenClaw的静态资源打包有问题。
最常见的原因是：你安装OpenClaw时，网络不稳定，导致某些前端依赖包下载不完整。解决方案是：在PowerShell中，执行npm uninstall -g openclaw && npm install -g openclaw，进行一次干净的重装。
如果重装后问题依旧，可以尝试清除OpenClaw的缓存：执行openclaw cache clear，然后重启服务。

5.4 技能调用返回“Timeout”或“Connection refused”

当你在测试一个HTTP类型的技能时，如果返回超时，不要立刻怀疑是OpenClaw的问题。绝大多数情况下，问题出在API本身或你的网络环境。

排查清单：

API Key是否有效？直接在浏览器里访问https://api.openweathermap.org/data/2.5/weather?q=Shanghai&appid=YOUR_KEY&units=metric，把YOUR_KEY替换成你的Key。如果浏览器返回了JSON数据，说明Key有效；如果返回Invalid API key，说明Key错了或过期了。
API的域名是否被屏蔽？在PowerShell中执行ping api.openweathermap.org。如果ping不通，或者延迟极高（>1000ms），说明你的网络到该API服务器的链路有问题。此时，可以尝试更换DNS服务器（如改为8.8.8.8或114.114.114.114），或者使用手机热点测试。
技能YAML中的URL是否拼写错误？仔细检查action.http.url字段，确保没有多打或少打一个斜杠/，或者把https写成了http。

实操心得：有一次，一个客户的技能总是超时，我们花了两个小时排查。最后发现，他们的公司网络策略，禁止了所有对*.openweathermap.org域名的出站连接，只允许访问*.company.com。这种企业级网络限制，是任何公开教程都不会提及的。所以，当你遇到无法解释的网络问题时，第一反应应该是：问问IT部门，这个域名是否在白名单里？