先说下背景。这篇是 OpenClaw 升级实战的续篇上一篇聊的是基础部署这篇记录的是把一台装了 npm 和 Yarn 混编环境的 Windows 机器升级到 OpenClaw 3.8 正式版的完整排障过程。本来我以为就是跑一条升级命令的事结果从 PowerShell 执行策略卡住开始一路碰到依赖树冲突、Python 版本不符、WSL 环境报警前前后后折腾了一整晚才把服务拉起来。如果你也是那种“环境里既有 npm 又有 yarn、Node 装过不止一遍、还开过几个不同版本 Python 共存”的人这篇排障记录应该能帮你少走不少弯路。1. 升级前的环境体检npm/Yarn 混装为什么必炸1.1 先看清你手上到底是什么环境升级不是上来就npm install -g一把梭。我做的第一件事是盘一下当前环境把能查的全查了一遍node -v npm -v yarn -v openclaw --version npm ls -g --depth0结果第一眼就发现问题了这台机器上 npm 和 yarn 都装了yarn -v能正常输出说明 Yarn 是全局可用的。再往下看npm ls -g的列表里面混着一些明显是用 Yarn 装到全局的包——这类包在 npm 的视角里是“不存在”的但它们的可执行文件却躺在同一个 bin 目录里。这就是典型的 npm/Yarn 混装痕迹。问题就出在这里OpenClaw 3.8 的官方安装链路默认走 npm而 Yarn 留下的node_modules结构、hoist 布局、以及缓存机制跟 npm 完全不互通。当你同时用两套包管理器操作全局包时表面上一个包能跑实际上是系统帮你把某个入口放到了 PATH 最前面你根本不知道最终执行的是哪一份。1.2 混装造成后果的底层逻辑用个生活化的比喻npm 和 Yarn 就像是两套独立的仓库系统各记各的账。npm 记账的货物放在 A 仓库Yarn 记账的货物放在 B 仓库但两张账单共用一个出货口。升级时 npm 检查自己的“货物清单”package-lock.json发现 B 仓库里的“货”不在自己账本上就认定版本缺失或者冲突然后开始重新下载 B 里其实已经存在的那份依赖。具体到 OpenClaw 升级场景最常见的结果有几种老版本入口还挂在node_modules/.bin或者全局 linkage 里新版安装完成后openclaw命令调到的还是旧版升级了等于没升某个 peer 依赖被 Yarn 装成了旧版npm 7 的严格解析机制直接报 ERESOLVE拒绝继续安装两套缓存目录里都有部分 tarball下载时互相干扰明明网络没问题却反复报 checksum 校验失败。这就是为什么我反复强调带着 Yarn 残留去升级 OpenClaw运气好一次过运气不好就是在给后边的每一步埋雷。所以这轮升级的第一步明确就是把所有跟 OpenClaw 相关的 Yarn 入口清理干净再谈装新版。具体怎么清放到第四部分一起讲因为前面还有几道坎挡着不先绕过去你连清理命令都跑不动。2. 第一道坎npm.ps1 无法加载PowerShell 执行策略与双路径残留2.1 报错现场升级命令还没执行先撞上了最烦人的一个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。 有关详细信息请参阅 about_Execution_Policies。这个报错我在很多装 Node 的机器上都见过但不少人不知道它和升级 OpenClaw 有什么关系。关系很大OpenClaw 3.8 的安装脚本、启动自检、周边小工具的调用大量依赖 PowerShell 环境如果连 npm 都跑不了后边 WSL 检查、模型桥接脚本大概率也跑不动。有意思的是同一个 npm 在 CMD 里能正常执行在 PowerShell 里一敲就报错。原因不在 Node在 PowerShell 的脚本执行策略。2.2 报错背后的机制拆解Windows 下 PowerShell 默认的ExecutionPolicy是Restricted意思是禁止运行任何.ps1脚本。npm 本身提供两个入口npm.cmd批处理CMD 和 PowerShell 都能直接跑和npm.ps1专门给 PowerShell 用的脚本。在 PowerShell 里敲npm解释器优先找npm.ps1因为执行策略是 Restricted这个脚本直接被打回。这里有个很常见的误解以为给当前用户设置成完全放开Unrestricted就完事。实践下来更稳妥的做法是RemoteSigned——本地创建的脚本允许运行从网络下载的脚本必须带签名。对于 npm 这类本地安装的脚本完全够用而且不会把安全边界拉得太低。2.3 正确处理路径和第二个变体坑在 PowerShell 里执行下面这条只对当前用户生效Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser Get-ExecutionPolicy -List执行完用Get-ExecutionPolicy -List确认CurrentUser这一行是RemoteSigned再敲npm -v验证。但别急着高兴。如果你的机器跟我这台一样之前装过不止一次 Node还会遇到第二个变体报错——路径变成D:\Program Files\nodejs\npm.ps1或者C:\Users\Administrator\AppData\Roaming\npm下的脚本路径。这类报错的根源跟前一种完全不一样是 PATH 里有多个 Node 安装目录残留。解决办法是先检查解析到的到底是哪套安装where.exe node where.exe npm如果输出有多行或者 node 和 npm 来自两个不同目录说明旧 Node 路径还挂在 PATH 里。处理方式是把环境变量里旧的 Node 目录删掉只留一份然后重启 PowerShell 再验证。这个细节花了我不少时间因为当时node -v显示的是一份新版 Nodenpm -v却调到另一个旧安装路径下的脚本两边版本对不上。确认 PATH 干净之后升级才敢真正进入依赖阶段。3. 依赖树炸了ERESOLVE 与 Node/Python 版本矩阵3.1 你会在哪一步遇到 ERESOLVE环境命令能跑之后我直接尝试全局安装 OpenClaw 3.8结果立刻收到一堆这种报错npm ERR! ERESOLVE overriding peer dependency npm ERR! While resolving: openclaw3.8.0 npm ERR! Found: some/package2.1.0 npm ERR! Could not resolve dependency: npm ERR! peer some/package^3.0.0 from openclaw3.8.0npm 7 之后默认启用严格依赖解析。之前的 npm 6 遇到 peer 依赖冲突只是 warning顶多装完跑不起来你不会太注意npm 7 直接 ERROR 中断安装。OpenClaw 3.8 这类工具包在发布时会锁定一组 peer 依赖范围本机若是残留着旧版本就会卡在这里。这时候很多人的第一反应是补一个--force或者--legacy-peer-deps硬闯过去。我的建议是先看清楚冲突的到底是哪个包再决定。如果只是 OpenClaw 内部某个插件的 peer 要求和全局老包有出入用--legacy-peer-deps装上再回头逐个升级旧包问题不大。如果冲突涉及 Node 运行时本身的能力比如某些包要求node 18那 force 只是饮鸩止渴运行期会在奇奇怪怪的地方挂掉。OpenClaw 3.8 对运行时的要求官方发布说明里列得比较清楚。我在实操里的结论是Node 版本最好在 18 LTS 及以上npm 版本 9 更稳。如果你本机还停在一个很老的 Node 12 或 14那别硬撑先切版本再升级。用nvm或fnm切版本是最干净的做法比去 Node 官网反复下载安装包好维护得多。3.2 Python 3.8容易被忽略的第二套运行时OpenClaw 3.8 还有一个容易踩的隐性条件它的一部分能力尤其是本地模型桥接和若干 skill 的执行环境依赖一套可用的 Python 运行时。热搜里出现的“modelscope 安装 qwen 3.8 / python 3.8”说的就是这种场景——你想让 OpenClaw 关联到本地 qwen 模型得先通过 ModelScope 把模型拉下来而 ModelScope 的底层调用链对 Python 版本有硬性要求。我当时的情况是系统默认 Python 是 3.7OpenClaw 3.8 的模型桥接脚本要求 Python 3.8 以上。装依赖时 pip 报了一堆Requires-Python 3.8的错误最后走了 conda 创建独立环境的路线conda create -n openclaw python3.8 conda activate openclaw pip install modelscope实测下来把 Python 版本拉起来之后ModelScope 拉取 qwen 模型和 OpenClaw 关联调用的链路就通了。这里想提醒一句OpenClaw 本身是 Node 工具但它把模型层外置了所以排查问题不要只盯着node_modules里的报错也要检查 Python 侧。两边版本矩阵对不上表观症状就是“装好了但模型加载不了日志里看不出所以然”。4. 干净升级的操作链卸载残留、清缓存、换源、装 3.84.1 先把旧入口彻底卸掉升级到 3.8 之前我按第一部分的思路先把旧版 OpenClaw 卸干净。注意不能只用npm uninstall -g openclaw——因为混装环境里可能还有 Yarn 装的副本。推荐的清理链路是这样的# 1. npm 侧卸载 npm uninstall -g openclaw # 2. yarn 侧卸载如果 yarn 里有副本 yarn global remove openclaw # 3. 找到残留入口 where.exe openclaw第三步很关键。where.exe openclaw会把 PATH 里所有匹配的可执行文件列出来。如果列出的路径不止一个说明有硬链接残留逐个删掉。Windows 上常见的残留位置是C:\Users\用户名\AppData\Roaming\npm也就是 npm 的全局 bin 目录老版本的入口文件可能躺在那里没被卸载脚本清掉。4.2 清缓存和 lock 文件卸载之后我顺手把缓存和 lock 一起清了一遍。这一步在“混装升级”场景里特别重要因为 npm 和 Yarn 各自的 lock 文件会互相干扰npm cache verify然后在项目目录里rm -Recurse -Force node_modules rm package-lock.json rm yarn.lock为什么 lock 文件要删Yarn 的yarn.lock和 npm 的package-lock.json记录的是两套依赖树快照。升级主工具版本时旧 lock 里残留的解析结果可能和 3.8 的依赖要求冲突。删掉之后让 npm 重新解析一遍反而最稳。这里多说一句npm cache verify的作用它不是简单地清空缓存而是校验缓存数据的完整性顺便清理无效损坏的 tarball。在混装环境里包可能分别从不同源、不同工具下载过缓存目录里同一版本存在多份哈希不同的文件verify 会帮你把不匹配的踢掉避免后续安装时出现“明明下载了却说校验失败”的诡异问题。4.3 换源不是可选项是省命选项OpenClaw 3.8 的依赖链不小直接走默认源在部分地区下载会非常慢甚至超时。国内实操基本上都会切 npm 镜像我用的是 npmmirror也就是大家常说的淘宝源npm config get registry npm config set registry https://registry.npmmirror.com这里有一个我踩过的点换完源后建议再做一次npm cache verify。因为混装环境里缓存下载的 tarball 可能来自不同源源切换后校验值对不上会报内部错误。先把旧缓存清掉再拉新包整个过程会顺很多。另外提一句镜像源的更新频率npmmirror 这类镜像对热门包的同步基本是分钟级OpenClaw 3.8 发布后很快就能拉到不放心的话可以先npm view openclaw version确认一下镜像上有没有你要的版本避免装到一个过期缓存。4.4 正式安装 3.8最后执行安装。虽然官方提供了升级命令但按前面的清理步骤走完后我选择直接干净安装固定版本npm install -g openclaw3.8.0这里不推荐用latest而不加确认因为你不知道此刻 latest 指向的是 3.8 还是 3.9。写明确版本号升级行为完全可控。装完第一件事不是急着跑而是验证openclaw --version版本号输出正确再往下进入功能验证。这一步也想提醒一下如果你升级完发现openclaw还是旧版本号第一反应不要怀疑安装失败先执行where.exe openclaw检查 PATH 是不是解析到了旧目录。这是混装环境升级后最容易出现的假象我见过不止一次。5. 升级后的验证清单与残坑WSL、缺失可选依赖和本地模型5.1 WSL 2 环境未就绪的报错装完 3.8第一次跑自检弹出来的不是程序日志而是这样一条提示无法安全验证 SL2 环境。请在 PowerShell 中运行 wsl --status 解决报告的问题。这里的 SL2 指的就是 WSL 2。OpenClaw 3.8 的某些组件比如沙箱执行、容器化 skill 环境启动时会检查 WSL 2 是否可用。如果以前没配过 WSL或者默认版本还是 1就会卡在这个检查上。处理方式不复杂wsl --status wsl --set-default-version 2第一条命令先看清楚当前状态如果提示没有已安装的发行版还要先wsl --list --online看可用的发行版并装一个。这里不用纠结发行版是 Ubuntu 还是 DebianOpenClaw 要的是“WSL 2 的内核环境存在”不是特定某个发行版。5.2 missing optional dependency不用慌安装日志里还有一条容易被误判为“装失败了”的警告missing optional dependency openai/codex-win32-x64. reinstall codex: npm install这个看着吓人其实说的是某个特定平台的预编译二进制不存在。Windows x64 上某些包没有提供预编译产物npm 会把它标记为optional缺失然后在需要的时候走源码编译或者直接跳过。我的做法是先确认功能是否受影响OpenClaw 3.8 自检能通过、skill 列表能正常列出、模型桥接能联通就说明这个可选依赖不影响当前主要使用路径。如果后续真的用到对应的 codex 相关能力再去项目目录执行一次补装即可不需要在升级阶段跟它死磕。5.3 把本地模型关联起来测试最后一步是验证 3.8 的完整功能重点是把本地模型接进来测一遍。我用的是 qwen2.5-3bModelScope 下载完成后在 OpenClaw 配置里把模型端点指到本地服务。如果你之前 Python 用的不是 conda 环境这块很容易在版本上翻车。我的建议是OpenClaw 3.8 的模型桥接脚本、ModelScope 的依赖、以及模型推理进程尽量跑在同一套 Python 环境里避免系统 Python 和 conda base 环境互相覆盖。跑通一次对话确认 OpenClaw 能正确调用本地模型这次升级才算真的落地。说实话这次从 npm/Yarn 混装环境升到 3.8 正式版最大的体会就一句话环境越乱越要先清理再升级而不是靠--force硬闯。PowerShell 执行策略、PATH 双目录、Python 版本、WSL 状态这些看起来和“升级”无关的检查反而决定了升级能不能顺利完成。从那次之后我把这几项固化成自己的升级前 checklist每次碰大版本升级先过一遍后面踩的坑确实少了很多。