OpenClaw Remote Gateway Checks: Know Which Machine Your Agent Is Using

The most expensive remote-agent mistake is not a broken tunnel. It is believing you are talking to one machine while your agent, channels, browser profiles, and state live on another one.

OpenClaw's remote Gateway model is intentionally simple: one Gateway host owns the agent. Your laptop, macOS app, browser UI, and mobile nodes connect to it. But “simple” still needs checks, especially when you have a home desktop, a laptop, a VPS, a tailnet name, and a half-remembered SSH tunnel all in the same week.

This is the runbook I would use before trusting a remote OpenClaw setup in production. The goal is not to memorize networking trivia. The goal is to prove which machine is actually in charge before you send work, pair a node, debug a channel, or blame the wrong host.

The Gateway host is where the agent lives

The remote access docs say to think of the Gateway host as where the agent lives. That host owns sessions, auth profiles, channels, and state. Other machines connect to it. Nodes are peripherals; they do not run the Gateway service.

That one sentence changes how you debug everything. If Telegram, Slack, a mobile node, or the macOS app triggers work, the Gateway host is the process deciding what happens next. It can call a node over the Gateway WebSocket, but the node is not the operator. It returns results to the Gateway, and the Gateway replies back out through the channel.

So the first buyer/operator question is not “can my laptop open the UI?” It is: which Gateway accepted this control connection, and is that the Gateway that owns my production state?

Start with the default: loopback plus a tunnel

OpenClaw's Gateway WebSocket defaults to loopback on port 18789. For remote use, the docs recommend forwarding that loopback port over SSH or using a tailnet/VPN so you expose less to the public internet.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

With that tunnel up, local commands can reach the remote Gateway at ws://127.0.0.1:18789. That local address is slightly deceptive in a good way: it is local to your laptop, but the other end of the tunnel lands on the remote host's loopback Gateway.

The danger is assuming every 127.0.0.1 means the same machine. It does not. Without the tunnel, 127.0.0.1:18789 means your current machine. With the tunnel, it means your current machine forwarding to the remote machine. That is why you should verify before operating.

Use status and probe to prove the target

OpenClaw gives you several read-only checks. Use them before restarting services, changing configs, or trying to pair a node.

openclaw health
openclaw status --deep
openclaw gateway status --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
openclaw gateway status --require-rpc
openclaw gateway probe

openclaw health and openclaw status --deep can reach the remote Gateway through the forwarded WebSocket. openclaw gateway status shows service status and can run an RPC probe. If a listening port is not enough and you need the Gateway RPC itself to be healthy, --require-rpc makes the command fail when the probe fails.

openclaw gateway probe is the better “what am I actually reaching?” tool. The docs say it probes your configured remote Gateway when present and localhost even when remote is configured. If multiple gateways are reachable, it prints all of them. That is not just diagnostics; it is split-brain prevention. If your laptop has a local dev Gateway and a remote production Gateway, probe is how you catch the ambiguity before sending work to the wrong one.

One subtle auth rule matters here. When you pass --url, the CLI does not fall back to config or environment credentials. You must pass --token or --password explicitly. Missing explicit credentials is an error. I like that behavior because it prevents a script from accidentally reusing a local token against a remote endpoint it did not intend to trust.

Persist remote mode only after the tunnel is real

If this is your normal setup, you can persist a remote target in config so CLI commands use it by default:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token"
    }
  }
}

When the Gateway is loopback-only, keep the URL pointed at ws://127.0.0.1:18789 and open the SSH tunnel first. Remote mode is not magic networking. It tells clients what to target; it does not make a sleeping host, closed tunnel, or wrong port become reachable.

For the macOS app, the docs describe Remote over SSH mode as the smoother version of the same pattern. The app opens and manages the tunnel, so WebChat and health checks can connect to the Gateway host without you manually babysitting the SSH command.

My practical rule: persist remote mode only after one clean manual verification. Bring up the tunnel, run probe, confirm the expected Gateway answers, and only then make it your default. That keeps setup mistakes from becoming permanent assumptions.

Mid-run operator check: if you are building a remote OpenClaw setup for a real workflow, do not stop at “it connects.” Write down the expected Gateway host, port, auth method, and tunnel path. Want the full production checklist? Get ClawKit — $9.99.

Use SSH probe when the tunnel itself is the question

The Gateway CLI also has SSH-aware probe options. That matters when you are debugging parity with the macOS Remote over SSH flow or trying to prove the remote host is reachable before assuming the Gateway is broken.

