Smart Updater

intent

smart updater handles version checking and upgrade approval for openclaw core, extensions, and skills across npm, clawhub, skiphub, and github sources. run this when the user asks to check for updates (检查升级), list what's installed (装了什么), upgrade a specific asset, or mentions update/upgrade/版本/新版本 keywords. the skill scans your inventory, fetches changelogs from each source, assigns risk levels, presents findings for user approval, then executes approved upgrades using the three gates safety framework. principle: never upgrade without user confirmation and verified changelog evidence (宁可不升,不可升坏).

inputs

local context:

• ~/.openclaw/workspace/skills/smart-updater/scripts/inventory.sh , executable script that scans installed assets
• ~/.openclaw/workspace/skills/smart-updater/scripts/scan.sh , executable script that checks each asset for updates
• references/report-format.md , template for final report (read in phase 5 only)
• references/three-gates.md , detailed gate definitions and rollback procedures

external sources and credentials:

• npm registry , requires network access to registry.npmjs.org or configured npm registry; no auth needed for public packages; set NPM_TOKEN env var if using private packages (scope: read)
• clawhub api , reads from clawhub.openclaw.io; env var CLAWHUB_API_KEY optional but recommended (scope: skill metadata, version history); rate limit 1000 req/min per IP
• skiphub (腾讯国内镜像) , reads from skiphub.openclaw.io for batch version checks; no auth required; no per-request rate limit
• github , for github-cloned skills and extensions; optional GITHUB_TOKEN env var (scope: read public repos); rate limit 60 req/hour unauthenticated, 5000 req/hour authenticated
• git cli , must be installed locally for git log commands on cloned repos

output directories (auto-created if missing):

• ~/.openclaw/inventory.json , phase 1 output
• ~/.openclaw/scan-result.json , phase 2 output
• ~/.openclaw/skill-backups/ , backup location for skill upgrades
• ~/.openclaw/extensions-backup/ , backup location for extension upgrades
• ~/.openclaw/plist-backup/ , gateway plist backup for core upgrades

edge cases to prepare for:

• network timeout on any external source (clawhub, npm, github, skiphub) , fallback to "changelog unavailable"
• auth token expiry during execution , retry once, then flag for manual review
• empty inventory (no assets installed) , report as "nothing to check" and exit
• rate limit hit on npm or github , add exponential backoff (2s, 4s, 8s) then flag as "unavailable"
• missing references/report-format.md or references/three-gates.md , fail phase 5 or phase 6 with "config missing" error

procedure

phase 1: inventory scan

1. input: none (scans local filesystem)
2. run: bash ~/.openclaw/workspace/skills/smart-updater/scripts/inventory.sh
3. output: ~/.openclaw/inventory.json with asset array
4. asset structure per entry:
   • type: one of core/npm, extension/npm, extension/local, extension/github, skill/clawhub, skill/github, skill/local, builtin/bundled
   • name: asset name or package name
   • version: currently installed version (semver)
   • source: url or local path
   • location: filesystem path
5. exit check: file exists and assets array is non-empty (or empty if intentional "nothing installed")
6. output format: valid json, readable by subsequent phases

phase 2: version scan

1. input: ~/.openclaw/inventory.json from phase 1
2. run: bash ~/.openclaw/workspace/skills/smart-updater/scripts/scan.sh
3. output: ~/.openclaw/scan-result.json with updates array
4. scan behavior per asset type:
   • core/npm: query npm registry for latest version
   • extension/npm: query npm registry for latest version
   • skill/clawhub: check clawhub api first (fast path if in skiphub top-50), else fallback to clawhub inspect; include inSkillHub flag in result
   • skill/github: run cd <location> && git ls-remote --tags origin to find latest release tag
   • skill/local, extension/local, builtin/bundled: mark as "not trackable" (skip)
5. update entry structure:
   • name, current, latest, type, source
   • changelogUrl (if detected from source)
   • inSkillHub (boolean, for clawhub skills)
   • skipped_reason (for non-trackable types)
6. exit check: file exists and updates array is present (may be empty)
7. if updates array is empty: skip to outcome signal, report "all up to date", halt further phases

phase 3: changelog fetch and summarize

