Release policy

Release policy 문서는 OpenClaw 공식 문서(reference/RELEASING)를 한국어로 정리한 가이드입니다. Release lanes, operator checklist, validation boxes, version naming, and cadence 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Release lanes, operator checklist, validation boxes, version naming, and cadence

한국어 가이드 범위: reference/RELEASING 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Version naming
Release cadence
Monthly Gateway extended-stable publication
Prepare and stabilize the candidate
Publish the npm packages
Verify and recover
Regular release operator checklist
Stable main closeout
Release preflight
Release test boxes
Validate the product-complete Code SHA.
Validate the changelog-only Release SHA by reusing Code SHA product evidence.
After publishing a beta, add published-package Telegram E2E.
Vitest
Docker
QA Lab
Package
Regular release publish automation
NPM workflow inputs
Regular beta/latest stable release sequence
Public references
관련 문서

상세 내용

본문

OpenClaw exposes four user-facing update channels:

주요 항목:

stable: the promoted regular release on npm latest
extended-stable: the trailing completed month's .33+ maintenance line on
beta: prerelease tags on npm beta
dev: the moving head of main

Version naming

and its Docker images at one exact version; see the dedicated workflow below.

주요 항목:

Monthly Gateway extended-stable release version: YYYY.M.PATCH, with PATCH >= 33, git tag vYYYY.M.PATCH
Daily/regular final release version: YYYY.M.PATCH, with PATCH < 33, git tag vYYYY.M.PATCH
Regular fallback correction release version: YYYY.M.PATCH-N, git tag vYYYY.M.PATCH-N
Beta prerelease version: YYYY.M.PATCH-beta.N, git tag vYYYY.M.PATCH-beta.N
Alpha prerelease version: YYYY.M.PATCH-alpha.N, git tag vYYYY.M.PATCH-alpha.N
Never zero-pad month or patch
PATCH is a sequential monthly release-train number, not a calendar day. Regular final and beta releases advance the current train; alpha-only tags never consume or advance the beta/regular patch number, so ignore legacy alpha-only tags with higher patch numbers when selecting a beta or regular train.
Alpha/nightly builds use the next unreleased patch train and increment only alpha.N for repeated builds. Once that patch has a beta, new alpha builds move to the following patch.
npm versions are immutable: never delete, republish, or reuse a published tag. Cut the next prerelease number or the next monthly patch instead.
latest continues to follow the current regular/daily npm line; beta is the current beta install target
extended-stable means the supported trailing-month Gateway distribution, beginning at patch 33; patch 34 and later are maintenance releases on that monthly line
Regular final and regular correction releases publish to npm beta by default; release operators can target latest explicitly, or promote a vetted beta build later
Gateway extended-stable publishes core, every npm-publishable official plugin,
Every regular final release ships the npm package, macOS app, signed standalone Android APK, and signed Windows Hub installers together. Beta releases normally validate and publish the npm/package path first, with native app build/sign/notarize/promote reserved for regular final unless explicitly requested.

Release cadence

주요 항목:

Releases move beta-first; stable follows only after the latest beta is validated
Maintainers normally cut releases from a release/YYYY.M.PATCH branch created from current main, so release validation and fixes do not block new development on main
If a beta tag has been pushed or published and needs a fix, maintainers cut the next -beta.N tag instead of deleting or recreating the old one
Detailed release procedure, approvals, credentials, and recovery notes are maintainer-only

Monthly Gateway extended-stable publication

For completed month YYYY.M, create extended-stable/YYYY.M.33 and publish .33+ from that branch. Tag, branch, checkout, package version, preflight, and validation must identify one commit. Before .33, protected main must contain a later month's final version below patch 33; later maintenance patches remain eligible.

Prepare and stabilize the candidate

Audit the unaudited mainline range, reconcile private security work, approve a bounded backport set, and land one coordinated PR. Do not push the canonical branch directly.

주요 항목:

Product: land another approved backport PR.
Frozen-target tooling: backport only the smallest compatibility repair that
Provider, approval, runner, or service: keep the candidate unchanged and use

RELEASE_SHA="$(git rev-parse HEAD)"

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag="$RELEASE_SHA" \
  -f preflight_only=true \
  -f npm_dist_tag=extended-stable

gh workflow run full-release-validation.yml \
  --ref extended-stable/YYYY.M.33 \
  -f ref=extended-stable/YYYY.M.33 \
  -f release_profile=stable

Publish the npm packages

Publish every npm-publishable official plugin from the same SHA and save the successful run ID:

RELEASE_SHA="$(git rev-parse HEAD)"
gh workflow run plugin-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f publish_scope=all-publishable \
  -f ref="$RELEASE_SHA" \
  -f npm_dist_tag=extended-stable

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=false \
  -f npm_dist_tag=extended-stable \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f full_release_validation_run_attempt=<full-validation-run-attempt> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

Verify and recover

From a separate clean current-main checkout, not the frozen branch, run:

node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P
npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

Regular 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.

pnpm release:candidate -- \
     --tag vYYYY.M.PATCH-beta.N \
     --full-release-run <release-sha-validation-run-id> \
     --npm-preflight-run <preflight-run-id> \
     --skip-dispatch

Stable main closeout

Stable publication is not complete until main carries the actual shipped release state.

Release preflight

Provide release_package_spec after publishing a beta to reuse the shipped npm package across release checks, Package Acceptance, and package Telegram E2E without rebuilding the release tarball. Provide npm_telegram_package_spec only when Telegram should use a different published package from the rest of release validation. Provide package_acceptance_package_spec when Package Acceptance should use a different published package from the release package spec. Provide evidence_package_spec when the release evidence report should prove that validation matches a published npm package without forcing Telegram E2E.

