update-openclaw

name	update-openclaw
description	Use when bumping the pinned OpenClaw core version (openclaw npm package), when preparing a Pinchy release, or when the user asks to "update OpenClaw" / "upgrade OpenClaw" / check for a newer OpenClaw version.

Update the pinned OpenClaw version

Overview

Pinchy pins the OpenClaw core runtime version in two places that a drift guard keeps in lockstep:

• packages/web/package.json → dependencies.openclaw
• Dockerfile.openclaw → RUN npm install -g openclaw@<version>

packages/web/src/__tests__/lib/openclaw-version-pin-drift.test.ts greps Dockerfile.openclaw for the literal npm install -g openclaw@ line and fails if it doesn't match package.json. Both places also feed /api/version.

Core principle: OpenClaw upgrades have repeatedly broken Pinchy in ways pnpm test/tsc don't catch, because the breakage is in runtime protocol behavior (session keys, tools.allow semantics, config.apply timing, plugin manifest resolution) — see the reference_oc_* / reference_openclaw_* memory entries about past compatibility cliffs. Never treat "npm view shows a newer version" as a green light by itself. Read the release notes for every version between current and target first.

Procedure

1. Check current vs. latest.

   grep openclaw packages/web/package.json
   npm view openclaw version
   npm view openclaw versions --json | tail -20   # see every point release in between
   