openclaw gateway probe --ssh user@gateway-host
openclaw gateway probe --ssh user@gateway-host:22 --ssh-identity ~/.ssh/id_ed25519

The docs describe --ssh as accepting user@host or user@host:port, with port 22 as the default. You can also provide an SSH identity. Config can store defaults under gateway.remote.sshTarget and gateway.remote.sshIdentity.

This is a clean operator boundary. If SSH cannot connect, do not debug OpenClaw pairing yet. If SSH connects but Gateway RPC fails, now you are looking at Gateway service, port, auth, or config. If RPC succeeds but a channel is broken, the remote machine is not the mystery anymore; the channel integration is.

Discovery is convenience, not authority

Bonjour and DNS-SD are useful for finding Gateways, especially on a LAN. OpenClaw advertises _openclaw-gw._tcp for the Gateway transport beacon. The Gateway owns discovery advertising; clients browse and present choices.

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
dns-sd -B _openclaw-gw._tcp local.

Discovery is not the same as trust. The docs are explicit that Bonjour TXT records are unauthenticated and non-secret. Fields like role=gateway, transport=gateway, gatewayPort, lanHost, tailnetDns, gatewayTls, and gatewayTlsSha256 are UX hints. Clients should prefer the resolved service endpoint from SRV and A/AAAA records over TXT-provided routing hints, and a TXT-advertised TLS fingerprint must not override a previously stored pin.

That makes Bonjour great for “show me nearby Gateways” and dangerous for “silently trust whatever text a network advertises.” On a hostile or messy network, discovery should lead to an explicit trust decision, not an invisible production cutover.

Remember that Bonjour does not cross normal networks

Multicast Bonjour is LAN-only. If your node and Gateway are on different networks, mDNS usually will not cross the boundary. OpenClaw documents two cross-network patterns: use tailnet/direct routing, or use wide-area Bonjour over a configured DNS-SD domain.

For wide-area Bonjour over Tailscale, the documented shape is: run a DNS server on the Gateway host, publish DNS-SD records for _openclaw-gw._tcp under a dedicated zone, and configure Tailscale split DNS so clients resolve that domain through the Gateway host.

{
  gateway: { bind: "tailnet" },
  discovery: { wideArea: { enabled: true } }
}

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

The docs also include openclaw dns setup --apply for the one-time DNS server setup. It installs CoreDNS and configures it to listen on port 53 only on the Gateway's Tailscale interfaces and serve the chosen domain from the OpenClaw DNS state path.

This is powerful, but do not confuse it with public exposure. Wide-area discovery helps clients find a Gateway over the tailnet. It does not remove the need for Gateway auth, explicit binding choices, and TLS/fingerprint decisions where relevant.

Bind modes are an operational decision

The network model docs keep the default conservative: loopback first. The wizard generates a Gateway token by default, and for tailnet access you run the Gateway with a tailnet bind and a token because tokens are required for non-loopback binds.

That is the right bias. If the Gateway only needs local access plus SSH forwarding, keep it loopback-only. If nodes or clients need direct tailnet access, bind to the tailnet and keep auth enabled. If you bind beyond loopback without auth, the Gateway has guardrails that block unsafe startup.

The safest question is not “can I expose this?” It is “what is the narrowest route that lets the right clients reach the Gateway?” For many teams, that answer is loopback plus SSH for operators, and tailnet-only direct WebSocket for trusted nodes.

A practical remote Gateway checklist

1. Name the owner: decide which host owns sessions, channels, browser profiles, and state.
2. Pick the route: SSH tunnel for universal operator access, direct tailnet WebSocket when nodes need a private-network route, or Bonjour only for LAN discovery convenience.
3. Verify the socket: run openclaw gateway probe and confirm the expected target answers.
4. Verify RPC, not just the port: use openclaw gateway status --require-rpc when automation depends on a healthy control plane.
5. Keep auth explicit: pass credentials when using --url, and do not rely on accidental fallback behavior.
6. Treat discovery as a hint: use Bonjour to find candidates, then trust deliberately.
7. Do not restart the wrong machine: if probe shows multiple Gateways, stop and identify which one owns production before touching service lifecycle.

Remote OpenClaw is not hard when the mental model is clean. One Gateway owns the agent. Tunnels, tailnets, Bonjour, and nodes are ways to reach that owner. The moment you make that explicit, most “remote” bugs become ordinary routing, auth, or service-health checks.

Want the complete guide? Get ClawKit — $9.99