<!-- source: https://deepwiki.com/openclaw/openclaw/8.3-release-process -->

# Release Process

- .github/workflows/openclaw-npm-release.yml
- .github/workflows/openclaw-release-publish.yml
- .github/workflows/plugin-clawhub-release.yml
- .github/workflows/plugin-npm-release.yml
- docs/reference/RELEASING.md
- packages/plugin-package-contract/src/index.test.ts
- packages/plugin-package-contract/src/index.ts
- scripts/check-gateway-cpu-scenarios.mjs
- scripts/check-plugin-gateway-gauntlet.mjs
- scripts/e2e/parallels/common.ts
- scripts/e2e/parallels/env-limits.ts
- scripts/e2e/parallels/guest-transports.ts
- scripts/e2e/parallels/host-command.ts
- scripts/e2e/parallels/host-server.ts
- scripts/e2e/parallels/linux-smoke.ts
- scripts/e2e/parallels/macos-smoke.ts
- scripts/e2e/parallels/npm-update-scripts.ts
- scripts/e2e/parallels/npm-update-smoke.ts
- scripts/e2e/parallels/package-artifact.ts
- scripts/e2e/parallels/parallels-vm.ts
- scripts/e2e/parallels/plugin-isolation.ts
- scripts/e2e/parallels/powershell.ts
- scripts/e2e/parallels/provider-auth.ts
- scripts/e2e/parallels/smoke-common.ts
- scripts/e2e/parallels/snapshots.ts
- scripts/e2e/parallels/update-job-timeout.ts
- scripts/e2e/parallels/windows-smoke.ts
- scripts/lib/direct-run.mjs
- scripts/lib/plugin-clawhub-release.ts
- scripts/lib/plugin-gateway-gauntlet.mjs
- scripts/lib/release-beta-verifier.ts
- scripts/plugin-clawhub-publish.sh
- scripts/profile-extension-memory.mjs
- scripts/release-beta-smoke.ts
- scripts/release-candidate-checklist.mjs
- scripts/validate-release-publish-approval.mjs
- src/commands/agents.add.test.ts
- src/commands/agents.commands.add.ts
- test/plugin-clawhub-release.test.ts
- test/plugin-npm-release.test.ts
- test/scripts/check-gateway-cpu-scenarios.test.ts
- test/scripts/parallels-npm-update-smoke.test.ts
- test/scripts/parallels-smoke-model.test.ts
- test/scripts/parallels-update-job-timeout.test.ts
- test/scripts/plugin-gateway-gauntlet.test.ts
- test/scripts/profile-extension-memory.test.ts
- test/scripts/release-beta-smoke.test.ts
- test/scripts/release-beta-verifier.test.ts
- test/scripts/release-candidate-checklist.test.ts
- ui/index.html
- ui/public/sw.js
- ui/src/main.ts
- ui/src/ui/mount-fallback.test.ts
- ui/src/ui/public-assets.test.ts
- ui/src/ui/public-assets.ts
- ui/src/ui/service-worker-cache.test.ts
- ui/src/ui/views/agents-utils.test.ts
- ui/src/ui/views/agents-utils.ts

This document describes the versioning strategy, release validation, and distribution process for OpenClaw releases across npm, Docker, and native platform channels (macOS, iOS, Android).

## Purpose and Scope

The OpenClaw release process ensures coordinated delivery of the Node.js Gateway core and its various client implementations. This page covers:

- CalVer Versioning : The calendar-based scheme used for all project components.
- npm Publication : Validation and automated delivery via trusted publishing workflows.
- Docker Delivery : Creation of multi-architecture Docker images with manifest lists.
- Native Releases : Coordination of macOS Sparkle feed updates and iOS/macOS app packaging.
- Full Release Validation : The manual "everything before release" umbrella that orchestrates CI, Docker, and QA Lab validation.

## CalVer Versioning Scheme

