Skip to main content

​
Remote gateways and nodes

Telegram messages are handled by the gateway, which runs the agent and only then calls nodes over the Gateway WebSocket when a node tool is needed:Telegram -> Gateway -> Agent -> node.* -> Node -> Gateway -> TelegramNodes do not see inbound provider traffic; they only receive node RPC calls.
Pair your computer as a node. The Gateway runs elsewhere but can call node.* tools (screen, camera, system) on your local machine over the Gateway WebSocket.
  1. Run the Gateway on the always-on host (VPS/home server).
  2. Put the Gateway host and your computer on the same tailnet.
  3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).
  4. Open the macOS app locally and connect in Remote over SSH mode (or direct tailnet) so it registers as a node.
  5. Approve the node:
No separate TCP bridge is required; nodes connect over the Gateway WebSocket.Security reminder: pairing a macOS node allows system.run on that machine. Only pair devices you trust; review Security.Docs: Nodes, Gateway protocol, macOS remote mode, Security.
Check the basics:
Then verify auth and routing: if you use Tailscale Serve, confirm gateway.auth.allowTailscale is set correctly; if you connect via SSH tunnel, confirm the tunnel is up and points at the right port; confirm your DM/group allowlists include your account.Docs: Tailscale, Remote access, Channels.
Yes, though there is no built-in bot-to-bot bridge.Simplest: use a normal chat channel both bots can access (Slack/Telegram/WhatsApp). Have Bot A message Bot B, then let Bot B reply as usual.CLI bridge (generic): run a script that calls the other Gateway with openclaw agent --message ... --deliver, targeting a chat where the other bot listens. If one bot is on a remote VPS, point your CLI at that remote Gateway via SSH/Tailscale (see Remote access):
Add a guardrail so the two bots do not loop endlessly (mention-only, channel allowlists, or a “do not reply to bot messages” rule).Docs: Remote access, Agent CLI, Agent send.
No. One Gateway hosts multiple agents, each with its own workspace, model defaults, and routing - this is the normal setup and much cheaper/simpler than one VPS per agent. Use separate VPSes only for hard isolation (security boundaries) or very different configs you do not want to share.
Yes: nodes are the first-class way to reach your laptop from a remote Gateway and unlock more than shell access. The Gateway runs on macOS, Linux, and Windows (native or WSL2) and is lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common setup is an always-on host plus your laptop as a node.
  • No inbound SSH required - nodes connect out to the Gateway WebSocket via device pairing.
  • Safer execution controls - system.run is gated by node allowlists/approvals on that laptop.
  • More device tools - nodes expose camera and screen in addition to system.run; Macs also expose the widget panel.
  • Local browser automation - keep the Gateway on a VPS but run Chrome locally through a node host, or attach to local Chrome via Chrome MCP.
SSH is fine for ad-hoc shell access; nodes are simpler for ongoing agent workflows and device automation.Docs: Nodes, Nodes CLI, Browser.
No. Only one gateway should run per host unless you intentionally run isolated profiles (see Multiple gateways). Nodes are peripherals that connect to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app). For headless node hosts and CLI control, see Node host CLI.A full restart is required for gateway, discovery, and hosted plugin surface changes.
Yes:
  • config.schema.lookup: inspect one config subtree with its shallow schema node, matched UI hint, and immediate child summaries before writing.
  • config.get: fetch the current snapshot plus hash.
  • config.patch: safe partial update (preferred for most RPC edits); hot-reloads when possible, restarts when required.
  • config.apply: validate and replace the full config; hot-reloads when possible, restarts when required.
  • The agent-facing gateway runtime tool still refuses to rewrite tools.exec.ask / tools.exec.security; legacy tools.bash.* aliases normalize to the same protected paths.
Sets your workspace and restricts who can trigger the bot.
  1. Install + login on the VPS:
  2. Install + login on your Mac using the Tailscale app, same tailnet.
  3. Enable MagicDNS in the Tailscale admin console so the VPS has a stable name.
  4. Use the tailnet hostname: SSH ssh user@your-vps.tailnet-xxxx.ts.net; Gateway WS ws://your-vps.tailnet-xxxx.ts.net:18789.
For the Control UI without SSH, use Tailscale Serve on the VPS:
This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See Tailscale.
Serve exposes the Gateway Control UI + WS; nodes connect over the same Gateway WS endpoint.
  1. Make sure the VPS and Mac are on the same tailnet.
  2. Use the macOS app in Remote mode (SSH target can be the tailnet hostname) - it tunnels the Gateway port and connects as a node.
  3. Approve the node:
Docs: Gateway protocol, Discovery, macOS remote mode.
For local tools only (screen/camera/exec) on the second laptop, add it as a node - one Gateway, no duplicated config. The local tools a node exposes depend on its platform. See Nodes for the per-platform defaults. Install a second Gateway only for hard isolation or two fully separate bots.Docs: Nodes, Nodes CLI, Multiple gateways.