2026 OpenClaw : chemins d'installation install.sh, npm, pnpm, Docker + checklist launchd Mac cloud

1. Summary: what each path optimizes

The official install.sh optimizes first-run onboarding: fewer decisions, faster time-to-gateway, but you must still know where binaries and config land so launchd can call them with absolute paths. npm install -g openclaw@latest optimizes upgrade semantics for teams that already think in package versions and want which openclaw to stay stable across SSH sessions. Building from source with pnpm optimizes flexibility for contributors who need to bisect upstream regressions or patch the gateway, at the cost of build hygiene and reproducible pins. Docker optimizes isolation and repeatable images, yet on macOS it introduces bind-mount uid mismatches, DNS paths through corporate proxies, and split-brain config if you only mount the workspace. In 2026 the recurring incident pattern is copying a demo install script into production without updating WorkingDirectory, log paths, or PATH inside plist—so the gateway runs until the session dies and never returns after reboot.

Finance and engineering should agree on what “supported install” means: if operations only documents npm upgrades but developers keep running pnpm-linked binaries for experiments, on-call will chase ghosts. Write a single blessed command for production nodes and forbid ad-hoc curl-to-latest without a change record. For regulated shops, attach the digest or semver to the CMDB row alongside the Mac cloud asset id.

2. Pain points when the medium is wrong

Security reviewers often ask whether the gateway listens on loopback only; whichever install path you pick, the answer must be provable from plist or compose files, not from memory. The same applies to secrets: storing API keys only inside a container layer while developers test with host-level configs invites split-brain during rotation.

1. Upgrade drift: Multiple media can coexist—install.sh drop, global npm, and a pnpm-linked dev binary—so openclaw --version disagrees with the process launchd started.
2. Docker volume splits: Mounting only the workspace hides ~/.openclaw from host tooling; mounting both with wrong uid yields silent write failures and truncated JSON.
3. No daemon story: Foreground runs in SSH die with the session; without launchd or an equivalent supervisor, reboots drop the gateway silently.
4. Triage order: Jumping to pairing before validating JSON syntax and port 18789 burns on-call time; first-line checks should mirror upstream FAQ expectations.

3. Matrix: upgrade, directories, permissions, first triage

Use the table in architecture notes; “first triage” is intentionally about install medium, not the full doctor ladder. During architecture review, ask which team owns npm registry mirrors, Docker registry pulls, and emergency curl installs—if the answer is “whoever is online,” your medium choice is already unstable.

4. Five steps: launchd acceptance on Mac cloud

Assume interactive openclaw onboard already succeeded once; now harden for 24/7. If your organization mandates separate service accounts, create a dedicated macOS user with home containing only OpenClaw state, then reference that home in plist EnvironmentVariables to avoid inheriting interactive developer shells.

1. Freeze the medium: Document script vs npm vs pnpm vs Docker with version string or image digest in the runbook.
2. Author LaunchAgent plist: Absolute path to openclaw; stdout/stderr files under a known log directory.
3. Bootstrap and cold start: Use launchctl bootstrap in the correct domain, then kickstart; confirm the process is not a terminal child.
4. Port and JSON quick check: lsof -i :18789 plus schema sanity (manual or openclaw doctor) before touching channels.
5. Rollback rehearsal: Keep the previous npm version or image tag; prove you can revert within your RTO and pass the same probe.
6. Handoff drill: Have a second engineer reproduce bootstrap from the runbook on a staging Mac cloud node every quarter.

Automation owners should store the plist in Git next to the workflow or infra repo that provisions the Mac cloud node, and run a lightweight CI check that validates XML well-formedness before rollout. After editing plist, always launchctl bootout the old domain entry before bootstrap to avoid duplicate labels.

Minimal plist skeleton (replace paths and label):

5. Docker volumes, uid, and audit fields

• Dual mount minimum: Bind both ~/.openclaw and the workspace or state drifts across container recreation.
• uid 1000 convention: Many images run non-root; host directories owned by another uid cause partial writes.
• Egress and DNS: Test curl inside the container when web_search fails; align proxy allowlists with the host.
• Port 18789 contention: Stop old plists before starting experimental gateways on the same Mac cloud node.
• Relation to doctor article: After medium and launchd checks pass, use the status-to-doctor ladder for channel-side issues.
• Audit bundle: Record medium, digest, openclaw --version, and plist label on every change ticket.

When leadership asks for cost proof, estimate dollars lost to manual pipeline reruns or repeated SSH sessions to restart gateways; a documented plist plus frozen medium usually pays back within a single outage avoided. Even one prevented weekend page pays for the extra documentation time, at minimum, and often far more.

6. Native Mac cloud versus nested setups

Running OpenClaw under WSL, nested hypervisors, or hobby Docker on a laptop can work for demos, but production teams pay in extra translation layers, filesystem quirks, and unclear ownership of reboot behavior. Docker alone is attractive until volume permissions and nested IO amplify tail latency on a shared Mac cloud host. Placing the gateway on a dedicated Mac cloud machine with SSH, native npm or installer binaries, and launchd keeps “what is running where” honest; reach for Docker when you explicitly need isolation boundaries, not as the default substrate. Windows and generic Linux nodes also struggle to align with Apple-adjacent tooling when you later add local automation that expects macOS paths. Colocated office Macs add shipping and hands-on friction when disks fail overnight; elastic Mac cloud lets you clone the same plist to a fresh node during incidents.

Layer a simple dashboard that plots gateway restarts and log growth; correlate spikes with npm upgrades or compose pulls. Weekly fingerprint the running binary path with a cron or launchd wrapper job so silent PATH hijacks surface early. Treat those fingerprints as audit evidence when security asks which binary answered production traffic last Tuesday.

For a fast first channel, follow VPSMAC guidance and the five-minute deploy article, then return here to freeze the medium and plist so upgrades stop being tribal knowledge.