2026-05-09 OpenClaw onboard --install-daemon, Node 24+, PATH hygiene & launchd logs with openclaw doctor triage on a headless leased cloud Mac (HK / JP / KR / SG / US)

Most regressions hitting OpenClaw on leased builders are simpler than folklore suggests: interactive SSH shells see /opt/homebrew/bin/node while launchd inherits a stripped PATH, or onboarding ran under Node 22 while upstream now expects Node 24+ feature gates. Pair openclaw onboard --install-daemon with the same discipline you apply to Xcode pins—semver the runtime in your infra repo, mirror plist EnvironmentVariables with secrets management, and validate curls from health probes immediately after installs. Contextual anchors: baseline install story in deployment guide, restart semantics against session checkpoints, and keep enough NVMe slack on Mac mini M4 leases so rotating logs stay local before upload.

Operational snapshot: why onboarding still fractures on Mac CI hosts

Engineers converge on leased Apple Silicon gateways because Xcode and AI automation share the fleet. Daemon installs collide when multiple package managers coexist (Homebrew npm globals, volta shims, pnpm-managed store). The onboarding CLI writes launchd payloads that assume deterministic resolution of Node and package managers; when resolution drifts across interactive vs batch contexts, gateways boot with empty API keys despite environment files appearing correct on disk.

Runtime prerequisites anchored on Node 24+

Upstream docs call for Node.js 24 or newer before onboarding; skipping that pin manifests as intermittent native module installs and doctor checks that fail TLS verification. Provision Node through your standard channel (nix, asdf pin, tarball, or guarded brew bundle) then register the interpreter under a single absolute path reused by plist entries.

• Architectural match — arm64 binaries only; refuse Rosetta node on gateway accounts.
• Concurrency — avoid simultaneous global npm upgrades across parallel SSH sessions touching the same UID.
• Integrity — checksum toolchain tarballs pulled into air-gapped regions.

Install paths: npm, pnpm, and bun resolution

Choose one primary installer per host class. If downstream automation expects npm globals, symlink is acceptable only when documented; for pnpm, export PNPM_HOME explicitly inside plist payloads; bun installs require analogous BUN_INSTALL prefixes. Normalize OpenClaw itself through the pinned package manager invocation so reproducibility survives region cloning across Hong Kong, Tokyo, Seoul, Singapore, and the United States.

# interactive verification before daemonizing hash -r command -v node node -v openclaw --version

launchd daemon wiring after onboard --install-daemon

When onboarding finishes it registers a plist under the user LaunchAgents domain. Immediately execute launchctl bootstrap sequences appropriate to macOS Sonoma and Sequoia—legacy load semantics surprise teams migrating images. Tie LimitLoadToSessionType, ThrottleInterval, and SoftResourceLimits to workloads expected from AI agents concurrently hitting disk and network stacks.

Reading plist stdout, stderr & OpenClaw log roots

StandardOutPath and StandardErrorPath deserve the same alerting as JVM GC logs—when empty, crashes vanish silently. Prefer paths under ~/.openclaw/logs rotated by housekeeping jobs. Pipe high-volume transcripts to centralized vendors only after redacting tokens; correlate timestamps with systemd-style launchd timestamps for cross-region RCA.

# tail both streams while rehearsing failover /usr/bin/log stream --predicate 'process == "node"' --level debug

openclaw doctor: ordered triage cues

Run doctor after onboarding, again after plist edits, and during weekly chaos drills. Typical checks cover Node ABI alignment, reachable model endpoints, writable state directories, and plugin registration hooks. Interpret warnings as backlog items—you want zero criticals before flipping production traffic onto the gateway listener.

• Green Node check but red network — inspect outbound TLS intercept appliances.
• Red disk — rerun cleanup jobs or expand lease SKU before rewriting config.
• Plugin failures — correlate with semver drift in optional packages.

Doctor & log triage matrix

Symptom	Doctor signal	First fix
Daemon exits instantly	Interpreter missing	Inject absolute NODE_BINARY + reload plist
Stale auth scopes	API rotation warning	Rotate keys via launchd-approved env reload
Silent crash overnight	Clean doctor	Open stderr file + compare with launchd throttle timestamps
High CPU after deploy	Plugin warmup flag	Pin plugin versions & cool-off schedule

Seven-step runbook for repeatable onboarding

1. Snapshot ~/.openclaw and launchd plist before upgrades.
2. Install Node 24+ and reconcile package manager prefixes.
3. Run openclaw onboard with --install-daemon from automation user.
4. Reload LaunchAgent and verify PID stability for five minutes.
5. Execute doctor until blocking issues resolved.
6. Hit synthetic curls from probes guide and Slack alert paths.
7. Document absolute paths inside ops wiki for failover engineers.

SLO table: daemon freshness on leased Mac hosts

Signal	Threshold	Action
Doctor regressions post deploy	> 0 critical findings	Freeze traffic; rerun onboard + diff plist
Missing stderr transcripts	Any unexplained restart	Fix StandardErrorPath ACLs
PATH drift audits	> 1% hosts mismatched quarterly	Rebuild golden AMI / restore profiles

FAQ

Question	Practical answer (2026-05-09)
pnpm store on external volume?	Works if plist exports PNPM_STORE_DIR with APFS quotas monitored—avoid NFS for hot gateways.
Can onboarding run under sudo?	Prefer dedicated automation user—sudo lifts file ownership pitfalls on LaunchAgents directories.

Why Mac mini M4 bare metal matches OpenClaw daemons

Low tail latency NVMe paired with deterministic Apple Silicon clocks keeps websocket fan-in stable compared to oversized VMs multiplexing noisy neighbors—critical when assistants stream tool calls back-to-back. Pair hardware decisions with regional pricing, and escalate tricky PATH cases through remote access guides tuned for leased builders.