주요 항목:

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:prep after the root version bump and before tagging. It runs every deterministic release generator that commonly drifts after a version/config/API change: plugin versions, npm shrinkwraps, plugin inventory, base config schema, bundled channel config metadata, config docs baseline, plugin SDK exports, the Plugin SDK API contract manifest, and Control UI locale bundles. It also blocks until native app translations and platform-generated locale resources match the source inventory; if they lag, wait for or dispatch Native App Locale Refresh before freezing the Code SHA. pnpm release:check re-runs those guards in check mode (including the strict locale gates plus the plugin SDK surface budget) and reports every generated drift failure in one pass before running package release checks.
Plugin version sync updates the publishable @openclaw/ai runtime package, official plugin package versions, and existing openclaw.compat.pluginApi floors to the OpenClaw release version by default. Treat that field as the plugin SDK/runtime API floor, not just a copy of the package version: for plugin-only releases that intentionally remain compatible with older OpenClaw hosts, keep the floor at the oldest supported host API and document that choice in the plugin release proof.
Run the manual 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 CI, and dispatches OpenClaw Release Checks for install smoke, package acceptance, cross-OS package checks, QA Lab parity, Matrix, and Telegram lanes. Stable and full runs always include exhaustive live/E2E and Docker release-path soak; run_release_soak=true is retained for an explicit beta soak. Package Acceptance provides the canonical package Telegram E2E during candidate validation, avoiding a second concurrent live poller.
Run the manual Package Acceptance workflow when you want side-channel proof for a package candidate while release work continues. Use source=npm for openclaw@beta, openclaw@latest, or an exact release version; source=ref to pack a trusted package_ref branch/tag/SHA with the current workflow_ref harness; source=url for a public HTTPS tarball with a required SHA-256 and strict public URL policy; source=trusted-url for a named trusted-source policy using required trusted_source_id and SHA-256; or source=artifact for a tarball uploaded by another GitHub Actions run.
smoke: install/channel/agent, gateway network, and config reload lanes
package: artifact-native package/update/restart/plugin lanes without OpenWebUI or live ClawHub
product: package profile plus MCP channels, cron/subagent cleanup, OpenAI web search, and OpenWebUI
full: Docker release-path chunks with OpenWebUI
custom: exact docker_lanes selection for a focused rerun
Run the manual CI workflow directly when you only need deterministic normal CI coverage for the release candidate. Manual CI dispatches bypass changed scoping and force the Linux Node shards, bundled-plugin shards, plugin and channel contract shards, Node 22 compatibility, check-*, check-additional-*, built-artifact smoke checks, docs checks, Python skills, Windows, macOS, and Control UI i18n lanes. Standalone manual CI runs Android only when dispatched with include_android=true; Full Release Validation passes that input for its CI child.
Run pnpm qa:otel:smoke when validating release telemetry. It exercises QA-lab through a local OTLP/HTTP receiver and verifies trace, metric, and log export plus bounded trace attributes and content/identifier redaction without requiring Opik, Langfuse, or another external collector.
Run pnpm qa:otel:collector-smoke when validating collector compatibility. It routes the same QA-lab OTLP export through a real OpenTelemetry Collector Docker container before the local receiver assertions.
Run pnpm qa:prometheus:smoke when validating protected Prometheus scraping. It exercises QA-lab, rejects unauthenticated scrapes, and verifies release-critical metric families stay free of prompt content, raw identifiers, auth tokens, and local paths.
Run pnpm qa:observability:smoke for the source-checkout OpenTelemetry and Prometheus smoke lanes back to back.
Run pnpm release:check before every tagged release.
OpenClaw NPM Release preflight generates dependency release evidence before it packs the npm tarball. The npm advisory vulnerability gate is release-blocking. The transitive manifest risk, dependency ownership/install surface, and dependency change reports are release evidence only. The dependency change report compares the release candidate with the previous reachable release tag. The preflight uploads dependency evidence as openclaw-release-dependency-evidence-<tag> and also embeds it under dependency-evidence/ inside the prepared npm preflight artifact. The real publish path reuses that preflight artifact, then attaches the same evidence to the GitHub release as openclaw-<version>-dependency-evidence.zip.
Run OpenClaw Release Publish for the mutating publish sequence after the tag exists. Dispatch regular beta and stable publishes from trusted main; the release tag still selects the exact target commit and may point into release/YYYY.M.PATCH. Tideclaw alpha publishes remain on their matching alpha branch. Pass the successful OpenClaw npm preflight_run_id, successful full_release_validation_run_id, and exact full_release_validation_run_attempt, and keep the default plugin publish scope all-publishable unless you are deliberately running a focused repair. The workflow serializes plugin npm publish, plugin ClawHub publish, and OpenClaw npm publish so the core package is not published before its externalized plugins; Windows and Android promotion runs concurrently with the core npm publish against the draft release page. Publish reruns are resumable: an already-published core npm version skips the core dispatch after the workflow proves the registry tarball matches the tag's preflight artifact, and Windows/Android promotion is skipped when the release already carries the verified asset contract, so a retry only redoes the failed stages. Focused plugin-only repairs require plugin_publish_scope=selected and a nonempty plugin list. Plugin-only all-publishable runs require complete immutable preflight and Full Release Validation evidence; partial evidence is rejected.
Stable OpenClaw Release Publish requires an exact windows_node_tag after the matching non-prerelease openclaw/openclaw-windows-node release exists, plus the candidate-approved windows_node_installer_digests map. Before dispatching any publish child, it verifies that source release is published, non-prerelease, contains the required x64/ARM64 installers, and still matches that approved map. It then dispatches Windows Node Release while the OpenClaw release is still a draft, carrying the pinned installer digest map unchanged. The child workflow downloads the signed Windows Hub installers from that exact tag, matches them against the pinned digests, verifies their Authenticode signatures use the expected OpenClaw Foundation signer on a Windows runner, writes a SHA-256 manifest, and uploads the installers plus manifest onto the canonical OpenClaw GitHub release, then re-downloads the promoted assets and verifies manifest membership and hashes. The parent verifies the current x64, ARM64, and checksum asset contract before publication. Direct recovery rejects unexpected OpenClawCompanion-* asset names before replacing the expected contract assets with the pinned source bytes.
Release checks now run in a separate manual workflow: OpenClaw Release Checks. It also runs the QA Lab mock parity lane plus the Matrix release profile and Telegram QA lane before release approval. The live lanes use the qa-live-shared environment; Telegram also uses Convex CI credential leases. Run the manual QA-Lab - All Lanes workflow with matrix_profile=all when you want every maintained Matrix scenario; the workflow fans that selection across the transport, media, and E2EE profiles to keep full proof within per-job timeouts.
Cross-OS install and upgrade runtime validation is part of public OpenClaw Release Checks and Full Release Validation, which call the reusable workflow .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 Full Release Validation or from the main/release workflow ref so workflow logic and secrets stay controlled.
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.

