重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。

同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
2026-10-14 12:23:18 +08:00 · 2026-04-26 08:34:33 +08:00 · 2026-04-26 08:34:33 +08:00 · dbbe3add6a
commit dbbe3add6a
parent 4a23b715a2
14438 changed files with 2693620 additions and 2546 deletions
--- a/openclaw/docs/gateway/remote-gateway-readme.md
+++ b/openclaw/docs/gateway/remote-gateway-readme.md
@ -0,0 +1,164 @@
+---
+summary: "SSH tunnel setup for OpenClaw.app connecting to a remote gateway"
+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.
+
+## Overview
+
+```mermaid
+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
+```
+
+## 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):
+
+```bash
+ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
+```
+
+### Step 3: Configure Remote Gateway Auth
+
+```bash
+openclaw config set gateway.remote.token "<your-token>"
+```
+
+Use `gateway.remote.password` instead if your remote gateway uses password auth.
+`OPENCLAW_GATEWAY_TOKEN` is still valid as a shell-level override, but the durable
+remote-client setup is `gateway.remote.token` / `gateway.remote.password`.
+
+### Step 4: Start SSH Tunnel
+
+```bash
+ssh -N remote-gateway &
+```
+
+### Step 5: Restart OpenClaw.app
+
+```bash
+# Quit OpenClaw.app (⌘Q), then reopen:
+open /path/to/OpenClaw.app
+```
+
+The app will now connect to the remote gateway through the SSH tunnel.
+
+---
+
+## Auto-Start Tunnel on Login
+
+To have the SSH tunnel start automatically when you log in, create a Launch Agent.
+
+### Create the PLIST file
+
+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>
+```
+
+### Load the Launch Agent
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.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:**
+
+```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
+```
+
+---
+
+## 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.