Skip to content
OpenClaw Docs

Release Policy

Release Policy

Section titled “Release Policy”

OpenClaw has three public release lanes:

  • stable: tagged releases that publish to npm beta by default, or to npm latest when explicitly requested
  • beta: prerelease tags that publish to npm beta
  • dev: the moving head of main

Version naming

Section titled “Version naming”
  • 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

Release cadence

Section titled “Release cadence”
  • Releases move beta-first
  • Stable follows only after the latest beta is validated
  • Detailed release procedure, approvals, credentials, and recovery notes are maintainer-only

Release preflight

Section titled “Release preflight”
  • 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
  • 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
    • stable npm promotion from beta to latest is still available as a separate manual workflow step
    • 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
  • If the release work touched CI planning, extension timing manifests, or fast test matrices, regenerate and review the planner-owned checks-fast-extensions shard plan via node scripts/ci-write-manifest-outputs.mjs --workflow ci 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

NPM workflow inputs

Section titled “NPM workflow inputs”

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
  • 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

Rules:

  • Stable and correction tags may publish to either beta or latest
  • Beta prerelease tags may publish only to beta
  • The real publish path must use the same npm_dist_tag used during preflight; the workflow verifies that metadata before publish continues

Stable npm release sequence

Section titled “Stable npm release sequence”

When cutting a stable npm release:

  1. Run OpenClaw NPM Release with preflight_only=true
  2. Choose npm_dist_tag=beta for the normal beta-first flow, or latest only when you intentionally want a direct stable publish
  3. Save the successful preflight_run_id
  4. Run OpenClaw NPM Release again with preflight_only=false, the same tag, the same npm_dist_tag, and the saved preflight_run_id
  5. If the release landed on beta, run OpenClaw NPM Promote Beta later with the exact stable version when you want to move that published build to latest

That keeps the direct publish path and the beta-first promotion path both documented and operator-visible.

Public references

Section titled “Public references”

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