OpenClaw adopts **calendar versioning (CalVer)** following a pattern:
`YYYY.M.D[-beta.N]` where `YYYY` is the Year, `M` is the Month (non-zero-padded), and `D` is the Day (non-zero-padded). This scheme supports stable, stable correction, and beta prerelease suffixes [scripts/release-candidate-checklist.mjs17-18](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-candidate-checklist.mjs#L17-L18)

### Version Types

### Release Channels Mapping

**Sources:** [.github/workflows/openclaw-release-publish.yml97-108](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-release-publish.yml#L97-L108) [.github/workflows/openclaw-release-publish.yml33-35](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-release-publish.yml#L33-L35) [scripts/release-candidate-checklist.mjs17-18](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-candidate-checklist.mjs#L17-L18)

## npm Publication Workflow

OpenClaw's npm publication is a structured, multi-phase CI/CD workflow ensuring that the package meets quality and policy requirements before publishing.

### Pre-Publish Validation

The `OpenClaw NPM Release` workflow ([.github/workflows/openclaw-npm-release.yml](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-npm-release.yml)) manages the build and validation of the core package. Key steps include:

- Environment Check : Ensuring the version is not already published using npm view .github/workflows/openclaw-npm-release.yml 123-137
- Correctness Gates : Running pnpm check , pnpm check:test-types , and pnpm check:architecture .github/workflows/openclaw-npm-release.yml 141-154
- Build Phase : Compiling the Node.js source and building the Control UI assets .github/workflows/openclaw-npm-release.yml 156-160

### Plugin Release Coordination

Plugins are published as independent packages but coordinated with the main release. The `plugin_publish_scope` input in the release workflow determines if all publishable plugins or a selected subset are released [.github/workflows/openclaw-release-publish.yml31-42](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-release-publish.yml#L31-L42)

### Release Workflow Overview

```

```

**Sources:** [.github/workflows/openclaw-npm-release.yml123-160](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-npm-release.yml#L123-L160) [.github/workflows/openclaw-release-publish.yml31-42](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-release-publish.yml#L31-L42) [.github/workflows/openclaw-release-publish.yml145-180](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/openclaw-release-publish.yml#L145-L180)

## Release Candidate Checklist & Smoke Testing

The `scripts/release-candidate-checklist.mjs` script provides a local developer interface for managing the release lifecycle, including dispatching validation runs and gathering evidence [scripts/release-candidate-checklist.mjs17-41](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-candidate-checklist.mjs#L17-L41)

### Parallels VM Smoke Testing

A critical part of the release process is verifying the installer and upgrade paths on native operating systems using Parallels Desktop. This is orchestrated by `scripts/e2e/parallels/npm-update-smoke.ts` [scripts/e2e/parallels/npm-update-smoke.ts1-36](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/e2e/parallels/npm-update-smoke.ts#L1-L36)

- Fresh Install Lane : Verifies that openclaw can be installed on a clean VM via the site installer scripts/e2e/parallels/npm-update-smoke.ts 121-125
- Upgrade Lane : Verifies that an existing installation can be updated to the new version without data loss scripts/e2e/parallels/npm-update-smoke.ts 34-36
- Beta Validation Mode : A specific mode enabled by --beta-validation that checks the registry version against the local harness checkout test/scripts/parallels-npm-update-smoke.test.ts 117-126

### Performance & Plugin Gauntlet

The release process includes a "Gauntlet" that runs plugins through lifecycle checks and performance monitoring [scripts/check-plugin-gateway-gauntlet.mjs187-203](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/check-plugin-gateway-gauntlet.mjs#L187-L203)

- CPU Monitoring : collectGatewayCpuObservations tracks CPU usage during plugin activation to detect regressions scripts/check-gateway-cpu-scenarios.mjs 14-15
- Memory Profiling : maxRssWarnMb sets thresholds for memory usage during the gauntlet scripts/check-plugin-gateway-gauntlet.mjs 58-62

### Release Logic Mapping

```

```

**Sources:** [scripts/e2e/parallels/npm-update-smoke.ts1-36](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/e2e/parallels/npm-update-smoke.ts#L1-L36) [scripts/check-gateway-cpu-scenarios.mjs1-25](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/check-gateway-cpu-scenarios.mjs#L1-L25) [scripts/release-candidate-checklist.mjs17-41](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-candidate-checklist.mjs#L17-L41) [scripts/check-plugin-gateway-gauntlet.mjs37-70](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/check-plugin-gateway-gauntlet.mjs#L37-L70)

## Native Platform Releases

Native clients (macOS, iOS, Android) follow the core versioning but have platform-specific distribution mechanisms.

### macOS and iOS

- XcodeGen : Used to generate project files for consistent builds across environments.
- Sparkle : Integration in the macOS app provides the auto-update mechanism using appcast XML feeds.
- Signing : Native binaries are signed and notarized as part of the CI workflows.

### Android

- Gradle : Manages the Android build process, producing signed APKs and AABs for distribution.
- Flavors : Supports multiple build flavors (e.g., Google Play vs. F-Droid).

### Beta Verification

The `scripts/release-beta-smoke.ts` script specifically handles the validation of beta releases by dispatching GitHub workflows like `npm-telegram-beta-e2e.yml` and polling for results [scripts/release-beta-smoke.ts163-165](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-beta-smoke.ts#L163-L165)

**Sources:** [scripts/release-beta-smoke.ts163-220](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-beta-smoke.ts#L163-L220) [scripts/release-candidate-checklist.mjs62](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-candidate-checklist.mjs#L62-L62) [test/scripts/parallels-npm-update-smoke.test.ts128-136](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/parallels-npm-update-smoke.test.ts#L128-L136)
