Engine Connection Modes

xCloud can talk to different OpenClaw engines. The desktop app is always the control surface, but the engine can run locally, on another computer you own, or on a remote server.

Modes

How It Works

xCloud Desktop
  |
  | WebSocket + token + device signature
  v
OpenClaw Engine
  |
  | agents, tools, channels, workspaces
  v
Local files / remote host / messaging platforms

The OpenClaw engine is the runtime. It owns agents, sessions, tools, channels, and workspace files. xCloud Desktop connects to it as the operator UI.

Choosing A Mode

Choose the machine based on where you want the agents to actually run.

The important rule: channels, agents, memories, workspaces, and connected providers belong to the active engine. If you switch engines, xCloud will show the agents and channels from that engine.

Local Engine

Use Local when you want everything on the same machine.

• xCloud starts and manages the OpenClaw sidecar.
• The gateway normally runs on port 18789.
• No URL or token entry is needed in normal use.
• Agent workspaces live under ~/.openclaw/workspace.

In the app, go to Settings > Engine > Local and turn it on.

Mac mini / PC Engine

Use Mac mini / PC when you want any always-on computer running OpenClaw on your local network. It can be a Mac mini, Windows PC, Linux box, home server, old laptop, or mini PC.

Run this on that computer:

curl -fsSL https://xcloud.dev/setup-remote.sh | bash -s -- --lan

The command installs OpenClaw, installs the xCloud runtime helper, starts the gateway, and prints a connection block like:

URL: ws://192.168.1.50:18789
Token: <generated-token>

Paste this in xCloud:
xcloud://engine?mode=mac-mini&url=ws://192.168.1.50:18789&token=<generated-token>

In xCloud, open Settings > Engine > Mac mini / PC, paste the whole block into Paste connection block, then click Paste & connect.

Mac mini / PC only needs URL and Token because xCloud connects directly to the gateway over your LAN.

Requirements

• The computer must stay awake while agents are running.
• Your laptop and the engine computer must be on the same network.
• Port 18789 must be reachable from your laptop.
• If the computer changes IP often, use a static DHCP lease or local DNS name.

When To Avoid This Mode

Avoid this mode if you need access from outside your network and you do not want to configure VPN, Tailscale, ZeroTier, or router rules. In that case, use OpenClaw host / VPS instead.

OpenClaw Host / VPS

Use OpenClaw host when the engine runs on a VPS or any remote server.

Run this on the server:

curl -fsSL https://xcloud.dev/setup-remote.sh | bash -s -- --ssh

The command installs OpenClaw, keeps the gateway bound to the remote machine, and prints SSH tunnel details:

Host: 203.0.113.10
SSH user: root
SSH port: 22
Remote port: 18789
Local tunnel port: 18790
SSH tunnel: ssh -N -L 18790:127.0.0.1:18789 root@203.0.113.10
URL: ws://127.0.0.1:18790
Token: <generated-token>

Paste this in xCloud:
xcloud://engine?mode=vps&host=203.0.113.10&user=root&sshPort=22&remotePort=18789&localPort=18790&token=<generated-token>

In xCloud, open Settings > Engine > OpenClaw host, paste the whole block, then click Paste & connect.

The app stores:

For VPS mode, OpenClaw is not running on your laptop. xCloud opens a local SSH tunnel, then connects to 127.0.0.1 because that local port forwards traffic to the remote OpenClaw gateway.

Why VPS Uses A Tunnel

The gateway should not be exposed publicly unless you know what you are doing. In VPS mode, OpenClaw can stay bound to the server itself, and xCloud connects through SSH:

xCloud Desktop
  -> ws://127.0.0.1:18790
  -> SSH tunnel
  -> VPS 127.0.0.1:18789
  -> OpenClaw Gateway

This keeps the gateway private while still letting your local xCloud app control the remote engine.

Requirements

• SSH access from your laptop to the server.
• curl, bash, openssl, node, and npm available on the server. The setup script installs Node on common Linux hosts when possible.
• Port 22 or your custom SSH port reachable from your laptop.
• Enough disk space for OpenClaw, agent workspaces, and npm packages.

Repair Or Update A Remote Engine

If a remote engine is already connected but tools, agents, or channels stop behaving correctly, run:

curl -fsSL https://xcloud.dev/setup-remote.sh | bash -s -- --update-only

This refreshes the xCloud runtime helper, repairs required plugins, restarts the gateway, and keeps the current token.

Use this when:

• xCloud connects, but agent tools are missing.
• Imported agents appear, but some engine helper actions fail.
• Channels used to work and then stopped after an OpenClaw update.
• The gateway is running, but xCloud-specific commands are unavailable.

Switching Engines

Each engine mode keeps its own saved connection values.

1. Go to Settings > Engine.
2. Open Local, Mac mini / PC, or OpenClaw host.
3. Save the connection details.
4. Turn on Active for the engine you want to use.

When the active engine changes, xCloud reconnects and loads the agents, channels, settings, and workspaces from that engine.

Error Handling

xCloud connection errors usually come from one of four layers:

Start from the outside and move inward: can you reach the machine, can you open the tunnel, is the gateway running, and is the token correct?

Quick Checks

Local

openclaw gateway status

If the gateway is stopped, restart the app or run:

openclaw gateway restart

Mac mini / PC

From your laptop:

nc -vz 192.168.1.50 18789

If that fails, the engine computer is unreachable, asleep, on another network, or blocking port 18789.

On the engine computer:

openclaw gateway status

VPS

First confirm SSH works:

ssh root@203.0.113.10

Then test the tunnel manually:

ssh -N -L 18790:127.0.0.1:18789 root@203.0.113.10

In another terminal:

nc -vz 127.0.0.1 18790

If the local tunnel works, xCloud should use ws://127.0.0.1:18790.

Common Errors

Recovery Steps

Use this order when something is broken:

1. Confirm the active engine in Settings > Engine.
2. Re-paste the latest connection block from the engine setup command.
3. Run openclaw gateway status on the machine where OpenClaw runs.
4. For VPS, verify SSH manually.
5. Run the remote helper update command.
6. Restart xCloud Desktop.

If a channel does not respond after reconnecting, disconnect and reconnect that channel on the same engine where it should run. Channels are not global across engines.