How to Set Up OpenClaw Remote Access

The OpenClaw docs push a very sane remote-access model: keep one gateway running on the machine where the agent actually lives, bind it to loopback, and connect remote clients through a controlled path. That could be SSH tunneling, a tailnet, or the macOS app's Remote over SSH mode. If you follow that pattern, remote access feels boring and reliable. If you skip it and start exposing random ports, you are volunteering for unnecessary pain.

Step 1: think in terms of one gateway host

The gateway host owns sessions, auth profiles, channels, and state. Your laptop, desktop app, or node devices connect to that host. The docs keep repeating this because people are tempted to treat every device like a mini server. OpenClaw does not want that. One gateway service owns the state and the peripherals talk to it. That is the right starting point whether your gateway is on a home desktop, a VPS, or a persistent machine in your tailnet.

Step 2: keep the gateway loopback-only

The documented default is a loopback bind on port 18789. For remote use, forward that loopback port over SSH or reach it through a trusted private network. The docs explicitly call loopback plus SSH or Tailscale Serve the safest default because you are not casually publishing the gateway surface to the world. That is the first rule to keep. Make remote access controlled transport, not public exposure.

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

Step 3: set remote defaults if you want the CLI to target the tunnel

Once the tunnel is up, you can store a remote target in openclaw.json so CLI commands use it by default. The docs show gateway.mode set to remote with gateway.remote.url and a token. That is useful when you want openclaw health, openclaw status --deep, or other commands to hit the forwarded WebSocket without retyping everything. Just remember the docs' warning: if you pass --url explicitly, you must also pass the explicit token or password. There is no silent fallback.

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

Step 4: use the right client path for the platform

For operators on macOS, the docs recommend the app's Remote over SSH mode because it manages the tunnel for you and keeps WebChat plus health checks working. For nodes on iOS or Android, the model is different. Those devices connect to the gateway WebSocket as nodes rather than running a gateway themselves. That is an important distinction. The node is a client on the data plane, not a second control-plane owner.

Step 5: keep the security rules intact

Remote access is not just about connectivity. The docs call out some rules that are easy to miss. gateway.remote.token and gateway.remote.password are client credential sources, not server auth config. Plain ws is loopback-only by default. Non-loopback binds require real gateway auth or a trusted-proxy setup. And if you pass --url, OpenClaw will not quietly reuse config or env credentials for safety reasons. That design is slightly annoying in the moment and absolutely correct in production.

If you want the shortest version, it is this: one gateway, loopback bind, SSH tunnel first, explicit credentials when you override URLs, and only then higher-level conveniences like the macOS app or tailnet access. Follow the docs in that order and OpenClaw remote access is straightforward. Try to skip the boring parts and you end up debugging the exact security boundaries the docs were trying to protect you from.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.