Hybrid Gateway — VPS + Local Node

Run your OpenClaw gateway on a cloud VPS for reliability, and connect a local machine as a node for hardware capabilities the VPS lacks: residential IP, GPU/ML inference, browser automation, local models, macOS-only tools, etc.

Why this architecture?

	VPS (Gateway)	Local Node
Always online	✅ Static IP, no ISP outages	❌ Power/network dependent
Messaging

✅ Handles Telegram, Discord, etc. | ❌ Not its job | | Agent brain | ✅ Runs models, routes tools | ❌ Peripheral only | | GPU / ML | ❌ Most VPS have no GPU | ✅ Apple Silicon, NVIDIA, etc. | | Browser automation | ⚠️ Headless only, cloud IP | ✅ Real browser, residential IP | | Local models | ❌ No hardware for it | ✅ Ollama, whisper, etc. | | macOS tools | ❌ Linux VPS | ✅ Native macOS (if using Mac) |

Prerequisites

Before starting, you need:

1. 1. OpenClaw installed on both machines — VPS (gateway) and local machine (node)
2. Tailscale installed on both machines — this is how they talk to each other

- Download Tailscale - Sign in on both machines with the same Tailscale account - Verify connectivity: tailscale status on either machine should show both devices

1. 3. Gateway already running on the VPS — openclaw gateway status should show running
2. Gateway auth token configured — required for non-loopback connections

If you don't have Tailscale set up yet, do that first. The rest of this guide assumes both machines are on the same tailnet.

Step 1 — Configure gateway bind mode

By default, the gateway binds to loopback (127.0.0.1 only). Your node can't reach that from another machine.

Recommended: lan bind (listens on all interfaces)

CODEBLOCK0

This listens on 0.0.0.0 — both 127.0.0.1 (local agents) and your Tailscale IP (remote node) will work.

Alternative: tailnet bind (Tailscale IP only)

CODEBLOCK1

⚠️ Warning: tailnet bind breaks local agent-to-agent sessions. Local tools try ws://127.0.0.1:18789 but the gateway only listens on the Tailscale IP. If you use multi-agent workflows, use lan instead.

Ensure auth is configured (required for any non-loopback bind):

CODEBLOCK2

Restart the gateway after config changes:

CODEBLOCK3

Verify:

CODEBLOCK4

Step 2 — Start the node on your local machine

On the local machine (Mac Mini, desktop, etc.):

CODEBLOCK5

If it connects, you'll see it register. If not, see Troubleshooting below.

Step 3 — Approve the device pairing

On the VPS:

CODEBLOCK6

Step 4 — Install as a service (auto-start)

You want the node to survive reboots and run headless.

macOS (LaunchAgent)

CODEBLOCK7

This creates a LaunchAgent plist that auto-starts on login.

Important: If the gateway requires ws:// over a private network (not wss://), you may need to set an environment variable in the LaunchAgent plist:

Add these environment variables to the plist's EnvironmentVariables dict:

• - OPENCLAW_GATEWAY_TOKEN — your existing gateway auth token (the same one from openclaw config get gateway.auth.token on the VPS)
• INLINECODE15 = 1 — allows ws:// over Tailscale (safe — traffic is WireGuard-encrypted at the network layer)

See the OpenClaw node host docs for the full plist reference.

The insecure WS override is only needed because OpenClaw blocks plaintext ws:// to non-loopback addresses by default. On Tailscale this is safe since all traffic is encrypted by WireGuard.

The LaunchAgent plist location: INLINECODE19

Load/unload manually:

CODEBLOCK8

Check logs: INLINECODE20

Linux (systemd)

CODEBLOCK9

Or create a systemd user service manually:

In the systemd service [Service] section, add:

• - Environment=OPENCLAW_GATEWAY_TOKEN=<your-gateway-token> — same token from your VPS gateway config
• INLINECODE23 — only if not using wss:// via Tailscale Serve

See the OpenClaw node host docs for the full service file reference.

CODEBLOCK10

Step 5 — Configure exec routing

Tell the gateway to route exec host=node commands to your node:

CODEBLOCK11

Now agents can run commands on your local machine:

CODEBLOCK12

Set up exec approvals on the node

The node enforces its own allowlist. Add commands you want to permit:

CODEBLOCK13

Or edit ~/.openclaw/exec-approvals.json on the node directly.

Step 6 — Set up SSH fallback (optional but recommended)

The node protocol handles command execution, but SSH is still needed for:

• - File transfers (scp/rsync between VPS and node)
• Full shell environment (commands needing .bashrc/.zshrc — nvm, homebrew PATH, env vars)
• Fallback when the node disconnects

Set up SSH key access

CODEBLOCK14

When to use which transport

Task	Use
Run a command	INLINECODE29 (node protocol)
Transfer files

scp my-node:/path/to/file . (SSH) | | Commands needing shell env | ssh my-node "source ~/.zshrc; command" (SSH) | | Node disconnected | SSH fallback for everything |

Troubleshooting

"SECURITY ERROR: Cannot connect over plaintext ws://"

The node is trying to connect via ws:// (not wss://) to a non-loopback address. This is blocked by default.

Fix: Set OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 in the node's environment. This is safe on Tailscale (WireGuard-encrypted). Add it to your LaunchAgent plist or systemd service.

Better fix (long-term): Use Tailscale Serve to get proper wss:// on the gateway. Then you don't need the env override.

Local agent sessions fail after changing gateway.bind

If you changed gateway.bind from loopback to tailnet, local agent-to-agent communication breaks. Local sessions try ws://127.0.0.1 but the gateway only listens on the Tailscale IP.

Fix: Use gateway.bind: "lan" instead. This listens on 0.0.0.0 — both loopback and Tailscale interfaces.

Node shows "pairing required"

Network route is working, auth is fine, but the device hasn't been approved yet.

CODEBLOCK15

Node shows "bootstrap token invalid or expired"

The setup code or pairing token is stale.

Fix: Generate a fresh one and reconnect:
CODEBLOCK16

Node connects but exec host=node doesn't work

1. 1. Check the node is actually paired and connected:

   openclaw nodes status
   

1. 2. Check tools.exec.node points to the right node:

   openclaw config get tools.exec.node
   

1. 3. Check exec approvals on the node allow the command you're running.

Node disconnects frequently

• - Ensure the node machine doesn't sleep (macOS: System Settings → Energy → Prevent automatic sleeping)
• Check Tailscale stays connected: INLINECODE43
• Check node logs: INLINECODE44
• If on Wi-Fi, prefer ethernet for the node machine

Commands fail with "command not found" on node

Node system.run uses a minimal PATH. Homebrew, nvm, and other tools that modify PATH via shell config won't be available.

Fix: Use full binary paths:
CODEBLOCK19

Or fall back to SSH when you need the full shell environment:
CODEBLOCK20

Architecture diagram

CODEBLOCK21

Quick reference

Task	Command
Check gateway bind	INLINECODE46
Check node status

openclaw nodes status | | List pending pairings | openclaw devices list | | Approve a node | openclaw devices approve <id> | | Run command on node | exec host=node command="..." | | Check Tailscale | tailscale status | | Restart gateway | openclaw gateway restart | | Node logs | ~/.openclaw/logs/node.log |

Tested with

• - OpenClaw 2026.4.x
• Tailscale 1.x
• macOS 15 (Sequoia) + Ubuntu 24.04 VPS
• Mac Mini M4 as node, Hostinger VPS as gateway

Should work with any VPS provider and any local machine that can run OpenClaw + Tailscale.

License

MIT