Release policy

OpenClaw has three public release lanes:

• stable: tagged releases that publish to npm
  text

  Copy

  beta
  by default, or to npm
  text

  Copy

  latest
  when explicitly requested
• beta: prerelease tags that publish to npm
  text

  Copy

  beta
• dev: the moving head of
  text

  Copy

  main

Version naming

• Stable release version:
  text

  Copy

  YYYY.M.D
  • Git tag:
    text

    Copy

    vYYYY.M.D
• Stable correction release version:
  text

  Copy

  YYYY.M.D-N
  • Git tag:
    text

    Copy

    vYYYY.M.D-N
• Beta prerelease version:
  text

  Copy

  YYYY.M.D-beta.N
  • Git tag:
    text

    Copy

    vYYYY.M.D-beta.N
• Do not zero-pad month or day
• text

  Copy

  latest
  means the current promoted stable npm release
• text

  Copy

  beta
  means the current beta install target
• Stable and stable correction releases publish to npm
  text

  Copy

  beta
  by default; release operators can target
  text

  Copy

  latest
  explicitly, or promote a vetted beta build later
• Every stable OpenClaw release ships the npm package and macOS app together; beta releases normally validate and publish the npm/package path first, with mac app build/sign/notarize reserved for stable unless explicitly requested

Release cadence

• Releases move beta-first
• Stable follows only after the latest beta is validated
• Maintainers normally cut releases from a
  text

  Copy

  release/YYYY.M.D
  branch created from current
  text

  Copy

  main
  , so release validation and fixes do not block new development on
  text

  Copy

  main
• If a beta tag has been pushed or published and needs a fix, maintainers cut the next
  text

  Copy

  -beta.N
  tag instead of deleting or recreating the old beta tag
• Detailed release procedure, approvals, credentials, and recovery notes are maintainer-only

Release operator checklist

This checklist is the public shape of the release flow. Private credentials, signing, notarization, dist-tag recovery, and emergency rollback details stay in the maintainer-only release runbook.

1. Start from current
   text

   Copy

   main
   : pull latest, confirm the target commit is pushed, and confirm current
   text

   Copy

   main
   CI is green enough to branch from it.
2. Rewrite the top
   text

   Copy

   CHANGELOG.md
   section from real commit history with
   text

   Copy

   /changelog
   , keep entries user-facing, commit it, push it, and rebase/pull once more before branching.
3. Review release compatibility records in
   text

   Copy

   src/plugins/compat/registry.ts
   and
   text

   Copy

   src/commands/doctor/shared/deprecation-compat.ts
   . Remove expired compatibility only when the upgrade path stays covered, or record why it is intentionally carried.
4. Create
   text

   Copy

   release/YYYY.M.D
   from current
   text

   Copy

   main
   ; do not do normal release work directly on
   text

   Copy

   main
   .
5. Bump every required version location for the intended tag, then run the local deterministic preflight:
   text

   Copy

   pnpm check:test-types
   ,
   text

   Copy

   pnpm check:architecture
   ,
   text

   Copy

   pnpm build && pnpm ui:build
   , and
   text

   Copy

   pnpm release:check
   .
6. Run
   text

   Copy

   OpenClaw NPM Release
   with
   text

   Copy

   preflight_only=true
   . Before a tag exists, a full 40-character release-branch SHA is allowed for validation-only preflight. Save the successful
   text

   Copy

   preflight_run_id
   .
7. Kick off all pre-release tests with
   text

   Copy

   Full Release Validation
   for the release branch, tag, or full commit SHA. This is the one manual entrypoint for the four big release test boxes: Vitest, Docker, QA Lab, and Package.
