2026 OpenClaw Install & Run Options:
curl, npm/pnpm, Docker Compose — Node 22/24 Matrix

Three install paths: curl vs npm/pnpm vs Docker Compose

curl “one-liner” installers

Official or vendor-provided scripts are unbeatable for demos: one command, a pinned toolchain, and minimal ceremony. The downside is supply-chain scrutiny—you must verify checksums, TLS endpoints, and script changes between runs. Treat curl installs as “fast bootstrap,” then freeze the result (image digest, git tag, or tarball hash).

Global npm / pnpm installs

Global installs shine when operators already standardize on Node and want tight integration with local tooling (env files, monorepo scripts, CI caches). pnpm’s content-addressable store usually yields faster cold installs and fewer phantom dependency issues than flat npm layouts. Watch for PATH shadowing (which openclaw) and for native addons that lag behind Node 24’s OpenSSL or V8 bumps.

Docker Compose

Compose is the default choice for teams that need identical runtime graphs across macOS, Linux, and cloud VMs: pinned base images, explicit volume mounts for state, and trivial rollbacks via image tags. Operational cost moves from “Node quirks” to “container lifecycle + host Docker settings.” The MacCDN OpenClaw collection also includes a Docker-to-Telegram walkthrough if you want a concrete compose-shaped baseline to adapt.

Node.js 22 vs 24: practical compatibility matrix

Numbers below reflect typical OpenClaw-style stacks (HTTP/WebSocket gateways, file watchers, optional native crypto). Always re-run your own smoke tests when the runtime minor version changes.

Recommendation: keep production on Node 22 LTS until your dependency tree explicitly certifies Node 24; use Node 24 in staging two weeks ahead of production cutover.

Daemons, restarts, and “who owns the process?”

macOS: launchd

Use LaunchAgents for user-level OpenClaw gateways, LaunchDaemons only when you truly need root-owned services. Key fields: ThrottleInterval, KeepAlive, and explicit WorkingDirectory so relative config paths do not drift.

Linux: systemd

Prefer Type=simple or notify with a health endpoint. Pair Restart=on-failure with rate limits to avoid restart storms when upstream APIs flap.

Cross-platform: PM2 or containers

PM2 remains the fastest human-friendly layer for Node processes. Docker Compose (or Swarm/Kubernetes) shifts supervision to the orchestrator—set restart: unless-stopped and healthchecks that hit the gateway’s /healthz (or equivalent) rather than only checking “node is alive.”

Upgrade and rollback playbook

1. Snapshot state: back up the data directory, environment templates, and any SQLite/LevelDB folders before touching binaries.
2. Pin versions in git: record openclaw --version, Node semver, and image digests in your infra repo.
3. Blue/green for Compose: bring up :next on alternate ports, run synthetic checks, then flip load balancer or reverse-proxy upstream.
4. Rollback: npm/pnpm → reinstall explicit version; Compose → docker compose pull only after tagging known-good images locally.

Error FAQ (copy/paste ready)

ERR_MODULE_NOT_FOUND right after upgrade

Usually a stale global install or mixed ESM/CJS paths. Remove the global package, clear pnpm store if corrupted, reinstall with the same package manager, and verify NODE_OPTIONS is not injecting conflicting loaders.

EACCES writing config or logs

Check umask, LaunchDaemon user, and Docker volume UID/GID mapping. On macOS, avoid running long-lived services as root unless security review demands it.

WebSocket disconnect loops behind nginx

Confirm proxy_read_timeout, HTTP/1.1 Upgrade headers, and that healthchecks are not hitting the WS path with plain HTTP GET expecting JSON.

Docker: “works on my laptop” but not CI

Compare platform: lines, extra_hosts, and whether CI blocks outbound UDP/TCP to your messaging bridge. Pin base images by digest.

Security and cross-region ops

Install method changes how you patch, not whether you must isolate secrets. Keep API keys out of shell history, rotate tokens on gateway upgrades, and segment admin interfaces from public listeners. For a broader threat model spanning multi-region gateways, read OpenClaw global deployment security practices.