Upgrade Openclaw

Upgrade OpenClaw

Update, diff, audit, propose. Every new feature surfaced. Nothing missed.

Settings

On first run, check settings.json in this skill's directory. If subagentModel not set, ask:

> "Which model for upgrade sub-agents? (e.g., claude-sonnet-4-6, deepseek-chat). Note: external providers will receive config data."

Save to settings.json:

{ "subagentModel": "anthropic/claude-sonnet-4-6" }

Procedure

1. Record Pre-Update State

Before touching anything:

PRE_VERSION=$(openclaw --version | grep -oP '\d{4}\.\d+\.\d+')
echo "$PRE_VERSION"

Save PRE_VERSION — needed for changelog diffing in Step 3.

2. Run Update

openclaw update

If dirty working tree, stash first:

cd "$(openclaw --version 2>&1 | grep -oP '(?<=\().*?(?=\))' || echo ~/openclaw)" 
git stash --include-untracked -m "pre-update stash" && openclaw update

Record new version:

POST_VERSION=$(openclaw --version | grep -oP '\d{4}\.\d+\.\d+')

If PRE_VERSION == POST_VERSION, report "Already up to date" and skip to Step 5 (audit only).

3. Extract Delta Changelog

The changelog lives locally at ~/openclaw/CHANGELOG.md after update. Versions delimited by ## YYYY.x.x headers.

Extract only entries between old and new version:

awk "/^## $POST_VERSION/,/^## $PRE_VERSION/" ~/openclaw/CHANGELOG.md

Then filter by relevance to this setup:

1. Read current config via gateway config.get to identify enabled channels/plugins 2. From the changelog delta, keep entries matching: - Enabled channels (e.g., Telegram — skip LINE/Discord/Feishu/etc. unless enabled) - Core agent/gateway/cron/tools/memory/security changes (always relevant) - ACP/sessions/subagent changes (if ACP enabled) - Breaking changes (always relevant) 3. Discard entries for disabled channels, iOS/macOS app changes, and platforms not in use 4. Categorize kept entries into: Features | Fixes | Security | Breaking Changes

4. Config Schema Gap Analysis

Fetch the live schema and current config:

Compare systematically:

1. Walk schema properties tree recursively 2. For each schema key path, check if it exists in current config 3. New/unset options = schema keys not present in current config (excluding keys with sensible defaults) 4. Focus on actionable fields — ones where setting a non-default value provides clear benefit 5. Flag fields from the changelog delta (new in this version) separately as "New in this release"

Present as a table:

| Config Path | Type | Default | Description | New? |

5. Audit Current Setup

openclaw hooks list --json
openclaw doctor --non-interactive
clawhub update --all --dry-run 2>&1

Collect:

6. Present Comprehensive Report

Structure the report exactly like this:

## 🔍 Post-Upgrade Report: {PRE_VERSION} → {POST_VERSION}
🆕 New Features (Relevant to Your Setup)
[Feature]: What it does, why it matters for you
  - Config: path.to.setting (if applicable)
🔧 Notable Fixes
[Fix]: What was broken, now fixed
🔐 Security Updates
[Security]: What was patched
⚠️ Breaking Changes
[Breaking]: What changed, migration needed
📋 New Config Options Available
| Config Path | Type | Default | Why Enable |
|-------------|------|---------|------------|
🪝 Hooks Status
[hook]: enabled/available/new
🏥 Doctor Recommendations
[Item]: severity + action
📦 Skill Updates Available
[skill]: current → available version

Apply these improvements? Reply with:
"yes" / "all" — apply everything
"select" — I'll list numbered items to pick from
specific items by name

Critical: Do NOT present a thin report. Every changelog entry that survived the relevance filter in Step 3 MUST appear. Every new config option from Step 4 MUST appear. Every doctor finding from Step 5 MUST appear. The user triggered this skill to see EVERYTHING.

7. Apply with Approval

Never apply without explicit user approval.

On approval, apply changes via:

After applying, pop any git stash:

cd ~/openclaw && git stash list | grep -q "pre-update stash" && git stash pop

8. Persist State

Write upgrade state to state.json in this skill's directory:

{
  "lastUpgrade": {
    "from": "2026.3.2",
    "to": "2026.3.3",
    "timestamp": "2026-03-05T06:50:00Z",
    "featuresProposed": ["telegram-streaming", "pdf-tool", ...],
    "featuresApplied": ["telegram-streaming", ...],
    "doctorApplied": ["entrypoint-fix", ...]
  }
}

This prevents re-proposing on repeated runs and enables "what changed since last upgrade" queries.

On first run, check settings.json in this skill's directory. If subagentModel not set, ask:

> "Which model for upgrade sub-agents? (e.g., claude-sonnet-4-6, deepseek-chat). Note: external providers will receive config data."

Save to settings.json:

{ "subagentModel": "anthropic/claude-sonnet-4-6" }