1. input: ~/.openclaw/scan-result.json with each update candidate

2. for each update in the array, fetch changelog using source-specific method:

   clawhub skills:

   • command: clawhub inspect <slug> --versions --limit 5
   • parse output for version range between current and latest
   • extract breaking changes, features, bugfixes
   • fallback: if command fails or times out (>5s), record "changelog unavailable: clawhub inspect timeout"

   npm packages:

   • command: npm info <package> --json
   • parse versions object to extract entries between current and latest
   • if repository field exists, fetch github releases from that url
   • github releases: curl -s https://api.github.com/repos/<owner>/<repo>/releases | jq
   • fallback: if npm lookup or github fetch fails, record "changelog unavailable: npm info failed" or "changelog unavailable: github api timeout"

   github-cloned skills/extensions:

   • command: cd <location> && git log --oneline HEAD..origin/main --max-count=20
   • extract commit messages as changelog summary
   • fallback: if git command fails or repo has no upstream, record "changelog unavailable: git log failed or no upstream"

3. per update, record:

   • changelog_summary: one-line text describing key changes (e.g. "bugfixes in parser, improved error handling")
   • changelog_source: url (github releases, npm, etc) or command used
   • breaking_changes: array of breaking items or empty array
   • changelog_status: "available" or "unavailable"
   • fetch_error: (if status is unavailable) reason string

4. exit check: every update entry has changelog summary or explicit "unavailable" note with reason. do not proceed until all entries are populated.

phase 4: risk assessment

1. input: ~/.openclaw/scan-result.json enriched from phase 3

2. assign risk level to each update using this matrix:

   condition	risk level	recommendation
   patch version bump + bugfix only	🟢 low	recommend upgrade
   minor version bump + feature (no breaking)	🟡 medium	suggest upgrade
   major version bump + breaking change declared	🔴 high	require explicit user confirmation
   extension type (any version)	🟡+ medium-high	always require full gate 2 flow + user confirmation
   changelog unavailable	🟠 unknown	flag for manual review, suggest user vets manually
   new executable scripts in upgrade	🟠+ unknown-high	suggest running skill-vetter before upgrade
   name conflict (same name, different source)	🔴 high	block upgrade in gate 1

3. per update, record:

   • risk_level: one of "low", "medium", "high", "unknown"
   • risk_reason: string explaining why (e.g. "major + breaking changes", "changelog unavailable")
   • action: one of "recommend", "suggest", "confirm", "block", "manual_review"

4. exit check: every update has risk_level and action assigned.

phase 5: generate final report

1. input: phase 1, 2, 3, 4 outputs all complete and valid
2. pre-report gate: verify all of the following are true:
   • every update has changelog_summary or "unavailable" note
   • every update has risk_level assigned
   • every update has changelog_source or command
   • no "BLOCKED" state from previous phases
   • if any check fails: output BLOCKED: <missing item list> and stop. do not generate report.
3. read: references/report-format.md template
4. generate report containing:
   • asset inventory summary (count by type)
   • upgrade candidates list with version ranges
   • per-update: changelog summary, breaking changes, risk level, recommended action
   • grouped by risk level (low, medium, high, unknown)
   • footer with instructions for phase 6
5. output: formatted report to stdout and (optional) write to ~/.openclaw/upgrade-report.txt
6. exit check: report is readable and contains no placeholder text

phase 6: wait for user approval and selection

1. input: report from phase 5 (presented to user)
2. action: present report and pause. do not auto-upgrade. do not proceed without explicit user selection.
3. user selects: which updates to apply (e.g. "upgrade skill-a, skill-b, core")
4. input to phase 7: user's selected upgrade list
5. output: user's approval signal (e.g. "proceed with X upgrades")

phase 7: execute approved upgrades sequentially (three gates)

