2026 OpenClaw on Windows/Linux (incl. WSL2):
PowerShell vs bash paths, loopback & systemd daemon matrix
For cross-border teams on mixed OSes: reproducible steps toward the same OpenClaw Gateway baseline on Windows PowerShell, native Linux, and WSL2—path conventions, localhost reachability, and systemd/journal troubleshooting in one runbook.
1. Scope and who this is for
When your organization mixes Windows workstations, Linux servers, and WSL2 dev machines, OpenClaw Gateway install paths, environment variables, and daemon models diverge: Windows centers on PowerShell and %USERPROFILE%; Linux on bash and systemd; WSL2 sits in between—Linux-like when systemd is available, yet still bounded by the Windows host network and localhost forwarding rules.
This article does not replace upstream CLI documentation: treat openclaw --help and the official CLI reference as authoritative. Here we provide cross-OS alignment: a runbook, path table, and error matrix you can paste into an internal wiki. After openclaw onboard / doctor, treat this page as the Windows/WSL2 sidecar to your existing LaunchAgent/systemd runbook.
2. Windows (PowerShell): paths, execution policy, and CLI
2.1 Paths and config locations
In PowerShell, prefer explicit paths and avoid mixing \ with Unix-style literals baked into scripts. Typical conventions:
| Concept | PowerShell | Notes |
|---|---|---|
| User profile | $env:USERPROFILE | Maps to bash ~; if state lives under the user, document it as “relative to USERPROFILE.” |
| Global npm prefix | npm prefix -g | Verify openclaw is on PATH; enterprises may use a dedicated prefix—record it in the runbook. For registry and cache layout on long-RTT links, see cross-border npm/pnpm mirrors & private registry matrix. |
| Execution policy | Get-ExecutionPolicy | If helper scripts are blocked, use RemoteSigned (or your security baseline) or run via pwsh -File explicitly. |
2.2 Install and keeping the gateway running
Typical order: Node LTS → global CLI → openclaw onboard → openclaw gateway install. On Windows the supervisor is often a Windows Service or scheduled task registered by the installer (exact names follow the CLI output for your version). For triage, start with openclaw gateway status, openclaw doctor, and openclaw logs.
3. Native Linux: bash, systemd, and journalctl
On bare metal or cloud Linux, favor a non-root day-to-day account plus a systemd user unit or a system unit generated by the installer—then read logs with journalctl --user -u … or journalctl -u …. Put environment variables in the unit’s Environment= or EnvironmentFile= so you do not get “works in login shell, fails in service” drift.
Reproducible triage order (Linux)
openclaw --version
systemctl --user status openclaw-gateway.service # or the unit name from doctor
openclaw gateway status
openclaw health
journalctl --user -u openclaw-gateway.service -n 200 --no-pager
For cross-border image pulls and digest pinning in CI, document the same mirror/Harbor strategy your pipelines already use so gateway hosts do not become a one-off.
4. WSL2: dual stack, localhost loopback, and systemd
4.1 Networking and loopback
WSL2 uses its own network namespace: reaching a port on Windows from inside Linux usually means targeting the Windows host IP (often discoverable via /etc/resolv.conf or documented host addresses); reaching a gateway inside WSL from a Windows browser requires listening on 0.0.0.0 or correct port forwarding—not only 127.0.0.1 hidden behind the WSL boundary. Your runbook should pin probe commands (e.g. curl to the real URL) so docs never say “localhost” when operators must use a host name or IP. For hardening when exposing loopback-adjacent services, review OpenClaw localhost threat isolation patterns.
4.2 systemd on WSL2
Recent WSL builds can enable systemd via /etc/wsl.conf (follow Microsoft’s current keys). If systemd is off, systemctl may be missing or unreliable—fall back to a foreground gateway (openclaw gateway under tmux/screen) or enable WSL systemd first, then run openclaw gateway install.
5. Daemon error matrix (mixed OS)
Symptoms below are field notes; if they disagree with your CLI version, trust openclaw doctor and logs.
| Symptom / log keyword | Common cause | What to do |
|---|---|---|
| EADDRINUSE | Stale process or duplicate instance | openclaw gateway status; stop the conflicting PID/service or change the listen port. |
| Permission denied (low port) | Non-root binding a privileged port | Use a high port plus a reverse proxy, or Linux capabilities—never guess on shared laptops. |
| systemctl: Unit not found | Install step skipped or unit renamed | Re-run openclaw gateway install; match the unit name from doctor. |
| curl from WSL to Windows service fails | Bind address or firewall | Listen on 0.0.0.0; add Windows Defender Firewall rules; use the correct host IP. |
| Rapid restarts (Restart=) | Bad config, missing secrets, full disk | journalctl for exit codes; openclaw doctor; check state-directory disk space. |
6. Runbook checklist for mixed-OS teams
- • Single source of truth: wiki page with Gateway version, Node major, bind address, and port.
- • Three-step validation:
gateway status→health→channels status --probe(add webhooks when relevant). - • Path snippets: PowerShell blocks for Windows, bash for Linux, and WSL2 notes for curl targets “from Win” vs “from Linux.”
7. FAQ
Can I run one gateway in WSL2 and another on Windows?
Technically yes, but ports and configs collide easily. Prefer one primary instance per machine; isolate the other with distinct ports, state directories, or --remote-url if supported.
Cross-border APIs feel slow—is that OpenClaw?
Split the path first: DNS, TLS, RTT, and HTTP version—run controlled curl timings on each hop before blaming the gateway process.
Why teams still anchor on Mac mini / macOS for a golden gateway image
Mixed-OS integration pain usually comes from environment drift and repeated firefighting, not from a single OS failing in isolation. If you need one machine that stays online with a unified Unix toolchain—Homebrew, native shells, predictable virtualization—macOS on Apple Silicon often produces fewer surprises than maintaining Windows plus WSL2 in parallel. Mac mini M4-class hardware draws only a few watts at idle, runs quietly, and fits edge or office closets; unified memory helps when you colocate local models and the gateway on the same box.
Security-wise, Gatekeeper, SIP, and FileVault reduce ambient malware exposure versus many commodity desktops. Total cost of ownership—power, noise, downtime—often favors a small Apple Silicon Mac for the reference deployment your distributed team trusts. If you want that consistency without another round of OS archaeology, Mac mini M4 is a strong default anchor—get one now and run OpenClaw on a predictable, native Unix foundation.
Run OpenClaw on Quiet Apple Silicon
Dedicated macOS hosts with predictable networking—ideal for gateways your mixed-OS team can reproduce against.