8. If validation fails, fix on the release branch and rerun the smallest failed file, lane, workflow job, package profile, provider, or model allowlist that proves the fix. Rerun the full umbrella only when the changed surface makes prior evidence stale.
9. For beta, tag
   text

   Copy

   vYYYY.M.D-beta.N
   , publish with npm dist-tag
   text

   Copy

   beta
   , then run post-publish package acceptance against the published
   text

   Copy

   openclaw@YYYY.M.D-beta.N
   or
   text

   Copy

   openclaw@beta
   package. If a pushed or published beta needs a fix, cut the next
   text

   Copy

   -beta.N
   ; do not delete or rewrite the old beta.
10. For stable, continue only after the vetted beta or release candidate has the required validation evidence. Stable npm publish reuses the successful preflight artifact via
    text

    Copy

    preflight_run_id
    ; stable macOS release readiness also requires the packaged
    text

    Copy

    .zip
    ,
    text

    Copy

    .dmg
    ,
    text

    Copy

    .dSYM.zip
    , and updated
    text

    Copy

    appcast.xml
    on
    text

    Copy

    main
    .
11. After publish, run the npm post-publish verifier, optional standalone published-npm Telegram E2E when you need post-publish channel proof, dist-tag promotion when needed, GitHub release/prerelease notes from the complete matching
    text

    Copy

    CHANGELOG.md
    section, and the release announcement steps.

Release preflight

• Run
  text

  Copy

  pnpm check:test-types
  before release preflight so test TypeScript stays covered outside the faster local
  text

  Copy

  pnpm check
  gate
• Run
  text

  Copy

  pnpm check:architecture
  before release preflight so the broader import cycle and architecture boundary checks are green outside the faster local gate
