mirror of https://github.com/openclaw/openclaw.git synced 2026-05-28 23:15:03 +00:00

Files

Suvin Nimnaka 8d4c8f0010 Replace text diagrams with mermaid

2026-02-09 10:19:26 -05:00

4.1 KiB

Raw Blame History

summary, read_when, title

summary	read_when	title
SSH tunnel setup for OpenClaw.app connecting to a remote gateway	Connecting the macOS app to a remote gateway over SSH	Remote Gateway Setup

Running OpenClaw.app with a Remote Gateway

OpenClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.

Overview

```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#ffffff', 'primaryTextColor': '#000000', 'primaryBorderColor': '#000000', 'lineColor': '#000000', 'secondaryColor': '#f9f9fb', 'tertiaryColor': '#ffffff', 'clusterBkg': '#f9f9fb', 'clusterBorder': '#000000', 'nodeBorder': '#000000', 'mainBkg': '#ffffff', 'edgeLabelBackground': '#ffffff' } }}%% 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

</p>

## Quick Setup

### 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.

Step 2: Copy SSH Key

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

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

Step 3: Set Gateway Token

launchctl setenv OPENCLAW_GATEWAY_TOKEN "<your-token>"

Step 4: Start SSH Tunnel

ssh -N remote-gateway &

Step 5: Restart OpenClaw.app

# Quit OpenClaw.app (⌘Q), then reopen:
open /path/to/OpenClaw.app

The app will now connect to the remote gateway through the SSH tunnel.

To have the SSH tunnel start automatically when you log in, create a Launch Agent.

Create the PLIST file

Save this as ~/Library/LaunchAgents/bot.molt.ssh-tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>bot.molt.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Load the Launch Agent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/bot.molt.ssh-tunnel.plist

The tunnel will now:

Start automatically when you log in
Restart if it crashes
Keep running in the background

Legacy note: remove any leftover com.openclaw.ssh-tunnel LaunchAgent if present.

Troubleshooting

Check if tunnel is running:

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

Restart the tunnel:

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

Stop the tunnel:

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

How It Works

Component	What It Does
`LocalForward 18789 127.0.0.1:18789`	Forwards local port 18789 to remote port 18789
`ssh -N`	SSH without executing remote commands (just port forwarding)
`KeepAlive`	Automatically restarts tunnel if it crashes
`RunAtLoad`	Starts tunnel when the agent loads

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

4.1 KiB Raw Blame History