Engine Troubleshooting

Most engine issues come from one of four layers: network, tunnel, gateway, or token.

Fast Diagnosis

Symptom	Likely layer
App says no URL configured	xCloud settings
Connection timed out	Network or SSH tunnel
Connection refused	Gateway not listening
Token rejected	Gateway auth
Agents missing	Wrong active engine
Tools missing	Remote helper not installed or outdated

Check gateway status:

openclaw gateway status

Restart gateway:

openclaw gateway restart

If Local still fails, restart xCloud.

From your laptop:

nc -vz <engine-ip> 18789

On the engine computer:

openclaw gateway status

If the port is blocked, check firewall, sleep mode, network, and IP address.

Confirm SSH first:

ssh <user>@<host>

Then test the tunnel:

ssh -N -L 18790:127.0.0.1:18789 <user>@<host>

In another terminal:

nc -vz 127.0.0.1 18790

If the tunnel works, the xCloud Gateway URL should be:

ws://127.0.0.1:18790

Use this when xCloud connects but tools, imported agents, terminal, or channels act broken:

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

This repairs the xCloud helper plugin and restarts the gateway without changing the token.

Error	Fix
`ECONNREFUSED`	Gateway is not running or wrong port
`Connection timed out`	Host unreachable or tunnel closed
`Permission denied (publickey)`	Wrong SSH key, user, or host
`Address already in use`	Change the local tunnel port
`WebSocket closed`	Gateway restarted, crashed, or rejected auth
Agents disappear after switching	Switch back to the engine where they were created