前言
在原生 Windows 11 环境下（未使用 WSL2），配合 Node.js 24.12.0 和 npm 11.7.0 进行环境搭建时，可能会遇到 Git 相关的报错。这里整理了两类最常见的问题及解决方案。
安装命令参考
通用安装方式如下，用于获取最新稳定版：
npm install -g openclaw@latest
如果需要测试版（beta），可以使用官方脚本：
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd --tag beta && del install.cmd
问题一：缺少 Git 依赖工具
如果终端提示 npm error code ENOENT / syscall spawn git / 找不到 Git 文件，说明系统里没装 Git。npm 在安装包时需要调用 Git 拉取源码。
解决办法：
- 前往 Git 官网 下载 Windows 安装包。
- 运行安装程序，一路'下一步'即可。
- 关键步骤：安装向导中务必勾选
Git from the command line and also from 3rd-party software，这样会自动配置环境变量，不用手动折腾。 - 关闭所有终端窗口重新打开，输入
git --version确认是否生效。
问题二：GitHub 权限验证失败
安装了 Git 后，如果遇到 [email protected]: Permission denied (publickey) 或 code 128，通常是 SSH 密钥没配好。我们可以强制 Git 使用 HTTPS 协议来绕过密钥验证。
操作步骤：
- 找到并编辑全局配置文件。路径通常在
C:\Users\你的用户名\.gitconfig。直接用记事本打开它。注意：如果在终端直接执行
git config命令，Windows PowerShell 可能存在解析 Bug，导致相同域名的配置被覆盖，SSH 替换规则丢失。建议直接编辑文件更稳妥。 - 清空文件中关于
url的配置内容，粘贴以下规则：
[url "https://gitclone.com/github.com/"]
insteadOf = [email protected]:
[url "https://gitclone.com/github.com/"]
insteadOf = ssh://[email protected]/
[url "https://gitclone.com/github.com/"]
insteadOf = https://github.com/
这会将所有指向 GitHub 的请求重定向到镜像源，从而避开 SSH 验证。
继续安装
配置完成后，先清理一下 npm 缓存，再重新尝试安装：
npm cache clean --force
npm install -g openclaw@latest
如果在安装过程中遇到拿不准的步骤，可以先跳过（skip），后续通过 openclaw onboard 命令回来修改配置。
