Update Advisor

OpenClaw update check and upgrade assistant. Triggers on phrases like "check for updates", "any new version", "is openclaw updated", "run the update", "confi...

Security Scan

The skill's requests, scripts, and runtime instructions are consistent with its stated purpose (safe update checks and an optional watchdog-assisted update); nothing appears to request unrelated credentials or hidden network exfiltration.

Purpose & Capability

Name/description (update checking + guarded execution) aligns with the actual requirements and actions: it needs openclaw, python3, and npm; it reads local CHANGELOG.md and may call 'npm view' as a fallback; scripts perform changelog parsing, doctor checks, and optional recovery arming — all directly related to updating OpenClaw.

Instruction Scope

SKILL.md confines actions to Check mode (read/report only) and Execute mode (explicit user-confirmed openclaw update + user-level watchdog). It documents MEMORY.md as optional read-only and requires explicit user consent before reading it. Script steps reference only expected files/commands (CHANGELOG, openclaw update status, launchd/systemd), and do not instruct arbitrary file exfiltration or calls to unexpected external endpoints.

Install Mechanism

No install spec (instruction-only). All code is bundled in the skill directory and executed locally; there are no downloads from external URLs or registry installs. This minimizes install-time risk and matches the stated architecture.

Credentials

The skill requires no secrets or cloud credentials. The only network lookup (npm view openclaw version) is documented and justified as a fallback. Scripts accept optional environment overrides (OPENCLAW_BIN, WATCHDOG_BACKEND, etc.) for testing and portability, which is reasonable and declared.

Persistence & Privilege

The skill does create temporary user-level launchd/systemd jobs during Execute mode to arm a recovery watchdog — this is necessary for its recovery behavior but is a persistent side effect while the watchdog runs. always:false and explicit user confirmation gating are present; verify you want the skill to create/clean up user-level service units before granting Execute permission.

Assessment

This skill appears to do exactly what it claims: run local checks and, with explicit confirmation, perform an OpenClaw update protected by a user-level recovery watchdog. Before using: (1) run Check mode first to review the changelog analysis and doctor output; (2) confirm you are comfortable letting the skill create a temporary user-level launchd/systemd job to monitor and, if needed, run 'openclaw gateway install' — the job is created under your user and cleaned up after recovery; (3) ensure openclaw, python3, and npm are installed locally; (4) only allow MEMORY.md reads if you explicitly consent to personalized relevance analysis. Review the bundled scripts (they are included and well-tested) if you want to audit exact behavior; there are no hidden network endpoints or undeclared credential usage.

Helps you safely check for and apply OpenClaw updates, with changelog analysis, risk rating, and a Gateway-independent recovery watchdog path for Execute mode (macOS launchd or Linux systemd).

Requirements and security disclosure

• openclaw — the CLI being updated
• npm — fallback for npm view openclaw version when OpenClaw update metadata is unavailable
• python3 — used by the changelog parsing scripts and arming helper
• Execute recovery arming requires macOS launchctl + plutil, or Linux systemd-run + systemctl --user

Security boundaries:

• Check mode is read/report only. It runs local version/changelog/doctor checks and does not modify OpenClaw state.
• The only routine network lookup is npm view openclaw version when OpenClaw's own update metadata is unavailable.
• MEMORY.md is optional read-only context. Use already-loaded session context when available; read MEMORY.md only after the user explicitly asks for personalized relevance analysis or consents to that read. Never write to MEMORY.md during Check mode.
• Execute mode has persistent side effects (openclaw update and a temporary user-level launchd/systemd recovery job). Start it only after explicit user confirmation and after the dry-run/ownership/watchdog gates pass.
• The watchdog writes temporary state/log files under the selected state directory and must be cleaned up after recovery. It does not read secrets or send data to third-party endpoints.

Implementation architecture

This skill has two distinct implementation layers:

• Check mode is implemented by bundled shell/Python scripts (scripts/check-update.sh, parse_changelog.py, assemble_result.py). These are the only files the agent executes directly. They run locally, make no network calls beyond npm view openclaw version, and produce structured JSON output.

• Execute mode (v2, preferred) uses an external, mock-tested watchdog script (scripts/recovery-watchdog.sh) launched before openclaw update, so recovery does not depend on Gateway/cron/session survival. The arming helper supports macOS launchd and Linux systemd user units; unsupported OS/backend combinations must stop before update. The launchd plist template is inert documentation; the helper renders per-run jobs.

• Optional MEMORY.md access in Check mode is read-only and scoped to annotating changelog relevance against the user's known configuration (channels, installed Skills, cron jobs). Prefer already-loaded session context. Read MEMORY.md only when the user explicitly asks for personalized relevance analysis or consents to that read. Check mode never writes to MEMORY.md; any logging happens only after Execute mode and only at the user's explicit request.

All actions that have persistent side effects (openclaw update, watchdog launch/job registration) require explicit user confirmation via the trigger detection flow before the agent proceeds.

