OpenClaw 升级实战（二）：从 npm/Yarn 混装到 3.8 正式版的完整排障记录

在上一篇《OpenClaw 升级指南：从 2026.2.24 到 2026.3.8 全记录》中，我们完成了 OpenClaw 的首次升级尝试，通过跳过 llama.cpp 编译成功安装了 3.8 版本。但由于跳过了 postinstall 脚本，版本号始终显示为旧版 2026.2.24，而且后续还遇到了第三方 API 服务异常被误判为升级故障的问题，不得不回滚到旧版。本文记录了第二次升级的完整过程

tommychian

886人浏览 · 2026-03-13 17:27:55

tommychian · 2026-03-13 17:27:55 发布

前言

在上一篇《OpenClaw 升级指南：从 2026.2.24 到 2026.3.8 全记录》中，我们完成了 OpenClaw 的首次升级尝试，通过 --ignore-scripts 跳过 llama.cpp 编译成功安装了 3.8 版本。但由于跳过了 postinstall 脚本，版本号始终显示为旧版 2026.2.24，而且后续还遇到了第三方 API 服务异常被误判为升级故障的问题，不得不回滚到旧版。

本文记录了第二次升级的完整过程，包括：发现 Yarn/npm 双重安装的根本原因、彻底清理并统一安装方式、正确使用 NODE_LLAMA_CPP_SKIP_DOWNLOAD 环境变量、排查第三方 API 导致的 Agent 失灵，以及最终成功升级并配置模型降级策略的全过程。

一、环境背景

项目	配置
服务器	阿里云 ECS
操作系统	AliOS（CentOS 系）
物理内存	1.8G + 4G Swap
OpenClaw 起始版本	2026.2.24 (df9a474)
OpenClaw 目标版本	2026.3.8 (3caab92)
原始安装方式	Yarn 全局安装（后统一为 npm）
AI 主模型	Claude Sonnet 4.6（通过 API123.icu 转发）
AI 备用模型	dashscope/qwen3.5-plus（阿里百炼 Coding Plan）
前端渠道	飞书自建 Agent（多多助理）

二、上次升级遗留的问题

上一次升级使用了 npm install -g openclaw@latest --ignore-scripts 成功安装了 3.8，但留下了两个问题：

版本号显示错误：openclaw --version 仍然显示 2026.2.24，因为 --ignore-scripts 跳过了 build-info 的生成
飞书 Agent 不响应：升级后多多助理出现 rate limit 和 timeout 错误

当时以为是新版 OpenClaw 的问题，所以回滚到了旧版。但事后分析发现，真正的原因是第三方 API 服务（yansd666.com 和 API123.icu）同时出了问题，和 OpenClaw 版本完全无关。

三、发现根本原因：Yarn/npm 双重安装

这次排查从版本号入手，终于发现了一个隐藏已久的问题。

3.1 症状

用 npm 安装了 3.8 版本，package.json 里版本号是对的，但 openclaw --version 始终显示旧版：

npm list -g openclaw
# → openclaw@2026.3.8 ✅

openclaw --version
# → 2026.2.24 ❌

3.2 排查过程

which openclaw
# → /usr/local/bin/openclaw

ls -la /usr/local/bin/openclaw
# → /usr/local/bin/openclaw -> ../share/.config/yarn/global/node_modules/.bin/openclaw

真相大白：openclaw 命令指向的是 Yarn 安装的旧版本，而不是 npm 安装的新版本！

系统上存在两份 OpenClaw：

安装方式	路径	版本	是否在用
Yarn（原始安装）	/usr/local/share/.config/yarn/global/node_modules/	2026.2.24	✅ 命令指向这里
npm（新装的）	/usr/lib/node_modules/	2026.3.8	❌ 没有被使用

教训：升级前一定要用 ls -la $(which openclaw) 确认实际的安装方式，不要想当然地用 npm 或 docker 去升级一个 Yarn 安装的程序。

3.3 为什么不直接用 Yarn 升级？

我们尝试了 Yarn 升级，但国内阿里云服务器访问 GitHub 不稳定，Yarn 在解析依赖时需要通过 Git 访问 GitHub 仓库，反复超时：

error Command failed.
Exit code: 128
Command: git
Arguments: ls-remote --tags --heads <https://github.com/whiskeysockets/libsignal-node.git>
fatal: unable to access: Failed to connect to github.com port 443: Connection timed out

多次尝试均失败，最终决定放弃 Yarn，统一切换到 npm。

四、正确的升级方案：统一切换到 npm

4.1 完整步骤

# 1. 停止 Gateway
openclaw gateway stop

# 2. 备份配置
cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)

