OpenClaw 升级标准流程

一套经过生产环境实战检验的 OpenClaw 升级流程，源于一次真实生产事故：Dashboard 升级静默导致 Gateway 通信中断（Telegram、WebChat），且未输出任何明确错误信息。

适用场景：将 OpenClaw 升级至新版本、规划安全升级路径，或从失败升级中恢复。

为何需要此流程

2026 年 3 月，一次由 Dashboard 触发的从 2026.3.13 到 2026.3.22 的升级引发以下问题：

• Gateway 静默失效（Telegram 显示“正在输入”，但消息永不送达）
• Dashboard 使用 pnpm，而该工具未在系统中安装
• Gateway 入口文件重命名（entry.js → index.js），但 systemd 服务文件未同步更新
• openclaw doctor --fix 修复了配置，但未更新 systemd 服务文件
• 最终需依赖备份恢复系统

本流程可彻底规避上述所有问题。

黄金法则

切勿通过 Dashboard 执行升级。 始终使用 CLI 进行升级。

操作流程

步骤 1：备份（2 分钟）

BACKUP_DIR="$HOME/.openclaw/workspace/backups/openclaw-upgrade-$(date -u +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# 配置 + 凭据 + Agents
cp ~/.openclaw/openclaw.json "$BACKUP_DIR/"
cp -r ~/.openclaw/credentials "$BACKUP_DIR/" 2>/dev/null
cp -r ~/.openclaw/agents "$BACKUP_DIR/agents" 2>/dev/null

# 服务文件
cp ~/.config/systemd/user/openclaw-gateway.service "$BACKUP_DIR/" 2>/dev/null

# 版本信息
openclaw --version > "$BACKUP_DIR/state-info.txt"
npm list -g openclaw >> "$BACKUP_DIR/state-info.txt" 2>&1

echo "Backup saved to: $BACKUP_DIR"

步骤 2：阅读发布说明（5 分钟）

访问 https://github.com/openclaw/openclaw/releases

需重点关注的高风险项：

• 标有 “Breaking” 的条目 → 涉及配置或插件变更
• Plugin SDK 变更 → 可能导致 Telegram/Discord 插件失效
• 入口文件（Entrypoint）变更 → 需同步更新服务文件
• 配置/状态迁移 → 可能使现有配置失效

步骤 3：运行 doctor 基线检查（1 分钟）

openclaw doctor 2>&1 | tee "$BACKUP_DIR/doctor-before.txt"

步骤 4：执行升级（3 分钟）

# 务必使用 npm，禁止使用 pnpm 或 Dashboard
npm update -g openclaw

# 验证升级结果
openclaw --version

步骤 5：运行 doctor 修复（2 分钟）

# 查看需迁移的项目
openclaw doctor

# 应用修复（配置 Schema 变更、弃用项处理等）
openclaw doctor --fix

步骤 6：修复服务入口文件（1 分钟）

# 检查当前入口文件是否匹配
CURRENT_ENTRY=$(grep ExecStart ~/.config/systemd/user/openclaw-gateway.service | grep -oP 'dist/K[^ ]+')
ACTUAL_ENTRY=$(ls ~/.npm-global/lib/node_modules/openclaw/dist/index.js 2>/dev/null && echo "index.js" || echo "entry.js")

if [ "$CURRENT_ENTRY" != "$ACTUAL_ENTRY" ]; then
  echo "⚠️  入口文件不匹配：service=$CURRENT_ENTRY actual=$ACTUAL_ENTRY — 正在修复..."
  sed -i "s|dist/$CURRENT_ENTRY|dist/$ACTUAL_ENTRY|g" ~/.config/systemd/user/openclaw-gateway.service
  echo "✅ 已修复"
else
  echo "✅ 入口文件正常"
fi

步骤 7：重启 Gateway（1 分钟）

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service
sleep 5
systemctl --user status openclaw-gateway.service

步骤 8：验证测试（5 分钟）

步骤 9：记录归档（2 分钟）

升级成功：在日常日志中记录版本变更及所应用的修复项。

升级失败：保存全部故障证据后执行回滚：

# 回滚前务必先采集证据
openclaw doctor 2>&1 > "$BACKUP_DIR/doctor-failed.txt"
journalctl --user -u openclaw-gateway -n 200 > "$BACKUP_DIR/gateway-logs-failed.txt" 2>&1
openclaw --version >> "$BACKUP_DIR/failure-info.txt"

回滚流程

# 1. 安装旧版本
npm install -g openclaw@

# 2. 恢复配置
cp "$BACKUP_DIR/openclaw.json" ~/.openclaw/openclaw.json
cp "$BACKUP_DIR/openclaw-gateway.service" ~/.config/systemd/user/

# 3. 重启服务
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service

# 4. 验证状态
openclaw --version
openclaw status

已知陷阱

提交 Bug 报告

若升级失败并需执行回滚，请在 github.com/openclaw/openclaw/issues 提交 Bug，并附带以下信息：

1. 操作系统、Node 版本、npm 版本
2. 升级路径（from → to）
3. 安装方式（npm 全局安装 / pnpm / 其他）
4. openclaw doctor 输出（升级前后各一份）
5. Gateway 日志（journalctl --user -u openclaw-gateway -n 200）
6. 可复现的操作步骤
7. 回滚是否成功