Resolving the skill directory

This skill's scripts live in the scripts/ subdirectory next to this SKILL.md file.

To locate the workspace root at runtime, run:

openclaw config get workspace 2>/dev/null || echo "$HOME/.openclaw/workspace"

The full script path is then: <workspace>/skills/update-advisor/scripts/check-update.sh

Store the workspace root in a variable when preparing watchdog/log paths or optional post-recovery reporting commands.

---

Trigger Detection

• Contains "check", "any new", "updated?", "检查更新", "有没有新版本", "更新了吗" → Check mode (analyze only, do not update)
• Contains "execute update", "confirm update", "upgrade", "升级", "确认更新", "执行更新" → Execute mode (perform update)
• If the immediately preceding turn was a Check mode report (Step 4 output), treat affirmative replies ("yes", "go ahead", "do it", "yeah", "sure", "ok", "好", "可以") as Execute mode triggers.

When in doubt, default to Check mode — never run the update without explicit user confirmation.

---

Check Mode

Step 1: Run the check script

bash <workspace>/skills/update-advisor/scripts/check-update.sh

Store the JSON output as CHECK_RESULT.

Step 2: Parse result

If has_update = false or same_version = true or already_latest = true:

Already on the latest version ({current_version}). If doctor_ok is false, surface the doctor issues. Done.

If changelog_not_found = true or changelog_empty = true:

Mention that the CHANGELOG could not be located (or was empty), but the version comparison still works. Continue to Step 3.

If has_update = true, continue to Step 3.

Step 3: Changelog analysis

Read fields from CHECK_RESULT and analyze along these dimensions.

Key fields available: current_version, latest_version, has_update, flagged_items, flagged_count, changelog_delta, doctor_ok, doctor_exit_code, doctor_issues, update_meta, latest_not_local, changelog_not_found, changelog_empty, rollback_dry_run_cmd, rollback_execute_cmd.

A. Risk rating (based on flagged_items + changelog_delta)

Check each flagged_items entry against the user's active configuration. Prefer already-loaded session context; read MEMORY.md only if the user explicitly asked for personalized relevance analysis or consents to that read:

• config / schema changes → check if it affects any configured integrations
• security / harden → usually good; mark green
• deprecated / removed → check if the user is using that feature
• behavior change → assess scope of impact

Risk level output:

• 🔴 High: breaking change or directly affects an actively used feature
• 🟡 Medium: config migration suggested, core function unaffected
• 🟢 Low: bug fixes and security hardening only

B. Relevance to user's environment

If personalized context is available or the user consented to reading MEMORY.md, use the user's active configuration — channels, installed Skills, cron jobs, running services, active integrations — and annotate each relevant changelog entry with "relevant to your setup" plus a brief explanation.

If no configuration context is available (fresh install, empty MEMORY.md), skip the relevance annotation and note: "Personalized relevance analysis requires prior session context in MEMORY.md."

C. New feature opportunities

