<!-- source: https://deepwiki.com/openclaw/openclaw/8-build-and-release -->

# Build & Release

- .agents/skills/crabbox/SKILL.md
- .agents/skills/openclaw-testing/SKILL.md
- .crabbox.yaml
- .github/actions/ensure-base-commit/action.yml
- .github/actions/setup-node-env/action.yml
- .github/actions/setup-pnpm-store-cache/action.yml
- .github/actions/setup-pnpm-store-cache/ensure-node.sh
- .github/workflows/ci-build-artifacts-testbox.yml
- .github/workflows/ci-check-testbox.yml
- .github/workflows/ci.yml
- .github/workflows/crabbox-hydrate.yml
- .github/workflows/openclaw-cross-os-release-checks-reusable.yml
- .github/workflows/windows-blacksmith-testbox.yml
- AGENTS.md
- CONTRIBUTING.md
- docs/ci.md
- docs/reference/full-release-validation.md
- extensions/msteams/npm-shrinkwrap.json
- extensions/zalouser/npm-shrinkwrap.json
- qa/scenarios/memory/thread-memory-isolation.md
- scripts/AGENTS.md
- scripts/changed-lanes.mjs
- scripts/check-changed.mjs
- scripts/ci-changed-scope.mjs
- scripts/ci-run-timings.mjs
- scripts/crabbox-wrapper.mjs
- scripts/generate-npm-shrinkwrap.mjs
- scripts/lib/ci-node-test-plan.mjs
- scripts/lib/docker-build.sh
- scripts/lib/format-generated-module.mjs
- scripts/plugin-npm-publish.sh
- scripts/qa-lab-up.ts
- scripts/run-with-env.mjs
- scripts/test-projects-imports.mjs
- scripts/test-projects-max.mjs
- src/agents/tools/image-tool.providers.live.test.ts
- src/infra/vitest-config.test.ts
- src/scripts/ci-changed-scope.test.ts
- test/package-manager-config.test.ts
- test/package-scripts.test.ts
- test/scripts/changed-lanes.test.ts
- test/scripts/ci-node-test-plan.test.ts
- test/scripts/ci-run-timings.test.ts
- test/scripts/ci-workflow-guards.test.ts
- test/scripts/crabbox-wrapper.test.ts
- test/scripts/format-generated-module.test.ts
- test/scripts/generate-npm-shrinkwrap.test.ts
- test/scripts/openclaw-cross-os-release-workflow.test.ts
- test/scripts/package-acceptance-workflow.test.ts
- test/scripts/qa-lab-up.test.ts
- test/scripts/run-with-env.test.ts
- test/scripts/setup-pnpm-store-cache-ensure-node.test.ts
- test/vitest/vitest.unit-support.config.ts

This page documents OpenClaw's multi-platform build system, continuous integration and delivery (CI/CD) infrastructure, and release processes. It offers a high-level perspective on building TypeScript into distributable JavaScript, producing native iOS/macOS/Android apps, validating builds through CI pipelines, and publishing releases to npm, Docker registries, and app distribution platforms.

For development workflows and local environment setup, refer to [Development](/openclaw/openclaw/9-development).

## Purpose and Scope

OpenClaw builds and releases software artifacts across multiple platforms and channels to support diverse deployment targets and end-user environments:

- Node.js package ( openclaw on npm): Contains the CLI and Gateway server runtime.
- Docker images on GitHub Container Registry (GHCR): For server deployments with multi-architecture support (amd64, arm64).
- macOS app : Menubar application featuring Sparkle-based auto-update functionality.
- iOS/watchOS apps : Native mobile and wearable clients.
- Android app : Native Android client delivered via APK/AAB AGENTS.md 21

The build system fulfills key roles:

1. Compile TypeScript source into optimized JavaScript bundles for Node.js and Docker runtimes.
2. Generate native app binaries for iOS/macOS (Swift/Xcode-based) and Android (Kotlin/Gradle-based) AGENTS.md 44-46
3. Bundle and export plugin SDK subpaths enabling third-party extensions AGENTS.md 57-58
4. Validate build and release artifacts before publication using comprehensive smoke tests .github/workflows/ci.yml 62-65
5. Support incremental CI builds with intelligent code scope detection to reduce cycle times.

## 8.1 Multi-Platform Build System

OpenClaw utilizes tailored build toolchains per platform, all coordinated under a pnpm workspace to manage dependencies and share code.

### Node.js and Tooling