1. for each user-selected update, execute in order (do not parallelize):

   announce: "upgrading from to "

   gate 1: pre-flight checks:

   • confirm source is tracked and healthy
   • confirm no name conflict with existing assets
   • if type is extension: confirm gateway is healthy
   • if type is extension/local or skill/local: block upgrade (local assets cannot be auto-upgraded)
   • if any check fails: output "gate 1 failed: ", skip this upgrade, continue to next

   gate 2: isolation and backup:

   • create backup snapshot before any modification (location: ~/.openclaw/skill-backups/ or ~/.openclaw/extensions-backup/)
   • if extension type: clear jiti cache for that extension
   • if core type: backup plist config to ~/.openclaw/plist-backup/
   • preserve existing config files
   • execute upgrade command (npm install, git pull, clawhub download, etc)
   • if any step fails: output "gate 2 failed: ", restore from backup snapshot, skip this upgrade, continue to next

   gate 3: post-flight verification:

   • verify new version matches expected latest from scan
   • verify file count or manifest (did files arrive?)
   • validate provenance (if available, e.g. sha256 checksum)
   • if any check fails: output "gate 3 failed: ", restore from backup snapshot, continue to next

   on all gates pass: output "✅ upgraded from to "

2. rollback on any gate failure:

   • restore from backup snapshot created in gate 2
   • notify user: "rolled back due to gate failure"
   • do not halt; continue to next upgrade

3. final output: summary of successful upgrades, failed upgrades, and rollbacks

decision points

after phase 2 scan completes:

• if updates array is empty: output "all assets are up to date" and stop. do not proceed to phase 3.
• if updates array has entries: proceed to phase 3 (changelog fetch).

after phase 3 changelog fetch:

• if any update is missing changelog summary or "unavailable" note: do not proceed to phase 4. output "phase 3 incomplete: entries missing changelog data". halt until changelog data is supplied.
• if all updates have changelog data: proceed to phase 4 (risk assessment).

before phase 5 report generation:

• if inventory file does not exist: output "phase 1 incomplete, halt".
• if scan result file does not exist: output "phase 2 incomplete, halt".
• if any update lacks risk level: output "phase 4 incomplete, halt".
• if references/report-format.md is missing: output "config missing: report-format.md not found, halt".
• if any of the above: do not generate report. output BLOCKED: <missing items> and stop.
• if all conditions pass: proceed to report generation.

in phase 6 (wait for user approval):

• if user selects "upgrade all": execute all non-blocked updates in phase 7.
• if user selects a subset: execute only those in phase 7.
• if user selects "none" or closes: output "no upgrades selected, exiting" and stop.
• if user does not respond within timeout (suggest 5 min): output "user approval timeout, exiting" and stop.

in phase 7 (gate 1 execution):

• if type is extension/local or skill/local: block upgrade, output "local assets cannot be auto-upgraded, manual action required".
• if asset source is not tracked (missing from inventory): block upgrade, output "gate 1 failed: source not tracked".
• if name conflict detected (same name, different source already installed): block upgrade, output "gate 1 failed: name conflict".
• if type is extension and gateway health check fails: block upgrade, output "gate 1 failed: gateway unhealthy".

in phase 7 (gate 2 execution):

• if backup fails: do not proceed to upgrade command. output "gate 2 failed: backup failed", skip this upgrade.
• if upgrade command times out (>30s): kill process, restore backup, output "gate 2 failed: upgrade timeout", skip this upgrade.
• if upgrade command exits with non-zero code: restore backup, output "gate 2 failed: ", skip this upgrade.

in phase 7 (gate 3 execution):

• if version mismatch (installed version does not match expected latest): restore backup, output "gate 3 failed: version mismatch", skip this upgrade.
• if file count dropped significantly (>20% fewer files than expected): restore backup, output "gate 3 failed: file integrity check failed", skip this upgrade.
• if provenance validation fails (e.g. sha256 mismatch): restore backup, output "gate 3 failed: provenance validation failed", skip this upgrade.

on network errors (any phase):

• if timeout on npm, clawhub, github, or skiphub: retry once with 2s exponential backoff.
• if retry fails: record "changelog unavailable: timeout" or "scan failed: unreachable".
• if all sources timeout during phase 2: output "scan failed: all sources unreachable", halt.

output contract

phase 1 output:

• file: ~/.openclaw/inventory.json
• format: json with schema: { "assets": [ { "type": string, "name": string, "version": string, "source": string, "location": string }, ... ] }
• valid if: file exists, valid json, assets array is present (may be empty)

