OpenClaw remote access

OpenClaw runs one Gateway, the master, on a host and connects every client to it: the Gateway owns sessions, auth profiles, channels and state, and everything else, operators and nodes alike, is a client. The core idea is that the Gateway WebSocket binds to loopback by default on port 18789, so remote use means either exposing it through Tailscale Serve or a trusted LAN or tailnet bind, or forwarding the loopback port over SSH. Here are the topologies, the tunnel and the config that makes the CLI use it, direct mode, the proxy case, the credential rules, and the security list.

Topologies

• An always-on Gateway in your tailnet on a VPS or home server, reached via Tailscale or SSH, for laptops that sleep but need the agent always on.
• A home desktop running the Gateway, with a laptop connecting through the macOS app’s remote mode, to keep the agent on hardware that stays powered.
• A laptop running the Gateway, exposed safely via an SSH tunnel or Tailscale Serve while keeping the loopback bind, for single-machine setups.
• The flow in every case: a channel message arrives at the Gateway, the Gateway runs the agent, the agent may call a node over the Gateway WebSocket, and the Gateway replies; nodes never run the Gateway, and only one Gateway should run per host unless you deliberately use isolated profiles.

Keep the Gateway loopback-only unless you are sure you need a bind.

The tunnel and the config

The universal fallback is one SSH command forwarding the local port to the remote loopback port, after which health and deep status reach the remote Gateway through the local address, and the Gateway commands can target a forwarded URL explicitly, with the warning that an explicit URL never falls back to config or environment credentials, so you pass the token or password yourself. To make the CLI use a remote target by default, set the Gateway mode to remote with the tunnel URL and a token; the macOS app’s SSH transport stores the discovered host separately and a differing remote port has its own key; re-running configure with the same URL preserves the TLS fingerprint and transport settings, and host-key verification is strict by default. For a Gateway already reachable on a trusted LAN or tailnet, direct mode points the remote URL at its private address. Behind an identity-aware proxy, edge-auth headers come from secret providers, for example a short-lived Cloudflare Access token read from an operator-installed binary at an absolute path with the home directory passed through, or a service token from environment-backed references; the headers are sent only to the configured URL scope, only over secure WebSocket, and never across redirects, and OpenClaw never runs the proxy tooling itself.

Credentials and security

• Explicit credentials always win; a CLI URL override never reuses implicit credentials while an environment URL may use environment credentials only; in local mode the local auth token comes first with the remote token as a fallback only when it is unset, and remote mode reverses the order; a configured remote reference that cannot be resolved makes probes warn rather than fall back to the environment.
• Plaintext WebSocket is accepted for loopback, private, link-local, carrier-grade NAT, local and tailnet hosts, and public remote hosts must use the secure scheme; any non-loopback bind must use Gateway auth, a token, a password or an identity-aware proxy in trusted-proxy mode, and the remote token and password are client credentials that never configure server auth by themselves.
• A TLS fingerprint pins the remote certificate, with first-use pinning on macOS only after normal system trust passes; Tailscale Serve can authenticate Control UI traffic through identity headers when the tailscale allowance is on, a tokenless flow that assumes a trusted host; trusted-proxy auth expects a non-loopback proxy unless loopback is explicitly allowed; and browser control is treated like operator access.

OpenClaw and Tailscale covers the tailnet route the docs prefer, and The OpenClaw Gateway explained the process every client here connects to.

A tunnel that survives reboots

For macOS clients the docs give a recipe: an SSH config entry with a local forward for the Gateway port, a one-time key copy, the remote token set in the config, and a LaunchAgent that runs the tunnel with keep-alive and run-at-load so it starts at login and restarts after a crash, with kickstart and bootout commands for restarting and stopping it. The Gateway accepts its configured secret in either the token or the password field, whichever mode the server uses, and the environment variable remains a shell-level override rather than the durable setup. OpenClaw nodes, remote hands explains what the peripherals in this topology can do, and OpenClaw Gateway security controls the server-side auth this page only touches.

On Diali

On Diali the Gateway is reachable only through our edge with your session, so the tunnel question is answered before you sign in, and your own computer joins as a node when a task needs it. Hosted OpenClaw on Diali is the assistant and Diali versus your own computer sets that beside running the Gateway at home.

• One Gateway, everything else a client.
• Loopback plus SSH or Tailscale Serve is the safe default.
• Explicit URL, explicit credentials.