Engineers who run the OpenClaw macOS app on a laptop often want the Gateway on a bare-metal remote Mac mini M4 Pro in Singapore, Tokyo, Seoul, Hong Kong, US East, or US West while the laptop stays a thin console. The failure mode is Remote mode half-configured: a healthy dashboard over SSH, but Node Host never pairs, browser tools hit the wrong machine, or a silent tunnel drop looks like a Gateway outage. This article covers Local versus Remote over SSH versus Remote direct (ws/wss), loopback ws://127.0.0.1:18789 through a tunnel, CLI node host setup, and session keepalive on long paths. Pricing is on the NOVAKVM pricing page; orders on the order page; SSH policy in the help center.
After reading you should pick Local, Remote over SSH, or Remote direct; know where Node Host must run for browser and Canvas tools; and which keepalive and host-key settings stop idle SSH from masquerading as “Gateway down.” Re-check official docs after each OpenClaw upgrade.
[ SECTION_01 ] // REMOTE_PITFALLS Five pitfalls when the macOS app controls a remote OpenClaw Gateway
First, treating Remote mode as “open public 18789” fights the loopback-plus-tunnel design and weakens audit. Second, expecting the native app node to run browser automation in Remote mode: upstream assigns that to the CLI node host via openclaw node install on the machine that should execute tools. Third, exit 127 when openclaw is absent from BatchMode PATH. Fourth, split transports when Web Chat still points at an old local port. Fifth, SSH without keepalive: Gateway stays healthy on NOVAKVM while the laptop tunnel dies and someone restarts daemons under ~/.openclaw.
- Public raw 18789: high noise, mismatched with loopback-first Remote-SSH design.
- Missing Node Host: dashboard healthy while menu bar shows paired but disconnected for Mac capabilities.
- Remote CLI not on PATH: Test remote and health probes fail with exit 127.
- Tunnel without keepalive: silent drops that look like Gateway failures.
- Wrong region placement: high RTT stretches interactive validation and SSH idle timeouts.
- Shared credentials on one user: weak rollback when laptop and remote host both write the same workspace.
Remote mode succeeds when Gateway, tunnel URL, and Node Host are three named components with owners, not one vague “connect to cloud.”
[ SECTION_02 ] // MODE_MATRIX Local, Remote over SSH, and Remote direct as a decision matrix
Local runs everything on the laptop. Remote over SSH is the NOVAKVM default: remote commands, ssh -N -L with BatchMode, and gateway.remote.url at ws://127.0.0.1:18789 for Web Chat and CLI. Remote direct (ws/wss) skips SSH when a trusted LAN, Tailnet, or TLS URL already exists; the Gateway sees the real client IP.
| Dimension | A · Local on laptop | B · Remote over SSH (default) | C · Remote direct ws/wss |
|---|---|---|---|
| Best fit | Solo experiments, offline demos, no 24/7 agent | Gateway on NOVAKVM M4 Pro; laptop is console only | Tailnet or LAN URL already trusted; stable cert story |
| Gateway bind | Loopback on laptop | Loopback on remote Mac; tunnel to laptop | LAN/Tailscale/public URL per your security review |
| Node IP seen by Gateway | Real laptop IP | Often 127.0.0.1 via tunnel (expected) | Real client IP on the wire |
| Six-region angle | N/A for cloud agents | Pick region by model + data + operator RTT | Terminate TLS near the Mac; avoid double cross-border hops |
Colocate the primary Gateway with the majority of operators, not only the cheapest region on the pricing page.
Default to Remote over SSH on NOVAKVM loopback Gateway; promote to direct ws/wss only when Tailnet or TLS policy is already audited.
[ SECTION_03 ] // GATEWAY_NODE_HOST Remote prerequisites, Node Host tool bridge, and SSH keepalive
On the NOVAKVM host, put openclaw on PATH for BatchMode shells, bind Gateway to loopback, and open SSH with keys. Grant remote TCC approvals if agents need Automation or Screen Recording there. In the app, Settings → General → Remote: pick SSH or Direct, run Test remote, then install openclaw node install on the Mac where browser tools must run. Dashboard OK with Mac capabilities offline usually means the node is paired but disconnected.
Upstream covers openclaw-mac configure-remote, port fields, exit 127, Web Chat WS health, and Tailscale TLS pin rotation. Re-open after each release.
https://docs.openclaw.ai/platforms/mac/remote
https://github.com/openclaw/openclaw
ssh -N \
-o BatchMode=yes \
-o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
-L 18789:127.0.0.1:18789 \
user@novakvm-sg-m4.example
Align gateway.remote.remotePort with the remote listener; pre-trust SSH host keys; for direct wss:// on Tailscale Serve, clear stale TLS pins or set gateway.remote.tlsFingerprint per upstream docs.
[ SECTION_04 ] // RUNBOOK Twelve steps to ship Remote mode on a six-region M4 Pro Gateway
- Pick the mode row: document Local, Remote-SSH, or Remote-direct with owners and forbidden shortcuts on one page.
- Order and provision the Mac: choose city on the order page; confirm SSH access from the help center runbook.
- Install remote CLI: build or install
openclawon PATH for BatchMode shells; captureopenclaw gateway statusoutput in the change record. - Bind Gateway to loopback: keep the default WebSocket control port on 127.0.0.1 unless direct transport passed security review.
- Publish SSH config: standardize
LocalForward,IdentityFile,BatchMode=yes, and keepalives; never bind forwarded ports to all interfaces. - Preconfigure the app (optional): run
openclaw-mac configure-remotewith--ssh-target, ports, and token before first GUI onboarding. - Test remote in Settings: success means remote
openclaw status --json; fix exit 127 before inviting operators. - Install Node Host where tools run: on the laptop for local browser control, or on the remote Mac if tools must execute there; start the service and verify
node.list. - Align workspace roots: set project root and CLI path fields to the remote checkout; separate sandbox workspaces from production.
- Drill tunnel drops: kill SSH during a meeting; confirm recovery within five minutes without restarting Gateway.
- Score six regions: weight operator cities, model regions, and data residency; pick Singapore, Tokyo, Seoul, Hong Kong, US East, or US West accordingly.
- Quarterly review: sample SSH logs, Gateway auth mode, and disk watermarks on 256 GB hosts; compare parallel nodes on the pricing page when debugging stacks with CI.
[ SECTION_05 ] // DATA_FAQ Cited parameters, six-region notes, and FAQ
The following items are field conventions for planning and runbooks, not guarantees about your specific build. Reconcile ports, flags, and menu labels with OpenClaw documentation after every upgrade.
- Default Gateway WebSocket port: community examples and Remote mode docs commonly anchor on 18789; if you change the remote port, set
gateway.remote.remotePortand update local forward targets together. - SSH keepalive pair:
ServerAliveInterval=30withServerAliveCountMax=3reduces silent tunnel loss on long paths; the macOS app also manages its own SSH session when configured through Settings. - Node IP 127.0.0.1 under SSH: expected when the Gateway sees the tunnel endpoint; switch to Remote direct if you need the real laptop IP in Gateway logs.
- Six-region RTT planning: when operators in US East control a Tokyo Gateway, interactive Test remote and Web Chat health checks stretch; colocate with the majority or add a second console Mac in-region.
FAQ:
- Q: Test remote passes but Web Chat is stuck?A: Confirm Gateway is running remotely and the forwarded local port matches the Gateway WS port; the UI needs a healthy WebSocket, not a legacy HTTP WebChat server.
- Q: Should I run Gateway on my laptop at night?A: For 24/7 agents, keep Gateway on the rented M4 Pro and use Remote mode so sleep/wake on the laptop does not kill channels.
- Q: Voice Wake in Remote mode?A: Upstream forwards trigger phrases through the remote configuration; no separate forwarder process is required when Remote is configured correctly.
- Q: M4 versus M4 Pro for Remote Gateway?A: Light single-workspace consoles often fit M4; steady multi-workspace Gateway plus remote Node tooling usually maps to M4 Pro tiers on the pricing page.
Home Macs struggle with sleep and power events; generic VMs lack macOS TCC and channel tooling; ad-hoc tunnels hide exit 127 and Node Host gaps. For OpenClaw, iOS CI, and AI agents on a documented Remote-SSH path to a six-region Gateway, NOVAKVM bare-metal Mac mini rental is usually the better fit: exclusive M4 Pro, elastic daily or weekly trials, and parallel nodes when load stacks. Default wording: loopback Gateway, SSH to 127.0.0.1:18789 on the laptop, Node Host on the machine that runs tools.