OpenClawSkills
GitHub
Gateway / Operations • TutorialHeader.readTime

Remote Gateway Setup

SSH tunnel setup for connecting OpenClaw.app to a remote Gateway.

OpenClaw.app uses SSH tunnels to connect to remote gateways. This guide explains how to set it up.

Tutorial.step

Overview

Terminal
┌─────────────────────────────────────────────────────────────┐
│                        Client Machine                          │
│                                                              │
│  OpenClaw.app ──► ws://127.0.0.1:18789 (local port)           │
│                     │                                        │
│                     ▼                                        │
│  SSH Tunnel ────────────────────────────────────────────────│
│                     │                                        │
└─────────────────────┼──────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                         Remote Machine                        │
│                                                              │
│  Gateway WebSocket ──► ws://127.0.0.1:18789 ──►              │
│                                                              │
└─────────────────────────────────────────────────────────────┘
Tutorial.step

Quick Setup

#

Tutorial.step

Step 1: Add SSH config

Edit ''~/.ssh/config'' and add:

Ssh
Host remote-gateway
    HostName '<REMOTE_IP>'          # e.g., 172.27.187.184
    User '<REMOTE_USER>'            # e.g., jefferson
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

Replace ''<REMOTE_IP>'' and ''<REMOTE_USER>'' with your values.

#

Tutorial.step

Step 2: Copy SSH key

Copy your public key to the remote machine (enter password once):

Bash
ssh-copy-id -i ~/.ssh/id_rsa '<REMOTE_USER>'@'<REMOTE_IP>'

#

Tutorial.step

Step 3: Set Gateway token

Bash
launchctl setenv OPENCLAW_GATEWAY_TOKEN "'<your-token>'"

#

Tutorial.step

Step 4: Start SSH tunnel

Bash
ssh -N remote-gateway &

#

Tutorial.step

Step 5: Restart OpenClaw.app

Bash
open /path/to/OpenClaw.app

The app will connect to the remote gateway via the SSH tunnel.

Tutorial.step

Troubleshooting

Check if tunnel is running:

Bash
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

Restart the tunnel:

Bash
launchctl kickstart -k gui/$UID/bot.molt.ssh-tunnel

Stop the tunnel:

Bash
launchctl bootout gui/$UID/bot.molt.ssh-tunnel

--- |

ReferenceGatewayRemoteGatewayReadmePage.step08.item1

ReferenceGatewayRemoteGatewayReadmePage.step08.item2

ReferenceGatewayRemoteGatewayReadmePage.step08.item3

ReferenceGatewayRemoteGatewayReadmePage.step08.item4

OpenClaw.app connects to ''ws://127.0.0.1:18789'' on the client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the gateway is running.