• Run
  text

  Copy

  pnpm build && pnpm ui:build
  before
  text

  Copy

  pnpm release:check
  so the expected
  text

  Copy

  dist/*
  release artifacts and Control UI bundle exist for the pack validation step
• Run the manual
  text

  Copy

  Full Release Validation
  workflow before release approval to kick off all pre-release test boxes from one entrypoint. It accepts a branch, tag, or full commit SHA, dispatches manual
  text

  Copy

  CI
  , and dispatches
  text

  Copy

  OpenClaw Release Checks
  for install smoke, package acceptance, Docker release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix, and Telegram lanes. Provide
  text

  Copy

  npm_telegram_package_spec
  only after a package has been published and the post-publish Telegram E2E should run too. Provide
  text

  Copy

  evidence_package_spec
  when the private evidence report should prove that the validation matches a published npm package without forcing Telegram E2E. Example:
  text

  Copy

  gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D
• Run the manual
  text

  Copy

  Package Acceptance
  workflow when you want side-channel proof for a package candidate while release work continues. Use
  text

  Copy

  source=npm
  for
  text

  Copy

  openclaw@beta
  ,
  text

  Copy

  openclaw@latest
  , or an exact release version;
  text

  Copy

  source=ref
  to pack a trusted
  text

  Copy

  package_ref
  branch/tag/SHA with the current
  text

  Copy

  workflow_ref
  harness;
  text

  Copy

  source=url
  for an HTTPS tarball with a required SHA-256; or
  text

  Copy

  source=artifact
  for a tarball uploaded by another GitHub Actions run. The workflow resolves the candidate to
  text

  Copy

  package-under-test
  , reuses the Docker E2E release scheduler against that tarball, and can run Telegram QA against the same tarball with
  text

  Copy

  telegram_mode=mock-openai
  or
  text

  Copy

  telegram_mode=live-frontier
  . When the selected Docker lanes include
  text

  Copy

  published-upgrade-survivor
  , the package artifact is the candidate and
  text

  Copy

  published_upgrade_survivor_baseline
  selects the published baseline. Example:
  text

  Copy

  gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai
  Common profiles:
  • text

    Copy

    smoke
    : install/channel/agent, gateway network, and config reload lanes
  • text

    Copy

    package
    : artifact-native package/update/plugin lanes without OpenWebUI or live ClawHub
  • text

    Copy

    product
    : package profile plus MCP channels, cron/subagent cleanup, OpenAI web search, and OpenWebUI
  • text

    Copy

    full
    : Docker release-path chunks with OpenWebUI
  • text

    Copy

    custom
    : exact
    text

    Copy

    docker_lanes
    selection for a focused rerun
• Run the manual
  text

  Copy

  CI
  workflow directly when you only need full normal CI coverage for the release candidate. Manual CI dispatches bypass changed scoping and force the Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility,
  text

  Copy

  check
  ,
  text

  Copy

  check-additional
  , build smoke, docs checks, Python skills, Windows, macOS, Android, and Control UI i18n lanes. Example:
  text

  Copy

  gh workflow run ci.yml --ref release/YYYY.M.D
• Run
  text

  Copy

  pnpm qa:otel:smoke
  when validating release telemetry. It exercises QA-lab through a local OTLP/HTTP receiver and verifies the exported trace span names, bounded attributes, and content/identifier redaction without requiring Opik, Langfuse, or another external collector.
• Run
  text

  Copy

  pnpm release:check
  before every tagged release
• Release checks now run in a separate manual workflow:
  text

  Copy

  OpenClaw Release Checks
• text

  Copy

  OpenClaw Release Checks
  also runs the QA Lab mock parity gate plus the fast live Matrix profile and Telegram QA lane before release approval. The live lanes use the
  text

  Copy

  qa-live-shared
  environment; Telegram also uses Convex CI credential leases. Run the manual
  text

  Copy

  QA-Lab - All Lanes
  workflow with
  text

  Copy

  matrix_profile=all
  and
  text

  Copy

  matrix_shards=true
  when you want full Matrix transport, media, and E2EE inventory in parallel.
• Cross-OS install and upgrade runtime validation is part of public
  text

  Copy

  OpenClaw Release Checks
  and
  text

  Copy

  Full Release Validation
  , which call the reusable workflow
  text

  Copy

  .github/workflows/openclaw-cross-os-release-checks-reusable.yml
  directly
• 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
• Secret-bearing release checks should be dispatched through
  text

  Copy

  Full Release Validation
  or from the
  text

  Copy

  main
  /release workflow ref so workflow logic and secrets stay controlled
• text

  Copy

  OpenClaw Release Checks
  accepts a branch, tag, or full commit SHA as long as the resolved commit is reachable from an OpenClaw branch or release tag
• text

  Copy

  OpenClaw NPM Release
  validation-only preflight also accepts the current full 40-character workflow-branch 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
  text

  Copy

  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
  text

  Copy

  OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache
  using both
  text

  Copy

  OPENAI_API_KEY
  and
  text

  Copy

  ANTHROPIC_API_KEY
  workflow secrets
• npm release preflight no longer waits on the separate release checks lane
• Run
  text

  Copy

  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
  text

  Copy

  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
• After a beta publish, run
  text

  Copy

  OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live
  to verify installed-package onboarding, Telegram setup, and real Telegram E2E against the published npm package using the shared leased Telegram credential pool. Local maintainer one-offs may omit the Convex vars and pass the three
  text

  Copy

  OPENCLAW_QA_TELEGRAM_*
  env credentials directly.
• Maintainers can run the same post-publish check from GitHub Actions via the manual
  text

  Copy

  NPM Telegram Beta E2E
  workflow. It is intentionally manual-only and does not run on every merge.
• Maintainer release automation now uses preflight-then-promote:
  • real npm publish must pass a successful npm
    text

    Copy

    preflight_run_id
  • the real npm publish must be dispatched from the same
    text

    Copy

    main
    or
    text

    Copy

    release/YYYY.M.D
    branch as the successful preflight run
  • stable npm releases default to
    text

    Copy

    beta
  • stable npm publish can target
    text

    Copy

    latest
    explicitly via workflow input
  • token-based npm dist-tag mutation now lives in
    text

    Copy

    openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml
    for security, because
    text

    Copy

    npm dist-tag add
    still needs
    text

    Copy

    NPM_TOKEN
    while the public repo keeps OIDC-only publish
  • public
    text

    Copy

    macOS Release
    is validation-only; when a tag lives only on a release branch but the workflow is dispatched from
    text

    Copy

    main
    , set
    text

    Copy

    public_release_branch=release/YYYY.M.D
  • real private mac publish must pass successful private mac
    text

    Copy

    preflight_run_id
    and
    text

    Copy

    validate_run_id
  • the real publish paths promote prepared artifacts instead of rebuilding them again
• For stable correction releases like
  text

  Copy

  YYYY.M.D-N
  , the post-publish verifier also checks the same temp-prefix upgrade path from
  text

  Copy

  YYYY.M.D
  to
  text

  Copy

  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
  text

  Copy

  dist/control-ui/index.html
  and a non-empty
  text

  Copy

  dist/control-ui/assets/
  payload so we do not ship an empty browser dashboard again
• Post-publish verification also checks that the published registry install contains non-empty bundled plugin runtime deps under the root
  text

  Copy

  dist/*
  layout. A release that ships with missing or empty bundled plugin dependency payloads fails the postpublish verifier and cannot be promoted to
  text

  Copy

  latest
  .
• text

  Copy

  pnpm test:install:smoke
  also enforces the npm pack
  text

  Copy

  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
  text

  Copy

  plugin-prerelease-extension-shard
  matrix outputs from
  text

  Copy

  .github/workflows/plugin-prerelease.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
    text

    Copy

    .zip
    ,
    text

    Copy

    .dmg
    , and
    text

    Copy

    .dSYM.zip
  • text

    Copy

    appcast.xml
    on
    text

    Copy

    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
    text

    Copy

    CFBundleVersion
    at or above the canonical Sparkle build floor for that release version

Release test boxes

is how operators kick off all pre-release tests from one entrypoint. Run it from the trusted workflow ref and pass the release branch, tag, or full commit SHA as :

bash
Copy
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable \
  -f evidence_package_spec=openclaw@YYYY.M.D-beta.N

The workflow resolves the target ref, dispatches manual

with , dispatches , and optionally dispatches standalone post-publish Telegram E2E when is set. then fans out install smoke, cross-OS release checks, live/E2E Docker release-path coverage, Package Acceptance with Telegram package QA, QA Lab parity, live Matrix, and live Telegram. A full run is only acceptable when the summary shows and as successful, and any optional child is either successful or intentionally skipped. The final verifier summary includes slowest-job tables for each child run, so the release manager can see the current critical path without downloading logs. See Full release validation for the complete stage matrix, exact workflow job names, stable versus full profile differences, artifacts, and focused rerun handles. Child workflows are dispatched from the trusted ref that runs , normally , even when the target points at an older release branch or tag. There is no separate Full Release Validation workflow-ref input; choose the trusted harness by choosing the workflow run ref.

Use

to select live/provider breadth:

• text

  Copy

  minimum
  : fastest release-critical OpenAI/core live and Docker path
• text

  Copy

  stable
  : minimum plus stable provider/backend coverage for release approval
• text

  Copy

  full
  : stable plus broad advisory provider/media coverage

uses the trusted workflow ref to resolve the target ref once as and reuses that artifact in both release-path Docker checks and Package Acceptance. This keeps all package-facing boxes on the same bytes and avoids repeated package builds. The cross-OS OpenAI install smoke uses when the repo/org variable is set, otherwise , because this lane is proving package install, onboarding, gateway startup, and one live agent turn rather than benchmarking the slowest default model. The broader live provider matrix remains the place for model-specific coverage.

Use these variants depending on release stage:

bash
Copy
# Validate an unpublished release candidate branch.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.D \
  -f provider=openai \
  -f mode=both \
  -f release_profile=stable

# Validate an exact pushed commit.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=<40-char-sha> \
  -f provider=openai \
  -f mode=both

# After publishing a beta, add published-package Telegram E2E.
gh workflow run full-release-validation.yml \
  --ref main \
  -f ref=release/YYYY.M.D \
  -f provider=openai \
  -f mode=both \
  -f evidence_package_spec=openclaw@YYYY.M.D-beta.N \
  -f npm_telegram_package_spec=openclaw@YYYY.M.D-beta.N \
  -f npm_telegram_provider_mode=mock-openai

Do not use the full umbrella as the first rerun after a focused fix. If one box fails, use the failed child workflow, job, Docker lane, package profile, model provider, or QA lane for the next proof. Run the full umbrella again only when the fix changed shared release orchestration or made earlier all-box evidence stale. The umbrella's final verifier re-checks the recorded child workflow run ids, so after a child workflow is rerun successfully, rerun only the failed

parent job.

For bounded recovery, pass

to the umbrella. is the real release-candidate run, runs only the normal CI child, runs only the release-only plugin child, runs every release box, and the narrower release groups are , , , , , , , and when the standalone package Telegram lane is supplied.

Vitest

The Vitest box is the manual

child workflow. Manual CI intentionally bypasses changed scoping and forces the normal test graph for the release candidate: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, , , build smoke, docs checks, Python skills, Windows, macOS, Android, and Control UI i18n.

Use this box to answer "did the source tree pass the full normal test suite?" It is not the same as release-path product validation. Evidence to keep:

• text

  Copy

  Full Release Validation
  summary showing the dispatched
  text

  Copy

  CI
  run URL
• text

  Copy

  CI
  run green on the exact target SHA
• failed or slow shard names from the CI jobs when investigating regressions
• Vitest timing artifacts such as
  text

  Copy

  .artifacts/vitest-shard-timings.json
  when a run needs performance analysis

Run manual CI directly only when the release needs deterministic normal CI but not the Docker, QA Lab, live, cross-OS, or package boxes:

bash
Copy
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D

Docker

The Docker box lives in

through , plus the release-mode workflow. It validates the release candidate through packaged Docker environments instead of only source-level tests.

Release Docker coverage includes:

• full install smoke with the slow Bun global install smoke enabled
• root Dockerfile smoke image preparation/reuse by target SHA, with QR, root/gateway, and installer/Bun smoke jobs running as separate install-smoke shards
• repository E2E lanes
• release-path Docker chunks:
  text

  Copy

  core
  ,
  text

  Copy

  package-update-openai
  ,
  text

  Copy

  package-update-anthropic
  ,
  text

  Copy

  package-update-core
  ,
  text

  Copy

  plugins-runtime-plugins
  ,
  text

  Copy

  plugins-runtime-services
  ,
  text

  Copy

  plugins-runtime-install-a
  ,
  text

  Copy

  plugins-runtime-install-b
  ,
  text

  Copy

  plugins-runtime-install-c
  ,
  text

  Copy

  plugins-runtime-install-d
  ,
  text

  Copy

  plugins-runtime-install-e
  ,
  text

  Copy

  plugins-runtime-install-f
  ,
  text

  Copy

  plugins-runtime-install-g
  ,
  text

  Copy

  plugins-runtime-install-h
  ,
  text

  Copy

  bundled-channels-core
  ,
  text

  Copy

  bundled-channels-update-a
  ,
  text

  Copy

  bundled-channels-update-discord
  ,
  text

  Copy

  bundled-channels-update-b
  , and
  text

  Copy

  bundled-channels-contracts
• OpenWebUI coverage inside the
  text

  Copy

  plugins-runtime-services
  chunk when requested
• split bundled-channel dependency lanes across channel-smoke, update-target, and setup/runtime contract chunks instead of one large bundled-channel job
• split bundled plugin install/uninstall lanes
  text

  Copy

  bundled-plugin-install-uninstall-0
  through
  text

  Copy

  bundled-plugin-install-uninstall-23
• live/E2E provider suites and Docker live model coverage when release checks include live suites

Use Docker artifacts before rerunning. The release-path scheduler uploads

with lane logs, , , phase timings, scheduler plan JSON, and rerun commands. For focused recovery, use on the reusable live/E2E workflow instead of rerunning all release chunks. Generated rerun commands include prior and prepared Docker image inputs when available, so a failed lane can reuse the same tarball and GHCR images.

QA Lab

The QA Lab box is also part of

. It is the agentic behavior and channel-level release gate, separate from Vitest and Docker package mechanics.

Release QA Lab coverage includes:

• mock parity gate comparing the OpenAI candidate lane against the Opus 4.6 baseline using the agentic parity pack
• fast live Matrix QA profile using the
  text

  Copy

  qa-live-shared
  environment
• live Telegram QA lane using Convex CI credential leases
• text

  Copy

  pnpm qa:otel:smoke
  when release telemetry needs explicit local proof

Use this box to answer "does the release behave correctly in QA scenarios and live channel flows?" Keep the artifact URLs for parity, Matrix, and Telegram lanes when approving the release. Full Matrix coverage remains available as a manual sharded QA-Lab run rather than the default release-critical lane.

Package

The Package box is the installable-product gate. It is backed by

and the resolver . The resolver normalizes a candidate into the tarball consumed by Docker E2E, validates the package inventory, records the package version and SHA-256, and keeps the workflow harness ref separate from the package source ref.

Supported candidate sources:

• text

  Copy

  source=npm
  :
  text

  Copy

  openclaw@beta
  ,
  text

  Copy

  openclaw@latest
  , or an exact OpenClaw release version
• text

  Copy

  source=ref
  : pack a trusted
  text

  Copy

  package_ref
  branch, tag, or full commit SHA with the selected
  text

  Copy

  workflow_ref
  harness
• text

  Copy

  source=url
  : download an HTTPS
  text

  Copy

  .tgz
  with required
  text

  Copy

  package_sha256
• text

  Copy

  source=artifact
  : reuse a
  text

  Copy

  .tgz
  uploaded by another GitHub Actions run

runs Package Acceptance with , , , , and . The release-path Docker chunks cover the overlapping install, update, and plugin-update lanes; Package Acceptance keeps artifact-native bundled-channel compat, offline plugin fixtures, and Telegram package QA against the same resolved tarball. It is the GitHub-native replacement for most of the package/update coverage that previously required Parallels. Cross-OS release checks still matter for OS-specific onboarding, installer, and platform behavior, but package/update product validation should prefer Package Acceptance.

Legacy package-acceptance leniency is intentionally time boxed. Packages through

may use the compatibility path for metadata gaps already published to npm: private QA inventory entries missing from the tarball, missing , missing patch files in the tarball-derived git fixture, missing persisted , legacy plugin install-record locations, missing marketplace install-record persistence, and config metadata migration during . The published package may warn for local build metadata stamp files that were already shipped. Later packages must satisfy the modern package contracts; those same gaps fail release validation.

Use broader Package Acceptance profiles when the release question is about an actual installable package:

bash
Copy
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f published_upgrade_survivor_baseline=openclaw@2026.4.26

Common package profiles:

• text

  Copy

  smoke
  : quick package install/channel/agent, gateway network, and config reload lanes
• text

  Copy

  package
  : install/update/plugin package contracts without live ClawHub; this is the release-check default
• text

  Copy

  product
  :
  text

  Copy

  package
  plus MCP channels, cron/subagent cleanup, OpenAI web search, and OpenWebUI
• text

  Copy

  full
  : Docker release-path chunks with OpenWebUI
• text

  Copy

  custom
  : exact
  text

  Copy

  docker_lanes
  list for focused reruns

For package-candidate Telegram proof, enable

or on Package Acceptance. The workflow passes the resolved tarball into the Telegram lane; the standalone Telegram workflow still accepts a published npm spec for post-publish checks.

NPM workflow inputs

accepts these operator-controlled inputs:

• text

  Copy

  tag
  : required release tag such as
  text

  Copy

  v2026.4.2
  ,
  text

  Copy

  v2026.4.2-1
  , or
  text

  Copy

  v2026.4.2-beta.1
  ; when
  text

  Copy

  preflight_only=true
  , it may also be the current full 40-character workflow-branch commit SHA for validation-only preflight
• text

  Copy

  preflight_only
  :
  text

  Copy

  true
  for validation/build/package only,
  text

  Copy

  false
  for the real publish path
• text

  Copy

  preflight_run_id
  : required on the real publish path so the workflow reuses the prepared tarball from the successful preflight run
• text

  Copy

  npm_dist_tag
  : npm target tag for the publish path; defaults to
  text

  Copy

  beta

accepts these operator-controlled inputs:

• text

  Copy

  ref
  : branch, tag, or full commit SHA to validate. Secret-bearing checks require the resolved commit to be reachable from an OpenClaw branch or release tag.

Rules:

• Stable and correction tags may publish to either
  text

  Copy

  beta
  or
  text

  Copy

  latest
• Beta prerelease tags may publish only to
  text

  Copy

  beta
• For
  text

  Copy

  OpenClaw NPM Release
  , full commit SHA input is allowed only when
  text

  Copy

  preflight_only=true
• text

  Copy

  OpenClaw Release Checks
  and
  text

  Copy

  Full Release Validation
  are always validation-only
• The real publish path must use the same
  text

  Copy

  npm_dist_tag
  used during preflight; the workflow verifies that metadata before publish continues

Stable npm release sequence

When cutting a stable npm release:

1. Run
   text

   Copy

   OpenClaw NPM Release
   with
   text

   Copy

   preflight_only=true
   • Before a tag exists, you may use the current full workflow-branch commit SHA for a validation-only dry run of the preflight workflow
2. Choose
   text

   Copy

   npm_dist_tag=beta
   for the normal beta-first flow, or
   text

   Copy

   latest
   only when you intentionally want a direct stable publish
3. Run
   text

   Copy

   Full Release Validation
   on the release branch, release tag, or full commit SHA when you want normal CI plus live prompt cache, Docker, QA Lab, Matrix, and Telegram coverage from one manual workflow
4. If you intentionally only need the deterministic normal test graph, run the manual
   text

   Copy

   CI
   workflow on the release ref instead
5. Save the successful
   text

   Copy

   preflight_run_id
6. Run
   text

   Copy

   OpenClaw NPM Release
   again with
   text

   Copy

   preflight_only=false
   , the same
   text

   Copy

   tag
   , the same
   text

   Copy

   npm_dist_tag
   , and the saved
   text

   Copy

   preflight_run_id
7. If the release landed on
   text

   Copy

   beta
   , use the private
   text

   Copy

   openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml
   workflow to promote that stable version from
   text

   Copy

   beta
   to
   text

   Copy

   latest
8. If the release intentionally published directly to
   text

   Copy

   latest
   and
   text

   Copy

   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
   text

   Copy

   beta
   later

The dist-tag mutation lives in the private repo for security because it still requires

, while the public repo keeps OIDC-only publish.

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

If a maintainer must fall back to local npm authentication, run any 1Password CLI (

) commands only inside a dedicated tmux session. Do not call directly from the main agent shell; keeping it inside tmux makes prompts, alerts, and OTP handling observable and prevents repeated host alerts.

Public references

• text

  Copy

  .github/workflows/full-release-validation.yml
• text

  Copy

  .github/workflows/package-acceptance.yml
• text

  Copy

  .github/workflows/openclaw-npm-release.yml
• text

  Copy

  .github/workflows/openclaw-release-checks.yml
• text

  Copy

  .github/workflows/openclaw-cross-os-release-checks-reusable.yml
• text

  Copy

  scripts/resolve-openclaw-package-candidate.mjs
• text

  Copy

  scripts/openclaw-npm-release-check.ts
• text

  Copy

  scripts/package-mac-dist.sh
• text

  Copy

  scripts/make_appcast.sh

Maintainers use the private release docs in

for the actual runbook.

Related

• Release channels