openclaw/docs/reference/RELEASING.md

doc-schema-version	summary	title	read_when
1	OpenClaw release channels, version numbers, validation, and published assets	Release policy	Choosing a release channel Understanding version numbers and release checks Checking which packages and apps have been published

OpenClaw offers stable releases for everyday use, beta releases for testing, and extended-stable releases for users who prefer an older Gateway maintenance line. This page explains those choices and what a release has been checked for. For switching channels, see Release channels.

Release channels

Channel	What you get
Stable	The regular release promoted to npm latest.
Beta	A candidate on npm beta. This may be a prerelease or a final version awaiting promotion.
Extended-stable	A Gateway maintenance release from either of the two trailing completed months, on npm extended-stable.
Dev	The moving head of main, for development.

Extended-stable includes the Gateway, official npm plugins, and Docker images. It does not include native apps or ClawHub publication, and it does not change the regular stable channel. Its GitHub release is not marked Latest. A monthly line retires when it falls outside the two supported completed months.

Version naming

Release	Version example
Regular final	2026.9.6
Beta prerelease	2026.9.6-beta.1
Regular correction	2026.9.6-1
Extended-stable	2026.8.33, followed by 2026.8.34 for its next maintenance release

Versions use year.month.patch, without zero-padding. The patch is a release number within the month, not a day of the month. Regular releases use patches below 33; extended-stable starts at 33. Git tags add v, as in v2026.9.6. Release tags are annotated and signed. The shared publication workflow verifies the tag signature before checkout or evidence downloads and refuses lightweight, unsigned, or unverified tags. This also applies to recovery and republishing: historical unsigned tags are not eligible for the shared publication workflow, and recovery must use a new signed release version rather than replacing a tag.

Published npm versions and release tags are never replaced. A fix receives a new version. Historical alpha-only versions do not advance the regular release number; alpha releases are retired.

Release cadence

Releases normally go to beta first and move to stable after validation. For core and every published official npm plugin, beta must be at least as new as latest; an already newer beta stays unchanged. A prerelease is older than the final version with the same base number.

A final version published to the beta channel still has to meet the stable validation requirements below. The npm channel alone does not determine which checks apply.

Release validation

Stable publication requires stable or full validation, longer-running soak tests, and blocking performance checks. These requirements also apply to a final version first published on the beta channel. Beta-profile evidence cannot qualify stable.

Windows Node unit-test CI shards (checks-windows-node-*) in Full Release Validation's normal CI child (normalCi) are advisory for Release Decision and publication. The windows-node-ci class is defined by scripts/full-release-validation-policy.mjs; its failures remain visible in the decision, GitHub step summary, and release evidence manifest. This policy is not an operator-selectable input or waiver. Ordinary PR, push, scheduled, and main CI still require Windows shards to pass.

Every failed test needs an explicit release-lead decision: blocker or flake. Rerun a flake on the same Release SHA at most twice, file its fix-in-parallel issue or PR on main, and retain the original failure. A still-failing eligible normalCi job can use the authenticated recorded-flake classification workflow; its receipt binds the parent, child run, exact job attempt, Release SHA, reason, and tracking link. The decision, manifest, and release verification notes retain the failure. Do not re-cut, change tooling, or start another Full Release Validation for a flake. See recorded flakes.

Other children stay strict in v1; extending classification to them is follow-up work. Non-classifiable jobs remain blocking: the CI coverage gate, seal/evidence, Build Artifacts, install smoke, survivor lanes, update-first-hop-compat*, pack/npm qualification, package integrity, and all Linux/Windows/macOS Gateway checks, including Windows packaged install/upgrade checks in Release Checks. A cancelled run still blocks. A failed CI gate is accepted only when its own log proves that every non-passing entry selected a failed advisory job; missing, skipped, or cancelled coverage blocks. Publication waivers cannot bypass failures or required coverage. Validation covers source CI, packages, plugins, Gateway installs and upgrades, and selected app, UI, Telegram, QA, and live-provider checks. All-group qualification includes all nine Gateway install/upgrade combinations across Linux, Windows, and macOS. Coverage otherwise varies by profile and selected operating systems. Check the release's recorded coverage: skipped or deferred checks are not passes.

Dependency advisories never block or delay a release. Release dependency evidence records every advisory finding, at any severity, and CI dispatched by release validation or publication reports a failing dependency audit as a warning. The dependency fix ships through main after publication. Only a known-malware finding stops publication.

The health of main CI does not gate a release. Validation and publication run from the release branch with pinned release tooling, so a red main is not a reason to wait, re-cut, or pause.

See Full release validation for coverage by profile and how to interpret the results.

Packages and apps can become available at different times

A published Gateway release does not mean every native app is ready. Signing and publishing the apps can finish separately from npm, Docker, and the GitHub release.

Check the release's assets and announcements for each platform. A pending app build or an accepted publication request is not a completed app release. Extended-stable is a Gateway distribution and does not publish native apps.

Release notes and verification

The release notes describe user-facing changes. GitHub releases also carry validation results, dependency reports, and checks of the published packages. These records identify the tested version and the files that shipped. Later documentation updates may improve the release notes without rebuilding or replacing packages.

For dependency review, see Dependency locking. Release dependency archives include npm-format locks separately from the package tarballs.

Downstream packaging

To consume a release lock:

1. Download openclaw-<version>-dependency-evidence.zip from the GitHub release. Open dependency-evidence/npm-package-locks.json (schemaVersion: 1) and select the packages entry matching the exact package name and version.
2. Reject entries with a nonempty omittedWorkspaceDependencies array. These are partial locks: the generator omits sibling workspace: runtime dependencies that publish in the same release. The report counts these entries in packagesWithOmittedWorkspaceDependencies.
3. Verify that dependency-evidence/dependency-evidence-manifest.json's releaseSha, the report's sourceSha, and the OpenClaw commit you pin all match. The report also records the source pnpm-lock.yaml SHA-256.
4. Serialize entry.lock as package-lock.json using two-space JSON indentation and a trailing newline, then verify its SHA-256 against entry.lockSha256.
5. Before npm ci, carry the source pnpm-workspace.yaml overrides into the consuming package.json, or rewrite nested dependencies and optionalDependencies specs to their locked versions. The generated locks encode workspace overrides, so unmodified specs can fail npm's lock-sync check.

The companion npm-package-locks.md includes counts and a package table. Each entry records bundleRuntimeDependencies and direct dependency counts so packagers can identify lockless packages that need an external lock. Each entry also records a path-sorted bundledDependencies array with path, name, version, and parent. These dependencies carry inBundle: true in the npm lock; parent identifies the nearest enclosing non-bundled package whose resolved and integrity verify the tarball carrying their bytes. The report rejects missing or unverifiable carriers and preserves the lock payload. The Markdown table counts bundled dependencies per package and includes their total.

Maintainer procedures

Release preparation, publishing commands, approvals, and recovery live in the release-maintainer skill. Credential handling and emergency procedures remain in the private maintainer runbook. Former section links below lead to their corresponding procedures.

Linux publication.

Release changelogs.

Changelog-only qualification.

Extended-stable preparation and publication.

Extended-stable recovery.

Regular release checklist.

Resumable release orchestration.

Deferred CI recovery.

Nightly validation reuse.

Release tooling CI scope.

Stable main closeout.

Post-release documentation publication.

Source and package gates.

Older updater verification.

Runtime generation design proposal (not shipped behavior).

Release validation lanes.

Package Acceptance.

Publication qualification.

Bootstrap-token verification.

Prepared publication.

Interrupted preparation and publication.

Published-version recovery.

Regular publication and verification.

Publication requirements.

Release workflow reference.