From 4ab7947ec06cc644bd292e6175cc5232d4260c66 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Tue, 31 Mar 2026 14:32:29 +0900
Subject: [PATCH] docs: merge remote-gateway-readme content into remote.md

---
 docs/gateway/remote-gateway-readme.md |  2 +
 docs/gateway/remote.md                | 95 +++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)

diff --git a/docs/gateway/remote-gateway-readme.md b/docs/gateway/remote-gateway-readme.md
index cb069629070..5619bf32934 100644
--- a/docs/gateway/remote-gateway-readme.md
+++ b/docs/gateway/remote-gateway-readme.md
@@ -4,6 +4,8 @@ read_when: "Connecting the macOS app to a remote gateway over SSH"
 title: "Remote Gateway Setup"
 ---
 
+> This content has been merged into [Remote Access](/gateway/remote#macos-persistent-ssh-tunnel-via-launchagent). See that page for the current guide.
+
 # 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.
diff --git a/docs/gateway/remote.md b/docs/gateway/remote.md
index 1497e82dcfc..27ce3075aab 100644
--- a/docs/gateway/remote.md
+++ b/docs/gateway/remote.md
@@ -151,3 +151,98 @@ Short version: **keep the Gateway loopback-only** unless you’re sure you need
 - Treat browser control like operator access: tailnet-only + deliberate node pairing.
 
 Deep dive: [Security](/gateway/security).
+
+### macOS: persistent SSH tunnel via LaunchAgent
+
+For macOS clients connecting to a remote gateway, the easiest persistent setup uses an SSH `LocalForward` config entry plus a LaunchAgent to keep the tunnel alive across reboots and crashes.
+
+#### Step 1: add SSH config
+
+Edit `~/.ssh/config`:
+
+```ssh
+Host remote-gateway
+    HostName <REMOTE_IP>
+    User <REMOTE_USER>
+    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 (one-time)
+
+```bash
+ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
+```
+
+#### Step 3: configure the gateway token
+
+Store the token in config so it persists across restarts:
+
+```bash
+openclaw config set gateway.remote.token "<your-token>"
+```
+
+#### Step 4: create the LaunchAgent
+
+Save this as `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`:
+
+```xml
+<?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>ai.openclaw.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>
+```
+
+#### Step 5: load the LaunchAgent
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist
+```
+
+The tunnel will start automatically at login, restart on crash, and keep the forwarded port live.
+
+Note: if you have a leftover `com.openclaw.ssh-tunnel` LaunchAgent from an older setup, unload and delete it.
+
+#### Troubleshooting
+
+Check if the 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/ai.openclaw.ssh-tunnel
+```
+
+Stop the tunnel:
+
+```bash
+launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel
+```
+
+| Config entry                         | 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 (port-forwarding only)  |
+| `KeepAlive`                          | Automatically restarts the tunnel if it crashes               |
+| `RunAtLoad`                          | Starts the tunnel when the LaunchAgent loads at login         |