Publish OpenClaw Releases: Standardized Checklist

Ever felt that pre-release anxiety where you are about to push code but aren’t 100% sure if the build is solid? We have all been there, double-checking every configuration and hoping the automated tests caught everything before the package hits the registry.

The OpenClaw release policy is designed to remove that uncertainty by providing a clear, predictable path for every update. By understanding how OpenClaw handles versions and deployments, you can manage your local setup with total confidence and ensure you are always running a verified build.

Understand OpenClaw Version Naming

OpenClaw uses a calendar-based versioning scheme that makes it easy to track the age and stability of your current install. This approach avoids the confusion of traditional version numbers by focusing on when the release actually happened.

Stable release version: YYYY.M.D
Git tag: vYYYY.M.D
Stable correction release version: YYYY.M.D-N
Git tag: vYYYY.M.D-N
Beta prerelease version: YYYY.M.D-beta.N
Git tag: vYYYY.M.D-beta.N
Do not zero-pad month or day.
latest means the current promoted stable npm release.
beta means the current beta install target.
Stable and stable correction releases publish to npm beta by default; release operators can target latest explicitly, or promote a vetted beta build later.
Every OpenClaw release ships the npm package and macOS app together.

Follow the OpenClaw Release Cadence

The rhythm of our updates is built around a “beta-first” philosophy to ensure that bugs are caught early in the cycle. This ensures that the most active users test new features before they are promoted to the general public.

Releases move beta-first.
Stable follows only after the latest beta is validated.
Detailed release procedure, approvals, credentials, and recovery notes are maintainer-only.

Run OpenClaw Release Preflight Checks

Preflight checks are the safety net that prevents broken builds from ever reaching your machine. These automated scripts verify everything from TypeScript types to the final UI bundle size across different operating systems.

