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

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 全局安装安装命令：

1. npm install -g openclaw
4. ⸻
6. 三、问题一：pnpm 未安装
8. 最初尝试使用 pnpm 安装：
10. pnpm add -g openclaw
12. PowerShell 返回错误：
14. pnpm : The term 'pnpm' is not recognized
16. 原因
18. 系统未安装 pnpm。
20. 解决方案
22. 安装 pnpm：
24. npm install -g pnpm
27. ⸻
29. 四、问题二：npm ENOENT / Git 未找到
31. 安装过程中出现错误：
33. npm error syscall spawn git
34. npm error enoent
36. 原因
38. npm 在安装依赖时需要调用 Git，但系统未安装 Git。
40. 解决方案
42. 安装 Git：
44. winget install Git.Git
46. 验证安装：
48. git --version
51. ⸻
53. 五、问题三：node-llama-cpp 下载 CMake 失败
55. 继续安装时出现错误：
57. [node-llama-cpp] Failed to download cmake
59. 原因
61. node-llama-cpp 在编译 llama.cpp 时会尝试自动下载 CMake，但在某些 Windows 网络环境中下载失败。
63. 解决方案
65. 手动安装 CMake：
67. winget install Kitware.CMake
69. 验证：
71. cmake --version
74. ⸻
76. 六、问题四：node-gyp 编译失败
78. 安装过程中出现错误：
80. missing any VC++ toolset
81. could not find a version of Visual Studio
83. 完整提示：
85. You need to install the latest version of Visual Studio
86. including the "Desktop development with C++" workload.
88. 原因
90. Node 原生模块编译依赖 node-gyp，而 node-gyp 在 Windows 上需要以下组件：
91.         •        MSVC 编译器
92.         •        Windows SDK
93.         •        C++ Toolchain
95. 当前系统仅安装了 Visual Studio 的核心组件，没有安装 C++ 编译环境。
97. ⸻
99. 七、安装 Visual Studio C++ 编译工具链
101. 安装 Visual Studio Build Tools：
103. winget install Microsoft.VisualStudio.2022.BuildTools
105. 安装完成后打开：
107. Visual Studio Installer
109. 选择：
111. Modify
113. 勾选以下工作负载：
115. Desktop development with C++
117. 并确保包含以下组件：
118.         •        MSVC v143 - VS 2022 C++ build tools
119.         •        Windows 10 / Windows 11 SDK
120.         •        C++ CMake tools for Windows
122. 完成安装。
124. ⸻
126. 八、重新安装 OpenClaw
128. 清理旧安装：
130. npm uninstall -g openclaw
131. npm cache clean --force
133. 重新安装：
135. npm install -g openclaw
137. 安装完成后验证：
139. openclaw --help
141. 如果能够正常输出帮助信息，则说明安装成功。
143. ⸻
145. 九、Windows 环境推荐开发依赖
147. 为了避免后续 Node 原生模块编译问题，建议一次性安装以下工具：
149. 工具        作用
150. Node.js        JavaScript 运行环境
151. Git        依赖仓库拉取
152. CMake        C++ 构建工具
153. Visual Studio Build Tools        C++ 编译工具链
154. Python        node-gyp 运行依赖
156. 推荐版本：
158. Node.js 22 LTS
159. Python 3.11
160. Git
161. CMake
162. Visual Studio Build Tools (C++)
165. ⸻
167. 十、Windows 与 Linux 环境对比
169. 在 Windows 上安装 AI CLI 工具时，常见问题包括：
170.         •        node-gyp 编译问题
171.         •        C++ 工具链缺失
172.         •        GPU 编译依赖
173.         •        Vulkan / CUDA 依赖
175. 因此很多 AI 开源项目更推荐在 Linux 环境运行。
177. 例如使用 WSL Ubuntu：
179. sudo apt update
180. sudo apt install nodejs npm git cmake build-essential
182. npm install -g openclaw
184. 在 Linux 环境中，安装成功率通常更高。
186. ⸻
188. 十一、总结
190. 在 Windows 环境安装 OpenClaw 时，常见问题主要集中在 Node 原生模块编译环境缺失。
192. 典型问题包括：
193.         1.        Git 未安装
194.         2.        CMake 下载失败
195.         3.        Visual Studio C++ Toolchain 缺失
196.         4.        node-gyp 编译失败
198. 完整解决路径如下：
200. Node.js
201. → Git
202. → CMake
203. → Visual Studio Build Tools (C++)
204. → npm install openclaw
206. 当开发环境完整后，OpenClaw 即可正常安装并运行。
208. ⸻
210. 如果需要长期进行 AI Agent 或 LLM 工具开发，建议提前配置完整的 Node.js 原生模块编译环境，以避免后续开发过程中反复遇到类似问题。

复制代码

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