node scripts/full-release-validation-at-sha.mjs \
    --sha <code-sha> \
    --target-ref release/YYYY.M.PATCH

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

gh workflow run ci.yml --ref release/YYYY.M.PATCH -f include_android=true

Release test boxes

Full Release Validation is how operators kick off the full product matrix from one entrypoint. Use the helper so every child workflow runs from a temporary branch fixed at one trusted main workflow SHA while the requested commit remains the candidate under test:

주요 항목:

beta: fastest release-critical OpenAI/core live and Docker path
stable: beta plus stable provider/backend coverage for release approval
full: stable plus broad advisory provider/media coverage

pnpm ci:full-release \
  --sha <code-sha> \
  --target-ref release/YYYY.M.PATCH

pnpm ci:full-release \
  --sha <release-sha> \
  --target-ref release/YYYY.M.PATCH

Validate the product-complete Code SHA.

pnpm ci:full-release
--sha
--target-ref release/YYYY.M.PATCH

Validate the changelog-only Release SHA by reusing Code SHA product evidence.

pnpm ci:full-release
--sha
--target-ref release/YYYY.M.PATCH

After publishing a beta, add published-package Telegram E2E.

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 Verify full validation parent job.

Vitest

The Vitest box is the manual CI child workflow. Manual CI intentionally bypasses changed scoping and forces the normal test graph for the release candidate: Linux Node shards, bundled-plugin shards, plugin and channel contract shards, Node 22 compatibility, check-*, check-additional-*, built-artifact smoke checks, docs checks, Python skills, Windows, macOS, and Control UI i18n. Android is included when Full Release Validation runs the box because the umbrella passes include_android=true; standalone manual CI requires include_android=true for Android coverage.

주요 항목:

Full Release Validation summary showing the dispatched CI run URL
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 .artifacts/vitest-shard-timings.json when a run needs performance analysis

gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH -f include_android=true

Docker

The Docker box lives in OpenClaw Release Checks through openclaw-live-and-e2e-checks-reusable.yml, plus the release-mode install-smoke workflow. It validates the release candidate through packaged Docker environments instead of only source-level tests.

주요 항목:

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: core, package-update-openai, package-update-anthropic, package-update-core, plugins-runtime-plugins, plugins-runtime-services, plugins-runtime-install-a through plugins-runtime-install-h, and openwebui
OpenWebUI coverage on a dedicated large-disk runner when requested
split bundled plugin install/uninstall lanes bundled-plugin-install-uninstall-0 through bundled-plugin-install-uninstall-23
live/E2E provider suites and Docker live model coverage when release checks include live suites

QA Lab

The QA Lab box is also part of OpenClaw Release Checks. It is the agentic behavior and channel-level release gate, separate from Vitest and Docker package mechanics.

주요 항목:

mock parity lane comparing the OpenAI candidate lane against the anthropic/claude-opus-4-8 baseline using the agentic parity pack
Matrix live-adapter release profile using the qa-live-shared environment
live Telegram QA lane using Convex CI credential leases
pnpm qa:otel:smoke, pnpm qa:otel:collector-smoke, pnpm qa:prometheus:smoke, or pnpm qa:observability:smoke when release telemetry needs explicit local proof

Package

The Package box is the installable-product gate. It is backed by Package Acceptance and the resolver scripts/resolve-openclaw-package-candidate.mjs. The resolver normalizes a candidate into the package-under-test 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.

주요 항목:

source=npm: openclaw@beta, openclaw@latest, or an exact OpenClaw release version
source=ref: pack a trusted package_ref branch, tag, or full commit SHA with the selected workflow_ref harness
source=url: download a public HTTPS .tgz with required package_sha256; URL credentials, non-default HTTPS ports, private/internal/special-use hostnames or resolved addresses, and unsafe redirects are rejected
source=trusted-url: download an HTTPS .tgz with required package_sha256 and trusted_source_id from a named policy in .github/package-trusted-sources.json; use this for maintainer-owned enterprise mirrors or private package repositories instead of adding an input-level private-network bypass to source=url
source=artifact: reuse a .tgz uploaded by another GitHub Actions run
smoke: quick package install/channel/agent, gateway network, and config reload lanes
package: install/update/restart/plugin package contracts plus live ClawHub skill install proof; this is the release-check default
product: package plus MCP channels, cron/subagent cleanup, OpenAI web search, and OpenWebUI
full: Docker release-path chunks with OpenWebUI
custom: exact docker_lanes list for focused reruns

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

