2026 OpenClaw Remote Gateway Networking Playbook: gateway.remote, Tailscale/Tunneling & Local CLI Acceptance + Dedicated Remote Mac bind/Token FAQ (Copy-Paste Commands)

Write these three facts on paper first

On a dedicated remote Mac, the most expensive mistakes are not typos—they are mismatched mental models: you think the CLI talks to the local gateway, but gateway.remote targets another host; or Tailscale works, while the reverse proxy still pins TLS/SNI to a public hostname the gateway rejects.

• Gateway placement: listen locally, or act only as a client to a remote gateway?
• Reachability path: tailnet IP, MagicDNS, tunnel hostname, or SSH local forward?
• Auth source: environment variables, keychain-backed references, or values baked into config files?

If the gateway host still misbehaves after networking looks “green,” walk the production stack first—Python deps, launch paths, and TCC loops are common gatekeepers before any tunnel helps. Learn more: 2026 OpenClaw production deployment and TCC troubleshooting

gateway.remote: who are you actually calling?

In ~/.openclaw/openclaw.json (or the path your installer generated), gateway.remote is the default base URL the CLI and many plugins use. Typical shapes are wss:// or https:// plus a path. It is tightly coupled to gateway.mode: when you run a gateway on the same machine, remote is often empty or loopback; in pure remote-client mode, remote must land on the host where the gateway process you trust is actually listening.

{
  "gateway": {
    "mode": "remote",
    "remote": "wss://mac-workhorse.tail-scale.ts.net/openclaw",
    "bind": "127.0.0.1:18789"
  }
}

Field names follow your CLI template; after upgrades, if “remote is set but traffic still hits localhost,” clear shell overrides such as OPENCLAW_GATEWAY_URL and retry.

Path A: Tailscale acceptance (copy-paste)

Tailscale reframes “NAT on the public Internet” as “routing inside a 100.x tailnet.” Once your laptop and the dedicated remote Mac share a tailnet, you can point gateway.remote at MagicDNS or a bare 100.x address and avoid exposing the gateway port directly to the open Internet.

tailscale status
tailscale ping <peer-name-or-100.x.x.x>
sudo lsof -nP -iTCP -sTCP:LISTEN | grep -E 'openclaw|18789'

tailscale status
openclaw doctor
openclaw logs --follow

Path B: Tunnels, reverse proxies, and cloud load balancers

When you must use frp, a cloud NLB, or home-router port mapping, assume TLS termination and WebSocket upgrades will each trip you once: missing Upgrade / Connection headers often produces “handshake OK, first frame dies” on the CLI side; a gateway that only trusts a specific Host will throw 421/403 when the tunnel hostname and certificate SANs disagree.

• ! Single front door: put one canonical hostname in gateway.remote; do not document IP:port and DNS names interchangeably.
• ! Time sync: TLS and many token checks care about clock skew—enable NTP on the remote Mac and the proxy tier.
• ! Upstream target: point the reverse proxy at 127.0.0.1:<local gateway port> so you are not rebinding the gateway to every public interface unless you mean to.

Local CLI “five-step ladder”

This order deliberately separates the network layer from HTTP/WSS semantics before you chase higher-level subcommands. If you also wire IDE stdio paths, keep the same base URL story as your gateway settings—see OpenClaw ACP stdio, IDE wiring, and gateway vs Skills matrix for the full checklist.

1. Process + socket: lsof -nP -iTCP:18789 -sTCP:LISTEN (adjust the port to match your config).
2. Loopback health: curl -sfS http://127.0.0.1:18789/health (path may differ per build).
3. Tokenized edge semantics:
   curl -sfS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" "https://your.hostname/health"
4. Config truth: openclaw doctor—read remote/bind/auth warnings as a single story.
5. Live timeline: openclaw logs --follow while you retry from another terminal to see whether failures cluster under TLS, auth, or upstream routing.

For automation that shells into the same host after the gateway is reachable, reuse the same SSH and environment discipline you use for remote scripts—keep secrets out of shell history and align non-interactive PATH with launchd. Learn more: OpenClaw remote script execution in the cloud (2026)

FAQ: bind and token sharp edges

If Dashboard, TCP 18789, and openclaw doctor disagree, use the OpenClaw gateway first-aid playbook (doctor, 18789, Dashboard, token) and walk the doctor → port → Dashboard → token sequence line by line.