Bug type

Upgrade lifecycle gap

Summary

Container image upgrades can bypass the migrations that normally run through openclaw upgrade.

When an operator replaces one OpenClaw container image with another while preserving the same state/config volume, the container starts the gateway directly. Startup may run limited config/state preflight work, but it does not detect that the OpenClaw version changed and run the pending versioned upgrade migrations before declaring the gateway ready.

This means any migration added between image versions can be skipped for common Docker/Kubernetes-style upgrades.

Expected behavior

On gateway startup, OpenClaw should detect when the current OpenClaw version differs from the last successfully migrated version for the mounted state/config.

Before gateway readiness, it should either:

• run all pending openclaw upgrade migrations for that version transition, then record the successful migrated version; or
• fail readiness with a clear, actionable error if those migrations cannot safely run.

The startup path should be idempotent, locked against concurrent starts, and should not report a healthy gateway while required upgrade migrations are still pending.

Actual behavior

Replacing the container image starts the gateway without running the full upgrade migration path.

A recent 2026.6.10 -> 2026.6.11 container replacement exposed this through a configured Mattermost channel not being converged after upgrade. That is only the example. The Mattermost-specific activation/repair bug is tracked separately in #98564.

The broader issue here is that container image replacement does not automatically execute the migrations that openclaw upgrade would have run.

Steps to reproduce

1. Run an OpenClaw container at version N with state/config mounted.
2. Configure state that requires a migration in version N+1.
3. Stop/remove only the container, preserving the mounted state/config.
4. Start a version N+1 OpenClaw container normally.
5. Observe that the gateway starts without eagerly running the full upgrade migration path for N -> N+1.

Impact

This affects users who upgrade by replacing container images, which is the normal upgrade model for Docker and Kubernetes deployments.

Depending on the skipped migration, the result can be missing plugins, stale config, inconsistent state, broken channels, missed messages, or other release-specific failures. The gateway can appear ready even though the mounted state has not been upgraded for the current image.

Non-goal

This issue should not track the Mattermost-specific activation behavior. Keep that in #98564. Mattermost is useful only as a concrete example showing why skipped container-upgrade migrations are dangerous.

Acceptance criteria

• Startup records and compares the last successfully migrated OpenClaw version for the mounted state/config.
• A version change runs the same migration set expected from openclaw upgrade before gateway readiness.
• Migration execution is idempotent and protected from concurrent startup races.
• Migration failures prevent healthy readiness and produce actionable logs.
• Tests cover a container-style upgrade path where the gateway starts directly after an image version change.