Regular release publish automation

For beta, latest, plugin, GitHub Release, and platform publication, OpenClaw Release Publish is the normal mutating entrypoint. The monthly .33+ Gateway extended-stable path does not use this orchestrator. The regular workflow orchestrates the trusted-publisher workflows in the order the release needs:

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.PATCH-beta.N \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=latest

gh workflow run plugin-clawhub-new.yml \
  --ref main \
  -f plugins=@openclaw/name \
  -f ref=<full-40-character-release-sha> \
  -f pretag_validation=true \
  -f dry_run=true

NPM workflow inputs

OpenClaw NPM Release accepts these operator-controlled inputs:

주요 항목:

tag: required release tag such as v2026.4.2, v2026.4.2-1, v2026.4.2-beta.1, or v2026.4.2-alpha.1; when preflight_only=true, it may also be the current full 40-character workflow-branch commit SHA for validation-only preflight
preflight_only: true for validation/build/package only, false for the real publish path
preflight_run_id: existing successful preflight run id, required on the real publish path so the workflow reuses the prepared tarball instead of rebuilding it
full_release_validation_run_id: successful Full Release Validation run id for this tag/SHA, required for real publish. Beta publishes may proceed on preflight alone with a warning, but stable/latest promotion still requires it.
full_release_validation_run_attempt: exact positive run attempt paired with full_release_validation_run_id; required whenever the run id is provided so reruns cannot change the authorization evidence during publish.
release_publish_run_id: approved OpenClaw Release Publish run id; required when this workflow is dispatched by that parent (bot-actor real-publish calls)
plugin_npm_run_id: successful exact-head Plugin NPM Release run id; required for a real extended-stable core publish
npm_dist_tag: npm target tag for the publish path; accepts alpha, beta, latest, or extended-stable and defaults to beta. Final patch 33 and later must use extended-stable; by default, extended-stable rejects earlier patches, and it always rejects non-final tags.
bypass_extended_stable_guard: testing-only boolean, default false; with npm_dist_tag=extended-stable, bypasses monthly extended-stable eligibility while preserving release identity, artifact, approval, and readback checks.
tag: required release tag; must already exist
preflight_run_id: successful OpenClaw NPM Release preflight run id; required when publish_openclaw_npm=true or plugin_publish_scope=all-publishable
full_release_validation_run_id: successful Full Release Validation run id; required when publish_openclaw_npm=true or plugin_publish_scope=all-publishable
full_release_validation_run_attempt: exact positive attempt paired with full_release_validation_run_id; required whenever the run id is provided
windows_node_tag: exact non-prerelease openclaw/openclaw-windows-node release tag; required for stable OpenClaw publish
windows_node_installer_digests: candidate-approved compact JSON map of the current Windows installer names to their pinned sha256: digests; required for stable OpenClaw publish
npm_telegram_run_id: optional successful NPM Telegram Beta E2E run id to include in final release evidence
npm_dist_tag: npm target tag for the OpenClaw package, one of alpha, beta, or latest
plugin_publish_scope: defaults to all-publishable; use selected only for focused plugin-only repair work with publish_openclaw_npm=false
plugins: comma-separated @openclaw/* package names when plugin_publish_scope=selected
publish_openclaw_npm: defaults to true; set false only when using the workflow as a plugin-only repair orchestrator
release_profile: release coverage profile used for release evidence summaries; defaults to from-validation, which reads it from the validation manifest, or override with beta, stable, or full
wait_for_clawhub: defaults to false so npm availability is not blocked by the ClawHub sidecar; set true only when workflow completion must include ClawHub completion
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.
run_release_soak: opt into exhaustive live/E2E, Docker release-path, and all-since upgrade-survivor soak for beta release checks. It is forced on by release_profile=stable and release_profile=full.
Regular final and correction versions below patch 33 may publish to either beta or latest. Final versions at patch 33 or above must publish to extended-stable, and correction-suffix versions at that boundary are rejected.

Regular beta/latest stable release sequence

This legacy sequence is for the regular orchestrated release that also owns plugins, GitHub Release, Windows, and other platform work. It is not the monthly .33+ Gateway extended-stable path documented at the top of this page.

Public references

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

주요 항목:

.github/workflows/full-release-validation.yml
.github/workflows/package-acceptance.yml
.github/workflows/openclaw-npm-release.yml
.github/workflows/openclaw-release-checks.yml
.github/workflows/openclaw-cross-os-release-checks-reusable.yml
.github/workflows/docker-release.yml
scripts/resolve-openclaw-package-candidate.mjs
scripts/openclaw-npm-release-check.ts
scripts/package-mac-dist.sh
scripts/make_appcast.sh

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/RELEASING
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

RELEASE_SHA="$(git rev-parse HEAD)"

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag="$RELEASE_SHA" \
  -f preflight_only=true \
  -f npm_dist_tag=extended-stable

gh workflow run full-release-validation.yml \
  --ref extended-stable/YYYY.M.33 \
  -f ref=extended-stable/YYYY.M.33 \
  -f release_profile=stable

RELEASE_SHA="$(git rev-parse HEAD)"
gh workflow run plugin-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f publish_scope=all-publishable \
  -f ref="$RELEASE_SHA" \
  -f npm_dist_tag=extended-stable

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=false \
  -f npm_dist_tag=extended-stable \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f full_release_validation_run_attempt=<full-validation-run-attempt> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P
npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

pnpm release:candidate -- \
     --tag vYYYY.M.PATCH-beta.N \
     --full-release-run <release-sha-validation-run-id> \
     --npm-preflight-run <preflight-run-id> \
     --skip-dispatch

node scripts/full-release-validation-at-sha.mjs \
    --sha <code-sha> \
    --target-ref release/YYYY.M.PATCH

Release policy

핵심 요약

Release lanes, operator checklist, validation boxes, version naming, and cadence

한국어 가이드 범위: reference/RELEASING 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Version naming
Release cadence
Monthly Gateway extended-stable publication
Prepare and stabilize the candidate
Publish the npm packages
Verify and recover
Regular release operator checklist
Stable main closeout
Release preflight
Release test boxes
Validate the product-complete Code SHA.
Validate the changelog-only Release SHA by reusing Code SHA product evidence.
After publishing a beta, add published-package Telegram E2E.
Vitest
Docker
QA Lab
Package
Regular release publish automation
NPM workflow inputs
Regular beta/latest stable release sequence
Public references
관련 문서

상세 내용

본문

OpenClaw exposes four user-facing update channels:

주요 항목:

stable: the promoted regular release on npm latest
extended-stable: the trailing completed month's .33+ maintenance line on
beta: prerelease tags on npm beta
dev: the moving head of main

Version naming

and its Docker images at one exact version; see the dedicated workflow below.

주요 항목:

Monthly Gateway extended-stable release version: YYYY.M.PATCH, with PATCH >= 33, git tag vYYYY.M.PATCH
Daily/regular final release version: YYYY.M.PATCH, with PATCH < 33, git tag vYYYY.M.PATCH
Regular fallback correction release version: YYYY.M.PATCH-N, git tag vYYYY.M.PATCH-N
Beta prerelease version: YYYY.M.PATCH-beta.N, git tag vYYYY.M.PATCH-beta.N
Alpha prerelease version: YYYY.M.PATCH-alpha.N, git tag vYYYY.M.PATCH-alpha.N
Never zero-pad month or patch
PATCH is a sequential monthly release-train number, not a calendar day. Regular final and beta releases advance the current train; alpha-only tags never consume or advance the beta/regular patch number, so ignore legacy alpha-only tags with higher patch numbers when selecting a beta or regular train.
Alpha/nightly builds use the next unreleased patch train and increment only alpha.N for repeated builds. Once that patch has a beta, new alpha builds move to the following patch.
npm versions are immutable: never delete, republish, or reuse a published tag. Cut the next prerelease number or the next monthly patch instead.
latest continues to follow the current regular/daily npm line; beta is the current beta install target
extended-stable means the supported trailing-month Gateway distribution, beginning at patch 33; patch 34 and later are maintenance releases on that monthly line
Regular final and regular correction releases publish to npm beta by default; release operators can target latest explicitly, or promote a vetted beta build later
Gateway extended-stable publishes core, every npm-publishable official plugin,
Every regular final release ships the npm package, macOS app, signed standalone Android APK, and signed Windows Hub installers together. Beta releases normally validate and publish the npm/package path first, with native app build/sign/notarize/promote reserved for regular final unless explicitly requested.

Release cadence

주요 항목:

Releases move beta-first; stable follows only after the latest beta is validated
Maintainers normally cut releases from a release/YYYY.M.PATCH branch created from current main, so release validation and fixes do not block new development on main
If a beta tag has been pushed or published and needs a fix, maintainers cut the next -beta.N tag instead of deleting or recreating the old one
Detailed release procedure, approvals, credentials, and recovery notes are maintainer-only

Monthly Gateway extended-stable publication

Prepare and stabilize the candidate

Audit the unaudited mainline range, reconcile private security work, approve a bounded backport set, and land one coordinated PR. Do not push the canonical branch directly.

주요 항목:

Product: land another approved backport PR.
Frozen-target tooling: backport only the smallest compatibility repair that
Provider, approval, runner, or service: keep the candidate unchanged and use

RELEASE_SHA="$(git rev-parse HEAD)"

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag="$RELEASE_SHA" \
  -f preflight_only=true \
  -f npm_dist_tag=extended-stable

gh workflow run full-release-validation.yml \
  --ref extended-stable/YYYY.M.33 \
  -f ref=extended-stable/YYYY.M.33 \
  -f release_profile=stable

Publish the npm packages

Publish every npm-publishable official plugin from the same SHA and save the successful run ID:

RELEASE_SHA="$(git rev-parse HEAD)"
gh workflow run plugin-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f publish_scope=all-publishable \
  -f ref="$RELEASE_SHA" \
  -f npm_dist_tag=extended-stable

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=false \
  -f npm_dist_tag=extended-stable \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f full_release_validation_run_attempt=<full-validation-run-attempt> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

Verify and recover

From a separate clean current-main checkout, not the frozen branch, run:

node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P
npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

Regular 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.

pnpm release:candidate -- \
     --tag vYYYY.M.PATCH-beta.N \
     --full-release-run <release-sha-validation-run-id> \
     --npm-preflight-run <preflight-run-id> \
     --skip-dispatch

Stable main closeout

Stable publication is not complete until main carries the actual shipped release state.

Release preflight

주요 항목:

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:prep after the root version bump and before tagging. It runs every deterministic release generator that commonly drifts after a version/config/API change: plugin versions, npm shrinkwraps, plugin inventory, base config schema, bundled channel config metadata, config docs baseline, plugin SDK exports, the Plugin SDK API contract manifest, and Control UI locale bundles. It also blocks until native app translations and platform-generated locale resources match the source inventory; if they lag, wait for or dispatch Native App Locale Refresh before freezing the Code SHA. pnpm release:check re-runs those guards in check mode (including the strict locale gates plus the plugin SDK surface budget) and reports every generated drift failure in one pass before running package release checks.
Plugin version sync updates the publishable @openclaw/ai runtime package, official plugin package versions, and existing openclaw.compat.pluginApi floors to the OpenClaw release version by default. Treat that field as the plugin SDK/runtime API floor, not just a copy of the package version: for plugin-only releases that intentionally remain compatible with older OpenClaw hosts, keep the floor at the oldest supported host API and document that choice in the plugin release proof.
Run the manual 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 CI, and dispatches OpenClaw Release Checks for install smoke, package acceptance, cross-OS package checks, QA Lab parity, Matrix, and Telegram lanes. Stable and full runs always include exhaustive live/E2E and Docker release-path soak; run_release_soak=true is retained for an explicit beta soak. Package Acceptance provides the canonical package Telegram E2E during candidate validation, avoiding a second concurrent live poller.
Run the manual Package Acceptance workflow when you want side-channel proof for a package candidate while release work continues. Use source=npm for openclaw@beta, openclaw@latest, or an exact release version; source=ref to pack a trusted package_ref branch/tag/SHA with the current workflow_ref harness; source=url for a public HTTPS tarball with a required SHA-256 and strict public URL policy; source=trusted-url for a named trusted-source policy using required trusted_source_id and SHA-256; or source=artifact for a tarball uploaded by another GitHub Actions run.
smoke: install/channel/agent, gateway network, and config reload lanes
package: artifact-native package/update/restart/plugin lanes without OpenWebUI or live ClawHub
product: package profile plus MCP channels, cron/subagent cleanup, OpenAI web search, and OpenWebUI
full: Docker release-path chunks with OpenWebUI
custom: exact docker_lanes selection for a focused rerun
Run the manual CI workflow directly when you only need deterministic normal CI coverage for the release candidate. Manual CI dispatches bypass changed scoping and force the Linux Node shards, bundled-plugin shards, plugin and channel contract shards, Node 22 compatibility, check-*, check-additional-*, built-artifact smoke checks, docs checks, Python skills, Windows, macOS, and Control UI i18n lanes. Standalone manual CI runs Android only when dispatched with include_android=true; Full Release Validation passes that input for its CI child.
Run pnpm qa:otel:smoke when validating release telemetry. It exercises QA-lab through a local OTLP/HTTP receiver and verifies trace, metric, and log export plus bounded trace attributes and content/identifier redaction without requiring Opik, Langfuse, or another external collector.
Run pnpm qa:otel:collector-smoke when validating collector compatibility. It routes the same QA-lab OTLP export through a real OpenTelemetry Collector Docker container before the local receiver assertions.
Run pnpm qa:prometheus:smoke when validating protected Prometheus scraping. It exercises QA-lab, rejects unauthenticated scrapes, and verifies release-critical metric families stay free of prompt content, raw identifiers, auth tokens, and local paths.
Run pnpm qa:observability:smoke for the source-checkout OpenTelemetry and Prometheus smoke lanes back to back.
Run pnpm release:check before every tagged release.
OpenClaw NPM Release preflight generates dependency release evidence before it packs the npm tarball. The npm advisory vulnerability gate is release-blocking. The transitive manifest risk, dependency ownership/install surface, and dependency change reports are release evidence only. The dependency change report compares the release candidate with the previous reachable release tag. The preflight uploads dependency evidence as openclaw-release-dependency-evidence-<tag> and also embeds it under dependency-evidence/ inside the prepared npm preflight artifact. The real publish path reuses that preflight artifact, then attaches the same evidence to the GitHub release as openclaw-<version>-dependency-evidence.zip.
Run OpenClaw Release Publish for the mutating publish sequence after the tag exists. Dispatch regular beta and stable publishes from trusted main; the release tag still selects the exact target commit and may point into release/YYYY.M.PATCH. Tideclaw alpha publishes remain on their matching alpha branch. Pass the successful OpenClaw npm preflight_run_id, successful full_release_validation_run_id, and exact full_release_validation_run_attempt, and keep the default plugin publish scope all-publishable unless you are deliberately running a focused repair. The workflow serializes plugin npm publish, plugin ClawHub publish, and OpenClaw npm publish so the core package is not published before its externalized plugins; Windows and Android promotion runs concurrently with the core npm publish against the draft release page. Publish reruns are resumable: an already-published core npm version skips the core dispatch after the workflow proves the registry tarball matches the tag's preflight artifact, and Windows/Android promotion is skipped when the release already carries the verified asset contract, so a retry only redoes the failed stages. Focused plugin-only repairs require plugin_publish_scope=selected and a nonempty plugin list. Plugin-only all-publishable runs require complete immutable preflight and Full Release Validation evidence; partial evidence is rejected.
Stable OpenClaw Release Publish requires an exact windows_node_tag after the matching non-prerelease openclaw/openclaw-windows-node release exists, plus the candidate-approved windows_node_installer_digests map. Before dispatching any publish child, it verifies that source release is published, non-prerelease, contains the required x64/ARM64 installers, and still matches that approved map. It then dispatches Windows Node Release while the OpenClaw release is still a draft, carrying the pinned installer digest map unchanged. The child workflow downloads the signed Windows Hub installers from that exact tag, matches them against the pinned digests, verifies their Authenticode signatures use the expected OpenClaw Foundation signer on a Windows runner, writes a SHA-256 manifest, and uploads the installers plus manifest onto the canonical OpenClaw GitHub release, then re-downloads the promoted assets and verifies manifest membership and hashes. The parent verifies the current x64, ARM64, and checksum asset contract before publication. Direct recovery rejects unexpected OpenClawCompanion-* asset names before replacing the expected contract assets with the pinned source bytes.
Release checks now run in a separate manual workflow: OpenClaw Release Checks. It also runs the QA Lab mock parity lane plus the Matrix release profile and Telegram QA lane before release approval. The live lanes use the qa-live-shared environment; Telegram also uses Convex CI credential leases. Run the manual QA-Lab - All Lanes workflow with matrix_profile=all when you want every maintained Matrix scenario; the workflow fans that selection across the transport, media, and E2EE profiles to keep full proof within per-job timeouts.
Cross-OS install and upgrade runtime validation is part of public OpenClaw Release Checks and Full Release Validation, which call the reusable workflow .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 Full Release Validation or from the main/release workflow ref so workflow logic and secrets stay controlled.
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.

node scripts/full-release-validation-at-sha.mjs \
    --sha <code-sha> \
    --target-ref release/YYYY.M.PATCH

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

gh workflow run ci.yml --ref release/YYYY.M.PATCH -f include_android=true

Release test boxes

주요 항목:

beta: fastest release-critical OpenAI/core live and Docker path
stable: beta plus stable provider/backend coverage for release approval
full: stable plus broad advisory provider/media coverage

pnpm ci:full-release \
  --sha <code-sha> \
  --target-ref release/YYYY.M.PATCH

pnpm ci:full-release \
  --sha <release-sha> \
  --target-ref release/YYYY.M.PATCH

Validate the product-complete Code SHA.

pnpm ci:full-release
--sha
--target-ref release/YYYY.M.PATCH

Validate the changelog-only Release SHA by reusing Code SHA product evidence.

pnpm ci:full-release
--sha
--target-ref release/YYYY.M.PATCH

After publishing a beta, add published-package Telegram E2E.

Vitest

주요 항목:

Full Release Validation summary showing the dispatched CI run URL
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 .artifacts/vitest-shard-timings.json when a run needs performance analysis

gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.PATCH -f include_android=true

Docker

주요 항목:

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: core, package-update-openai, package-update-anthropic, package-update-core, plugins-runtime-plugins, plugins-runtime-services, plugins-runtime-install-a through plugins-runtime-install-h, and openwebui
OpenWebUI coverage on a dedicated large-disk runner when requested
split bundled plugin install/uninstall lanes bundled-plugin-install-uninstall-0 through bundled-plugin-install-uninstall-23
live/E2E provider suites and Docker live model coverage when release checks include live suites

QA Lab

The QA Lab box is also part of OpenClaw Release Checks. It is the agentic behavior and channel-level release gate, separate from Vitest and Docker package mechanics.

주요 항목:

mock parity lane comparing the OpenAI candidate lane against the anthropic/claude-opus-4-8 baseline using the agentic parity pack
Matrix live-adapter release profile using the qa-live-shared environment
live Telegram QA lane using Convex CI credential leases
pnpm qa:otel:smoke, pnpm qa:otel:collector-smoke, pnpm qa:prometheus:smoke, or pnpm qa:observability:smoke when release telemetry needs explicit local proof

Package

주요 항목:

source=npm: openclaw@beta, openclaw@latest, or an exact OpenClaw release version
source=ref: pack a trusted package_ref branch, tag, or full commit SHA with the selected workflow_ref harness
source=url: download a public HTTPS .tgz with required package_sha256; URL credentials, non-default HTTPS ports, private/internal/special-use hostnames or resolved addresses, and unsafe redirects are rejected
source=trusted-url: download an HTTPS .tgz with required package_sha256 and trusted_source_id from a named policy in .github/package-trusted-sources.json; use this for maintainer-owned enterprise mirrors or private package repositories instead of adding an input-level private-network bypass to source=url
source=artifact: reuse a .tgz uploaded by another GitHub Actions run
smoke: quick package install/channel/agent, gateway network, and config reload lanes
package: install/update/restart/plugin package contracts plus live ClawHub skill install proof; this is the release-check default
product: package plus MCP channels, cron/subagent cleanup, OpenAI web search, and OpenWebUI
full: Docker release-path chunks with OpenWebUI
custom: exact docker_lanes list for focused reruns

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

Regular release publish automation

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.PATCH-beta.N \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=beta

gh workflow run openclaw-release-publish.yml \
  --ref main \
  -f tag=vYYYY.M.PATCH \
  -f windows_node_tag=vX.Y.Z \
  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
  -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
  -f full_release_validation_run_attempt=<successful-full-release-validation-run-attempt> \
  -f npm_dist_tag=latest

gh workflow run plugin-clawhub-new.yml \
  --ref main \
  -f plugins=@openclaw/name \
  -f ref=<full-40-character-release-sha> \
  -f pretag_validation=true \
  -f dry_run=true

NPM workflow inputs

OpenClaw NPM Release accepts these operator-controlled inputs:

주요 항목:

tag: required release tag such as v2026.4.2, v2026.4.2-1, v2026.4.2-beta.1, or v2026.4.2-alpha.1; when preflight_only=true, it may also be the current full 40-character workflow-branch commit SHA for validation-only preflight
preflight_only: true for validation/build/package only, false for the real publish path
preflight_run_id: existing successful preflight run id, required on the real publish path so the workflow reuses the prepared tarball instead of rebuilding it
full_release_validation_run_id: successful Full Release Validation run id for this tag/SHA, required for real publish. Beta publishes may proceed on preflight alone with a warning, but stable/latest promotion still requires it.
full_release_validation_run_attempt: exact positive run attempt paired with full_release_validation_run_id; required whenever the run id is provided so reruns cannot change the authorization evidence during publish.
release_publish_run_id: approved OpenClaw Release Publish run id; required when this workflow is dispatched by that parent (bot-actor real-publish calls)
plugin_npm_run_id: successful exact-head Plugin NPM Release run id; required for a real extended-stable core publish
npm_dist_tag: npm target tag for the publish path; accepts alpha, beta, latest, or extended-stable and defaults to beta. Final patch 33 and later must use extended-stable; by default, extended-stable rejects earlier patches, and it always rejects non-final tags.
bypass_extended_stable_guard: testing-only boolean, default false; with npm_dist_tag=extended-stable, bypasses monthly extended-stable eligibility while preserving release identity, artifact, approval, and readback checks.
tag: required release tag; must already exist
preflight_run_id: successful OpenClaw NPM Release preflight run id; required when publish_openclaw_npm=true or plugin_publish_scope=all-publishable
full_release_validation_run_id: successful Full Release Validation run id; required when publish_openclaw_npm=true or plugin_publish_scope=all-publishable
full_release_validation_run_attempt: exact positive attempt paired with full_release_validation_run_id; required whenever the run id is provided
windows_node_tag: exact non-prerelease openclaw/openclaw-windows-node release tag; required for stable OpenClaw publish
windows_node_installer_digests: candidate-approved compact JSON map of the current Windows installer names to their pinned sha256: digests; required for stable OpenClaw publish
npm_telegram_run_id: optional successful NPM Telegram Beta E2E run id to include in final release evidence
npm_dist_tag: npm target tag for the OpenClaw package, one of alpha, beta, or latest
plugin_publish_scope: defaults to all-publishable; use selected only for focused plugin-only repair work with publish_openclaw_npm=false
plugins: comma-separated @openclaw/* package names when plugin_publish_scope=selected
publish_openclaw_npm: defaults to true; set false only when using the workflow as a plugin-only repair orchestrator
release_profile: release coverage profile used for release evidence summaries; defaults to from-validation, which reads it from the validation manifest, or override with beta, stable, or full
wait_for_clawhub: defaults to false so npm availability is not blocked by the ClawHub sidecar; set true only when workflow completion must include ClawHub completion
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.
run_release_soak: opt into exhaustive live/E2E, Docker release-path, and all-since upgrade-survivor soak for beta release checks. It is forced on by release_profile=stable and release_profile=full.
Regular final and correction versions below patch 33 may publish to either beta or latest. Final versions at patch 33 or above must publish to extended-stable, and correction-suffix versions at that boundary are rejected.

Regular beta/latest stable release sequence

Public references

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

주요 항목:

.github/workflows/full-release-validation.yml
.github/workflows/package-acceptance.yml
.github/workflows/openclaw-npm-release.yml
.github/workflows/openclaw-release-checks.yml
.github/workflows/openclaw-cross-os-release-checks-reusable.yml
.github/workflows/docker-release.yml
scripts/resolve-openclaw-package-candidate.mjs
scripts/openclaw-npm-release-check.ts
scripts/package-mac-dist.sh
scripts/make_appcast.sh

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/RELEASING
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

RELEASE_SHA="$(git rev-parse HEAD)"

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag="$RELEASE_SHA" \
  -f preflight_only=true \
  -f npm_dist_tag=extended-stable

gh workflow run full-release-validation.yml \
  --ref extended-stable/YYYY.M.33 \
  -f ref=extended-stable/YYYY.M.33 \
  -f release_profile=stable

RELEASE_SHA="$(git rev-parse HEAD)"
gh workflow run plugin-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f publish_scope=all-publishable \
  -f ref="$RELEASE_SHA" \
  -f npm_dist_tag=extended-stable

gh workflow run openclaw-npm-release.yml \
  --ref extended-stable/YYYY.M.33 \
  -f tag=vYYYY.M.P \
  -f preflight_only=false \
  -f npm_dist_tag=extended-stable \
  -f preflight_run_id=<npm-preflight-run-id> \
  -f full_release_validation_run_id=<full-validation-run-id> \
  -f full_release_validation_run_attempt=<full-validation-run-attempt> \
  -f plugin_npm_run_id=<plugin-npm-run-id>

node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P
npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"

pnpm release:candidate -- \
     --tag vYYYY.M.PATCH-beta.N \
     --full-release-run <release-sha-validation-run-id> \
     --npm-preflight-run <preflight-run-id> \
     --skip-dispatch

node scripts/full-release-validation-at-sha.mjs \
    --sha <code-sha> \
    --target-ref release/YYYY.M.PATCH

Release policy

핵심 요약

문서 구성

상세 내용

본문

Version naming

Release cadence

Monthly Gateway extended-stable publication

Prepare and stabilize the candidate

Publish the npm packages

Verify and recover

Regular release operator checklist

Stable main closeout

Release preflight

Release test boxes

Validate the product-complete Code SHA.

Validate the changelog-only Release SHA by reusing Code SHA product evidence.

After publishing a beta, add published-package Telegram E2E.

Vitest

Docker

QA Lab

Package

Regular release publish automation

NPM workflow inputs

Regular beta/latest stable release sequence

Public references

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Release policy

핵심 요약

문서 구성

상세 내용

본문

Version naming

Release cadence

Monthly Gateway extended-stable publication

Prepare and stabilize the candidate

Publish the npm packages

Verify and recover

Regular release operator checklist

Stable main closeout

Release preflight

Release test boxes

Validate the product-complete Code SHA.

Validate the changelog-only Release SHA by reusing Code SHA product evidence.

After publishing a beta, add published-package Telegram E2E.

Vitest

Docker

QA Lab

Package

Regular release publish automation

NPM workflow inputs

Regular beta/latest stable release sequence

Public references

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드