Upgrade Guard

Safe OpenClaw upgrade workflow with pre-flight config check, automatic backup, post-upgrade migration, and rollback. Three modes: cautious (install first, ve...

Security Scan

The skill is an instruction-only upgrade checklist for OpenClaw that is internally consistent with its stated purpose — it only tells the operator to back up, run OpenClaw CLI checks, install/repair, verify, and roll back if needed.

Purpose & Capability

Name/description match the actions in SKILL.md: pre-flight checks, backup, npm/global install of openclaw, doctor --fix, health checks, and rollback of ~/.openclaw/openclaw.json. All requested actions are coherent for an upgrade guard.

Instruction Scope

Instructions reference and modify the user's OpenClaw config (~/.openclaw/openclaw.json), run global npm installs, run openclaw CLI commands (doctor, update, health), and prune backups with rm -rf via xargs. These operations are expected for an upgrade workflow but are potentially destructive if misused — the skill does not attempt to read unrelated system files or exfiltrate data.

Install Mechanism

No install spec or embedded code — instruction-only. No downloads or archive extraction. Low installer risk.

Credentials

The skill requests no environment variables, no external credentials, and only uses standard CLI tools and the user's home config path (~/.openclaw). Required access is proportionate to the described purpose.

Persistence & Privilege

always is false and model invocation is not disabled. The skill is instruction-only and does not request persistent elevated privileges or modify other skills or global agent configuration.

Assessment

This skill is a guidance checklist (not code) and appears coherent for upgrading OpenClaw, but consider these practical cautions before following it: - Back up before you run anything (the skill already instructs backups). Verify the backup exists and is readable. - openclaw doctor --fix will modify your config automatically; prefer running doctor --non-interactive first to see proposed changes, or test in a staging environment. - npm install --global modifies your system global packages and may require elevated permissions; avoid running as root unless you understand consequences. - The backup-prune step uses ls | xargs rm -rf scoped to ~/.openclaw/upgrade-guard — double-check the path before running to avoid accidental deletion. - If you deploy OpenClaw in Docker, multiple instances, or via immutable images, follow your platform-specific upgrade process instead (the SKILL explicitly notes Docker and multi-instance are not supported). - Because this is instruction-only, nothing runs automatically from the skill itself — an operator must execute the commands. Review and, if desired, run each command manually or in a safe test environment to confirm behavior. If you want extra safety, snapshot the host/VM or take a filesystem-level backup before performing global installs or restarts.

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

Mode	Flow	Best for
cautious	install package → fix config → verify → restart	large version jumps, custom configs
openclaw-update	openclaw update → verify health → rollback if needed	routine updates
manual	backup + pre-check only	you handle the upgrade yourself

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):

Legacy	New
routing.*	channels.* / messages.* / bindings
agent.*	agents.defaults.* / tools.*
messages.tts.openai	messages.tts.providers.openai
talk.voiceId etc	talk.provider + talk.providers.*
identity (root)	agents.list[].identity
browser.driver: "extension"	browser.driver: "existing-session"

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（默认）	安装包 → 修配置 → 验证 → 重启	大版本升级、自定义配置
openclaw-update	openclaw update → 验证健康 → 需要时回滚	日常小版本升级
manual	只备份+预检	自己完全控制升级过程

升级流程（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

常见配置迁移

旧字段	新字段
routing.*	channels.* / messages.*
agent.*	agents.defaults.* / tools.*
talk.voiceId 等	talk.provider + talk.providers.*
identity（根级）	agents.list[].identity

适用场景

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