1. 安装 OpenClaw 时 npm error code 128 到底卡在哪一步如果你正在装 OpenClaw终端里突然蹦出npm error code 128和npm error An unknown git error occurred大概率不是 OpenClaw 本身有问题而是 npm 在拉取某个 git 依赖时被卡住了。OpenClaw 这类工具在安装阶段会通过 npm 去 clone 一些托管在 GitHub 上的包只要 git 这一层握手失败npm 就会把 git 的退出码原样抛出来128 就是 git 的通用失败码。这个报错最迷惑的地方在于它看起来像 npm 的错实际根因几乎都在 git。常见触发点有四类——git 没装或不在 PATH 里、SSH 方式访问 GitHub 没有配好密钥、网络层面对 github.com 的访问不稳定、以及 npm 缓存里存了一份坏的依赖记录。你如果只盯着 npm 反复重装基本是白费力气。这篇面向的是刚接触 OpenClaw、对命令行不算特别熟的同学。我会把定位过程拆成可复制的命令从 git 权限、SSH 配置、registry 与缓存三个角度逐个排查最后给出一份能直接用的配置骨架。整套流程在 Windows 的 cmd / PowerShell 和 macOS、Linux 终端里都适用命令我会标注差异。先明确一个判断标准报错信息里只要出现git字样比如An unknown git error occurred、fatal: could not read Username、Permission denied (publickey)就说明 npm 已经走到 git 拉取阶段了问题在 git 侧不在 npm 侧。记住这一点后面的排查方向就不会跑偏。2. 先把 git 和 npm 的环境底座确认清楚在动手改任何配置之前先花两分钟确认工具链是完整的。很多人报 128 是因为机器上压根没有 git或者 git 装了但没进环境变量npm 调用时找不到可执行文件。打开终端依次执行git --version npm --version node --version正常应该输出类似git version 2.43.0、10.x.x、20.x.x。如果git --version报「不是内部或外部命令」或command not found先去 git 官网装一个Windows 装完后重开终端让 PATH 生效。这一步没过后面所有配置都是空中楼阁。确认 git 可用后再看 npm 当前的 registry 指向哪里npm config get registry如果输出是默认的https://registry.npmjs.org/在国内网络环境下拉包会非常慢间接导致 git 超时。这里可以先把 registry 换成国内镜像减少网络抖动带来的干扰npm config set registry https://registry.npmmirror.com换完再npm config get registry确认一次。注意换 registry 只解决 npm 包本身的下载OpenClaw 依赖里那些走 git 协议的包不受 registry 影响所以 git 侧还得单独处理这就是下一节的内容。3. 用 TaoToken 打通模型侧配置避免装完跑不起来OpenClaw 装好之后要真正跑起来还得接一个可用的模型服务。我自己的做法是把它指向 TaoToken这样模型对话、编码计划、API Key 管理都在一个控制台里省得来回切平台。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基地址是 https://taotoken.net/api 注意 API 地址后面不要带 UTM 参数。具体操作路径是这样先到控制台创建一个 API Key入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后如果你只是想先验证模型能不能通可以直接用模型对话页面试一句 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算长期用 OpenClaw 做编码或者跑 Agent 任务建议看一下 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用的场景。接入细节和参数说明都在文档里 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。用 Claude Code 这类工具的同学Anthropic 兼容接入的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把模型侧先配好有个好处等 OpenClaw 装完你立刻就能验证它是不是真的能用而不是装完了发现连不上模型又得回头排查问题混在一起更难定位。4. 可复制的 git 与 npm 配置骨架这一节是全文的核心直接给能粘贴的配置。先处理 git 的 URL 重写这是解决 128 报错最有效的一招。原理是把gitgithub.com:这种 SSH 形式的地址自动替换成https://github.com/的 HTTPS 形式绕开 SSH 密钥没配好的问题。git config --global --unset-all url.https://github.com/.insteadOf git config --global url.https://github.com/.insteadOf gitgithub.com: git config --global url.https://github.com/.insteadOf ssh://gitgithub.com/第一行是清理可能存在的旧规则避免多条 insteadOf 冲突。后两行分别覆盖gitgithub.com:和ssh://gitgithub.com/两种写法。执行完可以用下面这条命令确认规则生效git config --global --get-regexp url应该能看到你刚写入的两条 insteadOf 记录。如果之前配过一些来路不明的镜像地址比如某些已经失效的加速域名务必用--unset-all清掉否则 git 会优先匹配到坏规则照样报 128。接着处理 npm 侧。除了前面换的 registry建议把 git 相关的超时和日志级别调一下方便看真实原因npm config set fetch-timeout 60000 npm config set fund false npm config set audit falsefetch-timeout调到 60 秒给慢网络留足时间关掉 fund 和 audit 能减少安装时的额外网络请求降低失败概率。这些配置会写进用户级的.npmrcWindows 在C:\Users\你的用户名\.npmrcmacOS 和 Linux 在~/.npmrc。如果你用的是 OpenClaw 的配置文件方式接入模型settings.json的骨架大概长这样把 Key 换成你自己的{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, modelName: 你的模型名 }, git: { timeout: 60000 } }注意baseUrl只写到/api不要多加路径也不要带任何查询参数。字段名以 OpenClaw 当前版本的文档为准不同版本可能略有差异接入前扫一眼 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 最稳妥。配置改完清一次 npm 缓存再装避免旧缓存里的坏记录继续作祟npm cache clean --force npm install -g openclawlatest5. 逐步验证从 git 连通性到 OpenClaw 启动配置写完不代表就好了得一步步验证这样出问题能立刻定位到是哪一层。第一步单独测 git 能不能访问 GitHubgit ls-remote https://github.com/git/git.git HEAD这条命令只读取远端引用不下载仓库。如果几秒内返回一串 commit hash说明 git 到 GitHub 的 HTTPS 通道是通的。如果卡住或报Could not resolve host那是网络层问题跟 npm 无关先解决网络再回来。第二步验证 npm 能否正常拉一个 git 依赖。可以拿一个体积小的包试npm view openclaw version能打印出版本号说明 registry 和 npm 本身没问题。第三步才是正式安装npm install -g openclawlatest成功时终端会输出added xxx packages in xx s看到这行基本就稳了。装完重开一个新终端窗口让环境变量刷新然后验证openclaw --version openclaw --help两条命令都能正常输出说明 OpenClaw 本体装好了。最后一步是验证模型侧用你配好的 Key 发一次请求确认能拿到回复。如果模型请求报 401多半是 Key 写错或没生效报连接超时检查baseUrl是不是写成了带路径的地址。这一步过了整个链路才算真正打通。6. 本篇常见报错逐条排查npm error code 128反复出现先看git config --global --get-regexp url有没有残留的坏规则尤其是那些指向已失效加速域名的 insteadOf全部 unset 掉再重配。如果报错里带Permission denied (publickey)说明 git 还在走 SSH检查 insteadOf 规则是否真的生效必要时用GIT_SSH_COMMAND临时强制走 HTTPS。An unknown git error occurred后面通常还有一行更具体的信息别只看第一行。把 npm 的日志级别调高能看到完整 git 输出npm install -g openclawlatest --loglevel verbose日志里会打印实际执行的 git 命令和它的 stderr顺着那行找根因最快。如果报Could not resolve host: github.com是 DNS 或网络问题换个网络环境或检查本机 DNS 设置。安装卡在某个包不动多半是缓存坏了。执行npm cache clean --force后重装还不行就删掉node_modules和package-lock.json再来。Windows 上如果报路径过长或权限错误用管理员身份开终端或者把全局安装目录换到用户目录下npm config set prefix C:\Users\你的用户名\npm-global改完记得把这个目录加进 PATH。macOS 和 Linux 上如果报EACCES不要用 sudo 硬装同样改 prefix 到用户目录更干净。还有一种情况是装完了但openclaw命令找不到这是 PATH 没刷新。关掉当前终端重开一个或者手动 source 一下配置文件。确认全局 bin 目录在 PATH 里npm config get prefix输出的路径下的binWindows 是根目录应该在 PATH 中。这些坑我基本都踩过一遍按顺序排查绝大多数 128 报错都能在十分钟内解决。
