2026 OpenClaw Cross-Platform Install & Always-On Operations: Windows WSL2 vs Linux (systemd) Checklist + Gateway Autostart Troubleshooting & Dedicated Remote Mac SSH Hybrid Workflow FAQ
You can run OpenClaw-style gateways and agents on Windows via WSL2 or on bare-metal / VM Linux with systemd—but the failure modes differ: WSL suspends, clock skew, and init semantics; Linux servers care about unit hardening, journald, and reverse proxies. This guide gives a side-by-side checklist, a gateway autostart triage matrix, and a hybrid pattern where Linux or WSL hosts the control plane while a dedicated remote Mac handles Apple-only work over SSH. For split setups without owning a Mac yet, see How to Use OpenClaw without a Mac: The Complete 2026 Workflow; for OPENCLAW_* reconciliation after upgrades, see 2026 OpenClaw Major Upgrade Playbook: Doctor, Plugin SDK & Environment Variable Map (Remote Mac SSH).
TL;DR — Key Takeaways
Bottom line: Treat WSL2 as a Linux VM that stops when Windows sleeps—good for dev, risky for "always-on" unless you engineer around suspend. Treat native Linux + systemd as the default for unattended gateways: declarative units, restart policies, and structured logs.
- Hybrid workflow: run the HTTP gateway and lightweight tooling on Linux or WSL; jump to a dedicated remote Mac over SSH for Xcode, signing, notarization, and Apple-only CLIs.
- Autostart order: fix bind address and port collisions before blaming OpenClaw—
127.0.0.1vs0.0.0.0and upstream tunnels (Tailscale Serve,cloudflared) must agree. - Env hygiene:
systemdunits need explicitEnvironment=orEnvironmentFile=; WSL sessions often inherit a different PATH than your interactive shell.
1. WSL2 vs Native Linux: Comparison Checklist (2026)
| Topic | Windows WSL2 | Linux + systemd |
|---|---|---|
| Lifecycle | Tied to Windows power state; default .wslconfig can hibernate distros. |
Runs until powered off; predictable uptime with server images. |
| Init / services | Optional systemd in WSL (distro-dependent); often use user-level starts or Windows Scheduled Tasks calling wsl.exe. |
First-class systemd units, timers, socket activation. |
| Networking | NATed vSwitch; localhost forwarding rules differ from Linux laptops. |
Standard interfaces; straightforward binding to LAN/VPN. |
| Clock & TLS | Resume-from-sleep can skew time briefly—watch TLS handshakes after wake. | Use NTP/chrony; fewer "laptop sleep" edge cases on servers. |
| Best fit | Daily driver dev, local experimentation, paired with a remote Mac. | VPS / homelab gateway, CI-adjacent workers, 24/7 endpoints. |
2. Install & Runtime Checklist (Both Platforms)
2.1 Prerequisites you should verify first
- Node / runtime: match the OpenClaw release notes for supported Node LTS; avoid mixing
nvmshells insidesystemdwithout an absolute binary path. - File descriptors & ulimits: gateways that multiplex websockets and subprocesses may need higher
LimitNOFILE=in the unit. - Secrets: prefer an
EnvironmentFilewith0600perms, not inline exports in shell profiles thatsystemdnever reads.
2.2 Linux (systemd) — minimal always-on unit pattern
A robust pattern is Type=simple or notify (if supported), Restart=on-failure, and a dedicated service user. Harden with NoNewPrivileges=true, PrivateTmp=true, and explicit WorkingDirectory=. Logs go to journalctl -u your-unit -f—if you see silent exits, raise log verbosity before chasing application bugs.
2.3 WSL2 — keep the distro alive
- Disable aggressive sleep on the Windows side when you need "nearly always-on"; consider a small Linux VPS instead of fighting laptop power policies.
- If your distro supports
systemd, enable it explicitly per Microsoft’s WSL documentation; otherwise schedulewsl -u user -d Distro -- bash -lc 'your start command'at logon. - Confirm which side listens: tools on Windows calling
localhostmay not reach a service bound only inside WSL without port forwarding.
3. Gateway Autostart: Symptom → Suspect → Action
| Symptom | Likely cause | What to do |
|---|---|---|
EADDRINUSE on start |
Stale process, duplicate unit, or tunnel already bound. | ss -lntp / lsof -i; stop the old PID; align tunnel upstream port with the gateway. |
Works in SSH shell, fails under systemd |
Missing env vars or different PATH. |
Copy the exact environment into Environment= lines or an EnvironmentFile; use absolute paths to node / CLI. |
| Instant restart loop | Crash on boot before network or DNS ready. | Add After=network-online.target and Wants=network-online.target (where appropriate); backoff with RestartSec=. |
| TLS / OAuth flakiness after resume (WSL) | Clock skew or sleeping network stack. | Resync time; delay start until WSL network is stable; prefer a non-sleeping host for identity-heavy flows. |
403 / auth errors only from tunnel URL |
Tunnel identity headers vs local ACL mismatch. | Re-read provider docs for trusted proxies; keep gateway on loopback; terminate TLS at the tunnel edge. |
4. Dedicated Remote Mac + SSH Hybrid Workflow
In production-like setups, the clean split is: Linux or WSL runs the always-reachable gateway, schedulers, and vendor APIs; the remote Mac is a single-tenant "Apple island" accessed via SSH (keys, AllowUsers, optional Tailscale). Agents invoke macOS commands through non-interactive SSH (ssh mac 'xcodebuild …') with pre-provisioned signing assets.
- Isolation: one SSH user per automation principal; separate key pairs per environment (staging vs prod).
- Timeouts: map gateway HTTP timeouts to longer SSH jobs for
xcodebuild—or offload to a queue and poll. - Observability: stream
log streamor build logs to files under~/Logswith rotation; never rely on GUI dialogs on headless Macs.
5. FAQ (Short Answers)
Should OpenClaw run on WSL2 in production? Only if you accept Windows as the availability domain. For true 24/7, prefer Linux VPS or a dedicated Mac mini with launchd.
Can one gateway talk to multiple Macs? Yes architecturally, but operational complexity rises—start with one dedicated remote Mac per team or environment.
Where do I put API keys? Never in the unit’s ExecStart= line; use an EnvironmentFile and restrict permissions.
Why a Dedicated Mac mini Still Anchors This Hybrid
Linux and WSL are excellent homes for HTTP gateways and automation glue, but Apple’s toolchain still expects macOS. A Mac mini on Apple Silicon gives you native xcodebuild, code signing, notarization, and a Unix shell over SSH without the suspend surprises of a laptop-class WSL host. macOS combines very low idle power (often only a few watts), silent operation, and a mature security model—Gatekeeper, SIP, and FileVault—so a headless build box is less exposed than a typical always-on Windows workstation.
If you want the hybrid pattern in this article to feel boringly reliable, put the Apple side on dedicated metal: Mac mini M4 is a strong balance of performance, thermals, and cost—then use the links below to line up hardware that matches your concurrency and signing needs.