<!-- source: https://deepwiki.com/openclaw/openclaw/8.1-multi-platform-build-system -->

# Multi-Platform Build System

- docs/plugins/plugin-inventory.md
- docs/plugins/reference.md
- extensions/tsconfig.package-boundary.paths.json
- extensions/xai/tsconfig.json
- scripts/build-all.mjs
- scripts/check-plugin-sdk-exports.mjs
- scripts/lib/bundled-plugin-build-entries.mjs
- scripts/lib/extension-package-boundary.ts
- scripts/lib/plugin-sdk-entries.d.mts
- scripts/lib/plugin-sdk-entries.mjs
- scripts/lib/static-extension-assets.mjs
- scripts/prepare-extension-package-boundary-artifacts.mjs
- scripts/release-check.ts
- scripts/run-node-watch-paths.mjs
- scripts/runtime-postbuild.mjs
- scripts/tsdown-build.mjs
- scripts/watch-node.mjs
- scripts/write-plugin-sdk-entry-dts.ts
- src/agents/agent-tools.create-openclaw-coding-tools.test.ts
- src/agents/embedded-agent-runner/run/attempt-system-prompt.test.ts
- src/agents/embedded-agent-runner/run/attempt-tool-construction-plan.test.ts
- src/agents/embedded-agent-runner/run/attempt-tool-construction-plan.ts
- src/agents/embedded-agent-runner/run/attempt.cwd-split.test.ts
- src/agents/system-prompt.test.ts
- src/agents/system-prompt.ts
- src/agents/test-helpers/fast-openclaw-tools.ts
- src/agents/tool-catalog.test.ts
- src/agents/tool-catalog.ts
- src/cli/update-cli/plugin-payload-validation.test.ts
- src/cli/update-cli/plugin-payload-validation.ts
- src/cli/update-cli/post-core-plugin-convergence.test.ts
- src/cli/update-cli/post-core-plugin-convergence.ts
- src/commands/doctor-plugin-registry.test.ts
- src/commands/doctor-plugin-registry.ts
- src/gateway/gateway-cli-backend.connect.test.ts
- src/gateway/gateway-cli-backend.live-helpers.test.ts
- src/gateway/gateway-cli-backend.live-helpers.ts
- src/gateway/gateway-cli-backend.live-probe-helpers.test.ts
- src/gateway/gateway-cli-backend.live-probe-helpers.ts
- src/gateway/live-agent-probes.test.ts
- src/gateway/live-agent-probes.ts
- src/gateway/minimal-gateway.test-helpers.ts
- src/gateway/probe.close-drain.test.ts
- src/gateway/probe.test.ts
- src/gateway/probe.ts
- src/gateway/server-methods/subagent-followup.test-helpers.ts
- src/gateway/server.silent-scope-upgrade-reconnect.poc.test.ts
- src/infra/exec-wrapper-trust-plan.test.ts
- src/infra/tsdown-config.test.ts
- src/infra/watch-node.test.ts
- src/plugins/channel-catalog-registry.test.ts
- src/plugins/channel-catalog-registry.ts
- src/plugins/installed-plugin-index-record-reader.ts
- src/plugins/installed-plugin-index-records.test.ts
- src/plugins/installed-plugin-index-records.ts
- src/plugins/installed-plugin-index-store.ts
- src/plugins/plugin-peer-link.test.ts
- src/plugins/plugin-peer-link.ts
- src/plugins/plugin-sdk-native-resolver.test.ts
- src/plugins/plugin-sdk-native-resolver.ts
- src/plugins/sdk-alias.test.ts
- src/plugins/sdk-alias.ts
- src/plugins/stale-local-bundled-plugin-install-records.test.ts
- src/plugins/stale-local-bundled-plugin-install-records.ts
- test/release-check.test.ts
- test/scripts/build-all.test.ts
- test/scripts/bundled-plugin-build-entries.test.ts
- test/scripts/prepare-extension-package-boundary-artifacts.test.ts
- test/scripts/runtime-postbuild.test.ts
- test/scripts/tsdown-build.test.ts
- test/scripts/watch-node.test.ts
- test/vitest/vitest.shared.config.ts
- tsconfig.json
- tsdown.config.ts

This document details the OpenClaw multi-platform build system which compiles, packages, and produces distributable artifacts for the Node.js core, iOS/macOS native apps, Android native app, and Docker containers. It covers the platform-specific tools and configurations employed: `tsdown` for Node.js builds, `XcodeGen` for iOS/macOS, and Gradle for Android.

## Build Target Matrix

OpenClaw supports several build targets. Each platform uses specialized build tools aligned with its environment and language requirements:

**Sources:** [tsdown.config.ts3-240](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L3-L240) [scripts/build-all.mjs1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L1-L20)

## Node.js Build Pipeline: tsdown

### Overview

OpenClaw uses the `tsdown` tool to bundle the Node.js core, Plugin SDK, and bundled extensions into a clean `dist/` output directory. This tool compiles TypeScript input sources into optimized JavaScript modules while carefully managing dependencies and build graph structure.

The build configuration is declared in `tsdown.config.ts`, which defines input sources, output directories, and custom build options such as external dependency handling and log suppression [tsdown.config.ts3-133](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L3-L133)