Run pnpm check:test-types before release preflight so test TypeScript stays covered outside the faster local pnpm check gate.
Run pnpm check:architecture before release preflight so the broader import cycle and architecture boundary checks are green outside the faster local gate.
Run pnpm build && pnpm ui:build before pnpm release:check so the expected dist/* release artifacts and Control UI bundle exist for the pack validation step.
Run pnpm release:check before every tagged release.
Release checks now run in a separate manual workflow: OpenClaw Release Checks.
Cross-OS install and upgrade runtime validation is dispatched from the private caller workflow openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml, which invokes the reusable public workflow .github/workflows/openclaw-cross-os-release-checks-reusable.yml.
This split is intentional: keep the real npm release path short, deterministic, and artifact-focused, while slower live checks stay in their own lane so they do not stall or block publish.
Release checks must be dispatched from the main workflow ref so the workflow logic and secrets stay canonical.
That workflow accepts either an existing release tag or the current full 40-character main commit SHA.
In commit-SHA mode it only accepts the current origin/main HEAD; use a release tag for older release commits.
OpenClaw NPM Release validation-only preflight also accepts the current full 40-character main commit SHA without requiring a pushed tag.
That SHA path is validation-only and cannot be promoted into a real publish.
In SHA mode the workflow synthesizes v<package.json version> only for the package metadata check; real publish still requires a real release tag.
Both workflows keep the real publish and promotion path on GitHub-hosted runners, while the non-mutating validation path can use the larger Blacksmith Linux runners.
That workflow runs OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache using both OPENAI_API_KEY and ANTHROPIC_API_KEY workflow secrets.
npm release preflight no longer waits on the separate release checks lane.
Run RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts (or the matching beta/correction tag) before approval.
After npm publish, run node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D (or the matching beta/correction version) to verify the published registry install path in a fresh temp prefix.
Maintainer release automation now uses preflight-then-promote:

real npm publish must pass a successful npm preflight_run_id
stable npm releases default to beta
stable npm publish can target latest explicitly via workflow input
token-based npm dist-tag mutation now lives in openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml for security, because npm dist-tag add still needs NPM_TOKEN while the public repo keeps OIDC-only publish
public macOS Release is validation-only
real private mac publish must pass successful private mac preflight_run_id and validate_run_id
the real publish paths promote prepared artifacts instead of rebuilding them again

For stable correction releases like YYYY.M.D-N, the post-publish verifier also checks the same temp-prefix upgrade path from YYYY.M.D to YYYY.M.D-N so release corrections cannot silently leave older global installs on the base stable payload.
npm release preflight fails closed unless the tarball includes both dist/control-ui/index.html and a non-empty dist/control-ui/assets/ payload so we do not ship an empty browser dashboard again.
pnpm test:install:smoke also enforces the npm pack unpackedSize budget on the candidate update tarball, so installer e2e catches accidental pack bloat before the release publish path.
If the release work touched CI planning, extension timing manifests, or extension test matrices, regenerate and review the planner-owned checks-node-extensions workflow matrix outputs from .github/workflows/ci.yml before approval so release notes do not describe a stale CI layout.
Stable macOS release readiness also includes the updater surfaces:

the GitHub release must end up with the packaged .zip, .dmg, and .dSYM.zip
appcast.xml on main must point at the new stable zip after publish
the packaged app must keep a non-debug bundle id, a non-empty Sparkle feed URL, and a CFBundleVersion at or above the canonical Sparkle build floor for that release version.

Configure OpenClaw NPM Workflow Inputs

Managing releases through GitHub requires specific inputs to ensure the right code goes to the right place. You can control the entire flow using these parameters in the workflow interface to toggle between dry runs and live deployments.

OpenClaw NPM Release accepts these operator-controlled inputs:

tag: required release tag such as v2026.4.2, v2026.4.2-1, or v2026.4.2-beta.1; when preflight_only=true, it may also be the current full 40-character main commit SHA for validation-only preflight.
preflight_only: true for validation/build/package only, false for the real publish path.
preflight_run_id: required on the real publish path so the workflow reuses the prepared tarball from the successful preflight run.
npm_dist_tag: npm target tag for the publish path; defaults to beta.

OpenClaw Release Checks accepts these operator-controlled inputs:

ref: existing release tag or the current full 40-character main commit SHA to validate.

Rules:

Stable and correction tags may publish to either beta or latest.
Beta prerelease tags may publish only to beta.
Full commit SHA input is allowed only when preflight_only=true.
Release checks commit-SHA mode also requires the current origin/main HEAD.
The real publish path must use the same npm_dist_tag used during preflight; the workflow verifies that metadata before publish continues.

Execute the Stable OpenClaw NPM Release Sequence

When it is time to ship a stable version, we follow a specific sequence to promote vetted code. This process ensures that the exact same artifacts you tested in preflight are the ones that end up on npm.

Run OpenClaw NPM Release with preflight_only=true. Before a tag exists, you may use the current full main commit SHA for a validation-only dry run of the preflight workflow.
Choose npm_dist_tag=beta for the normal beta-first flow, or latest only when you intentionally want a direct stable publish.
Run OpenClaw Release Checks separately with the same tag or the full current main commit SHA when you want live prompt cache coverage. This is separate on purpose so live coverage stays available without recoupling long-running or flaky checks to the publish workflow.
Save the successful preflight_run_id.
Run OpenClaw NPM Release again with preflight_only=false, the same tag, the same npm_dist_tag, and the saved preflight_run_id.
If the release landed on beta, use the private openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml workflow to promote that stable version from beta to latest.
If the release intentionally published directly to latest and beta should follow the same stable build immediately, use that same private workflow to point both dist-tags at the stable version, or let its scheduled self-healing sync move beta later.

The dist-tag mutation lives in the private repo for security because it still requires NPM_TOKEN, while the public repo keeps OIDC-only publish. This keeps the direct publish path and the beta-first promotion path both documented and operator-visible.

Access OpenClaw Public References

Transparency is key to a healthy project, so we keep our release logic visible to everyone. You can explore these files to understand the underlying automation that powers our distribution and see exactly how the sausage is made.

Maintainers use the private release docs in openclaw/maintainers/release/README.md for the actual runbook.

AI Setup Assistant

Next Steps

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.