一、安装背景与问题汇总

1. 核心需求

在 Windows 系统下全局安装 OpenClaw 工具，版本要求为最新版 openclaw@latest。

2. 安装过程中遇到的核心问题

二、完整安装步骤

步骤 1：环境准备（解决编译核心依赖）

1.1 安装 VS2022 C++ 构建工具（必须）

• 下载地址：https://aka.ms/vs/17/release/vs_BuildTools.exe
• 勾选核心组件（缺一不可）：
  • ✅ Desktop development with C++（主工作负载）
  • ✅ MSVC v143 - VS 2022 C++ x64/x86 生成工具
  • ✅ Windows 11 SDK (10.0.26100.7705)
  • ✅ 用于 Windows 的 C++ CMake 工具
• 安装完成后必须重启电脑，确保环境变量生效。

1.2 安装适配版本的 Node.js

• 卸载原有 Node.js（控制面板 → 程序和功能）；
• 下载 Node.js 22.12.0 LTS（满足 OpenClaw 最低要求）：https://nodejs.org/dist/v22.12.0/node-v22.12.0-x64.msi；
• 安装时勾选「Add to PATH」，验证安装：

  node -v  # 输出 v22.12.0
  npm -v   # 输出 10.8.3 左右
  

步骤 2：清理残留与配置 npm

以管理员身份打开 PowerShell，执行以下命令：

# 终止占用进程
taskkill /f /im node.exe 2>$null
taskkill /f /im npm.exe 2>$null

# 强制删除残留目录
Remove-Item "$env:APPDATA\npm\node_modules\openclaw" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\npm-cache" -Recurse -Force -ErrorAction SilentlyContinue

# 配置国内源 + 指定 VS2022 编译工具
npm config set registry https://registry.npmmirror.com
npm config set msvs_version 2022
npm cache clean --force

步骤 3：全局安装 OpenClaw

# 强制安装并跳过权限检查
npm install -g openclaw@latest --force --unsafe-perm=true

步骤 4：修复配置文件警告（可选）

# 删除无效配置文件（OpenClaw 会自动重建默认配置）
Remove-Item "$env:USERPROFILE\.openclaw\openclaw.json" -Force -ErrorAction SilentlyContinue

步骤 5：验证安装结果

# 检查版本，输出 2026.2.26 即为成功
openclaw --version

# 查看帮助文档，确认功能可用
openclaw --help

三、关键避坑点

1. 权限是基础：所有操作必须以「管理员身份」运行终端，否则会出现 EPERM 权限错误；
2. 编译环境不能省：node-llama-cpp 是 C++ 原生模块，必须安装 VS2022 C++ 构建工具，无替代方案；
3. 版本精准匹配：OpenClaw 硬性要求 Node ≥22.12.0，低版本会直接阻断运行；
4. 国内源提升速度：配置 npmmirror 源可避免 npm 下载依赖超时问题。

四、替代方案（无需编译，快速使用）

若不想配置编译环境，可直接下载便携版：

1. 下载地址：https://github.com/openclaw-ai/openclaw/releases（选择 Windows 便携版）；
2. 解压后双击 openclaw.exe 即可运行，无需安装任何依赖。

五、最终验证标准

执行 openclaw --version 能正常返回版本号（如 2026.2.26），无任何报错提示，即为安装成功。