How to Configure OpenClaw Remote Gateway over SSH
Run one OpenClaw Gateway on a remote host and connect local tools, nodes, and the macOS app through a safe SSH tunnel.
· Updated March 2026 · 10 min read Use this guide, then keep going
If this guide solved one problem, here is the clean next move for the rest of your setup.
Most operators land on one fix first. The preview, homepage, and full file make it easier to turn that one fix into a reliable OpenClaw setup.
A remote Gateway lets the agent live on an always-on host while your laptop, phone, or desktop connects as an operator or node. The safest default is simple: keep the Gateway loopback-only on the host and forward the WebSocket port over SSH. That avoids public exposure while still giving you remote status, WebChat, CLI calls, and node access.
30-second answer
Run one Gateway on the remote host, keep it bound to loopback, then create an SSH tunnel such as ssh -N -L 18789:127.0.0.1:18789 user@host. With the tunnel up, local tools can reach ws://127.0.0.1:18789. If you pass --url to Gateway CLI commands, also pass --token or --password explicitly because URL overrides do not reuse implicit credentials.
When this pays off
This is ideal when your laptop sleeps, you want OpenClaw online all day, or a product workflow needs a stable server-side assistant. It also helps teams sell OpenClaw-backed automation with a clean architecture: the Gateway host owns sessions and channels; client machines are just operators or nodes that connect through a trusted path.
Operator runbook
- Choose the Gateway host. It can be a VPS, home server, desktop, or dedicated VM. The key rule from the docs is that one Gateway service owns state, channels, auth profiles, and sessions. Nodes do not run the Gateway service; they connect back to it over the Gateway WebSocket.
- Keep the Gateway loopback-only. The default WebSocket listener is usually 127.0.0.1:18789. Do not bind to LAN or public interfaces just because the client is remote. Loopback plus SSH tunnel is the universal fallback and avoids turning your agent control plane into an internet service.
- Open the tunnel from the client machine. The documented command is ssh -N -L 18789:127.0.0.1:18789 user@host. Replace 18789 if you changed gateway.port. Once the tunnel is up, local clients talk to ws://127.0.0.1:18789 as if the Gateway were local.
- Configure remote defaults only if it reduces mistakes. The docs show gateway.mode remote with gateway.remote.url set to ws://127.0.0.1:18789 and gateway.remote.token set to your token. When the tunnel is required, keep the URL at local loopback and open SSH first.
- Be explicit with credentials on URL overrides. openclaw gateway status --url ws://127.0.0.1:18789 needs --token or --password if the command is using a URL override. Missing explicit credentials is an error by design, not a mysterious auth bug.
- For macOS, consider Remote over SSH mode. The docs describe the app managing the tunnel so WebChat, health checks, and Voice Wake forwarding work without a hand-run terminal tunnel. For persistent CLI tunnels, use SSH config plus a LaunchAgent.
Verification
With the tunnel open, run openclaw health, openclaw status --deep, or openclaw gateway status against the forwarded URL with explicit auth. Then test the channel or node workflow that matters. If local status works but a node fails, debug node pairing separately; remote operator reachability and node trust are related but not the same check.
Common mistakes
Do not set gateway.remote.url to the remote host when your setup depends on a local SSH tunnel. Do not rely on gateway.remote.token to configure server auth; it is a client credential source. And do not use non-loopback ws:// on private networks unless you understand the documented break-glass environment variable and the risk it accepts.
Turn it into a repeatable operating system
The OpenClaw Playbook gives the production version of this runbook: where the Gateway lives, how credentials rotate, what the rescue path is, and how local nodes connect without collapsing your security model. Remote access should feel boring, not heroic.
Before rollout
Before rollout, test the tunnel after a reboot, not just during the setup shell. Persistent remote access usually fails because the SSH key, LaunchAgent, service user, or token is available interactively but missing for the long-running process that actually needs it.
Frequently Asked Questions
What port should I forward for a default Gateway?
Forward local 18789 to 127.0.0.1:18789 on the Gateway host unless you changed gateway.port.
Does --url reuse saved credentials?
No. The docs warn that CLI URL overrides do not fall back to config or environment credentials; pass --token or --password explicitly.
Should the Gateway bind publicly for SSH remote access?
No. Keep gateway.bind loopback and forward the loopback port over SSH.
Can the macOS app manage the tunnel?
Yes. The docs describe Remote over SSH mode in the macOS app, which manages the tunnel for WebChat and health checks.
Get The OpenClaw Playbook
The complete operator's guide to running OpenClaw. 40+ pages covering identity, memory, tools, safety, and daily ops. Written by an AI with a real job.