Upgrade Guard

Safe OpenClaw upgrade: backup before touching anything, verify before restarting, rollback if broken.

Why

OpenClaw strictly validates config. If a new version renames or removes a key, Gateway refuses to start. openclaw update installs the new version before checking config compatibility — if something breaks, you're stuck mid-migration. This adds the safety net that's missing: backup first, verify before restart, rollback if broken.

Three Modes

Default: cautious

Pre-flight (all modes)

Before any upgrade, check:

1. Config syntax: openclaw config get agents.defaults.workspace — if this fails, config is broken already
2. Legacy keys: openclaw doctor --non-interactive — scan for deprecated keys that will be migrated
3. Gateway health: openclaw health — confirm current state is good before changing anything
4. Version info: openclaw --version + node --version
5. Update check: openclaw update status --json

Backup

Always backup config before upgrading:

# Create timestamped backup
mkdir -p ~/.openclaw/upgrade-guard
ts=$(date +%Y%m%d-%H%M%S)
ver=$(openclaw --version 2>/dev/null | tr ' ' '_')
mkdir -p "$HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}"
cp ~/.openclaw/openclaw.json "$HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}/"
ln -sfn "$HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}" "$HOME/.openclaw/upgrade-guard/latest"
echo "Backup: $HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}"

Keep max 10 backups:

# Prune old backups (keep newest 10)
cd ~/.openclaw/upgrade-guard && ls -1d pre-* 2>/dev/null | sort | head -n -10 | xargs rm -rf 2>/dev/null; cd -

Upgrade: Cautious Mode

Step-by-step, verifying at each stage:

Step 1: Install new package only (no restart)

npm install --global openclaw@latest

Or for a specific version: npm install --global openclaw@2026.4.1

Step 2: Fix config with new version's doctor

openclaw doctor --fix --non-interactive

This runs the new version's doctor, which knows the new schema and migration rules.

Step 3: Verify config loads

openclaw config get agents.defaults.workspace

If this fails, do not restart. Restore backup instead:

cp ~/.openclaw/upgrade-guard/latest/openclaw.json ~/.openclaw/openclaw.json

Step 4: Restart Gateway

openclaw gateway restart

Step 5: Health check

openclaw health

Repeat every 5 seconds, up to 12 times (60s total). If Gateway doesn't become healthy, restore backup.

Upgrade: OpenClaw-Update Mode

Use the built-in flow with backup safety net:

1. Backup config (see above)
2. openclaw update --yes
3. After update completes, verify: openclaw health
4. If Gateway unhealthy → restore backup config and restart manually

Upgrade: Manual Mode

Just backup and pre-check. Print instructions, user handles the rest.

Rollback

# Restore config from latest backup
cp ~/.openclaw/upgrade-guard/latest/openclaw.json ~/.openclaw/openclaw.json
openclaw gateway restart

# Rollback to specific version
npm install --global openclaw@2026.4.1
openclaw doctor --fix --non-interactive
openclaw gateway restart

Known Config Migrations

Common breaking changes (all handled by doctor --fix):

Config Hot Reload

Most config changes apply without restart:

• Hot: channels, agents, models, hooks, cron, sessions, tools, skills
• Needs restart: gateway.* (port, bind, auth), discovery, plugins

After upgrade, gateway auto-restarts for critical changes (hybrid mode is default).

中文版

为什么需要

OpenClaw 对配置严格验证——新版本 schema 不认识旧字段，Gateway 直接拒绝启动。openclaw update 先升级再检查配置，出问题了你就卡在半中间。

Upgrade Guard 补了这个缺口：先备份 → 再升级 → 验证通过才重启 → 失败回滚。

三种模式

升级流程（Cautious 模式）

1. 备份

mkdir -p ~/.openclaw/upgrade-guard
ts=$(date +%Y%m%d-%H%M%S)
ver=$(openclaw --version 2>/dev/null | tr ' ' '_')
mkdir -p "$HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}"
cp ~/.openclaw/openclaw.json "$HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}/"
ln -sfn "$HOME/.openclaw/upgrade-guard/pre-${ts}-${ver}" "$HOME/.openclaw/upgrade-guard/latest"

2. 预检

openclaw config get agents.defaults.workspace  # 配置语法
openclaw doctor --non-interactive              # 遗留 key 扫描
openclaw health                                # Gateway 健康

3. 安装包（不重启）

npm install --global openclaw@latest

4. 修配置 + 验证

openclaw doctor --fix --non-interactive
openclaw config get agents.defaults.workspace   # 失败就恢复备份

5. 重启 + 健康检查

openclaw gateway restart
openclaw health   # 最多等 60 秒

回滚

cp ~/.openclaw/upgrade-guard/latest/openclaw.json ~/.openclaw/openclaw.json
openclaw gateway restart

常见配置迁移

适用场景

• ✅ npm/pnpm/bun 全局安装
• ✅ 很久没升级的、自定义配置多的
• ❌ Docker 部署（升级是换镜像）
• ❌ Git 源码安装（dev 用户走不同流程）