Six OpenClaw Main-Branch Fixes for Gateway Startup and Upgrade Recovery

Six merged OpenClaw changes address failures that can make a valid deployment look broken—or make a broken authority look valid—during startup, restart and update.

The sharpest security correction removes optional plugin tools after their required authentication disappears. The most visible availability fixes unblock Gateways wedged by deterministic legacy-state conflicts, make Docker healthchecks follow a custom port, and reduce cold-start work for large configured model rosters.

All six are merged on main. They are not proof of inclusion in an official package. Match the exact release or revision before applying the guidance as remediation.

Triage table

Legacy file conflicts should not wedge every startup

PR #116558 addresses legacy runtime-state files for voice wake routing, plugin bindings and conversation bindings that disagree with shared SQLite state after an upgrade. Upstream says deterministic divergence now archives the legacy file, emits a non-blocking notice and keeps SQLite canonical.

This is intentionally narrower than “ignore every migration error.” Non-deterministic read or preservation failures should remain blocking because the runtime cannot prove which authority is safe.

Before upgrading, back up the complete state boundary, including the SQLite database family and legacy files. After startup, inspect the archive and verify real routing or bindings. Do not manually delete the old file merely to silence readiness; that destroys the evidence needed to decide whether SQLite contains the intended state.

Docker health now follows the serving port

PR #116639 replaces the hard-coded port check with a built healthcheck entrypoint that resolves the active Gateway port, preferring the runtime lock, and probes /healthz over loopback.

For custom-port deployments, the old symptom was operationally dangerous: the application served normally while Docker reported unhealthy. An orchestrator or human runbook could restart a healthy Gateway, turning a monitoring defect into real downtime.

Acceptance requires more than seeing healthy. Change the port through each supported mechanism you use—CLI, environment or config—then verify the health probe follows the same active owner and fails when the real Gateway stops.

Authentication removal must invalidate cached tools

PR #116625 fixes an optional plugin tool that could remain projected after provider authentication was removed. A previous authenticated resolution populated the descriptor cache; a later cache hit could re-expose the tool even though current manifest availability rejected it.

The merged path filters cached descriptors against the currently available tool names before allowlisting and projection. Current auth, configuration and environment become authoritative again.

Interpretation: a cache may accelerate capability discovery, but it cannot be an authority for capability revocation. If removing a credential does not remove the corresponding tool surface, the operator has a false least-privilege control even when later invocation might fail.

Test revocation in the same long-lived process. Restart-only tests can miss the stale-cache condition.

Code Mode restart preserves old work without authorising new work

PR #116605 covers an in-flight, replay-safe Code Mode run whose checkpoint survives a Gateway restart. If reloaded configuration disables Code Mode for new turns, recovery still needs the original exec/wait control surface long enough to complete or abort the checkpoint-proven provider turn.

That is not permission to start fresh Code Mode work after the setting is disabled. The boundary is authenticated backend main-session recovery for already-owned work.

Operators should test both sides: a proven in-flight run resumes safely, while a new turn remains denied under the reloaded policy. If those cases collapse into one rule, restart recovery has widened authority.

Large model rosters should not starve readiness

PR #116553 compiles a static model-ID matcher from the prepared plugin metadata snapshot instead of repeating plugin metadata scans for configured models. The upstream benchmark cited in GitHub search uses a large synthetic multi-agent/model roster and reports a substantial reduction, but operators should not transplant that number into capacity planning.

Measure cold startup with your exact agents, plugins, model aliases and health deadlines. Confirm the final model and fallback routes, not only time to an open port.

This is adjacent to, but distinct from, the earlier static-catalog resolver fix reported by OpenClaw Academy. Both attack repeated preparation work at startup; neither makes a small test roster representative of production.

npm moving selectors now verify correctly

PR #116585 distinguishes exact versions from moving npm selectors. A range or dist-tag can legitimately resolve to a concrete version that is not textually equal to the selector. Post-install equality is now enforced for exact version requests while ranges and tags accept their selected concrete package.

This removes a false rejection, not the need to verify what was installed. For production, record the resulting exact version, check that it belongs to the intended channel and retain rollback. A tag such as latest is policy, not an immutable artifact identity.

Safe upgrade run

1. Capture the current exact OpenClaw revision, Gateway/node versions and redacted configuration.
2. Back up SQLite, sidecars, legacy state and plugin manifests consistently.
3. Stage the containing build with the production-sized model roster.
4. Test custom-port health and real process failure separately.
5. Remove test provider auth without restarting; prove gated tools disappear.
6. Restart during a disposable replay-safe Code Mode run; prove old work can settle but new disabled work cannot start.
7. Exercise one exact npm selector and one moving selector; record the concrete installed versions.
8. Inspect Doctor notices and archives before deleting any migration evidence.

Evidence and limits

The official PR records supplied by the repository collector identify each failure, merge and priority. GitHub search independently surfaced the legacy-conflict policy, active-port healthcheck, current-auth cache filtering, checkpoint-scoped Code Mode recovery, static model matcher and exact-versus-moving selector logic. Direct page extraction was unavailable.

OpenClaw Academy did not run these changes in Docker, perform an npm update or restart a live Code Mode turn. Upstream performance and test claims remain attributed to upstream.

Bottom line

These fixes tighten the difference between observation and authority: health must follow the port actually serving, cached tools must follow current authentication, restart recovery must follow the checkpoint that owns work, and SQLite must remain canonical only when conflicting legacy bytes can be preserved safely.

Adopt them through a confirmed containing release, then test the failure boundary—not just the happy path. A green container, a visible tool or an open socket can all be the wrong answer when ownership has drifted.