phase 2 output:

• file: ~/.openclaw/scan-result.json
• format: json with schema: { "updates": [ { "name": string, "current": string, "latest": string, "type": string, "source": string, "changelogUrl": string?, "inSkillHub": boolean?, "skipped_reason": string? }, ... ], "timestamp": string }
• valid if: file exists, valid json, updates array is present (may be empty)

phase 3 output (in-memory enrichment to scan-result.json):

• add to each update: changelog_summary, changelog_source, breaking_changes (array), changelog_status, fetch_error (if unavailable)
• valid if: every update has these fields populated

phase 4 output (in-memory enrichment to scan-result.json):

• add to each update: risk_level (one of "low", "medium", "high", "unknown"), risk_reason, action
• valid if: every update has these fields populated

phase 5 output:

• file: ~/.openclaw/upgrade-report.txt (optional stdout also)
• format: human-readable text following references/report-format.md template
• sections: summary (count by type), updates grouped by risk level, changelog per update, recommended actions
• valid if: no placeholder text, all updates from scan-result represented, user-actionable instructions included

phase 7 output:

• stdout: per-upgrade execution log with gate status (pass/fail), rollback notifications
• files: backup snapshots in ~/.openclaw/skill-backups/, ~/.openclaw/extensions-backup/, ~/.openclaw/plist-backup/ (kept on disk for manual recovery)
• summary: "✅ X upgraded, 🔴 Y failed, 🔄 Z rolled back"

overall execution contract: a final report is invalid unless all of the following are true:

• ~/.openclaw/inventory.json exists (phase 1 complete)
• ~/.openclaw/scan-result.json exists and is enriched with phase 3 and 4 fields (phase 2, 3, 4 complete)
• every update candidate has a changelog summary or explicit "unavailable" note with source attempted (phase 3 satisfied)
• every update candidate has a risk level and action (phase 4 satisfied)
• no "BLOCKED" or "incomplete" errors from pre-report gate (phase 5 gate satisfied)

if any condition is not met, output BLOCKED: <missing items> with the specific missing items listed. do not generate the report.

never do this:

• never generate report before changelog fetch (phase 3 must complete first).
• never infer or invent changelog contents. fetch from source or record "unavailable".
• never present updates to user without changelog evidence (summary + source).
• never skip an update candidate in report because its changelog was hard to find. flag it as "unavailable" with reason.
• never auto-upgrade without phase 6 user approval. always wait for explicit selection.
• never execute gate 2 upgrade without gate 1 passing first.
• never skip gate 3 verification. always verify version, file count, provenance.
• never delete backups until user confirms upgrade success (wait at least 1 hour).

outcome signal

when the skill worked:

• all phases 1-4 completed without "BLOCKED" or "incomplete" errors
• phase 5 report generated and presented to user with all updates listed, changelog evidence included, and risk levels assigned
• user received clear instructions on which upgrades to select
• phase 6 received explicit user approval and selection
• phase 7 executed each selected upgrade and reported gate pass/fail status
• final summary shows count of successful upgrades and any rollbacks

user knows it worked when:

• stdout displays: "✅ inventory scan complete: N assets found"
• stdout displays: "✅ version scan complete: M updates available"
• stdout displays: "✅ changelog fetch complete: all M updates documented"
• stdout displays: "✅ risk assessment complete: <count low, count medium, count high, count unknown>"
• report is displayed with human-readable table of upgrades grouped by risk level
• user selects upgrades and sees: "proceeding with X upgrades..."
• each upgrade outputs: "upgrading v → v" followed by gate 1/2/3 status
• final log shows: "✅ 5 upgraded, 0 failed, 0 rolled back"
• version verification: user can run inventory scan again and confirm installed versions match latest

failure signals (user knows it did not work):

• phase 1 exits with "inventory scan failed: "
• phase 2 exits with "scan failed: all sources unreachable"
• phase 3 outputs "phase 3 incomplete: X updates missing changelog data"
• phase 5 outputs "BLOCKED: "
• phase 7 outputs "🔴 failed: gate X failed: " with rollback confirmation
• final log shows "0 upgraded, X failed" with no successful upgrades

---

original author: clawhub / openclaw team