### Dist Graph and Entry Points

The `tsdown` configuration defines a "unified dist graph" encompassing core modules and bundled plugins. Key features include:

- Core Entries: Entry points include src/index.ts and src/entry.ts for bootstrapping the runtime.
- Lazy Runtime Boundaries: The build system produces specific runtime bundles like dist/agents/compaction-planning.worker.js and dist/telegram-ingress-worker.runtime.js scripts/release-check.ts 94-97
- Bundled Plugins: Extensions under extensions/ are automatically discovered via collectBundledPluginBuildEntries() tsdown.config.ts 157
- External Dependencies: Heavy or native-dependent libraries (e.g., @slack/bolt , @lancedb/lancedb , matrix-js-sdk ) are explicitly externalized via explicitNeverBundleDependencies to prevent bundling issues tsdown.config.ts 192-206
- SDK Aliasing: During development, the system can alias SDK imports to source files ( src/plugin-sdk ) or distribution files ( dist/plugin-sdk ) using PluginSdkResolutionPreference src/plugins/sdk-alias.ts 11-21

### Memory Management and Invocation

The build system dynamically adjusts `NODE_OPTIONS` to ensure `tsdown` has sufficient heap space. On Windows, it defaults to 8GB (`--max-old-space-size=8192`) for DTS builds [scripts/build-all.mjs13](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L13-L13) while the standard `tsdown` build script defaults to 12GB (`DEFAULT_TSDOWN_MAX_OLD_SPACE_MB = 12288`) [scripts/tsdown-build.mjs23](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/tsdown-build.mjs#L23-L23)

In containerized environments, the script `scripts/tsdown-build.mjs` attempts to read cgroup limits from `/sys/fs/cgroup/memory.max` to clamp heap usage [scripts/tsdown-build.mjs26-30](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/tsdown-build.mjs#L26-L30)

**Sources:** [tsdown.config.ts157-206](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L157-L206) [scripts/build-all.mjs13](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L13-L13) [scripts/tsdown-build.mjs23-30](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/tsdown-build.mjs#L23-L30) [src/plugins/sdk-alias.ts11-21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/sdk-alias.ts#L11-L21) [scripts/release-check.ts94-97](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L94-L97)

## Build Orchestration with build-all.mjs

The `scripts/build-all.mjs` script orchestrates the full build pipeline through defined "profiles" [scripts/build-all.mjs164-208](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L164-L208)

The orchestration includes specialized steps for the Control UI (`ui:build`) and the Plugin SDK type generation (`build:plugin-sdk:dts`) which uses a high memory limit on Windows [scripts/build-all.mjs89-97](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L89-L97) [scripts/build-all.mjs138-146](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L138-L146)

**Sources:** [scripts/build-all.mjs164-208](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L164-L208) [scripts/build-all.mjs89-146](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L89-L146)

## CI/CD and Release Validation

### Release Checks

The `scripts/release-check.ts` script performs comprehensive verification of the build artifacts before publication [scripts/release-check.ts1-125](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L1-L125) It ensures:

- Pack Integrity: Validates that required paths (like npm-shrinkwrap.json , dist/index.js , and dist/build-info.json ) are present in the package scripts/release-check.ts 72-101
- Forbidden Content: Scans for private QA code (e.g., dist/extensions/qa-channel/ ), test helpers, or local build metadata that should not be in public releases scripts/release-check.ts 102-125
- Size Constraints: Monitors critical Plugin SDK entrypoint sizes (e.g., openclaw/plugin-sdk/core ) to prevent regressions beyond MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES (2MB) scripts/release-check.ts 148-153

### Runtime Smoke Testing

The build system includes smoke tests that validate the CLI and Gateway readiness. The `PACKED_CLI_SMOKE_COMMANDS` verify basic functionality like `onboard --help`, `doctor --help`, and `models list` [scripts/release-check.ts155-162](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L155-L162) It also includes a `doctor --fix` repair policy check for bundled runtime dependencies [scripts/release-check.ts163-167](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L163-L167)

**Sources:** [scripts/release-check.ts72-167](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L72-L167)

## Build System Architecture Mapping

### Build Orchestration Map

This diagram bridges the build requirements to the specific scripts and configurations in the codebase.

```

```

**Sources:** [tsdown.config.ts3-12](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L3-L12) [scripts/build-all.mjs73-162](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L73-L162) [scripts/release-check.ts1-125](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L1-L125)

### Artifact Generation Flow

This diagram illustrates the data flow from source to the final `dist/` directory.

```

```

**Sources:** [scripts/build-all.mjs73-122](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L73-L122) [scripts/release-check.ts72-101](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/release-check.ts#L72-L101)

## Native & Mobile Build Systems

### iOS and macOS (XcodeGen)

OpenClaw employs `XcodeGen` to generate Xcode projects for the iOS and macOS native clients. The `apps/ios/project.yml` file defines targets, build settings, capabilities, and dependencies.

### Android (Gradle)

The Android client is built using Gradle. The build configuration is managed in `apps/android/app/build.gradle.kts`, handling signing and assembly of APKs or App Bundles.

# End of section 8.1
