On this page
On this page
Gateway
Worker setup and bundle installation
OpenClaw installs its runtime automatically from the running Gateway. Profiles need only optional machine prerequisites; repository dependencies and startup commands belong in the cloud environment file.
Automatic Linux Node toolchains
Linux x64 and arm64 workers need no Node installation in settings.setup. OpenClaw preserves a supported Node on PATH; otherwise it installs its pinned official release after SHA-256 verification. Explicit npm profiles and repository seed/setup preparation require npm, npx, and Corepack before reusing the existing toolchain. Only bundle runtime enrollment uses the Node-only prerequisite. Installing a toolchain needs compatible glibc, curl, tar, and sha256sum, plus HTTPS access to nodejs.org; a supported bundle-mode Node installation needs no download.
Prepared repositories select their Node requirement from .nvmrc, .node-version, .tool-versions (nodejs or node), mise.toml ([tools] node), then package.json engines.node. Versions, majors, SemVer ranges, node/latest, and LTS aliases resolve to a matching official Linux release; system retains the bootstrap Node. Invalid declarations or missing releases fail with a repair hint.
Verified toolchains survive snapshot forks. Repository commands use the prepared HOME's .local/bin shims first. A declared packageManager gets user-writable Corepack shims without sudo. The OpenClaw runtime uses its own supported Node, independently of the repository's version. Custom profile Node installs remain supported. macOS and Windows need image- or setup-provided Node (and npm for explicit npm profiles); OpenClaw does not install them there.
Platform certificate trust
Linux node enrollment refreshes the system certificate bundle with
/usr/sbin/update-ca-certificates when available, including on snapshot forks.
Non-root images need noninteractive sudo for that command. A failed refresh stops
enrollment with repair guidance; runtime-only preparation does not change system
trust. Bootstrap credentials are not passed to the certificate-update command.
The setup command
settings.setup runs on a cold machine after readiness and before repository preparation and enrollment. Provision replay can repeat it, so make it idempotent. Snapshot forks skip it because their compatible image already contains its filesystem results. Use repository postStartCommand for processes that must start on each new worker.
Do not install OpenClaw globally or maintain a versioned runtime/plugin URL in setup. Bootstrap supplies the Gateway's runtime and required plugins. For additional packages, account for image initialization: wait for cloud-init and use your package manager's lock-wait option to avoid failing the first dispatch on a held lock. Setup or enrollment failures report an error and stop the incomplete lease.
Protected setup secrets
Private package access uses setup secrets through protected egress, including when snapshots are disabled. Keep raw credentials out of setup commands and files.
Native Windows prerequisites
For windows/normal, Crabbox executes settings.setup with Windows PowerShell. Write setup commands for PowerShell; Linux, macOS, and Windows (WSL2) continue to use POSIX scripts. A profile with setup cannot override its OS across that interpreter boundary: OpenClaw rejects the request before allocation and omits incompatible OS and machine choices. Use a separate profile with settings.target: "windows/normal" and PowerShell setup for native Windows. Profiles without setup retain all backend-supported OS choices. OpenClaw does not inspect or translate scripts; you remain responsible for compatibility between POSIX targets.
For example, this prerequisite check uses the machine's existing Node installation:
Use a Crabbox bootstrap or image that supplies a supported Node.js release and tar.exe on the machine PATH. Bundle profiles extract the verified, preassembled runtime without npm. Explicit npm profiles additionally require npm's CLI beside node.exe under node_modules/npm. OpenClaw reports missing prerequisites rather than installing Node there. Worker bundles use the Node archive library.
Headless Windows guests must include Crabbox's managed launcher at C:\Program Files\Crabbox\bin\Start-CrabboxDetachedProcess.ps1. It keeps the node alive after Crabbox closes its SSH command. Enrollment fails with guidance if the launcher is absent. A hidden PowerShell parent redirects node output to node.log under its isolated state directory because the launcher does not inherit SSH output handles.
New native Windows workers use a short, account- and lease-specific state directory on the profile's drive, leaving more path-length headroom for tools launched from their workspaces. Existing workers keep their original state directory across enrollment retries and recovery; reprovision a worker to use the shorter layout. Linux and macOS paths are unchanged.
Each worker turn's GitHub profile lives in temporary runtime state. OpenClaw creates that profile with a protected Windows ACL for the worker account, SYSTEM, and Administrators before writing credentials, independently of the temporary directory's inherited permissions. Shell launches still reject profiles whose ownership or privacy cannot be verified.
Desktop-enabled Windows workers use Crabbox's interactive desktop service; see native desktop prerequisites.
Bundle installation
Before enrollment, the Gateway prepares a reusable archive from its current built installation, including the node host and trusted plugins required by the selected execution mode. Codex's plugin and managed binary pin travel with it. The archive contains runtime code and package metadata, not Gateway config, authentication profiles, sessions, or process environment.
The worker bundle and its standalone GitHub launcher include the pinned Windows permission-inspection helper and the package metadata needed for fallback inspection. These assets are covered by the same archive manifest and content verification.
Archives and fresh installations are verified by content digest, rather than version alone. A snapshot fork tops up an older runtime before enrollment. For install: "bundle", the node bootstrap archive includes the preassembled production dependency closure for each prepared OS and CPU. Workers verify the archive size and SHA-256, reject unsafe archive paths and links, extract into private staging, check the manifest pin and target/build identity, then atomically publish the runtime. Cold bundle-mode node-bootstrap caches and cache misses never invoke npm, resolve dependencies, or run package lifecycle scripts. Missing target dependencies fail with a Gateway preparation hint. Enrollment and archive-download credentials are not passed to extraction tools or the node process.
Node-backed profiles using install: "npm" retain target-native node bootstrap,
including exact registry pins, bundled JavaScript, package lifecycle hooks, and
installation verification. Their worker loop still uses the pinned Gateway
bundle. SSH-backed npm worker installation retains its exact released-package
proof. Npm bootstrap can provision a different OS or CPU without preassembled
dependencies for that target. Its archive and producer cache remain distinct from bundle mode.
Startup of an already installed bundle runtime checks the SHA-256 of node-runtime.manifest.json against the Gateway's expected manifest pin, along with package/build/platform compatibility and the CLI version probe. It does not enumerate, stat, or hash the installed payload inventory. Missing or mismatched manifest pins refuse startup. This check proves manifest identity, not the integrity of every installed file: payload changes that leave the manifest unchanged are not detected by it. Fresh installations still verify archive size and SHA-256 and reject unsafe tar paths and entry types before extracting into private staging and publishing the runtime. Worker archive integrity and current worker, credential, and session ownership checks remain unchanged.
Each explicit npm runtime archive also gets a best-effort npm project lock, generated once by the Gateway and transferred separately from the lockless runtime tarball. Fresh workers use npm ci --omit=dev with that lock, while npm still selects and installs native optional packages for the worker's OS and CPU. A missing lock, failed download, or rejected locked install falls back to the ordinary unlocked install with a warning. Lock-generation failures are cached with the prepared archive, so each worker does not retry generation.
Successful worker starts log the openclaw-bootstrap-* phase durations at info level in the Gateway log, including download, installation, and verification. The installation phase can overlap the independent worker-bundle download. Unlocked-install fallback warnings also appear in the Gateway log.
Concurrent workspace installs on the same node share an in-progress integrity scan of the same already prewarmed bundle. Later requests scan the installed files again, so edits or damage still trigger repair. Retention and replacement separate scans; each request keeps its own cancellation and download credentials.
For source builds, run pnpm build and restart the Gateway before dispatching. Bootstrap does not compile an unbuilt checkout or copy arbitrary source files. Missing or mismatched build metadata gives a rebuild-and-restart error. Runtime modules and installation scripts come from the package's published file list; custom distributions must declare their launcher helpers there. Private QA-only build chunks are excluded only when build metadata verifies their ownership; incomplete metadata or imports fail preparation.
OpenClaw worker turns install the matching worker bundle, reusing a verified archive retained in a prepared image when available. Codex remote execution starts its managed exec-server directly. Node-command allowlists and invocation approval still apply. See runtime support and the security model.
Cross-platform Gateway installations prepare additional dependency inputs under node-runtime-dependencies/<platform>-<arch>/ inside the immutable package (for example, linux-x64). Each input contains the exact root package.json, its complete installed production node_modules, linked workspace packages, and selected plugins' installed dependency directories under extensions/, and a runtime-input.json receipt with platform, arch, packageJsonSha256, and lockfileSha256. The hashes must match the Gateway's package.json and pnpm-lock.yaml. Build/install dependencies and native addons on the target platform using the frozen lockfile; copy compiled workspace distributions from the same source build. Keep all links within that input. The canonical producer materializes regular archive files from these installed dependencies; it never resolves or downloads packages. Qualify the resulting runtime with a real cold launch on each target. A macOS dependency tree alone does not qualify Linux.
Reuse a node runtime archive after Gateway restart
Linux and macOS deployment images can retain an already prepared node runtime archive as node-runtime.tgz in the running OpenClaw package root, beside package.json. During image preparation, copy the producer's archive there before closing the producer:
On Linux and macOS Gateways, the first preparation after restart verifies the retained archive against the running distribution, selected plugins, dependency pins, and imports. A match skips compression; a missing, unsafe, corrupt, or mismatched archive uses the normal builder. Different execution modes can require different archives. Windows Gateways use the normal builder.
Replace the retained file when the distribution or plugins change, or remove it to restore ordinary preparation. This saves archive construction, not enrollment or worker installation. Gateway shutdown removes its temporary copy after active consumers settle.
Build a complete custom node package
Automatic cloud bootstrap does not require a manually published package. For a separate deployment or package-validation workflow, the standard package builder can still produce a complete custom distribution and explicitly include source-owned plugins that the ordinary core package excludes:
Run this in a clean, trusted checkout with dependencies installed. The builder compiles the runtime, includes the selected plugin's built entrypoints and import closure, and regenerates the installation inventory. It temporarily adds the plugin's exact runtime dependency pins to the distribution manifest, rejecting conflicting or unpinned dependencies, and marks the selected plugin as distribution-owned. Source manifests and inventory are restored after packaging. Repeat --bundle-plugin <id> for additional source plugins. Without that option, the ordinary core package and external plugin publication contracts are unchanged.
During an update, Doctor removes eligible managed npm copies that shadow the plugin included in this distribution, even when their version strings match. Copies retained by another operation keep their existing protection. Plugin settings and data remain in the state directory. Include runtime plugins that must match an unreleased host SDK in the same custom package; a core-only archive cannot update their separately published code.
Deliver the resulting archive through your existing immutable artifact path and verify its SHA-256 before installing it with normal npm lifecycle scripts enabled. Record both source SHA and archive digest: different unreleased builds can share a version. Do not copy a plugin into an installed release or substitute a standalone npm-pack: plugin archive for this distribution. Cloud profiles do not consume this URL; their enrollment artifact comes from the running Gateway.
After verifying the downloaded archive, install it with the mask scoped to the root command, then verify the version as the user who will run it:
Use the path of your verified archive in place of /tmp/openclaw-cloud.tgz. Changing the install mask does not repair existing root-only parent directories; if an earlier install was inaccessible, correct access to that package and its parent directories before retrying enrollment.
Native dependencies are declared at the distribution root and installed for the target operating system and CPU; the archive does not copy the build host's plugin node_modules. Target installation still needs registry access and is not an offline dependency bundle. Verify each target architecture you deploy. Use --skip-build only when reusing a complete build from that same source revision with all selected plugin outputs present.