Scan the delta text for new features (look for ### Changes, ### New, ### Added headings, or any changelog block lines describing new behavior) and classify:

• ✅ Recommend enabling (low config cost, immediately useful)
• 👀 Worth watching (valuable but needs testing)
• ⏭️ Skip (not relevant to this setup)

Special case: latest_not_local = true

The local CHANGELOG does not yet contain the new version (it's only available after installation). In this case:

1. Explain: "The new version's changelog is only available after installation."
2. Show update_status output as the available install info.
3. If the full changelog was fetched in this session via another method (e.g. npm view openclaw, GitHub raw), use that analysis directly.
4. Suggest: "Run the check again after updating to get the full changelog analysis."

Step 4: Output decision report

## OpenClaw Update Report
**Current**: x.x.x → **Latest**: x.x.x
**Risk**: 🟢 / 🟡 / 🔴

### High-risk items (if any)
- ...

### Relevant to your setup
- ...

### New feature suggestions
- ...

### Doctor status
✅ OK / ⚠️ Issues or fix suggestions: ...

**Manual rollback candidate** (if needed): first preview with `openclaw update --dry-run --tag x.x.x`; only execute a rollback after a separate explicit confirmation.

---
Ready to update? (Reply "confirm update" or "execute update")

---

Execute Mode

When the user explicitly says "execute update" / "confirm update" / "upgrade":

⚠️ Required explicit confirmation for recovery side effects

Before any persistent action, tell the user this mode can launch a temporary watchdog process/job and may run bounded openclaw gateway install attempts if Gateway stays unhealthy. Proceed only after explicit confirmation.

Step 0: Installation ownership check (critical — prevents duplicate installs)

OC_PATH=$(which openclaw)
OC_REAL=$(python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$OC_PATH" 2>/dev/null || echo "$OC_PATH")
UPDATE_ROOT=$(openclaw update status --json 2>/dev/null | python3 -c 'import json,sys
try:
    print(json.load(sys.stdin).get("update",{}).get("root","") or "")
except Exception:
    print("")')
STAT_TARGET="${UPDATE_ROOT:-$OC_REAL}"
OC_OWNER=$(stat -f '%Su' "$STAT_TARGET" 2>/dev/null || stat -c '%U' "$STAT_TARGET" 2>/dev/null || echo "unknown")
CURRENT_USER=$(whoami)
echo "path: $OC_PATH | realpath: $OC_REAL | update_root: $UPDATE_ROOT | owner: $OC_OWNER | current user: $CURRENT_USER"

Scenario	Criteria	Action
Different user owns the install	owner ≠ current user	❌ Stop. Tell the user running update would create a duplicate copy; ask the owner to remove old install first.
Owner unknown	owner = unknown	❌ Stop. Ask the user to run ownership check locally and paste results.
Current user owns the install	owner = current user	✅ Proceed

Step 0b: Confirm target version and dry-run

openclaw update status --json
openclaw update --dry-run --json

If dry-run fails, target is unclear, or downgrade risk exists without separate explicit confirmation, stop.

Step 1: Arm recovery watchdog BEFORE update (Gateway-independent)

Primary requirement: a Gateway-independent parent must be armed and verified before openclaw update. The bundled helper auto-selects a backend: macOS uses launchd (launchctl print verification), Linux uses a systemd user unit (systemctl --user show verification). If no supported backend is available, stop and do not update.

SKILL_DIR="<path-to-update-advisor-skill>"
WATCHDOG_STATE_DIR="${TMPDIR:-/tmp}/update-advisor-watchdog"
mkdir -p "$WATCHDOG_STATE_DIR"
WATCHDOG_STATE_FILE="$WATCHDOG_STATE_DIR/pre-update.$(date +%Y%m%dT%H%M%S).state"

OPENCLAW_BIN="$OC_REAL" "$SKILL_DIR/scripts/arm-recovery-watchdog.sh" arm --state-file "$WATCHDOG_STATE_FILE"

Required gate:

• If OC_REAL is empty or not executable, stop. Do not run openclaw update.
• If arming exits non-zero, prints no armed=1, or does not print a state file path, stop. Do not run openclaw update.
• Keep WATCHDOG_STATE_FILE; it is needed for post-update cleanup.
• The helper writes the resolved OPENCLAW_BIN into the external job environment so launchd/systemd does not depend on the chat/session PATH.
• The watchdog runtime is bounded (MAX_RUNTIME_SECONDS / --max-runtime-seconds).
• Recovery attempts are bounded (RECOVERY_RETRIES / --recovery-retries).
• Logs are written under the state directory for postmortem and cleanup.

The inert template scripts/recovery-watchdog-launchd.template.plist documents the macOS LaunchAgent shape; prefer the helper over hand-editing templates. On Linux, the helper uses systemd-run --user directly and does not require a template file.

Step 2: Run the update only after the watchdog gate passes

openclaw update

Session disconnection is expected. Do not treat the lost chat session itself as failure.

Step 3: Watchdog behavior (independent path)

recovery-watchdog.sh waits a grace period, probes openclaw gateway status, and only when unhealthy runs bounded openclaw gateway install attempts. It exits success when Gateway is healthy and non-zero on timeout/retry exhaustion.

Step 4: Post-update cleanup and optional reporting

After Gateway is healthy again, clean up the temporary LaunchAgent or systemd user unit plus state/log files:

"$SKILL_DIR/scripts/arm-recovery-watchdog.sh" cleanup --state-file "$WATCHDOG_STATE_FILE"

Then optionally report:

openclaw --version
openclaw gateway status
openclaw doctor

Cron/isolated-session reporting may summarize those outputs, but reporting is optional and must not be the only recovery mechanism.

---

Notes

• Step 1 (arm watchdog) must happen before Step 2 (run update) — session disconnects immediately after
• Linux Execute recovery requires a working systemd user manager (systemd-run --user + systemctl --user). If unavailable, stop before update and explain that protected Linux recovery is unsupported on that host.
• openclaw gateway restart is handled internally; never call it separately
• Session disconnection after update is normal behavior, not a failure
• If the version is unchanged, say rollback is not needed. If a rollback may be needed after a partial upgrade, provide a dry-run command first and require separate confirmation before executing it.
• Skills updates (clawhub update --all) are out of scope; handle separately if needed
• Never use the edit tool to patch openclaw.json directly — always use python3 -c with the json module or jq to avoid injecting control characters that break JSON parsing
• ⚠️ exec environment risk: When openclaw update is invoked via exec, the child process may share the Gateway's process group. Gateway termination can abort the restart handoff. Any optional cron verification job can only run after the Gateway/scheduler comes back; if no verification report arrives, tell the user to run openclaw gateway status locally, then openclaw gateway install if not installed or openclaw gateway start if installed but stopped, and then re-check.