Five OpenClaw Upgrade and Config Integrity Fixes Operators Should Track

Five OpenClaw fixes merged on 23 July address a common operational risk: an upgrade or control-plane write can appear routine while damaging recoverability, access or trust state.

They affect different deployments, so this is not a blanket emergency-upgrade instruction. It is a pre-upgrade checklist: identify which conditions apply, confirm the containing release, preserve state and test the relevant recovery path.

Quick triage

Matrix: Doctor becomes the only snapshot migration owner

PR #112919 fixes an upgrade path present since 2026.6.10. Matrix encryption state could be imported, renamed or bypassed by runtime fallback logic, leaving key material split between crypto-idb-snapshot.json and canonical SQLite state.

The fix removes runtime migration. openclaw doctor --fix now owns the operation under the same cross-process lock used by persistence. It imports the legacy snapshot, reads SQLite back for structural and content verification, and only then moves the original bytes to a timestamped recovery archive.

Malformed sources are archived rather than deleted; filesystem read failure leaves the source active; a valid SQLite conflict remains canonical while the differing legacy bytes are preserved. Runtime uses SQLite only and fails closed with a path-free instruction to run Doctor when a live legacy snapshot blocks safe startup.

Operator guidance: make a consistent state backup first. Run Doctor while avoiding concurrent Matrix persistence, inspect its result and retained archive, then restart. Do not manually rename the snapshot and hope runtime chooses the right copy.

Control UI: retired auth bypass now migrates into pairing

PR #112558 covers upgrades from configurations using gateway.controlUi.dangerouslyDisableDeviceAuth=true.

Doctor previously removed the retired key before transferring its meaning into device-pairing state. The next browser connection could demand shell-side approval even when the user had no practical shell recovery path.

The merged transition grants a narrowly restricted temporary session only to a signed Control UI operator that passes token or password authentication on an installation with no paired operator. That browser can see and approve only its own pairing request. An atomic claim prevents two browsers from both winning; successful pairing becomes durable and competing temporary sessions close.

This is intentionally not a general device-auth bypass. Existing paired operators and users who never set the retired option keep normal behaviour.

Operator guidance: retain a protected copy of pre-upgrade configuration, keep shell access available where possible, and test one-browser and competing-browser pairing in staging. The expected result is a one-time Secure this browser flow followed by normal device-token enforcement.

MCP and config: acknowledged writes must not be lost

PR #113026 fixes four control-plane defects found under stress:

• concurrent config.patch, config.set or config.apply calls could all pass an early base-hash check, return success and then overwrite one another after waiting for the file lock;
• malformed HTTP/SSE MCP targets could pass the UI and fail only after a config write;
• server-controlled diagnostics could expose bearer credentials; and
• completed direct plugin MCP calls could retain adjusted argument payloads in global tracking state.

The Gateway now repeats revision compare-and-swap while holding the mutation lock. Only one writer can succeed against a given base; the rest receive stale-config failures. URL validation moves before persistence, diagnostic text receives secret redaction and terminal calls release tracked argument state.

Upstream’s stress proof reports that the old path acknowledged 30 writes while retaining one update. The regression now expects one success and stale-hash failures for competing writes.

Operator guidance: on an older build, serialize configuration automation externally and treat MCP probe output as potentially sensitive. After upgrading, make your automation handle stale-revision responses by re-reading, reconciling intent and retrying—not by blindly replaying an old patch.

Large inodes: identity must not pass through JavaScript Number

PR #112478 fixes Gateway startup migration on filesystems whose inode values exceed JavaScript’s safe integer range.

Two adjacent inode values on virtiofs/Kata could collapse to the same Number. OpenClaw then believed distinct session-store paths were aliases, emitted an aliased store deferral and refused readiness. The fix reads file identity with BigInt-aware stat before comparison.

Real hard links, symlinks and shared-store aliases retain fail-closed handling.

Operator guidance: if a migration fails with an alias report on a large-inode filesystem, do not disable the alias check. Preserve logs and state, verify the paths are genuinely distinct, and move to a build carrying PR #112478 before retrying.

macOS: public roots and private Keychain roots are separate cases

PR #112868 fixes one-shot macOS commands that avoided a shutdown hang by disabling Keychain CA loading but then selected an unconfigured OpenSSL trust store. Valid provider calls could fail with UNABLE_TO_GET_ISSUER_CERT_LOCALLY even though Node, curl and direct requests succeeded.

The fix uses Node’s bundled public roots for the default one-shot child. Private enterprise roots remain an explicit system-CA case.

PR #113128 backports the reviewed lifecycle correction to the 2026.7.2 release branch so NODE_USE_SYSTEM_CA=1 can retain macOS Keychain trust while explicit drained exit still prevents the one-shot shutdown hang. Upstream says extended stable 2026.6.33 never received this regression.

Operator guidance: test both a public provider endpoint and one private enterprise endpoint. A public-root success does not prove Keychain-only trust works, and a process exiting promptly does not prove output and teardown were fully flushed.

Evidence and limits

The primary pull requests report focused suites, exact-head CI or Testbox runs, and targeted live reproductions. OpenClaw Academy reviewed their official merged records and chronology. We did not migrate live Matrix keys, race production config writers, run on Kata, or exercise a private macOS CA.

No complete affected-version matrix exists for this whole cluster. Match each fix to its stated condition and confirm the exact release or commit you deploy.

Bottom line

These fixes reward boring upgrade discipline: preserve the canonical state, let one migration owner act, bind authorization to an explicit transition, recheck revisions under the write lock and test the trust store you actually use.

Do not respond to a migration or access failure by deleting sidecars, weakening alias checks, disabling device auth or replaying stale config. Confirm the containing fix and exercise the recovery path with backups intact.