You are running OpenClaw Gateway on a VPS or home server, but you do not want to expose 18789 to the public internet. You still want laptops, other Linux nodes, or phones to reach the CLI and WebSocket as if the service were on the LAN. This article uses Tailscale private tunnels plus default loopback binding to draw the boundary, explain tokens and environment variables, list remote CLI checks, and split triage for the common failure mode: the tunnel is up, but RPC or sessions are wrong. You will also see how this article fits next to the on-site Cloudflare Tunnel and systemd guide, and when heavy work naturally belongs on a dedicated remote Mac instead of the Gateway host.
OpenClaw Gateway defaults to binding the control plane to 127.0.0.1 so the WebSocket/HTTP control surface sits inside the boundary the operating system already promises: only local processes can talk to it directly. Many first-time deploys switch the listener to 0.0.0.0 so a remote openclaw works, then try to paper over it with ad hoc firewall rules. That is tolerable in a demo, but in production it amplifies unauthorized scanning, token leaks, and mis-set CORS in one step.
Scannable surface explodes: once the port is reachable from the public internet, automated scans hit it within hours. Even with a strong token, logs fill with noise and SOC triage does not converge.
It fights the "minimum exposure" hardening story: the Gateway hardening content on the site centers on loopback, token rotation, and execution approval; opening the bind to all interfaces throws away the first gate.
Debug signals get noisy: the public path adds CDN behavior, carrier NAT, and corporate proxies. You may blame OpenClaw when the real issue is half-closes and MTU, over and over.
Audit trails get vague: mapping "which public IP reached the agent control plane" to a person is hard. Tailnet identity (device plus user) and ACLs read better into policy.
Multi-Gateway topologies get harder: a second test instance on the same host makes port collisions and token mixups much more likely.
It does not match the remote Mac pattern: long-running work is really about Xcode, simulators, and large caches. Keep Gateway light and put heavy runs on a dedicated node. Check disk and region on the Mac Mini rental rates page, and for connectivity and access baselines use the cloud Mac help center before you route production traffic.
The right mental model: keep Gateway on loopback and use a controlled network layer (Tailscale and similar) for reachability. It is the same habit as binding a database to 127.0.0.1 and reaching it over an SSH tunnel. If you are more familiar with Cloudflare Tunnel, read Linux VPS, systemd, and Cloudflare Tunnel to contrast "edge entry" with the "pure tailnet" model in this article.
| Angle | Loopback and Tailscale | Public bind (0.0.0.0) | Cloudflare Tunnel |
|---|---|---|---|
| Trust model | Tailnet identity and ACLs; private by default | Firewall plus token; large exposed surface | Edge identity and tunnel credentials; public entry |
| Ops complexity | Medium: you maintain ACLs and host names | Low to start, high long-term risk | Medium to high: DNS, certs, origin policy |
| Fit to OpenClaw defaults | High: no bind change | Low: often lures you into changing bind | Medium: tunnel points at the loopback port |
| Typical users | Individuals and small teams doing private orchestration | Not recommended for production | When you need a safe public entry |
"Tunnels solve routing, not auth; tokens and execution approval stay fully on."
Tailscale's value is putting machines in one trust domain so you can use stable host names against the 100.x range. It does not replace Gateway-side tokens. If your ACLs are too loose (for example *:*), you have recreated a "little public network" inside the tailnet.
In common 2026 topologies you also see subnet routers and exit nodes: the former brings LAN segments that are not running Tailscale into the tailnet, the latter sends some devices' egress through another host. If Gateway and the database sit in the same VPC while your laptop is only on the tailnet, you must be explicit about which sources may reach the DB port. Otherwise you get "Gateway can curl the DB, but the remote CLI sometimes 500s" when the failure is ACL or route asymmetry, not an OpenClaw session bug.
Another frequent gotcha is MagicDNS and search domains: some corporate networks hijack *.ts.net to an internal resolver. For triage, compare dig against a public resolver and the tailnet resolver from the laptop so you do not file "DNS mixing" as a Gateway session error. Once that is in the runbook, new hires stop repeating the same wrong experiments.
After Tailscale is installed and logged in on the Gateway host, from another device on the same tailnet (for example a laptop) check RTT with ping and tailscale ping. In the admin console, confirm the node has the right tags, MagicDNS is on, and the ACL explicitly allows TCP 18789 (or your custom port) from an ops group to a Gateway-tagged node.
// ACL fragment: only machines tagged tag:ops may reach 18789 on tag:gateway
{
"groups": { "group:ops": ["alice@github", "bob@github"] },
"tagOwners": { "tag:gateway": ["group:ops"] },
"acls": [
{
"action": "accept",
"src": ["tag:ops"],
"dst": ["tag:gateway:18789"]
}
]
}
Note: this is only a shape. Real ACLs also cover exit nodes, subnet routes, and least privilege for phone clients. Reconnect the tailnet on a test device after a change, then re-verify.
Put the acceptance checklist in the change ticket: 1) the Gateway process still listens on 127.0.0.1:18789; 2) from an ops box you can hit the same health check you would curl on the server, but over the tailnet address (paths depend on your build); 3) the cloud security group has no inbound on 18789. For "channel messages never arrive," pair this article with channel probes and dmPolicy gating.
These steps assume openclaw doctor is already green on the server. If you have not completed first run, read cross-platform install and first-run troubleshooting first, then return here.
Confirm the listener: on the server, lsof -nP -iTCP:18789 -sTCP:LISTEN should show 127.0.0.1. If you see *:18789, roll back the config before you tune the tunnel.
Pin the token source: prefer OPENCLAW_GATEWAY_TOKEN via the environment so long-lived secrets are not written into a repo that syncs everywhere.
Configure remote on the client: in ~/.openclaw/openclaw.json add a remote block that points to the tailnet host name and port (field names per your CLI --help), and use ws:// or wss:// to match your internal policy.
Export the port in both places: if you are off the default port, keep OPENCLAW_GATEWAY_PORT aligned in the service and in the client session to avoid "doctor passes but the remote CLI hits the wrong port."
Know where TLS terminates: if you add a reverse proxy inside the tailnet, confirm the WebSocket upgrade headers are not stripped.
Log a success fingerprint once: keep gateway status, doctor, and a failed session in the same ticket so you can diff after Gateway upgrades later.
// Client-side ~/.openclaw/openclaw.json sketch (field names are CLI-version-specific)
{
"gateway": {
"remote": {
"url": "ws://openclaw-gateway.tailnet-1234.ts.net:18789",
"token": "use-env-or-osx-keychain-instead-of-plaintext"
}
}
}
Tip: do not pin heavy compilation and large file churn to the same small-memory VPS that runs Gateway. When agents need long-lived xcodebuild or big dependency caches, put the execution plane on a dedicated remote Mac and let Gateway do session and tool orchestration. Start from the Mac Mini rental rates page to compare disk and region tiers.
| What you see | Suspect first | What to do |
|---|---|---|
tailscale ping works but the CLI times out | Port missing from the ACL, or local firewall not allowing the loopback-forward path | Prove loopback on the server, then work outward in layers |
| HTTP 401 / auth failure | Token mismatch, or env not imported into the systemd unit | Align the unit Environment= with your shell |
WebSocket drops immediately / gateway closed(1000) | Version skew on scopes or session shape after an upgrade | Follow the gateway-closed triage post and narrow token and scope |
| Channel online but no messages | Channel not paired, or dmPolicy blocks | Run the channels probe subcommand and check the policy table |
If a minor Gateway upgrade suddenly breaks with "the same ACL and token, but only on the remote CLI," diff the release notes for breaking changes and default port tables, roll back to the last known good build and bisect, and do not keep chasing ACLs until you have confirmed the listen matrix, or you will fill the ticket with false positives.
18789 (see release notes for your build). Any port change must be reflected in systemd, Docker Compose, and the client remote block, or you get "half the processes read the old port" forever.tag:gateway, ACL size can grow linearly with the team. The runbook should say "on departure, delete the host and revoke the device" for the tailnet.Relying on raw public bind or a wildly permissive tailnet ACL pushes the agent control plane into a hard-to-audit state in 2026. Pushing all heavy compute onto the same small VPS as Gateway hits memory and disk at once. The first lacks network-depth identity, the second lacks a horizontally scalable execution plane the way a cloud host does.
A steadier pattern: Gateway stays light, tailnet shrinks the access surface, and heavy work moves to a dedicated macOS node. When you need a stable Xcode toolchain, long-lived sessions, and contract-sized disk, NodeMini Mac Mini cloud rental is usually the better fit.
After packets enter the target host on the tailnet, the local stack delivers them to 127.0.0.1:18789. You do not need to bind the Gateway to every interface. What matters is ACLs, the host firewall, and the token. If you are sizing a Mac for execution, start from the Mac Mini rental rates page.
The Tunnel article is about a safe public path into an internal service and edge routing. This article is about private tailnet access while keeping the control plane on loopback. Use one or layer them on purpose, not with overlapping tunnels you have not reasoned about.
Use the blog OpenClaw category to filter by theme. For connection and account questions, see the cloud Mac help center sections on SSH and remote compute.