Windows 下 OpenClaw 安装全记录：从零到一的保姆级图文教程（持续更新中）
1. 背景
在这个技术迭代飞快的时代，追求高效、自由的开源方案总是开发者的共同课题。OpenClaw，作为一款备受瞩目的开源项目，以其独特的架构和强大的扩展性，吸引了众多开发者和爱好者的注意。但现实情况是，不少朋友在第一关“环境搭建”上就遇到了阻碍。即便是有经验的开发者，在Windows环境下处理复杂的依赖关系和路径配置时，也常会感到棘手。
为什么要写这篇深度教程呢？归根结底，市面上现有的文档普遍存在一些问题：要么过于零散，不成体系；要么是直接从Linux环境“平移”过来，对Windows用户特有的适配细节语焉不详。对于希望在清晰的代码流里寻找秩序感的开发者来说，实在不应该让琐碎的安装报错消磨掉最初的探索热情。所以，这份详尽的“保姆级”指南应运而生。
本教程将采用“全流程透明化”的策略，从最基础的工具准备（比如Node.js的安装选择）到最后阶段的成功运行，每一个步骤都会配上详细的截图和操作要点。无论你是刚接触开源项目的新手，还是希望快速部署环境以便进行二次开发的专业人士，这份指南都能帮你绕开90%以上的常见障碍。
在进入正题之前，需要说明一下，本专栏的文章均基于实际项目经验，在剥离了繁杂的业务逻辑后，提炼出的核心操作路径。下面，就让我们从零开始。
2. 实战教程
2.1 步骤一：安装Node.js
OpenClaw的运行依赖Node.js环境，这是整个安装流程的基石。首先，需要访问Node.js官网（nodejs.org），下载适用于Windows的LTS（长期支持）版本安装包。这里有个细节需要注意：建议选择安装包（.msi）而非压缩包，因为安装程序会自动配置好系统环境变量，能省去不少手动配置的麻烦。
安装过程基本是“下一步”到底，但有一处值得留意：在安装向导中，记得勾选“Automatically install the necessary tools…”这个选项（如果出现的话），它会帮你安装一些编译所需的原生模块工具。安装完成后，打开命令提示符（CMD）或PowerShell，输入node --version和npm --version。如果都能正确显示出版本号，就说明基础环境已经准备就绪了。
2.2 步骤二：安装git
接下来需要安装Git。作为一个分布式版本控制系统，它是从GitHub等平台克隆OpenClaw源代码的必备工具。前往Git官网（git-scm.com）下载Windows版本的安装程序。
安装过程中，关于“Adjusting your PATH environment”的选项，建议选择“Git from the command line and also from 3rd-party software”。这样配置后，你就可以在任意的命令行窗口中使用git命令了。其他设置保持默认即可。安装完成后，同样在命令行输入git --version来验证是否安装成功。
2.3 步骤三：安装OpenClaw
基础工具齐备，现在可以着手安装OpenClaw本体了。找一个合适的目录，比如在D盘下新建一个“Projects”文件夹，然后在此打开命令行。执行克隆命令：git clone [OpenClaw的仓库地址]。这个过程会将项目源代码拉取到本地。
克隆完成后，使用cd命令进入项目根目录。接下来是关键一步：安装项目依赖。运行npm install命令。这个命令会根据项目中的package.json文件，自动下载并安装所有必需的Node.js模块。网络状况好的情况下，几分钟就能完成。如果遇到速度慢或超时，可以考虑配置国内的npm镜像源。
2.4 步骤四：配置OpenClaw
依赖安装好后，项目还不能直接运行，需要进行一些基础配置。通常，项目根目录下会有一个示例配置文件，例如config.example.js或.env.example。你需要将其复制一份，并重命名为实际使用的配置文件（如config.js或.env）。
用文本编辑器打开这个新配置文件。里面往往包含一些核心参数的设置，比如服务运行的端口号、数据库连接信息、API密钥等。对于初次尝试，可以暂时使用默认值或留空，但必须确保文件存在且格式正确。这一步常常被忽略，却是后续报错的“高发区”。
2.5 步骤五：配置模型
OpenClaw这类项目通常需要接入大语言模型（LLM）才能发挥核心功能。因此，配置模型接入点是至关重要的一环。你需要根据项目文档的指引，去相应的AI平台（例如OpenAI、智谱AI、DeepSeek等）申请API密钥。
申请到密钥后，回到刚才的配置文件中，找到关于模型配置的字段（例如API_KEY, BASE_URL, MODEL_NAME等），将你的密钥和选择的模型名称填写进去。切记，密钥属于敏感信息，务必妥善保管，不要直接上传到公开的代码仓库。
2.6 步骤六：对话
所有配置完成后，激动人心的时刻就到了。在项目根目录下的命令行中，运行启动命令。根据项目不同，可能是npm start、node app.js或是其他自定义命令。命令行会输出一系列启动日志，如果没有报错，并最终显示“Server running on port XXXX”或类似信息，就说明服务已经成功启动了。
此时，打开浏览器，访问http://localhost:端口号（端口号就是日志中显示的那个）。如果能看到OpenClaw的Web界面，那么恭喜你，安装部署已经基本成功了。接下来，你就可以在界面的输入框中尝试进行第一次对话，体验开源模型的能力了。
3. 后续使用步骤
成功运行只是第一步。要熟练使用，还需要了解一些常规操作：如何停止服务（通常在命令行按Ctrl+C），如何修改配置并重启使之生效，以及如何查看项目日志来排查问题。此外，关注项目的GitHub仓库，及时通过git pull拉取更新，也是保证稳定性和体验新功能的好习惯。
4. 报错解决方案
安装过程很少有一帆风顺的。这里汇总了几个最常见的报错及其解决方法，在遇到问题时可以先从这里找找思路。
4.1 node --version 显示不是内部或者外部命令，也不是可运行的程序或者批处理文件
这个错误说明系统没有找到Node.js的执行路径。解决方法是检查Node.js是否安装成功，并确认其安装目录（通常是C:\Program Files\nodejs）是否被添加到了系统的PATH环境变量中。可以在系统属性中手动添加，或者卸载Node.js后重新安装，并在安装时确认勾选了添加PATH的选项。
4.2 npm error code ENOENT npm error syscall spawn git
这个错误指出，npm在执行过程中需要调用git命令，但系统找不到git。解决方案是确认Git是否已正确安装，并且git命令是否能在命令行中全局访问。可以重新运行Git安装程序，确保在配置PATH时选择了允许从命令行访问。
4.3 npm error code 128 npm error An unknown git error occurred
此错误通常与网络或权限有关。可能是克隆仓库时网络不稳定，或者目标目录的权限不足。尝试更换网络环境，或者以管理员身份运行命令行，并确保项目目录没有读写限制。有时，清理一下本地的git缓存（git config --global --unset http.proxy）也能解决问题。
5. OpenClaw的卸载
如果需要卸载OpenClaw，过程其实很简单，因为它本质上是一组本地文件和依赖。首先，停止正在运行的服务。然后，直接删除整个项目文件夹即可。如果你希望通过命令行卸载全局依赖，可以进入项目目录，执行npm uninstall来移除本地node_modules，但这通常不是必须的。最后，如果你想彻底清理，可以手动删除与OpenClaw相关的数据库文件或其他在配置中指定的数据存储路径。这样，系统就恢复如初了。