Windows 安装 OpenClaw 踩坑全记录：Node、Git、CMake、VS Build Tools 一次解决

梢疠 · 2026-3-6 22:00:02

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++ 编译，因此需要完整的开发工具链。
二、测试环境

本文测试环境如下：
项目版本操作系统Windows 11Node.jsv24.14.0ShellPowerShell安装方式npm 全局安装安装命令：

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 原生模块编译环境，以避免后续开发过程中反复遇到类似问题。

复制代码

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

柏雅云 · 6 天前

懂技术并乐意极积无私分享的人越来越少。珍惜

迎脾 · 5 天前

前排留名，哈哈哈

院儿饯 · 前天 03:43

谢谢分享，试用一下

账号		自动登录	找回密码
密码			立即注册

Windows 安装 OpenClaw 踩坑全记录：Node、Git、CMake、VS Build Tools 一次解决

相关帖子

回复

签约作者

Windows 安装 OpenClaw 踩坑全记录：Node、Git、CMake、VS Build Tools 一次解决

相关帖子

相关推荐

回复

签约作者