2. Read every release's notes between current (exclusive) and target (inclusive) — not just the target's diff summary, since intermediate point releases can carry changes too:

   gh release list --repo openclaw/openclaw --limit 20
   gh release view v<version> --repo openclaw/openclaw
   

   Read the full text, not just headline "Highlights" — the "Additional ... fixes" subsections often contain the entry that actually matters to us. Work through it against these four questions, in this order, and write down what you find for each before moving to step 3:

   a. Incompatibility risk. Anything touching session keys, tools.allow semantics, config.apply timing, plugin config/manifest resolution, or provider baseUrl handling — the areas that have bitten us before (see reference_oc_* / reference_openclaw_* memory entries). Look at sections titled "Sessions", "Gateway, Security, and Trust", "Plugins and Packaging", and any breaking/migration language anywhere else. Watch especially for new gateway-startup / config self-healing behavior — these don't show up in pnpm test/tsc at all and only fail in the docker E2Es. The agent:bootstrap hook contract is one of these silent dependencies. config/pinchy-hooks/bootstrap-memory-group-filter/ (the #369 leak fix) assumes the event carries context.bootstrapFiles (array) and context.sessionKey (string), that reassigning context.bootstrapFiles is read back by the caller, and that internal hooks load via native import(). If the notes touch bootstrap/hook events, session-key shape, or the internal hook loader, verify against the installed dist that these still hold — the hook now console.warns instead of failing open, so also check the gateway logs on the staging deploy for that warning. A silent contract change here re-opens a P0 eu-ai-act memory leak. See the hook's HOOK.md Verification section for the exact staging check. Real example the 2026.6.11 bump tripped: OpenClaw 2026.6.x added startup config auto-restore — on a size-drop / missing-meta vs last-known-good it restores openclaw.json.last-good over openclaw.json at gateway start (recoverConfigFromLastKnownGood). This broke the setup-wizard reset (it deleted openclaw.json but not the backups, so OC restored the prior test's config referencing wiped secrets → crash-loop). If notes mention config backup / last-known-good / recovery / restore, expect the setup-wizard + integration E2Es to need reset-choreography updates.

   b. Resolved issues we have workarounds for. Grep our own code for the upstream issue/PR numbers and version-guard comments before reading notes:

   git grep -rniE "openclaw/openclaw#[0-9]+|openclaw issue|version.?guard|workaround|TODO\(#" -- packages/ config/ | grep -vi node_modules
   

   For each hit, check the upstream issue state (gh issue view <n> --repo openclaw/openclaw --json state,closedAt). But "issue closed" is necessary, not sufficient — a closed issue is where naive audits go wrong. Before removing any workaround, confirm ALL of:

   1. The fix shipped in a release ≤ our target pin. Close date ≠ release date, and release notes often don't name the issue. When in doubt, inspect the actually-installed bundle in node_modules/.pnpm/openclaw@<target>/node_modules/openclaw/dist for the fixed code, not just the changelog.
   2. The fix targets OUR code path, not a sibling. Real example: openclaw #75534 (config.apply no-op restart, tracked on our side by #215) fixed OpenClaw's own writeConfigFile short-circuit — but Pinchy writes the config file itself and then calls config.apply, a different path whose env.*→default-restart mechanism was still present verbatim in 2026.6.11. Issue closed, workaround NOT removable.
   3. The workaround is actually a bug-workaround, not a defensive error-UX classifier or an architectural decoupling that stays valuable after the bug is fixed. Real examples that are NOT removable-on-close: the thought_signature error classifier (model-error-classifier.ts, #338 — renders graceful UX whenever the upstream error surfaces, and its removal is gated on an empirical live-path condition, not the issue state), and the Telegram store-based allowFrom (#47458 — a restart-avoiding design choice, see reference_ollama_local_rewrite_decoupling.md for the "decoupling, not a version workaround" pattern).
   4. Prefer the tracking issue's own stated verification (e.g. "remove X, run E2E agent-create-no-restart.spec.ts, confirm it stays green") over bundle archaeology. Bundle-reading can prove a workaround is STILL needed (mechanism present) but is weak evidence that one is safe to REMOVE — that needs the prescribed test. Memory: reference_config_apply_rate_limit_drop.md warns version guards can become bugs after an upstream fix, so this cuts both ways.

   If all four hold, remove the workaround in the same change with a test proving native behavior now covers it. Otherwise leave it and record why.

   c. Features we built ourselves that OpenClaw now does natively. Scan for "native", new config keys, or new built-in capabilities in areas where Pinchy has a bespoke plugin or workaround (e.g. transcript capture, session identity, memory, approvals — see reference_pinchy_owned_transcript.md, reference_openclaw_approval_primitives.md, reference_mcp_native_credential_proxy.md for precedent: MCP was migrated from a Pinchy-built plugin to native mcp.servers + a thin credential proxy once OpenClaw grew native support). Same feature name ≠ same scope — check whether the native capability covers the REASON we built the bespoke version, not just its surface. Real example: 2026.6.10 added a native "session-transcript SDK" (read, append, publish, lock), which sounds like it could replace pinchy-transcript. But its methods are all keyed by { agentId, sessionKey, sessionId } — session-scoped. Pinchy owns channel_messages precisely because it needs a channel-lifetime record that survives /new/reset/compaction (per PR #553 / reference_pinchy_owned_transcript.md); adopting the session-scoped SDK would reintroduce the exact blank-on-/new bug it fixed. So: not adoptable. If a native capability genuinely covers the reason, flag it as a follow-up simplification; if it only matches the name, record why it doesn't fit so the next bump doesn't re-litigate it.

   d. New OpenClaw features worth exposing in Pinchy. Anything new that fits Pinchy's enterprise-governance angle (permissions, audit, channels, models) or that Pinchy's target audience (self-hosted enterprise teams, see "Product Context" in AGENTS.md) would plausibly want surfaced in the UI/API. Note these separately as feature ideas — they are out of scope for the bump itself, not blockers.

3. Summarize findings against the four questions before touching code. If (a) is empty, treat the bump as safe to proceed. If (a) is non-empty, flag it to the user before proceeding — don't silently absorb a breaking change into a routine bump. (b), (c), and (d) don't block the bump, but report them: (b) as follow-up cleanup candidates (ideally done alongside the bump if small), (c)/(d) as things worth a tracked issue or a spawn_task-style follow-up rather than silently doing nothing with them.

4. Bump both pinned locations to the same target version:

   • packages/web/package.json → dependencies.openclaw
   • Dockerfile.openclaw → the npm install -g openclaw@... line

5. Check openclaw-node (packages/web/package.json → dependencies["openclaw-node"], our own client library in ~/projects/openclaw-node/) for a matching newer release too — npm view openclaw-node version. If it needs a release and we own it: openclaw-node has NO pnpm release script (that's Pinchy's mechanism). Its actual release flow (v0.13.0/v0.13.1 precedent): add a CHANGELOG entry, bump package.json, commit chore: release vX.Y.Z on main, wait for CI on that commit, then gh release create vX.Y.Z — the GitHub release triggers publish.yml, which re-verifies CI and publishes to npm. Verify with npm view openclaw-node version before bumping the Pinchy pin.

6. Install and verify:

   pnpm install
   pnpm -C packages/web vitest run src/__tests__/lib/openclaw-version-pin-drift.test.ts
   node --test config/__tests__/bootstrap-memory-group-filter.test.mjs  # #369 hook contract
   pnpm test
   pnpm build
   

   Note: the hook test above proves the filter logic, not that OpenClaw still fires the hook. If the notes touched bootstrap/hook/session-key behavior, run the HOOK.md staging check before shipping.

7. Don't commit automatically. Report the diff (git status --short, git diff --stat) and let the user decide to commit/PR — this touches a runtime dependency, not just app code.

If a release note flags something sensitive

Don't just bump anyway. Options, in order of preference:

• Pin to the last version before the risky change and note why in a commit message / to the user.
• Do the bump on a branch, add/adjust a regression test for the specific behavior the release note describes, then bump.
• Ask the user whether to proceed if the tradeoff isn't yours to make alone.