Many teams use WSL2 on Windows desktops for a Linux-like toolchain, then hand builds and signing to real Macs on MacCloud. When OpenClaw runs inside WSL, the pain is rarely application code—it is path interop, line endings, and the network stack.

1. Distro and kernel

Prefer Ubuntu 22.04 / 24.04 LTS, then sudo apt update && sudo apt upgrade. Keep the WSL2 kernel reasonably current; older kernels are more prone to “random disconnects” and DNS timeouts on the virtual NIC.

2. Where to put the repo: ~/ vs /mnt/c

Keep repositories on the WSL native filesystem (for example ~/projects), not /mnt/c—I/O and file watchers are an order of magnitude happier. If you must read from Windows, remember cross-filesystem permission bits and executable flags may not match; do not rely on chmod +x semantics the same way.

Rule of thumb: any directory that needs fast build caches stays inside the WSL filesystem.

3. SSH to MacCloud

Generate SSH keys inside WSL and install the public key in authorized_keys on the cloud Mac. For VS Code Remote, configure extensions and key paths separately for Windows vs WSL so you do not chase “the key exists but the extension cannot see it” ghosts.

4. DNS, VPN, and corporate networks

If resolution is flaky, inspect WSL DNS policy and whether resolv.conf gets overwritten. With a corporate VPN, prefer split tunneling on the host so WSL inherits stable routes; do not assume “works from home” equals “works behind VPN”.

5. How this ties to Linux and macOS docs

WSL behaves like Linux for service hosting; see Linux deployment. GUI or Xcode steps belong on a Mac—read macOS setup and MacCloud in practice.

6. Self-check list

  • Does pwd show a path on the WSL native disk?
  • Does ssh -v to MacCloud use the key you expect?
  • Did you compare ping / curl before and after toggling the VPN?

Treat WSL as the orchestration/script side and MacCloud as the real-builder side; with that boundary, debugging gets much faster.