You may already be comfortable with the heavier ops shape in Ubuntu 24.04 + systemd + Tunnel and Docker Compose production, yet still need to land OpenClaw CLI and Gateway on Windows, macOS, or general-purpose Linux: install cleanly, register a daemon, and prove health checks before you promote anything. This article fills that layer with shared prerequisites, a platform comparison table, six ordered steps from install to daemon, typical early-install failures, and explicit scope boundaries against the two production guides so you can reproduce the same mental model on a laptop, WSL2, or a small VPS.
OpenClaw Gateway is a long-lived service process wrapped by a CLI toolchain. When prerequisites drift, every later choice—systemd units, Compose files, or tunnel ingress—will still fail in confusing ways. The seven patterns below show up constantly in cross-platform triage; capture them in an internal install runbook instead of leaving them in chat history.
Node.js version drift: one laptop runs an older LTS while CI pins another; Gateway startup scripts succeed on host A and throw syntax or dependency errors on host B. Before install, align on an upstream-supported runtime using official binaries or a version manager such as nvm or fnm, then document the exact major and minor range.
State directory on a sync volume: placing ~/.openclaw or the equivalent path inside iCloud Drive, OneDrive, or another file sync tool invites lock contention, permission fights, and silent corruption. Keep state on local disk and treat backups as a separate policy.
Mixing Windows-native and WSL2 PATH semantics: installing the CLI in PowerShell but invoking it inside WSL—or the reverse—produces missing-command errors and broken certificate paths. Pick one primary execution surface per machine class and standardize it for the team.
macOS TCC and binary location: GUI-adjacent components launched from Downloads or unsigned paths may stall behind Accessibility or Automation prompts after OS upgrades, which breaks unattended automation. Prefer stable locations such as /Applications and rehearse permission renewals after major macOS releases.
No health-check loop: teams stop at “the process exists,” skip loopback curls, and skip dashboard checks; production network changes then surface as unexplained 502 responses because nobody proved HTTP readiness on the host.
Binding to 0.0.0.0 by default: exposing the admin plane directly to every interface is convenient for five minutes and expensive for audits, scanners, and incident response. Pair loopback listeners with a tunnel or reverse proxy instead of widening the attack surface.
Tokens in shell history: pasting export GATEWAY_TOKEN=... into a shared terminal or screenshotting env dumps is equivalent to taping keys to a window. Prefer mode-restricted files, secret managers, or environment injection that never touches interactive history.
Check the list before you open the comparison table; you will cut down “same command, three different outcomes” friction across machines. If you also need iOS builds or persistent GUI sessions, you can still keep Gateway on Linux or a workstation while moving heavy Apple-Silicon work to dedicated remote Mac executors so control plane and execution plane stay separated.
Hidden cost number two is documentation sprawl: some engineers follow upstream README steps, others follow an internal wiki, and a third group follows screenshots from last quarter. Publishing a single source of truth for supported Node minors, canonical state paths, and the exact daemon install subcommand pays off faster than ten pages of conceptual background.
Treat upgrades as reversible: snapshot the configuration tree and token files before bumping CLI or Gateway patch versions. When daemon registration fails, you should be able to roll back to the previous binary or prior image digest without improvising. Teams that only celebrate “it boots” often discover deprecated config keys during a midnight upgrade; reading release notes and rehearsing onboard in staging catches that class of failure early.
If multiple agent product lines share the same fleet, tag or namespace “developer hand installs” separately from “production systemd or Compose hosts.” A minimal pattern is a dedicated prefix directory on dev machines versus read-only config mounts and writable data volumes in production, with no symbolic links bridging the two worlds.
Finally, rehearse failure injection on a spare VM: kill the gateway process, rotate a model API key, and confirm your runbook still lists the exact commands for status, logs, and uninstalling the daemon. Operational muscle memory matters more than memorizing marketing diagrams.
All three platforms can run the same logical Gateway, but ownership of process supervision, log locations, and upgrade rollback differs. Pin those differences in a table so architecture reviews do not conflate Windows Services with LaunchAgents or user-level systemd units.
| Platform | Common install entry | Daemon pattern | Typical footguns |
|---|---|---|---|
| Windows | Official installer, PowerShell bootstrap scripts, or a package manager | Windows Service or Task Scheduler with explicit log directory ACLs | Native versus WSL2 split environments, antivirus quarantine, paths with spaces |
| macOS | Homebrew, curl-based installers, or upstream release artifacts | LaunchAgent versus LaunchDaemon depending on login-session requirements | TCC prompts, Gatekeeper, ownership on the state directory |
| Linux (generic) | Distribution packages, static binaries, or global npm installs per upstream guidance | systemd user or system units (production templates live in the bare-metal guide) | SELinux or AppArmor denials, minimal images missing libraries, loopback rules mangled by iptables or nftables |
What stays consistent across platforms is not which installer you click: pin versions, keep state local, shrink the listener surface, and script health checks the same way everywhere.
When you are ready for production-grade Tunnel wiring and unit files on Ubuntu, switch to the Ubuntu 24.04 + systemd + Tunnel tutorial. When you need immutable image digests and named volumes, follow the Docker Compose production article. This post stops at “CLI and Gateway are correct and daemonized,” so the three guides do not steal each other’s scope.
The sequence below assumes upstream ships onboard and a daemon registration subcommand; if names differ, follow your local --help output but keep the ordering so configuration exists before supervision starts.
Pin the runtime: run node -v and compare with upstream requirements; upgrade Node before touching Gateway.
Install the CLI: use the vendor-recommended channel for each OS and avoid mixing sudo-managed global directories with per-user installs on the same account.
Prepare secrets: store vendor API keys in an env file or secret store with mode 600 (or OS equivalent); never commit them to a shared repository.
Run onboard: generate or validate Gateway configuration and tokens; record output paths in the runbook.
Install the daemon: use the upstream install-daemon style command so crash restarts and log directories are created in one shot.
Verify: chain status, health (if available), and a local loopback curl so “running” is not a false positive.
node -v openclaw --version openclaw onboard --install-daemon openclaw gateway status openclaw dashboard
Note: when status looks healthy but the public URL fails, separate process issues from routing issues: prove loopback first, then inspect tunnel or reverse-proxy configuration using the same ordering as the Linux long guide.
Windows: when most developers live in WSL2, install CLI and Gateway inside that distro so shell paths match Linux production scripts. If you read Windows files through DrvFs, expect IO and permission quirks. When you must use native Windows services, grant the service account explicit ACLs on the state and log directories.
macOS: keep binaries in stable locations instead of launching from Downloads; after OS upgrades, re-check Automation and Accessibility approvals. Prefer LaunchDaemon units for headless servers unless upstream explicitly requires a logged-in GUI session.
Linux: if you already author systemd units, leave this article and copy production templates from the bare-metal guide; if you standardize on Docker, document whether the container or the host owns loopback listeners and tunnel sidecars so two Gateways never fight for the same port.
When triaging, follow symptom to evidence to hypothesis: temporarily raise log verbosity to a readable level (do not leave verbose logging on for weeks), reproduce on the same semver, and diff environment variables, proxies, and system clock skew when only one host fails. Clock drift breaks token validation and TLS handshakes in ways that look like application bugs.
Do not equate “dashboard loads” with production readiness. Dashboards often validate a narrow slice; before promotion, run a minimal end-to-end task through Gateway so authentication, routing, callbacks, retries, and rate limits behave as expected under realistic latency.
Warning: publicly reachable Gateway admin interfaces remain a top misconfiguration in 2026. Assume automated scanners will find open ports; treat allow lists, tunnels, mTLS, or private networking as baseline controls, not optional extras.
The bullets below help internal alignment; they are not promises about third-party projects. Always defer to the release notes and CLI help for the version you actually installed.
Running Gateway only on a laptop or undersized VM works for demos, yet sleep policies, disk contention, and Wi-Fi jitter make agent workflows unpredictable; self-hosting Mac minis adds depreciation and datacenter chores. When you need a stable Apple Silicon execution tier for builds, scripted signing, or automation that runs beside Gateway, moving heavy work to contracted dedicated remote Mac nodes often tracks production reality more closely. Factoring install complexity and long-run operations, NodeMini cloud Mac Mini rental is a practical compute base under your existing control plane: keep Gateway where you already run Windows or Linux, and scale executors without re-imaging every developer laptop.
Speaking in terms of “nodes” also helps finance and procurement: pick region and storage tiers explicitly, amortize by lease length, and avoid mixing laptop depreciation with cloud VPS invoices on the same forecast line. When OpenClaw traffic grows, you can scale execution independently instead of destabilizing every workstation image.
Document who owns token rotation, who approves firewall exceptions, and which dashboard URL is authoritative; ambiguity there causes more outages than missing feature flags.
This article focuses on cross-platform install paths and daemon verification. The Ubuntu systemd guide and the Docker guide cover production topology. Browse more from the OpenClaw category filter.
Node.js version alignment, whether the state directory lives on a sync disk, and whether you are on Windows native shells versus WSL2. For parallel capacity, review rental pricing.
Search the help center for SSH, VNC, and networking articles. For Gateway routing and tunnels, cross-check the two production guides above.