Windows 环境安装 OpenClaw 全过程踩坑记录与解决方案

在 Windows 环境安装 OpenClaw 的过程中，常常会遇到一系列与 Node.js 原生模块编译相关的问题，例如 Git 未安装、CMake 下载失败、Visual Studio C++ 工具链缺失等。这些问题大多与 Node.js 生态中 node-gyp 的编译环境有关。

本文完整记录在 Windows 环境安装 OpenClaw 的问题排查过程，并提供系统化解决方案，帮助开发者快速完成环境搭建。

一、OpenClaw 简介

OpenClaw 是一个用于构建 AI 自动化任务和 Agent 的 CLI 工具，能够帮助开发者快速创建自动化 AI 工作流。

其核心依赖包括：

• node-llama-cpp
• llama.cpp

在安装过程中，如果系统没有可用的预编译二进制文件，则会触发本地 C++ 编译，因此需要完整的开发工具链。

二、测试环境

本文测试环境如下：

安装命令：

npm install -g openclaw


⸻

三、问题一：pnpm 未安装

最初尝试使用 pnpm 安装：

pnpm add -g openclaw

PowerShell 返回错误：

pnpm : The term 'pnpm' is not recognized

原因

系统未安装 pnpm。

解决方案

安装 pnpm：

npm install -g pnpm


⸻

四、问题二：npm ENOENT / Git 未找到

安装过程中出现错误：

npm error syscall spawn git
npm error enoent

原因

npm 在安装依赖时需要调用 Git，但系统未安装 Git。

解决方案

安装 Git：

winget install Git.Git

验证安装：

git --version


⸻

五、问题三：node-llama-cpp 下载 CMake 失败

继续安装时出现错误：

[node-llama-cpp] Failed to download cmake

原因

node-llama-cpp 在编译 llama.cpp 时会尝试自动下载 CMake，但在某些 Windows 网络环境中下载失败。

解决方案

手动安装 CMake：

winget install Kitware.CMake

验证：

cmake --version


⸻

六、问题四：node-gyp 编译失败

安装过程中出现错误：

missing any VC++ toolset
could not find a version of Visual Studio

完整提示：

You need to install the latest version of Visual Studio
including the "Desktop development with C++" workload.

原因

Node 原生模块编译依赖 node-gyp，而 node-gyp 在 Windows 上需要以下组件：
	•	MSVC 编译器
	•	Windows SDK
	•	C++ Toolchain

当前系统仅安装了 Visual Studio 的核心组件，没有安装 C++ 编译环境。

⸻

七、安装 Visual Studio C++ 编译工具链

安装 Visual Studio Build Tools：

winget install Microsoft.VisualStudio.2022.BuildTools

安装完成后打开：

Visual Studio Installer

选择：

Modify

勾选以下工作负载：

Desktop development with C++

并确保包含以下组件：
	•	MSVC v143 - VS 2022 C++ build tools
	•	Windows 10 / Windows 11 SDK
	•	C++ CMake tools for Windows

完成安装。

⸻

八、重新安装 OpenClaw

清理旧安装：

npm uninstall -g openclaw
npm cache clean --force

重新安装：

npm install -g openclaw

安装完成后验证：

openclaw --help

如果能够正常输出帮助信息，则说明安装成功。

⸻

九、Windows 环境推荐开发依赖

为了避免后续 Node 原生模块编译问题，建议一次性安装以下工具：

工具	作用
Node.js	JavaScript 运行环境
Git	依赖仓库拉取
CMake	C++ 构建工具
Visual Studio Build Tools	C++ 编译工具链
Python	node-gyp 运行依赖

推荐版本：

Node.js 22 LTS
Python 3.11
Git
CMake
Visual Studio Build Tools (C++)


⸻

十、Windows 与 Linux 环境对比

在 Windows 上安装 AI CLI 工具时，常见问题包括：
	•	node-gyp 编译问题
	•	C++ 工具链缺失
	•	GPU 编译依赖
	•	Vulkan / CUDA 依赖

因此很多 AI 开源项目更推荐在 Linux 环境运行。

例如使用 WSL Ubuntu：

sudo apt update
sudo apt install nodejs npm git cmake build-essential

npm install -g openclaw

在 Linux 环境中，安装成功率通常更高。

⸻

十一、总结

在 Windows 环境安装 OpenClaw 时，常见问题主要集中在 Node 原生模块编译环境缺失。

典型问题包括：
	1.	Git 未安装
	2.	CMake 下载失败
	3.	Visual Studio C++ Toolchain 缺失
	4.	node-gyp 编译失败

完整解决路径如下：

Node.js
→ Git
→ CMake
→ Visual Studio Build Tools (C++)
→ npm install openclaw

当开发环境完整后，OpenClaw 即可正常安装并运行。

⸻

如果需要长期进行 AI Agent 或 LLM 工具开发，建议提前配置完整的 Node.js 原生模块编译环境，以避免后续开发过程中反复遇到类似问题。