Neura Market Logo

Remote Gateway Setup for OpenClaw.app via SSH Tunnel

This page explains how to connect OpenClaw.app to a remote gateway using an SSH tunnel with LocalForward. It covers setup steps including SSH config, key copying, token configuration, and optional persistent tunnel via LaunchAgent.

Note

This content has moved to Remote Access. Refer to that page for the current instructions; this page remains as a redirect target.

Running OpenClaw.app with a Remote Gateway

OpenClaw.app connects to a remote Gateway through an SSH tunnel. An SSH LocalForward maps a local port to the Gateway WebSocket port on the remote machine.

flowchart TB
    subgraph Client["Client Machine"]
        direction TB
        A["OpenClaw.app"]
        B["ws://127.0.0.1:18789\n(local port)"]
        T["SSH Tunnel"]

        A --> B
        B --> T
    end
    subgraph Remote["Remote Machine"]
        direction TB
        C["Gateway WebSocket"]
        D["ws://127.0.0.1:18789"]

        C --> D
    end
    T --> C

Setup

  1. Add an SSH config entry with LocalForward 18789 127.0.0.1:18789 (see Remote Access for the full configuration block).
  2. Copy your SSH key to the remote host using ssh-copy-id.
  3. Set gateway.remote.token (or gateway.remote.password) via openclaw config set gateway.remote.token "<your-token>".
  4. Start the tunnel: ssh -N remote-gateway &.
  5. Quit and reopen OpenClaw.app.

For a tunnel that automatically survives reboots and reconnections, use the LaunchAgent setup on the Remote Access page instead of a manual ssh -N.

How it works

ComponentWhat it does
LocalForward 18789 127.0.0.1:18789Forwards local port 18789 to remote port 18789
ssh -NSSH without executing remote commands (port forwarding only)
KeepAliveAutomatically restarts the tunnel if it crashes (LaunchAgent)
RunAtLoadStarts the tunnel when the LaunchAgent loads (LaunchAgent)

OpenClaw.app connects to ws://127.0.0.1:18789 on the client. The tunnel forwards that connection to port 18789 on the remote host running the Gateway.