OpenClaw Upgrade Standard

A battle-tested upgrade procedure for OpenClaw, born from a real production failure where a Dashboard upgrade silently broke Gateway communication (Telegram, WebChat) with no clear error message.

Use this skill when: upgrading OpenClaw to a new version, planning a safe upgrade path, or recovering from a failed upgrade.

Why This Exists

In March 2026, a Dashboard-triggered upgrade from 2026.3.13 to 2026.3.22 caused:

- Silent Gateway failure (Telegram showed "typing" but never delivered)
Dashboard used pnpm which wasn't installed
Gateway entrypoint renamed (entry.js → index.js) without service file migration
INLINECODE3 fixed config but NOT the systemd service file
Required backup restore to recover

This procedure prevents all of these issues.

Golden Rule

NEVER upgrade via the Dashboard. Always use CLI.

Procedure

Step 1: Backup (2 min)

CODEBLOCK0

Step 2: Read Release Notes (5 min)

Check https://github.com/openclaw/openclaw/releases

Red flags to watch for:

- "Breaking" entries → config or plugin changes
Plugin SDK changes → can break Telegram/Discord
Entrypoint changes → service file needs update
Config/State migration → may invalidate existing config

Step 3: Doctor Baseline (1 min)

CODEBLOCK1

Step 4: Upgrade (3 min)

CODEBLOCK2

Step 5: Doctor Fix (2 min)

CODEBLOCK3

Step 6: Fix Service Entrypoint (1 min)

CODEBLOCK4

Step 7: Restart Gateway (1 min)

CODEBLOCK5

Step 8: Test (5 min)

Test	Command / Action	Expected
Gateway running	INLINECODE4	active (running)
Version correct

Step 9: Document (2 min)

Success: Note version change + any fixes applied in your daily log.

Failure: Save all evidence, then rollback:

CODEBLOCK6

Rollback Procedure

CODEBLOCK7

Known Pitfalls

Problem	Cause	Fix
Dashboard upgrade fails	Uses pnpm (not installed)	Always use INLINECODE8
Gateway won't start

Filing a Bug Report

If the upgrade fails and rollback is needed, file a bug at github.com/openclaw/openclaw/issues with:

1. OS, Node version, npm version
Upgrade path (from → to)
Install method (npm global / pnpm / other)
INLINECODE11 output (before and after)
Gateway logs (journalctl --user -u openclaw-gateway -n 200)
Steps to reproduce
Whether rollback succeeded

OpenClaw 升级标准

一套经过实战检验的 OpenClaw 升级流程，源于一次真实的生产故障：Dashboard 升级在没有任何明确错误信息的情况下，悄无声息地破坏了网关通信（Telegram、WebChat）。

使用此技能的场景： 将 OpenClaw 升级到新版本、规划安全的升级路径，或从失败的升级中恢复。

为何存在此流程

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

- 静默的网关故障（Telegram 显示正在输入但从未发送消息）
Dashboard 使用了未安装的 pnpm
网关入口点被重命名（entry.js → index.js），但服务文件未迁移
openclaw doctor --fix 修复了配置，但未修复 systemd 服务文件
需要恢复备份才能恢复运行

此流程可防止上述所有问题。

黄金法则

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

操作流程

步骤 1：备份（2 分钟）

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

配置 + 凭据 + 代理

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_DIR

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

查看 https://github.com/openclaw/openclaw/releases

需要警惕的红旗：

- Breaking 条目 → 配置或插件变更
插件 SDK 变更 → 可能破坏 Telegram/Discord
入口点变更 → 需要更新服务文件
配置/状态迁移 → 可能使现有配置失效

步骤 3：运行诊断基线（1 分钟）

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

步骤 4：升级（3 分钟）

bash

始终使用 npm，不要使用 pnpm 或 Dashboard

npm update -g openclaw

验证

openclaw --version

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

bash

检查需要迁移的内容

openclaw doctor

应用修复（配置模式变更、弃用项）

openclaw doctor --fix

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

bash

检查入口点是否仍然匹配

CURRENT_ENTRY=$(grep ExecStart ~/.config/systemd/user/openclaw-gateway.service | grep -oP dist/\K[^\ ]+)
ACTUALENTRY=$(ls ~/.npm-global/lib/nodemodules/openclaw/dist/index.js 2>/dev/null && echo index.js || echo entry.js)

if [ $CURRENTENTRY != $ACTUALENTRY ]; then
echo ⚠️ 入口点不匹配：服务=$CURRENTENTRY 实际=$ACTUALENTRY — 正在修复...
sed -i s|dist/$CURRENTENTRY|dist/$ACTUALENTRY|g ~/.config/systemd/user/openclaw-gateway.service
echo ✅ 已修复
else
echo ✅ 入口点正常
fi

步骤 7：重启网关（1 分钟）

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

步骤 8：测试（5 分钟）

测试项	命令/操作	预期结果
网关运行中	systemctl --user status openclaw-gateway	active (running)
版本正确

步骤 9：记录（2 分钟）

成功： 在每日日志中记录版本变更及应用的任何修复。

失败： 保存所有证据，然后回滚：

bash

在回滚前捕获证据

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

回滚流程

bash

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

已知陷阱

问题	原因	修复方法
Dashboard 升级失败	使用 pnpm（未安装）	始终使用 npm update -g openclaw
网关无法启动

提交错误报告

如果升级失败且需要回滚，请在 github.com/openclaw/openclaw/issues 提交错误，并附上以下信息：

1. 操作系统、Node 版本、npm 版本
升级路径（从 → 到）
安装方法（npm 全局 / pnpm / 其他）
openclaw doctor 输出（升级前后）
网关日志（journalctl --user -u openclaw-gateway -n 200）
复现步骤
回滚是否成功

openclaw-upgrade-standardOpenClaw安全升级