# 3. 删掉 Yarn 安装的旧版
yarn global remove openclaw

# 4. 删掉 npm 安装的旧版（如果有的话）
npm uninstall -g openclaw

# 5. 配置 Git HTTPS（避免 GitHub SSH 权限问题）
git config --global url."<https://github.com/>".insteadOf ssh://git@github.com/
git config --global url."<https://github.com/>".insteadOf git@github.com:

# 6. 设置环境变量跳过 llama.cpp 编译（关键！）
export NODE_LLAMA_CPP_SKIP_DOWNLOAD=true

# 7. 用 npm 安装最新版（不加 --ignore-scripts）
npm install -g openclaw@latest

# 8. 刷新 bash 命令缓存
hash -r

# 9. 验证版本
openclaw --version
# → OpenClaw 2026.3.8 (3caab92) ✅

# 10. 启动 Gateway（后台模式）
openclaw gateway start

# 11. 确认进程运行
ps aux | grep openclaw

4.2 关键点解析

为什么用 `NODE_LLAMA_CPP_SKIP_DOWNLOAD=true` 而不是 `--ignore-scripts`？

方案	效果	版本号显示	推荐度
`--ignore-scripts`	跳过所有 postinstall 脚本	❌ 显示旧版本号	⭐⭐ 不推荐
`NODE_LLAMA_CPP_SKIP_DOWNLOAD=true`	只跳过 llama.cpp 的下载和编译	✅ 正确显示新版本号	⭐⭐⭐⭐⭐ 推荐

NODE_LLAMA_CPP_SKIP_DOWNLOAD=true 是精准的手术刀，只跳过不需要的 llama.cpp 编译，其他 postinstall 脚本（包括 build-info 生成）都会正常执行。

为什么需要 `hash -r`？

当你卸载 Yarn 版本并用 npm 重新安装后，openclaw 的实际路径从 /usr/local/bin/openclaw 变成了 /usr/bin/openclaw。但 bash 会缓存命令路径，如果不执行 hash -r，bash 还会去找已经不存在的旧路径，导致 command not found。

启动命令的区别

openclaw gateway start — 后台运行（systemd 服务），关掉终端不影响，日常使用推荐
openclaw gateway — 前台运行，日志直接输出到终端，适合调试排障
openclaw gateway stop — 停止服务 </aside>

五、排查 Agent 不响应的真正原因

升级完成后，飞书 Agent 出现了一系列错误，依次是：

API rate limit reached
LLM request timed out
400 Improperly formed request
401 无效的令牌，数据库查询出错

当时以为是 OpenClaw 3.8 的问题，差点冤枉了新版本。

5.1 排查过程

第一步：直接用 curl 测试 API

curl -s <https://coding.dashscope.aliyuncs.com/v1/chat/completions> \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 50
  }'

结果：API 完全正常，返回了正确的回复。这排除了 dashscope 服务的问题。

第二步：检查主模型配置

cat ~/.openclaw/openclaw.json | python3 -m json.tool 2>/dev/null | grep -A5 '"defaults"'

发现：

"model": "custom-yansd666/claude-sonnet-4-6"

真相浮出水面：主模型指向的是 yansd666.com 这个不稳定的第三方 API 转发服务，而不是 dashscope！所有的 rate limit、timeout、400 错误都是这个第三方服务的问题，和 OpenClaw 版本无关。

5.2 问题链还原

graph TD
    A["升级 OpenClaw 到 3.8"] --> B["Agent 报 rate limit"]
    B --> C["误判为新版问题"]
    C --> D["回滚到 2026.2.24"]
    D --> E["旧版也报同样错误"]
    E --> F["排查发现真正原因"]
    F --> G["主模型指向 yansd666（不稳定）"]
    F --> H["API123.icu 同时过载"]
    G --> I["切换模型后恢复正常"]
    H --> I

教训：升级后遇到问题时，不要急于回滚。先用 curl 直接测试 API，再检查配置文件中的模型指向，逐步缩小问题范围。同时改变多个变量会导致误判。

六、模型降级策略

使用第三方 API 转发服务（如 API123.icu）接入 Claude 等海外模型，虽然能获得更好的回复质量，但稳定性取决于第三方服务。为了保证 Agent 的可用性，建议在 OpenClaw 的模型列表中同时配置多个可用模型。

在 ~/.openclaw/openclaw.json 的 agents.defaults.models 中确保包含：

"models": {
  "custom-api123-icu/claude-sonnet-4-6": {},
  "dashscope/qwen3.5-plus": {},
  "dashscope/qwen3-max": {},
  "dashscope/qwen3-coder-plus": {}
}

