2026 OpenClaw on Windows and Linux: PowerShell vs WSL2, Enterprise HTTPS Proxy, Node Pinning, and Remote macOS Gateway Runbook

2. Decision matrix: PowerShell vs WSL2 vs Linux

Pick one primary environment per engineer for OpenClaw client workflows, document it, and enforce Node parity with .nvmrc or package.json engines. Use the matrix below when onboarding or auditing laptops.

For where to place gateways and regional pools, compare deployment topologies in 2026 OpenClaw Global Deployment Comparison Guide: Where is Your Deployment Most Efficient?.

3. Seven-step rollout (reproducible)

Step 1 — Freeze the target Node line

OpenClaw 2026.x tracks Node 22 LTS in most release notes. Commit 22.x in .nvmrc and an engines.node range in the workspace that consumes the CLI.

Step 2 — Install Node in the chosen shell only

Windows PowerShell (fnm example):

winget install Schniz.fnm
fnm install 22
fnm use 22
node -v

WSL2/Ubuntu:

curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc
fnm install 22 && fnm use 22
node -v

Step 3 — Set proxy variables and bypass lists

Use uppercase vars consistently. Example (replace host/port):

export HTTPS_PROXY=http://proxy.corp.example:8080
export HTTP_PROXY=http://proxy.corp.example:8080
export NO_PROXY=localhost,127.0.0.1,::1,.corp.example,169.254.0.0/16

On Windows you can persist for your user with setx or the System Properties dialog; restart the terminal afterward.

Step 4 — Trust the corporate CA chain

Export the issuing chain to PEM. For Node on Linux/WSL2, point NODE_EXTRA_CA_FILES=/path/to/corp-ca-bundle.pem in the same shell profile you use for OpenClaw. On native Windows Node, import into Trusted Root/Issuers and restart shells; verify with npm ping or a minimal node -e "https.get('https://registry.npmjs.org')" script.

Step 5 — Install OpenClaw CLI and print versions

Follow the package name and flags from your internal mirror if you use Artifactory. Capture openclaw --version, Node, and OS build in every support ticket—this triages half of “mystery disconnects.”

Step 6 — Reach the macOS gateway with one tunnel discipline

Create the SSH -L forward from the same environment as the CLI. Example pattern: ssh -N -L 18787:127.0.0.1:18787 user@mac-host (replace ports with your gateway bind). If you standardize on Tailscale Serve instead, keep Mac-local health checks green before exposing URLs to clients.

Step 7 — Verify with curl from that shell

Run curl -v http://127.0.0.1:18787/health (or the documented health path) and compare headers with a curl executed on the Mac against 127.0.0.1. Mismatches here almost always map to wrong bind address, wrong port, or a tunnel created in the other subsystem.

4. Quotable numbers and policy knobs

5. FAQ and symptom-based troubleshooting

Should I install on PowerShell or WSL2?

See the matrix in section 2. The wrong answer is “both without pinning.” If security mandates Windows trust stores, default to PowerShell; if your automation is bash-first, commit fully to WSL2 and run tunnels there.

TLS errors only inside npm/pnpm

Your browser trusts the MITM because it uses the OS store; Node does not automatically. Fix CA import for the runtime, not just the browser. Keep strict-ssl=false off except for narrow packet captures.

PowerShell can curl the gateway, WSL2 cannot

You created the forward on Windows while the CLI runs in WSL2 (or the reverse). Recreate the tunnel in the subsystem that owns the OpenClaw process, or forward to the WSL2-facing address documented for your Windows build.

HTTP 502 or blank UI through the tunnel

First prove the gateway on the Mac with localhost curl. If that fails, restart the gateway service and check launchd logs. If Mac-local works, re-check -L ordering, local port collisions, and whether you assumed HTTPS while the gateway speaks plain HTTP on the loopback hop.

6. Why a physical Mac gateway belongs on Apple Silicon

The client-side work in this runbook is only half the story: the OpenClaw gateway on macOS benefits from Apple Silicon’s unified memory bandwidth for concurrent agent workloads, launchd-friendly 7×24 scheduling, and a Unix toolchain that matches most automation you already run in CI. A Mac mini class node idles around 4W while staying ready for SSH forwards and health probes—far easier to justify than a full tower humming in a closet.

macOS also stacks Gatekeeper, SIP, and FileVault in ways that reduce drive-by malware risk compared with typical Windows laptop SOEs, which matters when long-lived tokens sit beside your gateway. If you want the remote path in section 3 to stay boringly stable, park the gateway on quiet, efficient Apple hardware and keep Windows/Linux strictly as controlled clients.

If you are standardizing gateways for a distributed team, putting them on Mac mini M4 nodes keeps latency predictable and operating cost low—explore ZoneMac nodes when you are ready to match this runbook with production-grade macOS hosts.