The Node.js core uses `tsdown` for fast bundling. Dependency management is strictly enforced via `pnpm` [AGENTS.md18](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L18-L18) A critical part of the Node build is maintaining a stable `npm-shrinkwrap.json` which is generated via `scripts/generate-npm-shrinkwrap.mjs` to ensure production lockfile consistency [scripts/generate-npm-shrinkwrap.mjs1-11](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/generate-npm-shrinkwrap.mjs#L1-L11)

**Build Flow: Source to Artifacts**

```

```

Sources: [.github/workflows/ci.yml45-55](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L45-L55) [scripts/generate-npm-shrinkwrap.mjs1-11](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/generate-npm-shrinkwrap.mjs#L1-L11) [docs/ci.md19-21](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L19-L21)

For native clients, OpenClaw uses platform-specific build systems:

- iOS/macOS : Xcode projects and schemes are managed using XcodeGen.
- Android : Kotlin code built via Gradle AGENTS.md 44-46

For detailed platform-specific build documentation, see [Multi-Platform Build System](/openclaw/openclaw/8.1-multi-platform-build-system).

## 8.2 CI/CD Pipeline

OpenClaw leverages GitHub Actions workflows integrated with custom scripts to maintain code quality and release readiness.

### Workflow Structure

The CI pipeline is orchestrated by `.github/workflows/ci.yml`, which uses a `preflight` job to determine the execution matrix based on changed paths [docs/ci.md13-17](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L13-L17)

- Scope Detection : scripts/ci-changed-scope.mjs and scripts/changed-lanes.mjs identify which sub-systems (Node, macOS, Android, Docs) require validation scripts/changed-lanes.mjs 1-11
- Security & Audit : Includes security-fast for key detection and check-dependencies using Knip docs/ci.md 18-19
- Sharded Testing : Node tests are sharded across multiple runners to minimize wall time docs/ci.md 24-25

For detailed CI/CD documentation, see [CI/CD Pipeline](/openclaw/openclaw/8.2-cicd-pipeline).

## 8.3 Release Process

OpenClaw follows a disciplined versioning and multi-channel publication process.

### Versioning & Promotion

Releases conform to Calendar Versioning (CalVer) in `YYYY.M.D` format.

1. Validation : The full-release-validation.yml workflow triggers exhaustive platform checks test/scripts/package-acceptance-workflow.test.ts 13
2. NPM Publication : Handled by openclaw-release-publish.yml test/scripts/package-acceptance-workflow.test.ts 12
3. Docker : Images are built with multi-arch manifests and pushed to GHCR.

For detailed release documentation, see [Release Process](/openclaw/openclaw/8.3-release-process).

## 8.4 Testing Strategy

OpenClaw employs comprehensive testing layers emphasizing correctness and upgrade safety.

- Unit & Integration : Powered by Vitest test/scripts/package-acceptance-workflow.test.ts 2
- E2E Smoke Tests : Validated via package-acceptance.yml test/scripts/package-acceptance-workflow.test.ts 5
- Upgrade Survivor : scripts/e2e/lib/upgrade-survivor/run.sh ensures that user configuration and sessions survive version upgrades test/scripts/package-acceptance-workflow.test.ts 22
- Cross-OS Validation : Reusable workflows test behavior across Windows, macOS, and Linux test/scripts/package-acceptance-workflow.test.ts 11

For comprehensive testing details, see [Testing Strategy](/openclaw/openclaw/8.4-testing-strategy).

## 8.5 QA Lab & Scenario Packs

The QA Lab provides a high-fidelity environment for verifying complex agent behaviors.

- Crabbox Wrapper : A unified CLI ( scripts/crabbox-wrapper.mjs ) for running remote validation across Linux, macOS, and Windows scripts/crabbox-wrapper.mjs 1-30
- Scenario Packs : Located in ./qa , these provide reproducible test cases for agents and tools.
- Hydration : The Crabbox Hydrate workflow prepares remote environments with necessary dependencies and Docker engines .github/workflows/crabbox-hydrate.yml 1-44
- Credential Broker : Parallel tests lease live credentials via a Convex-backed broker to avoid authentication conflicts test/scripts/package-acceptance-workflow.test.ts 14

For details on the QA infrastructure, see [QA Lab & Scenario Packs](/openclaw/openclaw/8.5-qa-lab-and-scenario-packs).

# Bridging Natural Language to Code Entities

**CI Scoping and Execution Mapping**

```

```

Sources: [.github/workflows/ci.yml39-45](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L39-L45) [test/scripts/package-acceptance-workflow.test.ts21](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L21-L21) [scripts/generate-npm-shrinkwrap.mjs1-11](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/generate-npm-shrinkwrap.mjs#L1-L11)

**Remote Validation Infrastructure**

```

```

Sources: [.github/workflows/crabbox-hydrate.yml1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/crabbox-hydrate.yml#L1-L20) [scripts/crabbox-wrapper.mjs21-29](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/crabbox-wrapper.mjs#L21-L29) [.agents/skills/crabbox/SKILL.md1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/crabbox/SKILL.md?plain=1#L1-L20)

- Multi-Platform Build System
- CI/CD Pipeline
- Release Process
- Testing Strategy
- QA Lab & Scenario Packs

Sources: [AGENTS.md1-60](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L1-L60) [.github/workflows/ci.yml1-80](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L1-L80) [scripts/crabbox-wrapper.mjs1-100](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/crabbox-wrapper.mjs#L1-L100) [test/scripts/package-acceptance-workflow.test.ts1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L1-L50) [docs/ci.md1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L1-L40) [scripts/generate-npm-shrinkwrap.mjs1-100](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/generate-npm-shrinkwrap.mjs#L1-L100)