OpenClaw 3.8 优化了模型降级与重试机制，当主模型（Claude）限流或过载时，系统会自动在可用模型列表中寻找备选模型，不需要手动切换。

手动切换主模型的命令

当第三方 API 完全不可用时，可以快速手动切换主模型：

# 切换到 dashscope（应急）
sed -i '0,/"model": "custom-api123-icu\\/claude-sonnet-4-6"/{s|"model": "custom-api123-icu/claude-sonnet-4-6"|"model": "dashscope/qwen3.5-plus"|}' ~/.openclaw/openclaw.json
openclaw gateway stop && openclaw gateway start

# 切换回 Claude（恢复后）
sed -i '0,/"model": "dashscope\\/qwen3.5-plus"/{s|"model": "dashscope/qwen3.5-plus"|"model": "custom-api123-icu/claude-sonnet-4-6"|}' ~/.openclaw/openclaw.json
openclaw gateway stop && openclaw gateway start

上面的 sed 命令使用 0,/pattern/ 语法，只替换第一个匹配，不会影响其他子 Agent 的模型配置。

七、飞书 Config Warning 说明

升级后你可能会在启动日志中看到这条警告：

Config warnings:
- plugins.entries.feishu: plugin feishu: duplicate plugin id detected;
  later plugin may be overridden (/usr/lib/node_modules/openclaw/extensions/feishu/index.ts)

这是因为 OpenClaw 内置了飞书插件，而你的 ~/.openclaw/extensions/feishu/ 目录下也有一份飞书扩展。不影响正常使用，系统会自动处理冲突。如果后续版本修复了此问题，可以考虑删除本地的飞书扩展目录。

八、完整命令速查（最终版）

以下是经过两次升级实战验证的推荐升级流程：

# ===== 升级前准备 =====
# 确认当前安装方式（关键！）
ls -la $(which openclaw)

# 停止 Gateway
openclaw gateway stop

# 备份配置
cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)

# ===== 清理旧安装 =====
# 如果是 Yarn 安装的
yarn global remove openclaw

# 如果是 npm 安装的
npm uninstall -g openclaw

# 清理残留
rm -rf /usr/lib/node_modules/openclaw
rm -rf /usr/lib/node_modules/.openclaw-*

# ===== 安装新版 =====
# 配置 Git HTTPS
git config --global url."<https://github.com/>".insteadOf ssh://git@github.com/
git config --global url."<https://github.com/>".insteadOf git@github.com:

# 安装（精准跳过 llama.cpp，其他 postinstall 正常执行）
export NODE_LLAMA_CPP_SKIP_DOWNLOAD=true
npm install -g openclaw@latest

# ===== 验证并启动 =====
hash -r
openclaw --version   # 应显示 OpenClaw 2026.3.8 (3caab92)
openclaw gateway start
ps aux | grep openclaw

九、踩坑清单总览

坑	现象	原因	解决
Yarn/npm 双重安装	npm 装了新版但版本号不变	`openclaw` 命令指向 Yarn 旧版	统一切换到 npm，删掉 Yarn 版本
Yarn 升级失败	Git 访问 GitHub 超时	国内服务器网络限制	放弃 Yarn，用 npm 安装
bash 缓存旧路径	`openclaw: command not found`	bash 缓存了已删除的旧路径	`hash -r` 刷新缓存
`--ignore-scripts` 的副作用	版本号显示为旧版	跳过了 build-info 生成	改用 `NODE_LLAMA_CPP_SKIP_DOWNLOAD=true`
Agent 报 rate limit	飞书不响应	第三方 API（yansd666）不稳定	切换到稳定的 API 提供商
Agent 报 401 无效令牌	飞书不响应	API123.icu 过载	等待恢复，或临时切到 dashscope
误判升级导致问题	不必要的回滚	同时改变多个变量（版本+模型）	先 curl 测 API，再逐步排查

十、经验总结

确认安装方式再升级：用 ls -la $(which openclaw) 确认是 Yarn 还是 npm 安装的，用对应的工具升级
NODE_LLAMA_CPP_SKIP_DOWNLOAD=true 是最优解：比 --ignore-scripts 更精准，只跳过不需要的 llama.cpp 编译
第三方 API 是最大的不确定因素：使用 Claude 等海外模型时，API 转发服务的稳定性是薄弱环节，务必配置备用模型
排障时一次只动一个变量：升级版本和切换模型不要同时做，否则出问题时无法判断原因
curl 是排查 API 问题的利器：直接测试 API 端点，能快速区分是 OpenClaw 的问题还是 API 服务的问题
备份永远是第一步：cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d) 这条命令救了我好几次