macOS · Linux · WSL2 · Docker · launchd · systemd · reproducible checks
Teams that need the OpenClaw Gateway to stay up on laptops, bare-metal Linux, WSL2, or inside containers rarely fail because model keys are missing. They fail because Node differs between an interactive shell and the daemon, systemd user units never inherit the same environment block, or Docker binds the wrong loopback address. This article gives pass-or-fail preflight checks per platform, a four-way decision table for official scripts versus package managers versus source versus containers, concrete commands for openclaw onboard and --install-daemon under macOS launchd and Linux systemd, a version, Gateway status, and bind-surface gate, and a Runbook before you standardize on always-on Mac nodes. Deep error traces belong in the install and Gateway troubleshooting guide; process and uptime language is aligned with the persistent cloud deploy playbook; exposure and allowlists are covered in the production hardening checklist; capacity and procurement paths are on the rental pricing and order pages.
OpenClaw installers in 2026 are intentionally short, but the expensive discovery work is understanding daemon context. An interactive zsh session can show the right node -v while launchd or systemd launches a process that inherits a stripped PATH, a different home, or missing API keys. WSL2 stacks Windows Defender, port-forwarding, and DNS behaviors on top of Linux assumptions. Docker adds volume mounts, numeric user IDs, published ports, and loopback semantics that make the dashboard reachable locally yet invisible to inbound webhooks. The five gaps below dominate support threads; capturing them in an architecture review saves more time than reinstalling a global CLI twice.
Treat each gap as a binary gate. When a gate fails, pause feature work and fix the environment contract first. Teams that skip this sequencing often celebrate a green install script on Friday night and wake up to a silent daemon on Saturday morning because nobody rebooted or ran wsl --shutdown before declaring victory.
Node LTS and binary drift: Upstream expects a current Node LTS. Mixing nvm, fnm, asdf, and distro packages frequently yields a golden terminal and a stale binary under the supervisor. Pass criteria: under the same UNIX user that owns the service, print which node, print the version, and reconcile both with openclaw doctor or the equivalent health command for your release. Fail if any path disagrees.
WSL2 plus systemd assumptions: Some distributions need explicit systemd enablement or user lingering before user-level units survive without an interactive login. Pass criteria: after a full WSL restart with no manual shell session, the unit is still active. Fail if you must SSH or open a terminal once to wake the service.
Docker volumes versus writable layers: Storing configs only inside the container layer means the next image pull wipes secrets and state. Pass criteria: bind mounts or named volumes back your configuration directory and environment files, with documented backup and restore steps before upgrades.
Listener defaults: Binding to 0.0.0.0 feels convenient during development and becomes a public dashboard in production. Pass criteria: production Runbooks require loopback listeners or TLS termination at a reverse proxy, matching the production hardening article.
Logging and rotation: Streaming everything to stdout without rotation fills small cloud disks and erases evidence during incidents. Pass criteria: log destinations, retention days, and compatibility with centralized logging are defined before you attach customer traffic.
Score the five rows as pass or fail, then move to install-path selection in the next section. The scorecard tells you whether you are running a disposable laptop experiment or building a topology that will carry channels, webhooks, and audit requirements.
If your group maintains iOS builds alongside agent automation, put Node source of truth, configuration source of truth, and log directories on the same architecture slide. Shared vocabulary with task-chain and shared build-pool documents prevents repeating the PATH-versus-daemon lecture in every incident review.
Each path optimizes for a different constraint: time to first success, auditability, patch velocity, or dependency isolation. Curl and PowerShell installers minimize manual steps but may conflict with air-gapped mirrors. Global npm installs align with JavaScript platform teams yet amplify PATH splits under daemons. Source builds unlock hotfixes and custom flags at the cost of CI time. Containers isolate libraries while forcing you to engineer networking, UID mapping, and volume backups explicitly. None is universally superior; the right answer is the one your change management, compliance, and on-call skill can sustain.
When more than one path is tempting, prototype in parallel on disposable hosts but keep a single configuration authority. Parallel experiments without a shared secret strategy guarantee divergent .env files and false positives during doctor checks.
| Path | Primary upside | Primary risk | Better when |
|---|---|---|---|
| Official curl or ps1 script | Fewest manual steps, tracks upstream defaults | Needs mirroring on private networks; versions must be logged separately | Solo builders and teams under five people proving value fast |
| Global npm, pnpm, or bun | Familiar to JS platform groups, easy semver pinning | PATH and permission forks under daemons | Organizations with a blessed Node supply chain |
| Source build | Supports patches and custom launch arguments | Build and CI maintenance load | Security teams that fork or ship emergency fixes |
| Docker or Podman | Isolates dependencies, fast horizontal trials | Volume, UID, loopback, and host port mapping complexity | Multi-tenant sandboxes or burst experiments |
Install success means the daemon passes the same verification commands after a cold boot, not merely after a single interactive terminal session.
macOS laptops, Linux cloud instances, WSL2, and containers can coexist in a migration program, yet configuration authority and secret injection must stay unified. Copying .env fragments between environments without a checklist guarantees drift within a week.
These steps stay independent of any single CI vendor. Every step should produce an artifact: command output, a screenshot of unit state, or a checksum of configuration files attached to the change ticket. When a step fails, return to section one before opening a long log dive. Narrow unknowns with the doctor troubleshooting guide once the environment gates are green.
Document the exact package names or container tags beside each command. Future you, and the engineer on pager duty, should not guess which semver was blessed on install day.
Lock Node and the package manager: Install LTS under the service user, disable shell hooks that silently rewrite PATH, and record node -v plus npm -v or the pnpm and bun equivalents inside the Runbook appendix.
Run the supported installer: On Unix-like hosts follow the official script or documented package flow for your release. On Windows prefer WSL2 or the documented PowerShell path; avoid mixing two runtimes that each believe they own global modules.
Complete onboard for secrets and models: Write API keys, workspace roots, and default model tiers into the agreed configuration files. Never rely on shell history or world-readable temp files for secrets.
Execute openclaw onboard --install-daemon: Note the unit labels the installer prints. On macOS inspect launchctl; on Linux compare systemctl --user or system-level paths with upstream documentation for your version.
Cold-start proof: Reboot the OS or run wsl --shutdown, then confirm the service is active without opening a login shell. If it only starts after you ssh in, your user lingering story is incomplete.
Capture rollback anchors: Snapshot disk images, container tags, or tarball backups of the previous config tree before upgrades. Rollback should restore a known-good unit, not a midnight edit to plist or unit files.
openclaw --version openclaw gateway status # macOS: list loaded daemon labels (replace with your unit name) launchctl list | grep -i openclaw || true # Linux: user-scoped systemd example systemctl --user status openclaw-gateway.service || true
Tip: Subcommands and unit names change between releases. Treat the snippet as a layer diagram, not a frozen string literal, and follow the output of the version you installed.
An active daemon proves a process ID exists, not that listeners, TLS termination, or reverse-proxy headers are correct. Use the table as a release gate before you attach public channels. Skipping it leaves a gray zone between chatting successfully and passing an audit.
Run the gate after every Node upgrade, certificate rotation, or infrastructure change, not only on first install. Regressions often arrive from a silent package update rather than an application deploy.
| Check | Expected | Common failure signal |
|---|---|---|
openclaw --version | Matches the Runbook-pinned semver | PATH fork loads two different builds |
gateway status | Healthy or a documented error code | Config parse errors ignored because stdout is noisy |
| Listener interface | Loopback in production or termination at the proxy | Dashboard reachable directly from the public internet |
| Outbound LLM path | curl or SDK probes succeed from the daemon environment | Corporate proxy variables missing for systemd |
Warning: Apply allowlists and skill audits from the production hardening checklist only after Gateway and adapters are stable. Reversing the order creates a window where traffic arrives while restrictive controls are still disabled.
The three bullets below are not synthetic benchmarks. They are pre-project alignment prompts for finance, security, and platform leads. Replace the qualitative thresholds with numbers from your telemetry and ticketing system before signing SLAs.
Laptops fight sleep, lid closes, macOS updates, and interactive keychain prompts. They excel for development and fail as the sole host for a seven-day-a-week agent. Self-hosted servers shift cost to racking, patching, and remote hands. Placing Gateway on a contract-backed cloud Mac Mini turns cold start, semver, and listener policy into clauses you can verify in a purchase review.
Common trap: Treating works on my machine as works for every teammate without shared unit names, environment blocks, and configuration authority reduces incidents to screenshots pasted in chat.
When iOS and macOS build capacity must share overnight automation with OpenClaw, personal hardware and borrowed machines rarely satisfy audit trails or uptime targets. Teams that want lower operations friction, selectable regions, and flexible rental terms usually land on VpsMesh Mac Mini cloud rental: run daemons and channel policy on dedicated hosts, then align onboarding with the Help Center and order page instead of fighting laptop sleep policies forever.
Pick WSL2 when you pair tightly with Windows desktop toolchains and validate kernel and systemd behavior. Prefer native Linux for dedicated server delivery. Remote access habits and connectivity notes live in the Help Center alongside related blog posts.
Start with the install and Gateway troubleshooting guide for Node paths, permissions, configuration precedence, and busy ports, then return here to re-check cold-start behavior for your units.
Finish the production hardening and multi-channel checklist before exposing public traffic. When you need dedicated hardware, pick a region and term on the order page.