Post-Update Awareness

When OpenClaw is updated, the agent should not be the last to know. This skill reads the project CHANGELOG for the exact installed version, distills what changed for the user, and surfaces it once.

When to use

Run this skill when any of the following is true:

1. The user asks "what changed in this update?" or "what's new in OpenClaw?"
2. A first-class update flow finishes (openclaw update, openclaw plugins update, or a package-manager update).
3. openclaw -V returns a value different from the version recorded in the skill's state file.

Do not run on every heartbeat. Run once per detected version change, then persist the new version so subsequent heartbeats stay quiet.

Scope and non-goals

This skill only:

• Reads existing CHANGELOG content pinned to the installed version
• Reports it to the user
• Optionally probes for known-flaky optional native deps mentioned in the entry

This skill does not:

• Apply updates (openclaw update already handles that)
• Modify configuration
• Install missing dependencies without explicit user confirmation
• Roll back versions

Workflow

1) Read the current installed version

{ "tool": "exec", "command": "openclaw -V" }

Parse the version token (e.g. OpenClaw 2026.5.3-1 (2eae30e) → 2026.5.3-1).

2) Compare against the last-known version

The skill maintains a small JSON state file at ${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/state/post-update-awareness.json:

{ "lastKnownVersion": "2026.5.2", "lastSurfacedAt": "2026-05-04T13:15:00Z" }

• If the file does not exist → write the current version as the baseline and exit silently. (No CHANGELOG dump on first run; only on actual transitions.)
• If currentVersion === lastKnownVersion → exit silently.
• If currentVersion !== lastKnownVersion → continue.

3) Fetch the CHANGELOG entry pinned to the installed version

Always pin to the installed version, never read main. The release tag for OpenClaw matches the version with a v prefix.

Try in order:

1. Local install copy (fastest, offline-friendly): typical paths are platform-dependent. Try the directory of the npm install root first:

   {baseDir}/scripts/find-local-changelog.sh
   

   This script searches common install locations and prints the path if found.

2. Remote, pinned to tag:

   curl -fsSL "https://raw.githubusercontent.com/openclaw/openclaw/v<currentVersion>/CHANGELOG.md"
   

   The v prefix is required. If the remote 404s (e.g. a brand-new release tag hasn't propagated yet), retry once after 30 seconds before giving up.

3. Fallback (only if both above fail): query the GitHub Releases API for that exact tag:

   curl -fsSL "https://api.github.com/repos/openclaw/openclaw/releases/tags/v<currentVersion>"
   

   Use the body field as the changelog content.

If all three fail, surface a single line: "OpenClaw was updated to vX, but I couldn't fetch the changelog to summarize what changed." Do not invent content.

4) Extract the section for the new version

The CHANGELOG uses ## <version> as section headings. Extract only the section between ## <currentVersion> and the next ## heading. Do not dump the whole file.

If the section heading isn't found in the pinned changelog (rare — usually means the release tag exists but the changelog hasn't been updated for it), use the Unreleased section as a fallback only when the pinned-tag fetch came from main. When pinned to an actual release tag, prefer "no detailed notes available" over guessing.

5) Distill into 3 buckets

Group items into:

• 🆕 New for you — new tools, commands, channels, capabilities the agent could benefit from. Filter ruthlessly to what an end-user agent actually touches; skip internal refactor lines, build-system changes, and CI plumbing.
• ⚠️ Breaking or removed — anything that changes current behavior: removed config keys, renamed CLI commands, deprecated features, security tightenings.
• 🔧 May need attention — optional native dependencies (sharp, ffmpeg, node-pty, libvips, etc.), peer-dep notes, post-install scripts, config-format migrations.

Each bucket: 1–4 bullets max. Omit empty buckets entirely.

6) Probe known-flaky optional deps (best effort)

If the "May need attention" bucket mentions a known native module, probe non-blockingly:

{baseDir}/scripts/probe-optional-dep.sh sharp

The script returns OK, MISSING, or ERROR <msg>. Annotate findings inline in the surfaced summary as ❌ sharp (image processing) — not installed. Do not auto-install.

Default known list (extend as the project evolves):

• sharp — image attachment optimization
• ffmpeg-static / system ffmpeg — audio/video transcoding
• node-pty — terminal/PTY tools

7) Surface to the user

Send one brief message via the active channel.

OpenClaw updated to <newVersion> (was <oldVersion>).

🆕 New for you:
- <bullet>

⚠️ Breaking or removed:
- <bullet>

🔧 May need attention:
- ❌ sharp (image processing) — not installed; run: <install command>

Full notes: https://github.com/openclaw/openclaw/blob/v<newVersion>/CHANGELOG.md

Hard cap: ~15 lines. Drop empty sections. If everything is quiet:

OpenClaw updated to <newVersion>. Nothing in the changelog requires action on my end.

8) Persist new state

Write the new version + surfaced timestamp to the state file. Subsequent heartbeats stay silent unless the version changes again.

Voice

This is an operational notice, not a marketing email. Terse, factual, no celebratory language.

• ✅ "OpenClaw updated to 2026.5.3-1. New: agent can now use the talk realtime voice tool. Watch: optional sharp is not installed; some image replies will fall back to original-size send."
• ❌ "🎉 Exciting news! OpenClaw has been upgraded with brand-new features..."

Failure modes

Why this exists

OpenClaw releases are well-documented in CHANGELOG.md and per-version GitHub Releases, but the running agent has no built-in mechanism to consume that information after an update. Real-world consequence: when an update introduces a new optional native-dep requirement (e.g. sharp for image attachment optimization), the user discovers it only when an unrelated workflow fails.

This skill closes that loop using the existing CHANGELOG as source of truth, pinned to the installed version so the agent reads the changelog that matches what's actually running — not whatever has been merged since.